kanban-lite 1.0.50 → 1.0.52

package/.vscodeignore

@@ -28,7 +28,6 @@ CONTRIBUTING.md
 skills-lock.json
 README.md
 dist/standalone.js
-dist/webview/**
 dist/cli.js
 dist/mcp-server.js
 dist/sdk/**

package/AGENTS.md

@@ -2,44 +2,6 @@
 
 A VSCode extension + standalone server + CLI + MCP server for managing kanban boards stored as markdown files (default) or SQLite.
 
-## Architecture
-
-```
-src/
-  sdk/           # Core SDK (no external dependencies) - KanbanSDK class
-  shared/        # Shared types (Card, KanbanColumn, CardDisplaySettings) and config module
-  cli/           # CLI tool (built on SDK)
-  mcp-server/    # MCP server (built on SDK + config + webhooks)
-  extension/     # VSCode extension
-  standalone/    # HTTP server with REST API + WebSocket + file watcher
-  webview/       # React frontend (shared by extension + standalone)
-```
-
-## 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
-- `src/standalone/server.ts` - HTTP server with all REST API routes + WebSocket
-- `src/standalone/webhooks.ts` - Webhook CRUD and delivery
-- `src/cli/index.ts` - All CLI commands
-- `src/mcp-server/index.ts` - All MCP tool definitions
-
-## Build
-
-```bash
-npm run build              # Build everything
-npm run build:cli          # CLI only
-npm run build:mcp          # MCP server only
-npm run build:standalone-server  # HTTP server only
-npx tsc --noEmit           # Type-check
-npm test                   # Run tests (vitest)
-```
 
 ## Feature Parity
 
@@ -56,47 +18,6 @@ Always follow this order when adding or modifying any feature:
 
 Never implement a feature directly in an interface layer without the SDK method existing first. The SDK is the single source of truth for all business logic.
 
-## Data Storage
-
-- 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`
-- Logs: `.kanban/boards/<boardId>/<status>/attachments/<cardId>.log` (auto-attached text file)
-
-## 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
-
-Cards support an optional `metadata` field (`Record<string, any>`) for arbitrary user-defined key-value data. Metadata is stored as a native YAML block in the card's frontmatter:
-
-```yaml
----
-id: "42"
-status: "in-progress"
-metadata:
-  sprint: "2026-Q1"
-  links:
-    jira: "PROJ-123"
-  estimate: 5
----
-```
-
-- Parsed with `js-yaml` (only the metadata block; rest of frontmatter uses regex)
-- Omitted from frontmatter when undefined or empty `{}`
-- Supported across all interfaces: SDK (`createCard`/`updateCard`), CLI (`--metadata '<json>'`), API (JSON body), MCP (`metadata` param)
-- UI: key-count chip `{N}` on card grid, collapsible tree view in card detail panel
-
 ## Documentation
 
 - **JSDoc:** Always update JSDoc comments when changing any logic, parameters, return types, or behavior of functions, methods, interfaces, or types. JSDoc is the source of truth for `docs/sdk.md`.
@@ -104,15 +25,6 @@ metadata:
 - **README.md:** Always update `README.md` when adding or modifying user-facing features. Update the relevant Features section, configuration examples, CLI usage examples, REST API tables, and MCP tool table as appropriate.
 - **CHANGELOG.md:** Always add an entry to `CHANGELOG.md` for every new feature, behaviour change, or bug fix. Place it under an `## [Unreleased]` section at the top (or the current in-progress version block). Follow the existing format: `### Added`, `### Changed`, `### Fixed` subsections with concise bullet points.
 
-## Conventions
-
-- Card IDs are auto-generated from title + date
-- Partial ID matching is supported across all interfaces
-- Fractional indexing (base-62) for card ordering within columns
-- `completedAt` is auto-managed when status changes to/from `done`
-- `modified` timestamp is auto-updated on any change
-- The standalone server uses synchronous `fs` operations; the SDK uses async `fs/promises`
-
 ## Agent execution rules (cost control):
 
 1. Do NOT scan or summarize the entire repository.

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **Active card lookup**: Added `getActiveCard(boardId?)` to the SDK plus matching REST API, CLI, and MCP support for retrieving the currently active/open card tracked by the UI.
+- **Configurable card panel layout**: Added the `panelMode` setting to switch card creation and detail flows between a right-side drawer and a centered popup.
+- **Adjustable drawer width**: Added the `drawerWidth` setting (20–80%) so drawer mode can be tuned per workspace; board layout and card visibility calculations now respect the configured width.
+- **Clickable label filters**: Clicking a label on a board card or in the card detail panel now applies that label as the active board filter.
+- **Metadata-aware fuzzy search parity**: Added the web UI `Fuzzy` toggle, metadata filter buttons in rendered metadata fields, CLI `kl list --search ... --fuzzy`, REST `q` / `fuzzy` task-list parameters, and MCP `list_cards` `searchQuery` / `fuzzy` inputs with shared metadata-aware semantics.
+
+### Changed
+- **Standalone URL sync**: Browser history and deep links now persist the fuzzy-search state alongside the existing board, card, tab, filter, and search query routing state.
+
+### Fixed
+- **Minimized column drops**: Card drags now reach minimized-column rails correctly instead of being swallowed by the rail's column-reorder wrapper.
+- **Standalone reconnect recovery**: In standalone/browser mode, the app now automatically retries same-page backend reconnects when possible and shows an in-app connection-lost error with refresh/reopen guidance if recovery cannot be restored.
+- **Toolbar search chips**: Mixed search queries in the web UI now render separate removable chips for plain-text terms and each `meta.*` token, so individual constraints can be cleared without wiping the entire query.
+
+### Removed
+- **Legacy webview build path**: Deleted `src/webview/main.tsx`, `src/webview/index.html`, and `vite.config.ts` — these produced `dist/webview/` which was unused since the dual-runtime `standalone-shim.ts` design was introduced. The active build path (`vite.standalone.config.ts` → `dist/standalone-webview/`) is unchanged.
+- **npm scripts**: Removed `build:webview` and `watch:webview`; the `watch` aggregate script now uses `watch:standalone-webview`.
+
 ### Added
 - **Board logs**: Each board now has its own log file at `.kanban/boards/<boardId>/board.log` for board-level audit trail entries. Board logs share the same `LogEntry` format as card logs (timestamp, source, text, optional JSON object) but are not tied to any card.
 - **SDK**: `getBoardLogFilePath(boardId?)`, `listBoardLogs(boardId?)`, `addBoardLog(text, options?, boardId?)`, `clearBoardLogs(boardId?)` methods on `KanbanSDK`. Emits `board.log.added` and `board.log.cleared` events.

package/CONTRIBUTING.md

@@ -50,7 +50,7 @@ src/
 ```
 
 - **Extension** is bundled with esbuild (`npm run build:extension`)
-- **Webview** is bundled with Vite (`npm run build:webview`)
+- **Webview** is bundled with Vite (`npm run build:standalone-webview`)
 
 ## Development
 

package/README.md

@@ -45,9 +45,13 @@ kl add --title "My first task" --priority high
 - **Real-time updates**: WebSocket-powered live sync across clients
 - **Light & dark mode** support
 - **Tabbed settings panel**: Settings organized into **General**, **Defaults**, and **Labels** tabs
+- **Flexible panel layouts**: Open card details and creation flows as a right-side drawer or a centered popup
+- **Adjustable drawer width**: Tune drawer mode between 20–80% of the viewport from the Layout settings
 - **Zoom controls**: Scale the board view and card detail panel independently between 75–150% via settings sliders or keyboard shortcuts
 - **Column sorting**: Sort cards within a column by priority, due date, or creation date from the column menu
+- **Column visibility controls**: Minimize a column into a narrow rail with its name and card count from the column menu, or hide/show columns from **Board options → Columns**
 - **Smooth scroll to selection**: Board automatically scrolls to the selected card
+- **URL-synced standalone navigation**: In standalone mode, the active board, card, tab, filters, search query, and fuzzy mode persist in browser history and deep links
 - **Keyboard shortcuts**:
   - `N` - Create new card
   - `Esc` - Close dialogs
@@ -71,7 +75,11 @@ kl add --title "My first task" --priority high
 - **Timestamps**: Created and modified dates tracked automatically
 
 ### Filtering & Search
-- **Full-text search**: Search across content, IDs, assignees, and labels
+- **Toolbar search with optional fuzzy mode**: Exact search is the default; enable the `Fuzzy` toggle in the web UI to match near-misses across card text and metadata values
+- **Metadata token search**: Use `meta.field: value` tokens for field-scoped searches that behave consistently across the web UI, CLI, REST API, and MCP
+- **Removable search chips**: Mixed searches are split into separate toolbar chips for plain text and each `meta.*` token, so you can remove one constraint without clearing the whole query
+- **Metadata filter buttons**: Click the filter icon next to rendered metadata values in the card detail panel to inject the correct `meta.field: value` token into the shared search box
+- **Clickable label filters**: Click a label on a board card or in the card detail panel to immediately filter the board to that label
 - **Priority filter**: Show only critical, high, medium, or low items
 - **Assignee filter**: Filter by team member or show unassigned items
 - **Label filter**: Filter by specific labels
@@ -99,6 +107,13 @@ kl list
 # List with filters
 kl list --status todo --priority high
 
+# Exact and fuzzy search
+kl list --search "release meta.team: backend"
+kl list --search "meta.team: backnd api plumbng" --fuzzy
+
+# Combine fuzzy search with structured metadata filters
+kl list --search "release" --fuzzy --meta sprint=Q1 --meta links.jira=PROJ-123
+
 # Create a card
 kl add --title "Implement search" --priority high --label "frontend,search"
 
@@ -108,6 +123,9 @@ kl add --title "Deploy service" --actions "retry,rollback,notify"
 # Show card details
 kl show implement-search
 
+# Show the currently active/open card
+kl active
+
 # Move to a different column
 kl move implement-search in-progress
 
@@ -149,6 +167,12 @@ kl board-log add --text "Pipeline passed" \
   --source ci --object '{"build":"42"}'                    # With source and data
 kl board-log clear                                       # Clear all board logs
 
+# Board Actions
+kl board-actions list --board default                    # List board-level actions
+kl board-actions add --board default \
+  --key deploy --title "Deploy to Production"            # Add/update a board action
+kl board-actions fire --board default deploy             # Trigger a board action
+
 # Boards
 kl boards                                               # List boards
 kl boards add --id bugs --name "Bug Tracker"            # Create a board
@@ -228,6 +252,8 @@ The server provides:
 - **REST API** at `http://localhost:3000/api` — full programmatic access
 - **WebSocket** — real-time updates for connected clients
 
+> In standalone/browser mode, the app automatically retries same-page backend reconnects when possible after the connection drops. If reconnect cannot be restored, the UI shows an in-app connection-lost error with guidance to refresh or reopen the standalone page.
+
 ### REST API
 
 All responses follow the format `{ "ok": true, "data": ... }` or `{ "ok": false, "error": "message" }`. CORS is enabled for all origins.
@@ -244,11 +270,22 @@ All responses follow the format `{ "ok": true, "data": ... }` or `{ "ok": false,
 | `PUT` | `/api/boards/:boardId` | Update board configuration |
 | `DELETE` | `/api/boards/:boardId` | Delete an empty board |
 
+#### Board Actions
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/api/boards/:boardId/actions` | List named board actions |
+| `POST` | `/api/boards/:boardId/actions` | Replace the board action map |
+| `PUT` | `/api/boards/:boardId/actions/:key` | Add or update a single board action title |
+| `DELETE` | `/api/boards/:boardId/actions/:key` | Remove a named board action |
+| `POST` | `/api/boards/:boardId/actions/:key/trigger` | Trigger a board action webhook event |
+
 #### Tasks
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| `GET` | `/api/tasks` | List all tasks (query: `?status=&priority=&assignee=&label=`) |
+| `GET` | `/api/tasks` | List all tasks (query: `?q=&fuzzy=&meta.<field>=&status=&priority=&assignee=&label=`) |
+| `GET` | `/api/tasks/active` | Get the currently active/open task |
 | `GET` | `/api/tasks/:id` | Get a single task |
 | `POST` | `/api/tasks` | Create a task |
 | `PUT` | `/api/tasks/:id` | Update task properties |
@@ -257,6 +294,8 @@ All responses follow the format `{ "ok": true, "data": ... }` or `{ "ok": false,
 
 Board-scoped equivalents are available at `/api/boards/:boardId/tasks/...`.
 
+`q` is the free-text search input, `fuzzy=true` enables typo-tolerant matching, and `meta.<field>=value` keeps metadata filtering field-scoped. The same search semantics are shared with `kl list --search ... --fuzzy` and the MCP `list_cards` tool.
+
 #### Transfer
 
 | Method | Endpoint | Description |
@@ -338,6 +377,13 @@ curl -X POST http://localhost:3000/api/tasks \
   -d '{"content": "# My Task\n\nDescription here", "status": "todo", "priority": "high"}'
 ```
 
+### Example: Search tasks via API
+
+```bash
+curl "http://localhost:3000/api/tasks?q=release&fuzzy=true&meta.team=backend"
+curl "http://localhost:3000/api/boards/bugs/tasks?q=meta.team%3A%20backnd&fuzzy=true&meta.region=us-east"
+```
+
 ## Webhooks
 
 Register webhooks to receive HTTP POST notifications when data changes. Webhooks fire from **all interfaces** — REST API, CLI, MCP server, and the web UI — ensuring consistent event delivery regardless of how a mutation is triggered.
@@ -364,6 +410,7 @@ Register webhooks to receive HTTP POST notifications when data changes. Webhooks
 | `board.created` | A new board is created |
 | `board.updated` | Board configuration is changed |
 | `board.deleted` | A board is deleted |
+| `board.action` | A board-level action is triggered from the toolbar, CLI, REST API, or MCP |
 
 ### Payload
 
@@ -487,6 +534,53 @@ curl -X POST http://localhost:3000/api/tasks \
 - Actions are **fire-and-forget** — no retry logic or delivery guarantees are built in. Implement idempotency and retries in your own webhook handler if needed.
 - Action strings have no special meaning to Kanban Lite; you define the vocabulary.
 
+## Board Actions
+
+Board actions are the board-level sibling to card actions. Define them once per board, and they appear in the toolbar **Actions** dropdown for that board.
+
+### How it works
+
+1. **Define actions on the board** in `.kanban.json`:
+
+```json
+{
+  "boards": {
+    "default": {
+      "name": "Default Board",
+      "actions": {
+        "deploy": "Deploy to Production",
+        "announce": "Post release update"
+      }
+    }
+  }
+}
+```
+
+2. **Trigger them from any interface**:
+
+- **UI**: Use the toolbar **Actions** dropdown on a board that defines actions.
+- **CLI**: `kl board-actions fire --board <boardId> <key>`
+- **REST API**: `POST /api/boards/:boardId/actions/:key/trigger`
+- **MCP**: `trigger_board_action`
+
+3. **Receive a webhook event**: triggering a board action emits a `board.action` event containing the board ID, action key, and display title.
+
+### Managing board actions
+
+```bash
+# List existing actions
+kl board-actions list --board default
+
+# Add or update a named action
+kl board-actions add --board default --key deploy --title "Deploy to Production"
+
+# Remove an action
+kl board-actions remove --board default deploy
+
+# Trigger an action
+kl board-actions fire --board default deploy
+```
+
 ## MCP Server
 
 Expose your kanban board to AI agents (Claude, Cursor, etc.) via the [Model Context Protocol](https://modelcontextprotocol.io/).
@@ -526,9 +620,14 @@ kanban-mcp --dir .kanban        # Via dedicated binary
 | `create_board` | Create a new board with optional custom columns |
 | `get_board` | Get board configuration and details |
 | `delete_board` | Delete an empty board |
+| `list_board_actions` | List all named actions defined on a board |
+| `add_board_action` | Add or update a named board action |
+| `remove_board_action` | Remove a named board action |
+| `trigger_board_action` | Trigger a board action webhook event |
 | `transfer_card` | Move a card from one board to another |
-| `list_cards` | List/filter cards by status, priority, assignee, or label |
+| `list_cards` | List/filter cards by status, priority, assignee, label, `searchQuery`, `fuzzy`, and `metaFilter` |
 | `get_card` | Get full details of a card (supports partial ID matching) |
+| `get_active_card` | Get the currently active/open card, or `null` if none is active |
 | `create_card` | Create a new card with title, body, status, priority, etc. |
 | `update_card` | Update fields of an existing card |
 | `move_card` | Move a card to a different status column |
@@ -558,6 +657,8 @@ kanban-mcp --dir .kanban        # Via dedicated binary
 | `update_webhook` | Update a webhook (url, events, secret, active) |
 | `remove_webhook` | Remove a webhook |
 | `get_workspace_info` | Get workspace root path, storage engine, and features directory |
+
+For agent-driven search, pass `searchQuery` for free text (including inline tokens like `meta.team: backend`), set `fuzzy: true` to widen matching across text and metadata values, or use `metaFilter` when you want structured dot-notation field filters.
 | `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 |
@@ -581,6 +682,7 @@ await sdk.deleteBoard('bugs')
 
 // Cards (all accept optional boardId as last argument)
 const cards = await sdk.listCards()
+const activeCard = await sdk.getActiveCard()
 const card = await sdk.createCard({ content: '# My Task', status: 'todo', priority: 'high' })
 await sdk.moveCard(card.id, 'in-progress')
 await sdk.updateCard(card.id, { assignee: 'alice' })
@@ -739,6 +841,10 @@ Board configuration is stored in `.kanban.json` at your project root. It support
         { "id": "review", "name": "Review", "color": "#8b5cf6" },
         { "id": "done", "name": "Done", "color": "#22c55e" }
       ],
+      "actions": {
+        "deploy": "Deploy to Production",
+        "announce": "Post release update"
+      },
       "nextCardId": 1,
       "defaultStatus": "backlog",
       "defaultPriority": "medium"
@@ -751,6 +857,8 @@ Board configuration is stored in `.kanban.json` at your project root. It support
   "compactMode": false,
   "boardZoom": 100,
   "cardZoom": 100,
+  "panelMode": "drawer",
+  "drawerWidth": 50,
   "actionWebhookUrl": "https://example.com/kanban-actions"
 }
 ```
@@ -759,6 +867,8 @@ Columns are fully customizable per board — add, remove, rename, or recolor the
 
 `boardZoom` and `cardZoom` set the default zoom percentage (75–150) for the board view and card detail panel respectively. They can also be adjusted live in the Settings panel or with `Ctrl/Cmd + =` / `Ctrl/Cmd + -` keyboard shortcuts.
 
+`panelMode` controls whether card flows open as a centered popup or a right-side drawer. When using drawer mode, `drawerWidth` sets the default width percentage (20–80) for card creation and detail panels.
+
 ## AI Agent Integration
 - **Claude Code**: Default, Plan, Auto-edit, and Full Auto modes
 - **Codex**: Suggest, Auto-edit, and Full Auto modes