@oscharko-dev/keiko-tools 0.2.7 → 0.2.9

package/dist/git-mutation-evidence.js

@@ -0,0 +1,283 @@
+// Governed Git mutation EVIDENCE builder (Issue #474, Epic #470). Projects the #472 kernel's
+// GitMutationLifecycleResult into the content-free, redacted-by-construction GitDeliveryEvidenceRecord
+// the keiko-contracts evidence atom defines. This is the producer the orchestrator's idempotency
+// journal comment anticipates ("a durable journal — the evidence ledger, #474"), except it records
+// EVERY terminal outcome (succeeded, blocked, rejected, failed, recovery-required, approval-required),
+// not only succeeded retries.
+//
+// PURE: a deterministic function of (lifecycle result, content-free snapshot, correlation, injected
+// deps). No IO, no clock, no randomness — the clock and the hash are injected. Hashing uses the
+// shared keiko-security sha256Hex so remote identifiers, the provider external id, and the repository
+// identity become opaque hashes (AC2) rather than raw artifacts. Local branch names are retained as
+// content-free repository context, consistent with the #473 action-sheet projection.
+//
+// The kernel's lifecycle-phase and outcome vocabularies are mapped onto the contract's self-contained
+// mirrors with exhaustive switches/tables, so a divergence between the kernel and the contract is a
+// compile error here rather than a silent audit gap.
+import { GIT_DELIVERY_EVIDENCE_SCHEMA_VERSION, GIT_DELIVERY_RISK_CLASS_SEVERITY, gitDeliveryRecoveryDispositionForBlockReason, gitDeliveryRecoveryDispositionForExecutionError, gitDeliveryRiskClassForInputs, } from "@oscharko-dev/keiko-contracts";
+import { sha256Hex } from "@oscharko-dev/keiko-security";
+// ─── Phase + outcome-class mapping (exhaustive) ────────────────────────────────────────────────
+function mapLifecyclePhase(phase) {
+    switch (phase) {
+        case "resolve":
+            return "resolve";
+        case "preflight":
+            return "preflight";
+        case "preview":
+            return "preview";
+        case "policy":
+            return "policy";
+        case "execute":
+            return "execute";
+        case "result":
+            return "result";
+        default:
+            return assertNever(phase);
+    }
+}
+function outcomeClassFor(outcome) {
+    switch (outcome.status) {
+        case "succeeded":
+            return "succeeded";
+        case "approval-required":
+            return "approval-required";
+        case "blocked":
+            return "blocked";
+        case "recovery-required":
+            return "recovery-required";
+        case "failed":
+            // A provider rejection is a "rejected" attempt; every other failure (network, timeout,
+            // internal) is a transient "failed" attempt.
+            return outcome.executionResult.errorCode === "provider-rejected" ? "rejected" : "failed";
+        default:
+            return assertNever(outcome);
+    }
+}
+// ─── Recovery-metadata derivation (AC3) ─────────────────────────────────────────────────────────
+// Action hints REUSE the #473 GitDeliveryRecoveryActionHint vocabulary. Every table is exhaustive
+// over its closed contract/kernel vocabulary, so a new code forces an explicit classification here.
+const ACTION_HINT_BY_BLOCK_REASON = {
+    "policy-pack-blocked": "adjust-policy-target",
+    "protected-branch": "adjust-policy-target",
+    "provider-capability-absent": "adjust-policy-target",
+    "approval-expired": "request-approval",
+    "risk-class-ceiling": "adjust-policy-target",
+    "no-applicable-rule": "adjust-policy-target",
+};
+const ACTION_HINT_BY_EXECUTION_ERROR = {
+    // A provider rejection is most often a diverged/non-fast-forward ref; resolving the divergence is
+    // the operator's fix. The provider execution slices (#477/#478) may refine this.
+    "provider-rejected": "resolve-conflicts",
+    "network-failure": "wait-for-provider",
+    conflict: "resolve-conflicts",
+    "precondition-failed": "resolve-conflicts",
+    timeout: "retry",
+    "internal-error": "retry",
+};
+const ACTION_HINT_BY_PREFLIGHT_FINDING = {
+    "detached-head": "recover-via-strategy",
+    "branch-already-exists": "retry",
+    "base-branch-missing": "retry",
+    "switch-target-missing": "retry",
+    "no-changes-to-stage": "stage-changes",
+    "nothing-staged-to-unstage": "stage-changes",
+    "nothing-staged-to-commit": "stage-changes",
+    "untracked-files-impacted": "stage-changes",
+    "no-upstream-configured": "configure-upstream",
+    "nothing-to-push": "retry",
+    "non-fast-forward": "resolve-conflicts",
+    "remote-alias-missing": "configure-upstream",
+    "remote-unreachable": "wait-for-provider",
+    "operation-in-progress": "abort-in-progress-operation",
+    "no-operation-to-abort": "retry",
+    "recovery-target-unset": "recover-via-strategy",
+    "dirty-worktree-impacts-recovery": "recover-via-strategy",
+};
+function recoveryForBlockReason(reason) {
+    return {
+        disposition: gitDeliveryRecoveryDispositionForBlockReason(reason),
+        actionHint: ACTION_HINT_BY_BLOCK_REASON[reason],
+        blockReason: reason,
+    };
+}
+function recoveryForPreflight(findings) {
+    // A blocked-by-preflight attempt is user-fixable: the operator changes the named repository
+    // condition. The dominant (first, deterministic order) blocking finding names the action.
+    const code = findings[0]?.code;
+    return {
+        disposition: "user-fixable",
+        ...(code !== undefined ? { actionHint: ACTION_HINT_BY_PREFLIGHT_FINDING[code] } : {}),
+    };
+}
+function recoveryForExecution(result) {
+    const code = result.errorCode ?? "internal-error";
+    return {
+        disposition: gitDeliveryRecoveryDispositionForExecutionError(code),
+        actionHint: ACTION_HINT_BY_EXECUTION_ERROR[code],
+        ...(result.errorCode !== undefined ? { executionErrorCode: result.errorCode } : {}),
+    };
+}
+function recoveryForRecoveryRequired(result, inputs) {
+    const strategy = inputs.kind === "recovery" ? inputs.recoveryStrategyHint : undefined;
+    return {
+        disposition: "user-fixable",
+        actionHint: "recover-via-strategy",
+        ...(result.errorCode !== undefined ? { executionErrorCode: result.errorCode } : {}),
+        ...(strategy !== undefined ? { suggestedRecoveryStrategy: strategy } : {}),
+    };
+}
+function recoveryFor(outcome, inputs) {
+    switch (outcome.status) {
+        case "succeeded":
+            return { disposition: "none" };
+        case "approval-required":
+            return { disposition: "user-fixable", actionHint: "request-approval" };
+        case "blocked":
+            return outcome.category === "policy-block"
+                ? recoveryForBlockReason(outcome.blockReason)
+                : recoveryForPreflight(outcome.findings);
+        case "failed":
+            return recoveryForExecution(outcome.executionResult);
+        case "recovery-required":
+            return recoveryForRecoveryRequired(outcome.executionResult, inputs);
+        default:
+            return assertNever(outcome);
+    }
+}
+// ─── Section projections ─────────────────────────────────────────────────────────────────────
+// Branch names are echoed raw into the audit record (they are git refs, not secrets). Strip
+// bidirectional/zero-width/BOM format characters so a crafted ref cannot visually spoof which branch
+// an audit row refers to when the export is rendered. Mirrors the action-sheet route's boundary
+// scanner; git ref rules already bar C0/C1 controls and spaces, so only the format-char set is removed.
+const UNSAFE_FORMAT_CHARS = new RegExp("[\\u200B-\\u200F\\u202A-\\u202E\\u2060-\\u2064\\u2066-\\u206F\\uFEFF]", "gu");
+function sanitizeRef(value) {
+    return value.replace(UNSAFE_FORMAT_CHARS, "");
+}
+function approvalFor(approval) {
+    if (!approval.required) {
+        return { required: false };
+    }
+    return {
+        required: true,
+        approvalTokenHash: approval.approvalTokenHash,
+        approvedByUserId: approval.approvedByUserId,
+        approvedAtMs: approval.approvedAtMs,
+        ...(approval.expiresAtMs !== undefined ? { expiresAtMs: approval.expiresAtMs } : {}),
+    };
+}
+function previewFor(preview) {
+    if (preview === undefined) {
+        return undefined;
+    }
+    return {
+        ...(preview.affectedBranchName !== undefined
+            ? { affectedBranchName: sanitizeRef(preview.affectedBranchName) }
+            : {}),
+        ...(preview.estimatedFileCount !== undefined
+            ? { estimatedFileCount: preview.estimatedFileCount }
+            : {}),
+        ...(preview.estimatedBytesDelta !== undefined
+            ? { estimatedBytesDelta: preview.estimatedBytesDelta }
+            : {}),
+        wouldCreateRemoteBranch: preview.wouldCreateRemoteBranch,
+        wouldTriggerChecks: preview.wouldTriggerChecks,
+    };
+}
+function executionFor(result, hash) {
+    if (result === undefined) {
+        return undefined;
+    }
+    return {
+        outcome: result.outcome,
+        durationMs: result.durationMs,
+        ...(result.errorCode !== undefined ? { errorCode: result.errorCode } : {}),
+        ...(result.partialDetail !== undefined
+            ? {
+                attemptedUnitCount: result.partialDetail.attemptedUnitCount,
+                succeededUnitCount: result.partialDetail.succeededUnitCount,
+            }
+            : {}),
+        ...(result.externalId !== undefined ? { externalIdHash: hash(result.externalId) } : {}),
+    };
+}
+function repoContextFor(inputs, snapshot, repoId, hash) {
+    const target = inputs.kind === "branch-create" ? inputs.branchName : snapshot.currentBranchName;
+    return {
+        ...(repoId !== undefined ? { repoIdHash: hash(repoId) } : {}),
+        ...(target !== undefined ? { targetBranchName: sanitizeRef(target) } : {}),
+        headDetached: snapshot.headDetached,
+        stagedFileCount: snapshot.stagedFileCount,
+        unstagedFileCount: snapshot.unstagedFileCount,
+        untrackedFileCount: snapshot.untrackedFileCount,
+        ...(inputs.kind === "push"
+            ? { remoteRefHash: hash(`${inputs.remoteAlias}/${inputs.remoteBranchName}`) }
+            : {}),
+    };
+}
+function effectiveBlockReason(envelope, outcome) {
+    if (outcome.status === "blocked" && outcome.category === "policy-block") {
+        return outcome.blockReason;
+    }
+    // The kernel evaluates policy eagerly (prepareLifecycle) even when preflight halts the lifecycle
+    // first, so a preflight-blocked envelope can still carry a "blocked" policyDecision that was never
+    // the terminal enforcement. Recording that policy reason here would contradict the preflight
+    // disposition, so a preflight-blocked attempt (the only remaining "blocked" category) carries no
+    // policy block reason — its cause is a preflight finding, reflected in recovery.actionHint and
+    // phaseReached === "preflight".
+    if (outcome.status === "blocked") {
+        return undefined;
+    }
+    return envelope.policyDecision.outcome === "blocked" ? envelope.policyDecision.reason : undefined;
+}
+function effectiveApprovers(envelope, outcome) {
+    if (envelope.policyDecision.outcome === "approval-gated") {
+        return envelope.policyDecision.requiredApprovers;
+    }
+    return outcome.status === "approval-required" ? outcome.requiredApprovers : undefined;
+}
+function policyFieldsFor(envelope, outcome) {
+    const blockReason = effectiveBlockReason(envelope, outcome);
+    const requiredApprovers = effectiveApprovers(envelope, outcome);
+    return {
+        ...(blockReason !== undefined ? { blockReason } : {}),
+        ...(requiredApprovers !== undefined ? { requiredApprovers } : {}),
+    };
+}
+// ─── Entry point ─────────────────────────────────────────────────────────────────────────────
+export function buildGitDeliveryEvidenceRecord(input, deps) {
+    const hash = deps.hash ?? sha256Hex;
+    const { envelope, outcome, phaseReached } = input.result;
+    const inputs = envelope.resolvedInputs;
+    const riskClass = gitDeliveryRiskClassForInputs(inputs);
+    const workflowRunIdHash = hash(input.workflowRunId);
+    const evidenceId = `gde-${hash(`${workflowRunIdHash}:${envelope.actionId}`).slice(0, 40)}`;
+    const correlation = {
+        workflowRunIdHash,
+        actionId: envelope.actionId,
+        ...(input.attemptSequence !== undefined ? { attemptSequence: input.attemptSequence } : {}),
+    };
+    const preview = previewFor(envelope.preview);
+    const execution = executionFor(envelope.executionResult, hash);
+    return {
+        schemaVersion: GIT_DELIVERY_EVIDENCE_SCHEMA_VERSION,
+        evidenceId,
+        actionKind: envelope.kind,
+        riskClass,
+        riskSeverity: GIT_DELIVERY_RISK_CLASS_SEVERITY[riskClass],
+        outcomeClass: outcomeClassFor(outcome),
+        phaseReached: mapLifecyclePhase(phaseReached),
+        policyOutcome: envelope.policyDecision.outcome,
+        ...policyFieldsFor(envelope, outcome),
+        correlation,
+        approval: approvalFor(envelope.approvalRequirement),
+        ...(preview !== undefined ? { preview } : {}),
+        ...(execution !== undefined ? { execution } : {}),
+        repoContext: repoContextFor(inputs, input.snapshot, input.repoId, hash),
+        recovery: recoveryFor(outcome, inputs),
+        recordedAtMs: deps.now(),
+        ...(input.evidenceRef !== undefined ? { evidenceRef: input.evidenceRef } : {}),
+    };
+}
+function assertNever(value) {
+    throw new Error(`unhandled git mutation evidence variant: ${JSON.stringify(value)}`);
+}

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

@@ -0,0 +1,22 @@
+import type { WorkspaceInfo } from "@oscharko-dev/keiko-workspace";
+import { type GitLocalMutationAdapter } from "./git-mutation-adapter.js";
+import { type ExecutableResolver, type HomeProvider, type SpawnFn } from "./exec.js";
+import { type SandboxPolicy } from "./types.js";
+export interface NodeGitMutationAdapterDeps {
+    readonly workspace: WorkspaceInfo;
+    readonly processEnv?: NodeJS.ProcessEnv | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly spawn?: SpawnFn | undefined;
+    readonly policy?: SandboxPolicy | undefined;
+    readonly resolveExecutable?: ExecutableResolver | undefined;
+    readonly home?: HomeProvider | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly timeoutMs?: number | undefined;
+}
+export declare function createNodeGitMutationAdapter(deps: NodeGitMutationAdapterDeps): GitLocalMutationAdapter;
+export { GIT_WORKTREE_READ_COMMAND_RULES, GitWorktreeReadError, readGitWorktreeSnapshot, readStagedPaths, type NodeGitWorktreeReaderDeps, } from "./git-worktree-snapshot-node.js";
+export { buildAddExistingBranchArgv, buildAddWorktreeArgv, buildListWorktreesArgv, buildLocalBranchExistsArgv, buildPruneWorktreesArgv, buildRefResolvesArgv, buildRemoveWorktreeArgv, buildShowToplevelArgv, buildWorktreeStatusArgv, createNodeGitWorktreeAdapter, GIT_WORKTREE_COMMAND_RULES, GitWorktreeOperandError, GitWorktreeSpawnError, isSafeGitRefName, isSafeWorktreePathOperand, parseWorktreeListPorcelain, type AddExistingBranchOperands, type AddWorktreeOperands, type GitWorktreeAdapter, type NodeGitWorktreeAdapterDeps, type RemoveWorktreeOperands, type WorktreeListEntry, type WorktreeOperationResult, type WorktreeStatusResult, } from "./git-worktree-adapter.js";
+export { createNodeGitPublishAdapter, type NodeGitPublishAdapterDeps } from "./git-publish-node.js";
+export { createNodeGitPullRequestAdapter, type NodeGitPullRequestAdapterDeps, } from "./git-pr-node.js";
+export { createNodeGitMergeAdapter, type NodeGitMergeAdapterDeps } from "./git-merge-node.js";
+//# sourceMappingURL=git-mutation-node.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"git-mutation-node.d.ts","sourceRoot":"","sources":["../src/git-mutation-node.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAKnE,OAAO,EASL,KAAK,uBAAuB,EAE7B,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,YAAY,EAEjB,KAAK,OAAO,EACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAA8C,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5F,MAAM,WAAW,0BAA0B;IAEzC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAErC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IAEzC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AA4HD,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,0BAA0B,GAC/B,uBAAuB,CAWzB;AAKD,OAAO,EACL,+BAA+B,EAC/B,oBAAoB,EACpB,uBAAuB,EACvB,eAAe,EACf,KAAK,yBAAyB,GAC/B,MAAM,iCAAiC,CAAC;AAQzC,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,sBAAsB,EACtB,0BAA0B,EAC1B,uBAAuB,EACvB,oBAAoB,EACpB,uBAAuB,EACvB,qBAAqB,EACrB,uBAAuB,EACvB,4BAA4B,EAC5B,0BAA0B,EAC1B,uBAAuB,EACvB,qBAAqB,EACrB,gBAAgB,EAChB,yBAAyB,EACzB,0BAA0B,EAC1B,KAAK,yBAAyB,EAC9B,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAC/B,KAAK,sBAAsB,EAC3B,KAAK,iBAAiB,EACtB,KAAK,uBAAuB,EAC5B,KAAK,oBAAoB,GAC1B,MAAM,2BAA2B,CAAC;AAKnC,OAAO,EAAE,2BAA2B,EAAE,KAAK,yBAAyB,EAAE,MAAM,uBAAuB,CAAC;AAMpG,OAAO,EACL,+BAA+B,EAC/B,KAAK,6BAA6B,GACnC,MAAM,kBAAkB,CAAC;AAM1B,OAAO,EAAE,yBAAyB,EAAE,KAAK,uBAAuB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/git-mutation-node.js

@@ -0,0 +1,145 @@
+// Node implementation of the narrow local Git mutation adapter (Issue #472, Epic #470) — AC3.
+//
+// This is the ONLY place governed local Git writes actually execute. Each typed adapter method
+// builds a fixed argv plan from the pure builders (git-mutation-adapter.ts) and runs it through the
+// single keiko-tools no-shell spawn boundary (`runCommand`, exec.ts) with a dedicated mutation
+// allowlist. 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 every governed mutation exactly as they do to every other tool.
+//
+// Lives on the `./internal/git-mutation` subpath (mirroring `./internal/exec` and `./internal/writer`)
+// because it carries the Node execution effect; the pure port, builders, and rules it implements are
+// re-exported from the package's main barrel.
+import { GIT_DELIVERY_SCHEMA_VERSION, } from "@oscharko-dev/keiko-contracts";
+import { buildAbortArgv, buildBranchCreateArgv, buildBranchSwitchArgv, buildCommitArgv, buildRecoveryArgv, buildStageArgv, buildUnstageArgv, GIT_MUTATION_COMMAND_RULES, } from "./git-mutation-adapter.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,
+    };
+}
+// A non-zero git exit at execution time means a precondition that the preflight snapshot did not
+// capture failed against the live repository (a time-of-check/time-of-use gap) — classified as
+// `precondition-failed`, which the taxonomy routes to recovery-required. When part of a multi-step
+// plan already partially applied, the result is `partial` with the attempted/succeeded counts.
+function failureFromExit(durationMs, stepIndex) {
+    if (stepIndex > 0) {
+        return executionResult("partial", durationMs, {
+            errorCode: "precondition-failed",
+            partialDetail: { attemptedUnitCount: stepIndex + 1, succeededUnitCount: stepIndex },
+        });
+    }
+    return executionResult("failed", durationMs, { errorCode: "precondition-failed" });
+}
+function failureFromThrow(error, durationMs, stepIndex) {
+    const partial = stepIndex > 0
+        ? { partialDetail: { attemptedUnitCount: stepIndex + 1, succeededUnitCount: stepIndex } }
+        : {};
+    if (error instanceof CommandTimeoutError) {
+        return executionResult(stepIndex > 0 ? "partial" : "failed", durationMs, {
+            errorCode: "timeout",
+            ...partial,
+        });
+    }
+    if (error instanceof CommandCancelledError) {
+        return executionResult("aborted", durationMs, partial);
+    }
+    // A denied command (our own argv hit the allowlist), an argv-construction fault, or any other
+    // throw is an internal kernel error — it never means the user's repository is at fault.
+    return executionResult(stepIndex > 0 ? "partial" : "failed", durationMs, {
+        errorCode: "internal-error",
+        ...partial,
+    });
+}
+function runOne(ctx, argv) {
+    return runCommand({ command: "git", args: argv, cwd: undefined, timeoutMs: ctx.timeoutMs, signal: ctx.signal }, ctx.runDeps);
+}
+async function runPlan(ctx, plan) {
+    let totalDuration = 0;
+    for (const [stepIndex, argv] of plan.entries()) {
+        let result;
+        try {
+            result = await runOne(ctx, argv);
+        }
+        catch (error) {
+            return failureFromThrow(error, totalDuration, stepIndex);
+        }
+        totalDuration += result.durationMs;
+        if (result.exitCode !== 0) {
+            return failureFromExit(totalDuration, stepIndex);
+        }
+    }
+    return executionResult("succeeded", totalDuration);
+}
+// Builds the argv plan, then runs it. A builder throw (invalid operand) is an internal error that
+// never reaches a spawn.
+async function execPlan(ctx, build) {
+    let plan;
+    try {
+        plan = build();
+    }
+    catch {
+        return executionResult("failed", 0, { errorCode: "internal-error" });
+    }
+    return runPlan(ctx, plan);
+}
+function buildRunContext(deps) {
+    return {
+        runDeps: {
+            workspace: deps.workspace,
+            policy: deps.policy ?? DEFAULT_SANDBOX_POLICY,
+            commandRules: GIT_MUTATION_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,
+    };
+}
+export function createNodeGitMutationAdapter(deps) {
+    const ctx = buildRunContext(deps);
+    return {
+        createBranch: (req) => execPlan(ctx, () => buildBranchCreateArgv(req)),
+        switchBranch: (req) => execPlan(ctx, () => buildBranchSwitchArgv(req)),
+        stage: (req) => execPlan(ctx, () => buildStageArgv(req)),
+        unstage: (req) => execPlan(ctx, () => buildUnstageArgv(req)),
+        commit: (req) => execPlan(ctx, () => buildCommitArgv(req)),
+        abort: (req) => execPlan(ctx, () => buildAbortArgv(req)),
+        recover: (req) => execPlan(ctx, () => buildRecoveryArgv(req)),
+    };
+}
+// The read-only worktree snapshot reader (Issue #475) carries the same Node spawn effect as this
+// adapter, so it is exposed on the SAME `./internal/git-mutation` subpath rather than the pure barrel.
+// Its inspection allowlist is structurally separate from the mutation rules.
+export { GIT_WORKTREE_READ_COMMAND_RULES, GitWorktreeReadError, readGitWorktreeSnapshot, readStagedPaths, } from "./git-worktree-snapshot-node.js";
+// The narrow managed-worktree lifecycle adapter (Issue #445, Epic #443) carries the same Node spawn
+// effect through the same governed `runCommand` boundary with its OWN dedicated allowlist
+// (`GIT_WORKTREE_COMMAND_RULES`: worktree/rev-parse/show-ref only — structurally separate from the
+// mutation, read-inspection, publish, PR, and merge rule sets). It is exposed on the SAME
+// `./internal/git-mutation` subpath. The pure argv builders, operand validators, and porcelain parser
+// are re-exported alongside the node factory so the server can pre-validate operands without spawning.
+export { buildAddExistingBranchArgv, buildAddWorktreeArgv, buildListWorktreesArgv, buildLocalBranchExistsArgv, buildPruneWorktreesArgv, buildRefResolvesArgv, buildRemoveWorktreeArgv, buildShowToplevelArgv, buildWorktreeStatusArgv, createNodeGitWorktreeAdapter, GIT_WORKTREE_COMMAND_RULES, GitWorktreeOperandError, GitWorktreeSpawnError, isSafeGitRefName, isSafeWorktreePathOperand, parseWorktreeListPorcelain, } from "./git-worktree-adapter.js";
+// The Node remote publish executor (Issue #476) carries the same Node spawn effect and a DEDICATED
+// push allowlist; it is exposed on the SAME `./internal/git-mutation` subpath. Its allowlist is
+// structurally separate from both the mutation and the read-only inspection rules.
+export { createNodeGitPublishAdapter } from "./git-publish-node.js";
+// The Node GitHub pull request executor (Issue #477) shells `gh api` through the same spawn boundary
+// with its OWN dedicated PR allowlist (create / update / draft-toggle GraphQL — no merge, no delete);
+// it is exposed on the SAME `./internal/git-mutation` subpath. The GitHub token is read by gh itself,
+// never by Keiko.
+export { createNodeGitPullRequestAdapter, } from "./git-pr-node.js";
+// The Node governed merge executor (Issue #478) shells `gh api` through the same spawn boundary with its
+// OWN dedicated merge allowlist (the merge PUT, the readiness GETs, and the guarded branch DELETE — no
+// generic exec); it is exposed on the SAME `./internal/git-mutation` subpath. The GitHub token is read by
+// gh itself, never by Keiko.
+export { createNodeGitMergeAdapter } from "./git-merge-node.js";

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

@@ -0,0 +1,92 @@
+import type { GitDeliveryAbortableOperation, GitDeliveryActionEnvelope, GitDeliveryApprovalRequirement, GitDeliveryBlockReason, GitDeliveryExecutionResult, GitDeliveryOrgPolicyPack, GitDeliveryProviderCapability, GitDeliveryRecoveryStrategyHint, GitDeliveryRepoPolicyPack } from "@oscharko-dev/keiko-contracts";
+import type { GitLocalMutationAdapter } from "./git-mutation-adapter.js";
+import type { GitPreflightFinding, GitPreflightReport, GitWorktreeSnapshot } from "./git-mutation-preflight.js";
+import type { GitMutationFailureCategory, GitMutationLifecyclePhase } from "./git-mutation-taxonomy.js";
+export interface GitBranchCreateCommand {
+    readonly kind: "branch-create";
+    readonly branchName: string;
+    readonly baseBranchName: string;
+    readonly startPointRefHash: string;
+}
+export interface GitBranchSwitchCommand {
+    readonly kind: "branch-switch";
+    readonly branchName: string;
+}
+export interface GitStageCommand {
+    readonly kind: "stage";
+    readonly pathspecs: readonly string[];
+    readonly includeUntracked: boolean;
+}
+export interface GitUnstageCommand {
+    readonly kind: "unstage";
+    readonly pathspecs: readonly string[];
+}
+export interface GitCommitCommand {
+    readonly kind: "commit";
+    readonly message: string;
+    readonly allowEmpty: boolean;
+}
+export interface GitAbortCommand {
+    readonly kind: "abort";
+    readonly operationToAbort: GitDeliveryAbortableOperation;
+    readonly preserveIndexChanges: boolean;
+}
+export interface GitRecoveryCommand {
+    readonly kind: "recovery";
+    readonly recoveryStrategyHint: GitDeliveryRecoveryStrategyHint;
+    readonly targetRefHash: string;
+    readonly affectedPathspecs: readonly string[];
+}
+export type GitMutationCommand = GitBranchCreateCommand | GitBranchSwitchCommand | GitStageCommand | GitUnstageCommand | GitCommitCommand | GitAbortCommand | GitRecoveryCommand;
+export interface GitMutationRequest {
+    readonly command: GitMutationCommand;
+    readonly approval: GitDeliveryApprovalRequirement;
+    readonly idempotencyKey?: string | undefined;
+}
+export interface GitMutationJournal {
+    lookup(idempotencyKey: string): GitMutationLifecycleResult | undefined;
+    record(idempotencyKey: string, result: GitMutationLifecycleResult): void;
+}
+export interface GitMutationOrchestratorDeps {
+    readonly adapter: GitLocalMutationAdapter;
+    readonly snapshot: GitWorktreeSnapshot;
+    readonly orgPolicyPack?: GitDeliveryOrgPolicyPack | undefined;
+    readonly repoPolicyPack?: GitDeliveryRepoPolicyPack | undefined;
+    readonly activeProviderCapabilities?: readonly GitDeliveryProviderCapability[] | undefined;
+    readonly now: () => number;
+    readonly newActionId: () => string;
+    readonly journal?: GitMutationJournal | undefined;
+}
+export type GitMutationOutcome = {
+    readonly status: "succeeded";
+    readonly executionResult: GitDeliveryExecutionResult;
+} | {
+    readonly status: "approval-required";
+    readonly requiredApprovers: readonly string[];
+} | {
+    readonly status: "blocked";
+    readonly category: "policy-block";
+    readonly blockReason: GitDeliveryBlockReason;
+} | {
+    readonly status: "blocked";
+    readonly category: "preflight-block";
+    readonly findings: readonly GitPreflightFinding[];
+} | {
+    readonly status: "failed";
+    readonly category: "execution-failure" | "provider-failure";
+    readonly executionResult: GitDeliveryExecutionResult;
+} | {
+    readonly status: "recovery-required";
+    readonly category: "recovery-required";
+    readonly executionResult: GitDeliveryExecutionResult;
+};
+export interface GitMutationLifecycleResult {
+    readonly envelope: GitDeliveryActionEnvelope;
+    readonly outcome: GitMutationOutcome;
+    readonly phaseReached: GitMutationLifecyclePhase;
+    readonly preflight: GitPreflightReport;
+}
+export declare function gitMutationOutcomeFailureCategory(outcome: GitMutationOutcome): GitMutationFailureCategory | undefined;
+export declare function runGitMutation(request: GitMutationRequest, deps: GitMutationOrchestratorDeps): Promise<GitMutationLifecycleResult>;
+export declare function createInMemoryGitMutationJournal(): GitMutationJournal;
+//# sourceMappingURL=git-mutation-orchestrator.d.ts.map

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

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