@oscharko-dev/keiko-contracts 0.2.7 → 0.2.9

package/dist/git-pull-request.js

@@ -0,0 +1,351 @@
+// Governed GitHub pull request orchestration contracts (Issue #477, Epic #470; ADR-0064). Ownership:
+// the provider-neutral, content-free PR-orchestration leaf — the readiness model, the deterministic
+// metadata-synthesis heuristics, the reviewer/label/linkage suggestion shapes, and the provider-failure
+// rejection taxonomy. It is the PR counterpart of git-commit-intent.ts (deterministic composition) and
+// git-delivery-action-sheet.ts (content-free projection), and it sits on top of the existing PR input
+// shapes, provider-state interfaces, execution-error codes, and recovery-disposition vocabulary.
+//
+// Disjoint from git-delivery.ts (the action/risk model), git-delivery-provider.ts (provider-neutral
+// state), git-delivery-evidence.ts (the audit record), and git-delivery-action-sheet.ts (the approval
+// surface). The GitHub-specific transport, the raw-error classifier, and the actual PR title/body
+// strings are keiko-tools concerns; this leaf never imports a kernel type and never carries raw content.
+//
+// Leaf-package rules (ADR-0019, ADR-0058, ADR-0064): pure types, frozen const tables, and pure
+// functions only. No IO, no clock, no crypto, no randomness, no provider field names. Relative imports
+// end in ".js" and reference only sibling git-delivery*.ts leaves.
+//
+// Content-free by construction: the synthesizer's INPUTS are counts, coarse area tokens, typed enums,
+// and branch names — never raw diff content, file paths, or commit message bodies. The composed
+// title/body DRAFT it returns is user-editable and is NEVER persisted to evidence (evidence carries only
+// the titleByteLength / bodyByteLength already defined on the GitDeliveryPr*Inputs).
+// Pinned schema version. A breaking change adds a NEW literal member; this one is never mutated.
+export const GIT_PULL_REQUEST_SCHEMA_VERSION = "1";
+export const GIT_PR_CHANGE_TYPES = [
+    "feat",
+    "fix",
+    "refactor",
+    "docs",
+    "chore",
+    "test",
+    "mixed",
+];
+export const GIT_PR_POLICY_OUTCOMES = [
+    "allowed",
+    "blocked",
+    "approval-gated",
+    "constrained",
+];
+export const GIT_PR_READINESS_BLOCKER_CODES = [
+    "head-unpublished",
+    "base-missing",
+    "head-equals-base",
+    "draft-pr",
+    "required-checks-failing",
+    "checks-pending",
+    "approval-insufficient",
+    "merge-conflict",
+    "provider-error",
+];
+export const GIT_PR_RECOMMENDATIONS = [
+    "create-as-draft",
+    "create-as-ready",
+    "update-to-ready",
+    "keep-as-draft",
+    "blocked",
+];
+export const GIT_PR_REJECTION_REASONS = [
+    "already-exists",
+    "base-missing",
+    "head-unpublished",
+    "validation-error",
+    "permission-denied",
+    "not-found",
+    "rate-limited",
+    "provider-unavailable",
+    "unknown",
+];
+// Exhaustive reason → content-free execution error code (recorded in evidence). Total Record (not
+// Partial): a new reason is a compile error here rather than a silent gap.
+export const GIT_PR_REJECTION_ERROR_CODE = {
+    "already-exists": "precondition-failed",
+    "base-missing": "precondition-failed",
+    "head-unpublished": "precondition-failed",
+    "validation-error": "provider-rejected",
+    "permission-denied": "provider-rejected",
+    "not-found": "provider-rejected",
+    "rate-limited": "network-failure",
+    "provider-unavailable": "network-failure",
+    unknown: "provider-rejected",
+};
+// Exhaustive reason → three-way recovery disposition (reused #474 vocabulary).
+export const GIT_PR_REJECTION_DISPOSITION = {
+    "already-exists": "user-fixable",
+    "base-missing": "user-fixable",
+    "head-unpublished": "user-fixable",
+    "validation-error": "user-fixable",
+    "permission-denied": "user-fixable",
+    "not-found": "user-fixable",
+    "rate-limited": "retryable",
+    "provider-unavailable": "retryable",
+    unknown: "user-fixable",
+};
+export function gitPrRejectionToErrorCode(reason) {
+    return GIT_PR_REJECTION_ERROR_CODE[reason];
+}
+export function gitPrRejectionToDisposition(reason) {
+    return GIT_PR_REJECTION_DISPOSITION[reason];
+}
+// ─── Private predicate helpers ──────────────────────────────────────────────────────────────────────
+function isString(value) {
+    return typeof value === "string";
+}
+function isBoolean(value) {
+    return typeof value === "boolean";
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isInSet(set) {
+    return (v) => isString(v) && set.includes(v);
+}
+// ─── Exported enum guards ─────────────────────────────────────────────────────────────────────────
+export const isGitPrChangeType = isInSet(GIT_PR_CHANGE_TYPES);
+export const isGitPrPolicyOutcome = isInSet(GIT_PR_POLICY_OUTCOMES);
+export const isGitPullRequestReadinessBlockerCode = isInSet(GIT_PR_READINESS_BLOCKER_CODES);
+export const isGitPullRequestRecommendation = isInSet(GIT_PR_RECOMMENDATIONS);
+export const isGitPullRequestRejectionReason = isInSet(GIT_PR_REJECTION_REASONS);
+// ─── Metadata synthesis (PURE, deterministic) ───────────────────────────────────────────────────────
+// Title = `type(scope): <humanised head-branch slug>`, clamped to ≤ 72 code units. The slug strips the
+// branch namespace prefix and a leading `issue-<n>` token, then turns dashes into spaces. All inputs are
+// counts, enums, area tokens, and branch names — no raw content.
+const TITLE_MAX = 72;
+function primaryAreaOf(narrative) {
+    const first = narrative.areas[0];
+    return narrative.areaCount === 1 && first !== undefined && first.length > 0 ? first : undefined;
+}
+function humaniseBranchSlug(headBranch) {
+    const segments = headBranch.split("/");
+    const tail = segments[segments.length - 1] ?? headBranch;
+    const tokens = tail.split("-").filter((t) => t.length > 0);
+    // Drop a leading run of `issue` markers and pure-numeric issue numbers (e.g. "issue-477-…",
+    // "1234-…"), keeping only the descriptive remainder of the slug.
+    let start = 0;
+    while (start < tokens.length) {
+        const token = (tokens[start] ?? "").toLowerCase();
+        if (token === "issue" || /^[0-9]+$/.test(token)) {
+            start += 1;
+        }
+        else {
+            break;
+        }
+    }
+    return tokens.slice(start).join(" ").trim();
+}
+function clampTitle(title) {
+    return title.length <= TITLE_MAX ? title : title.slice(0, TITLE_MAX).trimEnd();
+}
+function composeTitle(narrative, headBranch) {
+    const scope = primaryAreaOf(narrative);
+    const prefix = scope !== undefined ? `${narrative.changeType}(${scope})` : narrative.changeType;
+    const slug = humaniseBranchSlug(headBranch);
+    const clause = slug.length > 0 ? slug : `update ${String(narrative.fileCount)} file(s)`;
+    return clampTitle(`${prefix}: ${clause}`);
+}
+function composeRiskNarrative(narrative, riskDigest) {
+    const testClause = narrative.touchesTests ? ", including test changes" : "";
+    return (`This change is classified ${riskDigest.riskClass} (severity ${String(riskDigest.riskSeverity)}); ` +
+        `policy outcome ${riskDigest.policyOutcome}. It spans ${String(narrative.fileCount)} file(s) across ` +
+        `${String(narrative.areaCount)} area(s) over ${String(narrative.commitCount)} commit(s)${testClause}.`);
+}
+export function synthesizePullRequestMetadata(narrative, riskDigest, headBranch, _baseBranch) {
+    const primaryArea = primaryAreaOf(narrative);
+    const summarySection = {
+        changeType: narrative.changeType,
+        commitCount: narrative.commitCount,
+        fileCount: narrative.fileCount,
+        areaCount: narrative.areaCount,
+        ...(primaryArea !== undefined ? { primaryArea } : {}),
+    };
+    return {
+        schemaVersion: GIT_PULL_REQUEST_SCHEMA_VERSION,
+        composedTitle: composeTitle(narrative, headBranch),
+        summarySection,
+        riskSection: {
+            riskClass: riskDigest.riskClass,
+            policyOutcome: riskDigest.policyOutcome,
+            requiresApproval: riskDigest.policyOutcome === "approval-gated",
+        },
+        changeNarrativeSection: {
+            touchesTests: narrative.touchesTests,
+            areas: narrative.areas,
+            changeType: narrative.changeType,
+        },
+        riskNarrative: composeRiskNarrative(narrative, riskDigest),
+    };
+}
+function blocking(code) {
+    return { code, severity: "blocking", remediation: "user-actionable" };
+}
+function advisory(code, remediation) {
+    return { code, severity: "advisory", remediation };
+}
+function collectBlockingBlockers(input) {
+    const out = [];
+    if (input.headBranchName === input.baseBranchName) {
+        out.push(blocking("head-equals-base"));
+    }
+    if (!input.headPublished) {
+        out.push(blocking("head-unpublished"));
+    }
+    if (!input.baseExists) {
+        out.push(blocking("base-missing"));
+    }
+    if (input.checks?.overallStatus === "failing") {
+        out.push(blocking("required-checks-failing"));
+    }
+    if (input.mergeReadiness?.blockingReason === "conflicts") {
+        out.push(blocking("merge-conflict"));
+    }
+    if (input.providerError === true) {
+        out.push({ code: "provider-error", severity: "blocking", remediation: "internal" });
+    }
+    return out;
+}
+function collectAdvisoryBlockers(input) {
+    const out = [];
+    if (input.pullRequest?.isDraft === true) {
+        out.push(advisory("draft-pr", "user-actionable"));
+    }
+    if (input.checks?.overallStatus === "pending") {
+        out.push(advisory("checks-pending", "internal"));
+    }
+    if (input.mergeReadiness?.blockingReason === "approvals-missing") {
+        out.push(advisory("approval-insufficient", "user-actionable"));
+    }
+    return out;
+}
+export function gitPullRequestReadinessFor(input) {
+    const blockingBlockers = collectBlockingBlockers(input);
+    const advisoryBlockers = collectAdvisoryBlockers(input);
+    const blockers = [...blockingBlockers, ...advisoryBlockers];
+    const objectExists = input.pullRequest !== undefined;
+    const isDraft = input.pullRequest?.isDraft === true;
+    const reviewReady = objectExists && !isDraft && blockingBlockers.length === 0;
+    return {
+        schemaVersion: GIT_PULL_REQUEST_SCHEMA_VERSION,
+        objectExists,
+        reviewReady,
+        blockers,
+    };
+}
+// ─── Recommendation derivation (PURE) ───────────────────────────────────────────────────────────────
+export function gitPullRequestRecommendationFor(readiness, riskDigest) {
+    const hasBlocking = readiness.blockers.some((b) => b.severity === "blocking");
+    if (hasBlocking) {
+        return "blocked";
+    }
+    if (!readiness.objectExists) {
+        return riskDigest.isDraft ? "create-as-draft" : "create-as-ready";
+    }
+    // The PR exists and has no blocking blockers. Advisory blockers (pending checks, missing approvals)
+    // counsel keeping it as a draft; a clean PR is recommended for the move to ready-for-review.
+    return readiness.blockers.length > 0 ? "keep-as-draft" : "update-to-ready";
+}
+// ─── Suggestion derivations (PURE, deterministic) ───────────────────────────────────────────────────
+const LABEL_BY_CHANGE_TYPE = {
+    feat: "enhancement",
+    fix: "bug",
+    refactor: "refactor",
+    docs: "documentation",
+    chore: "chore",
+    test: "test",
+    mixed: "enhancement",
+};
+// Optional area→owners map (e.g. derived server-side from CODEOWNERS). Absent ⇒ no reviewer derivation.
+export function gitPullRequestReviewerSuggestionsFor(narrative, areaOwners) {
+    if (areaOwners === undefined) {
+        return { suggestedReviewerIds: [], basis: "none" };
+    }
+    const ids = new Set();
+    for (const area of narrative.areas) {
+        for (const owner of areaOwners[area] ?? []) {
+            ids.add(owner);
+        }
+    }
+    return ids.size > 0
+        ? { suggestedReviewerIds: [...ids], basis: "area-ownership" }
+        : { suggestedReviewerIds: [], basis: "none" };
+}
+export function gitPullRequestLabelSuggestionsFor(narrative) {
+    const labels = new Set();
+    labels.add(LABEL_BY_CHANGE_TYPE[narrative.changeType]);
+    for (const area of narrative.areas) {
+        if (area.length > 0) {
+            labels.add(`area:${area}`);
+        }
+    }
+    return { suggestedLabelNames: [...labels], basis: "change-type" };
+}
+// Extracts issue-ref tokens from the head branch name only (e.g. "claude/issue-477-..." → "#477",
+// "fix/1234-..." → "#1234"). Deterministic; never scans commit bodies in this leaf.
+const BRANCH_ISSUE_RE = /(?:issue[-/])?(\d{1,7})/gi;
+export function gitPullRequestLinkageSuggestionsFor(headBranch) {
+    const refs = new Set();
+    for (const match of headBranch.matchAll(BRANCH_ISSUE_RE)) {
+        const digits = match[1];
+        if (digits !== undefined) {
+            refs.add(`#${digits}`);
+        }
+    }
+    return refs.size > 0
+        ? { suggestedIssueRefs: [...refs], basis: "branch-name" }
+        : { suggestedIssueRefs: [], basis: "none" };
+}
+// ─── Structural guards ──────────────────────────────────────────────────────────────────────────────
+export function isGitPullRequestReadinessBlocker(value) {
+    return (isRecord(value) &&
+        isGitPullRequestReadinessBlockerCode(value.code) &&
+        (value.severity === "blocking" || value.severity === "advisory") &&
+        (value.remediation === "user-actionable" || value.remediation === "internal"));
+}
+function isBlockerArray(value) {
+    return Array.isArray(value) && value.every(isGitPullRequestReadinessBlocker);
+}
+export function isGitPullRequestReadinessSummary(value) {
+    return (isRecord(value) &&
+        value.schemaVersion === GIT_PULL_REQUEST_SCHEMA_VERSION &&
+        isBoolean(value.objectExists) &&
+        isBoolean(value.reviewReady) &&
+        isBlockerArray(value.blockers));
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every(isString);
+}
+export function isGitPullRequestChangeNarrative(value) {
+    return (isRecord(value) &&
+        isNonNegativeInteger(value.commitCount) &&
+        isNonNegativeInteger(value.fileCount) &&
+        isNonNegativeInteger(value.areaCount) &&
+        isStringArray(value.areas) &&
+        isBoolean(value.touchesTests) &&
+        isGitPrChangeType(value.changeType));
+}
+export function isGitPullRequestMetadataDraft(value) {
+    return (isRecord(value) &&
+        value.schemaVersion === GIT_PULL_REQUEST_SCHEMA_VERSION &&
+        isString(value.composedTitle) &&
+        isRecord(value.summarySection) &&
+        isRecord(value.riskSection) &&
+        isRecord(value.changeNarrativeSection) &&
+        isString(value.riskNarrative));
+}
+// ─── Parse ──────────────────────────────────────────────────────────────────────────────────────────
+export function parseGitPullRequestReadinessSummary(value) {
+    if (!isGitPullRequestReadinessSummary(value)) {
+        return { ok: false, errors: ["value is not a valid GitPullRequestReadinessSummary"] };
+    }
+    return { ok: true, value };
+}

package/dist/git-repository-agent.d.ts

@@ -0,0 +1,46 @@
+export declare const GIT_REPOSITORY_AGENT_SCHEMA_VERSION: "1";
+export type GitRepositoryAgentOperationMode = "read" | "preview" | "execute";
+export declare const GIT_REPOSITORY_AGENT_OPERATION_MODES: readonly GitRepositoryAgentOperationMode[];
+export type GitRepositoryAgentOperationKind = "status" | "diff" | "branch-list" | "branch-create" | "branch-switch" | "stage" | "unstage" | "commit" | "fetch" | "pull" | "push" | "pull-request" | "merge";
+export declare const GIT_REPOSITORY_AGENT_OPERATION_KINDS: readonly GitRepositoryAgentOperationKind[];
+export type GitRepositoryAgentDenialReason = "unsupported-direct-shell" | "unsupported-operation" | "idempotency-conflict" | "bad-request";
+export declare const GIT_REPOSITORY_AGENT_DENIAL_REASONS: readonly GitRepositoryAgentDenialReason[];
+export interface GitRepositoryAgentOperationRequest {
+    readonly schemaVersion: typeof GIT_REPOSITORY_AGENT_SCHEMA_VERSION;
+    readonly operation: GitRepositoryAgentOperationKind;
+    readonly mode: GitRepositoryAgentOperationMode;
+    readonly projectId: string;
+    readonly idempotencyKey?: string | undefined;
+    readonly payload?: Readonly<Record<string, unknown>> | undefined;
+}
+export interface GitRepositoryAgentOperationDelegatedResponse {
+    readonly schemaVersion: typeof GIT_REPOSITORY_AGENT_SCHEMA_VERSION;
+    readonly operation: GitRepositoryAgentOperationKind;
+    readonly mode: GitRepositoryAgentOperationMode;
+    readonly status: "delegated";
+    readonly routeStatus: number;
+    readonly replay?: boolean | undefined;
+    readonly response: unknown;
+}
+export interface GitRepositoryAgentOperationDeniedResponse {
+    readonly schemaVersion: typeof GIT_REPOSITORY_AGENT_SCHEMA_VERSION;
+    readonly operation?: GitRepositoryAgentOperationKind | undefined;
+    readonly mode?: GitRepositoryAgentOperationMode | undefined;
+    readonly status: "denied";
+    readonly denialReason: GitRepositoryAgentDenialReason;
+    readonly message: string;
+}
+export type GitRepositoryAgentOperationResponse = GitRepositoryAgentOperationDelegatedResponse | GitRepositoryAgentOperationDeniedResponse;
+export interface GitRepositoryAgentParseOk {
+    readonly ok: true;
+    readonly value: GitRepositoryAgentOperationRequest;
+}
+export interface GitRepositoryAgentParseFail {
+    readonly ok: false;
+    readonly denialReason: GitRepositoryAgentDenialReason;
+    readonly message: string;
+}
+export type GitRepositoryAgentParseResult = GitRepositoryAgentParseOk | GitRepositoryAgentParseFail;
+export declare function parseGitRepositoryAgentOperationRequest(input: unknown): GitRepositoryAgentParseResult;
+export declare function isGitRepositoryAgentOperationResponse(input: unknown): input is GitRepositoryAgentOperationResponse;
+//# sourceMappingURL=git-repository-agent.d.ts.map

package/dist/git-repository-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-repository-agent.d.ts","sourceRoot":"","sources":["../src/git-repository-agent.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,mCAAmC,EAAG,GAAY,CAAC;AAEhE,MAAM,MAAM,+BAA+B,GAAG,MAAM,GAAG,SAAS,GAAG,SAAS,CAAC;AAE7E,eAAO,MAAM,oCAAoC,EAAE,SAAS,+BAA+B,EAIjF,CAAC;AAEX,MAAM,MAAM,+BAA+B,GACvC,QAAQ,GACR,MAAM,GACN,aAAa,GACb,eAAe,GACf,eAAe,GACf,OAAO,GACP,SAAS,GACT,QAAQ,GACR,OAAO,GACP,MAAM,GACN,MAAM,GACN,cAAc,GACd,OAAO,CAAC;AAEZ,eAAO,MAAM,oCAAoC,EAAE,SAAS,+BAA+B,EAcjF,CAAC;AAEX,MAAM,MAAM,8BAA8B,GACtC,0BAA0B,GAC1B,uBAAuB,GACvB,sBAAsB,GACtB,aAAa,CAAC;AAElB,eAAO,MAAM,mCAAmC,EAAE,SAAS,8BAA8B,EAK/E,CAAC;AAEX,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,aAAa,EAAE,OAAO,mCAAmC,CAAC;IACnE,QAAQ,CAAC,SAAS,EAAE,+BAA+B,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC;CAClE;AAED,MAAM,WAAW,4CAA4C;IAC3D,QAAQ,CAAC,aAAa,EAAE,OAAO,mCAAmC,CAAC;IACnE,QAAQ,CAAC,SAAS,EAAE,+BAA+B,CAAC;IACpD,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;IAC/C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,yCAAyC;IACxD,QAAQ,CAAC,aAAa,EAAE,OAAO,mCAAmC,CAAC;IACnE,QAAQ,CAAC,SAAS,CAAC,EAAE,+BAA+B,GAAG,SAAS,CAAC;IACjE,QAAQ,CAAC,IAAI,CAAC,EAAE,+BAA+B,GAAG,SAAS,CAAC;IAC5D,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,8BAA8B,CAAC;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,mCAAmC,GAC3C,4CAA4C,GAC5C,yCAAyC,CAAC;AAE9C,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,kCAAkC,CAAC;CACpD;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,YAAY,EAAE,8BAA8B,CAAC;IACtD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,6BAA6B,GACrC,yBAAyB,GACzB,2BAA2B,CAAC;AAsJhC,wBAAgB,uCAAuC,CACrD,KAAK,EAAE,OAAO,GACb,6BAA6B,CAwB/B;AAED,wBAAgB,qCAAqC,CACnD,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,mCAAmC,CAgB9C"}

package/dist/git-repository-agent.js

@@ -0,0 +1,198 @@
+// Agent-facing repository operation facade contract (Issue #1577, Epic #1571).
+// Pure wire types and validators only. The facade grants no shell, process, provider, credential, or
+// model authority; server handlers must delegate to existing Git read and Git delivery routes.
+export const GIT_REPOSITORY_AGENT_SCHEMA_VERSION = "1";
+export const GIT_REPOSITORY_AGENT_OPERATION_MODES = [
+    "read",
+    "preview",
+    "execute",
+];
+export const GIT_REPOSITORY_AGENT_OPERATION_KINDS = [
+    "status",
+    "diff",
+    "branch-list",
+    "branch-create",
+    "branch-switch",
+    "stage",
+    "unstage",
+    "commit",
+    "fetch",
+    "pull",
+    "push",
+    "pull-request",
+    "merge",
+];
+export const GIT_REPOSITORY_AGENT_DENIAL_REASONS = [
+    "unsupported-direct-shell",
+    "unsupported-operation",
+    "idempotency-conflict",
+    "bad-request",
+];
+const TOP_LEVEL_KEYS = new Set([
+    "schemaVersion",
+    "idempotencyKey",
+    "operation",
+    "mode",
+    "projectId",
+    "payload",
+]);
+const DIRECT_SHELL_KEYS = new Set([
+    "argv",
+    "args",
+    "body",
+    "command",
+    "credential",
+    "endpoint",
+    "cwd",
+    "env",
+    "executable",
+    "ghEndpoint",
+    "gitSubcommand",
+    "headers",
+    "method",
+    "providerPayload",
+    "providerState",
+    "repositoryRoot",
+    "root",
+    "script",
+    "shell",
+    "token",
+    "url",
+]);
+const MODE_BY_OPERATION = {
+    status: ["read"],
+    diff: ["read"],
+    "branch-list": ["read"],
+    "branch-create": ["execute"],
+    "branch-switch": ["execute"],
+    stage: ["execute"],
+    unstage: ["execute"],
+    commit: ["preview", "execute"],
+    fetch: ["preview", "execute"],
+    pull: ["preview", "execute"],
+    push: ["preview", "execute"],
+    "pull-request": ["preview", "execute"],
+    merge: ["preview", "execute"],
+};
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isOperation(value) {
+    return (typeof value === "string" &&
+        GIT_REPOSITORY_AGENT_OPERATION_KINDS.includes(value));
+}
+function isMode(value) {
+    return (typeof value === "string" &&
+        GIT_REPOSITORY_AGENT_OPERATION_MODES.includes(value));
+}
+function containsDirectShellShape(value) {
+    if (Array.isArray(value))
+        return value.some(containsDirectShellShape);
+    if (!isRecord(value))
+        return false;
+    for (const [key, child] of Object.entries(value)) {
+        if (DIRECT_SHELL_KEYS.has(key) || key.toLowerCase().includes("credential"))
+            return true;
+        if (containsDirectShellShape(child))
+            return true;
+    }
+    return false;
+}
+function parseFail(denialReason, message) {
+    return { ok: false, denialReason, message };
+}
+function validateEnvelope(input) {
+    if (!isRecord(input))
+        return parseFail("bad-request", "Request body must be an object.");
+    if (containsDirectShellShape(input)) {
+        return parseFail("unsupported-direct-shell", "Repository operations must use typed Git facade actions, not shell commands.");
+    }
+    for (const key of Object.keys(input)) {
+        if (!TOP_LEVEL_KEYS.has(key))
+            return parseFail("bad-request", "Request contains an extra field.");
+    }
+    if (input.schemaVersion !== GIT_REPOSITORY_AGENT_SCHEMA_VERSION) {
+        return parseFail("bad-request", "schemaVersion is invalid.");
+    }
+    return { ok: true, value: input };
+}
+function parseOperation(value) {
+    if (isOperation(value))
+        return value;
+    return parseFail("unsupported-operation", "Operation is not supported by the repository facade.");
+}
+function parseMode(operation, value) {
+    if (isMode(value) && MODE_BY_OPERATION[operation].includes(value))
+        return value;
+    return parseFail("bad-request", "Operation mode is invalid for this repository operation.");
+}
+function parseProjectId(value) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    return parseFail("bad-request", "projectId must be a string.");
+}
+function parseIdempotencyKey(mode, value) {
+    if (value !== undefined && (typeof value !== "string" || value.length === 0)) {
+        return parseFail("bad-request", "idempotencyKey must be a non-empty string.");
+    }
+    if (mode === "execute" && value === undefined) {
+        return parseFail("bad-request", "execute operations require an idempotencyKey.");
+    }
+    return value;
+}
+function parsePayload(value) {
+    if (value === undefined)
+        return undefined;
+    if (isRecord(value))
+        return value;
+    return parseFail("bad-request", "payload must be an object.");
+}
+function isParseFail(value) {
+    return isRecord(value) && value.ok === false;
+}
+export function parseGitRepositoryAgentOperationRequest(input) {
+    const envelope = validateEnvelope(input);
+    if (isParseFail(envelope))
+        return envelope;
+    const operation = parseOperation(envelope.value.operation);
+    if (isParseFail(operation))
+        return operation;
+    const mode = parseMode(operation, envelope.value.mode);
+    if (isParseFail(mode))
+        return mode;
+    const projectId = parseProjectId(envelope.value.projectId);
+    if (isParseFail(projectId))
+        return projectId;
+    const idempotencyKey = parseIdempotencyKey(mode, envelope.value.idempotencyKey);
+    if (isParseFail(idempotencyKey))
+        return idempotencyKey;
+    const payload = parsePayload(envelope.value.payload);
+    if (isParseFail(payload))
+        return payload;
+    return {
+        ok: true,
+        value: {
+            schemaVersion: GIT_REPOSITORY_AGENT_SCHEMA_VERSION,
+            operation,
+            mode,
+            projectId,
+            ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+            ...(payload === undefined ? {} : { payload }),
+        },
+    };
+}
+export function isGitRepositoryAgentOperationResponse(input) {
+    if (!isRecord(input))
+        return false;
+    if (input.schemaVersion !== GIT_REPOSITORY_AGENT_SCHEMA_VERSION)
+        return false;
+    if (input.status === "delegated") {
+        return isOperation(input.operation) && isMode(input.mode) && typeof input.routeStatus === "number";
+    }
+    if (input.status === "denied") {
+        return (typeof input.message === "string" &&
+            typeof input.denialReason === "string" &&
+            GIT_REPOSITORY_AGENT_DENIAL_REASONS.includes(input.denialReason));
+    }
+    return false;
+}

package/dist/git-repository-summary.d.ts

@@ -0,0 +1,54 @@
+import type { GitRepositoryState, GitUnavailableReason, GitRepositoryValidation } from "./git-repository.js";
+export declare const GIT_REPOSITORY_SUMMARY_SCHEMA_VERSION: "1";
+export interface GitRemoteSummary {
+    readonly name: string;
+    readonly fetchUrl?: string | undefined;
+    readonly pushUrl?: string | undefined;
+}
+export interface GitRepositorySummaryRemote {
+    readonly name: string;
+}
+export interface GitUpstreamSummary {
+    readonly ref: string;
+    readonly remote?: string | undefined;
+    readonly branch?: string | undefined;
+}
+export interface GitLastSyncMetadata {
+    readonly lastFetchAtMs?: number | undefined;
+}
+export interface GitRepositorySummary {
+    readonly schemaVersion: typeof GIT_REPOSITORY_SUMMARY_SCHEMA_VERSION;
+    readonly root: string;
+    readonly repositoryRoot?: string | undefined;
+    readonly state: GitRepositoryState;
+    readonly available: boolean;
+    readonly reason?: GitUnavailableReason | "unsafe-repository" | "git-error" | undefined;
+    readonly message?: string | undefined;
+    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 clean: boolean;
+    readonly remotes: readonly GitRepositorySummaryRemote[];
+    readonly lastSync?: GitLastSyncMetadata | undefined;
+    readonly truncated: boolean;
+}
+export interface GitRemotesResponse {
+    readonly schemaVersion: typeof GIT_REPOSITORY_SUMMARY_SCHEMA_VERSION;
+    readonly root: string;
+    readonly repositoryRoot?: string | undefined;
+    readonly state: GitRepositoryState;
+    readonly available: boolean;
+    readonly reason?: GitUnavailableReason | "unsafe-repository" | "git-error" | undefined;
+    readonly remotes: readonly GitRemoteSummary[];
+    readonly truncated: boolean;
+}
+export type GitRepositorySummaryValidation = GitRepositoryValidation;
+export declare function validateGitRepositorySummary(input: unknown): GitRepositoryValidation;
+export declare function validateGitRemotesResponse(input: unknown): GitRepositoryValidation;
+//# sourceMappingURL=git-repository-summary.d.ts.map

package/dist/git-repository-summary.d.ts.map

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