@lotics/cli 0.75.0 → 0.76.1

package/README.md

@@ -197,7 +197,7 @@ lotics ui link card --remove               # finalize: PR + publish, then drop t
 
 ## App packages
 
-A maintained, versioned app library: author once, install into many workspaces, upgrade per-workspace. Any org authors its own packages (publishing is owner-org-only); Lotics-backed packages carry the `official` badge. See `docs/app_packages.md` for the model.
+A maintained, versioned app library: author once, install into many workspaces, upgrade per-workspace. Any org authors its own packages (publishing is owner-org-only); Lotics-backed packages carry the `official` badge. See `docs/packages.md` for the model.
 
 ```bash
 # Author (any org admin; the package is owned by your org)
@@ -210,13 +210,19 @@ lotics package sync --workspace wsp_dev    # migrate the dev installation only
 lotics package reset --workspace wsp_dev   # DEV-ONLY: drop scaffolded tables, re-scaffold clean
 
 # Operate installations (workspace admin)
+lotics package show apg_...                # registry metadata + version history (trust badge, channel, yank)
 lotics package install apg_... --version 2 # scaffold + materialize + deploy + pin
+lotics package install apg_... --config heading="Ops board"   # per-knob overrides over contract defaults
+lotics package config app_... --set show_done=false           # edit a live installation's config (partial merge)
+lotics package uninstall app_... [--archive-tables]           # remove an installation; workflows stop firing
+lotics package retire apg_... [--undo]     # owner-org: refuse NEW installs (existing keep working + upgrading)
 lotics package doctor app_...              # version pin vs latest + drift + local edits (exit 1 on findings)
 lotics package rebind-role app_... <alias> <grp_id>  # re-point a package role at another group (re-materializes)
 lotics package upgrade app_...             # preview, then apply (additive; overlay preserved)
 lotics package fleet-upgrade apg_...       # upgrade EVERY org installation (clean ones apply; findings skip, exit 1)
 lotics package upgrade app_... --resolve fields.deal.stage=recreate   # resolve reported drift
 lotics package upgrade app_... --resolve queries.tasks=keep           # consent for a local edit (or =revert)
+lotics package upgrade app_... --resolve template.quote=revert        # a locally-edited template (clean ones auto-update; or =keep)
 lotics package eject app_...               # one-way: sever the package link
 lotics workspace doctor                    # dangling schema references across the workspace (exit 1 on findings)
 
@@ -233,6 +239,35 @@ lotics package adopt app_...               # bind the package onto the origin ap
 
 Extract writes `.lotics/adopt_binding.json` (the origin pin, excluded from published bundles); `adopt` reads it back and refuses a pin recorded for a different app. After promotion the package project is the master — iterate contract-first (`package dev`/`sync` → `publish`), never extract again.
 
+### Content packages
+
+A **content** package ships **knowledge docs and/or document templates** — no app, just the artifacts. Knowledge is the reference corpus an agent looks up by name; templates are standalone document templates. Content comes two ways: bundled *with an app* (installing the app delivers its agents' docs) or as a standalone content package (a versioned corpus). Install delivers, upgrade refreshes — preserving stable `kdc_`/`tmpl_` ids + a version snapshot per change. See `docs/packages.md` § Content.
+
+```bash
+# Author a content package (scaffolds a knowledge/ dir + manifest; add templates/ + a
+# lotics.package.templates entry per template — inline html/email or file-backed excel/word/pdf-form)
+lotics package new my-sops --kind content
+lotics package publish -m "v1: SOP corpus + templates"
+
+# Install into a workspace (a same-named local DOC collides — consent with --bind-to; templates never collide)
+lotics package install apg_...                          # app OR content, kind-branched
+lotics package install apg_... --bind-to policy=kdc_... # adopt an existing doc as package-managed
+
+# Discover installed content (the source for a pci_ id — install prints it once)
+lotics package list-content                           # id · package · version · standalone vs app-bundled
+
+# Refresh a standalone content install (pci_ id from install / list-content) — one gate over docs + templates
+lotics package upgrade pci_...                          # preview, then apply
+lotics package upgrade pci_... --resolve policy=apply   # a doc: apply|keep|archive|recreate|unbind
+lotics package upgrade pci_... --resolve quote=revert   # a locally-edited template: revert|keep (clean ones auto-update)
+lotics package upgrade pci_... --apply-all              # accept upstream for every doc + template (OVERWRITES local edits)
+lotics package uninstall pci_... --keep-content            # remove the pin; keep docs + templates (default archives them)
+```
+
+A package's knowledge can also arrive **bundled with an app**. Upgrading such an app (`lotics package upgrade <app_id>`) previews its bundled-knowledge changes alongside the plan and resolves them with the SAME flags: a `--resolve <alias>=apply|keep|archive|recreate|unbind` naming a bundled doc routes to the doc (anything else stays a core-artifact resolution; a name that is both errors), `--bind-to` consents an added-doc collision, `--apply-all` takes the package's version for every consent-requiring doc.
+
+To package the knowledge an existing app's agents route to, declare it in the app project's `package.json#lotics.knowledge` (`[{ alias, doc_id }]`, + `lotics.knowledge_expects` for docs the agents assume but the package doesn't own), then `lotics package extract` / `adopt` as usual.
+
 ## SDK
 
 ```typescript

package/dist/app_commands.d.ts

@@ -117,6 +117,22 @@ export declare function runNpm(args: string[], cwd: string): Promise<void>;
  * the author fixes the config.
  */
 export declare function ensureAppTsconfig(projectDir: string): void;
+/**
+ * Write the three `.lotics/app_{workflows,queries,agents}.d.ts` companions from
+ * the manifest's maps, then heal the app's tsconfig so they actually load. Called
+ * from `app create / pull / dev / deploy / codegen`, so the augmented `AppWorkflows`
+ * / `AppQueries` / `AppAgents` types stay in sync with the manifest.
+ *
+ * The heal is at the write boundary on purpose: a `.d.ts` written but not loaded is
+ * useless (a bare `.lotics` include is skipped by TypeScript's include-glob walk and
+ * loads zero of them), so `ensureAppTsconfig` couples "wrote the types" with "the
+ * program can see them" — no caller can do one without the other.
+ */
+export declare function writeAppDts(projectDir: string, manifest: {
+    workflows?: Record<string, AppWorkflowDeclaration>;
+    queries?: Record<string, AppQueryDeclaration>;
+    agents?: Record<string, AppAgentDeclaration>;
+}): string[];
 /**
  * `lotics app codegen [path]` — regenerate every `.lotics/` artifact from the
  * manifest + workspace schema, WITHOUT a deploy. The `.d.ts` companions are

package/dist/app_commands.js

@@ -386,7 +386,7 @@ export function ensureAppTsconfig(projectDir) {
  * loads zero of them), so `ensureAppTsconfig` couples "wrote the types" with "the
  * program can see them" — no caller can do one without the other.
  */
-function writeAppDts(projectDir, manifest) {
+export function writeAppDts(projectDir, manifest) {
     const dotLotics = path.join(projectDir, ".lotics");
     fs.mkdirSync(dotLotics, { recursive: true });
     const written = [

package/dist/args.d.ts

@@ -50,9 +50,30 @@ export declare function parseArgs(argv: string[]): {
          * `--resolve <key>=recreate|revert|keep|<id>` (repeatable): upgrade
          * resolutions — drift entries (`<namespace.alias>`) take `recreate` or an
          * existing id; modified-core entries (`<kind>.<alias>`) take `revert` or
-         * `keep`.
+         * `keep`. For a standalone KNOWLEDGE upgrade, `<alias>=apply|keep|archive|
+         * recreate|unbind`.
          */
         resolve: string[];
+        /**
+         * `--bind-to <alias>=<kdc_id>` (repeatable): consent to adopt an existing
+         * same-named doc as package-managed — resolves a knowledge name collision at
+         * install / a created-doc collision at upgrade.
+         */
+        bindTo: string[];
+        /** `--keep-content` (`package uninstall` of a content install): retain the package-bound docs instead of archiving them. */
+        keepContent: boolean;
+        /** `--apply-all` (knowledge `package upgrade`): accept the package's version for every consent entry. */
+        applyAll: boolean;
+        /** `--kind <app|content>` (`package new`): the package project kind to scaffold (default app). */
+        kind?: string;
+        /** `--config key=value` (repeatable): per-knob config overrides at `package install`. */
+        config: string[];
+        /** `--set key=value` (repeatable): per-knob config edits at `package config`. */
+        set: string[];
+        /** `--archive-tables` (`package uninstall` of an app install): also archive the scaffolded tables. */
+        archiveTables: boolean;
+        /** `--undo`: reverse a `package retire` / `package yank`. */
+        undo: boolean;
         version: boolean;
         help: boolean;
     };

package/dist/args.js

@@ -31,6 +31,14 @@ export function parseArgs(argv) {
         cleanup: false,
         packageVersion: undefined,
         resolve: [],
+        bindTo: [],
+        keepContent: false,
+        applyAll: false,
+        kind: undefined,
+        config: [],
+        set: [],
+        archiveTables: false,
+        undo: false,
         version: false,
         help: false,
     };
@@ -106,6 +114,45 @@ export function parseArgs(argv) {
                 flags.resolve.push(value);
                 break;
             }
+            case "--bind-to": {
+                const value = argv[++i];
+                if (value === undefined || value.startsWith("-")) {
+                    throw new Error("--bind-to requires a value: <alias>=<kdc_id>.");
+                }
+                flags.bindTo.push(value);
+                break;
+            }
+            case "--keep-content":
+                flags.keepContent = true;
+                break;
+            case "--apply-all":
+                flags.applyAll = true;
+                break;
+            case "--kind":
+                flags.kind = argv[++i];
+                break;
+            case "--config": {
+                const value = argv[++i];
+                if (value === undefined || value.startsWith("-")) {
+                    throw new Error("--config requires a value: key=value (repeatable).");
+                }
+                flags.config.push(value);
+                break;
+            }
+            case "--set": {
+                const value = argv[++i];
+                if (value === undefined || value.startsWith("-")) {
+                    throw new Error("--set requires a value: key=value (repeatable).");
+                }
+                flags.set.push(value);
+                break;
+            }
+            case "--archive-tables":
+                flags.archiveTables = true;
+                break;
+            case "--undo":
+                flags.undo = true;
+                break;
             case "--version":
             case "-v": {
                 // Inside a `package` command, `--version` carries a value (the

package/dist/cli.js

@@ -14,7 +14,7 @@ import { LoticsClient, API_BASE_URL } from "./client.js";
 import { resolveContext, deleteConfig, getConfigPath, loadGlobalConfig, saveGlobalConfig, loadLocalConfig, upsertProfile, removeProfile, setActiveOrg, setSelectedWorkspace, resolveProfileByNameOrId, checkForUpdate, } from "./config.js";
 import { VERSION } from "./version.js";
 import { appCreate, appPull, appDeploy, appDev, appSetSubdomain, appRename, appVersions, appCodegen, appExecuteWorkflow, appWorkflowSet, appWorkflowPull, appWorkflowCheck, appQuerySet, appUiLink, } from "./app_commands.js";
-import { packageInstall, packageEject, packageDoctor, packageUpgrade, parseResolveFlags, packageNew, packageBuild, packagePublish, packageDev, packageSync, packageReset, packageExtract, packageAdopt, packageFleetUpgrade, packageYank, } from "./package_commands.js";
+import { packageInstall, packageUninstall, packageListContent, packageConfig, packageRetire, packageShow, parseInstallConfigFlags, packageEject, packageDoctor, packageUpgrade, packageUpgradeKnowledge, parseBindToFlags, packageNew, packageBuild, packagePublish, packageDev, packageSync, packageReset, packageExtract, packageAdopt, packageFleetUpgrade, packageYank, } from "./package_commands.js";
 import { parseArgs } from "./args.js";
 import { ingestJsonArgs } from "./inputs.js";
 import { runXlsxCommand } from "./xlsx.js";
@@ -96,22 +96,41 @@ COMMANDS
   lotics app subdomain <new-subdomain> Rename the app's public <slug>.lotics.app address
   lotics app rename "<new name>"       Rename the app's display name (launcher title)
   lotics app dev [path]                Run the app locally with HMR (RPC forwarded to prod)
-  lotics package new <name> [path]     Scaffold a package project (contract + app source)
+  lotics package new <name> [path] [--kind app|content]
+                                       Scaffold a package project — an app (contract + source)
+                                       or a content corpus (docs-only, no app source)
   lotics package build [path]          Build the publishable bundle (source + dist)
   lotics package publish [path]        Publish a new immutable package version
   lotics package dev [path]            Sync the package into a dev workspace + run the app
                                        dev server (--workspace <dev_ws> selects it)
   lotics package sync [path]           Re-sync (additive migrate + materialize) into a dev ws
   lotics package reset [path]          DEV-ONLY: drop scaffolded tables + re-scaffold clean
-  lotics package install <package> [--version N]
-                                       Install an app package into this workspace
-                                       (scaffolds the data model + deploys + materializes)
-  lotics package upgrade <app_id> [--version N] [--resolve <key>=recreate|revert|keep|<id> ...]
-                                       Preview-then-apply a package upgrade; refuses while
-                                       any drift/modified finding lacks a --resolve, and
-                                       hard-stops on breaking contract changes
+  lotics package install <package> [--version N] [--bind-to <alias>=<kdc_id> ...] [--config key=value ...]
+                                       Install a package (app: scaffolds/deploys/materializes,
+                                       --config sets its knobs; content: installs the doc corpus,
+                                       --bind-to consents to adopt a same-named doc on a collision)
+  lotics package uninstall <app_id|pci_id> [--archive-tables] [--keep-content]
+                                       Uninstall — dispatched by id. App (app_id): archives
+                                       artifacts (+ --archive-tables also archives scaffolded
+                                       tables). Content (pci_): archives its package-bound docs
+                                       unless --keep-content
+  lotics package config <app_id> [--set key=value ...]
+                                       Show or edit an installation's config knobs
+  lotics package show <package_id>     Registry metadata + version history
+  lotics package retire <package_id> [--undo]
+                                       Retire a package (refuse new installs, hide from other
+                                       orgs); existing installations keep working + upgrade
+  lotics package list-content          List the workspace's content installations
+                                       (standalone pci_ + app-bundled) — source for a pci_ id
+  lotics package upgrade <app_id|pci_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]
+                                       Preview-then-apply an upgrade. App: refuses while any
+                                       drift/modified/bundled-knowledge finding lacks a --resolve
+                                       (a knowledge-alias --resolve routes to the doc). Content
+                                       (pci_): --resolve <alias>=apply|keep|archive|recreate|unbind;
+                                       --apply-all accepts the package's version for every doc
   lotics package doctor [app_id]       Installation health: version pin vs latest, binding
-                                       drift, locally modified core (exit 1 on findings)
+                                       drift, locally modified core, knowledge drift/edits
+                                       (exit 1 on findings)
   lotics package rebind-role <app_id> <alias> <grp_id>
                                        Re-point a package role at a different group
                                        (re-materializes at the pinned version)
@@ -158,6 +177,12 @@ FLAGS
   --local            Pin the current directory (lotics org use / auth api-key)
   --dev              (lotics workspace create) Mark a throwaway app-package dev
                      workspace — required for "lotics package reset"
+  --kind <k>         (lotics package new) Package kind: app (default) or content
+  --bind-to <a>=<id> (lotics package install/upgrade, repeatable) Adopt an existing
+                     same-named doc as package-managed (resolves a knowledge collision)
+  --keep-content     (lotics package uninstall) Keep the docs instead of archiving them
+  --apply-all        (lotics package upgrade, knowledge) Accept the package's version
+                     for every doc (overwrites local edits)
   --all              (lotics auth logout) Remove every saved credential
   --version          Show version
 
@@ -576,10 +601,18 @@ async function main() {
     if (command === "package" && subcommand === "new") {
         const name = toolArgs;
         if (!name) {
-            console.error("Usage: lotics package new <name> [path]");
+            console.error("Usage: lotics package new <name> [path] [--kind app|content]");
             process.exit(1);
         }
-        await packageNew({ name, targetPath: restArgs[0] });
+        if (flags.kind !== undefined && flags.kind !== "app" && flags.kind !== "content") {
+            console.error(`Invalid --kind "${flags.kind}" — expected "app" or "content".`);
+            process.exit(1);
+        }
+        await packageNew({
+            name,
+            targetPath: restArgs[0],
+            kind: flags.kind === "content" ? "content" : "app",
+        });
         return;
     }
     if (command === "package" && subcommand === "build") {
@@ -694,15 +727,20 @@ async function main() {
     }
     if (command === "package" && !subcommand) {
         console.error("Usage:");
-        console.error("  lotics package new <name> [path]                 Scaffold a package project (contract + app source)");
+        console.error("  lotics package new <name> [path] [--kind app|content]   Scaffold a package project (app source, or docs-only)");
         console.error("  lotics package build [path]                      Build the publishable bundle (source + dist)");
         console.error("  lotics package publish [path] [-m <changelog>]   Publish a new immutable package version");
         console.error("  lotics package dev [path] [--workspace <ws>]     Sync into a dev workspace + run the app dev server");
         console.error("  lotics package sync [path] [--workspace <ws>]    Re-sync (additive migrate + materialize) into a dev workspace");
         console.error("  lotics package reset [path] [--workspace <ws>]   DEV-ONLY: drop scaffolded tables + re-scaffold clean");
-        console.error("  lotics package install <package> [--version N]   Install a package into this workspace");
-        console.error("  lotics package upgrade <app_id> [--version N] [--resolve ns.alias=recreate|<id>]   Preview + apply an upgrade");
-        console.error("  lotics package doctor [app_id]                   Health: version pin vs latest + binding drift");
+        console.error("  lotics package install <package> [--version N] [--bind-to <alias>=<kdc_id>] [--config key=value ...]   Install a package (app or content)");
+        console.error("  lotics package uninstall <app_id|pci_id> [--archive-tables] [--keep-content]   Uninstall — dispatched by id (app vs content)");
+        console.error("  lotics package config <app_id> [--set key=value ...]   Show or edit an installation's config knobs");
+        console.error("  lotics package show <package_id>                 Registry metadata + version history (channel, yank, changelog)");
+        console.error("  lotics package retire <package_id> [--undo]      Retire a package (refuse new installs; installs keep working)");
+        console.error("  lotics package list-content                      List the workspace's content installations (standalone + app-bundled)");
+        console.error("  lotics package upgrade <app_id|pci_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]   Preview + apply an upgrade");
+        console.error("  lotics package doctor [app_id]                   Health: version pin vs latest + binding/knowledge drift");
         console.error("  lotics package rebind-role <app_id> <alias> <grp_id>   Re-point a package role at another group");
         console.error("  lotics package eject <app_id>                    Sever an installation's package link");
         console.error("  lotics package extract <app_id> [path]           Promote a bespoke app to a draft package project");
@@ -738,16 +776,6 @@ async function main() {
     const { client, ctx } = requireClient(flags);
     // lotics workspace / lotics workspace list / lotics workspace select <id>
     if (command === "workspace") {
-        if (subcommand === "yank") {
-            const [packageId, versionRaw, maybeUndo] = toolArgs ? toolArgs.split(/\s+/) : [];
-            const version = Number(versionRaw);
-            if (!packageId || !Number.isInteger(version) || version <= 0) {
-                console.error("Usage: lotics package yank <package_id> <version> [--undo]");
-                process.exit(1);
-            }
-            await packageYank(client, { package_id: packageId, version, undo: maybeUndo === "--undo" });
-            return;
-        }
         if (subcommand === "doctor") {
             // The workspace command family runs before the global workspace
             // resolution — doctor needs the same first-workspace fallback every
@@ -870,7 +898,7 @@ async function main() {
         if (subcommand === "install") {
             const packageId = toolArgs;
             if (!packageId) {
-                console.error("Usage: lotics package install <package> [--version N]");
+                console.error("Usage: lotics package install <package> [--version N] [--bind-to <alias>=<kdc_id> ...]");
                 process.exit(1);
             }
             let version;
@@ -881,7 +909,60 @@ async function main() {
                     process.exit(1);
                 }
             }
-            await packageInstall(client, { package_id: packageId, version });
+            const config = flags.config.length > 0 ? parseInstallConfigFlags(flags.config) : undefined;
+            await packageInstall(client, {
+                package_id: packageId,
+                version,
+                bind_to: parseBindToFlags(flags.bindTo),
+                ...(config !== undefined ? { config } : {}),
+            });
+            return;
+        }
+        if (subcommand === "uninstall") {
+            const id = toolArgs;
+            if (!id) {
+                console.error("Usage: lotics package uninstall <app_id|pci_id> [--archive-tables] [--keep-content]");
+                console.error("Dispatched by id: an app installation (app_id; --archive-tables to also archive its " +
+                    "scaffolded tables) or a standalone content installation (pci_ id from install / " +
+                    "lotics package list-content; --keep-content to retain its docs).");
+                process.exit(1);
+            }
+            await packageUninstall(client, {
+                id,
+                keep_content: flags.keepContent,
+                archive_tables: flags.archiveTables,
+            });
+            return;
+        }
+        if (subcommand === "list-content") {
+            await packageListContent(client);
+            return;
+        }
+        if (subcommand === "config") {
+            const appId = toolArgs;
+            if (!appId) {
+                console.error("Usage: lotics package config <app_id> [--set key=value ...]");
+                process.exit(1);
+            }
+            await packageConfig(client, { app_id: appId, sets: flags.set });
+            return;
+        }
+        if (subcommand === "retire") {
+            const packageId = toolArgs;
+            if (!packageId) {
+                console.error("Usage: lotics package retire <package_id> [--undo]");
+                process.exit(1);
+            }
+            await packageRetire(client, { package_id: packageId, undo: flags.undo });
+            return;
+        }
+        if (subcommand === "show") {
+            const packageId = toolArgs;
+            if (!packageId) {
+                console.error("Usage: lotics package show <package_id>");
+                process.exit(1);
+            }
+            await packageShow(client, { package_id: packageId });
             return;
         }
         if (subcommand === "eject") {
@@ -921,6 +1002,16 @@ async function main() {
             await packageAdopt(client, { app_id: appId, version, projectDir: restArgs[0] });
             return;
         }
+        if (subcommand === "yank") {
+            const packageId = toolArgs;
+            const version = Number(restArgs[0]);
+            if (!packageId || !Number.isInteger(version) || version <= 0) {
+                console.error("Usage: lotics package yank <package_id> <version> [--undo]");
+                process.exit(1);
+            }
+            await packageYank(client, { package_id: packageId, version, undo: flags.undo });
+            return;
+        }
         if (subcommand === "fleet-upgrade") {
             const packageId = toolArgs;
             if (!packageId) {
@@ -949,7 +1040,7 @@ async function main() {
                 console.error("Usage: lotics package rebind-role <app_id> <role_alias> <grp_id>");
                 process.exit(1);
             }
-            const result = await client.rebindAppPackageRole(appId, {
+            const result = await client.rebindPackageRole(appId, {
                 role_alias: roleAlias,
                 group_id: groupId,
             });
@@ -959,9 +1050,9 @@ async function main() {
             return;
         }
         if (subcommand === "upgrade") {
-            const appId = toolArgs;
-            if (!appId) {
-                console.error("Usage: lotics package upgrade <app_id> [--version N] [--resolve <namespace.alias>=recreate|<id> ...]");
+            const target = toolArgs;
+            if (!target) {
+                console.error("Usage: lotics package upgrade <app_id | pci_installation_id> [--version N] [--resolve <key>=... ...]");
                 process.exit(1);
             }
             let version;
@@ -972,10 +1063,24 @@ async function main() {
                     process.exit(1);
                 }
             }
+            // A `pci_` id is a standalone content installation (its own upgrade
+            // pipeline); everything else is an app installation.
+            if (target.startsWith("pci_")) {
+                await packageUpgradeKnowledge(client, {
+                    installation_id: target,
+                    version,
+                    resolve: flags.resolve,
+                    bind_to: parseBindToFlags(flags.bindTo),
+                    applyAll: flags.applyAll,
+                });
+                return;
+            }
             await packageUpgrade(client, {
-                app_id: appId,
+                app_id: target,
                 version,
-                resolutions: parseResolveFlags(flags.resolve),
+                resolve: flags.resolve,
+                bindTo: flags.bindTo,
+                applyAll: flags.applyAll,
             });
             return;
         }

package/dist/cli_dispatch.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli_dispatch.test.js

@@ -0,0 +1,90 @@
+/**
+ * Dispatch smoke test over the BUILT CLI artifact — every `package` subcommand
+ * must route to its own handler, proven by its usage/refusal line appearing on
+ * a bare invocation. The dispatch in cli.ts is one hand-rolled argv walk with
+ * subcommand names repeated across command families (`doctor` exists in both
+ * `workspace` and `package`) and split positional conventions (`toolArgs` +
+ * `restArgs`), and nothing else tests it: `package yank` shipped dispatched
+ * inside the WORKSPACE family and surfaced only on the first live invocation.
+ *
+ * The fake API key satisfies `requireClient` (client construction is offline);
+ * every asserted path exits before any network call. Spawns run in an empty
+ * temp cwd so path-defaulting subcommands fail on the missing project file —
+ * which equally proves their dispatch reached the right handler.
+ */
+import { beforeAll, describe, expect, it } from "vitest";
+import { execFileSync, spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const cliBin = path.join(packageRoot, "dist", "src", "cli.js");
+const emptyCwd = fs.mkdtempSync(path.join(os.tmpdir(), "lotics-cli-dispatch-"));
+function runCli(args) {
+    const result = spawnSync(process.execPath, [cliBin, ...args], {
+        cwd: emptyCwd,
+        env: {
+            ...process.env,
+            LOTICS_API_KEY: "ltk_dispatch_smoke_fake_key_never_used_on_wire",
+            // A pinned (fake) workspace skips the pre-dispatch auto-resolution,
+            // which would otherwise hit the network (`listWorkspaces`) before any
+            // usage gate. Nothing below ever reaches the wire.
+            LOTICS_WORKSPACE: "wsp_dispatch_smoke_fake",
+            LOTICS_ORG: "",
+        },
+        encoding: "utf-8",
+        timeout: 30_000,
+    });
+    return { status: result.status, stderr: result.stderr ?? "" };
+}
+beforeAll(() => {
+    // Bundle the real artifact from src (esbuild only — no tsgo; vitest's
+    // transform already type-agnostic). ~1s.
+    execFileSync(process.execPath, ["scripts/build_cli.mjs"], { cwd: packageRoot });
+}, 120_000);
+describe("lotics package <subcommand> dispatch", () => {
+    // Positional-requiring subcommands: a bare invocation must print the
+    // subcommand's OWN usage line — reaching it proves family routing AND that
+    // the usage gate fires before any network/filesystem work.
+    const usageCases = [
+        ["install", /Usage: lotics package install/],
+        ["uninstall", /Usage: lotics package uninstall/],
+        ["config", /Usage: lotics package config/],
+        ["retire", /Usage: lotics package retire <package_id>/],
+        ["show", /Usage: lotics package show <package_id>/],
+        ["upgrade", /Usage: lotics package upgrade/],
+        ["yank", /Usage: lotics package yank <package_id> <version>/],
+        ["rebind-role", /Usage: lotics package rebind-role/],
+        ["fleet-upgrade", /Usage: lotics package fleet-upgrade/],
+        ["extract", /Usage: lotics package extract/],
+        ["adopt", /Usage: lotics package adopt/],
+        ["new", /Usage: lotics package new/],
+    ];
+    for (const [sub, usage] of usageCases) {
+        it(`routes "package ${sub}" to its handler (usage on missing args)`, () => {
+            const { status, stderr } = runCli(["package", sub]);
+            expect(stderr).toMatch(usage);
+            expect(stderr).not.toMatch(/Unknown package subcommand/);
+            expect(status).toBe(1);
+        });
+    }
+    // Path-defaulting subcommands: in an empty cwd they must fail on the missing
+    // package project — their handler's message, not the dispatcher's. (`sync`
+    // is excluded: it validates the dev workspace over the network BEFORE
+    // reading the project, so it can't be smoke-tested offline.)
+    const projectCases = ["build", "publish"];
+    for (const sub of projectCases) {
+        it(`routes "package ${sub}" to its handler (missing project in empty cwd)`, () => {
+            const { status, stderr } = runCli(["package", sub]);
+            expect(stderr).toMatch(/No package\.json in|not a package project/);
+            expect(stderr).not.toMatch(/Unknown package subcommand/);
+            expect(status).toBe(1);
+        });
+    }
+    it("still rejects a genuinely unknown subcommand", () => {
+        const { status, stderr } = runCli(["package", "frobnicate"]);
+        expect(stderr).toMatch(/Unknown package subcommand/);
+        expect(status).toBe(1);
+    });
+});