vouchington-tooling 0.41.0 → 0.43.0

package/dist/mcp-server/pr-body.mjs

@@ -0,0 +1,47 @@
+import { basename } from 'node:path';
+function relatedLine(issue) {
+    const verb = issue.relation === 'closes' ? 'Closes' : 'Refs';
+    return `- ${verb} #${issue.number} — ${issue.reason}`;
+}
+/**
+ * The pull request body: the Summary, Impact, Related issues and Details sections followed by the
+ * provenance lines. Pure; the caller supplies the device and worktree facts.
+ */
+export function renderPullRequestBody(input, provenance) {
+    const related = input.relatedIssues.length ? input.relatedIssues.map(relatedLine) : ['- None'];
+    const agent = input.model === undefined ? input.agent : `${input.agent} (${input.model})`;
+    return [
+        '## Summary',
+        '',
+        input.summary,
+        '',
+        '## Impact',
+        '',
+        input.impact,
+        '',
+        '## Related issues',
+        '',
+        ...related,
+        '',
+        '## Details',
+        '',
+        input.details.join('\n\n'),
+        '',
+        `Workspace setup: ${input.workspaceSetup}`,
+        `Agent: ${agent} session ${provenance.sessionId}`,
+        `Device: ${provenance.user}@${provenance.host.toLowerCase()}`,
+        `Worktree: ${provenance.worktree}`,
+        '',
+    ].join('\n');
+}
+const MARKER = '/worktrees/';
+/**
+ * The worktree label: the path after `/worktrees/` when present, `main` for the repository's main
+ * worktree, else the directory name.
+ */
+export function worktreeLabel(worktree, mainWorktree) {
+    const marker = worktree.indexOf(MARKER);
+    if (marker !== -1)
+        return worktree.slice(marker + MARKER.length);
+    return worktree === mainWorktree ? 'main' : basename(worktree);
+}

package/dist/mcp-server/pr-defaults.d.mts

@@ -0,0 +1,16 @@
+import { type PolicyRun } from './policy-run.mts';
+import type { RelatedIssue } from './pr-input.mts';
+export type PullRequestDefaults = {
+    labels: string[];
+    milestone?: string;
+    project?: string;
+};
+/**
+ * Labels, milestone and project from the policy's `pullRequestDefaults` export; empty when the
+ * checkout declares no policy or the policy lacks the export.
+ */
+export declare function pullRequestDefaults(policy: Omit<PolicyRun, 'export' | 'input'>, input: {
+    title: string;
+    base: string;
+    relatedIssues: RelatedIssue[];
+}): Promise<PullRequestDefaults>;

package/dist/mcp-server/pr-defaults.mjs

@@ -0,0 +1,35 @@
+import { runPolicyExport } from "./policy-run.mjs";
+function optionalName(value, field) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string' || !value.trim())
+        throw new Error(`policy pullRequestDefaults ${field} must be a non-empty string`);
+    return value;
+}
+/**
+ * Labels, milestone and project from the policy's `pullRequestDefaults` export; empty when the
+ * checkout declares no policy or the policy lacks the export.
+ */
+export async function pullRequestDefaults(policy, input) {
+    const { title, base, relatedIssues } = input;
+    const outcome = await runPolicyExport({
+        ...policy,
+        export: 'pullRequestDefaults',
+        input: { title, base, relatedIssues },
+    });
+    if (outcome.status !== 'ok')
+        return { labels: [] };
+    const result = (outcome.result ?? {});
+    if (typeof result !== 'object' || Array.isArray(result))
+        throw new Error('policy pullRequestDefaults must return an object');
+    const labels = result.labels ?? [];
+    if (!Array.isArray(labels) || labels.some((label) => typeof label !== 'string' || !label.trim()))
+        throw new Error('policy pullRequestDefaults labels must be an array of non-empty strings');
+    const milestone = optionalName(result.milestone, 'milestone');
+    const project = optionalName(result.project, 'project');
+    return {
+        labels: labels,
+        ...(milestone === undefined ? {} : { milestone }),
+        ...(project === undefined ? {} : { project }),
+    };
+}

package/dist/mcp-server/pr-gh.d.mts

@@ -0,0 +1,16 @@
+export type GhRunner = (args: string[], options: {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+}) => Promise<string>;
+/**
+ * `gh` on the server's PATH, else a common absolute location. Relative PATH entries are skipped:
+ * gh runs with the target worktree as cwd, where a relative path could name a checkout file.
+ */
+export declare function locateGh(env: NodeJS.ProcessEnv, fallbacks?: readonly string[]): Promise<string>;
+/**
+ * The environment gh runs in: the server's, without the blackboard credentials, and without
+ * GH_REPO, which would point gh at a repository other than the validated worktree's.
+ */
+export declare function ghEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/** A runner that locates gh once, on first use, from the server's environment. */
+export declare function createGhRunner(serverEnv: NodeJS.ProcessEnv, locate?: (env: NodeJS.ProcessEnv) => Promise<string>): GhRunner;

package/dist/mcp-server/pr-gh.mjs

@@ -0,0 +1,56 @@
+import { execFile } from 'node:child_process';
+import { constants } from 'node:fs';
+import { access, stat } from 'node:fs/promises';
+import { delimiter, isAbsolute, join } from 'node:path';
+import { promisify } from 'node:util';
+const execFileAsync = promisify(execFile);
+const FALLBACKS = ['/opt/homebrew/bin/gh', '/usr/local/bin/gh', '/usr/bin/gh'];
+const MAX_BUFFER_BYTES = 16_000_000;
+/** The longest one gh call may run before it is killed. */
+const GH_TIMEOUT_MS = 120_000;
+async function isExecutableFile(path) {
+    try {
+        await access(path, constants.X_OK);
+        return (await stat(path)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * `gh` on the server's PATH, else a common absolute location. Relative PATH entries are skipped:
+ * gh runs with the target worktree as cwd, where a relative path could name a checkout file.
+ */
+export async function locateGh(env, fallbacks = FALLBACKS) {
+    const onPath = (env.PATH ?? '')
+        .split(delimiter)
+        .filter((directory) => isAbsolute(directory))
+        .map((directory) => join(directory, 'gh'));
+    for (const candidate of [...onPath, ...fallbacks])
+        if (await isExecutableFile(candidate))
+            return candidate;
+    throw new Error("gh CLI not found on PATH; install gh or add it to the server's PATH");
+}
+/**
+ * The environment gh runs in: the server's, without the blackboard credentials, and without
+ * GH_REPO, which would point gh at a repository other than the validated worktree's.
+ */
+export function ghEnvironment(env) {
+    const { AGENT_BLACKBOARD_URL: _url, AGENT_BLACKBOARD_TOKEN: _token, GH_REPO: _repo, ...rest } = env;
+    return rest;
+}
+/** A runner that locates gh once, on first use, from the server's environment. */
+export function createGhRunner(serverEnv, locate = locateGh) {
+    let located;
+    return async (args, options) => {
+        located ??= locate(serverEnv);
+        const { stdout } = await execFileAsync(await located, args, {
+            cwd: options.cwd,
+            env: options.env,
+            maxBuffer: MAX_BUFFER_BYTES,
+            timeout: GH_TIMEOUT_MS,
+            killSignal: 'SIGKILL',
+        });
+        return stdout;
+    };
+}

package/dist/mcp-server/pr-input.d.mts

@@ -0,0 +1,26 @@
+import { type Args } from './args.mts';
+declare const PR_MODES: readonly ["interactive", "autonomous"];
+export type RelatedIssue = {
+    number: number;
+    relation: 'closes' | 'refs';
+    reason: string;
+};
+export type PullRequestInput = {
+    title: string;
+    summary: string;
+    impact: string;
+    relatedIssues: RelatedIssue[];
+    details: string[];
+    base: string;
+    agent: string;
+    model?: string;
+    mode: (typeof PR_MODES)[number];
+    workspaceSetup: string;
+};
+/** A positive integer argument, such as a pull request number or an issue number. */
+export declare function positiveInteger(value: unknown, label: string): number;
+/** Rechecked after redaction, which can lengthen a title. */
+export declare function checkTitleLength(title: string): void;
+/** Reads and validates the structured pull request fields shared by the three pr_* tools. */
+export declare function readPullRequestInput(args: Args): PullRequestInput;
+export {};

package/dist/mcp-server/pr-input.mjs

@@ -0,0 +1,62 @@
+import { optionalString, rejectUnknown, requireObject, requiredChoice, requiredString, requiredStringArray, } from "./args.mjs";
+const PR_MODES = ['interactive', 'autonomous'];
+const RELATIONS = ['closes', 'refs'];
+const MAX_TITLE_CHARACTERS = 256;
+/** A positive integer argument, such as a pull request number or an issue number. */
+export function positiveInteger(value, label) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 1)
+        throw new Error(`${label} must be a positive integer`);
+    return value;
+}
+function readRelatedIssues(args) {
+    const value = args.relatedIssues;
+    if (!Array.isArray(value))
+        throw new Error('relatedIssues is required and must be an array');
+    return value.map((item, index) => {
+        const issue = requireObject(item);
+        rejectUnknown(issue, ['number', 'relation', 'reason']);
+        return {
+            number: positiveInteger(issue.number, `relatedIssues[${index}].number`),
+            relation: requiredChoice(issue, 'relation', RELATIONS),
+            reason: requiredString(issue, 'reason'),
+        };
+    });
+}
+function readDetails(args) {
+    const details = requiredStringArray(args, 'details');
+    details.forEach((detail, index) => {
+        if (!detail.trim())
+            throw new Error(`details[${index}] must not be empty`);
+    });
+    return details;
+}
+/** Rechecked after redaction, which can lengthen a title. */
+export function checkTitleLength(title) {
+    if (Array.from(title).length > MAX_TITLE_CHARACTERS)
+        throw new Error(`title must be at most ${MAX_TITLE_CHARACTERS} characters`);
+}
+function singleLine(args, key) {
+    const value = requiredString(args, key);
+    if (/[\r\n]/.test(value))
+        throw new Error(`${key} must be a single line`);
+    return value;
+}
+/** Reads and validates the structured pull request fields shared by the three pr_* tools. */
+export function readPullRequestInput(args) {
+    const title = singleLine(args, 'title');
+    checkTitleLength(title);
+    const model = args.model === undefined ? undefined : singleLine(args, 'model');
+    return {
+        title,
+        summary: requiredString(args, 'summary'),
+        impact: requiredString(args, 'impact'),
+        relatedIssues: readRelatedIssues(args),
+        details: readDetails(args),
+        base: optionalString(args, 'base') ?? 'main',
+        agent: singleLine(args, 'agent'),
+        ...(model === undefined ? {} : { model }),
+        mode: requiredChoice(args, 'mode', PR_MODES),
+        // It renders on its own provenance line; a newline would forge the lines after it.
+        workspaceSetup: singleLine(args, 'workspaceSetup'),
+    };
+}

package/dist/mcp-server/pr-journal.d.mts

@@ -0,0 +1,12 @@
+/**
+ * The Shepherd Journal of a pull request body, verbatim: a `<details>` block whose summary is
+ * "Shepherd Journal", else a legacy `## Shepherd Journal` section running to the next H2 or the
+ * end. Examples inside fenced code blocks are ignored. Undefined when the body has none; more than
+ * one candidate, or an unclosed one, is ambiguous and throws rather than guessing.
+ */
+export declare function findShepherdJournal(body: string): string | undefined;
+/**
+ * Appends the live body's journal to `rendered`. The rendered fields must not carry a journal of
+ * their own, and must not leave a code fence open: the journal would be hidden inside it.
+ */
+export declare function preserveShepherdJournal(rendered: string, live: string): string;

package/dist/mcp-server/pr-journal.mjs

@@ -0,0 +1,86 @@
+const DETAILS_OPEN = /<details(?:\s[^>]*)?>/gi;
+const DETAILS_CLOSE = /<\/details>/gi;
+const SUMMARY = '<summary>Shepherd Journal</summary>';
+/** An ATX H2 "Shepherd Journal", with optional indent and closing hashes. */
+const LEGACY = /^ {0,3}##[ \t]+Shepherd[ \t]+Journal(?:[ \t]+#+)?[ \t]*$/;
+/** A real ATX H2: `##` then whitespace or the end of the line (so not `###` or `##text`). */
+const H2 = /^ {0,3}##(?:[ \t]|$)/;
+const FENCE = /^ {0,3}(`{3,}|~{3,})/;
+/** A closing fence carries nothing but whitespace after its marker. */
+const CLOSING_FENCE = /^ {0,3}(`{3,}|~{3,})[ \t]*$/;
+const count = (line, expression) => [...line.matchAll(expression)].length;
+/**
+ * The lines with every fenced code block blanked, so journal-shaped examples there never match,
+ * and whether the text ends inside a fence that never closed.
+ */
+function outsideFences(lines) {
+    let fence;
+    const visible = lines.map((line) => {
+        if (fence === undefined) {
+            const marker = FENCE.exec(line)?.[1];
+            if (marker === undefined)
+                return line;
+            fence = marker;
+            return '';
+        }
+        const marker = CLOSING_FENCE.exec(line)?.[1];
+        if (marker !== undefined && marker[0] === fence[0] && marker.length >= fence.length)
+            fence = undefined;
+        return '';
+    });
+    return { visible, open: fence !== undefined };
+}
+function detailsStarts(lines) {
+    return lines.flatMap((line, index) => line.trim() === SUMMARY && lines[index - 1]?.trim() === '<details>' ? [index] : []);
+}
+/** Depth is tracked on the fence-blanked lines; the block is sliced from the original ones. */
+function detailsBlock(lines, visible, start) {
+    let depth = 1;
+    for (const [index, line] of visible.entries()) {
+        if (index < start)
+            continue;
+        depth += count(line, DETAILS_OPEN) - count(line, DETAILS_CLOSE);
+        if (depth <= 0)
+            return lines.slice(start - 1, index + 1);
+    }
+    // Treating an unclosed journal as absent would let an update overwrite its history.
+    throw new Error('the Shepherd Journal <details> block is never closed; repair it by hand');
+}
+function legacySection(lines, visible, start) {
+    const next = visible.findIndex((line, index) => index > start && H2.test(line));
+    const section = lines.slice(start, next === -1 ? lines.length : next);
+    while (section.at(-1)?.trim() === '')
+        section.pop();
+    return section;
+}
+/**
+ * The Shepherd Journal of a pull request body, verbatim: a `<details>` block whose summary is
+ * "Shepherd Journal", else a legacy `## Shepherd Journal` section running to the next H2 or the
+ * end. Examples inside fenced code blocks are ignored. Undefined when the body has none; more than
+ * one candidate, or an unclosed one, is ambiguous and throws rather than guessing.
+ */
+export function findShepherdJournal(body) {
+    const lines = body.replaceAll('\r\n', '\n').split('\n');
+    const { visible } = outsideFences(lines);
+    const details = detailsStarts(visible);
+    const legacy = visible.flatMap((line, index) => (LEGACY.test(line) ? [index] : []));
+    if (details.length + legacy.length > 1)
+        throw new Error('the pull request body has more than one Shepherd Journal; resolve it by hand');
+    if (details.length === 1)
+        return detailsBlock(lines, visible, details[0]).join('\n');
+    return legacy.length === 1 ? legacySection(lines, visible, legacy[0]).join('\n') : undefined;
+}
+/**
+ * Appends the live body's journal to `rendered`. The rendered fields must not carry a journal of
+ * their own, and must not leave a code fence open: the journal would be hidden inside it.
+ */
+export function preserveShepherdJournal(rendered, live) {
+    if (findShepherdJournal(rendered) !== undefined)
+        throw new Error('the pull request fields contain a Shepherd Journal; the server preserves the live one');
+    const journal = findShepherdJournal(live);
+    if (journal === undefined)
+        return rendered;
+    if (outsideFences(rendered.replaceAll('\r\n', '\n').split('\n')).open)
+        throw new Error('the pull request fields leave a code fence open; close it');
+    return `${rendered.trimEnd()}\n\n${journal}\n`;
+}

package/dist/mcp-server/pr-live.d.mts

@@ -0,0 +1,24 @@
+import type { RunTextCommand } from '../gh-cli/exec.mts';
+export type LivePullRequest = {
+    body: string;
+    headRefName: string;
+    baseRefName: string;
+    state: string;
+};
+/** The live pull request as gh reports it, rejected unless it is open. */
+export declare function livePullRequest(gh: RunTextCommand, pr: number): Promise<LivePullRequest>;
+/**
+ * The base to validate an existing pull request against: its live base. An explicit `base` that
+ * differs is rejected, because `gh pr edit` here changes only the title and body.
+ */
+export declare function liveBase(pr: number, live: LivePullRequest, given: string | undefined): string;
+/**
+ * Re-reads the live pull request just before the edit and aborts if its Shepherd Journal or base
+ * changed since the body was prepared and validated, so an entry appended in between is never
+ * overwritten and a retargeted PR never gets a body validated against its old base.
+ */
+export declare function assertJournalUnchanged(gh: RunTextCommand, pr: number, preparedFrom: string, base: string): Promise<void>;
+/** The server's credential values that must never reach the policy or GitHub, longest first. */
+export declare function credentials(env: NodeJS.ProcessEnv): string[];
+/** Replaces every server credential in every string of a JSON-shaped value. */
+export declare function redactCredentials<T>(value: T, secrets: string[]): T;

package/dist/mcp-server/pr-live.mjs

@@ -0,0 +1,49 @@
+import { findShepherdJournal } from "./pr-journal.mjs";
+const FIELDS = ['body', 'headRefName', 'baseRefName', 'state'];
+/** The live pull request as gh reports it, rejected unless it is open. */
+export async function livePullRequest(gh, pr) {
+    const output = await gh(['pr', 'view', String(pr), '--json', FIELDS.join(',')]);
+    const live = JSON.parse(output);
+    if (!isLive(live))
+        throw new Error(`gh pr view ${pr} did not return ${FIELDS.join(', ')}`);
+    // A closed or merged PR can share a reused branch name; its history must not be rewritten.
+    if (live.state !== 'OPEN')
+        throw new Error(`pull request ${pr} is ${live.state}, not OPEN`);
+    return live;
+}
+function isLive(value) {
+    return FIELDS.every((field) => typeof value?.[field] === 'string');
+}
+/**
+ * The base to validate an existing pull request against: its live base. An explicit `base` that
+ * differs is rejected, because `gh pr edit` here changes only the title and body.
+ */
+export function liveBase(pr, live, given) {
+    if (given !== undefined && given !== live.baseRefName)
+        throw new Error(`pull request ${pr} targets ${live.baseRefName}, not ${given}`);
+    return live.baseRefName;
+}
+/**
+ * Re-reads the live pull request just before the edit and aborts if its Shepherd Journal or base
+ * changed since the body was prepared and validated, so an entry appended in between is never
+ * overwritten and a retargeted PR never gets a body validated against its old base.
+ */
+export async function assertJournalUnchanged(gh, pr, preparedFrom, base) {
+    const now = await livePullRequest(gh, pr);
+    if (now.baseRefName !== base)
+        throw new Error(`pull request ${pr} was retargeted to ${now.baseRefName}; run pr_update again`);
+    if (findShepherdJournal(now.body) !== findShepherdJournal(preparedFrom))
+        throw new Error(`the Shepherd Journal of pull request ${pr} changed meanwhile; run pr_update again`);
+}
+/** The server's credential values that must never reach the policy or GitHub, longest first. */
+export function credentials(env) {
+    const values = [env.AGENT_BLACKBOARD_TOKEN, env.GH_TOKEN, env.GITHUB_TOKEN].filter((value) => value !== undefined && value.length >= 4);
+    return [...new Set(values)].sort((a, b) => b.length - a.length);
+}
+/** Replaces every server credential in every string of a JSON-shaped value. */
+export function redactCredentials(value, secrets) {
+    if (value === undefined || secrets.length === 0)
+        return value;
+    const json = secrets.reduce((text, secret) => text.split(JSON.stringify(secret).slice(1, -1)).join('[REDACTED]'), JSON.stringify(value));
+    return JSON.parse(json);
+}

package/dist/mcp-server/pr-tools.test-helpers.d.mts

@@ -0,0 +1,54 @@
+import type { RepoFixture } from './git-fixture.test-helpers.mts';
+import type { GhRunner } from './pr-gh.mts';
+import type { PolicyOutcome, PolicyRequest } from './policy-spawn.mts';
+export declare const PR_ARGS: {
+    sessionId: string;
+    title: string;
+    summary: string;
+    impact: string;
+    relatedIssues: {
+        number: number;
+        relation: string;
+        reason: string;
+    }[];
+    details: string[];
+    base: string;
+    agent: string;
+    mode: string;
+    workspaceSetup: string;
+};
+export declare function declarePolicy(fixture: RepoFixture): void;
+type Reply = (name: string, input: Record<string, unknown>) => unknown;
+export declare function policy(reply: Reply): {
+    requests: {
+        name: string;
+        input: Record<string, unknown>;
+    }[];
+    spawnPolicy: (request: PolicyRequest) => Promise<PolicyOutcome>;
+};
+type GhCall = {
+    args: string[];
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    body?: string;
+};
+/** A fake gh: records calls (reading any --body-file while it still exists) and replies by verb. */
+export declare function fakeGh(replies?: {
+    view?: unknown;
+    create?: string;
+    edit?: string;
+}): {
+    calls: GhCall[];
+    bodyFiles: {
+        path: string;
+        mode: number;
+    }[];
+    runGh: GhRunner;
+};
+export declare const device: () => {
+    user: string;
+    host: string;
+};
+/** Gives the fixture an `origin` that already has the linked branch at its current commit. */
+export declare function usePushedRemote(fixture: () => RepoFixture): void;
+export {};

package/dist/mcp-server/pr-tools.test-helpers.mjs

@@ -0,0 +1,67 @@
+import { readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { beforeEach } from 'vitest';
+export const PR_ARGS = {
+    sessionId: 'native:owner',
+    title: 'Add the thing',
+    summary: 'Adds the thing.',
+    impact: 'Nobody breaks.',
+    relatedIssues: [{ number: 7, relation: 'closes', reason: 'tracks the work' }],
+    details: ['First paragraph.', '- a bullet'],
+    base: 'trunk',
+    agent: 'codex',
+    mode: 'autonomous',
+    workspaceSetup: 'fresh worktree',
+};
+export function declarePolicy(fixture) {
+    writeFileSync(join(fixture.linked, 'package.json'), JSON.stringify({ 'vouchington-tooling': { policy: 'policy.mts' } }));
+    writeFileSync(join(fixture.linked, 'policy.mts'), '');
+}
+export function policy(reply) {
+    const requests = [];
+    const spawnPolicy = async (request) => {
+        const { export: name, input } = JSON.parse(request.input);
+        requests.push({ name, input });
+        const result = reply(name, input);
+        const stdout = result === undefined ? { ok: true, skipped: true } : { ok: true, result };
+        return {
+            exitCode: 0,
+            stdout: JSON.stringify(stdout),
+            stderr: '',
+            timedOut: false,
+            overflowed: false,
+        };
+    };
+    return { requests, spawnPolicy };
+}
+/** A fake gh: records calls (reading any --body-file while it still exists) and replies by verb. */
+export function fakeGh(replies = {}) {
+    const calls = [];
+    const bodyFiles = [];
+    const runGh = async (args, options) => {
+        const call = { args, ...options };
+        const file = args[args.indexOf('--body-file') + 1];
+        if (args.includes('--body-file') && file !== undefined) {
+            call.body = readFileSync(file, 'utf8');
+            bodyFiles.push({ path: file, mode: statSync(file).mode & 0o777 });
+        }
+        calls.push(call);
+        if (args[1] === 'view')
+            return JSON.stringify(replies.view);
+        if (args[1] === 'create')
+            return replies.create ?? 'https://github.com/o/r/pull/12\n';
+        return replies.edit ?? 'https://github.com/o/r/pull/5\n';
+    };
+    return { calls, bodyFiles, runGh };
+}
+export const device = () => ({ user: 'Jong', host: 'Laptop.Local' });
+/** Gives the fixture an `origin` that already has the linked branch at its current commit. */
+export function usePushedRemote(fixture) {
+    beforeEach(() => {
+        const f = fixture();
+        const origin = join(f.root, 'origin.git');
+        f.git(f.root, 'init', '--quiet', '--bare', origin);
+        f.git(f.linked, 'remote', 'add', 'origin', origin);
+        f.git(f.linked, 'push', '--quiet', 'origin', 'linked');
+    });
+}

package/dist/mcp-server/retrospective-facts-input.d.mts

@@ -0,0 +1,6 @@
+import type { Args } from './args.mts';
+/**
+ * Checks `compose.facts`: either `{ status, reason }` (unassessed) or a live collection selector,
+ * never both. Returns whether live collection was requested.
+ */
+export declare function checkFactsInput(facts: Args): boolean;

package/dist/mcp-server/retrospective-facts-input.mjs

@@ -0,0 +1,25 @@
+/** A plain branch name: no scheme or colon, no leading dash, no `..`. */
+const BRANCH = /^(?!-)(?!.*\.\.)[A-Za-z0-9._/-]+$/;
+/**
+ * Checks `compose.facts`: either `{ status, reason }` (unassessed) or a live collection selector,
+ * never both. Returns whether live collection was requested.
+ */
+export function checkFactsInput(facts) {
+    const selectors = ['pr', 'branch', 'noPr'].filter((key) => key in facts);
+    if ('status' in facts) {
+        if (selectors.length)
+            throw new Error(`compose.facts: status is exclusive with ${selectors.join(', ')}`);
+        return false;
+    }
+    if ('reason' in facts)
+        throw new Error('compose.facts.reason requires a status');
+    // The collector trusts these types; a string "false" must not read as noPr: true.
+    // gh accepts a pull request URL for either, which would reach another repository.
+    if ('pr' in facts && (typeof facts.pr !== 'string' || !/^\d+$/.test(facts.pr)))
+        throw new Error('compose.facts.pr must be a pull request number string');
+    if ('branch' in facts && (typeof facts.branch !== 'string' || !BRANCH.test(facts.branch)))
+        throw new Error('compose.facts.branch must be a branch name');
+    if ('noPr' in facts && typeof facts.noPr !== 'boolean')
+        throw new Error('compose.facts.noPr must be a boolean');
+    return true;
+}

package/dist/mcp-server/retrospective-front-matter.d.mts

@@ -0,0 +1,22 @@
+import type { FeedbackReference } from '../agent-blackboard/index.mts';
+/** The fields of the front matter `composeRetrospective` writes, with camelCase names. */
+export type RetrospectiveFrontMatter = {
+    date: string;
+    issues: FeedbackReference[];
+    prs: FeedbackReference[];
+    sessionId?: string;
+    description?: string;
+    workOutcome?: string;
+    feedbackCoverage?: {
+        status: string;
+        sources: string[];
+        droppedCount: number;
+    };
+    repositories?: string[];
+};
+/**
+ * Parses the block from the leading `---` line to the next `---` line. Every line is
+ * `key: <JSON value>`; unknown keys, duplicates, malformed lines and ill-typed values are errors,
+ * and `date`, `issues`, and `prs` are required.
+ */
+export declare function parseRetrospectiveFrontMatter(markdown: string): RetrospectiveFrontMatter;