brainfile 0.18.0

package/README.md

@@ -0,0 +1,222 @@
+# @brainfile/cli
+
+CLI for the [Brainfile](https://brainfile.md) task coordination protocol. Manage tasks, contracts, and ADRs from your terminal. Includes a TUI board view and an MCP server for AI agent integration.
+
+## Install
+
+```bash
+npm i -g @brainfile/cli
+```
+
+## Quick Start
+
+Initialize a new brainfile in your project root:
+
+```bash
+brainfile init
+```
+
+This creates the standard v2 structure:
+- `.brainfile/brainfile.md` (Configuration, rules, definitions)
+- `.brainfile/board/` (Active tasks)
+- `.brainfile/logs/` (Completed task files)
+
+The board comes pre-configured with `To Do` and `In Progress` columns.
+
+### Migrating older layouts
+
+If your repo still has a legacy `brainfile.md` layout, normal runtime commands will ask you to migrate before continuing. Run `brainfile migrate` from the directory that contains the old file, or pass `--dir` to point at that directory:
+
+```bash
+brainfile migrate --dir .
+```
+
+This upgrades your workspace to v2 (`.brainfile/brainfile.md` + `board/` + `logs/`). Use `--logs-to-ledger` when you also want legacy `logs/*.md` files migrated into `ledger.jsonl`.
+
+## Core Workflow
+
+### Add Tasks
+Create new tasks with rich metadata.
+
+```bash
+# Basic task
+brainfile add --title "Implement login" --column todo
+
+# Full featured task
+brainfile add \
+  --title "Refactor database layer" \
+  --type task \
+  --column todo \
+  --priority high \
+  --assignee @josh \
+  --tags "refactor,db" \
+  --parent epic-123
+
+# Create a parent with children in one shot
+brainfile add -c todo -t "Auth overhaul" \
+  --child "OAuth flow" --child "Session hardening"
+```
+
+**Key Flags:**
+- `--title, -t`: Task summary
+- `--type`: `task`, `epic`, or `adr` (default: `task`)
+- `--column, -c`: Target column ID
+- `--parent`: Parent task/epic ID
+- `--child`: Create child task(s) under the new parent (repeatable)
+- `--priority, -p`: `low`, `medium`, `high`, `critical`
+- `--tags`: Comma-separated list
+
+### List Tasks
+View your board from the command line.
+
+```bash
+brainfile list                        # View all active tasks
+brainfile list --column todo          # Filter by column
+brainfile list --tag bug              # Filter by tag
+brainfile list --parent epic-123      # See all children of an epic
+brainfile list --contract ready       # See tasks with contracts waiting for pickup
+```
+
+### Manage Tasks
+Manipulate tasks as you work.
+
+```bash
+# View details
+brainfile show -t task-10
+
+# Move to another column
+brainfile move -t task-10 -c in-progress
+
+# Update fields
+brainfile patch -t task-10 --priority critical --tags "frontend,urgent"
+
+# Clear fields
+brainfile patch -t task-10 --clear-tags --clear-assignee
+
+# Delete (permanently)
+brainfile delete -t task-10 --force
+```
+
+### Complete
+When a task is done, complete it from the active board.
+
+```bash
+brainfile complete -t task-10
+```
+This writes `.brainfile/logs/task-10.md` with a completion timestamp and removes the active task file from `.brainfile/board/`. Use `brainfile log` to view completed task history.
+
+## Types
+
+Brainfile supports different document types.
+
+```bash
+brainfile types list           # See configured types
+brainfile types list --json    # Output configured types as JSON
+brainfile types add epic       # Add a type (use --id-prefix, --completable, or --schema to customize it)
+```
+
+## Contracts: Working with AI Agents
+
+Contracts allow you to define explicit deliverables and validation rules for AI agents.
+
+### 1. Create a Contract
+Add a task with a contract definition.
+
+```bash
+brainfile add -c todo -t "Optimize image loader" \
+  --with-contract \
+  --deliverable "file:src/utils/loader.ts:Optimized implementation" \
+  --validation "npm test -- loader" \
+  --constraint "Must use lazy loading"
+```
+
+### 2. Pickup (Agent)
+The agent claims the task.
+
+```bash
+brainfile contract pickup -t task-45
+```
+Status changes to `in_progress`. Metrics tracking begins.
+
+### 3. Deliver (Agent)
+The agent marks work as ready for review.
+
+```bash
+brainfile contract deliver -t task-45
+```
+Status changes to `delivered`.
+
+### 4. Validate (User)
+Run the validation commands and check deliverables.
+
+```bash
+brainfile contract validate -t task-45
+```
+- **Pass**: Contract status becomes `done`.
+- **Fail**: Contract status becomes `failed` and records feedback for rework.
+
+## ADR Promotion
+
+Architecture Decision Records (ADRs) are first-class task files. You can promote an ADR into a project rule.
+
+```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
+```
+
+**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/`.
+
+## TUI (Terminal UI)
+
+Launch the interactive board:
+
+```bash
+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.
+
+### 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 |
+| `q` | Quit |
+
+## AI Integration
+
+The CLI includes an MCP (Model Context Protocol) server.
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "brainfile": {
+      "command": "npx",
+      "args": ["@brainfile/cli", "mcp"]
+    }
+  }
+}
+```
+
+This registers MCP tools to list, read, search, create, update, move, complete, and delete tasks; manage subtasks; and run contract workflows.

package/dist/__tests__/helpers/v2.d.ts

@@ -0,0 +1,12 @@
+import { type Task } from '@brainfile/core';
+export interface V2TestWorkspace {
+    tempDir: string;
+    dotDir: string;
+    brainfilePath: string;
+    boardDir: string;
+    logsDir: string;
+}
+export declare function createV2TestWorkspace(prefix?: string, config?: string): V2TestWorkspace;
+export declare function writeV2Task(workspace: V2TestWorkspace, task: Task, body?: string): string;
+export declare function readV2Task(workspace: V2TestWorkspace, taskId: string): import("@brainfile/core").TaskDocument | null;
+//# sourceMappingURL=v2.d.ts.map

package/dist/__tests__/helpers/v2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2.d.ts","sourceRoot":"","sources":["../../../src/__tests__/helpers/v2.ts"],"names":[],"mappings":"AAGA,OAAO,EAA6C,KAAK,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAEvF,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,qBAAqB,CACnC,MAAM,SAAuB,EAC7B,MAAM,SAWP,GACE,eAAe,CAYjB;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,eAAe,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,SAAK,GAAG,MAAM,CAIrF;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,iDAEpE"}

package/dist/__tests__/helpers/v2.js

@@ -0,0 +1,73 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createV2TestWorkspace = createV2TestWorkspace;
+exports.writeV2Task = writeV2Task;
+exports.readV2Task = readV2Task;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+const core_1 = require("@brainfile/core");
+function createV2TestWorkspace(prefix = 'brainfile-v2-test-', config = `---
+title: Test Board
+schema: https://brainfile.md/v2/board.json
+columns:
+  - id: todo
+    title: To Do
+  - id: in-progress
+    title: In Progress
+  - id: done
+    title: Done
+---
+`) {
+    const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+    const dotDir = path.join(tempDir, '.brainfile');
+    const boardDir = path.join(dotDir, 'board');
+    const logsDir = path.join(dotDir, 'logs');
+    const brainfilePath = path.join(dotDir, 'brainfile.md');
+    fs.mkdirSync(boardDir, { recursive: true });
+    fs.mkdirSync(logsDir, { recursive: true });
+    fs.writeFileSync(brainfilePath, config, 'utf-8');
+    return { tempDir, dotDir, brainfilePath, boardDir, logsDir };
+}
+function writeV2Task(workspace, task, body = '') {
+    const filePath = path.join(workspace.boardDir, (0, core_1.taskFileName)(task.id));
+    (0, core_1.writeTaskFile)(filePath, task, body);
+    return filePath;
+}
+function readV2Task(workspace, taskId) {
+    return (0, core_1.readTaskFile)(path.join(workspace.boardDir, (0, core_1.taskFileName)(taskId)));
+}
+//# sourceMappingURL=v2.js.map

package/dist/__tests__/helpers/v2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"v2.js","sourceRoot":"","sources":["../../../src/__tests__/helpers/v2.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAaA,sDA0BC;AAED,kCAIC;AAED,gCAEC;AAjDD,uCAAyB;AACzB,uCAAyB;AACzB,2CAA6B;AAC7B,0CAAuF;AAUvF,SAAgB,qBAAqB,CACnC,MAAM,GAAG,oBAAoB,EAC7B,MAAM,GAAG;;;;;;;;;;;CAWV;IAEC,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1C,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAExD,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5C,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC3C,EAAE,CAAC,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;IAEjD,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;AAC/D,CAAC;AAED,SAAgB,WAAW,CAAC,SAA0B,EAAE,IAAU,EAAE,IAAI,GAAG,EAAE;IAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAA,mBAAY,EAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IACtE,IAAA,oBAAa,EAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IACpC,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAgB,UAAU,CAAC,SAA0B,EAAE,MAAc;IACnE,OAAO,IAAA,mBAAY,EAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAA,mBAAY,EAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAC3E,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}