@oscharko-dev/keiko-server 0.2.8 → 0.2.9

package/dist/gitDelivery/actionSheetProjection.js

@@ -0,0 +1,206 @@
+// Pure projection: content-free kernel facts → UI-safe GitDeliveryActionSheet (Issue #473, Epic #470).
+//
+// This module is a PURE function of (resolvedInputs, worktreeSnapshot, trusted policy packs, approval
+// shape, provider state, providerReady). It runs the kernel preflight (keiko-tools) and the policy
+// evaluator (keiko-contracts), maps their content-free outputs into the action-sheet's typed
+// expected-blocker and recovery-hint vocabularies, and hands the assembled facts to the contract's
+// buildGitDeliveryActionSheet. No IO, no clock, no randomness, no request access — the caller (the
+// route handler) gathers the facts and supplies the actionId and trusted packs.
+//
+// AUTHORITY (AC1): the policy decision, approval necessity, and required approvers are derived ONLY
+// from evaluateGitPolicy over the server's TRUSTED packs. The approval payload is consumed for its
+// SHAPE alone (whether a granted approval is attached); it never asserts the policy decision.
+//
+// Content-free: every value produced here is a count, flag, branch name, or typed/closed-vocabulary
+// code. Never diff content, file paths, secrets, command strings, or raw subprocess output.
+import { buildGitDeliveryActionSheet, gitDeliverySuggestedRecoveryStrategy, evaluateGitPolicy, } from "@oscharko-dev/keiko-contracts";
+import { evaluateGitPreflight, } from "@oscharko-dev/keiko-tools";
+// Demotes an expired granted approval to "not attached" so the action-sheet projection never shows an
+// expired grant as satisfied/ready. The #472 execution kernel re-validates the token and expiry
+// independently before any mutation; this is the preview-time mirror of that check.
+function effectiveApproval(approval, nowMs) {
+    if (approval.required && approval.expiresAtMs !== undefined && approval.expiresAtMs <= nowMs) {
+        return { required: false };
+    }
+    return approval;
+}
+// ─── Target-branch derivation (for policy evaluation) ───────────────────────────────
+// The affected branch name the policy evaluator matches branch-pattern rules against. Mirrors the
+// contract's affectedBranchOf but is local so this module owns its own policy-context derivation.
+function targetBranchName(inputs) {
+    switch (inputs.kind) {
+        case "branch-create":
+            return inputs.branchName;
+        case "push":
+            return inputs.sourceBranchName;
+        case "pr-create":
+        case "pr-update":
+            return inputs.headBranchName;
+        default:
+            return undefined;
+    }
+}
+// ─── Expected-blocker mapping (AC2/AC3) ─────────────────────────────────────────────
+function preflightBlocker(finding) {
+    return {
+        source: "preflight",
+        severity: finding.severity,
+        remediation: finding.remediation,
+        reasonCode: finding.code,
+    };
+}
+function policyBlocker(decision) {
+    if (decision.outcome !== "blocked") {
+        return undefined;
+    }
+    return {
+        source: "policy",
+        severity: "blocking",
+        remediation: "user-actionable",
+        reasonCode: decision.reason,
+    };
+}
+const PROVIDER_BLOCKER_KINDS = [
+    "merge",
+    "pr-create",
+    "pr-update",
+];
+function providerBlocker(inputs, mergeReadiness) {
+    if (!PROVIDER_BLOCKER_KINDS.includes(inputs.kind)) {
+        return undefined;
+    }
+    if (mergeReadiness?.ready !== false || mergeReadiness.blockingReason === undefined) {
+        return undefined;
+    }
+    return {
+        source: "provider",
+        severity: "advisory",
+        remediation: "user-actionable",
+        reasonCode: mergeReadiness.blockingReason,
+    };
+}
+function collectExpectedBlockers(findings, decision, inputs, mergeReadiness) {
+    const blockers = findings.map(preflightBlocker);
+    const policy = policyBlocker(decision);
+    if (policy !== undefined) {
+        blockers.push(policy);
+    }
+    const provider = providerBlocker(inputs, mergeReadiness);
+    if (provider !== undefined) {
+        blockers.push(provider);
+    }
+    return blockers;
+}
+// ─── Recovery-hint mapping (AC4 — common failure classes, same surface) ─────────────
+// A deterministic, exhaustive table from each preflight finding code to a recovery action hint. The
+// "recover-via-strategy" hints are produced separately so they can carry a suggestedRecoveryStrategy.
+const STRATEGY_RECOVERY_CODES = new Set([
+    "dirty-worktree-impacts-recovery",
+    "recovery-target-unset",
+]);
+const FINDING_RECOVERY_HINT = {
+    "detached-head": "configure-upstream",
+    "branch-already-exists": "adjust-policy-target",
+    "base-branch-missing": "adjust-policy-target",
+    "switch-target-missing": "adjust-policy-target",
+    "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": "retry",
+    "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 worktreeIsDirty(snapshot) {
+    return (snapshot.stagedFileCount > 0 ||
+        snapshot.unstagedFileCount > 0 ||
+        snapshot.untrackedFileCount > 0);
+}
+function recoveryHintForFinding(finding, inputs, snapshot) {
+    if (STRATEGY_RECOVERY_CODES.has(finding.code)) {
+        return {
+            actionHint: "recover-via-strategy",
+            remediation: finding.remediation,
+            suggestedRecoveryStrategy: gitDeliverySuggestedRecoveryStrategy(inputs.kind, worktreeIsDirty(snapshot)),
+        };
+    }
+    return { actionHint: FINDING_RECOVERY_HINT[finding.code], remediation: finding.remediation };
+}
+function policyRecoveryHint(decision) {
+    if (decision.outcome === "approval-gated") {
+        return { actionHint: "request-approval", remediation: "user-actionable" };
+    }
+    if (decision.outcome === "blocked") {
+        const actionHint = decision.reason === "approval-expired" ? "request-approval" : "adjust-policy-target";
+        return { actionHint, remediation: "user-actionable" };
+    }
+    return undefined;
+}
+// De-duplicates recovery hints on a stable signature (action + strategy) so the same class of fix is
+// surfaced once even when several findings map to it. First occurrence wins (order-preserving).
+function dedupeRecoveryHints(hints) {
+    const seen = new Set();
+    const out = [];
+    for (const hint of hints) {
+        const signature = `${hint.actionHint}:${hint.suggestedRecoveryStrategy ?? ""}`;
+        if (!seen.has(signature)) {
+            seen.add(signature);
+            out.push(hint);
+        }
+    }
+    return out;
+}
+function buildRecoveryHints(findings, decision, inputs, snapshot, providerReady) {
+    const hints = findings.map((finding) => recoveryHintForFinding(finding, inputs, snapshot));
+    const policy = policyRecoveryHint(decision);
+    if (policy !== undefined) {
+        hints.push(policy);
+    }
+    if (!providerReady) {
+        hints.push({ actionHint: "wait-for-provider", remediation: "internal" });
+    }
+    return dedupeRecoveryHints(hints);
+}
+function definedProviderState(state) {
+    const out = {};
+    if (state.pullRequest !== undefined)
+        out.pullRequest = state.pullRequest;
+    if (state.mergeReadiness !== undefined)
+        out.mergeReadiness = state.mergeReadiness;
+    if (state.branchProtection !== undefined)
+        out.branchProtection = state.branchProtection;
+    if (state.checks !== undefined)
+        out.checks = state.checks;
+    return out;
+}
+/**
+ * The pure projection. Runs preflight + policy over the supplied content-free facts and assembles the
+ * UI-safe action sheet. Deterministic: identical facts always yield an identical sheet.
+ */
+export function buildActionSheetFromFacts(facts) {
+    const { resolvedInputs, worktreeSnapshot, providerState } = facts;
+    const preflight = evaluateGitPreflight(resolvedInputs, worktreeSnapshot);
+    const policyDecision = evaluateGitPolicy(facts.policyPacks.orgPack, facts.policyPacks.repoPack, {
+        actionKind: resolvedInputs.kind,
+        targetBranchName: targetBranchName(resolvedInputs),
+        activeProviderCapabilities: facts.activeProviderCapabilities,
+    });
+    const expectedBlockers = collectExpectedBlockers(preflight.findings, policyDecision, resolvedInputs, providerState.mergeReadiness);
+    const recovery = buildRecoveryHints(preflight.findings, policyDecision, resolvedInputs, worktreeSnapshot, facts.providerReady);
+    return buildGitDeliveryActionSheet({
+        actionId: facts.actionId,
+        resolvedInputs,
+        policyDecision,
+        approvalRequirement: effectiveApproval(facts.approvalRequirement, facts.nowMs),
+        providerReady: facts.providerReady,
+        expectedBlockers,
+        recovery,
+        ...definedProviderState(providerState),
+    });
+}

package/dist/gitDelivery/actionSheetRoutes.d.ts

@@ -0,0 +1,29 @@
+import { type GitDeliveryApprovalRequirement, type GitDeliveryProviderCapability, type GitDeliveryResolvedInputs } from "@oscharko-dev/keiko-contracts";
+import type { GitWorktreeSnapshot } from "@oscharko-dev/keiko-tools";
+import type { RouteContext, RouteDefinition, RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+import { type GitDeliveryProviderStateFacts, type GitDeliveryTrustedPolicyPacks } from "./actionSheetProjection.js";
+export type GitDeliveryActionSheetErrorCode = "GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST" | "GIT_DELIVERY_ACTION_SHEET_PAYLOAD_TOO_LARGE" | "GIT_DELIVERY_ACTION_SHEET_FORBIDDEN_PAYLOAD";
+export interface GitDeliveryActionSheetErrorBody {
+    readonly error: {
+        readonly code: GitDeliveryActionSheetErrorCode;
+        readonly message: string;
+    };
+}
+interface ValidatedRequest {
+    readonly resolvedInputs: GitDeliveryResolvedInputs;
+    readonly worktreeSnapshot: GitWorktreeSnapshot;
+    readonly approvalRequirement: GitDeliveryApprovalRequirement;
+    readonly providerState: GitDeliveryProviderStateFacts;
+    readonly activeProviderCapabilities: readonly GitDeliveryProviderCapability[];
+}
+export interface GitDeliveryActionSheetRouteOptions {
+    readonly idGenerator?: (request: ValidatedRequest) => string;
+    readonly policyPacks?: (deps: UiHandlerDeps) => GitDeliveryTrustedPolicyPacks;
+    readonly now?: () => number;
+}
+export declare const createHandleGitDeliveryActionSheet: (options?: GitDeliveryActionSheetRouteOptions) => ((ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>);
+export declare const handleGitDeliveryActionSheet: (ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>;
+export declare const GIT_DELIVERY_ACTION_SHEET_ROUTE_GROUP: readonly RouteDefinition[];
+export {};
+//# sourceMappingURL=actionSheetRoutes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"actionSheetRoutes.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/actionSheetRoutes.ts"],"names":[],"mappings":"AA2BA,OAAO,EAQL,KAAK,8BAA8B,EACnC,KAAK,6BAA6B,EAClC,KAAK,yBAAyB,EAC/B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAEL,KAAK,6BAA6B,EAClC,KAAK,6BAA6B,EACnC,MAAM,4BAA4B,CAAC;AAIpC,MAAM,MAAM,+BAA+B,GACvC,uCAAuC,GACvC,6CAA6C,GAC7C,6CAA6C,CAAC;AAElD,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;QAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH;AA6MD,UAAU,gBAAgB;IACxB,QAAQ,CAAC,cAAc,EAAE,yBAAyB,CAAC;IACnD,QAAQ,CAAC,gBAAgB,EAAE,mBAAmB,CAAC;IAC/C,QAAQ,CAAC,mBAAmB,EAAE,8BAA8B,CAAC;IAC7D,QAAQ,CAAC,aAAa,EAAE,6BAA6B,CAAC;IACtD,QAAQ,CAAC,0BAA0B,EAAE,SAAS,6BAA6B,EAAE,CAAC;CAC/E;AAgFD,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,MAAM,CAAC;IAE7D,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,aAAa,KAAK,6BAA6B,CAAC;IAG9E,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,kCAAkC,GAC7C,UAAS,kCAAuC,KAC/C,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAqCnE,CAAC;AAEF,eAAO,MAAM,4BAA4B,QAvC/B,YAAY,QAAQ,aAAa,KAAK,OAAO,CAAC,WAAW,CAuCa,CAAC;AAIjF,eAAO,MAAM,qCAAqC,EAAE,SAAS,eAAe,EAM3E,CAAC"}

package/dist/gitDelivery/actionSheetRoutes.js

@@ -0,0 +1,293 @@
+// Governed Git delivery action-sheet BFF route (Issue #473, Epic #470).
+//
+// Single additive, READ-ONLY HTTP handler:
+//   * POST /api/git-delivery/action-sheet
+//
+// It is a COMPUTATIONAL endpoint: it NEVER mutates the repository and NEVER calls runGitMutation. It
+// validates a content-free request envelope, runs the kernel preflight + the server-side policy
+// evaluator over TRUSTED packs, and returns a UI-safe GitDeliveryActionSheet projection.
+//
+// AUTHORITY (AC1): the policy decision, approval necessity, and required approvers come from
+// evaluateGitPolicy over the server's trusted packs — NEVER from a client-asserted field. The request
+// may carry a GRANTED approval payload; only its SHAPE is validated (isGitDeliveryApprovalRequirement).
+// There is no client-supplied policy-decision field, and there must never be one.
+//
+// Hard constraints (mirroring qualityIntelligence/handoffRoutes.ts):
+//   * Unknown top-level keys are REJECTED so a leaky client cannot smuggle content through the seam.
+//   * Every string field is scrubbed for credential-shaped substrings before processing.
+//   * Bounded body read (~64 KiB) → 413; bad JSON / failed validation → 400; both as a content-free
+//     `{ error: { code, message } }` envelope keyed by a typed code union.
+//   * CSRF + JSON content-type are enforced CENTRALLY by server.ts for POST — no per-route opt-in.
+//
+// Content-free: the response carries counts, flags, branch names, and typed codes only — never diff
+// content, file paths, secrets, command strings, or raw subprocess output. The assembled sheet is
+// additionally deep-redacted through deps.redactor before it leaves the server (defence-in-depth).
+import { sha256Hex } from "@oscharko-dev/keiko-security";
+import { isGitDeliveryApprovalRequirement, isGitDeliveryBranchProtection, isGitDeliveryChecksState, isGitDeliveryMergeReadiness, isGitDeliveryProviderCapability, isGitDeliveryPullRequestState, parseGitDeliveryResolvedInputs, } from "@oscharko-dev/keiko-contracts";
+import { containsForbiddenSecretShape } from "../qualityIntelligence/connectorErrors.js";
+import { buildActionSheetFromFacts, } from "./actionSheetProjection.js";
+const SAFE_MESSAGES = {
+    GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST: "The request body is not a valid Git delivery action-sheet request.",
+    GIT_DELIVERY_ACTION_SHEET_PAYLOAD_TOO_LARGE: "The Git delivery action-sheet request exceeds the maximum permitted size.",
+    GIT_DELIVERY_ACTION_SHEET_FORBIDDEN_PAYLOAD: "The action-sheet request contained a forbidden field. Requests may not carry credentials, headers, or URLs.",
+};
+const errResult = (status, code) => ({
+    status,
+    body: { error: { code, message: SAFE_MESSAGES[code] } },
+});
+// ─── Bounded body reading ──────────────────────────────────────────────────────────────
+const MAX_BODY_BYTES = 64 * 1024;
+class BodyTooLargeError extends Error {
+    constructor() {
+        super("Action-sheet body exceeds the route cap");
+        this.name = "BodyTooLargeError";
+    }
+}
+const readBody = (req) => new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    let capped = false;
+    req.on("data", (chunk) => {
+        total += chunk.length;
+        if (total > MAX_BODY_BYTES) {
+            if (!capped) {
+                capped = true;
+                chunks.length = 0;
+                reject(new BodyTooLargeError());
+                req.resume();
+            }
+            return;
+        }
+        chunks.push(chunk);
+    });
+    req.on("end", () => {
+        if (!capped)
+            resolve(Buffer.concat(chunks).toString("utf8"));
+    });
+    req.on("error", reject);
+});
+// ─── Validation helpers ──────────────────────────────────────────────────────────────
+const isPlainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const hasOnlyAllowedKeys = (obj, allowed) => {
+    for (const key of Object.keys(obj)) {
+        if (!allowed.has(key))
+            return false;
+    }
+    return true;
+};
+const ALLOWED_REQUEST_KEYS = new Set([
+    "schemaVersion",
+    "resolvedInputs",
+    "worktreeSnapshot",
+    "approval",
+    "providerState",
+    "activeProviderCapabilities",
+]);
+const ALLOWED_PROVIDER_STATE_KEYS = new Set([
+    "pullRequest",
+    "mergeReadiness",
+    "branchProtection",
+    "checks",
+]);
+const scanForbiddenStrings = (value) => {
+    if (typeof value === "string")
+        return containsForbiddenSecretShape(value);
+    if (Array.isArray(value))
+        return value.some(scanForbiddenStrings);
+    if (isPlainObject(value)) {
+        for (const v of Object.values(value)) {
+            if (scanForbiddenStrings(v))
+                return true;
+        }
+        return false;
+    }
+    return false;
+};
+// Zero-width, bidi-control, and BOM format characters. Branch names / refs / IDs in this content-free
+// request never legitimately contain them; a U+202E override or zero-width char would spoof the
+// approval target on the surface whose whole purpose is to show WHICH branch is being approved
+// (Trojan-Source). Reject fail-closed at the boundary. (C0/C1 controls are already barred by git ref
+// rules and the kernel adapter's NUL/flag guards, so this set deliberately omits them.)
+const UNSAFE_FORMAT_CHAR = new RegExp("[\\u200B-\\u200F\\u202A-\\u202E\\u2060-\\u2064\\u2066-\\u206F\\uFEFF]", "u");
+const scanUnsafeFormatChars = (value) => {
+    if (typeof value === "string")
+        return UNSAFE_FORMAT_CHAR.test(value);
+    if (Array.isArray(value))
+        return value.some(scanUnsafeFormatChars);
+    if (isPlainObject(value))
+        return Object.values(value).some(scanUnsafeFormatChars);
+    return false;
+};
+// ─── Worktree-snapshot shape validation (content-free; counts/flags/names only) ──────
+const isNonNegInt = (value) => typeof value === "number" && Number.isInteger(value) && value >= 0;
+const isBool = (value) => typeof value === "boolean";
+const isStringArray = (value) => Array.isArray(value) && value.every((entry) => typeof entry === "string");
+const isOptional = (check, v) => v === undefined || check(v);
+const ABORTABLE_OPERATIONS = new Set([
+    "merge",
+    "rebase",
+    "cherry-pick",
+    "revert",
+    "bisect",
+]);
+function snapshotCountFieldsValid(value) {
+    return (isBool(value.headDetached) &&
+        isOptional((v) => typeof v === "string", value.currentBranchName) &&
+        isNonNegInt(value.stagedFileCount) &&
+        isNonNegInt(value.unstagedFileCount) &&
+        isNonNegInt(value.untrackedFileCount));
+}
+function snapshotRemoteFieldsValid(value) {
+    return (isBool(value.hasUpstream) &&
+        isNonNegInt(value.aheadCount) &&
+        isNonNegInt(value.behindCount) &&
+        isStringArray(value.existingLocalBranchNames) &&
+        isStringArray(value.remoteAliases) &&
+        isOptional(isBool, value.remoteReachable) &&
+        isOptional((v) => typeof v === "string" && ABORTABLE_OPERATIONS.has(v), value.operationInProgress));
+}
+function isGitWorktreeSnapshot(value) {
+    return (isPlainObject(value) && snapshotCountFieldsValid(value) && snapshotRemoteFieldsValid(value));
+}
+// ─── Provider-state validation ───────────────────────────────────────────────────────
+function validateProviderState(raw) {
+    if (raw === undefined)
+        return { ok: true, value: {} };
+    if (!isPlainObject(raw) || !hasOnlyAllowedKeys(raw, ALLOWED_PROVIDER_STATE_KEYS)) {
+        return { ok: false };
+    }
+    if (!isOptional(isGitDeliveryPullRequestState, raw.pullRequest) ||
+        !isOptional(isGitDeliveryMergeReadiness, raw.mergeReadiness) ||
+        !isOptional(isGitDeliveryBranchProtection, raw.branchProtection) ||
+        !isOptional(isGitDeliveryChecksState, raw.checks)) {
+        return { ok: false };
+    }
+    return { ok: true, value: raw };
+}
+function validateProviderCapabilities(raw) {
+    if (raw === undefined)
+        return { ok: true, value: [] };
+    if (!Array.isArray(raw) || !raw.every(isGitDeliveryProviderCapability)) {
+        return { ok: false };
+    }
+    return { ok: true, value: raw };
+}
+function validateApproval(raw) {
+    if (raw === undefined)
+        return { ok: true, value: { required: false } };
+    if (!isGitDeliveryApprovalRequirement(raw))
+        return { ok: false };
+    return { ok: true, value: raw };
+}
+const badRequest = () => ({
+    kind: "err",
+    result: errResult(400, "GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST"),
+});
+// Envelope-level gate: shape, allowed keys, schema version, secret-shape scan, and unsafe-format-char
+// (bidi/zero-width/BOM) scan. Extracted so validateRequest stays within the complexity budget.
+function preValidateEnvelope(parsed) {
+    if (!isPlainObject(parsed) || !hasOnlyAllowedKeys(parsed, ALLOWED_REQUEST_KEYS)) {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST") };
+    }
+    if (parsed.schemaVersion !== "1") {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST") };
+    }
+    if (scanForbiddenStrings(parsed)) {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_ACTION_SHEET_FORBIDDEN_PAYLOAD") };
+    }
+    if (scanUnsafeFormatChars(parsed)) {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST") };
+    }
+    return { ok: true, obj: parsed };
+}
+function validateRequest(parsed) {
+    const envelope = preValidateEnvelope(parsed);
+    if (!envelope.ok)
+        return { kind: "err", result: envelope.result };
+    const obj = envelope.obj;
+    const inputs = parseGitDeliveryResolvedInputs(obj.resolvedInputs);
+    if (!inputs.ok)
+        return badRequest();
+    if (!isGitWorktreeSnapshot(obj.worktreeSnapshot))
+        return badRequest();
+    const approval = validateApproval(obj.approval);
+    if (!approval.ok)
+        return badRequest();
+    const providerState = validateProviderState(obj.providerState);
+    if (!providerState.ok)
+        return badRequest();
+    const capabilities = validateProviderCapabilities(obj.activeProviderCapabilities);
+    if (!capabilities.ok)
+        return badRequest();
+    return {
+        kind: "ok",
+        request: {
+            resolvedInputs: inputs.value,
+            worktreeSnapshot: obj.worktreeSnapshot,
+            approvalRequirement: approval.value,
+            providerState: providerState.value,
+            activeProviderCapabilities: capabilities.value,
+        },
+    };
+}
+// ─── Deterministic action id ─────────────────────────────────────────────────────────
+// A stable id derived from the content-free request facts so identical requests are addressable
+// identically and the projection is reproducible. Injectable via options.idGenerator for tests.
+function defaultActionId(request) {
+    const seed = JSON.stringify({
+        inputs: request.resolvedInputs,
+        snapshot: request.worktreeSnapshot,
+        capabilities: request.activeProviderCapabilities,
+    });
+    return `git-delivery-action-${sha256Hex(seed).slice(0, 24)}`;
+}
+export const createHandleGitDeliveryActionSheet = (options = {}) => {
+    const idGenerator = options.idGenerator ?? defaultActionId;
+    const resolvePolicyPacks = options.policyPacks ?? (() => ({}));
+    const now = options.now ?? (() => Date.now());
+    return async (ctx, deps) => {
+        let raw;
+        try {
+            raw = await readBody(ctx.req);
+        }
+        catch (error) {
+            if (error instanceof BodyTooLargeError) {
+                return errResult(413, "GIT_DELIVERY_ACTION_SHEET_PAYLOAD_TOO_LARGE");
+            }
+            return errResult(400, "GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST");
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return errResult(400, "GIT_DELIVERY_ACTION_SHEET_BAD_REQUEST");
+        }
+        const validation = validateRequest(parsed);
+        if (validation.kind === "err")
+            return validation.result;
+        const { request } = validation;
+        const sheet = buildActionSheetFromFacts({
+            actionId: idGenerator(request),
+            resolvedInputs: request.resolvedInputs,
+            worktreeSnapshot: request.worktreeSnapshot,
+            approvalRequirement: request.approvalRequirement,
+            policyPacks: resolvePolicyPacks(deps),
+            activeProviderCapabilities: request.activeProviderCapabilities,
+            providerState: request.providerState,
+            providerReady: true,
+            nowMs: now(),
+        });
+        return { status: 200, body: deps.redactor(sheet) };
+    };
+};
+export const handleGitDeliveryActionSheet = createHandleGitDeliveryActionSheet();
+// Mechanically-mergeable route group. routes.ts spreads this into API_ROUTES, mirroring
+// QI_HANDOFF_ROUTE_GROUP, so concurrent #470 epic merges stay merge-safe.
+export const GIT_DELIVERY_ACTION_SHEET_ROUTE_GROUP = [
+    {
+        method: "POST",
+        pattern: "/api/git-delivery/action-sheet",
+        handler: handleGitDeliveryActionSheet,
+    },
+];

package/dist/gitDelivery/agentOperationsRoutes.d.ts

@@ -0,0 +1,33 @@
+import { type GitRepositoryAgentOperationRequest, type GitRepositoryAgentOperationResponse } from "@oscharko-dev/keiko-contracts";
+import { type RouteContext, type RouteDefinition, type RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+interface IdempotencyEntry {
+    readonly fingerprint: string;
+    readonly pending?: Promise<GitRepositoryAgentOperationResponse>;
+    readonly result?: GitRepositoryAgentOperationResponse;
+}
+export declare const DEFAULT_IDEMPOTENCY_MAX_ENTRIES = 1024;
+export declare const DEFAULT_IDEMPOTENCY_TTL_MS: number;
+export interface IdempotencyCacheOptions {
+    readonly maxEntries?: number;
+    readonly ttlMs?: number;
+    readonly now?: () => number;
+}
+export declare class IdempotencyCache {
+    private readonly entries;
+    private readonly maxEntries;
+    private readonly ttlMs;
+    private readonly now;
+    constructor(options?: IdempotencyCacheOptions);
+    get size(): number;
+    get(key: string): IdempotencyEntry | undefined;
+    set(key: string, entry: IdempotencyEntry): void;
+    delete(key: string): void;
+    private pruneExpired;
+    private evictOverflow;
+}
+export declare function handleGitAgentOperationWithDelegate(request: GitRepositoryAgentOperationRequest, fingerprint: string, delegate: () => Promise<RouteResult>, cache?: IdempotencyCache): Promise<RouteResult>;
+export declare function handleGitAgentOperation(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare const GIT_AGENT_OPERATION_ROUTE_GROUP: readonly RouteDefinition[];
+export {};
+//# sourceMappingURL=agentOperationsRoutes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agentOperationsRoutes.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/agentOperationsRoutes.ts"],"names":[],"mappings":"AAUA,OAAO,EAKL,KAAK,kCAAkC,EACvC,KAAK,mCAAmC,EACzC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAa,KAAK,YAAY,EAAE,KAAK,eAAe,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAEpG,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AA+ChD,UAAU,gBAAgB;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,mCAAmC,CAAC,CAAC;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,mCAAmC,CAAC;CACvD;AAKD,eAAO,MAAM,+BAA+B,OAAO,CAAC;AACpD,eAAO,MAAM,0BAA0B,QAAiB,CAAC;AAEzD,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAaD,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAEhB,OAAO,GAAE,uBAA4B;IASxD,IAAW,IAAI,IAAI,MAAM,CAExB;IAEM,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS;IAa9C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAO/C,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIhC,OAAO,CAAC,YAAY;IASpB,OAAO,CAAC,aAAa;CAatB;AAqVD,wBAAsB,mCAAmC,CACvD,OAAO,EAAE,kCAAkC,EAC3C,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,EACpC,KAAK,GAAE,gBAAmC,GACzC,OAAO,CAAC,WAAW,CAAC,CAuBtB;AAED,wBAAsB,uBAAuB,CAC3C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAMtB;AAED,eAAO,MAAM,+BAA+B,EAAE,SAAS,eAAe,EAMrE,CAAC"}