@oscharko-dev/keiko-tools 0.2.8 → 0.2.9

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

@@ -0,0 +1,72 @@
+import type { GitDeliveryApprovalRequirement, GitDeliveryBlockReason, GitDeliveryExecutionErrorCode, GitDeliveryExecutionResult, GitDeliveryOrgPolicyPack, GitDeliveryPolicyDecision, GitDeliveryProviderCapability, GitDeliveryPushInputs, GitDeliveryRecoveryActionHint, GitDeliveryRecoveryDisposition, GitDeliveryRepoPolicyPack } from "@oscharko-dev/keiko-contracts";
+import type { GitWorktreeSnapshot } from "./git-mutation-preflight.js";
+import type { GitMutationLifecycleResult } from "./git-mutation-orchestrator.js";
+import type { CommandRule } from "./types.js";
+export interface GitPushCommand {
+    readonly kind: "push";
+    readonly sourceBranchName: string;
+    readonly remoteAlias: string;
+    readonly remoteBranchName: string;
+    readonly forcePush: boolean;
+    readonly setUpstreamTracking: boolean;
+}
+export interface GitPublishExecRequest {
+    readonly sourceBranchName: string;
+    readonly remoteAlias: string;
+    readonly remoteBranchName: string;
+    readonly setUpstreamTracking: boolean;
+}
+export interface GitPublishExecResult extends GitDeliveryExecutionResult {
+    readonly rejectionReason?: GitPublishRejectionReason | undefined;
+}
+export interface GitRemotePublishAdapter {
+    publish(req: GitPublishExecRequest): Promise<GitPublishExecResult>;
+}
+export type GitPublishRejectionReason = "non-fast-forward" | "fetch-first" | "no-upstream" | "auth-failed" | "permission-denied" | "protected-ref" | "remote-unavailable" | "unknown";
+export declare const GIT_PUBLISH_REJECTION_REASONS: readonly GitPublishRejectionReason[];
+export declare function isGitPublishRejectionReason(value: unknown): value is GitPublishRejectionReason;
+export declare function classifyGitPublishRejection(output: string): GitPublishRejectionReason;
+export declare function gitPublishRejectionToErrorCode(reason: GitPublishRejectionReason): GitDeliveryExecutionErrorCode;
+export interface GitPublishRejection {
+    readonly reason: GitPublishRejectionReason;
+    readonly disposition: GitDeliveryRecoveryDisposition;
+    readonly actionHint?: GitDeliveryRecoveryActionHint | undefined;
+}
+export declare function gitPublishRejectionFor(reason: GitPublishRejectionReason): GitPublishRejection;
+export declare const GIT_PUBLISH_ALLOWED_SUBCOMMANDS: readonly string[];
+export declare const GIT_PUBLISH_COMMAND_RULES: readonly CommandRule[];
+export declare class GitPublishArgvError extends Error {
+    constructor(message: string);
+}
+export declare function buildPushArgv(command: GitPushCommand): readonly string[];
+export interface GitPublishRequest {
+    readonly command: GitPushCommand;
+    readonly approval: GitDeliveryApprovalRequirement;
+}
+export interface GitPublishOrchestratorDeps {
+    readonly adapter: GitRemotePublishAdapter;
+    readonly snapshot: GitWorktreeSnapshot;
+    readonly orgPolicyPack?: GitDeliveryOrgPolicyPack | undefined;
+    readonly repoPolicyPack?: GitDeliveryRepoPolicyPack | undefined;
+    readonly activeProviderCapabilities?: readonly GitDeliveryProviderCapability[] | undefined;
+    readonly now: () => number;
+    readonly newActionId: () => string;
+}
+export interface GitPublishLifecycleResult {
+    readonly lifecycle: GitMutationLifecycleResult;
+    readonly rejection?: GitPublishRejection | undefined;
+}
+export interface GitPublishEffectivePolicy {
+    readonly outcome: "allowed" | "blocked" | "approval-gated";
+    readonly blockReason?: GitDeliveryBlockReason | undefined;
+}
+export declare function evaluateGitPublishEffectivePolicy(decision: GitDeliveryPolicyDecision, target: string | undefined, capabilities: readonly GitDeliveryProviderCapability[], pushInputs: GitDeliveryPushInputs): GitPublishEffectivePolicy;
+/**
+ * Runs ONE governed publish end-to-end: derive push inputs → preflight (push case) → preview → policy →
+ * (only when preflight passes, policy permits, approval satisfied) execute through the narrow remote
+ * adapter. Returns a kernel-shaped lifecycle result (so the #474 evidence builder records it unchanged)
+ * plus the live publish-rejection descriptor when the remote rejected an executed push.
+ */
+export declare function runGitPublish(request: GitPublishRequest, deps: GitPublishOrchestratorDeps): Promise<GitPublishLifecycleResult>;
+export declare function gitPublishArgvIsGoverned(argv: readonly string[]): boolean;
+//# sourceMappingURL=git-publish-gateway.d.ts.map

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

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

package/dist/git-publish-gateway.js

@@ -0,0 +1,423 @@
+// The governed remote publish gateway (Issue #476, Epic #470) — AC1–AC5.
+//
+// This is the SEPARATE remote execution authority the #472 kernel deferred: its command-union comment
+// places remote kinds in "later slices (#476–#478) that extend this union and register their executors",
+// and its local adapter allowlist excludes network verbs because "remote and provider execution is a
+// later slice (#476–#478) behind a SEPARATE gateway, never this local adapter". This module is that
+// gateway. It NEVER touches the local mutation adapter or its allowlist.
+//
+// Like the local kernel, the gateway is deterministic given its injected dependencies (snapshot, clock,
+// id generator, remote adapter). It performs no IO of its own: the actual `git push` lives behind the
+// injected GitRemotePublishAdapter (implemented by git-publish-node.ts on the Node subpath), so the
+// orchestrator is unit-testable with a fake adapter and never opens a parallel child_process path.
+//
+// Pure module except for awaiting the injected adapter. Reuses the kernel's pure machinery unchanged:
+// evaluateGitPreflight (push case), evaluateGitPolicy, the GitMutationLifecycleResult shape (so the
+// #474 evidence builder consumes a push lifecycle with no change), and the failure taxonomy.
+import { evaluateGitPolicy, GIT_DELIVERY_RISK_CLASS_SEVERITY, GIT_DELIVERY_SCHEMA_VERSION, gitDeliveryBranchNameMatchesAny, gitDeliveryRiskClassForInputs, } from "@oscharko-dev/keiko-contracts";
+import { evaluateGitPreflight } from "./git-mutation-preflight.js";
+import { gitMutationCategoryForExecutionResult } from "./git-mutation-taxonomy.js";
+export const GIT_PUBLISH_REJECTION_REASONS = [
+    "non-fast-forward",
+    "fetch-first",
+    "no-upstream",
+    "auth-failed",
+    "permission-denied",
+    "protected-ref",
+    "remote-unavailable",
+    "unknown",
+];
+export function isGitPublishRejectionReason(value) {
+    return (typeof value === "string" &&
+        GIT_PUBLISH_REJECTION_REASONS.includes(value));
+}
+// Ordered phrase table. The first reason whose any-phrase appears in the (lower-cased, secret-redacted)
+// git output wins, so specific causes are matched before generic ones. Phrases are SPECIFIC: the generic
+// "failed to push some refs" / "could not read from remote repository" lines git prints for many failures
+// are deliberately NOT used as discriminators — only the cause-bearing hint lines are.
+const REJECTION_PHRASES = [
+    ["non-fast-forward", ["non-fast-forward", "tip of your current branch is behind"]],
+    ["fetch-first", ["fetch first", "remote contains work that you do"]],
+    [
+        "protected-ref",
+        ["protected branch", "pre-receive hook declined", "refusing to update", "gh006"],
+    ],
+    // Auth markers are checked BEFORE the generic "permission denied": an SSH "Permission denied
+    // (publickey)" is an AUTHENTICATION failure, whereas "remote: Permission to repo denied to user" is
+    // an authorization failure caught just below.
+    // Auth includes smart-HTTP 401 ("returned error: 401"), which some hosts emit without a remote: line.
+    [
+        "auth-failed",
+        [
+            "authentication failed",
+            "could not read username",
+            "publickey",
+            "invalid username",
+            "error: 401",
+        ],
+    ],
+    // Permission includes smart-HTTP 403 ("returned error: 403"): git prints `unable to access ... returned
+    // error: 403` with NO literal "forbidden", and some hosts/proxies omit the `remote: Permission` line, so
+    // the bare 403 token must classify as an authorization denial (user-fixable) rather than falling through
+    // to remote-unavailable (retryable).
+    [
+        "permission-denied",
+        ["permission denied", "permission to", "error: 403", "403 forbidden", "access denied"],
+    ],
+    ["no-upstream", ["has no upstream branch", "no upstream configured", "set-upstream"]],
+    [
+        "remote-unavailable",
+        [
+            "could not resolve host",
+            "could not read from remote",
+            "connection refused",
+            "timed out",
+            "unable to access",
+        ],
+    ],
+];
+// Pure classifier. Deterministic: same output text always yields the same reason. Matches lower-cased
+// so capitalisation differences across git versions do not change the classification.
+export function classifyGitPublishRejection(output) {
+    const haystack = output.toLowerCase();
+    for (const [reason, phrases] of REJECTION_PHRASES) {
+        if (phrases.some((phrase) => haystack.includes(phrase))) {
+            return reason;
+        }
+    }
+    return "unknown";
+}
+// ─── Reason → contract error code + recovery (reuses #471/#473/#474 vocabularies) ───────────
+// The error code is the content-free token recorded in evidence; the recovery composes the reused
+// three-way disposition with an action hint where one fits the existing vocabulary cleanly.
+const REJECTION_ERROR_CODE = {
+    "non-fast-forward": "precondition-failed",
+    "fetch-first": "precondition-failed",
+    "no-upstream": "precondition-failed",
+    "auth-failed": "provider-rejected",
+    "permission-denied": "provider-rejected",
+    "protected-ref": "provider-rejected",
+    "remote-unavailable": "network-failure",
+    unknown: "provider-rejected",
+};
+export function gitPublishRejectionToErrorCode(reason) {
+    return REJECTION_ERROR_CODE[reason];
+}
+const REJECTION_DISPOSITION = {
+    "non-fast-forward": "user-fixable",
+    "fetch-first": "user-fixable",
+    "no-upstream": "user-fixable",
+    "auth-failed": "user-fixable",
+    "permission-denied": "user-fixable",
+    "protected-ref": "user-fixable",
+    "remote-unavailable": "retryable",
+    unknown: "user-fixable",
+};
+// Action hint only where the #473 vocabulary fits cleanly; auth/permission/unknown intentionally carry
+// NO hint (the precise rejectionReason is the user-facing signal) rather than a misleading one.
+const REJECTION_ACTION_HINT = {
+    "non-fast-forward": "resolve-conflicts",
+    "fetch-first": "resolve-conflicts",
+    "no-upstream": "configure-upstream",
+    "auth-failed": undefined,
+    "permission-denied": undefined,
+    "protected-ref": "adjust-policy-target",
+    "remote-unavailable": "retry",
+    unknown: undefined,
+};
+export function gitPublishRejectionFor(reason) {
+    const actionHint = REJECTION_ACTION_HINT[reason];
+    return {
+        reason,
+        disposition: REJECTION_DISPOSITION[reason],
+        ...(actionHint !== undefined ? { actionHint } : {}),
+    };
+}
+// ─── Dedicated push allowlist + pure argv builder (force refused) ────────────────────────────
+// A closed allowlist permitting ONLY `push`. Structurally separate from the local mutation rules and
+// the read-only inspection rules. Mirrors their defence-in-depth flag denials so a smuggled global flag
+// is rejected before spawn even though argv is built only from typed operands.
+export const GIT_PUBLISH_ALLOWED_SUBCOMMANDS = Object.freeze(["push"]);
+export const GIT_PUBLISH_COMMAND_RULES = Object.freeze([
+    {
+        executable: "git",
+        allowedSubcommands: GIT_PUBLISH_ALLOWED_SUBCOMMANDS,
+        valueFlags: Object.freeze([
+            "-C",
+            "-c",
+            "--git-dir",
+            "--work-tree",
+            "--namespace",
+            "--exec-path",
+        ]),
+        denyFlags: Object.freeze([
+            "-C",
+            "-c",
+            "--config-env",
+            "--git-dir",
+            "--work-tree",
+            "--namespace",
+            "--exec-path",
+            "--ext-diff",
+            "--textconv",
+            "--no-index",
+            "--contents",
+            "--output",
+            // Force / history-rewrite flags are denied at the boundary as well as refused by the builder.
+            "--force",
+            "-f",
+            "--force-with-lease",
+            "--force-if-includes",
+            "--mirror",
+            "--delete",
+            "-d",
+        ]),
+    },
+]);
+export class GitPublishArgvError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "GitPublishArgvError";
+    }
+}
+// NUL and the rest of the C0 control range plus DEL. A git ref never legitimately contains one;
+// rejecting them is defence-in-depth above git's own ref validation. NUL is NOT matched by \s, so
+// the control range is enumerated via a string-built RegExp (no literal control chars in source).
+// eslint-disable-next-line no-control-regex -- intentionally matches control chars to REJECT them
+const REF_CONTROL_CHAR = new RegExp("[\u0000-\u001f\u007f]");
+function assertRef(value, label) {
+    if (value.length === 0) {
+        throw new GitPublishArgvError(`${label} must not be empty`);
+    }
+    if (REF_CONTROL_CHAR.test(value)) {
+        throw new GitPublishArgvError(`${label} must not contain control characters`);
+    }
+    if (/\s/.test(value)) {
+        throw new GitPublishArgvError(`${label} must not contain whitespace`);
+    }
+    if (value.startsWith("-")) {
+        throw new GitPublishArgvError(`${label} must not start with "-" (flag-injection guard)`);
+    }
+    if (value.includes(":")) {
+        throw new GitPublishArgvError(`${label} must not contain ":" (refspec-injection guard)`);
+    }
+    return value;
+}
+// Builds the single governed push argv. An explicit `src:dst` refspec is always used so the push target
+// is never inferred from ambient `push.default` config. AC4: a force push is REFUSED here — there is no
+// branch in this builder that can emit a force flag.
+export function buildPushArgv(command) {
+    if (command.forcePush) {
+        throw new GitPublishArgvError("force push is not permitted (AC4 — blocked by default)");
+    }
+    const remote = assertRef(command.remoteAlias, "remoteAlias");
+    const source = assertRef(command.sourceBranchName, "sourceBranchName");
+    const target = assertRef(command.remoteBranchName, "remoteBranchName");
+    const argv = ["push"];
+    if (command.setUpstreamTracking) {
+        argv.push("--set-upstream");
+    }
+    argv.push(remote, `${source}:${target}`);
+    return argv;
+}
+function pushResolvedInputs(command) {
+    return {
+        kind: "push",
+        sourceBranchName: command.sourceBranchName,
+        remoteAlias: command.remoteAlias,
+        remoteBranchName: command.remoteBranchName,
+        forcePush: command.forcePush,
+        setUpstreamTracking: command.setUpstreamTracking,
+    };
+}
+// The remote target a branch-pattern policy constraint is evaluated against: the published-to branch,
+// so a protected/shared REMOTE target is judged by policy, not the local source name.
+function buildPushPreview(command, snapshot) {
+    return {
+        schemaVersion: GIT_DELIVERY_SCHEMA_VERSION,
+        affectedBranchName: command.remoteBranchName,
+        wouldCreateRemoteBranch: command.setUpstreamTracking && !snapshot.hasUpstream,
+        wouldTriggerChecks: true,
+    };
+}
+function assemblePushEnvelope(actionId, inputs, policyDecision, approval, preview, executionResult) {
+    return {
+        schemaVersion: GIT_DELIVERY_SCHEMA_VERSION,
+        actionId,
+        kind: "push",
+        resolvedInputs: inputs,
+        policyDecision,
+        approvalRequirement: approval,
+        preview,
+        ...(executionResult !== undefined ? { executionResult } : {}),
+    };
+}
+function approvalState(approval, now) {
+    if (!approval.required) {
+        return "absent";
+    }
+    if (approval.expiresAtMs !== undefined && approval.expiresAtMs <= now) {
+        return "expired";
+    }
+    return "valid";
+}
+function constraintBlock(constraint, target, capabilities, pushInputs) {
+    if (constraint.kind === "branch-pattern") {
+        const ok = target !== undefined && gitDeliveryBranchNameMatchesAny(target, constraint.patterns);
+        return ok ? undefined : "policy-pack-blocked";
+    }
+    if (constraint.kind === "provider-capability") {
+        return capabilities.includes(constraint.capability) ? undefined : "provider-capability-absent";
+    }
+    // The FORCE-AWARE risk class: a force push escalates to recovery-or-rewrite (severity 4), so the
+    // publish ceiling (severity 2) blocks it (AC4). A future pack with a recovery-or-rewrite ceiling is
+    // the "explicit policy path" that could permit force; the default publish ceiling does not.
+    const pushSeverity = GIT_DELIVERY_RISK_CLASS_SEVERITY[gitDeliveryRiskClassForInputs(pushInputs)];
+    const ceilingSeverity = GIT_DELIVERY_RISK_CLASS_SEVERITY[constraint.maxRiskClass];
+    return pushSeverity <= ceilingSeverity ? undefined : "risk-class-ceiling";
+}
+export function evaluateGitPublishEffectivePolicy(decision, target, capabilities, pushInputs) {
+    if (decision.outcome === "allowed") {
+        return { outcome: "allowed" };
+    }
+    if (decision.outcome === "blocked") {
+        return { outcome: "blocked", blockReason: decision.reason };
+    }
+    if (decision.outcome === "approval-gated") {
+        return { outcome: "approval-gated" };
+    }
+    for (const constraint of decision.constraints) {
+        const reason = constraintBlock(constraint, target, capabilities, pushInputs);
+        if (reason !== undefined) {
+            return { outcome: "blocked", blockReason: reason };
+        }
+    }
+    return { outcome: "allowed" };
+}
+function resolvePublishGate(decision, approval, target, capabilities, pushInputs, now) {
+    if (decision.outcome === "allowed") {
+        return { proceed: true };
+    }
+    if (decision.outcome === "blocked") {
+        return { proceed: false, status: "policy-block", reason: decision.reason };
+    }
+    if (decision.outcome === "approval-gated") {
+        const state = approvalState(approval, now);
+        if (state === "valid")
+            return { proceed: true };
+        if (state === "expired") {
+            return { proceed: false, status: "policy-block", reason: "approval-expired" };
+        }
+        return { proceed: false, status: "approval-required", approvers: decision.requiredApprovers };
+    }
+    for (const constraint of decision.constraints) {
+        const reason = constraintBlock(constraint, target, capabilities, pushInputs);
+        if (reason !== undefined) {
+            return { proceed: false, status: "policy-block", reason };
+        }
+    }
+    return { proceed: true };
+}
+// ─── Execution outcome mapping (reuses the taxonomy) ─────────────────────────────────────────
+function publishOutcomeFor(result) {
+    if (result.outcome === "succeeded") {
+        return { status: "succeeded", executionResult: result };
+    }
+    const category = gitMutationCategoryForExecutionResult(result) ?? "execution-failure";
+    if (category === "recovery-required") {
+        return { status: "recovery-required", category, executionResult: result };
+    }
+    if (category === "provider-failure") {
+        return { status: "failed", category, executionResult: result };
+    }
+    return { status: "failed", category: "execution-failure", executionResult: result };
+}
+function preparePublish(request, deps) {
+    const inputs = pushResolvedInputs(request.command);
+    const capabilities = deps.activeProviderCapabilities ?? [];
+    const context = {
+        actionKind: "push",
+        targetBranchName: request.command.remoteBranchName,
+        activeProviderCapabilities: capabilities,
+    };
+    return {
+        inputs,
+        preflight: evaluateGitPreflight(inputs, deps.snapshot),
+        preview: buildPushPreview(request.command, deps.snapshot),
+        policyDecision: evaluateGitPolicy(deps.orgPolicyPack, deps.repoPolicyPack, context),
+        actionId: deps.newActionId(),
+    };
+}
+function lifecycleFor(prep, approval, outcome, phaseReached, executionResult) {
+    return {
+        envelope: assemblePushEnvelope(prep.actionId, prep.inputs, prep.policyDecision, approval, prep.preview, executionResult),
+        outcome,
+        phaseReached,
+        preflight: prep.preflight,
+    };
+}
+// Isolates the adapter call so a thrown/rejected adapter becomes a structured internal-error result
+// (an argv-builder refusal of a force push lands here too) rather than escaping the gateway.
+async function runPublishAdapter(command, adapter) {
+    try {
+        // Build the argv eagerly so a force-push refusal (AC4) is a structured failure, never a spawn.
+        buildPushArgv(command);
+        return await adapter.publish({
+            sourceBranchName: command.sourceBranchName,
+            remoteAlias: command.remoteAlias,
+            remoteBranchName: command.remoteBranchName,
+            setUpstreamTracking: command.setUpstreamTracking,
+        });
+    }
+    catch {
+        return {
+            schemaVersion: GIT_DELIVERY_SCHEMA_VERSION,
+            outcome: "failed",
+            durationMs: 0,
+            errorCode: "internal-error",
+        };
+    }
+}
+/**
+ * Runs ONE governed publish end-to-end: derive push inputs → preflight (push case) → preview → policy →
+ * (only when preflight passes, policy permits, approval satisfied) execute through the narrow remote
+ * adapter. Returns a kernel-shaped lifecycle result (so the #474 evidence builder records it unchanged)
+ * plus the live publish-rejection descriptor when the remote rejected an executed push.
+ */
+export async function runGitPublish(request, deps) {
+    const prep = preparePublish(request, deps);
+    // Gate 1: a blocking preflight finding halts before policy and execution.
+    if (!prep.preflight.ok) {
+        const outcome = {
+            status: "blocked",
+            category: "preflight-block",
+            findings: prep.preflight.blocking,
+        };
+        return { lifecycle: lifecycleFor(prep, request.approval, outcome, "preflight", undefined) };
+    }
+    // Gate 2: policy must permit (and any required approval must be satisfied).
+    const gate = resolvePublishGate(prep.policyDecision, request.approval, request.command.remoteBranchName, deps.activeProviderCapabilities ?? [], prep.inputs, deps.now());
+    if (!gate.proceed) {
+        const outcome = gate.status === "approval-required"
+            ? { status: "approval-required", requiredApprovers: gate.approvers }
+            : { status: "blocked", category: "policy-block", blockReason: gate.reason };
+        return { lifecycle: lifecycleFor(prep, request.approval, outcome, "policy", undefined) };
+    }
+    // Execute through the narrow remote adapter and classify any rejection.
+    const result = await runPublishAdapter(request.command, deps.adapter);
+    const outcome = publishOutcomeFor(result);
+    const lifecycle = lifecycleFor(prep, request.approval, outcome, "result", result);
+    // Attach a publish-rejection descriptor only for a genuine remote/precondition rejection. An ABORTED
+    // outcome (the run was cancelled) is not a remote rejection, so it carries no "user-fixable" recovery
+    // hint — surfacing one would mislead the operator into thinking the remote refused the push.
+    if (result.outcome !== "succeeded" && result.outcome !== "aborted") {
+        const reason = result.rejectionReason ?? "unknown";
+        return { lifecycle, rejection: gitPublishRejectionFor(reason) };
+    }
+    return { lifecycle };
+}
+// True iff the argv begins with the single allowed publish subcommand. Lets tests prove the
+// no-generic-fallback property structurally for the remote authority.
+export function gitPublishArgvIsGoverned(argv) {
+    return argv.length > 0 && GIT_PUBLISH_ALLOWED_SUBCOMMANDS.includes(argv[0] ?? "");
+}

package/dist/git-publish-node.d.ts

@@ -0,0 +1,17 @@
+import type { WorkspaceInfo } from "@oscharko-dev/keiko-workspace";
+import { type GitRemotePublishAdapter } from "./git-publish-gateway.js";
+import { type ExecutableResolver, type HomeProvider, type SpawnFn } from "./exec.js";
+import { type SandboxPolicy } from "./types.js";
+export interface NodeGitPublishAdapterDeps {
+    readonly workspace: WorkspaceInfo;
+    readonly processEnv?: NodeJS.ProcessEnv | undefined;
+    readonly now?: (() => number) | undefined;
+    readonly spawn?: SpawnFn | undefined;
+    readonly policy?: SandboxPolicy | undefined;
+    readonly resolveExecutable?: ExecutableResolver | undefined;
+    readonly home?: HomeProvider | undefined;
+    readonly signal?: AbortSignal | undefined;
+    readonly timeoutMs?: number | undefined;
+}
+export declare function createNodeGitPublishAdapter(deps: NodeGitPublishAdapterDeps): GitRemotePublishAdapter;
+//# sourceMappingURL=git-publish-node.d.ts.map

package/dist/git-publish-node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"git-publish-node.d.ts","sourceRoot":"","sources":["../src/git-publish-node.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAKnE,OAAO,EAOL,KAAK,uBAAuB,EAC7B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAGL,KAAK,kBAAkB,EACvB,KAAK,YAAY,EAEjB,KAAK,OAAO,EACb,MAAM,WAAW,CAAC;AACnB,OAAO,EAA8C,KAAK,aAAa,EAAE,MAAM,YAAY,CAAC;AAE5F,MAAM,WAAW,yBAAyB;IAExC,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,MAAM,MAAM,CAAC,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAGrC,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,iBAAiB,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,SAAS,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC1C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACzC;AAwFD,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,yBAAyB,GAC9B,uBAAuB,CAezB"}

package/dist/git-publish-node.js

@@ -0,0 +1,107 @@
+// Node implementation of the narrow remote publish adapter (Issue #476, Epic #470) — AC3/AC5.
+//
+// This is the ONLY place a governed `git push` actually executes. It builds the single governed push
+// argv from the pure builder (git-publish-gateway.ts) and runs it through the SAME keiko-tools no-shell
+// spawn boundary (`runCommand`, exec.ts) with a DEDICATED publish allowlist (`GIT_PUBLISH_COMMAND_RULES`)
+// that permits only `push` and denies every force/history-rewrite flag. There is no method that accepts
+// an arbitrary command string and no parallel child_process path: the deny-by-default allowlist, env
+// isolation, redaction, and cancellation of the shared boundary apply to the publish exactly as to every
+// other tool.
+//
+// A non-zero push exit is classified into a typed GitPublishRejectionReason by matching git's own
+// English status phrases in the (already secret-redacted) output. Raw stdout/stderr never leave this
+// module — only the typed reason and the content-free contract error code cross the boundary.
+//
+// Lives on the `./internal/git-mutation` subpath (re-exported by git-mutation-node.ts) because it carries
+// the Node execution effect; the pure port, builder, and rules it implements are on the package barrel.
+import { GIT_DELIVERY_SCHEMA_VERSION, } from "@oscharko-dev/keiko-contracts";
+import { buildPushArgv, classifyGitPublishRejection, GIT_PUBLISH_COMMAND_RULES, gitPublishRejectionToErrorCode, } from "./git-publish-gateway.js";
+import { CommandCancelledError, CommandTimeoutError } from "./errors.js";
+import { nodeSpawnFn, runCommand, } from "./exec.js";
+import { DEFAULT_SANDBOX_POLICY } from "./types.js";
+function executionResult(outcome, durationMs, extra) {
+    return {
+        schemaVersion: GIT_DELIVERY_SCHEMA_VERSION,
+        outcome,
+        durationMs: Math.max(0, Math.trunc(durationMs)),
+        ...extra,
+    };
+}
+function buildRunContext(deps) {
+    return {
+        runDeps: {
+            workspace: deps.workspace,
+            policy: deps.policy ?? DEFAULT_SANDBOX_POLICY,
+            commandRules: GIT_PUBLISH_COMMAND_RULES,
+            spawn: deps.spawn ?? nodeSpawnFn,
+            processEnv: deps.processEnv ?? process.env,
+            now: deps.now ?? Date.now,
+            ...(deps.resolveExecutable !== undefined
+                ? { resolveExecutable: deps.resolveExecutable }
+                : {}),
+            ...(deps.home !== undefined ? { home: deps.home } : {}),
+        },
+        signal: deps.signal ?? new AbortController().signal,
+        timeoutMs: deps.timeoutMs,
+    };
+}
+// A non-zero push exit means the remote (or a local precondition) rejected the push. The reason is
+// classified from the combined, already-redacted output; only the typed reason + content-free error
+// code are returned. A `timedOut` run is a transient network timeout, not a remote rejection.
+function rejectionFromExit(result) {
+    if (result.timedOut) {
+        return executionResult("failed", result.durationMs, {
+            errorCode: "timeout",
+            rejectionReason: "remote-unavailable",
+        });
+    }
+    const reason = classifyGitPublishRejection(`${result.stdout}\n${result.stderr}`);
+    return executionResult("failed", result.durationMs, {
+        errorCode: gitPublishRejectionToErrorCode(reason),
+        rejectionReason: reason,
+    });
+}
+function failureFromThrow(error, durationMs) {
+    if (error instanceof CommandTimeoutError) {
+        return executionResult("failed", durationMs, {
+            errorCode: "timeout",
+            rejectionReason: "remote-unavailable",
+        });
+    }
+    if (error instanceof CommandCancelledError) {
+        return executionResult("aborted", durationMs);
+    }
+    // A denied command (our own argv hit the allowlist), an argv-construction fault, or any other throw
+    // is an internal gateway error — it never means the remote is at fault.
+    return executionResult("failed", durationMs, { errorCode: "internal-error" });
+}
+async function runPush(ctx, argv) {
+    let result;
+    try {
+        result = await runCommand({ command: "git", args: argv, cwd: undefined, timeoutMs: ctx.timeoutMs, signal: ctx.signal }, ctx.runDeps);
+    }
+    catch (error) {
+        return failureFromThrow(error, 0);
+    }
+    if (result.exitCode === 0) {
+        return executionResult("succeeded", result.durationMs);
+    }
+    return rejectionFromExit(result);
+}
+export function createNodeGitPublishAdapter(deps) {
+    const ctx = buildRunContext(deps);
+    return {
+        publish: (req) => {
+            let argv;
+            try {
+                // forcePush is hard-false and LAST so it can never be overridden by the request: a force
+                // operand never reaches this executor (AC4 defence-in-depth above the gateway gate).
+                argv = buildPushArgv({ ...req, kind: "push", forcePush: false });
+            }
+            catch {
+                return Promise.resolve(executionResult("failed", 0, { errorCode: "internal-error" }));
+            }
+            return runPush(ctx, argv);
+        },
+    };
+}