@oscharko-dev/keiko-tools 0.2.7 → 0.2.9

package/dist/git-merge-node.js

@@ -0,0 +1,243 @@
+// Node implementation of the narrow governed merge adapter (Issue #478, Epic #470) — AC1/AC4/AC5.
+//
+// This is the ONLY place a governed merge operation actually executes. It builds the governed `gh api`
+// argv from the pure builders (git-merge-gateway.ts) and runs them through the SAME keiko-tools no-shell
+// spawn boundary (`runCommand`, exec.ts) with a DEDICATED merge allowlist (`GIT_MERGE_COMMAND_RULES`)
+// that permits only `gh api` and denies file-input flags. There is no method that accepts an arbitrary
+// command string and no parallel child_process path: the deny-by-default allowlist, env isolation,
+// redaction, and cancellation of the shared boundary apply to the merge operation exactly as to every
+// other tool.
+//
+// `gh` reads its own GitHub token from its keyring or from GH_TOKEN/GITHUB_TOKEN in the inherited
+// process environment; Keiko never reads or handles the token value. The readiness READ maps GitHub's
+// content-free PR facts (state / draft / mergeable_state) and repo merge configuration into the
+// provider-neutral contract interfaces; a non-OK merge status is classified into a typed
+// GitMergeRejectionReason. Raw stdout/stderr never leave this module — only the typed facts, the
+// content-free contract error code, and the typed rejection reason cross out.
+//
+// Lives on the `./internal/git-mutation` subpath (re-exported by git-mutation-node.ts) because it carries
+// the Node execution effect; the pure port, builders, and rules it implements are on the barrel.
+import { GIT_DELIVERY_SCHEMA_VERSION, } from "@oscharko-dev/keiko-contracts";
+import { buildDeleteMergedBranchArgv, buildHeadStatusArgv, buildMergeArgv, buildMergeReadinessArgv, buildRepoMergeConfigArgv, classifyGitMergeRejection, GIT_MERGE_COMMAND_RULES, gitMergeRejectionToErrorCode, mapRawMergeReadiness, } from "./git-merge-gateway.js";
+import { CommandCancelledError, CommandTimeoutError } from "./errors.js";
+import { nodeSpawnFn, runCommand, } from "./exec.js";
+import { DEFAULT_SANDBOX_POLICY } from "./types.js";
+function executionResult(outcome, durationMs, extra) {
+    return {
+        schemaVersion: GIT_DELIVERY_SCHEMA_VERSION,
+        outcome,
+        durationMs: Math.max(0, Math.trunc(durationMs)),
+        ...extra,
+    };
+}
+function buildRunContext(deps) {
+    return {
+        runDeps: {
+            workspace: deps.workspace,
+            policy: deps.policy ?? DEFAULT_SANDBOX_POLICY,
+            commandRules: GIT_MERGE_COMMAND_RULES,
+            spawn: deps.spawn ?? nodeSpawnFn,
+            processEnv: deps.processEnv ?? process.env,
+            now: deps.now ?? Date.now,
+            ...(deps.resolveExecutable !== undefined
+                ? { resolveExecutable: deps.resolveExecutable }
+                : {}),
+            ...(deps.home !== undefined ? { home: deps.home } : {}),
+        },
+        signal: deps.signal ?? new AbortController().signal,
+        timeoutMs: deps.timeoutMs,
+    };
+}
+function rejectionFromExit(result) {
+    if (result.timedOut) {
+        return executionResult("failed", result.durationMs, {
+            errorCode: "timeout",
+            rejectionReason: "provider-unavailable",
+        });
+    }
+    const reason = classifyGitMergeRejection(`${result.stdout}\n${result.stderr}`);
+    return executionResult("failed", result.durationMs, {
+        errorCode: gitMergeRejectionToErrorCode(reason),
+        rejectionReason: reason,
+    });
+}
+function failureFromThrow(error, durationMs) {
+    if (error instanceof CommandTimeoutError) {
+        return executionResult("failed", durationMs, {
+            errorCode: "timeout",
+            rejectionReason: "provider-unavailable",
+        });
+    }
+    if (error instanceof CommandCancelledError) {
+        return executionResult("aborted", durationMs);
+    }
+    return executionResult("failed", durationMs, { errorCode: "internal-error" });
+}
+async function runGh(ctx, argv) {
+    try {
+        return await runCommand({ command: "gh", args: argv, cwd: undefined, timeoutMs: ctx.timeoutMs, signal: ctx.signal }, ctx.runDeps);
+    }
+    catch (error) {
+        return error instanceof Error ? error : new Error("gh invocation failed");
+    }
+}
+function parseJsonObject(stdout) {
+    try {
+        const parsed = JSON.parse(stdout);
+        return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function optionalString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function rawMergeReadinessFrom(facts, req) {
+    return {
+        prNumber: req.prExternalId,
+        headBranchName: optionalString(facts.headRef) ?? "unknown",
+        ...(optionalString(facts.state) !== undefined ? { state: optionalString(facts.state) } : {}),
+        ...(typeof facts.merged === "boolean" ? { merged: facts.merged } : {}),
+        ...(typeof facts.draft === "boolean" ? { draft: facts.draft } : {}),
+        ...(optionalString(facts.mergeable_state) !== undefined
+            ? { mergeableState: optionalString(facts.mergeable_state) }
+            : {}),
+        ...(optionalString(facts.base) !== undefined ? { baseRef: optionalString(facts.base) } : {}),
+        ...(optionalString(facts.head) !== undefined ? { headSha: optionalString(facts.head) } : {}),
+    };
+}
+function capableStrategiesFrom(cfg) {
+    const caps = [];
+    if (cfg.squash === true)
+        caps.push("squash");
+    if (cfg.rebase === true)
+        caps.push("rebase");
+    if (cfg.merge === true)
+        caps.push("merge-commit");
+    return caps;
+}
+const CHECKS_STATUS_BY_STATE = {
+    success: "passing",
+    pending: "pending",
+    failure: "failing",
+    error: "failing",
+};
+// A best-effort combined check-status read. Only the overallStatus drives the contract readiness
+// derivation; the per-bucket counts are coarse (the combined state attributed to the matching bucket).
+function checksStateFrom(state, total) {
+    const overallStatus = CHECKS_STATUS_BY_STATE[state] ?? "skipped";
+    return {
+        total,
+        passing: overallStatus === "passing" ? total : 0,
+        failing: overallStatus === "failing" ? total : 0,
+        pending: overallStatus === "pending" ? total : 0,
+        overallStatus,
+    };
+}
+function shouldReadHeadStatus(mergeableState) {
+    return (mergeableState === "blocked" || mergeableState === "unstable" || mergeableState === "unknown");
+}
+async function readHeadChecks(ctx, ownerAndRepo, headSha) {
+    if (headSha === undefined) {
+        return undefined;
+    }
+    let argv;
+    try {
+        argv = buildHeadStatusArgv(ownerAndRepo, headSha);
+    }
+    catch {
+        return undefined;
+    }
+    const result = await runGh(ctx, argv);
+    if (result instanceof Error || result.exitCode !== 0) {
+        return undefined;
+    }
+    const state = result.stdout.trim();
+    if (state.length === 0) {
+        return undefined;
+    }
+    return checksStateFrom(state, 0);
+}
+async function readMergeReadiness(ctx, req) {
+    let prArgv;
+    let cfgArgv;
+    try {
+        prArgv = buildMergeReadinessArgv(req);
+        cfgArgv = buildRepoMergeConfigArgv(req);
+    }
+    catch {
+        return { providerCapableStrategies: [], providerError: true };
+    }
+    const prResult = await runGh(ctx, prArgv);
+    if (prResult instanceof Error || prResult.exitCode !== 0) {
+        return { providerCapableStrategies: [], providerError: true };
+    }
+    const prObj = parseJsonObject(prResult.stdout);
+    if (prObj === undefined) {
+        return { providerCapableStrategies: [], providerError: true };
+    }
+    const raw = rawMergeReadinessFrom(prObj, req);
+    const pullRequest = mapRawMergeReadiness(raw);
+    const cfgResult = await runGh(ctx, cfgArgv);
+    const cfgObj = cfgResult instanceof Error || cfgResult.exitCode !== 0
+        ? undefined
+        : parseJsonObject(cfgResult.stdout);
+    const providerCapableStrategies = cfgObj !== undefined ? capableStrategiesFrom(cfgObj) : [];
+    const checks = shouldReadHeadStatus(raw.mergeableState)
+        ? await readHeadChecks(ctx, req.ownerAndRepo, raw.headSha)
+        : undefined;
+    return {
+        pullRequest,
+        providerCapableStrategies,
+        ...(checks !== undefined ? { checks } : {}),
+    };
+}
+// ─── Merge execute (+ guarded, non-fatal branch deletion) ─────────────────────────────────────────────
+function parseMerged(stdout) {
+    return stdout.trim() === "true";
+}
+// Deletes the merged head branch best-effort. A failed deletion NEVER fails the merge (the merge already
+// succeeded); it only reports branchDeleted=false.
+async function deleteMergedBranch(ctx, req) {
+    let argv;
+    try {
+        argv = buildDeleteMergedBranchArgv(req.ownerAndRepo, req.headBranchName);
+    }
+    catch {
+        return false;
+    }
+    const result = await runGh(ctx, argv);
+    return !(result instanceof Error) && result.exitCode === 0;
+}
+async function mergePullRequest(ctx, req) {
+    let argv;
+    try {
+        argv = buildMergeArgv(req);
+    }
+    catch {
+        return executionResult("failed", 0, { errorCode: "internal-error" });
+    }
+    const result = await runGh(ctx, argv);
+    if (result instanceof Error) {
+        return failureFromThrow(result, 0);
+    }
+    if (result.exitCode !== 0) {
+        return rejectionFromExit(result);
+    }
+    const merged = parseMerged(result.stdout);
+    if (!req.deleteBranchAfterMerge || !merged) {
+        return executionResult("succeeded", result.durationMs, { merged });
+    }
+    const branchDeleted = await deleteMergedBranch(ctx, req);
+    return executionResult("succeeded", result.durationMs, { merged, branchDeleted });
+}
+export function createNodeGitMergeAdapter(deps) {
+    const ctx = buildRunContext(deps);
+    return {
+        readMergeReadiness: (req) => readMergeReadiness(ctx, req),
+        mergePullRequest: (req) => mergePullRequest(ctx, req),
+    };
+}

package/dist/git-mutation-adapter.d.ts

@@ -0,0 +1,51 @@
+import type { GitDeliveryAbortableOperation, GitDeliveryExecutionResult, GitDeliveryRecoveryStrategyHint } from "@oscharko-dev/keiko-contracts";
+import type { CommandRule } from "./types.js";
+export interface GitBranchCreateExecRequest {
+    readonly branchName: string;
+    readonly startPointRefHash: string;
+}
+export interface GitBranchSwitchExecRequest {
+    readonly branchName: string;
+}
+export interface GitStageExecRequest {
+    readonly pathspecs: readonly string[];
+}
+export interface GitUnstageExecRequest {
+    readonly pathspecs: readonly string[];
+}
+export interface GitCommitExecRequest {
+    readonly message: string;
+    readonly allowEmpty: boolean;
+}
+export interface GitAbortExecRequest {
+    readonly operationToAbort: GitDeliveryAbortableOperation;
+}
+export interface GitRecoveryExecRequest {
+    readonly recoveryStrategyHint: GitDeliveryRecoveryStrategyHint;
+    readonly targetRefHash: string;
+    readonly pathspecs: readonly string[];
+}
+export interface GitLocalMutationAdapter {
+    createBranch(req: GitBranchCreateExecRequest): Promise<GitDeliveryExecutionResult>;
+    switchBranch(req: GitBranchSwitchExecRequest): Promise<GitDeliveryExecutionResult>;
+    stage(req: GitStageExecRequest): Promise<GitDeliveryExecutionResult>;
+    unstage(req: GitUnstageExecRequest): Promise<GitDeliveryExecutionResult>;
+    commit(req: GitCommitExecRequest): Promise<GitDeliveryExecutionResult>;
+    abort(req: GitAbortExecRequest): Promise<GitDeliveryExecutionResult>;
+    recover(req: GitRecoveryExecRequest): Promise<GitDeliveryExecutionResult>;
+}
+export declare const GIT_MUTATION_ALLOWED_SUBCOMMANDS: readonly string[];
+export declare const GIT_MUTATION_COMMAND_RULES: readonly CommandRule[];
+export declare class GitMutationArgvError extends Error {
+    constructor(message: string);
+}
+export type GitMutationArgvPlan = readonly (readonly string[])[];
+export declare function buildBranchCreateArgv(req: GitBranchCreateExecRequest): GitMutationArgvPlan;
+export declare function buildBranchSwitchArgv(req: GitBranchSwitchExecRequest): GitMutationArgvPlan;
+export declare function buildStageArgv(req: GitStageExecRequest): GitMutationArgvPlan;
+export declare function buildUnstageArgv(req: GitUnstageExecRequest): GitMutationArgvPlan;
+export declare function buildCommitArgv(req: GitCommitExecRequest): GitMutationArgvPlan;
+export declare function buildAbortArgv(req: GitAbortExecRequest): GitMutationArgvPlan;
+export declare function buildRecoveryArgv(req: GitRecoveryExecRequest): GitMutationArgvPlan;
+export declare function gitMutationPlanIsGoverned(plan: GitMutationArgvPlan): boolean;
+//# sourceMappingURL=git-mutation-adapter.d.ts.map

package/dist/git-mutation-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-mutation-adapter.d.ts","sourceRoot":"","sources":["../src/git-mutation-adapter.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EACV,6BAA6B,EAC7B,0BAA0B,EAC1B,+BAA+B,EAChC,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAM9C,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,gBAAgB,EAAE,6BAA6B,CAAC;CAC1D;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,oBAAoB,EAAE,+BAA+B,CAAC;IAC/D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAOD,MAAM,WAAW,uBAAuB;IACtC,YAAY,CAAC,GAAG,EAAE,0BAA0B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACnF,YAAY,CAAC,GAAG,EAAE,0BAA0B,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACnF,KAAK,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACrE,OAAO,CAAC,GAAG,EAAE,qBAAqB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACzE,MAAM,CAAC,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACvE,KAAK,CAAC,GAAG,EAAE,mBAAmB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IACrE,OAAO,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;CAC3E;AAOD,eAAO,MAAM,gCAAgC,EAAE,SAAS,MAAM,EAa5D,CAAC;AAMH,eAAO,MAAM,0BAA0B,EAAE,SAAS,WAAW,EA2B3D,CAAC;AAOH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM;CAI5B;AA6DD,MAAM,MAAM,mBAAmB,GAAG,SAAS,CAAC,SAAS,MAAM,EAAE,CAAC,EAAE,CAAC;AAEjE,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,0BAA0B,GAAG,mBAAmB,CAQ1F;AAMD,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,0BAA0B,GAAG,mBAAmB,CAE1F;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,mBAAmB,GAAG,mBAAmB,CAE5E;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,qBAAqB,GAAG,mBAAmB,CAEhF;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,oBAAoB,GAAG,mBAAmB,CAO9E;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,mBAAmB,GAAG,mBAAmB,CAgB5E;AAMD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,sBAAsB,GAAG,mBAAmB,CAmBlF;AASD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,mBAAmB,GAAG,OAAO,CAI5E"}

package/dist/git-mutation-adapter.js

@@ -0,0 +1,207 @@
+// The narrow local Git mutation adapter contract (Issue #472, Epic #470) — AC3.
+//
+// This module defines WHAT the governed local Git adapter may do, as data and pure functions:
+//
+//   1. `GitLocalMutationAdapter` — the port. One typed method per local mutation kind. There is NO
+//      method that accepts an arbitrary argument vector, so there is no path from the kernel to
+//      "run this git command string". Local Git write authority is reachable only through these
+//      typed operations.
+//   2. `GIT_MUTATION_ALLOWED_SUBCOMMANDS` / `GIT_MUTATION_COMMAND_RULES` — the closed allowlist the
+//      Node adapter (git-mutation-node.ts) hands to the keiko-tools no-shell spawn boundary. It is a
+//      SEPARATE, dedicated rule set from both the read-only terminal policy and the harness default,
+//      and it permits only the governed mutation subcommands.
+//   3. The pure argv builders — each maps validated, typed operands to a fixed argument vector whose
+//      first token is always one of the allowed subcommands. Operands are validated (no NUL, no
+//      flag-injection via a leading "-" on refs) and file operands are literalized before they are
+//      placed after a "--" sentinel so a repository-controlled filename cannot be reinterpreted as an
+//      option or Git pathspec magic.
+//
+// Pure module: types, frozen tables, and total pure functions. No IO, no spawn, no child_process —
+// the actual execution adapter is git-mutation-node.ts on the `./internal/git-mutation` subpath.
+// ─── Closed subcommand allowlist + dedicated command rules ────────────────────────────────
+// The exact git subcommands the governed adapter may run. No read-only inspection subcommand and no
+// network subcommand (push/fetch/pull/clone) appears here; remote and provider execution is a later
+// slice (#476–#478) behind a separate gateway, never this local adapter.
+export const GIT_MUTATION_ALLOWED_SUBCOMMANDS = Object.freeze([
+    "branch",
+    "switch",
+    "add",
+    "restore",
+    "commit",
+    "reset",
+    "stash",
+    "merge",
+    "rebase",
+    "cherry-pick",
+    "revert",
+    "bisect",
+]);
+// The dedicated allowlist handed to the keiko-tools spawn boundary by the Node adapter. Mirrors the
+// terminal policy's defense-in-depth flag denials (global config/cwd-shifting/code-execution flags)
+// so that even though the adapter only ever builds argv from typed operands, a smuggled global flag
+// would still be rejected before spawn.
+export const GIT_MUTATION_COMMAND_RULES = Object.freeze([
+    {
+        executable: "git",
+        allowedSubcommands: GIT_MUTATION_ALLOWED_SUBCOMMANDS,
+        valueFlags: Object.freeze([
+            "-C",
+            "-c",
+            "--git-dir",
+            "--work-tree",
+            "--namespace",
+            "--exec-path",
+        ]),
+        denyFlags: Object.freeze([
+            "-C",
+            "-c",
+            "--config-env",
+            "--git-dir",
+            "--work-tree",
+            "--namespace",
+            "--exec-path",
+            "--ext-diff",
+            "--textconv",
+            "--no-index",
+            "--contents",
+            "--output",
+        ]),
+    },
+]);
+// ─── Operand validation ───────────────────────────────────────────────────────────────────
+// Thrown when typed operands cannot be turned into a safe argv (empty, NUL-bearing, or a ref/branch
+// that would be read as a flag). The Node adapter maps this to an `internal-error` execution result;
+// it never reaches a spawn.
+export class GitMutationArgvError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GitMutationArgvError";
+    }
+}
+function hasNul(value) {
+    return value.includes("\u0000");
+}
+// A ref/branch operand passed as a bare positional. Rejects empty, NUL, and a leading "-" so it can
+// never be reinterpreted as a git option.
+function assertRef(value, label) {
+    if (value.length === 0) {
+        throw new GitMutationArgvError(`${label} must not be empty`);
+    }
+    if (hasNul(value)) {
+        throw new GitMutationArgvError(`${label} must not contain a NUL byte`);
+    }
+    if (value.startsWith("-")) {
+        throw new GitMutationArgvError(`${label} must not start with "-" (flag-injection guard)`);
+    }
+    return value;
+}
+// A commit message passed as the value of `--message`. May start with "-" (git consumes it as the
+// flag's value), but must be non-empty and NUL-free.
+function assertMessage(value) {
+    if (value.length === 0) {
+        throw new GitMutationArgvError("commit message must not be empty");
+    }
+    if (hasNul(value)) {
+        throw new GitMutationArgvError("commit message must not contain a NUL byte");
+    }
+    return value;
+}
+function literalPathspec(value) {
+    return `:(literal)${value}`;
+}
+// File operands placed after the "--" sentinel. May start with "-" (the sentinel disarms option
+// parsing), but must be non-empty and NUL-free, and the list must be non-empty. Returned argv tokens
+// are literal pathspecs so names such as ":(top)*" cannot expand beyond the selected file.
+function assertPathspecs(values) {
+    if (values.length === 0) {
+        throw new GitMutationArgvError("at least one pathspec is required");
+    }
+    for (const value of values) {
+        if (value.length === 0) {
+            throw new GitMutationArgvError("pathspec must not be empty");
+        }
+        if (hasNul(value)) {
+            throw new GitMutationArgvError("pathspec must not contain a NUL byte");
+        }
+    }
+    return values.map(literalPathspec);
+}
+export function buildBranchCreateArgv(req) {
+    return [
+        [
+            "branch",
+            assertRef(req.branchName, "branchName"),
+            assertRef(req.startPointRefHash, "startPointRefHash"),
+        ],
+    ];
+}
+// Switch HEAD to an EXISTING local branch. `git switch` (never `checkout`) is branch-only: it cannot
+// be coerced into a path checkout, so it carries no file-overwrite surface. The branch operand is a
+// bare positional guarded by assertRef (non-empty, NUL-free, no leading "-" flag-injection), mirroring
+// branch-create; switch takes no pathspecs so no "--" sentinel is needed.
+export function buildBranchSwitchArgv(req) {
+    return [["switch", assertRef(req.branchName, "branchName")]];
+}
+export function buildStageArgv(req) {
+    return [["add", "--", ...assertPathspecs(req.pathspecs)]];
+}
+export function buildUnstageArgv(req) {
+    return [["restore", "--staged", "--", ...assertPathspecs(req.pathspecs)]];
+}
+export function buildCommitArgv(req) {
+    const argv = ["commit"];
+    if (req.allowEmpty) {
+        argv.push("--allow-empty");
+    }
+    argv.push("--message", assertMessage(req.message));
+    return [argv];
+}
+export function buildAbortArgv(req) {
+    switch (req.operationToAbort) {
+        case "merge":
+            return [["merge", "--abort"]];
+        case "rebase":
+            return [["rebase", "--abort"]];
+        case "cherry-pick":
+            return [["cherry-pick", "--abort"]];
+        case "revert":
+            return [["revert", "--abort"]];
+        case "bisect":
+            // A bisect has no `--abort`; `git bisect reset` is its termination form.
+            return [["bisect", "reset"]];
+        default:
+            return assertNeverAbort(req.operationToAbort);
+    }
+}
+function assertNeverAbort(operation) {
+    throw new GitMutationArgvError(`unhandled abortable operation: ${JSON.stringify(operation)}`);
+}
+export function buildRecoveryArgv(req) {
+    const target = assertRef(req.targetRefHash, "targetRefHash");
+    switch (req.recoveryStrategyHint) {
+        case "soft-reset":
+            return [["reset", "--soft", target]];
+        case "mixed-reset":
+            return [["reset", "--mixed", target]];
+        case "stash-and-reset":
+            // Stash (including untracked) FIRST so no local work is lost, then hard-reset to the target.
+            // The stash is the guided recovery point; the hard reset is safe because the work is preserved.
+            return [
+                ["stash", "push", "--include-untracked"],
+                ["reset", "--hard", target],
+            ];
+        case "restore-index":
+            return [["restore", "--source", target, "--staged", "--", ...assertPathspecs(req.pathspecs)]];
+        default:
+            return assertNeverRecovery(req.recoveryStrategyHint);
+    }
+}
+function assertNeverRecovery(hint) {
+    throw new GitMutationArgvError(`unhandled recovery strategy: ${JSON.stringify(hint)}`);
+}
+// True iff every command in the plan begins with an allowed governed mutation subcommand. Used by
+// tests (and available to callers) to prove the no-generic-fallback property structurally: there is
+// no producible plan whose first token is outside GIT_MUTATION_ALLOWED_SUBCOMMANDS.
+export function gitMutationPlanIsGoverned(plan) {
+    return plan.every((argv) => argv.length > 0 && GIT_MUTATION_ALLOWED_SUBCOMMANDS.includes(argv[0] ?? ""));
+}

package/dist/git-mutation-evidence.d.ts

@@ -0,0 +1,23 @@
+import type { GitDeliveryEvidenceRecord, GitDeliveryEvidenceRef } from "@oscharko-dev/keiko-contracts";
+import type { GitMutationLifecycleResult } from "./git-mutation-orchestrator.js";
+export interface GitDeliveryEvidenceBuildInput {
+    readonly result: GitMutationLifecycleResult;
+    readonly snapshot: GitDeliveryEvidenceSnapshot;
+    readonly workflowRunId: string;
+    readonly repoId?: string | undefined;
+    readonly attemptSequence?: number | undefined;
+    readonly evidenceRef?: GitDeliveryEvidenceRef | undefined;
+}
+export interface GitDeliveryEvidenceSnapshot {
+    readonly headDetached: boolean;
+    readonly currentBranchName?: string | undefined;
+    readonly stagedFileCount: number;
+    readonly unstagedFileCount: number;
+    readonly untrackedFileCount: number;
+}
+export interface GitDeliveryEvidenceBuildDeps {
+    readonly now: () => number;
+    readonly hash?: ((input: string) => string) | undefined;
+}
+export declare function buildGitDeliveryEvidenceRecord(input: GitDeliveryEvidenceBuildInput, deps: GitDeliveryEvidenceBuildDeps): GitDeliveryEvidenceRecord;
+//# sourceMappingURL=git-mutation-evidence.d.ts.map

package/dist/git-mutation-evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-mutation-evidence.d.ts","sourceRoot":"","sources":["../src/git-mutation-evidence.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAUV,yBAAyB,EACzB,sBAAsB,EAOvB,MAAM,+BAA+B,CAAC;AASvC,OAAO,KAAK,EACV,0BAA0B,EAE3B,MAAM,gCAAgC,CAAC;AAMxC,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,MAAM,EAAE,0BAA0B,CAAC;IAE5C,QAAQ,CAAC,QAAQ,EAAE,2BAA2B,CAAC;IAG/C,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAE/B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9C,QAAQ,CAAC,WAAW,CAAC,EAAE,sBAAsB,GAAG,SAAS,CAAC;CAC3D;AAKD,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,MAAM,CAAC;IAE3B,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC,GAAG,SAAS,CAAC;CACzD;AAwSD,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,6BAA6B,EACpC,IAAI,EAAE,4BAA4B,GACjC,yBAAyB,CAiC3B"}