kanban-lite 1.0.31 → 1.0.33

package/AGENTS.md

@@ -1,6 +1,6 @@
 # Kanban Markdown - Development Guide
 
-A VSCode extension + standalone server + CLI + MCP server for managing kanban boards stored as markdown files.
+A VSCode extension + standalone server + CLI + MCP server for managing kanban boards stored as markdown files (default) or SQLite.
 
 ## Architecture
 
@@ -18,6 +18,10 @@ src/
 ## Key Files
 
 - `src/sdk/KanbanSDK.ts` - Core card/column CRUD operations
+- `src/sdk/storage/types.ts` - StorageEngine interface and BootstrapConfig
+- `src/sdk/storage/markdown.ts` - MarkdownStorageEngine (default)
+- `src/sdk/storage/sqlite.ts` - SqliteStorageEngine (better-sqlite3)
+- `src/sdk/storage/index.ts` - Storage engine factory + readBootstrapConfig
 - `src/sdk/parser.ts` - Markdown frontmatter parsing and serialization
 - `src/shared/types.ts` - All TypeScript types and enums
 - `src/shared/config.ts` - `.kanban.json` config read/write, settings conversion
@@ -54,10 +58,22 @@ Never implement a feature directly in an interface layer without the SDK method
 
 ## Data Storage
 
-- Cards: `.kanban/{status}/card-name-YYYY-MM-DD.md` (markdown with YAML frontmatter)
-- Config: `.kanban.json` (columns, display settings, label definitions)
+- Cards (markdown engine): `.kanban/boards/<boardId>/<status>/card-name-YYYY-MM-DD.md`
+- Cards (sqlite engine): `.kanban/kanban.db` (configurable via `sqlitePath` in `.kanban.json`)
+- Config: `.kanban.json` (boards, columns, display settings, label definitions)
 - Webhooks: `.kanban-webhooks.json`
-- SDK board config: `.kanban/board.json` (used by SDK for column management)
+
+## Storage Engines
+
+The `StorageEngine` interface (`src/sdk/storage/types.ts`) abstracts all card I/O. Only card data (cards, comments) is engine-dependent — workspace config always lives in `.kanban.json`.
+
+- **MarkdownStorageEngine** — default; full backward compatibility
+- **SqliteStorageEngine** — single DB file; no chokidar watcher needed in server.ts
+- Factory: `createStorageEngine(kanbanDir, options?)` in `src/sdk/storage/index.ts`
+- Bootstrap: `readBootstrapConfig(workspaceRoot)` reads only `storageEngine`/`sqlitePath` before engine creation (chicken-and-egg resolution)
+- SDK migration methods: `migrateToSqlite(dbPath?)` and `migrateToMarkdown()`
+- `filePath` is set to `''` for SQLite cards; `sanitizeCard()` strips it from API responses
+- **Caution**: JSDoc backticks inside `/** ... */` TypeScript interface comments may contain patterns like `**/` which prematurely close the comment block (e.g. glob patterns). Use prose descriptions instead.
 
 ## Card Metadata
 

package/CHANGELOG.md

@@ -8,6 +8,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+- **Attachments subfolder**: attachments for the markdown storage engine are now stored in an `attachments/` subdirectory inside each column folder (e.g. `.kanban/boards/default/backlog/attachments/`) instead of alongside the card `.md` files
+- **Browser-viewable attachments**: PDFs and other binary attachments now open with the OS/browser default viewer in the VS Code extension; the standalone server now serves PDF, JPEG, GIF, WebP, CSV, plain-text, and XML attachments with correct `Content-Type` headers so browsers render them inline in a new tab
+- **KanbanSDK.getAttachmentDir(cardId, boardId?)**: new public SDK method that returns the absolute path to the attachment directory for a card (delegates to the active storage engine)
+- **Pluggable storage engine**: new `StorageEngine` interface (`src/sdk/storage/types.ts`) decouples all card I/O from the SDK business logic
+- **SQLite storage engine**: `SqliteStorageEngine` stores cards and comments in a single `.kanban/kanban.db` file using `better-sqlite3`; config (boards, columns, labels, webhooks) always stays in `.kanban.json`
+- **Markdown storage engine**: `MarkdownStorageEngine` wraps the existing file-based I/O, unchanged default behavior
+- **Storage engine configuration**: `storageEngine` (`"markdown"` | `"sqlite"`) and `sqlitePath` fields in `.kanban.json`
+- **KanbanSDK.migrateToSqlite(dbPath?)**: migrates all markdown cards to SQLite and updates `.kanban.json`
+- **KanbanSDK.migrateToMarkdown()**: migrates all SQLite cards back to markdown files and updates `.kanban.json`
+- **KanbanSDK.close()**: releases storage engine resources (e.g. closes SQLite DB connection)
+- **KanbanSDK.storageEngine** getter: exposes the active `StorageEngine` instance
+- **CLI storage commands**: `kl storage status`, `kl storage migrate-to-sqlite [--sqlite-path <path>]`, `kl storage migrate-to-markdown`
+- **REST API storage endpoints**: `GET /api/storage`, `POST /api/storage/migrate-to-sqlite`, `POST /api/storage/migrate-to-markdown`; `/api/workspace` now includes `storageEngine` and `sqlitePath`
+- **MCP storage tools**: `get_storage_status`, `migrate_to_sqlite`, `migrate_to_markdown`
+- **Storage engine tests**: `storage-markdown.test.ts` (10 tests), `storage-sqlite.test.ts` (15 tests), `storage-migration.test.ts` (5 tests)
+
+### Changed
+- `src/standalone/server.ts`: chokidar file watcher is skipped when the active storage engine is `sqlite` (no `.md` files to watch)
 - **Multi-select cards**: Cmd/Ctrl+click to toggle individual cards, Shift+click to select a range, "Select All" in column menu
 - **Bulk actions bar**: floating toolbar when multiple cards are selected with Move to, Priority, Assign, Labels, and Delete actions
 - Multi-card drag & drop to move selected cards to another column

package/README.md

@@ -168,6 +168,11 @@ kl settings update --compactMode true                   # Update a setting
 # Workspace
 kl pwd                                                  # Print workspace root path
 
+# Storage engine
+kl storage status                                       # Show current engine
+kl storage migrate-to-sqlite --sqlite-path .kanban/kanban.db  # Migrate to SQLite
+kl storage migrate-to-markdown                          # Migrate back to markdown
+
 # Start web server
 kl serve                                                # Start on port 3000
 kl serve --port 8080 --no-browser                       # Custom port, no auto-open
@@ -272,7 +277,10 @@ Board-scoped equivalents are available at `/api/boards/:boardId/tasks/...`.
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `GET` | `/api/workspace` | Get workspace root path |
+| `GET` | `/api/workspace` | Get workspace root path and storage engine |
+| `GET` | `/api/storage` | Get current storage engine type and config |
+| `POST` | `/api/storage/migrate-to-sqlite` | Migrate cards to SQLite (`{ sqlitePath? }`) |
+| `POST` | `/api/storage/migrate-to-markdown` | Migrate cards back to markdown files |
 
 #### Comments
 
@@ -510,7 +518,10 @@ kanban-mcp --dir .kanban        # Via dedicated binary
 | `add_webhook` | Register a new webhook |
 | `update_webhook` | Update a webhook (url, events, secret, active) |
 | `remove_webhook` | Remove a webhook |
-| `get_workspace_info` | Get workspace root path and features directory |
+| `get_workspace_info` | Get workspace root path, storage engine, and features directory |
+| `get_storage_status` | Get current storage engine type and configuration |
+| `migrate_to_sqlite` | Migrate all card data from markdown to SQLite |
+| `migrate_to_markdown` | Migrate all card data from SQLite back to markdown files |
 
 All card, column, comment, and attachment tools accept an optional `boardId` parameter to target a specific board.
 
@@ -613,6 +624,64 @@ Yes, good idea. I'll add that as a follow-up.
 
 Comments are stored as additional YAML documents in the same file, keeping everything in one place and version-controllable.
 
+## Storage Engines
+
+By default cards are stored as markdown files. You can optionally switch to a **SQLite** backend to keep all card data in a single database file — useful for programmatic access or performance at scale.
+
+The active engine is configured in `.kanban.json`:
+
+```json
+{
+  "storageEngine": "sqlite",
+  "sqlitePath": ".kanban/kanban.db"
+}
+```
+
+| Engine | Default | Card storage | Config storage |
+|--------|---------|--------------|----------------|
+| `markdown` | ✓ | `.kanban/boards/<board>/<status>/*.md` | `.kanban.json` |
+| `sqlite` | | `.kanban/kanban.db` (configurable) | `.kanban.json` |
+
+In both cases `.kanban.json` remains the source of truth for board config, columns, labels, settings, and webhooks.
+
+### Migrating between engines
+
+**CLI:**
+```bash
+# Check current engine
+kl storage status
+
+# Migrate to SQLite
+kl storage migrate-to-sqlite --sqlite-path .kanban/kanban.db
+
+# Migrate back to markdown
+kl storage migrate-to-markdown
+```
+
+**REST API:**
+```bash
+curl -X POST http://localhost:3000/api/storage/migrate-to-sqlite \
+  -H 'Content-Type: application/json' \
+  -d '{"sqlitePath": ".kanban/kanban.db"}'
+```
+
+**SDK:**
+```ts
+const sdk = new KanbanSDK('.kanban')
+await sdk.init()
+
+// Migrate to SQLite
+const count = await sdk.migrateToSqlite('.kanban/kanban.db')
+console.log(`Migrated ${count} cards to SQLite`)
+
+// Or migrate back
+await sdk.migrateToMarkdown()
+```
+
+Existing files / the database are **not deleted** during migration — they serve as a manual backup until you remove them.
+
+**MCP tools:** `get_storage_status`, `migrate_to_sqlite`, `migrate_to_markdown`
+
 ## Configuration
 
 Board configuration is stored in `.kanban.json` at your project root. It supports multiple boards, each with their own columns and settings: