73 lines
3.1 KiB
Markdown
73 lines
3.1 KiB
Markdown
# SilverBullet Development Guide
|
|
|
|
## Good practices
|
|
* After each significant change, run the typechecker, linter, and tests.
|
|
* Write unit tests for new functionality first
|
|
* Always keep DEVELOPMENT.md up to date with new best practices, based on guidance.
|
|
|
|
## Commands
|
|
- Build: `deno task build`
|
|
- Test: `deno task test`
|
|
- Test single file: `deno task test /path/to/test.ts`
|
|
- Run all Lua tests: `deno task test common/space_lua/lua.test.ts`
|
|
- Lint: `deno task lint`
|
|
- Format: `deno task fmt`
|
|
- Type checking: `deno task check`
|
|
- Watch server: `deno task watch-server <PATH-TO-SPACE>`
|
|
- Watch web: `deno task watch-web`
|
|
- Watch plugs: `deno task watch-plugs`
|
|
|
|
## Code Style
|
|
- TypeScript: Use explicit types for function parameters and return values
|
|
- Imports: Group related imports together, sort alphabetically within groups
|
|
- Naming: camelCase for variables/functions, PascalCase for classes/interfaces/types
|
|
- Error handling: Use explicit error types and handle errors gracefully
|
|
- Tests: Write unit tests for new functionality using `@std/assert` for assertions (e.g., `assert`, `assertEquals`)
|
|
- Comments: Focus on "why" not "what", especially for complex logic
|
|
- Prefer const over let when variable won't be reassigned
|
|
- In Lua: use camelCase for variables and functions
|
|
- Tests end with .test.ts
|
|
|
|
## Architecture Overview
|
|
|
|
### Plugin System (Plugs)
|
|
- **PlugOS**: Extension framework with System, Plug, Sandbox, and Syscalls components
|
|
- **Hooks**: Extension points (commands, events, slash commands, widgets)
|
|
- **Manifest**: Configuration for plugins defining functions, permissions, and dependencies
|
|
|
|
### Data Models
|
|
- **Pages**: Markdown documents with frontmatter, structured as `ObjectValue`
|
|
- **Documents**: Any file type (images, PDFs) with metadata
|
|
- **Objects**: Structured data extracted from pages, supporting tagging and attributes
|
|
|
|
### Key Design Patterns
|
|
- Event-driven architecture with EventHook system
|
|
- Middleware layers with composable SpacePrimitives implementations
|
|
- Syscall pattern for sandboxed plugin functions
|
|
- Command pattern for UI and programmatic actions
|
|
- Hook system for extension points
|
|
- Client-server synchronization with offline support
|
|
- Template rendering with query language for data extraction
|
|
|
|
## Directory Structure
|
|
|
|
### Top-level Directories
|
|
- `/Library`: Standard library shipped with SilverBullet
|
|
- `/cmd`: Command-line interfaces and entry points
|
|
- `/common`: Shared core functionality for both server and client
|
|
- `/lib`: Utility libraries and internal modules
|
|
- `/plug-api`: API exposed to plugins (syscalls and utility functions)
|
|
- `/plugs`: Built-in plugins that provide core functionality
|
|
- `/server`: Server-side implementation (HTTP, storage)
|
|
- `/web`: Client-side/browser implementation
|
|
- `/website`: Documentation site content
|
|
|
|
### Key Areas
|
|
- `/common/space_lua`: Lua scripting implementation with parsers and runtime
|
|
- `/lib/plugos`: Plugin system core functionality
|
|
- `/plugs`: Plugs for core functionality (editor, indexing, etc) distributed with the system
|
|
- `/web`: Client implementation
|
|
- `/web/cm_plugins`: CodeMirror editor extensions
|
|
- `/web/hooks`: Client-side hook implementations
|
|
- `/web/syscalls`: Client-side specific syscall implementations
|