@oscharko-dev/keiko-server 0.2.7 → 0.2.9

package/dist/gitDelivery/mergeExecution.js

@@ -0,0 +1,168 @@
+// Governed merge execution core for the #478 merge routes (Epic #470, ADR-0065).
+//
+// The merge preview + execute routes share ONE path: resolve and authorize the project workspace, read
+// the provider's content-free merge-readiness facts, and (for execute) drive the #478 merge gateway
+// `runGitMerge` (the SEPARATE merge-orchestration authority — preflight + policy + final-approval gates +
+// the readiness gate, executing through a narrow `gh api` adapter with a dedicated merge-only allowlist)
+// and append a content-free evidence record through the #474 ledger for EVERY terminal outcome (allowed
+// and blocked alike — AC4). No second orchestrator, no generic shell, no widening of the local mutation,
+// publish, or PR allowlists. The Node `gh api` effect is injected via seams so route tests run
+// deterministically against a fake.
+import { deriveEligibleMergeStrategies, evaluateGitPolicy, GIT_DELIVERY_POLICY_SCHEMA_VERSION, GIT_DELIVERY_RISK_CLASS_SEVERITY, gitMergeBlockerActionHintFor, gitMergeReadinessFor, gitMergeRecommendationFor, } from "@oscharko-dev/keiko-contracts";
+import { evaluateGitMergeEffectivePolicy, runGitMerge, } from "@oscharko-dev/keiko-tools";
+import { createNodeGitMergeAdapter } from "@oscharko-dev/keiko-tools/internal/git-mutation";
+import { defaultGitDeliveryActionId, gitDeliveryMutationResponse, persistGitDeliveryEvidence, readWorktreeSnapshotFor, } from "./execution.js";
+// Default trusted merge policy: merge is APPROVAL-GATED — the explicit final, high-risk confirmation a
+// merge requires (AC1). No approval token ⇒ approval-required; every other action kind is fail-closed via
+// the blocked defaultRule. Base-branch and strategy enforcement live in the readiness layer (where merge
+// prerequisites belong), not in this authorization pack. Applies only when governed git delivery is
+// ENABLED and no stricter pack is configured; still EVALUATED every time. A deployment may override with a
+// pack naming specific requiredApprovers.
+export const KEIKO_DEFAULT_MERGE_POLICY_PACK = {
+    schemaVersion: GIT_DELIVERY_POLICY_SCHEMA_VERSION,
+    repoId: "keiko-merge-default",
+    rules: [{ actionKind: "merge", decision: "approval-gated", requiredApprovers: [] }],
+    defaultRule: { decision: "blocked" },
+};
+function mergeAdapterFor(workspace, seams, now) {
+    if (seams.mergeAdapterFactory !== undefined)
+        return seams.mergeAdapterFactory(workspace);
+    return createNodeGitMergeAdapter({ workspace, processEnv: process.env, now });
+}
+// Reads the provider's content-free merge-readiness facts. Never throws: a thrown read becomes a
+// provider-error readiness so callers fail closed.
+export async function readMergeProviderReadiness(command, workspace, seams, now) {
+    const adapter = mergeAdapterFor(workspace, seams, now);
+    try {
+        return await adapter.readMergeReadiness({
+            ownerAndRepo: command.ownerAndRepo,
+            prExternalId: command.prExternalId,
+        });
+    }
+    catch {
+        return { providerCapableStrategies: [], providerError: true };
+    }
+}
+/**
+ * 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 async function executeGovernedMerge(command, approval, workspace, deps, seams) {
+    const now = seams.now ?? Date.now;
+    const snapshot = await readWorktreeSnapshotFor(workspace, seams, now);
+    const adapter = mergeAdapterFor(workspace, seams, now);
+    const packs = seams.policyPacks ?? { repoPack: KEIKO_DEFAULT_MERGE_POLICY_PACK };
+    const newActionId = seams.newActionId ?? (() => defaultGitDeliveryActionId(command, now()));
+    const result = await runGitMerge({ command, approval }, {
+        adapter,
+        snapshot,
+        ...(packs.orgPack !== undefined ? { orgPolicyPack: packs.orgPack } : {}),
+        ...(packs.repoPack !== undefined ? { repoPolicyPack: packs.repoPack } : {}),
+        ...(seams.strategyPolicy !== undefined ? { strategyPolicy: seams.strategyPolicy } : {}),
+        now,
+        newActionId,
+    });
+    persistGitDeliveryEvidence(deps, result.lifecycle, snapshot, workspace.root, now);
+    return result;
+}
+function mergeBlockerView(blocker) {
+    const actionHint = gitMergeBlockerActionHintFor(blocker.code);
+    return {
+        code: blocker.code,
+        severity: blocker.severity,
+        remediation: blocker.remediation,
+        ...(actionHint !== undefined ? { actionHint } : {}),
+    };
+}
+function mergeBlockerViews(summary) {
+    return summary.blockers.map(mergeBlockerView);
+}
+function deriveMergePreviewParts(command, provider, packs, strategyPolicy) {
+    const decision = evaluateGitPolicy(packs.orgPack, packs.repoPack, {
+        actionKind: "merge",
+        targetBranchName: command.baseBranchName,
+        activeProviderCapabilities: [],
+    });
+    const effective = evaluateGitMergeEffectivePolicy(decision, command.baseBranchName, []);
+    const eligibility = deriveEligibleMergeStrategies(command.mergeStrategy, strategyPolicy, provider.providerCapableStrategies);
+    const readiness = gitMergeReadinessFor({
+        ...(provider.pullRequest !== undefined ? { pullRequest: provider.pullRequest } : {}),
+        ...(provider.checks !== undefined ? { checks: provider.checks } : {}),
+        ...(provider.branchProtection !== undefined
+            ? { branchProtection: provider.branchProtection }
+            : {}),
+        strategyEligible: eligibility.requestedEligible,
+        ...(provider.providerError === true ? { providerError: true } : {}),
+    });
+    const requiresApproval = effective.outcome === "approval-gated";
+    return {
+        effectiveOutcome: effective.outcome,
+        ...(effective.blockReason !== undefined ? { blockReason: effective.blockReason } : {}),
+        requiresApproval,
+        eligibleStrategies: eligibility.eligible,
+        ...(eligibility.selectedDefault !== undefined
+            ? { selectedDefaultStrategy: eligibility.selectedDefault }
+            : {}),
+        requestedStrategyEligible: eligibility.requestedEligible,
+        readiness,
+        // The preview has no approval token, so approvalSatisfied is false.
+        recommendation: gitMergeRecommendationFor(readiness, {
+            requiresApproval,
+            approvalSatisfied: false,
+        }),
+    };
+}
+export function buildGitDeliveryMergePreview(command, provider, packs, strategyPolicy) {
+    const parts = deriveMergePreviewParts(command, provider, packs, strategyPolicy);
+    const riskClass = "protected-or-merge";
+    return {
+        schemaVersion: "1",
+        actionKind: "merge",
+        baseBranchName: command.baseBranchName,
+        headBranchName: command.headBranchName,
+        prExternalId: command.prExternalId,
+        riskClass,
+        riskSeverity: GIT_DELIVERY_RISK_CLASS_SEVERITY[riskClass],
+        requestedStrategy: command.mergeStrategy,
+        eligibleStrategies: parts.eligibleStrategies,
+        ...(parts.selectedDefaultStrategy !== undefined
+            ? { selectedDefaultStrategy: parts.selectedDefaultStrategy }
+            : {}),
+        requestedStrategyEligible: parts.requestedStrategyEligible,
+        policyOutcome: parts.effectiveOutcome,
+        ...(parts.blockReason !== undefined ? { policyBlockReason: parts.blockReason } : {}),
+        requiresApproval: parts.requiresApproval,
+        readiness: {
+            mergeable: parts.readiness.mergeable,
+            blockers: mergeBlockerViews(parts.readiness),
+        },
+        recommendation: parts.recommendation,
+    };
+}
+export function gitDeliveryMergeExecuteResponse(result) {
+    const base = gitDeliveryMutationResponse(result.lifecycle);
+    const withReadiness = {
+        ...base,
+        ...(result.readiness !== undefined
+            ? {
+                mergeable: result.readiness.mergeable,
+                readinessBlockers: mergeBlockerViews(result.readiness),
+            }
+            : {}),
+        ...(result.merged !== undefined ? { merged: result.merged } : {}),
+        ...(result.branchDeleted !== undefined ? { branchDeleted: result.branchDeleted } : {}),
+    };
+    if (result.rejection === undefined) {
+        return withReadiness;
+    }
+    return {
+        ...withReadiness,
+        mergeRejectionReason: result.rejection.reason,
+        recoveryDisposition: result.rejection.disposition,
+        ...(result.rejection.actionHint !== undefined
+            ? { recoveryActionHint: result.rejection.actionHint }
+            : {}),
+    };
+}

package/dist/gitDelivery/mergeRoutes.d.ts

@@ -0,0 +1,12 @@
+import type { RouteContext, RouteDefinition, RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+import { type GitDeliveryMergeSeams } from "./mergeExecution.js";
+export type GitDeliveryMergeErrorCode = "GIT_DELIVERY_MERGE_BAD_REQUEST" | "GIT_DELIVERY_MERGE_PAYLOAD_TOO_LARGE" | "GIT_DELIVERY_MERGE_FORBIDDEN_PAYLOAD" | "GIT_DELIVERY_MERGE_UNKNOWN_PROJECT" | "GIT_DELIVERY_MERGE_WORKTREE_UNAVAILABLE";
+export interface GitDeliveryMergeRouteOptions {
+    readonly execution?: GitDeliveryMergeSeams;
+}
+export declare const createHandleMergePreview: (options?: GitDeliveryMergeRouteOptions) => ((ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>);
+export declare const createHandleMergeExecute: (options?: GitDeliveryMergeRouteOptions) => ((ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>);
+export declare const createGitDeliveryMergeRouteGroup: (options?: GitDeliveryMergeRouteOptions) => readonly RouteDefinition[];
+export declare const GIT_DELIVERY_MERGE_ROUTE_GROUP: readonly RouteDefinition[];
+//# sourceMappingURL=mergeRoutes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mergeRoutes.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/mergeRoutes.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAML,KAAK,qBAAqB,EAC3B,MAAM,qBAAqB,CAAC;AAa7B,MAAM,MAAM,yBAAyB,GACjC,gCAAgC,GAChC,sCAAsC,GACtC,sCAAsC,GACtC,oCAAoC,GACpC,yCAAyC,CAAC;AAmB9C,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,SAAS,CAAC,EAAE,qBAAqB,CAAC;CAC5C;AA+ID,eAAO,MAAM,wBAAwB,GACnC,UAAS,4BAAiC,KACzC,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAqBnE,CAAC;AAIF,eAAO,MAAM,wBAAwB,GACnC,UAAS,4BAAiC,KACzC,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAmBnE,CAAC;AAIF,eAAO,MAAM,gCAAgC,GAC3C,UAAS,4BAAiC,KACzC,SAAS,eAAe,EAW1B,CAAC;AAEF,eAAO,MAAM,8BAA8B,EAAE,SAAS,eAAe,EACjC,CAAC"}

package/dist/gitDelivery/mergeRoutes.js

@@ -0,0 +1,218 @@
+// Governed merge routes (Issue #478, Epic #470, ADR-0065).
+//
+//   * POST /api/git-delivery/merge/preview  — READ-ONLY. Reads the provider's content-free merge-readiness
+//       facts and builds the pre-merge context: the readiness summary (mergeable + severity-ranked
+//       blockers), the eligible merge strategies (policy ∩ provider capability — never a hard-coded UI
+//       default), the recommendation, the effective policy decision, and whether final approval is
+//       required. Never mutates, never records evidence.
+//   * POST /api/git-delivery/merge/execute  — Governed. Drives the #478 merge gateway end-to-end through
+//       executeGovernedMerge (preflight + policy + final-approval + the readiness gate + the dedicated
+//       `gh api` merge adapter) and appends content-free evidence for the allowed AND blocked outcome
+//       alike. Returns the typed provider-rejection reason + reused recovery hint and the merged /
+//       branch-deleted flags.
+//
+// Content-free in evidence: only the merge inputs (PR number, strategy, delete flag) and outcome enter the
+// ledger. CSRF + JSON content type are enforced centrally by server.ts.
+import { isGitDeliveryApprovalRequirement, isGitDeliveryMergeStrategyHint, } from "@oscharko-dev/keiko-contracts";
+import { resolveProjectWorkspace } from "./execution.js";
+import { buildGitDeliveryMergePreview, executeGovernedMerge, gitDeliveryMergeExecuteResponse, KEIKO_DEFAULT_MERGE_POLICY_PACK, readMergeProviderReadiness, } from "./mergeExecution.js";
+import { GitDeliveryBodyTooLargeError, hasOnlyAllowedKeys, isNonEmptyString, isPlainObject, readGitDeliveryBody, scanForbiddenStrings, scanUnsafeFormatChars, } from "./requestGuards.js";
+const SAFE_MESSAGES = {
+    GIT_DELIVERY_MERGE_BAD_REQUEST: "The request body is not a valid governed merge.",
+    GIT_DELIVERY_MERGE_PAYLOAD_TOO_LARGE: "The governed merge request exceeds the maximum size.",
+    GIT_DELIVERY_MERGE_FORBIDDEN_PAYLOAD: "The request contained a forbidden field. Requests may not carry credentials or auth headers.",
+    GIT_DELIVERY_MERGE_UNKNOWN_PROJECT: "The requested project is not a known workspace.",
+    GIT_DELIVERY_MERGE_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] } },
+});
+async function readParsed(req) {
+    let raw;
+    try {
+        raw = await readGitDeliveryBody(req);
+    }
+    catch (error) {
+        const result = error instanceof GitDeliveryBodyTooLargeError
+            ? errResult(413, "GIT_DELIVERY_MERGE_PAYLOAD_TOO_LARGE")
+            : errResult(400, "GIT_DELIVERY_MERGE_BAD_REQUEST");
+        return { ok: false, result };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_MERGE_BAD_REQUEST") };
+    }
+}
+// A git ref operand: non-empty, no whitespace, no leading "-" (flag-injection guard), no NUL/control.
+// eslint-disable-next-line no-control-regex -- intentionally matches control chars to REJECT them
+const REF_CONTROL_CHAR = new RegExp("[\u0000-\u001f\u007f]");
+function isSafeGitRef(value) {
+    if (typeof value !== "string" || value.length === 0)
+        return false;
+    if (/\s/.test(value))
+        return false;
+    if (value.startsWith("-"))
+        return false;
+    if (REF_CONTROL_CHAR.test(value))
+        return false;
+    if (value.includes(":"))
+        return false;
+    return true;
+}
+const OWNER_REPO_RE = /^[A-Za-z0-9._-]+\/[A-Za-z0-9._-]+$/;
+const PR_NUMBER_RE = /^[1-9][0-9]{0,9}$/;
+const SHA_RE = /^[0-9a-fA-F]{7,64}$/;
+function isOwnerAndRepo(value) {
+    return typeof value === "string" && OWNER_REPO_RE.test(value);
+}
+function isPrNumberString(value) {
+    return typeof value === "string" && PR_NUMBER_RE.test(value);
+}
+const ALLOWED_KEYS = new Set([
+    "schemaVersion",
+    "projectId",
+    "kind",
+    "ownerAndRepo",
+    "prExternalId",
+    "baseBranchName",
+    "headBranchName",
+    "mergeStrategy",
+    "deleteBranchAfterMerge",
+    "expectedHeadRefHash",
+    "approval",
+]);
+const NO_APPROVAL = { required: false };
+function parseApproval(value) {
+    if (value === undefined)
+        return NO_APPROVAL;
+    return isGitDeliveryApprovalRequirement(value) ? value : undefined;
+}
+function optionalBool(value) {
+    if (value === undefined)
+        return false;
+    return typeof value === "boolean" ? value : undefined;
+}
+function parseExpectedHeadRefHash(value) {
+    if (value === undefined)
+        return { ok: true };
+    if (typeof value === "string" && SHA_RE.test(value))
+        return { ok: true, value };
+    return { ok: false };
+}
+function scanError(parsed) {
+    if (scanForbiddenStrings(parsed)) {
+        return errResult(400, "GIT_DELIVERY_MERGE_FORBIDDEN_PAYLOAD");
+    }
+    if (scanUnsafeFormatChars(parsed)) {
+        return errResult(400, "GIT_DELIVERY_MERGE_BAD_REQUEST");
+    }
+    return undefined;
+}
+function buildMergeCommand(parsed) {
+    if (parsed.kind !== "merge" ||
+        !isOwnerAndRepo(parsed.ownerAndRepo) ||
+        !isPrNumberString(parsed.prExternalId) ||
+        !isSafeGitRef(parsed.baseBranchName) ||
+        !isSafeGitRef(parsed.headBranchName) ||
+        !isGitDeliveryMergeStrategyHint(parsed.mergeStrategy)) {
+        return undefined;
+    }
+    const deleteBranchAfterMerge = optionalBool(parsed.deleteBranchAfterMerge);
+    const expectedHead = parseExpectedHeadRefHash(parsed.expectedHeadRefHash);
+    if (deleteBranchAfterMerge === undefined || !expectedHead.ok) {
+        return undefined;
+    }
+    return {
+        kind: "merge",
+        ownerAndRepo: parsed.ownerAndRepo,
+        prExternalId: parsed.prExternalId,
+        baseBranchName: parsed.baseBranchName,
+        headBranchName: parsed.headBranchName,
+        mergeStrategy: parsed.mergeStrategy,
+        deleteBranchAfterMerge,
+        ...(expectedHead.value !== undefined ? { expectedHeadRefHash: expectedHead.value } : {}),
+    };
+}
+function validate(parsed) {
+    const bad = { kind: "err", result: errResult(400, "GIT_DELIVERY_MERGE_BAD_REQUEST") };
+    if (!isPlainObject(parsed) || !hasOnlyAllowedKeys(parsed, ALLOWED_KEYS))
+        return bad;
+    if (parsed.schemaVersion !== "1" || !isNonEmptyString(parsed.projectId))
+        return bad;
+    const scanErr = scanError(parsed);
+    if (scanErr !== undefined)
+        return { kind: "err", result: scanErr };
+    const command = buildMergeCommand(parsed);
+    const approval = parseApproval(parsed.approval);
+    if (command === undefined || approval === undefined)
+        return bad;
+    return { kind: "ok", value: { projectId: parsed.projectId, command, approval } };
+}
+// ─── Preview handler (read-only) ────────────────────────────────────────────────────────────────
+export const createHandleMergePreview = (options = {}) => {
+    const seams = options.execution ?? {};
+    const now = () => (seams.now ?? Date.now)();
+    return async (ctx, deps) => {
+        const read = await readParsed(ctx.req);
+        if (!read.ok)
+            return read.result;
+        const validation = validate(read.value);
+        if (validation.kind === "err")
+            return validation.result;
+        const { projectId, command } = validation.value;
+        const workspace = resolveProjectWorkspace(deps, projectId);
+        if (workspace === undefined)
+            return errResult(404, "GIT_DELIVERY_MERGE_UNKNOWN_PROJECT");
+        const packs = seams.policyPacks ?? { repoPack: KEIKO_DEFAULT_MERGE_POLICY_PACK };
+        const strategyPolicy = seams.strategyPolicy ?? {
+            allowedStrategies: ["squash", "rebase", "merge-commit", "provider-default"],
+        };
+        const provider = await readMergeProviderReadiness(command, workspace, seams, now);
+        return {
+            status: 200,
+            body: deps.redactor(buildGitDeliveryMergePreview(command, provider, packs, strategyPolicy)),
+        };
+    };
+};
+// ─── Execute handler (governed) ───────────────────────────────────────────────────────────────
+export const createHandleMergeExecute = (options = {}) => {
+    const seams = options.execution ?? {};
+    return async (ctx, deps) => {
+        const read = await readParsed(ctx.req);
+        if (!read.ok)
+            return read.result;
+        const validation = validate(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_MERGE_UNKNOWN_PROJECT");
+        let result;
+        try {
+            result = await executeGovernedMerge(command, approval, workspace, deps, seams);
+        }
+        catch {
+            // Only the read-only snapshot step can throw (not a git repository); the gateway never throws.
+            return errResult(409, "GIT_DELIVERY_MERGE_WORKTREE_UNAVAILABLE");
+        }
+        return { status: 200, body: deps.redactor(gitDeliveryMergeExecuteResponse(result)) };
+    };
+};
+// ─── Route group ───────────────────────────────────────────────────────────────────────────────
+export const createGitDeliveryMergeRouteGroup = (options = {}) => [
+    {
+        method: "POST",
+        pattern: "/api/git-delivery/merge/preview",
+        handler: createHandleMergePreview(options),
+    },
+    {
+        method: "POST",
+        pattern: "/api/git-delivery/merge/execute",
+        handler: createHandleMergeExecute(options),
+    },
+];
+export const GIT_DELIVERY_MERGE_ROUTE_GROUP = createGitDeliveryMergeRouteGroup();

package/dist/gitDelivery/mutationEvidenceLedger.d.ts

@@ -0,0 +1,23 @@
+import type { GitDeliveryEvidenceRecord } from "@oscharko-dev/keiko-contracts";
+import { GIT_DELIVERY_EVIDENCE_SCHEMA_VERSION } from "@oscharko-dev/keiko-contracts";
+import type { EvidenceStore } from "@oscharko-dev/keiko-evidence";
+export declare const GIT_DELIVERY_EVIDENCE_RUNID_PREFIX: "git-delivery-evidence-";
+export declare const GIT_DELIVERY_EVIDENCE_DEFAULT_BUCKET_CAP = 500;
+export interface GitDeliveryEvidenceLedgerDoc {
+    readonly schemaVersion: typeof GIT_DELIVERY_EVIDENCE_SCHEMA_VERSION;
+    readonly records: readonly GitDeliveryEvidenceRecord[];
+}
+export declare function gitDeliveryEvidenceRunIdFor(nowMs: number): string;
+export interface RecordGitDeliveryEvidenceOptions {
+    readonly evidenceStore: EvidenceStore;
+    readonly redactString: (input: string) => string;
+    readonly maxRecordsPerBucket?: number | undefined;
+    readonly onPersistError?: ((error: unknown) => void) | undefined;
+}
+/**
+ * Appends one governed Git mutation evidence record to its date-bucketed ledger. Redacts every string
+ * leaf, bounds the bucket, and never throws into the caller's path. Returns nothing — audit recording
+ * is best-effort and is reported (not propagated) on failure.
+ */
+export declare function recordGitDeliveryMutationEvidence(options: RecordGitDeliveryEvidenceOptions, record: GitDeliveryEvidenceRecord): void;
+//# sourceMappingURL=mutationEvidenceLedger.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mutationEvidenceLedger.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/mutationEvidenceLedger.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,+BAA+B,CAAC;AAC/E,OAAO,EAAE,oCAAoC,EAAE,MAAM,+BAA+B,CAAC;AAErF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAElE,eAAO,MAAM,kCAAkC,EAAG,wBAAiC,CAAC;AAGpF,eAAO,MAAM,wCAAwC,MAAM,CAAC;AAE5D,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,aAAa,EAAE,OAAO,oCAAoC,CAAC;IACpE,QAAQ,CAAC,OAAO,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACxD;AAID,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAGjE;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IAGtC,QAAQ,CAAC,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;IACjD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAElD,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC;CAClE;AA6DD;;;;GAIG;AACH,wBAAgB,iCAAiC,CAC/C,OAAO,EAAE,gCAAgC,EACzC,MAAM,EAAE,yBAAyB,GAChC,IAAI,CAUN"}

package/dist/gitDelivery/mutationEvidenceLedger.js

@@ -0,0 +1,87 @@
+// Governed Git mutation EVIDENCE ledger (Issue #474, Epic #470).
+//
+// The durable, bounded, append-only sink the #472 orchestrator's idempotency-journal comment
+// anticipates ("a durable journal — the evidence ledger, #474"). It records the content-free
+// GitDeliveryEvidenceRecord produced by the keiko-tools builder for EVERY terminal outcome of a
+// governed Git mutation — succeeded, blocked, rejected, failed, recovery-required, or held for
+// approval — so a governance decision is auditable even when no mutation executed.
+//
+// Persistence shape: ONE ledger document per UTC date bucket (runId `git-delivery-evidence-YYYY-MM-DD`),
+// mirroring memory-audit-handler.ts. Stores that expose EvidenceStore.update() serialize the
+// read-append-write step so concurrent appenders never drop a record; stores without it fall back to
+// get+put. The bucket is bounded to the most recent N records so a long-lived ledger cannot grow
+// without limit.
+//
+// Redaction: each record is run through deepRedactStrings before it is serialized (defence-in-depth on
+// top of the builder's by-construction content-free hashing). Persistence failures are caught and
+// reported through an injectable sink; an audit-write failure must NEVER break the user's mutation.
+// Corrupt ledger documents are never reset or overwritten — an append against a corrupt bucket fails
+// closed and preserves the existing artifact for operator investigation.
+import { GIT_DELIVERY_EVIDENCE_SCHEMA_VERSION } from "@oscharko-dev/keiko-contracts";
+import { deepRedactStrings } from "@oscharko-dev/keiko-evidence";
+export const GIT_DELIVERY_EVIDENCE_RUNID_PREFIX = "git-delivery-evidence-";
+// Default bound on records retained per UTC date bucket. The most recent records are kept.
+export const GIT_DELIVERY_EVIDENCE_DEFAULT_BUCKET_CAP = 500;
+// UTC date-bucket runId. 22 chars (`git-delivery-evidence-` is 22) + 10 (`YYYY-MM-DD`) = 32, well
+// under the evidence-store run-id length cap.
+export function gitDeliveryEvidenceRunIdFor(nowMs) {
+    const iso = new Date(nowMs).toISOString();
+    return `${GIT_DELIVERY_EVIDENCE_RUNID_PREFIX}${iso.slice(0, 10)}`;
+}
+function defaultOnPersistError(error) {
+    // eslint-disable-next-line no-console
+    console.error("git-delivery evidence ledger: persistence failed", error);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// Parses an existing bucket document. Returns the records faithfully (they were written valid).
+// Throws on gross corruption so the caller fails closed and preserves the artifact.
+function parseExistingRecords(json) {
+    if (json === undefined) {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch (error) {
+        throw new Error("git-delivery evidence ledger is corrupt; refusing to overwrite existing audit evidence", { cause: error });
+    }
+    if (!isPlainObject(parsed) || !Array.isArray(parsed.records)) {
+        throw new Error("git-delivery evidence ledger has an unexpected shape; refusing to overwrite existing audit evidence");
+    }
+    return parsed.records;
+}
+function boundedDoc(existing, record, cap) {
+    const records = [...existing, record];
+    return {
+        schemaVersion: GIT_DELIVERY_EVIDENCE_SCHEMA_VERSION,
+        records: cap > 0 && records.length > cap ? records.slice(records.length - cap) : records,
+    };
+}
+function appendRecord(store, runId, record, cap) {
+    const append = (existingJson) => JSON.stringify(boundedDoc(parseExistingRecords(existingJson), record, cap));
+    if (store.update !== undefined) {
+        store.update(runId, append);
+        return;
+    }
+    store.put(runId, append(store.get(runId)));
+}
+/**
+ * Appends one governed Git mutation evidence record to its date-bucketed ledger. Redacts every string
+ * leaf, bounds the bucket, and never throws into the caller's path. Returns nothing — audit recording
+ * is best-effort and is reported (not propagated) on failure.
+ */
+export function recordGitDeliveryMutationEvidence(options, record) {
+    const onPersistError = options.onPersistError ?? defaultOnPersistError;
+    const cap = options.maxRecordsPerBucket ?? GIT_DELIVERY_EVIDENCE_DEFAULT_BUCKET_CAP;
+    const safe = deepRedactStrings(record, options.redactString);
+    const runId = gitDeliveryEvidenceRunIdFor(record.recordedAtMs);
+    try {
+        appendRecord(options.evidenceStore, runId, safe, cap);
+    }
+    catch (error) {
+        onPersistError(error);
+    }
+}

package/dist/gitDelivery/prExecution.d.ts

@@ -0,0 +1,54 @@
+import type { WorkspaceInfo } from "@oscharko-dev/keiko-workspace";
+import { type GitDeliveryApprovalRequirement, type GitDeliveryRepoPolicyPack, type GitDeliveryRiskClass } from "@oscharko-dev/keiko-contracts";
+import { type GitPullRequestAdapter, type GitPullRequestCommand, type GitPullRequestLifecycleResult, 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_PR_POLICY_PACK: GitDeliveryRepoPolicyPack;
+export interface GitDeliveryPullRequestSeams {
+    readonly prAdapterFactory?: ((workspace: WorkspaceInfo) => GitPullRequestAdapter) | undefined;
+    readonly snapshotReader?: ((workspace: WorkspaceInfo) => Promise<GitWorktreeSnapshot>) | undefined;
+    readonly policyPacks?: GitDeliveryTrustedPolicyPacks | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly newActionId?: (() => string) | undefined;
+}
+/**
+ * Runs ONE governed PR operation end-to-end: live snapshot → PR gateway (preflight + policy + approval +
+ * 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 executeGovernedPullRequest(command: GitPullRequestCommand, approval: GitDeliveryApprovalRequirement, workspace: WorkspaceInfo, deps: Pick<UiHandlerDeps, "evidenceStore" | "redactor">, seams: GitDeliveryPullRequestSeams): Promise<GitPullRequestLifecycleResult>;
+export interface GitDeliveryPrReadinessBody {
+    readonly objectExists: boolean;
+    readonly reviewReady: boolean;
+    readonly blockerCodes: readonly string[];
+}
+export interface GitDeliveryPrPreviewBody {
+    readonly schemaVersion: "1";
+    readonly actionKind: "pr-create" | "pr-update";
+    readonly headBranchName: string;
+    readonly baseBranchName: string;
+    readonly riskClass: GitDeliveryRiskClass;
+    readonly riskSeverity: number;
+    readonly isDraft: boolean;
+    readonly policyOutcome: string;
+    readonly policyBlockReason?: string;
+    readonly composedTitle: string;
+    readonly composedBody: string;
+    readonly riskNarrative: string;
+    readonly recommendation: string;
+    readonly readiness: GitDeliveryPrReadinessBody;
+    readonly suggestedLabels: readonly string[];
+    readonly suggestedIssueRefs: readonly string[];
+    readonly titleByteLength: number;
+    readonly bodyByteLength: number;
+}
+export declare function buildGitDeliveryPrPreview(command: GitPullRequestCommand, snapshot: GitWorktreeSnapshot, packs: GitDeliveryTrustedPolicyPacks): GitDeliveryPrPreviewBody;
+export interface GitDeliveryPrExecuteResponseBody extends GitDeliveryMutationResponseBody {
+    readonly prRejectionReason?: string;
+    readonly recoveryDisposition?: string;
+    readonly recoveryActionHint?: string;
+    readonly createdPrExternalId?: string;
+}
+export declare function gitDeliveryPrExecuteResponse(result: GitPullRequestLifecycleResult): GitDeliveryPrExecuteResponseBody;
+//# sourceMappingURL=prExecution.d.ts.map

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

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