brainfile 0.20.0 → 0.21.1

package/dist/utils/actor.d.ts

@@ -0,0 +1,22 @@
+export type ActorSource = 'flag' | 'env' | 'process' | 'fingerprint' | 'git';
+export interface Actor {
+    name: string;
+    source: ActorSource;
+}
+/** The nearest agent CLI among this process's ancestors, or null. */
+export declare function agentFromProcessTree(startPid?: number): string | null;
+/**
+ * Environment variables agents set for the commands they run. Specific
+ * markers only: a Claude session can carry `CODEX_COMPANION_*` from a plugin,
+ * so a loose `CODEX_` prefix would misattribute it. Codex comes first because
+ * its sandbox hides the process tree while inheriting a parent Claude's
+ * variables when it was started from one.
+ */
+export declare function agentFromEnvironment(env?: NodeJS.ProcessEnv): string | null;
+/** The agent running this process, when one can be told; never the git user. */
+export declare function detectAgent(argv?: string[], env?: NodeJS.ProcessEnv): Actor | null;
+/** The agent, else the git user (`user.name`) for `cwd`, else null. */
+export declare function resolveActor(cwd?: string, argv?: string[]): Actor | null;
+/** For tests: forget the cached process-tree answer. */
+export declare function resetActorCache(): void;
+//# sourceMappingURL=actor.d.ts.map

package/dist/utils/actor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor.d.ts","sourceRoot":"","sources":["../../src/utils/actor.ts"],"names":[],"mappings":"AAqBA,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,KAAK,GAAG,SAAS,GAAG,aAAa,GAAG,KAAK,CAAC;AAE7E,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;CACrB;AA+DD,qEAAqE;AACrE,wBAAgB,oBAAoB,CAAC,QAAQ,GAAE,MAAqB,GAAG,MAAM,GAAG,IAAI,CAanF;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,IAAI,CAQxF;AAWD,gFAAgF;AAChF,wBAAgB,WAAW,CAAC,IAAI,GAAE,MAAM,EAAiB,EAAE,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,KAAK,GAAG,IAAI,CAoB7G;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,GAAG,GAAE,MAAsB,EAAE,IAAI,GAAE,MAAM,EAAiB,GAAG,KAAK,GAAG,IAAI,CAKrG;AAED,wDAAwD;AACxD,wBAAgB,eAAe,IAAI,IAAI,CAEtC"}

package/dist/utils/actor.js

@@ -0,0 +1,200 @@
+"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.agentFromProcessTree = agentFromProcessTree;
+exports.agentFromEnvironment = agentFromEnvironment;
+exports.detectAgent = detectAgent;
+exports.resolveActor = resolveActor;
+exports.resetActorCache = resetActorCache;
+/**
+ * Who is acting on the board. Board commits are always authored by the git
+ * user; the actor is what the board itself records: the `[name]` on a note
+ * and the `[name]` suffix on a board commit message.
+ *
+ *   1. `--agent <name>` or `BRAINFILE_AGENT`, when the agent says who it is
+ *   2. the nearest agent CLI among this process's ancestors (claude, codex, …)
+ *   3. an agent's environment fingerprint (for sandboxes that hide the
+ *      process tree, like Codex's)
+ *   4. the git user
+ *
+ * `BRAINFILE_DETECT_AGENT=off` turns off 2 and 3.
+ *
+ * Only agent command-line tools count. Desktop apps and editors (the Claude
+ * app, Cursor, VS Code) also host the person's own terminals, so a command
+ * under them is the person's.
+ */
+const fs = __importStar(require("fs"));
+const child_process_1 = require("child_process");
+const board_repo_1 = require("./board-repo");
+/** Executable name → the name recorded on the board. */
+const AGENT_BINARIES = {
+    claude: 'claude',
+    codex: 'codex',
+    'cursor-agent': 'cursor',
+    gemini: 'gemini',
+    opencode: 'opencode',
+    goose: 'goose',
+    droid: 'droid',
+    crush: 'crush',
+    aider: 'aider',
+    cline: 'cline',
+    amp: 'amp',
+    qwen: 'qwen',
+    copilot: 'copilot',
+};
+const MAX_DEPTH = 32;
+function sanitize(name) {
+    return name.replace(/[[\]<>\r\n]/g, '').trim();
+}
+function agentFromCommand(words) {
+    // A native binary shows as argv[0]; a node/python-wrapped CLI as argv[1].
+    for (const word of words.slice(0, 2)) {
+        const base = word.split('/').pop()?.replace(/\.(c|m)?js$/, '') ?? '';
+        if (AGENT_BINARIES[base])
+            return AGENT_BINARIES[base];
+    }
+    return null;
+}
+function linuxProc(pid) {
+    try {
+        const stat = fs.readFileSync(`/proc/${pid}/stat`, 'utf-8');
+        // The command name is in parentheses and may contain spaces.
+        const ppid = Number.parseInt(stat.slice(stat.lastIndexOf(')') + 2).split(' ')[1], 10);
+        const comm = stat.slice(stat.indexOf('(') + 1, stat.lastIndexOf(')'));
+        const cmdline = fs.readFileSync(`/proc/${pid}/cmdline`, 'utf-8').split('\0').filter(Boolean);
+        return { ppid, words: [comm, ...cmdline] };
+    }
+    catch {
+        return null;
+    }
+}
+function psTable() {
+    const r = (0, child_process_1.spawnSync)('ps', ['-A', '-o', 'pid=,ppid=,args='], { encoding: 'utf-8', timeout: 2000 });
+    if (r.status !== 0 || !r.stdout)
+        return null;
+    const table = new Map();
+    for (const line of r.stdout.split('\n')) {
+        const m = /^\s*(\d+)\s+(\d+)\s+(.*)$/.exec(line);
+        if (m)
+            table.set(Number(m[1]), { ppid: Number(m[2]), words: m[3].split(/\s+/) });
+    }
+    return table;
+}
+/** The nearest agent CLI among this process's ancestors, or null. */
+function agentFromProcessTree(startPid = process.ppid) {
+    const useProc = process.platform === 'linux' && fs.existsSync('/proc/self/stat');
+    const table = useProc ? null : process.platform === 'win32' ? null : psTable();
+    if (!useProc && !table)
+        return null;
+    let pid = startPid;
+    for (let depth = 0; depth < MAX_DEPTH && pid > 1; depth++) {
+        const info = useProc ? linuxProc(pid) : table?.get(pid) ?? null;
+        if (!info)
+            return null;
+        const agent = agentFromCommand(info.words);
+        if (agent)
+            return agent;
+        pid = info.ppid;
+    }
+    return null;
+}
+/**
+ * Environment variables agents set for the commands they run. Specific
+ * markers only: a Claude session can carry `CODEX_COMPANION_*` from a plugin,
+ * so a loose `CODEX_` prefix would misattribute it. Codex comes first because
+ * its sandbox hides the process tree while inheriting a parent Claude's
+ * variables when it was started from one.
+ */
+function agentFromEnvironment(env = process.env) {
+    if (env.CODEX_THREAD_ID || env.CODEX_SESSION_ID)
+        return 'codex';
+    if (env.GEMINI_CLI === '1')
+        return 'gemini';
+    if (env.CLAUDECODE === '1')
+        return 'claude';
+    // A shared convention some agents follow, e.g. `claude-code_2-1-280_agent`.
+    const generic = env.AI_AGENT?.split('_')[0];
+    if (generic)
+        return generic === 'claude-code' ? 'claude' : sanitize(generic) || null;
+    return null;
+}
+function flagValue(argv) {
+    const at = argv.indexOf('--agent');
+    if (at >= 0 && argv[at + 1] && !argv[at + 1].startsWith('-'))
+        return argv[at + 1];
+    const inline = argv.find((a) => a.startsWith('--agent='));
+    return inline ? inline.slice('--agent='.length) : null;
+}
+let detected = null;
+/** The agent running this process, when one can be told; never the git user. */
+function detectAgent(argv = process.argv, env = process.env) {
+    const flag = sanitize(flagValue(argv) ?? '');
+    if (flag)
+        return { name: flag, source: 'flag' };
+    const named = sanitize(env.BRAINFILE_AGENT ?? '');
+    if (named)
+        return { name: named, source: 'env' };
+    // `BRAINFILE_DETECT_AGENT=off` keeps only explicit names (the test runner
+    // sets it, so running the suite inside an agent does not change results).
+    if (env.BRAINFILE_DETECT_AGENT === 'off')
+        return null;
+    if (!detected) {
+        let value = null;
+        try {
+            value = agentFromProcessTree();
+        }
+        catch {
+            value = null;
+        }
+        detected = { value };
+    }
+    if (detected.value)
+        return { name: detected.value, source: 'process' };
+    const fingerprint = agentFromEnvironment(env);
+    return fingerprint ? { name: fingerprint, source: 'fingerprint' } : null;
+}
+/** The agent, else the git user (`user.name`) for `cwd`, else null. */
+function resolveActor(cwd = process.cwd(), argv = process.argv) {
+    const agent = detectAgent(argv);
+    if (agent)
+        return agent;
+    const user = sanitize((0, board_repo_1.git)(['config', '--get', 'user.name'], cwd).stdout);
+    return user ? { name: user, source: 'git' } : null;
+}
+/** For tests: forget the cached process-tree answer. */
+function resetActorCache() {
+    detected = null;
+}
+//# sourceMappingURL=actor.js.map

package/dist/utils/actor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"actor.js","sourceRoot":"","sources":["../../src/utils/actor.ts"],"names":[],"mappings":"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"}

package/dist/utils/board-autosync.d.ts

@@ -0,0 +1,22 @@
+import { type AutosyncMode, type SyncResult } from './board-sync';
+export declare const AUTOSYNC_DELAY_MS = 5000;
+export declare const FETCH_MAX_AGE_SECONDS = 60;
+export declare function effectiveAutosync(dotDir: string): AutosyncMode;
+/** The runnable CLI: the bundle we live in, or the built one next to the sources. */
+export declare function autosyncCliPath(): string | null;
+export declare function clearPushLock(dotDir: string): void;
+/**
+ * Queue a background push for the board. Returns true when a child was
+ * started; false when autosync is off, no remote is set, a push is already
+ * pending (it will carry this commit too), or there is no CLI to run.
+ */
+export declare function schedulePush(dotDir: string, delayMs?: number): boolean;
+/**
+ * In `full` mode, bring the board up to date before a read when the last
+ * sync attempt is older than `maxAgeSeconds`. Returns the sync result, or
+ * null when nothing was fetched.
+ */
+export declare function fetchBeforeRead(dotDir: string, maxAgeSeconds?: number): SyncResult | null;
+/** Push after every successful board commit made by this process. */
+export declare function installAutosync(): void;
+//# sourceMappingURL=board-autosync.d.ts.map

package/dist/utils/board-autosync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-autosync.d.ts","sourceRoot":"","sources":["../../src/utils/board-autosync.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,UAAU,EAA2D,MAAM,cAAc,CAAC;AAE3H,eAAO,MAAM,iBAAiB,OAAO,CAAC;AACtC,eAAO,MAAM,qBAAqB,KAAK,CAAC;AAKxC,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,YAAY,CAI9D;AAED,qFAAqF;AACrF,wBAAgB,eAAe,IAAI,MAAM,GAAG,IAAI,CAO/C;AAuBD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAMlD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,SAAoB,GAAG,OAAO,CAuBjF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,SAAwB,GAAG,UAAU,GAAG,IAAI,CAMxG;AAGD,qEAAqE;AACrE,wBAAgB,eAAe,IAAI,IAAI,CAMtC"}

package/dist/utils/board-autosync.js

@@ -0,0 +1,166 @@
+"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.FETCH_MAX_AGE_SECONDS = exports.AUTOSYNC_DELAY_MS = void 0;
+exports.effectiveAutosync = effectiveAutosync;
+exports.autosyncCliPath = autosyncCliPath;
+exports.clearPushLock = clearPushLock;
+exports.schedulePush = schedulePush;
+exports.fetchBeforeRead = fetchBeforeRead;
+exports.installAutosync = installAutosync;
+/**
+ * Autosync (spec-9 phase 3): keep a shared board flowing without anyone
+ * typing `sync`.
+ *
+ *   push  after every committed mutation, a detached `brainfile sync --push`
+ *         runs a few seconds later so bursts collapse into one push and the
+ *         mutation itself never waits on the network
+ *   full  additionally fetch before a read when the last sync is older than
+ *         a minute
+ *
+ * `BRAINFILE_AUTOSYNC=off|push|full` overrides the board's config for one
+ * process (tests and CI set `off`).
+ */
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+const board_repo_1 = require("./board-repo");
+const board_sync_1 = require("./board-sync");
+exports.AUTOSYNC_DELAY_MS = 5000;
+exports.FETCH_MAX_AGE_SECONDS = 60;
+const LOCK_FILE = path.join('state', 'autosync.lock');
+/** A pending push older than this is assumed dead (crashed child). */
+const LOCK_STALE_MS = 60000;
+function effectiveAutosync(dotDir) {
+    const override = process.env.BRAINFILE_AUTOSYNC;
+    if (override === 'off' || override === 'push' || override === 'full')
+        return override;
+    return (0, board_sync_1.boardAutosync)(dotDir);
+}
+/** The runnable CLI: the bundle we live in, or the built one next to the sources. */
+function autosyncCliPath() {
+    const candidates = [
+        path.join(__dirname, 'cli.js'),
+        path.join(__dirname, '..', 'cli.js'),
+        path.join(__dirname, '..', '..', 'dist', 'cli.js'),
+    ];
+    return candidates.find((p) => fs.existsSync(p)) ?? null;
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function pushPending(dotDir) {
+    const lock = path.join(dotDir, LOCK_FILE);
+    try {
+        const st = fs.statSync(lock);
+        if (Date.now() - st.mtimeMs > LOCK_STALE_MS)
+            return false;
+        const pid = Number.parseInt(fs.readFileSync(lock, 'utf-8'), 10);
+        return Number.isFinite(pid) && pidAlive(pid);
+    }
+    catch {
+        return false;
+    }
+}
+function clearPushLock(dotDir) {
+    try {
+        fs.rmSync(path.join(dotDir, LOCK_FILE), { force: true });
+    }
+    catch {
+        /* nothing to clear */
+    }
+}
+/**
+ * Queue a background push for the board. Returns true when a child was
+ * started; false when autosync is off, no remote is set, a push is already
+ * pending (it will carry this commit too), or there is no CLI to run.
+ */
+function schedulePush(dotDir, delayMs = exports.AUTOSYNC_DELAY_MS) {
+    if (!(0, board_repo_1.isTrackedBoard)(dotDir))
+        return false;
+    const mode = effectiveAutosync(dotDir);
+    if (mode === 'off' || !(0, board_sync_1.boardRemote)(dotDir))
+        return false;
+    if (pushPending(dotDir))
+        return false;
+    const cli = autosyncCliPath();
+    if (!cli)
+        return false;
+    const delay = process.env.BRAINFILE_AUTOSYNC_DELAY_MS ? Number(process.env.BRAINFILE_AUTOSYNC_DELAY_MS) : delayMs;
+    try {
+        const child = (0, child_process_1.spawn)(process.execPath, [cli, 'sync', '--push', '--file', path.join(dotDir, 'brainfile.md'), '--wait', String(delay)], { cwd: dotDir, detached: true, stdio: 'ignore', env: { ...process.env, BRAINFILE_AUTOSYNC: 'off' } });
+        child.unref();
+        if (child.pid) {
+            fs.mkdirSync(path.join(dotDir, 'state'), { recursive: true });
+            fs.writeFileSync(path.join(dotDir, LOCK_FILE), String(child.pid), 'utf-8');
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * In `full` mode, bring the board up to date before a read when the last
+ * sync attempt is older than `maxAgeSeconds`. Returns the sync result, or
+ * null when nothing was fetched.
+ */
+function fetchBeforeRead(dotDir, maxAgeSeconds = exports.FETCH_MAX_AGE_SECONDS) {
+    if (!(0, board_repo_1.isTrackedBoard)(dotDir))
+        return null;
+    if (effectiveAutosync(dotDir) !== 'full')
+        return null;
+    const age = (0, board_sync_1.secondsSinceSync)(dotDir);
+    if (age !== null && age < maxAgeSeconds)
+        return null;
+    return (0, board_sync_1.syncBoard)(dotDir, { pull: true, push: false });
+}
+let installed = false;
+/** Push after every successful board commit made by this process. */
+function installAutosync() {
+    if (installed)
+        return;
+    installed = true;
+    (0, board_repo_1.onBoardCommitted)((dotDir) => {
+        schedulePush(dotDir);
+    });
+}
+//# sourceMappingURL=board-autosync.js.map

package/dist/utils/board-autosync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-autosync.js","sourceRoot":"","sources":["../../src/utils/board-autosync.ts"],"names":[],"mappings":"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"}

package/dist/utils/board-commit-hooks.d.ts

@@ -0,0 +1,12 @@
+interface CommandLike {
+    name(): string;
+    args: string[];
+    opts(): Record<string, unknown>;
+    parent?: CommandLike | null;
+}
+export declare function topLevelCommandName(command: CommandLike): string;
+export declare function boardDirForCommand(command: CommandLike): string | null;
+export declare function beforeCommand(command: CommandLike): boolean;
+export declare function afterCommand(command: CommandLike): boolean;
+export {};
+//# sourceMappingURL=board-commit-hooks.d.ts.map

package/dist/utils/board-commit-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-commit-hooks.d.ts","sourceRoot":"","sources":["../../src/utils/board-commit-hooks.ts"],"names":[],"mappings":"AAYA,UAAU,WAAW;IACnB,IAAI,IAAI,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CAC7B;AAKD,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAQhE;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAItE;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAQ3D;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAI1D"}

package/dist/utils/board-commit-hooks.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.topLevelCommandName = topLevelCommandName;
+exports.boardDirForCommand = boardDirForCommand;
+exports.beforeCommand = beforeCommand;
+exports.afterCommand = afterCommand;
+/**
+ * Commander hooks that turn every CLI mutation into one commit on a tracked
+ * board (spec-9). `beforeCommand` commits hand edits on their own so they are
+ * never folded into the command's commit; `afterCommand` commits whatever the
+ * command changed, authored by the git user and tagged with the agent, if any.
+ */
+const board_repo_1 = require("./board-repo");
+const actor_1 = require("./actor");
+const brainfile_path_1 = require("./brainfile-path");
+const board_autosync_1 = require("./board-autosync");
+const board_sync_1 = require("./board-sync");
+/** Long-running or board-unrelated commands that manage their own commits, or none. */
+const SKIP_COMMANDS = new Set(['mcp', 'tui', 'hooks', 'auth', 'sync', 'merge-driver', 'where']);
+function topLevelCommandName(command) {
+    let cursor = command;
+    let name = command.name();
+    while (cursor.parent && cursor.parent.parent) {
+        cursor = cursor.parent;
+        name = cursor.name();
+    }
+    return name;
+}
+function boardDirForCommand(command) {
+    if (SKIP_COMMANDS.has(topLevelCommandName(command)))
+        return null;
+    const file = command.opts().file;
+    return (0, brainfile_path_1.tryResolveBoardDir)(typeof file === 'string' ? file : undefined);
+}
+function beforeCommand(command) {
+    const dotDir = boardDirForCommand(command);
+    if (!dotDir)
+        return false;
+    const committed = (0, board_repo_1.commitHandEdits)(dotDir);
+    // autosync=full: reads see other machines' work when the last sync is stale.
+    const fetched = (0, board_autosync_1.fetchBeforeRead)(dotDir);
+    if (fetched && !fetched.ok)
+        process.stderr.write(`${(0, board_sync_1.syncMessage)(fetched).text}\n`);
+    return committed;
+}
+function afterCommand(command) {
+    const dotDir = boardDirForCommand(command);
+    if (!dotDir)
+        return false;
+    return (0, board_repo_1.commitBoard)(dotDir, { message: (0, board_repo_1.describeCommandForCommit)(command), agent: (0, actor_1.detectAgent)()?.name });
+}
+//# sourceMappingURL=board-commit-hooks.js.map

package/dist/utils/board-commit-hooks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-commit-hooks.js","sourceRoot":"","sources":["../../src/utils/board-commit-hooks.ts"],"names":[],"mappings":";;AAsBA,kDAQC;AAED,gDAIC;AAED,sCAQC;AAED,oCAIC;AApDD;;;;;GAKG;AACH,6CAAsF;AACtF,mCAAsC;AACtC,qDAAsD;AACtD,qDAAmD;AACnD,6CAA2C;AAS3C,uFAAuF;AACvF,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,CAAC,CAAC,CAAC;AAEhG,SAAgB,mBAAmB,CAAC,OAAoB;IACtD,IAAI,MAAM,GAAgB,OAAO,CAAC;IAClC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAC1B,OAAO,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QAC7C,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QACvB,IAAI,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAgB,kBAAkB,CAAC,OAAoB;IACrD,IAAI,aAAa,CAAC,GAAG,CAAC,mBAAmB,CAAC,OAAO,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACjE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC;IACjC,OAAO,IAAA,mCAAkB,EAAC,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AACzE,CAAC;AAED,SAAgB,aAAa,CAAC,OAAoB;IAChD,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,MAAM,SAAS,GAAG,IAAA,4BAAe,EAAC,MAAM,CAAC,CAAC;IAC1C,6EAA6E;IAC7E,MAAM,OAAO,GAAG,IAAA,gCAAe,EAAC,MAAM,CAAC,CAAC;IACxC,IAAI,OAAO,IAAI,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAA,wBAAW,EAAC,OAAO,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC;IACnF,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAgB,YAAY,CAAC,OAAoB;IAC/C,MAAM,MAAM,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,OAAO,IAAA,wBAAW,EAAC,MAAM,EAAE,EAAE,OAAO,EAAE,IAAA,qCAAwB,EAAC,OAAO,CAAC,EAAE,KAAK,EAAE,IAAA,mBAAW,GAAE,EAAE,IAAI,EAAE,CAAC,CAAC;AACzG,CAAC"}

package/dist/utils/board-repo.d.ts

@@ -0,0 +1,132 @@
+export declare const DEFAULT_BOARD_BRANCH = "brainfile";
+export declare const BOARD_BRANCH_CONFIG_KEY = "brainfile.branch";
+/**
+ * On a remote, a board is stored under `refs/brainfile/<name>` rather than as
+ * a branch: hosts list, badge and offer pull requests for branches only, so
+ * the board stays out of the project's branch list while still being pushed,
+ * fetched and kept like any other ref. Locally the last-known remote position
+ * lives under `refs/brainfile/remotes/<remote>/<name>`, outside `refs/remotes/`
+ * so a user's `git fetch --prune` never deletes it.
+ */
+export declare const BOARD_REF_NAMESPACE = "refs/brainfile";
+export declare const BOARD_NAME_CONFIG_KEY = "brainfile.boardName";
+/** 0.21.0 key: the branch the board was pushed to. Still read as the name. */
+export declare const LEGACY_REMOTE_BRANCH_CONFIG_KEY = "brainfile.remoteBranch";
+/** Default name for a board that lives in a code repository. */
+export declare const DEFAULT_BOARD_NAME = "board";
+export declare function remoteBoardRef(name: string): string;
+export declare function boardTrackingRef(remote: string, name: string): string;
+export declare function gitNetwork(args: string[], cwd: string): GitResult;
+export interface GitResult {
+    ok: boolean;
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Run git synchronously. Never throws; a missing git binary is `ok: false`. */
+export declare function git(args: string[], cwd: string, env?: NodeJS.ProcessEnv, timeoutMs?: number): GitResult;
+/** Toplevel of the working tree containing `cwd`, or null outside any repo. */
+export declare function gitToplevel(cwd: string): string | null;
+/** The git directory shared by every worktree of the repo containing `cwd`. */
+export declare function gitCommonDir(cwd: string): string | null;
+export interface WorktreeEntry {
+    path: string;
+    head?: string;
+    /** Full ref, e.g. `refs/heads/brainfile`; absent when detached or bare. */
+    branch?: string;
+    bare: boolean;
+    detached: boolean;
+}
+/** `git worktree list --porcelain`, parsed. Empty outside a repo. */
+export declare function listWorktrees(cwd: string): WorktreeEntry[];
+/** Name of the board branch for the repo containing `cwd` (`brainfile.branch`, default `brainfile`). */
+export declare function boardBranch(cwd: string): string;
+export type BoardRepoKind = 'linked' | 'standalone';
+/**
+ * How the board directory is tracked: a linked worktree (`.git` is a gitdir
+ * pointer file), a standalone repository (`.git` is a directory), or null for
+ * a plain directory.
+ */
+export declare function boardRepoKind(dotDir: string): BoardRepoKind | null;
+export declare function isTrackedBoard(dotDir: string): boolean;
+/**
+ * Resolution step 3: from anywhere inside a repo (including a linked code
+ * worktree that has no `.brainfile/` of its own), find the worktree checked
+ * out on the board branch.
+ */
+export declare function findTrackedBoardDir(cwd: string): string | null;
+/**
+ * Board names published on `remote` (`refs/brainfile/<name>`), or null when
+ * the remote could not be asked. One network round trip.
+ */
+export declare function listRemoteBoards(cwd: string, remote: string): string[] | null;
+export interface MaterializeOptions {
+    /** Ask the remote even if a recent lookup found nothing (after `--set-remote`). */
+    fresh?: boolean;
+}
+/**
+ * Resolution step 4: the board is not checked out anywhere (a fresh clone,
+ * or the directory was removed). Create the worktree at
+ * `<main worktree>/.brainfile` — or inside the common git dir for bare
+ * layouts — and hide it from the code branch. Returns the new board
+ * directory, or null when there is nothing to materialize.
+ */
+export declare function materializeBoardWorktree(cwd: string, options?: MaterializeOptions): string | null;
+/** Hide `.brainfile/` from the code branch without touching `.gitignore`. Returns true when an entry was added. */
+export declare function ensureExcludeEntry(cwd: string): boolean;
+/** Remove the exclude entry, but only the one we wrote (identified by its marker). */
+export declare function removeExcludeEntry(cwd: string): boolean;
+/** `git worktree add --orphan -b <branch> <dotDir>` (git >= 2.42). */
+export declare function createOrphanBoardWorktree(repoCwd: string, dotDir: string, branch: string): void;
+/** `git init` inside the board directory for boards outside any repo. */
+export declare function initStandaloneBoardRepo(dotDir: string): void;
+export declare function boardIsDirty(dotDir: string): boolean;
+export declare function boardHasCommits(dotDir: string): boolean;
+/** Files with uncommitted changes, relative to the board directory. */
+/** Paths still carrying conflict markers from an unfinished merge. */
+export declare function unmergedFiles(dotDir: string): string[];
+export declare function boardDirtyFiles(dotDir: string): string[];
+type CommitListener = (dotDir: string) => void;
+/** Run `listener` after every successful board commit made by this process. */
+export declare function onBoardCommitted(listener: CommitListener): void;
+export interface CommitBoardOptions {
+    message: string;
+    /** The agent acting, recorded as a `[name]` suffix; the author stays the git user. */
+    agent?: string | null;
+}
+/**
+ * Stage everything in the board directory and commit it. Returns true when a
+ * commit was made, false when the board is plain or nothing changed. Never
+ * throws: a failed commit must not fail the mutation it records.
+ */
+/**
+ * git does not store empty directories, and a board without `board/` reads
+ * as legacy on the other side. Keep both alive with a `.gitkeep`.
+ */
+export declare function ensureBoardDirs(dotDir: string): boolean;
+export declare function commitBoard(dotDir: string, options: CommitBoardOptions): boolean;
+/**
+ * Commit outstanding hand edits (files changed outside the CLI) before a
+ * command mutates, so they are never folded into that command's commit.
+ */
+export declare function commitHandEdits(dotDir: string): boolean;
+/** The home board: `~/.brainfile`, addressed with `-g` / `--global` or `BRAINFILE_GLOBAL=1`. */
+export declare function homeBoardDir(): string;
+export declare function isGlobalBoardRequested(argv?: string[]): boolean;
+interface CommandLike {
+    name(): string;
+    args: string[];
+    opts(): Record<string, unknown>;
+    parent?: CommandLike | null;
+}
+/**
+ * Commit message for a CLI invocation: `<verb> <id>: <detail>`, e.g.
+ * `move task-3: in-progress`, `add: Fix login bug`, `contract pickup task-2`.
+ */
+export declare function describeCommandForCommit(command: CommandLike): string;
+/** Queue a commit for a board; bursts of edits within `delayMs` become one commit. */
+export declare function scheduleBoardCommit(brainfilePath: string, message: string, delayMs?: number): void;
+/** Commit every queued board now. Safe to call from an `exit` handler (synchronous). */
+export declare function flushBoardCommits(): void;
+export {};
+//# sourceMappingURL=board-repo.d.ts.map

package/dist/utils/board-repo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"board-repo.d.ts","sourceRoot":"","sources":["../../src/utils/board-repo.ts"],"names":[],"mappings":"AAkBA,eAAO,MAAM,oBAAoB,cAAc,CAAC;AAChD,eAAO,MAAM,uBAAuB,qBAAqB,CAAC;AAE1D;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AACpD,eAAO,MAAM,qBAAqB,wBAAwB,CAAC;AAC3D,8EAA8E;AAC9E,eAAO,MAAM,+BAA+B,2BAA2B,CAAC;AACxE,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,UAAU,CAAC;AAE1C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAErE;AAKD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAEjE;AAQD,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gFAAgF;AAChF,wBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAcvG;AAED,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGtD;AAED,+EAA+E;AAC/E,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIvD;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,EAAE,CAsB1D;AAED,wGAAwG;AACxG,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAG/C;AAED,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,YAAY,CAAC;AAEpD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CASlE;AAED,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAO9D;AAoCD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAU7E;AAED,MAAM,WAAW,kBAAkB;IACjC,mFAAmF;IACnF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAoDD;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,MAAM,GAAG,IAAI,CAsCrG;AAED,mHAAmH;AACnH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAavD;AAED,sFAAsF;AACtF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAYvD;AAED,sEAAsE;AACtE,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAO/F;AAED,yEAAyE;AACzE,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAK5D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAGpD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED,uEAAuE;AACvE,sEAAsE;AACtE,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAGtD;AAED,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CASxD;AASD,KAAK,cAAc,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;AAG/C,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,cAAc,GAAG,IAAI,CAE/D;AAYD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;GAIG;AACH;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAgBvD;AAED,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAgBhF;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAavD;AAED,gGAAgG;AAChG,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,wBAAgB,sBAAsB,CAAC,IAAI,GAAE,MAAM,EAAiB,GAAG,OAAO,CAG7E;AASD,UAAU,WAAW;IACnB,IAAI,IAAI,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,CAAC,EAAE,WAAW,GAAG,IAAI,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAerE;AAQD,sFAAsF;AACtF,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,SAAO,GAAG,IAAI,CAahG;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,IAAI,IAAI,CAWxC"}