@norskvideo/ctl-commands 0.1.8 → 0.1.10

package/commands.d.ts

@@ -3,6 +3,16 @@ import type { CertSource, HardwareProfile, NetworkMode, ProductNetworkMode, Rest
 export type LeafCmd<F extends (...args: never[]) => unknown> = F & {
     readonly __sig: string;
 };
+/** What a leaf declares about itself, and all `toArgv` needs to render it. */
+export interface CommandSpec {
+    readonly kind: string;
+    /** argv path segments, e.g. `["instance", "launch-template"]`. */
+    readonly path: readonly string[];
+    /** Command fields emitted as bare positionals, in argv order. */
+    readonly positionals: readonly string[];
+}
+/** Every leaf's spec, by kind. */
+export declare const commandSpecs: ReadonlyMap<string, CommandSpec>;
 export interface RelaunchOpts {
     /** Raw `SPEC` / `SPEC@service` flag values; parsed into HostPort[] by the coercer. */
     hostPorts?: string[];
@@ -80,6 +90,16 @@ export interface SideloadFetchOpts {
 export interface TemplateImportOpts {
     name: string;
 }
+export interface TemplateBuildOpts {
+    /** Registered product to build from; its `/api/product-template` renders the tar. */
+    product: string;
+    /** Path to a JSON file of the product's template inputs, forwarded verbatim. */
+    input: string;
+    /** Overwrite an existing template of this name instead of failing. What makes
+     *  a re-run of a bring-up script idempotent without removing the only copy
+     *  first. Refused while an instance references the template. */
+    replace?: boolean;
+}
 export interface InstanceLaunchTemplateOpts {
     template: string;
     param?: string[];
@@ -103,148 +123,12 @@ export interface InstanceLaunchTemplateOpts {
     memoryLimit?: string;
     restartPolicy?: RestartPolicy;
 }
-export type GetResource = "versions" | "hardware" | "status" | "prerequisites";
-export type Command = {
-    kind: "config.set";
-} | {
-    kind: "config.show";
-} | {
-    kind: "fetch.mkcert";
-} | {
-    kind: "get";
-    resource: GetResource;
-} | {
-    kind: "init";
-    opts: InitOpts;
-} | {
-    kind: "inspect";
-} | {
-    kind: "instance.delete";
-    id: string;
-    opts: InstanceDeleteOpts;
-} | {
-    kind: "instance.describe";
-    id: string;
-} | {
-    kind: "instance.restart";
-    id: string;
-} | {
-    kind: "instance.stop";
-    id: string;
-} | {
-    kind: "instance.start";
-    id: string;
-} | {
-    kind: "instance.relaunch";
-    id: string;
-    opts: RelaunchOpts;
-} | {
-    kind: "instance.list";
-} | {
-    kind: "instance.exists";
-    id: string;
-} | {
-    kind: "instance.launchTemplate";
-    id: string;
-    opts: InstanceLaunchTemplateOpts;
-} | {
-    kind: "orphaned-dirs.list";
-    opts: OrphanListOpts;
-} | {
-    kind: "orphaned-dirs.clear";
-    id: string;
-} | {
-    kind: "shm.list";
-} | {
-    kind: "sideload.status";
-} | {
-    kind: "sideload.fetch";
-    opts: SideloadFetchOpts;
-} | {
-    kind: "template.list";
-} | {
-    kind: "template.show";
-    name: string;
-} | {
-    kind: "template.default";
-    product: string;
-} | {
-    kind: "template.import";
-    file: string;
-    opts: TemplateImportOpts;
-} | {
-    kind: "template.refresh";
-    name: string;
-} | {
-    kind: "template.remove";
-    name: string;
-} | {
-    kind: "product.add";
-    opts: ProductAddOpts;
-} | {
-    kind: "product.list";
-} | {
-    kind: "product.exists";
-    name: string;
-} | {
-    kind: "product.remove";
-    name: string;
-} | {
-    kind: "product.reload";
-    name: string;
-} | {
-    kind: "product.pull";
-    name: string;
-    opts: ProductPullOpts;
-} | {
-    kind: "mcp";
-} | {
-    kind: "proxy.pull";
-} | {
-    kind: "proxy.start";
-} | {
-    kind: "proxy.stop";
-} | {
-    kind: "proxy.reload";
-} | {
-    kind: "proxy.status";
-} | {
-    kind: "proxy.logs";
-    opts: ProxyLogsOpts;
-} | {
-    kind: "serve";
-} | {
-    kind: "source.start";
-    instanceId: string;
-    preset: string;
-    opts: SourceStartOpts;
-} | {
-    kind: "source.stop";
-    instanceId: string;
-    name: string;
-} | {
-    kind: "source.list";
-} | {
-    kind: "source.presets";
-} | {
-    kind: "stats";
-    opts: StatsOpts;
-} | {
-    kind: "restart";
-} | {
-    kind: "shutdown";
-    opts: ShutdownOpts;
-} | {
-    kind: "upgrade";
-    opts: UpgradeOpts;
-} | {
-    kind: "user.set";
-    name: string;
-    opts: UserSetOpts;
-} | {
-    kind: "user.delete";
-    name: string;
-};
+/** Runtime source for the `get` vocabulary — the CLI's yargs `choices` and
+ *  help text derive from it, so the type and the accepted words cannot drift.
+ *  (`versions` was removed when core's Studio version surface went away; its
+ *  route no longer exists.) */
+export declare const GET_RESOURCES: readonly ["hardware", "status", "prerequisites"];
+export type GetResource = (typeof GET_RESOURCES)[number];
 export declare const commands: {
     readonly config: {
         readonly set: LeafCmd<() => {
@@ -261,7 +145,7 @@ export declare const commands: {
     };
     readonly get: LeafCmd<(resource: GetResource) => {
         readonly kind: "get";
-        readonly resource: GetResource;
+        readonly resource: "hardware" | "status" | "prerequisites";
     }>;
     readonly init: LeafCmd<(opts: InitOpts) => {
         readonly kind: "init";
@@ -377,6 +261,11 @@ export declare const commands: {
             readonly file: string;
             readonly opts: TemplateImportOpts;
         }>;
+        readonly build: LeafCmd<(name: string, opts: TemplateBuildOpts) => {
+            readonly kind: "template.build";
+            readonly name: string;
+            readonly opts: TemplateBuildOpts;
+        }>;
         readonly refresh: LeafCmd<(name: string) => {
             readonly kind: "template.refresh";
             readonly name: string;
@@ -459,3 +348,15 @@ export declare const commands: {
         }>;
     };
 };
+/** Every leaf in a factory subtree, as a union of its `LeafCmd` types. */
+type LeavesOf<T> = T extends LeafCmd<(...args: never[]) => unknown> ? T : T extends object ? {
+    [K in keyof T]: LeavesOf<T[K]>;
+}[keyof T] : never;
+/** The constructors build `as const` objects, so their properties come back
+ *  readonly; `Command` has always been the mutable view of them. */
+type Mutable<T> = {
+    -readonly [K in keyof T]: T[K];
+};
+/** Everything the CLI can be asked to do, discriminated by `kind`. */
+export type Command = Mutable<ReturnType<LeavesOf<typeof commands>>>;
+export {};

package/commands.js

@@ -3,92 +3,112 @@
 // of stringly-typed argv arrays. Renaming or removing a CLI verb is a
 // typecheck error at the call site, not a runtime "Unknown arguments" surprise.
 //
-// Each leaf factory carries a `__sig` field with the help-display signature
-// (e.g. "launch <id>"). `describeCommands` (in ./help.ts) reads these to build
-// HelpTrees, and the `DescriptionsFor<T>` type forces every per-module
-// description object to enumerate exactly the leaves of its factory subtree —
-// drift between this file and commands/<group>.ts is a typecheck error.
+// A leaf is declared ONCE, by its kind, its constructor and its positional
+// names. Everything else falls out: the argv path is the kind's dot-segments
+// kebab-cased, the `__sig` help string is the last segment plus the
+// positionals, the `Command` union is the union of the constructors' return
+// types, and `format.toArgv` renders from the same spec. Adding a verb here
+// leaves nothing else in this package to update.
+//
+// `describeCommands` (in norsk-ctl's cli/src/typed/help.ts) reads `__sig` to
+// build HelpTrees, and the `DescriptionsFor<T>` type forces every per-module
+// description object to enumerate exactly the leaves of its factory subtree.
 //
 // Pair with `format.toArgv(cmd)` to render to a string[] for execution and
 // `format.commandToString(cmd)` for human-readable error messages.
-function leaf(sig, fn) {
+const specs = new Map();
+/** Every leaf's spec, by kind. */
+export const commandSpecs = specs;
+const camelToKebab = (s) => s.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
+function leaf(kind, fn, ...positionals) {
+    // `instance.launchTemplate` is the only kind whose argv differs from its
+    // segments, and it differs exactly by camelCase — the same transform the
+    // flag renderer applies.
+    const path = kind.split(".").map(camelToKebab);
+    const sig = [path[path.length - 1], ...positionals.map((p) => `<${String(p)}>`)].join(" ");
+    specs.set(kind, { kind, path, positionals: positionals.map(String) });
     return Object.assign(fn, { __sig: sig });
 }
+/** Runtime source for the `get` vocabulary — the CLI's yargs `choices` and
+ *  help text derive from it, so the type and the accepted words cannot drift.
+ *  (`versions` was removed when core's Studio version surface went away; its
+ *  route no longer exists.) */
+export const GET_RESOURCES = ["hardware", "status", "prerequisites"];
 // ---- Factory tree -----------------------------------------------------------
-// Mirrors cli-builder.ts. Adding a new CLI verb requires a Command variant
-// here, a leaf entry below, and (via DescriptionsFor) a description in the
-// owning command module's helpEntries.
+// Mirrors cli-builder.ts. Adding a new CLI verb is one leaf here, plus (via
+// DescriptionsFor) a description in the owning command module's helpEntries.
 export const commands = {
     config: {
-        set: leaf("set", () => ({ kind: "config.set" })),
-        show: leaf("show", () => ({ kind: "config.show" })),
+        set: leaf("config.set", () => ({ kind: "config.set" })),
+        show: leaf("config.show", () => ({ kind: "config.show" })),
     },
     fetch: {
-        mkcert: leaf("mkcert", () => ({ kind: "fetch.mkcert" })),
+        mkcert: leaf("fetch.mkcert", () => ({ kind: "fetch.mkcert" })),
     },
-    get: leaf("get <resource>", (resource) => ({ kind: "get", resource })),
+    get: leaf("get", (resource) => ({ kind: "get", resource }), "resource"),
     init: leaf("init", (opts) => ({ kind: "init", opts })),
     inspect: leaf("inspect", () => ({ kind: "inspect" })),
     instance: {
-        delete: leaf("delete <id>", (id, opts = {}) => ({ kind: "instance.delete", id, opts })),
-        describe: leaf("describe <id>", (id) => ({ kind: "instance.describe", id })),
-        restart: leaf("restart <id>", (id) => ({ kind: "instance.restart", id })),
-        stop: leaf("stop <id>", (id) => ({ kind: "instance.stop", id })),
-        start: leaf("start <id>", (id) => ({ kind: "instance.start", id })),
-        relaunch: leaf("relaunch <id>", (id, opts = {}) => ({ kind: "instance.relaunch", id, opts })),
-        list: leaf("list", () => ({ kind: "instance.list" })),
-        exists: leaf("exists <id>", (id) => ({ kind: "instance.exists", id })),
-        launchTemplate: leaf("launch-template <id>", (id, opts) => ({ kind: "instance.launchTemplate", id, opts })),
+        delete: leaf("instance.delete", (id, opts = {}) => ({ kind: "instance.delete", id, opts }), "id"),
+        describe: leaf("instance.describe", (id) => ({ kind: "instance.describe", id }), "id"),
+        restart: leaf("instance.restart", (id) => ({ kind: "instance.restart", id }), "id"),
+        stop: leaf("instance.stop", (id) => ({ kind: "instance.stop", id }), "id"),
+        start: leaf("instance.start", (id) => ({ kind: "instance.start", id }), "id"),
+        relaunch: leaf("instance.relaunch", (id, opts = {}) => ({ kind: "instance.relaunch", id, opts }), "id"),
+        list: leaf("instance.list", () => ({ kind: "instance.list" })),
+        exists: leaf("instance.exists", (id) => ({ kind: "instance.exists", id }), "id"),
+        launchTemplate: leaf("instance.launchTemplate", (id, opts) => ({ kind: "instance.launchTemplate", id, opts }), "id"),
     },
     orphanedDirs: {
-        list: leaf("list", (opts = {}) => ({ kind: "orphaned-dirs.list", opts })),
-        clear: leaf("clear <id>", (id) => ({ kind: "orphaned-dirs.clear", id })),
+        list: leaf("orphaned-dirs.list", (opts = {}) => ({ kind: "orphaned-dirs.list", opts })),
+        clear: leaf("orphaned-dirs.clear", (id) => ({ kind: "orphaned-dirs.clear", id }), "id"),
     },
     product: {
-        add: leaf("add", (opts = {}) => ({ kind: "product.add", opts })),
-        list: leaf("list", () => ({ kind: "product.list" })),
-        exists: leaf("exists <name>", (name) => ({ kind: "product.exists", name })),
-        remove: leaf("remove <name>", (name) => ({ kind: "product.remove", name })),
-        reload: leaf("reload <name>", (name) => ({ kind: "product.reload", name })),
-        pull: leaf("pull <name>", (name, opts = {}) => ({ kind: "product.pull", name, opts })),
+        add: leaf("product.add", (opts = {}) => ({ kind: "product.add", opts })),
+        list: leaf("product.list", () => ({ kind: "product.list" })),
+        exists: leaf("product.exists", (name) => ({ kind: "product.exists", name }), "name"),
+        remove: leaf("product.remove", (name) => ({ kind: "product.remove", name }), "name"),
+        reload: leaf("product.reload", (name) => ({ kind: "product.reload", name }), "name"),
+        pull: leaf("product.pull", (name, opts = {}) => ({ kind: "product.pull", name, opts }), "name"),
     },
     shm: {
-        list: leaf("list", () => ({ kind: "shm.list" })),
+        list: leaf("shm.list", () => ({ kind: "shm.list" })),
     },
     sideload: {
-        status: leaf("status", () => ({ kind: "sideload.status" })),
-        fetch: leaf("fetch", (opts = {}) => ({ kind: "sideload.fetch", opts })),
+        status: leaf("sideload.status", () => ({ kind: "sideload.status" })),
+        fetch: leaf("sideload.fetch", (opts = {}) => ({ kind: "sideload.fetch", opts })),
     },
     template: {
-        list: leaf("list", () => ({ kind: "template.list" })),
-        show: leaf("show <name>", (name) => ({ kind: "template.show", name })),
-        default: leaf("default <product>", (product) => ({ kind: "template.default", product })),
-        import: leaf("import <file>", (file, opts) => ({ kind: "template.import", file, opts })),
-        refresh: leaf("refresh <name>", (name) => ({ kind: "template.refresh", name })),
-        remove: leaf("remove <name>", (name) => ({ kind: "template.remove", name })),
+        list: leaf("template.list", () => ({ kind: "template.list" })),
+        show: leaf("template.show", (name) => ({ kind: "template.show", name }), "name"),
+        default: leaf("template.default", (product) => ({ kind: "template.default", product }), "product"),
+        import: leaf("template.import", (file, opts) => ({ kind: "template.import", file, opts }), "file"),
+        build: leaf("template.build", (name, opts) => ({ kind: "template.build", name, opts }), "name"),
+        refresh: leaf("template.refresh", (name) => ({ kind: "template.refresh", name }), "name"),
+        remove: leaf("template.remove", (name) => ({ kind: "template.remove", name }), "name"),
     },
     proxy: {
-        pull: leaf("pull", () => ({ kind: "proxy.pull" })),
-        start: leaf("start", () => ({ kind: "proxy.start" })),
-        stop: leaf("stop", () => ({ kind: "proxy.stop" })),
-        reload: leaf("reload", () => ({ kind: "proxy.reload" })),
-        status: leaf("status", () => ({ kind: "proxy.status" })),
-        logs: leaf("logs", (opts = {}) => ({ kind: "proxy.logs", opts })),
+        pull: leaf("proxy.pull", () => ({ kind: "proxy.pull" })),
+        start: leaf("proxy.start", () => ({ kind: "proxy.start" })),
+        stop: leaf("proxy.stop", () => ({ kind: "proxy.stop" })),
+        reload: leaf("proxy.reload", () => ({ kind: "proxy.reload" })),
+        status: leaf("proxy.status", () => ({ kind: "proxy.status" })),
+        logs: leaf("proxy.logs", (opts = {}) => ({ kind: "proxy.logs", opts })),
     },
     mcp: leaf("mcp", () => ({ kind: "mcp" })),
     serve: leaf("serve", () => ({ kind: "serve" })),
     source: {
-        start: leaf("start <instanceId> <preset>", (instanceId, preset, opts = {}) => ({ kind: "source.start", instanceId, preset, opts })),
-        stop: leaf("stop <instanceId> <name>", (instanceId, name) => ({ kind: "source.stop", instanceId, name })),
-        list: leaf("list", () => ({ kind: "source.list" })),
-        presets: leaf("presets", () => ({ kind: "source.presets" })),
+        start: leaf("source.start", (instanceId, preset, opts = {}) => ({ kind: "source.start", instanceId, preset, opts }), "instanceId", "preset"),
+        stop: leaf("source.stop", (instanceId, name) => ({ kind: "source.stop", instanceId, name }), "instanceId", "name"),
+        list: leaf("source.list", () => ({ kind: "source.list" })),
+        presets: leaf("source.presets", () => ({ kind: "source.presets" })),
     },
     stats: leaf("stats", (opts = {}) => ({ kind: "stats", opts })),
     restart: leaf("restart", () => ({ kind: "restart" })),
     shutdown: leaf("shutdown", (opts = {}) => ({ kind: "shutdown", opts })),
     upgrade: leaf("upgrade", (opts = {}) => ({ kind: "upgrade", opts })),
     user: {
-        set: leaf("set <name>", (name, opts) => ({ kind: "user.set", name, opts })),
-        delete: leaf("delete <name>", (name) => ({ kind: "user.delete", name })),
+        set: leaf("user.set", (name, opts) => ({ kind: "user.set", name, opts }), "name"),
+        delete: leaf("user.delete", (name) => ({ kind: "user.delete", name }), "name"),
     },
 };

package/format.d.ts

@@ -1,3 +1,3 @@
-import type { Command } from "./commands.js";
+import { type Command } from "./commands.js";
 export declare function toArgv(cmd: Command): string[];
 export declare function commandToString(cmd: Command): string;

package/format.js

@@ -3,11 +3,8 @@
 // docs). Mirrors the CLI's flag conventions: camelCase option keys become
 // --kebab-case flags; arrays become repeated --flag value pairs; boolean true
 // becomes a bare --flag, boolean false is omitted (yargs default).
+import { commandSpecs } from "./commands.js";
 const camelToKebab = (s) => s.replace(/[A-Z]/g, (m) => `-${m.toLowerCase()}`);
-/** Self-referential constraint: every key in T must map to an OptValue. Lets
- *  callers pass typed interfaces (LaunchOpts, InitOpts, …) without polluting
- *  them with index signatures, while still rejecting an opts object that
- *  carries an unsupported field shape (e.g. a Date or nested object). */
 function formatOpts(opts) {
     if (!opts)
         return [];
@@ -31,108 +28,15 @@ function formatOpts(opts) {
     return out;
 }
 export function toArgv(cmd) {
-    switch (cmd.kind) {
-        case "config.set":
-            return ["config", "set"];
-        case "config.show":
-            return ["config", "show"];
-        case "fetch.mkcert":
-            return ["fetch", "mkcert"];
-        case "get":
-            return ["get", cmd.resource];
-        case "init":
-            return ["init", ...formatOpts(cmd.opts)];
-        case "inspect":
-            return ["inspect"];
-        case "instance.delete":
-            return ["instance", "delete", cmd.id, ...formatOpts(cmd.opts)];
-        case "instance.describe":
-            return ["instance", "describe", cmd.id];
-        case "instance.restart":
-            return ["instance", "restart", cmd.id];
-        case "instance.stop":
-            return ["instance", "stop", cmd.id];
-        case "instance.start":
-            return ["instance", "start", cmd.id];
-        case "instance.relaunch":
-            return ["instance", "relaunch", cmd.id, ...formatOpts(cmd.opts)];
-        case "instance.list":
-            return ["instance", "list"];
-        case "instance.exists":
-            return ["instance", "exists", cmd.id];
-        case "instance.launchTemplate":
-            return ["instance", "launch-template", cmd.id, ...formatOpts(cmd.opts)];
-        case "orphaned-dirs.list":
-            return ["orphaned-dirs", "list", ...formatOpts(cmd.opts)];
-        case "orphaned-dirs.clear":
-            return ["orphaned-dirs", "clear", cmd.id];
-        case "product.add":
-            return ["product", "add", ...formatOpts(cmd.opts)];
-        case "product.list":
-            return ["product", "list"];
-        case "product.exists":
-            return ["product", "exists", cmd.name];
-        case "product.remove":
-            return ["product", "remove", cmd.name];
-        case "product.reload":
-            return ["product", "reload", cmd.name];
-        case "product.pull":
-            return ["product", "pull", cmd.name, ...formatOpts(cmd.opts)];
-        case "shm.list":
-            return ["shm", "list"];
-        case "sideload.status":
-            return ["sideload", "status"];
-        case "sideload.fetch":
-            return ["sideload", "fetch", ...formatOpts(cmd.opts)];
-        case "template.list":
-            return ["template", "list"];
-        case "template.show":
-            return ["template", "show", cmd.name];
-        case "template.default":
-            return ["template", "default", cmd.product];
-        case "template.import":
-            return ["template", "import", cmd.file, ...formatOpts(cmd.opts)];
-        case "template.refresh":
-            return ["template", "refresh", cmd.name];
-        case "template.remove":
-            return ["template", "remove", cmd.name];
-        case "mcp":
-            return ["mcp"];
-        case "proxy.pull":
-            return ["proxy", "pull"];
-        case "proxy.start":
-            return ["proxy", "start"];
-        case "proxy.stop":
-            return ["proxy", "stop"];
-        case "proxy.reload":
-            return ["proxy", "reload"];
-        case "proxy.status":
-            return ["proxy", "status"];
-        case "proxy.logs":
-            return ["proxy", "logs", ...formatOpts(cmd.opts)];
-        case "serve":
-            return ["serve"];
-        case "source.start":
-            return ["source", "start", cmd.instanceId, cmd.preset, ...formatOpts(cmd.opts)];
-        case "source.stop":
-            return ["source", "stop", cmd.instanceId, cmd.name];
-        case "source.list":
-            return ["source", "list"];
-        case "source.presets":
-            return ["source", "presets"];
-        case "stats":
-            return ["stats", ...formatOpts(cmd.opts)];
-        case "restart":
-            return ["restart"];
-        case "shutdown":
-            return ["shutdown", ...formatOpts(cmd.opts)];
-        case "upgrade":
-            return ["upgrade", ...formatOpts(cmd.opts)];
-        case "user.set":
-            return ["user", "set", cmd.name, ...formatOpts(cmd.opts)];
-        case "user.delete":
-            return ["user", "delete", cmd.name];
-    }
+    const spec = commandSpecs.get(cmd.kind);
+    if (!spec)
+        throw new Error(`toArgv: '${cmd.kind}' is not a declared command kind`);
+    const fields = cmd;
+    return [
+        ...spec.path,
+        ...spec.positionals.map((name) => String(fields[name])),
+        ...formatOpts(fields.opts),
+    ];
 }
 export function commandToString(cmd) {
     return ["norsk-ctl", ...toArgv(cmd)].join(" ");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-commands",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "exports": {
     ".": {