@lotics/cli 0.76.1 → 0.83.0

package/dist/cli_dispatch.test.js

@@ -1,11 +1,14 @@
 /**
- * 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.
+ * 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.
  *
  * The fake API key satisfies `requireClient` (client construction is offline);
  * every asserted path exits before any network call. Spawns run in an empty
@@ -48,18 +51,11 @@ describe("lotics package <subcommand> dispatch", () => {
     // 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/],
+        // 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)`, () => {
@@ -69,16 +65,30 @@ describe("lotics package <subcommand> dispatch", () => {
             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)`, () => {
+    // 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(/No package\.json in|not a package project/);
-            expect(stderr).not.toMatch(/Unknown package subcommand/);
+            expect(stderr).toMatch(redirect);
+            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);
         });
     }
@@ -88,3 +98,45 @@ describe("lotics package <subcommand> dispatch", () => {
         expect(status).toBe(1);
     });
 });
+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\|pci_id>/],
+        ["upgrade", /Usage: lotics upgrade <app_id \| pci_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);
+        });
+    }
+});
+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/);
+        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/);
+        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/);
+        expect(status).toBe(1);
+    });
+});

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { KnowledgeUpgradeEntry, KnowledgeUpgradeResolutions, ContentUpgradeResolutions, ModifiedArtifact, PackageContentBinding } from "@lotics/shared/schemas/packages";
+import type { 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
@@ -44,14 +44,6 @@ export interface WorkspaceInfo {
     default_currency: string;
     organization_id: string;
     created_at: string;
-    /**
-     * Whether this is a throwaway app-package dev workspace (set with
-     * `lotics workspace create <name> --dev`). Gates the destructive package
-     * dev/sync scaffold + the server-side `package reset`. Optional because the
-     * list endpoint only carries it once the server serializes `is_dev`; an absent
-     * value is treated as non-dev by the guard (fail closed).
-     */
-    is_dev?: boolean;
 }
 export interface ToolExecuteResult {
     result: unknown;
@@ -74,23 +66,7 @@ export interface FileUploadResult {
         error: string;
     }>;
 }
-/**
- * A materialized app package's binding — alias → this workspace's concrete id,
- * one string-map per namespace. Mirrors the server's `bindingSchema`. The
- * `workflows` map is the entity-lifecycle table-workflow ROW ledger (an artifact
- * registry, not a schema binding), carried in the same shape. The CLI never
- * interprets these maps — it round-trips them verbatim between `extract` (which
- * emits the origin workspace's) and `adopt` (which replays it onto the app).
- */
-export interface PackageBinding {
-    entities: Record<string, string>;
-    fields: Record<string, string>;
-    options: Record<string, string>;
-    templates: Record<string, string>;
-    roles: Record<string, string>;
-    workflows: Record<string, string>;
-}
-/** One finding from a bespoke→package extraction (`extractPackage`). */
+/** One finding from a package publish/release extract. */
 export interface ExtractFinding {
     severity: "error" | "warning" | "info";
     area: string;
@@ -143,16 +119,9 @@ export declare class LoticsClient {
     /** The workspace id the client targets (the `x-workspace-id` header), if resolved. */
     getWorkspaceId(): string | undefined;
     listWorkspaces(): Promise<WorkspaceInfo[]>;
-    /**
-     * Resolve one workspace's info by id from the org's workspace list (the only
-     * API-key-accessible source carrying `is_dev`). Returns null when the
-     * workspace isn't visible to these credentials.
-     */
-    getWorkspaceInfo(id: string): Promise<WorkspaceInfo | null>;
     createWorkspace(body: {
         name: string;
         timezone?: string;
-        is_dev?: boolean;
     }): Promise<WorkspaceInfo>;
     deleteWorkspace(id: string): Promise<{
         id: string;
@@ -277,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 package uninstall`.
+     * ordinary workspace docs. Admin-only. Backs `lotics uninstall`.
      */
     uninstallContentPackage(installation_id: string, opts?: {
         keep_content?: boolean;
@@ -314,7 +283,7 @@ export declare class LoticsClient {
      */
     applyContentInstallationUpgrade(installation_id: string, body: {
         version?: number;
-        resolutions?: ContentUpgradeResolutions;
+        resolutions?: UpgradeResolutions;
     }): Promise<ContentInstallation>;
     /**
      * List a workspace's package-managed knowledge installations, each folded with
@@ -331,7 +300,7 @@ export declare class LoticsClient {
         } | null;
     }>>;
     /**
-     * Uninstall a package installation (backs `lotics package uninstall`). Does
+     * Uninstall a package installation (backs `lotics 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
@@ -355,10 +324,11 @@ export declare class LoticsClient {
         config: Record<string, string | number | boolean>;
     }>;
     /**
-     * Retire (or `undo` un-retire) a registry package (backs `lotics package
-     * retire`). Retiring refuses NEW installs and hides the package from
-     * non-owning orgs; existing installations keep working and may still upgrade.
-     * Owner-org admin-only.
+     * Retire (or `undo` un-retire) a registry package (backs `lotics app
+     * unpublish` — the endpoint/audit action keep the `retire` name to avoid API
+     * churn). Retiring refuses NEW installs and hides the package from non-owning
+     * orgs; existing installations keep working and may still upgrade. Owner-org
+     * admin-only.
      */
     retirePackage(package_id: string, body: {
         undo: boolean;
@@ -380,65 +350,12 @@ export declare class LoticsClient {
         workspace_id: string;
         current_version_id: string | null;
     }>;
-    /**
-     * Extract a DRAFT app package from an existing bespoke app — the promotion
-     * read (docs/packages.md § Promotion). Pure: nothing is written. Returns
-     * the alias-keyed draft `contract` (opaque to the CLI — the server is the
-     * validating authority), the origin workspace's `binding` (which doubles as
-     * the adopt binding), a findings `report` (any `error` ⇒ not publishable
-     * as-is), and the file-backed `template_files` the CLI must stage into the
-     * project at their `bytes_ref` paths. Backs `lotics package extract`.
-     * Admin-only.
-     */
-    extractPackage(app_id: string, opts?: {
-        knowledge?: Array<{
-            alias: string;
-            doc_id: string;
-        }>;
-    }): Promise<{
-        contract: unknown;
-        binding: PackageBinding;
-        report: ExtractFinding[];
-        template_files: Array<{
-            bytes_ref: string;
-            file_id: string;
-            filename: string;
-        }>;
-        /** Knowledge doc content to write to `knowledge/<alias>.md` in the draft project. */
-        knowledge_files: Array<{
-            content_ref: string;
-            content: string;
-        }>;
-        /** alias → the origin workspace's kdc_ id (the adopt knowledge binding). */
-        knowledge_binding: Record<string, string>;
-    }>;
-    /**
-     * Adopt a published package onto an EXISTING (bespoke or ejected) app — the
-     * final promotion step. The workspace already holds the concrete objects, so
-     * nothing is scaffolded or rewritten: the server verifies the `binding` is
-     * complete, live, and FAITHFUL to the version's contract, then writes only the
-     * installation pin (the app becomes installation #1, upgradeable again). A
-     * ConflictError names the aliases that diverge. `version` omitted adopts the
-     * latest. Backs `lotics package adopt`. Admin-only.
-     */
-    adoptPackage(app_id: string, body: {
-        package_id: string;
-        version?: number;
-        binding: PackageBinding;
-        /** alias → this workspace's kdc_ id for the contract's knowledge docs (from extract). */
-        knowledge_binding?: Record<string, string>;
-    }): Promise<{
-        id: string;
-        name: string;
-        package_id: string | null;
-        package_version: number | null;
-    }>;
     /**
      * Fleet upgrade — bring every installation of a package across the CALLER'S
      * 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 package fleet-upgrade`.
+     * per-installation consent flow. Backs `lotics upgrade <package_id>` (fleet).
      * Admin-only; org-scoped (no workspace header needed).
      */
     /**
@@ -472,27 +389,6 @@ export declare class LoticsClient {
             message?: string;
         }>;
     }>;
-    /**
-     * Create a registry app package — the Lotics-owned, workspace-agnostic
-     * blueprint. `lotics package publish` calls this on first publish (when the
-     * local manifest has no `package_id`), then publishes version 1 against the
-     * returned id. Admin-only.
-     */
-    createPackage(body: {
-        name: string;
-        description?: string | null;
-        /** 'app' (default) | 'content'. Immutable after create. */
-        kind?: PackageKind;
-    }): Promise<{
-        id: string;
-        name: string;
-        description: string | null;
-        kind: PackageKind;
-        latest_version: number;
-        is_official: boolean;
-        created_at: string;
-        updated_at: string;
-    }>;
     /**
      * Fetch a registry app package's metadata (incl. `kind`, `latest_version` and
      * the Lotics-backed `is_official` trust badge). Admin-only; cross-tenant by id.
@@ -520,27 +416,6 @@ export declare class LoticsClient {
             created_at: string;
         }>;
     }>;
-    /**
-     * Publish a new immutable package version — multipart upload of the alias-keyed
-     * contract (JSON) + the prebuilt code bundle (a gzipped tarball carrying
-     * `source.tar.gz` + `dist.tar.gz` members). The server validates the contract +
-     * bundle, then allocates the next monotonic version. The `contract` is opaque
-     * JSON to the transport (the server is the validating authority). Admin-only.
-     */
-    publishPackageVersion(package_id: string, args: {
-        contract: unknown;
-        bundle: Buffer;
-        changelog?: string | null;
-        /** 'dev' = dev-loop publish: pinned by the dev installation, never the installable latest. */
-        channel?: "release" | "dev";
-    }): Promise<{
-        id: string;
-        package_id: string;
-        version: number;
-        bundle_r2_prefix: string;
-        changelog: string | null;
-        created_at: string;
-    }>;
     /**
      * Upgrade a package installation to a newer published version — extends the
      * binding additively, re-materializes the target version's
@@ -551,21 +426,15 @@ export declare class LoticsClient {
     upgradePackage(app_id: string, body: {
         version?: number;
         /**
-         * Per preview finding: drifted binding entries (`<namespace>.<alias>`)
-         * take `"recreate"` or `{ bind_to: "<id>" }`; locally modified
-         * artifacts (`<kind>.<alias>`) take `"revert"` or `"keep"`. Required
-         * for every finding — anything unresolved refuses the upgrade.
-         */
-        resolutions?: Record<string, "recreate" | "revert" | "keep" | {
-            bind_to: string;
-        }>;
-        /**
-         * Per bundled-knowledge finding: a consent resolution
-         * (`apply`/`keep`/`archive`/`recreate`/`unbind`) per alias + `bind_to`
-         * consents for added-doc name collisions. Consent-requiring docs left
-         * unresolved refuse the upgrade; unmodified changes apply automatically.
+         * ONE map, one namespaced grammar, per preview finding: a drifted binding
+         * entry (`<namespace>.<alias>`) takes `"recreate"` or `{ bind_to }`; a
+         * modified artifact (`<kind>.<alias>`) takes `"revert"` or `"keep"`; a
+         * bundled knowledge doc (`knowledge.<alias>`) takes
+         * `apply|keep|archive|recreate|unbind` or `{ bind_to: "<kdc_id>" }`; and
+         * `roles.<alias> = { bind_to: "<grp_id>" }` re-points a LIVE role.
+         * Required for every finding — anything unresolved refuses the upgrade.
          */
-        knowledge_resolutions?: KnowledgeUpgradeResolutions;
+        resolutions?: UpgradeResolutions;
     }): Promise<{
         id: string;
         name: string;
@@ -614,24 +483,10 @@ export declare class LoticsClient {
         /**
          * Bundled package-managed knowledge docs the version bump adds/changes/
          * removes/drifts — the app-install analogue of a standalone knowledge
-         * upgrade's `entries`. Consent-requiring docs resolve via `knowledge_resolutions`.
+         * upgrade's `entries`. Consent-requiring docs resolve via `knowledge.<alias>` resolutions.
          */
         knowledge: KnowledgeUpgradeEntry[];
     }>;
-    /**
-     * Re-bind a package role to a different workspace group (the current group
-     * still exists). Re-materializes at the pinned version; refuses over
-     * modified-core findings. Admin-only.
-     */
-    rebindPackageRole(app_id: string, body: {
-        role_alias: string;
-        group_id: string;
-    }): Promise<{
-        app_id: string;
-        role_alias: string;
-        group_id: string;
-        previous_group_id: string | null;
-    }>;
     /**
      * Workspace-wide dangling-reference sweep — active app/workflow artifacts
      * whose prefixed schema ids no longer resolve. Backs
@@ -655,6 +510,8 @@ export declare class LoticsClient {
         app_id: string;
         package_id: string;
         package_name: string;
+        /** The author's origin copy (installation #1) — doctor frames modified core as staged release work, not drift. */
+        is_origin: boolean;
         installed_version: number;
         latest_version: number;
         update_available: boolean;
@@ -683,18 +540,90 @@ export declare class LoticsClient {
         missing_expected_docs: string[];
     }>;
     /**
-     * Reset a package installation in a DEV workspace — drop the package-owned
-     * scaffolded tables and re-scaffold clean. Hard-gated server-side to dev
-     * workspaces (a non-dev workspace is refused). Returns the resulting app.
-     * Admin-only.
+     * Preview a release — the dry run behind `lotics 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, and
+     * any extract findings (an `error` blocks the apply). No writes. Admin,
+     * owning-org only.
      */
-    resetPackage(app_id: string): Promise<{
-        id: string;
-        name: string;
-        workspace_id: string;
-        package_id: string | null;
-        package_version: number | null;
-        current_version_id: string | null;
+    previewPackageRelease(app_id: string): Promise<{
+        package_id: string;
+        version: number;
+        added_aliases: string[];
+        changed_artifacts: string[];
+        findings: ExtractFinding[];
+    }>;
+    /**
+     * Release — snapshot the origin app into the next registry version. The server
+     * binding-aware-extracts it, repackages its deployed source + dist as the
+     * bundle, publishes the next `release`-channel version with the changelog, and
+     * re-pins the origin. Error findings from extract surface as a 409. Admin,
+     * owning-org only. Backs `lotics app release --yes`.
+     */
+    releasePackage(app_id: string, body: {
+        changelog: string;
+    }): Promise<{
+        package_id: string;
+        version: number;
+        added_aliases: string[];
+        changed_artifacts: string[];
+    }>;
+    /**
+     * Dry-run preview of a first-release — the `GET` behind `lotics 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
+     * auto-minted RENAMABLE aliases (the exact `--rename` keys), and the extract
+     * findings (an `error` blocks the apply). No writes. Admin-only.
+     */
+    previewPublishAppPackage(app_id: string, opts?: {
+        renames?: Array<{
+            from: string;
+            to: string;
+        }>;
+        /** alias → doc_id for the app's package-managed knowledge (from its manifest). */
+        knowledge?: Array<{
+            alias: string;
+            doc_id: string;
+        }>;
+    }): Promise<{
+        app_id: string;
+        package_name: string;
+        renamable_aliases: {
+            entities: string[];
+            fields: string[];
+            options: string[];
+            roles: string[];
+            templates: string[];
+            workflows: string[];
+        };
+        findings: ExtractFinding[];
+    }>;
+    /**
+     * 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
+     * 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>`.
+     */
+    publishAppAsPackage(app_id: string, body: {
+        renames?: Array<{
+            from: string;
+            to: string;
+        }>;
+        changelog?: string | null;
+        /** alias → doc_id for the app's package-managed knowledge (from its manifest). */
+        knowledge?: Array<{
+            alias: string;
+            doc_id: string;
+        }>;
+    }): Promise<{
+        package_id: string;
+        version: number;
+        app_id: string;
     }>;
     /**
      * Resolve the display name + fields (incl. select options) of the given tables