@oscharko-dev/keiko-server 0.2.7 → 0.2.9

package/dist/gitDelivery/evidenceRoutes.js

@@ -0,0 +1,101 @@
+// Governed Git mutation EVIDENCE export route (Issue #474, Epic #470).
+//
+// Single additive, READ-ONLY HTTP handler:
+//   * GET /api/git-delivery/evidence
+//
+// It returns the exportable GitDeliveryAuditPacket — the redacted records, per-class and
+// per-disposition counts, and the honest known-limitations list — that compliance and support
+// workflows inspect without replaying raw logs or shell transcripts. It mutates nothing and reads
+// only the bounded, date-bucketed evidence ledger written by mutationEvidenceLedger.ts.
+//
+// ACCESS: the route is read-only and returns only the bounded, redacted evidence packet. A GET is not
+// state-changing, so the central CSRF guard does not cover it; the records themselves remain
+// content-free and are revalidated before export.
+//
+// DEFENCE IN DEPTH: every record is re-validated through the contract guard and the whole packet is
+// re-run through deps.redactor before it leaves the server, so a record that somehow escaped
+// build-time or persist-time redaction is scrubbed on the way out, and a tampered/malformed record is
+// dropped rather than served.
+import { buildGitDeliveryAuditPacket, isGitDeliveryEvidenceRecord, } from "@oscharko-dev/keiko-contracts";
+import { GIT_DELIVERY_EVIDENCE_RUNID_PREFIX } from "./mutationEvidenceLedger.js";
+// ─── Read-window bounds ──────────────────────────────────────────────────────────────────
+const DAY_MS = 86_400_000;
+const DEFAULT_BUCKET_DAYS = 7;
+const MAX_BUCKET_DAYS = 30;
+const DEFAULT_EXPORT_RECORDS = 200;
+const MAX_EXPORT_RECORDS = 500;
+function clampInt(raw, fallback, min, max) {
+    if (raw === null) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    if (!Number.isFinite(parsed)) {
+        return fallback;
+    }
+    return Math.min(Math.max(parsed, min), max);
+}
+// Date-bucket run ids for the most recent `days` UTC days, OLDEST first so concatenated records stay
+// chronological and the tail slice keeps the most recent.
+function recentRunIds(nowMs, days) {
+    const ids = [];
+    for (let offset = days - 1; offset >= 0; offset -= 1) {
+        const iso = new Date(nowMs - offset * DAY_MS).toISOString();
+        ids.push(`${GIT_DELIVERY_EVIDENCE_RUNID_PREFIX}${iso.slice(0, 10)}`);
+    }
+    return ids;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Reads a single bucket, dropping a corrupt/unparseable document rather than failing the whole export,
+// and re-validating each record through the contract guard (tamper/malformation rejection on read).
+function readBucket(store, runId) {
+    const json = store.get(runId);
+    if (json === undefined) {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return [];
+    }
+    if (!isPlainObject(parsed) || !Array.isArray(parsed.records)) {
+        return [];
+    }
+    return parsed.records.filter(isGitDeliveryEvidenceRecord);
+}
+function collectRecords(store, runIds) {
+    const out = [];
+    for (const runId of runIds) {
+        out.push(...readBucket(store, runId));
+    }
+    return out;
+}
+export const createHandleGitDeliveryEvidenceExport = (options = {}) => {
+    const now = options.now ?? (() => Date.now());
+    return (ctx, deps) => {
+        const days = clampInt(ctx.url.searchParams.get("days"), DEFAULT_BUCKET_DAYS, 1, MAX_BUCKET_DAYS);
+        const limit = clampInt(ctx.url.searchParams.get("limit"), DEFAULT_EXPORT_RECORDS, 1, MAX_EXPORT_RECORDS);
+        const nowMs = now();
+        const all = collectRecords(deps.evidenceStore, recentRunIds(nowMs, days));
+        const truncated = all.length > limit;
+        const records = truncated ? all.slice(all.length - limit) : all;
+        const windowNote = `This export is a bounded window: the most recent ${String(records.length)} record(s) ` +
+            `across the last ${String(days)} day(s)` +
+            (truncated ? `, truncated to the ${String(limit)}-record limit.` : ".");
+        const packet = buildGitDeliveryAuditPacket(records, nowMs, [windowNote]);
+        return { status: 200, body: deps.redactor(packet) };
+    };
+};
+export const handleGitDeliveryEvidenceExport = createHandleGitDeliveryEvidenceExport();
+// Mechanically-mergeable route group. routes.ts spreads this into API_ROUTES alongside
+// GIT_DELIVERY_ACTION_SHEET_ROUTE_GROUP so concurrent #470 epic merges stay merge-safe.
+export const GIT_DELIVERY_EVIDENCE_ROUTE_GROUP = [
+    {
+        method: "GET",
+        pattern: "/api/git-delivery/evidence",
+        handler: handleGitDeliveryEvidenceExport,
+    },
+];

package/dist/gitDelivery/execution.d.ts

@@ -0,0 +1,38 @@
+import type { WorkspaceInfo } from "@oscharko-dev/keiko-workspace";
+import { type GitDeliveryActionKind, type GitDeliveryApprovalRequirement, type GitDeliveryRepoPolicyPack } from "@oscharko-dev/keiko-contracts";
+import { type GitLocalMutationAdapter, type GitMutationCommand, type GitMutationLifecycleResult, type GitMutationOutcome, type GitWorktreeSnapshot } from "@oscharko-dev/keiko-tools";
+import type { UiHandlerDeps } from "../deps.js";
+import type { GitDeliveryTrustedPolicyPacks } from "./actionSheetProjection.js";
+export declare const KEIKO_DEFAULT_LOCAL_GIT_POLICY_PACK: GitDeliveryRepoPolicyPack;
+export interface GitDeliveryExecutionSeams {
+    readonly adapterFactory?: ((workspace: WorkspaceInfo) => GitLocalMutationAdapter) | undefined;
+    readonly snapshotReader?: ((workspace: WorkspaceInfo) => Promise<GitWorktreeSnapshot>) | undefined;
+    readonly stagedPathsReader?: ((workspace: WorkspaceInfo) => Promise<readonly string[]>) | undefined;
+    readonly policyPacks?: GitDeliveryTrustedPolicyPacks | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly newActionId?: (() => string) | undefined;
+}
+export declare function resolveProjectWorkspace(deps: Pick<UiHandlerDeps, "managedTaskWorkspaceRoot" | "store" | "workspaceProvisioning">, projectId: string): WorkspaceInfo | undefined;
+export declare function readWorktreeSnapshotFor(workspace: WorkspaceInfo, seams: GitDeliveryExecutionSeams, now: () => number): Promise<GitWorktreeSnapshot>;
+export declare function readStagedPathsFor(workspace: WorkspaceInfo, seams: GitDeliveryExecutionSeams, now: () => number): Promise<readonly string[]>;
+export declare function defaultGitDeliveryActionId(command: unknown, nowMs: number): string;
+export declare function persistGitDeliveryEvidence(deps: Pick<UiHandlerDeps, "evidenceStore" | "redactor">, result: GitMutationLifecycleResult, snapshot: GitWorktreeSnapshot, repoId: string, now: () => number): void;
+/**
+ * Runs ONE governed local mutation end-to-end: live snapshot → kernel (preflight + policy + approval +
+ * execute) → evidence. Returns the kernel lifecycle result; the caller projects it into a content-free
+ * HTTP body. Evidence is appended best-effort BEFORE the caller responds.
+ */
+export declare function executeGovernedMutation(command: GitMutationCommand, approval: GitDeliveryApprovalRequirement, workspace: WorkspaceInfo, deps: Pick<UiHandlerDeps, "evidenceStore" | "redactor">, seams: GitDeliveryExecutionSeams): Promise<GitMutationLifecycleResult>;
+export interface GitDeliveryMutationResponseBody {
+    readonly schemaVersion: "1";
+    readonly status: GitMutationOutcome["status"];
+    readonly actionKind: GitDeliveryActionKind;
+    readonly phaseReached: GitMutationLifecycleResult["phaseReached"];
+    readonly policyOutcome: GitMutationLifecycleResult["envelope"]["policyDecision"]["outcome"];
+    readonly blockReason?: string;
+    readonly preflightFindingCodes?: readonly string[];
+    readonly requiredApprovers?: readonly string[];
+    readonly executionErrorCode?: string;
+}
+export declare function gitDeliveryMutationResponse(result: GitMutationLifecycleResult): GitDeliveryMutationResponseBody;
+//# sourceMappingURL=execution.d.ts.map

package/dist/gitDelivery/execution.d.ts.map

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

package/dist/gitDelivery/execution.js

@@ -0,0 +1,117 @@
+// Governed local Git execution core for the #475 branch/staging/commit routes (Epic #470).
+//
+// Both #475 route groups (localMutationRoutes, commitRoutes) share ONE execution path: resolve and
+// authorize the project workspace, build a TRUSTWORTHY snapshot from the live worktree, drive the
+// #472 kernel `runGitMutation` (the sole execution authority — preflight + policy + approval gates),
+// and append a content-free evidence record through the #474 ledger. No second orchestrator, no
+// generic shell, no terminal-allowlist widening. The git Node effect (adapter + reader) is injected
+// via seams so route tests run deterministically against a fake repository.
+import { GIT_DELIVERY_POLICY_SCHEMA_VERSION, } from "@oscharko-dev/keiko-contracts";
+import { sha256Hex } from "@oscharko-dev/keiko-security";
+import { buildGitDeliveryEvidenceRecord, runGitMutation, } from "@oscharko-dev/keiko-tools";
+import { createNodeGitMutationAdapter, readGitWorktreeSnapshot, readStagedPaths, } from "@oscharko-dev/keiko-tools/internal/git-mutation";
+import { resolveRegisteredOrManagedWorkspaceRoot } from "../task-workspace/authorization.js";
+import { recordGitDeliveryMutationEvidence } from "./mutationEvidenceLedger.js";
+// Default trusted policy: PERMIT the lowest risk class (local-mutation = branch create/switch, stage,
+// unstage, commit) and fail-closed for everything else (publish / protected-or-merge / recovery). It
+// applies when no stricter pack is configured. The decision is still EVALUATED for every action —
+// governance is preserved.
+export const KEIKO_DEFAULT_LOCAL_GIT_POLICY_PACK = {
+    schemaVersion: GIT_DELIVERY_POLICY_SCHEMA_VERSION,
+    repoId: "keiko-local-default",
+    rules: [],
+    defaultRule: {
+        decision: "constrained",
+        constraints: [{ kind: "risk-class-ceiling", maxRiskClass: "local-mutation" }],
+    },
+};
+// projectId IS the workspace root path (mirrors the terminal execution manager). Resolving it through
+// the UI project store both AUTHORIZES the path (only a registered project may be mutated) and yields
+// the WorkspaceInfo the spawn boundary runs in.
+export function resolveProjectWorkspace(deps, projectId) {
+    return resolveRegisteredOrManagedWorkspaceRoot(deps, projectId);
+}
+export function readWorktreeSnapshotFor(workspace, seams, now) {
+    if (seams.snapshotReader !== undefined)
+        return seams.snapshotReader(workspace);
+    return readGitWorktreeSnapshot({ workspace, processEnv: process.env, now });
+}
+export function readStagedPathsFor(workspace, seams, now) {
+    if (seams.stagedPathsReader !== undefined)
+        return seams.stagedPathsReader(workspace);
+    return readStagedPaths({ workspace, processEnv: process.env, now });
+}
+function adapterFor(workspace, seams, now) {
+    if (seams.adapterFactory !== undefined)
+        return seams.adapterFactory(workspace);
+    return createNodeGitMutationAdapter({ workspace, processEnv: process.env, now });
+}
+export function defaultGitDeliveryActionId(command, nowMs) {
+    return `gde-action-${sha256Hex(`${JSON.stringify(command)}:${String(nowMs)}`).slice(0, 24)}`;
+}
+// String-leaf redactor for the evidence ledger, reusing the deps payload redactor (deepRedactStrings
+// applies the inner audit redactString to a top-level string leaf). No new regex.
+function redactStringFor(deps) {
+    return (input) => deps.redactor(input);
+}
+export function persistGitDeliveryEvidence(deps, result, snapshot, repoId, now) {
+    const record = buildGitDeliveryEvidenceRecord({
+        result,
+        snapshot: {
+            headDetached: snapshot.headDetached,
+            ...(snapshot.currentBranchName !== undefined
+                ? { currentBranchName: snapshot.currentBranchName }
+                : {}),
+            stagedFileCount: snapshot.stagedFileCount,
+            unstagedFileCount: snapshot.unstagedFileCount,
+            untrackedFileCount: snapshot.untrackedFileCount,
+        },
+        workflowRunId: `local-git-delivery:${repoId}`,
+        repoId,
+    }, { now });
+    recordGitDeliveryMutationEvidence({ evidenceStore: deps.evidenceStore, redactString: redactStringFor(deps) }, record);
+}
+/**
+ * Runs ONE governed local mutation end-to-end: live snapshot → kernel (preflight + policy + approval +
+ * execute) → evidence. Returns the kernel lifecycle result; the caller projects it into a content-free
+ * HTTP body. Evidence is appended best-effort BEFORE the caller responds.
+ */
+export async function executeGovernedMutation(command, approval, workspace, deps, seams) {
+    const now = seams.now ?? Date.now;
+    const snapshot = await readWorktreeSnapshotFor(workspace, seams, now);
+    const adapter = adapterFor(workspace, seams, now);
+    const packs = seams.policyPacks ?? { repoPack: KEIKO_DEFAULT_LOCAL_GIT_POLICY_PACK };
+    const newActionId = seams.newActionId ?? (() => defaultGitDeliveryActionId(command, now()));
+    const result = await runGitMutation({ command, approval }, {
+        adapter,
+        snapshot,
+        ...(packs.orgPack !== undefined ? { orgPolicyPack: packs.orgPack } : {}),
+        ...(packs.repoPack !== undefined ? { repoPolicyPack: packs.repoPack } : {}),
+        now,
+        newActionId,
+    });
+    persistGitDeliveryEvidence(deps, result, snapshot, workspace.root, now);
+    return result;
+}
+export function gitDeliveryMutationResponse(result) {
+    const { outcome, envelope, phaseReached, preflight } = result;
+    const base = {
+        schemaVersion: "1",
+        status: outcome.status,
+        actionKind: envelope.kind,
+        phaseReached,
+        policyOutcome: envelope.policyDecision.outcome,
+    };
+    if (outcome.status === "blocked") {
+        return outcome.category === "policy-block"
+            ? { ...base, blockReason: outcome.blockReason }
+            : { ...base, preflightFindingCodes: preflight.blocking.map((f) => f.code) };
+    }
+    if (outcome.status === "approval-required") {
+        return { ...base, requiredApprovers: outcome.requiredApprovers };
+    }
+    if (outcome.status === "failed" || outcome.status === "recovery-required") {
+        return { ...base, executionErrorCode: outcome.executionResult.errorCode ?? "internal-error" };
+    }
+    return base;
+}

package/dist/gitDelivery/localMutationRoutes.d.ts

@@ -0,0 +1,30 @@
+import type { GitMutationCommand } from "@oscharko-dev/keiko-tools";
+import type { RouteContext, RouteDefinition, RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+import { type GitDeliveryExecutionSeams } from "./execution.js";
+export type GitDeliveryLocalErrorCode = "GIT_DELIVERY_LOCAL_BAD_REQUEST" | "GIT_DELIVERY_LOCAL_PAYLOAD_TOO_LARGE" | "GIT_DELIVERY_LOCAL_FORBIDDEN_PAYLOAD" | "GIT_DELIVERY_LOCAL_UNKNOWN_PROJECT" | "GIT_DELIVERY_LOCAL_WORKTREE_UNAVAILABLE";
+export interface GitDeliveryLocalErrorBody {
+    readonly error: {
+        readonly code: GitDeliveryLocalErrorCode;
+        readonly message: string;
+    };
+}
+type ParsedCommand = {
+    readonly ok: true;
+    readonly command: GitMutationCommand;
+} | {
+    readonly ok: false;
+};
+interface LocalMutationSpec {
+    readonly pattern: string;
+    readonly allowedKeys: ReadonlySet<string>;
+    readonly parse: (obj: Record<string, unknown>) => ParsedCommand;
+}
+export interface GitDeliveryLocalRouteOptions {
+    readonly execution?: GitDeliveryExecutionSeams;
+}
+export declare const createHandleLocalMutation: (spec: LocalMutationSpec, options?: GitDeliveryLocalRouteOptions) => ((ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>);
+export declare const createGitDeliveryLocalMutationRouteGroup: (options?: GitDeliveryLocalRouteOptions) => readonly RouteDefinition[];
+export declare const GIT_DELIVERY_LOCAL_MUTATION_ROUTE_GROUP: readonly RouteDefinition[];
+export {};
+//# sourceMappingURL=localMutationRoutes.d.ts.map

package/dist/gitDelivery/localMutationRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"localMutationRoutes.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/localMutationRoutes.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAC;AACpE,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAIL,KAAK,yBAAyB,EAC/B,MAAM,gBAAgB,CAAC;AAcxB,MAAM,MAAM,yBAAyB,GACjC,gCAAgC,GAChC,sCAAsC,GACtC,sCAAsC,GACtC,oCAAoC,GACpC,yCAAyC,CAAC;AAE9C,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACxF;AAsBD,KAAK,aAAa,GACd;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AAE3B,UAAU,iBAAiB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,QAAQ,CAAC,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,aAAa,CAAC;CACjE;AAwGD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,yBAAyB,CAAC;CAChD;AAwBD,eAAO,MAAM,yBAAyB,GACpC,MAAM,iBAAiB,EACvB,UAAS,4BAAiC,KACzC,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAqBnE,CAAC;AAEF,eAAO,MAAM,wCAAwC,GACnD,UAAS,4BAAiC,KACzC,SAAS,eAAe,EAKtB,CAAC;AAGN,eAAO,MAAM,uCAAuC,EAAE,SAAS,eAAe,EAClC,CAAC"}

package/dist/gitDelivery/localMutationRoutes.js

@@ -0,0 +1,165 @@
+// Governed local Git branch + staging execution routes (Issue #475, Epic #470).
+//
+// Four additive POST handlers that EXECUTE a governed local mutation through the #472 kernel:
+//   * POST /api/git-delivery/local-branch/create
+//   * POST /api/git-delivery/local-branch/switch
+//   * POST /api/git-delivery/staging/stage
+//   * POST /api/git-delivery/staging/unstage
+//
+// Every handler runs the SAME chain: bounded body + envelope hardening (allowed keys,
+// credential-shape + unsafe-format-char scans) →
+// typed field validation → project authorization → executeGovernedMutation (live snapshot → kernel
+// preflight/policy/approval/execute → evidence) → redacted content-free response. CSRF + JSON content
+// type are enforced centrally by server.ts.
+import { isGitDeliveryApprovalRequirement, } from "@oscharko-dev/keiko-contracts";
+import { executeGovernedMutation, gitDeliveryMutationResponse, resolveProjectWorkspace, } from "./execution.js";
+import { GitDeliveryBodyTooLargeError, hasOnlyAllowedKeys, isContainedPathspec, isNonEmptyString, isPlainObject, readGitDeliveryBody, scanForbiddenStrings, scanUnsafeFormatChars, } from "./requestGuards.js";
+const SAFE_MESSAGES = {
+    GIT_DELIVERY_LOCAL_BAD_REQUEST: "The request body is not a valid governed local Git request.",
+    GIT_DELIVERY_LOCAL_PAYLOAD_TOO_LARGE: "The governed local Git request exceeds the maximum permitted size.",
+    GIT_DELIVERY_LOCAL_FORBIDDEN_PAYLOAD: "The request contained a forbidden field. Requests may not carry credentials, headers, or URLs.",
+    GIT_DELIVERY_LOCAL_UNKNOWN_PROJECT: "The requested project is not a known workspace.",
+    GIT_DELIVERY_LOCAL_WORKTREE_UNAVAILABLE: "The repository worktree could not be inspected. Confirm the project is a Git repository.",
+};
+const errResult = (status, code) => ({
+    status,
+    body: { error: { code, message: SAFE_MESSAGES[code] } },
+});
+const sharedKeys = ["schemaVersion", "projectId", "approval"];
+const BRANCH_CREATE_SPEC = {
+    pattern: "/api/git-delivery/local-branch/create",
+    allowedKeys: new Set([...sharedKeys, "branchName", "baseBranchName", "startPointRefHash"]),
+    parse: (obj) => {
+        if (isNonEmptyString(obj.branchName) &&
+            isNonEmptyString(obj.baseBranchName) &&
+            isNonEmptyString(obj.startPointRefHash)) {
+            return {
+                ok: true,
+                command: {
+                    kind: "branch-create",
+                    branchName: obj.branchName,
+                    baseBranchName: obj.baseBranchName,
+                    startPointRefHash: obj.startPointRefHash,
+                },
+            };
+        }
+        return { ok: false };
+    },
+};
+const BRANCH_SWITCH_SPEC = {
+    pattern: "/api/git-delivery/local-branch/switch",
+    allowedKeys: new Set([...sharedKeys, "branchName"]),
+    parse: (obj) => isNonEmptyString(obj.branchName)
+        ? { ok: true, command: { kind: "branch-switch", branchName: obj.branchName } }
+        : { ok: false },
+};
+function parsePathspecs(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return undefined;
+    if (!value.every(isContainedPathspec))
+        return undefined;
+    return value;
+}
+const STAGE_SPEC = {
+    pattern: "/api/git-delivery/staging/stage",
+    allowedKeys: new Set([...sharedKeys, "pathspecs", "includeUntracked"]),
+    parse: (obj) => {
+        const pathspecs = parsePathspecs(obj.pathspecs);
+        if (pathspecs === undefined || typeof obj.includeUntracked !== "boolean")
+            return { ok: false };
+        return {
+            ok: true,
+            command: { kind: "stage", pathspecs, includeUntracked: obj.includeUntracked },
+        };
+    },
+};
+const UNSTAGE_SPEC = {
+    pattern: "/api/git-delivery/staging/unstage",
+    allowedKeys: new Set([...sharedKeys, "pathspecs"]),
+    parse: (obj) => {
+        const pathspecs = parsePathspecs(obj.pathspecs);
+        return pathspecs === undefined
+            ? { ok: false }
+            : { ok: true, command: { kind: "unstage", pathspecs } };
+    },
+};
+function parseApproval(value) {
+    if (value === undefined)
+        return { required: false };
+    return isGitDeliveryApprovalRequirement(value) ? value : undefined;
+}
+function validate(spec, parsed) {
+    const bad = {
+        kind: "err",
+        result: errResult(400, "GIT_DELIVERY_LOCAL_BAD_REQUEST"),
+    };
+    if (!isPlainObject(parsed) || !hasOnlyAllowedKeys(parsed, spec.allowedKeys))
+        return bad;
+    if (parsed.schemaVersion !== "1")
+        return bad;
+    if (scanForbiddenStrings(parsed)) {
+        return { kind: "err", result: errResult(400, "GIT_DELIVERY_LOCAL_FORBIDDEN_PAYLOAD") };
+    }
+    if (scanUnsafeFormatChars(parsed))
+        return bad;
+    if (!isNonEmptyString(parsed.projectId))
+        return bad;
+    const approval = parseApproval(parsed.approval);
+    if (approval === undefined)
+        return bad;
+    const command = spec.parse(parsed);
+    if (!command.ok)
+        return bad;
+    return { kind: "ok", value: { projectId: parsed.projectId, command: command.command, approval } };
+}
+async function readParsed(req) {
+    let raw;
+    try {
+        raw = await readGitDeliveryBody(req);
+    }
+    catch (error) {
+        const result = error instanceof GitDeliveryBodyTooLargeError
+            ? errResult(413, "GIT_DELIVERY_LOCAL_PAYLOAD_TOO_LARGE")
+            : errResult(400, "GIT_DELIVERY_LOCAL_BAD_REQUEST");
+        return { ok: false, result };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_LOCAL_BAD_REQUEST") };
+    }
+}
+export const createHandleLocalMutation = (spec, options = {}) => {
+    const seams = options.execution ?? {};
+    return async (ctx, deps) => {
+        const read = await readParsed(ctx.req);
+        if (!read.ok)
+            return read.result;
+        const validation = validate(spec, read.value);
+        if (validation.kind === "err")
+            return validation.result;
+        const { projectId, command, approval } = validation.value;
+        const workspace = resolveProjectWorkspace(deps, projectId);
+        if (workspace === undefined)
+            return errResult(404, "GIT_DELIVERY_LOCAL_UNKNOWN_PROJECT");
+        let result;
+        try {
+            result = await executeGovernedMutation(command, approval, workspace, deps, seams);
+        }
+        catch {
+            // The live worktree could not be read (not a git repository, git unavailable). The kernel itself
+            // never throws — only the read-only snapshot step can — so this is a precondition failure, not a
+            // mutation; nothing was executed.
+            return errResult(409, "GIT_DELIVERY_LOCAL_WORKTREE_UNAVAILABLE");
+        }
+        return { status: 200, body: deps.redactor(gitDeliveryMutationResponse(result)) };
+    };
+};
+export const createGitDeliveryLocalMutationRouteGroup = (options = {}) => [BRANCH_CREATE_SPEC, BRANCH_SWITCH_SPEC, STAGE_SPEC, UNSTAGE_SPEC].map((spec) => ({
+    method: "POST",
+    pattern: spec.pattern,
+    handler: createHandleLocalMutation(spec, options),
+}));
+// Mechanically-mergeable route group spread into API_ROUTES by routes.ts.
+export const GIT_DELIVERY_LOCAL_MUTATION_ROUTE_GROUP = createGitDeliveryLocalMutationRouteGroup();

package/dist/gitDelivery/mergeExecution.d.ts

@@ -0,0 +1,63 @@
+import type { WorkspaceInfo } from "@oscharko-dev/keiko-workspace";
+import { type GitDeliveryApprovalRequirement, type GitDeliveryMergeStrategyHint, type GitDeliveryRepoPolicyPack, type GitDeliveryRiskClass, type GitMergeStrategyPolicy } from "@oscharko-dev/keiko-contracts";
+import { type GitMergeAdapter, type GitMergeCommand, type GitMergeLifecycleResult, type GitMergeProviderReadiness, type GitWorktreeSnapshot } from "@oscharko-dev/keiko-tools";
+import type { UiHandlerDeps } from "../deps.js";
+import type { GitDeliveryTrustedPolicyPacks } from "./actionSheetProjection.js";
+import { type GitDeliveryMutationResponseBody } from "./execution.js";
+export declare const KEIKO_DEFAULT_MERGE_POLICY_PACK: GitDeliveryRepoPolicyPack;
+export interface GitDeliveryMergeSeams {
+    readonly mergeAdapterFactory?: ((workspace: WorkspaceInfo) => GitMergeAdapter) | undefined;
+    readonly snapshotReader?: ((workspace: WorkspaceInfo) => Promise<GitWorktreeSnapshot>) | undefined;
+    readonly policyPacks?: GitDeliveryTrustedPolicyPacks | undefined;
+    readonly strategyPolicy?: GitMergeStrategyPolicy | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly newActionId?: (() => string) | undefined;
+}
+export declare function readMergeProviderReadiness(command: GitMergeCommand, workspace: WorkspaceInfo, seams: GitDeliveryMergeSeams, now: () => number): Promise<GitMergeProviderReadiness>;
+/**
+ * Runs ONE governed merge end-to-end: live snapshot → merge gateway (preflight + policy + approval +
+ * readiness gate + execute) → evidence. Returns the gateway lifecycle result; the caller projects it into
+ * a content-free HTTP body. Evidence is appended best-effort BEFORE the caller responds, for allowed AND
+ * blocked alike.
+ */
+export declare function executeGovernedMerge(command: GitMergeCommand, approval: GitDeliveryApprovalRequirement, workspace: WorkspaceInfo, deps: Pick<UiHandlerDeps, "evidenceStore" | "redactor">, seams: GitDeliveryMergeSeams): Promise<GitMergeLifecycleResult>;
+export interface GitDeliveryMergeBlockerView {
+    readonly code: string;
+    readonly severity: string;
+    readonly remediation: string;
+    readonly actionHint?: string;
+}
+export interface GitDeliveryMergeReadinessBody {
+    readonly mergeable: boolean;
+    readonly blockers: readonly GitDeliveryMergeBlockerView[];
+}
+export interface GitDeliveryMergePreviewBody {
+    readonly schemaVersion: "1";
+    readonly actionKind: "merge";
+    readonly baseBranchName: string;
+    readonly headBranchName: string;
+    readonly prExternalId: string;
+    readonly riskClass: GitDeliveryRiskClass;
+    readonly riskSeverity: number;
+    readonly requestedStrategy: GitDeliveryMergeStrategyHint;
+    readonly eligibleStrategies: readonly GitDeliveryMergeStrategyHint[];
+    readonly selectedDefaultStrategy?: GitDeliveryMergeStrategyHint;
+    readonly requestedStrategyEligible: boolean;
+    readonly policyOutcome: string;
+    readonly policyBlockReason?: string;
+    readonly requiresApproval: boolean;
+    readonly readiness: GitDeliveryMergeReadinessBody;
+    readonly recommendation: string;
+}
+export declare function buildGitDeliveryMergePreview(command: GitMergeCommand, provider: GitMergeProviderReadiness, packs: GitDeliveryTrustedPolicyPacks, strategyPolicy: GitMergeStrategyPolicy): GitDeliveryMergePreviewBody;
+export interface GitDeliveryMergeExecuteResponseBody extends GitDeliveryMutationResponseBody {
+    readonly mergeRejectionReason?: string;
+    readonly recoveryDisposition?: string;
+    readonly recoveryActionHint?: string;
+    readonly mergeable?: boolean;
+    readonly readinessBlockers?: readonly GitDeliveryMergeBlockerView[];
+    readonly merged?: boolean;
+    readonly branchDeleted?: boolean;
+}
+export declare function gitDeliveryMergeExecuteResponse(result: GitMergeLifecycleResult): GitDeliveryMergeExecuteResponseBody;
+//# sourceMappingURL=mergeExecution.d.ts.map

package/dist/gitDelivery/mergeExecution.d.ts.map

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