@wardby/cli 0.1.0

package/dist/providers/jobs/fake-kubernetes-api.d.ts

@@ -0,0 +1,98 @@
+import type { V1ConfigMap, V1Endpoints, V1NetworkPolicy, V1Pod, V1Secret, V1Service } from "@kubernetes/client-node";
+import type { Readable, Writable } from "node:stream";
+import { type KubernetesApi, type KubernetesExecOptions } from "./kubernetes-api.js";
+export interface FakeExecCall {
+    namespace: string;
+    pod: string;
+    container: string;
+    command: string[];
+    stdin?: Readable;
+    stdout?: Writable;
+}
+type Kind = "configmap" | "secret" | "pod" | "networkpolicy" | "service" | "endpoints";
+type Obj = {
+    metadata?: {
+        name?: string;
+        namespace?: string;
+        resourceVersion?: string;
+    };
+};
+/** In-memory KubernetesApi for unit tests. Tests drive pod status and exec behavior directly. */
+export declare class FakeKubernetesApi implements KubernetesApi {
+    readonly objects: Map<string, Obj>;
+    readonly namespaces: Set<string>;
+    readonly execCalls: FakeExecCall[];
+    readonly deletedPods: Array<{
+        name: string;
+        gracePeriodSeconds: number;
+    }>;
+    /** Returns the exit code; write to stdout / read stdin as the command would. Default: exit 0, no output. */
+    onExec: (call: FakeExecCall) => Promise<number>;
+    /** The admission chain a dry-run create runs through. Default: echo the pod back unchanged. */
+    onDryRunCreatePod: (namespace: string, body: V1Pod) => Promise<V1Pod>;
+    logs: Map<string, string>;
+    /** What readApiServerVersion reports; tests that care about provenance set it. */
+    apiServerVersion: string;
+    private version;
+    private key;
+    private create;
+    private read;
+    private delete;
+    /** Test helper: overwrite an object without a resourceVersion check (e.g. to set pod status). */
+    put<T extends Obj>(kind: Kind, namespace: string, body: T): void;
+    createConfigMap(namespace: string, body: V1ConfigMap): Promise<V1ConfigMap>;
+    readConfigMap(namespace: string, name: string): Promise<V1ConfigMap | undefined>;
+    replaceConfigMap(namespace: string, name: string, body: V1ConfigMap): Promise<{
+        metadata: {
+            namespace: string;
+            resourceVersion: string;
+            annotations?: {
+                [key: string]: string;
+            };
+            creationTimestamp?: Date;
+            deletionGracePeriodSeconds?: number;
+            deletionTimestamp?: Date;
+            finalizers?: Array<string>;
+            generateName?: string;
+            generation?: number;
+            labels?: {
+                [key: string]: string;
+            };
+            managedFields?: Array<import("@kubernetes/client-node").V1ManagedFieldsEntry>;
+            name?: string;
+            ownerReferences?: Array<import("@kubernetes/client-node").V1OwnerReference>;
+            selfLink?: string;
+            uid?: string;
+        };
+        apiVersion?: string;
+        binaryData?: {
+            [key: string]: string;
+        };
+        data?: {
+            [key: string]: string;
+        };
+        immutable?: boolean;
+        kind?: string;
+    }>;
+    createSecret(namespace: string, body: V1Secret): Promise<V1Secret>;
+    deleteSecret(namespace: string, name: string): Promise<void>;
+    createPod(namespace: string, body: V1Pod): Promise<V1Pod>;
+    /**
+     * A dry-run create persists nothing, but it is still a create: the API server runs the same
+     * validation and name checks, so a nameless body and a colliding name both fail exactly as
+     * they would on a real create. Tests override `onDryRunCreatePod` to model an admission chain.
+     */
+    dryRunCreatePod(namespace: string, body: V1Pod): Promise<V1Pod>;
+    readPod(namespace: string, name: string): Promise<V1Pod | undefined>;
+    deletePod(namespace: string, name: string, gracePeriodSeconds: number): Promise<void>;
+    createNetworkPolicy(namespace: string, body: V1NetworkPolicy): Promise<V1NetworkPolicy>;
+    readNetworkPolicy(namespace: string, name: string): Promise<V1NetworkPolicy | undefined>;
+    deleteNetworkPolicy(namespace: string, name: string): Promise<void>;
+    readService(namespace: string, name: string): Promise<V1Service | undefined>;
+    readEndpoints(namespace: string, name: string): Promise<V1Endpoints | undefined>;
+    readApiServerVersion(): Promise<string>;
+    readNamespace(name: string): Promise<boolean>;
+    exec(namespace: string, pod: string, container: string, command: string[], options: KubernetesExecOptions): Promise<number>;
+    readLogTail(namespace: string, pod: string, container: string, tailLines: number, limitBytes: number): Promise<string>;
+}
+export {};

package/dist/providers/jobs/fake-kubernetes-api.js

@@ -0,0 +1,142 @@
+import { KubernetesAlreadyExistsError, KubernetesConflictError, KubernetesNotFoundError, } from "./kubernetes-api.js";
+/** In-memory KubernetesApi for unit tests. Tests drive pod status and exec behavior directly. */
+export class FakeKubernetesApi {
+    objects = new Map();
+    namespaces = new Set(["wardby-coding"]);
+    execCalls = [];
+    deletedPods = [];
+    /** Returns the exit code; write to stdout / read stdin as the command would. Default: exit 0, no output. */
+    onExec = async ({ stdout, stdin }) => {
+        stdin?.resume();
+        stdout?.end();
+        return 0;
+    };
+    /** The admission chain a dry-run create runs through. Default: echo the pod back unchanged. */
+    onDryRunCreatePod = async (_namespace, body) => body;
+    logs = new Map();
+    /** What readApiServerVersion reports; tests that care about provenance set it. */
+    apiServerVersion = "v1.33.0";
+    version = 0;
+    key(kind, namespace, name) {
+        return `${kind}/${namespace}/${name}`;
+    }
+    create(kind, namespace, body) {
+        const name = body.metadata?.name;
+        if (!name)
+            throw new Error("fake_name_required");
+        const key = this.key(kind, namespace, name);
+        if (this.objects.has(key))
+            throw new KubernetesAlreadyExistsError(key);
+        const stored = structuredClone({
+            ...body,
+            metadata: { ...body.metadata, namespace, resourceVersion: String(++this.version) },
+        });
+        this.objects.set(key, stored);
+        return structuredClone(stored);
+    }
+    read(kind, namespace, name) {
+        const found = this.objects.get(this.key(kind, namespace, name));
+        return found ? structuredClone(found) : undefined;
+    }
+    delete(kind, namespace, name) {
+        this.objects.delete(this.key(kind, namespace, name));
+    }
+    /** Test helper: overwrite an object without a resourceVersion check (e.g. to set pod status). */
+    put(kind, namespace, body) {
+        const name = body.metadata?.name;
+        this.objects.set(this.key(kind, namespace, name), {
+            ...structuredClone(body),
+            metadata: { ...body.metadata, namespace, resourceVersion: String(++this.version) },
+        });
+    }
+    async createConfigMap(namespace, body) {
+        return this.create("configmap", namespace, body);
+    }
+    async readConfigMap(namespace, name) {
+        return this.read("configmap", namespace, name);
+    }
+    async replaceConfigMap(namespace, name, body) {
+        const key = this.key("configmap", namespace, name);
+        const current = this.objects.get(key);
+        if (!current)
+            throw new KubernetesNotFoundError(key);
+        if (body.metadata?.resourceVersion !== current.metadata?.resourceVersion)
+            throw new KubernetesConflictError(key);
+        const stored = structuredClone({
+            ...body,
+            metadata: { ...body.metadata, namespace, resourceVersion: String(++this.version) },
+        });
+        this.objects.set(key, stored);
+        return structuredClone(stored);
+    }
+    async createSecret(namespace, body) {
+        return this.create("secret", namespace, body);
+    }
+    async deleteSecret(namespace, name) {
+        this.delete("secret", namespace, name);
+    }
+    async createPod(namespace, body) {
+        return this.create("pod", namespace, body);
+    }
+    /**
+     * A dry-run create persists nothing, but it is still a create: the API server runs the same
+     * validation and name checks, so a nameless body and a colliding name both fail exactly as
+     * they would on a real create. Tests override `onDryRunCreatePod` to model an admission chain.
+     */
+    async dryRunCreatePod(namespace, body) {
+        const name = body.metadata?.name;
+        if (!name)
+            throw new Error("fake_name_required");
+        const key = this.key("pod", namespace, name);
+        if (this.objects.has(key))
+            throw new KubernetesAlreadyExistsError(key);
+        return this.onDryRunCreatePod(namespace, structuredClone(body));
+    }
+    async readPod(namespace, name) {
+        return this.read("pod", namespace, name);
+    }
+    async deletePod(namespace, name, gracePeriodSeconds) {
+        this.deletedPods.push({ name, gracePeriodSeconds });
+        this.delete("pod", namespace, name);
+    }
+    async createNetworkPolicy(namespace, body) {
+        return this.create("networkpolicy", namespace, body);
+    }
+    async readNetworkPolicy(namespace, name) {
+        return this.read("networkpolicy", namespace, name);
+    }
+    async deleteNetworkPolicy(namespace, name) {
+        this.delete("networkpolicy", namespace, name);
+    }
+    async readService(namespace, name) {
+        return this.read("service", namespace, name);
+    }
+    async readEndpoints(namespace, name) {
+        return this.read("endpoints", namespace, name);
+    }
+    async readApiServerVersion() {
+        return this.apiServerVersion;
+    }
+    async readNamespace(name) {
+        return this.namespaces.has(name);
+    }
+    async exec(namespace, pod, container, command, options) {
+        // Like the real API: exec into a missing pod or an unknown container fails instead of succeeding
+        // silently, so no test can pass on behaviour a cluster would reject. (The adapter's timeoutMs is
+        // not modelled: tests drive slow execs through onExec directly.)
+        const target = this.read("pod", namespace, pod);
+        if (!target)
+            throw new KubernetesNotFoundError(this.key("pod", namespace, pod));
+        const containers = [...(target.spec?.containers ?? []), ...(target.spec?.initContainers ?? [])];
+        if (!containers.some((entry) => entry.name === container)) {
+            throw new KubernetesNotFoundError(`${this.key("pod", namespace, pod)}/${container}`);
+        }
+        const call = { namespace, pod, container, command, stdin: options.stdin, stdout: options.stdout };
+        this.execCalls.push(call);
+        return this.onExec(call);
+    }
+    async readLogTail(namespace, pod, container, tailLines, limitBytes) {
+        const lines = (this.logs.get(`${namespace}/${pod}/${container}`) ?? "").split("\n").slice(-tailLines).join("\n");
+        return Buffer.from(lines).subarray(0, limitBytes).toString();
+    }
+}

package/dist/providers/jobs/fake.d.ts

@@ -0,0 +1,23 @@
+import type { JobHandle, JobLauncher, JobResult, JobSpec, JobStatus } from "./types.js";
+export interface FakeJobPlan {
+    /** Status returned by each successive poll; the final entry remains stable. */
+    statusScript?: JobStatus[];
+    result?: JobResult;
+}
+export declare class FakeJobLauncher implements JobLauncher {
+    private readonly jobs;
+    private readonly runIds;
+    private readonly plans;
+    private nextId;
+    queuePlan(plan: FakeJobPlan): void;
+    launch(spec: JobSpec): Promise<JobHandle>;
+    status(handle: JobHandle): Promise<JobStatus>;
+    collect(handle: JobHandle): Promise<JobResult>;
+    stop(handle: JobHandle, _reason?: string): Promise<void>;
+    remove(handle: JobHandle): Promise<void>;
+    finish(handle: JobHandle, result?: JobResult): Promise<void>;
+    lose(handle: JobHandle): Promise<void>;
+    private transition;
+    private findRecord;
+    private requireRecord;
+}

package/dist/providers/jobs/fake.js

@@ -0,0 +1,132 @@
+import { isDeepStrictEqual } from "node:util";
+const BACKEND = "fake";
+const TERMINAL_STATES = new Set(["succeeded", "failed", "stopped", "lost"]);
+function clone(value) {
+    return structuredClone(value);
+}
+function resultFor(status) {
+    switch (status.state) {
+        case "succeeded":
+            return { exitCode: 0, reason: "completed" };
+        case "failed":
+            return { exitCode: 1, reason: "failed" };
+        case "stopped":
+            return { exitCode: 143, reason: "stopped" };
+        case "lost":
+            return { exitCode: 1, reason: "lost" };
+        default:
+            throw new Error("job_not_terminal");
+    }
+}
+function statusFor(result) {
+    switch (result.reason) {
+        case "completed":
+            return { state: "succeeded" };
+        case "stopped":
+            return { state: "stopped" };
+        case "lost":
+            return { state: "lost" };
+        case "failed":
+            return { state: "failed" };
+        case "timed_out":
+            return { state: "failed", reason: "timed_out" };
+    }
+}
+export class FakeJobLauncher {
+    jobs = new Map();
+    runIds = new Map();
+    plans = [];
+    nextId = 1;
+    queuePlan(plan) {
+        this.plans.push(clone(plan));
+    }
+    async launch(spec) {
+        const existingId = this.runIds.get(spec.runId);
+        if (existingId) {
+            const existing = this.jobs.get(existingId);
+            if (!existing)
+                throw new Error("job_state_corrupt");
+            if (!isDeepStrictEqual(existing.spec, spec))
+                throw new Error("job_spec_conflict");
+            return clone(existing.handle);
+        }
+        const handle = { backend: BACKEND, id: `job-${String(this.nextId++).padStart(4, "0")}` };
+        const plan = this.plans.shift() ?? {};
+        const statusScript = plan.statusScript?.length ? clone(plan.statusScript) : [{ state: "pending" }];
+        const record = {
+            handle,
+            spec: clone(spec),
+            status: { state: "pending" },
+            statusScript,
+            statusCursor: 0,
+            plannedResult: plan.result ? clone(plan.result) : undefined,
+            removed: false,
+        };
+        this.jobs.set(handle.id, record);
+        this.runIds.set(spec.runId, handle.id);
+        return clone(handle);
+    }
+    async status(handle) {
+        const record = this.requireRecord(handle);
+        if (!TERMINAL_STATES.has(record.status.state)) {
+            const scripted = record.statusScript[Math.min(record.statusCursor, record.statusScript.length - 1)];
+            record.statusCursor += 1;
+            this.transition(record, scripted, TERMINAL_STATES.has(scripted.state) ? record.plannedResult : undefined);
+        }
+        return clone(record.status);
+    }
+    async collect(handle) {
+        const record = this.requireRecord(handle);
+        if (!TERMINAL_STATES.has(record.status.state) || !record.result)
+            throw new Error("job_not_terminal");
+        return clone(record.result);
+    }
+    async stop(handle, _reason) {
+        const record = this.findRecord(handle);
+        if (!record || record.removed || TERMINAL_STATES.has(record.status.state))
+            return;
+        this.transition(record, { state: "stopped" });
+    }
+    async remove(handle) {
+        const record = this.findRecord(handle);
+        if (!record || record.removed)
+            return;
+        if (!TERMINAL_STATES.has(record.status.state))
+            throw new Error("job_not_terminal");
+        record.removed = true;
+    }
+    async finish(handle, result = { exitCode: 0, reason: "completed" }) {
+        const record = this.requireRecord(handle);
+        this.transition(record, statusFor(result), result);
+    }
+    async lose(handle) {
+        const record = this.requireRecord(handle);
+        this.transition(record, { state: "lost" });
+    }
+    transition(record, next, result) {
+        if (TERMINAL_STATES.has(record.status.state))
+            return;
+        if (record.status.state === "running" && next.state === "pending") {
+            throw new Error("job_illegal_transition");
+        }
+        if (result && statusFor(result).state !== next.state)
+            throw new Error("job_result_status_mismatch");
+        record.status = clone(next);
+        if (TERMINAL_STATES.has(next.state)) {
+            record.result = clone(result ?? resultFor(next));
+        }
+    }
+    findRecord(handle) {
+        if (handle.backend !== BACKEND)
+            throw new Error("job_backend_mismatch");
+        return this.jobs.get(handle.id);
+    }
+    requireRecord(handle) {
+        const record = this.findRecord(handle);
+        if (!record)
+            throw new Error("job_not_found");
+        if (record.removed)
+            throw new Error("job_removed");
+        return record;
+    }
+}

package/dist/providers/jobs/kubernetes-api.d.ts

@@ -0,0 +1,60 @@
+/**
+ * The only surface KubernetesJobLauncher uses to reach a cluster. Kept narrow
+ * so every launcher behavior is unit-tested against FakeKubernetesApi and
+ * re-proven against a real cluster by kubernetes.integration.test.ts.
+ */
+import type { V1ConfigMap, V1Endpoints, V1NetworkPolicy, V1Pod, V1Secret, V1Service } from "@kubernetes/client-node";
+import type { Readable, Writable } from "node:stream";
+export declare class KubernetesNotFoundError extends Error {
+    constructor(message?: string);
+}
+/** Stale resourceVersion on replace. */
+export declare class KubernetesConflictError extends Error {
+    constructor(message?: string);
+}
+/** Create of an existing name. */
+export declare class KubernetesAlreadyExistsError extends Error {
+    constructor(message?: string);
+}
+export interface KubernetesExecOptions {
+    stdin?: Readable;
+    stdout?: Writable;
+    timeoutMs: number;
+}
+/** Deletes are idempotent (a missing object is not an error). Reads return `undefined` for a missing object. */
+export interface KubernetesApi {
+    createConfigMap(namespace: string, body: V1ConfigMap): Promise<V1ConfigMap>;
+    readConfigMap(namespace: string, name: string): Promise<V1ConfigMap | undefined>;
+    replaceConfigMap(namespace: string, name: string, body: V1ConfigMap): Promise<V1ConfigMap>;
+    createSecret(namespace: string, body: V1Secret): Promise<V1Secret>;
+    deleteSecret(namespace: string, name: string): Promise<void>;
+    createPod(namespace: string, body: V1Pod): Promise<V1Pod>;
+    /**
+     * Server-side dry-run create: the API server runs the whole admission chain and returns the
+     * mutated object without persisting anything. Used only by src/tools/capture-autopilot-dry-run.ts;
+     * never by the launcher, which must not let a cluster tell it what it is allowed to change.
+     */
+    dryRunCreatePod(namespace: string, body: V1Pod): Promise<V1Pod>;
+    readPod(namespace: string, name: string): Promise<V1Pod | undefined>;
+    deletePod(namespace: string, name: string, gracePeriodSeconds: number): Promise<void>;
+    createNetworkPolicy(namespace: string, body: V1NetworkPolicy): Promise<V1NetworkPolicy>;
+    readNetworkPolicy(namespace: string, name: string): Promise<V1NetworkPolicy | undefined>;
+    deleteNetworkPolicy(namespace: string, name: string): Promise<void>;
+    readService(namespace: string, name: string): Promise<V1Service | undefined>;
+    /**
+     * Reads a Service's Endpoints by name. EndpointSlice is the durable successor to this core/v1
+     * resource (migrating to it is a follow-up); Endpoints is read by name so RBAC stays one object wide.
+     */
+    readEndpoints(namespace: string, name: string): Promise<V1Endpoints | undefined>;
+    readNamespace(name: string): Promise<boolean>;
+    /** Runs a command in a container; resolves with its exit code. Never uses a shell. */
+    exec(namespace: string, pod: string, container: string, command: string[], options: KubernetesExecOptions): Promise<number>;
+    /**
+     * The API server's reported version (`gitVersion`, e.g. `v1.33.4-gke.1000`). Read-only and
+     * cluster-wide; used by src/tools/capture-fixture.ts to stamp a capture with the server that
+     * produced it, so a fixture cannot claim provenance it never recorded.
+     */
+    readApiServerVersion(): Promise<string>;
+    /** Reads at most `limitBytes` of the last `tailLines` lines of a container's log. */
+    readLogTail(namespace: string, pod: string, container: string, tailLines: number, limitBytes: number): Promise<string>;
+}

package/dist/providers/jobs/kubernetes-api.js

@@ -0,0 +1,20 @@
+export class KubernetesNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "KubernetesNotFoundError";
+    }
+}
+/** Stale resourceVersion on replace. */
+export class KubernetesConflictError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "KubernetesConflictError";
+    }
+}
+/** Create of an existing name. */
+export class KubernetesAlreadyExistsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "KubernetesAlreadyExistsError";
+    }
+}

package/dist/providers/jobs/kubernetes-client.d.ts

@@ -0,0 +1,36 @@
+/**
+ * KubernetesApi over @kubernetes/client-node 2.x. A thin mapping: each seam
+ * method is one client call plus HTTP-status translation into the seam's
+ * error classes. Proven against a real cluster by kubernetes.integration.test.ts.
+ */
+import { type V1ConfigMap, type V1Endpoints, type V1NetworkPolicy, type V1Pod, type V1Secret, type V1Service } from "@kubernetes/client-node";
+import { type KubernetesApi, type KubernetesExecOptions } from "./kubernetes-api.js";
+export interface ClientNodeKubernetesApiOptions {
+    /** kubeconfig context to use; defaults to the current context (or in-cluster credentials). */
+    context?: string;
+}
+export declare class ClientNodeKubernetesApi implements KubernetesApi {
+    private readonly config;
+    private readonly core;
+    private readonly networking;
+    private readonly version;
+    constructor(options?: ClientNodeKubernetesApiOptions);
+    createConfigMap(namespace: string, body: V1ConfigMap): Promise<V1ConfigMap>;
+    readConfigMap(namespace: string, name: string): Promise<V1ConfigMap | undefined>;
+    replaceConfigMap(namespace: string, name: string, body: V1ConfigMap): Promise<V1ConfigMap>;
+    createSecret(namespace: string, body: V1Secret): Promise<V1Secret>;
+    deleteSecret(namespace: string, name: string): Promise<void>;
+    createPod(namespace: string, body: V1Pod): Promise<V1Pod>;
+    dryRunCreatePod(namespace: string, body: V1Pod): Promise<V1Pod>;
+    readPod(namespace: string, name: string): Promise<V1Pod | undefined>;
+    deletePod(namespace: string, name: string, gracePeriodSeconds: number): Promise<void>;
+    createNetworkPolicy(namespace: string, body: V1NetworkPolicy): Promise<V1NetworkPolicy>;
+    readNetworkPolicy(namespace: string, name: string): Promise<V1NetworkPolicy | undefined>;
+    deleteNetworkPolicy(namespace: string, name: string): Promise<void>;
+    readService(namespace: string, name: string): Promise<V1Service | undefined>;
+    readEndpoints(namespace: string, name: string): Promise<V1Endpoints | undefined>;
+    readApiServerVersion(): Promise<string>;
+    readNamespace(name: string): Promise<boolean>;
+    exec(namespace: string, pod: string, container: string, command: string[], options: KubernetesExecOptions): Promise<number>;
+    readLogTail(namespace: string, pod: string, container: string, tailLines: number, limitBytes: number): Promise<string>;
+}