@nodetool-ai/cli 0.7.0-rc.23 → 0.8.2

package/dist/commands/validation-output.d.ts

@@ -0,0 +1,25 @@
+/**
+ * One rendering of a document validation, shared by the timeline, sketch and
+ * JS-script commands. A restored document is checked and reported exactly the
+ * way a validated one is, and all three read the same on screen.
+ */
+export interface ValidationIssueLike {
+    severity: string;
+    message: string;
+    code: string;
+    path?: string | null;
+}
+export interface ValidationLike<I extends ValidationIssueLike> {
+    ok: boolean;
+    errors: I[];
+    warnings: I[];
+}
+/** `[path]` when the issue carries one, nothing otherwise. */
+export declare function issueLocation(issue: ValidationIssueLike): string;
+/**
+ * Headline, then one line per issue — errors before warnings. `where` names the
+ * part of the document an issue points at; per-document renderers pass the
+ * locator their issue type carries and fall back to `issueLocation`.
+ */
+export declare function renderValidation<I extends ValidationIssueLike>(validation: ValidationLike<I>, where?: (issue: I) => string): string[];
+//# sourceMappingURL=validation-output.d.ts.map

package/dist/commands/validation-output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-output.d.ts","sourceRoot":"","sources":["../../src/commands/validation-output.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAED,MAAM,WAAW,cAAc,CAAC,CAAC,SAAS,mBAAmB;IAC3D,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,CAAC,EAAE,CAAC;IACZ,QAAQ,EAAE,CAAC,EAAE,CAAC;CACf;AAED,8DAA8D;AAC9D,wBAAgB,aAAa,CAAC,KAAK,EAAE,mBAAmB,GAAG,MAAM,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,mBAAmB,EAC5D,UAAU,EAAE,cAAc,CAAC,CAAC,CAAC,EAC7B,KAAK,GAAE,CAAC,KAAK,EAAE,CAAC,KAAK,MAAsB,GAC1C,MAAM,EAAE,CAaV"}

package/dist/commands/validation-output.js

@@ -0,0 +1,29 @@
+/**
+ * One rendering of a document validation, shared by the timeline, sketch and
+ * JS-script commands. A restored document is checked and reported exactly the
+ * way a validated one is, and all three read the same on screen.
+ */
+/** `[path]` when the issue carries one, nothing otherwise. */
+export function issueLocation(issue) {
+    return issue.path != null ? ` [${issue.path}]` : "";
+}
+/**
+ * Headline, then one line per issue — errors before warnings. `where` names the
+ * part of the document an issue points at; per-document renderers pass the
+ * locator their issue type carries and fall back to `issueLocation`.
+ */
+export function renderValidation(validation, where = issueLocation) {
+    const errors = validation.errors.length;
+    const warnings = validation.warnings.length;
+    const mark = validation.ok ? (warnings ? "⚠️" : "✅") : "❌";
+    const lines = ["", `${mark} ${errors} error(s), ${warnings} warning(s)`];
+    if (errors + warnings === 0)
+        return lines;
+    lines.push("");
+    for (const issue of [...validation.errors, ...validation.warnings]) {
+        const tag = issue.severity === "error" ? "error" : "warn ";
+        lines.push(`  ${tag} ${issue.message}${where(issue)} (${issue.code})`);
+    }
+    return lines;
+}
+//# sourceMappingURL=validation-output.js.map

package/dist/commands/validation-output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-output.js","sourceRoot":"","sources":["../../src/commands/validation-output.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAeH,8DAA8D;AAC9D,MAAM,UAAU,aAAa,CAAC,KAA0B;IACtD,OAAO,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;AACtD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,UAA6B,EAC7B,KAAK,GAAyB,aAAa;IAE3C,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC;IACxC,MAAM,QAAQ,GAAG,UAAU,CAAC,QAAQ,CAAC,MAAM,CAAC;IAC5C,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC3D,MAAM,KAAK,GAAG,CAAC,EAAE,EAAE,GAAG,IAAI,IAAI,MAAM,cAAc,QAAQ,aAAa,CAAC,CAAC;IACzE,IAAI,MAAM,GAAG,QAAQ,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IAE1C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,MAAM,KAAK,IAAI,CAAC,GAAG,UAAU,CAAC,MAAM,EAAE,GAAG,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACnE,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;QAC3D,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,IAAI,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,KAAK,KAAK,CAAC,IAAI,GAAG,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/commands/version-commands.d.ts

@@ -0,0 +1,94 @@
+/**
+ * `<document> versions list|show|create|restore|delete` — one registration for
+ * every document type that keeps immutable snapshots (timeline sequences,
+ * image documents, JS scripts).
+ *
+ * Each type keeps its own row shapes, table columns and messages in a
+ * `VersionCommandSpec`; the command wiring, the CAS-guarded restore order
+ * (snapshot the pre-restore state, write, re-validate) and the exit codes are
+ * written once here. `restore` mirrors the tRPC routers: an old document is
+ * restored against today's schema, so a restore whose document no longer
+ * validates exits non-zero.
+ */
+import type { Command } from "commander";
+/** A decoded JSON document, before anything validates its shape. */
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** The model calls these commands make — the whole database seam. */
+export interface VersionStore<Doc, Row> {
+    load: (id: string) => Promise<Doc | null>;
+    listVersions: (documentId: string, opts: {
+        limit?: number;
+        saveType?: string;
+    }) => Promise<Row[]>;
+    findVersion: (documentId: string, version: number) => Promise<Row | null>;
+    snapshot: (doc: Doc, opts: {
+        saveType: "manual" | "restore";
+        name?: string | null;
+    }) => Promise<Row>;
+    /**
+     * Write a version's document and settings back onto the parent document,
+     * compare-and-swap on the `updated_at` it was loaded with. Resolves to null
+     * when someone else wrote first.
+     */
+    restore: (doc: Doc, version: Row) => Promise<Doc | null>;
+    deleteVersion: (documentId: string, version: number) => Promise<void>;
+}
+interface Validation {
+    ok: boolean;
+}
+/** Everything one document type contributes to the shared commands. */
+export interface VersionCommandSpec<Doc, Row, Item, V extends Validation, Counts, Meta> {
+    /** Argument placeholder, e.g. `timeline_id`. */
+    idArg: string;
+    /** The key naming the parent document in `--json` output, e.g. `timelineId`. */
+    idKey: string;
+    /** Descriptions, verbatim — these are the documented CLI surface. */
+    descriptions: {
+        group: string;
+        list: string;
+        show: string;
+        create: string;
+        restore: string;
+        delete: string;
+        restoreJson: string;
+    };
+    notFoundDocument: (id: string) => string;
+    notFoundVersion: (id: string, version: number) => string;
+    /** Thrown when the CAS restore loses the race. */
+    conflict: string;
+    confirmDelete: (id: string, version: number) => string;
+    deleted: (id: string, version: number) => string;
+    toItem: (row: Row) => Item;
+    /** The table columns, for `list` and for `show`'s header row. */
+    tableRow: (item: Item) => Record<string, unknown>;
+    counts: (document: JsonValue | undefined) => Counts;
+    /** The line `show` prints under the table. */
+    showSummary: (counts: Counts, item: Item) => string;
+    /** The line `restore` prints on success. */
+    restoreSummary: (id: string, version: number, counts: Counts, row: Row) => string;
+    /** Extra `--json` keys describing the document after a restore. */
+    restoreJsonExtra: (doc: Doc) => Record<string, unknown>;
+    /** The render settings the validator needs, read off the version row. */
+    validateMeta: (row: Row) => Meta;
+    renderValidation: (validation: V) => string[];
+}
+/** Injected with lazy defaults so registration stays light and actions unit-test. */
+export interface VersionCommandDeps<Doc, Row, V extends Validation, Meta> {
+    store?: () => Promise<VersionStore<Doc, Row>>;
+    validate?: (document: unknown, meta: Meta) => Promise<V> | V;
+    confirmDelete?: (message: string, force?: boolean) => Promise<boolean>;
+}
+/** A version is a positive integer; anything else names itself in the error. */
+export declare function parseVersionNumber(raw: string): number;
+/** Parse a stored document without throwing — an unreadable one is a finding. */
+export declare function parseVersionDocument(raw: unknown): JsonValue;
+/** Count an array-valued field, or 0 for anything else. */
+export declare function countArray(value: unknown): number;
+export declare function registerVersionCommands<Doc, Row, Item, V extends Validation, Counts, Meta>(parent: Command, spec: VersionCommandSpec<Doc, Row, Item, V, Counts, Meta>, deps: VersionCommandDeps<Doc, Row, V, Meta>, defaults: {
+    store: () => Promise<VersionStore<Doc, Row>>;
+    validate: (document: unknown, meta: Meta) => Promise<V> | V;
+}): void;
+export {};
+//# sourceMappingURL=version-commands.d.ts.map

package/dist/commands/version-commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version-commands.d.ts","sourceRoot":"","sources":["../../src/commands/version-commands.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAMzC,oEAAoE;AACpE,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAEjC,qEAAqE;AACrE,MAAM,WAAW,YAAY,CAAC,GAAG,EAAE,GAAG;IACpC,IAAI,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IAC1C,YAAY,EAAE,CACZ,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,KACxC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACpB,WAAW,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IAC1E,QAAQ,EAAE,CACR,GAAG,EAAE,GAAG,EACR,IAAI,EAAE;QAAE,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,KAC3D,OAAO,CAAC,GAAG,CAAC,CAAC;IAClB;;;;OAIG;IACH,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,KAAK,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC;IACzD,aAAa,EAAE,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvE;AAED,UAAU,UAAU;IAClB,EAAE,EAAE,OAAO,CAAC;CACb;AAED,uEAAuE;AACvE,MAAM,WAAW,kBAAkB,CACjC,GAAG,EACH,GAAG,EACH,IAAI,EACJ,CAAC,SAAS,UAAU,EACpB,MAAM,EACN,IAAI;IAEJ,gDAAgD;IAChD,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,YAAY,EAAE;QACZ,KAAK,EAAE,MAAM,CAAC;QACd,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,gBAAgB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,MAAM,CAAC;IACzC,eAAe,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACzD,kDAAkD;IAClD,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACvD,OAAO,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;IACjD,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;IAC3B,iEAAiE;IACjE,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClD,MAAM,EAAE,CAAC,QAAQ,EAAE,SAAS,GAAG,SAAS,KAAK,MAAM,CAAC;IACpD,8CAA8C;IAC9C,WAAW,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,KAAK,MAAM,CAAC;IACpD,4CAA4C;IAC5C,cAAc,EAAE,CACd,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,GAAG,KACL,MAAM,CAAC;IACZ,mEAAmE;IACnE,gBAAgB,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxD,yEAAyE;IACzE,YAAY,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;IACjC,gBAAgB,EAAE,CAAC,UAAU,EAAE,CAAC,KAAK,MAAM,EAAE,CAAC;CAC/C;AAED,qFAAqF;AACrF,MAAM,WAAW,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS,UAAU,EAAE,IAAI;IACtE,KAAK,CAAC,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC9C,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7D,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE;AAED,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAMtD;AAED,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,CAS5D;AAED,2DAA2D;AAC3D,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEjD;AAWD,wBAAgB,uBAAuB,CACrC,GAAG,EACH,GAAG,EACH,IAAI,EACJ,CAAC,SAAS,UAAU,EACpB,MAAM,EACN,IAAI,EAEJ,MAAM,EAAE,OAAO,EACf,IAAI,EAAE,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EACzD,IAAI,EAAE,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,EAC3C,QAAQ,EAAE;IACR,KAAK,EAAE,MAAM,OAAO,CAAC,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;IAC7C,QAAQ,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;CAC7D,GACA,IAAI,CA8ON"}

package/dist/commands/version-commands.js

@@ -0,0 +1,227 @@
+import { printCommandError } from "../command-errors.js";
+import { asJson, confirm, printTable } from "./output.js";
+import { numericOptionParser } from "../numeric-options.js";
+import { isString } from "../predicates.js";
+/** A version is a positive integer; anything else names itself in the error. */
+export function parseVersionNumber(raw) {
+    const value = Number(raw.trim());
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`version must be a positive integer (got "${raw}")`);
+    }
+    return value;
+}
+/** Parse a stored document without throwing — an unreadable one is a finding. */
+export function parseVersionDocument(raw) {
+    // SAFETY: a Postgres json column arrives already decoded; either way the
+    // stored document is JSON.
+    if (!isString(raw))
+        return raw;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+/** Count an array-valued field, or 0 for anything else. */
+export function countArray(value) {
+    return Array.isArray(value) ? value.length : 0;
+}
+export function registerVersionCommands(parent, spec, deps, defaults) {
+    const openStore = deps.store ?? defaults.store;
+    const validate = deps.validate ?? defaults.validate;
+    const confirmDelete = deps.confirmDelete ??
+        ((message, force) => confirm(message, { force }));
+    const id = `<${spec.idArg}>`;
+    async function requireDocument(store, documentId) {
+        const doc = await store.load(documentId);
+        if (!doc)
+            throw new Error(spec.notFoundDocument(documentId));
+        return doc;
+    }
+    async function requireVersion(store, documentId, version) {
+        const row = await store.findVersion(documentId, version);
+        if (!row)
+            throw new Error(spec.notFoundVersion(documentId, version));
+        return row;
+    }
+    const versions = parent
+        .command("versions")
+        .description(spec.descriptions.group);
+    versions
+        .command(`list ${id}`)
+        .description(spec.descriptions.list)
+        .option("--save-type <type>", "Only manual, autosave or restore snapshots")
+        .option("--limit <n>", "Maximum versions to list (default 100)", numericOptionParser("--limit", { integer: true, min: 1 }))
+        .option("--json", "Print the versions as JSON")
+        .action(async (documentId, opts) => {
+        try {
+            const store = await openStore();
+            await requireDocument(store, documentId);
+            const query = {};
+            if (opts.limit !== undefined) {
+                query.limit = opts.limit;
+            }
+            if (opts.saveType) {
+                query.saveType = opts.saveType;
+            }
+            const rows = await store.listVersions(documentId, query);
+            const items = rows.map(spec.toItem);
+            if (opts.json) {
+                asJson({ [spec.idKey]: documentId, versions: items });
+                return;
+            }
+            printTable(items.map(spec.tableRow));
+        }
+        catch (e) {
+            printCommandError(e, opts.json);
+            process.exit(1);
+        }
+    });
+    versions
+        .command(`show ${id} <version>`)
+        .description(spec.descriptions.show)
+        .option("--json", "Print the metadata and the full document as JSON")
+        .action(async (documentId, version, opts) => {
+        try {
+            const number = parseVersionNumber(version);
+            const store = await openStore();
+            await requireDocument(store, documentId);
+            const row = await requireVersion(store, documentId, number);
+            const item = spec.toItem(row);
+            const document = parseVersionDocument(row.document);
+            if (opts.json) {
+                asJson({ ...item, document });
+                return;
+            }
+            printTable([spec.tableRow(item)]);
+            console.log(spec.showSummary(spec.counts(document), item));
+        }
+        catch (e) {
+            printCommandError(e, opts.json);
+            process.exit(1);
+        }
+    });
+    versions
+        .command(`create ${id}`)
+        .description(spec.descriptions.create)
+        .option("--name <name>", "Label for the snapshot")
+        .option("--json", "Print the created version as JSON")
+        .action(async (documentId, opts) => {
+        try {
+            const store = await openStore();
+            const doc = await requireDocument(store, documentId);
+            const row = await store.snapshot(doc, {
+                saveType: "manual",
+                name: opts.name ?? null
+            });
+            const item = spec.toItem(row);
+            if (opts.json) {
+                asJson(item);
+                return;
+            }
+            console.log(`✅ Snapshot saved as v${item.version}${item.name ? ` (${String(item.name)})` : ""}`);
+        }
+        catch (e) {
+            printCommandError(e, opts.json);
+            process.exit(1);
+        }
+    });
+    versions
+        .command(`restore ${id} <version>`)
+        .description(spec.descriptions.restore)
+        .option("--json", spec.descriptions.restoreJson)
+        .action(async (documentId, version, opts) => {
+        // The verdict leaves the try block in a variable: `process.exit` throws
+        // under test, and an exit inside the try would be caught here as a
+        // command failure.
+        let restoredOk = false;
+        try {
+            const number = parseVersionNumber(version);
+            const store = await openStore();
+            const doc = await requireDocument(store, documentId);
+            const target = await requireVersion(store, documentId, number);
+            // Snapshot what is about to be overwritten first, so the restore is
+            // itself undoable — same order the tRPC router uses.
+            const backup = await store.snapshot(doc, {
+                saveType: "restore",
+                name: `Before restore to v${number}`
+            });
+            const updated = await store.restore(doc, target);
+            if (!updated)
+                throw new Error(spec.conflict);
+            const document = parseVersionDocument(target.document);
+            const validation = await validate(document, spec.validateMeta(target));
+            if (opts.json) {
+                asJson({
+                    [spec.idKey]: documentId,
+                    restored: spec.toItem(target),
+                    snapshot: spec.toItem(backup),
+                    ...spec.restoreJsonExtra(updated),
+                    validation
+                });
+            }
+            else {
+                console.log(spec.restoreSummary(documentId, number, spec.counts(document), target));
+                const meta = backup;
+                console.log(`  pre-restore state saved as v${meta.version} (${meta.save_type})`);
+                console.log(spec.renderValidation(validation).join("\n"));
+            }
+            restoredOk = validation.ok;
+        }
+        catch (e) {
+            printCommandError(e, opts.json);
+            process.exit(1);
+        }
+        process.exit(restoredOk ? 0 : 1);
+    });
+    versions
+        .command(`delete ${id} <version>`)
+        .description(spec.descriptions.delete)
+        .option("-y, --yes", "Skip the confirmation prompt")
+        .option("--json", "Print the result as JSON")
+        .action(async (documentId, version, opts) => {
+        let aborted = false;
+        try {
+            const number = parseVersionNumber(version);
+            const store = await openStore();
+            await requireDocument(store, documentId);
+            await requireVersion(store, documentId, number);
+            const ok = await confirmDelete(spec.confirmDelete(documentId, number), opts.yes);
+            if (!ok) {
+                aborted = true;
+                if (opts.json) {
+                    asJson({
+                        [spec.idKey]: documentId,
+                        version: number,
+                        deleted: false,
+                        aborted: true
+                    });
+                }
+                else {
+                    console.error("Aborted.");
+                }
+            }
+            else {
+                await store.deleteVersion(documentId, number);
+                if (opts.json) {
+                    asJson({
+                        [spec.idKey]: documentId,
+                        version: number,
+                        deleted: true
+                    });
+                }
+                else {
+                    console.log(spec.deleted(documentId, number));
+                }
+            }
+        }
+        catch (e) {
+            printCommandError(e, opts.json);
+            process.exit(1);
+        }
+        if (aborted)
+            process.exit(1);
+    });
+}
+//# sourceMappingURL=version-commands.js.map

package/dist/commands/version-commands.js.map

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

package/dist/commands/worker-models.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `nodetool worker models` — inspect and manage the HF model cache on a
+ * remote GPU worker directly via the WebSocket bridge (no TS server required).
+ *
+ * Verbs:
+ *   worker models list   [<worker-id>] [--json]
+ *   worker models download --repo-id <id> [<worker-id>] [-a <glob>] [-i <glob>]
+ *   worker models delete  --repo-id <id> [<worker-id>]
+ */
+import type { Command } from "commander";
+import { WorkerManager } from "@nodetool-ai/compute";
+export declare function registerWorkerModelsCommands(worker: Command, getManager: () => Promise<WorkerManager>): void;
+//# sourceMappingURL=worker-models.d.ts.map

package/dist/commands/worker-models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-models.d.ts","sourceRoot":"","sources":["../../src/commands/worker-models.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EACL,aAAa,EAEd,MAAM,sBAAsB,CAAC;AA+F9B,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,OAAO,EACf,UAAU,EAAE,MAAM,OAAO,CAAC,aAAa,CAAC,GACvC,IAAI,CAQN"}

package/dist/commands/worker-models.js

@@ -0,0 +1,207 @@
+/**
+ * `nodetool worker models` — inspect and manage the HF model cache on a
+ * remote GPU worker directly via the WebSocket bridge (no TS server required).
+ *
+ * Verbs:
+ *   worker models list   [<worker-id>] [--json]
+ *   worker models download --repo-id <id> [<worker-id>] [-a <glob>] [-i <glob>]
+ *   worker models delete  --repo-id <id> [<worker-id>]
+ */
+import { attachWorkerActivityHeartbeat } from "@nodetool-ai/compute";
+import { WebsocketPythonBridge } from "@nodetool-ai/runtime";
+import { resolveWorkerHfToken } from "@nodetool-ai/huggingface";
+import { getSecret } from "@nodetool-ai/models";
+import { printTable, asJson } from "./output.js";
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+function formatBytes(n) {
+    if (!n || n <= 0)
+        return "-";
+    const units = ["B", "KB", "MB", "GB", "TB"];
+    let value = n;
+    let i = 0;
+    while (value >= 1024 && i < units.length - 1) {
+        value /= 1024;
+        i++;
+    }
+    return `${value.toFixed(1)} ${units[i]}`;
+}
+/** Local single-user id used across the TS stack for secret-store reads. */
+const LOCAL_USER_ID = "1";
+function collectOption(value, previous) {
+    return previous ? [...previous, value] : [value];
+}
+// ---------------------------------------------------------------------------
+// Bridge connection helper
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the target worker, open a WebSocket bridge, and return it.
+ * The bridge has `autoRestart: false` so it won't reconnect once closed —
+ * CLI commands are one-shot and call `bridge.close()` in a finally block.
+ *
+ * When `workerId` is omitted, falls back to the currently-attached instance.
+ */
+async function openBridge(manager, workerId) {
+    let conn;
+    let instanceId;
+    if (workerId) {
+        conn = await manager.connectionInfo(workerId);
+        instanceId = workerId;
+    }
+    else {
+        const active = await manager.getActiveWorker();
+        if (!active) {
+            throw new Error("No worker attached. Provide a worker id or attach one with `worker create --attach`.");
+        }
+        conn = { wsUrl: active.ws_url, token: active.token };
+        instanceId = active.id;
+    }
+    const bridge = new WebsocketPythonBridge({
+        wsUrl: conn.wsUrl,
+        workerToken: conn.token ?? undefined,
+        autoRestart: false
+    });
+    // A model download runs for tens of minutes and sends nothing outbound after
+    // the request — the reaper would otherwise pause the pod mid-download. This
+    // touches the worker the command names, not the attached one.
+    attachWorkerActivityHeartbeat(bridge, {
+        resolveInstanceId: async () => instanceId
+    });
+    await bridge.connect();
+    if (!bridge.supportsModelManagement()) {
+        bridge.close();
+        throw new Error("This worker's image is too old for model management (protocol_version < 2). " +
+            "Upgrade the worker image.");
+    }
+    return bridge;
+}
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+export function registerWorkerModelsCommands(worker, getManager) {
+    const models = worker
+        .command("models")
+        .description("Manage the HF model cache on a remote worker");
+    registerList(models, getManager);
+    registerDownload(models, getManager);
+    registerDelete(models, getManager);
+}
+// ---------------------------------------------------------------------------
+// worker models list
+// ---------------------------------------------------------------------------
+function registerList(models, getManager) {
+    models
+        .command("list [worker-id]")
+        .description("List cached HuggingFace models on the worker")
+        .option("--json", "Output as JSON")
+        .action(async (workerId, opts) => {
+        const manager = await getManager();
+        let bridge = null;
+        try {
+            bridge = await openBridge(manager, workerId);
+            const cached = await bridge.listCachedModels();
+            if (opts.json) {
+                asJson(cached);
+                return;
+            }
+            if (cached.length === 0) {
+                console.log("(no cached models)");
+                return;
+            }
+            printTable(cached.map((m) => ({
+                repo_id: m["repo_id"] ?? m["id"] ?? "",
+                type: m["type"] ?? "-",
+                size: formatBytes(m["size_on_disk"]),
+                pipeline: m["pipeline_tag"] ?? "-"
+            })), ["repo_id", "type", "size", "pipeline"]);
+        }
+        finally {
+            bridge?.close();
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// worker models download
+// ---------------------------------------------------------------------------
+function registerDownload(models, getManager) {
+    models
+        .command("download [worker-id]")
+        .description("Download a HuggingFace model into the worker's cache")
+        .requiredOption("--repo-id <id>", "HuggingFace repo id (owner/name)")
+        .option("--file-path <path>", "Download a single file from the repo")
+        .option("-a, --allow-patterns <pattern>", "Only download files matching this glob (repeatable)", collectOption)
+        .option("-i, --ignore-patterns <pattern>", "Skip files matching this glob (repeatable)", collectOption)
+        .action(async (workerId, opts) => {
+        const manager = await getManager();
+        let bridge = null;
+        try {
+            bridge = await openBridge(manager, workerId);
+            let lastLine = "";
+            let errorMessage = null;
+            const render = (u) => {
+                if (u.status === "error") {
+                    errorMessage = u.error ?? "download failed";
+                }
+                const pct = u.total_bytes > 0
+                    ? Math.floor((u.downloaded_bytes / u.total_bytes) * 100)
+                    : 0;
+                const line = `[${u.status}] ${u.repo_id} ${u.downloaded_files}/${u.total_files} files  ${formatBytes(u.downloaded_bytes)}/${formatBytes(u.total_bytes)}  ${pct}%`;
+                if (line !== lastLine) {
+                    process.stderr.write(`\r${line.padEnd(100)}`);
+                    lastLine = line;
+                }
+                if (u.status === "completed" ||
+                    u.status === "error" ||
+                    u.status === "cancelled") {
+                    process.stderr.write("\n");
+                }
+            };
+            // The worker holds no HuggingFace credential, so a gated repo
+            // (FLUX.1-dev, RMBG-2.0, ...) 401s unless this host supplies one.
+            const token = await resolveWorkerHfToken((key) => getSecret(key, LOCAL_USER_ID));
+            await bridge.downloadModel({
+                repo_id: opts.repoId,
+                path: opts.filePath ?? null,
+                allow_patterns: opts.allowPatterns ?? null,
+                ignore_patterns: opts.ignorePatterns ?? null,
+                token
+            }, render);
+            if (errorMessage) {
+                console.error(errorMessage);
+                process.exit(1);
+            }
+            console.log(`Downloaded '${opts.repoId}' to worker cache.`);
+        }
+        finally {
+            bridge?.close();
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// worker models delete
+// ---------------------------------------------------------------------------
+function registerDelete(models, getManager) {
+    models
+        .command("delete [worker-id]")
+        .description("Delete a cached HuggingFace model from the worker")
+        .requiredOption("--repo-id <id>", "HuggingFace repo id (owner/name)")
+        .action(async (workerId, opts) => {
+        const manager = await getManager();
+        let bridge = null;
+        try {
+            bridge = await openBridge(manager, workerId);
+            const deleted = await bridge.deleteCachedModel(opts.repoId);
+            if (deleted) {
+                console.log(`Deleted '${opts.repoId}' from worker cache.`);
+            }
+            else {
+                console.log(`'${opts.repoId}' was not found in the worker cache.`);
+            }
+        }
+        finally {
+            bridge?.close();
+        }
+    });
+}
+//# sourceMappingURL=worker-models.js.map

package/dist/commands/worker-models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-models.js","sourceRoot":"","sources":["../../src/commands/worker-models.ts"],"names":[],"mappings":"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"}