@lotics/cli 0.181.1 → 0.183.0

package/dist/src/client.d.ts

@@ -114,13 +114,75 @@ export interface FileUploadResult {
         error: string;
     }>;
 }
-/** One finding from a package publish/release extract. */
+/** One finding from the extract behind a starter publish. */
 export interface ExtractFinding {
     severity: "error" | "warning" | "info";
     area: string;
     message: string;
 }
-/** Advisory knowledge warnings surfaced by install/upgrade (never block). */
+export interface StarterPublishRequest {
+    /** The origin apps that ship, in alias-minting order. */
+    app_ids: string[];
+    /** Live knowledge doc ids to bundle. Omitted keeps the previous version's set; [] drops them all. */
+    knowledge_doc_ids?: string[];
+    /** First publish only: alias fixes before v1 freezes them. */
+    renames?: Array<{
+        from: string;
+        to: string;
+    }>;
+    /** First publish only: the listing name; defaults to the workspace's. */
+    name?: string;
+    /** First publish only: the listing description; defaults to the first app's. */
+    description?: string;
+    /** First publish only: the listing icon; defaults to the first app's. */
+    icon?: string;
+    /** First publish only: the listing accent colour; defaults to the first app's. */
+    color?: string;
+}
+export interface StarterPublishPreview {
+    /** The starter this would publish into, or null when it would mint one. */
+    starter_id: string | null;
+    starter_name: string;
+    version: number;
+    apps: Array<{
+        alias: string;
+        app_id: string;
+        name: string;
+    }>;
+    /** Empty after v1 — the aliases froze there. */
+    renamable_aliases: {
+        entities: string[];
+        fields: string[];
+        options: string[];
+        roles: string[];
+        templates: string[];
+    };
+    added_aliases: string[];
+    changed_artifacts: string[];
+    knowledge: {
+        added: string[];
+        removed: string[];
+        changed: string[];
+    };
+    findings: ExtractFinding[];
+}
+/** A publish is a job; this is the row the requester polls. */
+export interface StarterPublish {
+    id: string;
+    status: "pending" | "building" | "completed" | "failed";
+    /** Null until a first publish completes. */
+    starter_id: string | null;
+    version_id: string | null;
+    version: number | null;
+    app_ids: string[];
+    building_app_alias: string | null;
+    apps_built: number;
+    error: string | null;
+    created_at: string;
+    started_at: string | null;
+    finished_at: string | null;
+}
+/** Advisory knowledge warnings surfaced by a copy (never block). */
 export interface KnowledgeWarnings {
     /** `knowledge_expects` doc names with no matching workspace doc. */
     missing_expected_docs: string[];
@@ -344,13 +406,12 @@ export declare class LoticsClient {
         current_version_id: string | null;
     }>;
     /**
-     * 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.
+     * Take a starter off the shelf, or `undo` to put it back (backs `opctl
+     * starter unpublish`). It hides from non-owning orgs and can no longer be
+     * copied; copies already made are unaffected — they never linked back.
+     * Owner-org admin-only.
      */
-    retirePackage(package_id: string, body: {
+    unpublishStarter(starter_id: string, body: {
         undo: boolean;
     }): Promise<{
         id: string;
@@ -364,7 +425,7 @@ export declare class LoticsClient {
      * A version is an immutable snapshot; the listing is not. Omit a field to
      * leave it, pass `description: null` to clear it. Owner-org admin-only.
      */
-    editPackageListing(package_id: string, body: {
+    editStarterListing(starter_id: string, body: {
         name?: string;
         description?: string | null;
         icon?: string | null;
@@ -375,11 +436,8 @@ export declare class LoticsClient {
         id: string;
         name: string;
         description: string | null;
-        icon?: string | null;
-        /** Optional for the same reason as `getPackage`'s: an older server omits it. */
-        theme?: {
-            color?: string | null;
-        } | null;
+        icon: string | null;
+        theme: Record<string, unknown> | null;
     }>;
     /**
      * The starters this organization can copy — Lotics-reviewed ones plus its own,
@@ -392,51 +450,38 @@ export declare class LoticsClient {
         description: string | null;
         latest_version: number;
         is_official: boolean;
-        owned_by_caller?: boolean;
+        owned_by_caller: boolean;
     }>>;
     /**
      * Copy a starter into the current workspace.
      *
      * Server-side this scaffolds the schema, creates the templates, docs and
-     * sample records, creates a BESPOKE app and materializes onto it — then stops.
-     * It deploys nothing: a starter ships source only, and the source has to be
-     * built where codegen can bake THIS workspace's field ids. `bundle_url` is a
-     * presigned GET of that source, and finishing the job is the caller's half.
+     * sample records, creates every app the starter carries and deploys each
+     * from its prebuilt dist — no build anywhere. `apps` reports each deploy;
+     * one that failed carries its `error` and the copy is complete around it.
      * Admin-only.
      */
     instantiateStarter(starter_id: string, body: {
         version?: number;
         no_sample_data?: boolean;
         adopt?: boolean;
-        /** Ask the server to build and deploy the copy, so this machine needs no Node. */
-        build_on_server?: boolean;
     }): Promise<{
-        app_id: string | null;
+        /** Each app's deploy, in contract order. `error` set and `deployed` null when one did not land. */
+        apps: Array<{
+            alias: string;
+            app_id: string;
+            name: string;
+            deployed: {
+                version_id: string;
+                version_number: number;
+            } | null;
+            error: string | null;
+        }>;
         starter_id: string;
         version: number;
-        bundle_url: string | null;
-        /**
-         * The version the SERVER deployed, when it did.
-         *
-         * Optional in this type on purpose: a server that predates the field omits
-         * it entirely, and it is absent rather than null. Callers must treat "not
-         * there" and "null" alike and build locally — assuming the request was
-         * honoured would report success over an app nobody built.
-         */
-        deployed?: {
-            version_id: string;
-            version_number: number;
-        } | null;
-        /**
-         * Why the server built nothing, when it was asked to and `deployed` is null.
-         * Absent from an older server's response for the same reason as `deployed`.
-         */
-        build_error?: string | null;
         binding: Record<string, Record<string, string>>;
         sample_record_ids: Record<string, string[]>;
-        knowledge_warnings: {
-            missing_expected_docs: string[];
-        };
+        knowledge_warnings: KnowledgeWarnings;
     }>;
     /**
      * Which starter this app is the origin of. 404 when it has published none.
@@ -479,34 +524,26 @@ export declare class LoticsClient {
      * Fetch a registry starter's metadata (`latest_version` and the Lotics-backed
      * `is_official` trust badge). Admin-only; cross-tenant by id.
      */
-    getPackage(package_id: string): Promise<{
+    getStarter(starter_id: string): Promise<{
         id: string;
         name: string;
         description: string | null;
         latest_version: number;
         is_official: boolean;
         retired_at: string | null;
-        /** Absent from a pre-deploy server — treat undefined as not-owned (the badge under-claims, never over-claims). */
-        owned_by_caller?: boolean;
-        /**
-         * The shelf tile, which every copy's app inherits.
-         *
-         * Optional for the same reason `owned_by_caller` is: a server that predates
-         * the field answers without it, and a CLI newer than the deployment it is
-         * talking to must read that as "not stated" rather than "not set".
-         */
-        icon?: string | null;
-        theme?: Record<string, unknown> | null;
+        /** Whether the CALLING org owns it — the copy-time trust badge, without exposing the owner's org id. */
+        owned_by_caller: boolean;
+        /** The shelf tile. Null = unset; a copy's app tiles come from the contract. */
+        icon: string | null;
+        theme: Record<string, unknown> | null;
         created_at: string;
         updated_at: string;
     }>;
-    /** Version history newest-first (no contract payloads) — backs `opctl package show`. Admin-only. */
-    listPackageVersions(package_id: string): Promise<{
+    /** Version history newest-first (no contract payloads) — backs `opctl starter show`. Admin-only. */
+    listStarterVersions(starter_id: string): Promise<{
         versions: Array<{
             version: number;
             changelog: string | null;
-            channel: "release" | "dev";
-            yanked_at: string | null;
             created_at: string;
         }>;
     }>;
@@ -525,120 +562,28 @@ export declare class LoticsClient {
         };
     }>>;
     /**
-     * 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
-     * apply). An optional `knowledge` declaration (from the pulled app manifest)
-     * re-declares the bundle set — added/dropped/changed docs surface in the delta;
-     * omitted, the current corpus is reconstructed from the pin. No writes. Admin,
-     * owning-org only.
-     */
-    previewPackageRelease(app_id: string, opts?: {
-        /** alias → doc_id re-declaring the bundled-knowledge set (from the manifest). */
-        knowledge?: Array<{
-            alias: string;
-            doc_id: string;
-        }>;
-    }): Promise<{
-        package_id: string;
-        version: number;
-        added_aliases: string[];
-        changed_artifacts: string[];
-        /** Absent from a pre-declaration server (deploy skew) — treat as empty delta. */
-        knowledge?: {
-            added: string[];
-            removed: string[];
-            changed: 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. An optional `knowledge` declaration re-declares the
-     * 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 `opctl app release --yes`.
-     */
-    releasePackage(app_id: string, body: {
-        changelog: string;
-        /** alias → doc_id re-declaring the bundled-knowledge set (from the manifest). */
-        knowledge?: Array<{
-            alias: string;
-            doc_id: string;
-        }>;
-    }): Promise<{
-        package_id: string;
-        version: number;
-        added_aliases: string[];
-        changed_artifacts: string[];
-        /** Absent from a pre-declaration server (deploy skew) — treat as empty delta. */
-        knowledge?: {
-            added: string[];
-            removed: string[];
-            changed: string[];
-        };
-    }>;
+     * Preview publishing a set of this workspace's apps as one starter version —
+     * the GET behind `opctl starter publish` (no `--yes`). The server runs the
+     * same extraction the publish runs and reports which starter it would
+     * release into (null: it would mint one), the next version, the aliases a
+     * first publish can still rename, the diff against the current version, the
+     * knowledge delta, and the findings (an `error` blocks the publish). No
+     * writes. Admin-only.
+     */
+    previewStarterPublish(opts: StarterPublishRequest): Promise<StarterPublishPreview>;
     /**
-     * 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
-     * auto-minted RENAMABLE aliases (the exact `--rename` keys), and the extract
-     * findings (an `error` blocks the apply). No writes. Admin-only.
+     * Publish this workspace's apps as a starter version — a JOB, because every
+     * app is built once against sentinel field keys and eleven builds outlast a
+     * request. Everything a request can refuse is refused here with nothing
+     * written: a blocking finding or another publish still running for this
+     * org (409), a missing deploy or a bad declaration (400). The response is
+     * the job to poll with `getStarterPublish`. 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 `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
-     * `opctl app publish <app_id>`.
-     */
-    publishAppAsPackage(app_id: string, body: {
-        renames?: Array<{
-            from: string;
-            to: string;
-        }>;
+    requestStarterPublish(body: StarterPublishRequest & {
         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;
-    }>;
+    }): Promise<StarterPublish>;
+    /** The state of a publish: which app is building, and the version once every dist is in. */
+    getStarterPublish(publish_id: string): Promise<StarterPublish>;
     /**
      * Resolve the display name + fields (incl. select options) of the given tables
      * — the schema `lotics app codegen` turns into the runtime `.lotics/app_fields.ts`

package/dist/src/client.js

@@ -324,14 +324,13 @@ export class LoticsClient {
         return this.request("POST", "/v1/apps", body);
     }
     /**
-     * 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.
+     * Take a starter off the shelf, or `undo` to put it back (backs `opctl
+     * starter unpublish`). It hides from non-owning orgs and can no longer be
+     * copied; copies already made are unaffected — they never linked back.
+     * Owner-org admin-only.
      */
-    async retirePackage(package_id, body) {
-        return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/retire`, body);
+    async unpublishStarter(starter_id, body) {
+        return this.request("POST", `/v1/starters/${encodeURIComponent(starter_id)}/unpublish`, body);
     }
     /**
      * Edit a starter's registry listing — the name and description a stranger
@@ -340,13 +339,12 @@ export class LoticsClient {
      * A version is an immutable snapshot; the listing is not. Omit a field to
      * leave it, pass `description: null` to clear it. Owner-org admin-only.
      */
-    async editPackageListing(package_id, body) {
-        return this.request("POST", `/v1/packages/${encodeURIComponent(package_id)}/listing`, body);
+    async editStarterListing(starter_id, body) {
+        return this.request("POST", `/v1/starters/${encodeURIComponent(starter_id)}/listing`, body);
     }
-    // --- Packages (registry reads + installations) ---
-    // Authoring is server-side: apps via `POST /v1/apps/{id}/package-publish|release`,
-    // content packages via the `publish_content`/`release_content` tools. There is no
-    // client-side create-package / upload-bundle path.
+    // --- Starters (registry reads + copies) ---
+    // Authoring is server-side, through the publish job (`requestStarterPublish`).
+    // There is no client-side create-starter / upload-bundle path.
     /**
      * The starters this organization can copy — Lotics-reviewed ones plus its own,
      * never a catalogue of everything published. The server returns exactly what
@@ -359,10 +357,9 @@ export class LoticsClient {
      * Copy a starter into the current workspace.
      *
      * Server-side this scaffolds the schema, creates the templates, docs and
-     * sample records, creates a BESPOKE app and materializes onto it — then stops.
-     * It deploys nothing: a starter ships source only, and the source has to be
-     * built where codegen can bake THIS workspace's field ids. `bundle_url` is a
-     * presigned GET of that source, and finishing the job is the caller's half.
+     * sample records, creates every app the starter carries and deploys each
+     * from its prebuilt dist — no build anywhere. `apps` reports each deploy;
+     * one that failed carries its `error` and the copy is complete around it.
      * Admin-only.
      */
     async instantiateStarter(starter_id, body) {
@@ -400,12 +397,12 @@ export class LoticsClient {
      * Fetch a registry starter's metadata (`latest_version` and the Lotics-backed
      * `is_official` trust badge). Admin-only; cross-tenant by id.
      */
-    async getPackage(package_id) {
-        return this.request("GET", `/v1/packages/${encodeURIComponent(package_id)}`);
+    async getStarter(starter_id) {
+        return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}`);
     }
-    /** 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`);
+    /** Version history newest-first (no contract payloads) — backs `opctl starter show`. Admin-only. */
+    async listStarterVersions(starter_id) {
+        return this.request("GET", `/v1/starters/${encodeURIComponent(starter_id)}/versions`);
     }
     /**
      * Workspace-wide dangling-reference sweep — active app/workflow artifacts
@@ -415,68 +412,51 @@ export class LoticsClient {
     async getWorkspaceDanglingReferences() {
         return this.request("GET", "/v1/workspaces/dangling-references");
     }
+    // --- Starter publishing (the authoring verbs; copying is `instantiateStarter`) ---
     /**
-     * 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
-     * apply). An optional `knowledge` declaration (from the pulled app manifest)
-     * re-declares the bundle set — added/dropped/changed docs surface in the delta;
-     * omitted, the current corpus is reconstructed from the pin. No writes. Admin,
-     * owning-org only.
+     * Preview publishing a set of this workspace's apps as one starter version —
+     * the GET behind `opctl starter publish` (no `--yes`). The server runs the
+     * same extraction the publish runs and reports which starter it would
+     * release into (null: it would mint one), the next version, the aliases a
+     * first publish can still rename, the diff against the current version, the
+     * knowledge delta, and the findings (an `error` blocks the publish). No
+     * writes. Admin-only.
      */
-    async previewPackageRelease(app_id, opts = {}) {
+    async previewStarterPublish(opts) {
         const params = new URLSearchParams();
-        if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
-            params.set("knowledge", JSON.stringify(opts.knowledge));
-        }
-        const query = params.toString();
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-release${query ? `?${query}` : ""}`);
-    }
-    /**
-     * 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. An optional `knowledge` declaration re-declares the
-     * 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 `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 `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
-     * auto-minted RENAMABLE aliases (the exact `--rename` keys), and the extract
-     * findings (an `error` blocks the apply). No writes. Admin-only.
-     */
-    async previewPublishAppPackage(app_id, opts = {}) {
-        const params = new URLSearchParams();
-        if (opts.knowledge !== undefined && opts.knowledge.length > 0) {
-            params.set("knowledge", JSON.stringify(opts.knowledge));
-        }
-        if (opts.renames !== undefined && opts.renames.length > 0) {
+        params.set("app_ids", opts.app_ids.join(","));
+        if (opts.knowledge_doc_ids !== undefined)
+            params.set("knowledge_doc_ids", opts.knowledge_doc_ids.join(","));
+        if (opts.renames !== undefined && opts.renames.length > 0)
             params.set("renames", JSON.stringify(opts.renames));
-        }
-        const query = params.toString();
-        return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-publish${query ? `?${query}` : ""}`);
+        if (opts.name !== undefined)
+            params.set("name", opts.name);
+        if (opts.description !== undefined)
+            params.set("description", opts.description);
+        if (opts.icon !== undefined)
+            params.set("icon", opts.icon);
+        if (opts.color !== undefined)
+            params.set("color", opts.color);
+        return this.request("GET", `/v1/starters/publish-preview?${params.toString()}`);
+    }
+    /**
+     * Publish this workspace's apps as a starter version — a JOB, because every
+     * app is built once against sentinel field keys and eleven builds outlast a
+     * request. Everything a request can refuse is refused here with nothing
+     * written: a blocking finding or another publish still running for this
+     * org (409), a missing deploy or a bad declaration (400). The response is
+     * the job to poll with `getStarterPublish`. Admin-only.
+     */
+    async requestStarterPublish(body) {
+        const { color, ...rest } = body;
+        return this.request("POST", "/v1/starters/publishes", {
+            ...rest,
+            ...(color !== undefined ? { theme: { color } } : {}),
+        });
     }
-    /**
-     * First-release apply — mint a package from a BESPOKE app and publish v1 in one
-     * 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
-     * `opctl app publish <app_id>`.
-     */
-    async publishAppAsPackage(app_id, body) {
-        return this.request("POST", `/v1/apps/${encodeURIComponent(app_id)}/package-publish`, body);
+    /** The state of a publish: which app is building, and the version once every dist is in. */
+    async getStarterPublish(publish_id) {
+        return this.request("GET", `/v1/starters/publishes/${encodeURIComponent(publish_id)}`);
     }
     /**
      * Resolve the display name + fields (incl. select options) of the given tables