@oscharko-dev/keiko-server 0.2.8 → 0.2.9

package/dist/gitDelivery/prExecution.js

@@ -0,0 +1,192 @@
+// Governed GitHub pull request execution core for the #477 PR routes (Epic #470, ADR-0064).
+//
+// The PR preview + execute routes share ONE path: resolve and authorize the project workspace, build a
+// TRUSTWORTHY snapshot from the live worktree, drive the #477 PR gateway `runGitPullRequest` (the
+// SEPARATE PR-orchestration authority — preflight + policy + approval gates, executing through a narrow
+// `gh api` adapter with a dedicated PR-only allowlist), and append a content-free evidence record
+// through the #474 ledger for EVERY terminal outcome (allowed and blocked alike — AC5). No second
+// orchestrator, no generic shell, no widening of the local mutation or read-only inspection allowlists.
+// The Node `gh api` effect is injected via seams so route tests run deterministically against a fake.
+import { GIT_DELIVERY_POLICY_SCHEMA_VERSION, GIT_DELIVERY_RISK_CLASS_SEVERITY, evaluateGitPolicy, gitPullRequestLabelSuggestionsFor, gitPullRequestLinkageSuggestionsFor, gitPullRequestReadinessFor, gitPullRequestRecommendationFor, synthesizePullRequestMetadata, } from "@oscharko-dev/keiko-contracts";
+import { evaluateGitPullRequestEffectivePolicy, runGitPullRequest, } from "@oscharko-dev/keiko-tools";
+import { createNodeGitPullRequestAdapter } from "@oscharko-dev/keiko-tools/internal/git-mutation";
+import { defaultGitDeliveryActionId, gitDeliveryMutationResponse, persistGitDeliveryEvidence, readWorktreeSnapshotFor, } from "./execution.js";
+// Default trusted PR policy: PERMIT `pr-create` / `pr-update` whose BASE is a legitimate integration
+// branch (dev, main, release/*, feat/*) and only within the protected-or-merge ceiling. A base outside
+// this allow-list is blocked with `policy-pack-blocked`. Opening a PR TO a protected base is a governed,
+// normal operation (unlike a direct push to one, which the #476 publish pack blocks). Per-target
+// approval escalation is a deployment override (an `approval-gated` rule); the gateway supports it but
+// the default keeps PR creation reviewable-by-default with merge-approval deferred to #478. Applies only
+// when governed git delivery is ENABLED and no stricter pack is configured; still EVALUATED every time.
+const PR_BASE_CONSTRAINTS = [
+    { kind: "risk-class-ceiling", maxRiskClass: "protected-or-merge" },
+    {
+        kind: "branch-pattern",
+        patterns: [
+            { matchKind: "exact", value: "dev" },
+            { matchKind: "exact", value: "main" },
+            { matchKind: "prefix", value: "release/" },
+            { matchKind: "prefix", value: "feat/" },
+        ],
+    },
+];
+export const KEIKO_DEFAULT_PR_POLICY_PACK = {
+    schemaVersion: GIT_DELIVERY_POLICY_SCHEMA_VERSION,
+    repoId: "keiko-pr-default",
+    rules: [
+        { actionKind: "pr-create", decision: "constrained", constraints: [...PR_BASE_CONSTRAINTS] },
+        { actionKind: "pr-update", decision: "constrained", constraints: [...PR_BASE_CONSTRAINTS] },
+    ],
+    defaultRule: { decision: "blocked" },
+};
+function prAdapterFor(workspace, seams, now) {
+    if (seams.prAdapterFactory !== undefined)
+        return seams.prAdapterFactory(workspace);
+    return createNodeGitPullRequestAdapter({ workspace, processEnv: process.env, now });
+}
+/**
+ * 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 async function executeGovernedPullRequest(command, approval, workspace, deps, seams) {
+    const now = seams.now ?? Date.now;
+    const snapshot = await readWorktreeSnapshotFor(workspace, seams, now);
+    const adapter = prAdapterFor(workspace, seams, now);
+    const packs = seams.policyPacks ?? { repoPack: KEIKO_DEFAULT_PR_POLICY_PACK };
+    const newActionId = seams.newActionId ?? (() => defaultGitDeliveryActionId(command, now()));
+    const result = await runGitPullRequest({ command, approval }, {
+        adapter,
+        snapshot,
+        ...(packs.orgPack !== undefined ? { orgPolicyPack: packs.orgPack } : {}),
+        ...(packs.repoPack !== undefined ? { repoPolicyPack: packs.repoPack } : {}),
+        now,
+        newActionId,
+    });
+    persistGitDeliveryEvidence(deps, result.lifecycle, snapshot, workspace.root, now);
+    return result;
+}
+// ─── Deterministic change-narrative derivation (content-free) ─────────────────────────────────────
+const CHANGE_TYPE_BY_PREFIX = {
+    fix: "fix",
+    feat: "feat",
+    docs: "docs",
+    chore: "chore",
+    test: "test",
+    refactor: "refactor",
+};
+function changeTypeFromBranch(headBranch) {
+    const segments = headBranch.split("/");
+    const lead = (segments[0] ?? "").toLowerCase();
+    return CHANGE_TYPE_BY_PREFIX[lead] ?? "feat";
+}
+// A best-effort, content-free narrative from the live snapshot: commit count proxied by the ahead-count,
+// file count by the working-tree counts, change type inferred from the head-branch namespace. Area tokens
+// are intentionally empty here (the snapshot carries no diff paths); the title falls back to the branch
+// slug, which is the actual, user-meaningful context.
+function narrativeFromSnapshot(headBranch, snapshot) {
+    return {
+        commitCount: Math.max(snapshot.aheadCount, 1),
+        fileCount: snapshot.stagedFileCount + snapshot.unstagedFileCount + snapshot.untrackedFileCount,
+        areaCount: 0,
+        areas: [],
+        touchesTests: false,
+        changeType: changeTypeFromBranch(headBranch),
+    };
+}
+function commandTitle(command) {
+    return command.title;
+}
+function commandBody(command) {
+    return command.body;
+}
+const UTF8 = new TextEncoder();
+function riskDigestFor(command, policyOutcome) {
+    const riskClass = "protected-or-merge";
+    return {
+        riskClass,
+        riskSeverity: GIT_DELIVERY_RISK_CLASS_SEVERITY[riskClass],
+        policyOutcome,
+        isDraft: command.kind === "pr-create" ? command.isDraft : command.convertToDraft,
+    };
+}
+function previewReadiness(command, snapshot) {
+    return gitPullRequestReadinessFor({
+        headBranchName: command.headBranchName,
+        baseBranchName: command.baseBranchName,
+        // A PR can only be opened from a published head; the current branch's upstream is the proxy.
+        headPublished: snapshot.hasUpstream,
+        baseExists: true,
+    });
+}
+// Assembles an editable Markdown body seed from the synthesized draft + linkage refs.
+function composeBody(draft, issueRefs) {
+    const linkage = issueRefs.length > 0 ? `\n\n## Linked issues\nRefs ${issueRefs.join(", ")}` : "";
+    return `## Summary\n${draft.composedTitle}\n\n## Risk\n${draft.riskNarrative}${linkage}`;
+}
+function derivePrPreviewParts(command, snapshot, packs) {
+    const decision = evaluateGitPolicy(packs.orgPack, packs.repoPack, {
+        actionKind: command.kind,
+        targetBranchName: command.baseBranchName,
+        activeProviderCapabilities: [],
+    });
+    const effective = evaluateGitPullRequestEffectivePolicy(decision, command.baseBranchName, [], command.kind);
+    const narrative = narrativeFromSnapshot(command.headBranchName, snapshot);
+    const riskDigest = riskDigestFor(command, effective.outcome);
+    const draft = synthesizePullRequestMetadata(narrative, riskDigest, command.headBranchName, command.baseBranchName);
+    const readiness = previewReadiness(command, snapshot);
+    return {
+        effectiveOutcome: effective.outcome,
+        ...(effective.blockReason !== undefined ? { blockReason: effective.blockReason } : {}),
+        riskDigest,
+        draft,
+        readiness,
+        recommendation: gitPullRequestRecommendationFor(readiness, riskDigest),
+        labels: gitPullRequestLabelSuggestionsFor(narrative).suggestedLabelNames,
+        linkage: gitPullRequestLinkageSuggestionsFor(command.headBranchName).suggestedIssueRefs,
+    };
+}
+export function buildGitDeliveryPrPreview(command, snapshot, packs) {
+    const parts = derivePrPreviewParts(command, snapshot, packs);
+    return {
+        schemaVersion: "1",
+        actionKind: command.kind,
+        headBranchName: command.headBranchName,
+        baseBranchName: command.baseBranchName,
+        riskClass: parts.riskDigest.riskClass,
+        riskSeverity: parts.riskDigest.riskSeverity,
+        isDraft: parts.riskDigest.isDraft,
+        policyOutcome: parts.effectiveOutcome,
+        ...(parts.blockReason !== undefined ? { policyBlockReason: parts.blockReason } : {}),
+        composedTitle: parts.draft.composedTitle,
+        composedBody: composeBody(parts.draft, parts.linkage),
+        riskNarrative: parts.draft.riskNarrative,
+        recommendation: parts.recommendation,
+        readiness: {
+            objectExists: parts.readiness.objectExists,
+            reviewReady: parts.readiness.reviewReady,
+            blockerCodes: parts.readiness.blockers.map((b) => b.code),
+        },
+        suggestedLabels: parts.labels,
+        suggestedIssueRefs: parts.linkage,
+        titleByteLength: UTF8.encode(commandTitle(command)).length,
+        bodyByteLength: UTF8.encode(commandBody(command)).length,
+    };
+}
+export function gitDeliveryPrExecuteResponse(result) {
+    const base = gitDeliveryMutationResponse(result.lifecycle);
+    const withId = result.createdPrExternalId !== undefined
+        ? { ...base, createdPrExternalId: result.createdPrExternalId }
+        : base;
+    if (result.rejection === undefined) {
+        return withId;
+    }
+    return {
+        ...withId,
+        prRejectionReason: result.rejection.reason,
+        recoveryDisposition: result.rejection.disposition,
+        ...(result.rejection.actionHint !== undefined
+            ? { recoveryActionHint: result.rejection.actionHint }
+            : {}),
+    };
+}

package/dist/gitDelivery/prRoutes.d.ts

@@ -0,0 +1,12 @@
+import type { RouteContext, RouteDefinition, RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+import { type GitDeliveryPullRequestSeams } from "./prExecution.js";
+export type GitDeliveryPrErrorCode = "GIT_DELIVERY_PR_BAD_REQUEST" | "GIT_DELIVERY_PR_PAYLOAD_TOO_LARGE" | "GIT_DELIVERY_PR_FORBIDDEN_PAYLOAD" | "GIT_DELIVERY_PR_UNKNOWN_PROJECT" | "GIT_DELIVERY_PR_WORKTREE_UNAVAILABLE";
+export interface GitDeliveryPrRouteOptions {
+    readonly execution?: GitDeliveryPullRequestSeams;
+}
+export declare const createHandlePrPreview: (options?: GitDeliveryPrRouteOptions) => ((ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>);
+export declare const createHandlePrExecute: (options?: GitDeliveryPrRouteOptions) => ((ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>);
+export declare const createGitDeliveryPrRouteGroup: (options?: GitDeliveryPrRouteOptions) => readonly RouteDefinition[];
+export declare const GIT_DELIVERY_PR_ROUTE_GROUP: readonly RouteDefinition[];
+//# sourceMappingURL=prRoutes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prRoutes.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/prRoutes.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAKL,KAAK,2BAA2B,EACjC,MAAM,kBAAkB,CAAC;AAa1B,MAAM,MAAM,sBAAsB,GAC9B,6BAA6B,GAC7B,mCAAmC,GACnC,mCAAmC,GACnC,iCAAiC,GACjC,sCAAsC,CAAC;AAmB3C,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,2BAA2B,CAAC;CAClD;AAmMD,eAAO,MAAM,qBAAqB,GAChC,UAAS,yBAA8B,KACtC,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAsBnE,CAAC;AAIF,eAAO,MAAM,qBAAqB,GAChC,UAAS,yBAA8B,KACtC,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAmBnE,CAAC;AAIF,eAAO,MAAM,6BAA6B,GACxC,UAAS,yBAA8B,KACtC,SAAS,eAAe,EAW1B,CAAC;AAEF,eAAO,MAAM,2BAA2B,EAAE,SAAS,eAAe,EACjC,CAAC"}

package/dist/gitDelivery/prRoutes.js

@@ -0,0 +1,256 @@
+// Governed GitHub pull request routes (Issue #477, Epic #470, ADR-0064).
+//
+//   * POST /api/git-delivery/pr/preview  — READ-ONLY. Builds the pre-create context: the synthesized,
+//       user-editable metadata draft (title/body/risk narrative), the readiness summary (objectExists vs
+//       reviewReady) with structured blockers, the draft-vs-ready recommendation, the reviewer/label/
+//       linkage suggestions, and the effective policy decision. Never mutates, never records evidence.
+//   * POST /api/git-delivery/pr/execute  — Governed. Drives the #477 PR gateway end-to-end through
+//       executeGovernedPullRequest (preflight + policy + approval + the dedicated `gh api` adapter) and
+//       appends content-free evidence for the allowed AND blocked outcome alike. Returns the typed
+//       provider-rejection reason + reused recovery hint so a rejected operation recovers without
+//       guessing, and the provider-assigned PR number on a successful create.
+//
+// Content-free in evidence: title/body strings flow to the provider but only their byte lengths enter
+// the ledger. CSRF + JSON content type are enforced centrally by server.ts.
+import { isGitDeliveryApprovalRequirement, } from "@oscharko-dev/keiko-contracts";
+import { readWorktreeSnapshotFor, resolveProjectWorkspace } from "./execution.js";
+import { buildGitDeliveryPrPreview, executeGovernedPullRequest, gitDeliveryPrExecuteResponse, KEIKO_DEFAULT_PR_POLICY_PACK, } from "./prExecution.js";
+import { GitDeliveryBodyTooLargeError, hasOnlyAllowedKeys, isNonEmptyString, isPlainObject, readGitDeliveryBody, scanForbiddenStrings, scanUnsafeFormatChars, } from "./requestGuards.js";
+const SAFE_MESSAGES = {
+    GIT_DELIVERY_PR_BAD_REQUEST: "The request body is not a valid governed pull request.",
+    GIT_DELIVERY_PR_PAYLOAD_TOO_LARGE: "The governed pull request request exceeds the maximum size.",
+    GIT_DELIVERY_PR_FORBIDDEN_PAYLOAD: "The request contained a forbidden field. Requests may not carry credentials or auth headers.",
+    GIT_DELIVERY_PR_UNKNOWN_PROJECT: "The requested project is not a known workspace.",
+    GIT_DELIVERY_PR_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_PR_PAYLOAD_TOO_LARGE")
+            : errResult(400, "GIT_DELIVERY_PR_BAD_REQUEST");
+        return { ok: false, result };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_PR_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}$/;
+function isOwnerAndRepo(value) {
+    return typeof value === "string" && OWNER_REPO_RE.test(value);
+}
+const ALLOWED_KEYS = new Set([
+    "schemaVersion",
+    "projectId",
+    "kind",
+    "ownerAndRepo",
+    "headBranchName",
+    "baseBranchName",
+    "title",
+    "body",
+    "isDraft",
+    "prExternalId",
+    "convertToDraft",
+    "convertFromDraft",
+    "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 isBodyString(value) {
+    // A PR body may be empty; it must still be a string.
+    return typeof value === "string";
+}
+function scanError(parsed) {
+    if (scanForbiddenStrings(parsed)) {
+        return errResult(400, "GIT_DELIVERY_PR_FORBIDDEN_PAYLOAD");
+    }
+    if (scanUnsafeFormatChars(parsed)) {
+        return errResult(400, "GIT_DELIVERY_PR_BAD_REQUEST");
+    }
+    return undefined;
+}
+function buildCreateCommand(parsed) {
+    if (!isOwnerAndRepo(parsed.ownerAndRepo) ||
+        !isSafeGitRef(parsed.headBranchName) ||
+        !isSafeGitRef(parsed.baseBranchName) ||
+        !isNonEmptyString(parsed.title) ||
+        !isBodyString(parsed.body)) {
+        return undefined;
+    }
+    const isDraft = optionalBool(parsed.isDraft);
+    if (isDraft === undefined)
+        return undefined;
+    return {
+        kind: "pr-create",
+        ownerAndRepo: parsed.ownerAndRepo,
+        headBranchName: parsed.headBranchName,
+        baseBranchName: parsed.baseBranchName,
+        title: parsed.title,
+        body: parsed.body,
+        isDraft,
+    };
+}
+function isPrNumberString(value) {
+    return typeof value === "string" && PR_NUMBER_RE.test(value);
+}
+function hasValidUpdateFields(parsed) {
+    return (isOwnerAndRepo(parsed.ownerAndRepo) &&
+        isPrNumberString(parsed.prExternalId) &&
+        isSafeGitRef(parsed.headBranchName) &&
+        isSafeGitRef(parsed.baseBranchName) &&
+        isNonEmptyString(parsed.title) &&
+        isBodyString(parsed.body));
+}
+// Exactly one of convert-to-draft / convert-from-draft may be set; both default to false.
+function parseConvertFlags(parsed) {
+    const convertToDraft = optionalBool(parsed.convertToDraft);
+    const convertFromDraft = optionalBool(parsed.convertFromDraft);
+    if (convertToDraft === undefined || convertFromDraft === undefined)
+        return undefined;
+    if (convertToDraft && convertFromDraft)
+        return undefined;
+    return { convertToDraft, convertFromDraft };
+}
+function buildUpdateCommand(parsed) {
+    if (!hasValidUpdateFields(parsed))
+        return undefined;
+    const converts = parseConvertFlags(parsed);
+    if (converts === undefined)
+        return undefined;
+    return {
+        kind: "pr-update",
+        ownerAndRepo: parsed.ownerAndRepo,
+        prExternalId: parsed.prExternalId,
+        headBranchName: parsed.headBranchName,
+        baseBranchName: parsed.baseBranchName,
+        title: parsed.title,
+        body: parsed.body,
+        convertToDraft: converts.convertToDraft,
+        convertFromDraft: converts.convertFromDraft,
+    };
+}
+function buildPrCommand(parsed) {
+    if (parsed.kind === "pr-create")
+        return buildCreateCommand(parsed);
+    if (parsed.kind === "pr-update")
+        return buildUpdateCommand(parsed);
+    return undefined;
+}
+function validate(parsed) {
+    const bad = { kind: "err", result: errResult(400, "GIT_DELIVERY_PR_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 = buildPrCommand(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 createHandlePrPreview = (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_PR_UNKNOWN_PROJECT");
+        const packs = seams.policyPacks ?? { repoPack: KEIKO_DEFAULT_PR_POLICY_PACK };
+        try {
+            const snapshot = await readWorktreeSnapshotFor(workspace, seams, now);
+            return {
+                status: 200,
+                body: deps.redactor(buildGitDeliveryPrPreview(command, snapshot, packs)),
+            };
+        }
+        catch {
+            return errResult(409, "GIT_DELIVERY_PR_WORKTREE_UNAVAILABLE");
+        }
+    };
+};
+// ─── Execute handler (governed) ───────────────────────────────────────────────────────────────
+export const createHandlePrExecute = (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_PR_UNKNOWN_PROJECT");
+        let result;
+        try {
+            result = await executeGovernedPullRequest(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_PR_WORKTREE_UNAVAILABLE");
+        }
+        return { status: 200, body: deps.redactor(gitDeliveryPrExecuteResponse(result)) };
+    };
+};
+// ─── Route group ───────────────────────────────────────────────────────────────────────────────
+export const createGitDeliveryPrRouteGroup = (options = {}) => [
+    {
+        method: "POST",
+        pattern: "/api/git-delivery/pr/preview",
+        handler: createHandlePrPreview(options),
+    },
+    {
+        method: "POST",
+        pattern: "/api/git-delivery/pr/execute",
+        handler: createHandlePrExecute(options),
+    },
+];
+export const GIT_DELIVERY_PR_ROUTE_GROUP = createGitDeliveryPrRouteGroup();

package/dist/gitDelivery/pushExecution.d.ts

@@ -0,0 +1,43 @@
+import type { WorkspaceInfo } from "@oscharko-dev/keiko-workspace";
+import { type GitDeliveryApprovalRequirement, type GitDeliveryRepoPolicyPack, type GitDeliveryRiskClass } from "@oscharko-dev/keiko-contracts";
+import { type GitPublishLifecycleResult, type GitPushCommand, type GitRemotePublishAdapter, 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_PUBLISH_POLICY_PACK: GitDeliveryRepoPolicyPack;
+export interface GitDeliveryPublishSeams {
+    readonly publishAdapterFactory?: ((workspace: WorkspaceInfo) => GitRemotePublishAdapter) | undefined;
+    readonly snapshotReader?: ((workspace: WorkspaceInfo) => Promise<GitWorktreeSnapshot>) | undefined;
+    readonly policyPacks?: GitDeliveryTrustedPolicyPacks | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly newActionId?: (() => string) | undefined;
+}
+/**
+ * Runs ONE governed publish end-to-end: live snapshot → publish 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
+ * attempts.
+ */
+export declare function executeGovernedPublish(command: GitPushCommand, approval: GitDeliveryApprovalRequirement, workspace: WorkspaceInfo, deps: Pick<UiHandlerDeps, "evidenceStore" | "redactor">, seams: GitDeliveryPublishSeams): Promise<GitPublishLifecycleResult>;
+export interface GitDeliveryPushPreviewBody {
+    readonly schemaVersion: "1";
+    readonly remoteAlias: string;
+    readonly remoteBranchName: string;
+    readonly sourceBranchName: string;
+    readonly riskClass: GitDeliveryRiskClass;
+    readonly wouldCreateRemoteBranch: boolean;
+    readonly wouldTriggerChecks: boolean;
+    readonly forceBlocked: boolean;
+    readonly preflightBlockingCodes: readonly string[];
+    readonly preflightAdvisoryCodes: readonly string[];
+    readonly policyOutcome: string;
+    readonly policyBlockReason?: string;
+}
+export declare function buildGitDeliveryPushPreview(command: GitPushCommand, snapshot: GitWorktreeSnapshot, packs: GitDeliveryTrustedPolicyPacks): GitDeliveryPushPreviewBody;
+export interface GitDeliveryPushExecuteResponseBody extends GitDeliveryMutationResponseBody {
+    readonly publishRejectionReason?: string;
+    readonly recoveryDisposition?: string;
+    readonly recoveryActionHint?: string;
+}
+export declare function gitDeliveryPublishExecuteResponse(result: GitPublishLifecycleResult): GitDeliveryPushExecuteResponseBody;
+//# sourceMappingURL=pushExecution.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pushExecution.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/pushExecution.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAIL,KAAK,8BAA8B,EAEnC,KAAK,yBAAyB,EAC9B,KAAK,oBAAoB,EAC1B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAIL,KAAK,yBAAyB,EAC9B,KAAK,cAAc,EACnB,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,KAAK,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAChF,OAAO,EAKL,KAAK,+BAA+B,EACrC,MAAM,gBAAgB,CAAC;AAQxB,eAAO,MAAM,iCAAiC,EAAE,yBAuB/C,CAAC;AAEF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,qBAAqB,CAAC,EAC3B,CAAC,CAAC,SAAS,EAAE,aAAa,KAAK,uBAAuB,CAAC,GACvD,SAAS,CAAC;IACd,QAAQ,CAAC,cAAc,CAAC,EACpB,CAAC,CAAC,SAAS,EAAE,aAAa,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC,GAC5D,SAAS,CAAC;IACd,QAAQ,CAAC,WAAW,CAAC,EAAE,6BAA6B,GAAG,SAAS,CAAC;IACjE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CACnD;AAsBD;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,8BAA8B,EACxC,SAAS,EAAE,aAAa,EACxB,IAAI,EAAE,IAAI,CAAC,aAAa,EAAE,eAAe,GAAG,UAAU,CAAC,EACvD,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAAC,yBAAyB,CAAC,CAoBpC;AAID,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,aAAa,EAAE,GAAG,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,oBAAoB,CAAC;IACzC,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;IAC1C,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IAGrC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,QAAQ,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IACnD,QAAQ,CAAC,sBAAsB,EAAE,SAAS,MAAM,EAAE,CAAC;IACnD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAKD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,mBAAmB,EAC7B,KAAK,EAAE,6BAA6B,GACnC,0BAA0B,CA8B5B;AAID,MAAM,WAAW,kCAAmC,SAAQ,+BAA+B;IAGzF,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;IACtC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,wBAAgB,iCAAiC,CAC/C,MAAM,EAAE,yBAAyB,GAChC,kCAAkC,CAapC"}

package/dist/gitDelivery/pushExecution.js

@@ -0,0 +1,124 @@
+// Governed remote publish execution core for the #476 push routes (Epic #470, ADR-0063).
+//
+// The push preview + execute routes share ONE path: resolve and authorize the project workspace, build
+// a TRUSTWORTHY snapshot from the live worktree, drive the #476 publish gateway `runGitPublish` (the
+// SEPARATE remote execution authority — preflight + policy + approval gates, executing through a narrow
+// remote adapter with a dedicated push-only allowlist), and append a content-free evidence record through
+// the #474 ledger for EVERY terminal outcome (allowed and blocked alike — AC5). No second orchestrator,
+// no generic shell, no widening of the local mutation or read-only inspection allowlists. The Node push
+// effect is injected via seams so route tests run deterministically against a fake remote.
+import { GIT_DELIVERY_POLICY_SCHEMA_VERSION, evaluateGitPolicy, gitDeliveryRiskClassForInputs, } from "@oscharko-dev/keiko-contracts";
+import { evaluateGitPreflight, evaluateGitPublishEffectivePolicy, runGitPublish, } from "@oscharko-dev/keiko-tools";
+import { createNodeGitPublishAdapter } from "@oscharko-dev/keiko-tools/internal/git-mutation";
+import { defaultGitDeliveryActionId, gitDeliveryMutationResponse, persistGitDeliveryEvidence, readWorktreeSnapshotFor, } from "./execution.js";
+// Default trusted publish policy: PERMIT `push` only to safe, non-protected branch namespaces and only
+// within the `publish` risk ceiling (which fail-closed BLOCKS force pushes, classed recovery-or-rewrite).
+// A push whose REMOTE target is a shared/protected branch (dev, main, release/*, …) falls the branch-
+// pattern constraint and is blocked with `policy-pack-blocked` — stricter than an ordinary user branch
+// (AC2). Every other action kind is denied. Applies only when governed git delivery is ENABLED and no
+// stricter pack is configured; the decision is still EVALUATED for every push, so governance is preserved.
+export const KEIKO_DEFAULT_PUBLISH_POLICY_PACK = {
+    schemaVersion: GIT_DELIVERY_POLICY_SCHEMA_VERSION,
+    repoId: "keiko-publish-default",
+    rules: [
+        {
+            actionKind: "push",
+            decision: "constrained",
+            constraints: [
+                { kind: "risk-class-ceiling", maxRiskClass: "publish" },
+                {
+                    kind: "branch-pattern",
+                    patterns: [
+                        { matchKind: "prefix", value: "claude/" },
+                        { matchKind: "prefix", value: "feat/" },
+                        { matchKind: "prefix", value: "fix/" },
+                        { matchKind: "prefix", value: "chore/" },
+                        { matchKind: "prefix", value: "docs/" },
+                    ],
+                },
+            ],
+        },
+    ],
+    defaultRule: { decision: "blocked" },
+};
+function publishAdapterFor(workspace, seams, now) {
+    if (seams.publishAdapterFactory !== undefined)
+        return seams.publishAdapterFactory(workspace);
+    return createNodeGitPublishAdapter({ workspace, processEnv: process.env, now });
+}
+function pushInputsOf(command) {
+    return {
+        kind: "push",
+        sourceBranchName: command.sourceBranchName,
+        remoteAlias: command.remoteAlias,
+        remoteBranchName: command.remoteBranchName,
+        forcePush: command.forcePush,
+        setUpstreamTracking: command.setUpstreamTracking,
+    };
+}
+/**
+ * Runs ONE governed publish end-to-end: live snapshot → publish 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
+ * attempts.
+ */
+export async function executeGovernedPublish(command, approval, workspace, deps, seams) {
+    const now = seams.now ?? Date.now;
+    const snapshot = await readWorktreeSnapshotFor(workspace, seams, now);
+    const adapter = publishAdapterFor(workspace, seams, now);
+    const packs = seams.policyPacks ?? { repoPack: KEIKO_DEFAULT_PUBLISH_POLICY_PACK };
+    const newActionId = seams.newActionId ?? (() => defaultGitDeliveryActionId(command, now()));
+    const result = await runGitPublish({ command, approval }, {
+        adapter,
+        snapshot,
+        ...(packs.orgPack !== undefined ? { orgPolicyPack: packs.orgPack } : {}),
+        ...(packs.repoPack !== undefined ? { repoPolicyPack: packs.repoPack } : {}),
+        now,
+        newActionId,
+    });
+    persistGitDeliveryEvidence(deps, result.lifecycle, snapshot, workspace.root, now);
+    return result;
+}
+// Builds the read-only push preview from a live snapshot: the remote target, the risk summary, the
+// preflight findings (incl. non-fast-forward and missing-upstream), and the policy decision — no
+// execution, no evidence.
+export function buildGitDeliveryPushPreview(command, snapshot, packs) {
+    const inputs = pushInputsOf(command);
+    const preflight = evaluateGitPreflight(inputs, snapshot);
+    const decision = evaluateGitPolicy(packs.orgPack, packs.repoPack, {
+        actionKind: "push",
+        targetBranchName: command.remoteBranchName,
+        activeProviderCapabilities: [],
+    });
+    // The EFFECTIVE policy outcome for THIS target, so the preview predicts the execute outcome exactly:
+    // a constrained decision is resolved against the target (a protected/shared branch reads as blocked).
+    const effective = evaluateGitPublishEffectivePolicy(decision, command.remoteBranchName, [], inputs);
+    return {
+        schemaVersion: "1",
+        remoteAlias: command.remoteAlias,
+        remoteBranchName: command.remoteBranchName,
+        sourceBranchName: command.sourceBranchName,
+        riskClass: gitDeliveryRiskClassForInputs(inputs),
+        wouldCreateRemoteBranch: command.setUpstreamTracking && !snapshot.hasUpstream,
+        wouldTriggerChecks: true,
+        forceBlocked: command.forcePush,
+        preflightBlockingCodes: preflight.blocking.map((f) => f.code),
+        preflightAdvisoryCodes: preflight.advisory.map((f) => f.code),
+        policyOutcome: effective.outcome,
+        ...(effective.blockReason !== undefined ? { policyBlockReason: effective.blockReason } : {}),
+    };
+}
+export function gitDeliveryPublishExecuteResponse(result) {
+    const base = gitDeliveryMutationResponse(result.lifecycle);
+    if (result.rejection === undefined) {
+        return base;
+    }
+    return {
+        ...base,
+        publishRejectionReason: result.rejection.reason,
+        recoveryDisposition: result.rejection.disposition,
+        ...(result.rejection.actionHint !== undefined
+            ? { recoveryActionHint: result.rejection.actionHint }
+            : {}),
+    };
+}

package/dist/gitDelivery/pushRoutes.d.ts

@@ -0,0 +1,12 @@
+import type { RouteContext, RouteDefinition, RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+import { type GitDeliveryPublishSeams } from "./pushExecution.js";
+export type GitDeliveryPushErrorCode = "GIT_DELIVERY_PUSH_BAD_REQUEST" | "GIT_DELIVERY_PUSH_PAYLOAD_TOO_LARGE" | "GIT_DELIVERY_PUSH_FORBIDDEN_PAYLOAD" | "GIT_DELIVERY_PUSH_UNKNOWN_PROJECT" | "GIT_DELIVERY_PUSH_WORKTREE_UNAVAILABLE";
+export interface GitDeliveryPushRouteOptions {
+    readonly execution?: GitDeliveryPublishSeams;
+}
+export declare const createHandlePushPreview: (options?: GitDeliveryPushRouteOptions) => ((ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>);
+export declare const createHandlePushExecute: (options?: GitDeliveryPushRouteOptions) => ((ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>);
+export declare const createGitDeliveryPushRouteGroup: (options?: GitDeliveryPushRouteOptions) => readonly RouteDefinition[];
+export declare const GIT_DELIVERY_PUSH_ROUTE_GROUP: readonly RouteDefinition[];
+//# sourceMappingURL=pushRoutes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pushRoutes.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/pushRoutes.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,OAAO,EAKL,KAAK,uBAAuB,EAC7B,MAAM,oBAAoB,CAAC;AAa5B,MAAM,MAAM,wBAAwB,GAChC,+BAA+B,GAC/B,qCAAqC,GACrC,qCAAqC,GACrC,mCAAmC,GACnC,wCAAwC,CAAC;AAmB7C,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,uBAAuB,CAAC;CAC9C;AAyHD,eAAO,MAAM,uBAAuB,GAClC,UAAS,2BAAgC,KACxC,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAsBnE,CAAC;AAIF,eAAO,MAAM,uBAAuB,GAClC,UAAS,2BAAgC,KACxC,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAmBnE,CAAC;AAIF,eAAO,MAAM,+BAA+B,GAC1C,UAAS,2BAAgC,KACxC,SAAS,eAAe,EAW1B,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,SAAS,eAAe,EACjC,CAAC"}