@oscharko-dev/keiko-server 0.2.8 → 0.2.9

package/dist/gitDelivery/syncExecution.js

@@ -0,0 +1,266 @@
+// Bounded fetch/pull sync execution core (Issue #1573, Epic #1572).
+//
+// fetch/pull are NOT governed mutations: they have no `GitDeliveryActionKind` and do NOT enter the
+// #472 `runGitMutation` kernel. That taxonomy is frozen (#1572 reuse contract §3); widening it to add
+// fetch/pull would weaken the governed control plane. Instead this module mirrors the push route
+// STRUCTURE while reusing the hardened, fixed-arg process runner (`defaultGitProcessRunner`) and the
+// shared porcelain-v2 parser. Two operations:
+//
+//   * buildSyncPreview — READ-ONLY readiness: parse `status --porcelain=v2 --branch` + remote names to
+//       compute branch/detached/upstream/ahead/behind/hasRemote/hasUpstream/dirty + an executable gate
+//       and a typed blockReason.
+//   * runSyncExecute — requires an executable preview before running the bounded fetch/pull command,
+//       classifies exitCode/stderr/stdout/truncated, and re-reads ahead/behind after success.
+//
+// Pure parsing lives in gitPorcelainStatus.ts; this module owns only the bounded process effect and
+// the deterministic outcome classifier. Both are seam-injectable for tests.
+import { GIT_SYNC_SCHEMA_VERSION } from "@oscharko-dev/keiko-contracts";
+import { defaultGitNetworkProcessRunner, defaultGitProcessRunner, } from "../gitRoutes.js";
+import { parsePorcelainV2Branch } from "../gitPorcelainStatus.js";
+const DEFAULT_SYNC_MAX_BYTES = 128 * 1024;
+const DEFAULT_SYNC_TIMEOUT_MS = 30_000;
+// An injected `seams.runner` overrides BOTH runners so tests stay deterministic; in production the
+// local reads use the hardened `defaultGitProcessRunner` while the fetch/pull command uses the
+// credential-capable `defaultGitNetworkProcessRunner` (see networkGitEnv in gitRoutes.ts).
+function normalizeSeams(seams) {
+    return {
+        readRunner: seams.runner ?? defaultGitProcessRunner,
+        networkRunner: seams.runner ?? defaultGitNetworkProcessRunner,
+        maxBytes: seams.maxBytes ?? DEFAULT_SYNC_MAX_BYTES,
+        timeoutMs: seams.timeoutMs ?? DEFAULT_SYNC_TIMEOUT_MS,
+    };
+}
+function runWith(runner, repoRoot, seams, args) {
+    return runner(["--no-pager", "--no-optional-locks", "-C", repoRoot, ...args], {
+        cwd: repoRoot,
+        maxBytes: seams.maxBytes,
+        timeoutMs: seams.timeoutMs,
+    });
+}
+// Local read (status / remote / post-op re-read): config-isolated, never authenticates.
+function runGit(repoRoot, seams, args) {
+    return runWith(seams.readRunner, repoRoot, seams, args);
+}
+// The actual fetch/pull network command: credential-capable env, still GIT_TERMINAL_PROMPT=0.
+function runNetworkGit(repoRoot, seams, args) {
+    return runWith(seams.networkRunner, repoRoot, seams, args);
+}
+// `git remote` (names only — never URLs) tells us whether a fetch target exists at all.
+function parseRemoteNames(stdout) {
+    return stdout
+        .split(/\r?\n/u)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0);
+}
+// --- preview ---------------------------------------------------------------
+function hasRequestedRemote(remoteNames, remote) {
+    return remote === undefined ? remoteNames.length > 0 : remoteNames.includes(remote);
+}
+function previewBlockReason(operation, status, hasRemote) {
+    if (!hasRemote)
+        return "no-remote";
+    if (operation === "fetch")
+        return undefined;
+    if (status.detached)
+        return "detached-head";
+    if (status.upstream === undefined)
+        return "no-upstream";
+    return undefined;
+}
+function previewFor(operation, status, remote, hasRemote) {
+    const blockReason = previewBlockReason(operation, status, hasRemote);
+    return {
+        schemaVersion: GIT_SYNC_SCHEMA_VERSION,
+        operation,
+        available: true,
+        state: "available",
+        branch: status.branch,
+        detached: status.detached,
+        upstream: status.upstream,
+        remote,
+        ahead: status.ahead,
+        behind: status.behind,
+        hasRemote,
+        hasUpstream: status.upstream !== undefined,
+        dirty: status.dirty,
+        executable: blockReason === undefined,
+        blockReason,
+    };
+}
+/**
+ * Read-only fetch/pull readiness. Runs `status --porcelain=v2 --branch -z` + `git remote` (names only)
+ * and projects a content-free preview with an executable gate. Throws only when the status read fails
+ * (not a repository / unsafe owner); the caller maps that to a 409.
+ */
+export async function buildSyncPreview(operation, repoRoot, remote, seams = {}) {
+    const normalized = normalizeSeams(seams);
+    const status = await runGit(repoRoot, normalized, [
+        "status",
+        "--porcelain=v2",
+        "--branch",
+        "-z",
+        "--untracked-files=all",
+    ]);
+    if (status.exitCode !== 0) {
+        throw new Error("git status failed for the sync preview");
+    }
+    const parsed = parsePorcelainV2Branch(status.stdout);
+    const remotesResult = await runGit(repoRoot, normalized, ["remote"]);
+    const remoteNames = remotesResult.exitCode === 0 ? parseRemoteNames(remotesResult.stdout) : [];
+    return previewFor(operation, parsed, remote, hasRequestedRemote(remoteNames, remote));
+}
+function syncArgs(operation, remote) {
+    const remoteArgs = remote === undefined ? [] : [remote];
+    return operation === "fetch"
+        ? ["fetch", "--no-tags", ...remoteArgs]
+        : ["pull", "--ff-only", "--no-edit", ...remoteArgs];
+}
+// Classifies the most-specific failure the stderr surfaces. Order matters: ownership, host trust, and
+// auth checks precede generic remote/repository checks so trust and credential failures stay precise.
+function isUnsafeRepositoryStderr(text) {
+    return text.includes("dubious ownership") || text.includes("safe.directory");
+}
+function isUntrustedHostKeyStderr(text) {
+    return (text.includes("host key verification failed") ||
+        text.includes("remote host identification has changed") ||
+        text.includes("strict host key checking") ||
+        text.includes("offending key"));
+}
+function isAuthFailedStderr(text) {
+    return (text.includes("could not read username") ||
+        text.includes("authentication failed") ||
+        text.includes("permission denied") ||
+        text.includes("could not read from remote") ||
+        text.includes("terminal prompts disabled"));
+}
+function isNoRemoteStderr(text) {
+    return text.includes("no such remote") || text.includes("does not appear to be a git repository");
+}
+function classifyStderr(stderr) {
+    const text = stderr.toLowerCase();
+    if (isUnsafeRepositoryStderr(text))
+        return "unsafe-repository";
+    if (isUntrustedHostKeyStderr(text))
+        return "untrusted-host-key";
+    if (isAuthFailedStderr(text))
+        return "auth-failed";
+    if (isNoRemoteStderr(text))
+        return "no-remote";
+    return undefined;
+}
+// Pull-only refusal reasons layered on top of the shared classifier.
+function classifyPullStderr(stderr) {
+    const text = stderr.toLowerCase();
+    // A pull on a detached HEAD aborts with "You are not currently on a branch." — the execute-side
+    // mirror of the preview block reason, keeping the sync taxonomy fully live from execute.
+    if (text.includes("not currently on a branch"))
+        return "detached-head";
+    if (text.includes("there is no tracking information") ||
+        text.includes("no tracking information for the current branch")) {
+        return "no-upstream";
+    }
+    if (text.includes("not possible to fast-forward"))
+        return "not-fast-forward";
+    if (text.includes("local changes") || text.includes("would be overwritten")) {
+        return "dirty-worktree";
+    }
+    return undefined;
+}
+function isAlreadyUpToDate(stdout) {
+    return stdout.toLowerCase().includes("already up to date");
+}
+function classifyOutcome(operation, result) {
+    if (result.truncated)
+        return "timeout";
+    if (result.exitCode === 127)
+        return "git-missing";
+    const shared = classifyStderr(result.stderr);
+    if (shared !== undefined)
+        return shared;
+    if (operation === "pull") {
+        const pullReason = classifyPullStderr(result.stderr);
+        if (pullReason !== undefined)
+            return pullReason;
+    }
+    if (result.exitCode === 0) {
+        if (operation === "pull" && isAlreadyUpToDate(result.stdout))
+            return "up-to-date";
+        return "succeeded";
+    }
+    return "git-error";
+}
+function isSettledOk(outcome) {
+    return outcome === "succeeded" || outcome === "up-to-date";
+}
+function blockedOutcomeFor(preview) {
+    switch (preview.blockReason) {
+        case "no-remote":
+            return "no-remote";
+        case "no-upstream":
+            return "no-upstream";
+        case "detached-head":
+            return "detached-head";
+        case "git-missing":
+            return "git-missing";
+        case "unsafe-repository":
+            return "unsafe-repository";
+        case "unavailable":
+        case undefined:
+            return "git-error";
+    }
+}
+function blockedResultFor(preview) {
+    return {
+        outcome: blockedOutcomeFor(preview),
+        branch: preview.branch,
+        upstream: preview.upstream,
+        ahead: preview.ahead,
+        behind: preview.behind,
+        truncated: false,
+    };
+}
+// Re-reads branch/upstream/ahead/behind after a settled op so the response reflects the post-sync
+// position. Best-effort: any failure tolerates and omits the counts.
+async function readPostState(repoRoot, seams) {
+    try {
+        const status = await runGit(repoRoot, seams, [
+            "status",
+            "--porcelain=v2",
+            "--branch",
+            "-z",
+            "--untracked-files=all",
+        ]);
+        if (status.exitCode !== 0)
+            return {};
+        const parsed = parsePorcelainV2Branch(status.stdout);
+        return {
+            branch: parsed.branch,
+            upstream: parsed.upstream,
+            ahead: parsed.ahead,
+            behind: parsed.behind,
+        };
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Runs ONE bounded fetch/pull and classifies the outcome. Never governs (no kernel, no policy) — the
+ * control surface is the fixed argv + hardened env of the reused runner. After a settled op the
+ * branch/upstream/ahead/behind are re-read best-effort for the response.
+ */
+export async function runSyncExecute(operation, repoRoot, remote, seams = {}, preflight) {
+    const normalized = normalizeSeams(seams);
+    const preview = preflight ?? (await buildSyncPreview(operation, repoRoot, remote, seams));
+    if (!preview.executable)
+        return blockedResultFor(preview);
+    // ONLY the network fetch/pull uses the credential-capable runner; the post-state re-read below
+    // stays on the hardened local read runner.
+    const result = await runNetworkGit(repoRoot, normalized, syncArgs(operation, remote));
+    const outcome = classifyOutcome(operation, result);
+    if (!isSettledOk(outcome)) {
+        return { outcome, truncated: result.truncated };
+    }
+    const post = await readPostState(repoRoot, normalized);
+    return { outcome, ...post, truncated: result.truncated };
+}

package/dist/gitDelivery/syncRoutes.d.ts

@@ -0,0 +1,13 @@
+import type { GitSyncOperation } from "@oscharko-dev/keiko-contracts";
+import type { RouteContext, RouteDefinition, RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+import { type GitDeliverySyncSeams } from "./syncExecution.js";
+export type GitDeliverySyncErrorCode = "GIT_DELIVERY_SYNC_BAD_REQUEST" | "GIT_DELIVERY_SYNC_PAYLOAD_TOO_LARGE" | "GIT_DELIVERY_SYNC_FORBIDDEN_PAYLOAD" | "GIT_DELIVERY_SYNC_UNKNOWN_PROJECT" | "GIT_DELIVERY_SYNC_WORKTREE_UNAVAILABLE";
+export interface GitDeliverySyncRouteOptions {
+    readonly execution?: GitDeliverySyncSeams;
+}
+export declare const createHandleSyncPreview: (operation: GitSyncOperation, options?: GitDeliverySyncRouteOptions) => ((ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>);
+export declare const createHandleSyncExecute: (operation: GitSyncOperation, options?: GitDeliverySyncRouteOptions) => ((ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>);
+export declare const createGitDeliverySyncRouteGroup: (options?: GitDeliverySyncRouteOptions) => readonly RouteDefinition[];
+export declare const GIT_DELIVERY_SYNC_ROUTE_GROUP: readonly RouteDefinition[];
+//# sourceMappingURL=syncRoutes.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"syncRoutes.d.ts","sourceRoot":"","sources":["../../src/gitDelivery/syncRoutes.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAEV,gBAAgB,EAEjB,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;AAWhD,OAAO,EAGL,KAAK,oBAAoB,EAE1B,MAAM,oBAAoB,CAAC;AAU5B,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,oBAAoB,CAAC;CAC3C;AA4ED,eAAO,MAAM,uBAAuB,GAClC,WAAW,gBAAgB,EAC3B,UAAS,2BAAgC,KACxC,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAiBnE,CAAC;AAkDF,eAAO,MAAM,uBAAuB,GAClC,WAAW,gBAAgB,EAC3B,UAAS,2BAAgC,KACxC,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAgCnE,CAAC;AAIF,eAAO,MAAM,+BAA+B,GAC1C,UAAS,2BAAgC,KACxC,SAAS,eAAe,EAqB1B,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,SAAS,eAAe,EACjC,CAAC"}

package/dist/gitDelivery/syncRoutes.js

@@ -0,0 +1,200 @@
+// Governed fetch/pull sync routes: read-only preview + bounded execute (Issue #1573, Epic #1572).
+//
+//   * POST /api/git-delivery/{fetch,pull}/preview  — READ-ONLY. Projects the sync readiness envelope
+//       (branch / upstream / ahead / behind / hasRemote / hasUpstream / dirty + an executable gate and
+//       typed blockReason). Never mutates, never records evidence.
+//   * POST /api/git-delivery/{fetch,pull}/execute  — Requires an executable preview before running
+//       ONE bounded fetch/pull through the credential-capable runner (NOT the #472 kernel —
+//       fetch/pull have no GitDeliveryActionKind) and appends a content-free sync evidence record for
+//       the terminal outcome.
+//
+// Mirrors pushRoutes.ts: the same bounded body read, allowed-key whitelist, credential-shape +
+// unsafe-format-char scans, isSafeGitRef operand guard plus configured-remote preflight,
+// content-free typed error envelope, and a `createGitDeliverySyncRouteGroup(options)` factory with
+// an injectable execution seam. CSRF + JSON
+// content type are enforced CENTRALLY by server.ts for POST, so they are NOT re-checked here.
+import { GIT_SYNC_SCHEMA_VERSION } from "@oscharko-dev/keiko-contracts";
+import { resolveProjectWorkspace } from "./execution.js";
+import { GitDeliveryBodyTooLargeError, hasOnlyAllowedKeys, isNonEmptyString, isPlainObject, readGitDeliveryBody, scanForbiddenStrings, scanUnsafeFormatChars, } from "./requestGuards.js";
+import { buildSyncPreview, runSyncExecute, } from "./syncExecution.js";
+import { gitSyncRepoIdHash, recordGitSyncEvidence, GIT_SYNC_EVIDENCE_SCHEMA_VERSION, } from "./syncEvidence.js";
+const SAFE_MESSAGES = {
+    GIT_DELIVERY_SYNC_BAD_REQUEST: "The request body is not a valid git sync request.",
+    GIT_DELIVERY_SYNC_PAYLOAD_TOO_LARGE: "The git sync request exceeds the maximum size.",
+    GIT_DELIVERY_SYNC_FORBIDDEN_PAYLOAD: "The request contained a forbidden field. Requests may not carry credentials, headers, or URLs.",
+    GIT_DELIVERY_SYNC_UNKNOWN_PROJECT: "The requested project is not a known workspace.",
+    GIT_DELIVERY_SYNC_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_SYNC_PAYLOAD_TOO_LARGE")
+            : errResult(400, "GIT_DELIVERY_SYNC_BAD_REQUEST");
+        return { ok: false, result };
+    }
+    try {
+        return { ok: true, value: JSON.parse(raw) };
+    }
+    catch {
+        return { ok: false, result: errResult(400, "GIT_DELIVERY_SYNC_BAD_REQUEST") };
+    }
+}
+// A remote alias operand: non-empty, no whitespace, no leading "-" (flag-injection guard), no ":"
+// (refspec-injection guard), no NUL. Defence-in-depth so a malformed remote is a clean 400 rather than
+// an internal execution error.
+// 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 ALLOWED_KEYS = new Set(["schemaVersion", "projectId", "remote"]);
+// The credential-shape + unsafe-format-char boundary scans. Returns the typed error RouteResult or
+// undefined when the payload is clean.
+function scanError(parsed) {
+    if (scanForbiddenStrings(parsed)) {
+        return errResult(400, "GIT_DELIVERY_SYNC_FORBIDDEN_PAYLOAD");
+    }
+    if (scanUnsafeFormatChars(parsed)) {
+        return errResult(400, "GIT_DELIVERY_SYNC_BAD_REQUEST");
+    }
+    return undefined;
+}
+function validate(parsed) {
+    const bad = { kind: "err", result: errResult(400, "GIT_DELIVERY_SYNC_BAD_REQUEST") };
+    if (!isPlainObject(parsed) || !hasOnlyAllowedKeys(parsed, ALLOWED_KEYS))
+        return bad;
+    if (parsed.schemaVersion !== GIT_SYNC_SCHEMA_VERSION || !isNonEmptyString(parsed.projectId)) {
+        return bad;
+    }
+    const scanErr = scanError(parsed);
+    if (scanErr !== undefined)
+        return { kind: "err", result: scanErr };
+    if (parsed.remote !== undefined && !isSafeGitRef(parsed.remote))
+        return bad;
+    return { kind: "ok", value: { projectId: parsed.projectId, remote: parsed.remote } };
+}
+// ─── Preview handler (read-only) ────────────────────────────────────────────────────────────────
+export const createHandleSyncPreview = (operation, 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, remote } = validation.value;
+        const workspace = resolveProjectWorkspace(deps, projectId);
+        if (workspace === undefined)
+            return errResult(404, "GIT_DELIVERY_SYNC_UNKNOWN_PROJECT");
+        try {
+            const preview = await buildSyncPreview(operation, workspace.root, remote, seams);
+            return { status: 200, body: deps.redactor(preview) };
+        }
+        catch {
+            return errResult(409, "GIT_DELIVERY_SYNC_WORKTREE_UNAVAILABLE");
+        }
+    };
+};
+// ─── Execute handler (bounded fetch/pull) ───────────────────────────────────────────────────────
+function redactStringFor(deps) {
+    return (input) => deps.redactor(input);
+}
+function executeResponse(operation, remote, result) {
+    return {
+        schemaVersion: GIT_SYNC_SCHEMA_VERSION,
+        operation,
+        status: result.outcome,
+        available: true,
+        branch: result.branch,
+        upstream: result.upstream,
+        remote,
+        ahead: result.ahead,
+        behind: result.behind,
+        truncated: result.truncated,
+    };
+}
+function evidenceRecord(operation, remote, repoIdHash, before, result, recordedAtMs) {
+    return {
+        schemaVersion: GIT_SYNC_EVIDENCE_SCHEMA_VERSION,
+        operation,
+        outcome: result.outcome,
+        repoIdHash,
+        branch: result.branch ?? before?.branch,
+        remote,
+        aheadBefore: before?.ahead,
+        behindBefore: before?.behind,
+        aheadAfter: result.ahead,
+        behindAfter: result.behind,
+        recordedAtMs,
+    };
+}
+export const createHandleSyncExecute = (operation, 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, remote } = validation.value;
+        const workspace = resolveProjectWorkspace(deps, projectId);
+        if (workspace === undefined)
+            return errResult(404, "GIT_DELIVERY_SYNC_UNKNOWN_PROJECT");
+        let before;
+        try {
+            before = await buildSyncPreview(operation, workspace.root, remote, seams);
+        }
+        catch {
+            return errResult(409, "GIT_DELIVERY_SYNC_WORKTREE_UNAVAILABLE");
+        }
+        const result = await runSyncExecute(operation, workspace.root, remote, seams, before);
+        const record = evidenceRecord(operation, remote, gitSyncRepoIdHash(workspace.root), before, result, now());
+        recordGitSyncEvidence({ evidenceStore: deps.evidenceStore, redactString: redactStringFor(deps) }, record);
+        return { status: 200, body: deps.redactor(executeResponse(operation, remote, result)) };
+    };
+};
+// ─── Route group ───────────────────────────────────────────────────────────────────────────────
+export const createGitDeliverySyncRouteGroup = (options = {}) => [
+    {
+        method: "POST",
+        pattern: "/api/git-delivery/fetch/preview",
+        handler: createHandleSyncPreview("fetch", options),
+    },
+    {
+        method: "POST",
+        pattern: "/api/git-delivery/fetch/execute",
+        handler: createHandleSyncExecute("fetch", options),
+    },
+    {
+        method: "POST",
+        pattern: "/api/git-delivery/pull/preview",
+        handler: createHandleSyncPreview("pull", options),
+    },
+    {
+        method: "POST",
+        pattern: "/api/git-delivery/pull/execute",
+        handler: createHandleSyncExecute("pull", options),
+    },
+];
+export const GIT_DELIVERY_SYNC_ROUTE_GROUP = createGitDeliverySyncRouteGroup();

package/dist/gitPorcelainStatus.d.ts

@@ -0,0 +1,15 @@
+import type { GitUpstreamSummary } from "@oscharko-dev/keiko-contracts";
+export interface PorcelainV2Status {
+    readonly branch?: string | undefined;
+    readonly detached: boolean;
+    readonly upstream?: GitUpstreamSummary | undefined;
+    readonly ahead: number;
+    readonly behind: number;
+    readonly stagedCount: number;
+    readonly unstagedCount: number;
+    readonly untrackedCount: number;
+    readonly conflictedCount: number;
+    readonly dirty: boolean;
+}
+export declare function parsePorcelainV2Branch(stdout: string): PorcelainV2Status;
+//# sourceMappingURL=gitPorcelainStatus.d.ts.map

package/dist/gitPorcelainStatus.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitPorcelainStatus.d.ts","sourceRoot":"","sources":["../src/gitPorcelainStatus.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAExE,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACnD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAoFD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,iBAAiB,CA2BxE"}

package/dist/gitPorcelainStatus.js

@@ -0,0 +1,104 @@
+// Shared `git status --porcelain=v2 --branch -z` parser (Issue #1573, Epic #1572).
+// Pure parsing only: no process, no filesystem, no clock. Centralizing the porcelain-v2 XY
+// semantics keeps branch/ahead/behind and change-record counting audited in one place so the
+// summary read route and the fetch/pull sync preview consume identical logic.
+// Upstream ref splits on the first `/`: prefix is the remote, remainder the tracked branch.
+function parseUpstreamRef(ref) {
+    const slash = ref.indexOf("/");
+    if (slash <= 0 || slash >= ref.length - 1) {
+        return { ref };
+    }
+    return { ref, remote: ref.slice(0, slash), branch: ref.slice(slash + 1) };
+}
+function parseAheadBehind(value) {
+    let ahead = 0;
+    let behind = 0;
+    for (const token of value.split(/\s+/u).filter((entry) => entry.length > 0)) {
+        const magnitude = Number.parseInt(token.slice(1), 10);
+        if (Number.isNaN(magnitude))
+            continue;
+        if (token.startsWith("+"))
+            ahead = magnitude;
+        else if (token.startsWith("-"))
+            behind = magnitude;
+    }
+    return { ahead, behind };
+}
+function applyHeader(record, headers) {
+    const body = record.slice(2).trim();
+    if (body.startsWith("branch.head ")) {
+        const name = body.slice("branch.head ".length).trim();
+        if (name === "(detached)")
+            headers.detached = true;
+        else if (name.length > 0)
+            headers.branch = name;
+        return;
+    }
+    if (body.startsWith("branch.upstream ")) {
+        const ref = body.slice("branch.upstream ".length).trim();
+        if (ref.length > 0)
+            headers.upstream = parseUpstreamRef(ref);
+        return;
+    }
+    if (body.startsWith("branch.ab ")) {
+        const parsed = parseAheadBehind(body.slice("branch.ab ".length));
+        headers.ahead = parsed.ahead;
+        headers.behind = parsed.behind;
+    }
+}
+// Ordinary (`1`) and rename/copy (`2`) records carry XY at field offset 2..4 of the
+// space-split tokens: X = index (staged) status, Y = worktree (unstaged) status.
+function applyOrdinaryChange(record, counts) {
+    const xy = record.split(" ")[1] ?? "..";
+    const index = xy[0] ?? ".";
+    const worktree = xy[1] ?? ".";
+    if (index !== ".")
+        counts.staged += 1;
+    if (worktree !== ".")
+        counts.unstaged += 1;
+}
+function applyChangeRecord(record, counts) {
+    if (record.startsWith("1 ") || record.startsWith("2 ")) {
+        applyOrdinaryChange(record, counts);
+    }
+    else if (record.startsWith("u ")) {
+        counts.conflicted += 1;
+    }
+    else if (record.startsWith("? ")) {
+        counts.untracked += 1;
+    }
+}
+// Rename/copy (`2`) records are followed by an extra NUL-separated original-path field that must
+// be skipped so it is never mistaken for a change record.
+function isRenameRecord(record) {
+    return record.startsWith("2 ");
+}
+export function parsePorcelainV2Branch(stdout) {
+    const records = stdout.split("\0").filter((record) => record.length > 0);
+    const headers = { detached: false, ahead: 0, behind: 0 };
+    const counts = { staged: 0, unstaged: 0, untracked: 0, conflicted: 0 };
+    let changeRecords = 0;
+    for (let index = 0; index < records.length; index += 1) {
+        const record = records[index] ?? "";
+        if (record.startsWith("# ")) {
+            applyHeader(record, headers);
+            continue;
+        }
+        applyChangeRecord(record, counts);
+        changeRecords += 1;
+        if (isRenameRecord(record))
+            index += 1;
+    }
+    return {
+        branch: headers.branch,
+        detached: headers.detached,
+        upstream: headers.upstream,
+        ahead: headers.ahead,
+        behind: headers.behind,
+        stagedCount: counts.staged,
+        unstagedCount: counts.unstaged,
+        untrackedCount: counts.untracked,
+        conflictedCount: counts.conflicted,
+        dirty: changeRecords > 0,
+    };
+}

package/dist/gitRepositoryReads.d.ts

@@ -0,0 +1,10 @@
+import type { GitHistoryEntry, GitRemoteSummary } from "@oscharko-dev/keiko-contracts";
+import { type GitRouteOptions } from "./gitRoutes.js";
+import type { RouteContext, RouteResult } from "./routes.js";
+import type { UiHandlerDeps } from "./deps.js";
+export declare function parseRemotes(stdout: string): readonly GitRemoteSummary[];
+export declare function handleGitSummary(ctx: RouteContext, deps: UiHandlerDeps, rawOptions?: GitRouteOptions): Promise<RouteResult>;
+export declare function handleGitRemotes(ctx: RouteContext, deps: UiHandlerDeps, rawOptions?: GitRouteOptions): Promise<RouteResult>;
+export declare function parseHistory(stdout: string): readonly GitHistoryEntry[];
+export declare function handleGitHistory(ctx: RouteContext, deps: UiHandlerDeps, rawOptions?: GitRouteOptions): Promise<RouteResult>;
+//# sourceMappingURL=gitRepositoryReads.d.ts.map

package/dist/gitRepositoryReads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gitRepositoryReads.d.ts","sourceRoot":"","sources":["../src/gitRepositoryReads.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,eAAe,EAGf,gBAAgB,EAMjB,MAAM,+BAA+B,CAAC;AAKvC,OAAO,EAML,KAAK,eAAe,EAGrB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AA4B/C,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,gBAAgB,EAAE,CAqBxE;AA0GD,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,EACnB,UAAU,CAAC,EAAE,eAAe,GAC3B,OAAO,CAAC,WAAW,CAAC,CA2BtB;AAID,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,EACnB,UAAU,CAAC,EAAE,eAAe,GAC3B,OAAO,CAAC,WAAW,CAAC,CA2BtB;AA4CD,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,eAAe,EAAE,CAMvE;AAgED,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,EACnB,UAAU,CAAC,EAAE,eAAe,GAC3B,OAAO,CAAC,WAAW,CAAC,CAgCtB"}