@lotics/cli 0.86.1 → 0.87.0

package/dist/cli_dispatch.test.js

@@ -1,19 +1,13 @@
 /**
- * Dispatch smoke test over the BUILT CLI artifact — every `package` subcommand,
- * the top-level consumer verbs (`install`/`uninstall`/`upgrade`), and the app
- * author verbs (publish/release/unpublish) must route to their own handler,
- * proven by the 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 (top-level verbs read the id from `subcommand`; the
- * `package` family from `toolArgs`), and nothing else tests it: `package yank`
- * shipped dispatched inside the WORKSPACE family and surfaced only on the first
- * live invocation.
+ * Dispatch smoke test over the BUILT public CLI artifact, focused on the
+ * build-vs-operate split: the packages distribution surface moved WHOLESALE to
+ * the private operator CLI (`packages/opctl`), and the public CLI keeps ZERO
+ * knowledge of it — every removed verb must fall through to the plain
+ * unknown-command refusal (no redirect, no hint), while the build surface
+ * (app/workspace/run/upload) keeps routing.
  *
  * 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.
+ * every asserted path exits before any network call.
  */
 import { beforeAll, describe, expect, it } from "vitest";
 import { execFileSync, spawnSync } from "node:child_process";
@@ -30,9 +24,6 @@ function runCli(args) {
         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: "",
         },
@@ -42,114 +33,57 @@ function runCli(args) {
     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.
+    // Bundle the real artifact from src (esbuild only — vitest's transform is
+    // 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 = [
-        ["config", /Usage: lotics package config/],
-        ["show", /Usage: lotics package show <package_id>/],
-        ["yank", /Usage: lotics package yank <package_id> <version>/],
-        // Folded into the upgrade grammar — the removed verb must redirect loudly.
-        ["rebind-role", /folded into the upgrade grammar[\s\S]*--resolve roles\./],
-    ];
-    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/);
+describe("removed packages surface — unknown commands, zero knowledge", () => {
+    // The whole distribution surface lives in opctl now. The public CLI treats
+    // the old verbs as any other unknown command — no "moved to opctl" hint.
+    for (const verb of ["install", "uninstall", "upgrade", "package"]) {
+        it(`rejects "${verb}" as an unknown command`, () => {
+            const { status, stderr } = runCli([verb, "apg_x"]);
+            expect(stderr).toMatch(new RegExp(`Unknown command: ${verb}`));
+            expect(stderr).not.toMatch(/opctl/);
             expect(status).toBe(1);
         });
     }
-    // The high-traffic consumer verbs MOVED to the top level. The old
-    // `lotics package <verb>` forms must REJECT with a redirect (never silently
-    // do nothing) — proving the removal is loud and points to the new form.
-    const movedForms = [
-        ["install", /moved to the top level.*lotics install/],
-        ["uninstall", /moved to the top level.*lotics uninstall/],
-        ["upgrade", /moved to the top level.*lotics upgrade/],
-        ["fleet-upgrade", /moved to the top level.*lotics upgrade <package_id>/],
-    ];
-    for (const [sub, redirect] of movedForms) {
-        it(`rejects the moved "package ${sub}" form with a top-level redirect`, () => {
-            const { status, stderr } = runCli(["package", sub]);
-            expect(stderr).toMatch(redirect);
+    for (const sub of ["publish", "release", "unpublish"]) {
+        it(`rejects "app ${sub}" as an unknown app subcommand`, () => {
+            const { status, stderr } = runCli(["app", sub]);
+            expect(stderr).toMatch(/Unknown app subcommand/);
+            expect(stderr).not.toMatch(/opctl/);
             expect(status).toBe(1);
         });
     }
-    // Deleted author-loop + package-project surfaces must be GONE, not silently
-    // absorbed: each now falls through to the unknown-subcommand refusal. Content
-    // packages are published via the `publish_content`/`release_content` tools
-    // (`lotics run …`), apps via `lotics app publish`/`release`.
-    for (const sub of ["dev", "sync", "reset", "extract", "adopt", "retire", "release", "new", "build", "publish"]) {
-        it(`rejects the removed "package ${sub}" subcommand`, () => {
-            const { status, stderr } = runCli(["package", sub]);
-            expect(stderr).toMatch(/Unknown package subcommand/);
-            expect(status).toBe(1);
+    it("keeps --help free of package verbs", () => {
+        const result = spawnSync(process.execPath, [cliBin, "--help"], {
+            cwd: emptyCwd,
+            encoding: "utf-8",
+            timeout: 30_000,
         });
-    }
-    it("still rejects a genuinely unknown subcommand", () => {
-        const { status, stderr } = runCli(["package", "frobnicate"]);
-        expect(stderr).toMatch(/Unknown package subcommand/);
-        expect(status).toBe(1);
+        const help = `${result.stdout}\n${result.stderr}`;
+        expect(help).not.toMatch(/opctl/);
+        expect(help).not.toMatch(/lotics install/);
+        expect(help).not.toMatch(/lotics package/);
+        expect(help).not.toMatch(/app publish/);
     });
 });
-describe("lotics top-level consumer-verb dispatch", () => {
-    // The noun-less consumer verbs route from the top level (the package id is the
-    // second positional → `subcommand`), each proven by its OWN usage line on a
-    // bare invocation — reaching it fires before any network work.
-    const usageCases = [
-        ["install", /Usage: lotics install <package_id>/],
-        ["uninstall", /Usage: lotics uninstall <app_id\|package_id>/],
-        ["upgrade", /Usage: lotics upgrade <app_id \| package_id>/],
-    ];
-    for (const [verb, usage] of usageCases) {
-        it(`routes top-level "${verb}" to its handler (usage on missing id)`, () => {
-            const { status, stderr } = runCli([verb]);
-            expect(stderr).toMatch(usage);
-            expect(stderr).not.toMatch(/Unknown command/);
-            expect(status).toBe(1);
-        });
-    }
-    // CLEAN BREAK: content installs are addressed by their PACKAGE id — an explicit
-    // `pci_` resource id must get a loud redirect to the package-id form. The redirect
-    // header prints SYNCHRONOUSLY (before the best-effort list-content resolution that
-    // spells out the exact command), so it is observable without a live registry; the
-    // process exits 1 either way (best-effort resolution fails on the fake key).
-    for (const verb of ["upgrade", "uninstall"]) {
-        it(`redirects an explicit pci_ id on "${verb}" to the package-id form`, () => {
-            const { status, stderr } = runCli([verb, "pci_dispatch_smoke_fake"]);
-            expect(stderr).toMatch(/addressed by their PACKAGE id now/);
-            expect(stderr).not.toMatch(/Unknown command/);
-            expect(status).toBe(1);
-        });
-    }
-});
-describe("lotics app author-verb dispatch", () => {
-    // `app publish` (no id, empty cwd) must fail on the missing local app
-    // manifest — its handler's message, proving routing without any network.
-    it('routes "app publish" to its handler (no app id in empty cwd)', () => {
-        const { status, stderr } = runCli(["app", "publish"]);
-        expect(stderr).toMatch(/No app id/);
-        expect(stderr).not.toMatch(/Unknown app subcommand/);
+describe("build surface keeps routing", () => {
+    it('routes "app deploy" to its handler (usage on missing -m)', () => {
+        const { status, stderr } = runCli(["app", "deploy"]);
+        expect(stderr).toMatch(/Usage: lotics app deploy/);
         expect(status).toBe(1);
     });
-    // `app release` requires -m before any resolution.
-    it('routes "app release" to its handler (usage on missing -m)', () => {
-        const { status, stderr } = runCli(["app", "release"]);
-        expect(stderr).toMatch(/Usage: lotics app release/);
-        expect(stderr).not.toMatch(/Unknown app subcommand/);
+    it('routes "download" to its usage gate', () => {
+        const { status, stderr } = runCli(["download"]);
+        expect(stderr).toMatch(/Usage:/);
+        expect(stderr).toMatch(/lotics download <file_id>/);
         expect(status).toBe(1);
     });
-    // `app unpublish` requires an id.
-    it('routes "app unpublish" to its handler (usage on missing id)', () => {
-        const { status, stderr } = runCli(["app", "unpublish"]);
-        expect(stderr).toMatch(/Usage: lotics app unpublish/);
-        expect(stderr).not.toMatch(/Unknown app subcommand/);
+    it('routes "run" to its usage gate', () => {
+        const { status, stderr } = runCli(["run"]);
+        expect(stderr).toMatch(/Usage: lotics run <tool>/);
         expect(status).toBe(1);
     });
 });

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeUpgradeEntry, ModifiedArtifact, PackageContentBinding, UpgradeResolutions } from "@lotics/shared/schemas/packages";
+import type { ContractConfigEntry, KnowledgeUpgradeEntry, ModifiedArtifact, PackageContentBinding, UpgradeResolutions } from "@lotics/shared/schemas/packages";
 /**
  * The error message for a non-ok response. A genuine JSON error (a 4xx carrying
  * a `message`) surfaces verbatim; a non-JSON body (a gateway HTML page), any
@@ -246,7 +246,7 @@ export declare class LoticsClient {
     /**
      * Uninstall a standalone content package — delete the installation row. By
      * default the package-bound docs are ARCHIVED; `keep_content` retains them as
-     * ordinary workspace docs. Admin-only. Backs `lotics uninstall`.
+     * ordinary workspace docs. Admin-only. Backs `opctl uninstall`.
      */
     uninstallContentPackage(installation_id: string, opts?: {
         keep_content?: boolean;
@@ -300,7 +300,7 @@ export declare class LoticsClient {
         } | null;
     }>>;
     /**
-     * Uninstall a package installation (backs `lotics uninstall`). Does
+     * Uninstall a package installation (backs `opctl uninstall`). Does
      * everything DELETE does plus archives the installation's lifecycle
      * artifacts; with `archive_tables` it also archives the scaffolded entity
      * tables — refused server-side unless this installation created them
@@ -314,7 +314,7 @@ export declare class LoticsClient {
         archived_table_ids: string[];
     }>;
     /**
-     * Partial-merge a package installation's config (backs `lotics package config
+     * Partial-merge a package installation's config (backs `opctl package config
      * --set`). Only the provided keys change; validated against the installed
      * contract. Returns the full effective config. Admin-only.
      */
@@ -355,13 +355,13 @@ export declare class LoticsClient {
      * org to the target version (latest when omitted) in one call. Hands-off
      * applies only where the preview is clean; installations with breaking/
      * drift/modified-core findings are skipped and reported for the normal
-     * per-installation consent flow. Backs `lotics upgrade <package_id>` (fleet).
+     * per-installation consent flow. Backs `opctl upgrade <package_id>` (fleet).
      * Admin-only; org-scoped (no workspace header needed).
      */
     /**
      * Yank / unyank a published package version — refuses NEW installs/upgrades/
      * adopts targeting it; pinned installations keep running. Owner-org
-     * admin-only. Backs `lotics package yank`.
+     * admin-only. Backs `opctl package yank`.
      */
     yankPackageVersion(package_id: string, version: number, yanked: boolean): Promise<{
         package_id: string;
@@ -385,6 +385,7 @@ export declare class LoticsClient {
                 breaking: number;
                 drift: number;
                 modified: number;
+                knowledge: number;
             };
             message?: string;
         }>;
@@ -406,7 +407,7 @@ export declare class LoticsClient {
         created_at: string;
         updated_at: string;
     }>;
-    /** Version history newest-first (no contract payloads) — backs `lotics package show`. Admin-only. */
+    /** Version history newest-first (no contract payloads) — backs `opctl package show`. Admin-only. */
     listPackageVersions(package_id: string): Promise<{
         versions: Array<{
             version: number;
@@ -504,7 +505,7 @@ export declare class LoticsClient {
     /**
      * Health check for a package installation — version pin vs. registry latest,
      * binding drift, and locally modified core artifacts. Read-only; backs
-     * `lotics package doctor`. Admin-only.
+     * `opctl package doctor`. Admin-only.
      */
     getPackageHealth(app_id: string): Promise<{
         app_id: string;
@@ -540,7 +541,7 @@ export declare class LoticsClient {
         missing_expected_docs: string[];
     }>;
     /**
-     * Preview a release — the dry run behind `lotics app release`. Runs the
+     * Preview a release — the dry run behind `opctl app release`. Runs the
      * binding-aware extract of the origin (aliases stable through the app's current
      * binding) and reports the next version number, the new + changed aliases, the
      * bundled-knowledge delta, and any extract findings (an `error` blocks the
@@ -555,6 +556,8 @@ export declare class LoticsClient {
             alias: string;
             doc_id: string;
         }>;
+        /** Config knob declarations re-declaring the config (from the manifest). */
+        config?: ContractConfigEntry[];
     }): Promise<{
         package_id: string;
         version: number;
@@ -566,6 +569,12 @@ export declare class LoticsClient {
             removed: string[];
             changed: string[];
         };
+        /** Absent from a pre-declaration server (deploy skew) — treat as empty delta. */
+        config?: {
+            added: string[];
+            removed: string[];
+            changed: string[];
+        };
         findings: ExtractFinding[];
     }>;
     /**
@@ -576,7 +585,7 @@ export declare class LoticsClient {
      * bundled-knowledge set (added/dropped/re-snapshotted docs; omitted preserves
      * the current corpus). Error findings from extract surface as a 409; a
      * missing/archived declared doc is a 400, a foreign-package doc a 409. Admin,
-     * owning-org only. Backs `lotics app release --yes`.
+     * owning-org only. Backs `opctl app release --yes`.
      */
     releasePackage(app_id: string, body: {
         changelog: string;
@@ -585,6 +594,8 @@ export declare class LoticsClient {
             alias: string;
             doc_id: string;
         }>;
+        /** Config knob declarations re-declaring the config (from the manifest). */
+        config?: ContractConfigEntry[];
     }): Promise<{
         package_id: string;
         version: number;
@@ -596,9 +607,15 @@ export declare class LoticsClient {
             removed: string[];
             changed: string[];
         };
+        /** Absent from a pre-declaration server (deploy skew) — treat as empty delta. */
+        config?: {
+            added: string[];
+            removed: string[];
+            changed: string[];
+        };
     }>;
     /**
-     * Dry-run preview of a first-release — the `GET` behind `lotics app publish`
+     * Dry-run preview of a first-release — the `GET` behind `opctl app publish`
      * (no `--yes`), the publish-side analogue of `previewPackageRelease`. The
      * server runs the same fresh-alias extract + `src/` scan the apply runs
      * (through any `renames`) and returns the package name it would mint, the
@@ -615,6 +632,8 @@ export declare class LoticsClient {
             alias: string;
             doc_id: string;
         }>;
+        /** Config knob declarations v1 would freeze (from the manifest's `lotics.config`). */
+        config?: ContractConfigEntry[];
     }): Promise<{
         app_id: string;
         package_name: string;
@@ -630,13 +649,13 @@ export declare class LoticsClient {
     }>;
     /**
      * First-release apply — mint a package from a BESPOKE app and publish v1 in one
-     * call (the `POST` behind `lotics app publish --yes`). The server extracts an
+     * call (the `POST` behind `opctl app publish --yes`). The server extracts an
      * alias-keyed contract from the app (fresh aliases; `renames` fixes them before
      * v1 freezes), creates the registry package (name/description from the app),
      * publishes v1 from the app's deployed source + dist, and pins the origin as
      * installation #1. Error findings from extract surface as a 409. An
      * already-linked app must use `releasePackage` instead. Admin-only. Backs
-     * `lotics app publish <app_id>`.
+     * `opctl app publish <app_id>`.
      */
     publishAppAsPackage(app_id: string, body: {
         renames?: Array<{
@@ -649,6 +668,8 @@ export declare class LoticsClient {
             alias: string;
             doc_id: string;
         }>;
+        /** Config knob declarations v1 freezes (from the manifest's `lotics.config`). */
+        config?: ContractConfigEntry[];
     }): Promise<{
         package_id: string;
         version: number;

package/dist/client.js

@@ -209,7 +209,7 @@ export class LoticsClient {
     /**
      * Uninstall a standalone content package — delete the installation row. By
      * default the package-bound docs are ARCHIVED; `keep_content` retains them as
-     * ordinary workspace docs. Admin-only. Backs `lotics uninstall`.
+     * ordinary workspace docs. Admin-only. Backs `opctl uninstall`.
      */
     async uninstallContentPackage(installation_id, opts = {}) {
         const qs = opts.keep_content ? "?keep_content=true" : "";
@@ -244,7 +244,7 @@ export class LoticsClient {
         return this.request("GET", `/v1/workspaces/${encodeURIComponent(workspace_id)}/content-installations`);
     }
     /**
-     * Uninstall a package installation (backs `lotics uninstall`). Does
+     * Uninstall a package installation (backs `opctl uninstall`). Does
      * everything DELETE does plus archives the installation's lifecycle
      * artifacts; with `archive_tables` it also archives the scaffolded entity
      * tables — refused server-side unless this installation created them
@@ -254,7 +254,7 @@ export class LoticsClient {
         return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/uninstall`, body);
     }
     /**
-     * Partial-merge a package installation's config (backs `lotics package config
+     * Partial-merge a package installation's config (backs `opctl package config
      * --set`). Only the provided keys change; validated against the installed
      * contract. Returns the full effective config. Admin-only.
      */
@@ -286,13 +286,13 @@ export class LoticsClient {
      * org to the target version (latest when omitted) in one call. Hands-off
      * applies only where the preview is clean; installations with breaking/
      * drift/modified-core findings are skipped and reported for the normal
-     * per-installation consent flow. Backs `lotics upgrade <package_id>` (fleet).
+     * per-installation consent flow. Backs `opctl upgrade <package_id>` (fleet).
      * Admin-only; org-scoped (no workspace header needed).
      */
     /**
      * Yank / unyank a published package version — refuses NEW installs/upgrades/
      * adopts targeting it; pinned installations keep running. Owner-org
-     * admin-only. Backs `lotics package yank`.
+     * admin-only. Backs `opctl package yank`.
      */
     async yankPackageVersion(package_id, version, yanked) {
         return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/versions/${version}/yank`, { yanked });
@@ -311,7 +311,7 @@ export class LoticsClient {
     async getPackage(package_id) {
         return this.request("GET", `/v1/packages/${encodeURIComponent(package_id)}`);
     }
-    /** Version history newest-first (no contract payloads) — backs `lotics package show`. Admin-only. */
+    /** Version history newest-first (no contract payloads) — backs `opctl package show`. Admin-only. */
     async listPackageVersions(package_id) {
         return this.request("GET", `/v1/packages/${encodeURIComponent(package_id)}/versions`);
     }
@@ -345,13 +345,13 @@ export class LoticsClient {
     /**
      * Health check for a package installation — version pin vs. registry latest,
      * binding drift, and locally modified core artifacts. Read-only; backs
-     * `lotics package doctor`. Admin-only.
+     * `opctl package doctor`. Admin-only.
      */
     async getPackageHealth(app_id) {
         return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-health`);
     }
     /**
-     * Preview a release — the dry run behind `lotics app release`. Runs the
+     * Preview a release — the dry run behind `opctl app release`. Runs the
      * binding-aware extract of the origin (aliases stable through the app's current
      * binding) and reports the next version number, the new + changed aliases, the
      * bundled-knowledge delta, and any extract findings (an `error` blocks the
@@ -365,6 +365,9 @@ export class LoticsClient {
         if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
             params.set("knowledge", JSON.stringify(opts.knowledge));
         }
+        if (opts.config !== undefined) {
+            params.set("config", JSON.stringify(opts.config));
+        }
         const query = params.toString();
         return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-release${query ? `?${query}` : ""}`);
     }
@@ -376,13 +379,13 @@ export class LoticsClient {
      * bundled-knowledge set (added/dropped/re-snapshotted docs; omitted preserves
      * the current corpus). Error findings from extract surface as a 409; a
      * missing/archived declared doc is a 400, a foreign-package doc a 409. Admin,
-     * owning-org only. Backs `lotics app release --yes`.
+     * owning-org only. Backs `opctl app release --yes`.
      */
     async releasePackage(app_id, body) {
         return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-release`, body);
     }
     /**
-     * Dry-run preview of a first-release — the `GET` behind `lotics app publish`
+     * Dry-run preview of a first-release — the `GET` behind `opctl app publish`
      * (no `--yes`), the publish-side analogue of `previewPackageRelease`. The
      * server runs the same fresh-alias extract + `src/` scan the apply runs
      * (through any `renames`) and returns the package name it would mint, the
@@ -394,6 +397,9 @@ export class LoticsClient {
         if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
             params.set("knowledge", JSON.stringify(opts.knowledge));
         }
+        if (opts.config !== undefined && opts.config.length > 0) {
+            params.set("config", JSON.stringify(opts.config));
+        }
         if (opts.renames !== undefined && opts.renames.length > 0) {
             params.set("renames", JSON.stringify(opts.renames));
         }
@@ -402,13 +408,13 @@ export class LoticsClient {
     }
     /**
      * First-release apply — mint a package from a BESPOKE app and publish v1 in one
-     * call (the `POST` behind `lotics app publish --yes`). The server extracts an
+     * call (the `POST` behind `opctl app publish --yes`). The server extracts an
      * alias-keyed contract from the app (fresh aliases; `renames` fixes them before
      * v1 freezes), creates the registry package (name/description from the app),
      * publishes v1 from the app's deployed source + dist, and pins the origin as
      * installation #1. Error findings from extract surface as a 409. An
      * already-linked app must use `releasePackage` instead. Admin-only. Backs
-     * `lotics app publish <app_id>`.
+     * `opctl app publish <app_id>`.
      */
     async publishAppAsPackage(app_id, body) {
         return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-publish`, body);