@oscharko-dev/keiko-tools 0.2.8 → 0.2.9

package/dist/git-mutation-taxonomy.js

@@ -0,0 +1,102 @@
+// Orchestration-level lifecycle and failure taxonomy for governed Git writes
+// (Issue #472, Epic #470). This module sits ABOVE the keiko-contracts git-delivery wire types.
+//
+// The contract layer (Issue #471) names two low-level vocabularies: execution error codes
+// (`GitDeliveryExecutionErrorCode`) and policy block reasons (`GitDeliveryBlockReason`). This
+// module names the orchestration-level concepts the contract layer deliberately left to the
+// execution kernel:
+//
+//   1. The canonical, ordered LIFECYCLE PHASES every governed mutation advances through (AC1).
+//   2. The five FAILURE CATEGORIES that approval UX, evidence capture, and recovery logic consume
+//      WITHOUT string parsing (AC4).
+//   3. Deterministic, total mappings from the contract's low-level error codes to those categories,
+//      so later slices never re-derive severity from a free-form message.
+//
+// Pure module: type literals, frozen const tables, and total pure functions only. No IO, no clock,
+// no randomness. Imports only type-level names from keiko-contracts. Relative imports end in ".js".
+export const GIT_MUTATION_LIFECYCLE_PHASES = [
+    "resolve",
+    "preflight",
+    "preview",
+    "policy",
+    "execute",
+    "result",
+];
+// Ordinal phase order. Higher ordinal = later in the lifecycle. Callers compare progress by ordinal
+// (never by phase-name string) so "did execution start?" is `GIT_MUTATION_PHASE_ORDER[reached] >=
+// GIT_MUTATION_PHASE_ORDER["execute"]`.
+export const GIT_MUTATION_PHASE_ORDER = {
+    resolve: 0,
+    preflight: 1,
+    preview: 2,
+    policy: 3,
+    execute: 4,
+    result: 5,
+};
+export const GIT_MUTATION_FAILURE_CATEGORIES = [
+    "policy-block",
+    "preflight-block",
+    "execution-failure",
+    "provider-failure",
+    "recovery-required",
+];
+export const GIT_MUTATION_STATUSES = [
+    "succeeded",
+    "approval-required",
+    "blocked",
+    "failed",
+    "recovery-required",
+];
+// ─── Deterministic execution-error classification ───────────────────────────────────────
+// Total mapping from the closed contract error-code union to a failure category. Keyed exhaustively
+// so adding a new GitDeliveryExecutionErrorCode forces a compile error here (the Record is not
+// Partial), guaranteeing every code has an explicit category and the kernel never falls back to a
+// string heuristic.
+//
+//   provider-rejected / network-failure → provider-failure   (the remote refused or was unreachable)
+//   conflict / precondition-failed      → recovery-required   (a guided fix path exists; re-resolve)
+//   timeout / internal-error            → execution-failure   (transient or internal; safe to retry)
+const EXECUTION_ERROR_CATEGORY = {
+    "provider-rejected": "provider-failure",
+    "network-failure": "provider-failure",
+    conflict: "recovery-required",
+    "precondition-failed": "recovery-required",
+    timeout: "execution-failure",
+    "internal-error": "execution-failure",
+};
+export function gitMutationCategoryForExecutionError(code) {
+    return EXECUTION_ERROR_CATEGORY[code];
+}
+// Classifies a finished adapter execution result. A `succeeded` / `partial` / `aborted` outcome with
+// no error code is not a failure and returns undefined; otherwise the error code's category is
+// returned. `partial` and `aborted` outcomes that DO carry an error code are classified by that
+// code, so a partially-applied mutation that failed mid-flight is categorized rather than silently
+// treated as success.
+export function gitMutationCategoryForExecutionResult(result) {
+    if (result.outcome === "succeeded") {
+        return undefined;
+    }
+    if (result.errorCode === undefined) {
+        // `failed` with no code is an internal contract violation upstream; classify conservatively so
+        // the kernel never emits a failed result with no category.
+        return result.outcome === "failed" ? "execution-failure" : undefined;
+    }
+    return gitMutationCategoryForExecutionError(result.errorCode);
+}
+// True when a failure category should route into the guided recovery workflow rather than a plain
+// retry. Only `recovery-required` does; the rest are retried or surfaced as a hard block/failure.
+export function gitMutationFailureIsRecoverable(category) {
+    return category === "recovery-required";
+}
+// ─── Guards ─────────────────────────────────────────────────────────────────────────────
+export function isGitMutationLifecyclePhase(value) {
+    return (typeof value === "string" &&
+        GIT_MUTATION_LIFECYCLE_PHASES.includes(value));
+}
+export function isGitMutationFailureCategory(value) {
+    return (typeof value === "string" &&
+        GIT_MUTATION_FAILURE_CATEGORIES.includes(value));
+}
+export function isGitMutationStatus(value) {
+    return typeof value === "string" && GIT_MUTATION_STATUSES.includes(value);
+}

package/dist/git-pr-gateway.d.ts

@@ -0,0 +1,101 @@
+import type { GitDeliveryApprovalRequirement, GitDeliveryBlockReason, GitDeliveryExecutionResult, GitDeliveryOrgPolicyPack, GitDeliveryPolicyDecision, GitDeliveryProviderCapability, GitDeliveryRecoveryActionHint, GitDeliveryRecoveryDisposition, GitDeliveryRepoPolicyPack, GitPullRequestRejectionReason } from "@oscharko-dev/keiko-contracts";
+import { gitPrRejectionToErrorCode } from "@oscharko-dev/keiko-contracts";
+import type { CommandRule } from "@oscharko-dev/keiko-contracts";
+import type { GitWorktreeSnapshot } from "./git-mutation-preflight.js";
+import type { GitMutationLifecycleResult } from "./git-mutation-orchestrator.js";
+export interface GitPrCreateCommand {
+    readonly kind: "pr-create";
+    readonly ownerAndRepo: string;
+    readonly headBranchName: string;
+    readonly baseBranchName: string;
+    readonly title: string;
+    readonly body: string;
+    readonly isDraft: boolean;
+}
+export interface GitPrUpdateCommand {
+    readonly kind: "pr-update";
+    readonly ownerAndRepo: string;
+    readonly prExternalId: string;
+    readonly headBranchName: string;
+    readonly baseBranchName: string;
+    readonly title: string;
+    readonly body: string;
+    readonly convertToDraft: boolean;
+    readonly convertFromDraft: boolean;
+}
+export type GitPullRequestCommand = GitPrCreateCommand | GitPrUpdateCommand;
+export interface GitPrCreateExecRequest {
+    readonly ownerAndRepo: string;
+    readonly headBranchName: string;
+    readonly baseBranchName: string;
+    readonly title: string;
+    readonly body: string;
+    readonly isDraft: boolean;
+}
+export interface GitPrUpdateExecRequest {
+    readonly ownerAndRepo: string;
+    readonly prExternalId: string;
+    readonly baseBranchName: string;
+    readonly title: string;
+    readonly body: string;
+    readonly convertToDraft: boolean;
+    readonly convertFromDraft: boolean;
+}
+export interface GitPrExecResult extends GitDeliveryExecutionResult {
+    readonly rejectionReason?: GitPullRequestRejectionReason | undefined;
+    readonly createdPrExternalId?: string | undefined;
+}
+export interface GitPullRequestAdapter {
+    createPullRequest(req: GitPrCreateExecRequest): Promise<GitPrExecResult>;
+    updatePullRequest(req: GitPrUpdateExecRequest): Promise<GitPrExecResult>;
+}
+export declare const GIT_PULL_REQUEST_ALLOWED_SUBCOMMANDS: readonly string[];
+export declare const GIT_PULL_REQUEST_COMMAND_RULES: readonly CommandRule[];
+export declare class GitPrArgvError extends Error {
+    constructor(message: string);
+}
+export declare function buildPrCreateArgv(req: GitPrCreateExecRequest): readonly string[];
+export declare function buildPrUpdateArgv(req: GitPrUpdateExecRequest): readonly string[];
+export declare function buildPrMarkReadyGraphqlArgv(nodeId: string): readonly string[];
+export declare function buildPrConvertDraftGraphqlArgv(nodeId: string): readonly string[];
+export declare function gitPrArgvIsGoverned(argv: readonly string[]): boolean;
+export declare function classifyGitPullRequestRejection(output: string): GitPullRequestRejectionReason;
+export interface GitPullRequestRejection {
+    readonly reason: GitPullRequestRejectionReason;
+    readonly disposition: GitDeliveryRecoveryDisposition;
+    readonly actionHint?: GitDeliveryRecoveryActionHint | undefined;
+}
+export declare function gitPullRequestRejectionFor(reason: GitPullRequestRejectionReason): GitPullRequestRejection;
+export interface GitPullRequestEffectivePolicy {
+    readonly outcome: "allowed" | "blocked" | "approval-gated";
+    readonly blockReason?: GitDeliveryBlockReason | undefined;
+}
+export declare function evaluateGitPullRequestEffectivePolicy(decision: GitDeliveryPolicyDecision, baseTarget: string | undefined, capabilities: readonly GitDeliveryProviderCapability[], actionKind: "pr-create" | "pr-update"): GitPullRequestEffectivePolicy;
+export interface GitPullRequestRequest {
+    readonly command: GitPullRequestCommand;
+    readonly approval: GitDeliveryApprovalRequirement;
+}
+export interface GitPullRequestOrchestratorDeps {
+    readonly adapter: GitPullRequestAdapter;
+    readonly snapshot: GitWorktreeSnapshot;
+    readonly orgPolicyPack?: GitDeliveryOrgPolicyPack | undefined;
+    readonly repoPolicyPack?: GitDeliveryRepoPolicyPack | undefined;
+    readonly activeProviderCapabilities?: readonly GitDeliveryProviderCapability[] | undefined;
+    readonly now: () => number;
+    readonly newActionId: () => string;
+}
+export interface GitPullRequestLifecycleResult {
+    readonly lifecycle: GitMutationLifecycleResult;
+    readonly rejection?: GitPullRequestRejection | undefined;
+    readonly createdPrExternalId?: string | undefined;
+}
+/**
+ * Runs ONE governed pull request operation end-to-end: derive PR inputs → preflight (no local
+ * precondition) → preview → policy → (only when policy permits and any approval is satisfied) execute
+ * through the narrow PR adapter. Returns a kernel-shaped lifecycle result (so the #474 evidence builder
+ * records it unchanged) plus the live provider-rejection descriptor when the provider rejected the
+ * operation, and the provider-assigned PR number on a successful create.
+ */
+export declare function runGitPullRequest(request: GitPullRequestRequest, deps: GitPullRequestOrchestratorDeps): Promise<GitPullRequestLifecycleResult>;
+export { gitPrRejectionToErrorCode };
+//# sourceMappingURL=git-pr-gateway.d.ts.map

package/dist/git-pr-gateway.d.ts.map

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