@norskvideo/ctl-commands 0.1.0

package/commands.d.ts

@@ -0,0 +1,404 @@
+import type { CertSource, HardwareProfile, NetworkMode, ProductNetworkMode, RestartPolicy } from "./types.js";
+/** A factory function tagged with its help-display signature. */
+export type LeafCmd<F extends (...args: never[]) => unknown> = F & {
+    readonly __sig: string;
+};
+export interface RelaunchOpts {
+    /** Raw `SPEC` / `SPEC@service` flag values; parsed into HostPort[] by the coercer. */
+    hostPorts?: string[];
+}
+export interface InstanceDeleteOpts {
+    /** Also delete the working directory — backend honours it only for a
+     *  runner-created dir that clears the safety guard (see ADR 0001). */
+    purge?: boolean;
+}
+export interface OrphanListOpts {
+    /** Omit for the human-readable table; set to dump the raw entries. */
+    output?: "yaml" | "json";
+}
+export interface InitOpts {
+    networkMode: NetworkMode;
+    workingDirectory?: string;
+    certPath?: string;
+    keyPath?: string;
+    certSource?: CertSource;
+    proxyUser?: string;
+    proxyPassword?: string;
+    proxyPort?: number;
+    httpRedirect?: boolean;
+    force?: boolean;
+}
+export interface ProxyLogsOpts {
+    type?: "access" | "error";
+    lines?: number;
+    follow?: boolean;
+}
+export interface SourceStartOpts {
+    port?: number;
+}
+export interface StatsOpts {
+    output?: "table" | "yaml" | "json";
+}
+export interface ShutdownOpts {
+    daemonOnly?: boolean;
+}
+export interface UpgradeOpts {
+    version?: string;
+    channel?: "latest" | "stable" | "beta";
+    list?: boolean;
+    dryRun?: boolean;
+    maxVersions?: number;
+}
+export interface UserSetOpts {
+    password: string;
+}
+export interface ProductAddOpts {
+    image?: string;
+    devUrl?: string;
+    /** BYOL license file path — required unless marketplaceProvider is given. */
+    licenseFile?: string;
+    marketplaceProvider?: string;
+}
+export interface TemplateImportOpts {
+    name: string;
+}
+export interface InstanceLaunchTemplateOpts {
+    template: string;
+    param?: string[];
+    networkMode?: ProductNetworkMode;
+    /** Raw `SPEC` / `SPEC@service` flag values; parsed into HostPort[] by the coercer. */
+    hostPorts?: string[];
+    hardware?: HardwareProfile;
+    sidecars?: string[];
+    cpuPinning?: number[];
+    cpuCount?: number;
+    containerUser?: string;
+    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: "template.list";
+} | {
+    kind: "template.show";
+    name: string;
+} | {
+    kind: "template.default";
+    product: string;
+} | {
+    kind: "template.import";
+    file: string;
+    opts: TemplateImportOpts;
+} | {
+    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;
+} | {
+    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;
+};
+export declare const commands: {
+    readonly config: {
+        readonly set: LeafCmd<() => {
+            readonly kind: "config.set";
+        }>;
+        readonly show: LeafCmd<() => {
+            readonly kind: "config.show";
+        }>;
+    };
+    readonly fetch: {
+        readonly mkcert: LeafCmd<() => {
+            readonly kind: "fetch.mkcert";
+        }>;
+    };
+    readonly get: LeafCmd<(resource: GetResource) => {
+        readonly kind: "get";
+        readonly resource: GetResource;
+    }>;
+    readonly init: LeafCmd<(opts: InitOpts) => {
+        readonly kind: "init";
+        readonly opts: InitOpts;
+    }>;
+    readonly inspect: LeafCmd<() => {
+        readonly kind: "inspect";
+    }>;
+    readonly instance: {
+        readonly delete: LeafCmd<(id: string, opts?: InstanceDeleteOpts) => {
+            readonly kind: "instance.delete";
+            readonly id: string;
+            readonly opts: InstanceDeleteOpts;
+        }>;
+        readonly describe: LeafCmd<(id: string) => {
+            readonly kind: "instance.describe";
+            readonly id: string;
+        }>;
+        readonly restart: LeafCmd<(id: string) => {
+            readonly kind: "instance.restart";
+            readonly id: string;
+        }>;
+        readonly stop: LeafCmd<(id: string) => {
+            readonly kind: "instance.stop";
+            readonly id: string;
+        }>;
+        readonly start: LeafCmd<(id: string) => {
+            readonly kind: "instance.start";
+            readonly id: string;
+        }>;
+        readonly relaunch: LeafCmd<(id: string, opts?: RelaunchOpts) => {
+            readonly kind: "instance.relaunch";
+            readonly id: string;
+            readonly opts: RelaunchOpts;
+        }>;
+        readonly list: LeafCmd<() => {
+            readonly kind: "instance.list";
+        }>;
+        readonly exists: LeafCmd<(id: string) => {
+            readonly kind: "instance.exists";
+            readonly id: string;
+        }>;
+        readonly launchTemplate: LeafCmd<(id: string, opts: InstanceLaunchTemplateOpts) => {
+            readonly kind: "instance.launchTemplate";
+            readonly id: string;
+            readonly opts: InstanceLaunchTemplateOpts;
+        }>;
+    };
+    readonly orphanedDirs: {
+        readonly list: LeafCmd<(opts?: OrphanListOpts) => {
+            readonly kind: "orphaned-dirs.list";
+            readonly opts: OrphanListOpts;
+        }>;
+        readonly clear: LeafCmd<(id: string) => {
+            readonly kind: "orphaned-dirs.clear";
+            readonly id: string;
+        }>;
+    };
+    readonly product: {
+        readonly add: LeafCmd<(opts?: ProductAddOpts) => {
+            readonly kind: "product.add";
+            readonly opts: ProductAddOpts;
+        }>;
+        readonly list: LeafCmd<() => {
+            readonly kind: "product.list";
+        }>;
+        readonly exists: LeafCmd<(name: string) => {
+            readonly kind: "product.exists";
+            readonly name: string;
+        }>;
+        readonly remove: LeafCmd<(name: string) => {
+            readonly kind: "product.remove";
+            readonly name: string;
+        }>;
+        readonly reload: LeafCmd<(name: string) => {
+            readonly kind: "product.reload";
+            readonly name: string;
+        }>;
+        readonly pull: LeafCmd<(name: string) => {
+            readonly kind: "product.pull";
+            readonly name: string;
+        }>;
+    };
+    readonly template: {
+        readonly list: LeafCmd<() => {
+            readonly kind: "template.list";
+        }>;
+        readonly show: LeafCmd<(name: string) => {
+            readonly kind: "template.show";
+            readonly name: string;
+        }>;
+        readonly default: LeafCmd<(product: string) => {
+            readonly kind: "template.default";
+            readonly product: string;
+        }>;
+        readonly import: LeafCmd<(file: string, opts: TemplateImportOpts) => {
+            readonly kind: "template.import";
+            readonly file: string;
+            readonly opts: TemplateImportOpts;
+        }>;
+        readonly remove: LeafCmd<(name: string) => {
+            readonly kind: "template.remove";
+            readonly name: string;
+        }>;
+    };
+    readonly proxy: {
+        readonly pull: LeafCmd<() => {
+            readonly kind: "proxy.pull";
+        }>;
+        readonly start: LeafCmd<() => {
+            readonly kind: "proxy.start";
+        }>;
+        readonly stop: LeafCmd<() => {
+            readonly kind: "proxy.stop";
+        }>;
+        readonly reload: LeafCmd<() => {
+            readonly kind: "proxy.reload";
+        }>;
+        readonly status: LeafCmd<() => {
+            readonly kind: "proxy.status";
+        }>;
+        readonly logs: LeafCmd<(opts?: ProxyLogsOpts) => {
+            readonly kind: "proxy.logs";
+            readonly opts: ProxyLogsOpts;
+        }>;
+    };
+    readonly mcp: LeafCmd<() => {
+        readonly kind: "mcp";
+    }>;
+    readonly serve: LeafCmd<() => {
+        readonly kind: "serve";
+    }>;
+    readonly source: {
+        readonly start: LeafCmd<(instanceId: string, preset: string, opts?: SourceStartOpts) => {
+            readonly kind: "source.start";
+            readonly instanceId: string;
+            readonly preset: string;
+            readonly opts: SourceStartOpts;
+        }>;
+        readonly stop: LeafCmd<(instanceId: string, name: string) => {
+            readonly kind: "source.stop";
+            readonly instanceId: string;
+            readonly name: string;
+        }>;
+        readonly list: LeafCmd<() => {
+            readonly kind: "source.list";
+        }>;
+        readonly presets: LeafCmd<() => {
+            readonly kind: "source.presets";
+        }>;
+    };
+    readonly stats: LeafCmd<(opts?: StatsOpts) => {
+        readonly kind: "stats";
+        readonly opts: StatsOpts;
+    }>;
+    readonly restart: LeafCmd<() => {
+        readonly kind: "restart";
+    }>;
+    readonly shutdown: LeafCmd<(opts?: ShutdownOpts) => {
+        readonly kind: "shutdown";
+        readonly opts: ShutdownOpts;
+    }>;
+    readonly upgrade: LeafCmd<(opts?: UpgradeOpts) => {
+        readonly kind: "upgrade";
+        readonly opts: UpgradeOpts;
+    }>;
+    readonly user: {
+        readonly set: LeafCmd<(name: string, opts: UserSetOpts) => {
+            readonly kind: "user.set";
+            readonly name: string;
+            readonly opts: UserSetOpts;
+        }>;
+        readonly delete: LeafCmd<(name: string) => {
+            readonly kind: "user.delete";
+            readonly name: string;
+        }>;
+    };
+};

package/commands.js

@@ -0,0 +1,86 @@
+// Typed CLI command factory. Mirrors the yargs hierarchy in cli-builder.ts so
+// callers (mostly tests) can express commands with full type checking instead
+// 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.
+//
+// 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) {
+    return Object.assign(fn, { __sig: sig });
+}
+// ---- 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.
+export const commands = {
+    config: {
+        set: leaf("set", () => ({ kind: "config.set" })),
+        show: leaf("show", () => ({ kind: "config.show" })),
+    },
+    fetch: {
+        mkcert: leaf("mkcert", () => ({ kind: "fetch.mkcert" })),
+    },
+    get: leaf("get <resource>", (resource) => ({ kind: "get", 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 })),
+    },
+    orphanedDirs: {
+        list: leaf("list", (opts = {}) => ({ kind: "orphaned-dirs.list", opts })),
+        clear: leaf("clear <id>", (id) => ({ kind: "orphaned-dirs.clear", 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) => ({ kind: "product.pull", name })),
+    },
+    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 })),
+        remove: leaf("remove <name>", (name) => ({ kind: "template.remove", 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 })),
+    },
+    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" })),
+    },
+    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 })),
+    },
+};

package/format.d.ts

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

package/format.js

@@ -0,0 +1,131 @@
+// Pretty-printer for typed Commands. Render to either an argv string[] (for
+// spawning the CLI) or a single human-readable string (for error messages and
+// 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).
+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 [];
+    const out = [];
+    for (const [key, val] of Object.entries(opts)) {
+        if (val === undefined)
+            continue;
+        const flag = `--${camelToKebab(key)}`;
+        if (typeof val === "boolean") {
+            if (val)
+                out.push(flag);
+        }
+        else if (Array.isArray(val)) {
+            for (const v of val)
+                out.push(flag, String(v));
+        }
+        else {
+            out.push(flag, String(val));
+        }
+    }
+    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];
+        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.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];
+    }
+}
+export function commandToString(cmd) {
+    return ["norsk-ctl", ...toArgv(cmd)].join(" ");
+}

package/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./commands.js";
+export * from "./format.js";
+export * from "./types.js";

package/index.js

@@ -0,0 +1,8 @@
+// Typed command surface for driving the norsk-ctl CLI. `commands` builds typed
+// Command values, `toArgv`/`commandToString` render them for spawning and for
+// error messages. Consumed by norsk-ctl's own CLI modules and by product test
+// harnesses, which pin it via a published range so a split-repo product keeps a
+// typed launch surface without reaching into norsk-ctl's source.
+export * from "./commands.js";
+export * from "./format.js";
+export * from "./types.js";

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@norskvideo/ctl-commands",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    }
+  },
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/types.d.ts

@@ -0,0 +1,5 @@
+export type NetworkMode = "docker" | "hybrid";
+export type CertSource = "mkcert" | "self-signed" | "user" | "certbot";
+export type HardwareProfile = "none" | "nvidia" | "quadra";
+export type ProductNetworkMode = "docker" | "hybrid";
+export type RestartPolicy = "unless-stopped" | "always" | "on-failure" | "no";

package/types.js

@@ -0,0 +1,7 @@
+// The ctl CLI's launch/config option vocabulary. These closed unions mirror the
+// zod enums in norsk-ctl's API spec (shared/src/spec/schemas). They are copied
+// rather than imported because this package publishes standalone — it cannot
+// depend on norsk-ctl's private spec. norsk-ctl carries a drift-guard test
+// (commands-vocab.guard.test.ts) that fails typecheck/CI the moment a union
+// here diverges from the spec it shadows.
+export {};