plainleaf/DEVELOPMENT.md

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