@oscharko-dev/keiko-server 0.2.8 → 0.2.9

package/dist/gitDelivery/agentOperationsRoutes.js

@@ -0,0 +1,405 @@
+// Typed repository-operation facade for agents (Issue #1577, Epic #1571).
+//
+// This is an admission and dispatch layer only. It accepts a closed semantic operation envelope,
+// rejects shell/provider-shaped input before delegation, and forwards to existing Git read /
+// git-delivery route handlers. It does not import or create any new Git, gh, terminal, or provider
+// adapter authority.
+import { createHash } from "node:crypto";
+import { Readable } from "node:stream";
+import { GIT_REPOSITORY_AGENT_SCHEMA_VERSION, parseGitRepositoryAgentOperationRequest, } from "@oscharko-dev/keiko-contracts";
+import { STREAMING } from "../routes.js";
+import { handleGitBranches, handleGitDiff, handleGitStatus } from "../gitRoutes.js";
+import { createGitDeliveryCommitRouteGroup } from "./commitRoutes.js";
+import { createGitDeliveryLocalMutationRouteGroup } from "./localMutationRoutes.js";
+import { createGitDeliveryMergeRouteGroup } from "./mergeRoutes.js";
+import { createGitDeliveryPrRouteGroup } from "./prRoutes.js";
+import { createGitDeliveryPushRouteGroup } from "./pushRoutes.js";
+import { createGitDeliverySyncRouteGroup } from "./syncRoutes.js";
+import { GitDeliveryBodyTooLargeError, hasOnlyAllowedKeys, isPlainObject, readGitDeliveryBody, scanForbiddenStrings, scanUnsafeFormatChars, } from "./requestGuards.js";
+const SAFE_MESSAGES = {
+    GIT_AGENT_OPERATION_BAD_REQUEST: "The request body is not a valid repository operation.",
+    GIT_AGENT_OPERATION_PAYLOAD_TOO_LARGE: "The repository operation request exceeds the maximum permitted size.",
+    GIT_AGENT_OPERATION_FORBIDDEN_PAYLOAD: "The request contained a forbidden credential, header, URL, or unsafe text shape.",
+    GIT_AGENT_OPERATION_UNSUPPORTED: "The repository operation is not supported.",
+};
+const errResult = (status, code) => ({
+    status,
+    body: { error: { code, message: SAFE_MESSAGES[code] } },
+});
+const routeGroups = [
+    ...createGitDeliveryLocalMutationRouteGroup(),
+    ...createGitDeliveryCommitRouteGroup(),
+    ...createGitDeliveryPushRouteGroup(),
+    ...createGitDeliveryPrRouteGroup(),
+    ...createGitDeliveryMergeRouteGroup(),
+    ...createGitDeliverySyncRouteGroup(),
+];
+// Defaults for the process-memory idempotency cache. The cap bounds worst-case memory against a client
+// that streams many distinct idempotency keys; the TTL lets settled replay entries self-evict so the
+// map self-cleans even for keys that are never queried again.
+export const DEFAULT_IDEMPOTENCY_MAX_ENTRIES = 1024;
+export const DEFAULT_IDEMPOTENCY_TTL_MS = 10 * 60 * 1000;
+// Bounded LRU + TTL store for the agent-facade idempotency replay window. Exposes the Map subset the
+// handler relies on (get / set / delete) plus `size` for tests. Overflow eviction targets the
+// least-recently-used *settled* entry only; in-flight reservations are exempt.
+export class IdempotencyCache {
+    entries = new Map();
+    maxEntries;
+    ttlMs;
+    now;
+    constructor(options = {}) {
+        this.maxEntries = Math.max(1, Math.floor(options.maxEntries ?? DEFAULT_IDEMPOTENCY_MAX_ENTRIES));
+        this.ttlMs = Math.max(1, Math.floor(options.ttlMs ?? DEFAULT_IDEMPOTENCY_TTL_MS));
+        this.now = options.now ?? Date.now;
+    }
+    get size() {
+        return this.entries.size;
+    }
+    get(key) {
+        const stored = this.entries.get(key);
+        if (stored === undefined)
+            return undefined;
+        if (stored.entry.result !== undefined && this.now() >= stored.expiresAt) {
+            this.entries.delete(key);
+            return undefined;
+        }
+        // Refresh LRU recency on a hit by reinserting at the tail; the TTL window is unchanged.
+        this.entries.delete(key);
+        this.entries.set(key, stored);
+        return stored.entry;
+    }
+    set(key, entry) {
+        this.entries.delete(key);
+        this.pruneExpired();
+        this.entries.set(key, { entry, expiresAt: this.now() + this.ttlMs });
+        this.evictOverflow();
+    }
+    delete(key) {
+        this.entries.delete(key);
+    }
+    pruneExpired() {
+        const now = this.now();
+        for (const [key, stored] of this.entries) {
+            if (stored.entry.result !== undefined && now >= stored.expiresAt) {
+                this.entries.delete(key);
+            }
+        }
+    }
+    evictOverflow() {
+        while (this.entries.size > this.maxEntries) {
+            let victim;
+            for (const [key, stored] of this.entries) {
+                if (stored.entry.pending === undefined) {
+                    victim = key;
+                    break;
+                }
+            }
+            if (victim === undefined)
+                break; // every entry is an in-flight reservation — cannot safely evict
+            this.entries.delete(victim);
+        }
+    }
+}
+const idempotencyCache = new IdempotencyCache();
+function denied(request, denialReason, message) {
+    return {
+        schemaVersion: GIT_REPOSITORY_AGENT_SCHEMA_VERSION,
+        ...(request.operation === undefined ? {} : { operation: request.operation }),
+        ...(request.mode === undefined ? {} : { mode: request.mode }),
+        status: "denied",
+        denialReason,
+        message,
+    };
+}
+async function readParsed(req) {
+    let raw;
+    try {
+        raw = await readGitDeliveryBody(req);
+    }
+    catch (error) {
+        if (error instanceof GitDeliveryBodyTooLargeError) {
+            return { ok: false, result: errResult(413, "GIT_AGENT_OPERATION_PAYLOAD_TOO_LARGE") };
+        }
+        return { ok: false, result: errResult(400, "GIT_AGENT_OPERATION_BAD_REQUEST") };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false, result: errResult(400, "GIT_AGENT_OPERATION_BAD_REQUEST") };
+    }
+}
+function makeRequest(body, base) {
+    const req = Readable.from([Buffer.from(JSON.stringify(body), "utf8")]);
+    req.method = "POST";
+    req.headers = { ...base.headers, "content-type": "application/json" };
+    return req;
+}
+function postContext(ctx, pattern, body) {
+    return {
+        req: makeRequest(body, ctx.req),
+        res: ctx.res,
+        params: {},
+        url: new URL(`http://127.0.0.1${pattern}`),
+    };
+}
+function readContext(ctx, path) {
+    return {
+        req: Readable.from([]),
+        res: ctx.res,
+        params: {},
+        url: new URL(`http://127.0.0.1${path}`),
+    };
+}
+function queryFor(path, entries) {
+    const url = new URL(`http://127.0.0.1${path}`);
+    for (const [key, value] of entries) {
+        if (value !== undefined && value !== "")
+            url.searchParams.set(key, value);
+    }
+    return `${url.pathname}${url.search}`;
+}
+const READ_PAYLOAD_KEYS = {
+    status: new Set(),
+    diff: new Set(["path", "scope"]),
+    "branch-list": new Set(),
+};
+function payloadOrEmpty(request) {
+    return request.payload ?? {};
+}
+function validatePayloadKeys(request, allowed) {
+    const payload = payloadOrEmpty(request);
+    if (!hasOnlyAllowedKeys(payload, allowed)) {
+        return errResult(400, "GIT_AGENT_OPERATION_BAD_REQUEST");
+    }
+    return undefined;
+}
+async function delegateRead(request, ctx, deps) {
+    if (request.operation !== "status" &&
+        request.operation !== "diff" &&
+        request.operation !== "branch-list") {
+        return errResult(400, "GIT_AGENT_OPERATION_BAD_REQUEST");
+    }
+    const keyError = validatePayloadKeys(request, READ_PAYLOAD_KEYS[request.operation]);
+    if (keyError !== undefined)
+        return keyError;
+    const payload = payloadOrEmpty(request);
+    if (request.operation === "status") {
+        return handleGitStatus(readContext(ctx, queryFor("/api/git/status", [["root", request.projectId]])), deps, deps.gitRouteOptions);
+    }
+    if (request.operation === "branch-list") {
+        return handleGitBranches(readContext(ctx, queryFor("/api/git/branches", [["root", request.projectId]])), deps, deps.gitRouteOptions);
+    }
+    return handleGitDiff(readContext(ctx, queryFor("/api/git/diff", [
+        ["root", request.projectId],
+        ["path", typeof payload.path === "string" ? payload.path : undefined],
+        ["scope", typeof payload.scope === "string" ? payload.scope : undefined],
+    ])), deps, deps.gitRouteOptions);
+}
+const WRITE_KEYS = {
+    status: new Set(),
+    diff: new Set(),
+    "branch-list": new Set(),
+    "branch-create": new Set(["branchName", "baseBranchName", "startPointRefHash"]),
+    "branch-switch": new Set(["branchName"]),
+    stage: new Set(["pathspecs", "includeUntracked"]),
+    unstage: new Set(["pathspecs"]),
+    commit: new Set(["messageDraft", "message", "allowEmpty"]),
+    fetch: new Set(["remote"]),
+    pull: new Set(["remote"]),
+    push: new Set([
+        "remoteAlias",
+        "remoteBranchName",
+        "sourceBranchName",
+        "forcePush",
+        "setUpstreamTracking",
+    ]),
+    "pull-request": new Set([
+        "kind",
+        "ownerAndRepo",
+        "headBranchName",
+        "baseBranchName",
+        "title",
+        "description",
+        "isDraft",
+        "prExternalId",
+        "convertToDraft",
+        "convertFromDraft",
+    ]),
+    merge: new Set([
+        "kind",
+        "ownerAndRepo",
+        "prExternalId",
+        "baseBranchName",
+        "headBranchName",
+        "mergeStrategy",
+        "deleteBranchAfterMerge",
+        "expectedHeadRefHash",
+    ]),
+};
+const STATIC_WRITE_PATTERNS = {
+    "branch-create": "/api/git-delivery/local-branch/create",
+    "branch-switch": "/api/git-delivery/local-branch/switch",
+    stage: "/api/git-delivery/staging/stage",
+    unstage: "/api/git-delivery/staging/unstage",
+};
+const PHASED_WRITE_PATTERNS = {
+    commit: "/api/git-delivery/commit",
+    fetch: "/api/git-delivery/fetch",
+    pull: "/api/git-delivery/pull",
+    push: "/api/git-delivery/push",
+    "pull-request": "/api/git-delivery/pr",
+    merge: "/api/git-delivery/merge",
+};
+function delegatedPattern(request) {
+    const staticPattern = STATIC_WRITE_PATTERNS[request.operation];
+    if (staticPattern !== undefined)
+        return staticPattern;
+    const phasedPrefix = PHASED_WRITE_PATTERNS[request.operation];
+    return phasedPrefix === undefined ? undefined : `${phasedPrefix}/${request.mode}`;
+}
+function delegatedBody(request) {
+    const payload = payloadOrEmpty(request);
+    const body = {
+        schemaVersion: "1",
+        projectId: request.projectId,
+        ...payload,
+    };
+    if (request.operation === "pull-request") {
+        body.body = typeof payload.description === "string" ? payload.description : "";
+        delete body.description;
+    }
+    if (request.operation === "merge") {
+        body.kind = "merge";
+    }
+    return body;
+}
+async function delegateWrite(request, ctx, deps) {
+    const keyError = validatePayloadKeys(request, WRITE_KEYS[request.operation]);
+    if (keyError !== undefined)
+        return keyError;
+    const pattern = delegatedPattern(request);
+    if (pattern === undefined)
+        return errResult(400, "GIT_AGENT_OPERATION_UNSUPPORTED");
+    const route = routeGroups.find((candidate) => candidate.pattern === pattern);
+    if (route === undefined)
+        return errResult(400, "GIT_AGENT_OPERATION_UNSUPPORTED");
+    const body = delegatedBody(request);
+    const outcome = await route.handler(postContext(ctx, pattern, body), deps);
+    return outcome === STREAMING ? errResult(400, "GIT_AGENT_OPERATION_UNSUPPORTED") : outcome;
+}
+function wrapDelegated(request, result, replay = false) {
+    return {
+        schemaVersion: GIT_REPOSITORY_AGENT_SCHEMA_VERSION,
+        operation: request.operation,
+        mode: request.mode,
+        status: "delegated",
+        routeStatus: result.status,
+        ...(replay ? { replay: true } : {}),
+        response: result.body,
+    };
+}
+function cacheKey(request) {
+    if (request.mode !== "execute" || request.idempotencyKey === undefined)
+        return undefined;
+    return `${request.projectId}\0${request.idempotencyKey}`;
+}
+function normalizedForDigest(value) {
+    if (Array.isArray(value))
+        return value.map(normalizedForDigest);
+    if (!isPlainObject(value))
+        return value;
+    return Object.fromEntries(Object.keys(value)
+        .sort()
+        .map((key) => [key, normalizedForDigest(value[key])]));
+}
+function fingerprintRequest(request) {
+    return createHash("sha256")
+        .update(JSON.stringify(normalizedForDigest(request)))
+        .digest("hex");
+}
+function deniedStatus(reason) {
+    return reason === "unsupported-direct-shell" ? 200 : 400;
+}
+async function parseAgentRequest(req) {
+    const read = await readParsed(req);
+    if (!read.ok)
+        return read;
+    const parsed = parseGitRepositoryAgentOperationRequest(read.value);
+    if (!parsed.ok) {
+        return {
+            ok: false,
+            result: {
+                status: deniedStatus(parsed.denialReason),
+                body: denied({}, parsed.denialReason, parsed.message),
+            },
+        };
+    }
+    if (scanForbiddenStrings(read.value)) {
+        return { ok: false, result: errResult(400, "GIT_AGENT_OPERATION_FORBIDDEN_PAYLOAD") };
+    }
+    if (scanUnsafeFormatChars(read.value) || !isPlainObject(read.value)) {
+        return { ok: false, result: errResult(400, "GIT_AGENT_OPERATION_BAD_REQUEST") };
+    }
+    return { ok: true, request: parsed.value, fingerprint: fingerprintRequest(parsed.value) };
+}
+function idempotencyConflict(request) {
+    return {
+        status: 409,
+        body: denied(request, "idempotency-conflict", "The idempotencyKey was already used for a different repository operation."),
+    };
+}
+function responseResult(body, replay = false) {
+    const response = body.status === "delegated" && replay ? { ...body, replay: true } : body;
+    return {
+        status: body.status === "delegated" ? body.routeStatus : 200,
+        body: response,
+    };
+}
+async function delegateRequest(request, ctx, deps) {
+    return request.mode === "read"
+        ? delegateRead(request, ctx, deps)
+        : delegateWrite(request, ctx, deps);
+}
+export async function handleGitAgentOperationWithDelegate(request, fingerprint, delegate, cache = idempotencyCache) {
+    const key = cacheKey(request);
+    if (key === undefined) {
+        const result = await delegate();
+        return { status: result.status, body: wrapDelegated(request, result) };
+    }
+    const cached = cache.get(key);
+    if (cached !== undefined) {
+        if (cached.fingerprint !== fingerprint)
+            return idempotencyConflict(request);
+        if (cached.result !== undefined)
+            return responseResult(cached.result, true);
+        if (cached.pending !== undefined)
+            return responseResult(await cached.pending, true);
+    }
+    const pending = delegate().then((result) => wrapDelegated(request, result));
+    cache.set(key, { fingerprint, pending });
+    try {
+        const body = await pending;
+        cache.set(key, { fingerprint, result: body });
+        return responseResult(body);
+    }
+    catch (error) {
+        const current = cache.get(key);
+        if (current?.pending === pending)
+            cache.delete(key);
+        throw error;
+    }
+}
+export async function handleGitAgentOperation(ctx, deps) {
+    const parsed = await parseAgentRequest(ctx.req);
+    if (!parsed.ok)
+        return parsed.result;
+    return handleGitAgentOperationWithDelegate(parsed.request, parsed.fingerprint, () => delegateRequest(parsed.request, ctx, deps));
+}
+export const GIT_AGENT_OPERATION_ROUTE_GROUP = [
+    {
+        method: "POST",
+        pattern: "/api/git/agent/operations",
+        handler: handleGitAgentOperation,
+    },
+];

package/dist/gitDelivery/commitRoutes.d.ts

@@ -0,0 +1,23 @@
+import { type GitCommitChangeSummary, type GitCommitIntentAnalysis, type GitCommitMessagePolicy, type GitCommitMessageValidation } from "@oscharko-dev/keiko-contracts";
+import type { RouteContext, RouteDefinition, RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+import { type GitDeliveryExecutionSeams } from "./execution.js";
+export type GitDeliveryCommitErrorCode = "GIT_DELIVERY_COMMIT_BAD_REQUEST" | "GIT_DELIVERY_COMMIT_PAYLOAD_TOO_LARGE" | "GIT_DELIVERY_COMMIT_FORBIDDEN_PAYLOAD" | "GIT_DELIVERY_COMMIT_UNKNOWN_PROJECT" | "GIT_DELIVERY_COMMIT_WORKTREE_UNAVAILABLE";
+export interface GitDeliveryCommitRouteOptions {
+    readonly execution?: GitDeliveryExecutionSeams;
+    readonly messagePolicy?: GitCommitMessagePolicy;
+}
+export interface GitDeliveryCommitPreviewBody {
+    readonly schemaVersion: "1";
+    readonly summary: GitCommitChangeSummary;
+    readonly intent: GitCommitIntentAnalysis;
+    readonly messageValidation: GitCommitMessageValidation;
+    readonly preflightFindingCodes: readonly string[];
+    readonly policyOutcome: string;
+    readonly policyBlockReason?: string;
+}
+export declare const createHandleCommitPreview: (options?: GitDeliveryCommitRouteOptions) => ((ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>);
+export declare const createHandleCommitExecute: (options?: GitDeliveryCommitRouteOptions) => ((ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>);
+export declare const createGitDeliveryCommitRouteGroup: (options?: GitDeliveryCommitRouteOptions) => readonly RouteDefinition[];
+export declare const GIT_DELIVERY_COMMIT_ROUTE_GROUP: readonly RouteDefinition[];
+//# sourceMappingURL=commitRoutes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"commitRoutes.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/commitRoutes.ts"],"names":[],"mappings":"AAeA,OAAO,EAML,KAAK,sBAAsB,EAC3B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,0BAA0B,EAGhC,MAAM,+BAA+B,CAAC;AAEvC,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAOL,KAAK,yBAAyB,EAC/B,MAAM,gBAAgB,CAAC;AAaxB,MAAM,MAAM,0BAA0B,GAClC,iCAAiC,GACjC,uCAAuC,GACvC,uCAAuC,GACvC,qCAAqC,GACrC,0CAA0C,CAAC;AAqB/C,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,CAAC,EAAE,yBAAyB,CAAC;IAE/C,QAAQ,CAAC,aAAa,CAAC,EAAE,sBAAsB,CAAC;CACjD;AA6CD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,aAAa,EAAE,GAAG,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,iBAAiB,EAAE,0BAA0B,CAAC;IACvD,QAAQ,CAAC,qBAAqB,EAAE,SAAS,MAAM,EAAE,CAAC;IAClD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AA0DD,eAAO,MAAM,yBAAyB,GACpC,UAAS,6BAAkC,KAC1C,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAoBnE,CAAC;AAuCF,eAAO,MAAM,yBAAyB,GACpC,UAAS,6BAAkC,KAC1C,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAyCnE,CAAC;AAIF,eAAO,MAAM,iCAAiC,GAC5C,UAAS,6BAAkC,KAC1C,SAAS,eAAe,EAW1B,CAAC;AAEF,eAAO,MAAM,+BAA+B,EAAE,SAAS,eAAe,EACjC,CAAC"}

package/dist/gitDelivery/commitRoutes.js

@@ -0,0 +1,204 @@
+// Governed local Git commit routes: read-only preview + governed execute (Issue #475, Epic #470).
+//
+//   * POST /api/git-delivery/commit/preview  — READ-ONLY. Builds the pre-commit verification context:
+//       staged scope, commit-intent quality warnings (mixed-scope / WIP / large-change), message-policy
+//       validation of the draft, preflight findings, and the policy decision. Never mutates, never
+//       records evidence.
+//   * POST /api/git-delivery/commit/execute  — Governed. Enforces the message policy FIRST (the kernel
+//       only sees a byte length, so message rules are evaluated here with the pure contract validator);
+//       a violation blocks the commit with typed codes BEFORE the kernel runs. A valid message drives
+//       executeGovernedMutation (preflight + policy + approval + execute) and appends evidence.
+//
+// Content-free throughout: counts, structural area tokens, typed warning/violation/finding codes, and
+// the deterministic suggestion scaffold only — never the message body, diff, or raw paths.
+import { analyzeGitCommitIntent, evaluateGitPolicy, isGitDeliveryApprovalRequirement, KEIKO_DEFAULT_COMMIT_MESSAGE_POLICY, validateGitCommitMessage, } from "@oscharko-dev/keiko-contracts";
+import { evaluateGitPreflight, summarizeStagedChangeset } from "@oscharko-dev/keiko-tools";
+import { executeGovernedMutation, gitDeliveryMutationResponse, KEIKO_DEFAULT_LOCAL_GIT_POLICY_PACK, readStagedPathsFor, readWorktreeSnapshotFor, resolveProjectWorkspace, } from "./execution.js";
+import { GitDeliveryBodyTooLargeError, hasOnlyAllowedKeys, isNonEmptyString, isPlainObject, readGitDeliveryBody, scanForbiddenStrings, scanUnsafeFormatChars, } from "./requestGuards.js";
+const SAFE_MESSAGES = {
+    GIT_DELIVERY_COMMIT_BAD_REQUEST: "The request body is not a valid governed commit request.",
+    GIT_DELIVERY_COMMIT_PAYLOAD_TOO_LARGE: "The governed commit request exceeds the maximum size.",
+    GIT_DELIVERY_COMMIT_FORBIDDEN_PAYLOAD: "The request contained a forbidden field. Requests may not carry credentials, headers, or URLs.",
+    GIT_DELIVERY_COMMIT_UNKNOWN_PROJECT: "The requested project is not a known workspace.",
+    GIT_DELIVERY_COMMIT_WORKTREE_UNAVAILABLE: "The repository worktree could not be inspected. Confirm the project is a Git repository.",
+};
+const errResult = (status, code) => ({
+    status,
+    body: { error: { code, message: SAFE_MESSAGES[code] } },
+});
+const UTF8 = new TextEncoder();
+async function readParsed(req) {
+    let raw;
+    try {
+        raw = await readGitDeliveryBody(req);
+    }
+    catch (error) {
+        const result = error instanceof GitDeliveryBodyTooLargeError
+            ? errResult(413, "GIT_DELIVERY_COMMIT_PAYLOAD_TOO_LARGE")
+            : errResult(400, "GIT_DELIVERY_COMMIT_BAD_REQUEST");
+        return { ok: false, result };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_COMMIT_BAD_REQUEST") };
+    }
+}
+// Envelope pre-checks shared by both handlers. Returns the validated object or an error RouteResult.
+function preValidate(parsed, allowed) {
+    const bad = { ok: false, result: errResult(400, "GIT_DELIVERY_COMMIT_BAD_REQUEST") };
+    if (!isPlainObject(parsed) || !hasOnlyAllowedKeys(parsed, allowed))
+        return bad;
+    if (parsed.schemaVersion !== "1" || !isNonEmptyString(parsed.projectId))
+        return bad;
+    if (scanForbiddenStrings(parsed)) {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_COMMIT_FORBIDDEN_PAYLOAD") };
+    }
+    if (scanUnsafeFormatChars(parsed))
+        return bad;
+    return { ok: true, obj: parsed };
+}
+// ─── Preview (read-only) ──────────────────────────────────────────────────────────────────────
+const PREVIEW_KEYS = new Set(["schemaVersion", "projectId", "messageDraft"]);
+function buildPreviewBody(summary, messageDraft, policy, preflightCodes, policyOutcome, policyBlockReason) {
+    return {
+        schemaVersion: "1",
+        summary,
+        intent: analyzeGitCommitIntent({ summary, message: messageDraft }),
+        messageValidation: validateGitCommitMessage(messageDraft, policy),
+        preflightFindingCodes: preflightCodes,
+        policyOutcome,
+        ...(policyBlockReason !== undefined ? { policyBlockReason } : {}),
+    };
+}
+// Reads the live worktree and assembles the read-only preview. May throw if the worktree cannot be
+// inspected (not a git repository); the handler maps that to a typed content-free error.
+async function computePreview(workspace, messageDraft, policy, seams, now) {
+    const snapshot = await readWorktreeSnapshotFor(workspace, seams, now);
+    const stagedPaths = await readStagedPathsFor(workspace, seams, now);
+    const summary = summarizeStagedChangeset(stagedPaths);
+    const commitInputs = {
+        kind: "commit",
+        messageByteLength: UTF8.encode(messageDraft).length,
+        stagedPathCount: snapshot.stagedFileCount,
+        allowEmptyCommit: false,
+    };
+    const preflight = evaluateGitPreflight(commitInputs, snapshot);
+    const packs = seams.policyPacks ?? { repoPack: KEIKO_DEFAULT_LOCAL_GIT_POLICY_PACK };
+    const decision = evaluateGitPolicy(packs.orgPack, packs.repoPack, {
+        actionKind: "commit",
+        ...(snapshot.currentBranchName !== undefined
+            ? { targetBranchName: snapshot.currentBranchName }
+            : {}),
+        activeProviderCapabilities: [],
+    });
+    return buildPreviewBody(summary, messageDraft, policy, preflight.findings.map((f) => f.code), decision.outcome, decision.outcome === "blocked" ? decision.reason : undefined);
+}
+export const createHandleCommitPreview = (options = {}) => {
+    const seams = options.execution ?? {};
+    const policy = options.messagePolicy ?? KEIKO_DEFAULT_COMMIT_MESSAGE_POLICY;
+    const now = () => (seams.now ?? Date.now)();
+    return async (ctx, deps) => {
+        const read = await readParsed(ctx.req);
+        if (!read.ok)
+            return read.result;
+        const pre = preValidate(read.value, PREVIEW_KEYS);
+        if (!pre.ok)
+            return pre.result;
+        const messageDraft = typeof pre.obj.messageDraft === "string" ? pre.obj.messageDraft : "";
+        const workspace = resolveProjectWorkspace(deps, pre.obj.projectId);
+        if (workspace === undefined)
+            return errResult(404, "GIT_DELIVERY_COMMIT_UNKNOWN_PROJECT");
+        let body;
+        try {
+            body = await computePreview(workspace, messageDraft, policy, seams, now);
+        }
+        catch {
+            return errResult(409, "GIT_DELIVERY_COMMIT_WORKTREE_UNAVAILABLE");
+        }
+        return { status: 200, body: deps.redactor(body) };
+    };
+};
+// ─── Execute (governed, with message-policy gate) ───────────────────────────────────────────────
+const EXECUTE_KEYS = new Set([
+    "schemaVersion",
+    "projectId",
+    "message",
+    "allowEmpty",
+    "approval",
+]);
+const NO_APPROVAL = { required: false };
+function validateExecute(obj) {
+    if (!isNonEmptyString(obj.message))
+        return undefined;
+    if (obj.allowEmpty !== undefined && typeof obj.allowEmpty !== "boolean")
+        return undefined;
+    const approval = obj.approval === undefined
+        ? NO_APPROVAL
+        : isGitDeliveryApprovalRequirement(obj.approval)
+            ? obj.approval
+            : undefined;
+    if (approval === undefined)
+        return undefined;
+    return {
+        projectId: obj.projectId,
+        message: obj.message,
+        allowEmpty: obj.allowEmpty === true,
+        approval,
+    };
+}
+export const createHandleCommitExecute = (options = {}) => {
+    const seams = options.execution ?? {};
+    const policy = options.messagePolicy ?? KEIKO_DEFAULT_COMMIT_MESSAGE_POLICY;
+    return async (ctx, deps) => {
+        const read = await readParsed(ctx.req);
+        if (!read.ok)
+            return read.result;
+        const pre = preValidate(read.value, EXECUTE_KEYS);
+        if (!pre.ok)
+            return pre.result;
+        const req = validateExecute(pre.obj);
+        if (req === undefined)
+            return errResult(400, "GIT_DELIVERY_COMMIT_BAD_REQUEST");
+        const workspace = resolveProjectWorkspace(deps, req.projectId);
+        if (workspace === undefined)
+            return errResult(404, "GIT_DELIVERY_COMMIT_UNKNOWN_PROJECT");
+        // Message-policy gate (AC2): a policy-violating message blocks the commit BEFORE the kernel runs.
+        const validation = validateGitCommitMessage(req.message, policy);
+        if (!validation.ok) {
+            return {
+                status: 200,
+                body: deps.redactor({
+                    schemaVersion: "1",
+                    status: "blocked",
+                    actionKind: "commit",
+                    blockReason: "message-policy",
+                    messageViolations: validation.violations,
+                }),
+            };
+        }
+        let result;
+        try {
+            result = await executeGovernedMutation({ kind: "commit", message: req.message, allowEmpty: req.allowEmpty }, req.approval, workspace, deps, seams);
+        }
+        catch {
+            return errResult(409, "GIT_DELIVERY_COMMIT_WORKTREE_UNAVAILABLE");
+        }
+        return { status: 200, body: deps.redactor(gitDeliveryMutationResponse(result)) };
+    };
+};
+// ─── Route group ───────────────────────────────────────────────────────────────────────────────
+export const createGitDeliveryCommitRouteGroup = (options = {}) => [
+    {
+        method: "POST",
+        pattern: "/api/git-delivery/commit/preview",
+        handler: createHandleCommitPreview(options),
+    },
+    {
+        method: "POST",
+        pattern: "/api/git-delivery/commit/execute",
+        handler: createHandleCommitExecute(options),
+    },
+];
+export const GIT_DELIVERY_COMMIT_ROUTE_GROUP = createGitDeliveryCommitRouteGroup();

package/dist/gitDelivery/evidenceRoutes.d.ts

@@ -0,0 +1,9 @@
+import type { RouteContext, RouteDefinition, RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+export interface GitDeliveryEvidenceRouteOptions {
+    readonly now?: (() => number) | undefined;
+}
+export declare const createHandleGitDeliveryEvidenceExport: (options?: GitDeliveryEvidenceRouteOptions) => ((ctx: RouteContext, deps: UiHandlerDeps) => RouteResult);
+export declare const handleGitDeliveryEvidenceExport: (ctx: RouteContext, deps: UiHandlerDeps) => RouteResult;
+export declare const GIT_DELIVERY_EVIDENCE_ROUTE_GROUP: readonly RouteDefinition[];
+//# sourceMappingURL=evidenceRoutes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"evidenceRoutes.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/evidenceRoutes.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAqEhD,MAAM,WAAW,+BAA+B;IAE9C,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;CAC3C;AAED,eAAO,MAAM,qCAAqC,GAChD,UAAS,+BAAoC,KAC5C,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,WAAW,CA0B1D,CAAC;AAEF,eAAO,MAAM,+BAA+B,QA5BlC,YAAY,QAAQ,aAAa,KAAK,WA4BsC,CAAC;AAIvF,eAAO,MAAM,iCAAiC,EAAE,SAAS,eAAe,EAMvE,CAAC"}