brainfile 0.19.0 → 0.21.0

package/README.md

@@ -17,9 +17,9 @@ brainfile init
 ```
 
 This creates the standard v2 structure:
-- `.brainfile/brainfile.md` (Configuration, rules, definitions)
+- `.brainfile/brainfile.md` (Configuration: columns, types, agent instructions)
 - `.brainfile/board/` (Active tasks)
-- `.brainfile/logs/` (Completed task files)
+- `.brainfile/logs/` (Completed task files and `ledger.jsonl`)
 
 The board comes pre-configured with `To Do` and `In Progress` columns.
 
@@ -157,23 +157,17 @@ brainfile contract validate -t task-45
 
 ## ADR Promotion
 
-Architecture Decision Records (ADRs) are first-class task files. You can promote an ADR into a project rule.
+Architecture Decision Records (ADRs) are first-class task files. Promote an ADR to mark it accepted and archive it to `logs/`. Accepted ADRs show up in `brainfile brief`.
 
 ```bash
 # 1. Create an ADR
 brainfile add -t "Use Postgres for all user data" --type adr -c todo
 
-# 2. Promote it to a rule
-brainfile adr promote -t adr-1 --category always
+# 2. Promote it
+brainfile adr promote -t adr-1
 ```
 
-**Categories:**
-- `always`: Strict rules (e.g., "Always use TypeScript")
-- `never`: Prohibitions (e.g., "Never commit secrets")
-- `prefer`: Guidelines (e.g., "Prefer functional components")
-- `context`: informational context
-
-Promoted rules are added to `.brainfile/brainfile.md`, and the promoted ADR file moves to `.brainfile/logs/`.
+The ADR file moves to `.brainfile/logs/` with `status: promoted`. Project guidance belongs in `agent.instructions` (or `brainfile lint --fix` will fold a legacy `rules:` block there).
 
 ## TUI (Terminal UI)
 
@@ -184,22 +178,22 @@ brainfile          # No arguments launches the TUI
 brainfile tui      # Explicit subcommand also works
 ```
 
-### Panels
-- **Tasks (`1`)**: Kanban view of active tasks.
-- **Rules (`2`)**: Active rules and configuration.
-- **Logs (`3`)**: Completed task files.
+Completed work is the `L` done view, not a column and not a stop on `t`. `e` opens the document in `$EDITOR`.
 
 ### Keyboard Shortcuts
 | Key | Action |
 |-----|--------|
-| `tab` / `shift+tab` | Next / previous column in wide mode |
-| `j` / `k` | Down / up |
-| `enter` | Expand or collapse the selected task |
-| `n` | New task |
-| `m` | Move task |
-| `e` | Edit task in `$EDITOR` |
-| `/` | Search |
-| `?` | Show help |
+| `j` / `k` | Move selection |
+| `h` / `l` / `tab` | Cycle column |
+| `enter` | Open detail |
+| `t` | Cycle type |
+| `L` | Toggle done view |
+| `space` | Collapse parent / toggle subtask in detail |
+| `a` | Add |
+| `c` | Complete |
+| `e` | Edit in `$EDITOR` |
+| `/` | Filter |
+| `?` | Help |
 | `q` | Quit |
 
 ## AI Integration

package/dist/__tests__/helpers/mcp-wire.d.ts

@@ -0,0 +1,45 @@
+export type Era = 'legacy' | 'modern';
+export interface ToolResult {
+    content?: Array<{
+        type: string;
+        text?: string;
+    }>;
+    structuredContent?: unknown;
+    isError?: boolean;
+}
+export interface AdvertisedTool {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+}
+/**
+ * An MCP client speaking raw JSON-RPC to a real server over an in-memory
+ * transport. No `@modelcontextprotocol/client` package is installed, so the
+ * wire protocol is driven by hand.
+ */
+export declare class WireClient {
+    private readonly era;
+    private nextId;
+    private readonly pending;
+    private readonly clientTransport;
+    private readonly handle;
+    private constructor();
+    /** Opens a connection in the given era and completes the handshake. */
+    static open(brainfilePath: string, era: Era): Promise<WireClient>;
+    /**
+     * The 2026 era carries a `_meta` envelope on every request; the 2025 era
+     * carries none and its wire stays byte-identical to a plain stdio server.
+     */
+    private envelope;
+    private handshake;
+    request(method: string, params?: Record<string, unknown>, opts?: {
+        envelope?: boolean;
+    }): Promise<any>;
+    listTools(): Promise<AdvertisedTool[]>;
+    callTool(name: string, args?: Record<string, unknown>): Promise<ToolResult>;
+    /** The text of the first `type: 'text'` content block, if any. */
+    static text(result: ToolResult): string | undefined;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=mcp-wire.d.ts.map

package/dist/__tests__/helpers/mcp-wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-wire.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/mcp-wire.ts"],"names":[],"mappings":"AAmBA,MAAM,MAAM,GAAG,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAQtC,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACjD,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxC;AAED;;;;GAIG;AACH,qBAAa,UAAU;IAYnB,OAAO,CAAC,QAAQ,CAAC,GAAG;IAXtB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAGpB;IACJ,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAoB;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IAEpD,OAAO;IAoBP,uEAAuE;WAC1D,IAAI,CAAC,aAAa,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,UAAU,CAAC;IAWvE;;;OAGG;IACH,OAAO,CAAC,QAAQ;YAQF,SAAS;IAwBjB,OAAO,CACX,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EACpC,IAAI,GAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAO,GAChC,OAAO,CAAC,GAAG,CAAC;IAsBT,SAAS,IAAI,OAAO,CAAC,cAAc,EAAE,CAAC;IAKtC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAIrF,kEAAkE;IAClE,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS;IAI7C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/__tests__/helpers/mcp-wire.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WireClient = void 0;
+/**
+ * Drives the REAL MCP server over a real transport, in-process.
+ *
+ * `FakeMcpServer` (./mcp.ts) captures handler functions and calls them
+ * directly, which is fine for handler logic but structurally cannot see any
+ * of the SDK behaviour this helper exists to test: zod input parsing,
+ * `outputSchema` validation, the era-specific wire codec, or the
+ * `structuredContent` projection. Those only happen inside `McpServer` +
+ * `serveStdio`.
+ *
+ * `serveStdio` owns the era decision for a connection (the opening exchange
+ * picks it and pins one server instance), and it accepts a caller-supplied
+ * transport — so an `InMemoryTransport` linked pair gets the genuine
+ * two-era code path without spawning a process or requiring a built bundle.
+ */
+const server_1 = require("@modelcontextprotocol/server");
+const stdio_1 = require("@modelcontextprotocol/server/stdio");
+const mcp_1 = require("../../commands/mcp");
+/** Wire constants, matching @modelcontextprotocol/core's exported keys. */
+const PROTOCOL_VERSION_META_KEY = 'io.modelcontextprotocol/protocolVersion';
+const CLIENT_CAPABILITIES_META_KEY = 'io.modelcontextprotocol/clientCapabilities';
+const MODERN_PROTOCOL_VERSION = '2026-07-28';
+const LEGACY_PROTOCOL_VERSION = '2025-11-25';
+/**
+ * An MCP client speaking raw JSON-RPC to a real server over an in-memory
+ * transport. No `@modelcontextprotocol/client` package is installed, so the
+ * wire protocol is driven by hand.
+ */
+class WireClient {
+    constructor(clientTransport, handle, era) {
+        this.era = era;
+        this.nextId = 1;
+        this.pending = new Map();
+        this.clientTransport = clientTransport;
+        this.handle = handle;
+        this.clientTransport.onmessage = (message) => {
+            if (message?.id === undefined)
+                return;
+            const waiter = this.pending.get(message.id);
+            if (!waiter)
+                return;
+            this.pending.delete(message.id);
+            if (message.error) {
+                waiter.reject(new Error(`${message.error.code}: ${message.error.message}`));
+            }
+            else {
+                waiter.resolve(message.result);
+            }
+        };
+    }
+    /** Opens a connection in the given era and completes the handshake. */
+    static async open(brainfilePath, era) {
+        const [clientTransport, serverTransport] = server_1.InMemoryTransport.createLinkedPair();
+        const handle = (0, stdio_1.serveStdio)(() => (0, mcp_1.createBrainfileMcpServer)(brainfilePath), {
+            transport: serverTransport,
+        });
+        const client = new WireClient(clientTransport, handle, era);
+        await clientTransport.start();
+        await client.handshake();
+        return client;
+    }
+    /**
+     * The 2026 era carries a `_meta` envelope on every request; the 2025 era
+     * carries none and its wire stays byte-identical to a plain stdio server.
+     */
+    envelope() {
+        if (this.era !== 'modern')
+            return undefined;
+        return {
+            [PROTOCOL_VERSION_META_KEY]: MODERN_PROTOCOL_VERSION,
+            [CLIENT_CAPABILITIES_META_KEY]: {},
+        };
+    }
+    async handshake() {
+        if (this.era === 'legacy') {
+            await this.request('initialize', {
+                protocolVersion: LEGACY_PROTOCOL_VERSION,
+                capabilities: {},
+                clientInfo: { name: 'wire-test', version: '0.0.0' },
+            }, { envelope: false });
+            await this.clientTransport.send({
+                jsonrpc: '2.0',
+                method: 'notifications/initialized',
+                params: {},
+            });
+            return;
+        }
+        await this.request('server/discover', {
+            protocolVersions: [MODERN_PROTOCOL_VERSION],
+            clientInfo: { name: 'wire-test', version: '0.0.0' },
+        });
+    }
+    async request(method, params = {}, opts = {}) {
+        const id = this.nextId++;
+        const env = opts.envelope === false ? undefined : this.envelope();
+        const message = {
+            jsonrpc: '2.0',
+            id,
+            method,
+            params: env ? { ...params, _meta: env } : params,
+        };
+        const result = new Promise((resolve, reject) => {
+            this.pending.set(id, { resolve, reject });
+            setTimeout(() => {
+                if (this.pending.has(id)) {
+                    this.pending.delete(id);
+                    reject(new Error(`timeout waiting for ${method}`));
+                }
+            }, 15000).unref?.();
+        });
+        await this.clientTransport.send(message);
+        return result;
+    }
+    async listTools() {
+        const result = await this.request('tools/list', {});
+        return result.tools ?? [];
+    }
+    async callTool(name, args = {}) {
+        return this.request('tools/call', { name, arguments: args });
+    }
+    /** The text of the first `type: 'text'` content block, if any. */
+    static text(result) {
+        return result.content?.find((b) => b.type === 'text')?.text;
+    }
+    async close() {
+        await this.handle.close();
+    }
+}
+exports.WireClient = WireClient;
+//# sourceMappingURL=mcp-wire.js.map

package/dist/__tests__/helpers/mcp-wire.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-wire.js","sourceRoot":"","sources":["../../../src/__tests__/helpers/mcp-wire.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;GAcG;AACH,yDAAiE;AACjE,8DAAgE;AAChE,4CAA8D;AAI9D,2EAA2E;AAC3E,MAAM,yBAAyB,GAAG,yCAAyC,CAAC;AAC5E,MAAM,4BAA4B,GAAG,4CAA4C,CAAC;AAClF,MAAM,uBAAuB,GAAG,YAAY,CAAC;AAC7C,MAAM,uBAAuB,GAAG,YAAY,CAAC;AAe7C;;;;GAIG;AACH,MAAa,UAAU;IASrB,YACE,eAAkC,EAClC,MAAkC,EACjB,GAAQ;QAAR,QAAG,GAAH,GAAG,CAAK;QAXnB,WAAM,GAAG,CAAC,CAAC;QACF,YAAO,GAAG,IAAI,GAAG,EAG/B,CAAC;QASF,IAAI,CAAC,eAAe,GAAG,eAAe,CAAC;QACvC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,eAAe,CAAC,SAAS,GAAG,CAAC,OAAY,EAAE,EAAE;YAChD,IAAI,OAAO,EAAE,EAAE,KAAK,SAAS;gBAAE,OAAO;YACtC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAC5C,IAAI,CAAC,MAAM;gBAAE,OAAO;YACpB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YAChC,IAAI,OAAO,CAAC,KAAK,EAAE,CAAC;gBAClB,MAAM,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;YAC9E,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACjC,CAAC;QACH,CAAC,CAAC;IACJ,CAAC;IAED,uEAAuE;IACvE,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,aAAqB,EAAE,GAAQ;QAC/C,MAAM,CAAC,eAAe,EAAE,eAAe,CAAC,GAAG,0BAAiB,CAAC,gBAAgB,EAAE,CAAC;QAChF,MAAM,MAAM,GAAG,IAAA,kBAAU,EAAC,GAAG,EAAE,CAAC,IAAA,8BAAwB,EAAC,aAAa,CAAC,EAAE;YACvE,SAAS,EAAE,eAAe;SAC3B,CAAC,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC;QAC5D,MAAM,eAAe,CAAC,KAAK,EAAE,CAAC;QAC9B,MAAM,MAAM,CAAC,SAAS,EAAE,CAAC;QACzB,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACK,QAAQ;QACd,IAAI,IAAI,CAAC,GAAG,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC;QAC5C,OAAO;YACL,CAAC,yBAAyB,CAAC,EAAE,uBAAuB;YACpD,CAAC,4BAA4B,CAAC,EAAE,EAAE;SACnC,CAAC;IACJ,CAAC;IAEO,KAAK,CAAC,SAAS;QACrB,IAAI,IAAI,CAAC,GAAG,KAAK,QAAQ,EAAE,CAAC;YAC1B,MAAM,IAAI,CAAC,OAAO,CAChB,YAAY,EACZ;gBACE,eAAe,EAAE,uBAAuB;gBACxC,YAAY,EAAE,EAAE;gBAChB,UAAU,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE;aACpD,EACD,EAAE,QAAQ,EAAE,KAAK,EAAE,CACpB,CAAC;YACF,MAAM,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC;gBAC9B,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,2BAA2B;gBACnC,MAAM,EAAE,EAAE;aACJ,CAAC,CAAC;YACV,OAAO;QACT,CAAC;QACD,MAAM,IAAI,CAAC,OAAO,CAAC,iBAAiB,EAAE;YACpC,gBAAgB,EAAE,CAAC,uBAAuB,CAAC;YAC3C,UAAU,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,EAAE;SACpD,CAAC,CAAC;IACL,CAAC;IAED,KAAK,CAAC,OAAO,CACX,MAAc,EACd,SAAkC,EAAE,EACpC,OAA+B,EAAE;QAEjC,MAAM,EAAE,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACzB,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClE,MAAM,OAAO,GAAG;YACd,OAAO,EAAE,KAAc;YACvB,EAAE;YACF,MAAM;YACN,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,MAAM;SACjD,CAAC;QACF,MAAM,MAAM,GAAG,IAAI,OAAO,CAAM,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAClD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;YAC1C,UAAU,CAAC,GAAG,EAAE;gBACd,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC;oBACzB,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;oBACxB,MAAM,CAAC,IAAI,KAAK,CAAC,uBAAuB,MAAM,EAAE,CAAC,CAAC,CAAC;gBACrD,CAAC;YACH,CAAC,EAAE,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC;QACtB,CAAC,CAAC,CAAC;QACH,MAAM,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,OAAc,CAAC,CAAC;QAChD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,KAAK,CAAC,SAAS;QACb,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QACpD,OAAO,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,IAAY,EAAE,OAAgC,EAAE;QAC7D,OAAO,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,kEAAkE;IAClE,MAAM,CAAC,IAAI,CAAC,MAAkB;QAC5B,OAAO,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,EAAE,IAAI,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;CACF;AAxHD,gCAwHC"}