ctxr-cli 0.30.0 → 0.31.0

package/dist/core/mcp/surface.js

@@ -0,0 +1,141 @@
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+import { ContextureError } from '../errors.js';
+import { handleMcpRequest, MCP_PATH, sendText } from './http.js';
+import { ToolRefusal } from './jsonrpc.js';
+import { AuthorizationServer, OAUTH_PATHS, Signer } from './oauth.js';
+import { renderConsentPage } from './pages.js';
+import { Mutex } from './sessions.js';
+import { McpView } from './sync.js';
+import { buildTools, serverInstructions } from './tools/index.js';
+/**
+ * serve-the-store-over-mcp design.md D3, D10 (remote-access spec): the MCP
+ * surface `ctxr serve` routes its MCP paths to. One per server, holding only
+ * what must outlive a configuration reload — the read view, the spent-code
+ * nonces, and the signer. Everything else is built per request from the
+ * state `serve` last loaded, so adding, changing or removing the `mcp` block
+ * takes effect on the next request with no restart.
+ */
+/** Every path the MCP surface answers; `serve` routes these here ahead of its own routes. */
+export function isMcpPath(pathname) {
+    return pathname === MCP_PATH || OAUTH_PATHS.includes(pathname);
+}
+/** HKDF info for the token-signing key derived from the App's private key (design.md D5). Changing it signs everyone out. */
+const SIGNING_KEY_INFO = 'contexture mcp token signing v1';
+function describeMessage(body) {
+    const one = (m) => {
+        if (typeof m !== 'object' || m === null)
+            return '?';
+        const message = m;
+        if (message.method === 'tools/call')
+            return `tools/call ${typeof message.params?.name === 'string' ? message.params.name : '?'}`;
+        return typeof message.method === 'string' ? message.method : 'response';
+    };
+    return Array.isArray(body) ? `[${body.map(one).join(', ')}]` : one(body);
+}
+export class McpSurface {
+    options;
+    view;
+    spentCodes = new Map();
+    mutex = new Mutex();
+    signers = new Map();
+    randomKey;
+    /** Derived once per credential: the key never changes while a credential object lives. */
+    derived = new WeakMap();
+    repoPrefix;
+    constructor(options) {
+        this.options = options;
+        this.view = new McpView({ git: options.git, canonicalRoot: options.canonicalRoot, now: options.now });
+    }
+    /** The App-derived key when there is an App; otherwise one random key for this process, said once. */
+    signerFor(approval) {
+        if (!this.derived.has(approval.credentials))
+            this.derived.set(approval.credentials, approval.credentials.derivedSecret(SIGNING_KEY_INFO));
+        let key = this.derived.get(approval.credentials) ?? null;
+        if (key === null) {
+            if (this.randomKey === undefined) {
+                this.randomKey = randomBytes(32);
+                this.options.log("serve: MCP sign-in tokens are signed with a per-process key (the forge credential is gh's own, not a GitHub App); members sign in again after each restart.");
+            }
+            key = this.randomKey;
+        }
+        const id = key.toString('hex');
+        let signer = this.signers.get(id);
+        if (signer === undefined) {
+            signer = new Signer(key);
+            this.signers.set(id, signer);
+        }
+        return signer;
+    }
+    async handle(state, req, res, pathname) {
+        const method = req.method ?? 'GET';
+        const config = state.store.config;
+        // context-browsing spec: without the block these paths are no different from any unknown path.
+        if (config.mcp === undefined) {
+            if (method === 'GET' || method === 'HEAD')
+                sendText(res, 404, 'not found\n');
+            else
+                sendText(res, 405, 'method not allowed\n');
+            return;
+        }
+        if (state.approval === null) {
+            sendText(res, 503, `The MCP surface is unavailable: ${state.approvalError ?? 'change approval could not be set up'}.\n`);
+            return;
+        }
+        const approval = state.approval;
+        const issuer = approval.origin;
+        const storeName = path.basename(state.store.root);
+        const oauth = new AuthorizationServer({
+            issuer,
+            resource: `${issuer}${MCP_PATH}`,
+            identityHeader: approval.approval.identity.header,
+            verifier: approval.verifier,
+            mcp: () => config.mcp,
+            signer: this.signerFor(approval),
+            spentCodes: this.spentCodes,
+            now: this.options.now,
+            renderConsentPage: (view) => renderConsentPage(storeName, view),
+            log: this.options.log,
+        });
+        if (await oauth.handle(req, res, pathname)) {
+            this.options.log(`mcp ${method} ${pathname} -> ${res.statusCode}`);
+            return;
+        }
+        this.repoPrefix ??= (await this.options.git.run(['rev-parse', '--show-prefix'], { cwd: this.options.canonicalRoot, allowFailure: true })).stdout.trim();
+        const syncDeps = { config, credentials: approval.credentials, forge: approval.forge, env: this.options.env };
+        const tools = buildTools({
+            view: this.view,
+            syncDeps,
+            write: {
+                ...syncDeps,
+                git: this.options.git,
+                canonicalRoot: this.options.canonicalRoot,
+                now: this.options.now,
+                recordingLogin: approval.approval.recording_login,
+                baseUrl: config.serve?.base_url ?? issuer,
+                repoPrefix: this.repoPrefix,
+            },
+            mutex: this.mutex,
+            baseUrl: config.serve?.base_url,
+        });
+        const instructions = serverInstructions(storeName);
+        await handleMcpRequest({
+            originAllowed: (origin) => origin === issuer,
+            authenticate: (r) => oauth.authenticate(r),
+            onMessage: (principal, body) => this.options.log(`mcp ${principal.email}: ${describeMessage(body)}`),
+            contextFor: (principal) => ({
+                principal,
+                tools: () => tools.filter((tool) => principal.scopes.includes(tool.scope)),
+                lookup: (name) => tools.find((tool) => tool.name === name),
+                instructions,
+                authorizeCall: (tool) => {
+                    if (!principal.scopes.includes(tool.scope)) {
+                        throw new ToolRefusal('mcp.insufficient_scope', `Calling "${tool.name}" needs the "${tool.scope}" scope.`);
+                    }
+                },
+                refusalFor: (err) => (err instanceof ContextureError ? new ToolRefusal(err.finding.code, err.finding.message, err.finding.details) : undefined),
+            }),
+        }, req, res, pathname);
+    }
+}
+//# sourceMappingURL=surface.js.map

package/dist/core/mcp/surface.js.map

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

package/dist/core/mcp/sync.d.ts

@@ -0,0 +1,91 @@
+import type { StoreConfig } from '../../config/schema.js';
+import type { ForgeCredentials } from '../forge/credentials.js';
+import type { ForgeClient } from '../forge/github.js';
+import type { GitRunner } from '../git/exec.js';
+import type { Store } from '../store.js';
+/**
+ * serve-the-store-over-mcp design.md D6 (remote-access spec, *The surface
+ * reads from a checkout of its own*): the canonical checkout `serve` was
+ * started on is shared with the agents and moved by `ctxr land`, so the MCP
+ * surface never changes it. It reads from a detached worktree of its own
+ * under the derived cache path, which it moves by forced checkout to the
+ * remote default branch at most once per interval, with its own graph. A
+ * reader-writer lock keeps every tool call on one commit; a sync that cannot
+ * finish restores the view and its graph together, or refuses calls until a
+ * sync works.
+ */
+export declare const DEFAULT_SYNC_INTERVAL_SECONDS = 60;
+/** An inbox file added by a session branch that has an open pull request — a capture awaiting a decision. */
+export interface PendingCapture {
+    branch: string;
+    /** Store-relative. */
+    path: string;
+    text: string;
+}
+export interface StoreState {
+    head: string;
+    sync_error: string | null;
+}
+export interface Snapshot {
+    head: string;
+    /** The view as a store: its own root, and the configuration committed at `head`. */
+    store: Store;
+    pending: readonly PendingCapture[];
+}
+/** What a sync needs from the server's current state — re-read per request, so configuration reloads apply. */
+export interface SyncDeps {
+    /** The configuration `serve` loaded for the canonical checkout (session prefix, default branch). */
+    config: StoreConfig;
+    credentials: ForgeCredentials;
+    forge: ForgeClient;
+    env: Readonly<Record<string, string | undefined>>;
+}
+export interface ViewOptions {
+    git: GitRunner;
+    /** The store root `serve` was started on. */
+    canonicalRoot: string;
+    intervalSeconds?: number;
+    now(): Date;
+}
+/** Where the view's worktree lives: under the canonical checkout's derived cache, beside the graph. */
+export declare function viewWorktreeDir(canonicalRoot: string): string;
+export declare class McpView {
+    private readonly options;
+    private readonly lock;
+    private readonly intervalMs;
+    private head;
+    private lastError;
+    private unavailable;
+    private lastSyncAt;
+    private syncing;
+    private pending;
+    private viewStore;
+    /** The canonical store root's path inside its repository ("" at the top level, else "sub/dir/"). */
+    private repoPrefix;
+    constructor(options: ViewOptions);
+    private run;
+    get state(): StoreState;
+    /** Runs `fn` against one commit, after a sync if one is due, and stamps the result with what it read. */
+    read<T extends object>(deps: SyncDeps, fn: (snapshot: Snapshot) => Promise<T>): Promise<T & {
+        store: StoreState;
+    }>;
+    /** For `capture`: a sync forced now, so the duplicate check sees what was pushed and opened a moment ago (design.md D9). */
+    refresh(deps: SyncDeps): Promise<void>;
+    private maybeSync;
+    private ensureView;
+    /** Exclusive: no tool call is reading while this runs. */
+    private syncOnce;
+    /** Forced, detached, and cleaned of untracked files — the view is this surface's alone. Null on success. */
+    private checkout;
+    /** The configuration committed at the view's commit, and that commit's graph. */
+    private rebuild;
+    /** Back to `commit` with its graph; null on success, else why not. */
+    private restore;
+    /**
+     * design.md D6–D7: "pending" means what the approval index means by it — a
+     * session branch with an open pull request. Returns an error line when the
+     * forge could not be read, keeping the previous list.
+     */
+    private readPending;
+}
+//# sourceMappingURL=sync.d.ts.map

package/dist/core/mcp/sync.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/sync.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAMhD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAIzC;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,6BAA6B,KAAK,CAAC;AAEhD,6GAA6G;AAC7G,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,SAAS,cAAc,EAAE,CAAC;CACpC;AAED,+GAA+G;AAC/G,MAAM,WAAW,QAAQ;IACvB,oGAAoG;IACpG,MAAM,EAAE,WAAW,CAAC;IACpB,WAAW,EAAE,gBAAgB,CAAC;IAC9B,KAAK,EAAE,WAAW,CAAC;IACnB,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,SAAS,CAAC;IACf,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,GAAG,IAAI,IAAI,CAAC;CACb;AAMD,uGAAuG;AACvG,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE7D;AAED,qBAAa,OAAO;IAaN,OAAO,CAAC,QAAQ,CAAC,OAAO;IAZpC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAuB;IAC5C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,IAAI,CAAM;IAClB,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,SAAS,CAAoB;IACrC,oGAAoG;IACpG,OAAO,CAAC,UAAU,CAAqB;IAEvC,YAA6B,OAAO,EAAE,WAAW,EAEhD;IAED,OAAO,CAAC,GAAG;IAIX,IAAI,KAAK,IAAI,UAAU,CAEtB;IAED,yGAAyG;IACnG,IAAI,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,GAAG;QAAE,KAAK,EAAE,UAAU,CAAA;KAAE,CAAC,CASvH;IAED,4HAA4H;IACtH,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAE3C;YAEa,SAAS;YAUT,UAAU;IAaxB,0DAA0D;YAC5C,QAAQ;IAwDtB,4GAA4G;YAC9F,QAAQ;IAOtB,iFAAiF;YACnE,OAAO;IAUrB,sEAAsE;YACxD,OAAO;IAWrB;;;;OAIG;YACW,WAAW;CA2B1B"}

package/dist/core/mcp/sync.js

@@ -0,0 +1,218 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { readConfig } from '../../config/load.js';
+import { MIGRATION_STEPS } from '../../config/migrations.js';
+import { sessionWorktrees } from '../approval/sessions.js';
+import { runRemoteGit } from '../forge/credentials.js';
+import { isUnderAnyPrefix } from '../fs/prefix.js';
+import { pruneWorktrees } from '../git/worktree.js';
+import { renderGraphDocument } from '../graph/document.js';
+import { buildGraphFromNotes, graphBuildOptions } from '../graph/model.js';
+import { readGraph, writeGraph, writeGraphDocument } from '../graph/persist.js';
+import { listNotes } from '../notes/list.js';
+import { ToolRefusal } from './jsonrpc.js';
+import { ReadWriteLock } from './rwlock.js';
+/**
+ * serve-the-store-over-mcp design.md D6 (remote-access spec, *The surface
+ * reads from a checkout of its own*): the canonical checkout `serve` was
+ * started on is shared with the agents and moved by `ctxr land`, so the MCP
+ * surface never changes it. It reads from a detached worktree of its own
+ * under the derived cache path, which it moves by forced checkout to the
+ * remote default branch at most once per interval, with its own graph. A
+ * reader-writer lock keeps every tool call on one commit; a sync that cannot
+ * finish restores the view and its graph together, or refuses calls until a
+ * sync works.
+ */
+export const DEFAULT_SYNC_INTERVAL_SECONDS = 60;
+function firstLine(text) {
+    return text.trim().split('\n')[0] ?? '';
+}
+/** Where the view's worktree lives: under the canonical checkout's derived cache, beside the graph. */
+export function viewWorktreeDir(canonicalRoot) {
+    return path.join(canonicalRoot, '.contexture', 'cache', 'mcp', 'view');
+}
+export class McpView {
+    options;
+    lock = new ReadWriteLock();
+    intervalMs;
+    head = '';
+    lastError = null;
+    unavailable = false;
+    lastSyncAt;
+    syncing;
+    pending = [];
+    viewStore;
+    /** The canonical store root's path inside its repository ("" at the top level, else "sub/dir/"). */
+    repoPrefix;
+    constructor(options) {
+        this.options = options;
+        this.intervalMs = (options.intervalSeconds ?? DEFAULT_SYNC_INTERVAL_SECONDS) * 1000;
+    }
+    run(args, cwd) {
+        return this.options.git.run(args, { cwd, allowFailure: true });
+    }
+    get state() {
+        return { head: this.head, sync_error: this.lastError };
+    }
+    /** Runs `fn` against one commit, after a sync if one is due, and stamps the result with what it read. */
+    async read(deps, fn) {
+        await this.maybeSync(deps, false);
+        return this.lock.read(async () => {
+            if (this.unavailable || this.viewStore === undefined) {
+                throw new ToolRefusal('mcp.store_unavailable', `The store cannot be read until a sync succeeds: ${this.lastError ?? 'it has not been read yet'}.`);
+            }
+            const result = await fn({ head: this.head, store: this.viewStore, pending: this.pending });
+            return { ...result, store: this.state };
+        });
+    }
+    /** For `capture`: a sync forced now, so the duplicate check sees what was pushed and opened a moment ago (design.md D9). */
+    async refresh(deps) {
+        await this.maybeSync(deps, true);
+    }
+    async maybeSync(deps, force) {
+        const now = this.options.now().getTime();
+        const due = force || this.lastSyncAt === undefined || now - this.lastSyncAt >= this.intervalMs;
+        if (!due)
+            return;
+        this.syncing ??= this.lock.write(() => this.syncOnce(deps)).finally(() => {
+            this.syncing = undefined;
+        });
+        await this.syncing;
+    }
+    async ensureView(startRef) {
+        const canonical = this.options.canonicalRoot;
+        this.repoPrefix ??= (await this.run(['rev-parse', '--show-prefix'], canonical)).stdout.trim();
+        const dir = viewWorktreeDir(canonical);
+        if (!existsSync(path.join(dir, '.git'))) {
+            // A view deleted with the derived cache leaves a registration behind; clear it before adding another.
+            await pruneWorktrees(this.options.git, canonical);
+            const added = await this.run(['worktree', 'add', '--detach', '--force', dir, startRef], canonical);
+            if (added.exitCode !== 0)
+                throw new Error(`could not create the read view: ${firstLine(added.stderr)}`);
+        }
+        return path.join(dir, this.repoPrefix);
+    }
+    /** Exclusive: no tool call is reading while this runs. */
+    async syncOnce(deps) {
+        this.lastSyncAt = this.options.now().getTime();
+        const canonical = this.options.canonicalRoot;
+        const branch = deps.config.git.default_branch;
+        const remoteRef = `refs/remotes/origin/${branch}`;
+        const fetched = await runRemoteGit(this.options.git, deps.credentials, deps.env, ['fetch', '--quiet', 'origin', `+refs/heads/${branch}:${remoteRef}`], {
+            cwd: canonical,
+            allowFailure: true,
+        });
+        const fetchError = fetched.exitCode === 0 ? null : `fetch failed: ${firstLine(fetched.stderr) || `exit ${fetched.exitCode}`}`;
+        const hasRemoteRef = (await this.run(['rev-parse', '--verify', '--quiet', `${remoteRef}^{commit}`], canonical)).exitCode === 0;
+        const target = hasRemoteRef ? remoteRef : branch;
+        let viewRoot;
+        try {
+            viewRoot = await this.ensureView(target);
+        }
+        catch (err) {
+            this.lastError = err instanceof Error ? err.message : String(err);
+            this.unavailable = this.viewStore === undefined;
+            return;
+        }
+        const previous = this.head;
+        const moved = await this.checkout(viewRoot, target);
+        if (moved !== null) {
+            this.lastError = moved;
+            this.unavailable = this.viewStore === undefined;
+            return;
+        }
+        const next = (await this.run(['rev-parse', 'HEAD'], viewRoot)).stdout.trim();
+        if (next !== previous || this.viewStore === undefined || (await readGraph(this.viewStore)) === null) {
+            try {
+                this.viewStore = await this.rebuild(viewRoot);
+            }
+            catch (err) {
+                const reason = err instanceof Error ? err.message : String(err);
+                const restored = previous === '' ? 'nothing to restore' : await this.restore(viewRoot, previous);
+                if (restored === null) {
+                    this.lastError = `the read view could not be built at ${next.slice(0, 12)} (${reason}); serving ${previous.slice(0, 12)}`;
+                    this.unavailable = false;
+                }
+                else {
+                    this.lastError = `the read view could not be built at ${next.slice(0, 12)} (${reason}), and restoring the previous commit failed (${restored})`;
+                    this.unavailable = true;
+                }
+                await this.readPending(deps);
+                return;
+            }
+        }
+        this.head = next;
+        this.unavailable = false;
+        const pendingError = await this.readPending(deps);
+        this.lastError = fetchError ?? pendingError;
+    }
+    /** Forced, detached, and cleaned of untracked files — the view is this surface's alone. Null on success. */
+    async checkout(viewRoot, ref) {
+        const checkedOut = await this.run(['checkout', '--quiet', '--detach', '--force', ref], viewRoot);
+        if (checkedOut.exitCode !== 0)
+            return `the read view could not check out ${ref}: ${firstLine(checkedOut.stderr)}`;
+        await this.run(['clean', '-fdq'], viewRoot);
+        return null;
+    }
+    /** The configuration committed at the view's commit, and that commit's graph. */
+    async rebuild(viewRoot) {
+        const config = await readConfig(viewRoot, MIGRATION_STEPS);
+        const store = { root: viewRoot, config };
+        const notes = await listNotes(store.root, store.config);
+        const graph = buildGraphFromNotes(notes, graphBuildOptions(store.config));
+        await writeGraph(store, graph);
+        await writeGraphDocument(store, renderGraphDocument(graph, store.config.retrieval.graph).text);
+        return store;
+    }
+    /** Back to `commit` with its graph; null on success, else why not. */
+    async restore(viewRoot, commit) {
+        const failed = await this.checkout(viewRoot, commit);
+        if (failed !== null)
+            return failed;
+        try {
+            this.viewStore = await this.rebuild(viewRoot);
+            return null;
+        }
+        catch (err) {
+            return err instanceof Error ? err.message : String(err);
+        }
+    }
+    /**
+     * design.md D6–D7: "pending" means what the approval index means by it — a
+     * session branch with an open pull request. Returns an error line when the
+     * forge could not be read, keeping the previous list.
+     */
+    async readPending(deps) {
+        let open;
+        try {
+            open = new Set((await deps.forge.openPulls()).map((p) => p.headRef));
+        }
+        catch (err) {
+            return `open pull requests could not be read: ${err instanceof Error ? firstLine(err.message) : String(err)}`;
+        }
+        const canonical = this.options.canonicalRoot;
+        const prefix = this.repoPrefix ?? '';
+        const inbox = deps.config.ingest.inbox_path;
+        const base = `refs/remotes/origin/${deps.config.git.default_branch}`;
+        const found = [];
+        const sessions = (await sessionWorktrees(this.options.git, canonical, deps.config)).filter((s) => open.has(s.branch));
+        for (const session of sessions.sort((a, b) => (a.branch < b.branch ? -1 : 1))) {
+            const added = await this.run(['diff', '--name-only', '--diff-filter=A', '--no-renames', `${base}...${session.branch}`], canonical);
+            if (added.exitCode !== 0)
+                continue;
+            for (const repoPath of added.stdout.split('\n').filter((p) => p.length > 0)) {
+                if (!repoPath.startsWith(prefix))
+                    continue;
+                const filePath = repoPath.slice(prefix.length);
+                if (!filePath.endsWith('.md') || !isUnderAnyPrefix(filePath, [inbox]))
+                    continue;
+                const shown = await this.run(['show', `${session.branch}:${repoPath}`], canonical);
+                if (shown.exitCode === 0)
+                    found.push({ branch: session.branch, path: filePath, text: shown.stdout });
+            }
+        }
+        this.pending = found;
+        return null;
+    }
+}
+//# sourceMappingURL=sync.js.map

package/dist/core/mcp/sync.js.map

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

package/dist/core/mcp/tools/capture.d.ts

@@ -0,0 +1,64 @@
+import { type WriteDeps } from '../sessions.js';
+import type { McpView, SyncDeps } from '../sync.js';
+/**
+ * remote-access spec, *`capture` opens a session pull request and never
+ * writes the default branch* (design.md D9). One new inbox file, on its own
+ * session, pushed as the App, with a pull request the approval page lists. A
+ * capture is idempotent by source identity — derived from the content when
+ * the caller names none — so a call that failed after committing resumes into
+ * the same pull request instead of being refused as its own duplicate.
+ */
+export declare const MAX_CAPTURE_BODY_BYTES: number;
+export declare const CAPTURE_LABEL_PREFIX = "capture-";
+export interface CaptureArgs {
+    title: string;
+    body: string;
+    source_type: string;
+    source_id?: string;
+}
+/** Plain on purpose (see FIND_INPUT_SCHEMA): `parseCaptureArgs` enforces every limit. */
+export declare const CAPTURE_INPUT_SCHEMA: {
+    readonly type: 'object';
+    readonly properties: {
+        readonly title: {
+            readonly type: 'string';
+            readonly description: 'A short title naming the item, e.g. "Pricing review call, 14 October".';
+        };
+        readonly body: {
+            readonly type: 'string';
+            readonly description: 'The material itself, in its own words, as markdown.';
+        };
+        readonly source_type: {
+            readonly type: 'string';
+            readonly description: 'Where it came from, lowercased: email, meeting, web, document, …';
+        };
+        readonly source_id: {
+            readonly type: 'string';
+            readonly description: "The source system's own id for the item (a message id, a meeting id, a URL), when there is one.";
+        };
+    };
+    readonly required: readonly ['title', 'body', 'source_type'];
+};
+export declare function parseCaptureArgs(args: Record<string, unknown>): CaptureArgs;
+export interface CaptureResult {
+    saved: true;
+    resumed: boolean;
+    path: string;
+    source_id: string;
+    pull_request: {
+        number: number;
+        url: string;
+    };
+    approval_url: string;
+    message: string;
+}
+export interface CaptureContext {
+    view: McpView;
+    syncDeps: SyncDeps;
+    write: WriteDeps;
+}
+/** Run under the write mutex (design.md D9). */
+export declare function capture(ctx: CaptureContext, email: string, args: CaptureArgs): Promise<CaptureResult>;
+/** WriteRefusal → ToolRefusal, so the client reads the reason rather than a protocol error. */
+export declare function asToolRefusal(err: unknown): unknown;
+//# sourceMappingURL=capture.d.ts.map

package/dist/core/mcp/tools/capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.d.ts","sourceRoot":"","sources":["../../../../src/core/mcp/tools/capture.ts"],"names":[],"mappings":"AAaA,OAAO,EAWL,KAAK,SAAS,EACf,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;GAOG;AAEH,eAAO,MAAM,sBAAsB,QAAa,CAAC;AAGjD,eAAO,MAAM,oBAAoB,aAAa,CAAC;AAE/C,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,yFAAyF;AACzF,eAAO,MAAM,oBAAoB;aAC/B,IAAI,EAAE,QAAQ;aACd,UAAU;iBACR,KAAK;qBAAI,IAAI,EAAE,QAAQ;qBAAE,WAAW,EAAE,wEAAwE;;iBAC9G,IAAI;qBAAI,IAAI,EAAE,QAAQ;qBAAE,WAAW,EAAE,qDAAqD;;iBAC1F,WAAW;qBAAI,IAAI,EAAE,QAAQ;qBAAE,WAAW,EAAE,kEAAkE;;iBAC9G,SAAS;qBAAI,IAAI,EAAE,QAAQ;qBAAE,WAAW,EAAE,iGAAiG;;;aAE7I,QAAQ,YAAG,OAAO,EAAE,MAAM,EAAE,aAAa;CACjC,CAAC;AAEX,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAkB3E;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,IAAI,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,OAAO,CAAC;IACd,QAAQ,EAAE,QAAQ,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;CAClB;AAoDD,gDAAgD;AAChD,wBAAsB,OAAO,CAAC,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAkE3G;AAED,+FAA+F;AAC/F,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEnD"}