@claudexor/cli 3.23.2 → 3.24.0

package/dist/harness-maintenance-service.d.ts

@@ -0,0 +1,473 @@
+/**
+ * The engine-owned harness maintenance OPERATION. One accepted request is one
+ * durable command on the daemon's existing queue/cancel/idempotency authority
+ * (the model-operation precedent: no second scheduler or job ledger). Execution
+ * runs the CLI primitive (`harness inspect|update`, harness-maintenance.ts) as
+ * a child through core spawnProcess, so the blocking installer never runs on
+ * the daemon event loop, Cancel reaches the whole process group, and an
+ * unconfirmed tree death stays a typed fact instead of a clean cancel.
+ *
+ * Evidence (before/target/after/mutation) lives in the command record. The
+ * proved `before` and the exact resolved target are written durably BEFORE
+ * the first mutation; a restart leaves the command interrupted with that
+ * evidence and never replays the install. A small in-memory index answers
+ * per-harness reads without scanning history on every poll.
+ */
+import { existsSync } from "node:fs";
+import { spawnProcess } from "@claudexor/core";
+import { type CommandAuthority, type DaemonClient, type RunContext } from "@claudexor/daemon";
+import type { AuthReadinessService } from "@claudexor/gateway";
+export declare const HARNESS_MAINTENANCE_OPERATION_ID = "harness.maintenance.create";
+/** The CLI entry beside this module: the packaged bundle, else the dist CLI. */
+export declare function claudexorCliEntry(moduleUrl?: string, exists?: typeof existsSync): string;
+export interface HarnessMaintenanceDependencies {
+    commands: CommandAuthority;
+    client: Pick<DaemonClient, "enqueue" | "cancel">;
+    readiness?: () => Pick<AuthReadinessService, "invalidate">;
+    /** Test seams; production runs `<node> <cli entry>` through spawnProcess. */
+    cli?: {
+        command: string;
+        args: string[];
+    };
+    spawn?: typeof spawnProcess;
+    cancelKillDelayMs?: number;
+    now?: () => Date;
+}
+export declare function createHarnessMaintenance(deps: HarnessMaintenanceDependencies): {
+    owns: (params: unknown) => boolean;
+    execute: (raw: unknown, ctx: RunContext) => Promise<{
+        phase: "accepted" | "installing" | "preparing" | "settled";
+        mechanism: "managed_npm" | "vendor_script" | "vendor_updater" | null;
+        target: {
+            kind: "baseline" | "latest" | "previous" | "version";
+            version: string | null;
+        };
+        before: {
+            version: string | null;
+            binary: string | null;
+            selection: "managed" | "missing" | "override" | "path";
+            proved: boolean;
+        } | null;
+        after: {
+            version: string | null;
+            binary: string | null;
+            selected: boolean;
+            proved: boolean;
+        } | null;
+        mutation: "applied" | "none" | "unknown";
+        termination: "confirmed" | "not_applicable" | "unconfirmed";
+        limitations: string[];
+        progress: string[];
+        problem: {
+            code: string;
+            message: string;
+            retryable: boolean;
+            fieldErrors: Record<string, string[]>;
+            requiredActions: string[];
+            evidenceRefs: string[];
+            context: Record<string, unknown>;
+        } | null;
+        lifecycle: "cancelled" | "failed" | "succeeded";
+    }>;
+    routes: {
+        maintenanceInventory: (input?: {
+            harnessIds?: string[];
+            fresh?: boolean;
+            checkLatest?: boolean;
+        }) => Promise<{
+            observedAt: string;
+            harnesses: {
+                harness: string;
+                mechanism: "managed_npm" | "vendor_script" | "vendor_updater";
+                maintainable: boolean;
+                canCheckLatest: boolean;
+                targets: ("baseline" | "latest" | "previous" | "version")[];
+                remedy: string | null;
+                selection: {
+                    kind: "managed" | "missing" | "override" | "path";
+                    binary: string | null;
+                    version: string | null;
+                    overrideEnv: string | null;
+                };
+                installed: {
+                    version: string | null;
+                    binary: string | null;
+                    proved: boolean;
+                };
+                releaseTested: {
+                    version: string | null;
+                    verification: "deterministic_only" | "release_verified" | null;
+                };
+                available: {
+                    version: string;
+                    observedAt: string;
+                } | null;
+                availableProblem: {
+                    code: string;
+                    message: string;
+                    retryable: boolean;
+                    fieldErrors: Record<string, string[]>;
+                    requiredActions: string[];
+                    evidenceRefs: string[];
+                    context: Record<string, unknown>;
+                } | null;
+                previous: {
+                    version: string;
+                    operationId: string;
+                } | null;
+                operation: {
+                    id: string;
+                    state: string;
+                    phase: string;
+                    targetVersion: string | null;
+                    finishedAt: string | null;
+                } | null;
+                observedAt: string;
+            }[];
+        }>;
+        createMaintenanceOperation: (body: unknown, idempotencyKey: string) => Promise<{
+            phase: "accepted" | "installing" | "preparing" | "settled";
+            mechanism: "managed_npm" | "vendor_script" | "vendor_updater" | null;
+            target: {
+                kind: "baseline" | "latest" | "previous" | "version";
+                version: string | null;
+            };
+            before: {
+                version: string | null;
+                binary: string | null;
+                selection: "managed" | "missing" | "override" | "path";
+                proved: boolean;
+            } | null;
+            after: {
+                version: string | null;
+                binary: string | null;
+                selected: boolean;
+                proved: boolean;
+            } | null;
+            mutation: "applied" | "none" | "unknown";
+            termination: "confirmed" | "not_applicable" | "unconfirmed";
+            limitations: string[];
+            progress: string[];
+            problem: {
+                code: string;
+                message: string;
+                retryable: boolean;
+                fieldErrors: Record<string, string[]>;
+                requiredActions: string[];
+                evidenceRefs: string[];
+                context: Record<string, unknown>;
+            } | null;
+            id: string;
+            harness: string;
+            state: "cancelled" | "failed" | "interrupted" | "queued" | "running" | "succeeded";
+            createdAt: string;
+            startedAt: string | null;
+            finishedAt: string | null;
+        }>;
+        getMaintenanceOperation: (id: string) => Promise<{
+            phase: "accepted" | "installing" | "preparing" | "settled";
+            mechanism: "managed_npm" | "vendor_script" | "vendor_updater" | null;
+            target: {
+                kind: "baseline" | "latest" | "previous" | "version";
+                version: string | null;
+            };
+            before: {
+                version: string | null;
+                binary: string | null;
+                selection: "managed" | "missing" | "override" | "path";
+                proved: boolean;
+            } | null;
+            after: {
+                version: string | null;
+                binary: string | null;
+                selected: boolean;
+                proved: boolean;
+            } | null;
+            mutation: "applied" | "none" | "unknown";
+            termination: "confirmed" | "not_applicable" | "unconfirmed";
+            limitations: string[];
+            progress: string[];
+            problem: {
+                code: string;
+                message: string;
+                retryable: boolean;
+                fieldErrors: Record<string, string[]>;
+                requiredActions: string[];
+                evidenceRefs: string[];
+                context: Record<string, unknown>;
+            } | null;
+            id: string;
+            harness: string;
+            state: "cancelled" | "failed" | "interrupted" | "queued" | "running" | "succeeded";
+            createdAt: string;
+            startedAt: string | null;
+            finishedAt: string | null;
+        }>;
+        cancelMaintenanceOperation: (id: string) => Promise<{
+            phase: "accepted" | "installing" | "preparing" | "settled";
+            mechanism: "managed_npm" | "vendor_script" | "vendor_updater" | null;
+            target: {
+                kind: "baseline" | "latest" | "previous" | "version";
+                version: string | null;
+            };
+            before: {
+                version: string | null;
+                binary: string | null;
+                selection: "managed" | "missing" | "override" | "path";
+                proved: boolean;
+            } | null;
+            after: {
+                version: string | null;
+                binary: string | null;
+                selected: boolean;
+                proved: boolean;
+            } | null;
+            mutation: "applied" | "none" | "unknown";
+            termination: "confirmed" | "not_applicable" | "unconfirmed";
+            limitations: string[];
+            progress: string[];
+            problem: {
+                code: string;
+                message: string;
+                retryable: boolean;
+                fieldErrors: Record<string, string[]>;
+                requiredActions: string[];
+                evidenceRefs: string[];
+                context: Record<string, unknown>;
+            } | null;
+            id: string;
+            harness: string;
+            state: "cancelled" | "failed" | "interrupted" | "queued" | "running" | "succeeded";
+            createdAt: string;
+            startedAt: string | null;
+            finishedAt: string | null;
+        }>;
+    };
+    decorateHarnessList: <A extends unknown[]>(list: (...args: A) => Promise<unknown>) => (...args: A) => Promise<{
+        harnesses?: Array<Record<string, unknown>>;
+    }>;
+    /** Daemon composition: routes + readiness decoration on the control services. */
+    bind(services: {
+        harnesses?: (input?: never) => Promise<unknown>;
+    } & Record<string, unknown>): void;
+};
+/** The daemon's composition (claudexord.ts); readiness is bound lazily. */
+export declare function daemonHarnessMaintenance(commands: CommandAuthority, client: Pick<DaemonClient, "enqueue" | "cancel">, readiness: () => Pick<AuthReadinessService, "invalidate">): {
+    owns: (params: unknown) => boolean;
+    execute: (raw: unknown, ctx: RunContext) => Promise<{
+        phase: "accepted" | "installing" | "preparing" | "settled";
+        mechanism: "managed_npm" | "vendor_script" | "vendor_updater" | null;
+        target: {
+            kind: "baseline" | "latest" | "previous" | "version";
+            version: string | null;
+        };
+        before: {
+            version: string | null;
+            binary: string | null;
+            selection: "managed" | "missing" | "override" | "path";
+            proved: boolean;
+        } | null;
+        after: {
+            version: string | null;
+            binary: string | null;
+            selected: boolean;
+            proved: boolean;
+        } | null;
+        mutation: "applied" | "none" | "unknown";
+        termination: "confirmed" | "not_applicable" | "unconfirmed";
+        limitations: string[];
+        progress: string[];
+        problem: {
+            code: string;
+            message: string;
+            retryable: boolean;
+            fieldErrors: Record<string, string[]>;
+            requiredActions: string[];
+            evidenceRefs: string[];
+            context: Record<string, unknown>;
+        } | null;
+        lifecycle: "cancelled" | "failed" | "succeeded";
+    }>;
+    routes: {
+        maintenanceInventory: (input?: {
+            harnessIds?: string[];
+            fresh?: boolean;
+            checkLatest?: boolean;
+        }) => Promise<{
+            observedAt: string;
+            harnesses: {
+                harness: string;
+                mechanism: "managed_npm" | "vendor_script" | "vendor_updater";
+                maintainable: boolean;
+                canCheckLatest: boolean;
+                targets: ("baseline" | "latest" | "previous" | "version")[];
+                remedy: string | null;
+                selection: {
+                    kind: "managed" | "missing" | "override" | "path";
+                    binary: string | null;
+                    version: string | null;
+                    overrideEnv: string | null;
+                };
+                installed: {
+                    version: string | null;
+                    binary: string | null;
+                    proved: boolean;
+                };
+                releaseTested: {
+                    version: string | null;
+                    verification: "deterministic_only" | "release_verified" | null;
+                };
+                available: {
+                    version: string;
+                    observedAt: string;
+                } | null;
+                availableProblem: {
+                    code: string;
+                    message: string;
+                    retryable: boolean;
+                    fieldErrors: Record<string, string[]>;
+                    requiredActions: string[];
+                    evidenceRefs: string[];
+                    context: Record<string, unknown>;
+                } | null;
+                previous: {
+                    version: string;
+                    operationId: string;
+                } | null;
+                operation: {
+                    id: string;
+                    state: string;
+                    phase: string;
+                    targetVersion: string | null;
+                    finishedAt: string | null;
+                } | null;
+                observedAt: string;
+            }[];
+        }>;
+        createMaintenanceOperation: (body: unknown, idempotencyKey: string) => Promise<{
+            phase: "accepted" | "installing" | "preparing" | "settled";
+            mechanism: "managed_npm" | "vendor_script" | "vendor_updater" | null;
+            target: {
+                kind: "baseline" | "latest" | "previous" | "version";
+                version: string | null;
+            };
+            before: {
+                version: string | null;
+                binary: string | null;
+                selection: "managed" | "missing" | "override" | "path";
+                proved: boolean;
+            } | null;
+            after: {
+                version: string | null;
+                binary: string | null;
+                selected: boolean;
+                proved: boolean;
+            } | null;
+            mutation: "applied" | "none" | "unknown";
+            termination: "confirmed" | "not_applicable" | "unconfirmed";
+            limitations: string[];
+            progress: string[];
+            problem: {
+                code: string;
+                message: string;
+                retryable: boolean;
+                fieldErrors: Record<string, string[]>;
+                requiredActions: string[];
+                evidenceRefs: string[];
+                context: Record<string, unknown>;
+            } | null;
+            id: string;
+            harness: string;
+            state: "cancelled" | "failed" | "interrupted" | "queued" | "running" | "succeeded";
+            createdAt: string;
+            startedAt: string | null;
+            finishedAt: string | null;
+        }>;
+        getMaintenanceOperation: (id: string) => Promise<{
+            phase: "accepted" | "installing" | "preparing" | "settled";
+            mechanism: "managed_npm" | "vendor_script" | "vendor_updater" | null;
+            target: {
+                kind: "baseline" | "latest" | "previous" | "version";
+                version: string | null;
+            };
+            before: {
+                version: string | null;
+                binary: string | null;
+                selection: "managed" | "missing" | "override" | "path";
+                proved: boolean;
+            } | null;
+            after: {
+                version: string | null;
+                binary: string | null;
+                selected: boolean;
+                proved: boolean;
+            } | null;
+            mutation: "applied" | "none" | "unknown";
+            termination: "confirmed" | "not_applicable" | "unconfirmed";
+            limitations: string[];
+            progress: string[];
+            problem: {
+                code: string;
+                message: string;
+                retryable: boolean;
+                fieldErrors: Record<string, string[]>;
+                requiredActions: string[];
+                evidenceRefs: string[];
+                context: Record<string, unknown>;
+            } | null;
+            id: string;
+            harness: string;
+            state: "cancelled" | "failed" | "interrupted" | "queued" | "running" | "succeeded";
+            createdAt: string;
+            startedAt: string | null;
+            finishedAt: string | null;
+        }>;
+        cancelMaintenanceOperation: (id: string) => Promise<{
+            phase: "accepted" | "installing" | "preparing" | "settled";
+            mechanism: "managed_npm" | "vendor_script" | "vendor_updater" | null;
+            target: {
+                kind: "baseline" | "latest" | "previous" | "version";
+                version: string | null;
+            };
+            before: {
+                version: string | null;
+                binary: string | null;
+                selection: "managed" | "missing" | "override" | "path";
+                proved: boolean;
+            } | null;
+            after: {
+                version: string | null;
+                binary: string | null;
+                selected: boolean;
+                proved: boolean;
+            } | null;
+            mutation: "applied" | "none" | "unknown";
+            termination: "confirmed" | "not_applicable" | "unconfirmed";
+            limitations: string[];
+            progress: string[];
+            problem: {
+                code: string;
+                message: string;
+                retryable: boolean;
+                fieldErrors: Record<string, string[]>;
+                requiredActions: string[];
+                evidenceRefs: string[];
+                context: Record<string, unknown>;
+            } | null;
+            id: string;
+            harness: string;
+            state: "cancelled" | "failed" | "interrupted" | "queued" | "running" | "succeeded";
+            createdAt: string;
+            startedAt: string | null;
+            finishedAt: string | null;
+        }>;
+    };
+    decorateHarnessList: <A extends unknown[]>(list: (...args: A) => Promise<unknown>) => (...args: A) => Promise<{
+        harnesses?: Array<Record<string, unknown>>;
+    }>;
+    /** Daemon composition: routes + readiness decoration on the control services. */
+    bind(services: {
+        harnesses?: (input?: never) => Promise<unknown>;
+    } & Record<string, unknown>): void;
+};
+//# sourceMappingURL=harness-maintenance-service.d.ts.map

package/dist/harness-maintenance-service.d.ts.map

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