581 lines
24 KiB
Markdown
581 lines
24 KiB
Markdown
# MCP Standalone CLI Plan
|
|
|
|
## Goal
|
|
|
|
Ship a bundled CLI tool (`bds-mcp`) alongside the Electron app that:
|
|
|
|
- Runs as a self-contained MCP server over **stdio** (for Claude Desktop, VS Code, etc.)
|
|
- Works entirely against the **SQLite database** — no Electron process required
|
|
- Signals the running app of changes via a **`db_notifications`** table
|
|
- Is installed into agent configs by the app's existing agent-config UI (with add **and remove**)
|
|
|
|
---
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────┐ ┌────────────────────────────────────┐
|
|
│ bds-mcp (bundled CLI binary) │ │ bDS Electron app │
|
|
│ │ │ │
|
|
│ StdioServerTransport ──────┐ │ │ HTTP MCPServer :4124 │
|
|
│ │ │ │ ├── same engines │
|
|
│ │ │ │ └── NotificationWatcher │
|
|
│ PostEngine ├───┼─────┼──► SQLite (WAL mode, shared) │
|
|
│ MediaEngine │ │ │ posts / media / scripts … │
|
|
│ ScriptEngine │ │ │ db_notifications ← new │
|
|
│ TemplateEngine │ │ └────────────────────────────────────┘
|
|
│ MCPServer (tools/res) │ │ ▲
|
|
│ ProposalStore (in-memory) │ │ chokidar(-wal) + 100 ms debounce
|
|
└─────────────────────────────┘ │ invalidate engines + IPC to renderer
|
|
│
|
|
agent (Claude Desktop, VS Code…) ─┘
|
|
(stdio)
|
|
```
|
|
|
|
### Port mapping
|
|
|
|
| Context | Port | Transport |
|
|
|---|---|---|
|
|
| bDS app running | :4124 | HTTP (existing, unchanged) |
|
|
| `bds-mcp` CLI | — | stdio |
|
|
|
|
---
|
|
|
|
## Required Changes
|
|
|
|
### A — `db_notifications` table (new Drizzle migration)
|
|
|
|
```sql
|
|
CREATE TABLE db_notifications (
|
|
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
entity TEXT NOT NULL, -- 'post' | 'media' | 'script' | 'template'
|
|
entityId TEXT NOT NULL,
|
|
action TEXT NOT NULL, -- 'created' | 'updated' | 'deleted'
|
|
fromCli INTEGER NOT NULL DEFAULT 1, -- 1 = written by CLI; reserved for future app→CLI signalling
|
|
seenAt INTEGER, -- NULL = unprocessed by app
|
|
createdAt INTEGER NOT NULL
|
|
);
|
|
```
|
|
|
|
The CLI writes a row after every mutation. The app's `NotificationWatcher` queries for
|
|
`seenAt IS NULL AND fromCli = 1`, invalidates the relevant engine cache, emits IPC events
|
|
to the renderer, stamps `seenAt`, then **prunes rows whose `seenAt` is older than 1 hour**
|
|
to prevent unbounded table growth.
|
|
|
|
---
|
|
|
|
### B — Draft mode for scripts and templates (new Drizzle migration)
|
|
|
|
Scripts and templates currently write the file immediately on create. To allow CLI-created
|
|
proposals to be durable (survive CLI restarts) without polluting the filesystem until
|
|
accepted, add the same draft pattern that posts already use.
|
|
|
|
```sql
|
|
-- scripts
|
|
ALTER TABLE scripts ADD COLUMN status TEXT NOT NULL DEFAULT 'published'
|
|
CHECK (status IN ('draft', 'published'));
|
|
ALTER TABLE scripts ADD COLUMN content TEXT; -- draft body; NULL when on-disk
|
|
|
|
-- templates
|
|
ALTER TABLE templates ADD COLUMN status TEXT NOT NULL DEFAULT 'published'
|
|
CHECK (status IN ('draft', 'published'));
|
|
ALTER TABLE templates ADD COLUMN content TEXT; -- draft body; NULL when on-disk
|
|
```
|
|
|
|
Behaviour:
|
|
- **`propose_script` / `propose_template`** → `INSERT` with `status: 'draft'`, body in
|
|
`content`, `filePath: ''` — no file written yet; `ProposalStore` maps
|
|
`proposalId → rowId`
|
|
- **`accept_proposal`** → write file to disk, set `status: 'published'`, clear `content`
|
|
- **`discard_proposal`** → `DELETE` the row (never touched the filesystem)
|
|
|
|
---
|
|
|
|
### C0 — Decouple `DatabaseConnection` from Electron
|
|
|
|
`src/main/database/connection.ts` currently imports `{ app } from 'electron'` for three
|
|
things: `app.getPath('userData')`, `app.isPackaged`, and `process.resourcesPath`. The CLI
|
|
cannot load this file at all without Electron present.
|
|
|
|
Refactor `DatabaseConnection` to accept explicit constructor arguments:
|
|
|
|
```typescript
|
|
interface DatabaseConnectionConfig {
|
|
dbPath: string; // absolute path to bds.db
|
|
migrationsFolder: string; // absolute path to the drizzle/ migrations dir
|
|
dataDirs?: string[]; // extra directories to mkdir at startup (posts/, media/, etc.)
|
|
}
|
|
```
|
|
|
|
Four things must move out of `connection.ts` into `main.ts` (or equivalent callers):
|
|
|
|
1. `app.getPath('userData')` in the constructor — replaced by the explicit `dbPath`
|
|
2. `app.isPackaged` + `process.resourcesPath` in `runMigrations()` — replaced by
|
|
the explicit `migrationsFolder`
|
|
3. The `posts/` and `media/` `mkdirSync` calls in the constructor — absorbed into
|
|
the new `dataDirs` option (caller supplies the list)
|
|
4. **`getDataPaths()`** — this method also calls `app.getPath('userData')` directly and
|
|
must be removed from `DatabaseConnection` entirely. Move callers to compute data
|
|
paths themselves (they already have `userData` in scope in `main.ts`).
|
|
|
|
The Electron `main.ts` constructs it as today, computing paths via `app.getPath` before
|
|
passing them in. The CLI uses `platformConfigPath()` and `__dirname`-relative resolution.
|
|
All Electron imports are removed from `connection.ts` itself.
|
|
|
|
**WAL mode and synchronous pragma** — add to `initializeLocal()` immediately after
|
|
creating the client, before running migrations:
|
|
|
|
```typescript
|
|
await this.localClient.execute('PRAGMA journal_mode=WAL');
|
|
await this.localClient.execute('PRAGMA synchronous=NORMAL');
|
|
```
|
|
|
|
This must be done for **both** the app and CLI connections. It ensures the `-wal` file
|
|
exists (enabling chokidar to watch it) and gives consistent write performance.
|
|
|
|
This is a prerequisite for every CLI section that follows.
|
|
|
|
---
|
|
|
|
### C — `platformConfigPath()` — userData without Electron (`src/cli/platform.ts`)
|
|
|
|
Pure-Node helper to resolve the same path as Electron's `app.getPath('userData')`:
|
|
|
|
| Platform | Path |
|
|
|---|---|
|
|
| macOS | `~/Library/Application Support/Blogging Desktop Server` |
|
|
| Windows | `%APPDATA%\Blogging Desktop Server` |
|
|
| Linux | `~/.config/Blogging Desktop Server` |
|
|
|
|
Used by the CLI entrypoint to find the SQLite database without loading Electron.
|
|
|
|
---
|
|
|
|
### D — `CliNotifier` interface + injected DB writer
|
|
|
|
```typescript
|
|
interface CliNotifier {
|
|
notify(entity: string, id: string, action: 'created' | 'updated' | 'deleted'): Promise<void>;
|
|
}
|
|
```
|
|
|
|
- Electron app passes a no-op implementation (keeps engines clean, no code change needed
|
|
in the app path)
|
|
- CLI passes a DB writer implementation that inserts into `db_notifications`
|
|
|
|
Injected as an optional constructor argument on `PostEngine`, `ScriptEngine`,
|
|
`TemplateEngine`, `MediaEngine`.
|
|
|
|
---
|
|
|
|
### E — Engine `invalidate()` API
|
|
|
|
No engine currently exposes a way to signal that its data is stale. Before
|
|
`NotificationWatcher` can be implemented, each engine that holds any in-memory state needs
|
|
an `invalidate(entityId?: string): void` method that clears the relevant cached entries
|
|
(or the whole cache when `entityId` is omitted), forcing a fresh DB read on the next
|
|
access. Engines that are already fully stateless (query DB on every call) get a no-op stub
|
|
so `NotificationWatcher` can call a uniform API.
|
|
|
|
Engines to update: `PostEngine`, `MediaEngine`, `ScriptEngine`, `TemplateEngine`.
|
|
|
|
---
|
|
|
|
### F — `NotificationWatcher` (new engine, app-side only)
|
|
|
|
`src/main/engine/NotificationWatcher.ts`
|
|
|
|
Uses **chokidar** (already in `dependencies`) to watch both `bds.db` and `bds.db-wal`.
|
|
This gives sub-100 ms latency with zero boilerplate: chokidar handles missing files (the
|
|
`-wal` file doesn't exist until the first write after WAL mode is enabled), platform
|
|
differences (FSEvents on macOS, inotify on Linux, FSWatch on Windows), and
|
|
`add` events for when the WAL file is created for the first time.
|
|
|
|
```typescript
|
|
import chokidar, { FSWatcher } from 'chokidar';
|
|
|
|
export class NotificationWatcher {
|
|
private watcher: FSWatcher | null = null;
|
|
private debounceTimer: ReturnType<typeof setTimeout> | null = null;
|
|
|
|
constructor(
|
|
private readonly dbPath: string, // absolute path to bds.db
|
|
private readonly db: DrizzleDB,
|
|
private readonly engines: WatchableEngines,
|
|
private readonly mainWindow: BrowserWindow,
|
|
private readonly debounceMs = 100,
|
|
) {}
|
|
|
|
start(): void {
|
|
// Watch both the main db file (catches checkpoints) and the WAL file
|
|
// (catches every write before checkpoint). chokidar handles the case
|
|
// where bds.db-wal does not yet exist — it fires 'add' when it appears.
|
|
this.watcher = chokidar.watch(
|
|
[this.dbPath, `${this.dbPath}-wal`],
|
|
{
|
|
persistent: false,
|
|
ignoreInitial: true, // don't fire on startup for pre-existing files
|
|
usePolling: false, // rely on native FSEvents/inotify/kqueue
|
|
awaitWriteFinish: false,
|
|
},
|
|
);
|
|
this.watcher.on('change', () => this.schedule());
|
|
this.watcher.on('add', () => this.schedule()); // WAL created for first time
|
|
}
|
|
|
|
private schedule(): void {
|
|
if (this.debounceTimer) clearTimeout(this.debounceTimer);
|
|
this.debounceTimer = setTimeout(() => this.process(), this.debounceMs);
|
|
}
|
|
|
|
private async process(): Promise<void> {
|
|
const rows = await this.db
|
|
.select()
|
|
.from(dbNotifications)
|
|
.where(and(
|
|
isNull(dbNotifications.seenAt),
|
|
eq(dbNotifications.fromCli, 1),
|
|
));
|
|
|
|
for (const row of rows) {
|
|
this.engines[row.entity]?.invalidate(row.entityId);
|
|
this.mainWindow.webContents.send(
|
|
'entity:changed',
|
|
{ entity: row.entity, entityId: row.entityId, action: row.action },
|
|
);
|
|
await this.db
|
|
.update(dbNotifications)
|
|
.set({ seenAt: Date.now() })
|
|
.where(eq(dbNotifications.id, row.id));
|
|
}
|
|
|
|
// Prune rows processed more than 1 hour ago to prevent unbounded growth.
|
|
await this.db
|
|
.delete(dbNotifications)
|
|
.where(lt(dbNotifications.seenAt, Date.now() - 3_600_000));
|
|
}
|
|
|
|
stop(): void {
|
|
if (this.debounceTimer) clearTimeout(this.debounceTimer);
|
|
this.watcher?.close().catch(() => {});
|
|
}
|
|
}
|
|
```
|
|
|
|
`WatchableEngines` is a plain record keyed by entity name (`post`, `media`, `script`,
|
|
`template`) mapping to objects that expose `invalidate()`. Started in `main.ts` alongside
|
|
`PreviewServer` and `MCPServer`; stopped in the `app.on('before-quit')` handler.
|
|
|
|
---
|
|
|
|
### G — `MCPServer.startCli()` (extend existing `MCPServer.ts`)
|
|
|
|
The App View's `app.callServerTool()` routes through the MCP host (Claude Desktop, VS
|
|
Code, etc.) over the **same** connection the server is on — it does not make a direct HTTP
|
|
call to a secondary endpoint. The CLI therefore needs exactly one server and one transport:
|
|
|
|
```typescript
|
|
async startCli(): Promise<void> {
|
|
const server = this.createMcpServer();
|
|
const transport = new StdioServerTransport();
|
|
await server.connect(transport);
|
|
|
|
// Block until the MCP host closes stdin (normal session end).
|
|
// Signal-based shutdown is the caller's responsibility: do NOT register
|
|
// signal handlers here or they will race with the bds-mcp.ts handlers.
|
|
await new Promise<void>((resolve) => {
|
|
process.stdin.on('close', resolve);
|
|
});
|
|
|
|
await server.close();
|
|
}
|
|
```
|
|
|
|
No secondary HTTP port. No `bds-mcp-base-url` meta tag. The `ProposalStore` is owned by
|
|
the single `MCPServer` instance as before.
|
|
|
|
---
|
|
|
|
### H — `src/cli/bds-mcp.ts` — CLI entrypoint (no Electron imports)
|
|
|
|
```
|
|
1. platformConfigPath() → userData dir
|
|
2. dbPath = path.join(userData, 'bds.db')
|
|
3. migrationsFolder = path.join(__dirname, 'drizzle') // Contents/Resources/drizzle/
|
|
4. new DatabaseConnection({ dbPath, migrationsFolder, dataDirs: [postsDir, mediaDir] })
|
|
5. await db.initializeLocal() // runs WAL + synchronous pragmas, then migrations
|
|
6. SELECT active project (isActive = 1); exit with message if none
|
|
7. instantiate engines with CliNotifier DB writer
|
|
8. new MCPServer({ postEngine, mediaEngine, … }, { proposalTtlMs: 8 * 60 * 60 * 1000 })
|
|
9. await mcpServer.startCli() // blocks until stdin closes
|
|
10. await shutdown() // graceful post-stdin exit
|
|
```
|
|
|
|
`MCPServer` should accept an optional `proposalTtlMs` to override the default 30-minute
|
|
TTL. CLI sessions can last hours (overnight agent runs), so **8 hours** is the appropriate
|
|
default. Pass `proposalTtlMs` through to the `ProposalStore` constructor.
|
|
|
|
No `electron` imports. Fully standalone Node process.
|
|
|
|
**Graceful shutdown** — two paths, no racing:
|
|
|
|
```typescript
|
|
// Called both by signal handlers (forced) and after normal stdin-close (graceful).
|
|
// process.exit() makes it non-reentrant even without the once guards.
|
|
async function shutdown(): Promise<never> {
|
|
mcpServer.proposalStore.destroy();
|
|
await db.close(); // flushes any in-flight @libsql writes
|
|
process.exit(0);
|
|
}
|
|
|
|
// Signal handlers own interruption; registered before startCli() so they are
|
|
// active during the entire session. Do NOT register signals inside startCli().
|
|
process.once('SIGTERM', shutdown);
|
|
process.once('SIGINT', shutdown);
|
|
|
|
// Normal path: stdin closes → startCli() resolves → server.close() runs → shutdown()
|
|
await mcpServer.startCli();
|
|
await shutdown();
|
|
```
|
|
|
|
When SIGTERM fires, `shutdown()` runs and calls `process.exit(0)` — `startCli()` never
|
|
resumes, `server.close()` is skipped (safe: the process is exiting anyway). When stdin
|
|
closes cleanly, `startCli()` resumes, `server.close()` runs first, then `shutdown()`
|
|
exits. The `once` guards and `process.exit` together make the function non-reentrant.
|
|
|
|
**Native module resolution** — When launched as `ELECTRON_RUN_AS_NODE=1`, Electron's
|
|
ASAR patching is still active, so `require('@libsql/client')` resolves into
|
|
`app.asar/node_modules`. This is a documented side-effect of `ELECTRON_RUN_AS_NODE` that
|
|
has been stable since Electron 20. Add an integration test that verifies the module
|
|
resolves and the DB opens successfully from the bundled path; if a future Electron major
|
|
breaks this, the test will catch it early.
|
|
|
|
---
|
|
|
|
### I — esbuild/Vite build target for CLI bundle
|
|
|
|
New build target in `vite.config.ts` (or `package.json` scripts):
|
|
|
|
```
|
|
src/cli/bds-mcp.ts → dist/cli/bds-mcp.cjs
|
|
target: node, format: cjs, bundle: true
|
|
```
|
|
|
|
The project uses `@libsql/client` with platform-specific native binaries (e.g.
|
|
`@libsql/darwin-arm64`). These **cannot** be bundled by esbuild. Externalize all
|
|
`@libsql/*` and `chokidar`-related native packages, and ensure they resolve at runtime
|
|
from the app bundle (see the ASAR resolution note in section H):
|
|
|
|
```
|
|
externals: ['@libsql/client', '@libsql/darwin-arm64', '@libsql/linux-x64-gnu',
|
|
'chokidar', 'fsevents', …]
|
|
```
|
|
|
|
The `drizzle/` migrations folder does **not** need to be re-bundled alongside the `.cjs`
|
|
file — it is already included in `extraResources` (see J). The path resolution
|
|
`path.join(__dirname, 'drizzle')` resolves correctly when `bds-mcp.cjs` sits at
|
|
`Contents/Resources/bds-mcp.cjs` and `drizzle/` is at `Contents/Resources/drizzle/`.
|
|
|
|
Runs as part of `npm run build` before the Electron build.
|
|
|
|
---
|
|
|
|
### J — electron-builder `extraResources`
|
|
|
|
The `{ "from": "drizzle", "to": "drizzle" }` entry **already exists** in `package.json`.
|
|
Only the CLI bundle itself needs to be added:
|
|
|
|
```json
|
|
"build": {
|
|
"extraResources": [
|
|
{ "from": "dist/cli/bds-mcp.cjs", "to": "bds-mcp.cjs" }
|
|
// { "from": "drizzle", "to": "drizzle" } ← already present, do not duplicate
|
|
]
|
|
}
|
|
```
|
|
|
|
`bds-mcp.cjs` lands at `Contents/Resources/bds-mcp.cjs`; `drizzle/` is already at
|
|
`Contents/Resources/drizzle/`. The CLI migration resolver `path.join(__dirname, 'drizzle')`
|
|
resolves `Contents/Resources/drizzle/` correctly from that location.
|
|
|
|
---
|
|
|
|
### K — `MCPAgentConfigEngine` — add Claude Desktop + stdio support + remove
|
|
|
|
#### New agent type
|
|
|
|
```typescript
|
|
export type MCPAgentId =
|
|
| 'claude-code'
|
|
| 'claude-desktop' // ← NEW (stdio)
|
|
| 'github-copilot'
|
|
| 'gemini-cli'
|
|
| 'opencode';
|
|
```
|
|
|
|
#### Extended options
|
|
|
|
```typescript
|
|
export interface MCPAgentConfigOptions {
|
|
homeDir: string;
|
|
platform: NodeJS.Platform;
|
|
mcpUrl: string;
|
|
// stdio agents (set from app at runtime)
|
|
execPath: string; // process.execPath (packaged) or 'node' (dev)
|
|
scriptPath: string; // path to bds-mcp.cjs
|
|
}
|
|
```
|
|
|
|
#### Claude Desktop entry
|
|
|
|
```typescript
|
|
case 'claude-desktop':
|
|
return {
|
|
command: this.execPath,
|
|
args: [this.scriptPath],
|
|
env: { ELECTRON_RUN_AS_NODE: '1' },
|
|
};
|
|
```
|
|
|
|
Config file path:
|
|
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
- Linux: `~/.config/Claude/claude_desktop_config.json`
|
|
|
|
> **Note:** Verify the current OpenCode config schema before implementing the `opencode`
|
|
> entry — the format has changed between releases. Check the live spec at
|
|
> https://opencode.ai/docs before writing the `buildEntry` case.
|
|
|
|
#### Remove from config (new method)
|
|
|
|
```typescript
|
|
removeFromConfig(agentId: MCPAgentId): AgentConfigResult
|
|
```
|
|
|
|
- Reads the config file
|
|
- Deletes `config[serversKey][SERVER_NAME]`
|
|
- If `serversKey` object is now empty, removes the key entirely
|
|
- Writes back; returns `{ success, configPath }`
|
|
- No-ops gracefully if file or entry does not exist
|
|
|
|
This powers **Remove** buttons in the agent-config UI alongside the existing **Add**
|
|
buttons, so users never have to hunt down config files manually.
|
|
|
|
---
|
|
|
|
### L — `ScriptEngine` / `TemplateEngine` — draft lifecycle methods
|
|
|
|
New methods on each engine:
|
|
|
|
```typescript
|
|
// ScriptEngine
|
|
createDraftScript(data: CreateScriptInput): Promise<ScriptData> // status: 'draft', no file
|
|
publishScript(id: string): Promise<ScriptData | null> // write file, status: 'published'
|
|
deleteDraftScript(id: string): Promise<boolean> // only if status: 'draft'
|
|
|
|
// TemplateEngine
|
|
createDraftTemplate(data: CreateTemplateInput): Promise<TemplateData>
|
|
publishTemplate(id: string): Promise<TemplateData | null>
|
|
deleteDraftTemplate(id: string): Promise<boolean>
|
|
```
|
|
|
|
---
|
|
|
|
### M — `ProposalStore` — map proposals to DB row IDs
|
|
|
|
For `draftPost` proposals the store already maps `proposalId → postId` (the DB row). Extend
|
|
this consistently:
|
|
|
|
- `proposeScript` → maps `proposalId → scriptId` (DB row, `status: 'draft'`)
|
|
- `proposeTemplate` → maps `proposalId → templateId` (DB row, `status: 'draft'`)
|
|
- `proposeMediaMetadata` → stays in-memory (no draft DB row needed, metadata diff only)
|
|
- `proposePostMetadata` → stays in-memory (same reason)
|
|
|
|
`accept_proposal` dispatches to `publishScript` / `publishTemplate` / `publishPost` etc.
|
|
`discard_proposal` dispatches to `deleteDraftScript` / `deleteDraftTemplate` / `deletePost`.
|
|
|
|
**Known failure mode for in-memory metadata proposals:** if the CLI process is killed after
|
|
a `propose_media_metadata` or `propose_post_metadata` call but before accept/discard, the
|
|
`proposalId` no longer exists in any `ProposalStore`. The App View buttons will call
|
|
`accept_proposal` and receive `{ success: false, message: "Proposal … not found" }` —
|
|
this is already user-visible in the review UI. No silent corruption occurs; the post or
|
|
media item is simply unchanged. This is accepted as the trade-off for keeping metadata
|
|
proposals lightweight (no DB rows, no filesystem side effects).
|
|
|
|
---
|
|
|
|
### N — Renderer: subscribe to `entity:changed` IPC events
|
|
|
|
The app's UI must reflect changes the CLI makes while the app is open. `NotificationWatcher`
|
|
fires `entity:changed` IPC events (section F), but nothing currently handles them in the
|
|
renderer.
|
|
|
|
**`preload.ts`** — expose the channel alongside existing IPC listeners:
|
|
|
|
```typescript
|
|
onEntityChanged: (cb: (payload: EntityChangedPayload) => void) =>
|
|
ipcRenderer.on('entity:changed', (_, payload) => cb(payload)),
|
|
```
|
|
|
|
**Renderer subscription** — in the top-level app component (or a dedicated `IpcListener`
|
|
component that mounts once), subscribe on mount and unsubscribe on unmount:
|
|
|
|
```typescript
|
|
useEffect(() => {
|
|
const unsub = window.api.onEntityChanged(({ entity, entityId, action }) => {
|
|
// Dispatch store invalidation so the next render fetches fresh data
|
|
if (entity === 'post') postsStore.getState().invalidate(entityId);
|
|
if (entity === 'media') mediaStore.getState().invalidate(entityId);
|
|
if (entity === 'script') scriptsStore.getState().invalidate(entityId);
|
|
if (entity === 'template') templatesStore.getState().invalidate(entityId);
|
|
});
|
|
return () => unsub();
|
|
}, []);
|
|
```
|
|
|
|
Store `invalidate()` methods should clear the cached entry and, if the entity is
|
|
currently displayed, trigger an immediate refetch — consistent with how other
|
|
IPC-driven refreshes work in the app.
|
|
|
|
---
|
|
|
|
## Design Decisions
|
|
|
|
| Question | Decision |
|
|
|---|---|
|
|
| Active project in CLI | Use `isActive = 1` from DB; fail fast if none |
|
|
| Proposal durability | Scripts/templates use DB draft rows; metadata proposals stay in-memory (failure mode documented in M) |
|
|
| Proposal TTL | 30 min default in app; **8 hours** in CLI (overnight agent sessions) |
|
|
| App View tool calls in CLI mode | `app.callServerTool()` routes through the MCP host, not a direct HTTP call — no secondary port needed |
|
|
| Claude Desktop support | stdio via bundled `bds-mcp.cjs` + `ELECTRON_RUN_AS_NODE=1` (entitlements already set) |
|
|
| Remove from config | New `removeFromConfig()` method + Remove buttons in UI |
|
|
| DB change detection | **chokidar** on both `bds.db` and `bds.db-wal`; 100 ms debounce; handles missing WAL via `add` events |
|
|
| WAL mode | Explicit `PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL` in `initializeLocal()` for both app and CLI |
|
|
| `db_notifications` growth | Rows pruned after `seenAt` is 1 hour old, inside each `process()` call |
|
|
| DB coupling to Electron | `DatabaseConnection` accepts explicit paths; `getDataPaths()` removed; Electron path resolution stays in `main.ts` |
|
|
| Native module resolution | `ELECTRON_RUN_AS_NODE` inherits Electron ASAR require-hooking; integration test guards against regression |
|
|
| Signal handling | Signal handlers in `bds-mcp.ts` only; `startCli()` only listens to stdin-close — no competing handlers |
|
|
| Renderer live updates | Section N: `entity:changed` IPC → store `invalidate()` → refetch |
|
|
|
|
---
|
|
|
|
## Implementation Order (TDD per AGENTS.md)
|
|
|
|
1. **Migrations** (A + B) — schema changes first, all other work builds on them
|
|
2. **Decouple `DatabaseConnection` from Electron** (C0) — remove `app` import, move `getDataPaths()` to callers, add WAL pragmas; update existing DB tests to pass explicit paths
|
|
3. **`platformConfigPath()`** (C) — pure function, easy to test
|
|
4. **`CliNotifier` + DB writer** (D) — unit tests with mock DB
|
|
5. **Engine `invalidate()` API** (E) — add and test on each engine before NotificationWatcher
|
|
6. **`ScriptEngine`/`TemplateEngine` draft lifecycle** (L) — tests first
|
|
7. **`ProposalStore` TTL option + DB mapping** (M) — extend existing tests; add `proposalTtlMs` constructor arg
|
|
8. **`NotificationWatcher`** (F) — test with mock DB rows + mock chokidar emitter (emit `'change'` / `'add'` events on a fake `FSWatcher`)
|
|
9. **`MCPAgentConfigEngine` — `claude-desktop` + `removeFromConfig`** (K) — extend existing tests; verify opencode format before writing its case
|
|
10. **`MCPServer.startCli()`** (G) — test with in-process `StdioServerTransport`
|
|
11. **`src/cli/bds-mcp.ts`** (H) — integration test: spawn process, send `initialize`, assert response, assert clean shutdown on SIGTERM and on stdin-close
|
|
12. **Build target + `extraResources`** (I + J) — verify `npm run build` produces `dist/cli/bds-mcp.cjs`; `drizzle/` entry already in `extraResources`, only add `bds-mcp.cjs`
|
|
13. **UI: Remove buttons** — renderer component changes, follows K
|
|
14. **`NotificationWatcher` wired in `main.ts`** (F, app side) + stopped in `before-quit`
|
|
15. **Renderer `entity:changed` subscription** (N) — `preload.ts` exposure + store `invalidate()` hookup + component subscription
|
|
|
|
Each step: write failing test → implement → green → next.
|