@lotics/cli 0.76.0 → 0.83.0

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+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
@@ -43,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;
@@ -73,28 +66,33 @@ 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 (`extractAppPackage`). */
+/** One finding from a package publish/release extract. */
 export interface ExtractFinding {
     severity: "error" | "warning" | "info";
     area: string;
     message: string;
 }
+/** A package's kind — a full app blueprint, or a standalone content package. */
+export type PackageKind = "app" | "content";
+/** One workspace's installation of a package's content (the standalone anchor). */
+export interface ContentInstallation {
+    id: string;
+    workspace_id: string;
+    package_id: string;
+    package_version: number;
+    /** Set when the content arrived bundled with an app install; null for a standalone content package. */
+    app_id: string | null;
+    /** The namespaced content binding: `knowledge` (alias → `kdc_` id) + `templates` (alias → `tmpl_` id). */
+    binding: PackageContentBinding;
+    installed_by: string | null;
+    created_at: string;
+    updated_at: string;
+}
+/** Advisory knowledge warnings surfaced by install/upgrade (never block). */
+export interface KnowledgeWarnings {
+    /** `knowledge_expects` doc names with no matching workspace doc. */
+    missing_expected_docs: string[];
+}
 export declare const API_BASE_URL: string;
 export declare class LoticsClient {
     private apiKey;
@@ -121,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;
@@ -222,24 +213,94 @@ export declare class LoticsClient {
         current_version_id: string | null;
     }>;
     /**
-     * Install an app package version into the current workspace — scaffolds the
-     * data model, deploys the package bundle, materializes its
-     * queries/workflows/agents, and pins the installation. Returns the resulting
-     * installation app. `version` omitted installs the latest published version.
+     * Install a package version into the current workspace — ONE endpoint,
+     * kind-branched into a discriminated response (`kind`). An `app` package
+     * scaffolds the data model / deploys / materializes and returns the installation
+     * app (+ advisory knowledge warnings); a `content` package installs only its
+     * doc corpus and returns the installation row. `bind_to` (content only)
+     * resolves a name collision by adopting an existing same-named doc as
+     * package-managed. `version` omitted installs the latest published version.
      */
-    installAppPackage(package_id: string, body: {
+    installPackage(package_id: string, body: {
         version?: number;
+        /** Content-kind only: consent to adopt a same-named workspace doc on a knowledge collision. */
+        bind_to?: Record<string, string>;
+        /** App-kind only: per-knob config overrides applied over the contract defaults at install. */
         config?: Record<string, string | number | boolean>;
     }): Promise<{
-        id: string;
-        name: string;
-        workspace_id: string;
-        package_id: string | null;
-        package_version: number | null;
-        current_version_id: string | null;
+        kind: "app";
+        app: {
+            id: string;
+            name: string;
+            workspace_id: string;
+            package_id: string | null;
+            package_version: number | null;
+            current_version_id: string | null;
+        };
+        knowledge_warnings: KnowledgeWarnings;
+    } | {
+        kind: "content";
+        installation: ContentInstallation;
+        warnings: KnowledgeWarnings;
+    }>;
+    /**
+     * 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`.
+     */
+    uninstallContentPackage(installation_id: string, opts?: {
+        keep_content?: boolean;
+    }): Promise<{
+        installation_id: string;
+        archived_doc_ids: string[];
+        archived_template_ids: string[];
+        deleted: true;
     }>;
     /**
-     * Uninstall a package installation (backs `lotics package uninstall`). Does
+     * Preview upgrading a standalone content installation — the knowledge namespace's
+     * per-alias `entries` (added/changed/removed/drifted + a `modified` flag) plus the
+     * consent-requiring `templates` (a template the target changed whose live content
+     * was locally edited; a clean one auto-updates and is absent). No writes.
+     * Admin-only.
+     */
+    previewContentInstallationUpgrade(installation_id: string, opts?: {
+        version?: number;
+    }): Promise<{
+        installation_id: string;
+        package_id: string;
+        from_version: number;
+        to_version: number;
+        changelog: string | null;
+        update_available: boolean;
+        entries: KnowledgeUpgradeEntry[];
+        templates: ModifiedArtifact[];
+    }>;
+    /**
+     * Apply a standalone content upgrade — propagate the target version's content per
+     * the resolutions (`knowledge`: a modified change/removal or drift needs consent;
+     * `templates`: a locally-edited changed template takes revert|keep), then advance
+     * the pin + binding. Returns the updated installation row. Admin-only.
+     */
+    applyContentInstallationUpgrade(installation_id: string, body: {
+        version?: number;
+        resolutions?: UpgradeResolutions;
+    }): Promise<ContentInstallation>;
+    /**
+     * List a workspace's package-managed knowledge installations, each folded with
+     * registry status (name, kind, official badge, latest version, update-available).
+     * Member-accessible (workspace-scoped); backs the settings "Managed by" badge.
+     */
+    listContentInstallations(workspace_id: string): Promise<Array<ContentInstallation & {
+        package_registry: {
+            name: string;
+            kind: PackageKind;
+            is_official: boolean;
+            latest_version: number;
+            update_available: boolean;
+        } | null;
+    }>>;
+    /**
+     * 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
@@ -263,12 +324,13 @@ 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.
      */
-    retireAppPackage(package_id: string, body: {
+    retirePackage(package_id: string, body: {
         undo: boolean;
     }): Promise<{
         id: string;
@@ -282,57 +344,18 @@ export declare class LoticsClient {
      * app becomes a normal bespoke app and can no longer be upgraded. Returns the
      * resulting app.
      */
-    ejectAppPackage(app_id: string): Promise<{
+    ejectPackage(app_id: string): Promise<{
         id: string;
         name: string;
         workspace_id: string;
         current_version_id: string | null;
     }>;
-    /**
-     * Extract a DRAFT app package from an existing bespoke app — the promotion
-     * read (docs/app_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.
-     */
-    extractAppPackage(app_id: string): Promise<{
-        contract: unknown;
-        binding: PackageBinding;
-        report: ExtractFinding[];
-        template_files: Array<{
-            bytes_ref: string;
-            file_id: string;
-            filename: 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.
-     */
-    adoptAppPackage(app_id: string, body: {
-        package_id: string;
-        version?: number;
-        binding: PackageBinding;
-    }): 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).
      */
     /**
@@ -340,13 +363,13 @@ export declare class LoticsClient {
      * adopts targeting it; pinned installations keep running. Owner-org
      * admin-only. Backs `lotics package yank`.
      */
-    yankAppPackageVersion(package_id: string, version: number, yanked: boolean): Promise<{
+    yankPackageVersion(package_id: string, version: number, yanked: boolean): Promise<{
         package_id: string;
         version: number;
         yanked_at: string | null;
         latest_version: number;
     }>;
-    fleetUpgradeAppPackage(package_id: string, body: {
+    fleetUpgradePackage(package_id: string, body: {
         version?: number;
     }): Promise<{
         package_id: string;
@@ -367,31 +390,14 @@ export declare class LoticsClient {
         }>;
     }>;
     /**
-     * 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.
-     */
-    createAppPackage(body: {
-        name: string;
-        description?: string | null;
-    }): Promise<{
-        id: string;
-        name: string;
-        description: string | null;
-        latest_version: number;
-        is_official: boolean;
-        created_at: string;
-        updated_at: string;
-    }>;
-    /**
-     * Fetch a registry app package's metadata (incl. `latest_version` and the
-     * Lotics-backed `is_official` trust badge). Admin-only; cross-tenant by id.
+     * 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.
      */
-    getAppPackage(package_id: string): Promise<{
+    getPackage(package_id: string): Promise<{
         id: string;
         name: string;
         description: string | null;
+        kind: PackageKind;
         latest_version: number;
         is_official: boolean;
         retired_at: string | null;
@@ -401,7 +407,7 @@ export declare class LoticsClient {
         updated_at: string;
     }>;
     /** Version history newest-first (no contract payloads) — backs `lotics package show`. Admin-only. */
-    listAppPackageVersions(package_id: string): Promise<{
+    listPackageVersions(package_id: string): Promise<{
         versions: Array<{
             version: number;
             changelog: string | null;
@@ -410,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.
-     */
-    publishAppPackageVersion(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
@@ -438,17 +423,18 @@ export declare class LoticsClient {
      * package artifacts, and bumps the pin. `version` omitted upgrades to the
      * latest. Returns the resulting app. Admin-only.
      */
-    upgradeAppPackage(app_id: string, body: {
+    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.
+         * 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.
          */
-        resolutions?: Record<string, "recreate" | "revert" | "keep" | {
-            bind_to: string;
-        }>;
+        resolutions?: UpgradeResolutions;
     }): Promise<{
         id: string;
         name: string;
@@ -462,7 +448,7 @@ export declare class LoticsClient {
      * breaking contract changes, the binding drift report, and the modified-core
      * report — with no writes. Admin-only.
      */
-    previewAppPackageUpgrade(app_id: string, opts?: {
+    previewPackageUpgrade(app_id: string, opts?: {
         version?: number;
     }): Promise<{
         app_id: string;
@@ -480,6 +466,9 @@ export declare class LoticsClient {
                 from: string;
                 to: string;
             }>;
+            changed: {
+                templates: string[];
+            };
         };
         drift: Array<{
             namespace: string;
@@ -489,21 +478,14 @@ export declare class LoticsClient {
         modified: Array<{
             kind: string;
             alias: string;
+            baseline_unknown?: boolean;
         }>;
-    }>;
-    /**
-     * 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.
-     */
-    rebindAppPackageRole(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;
+        /**
+         * 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.<alias>` resolutions.
+         */
+        knowledge: KnowledgeUpgradeEntry[];
     }>;
     /**
      * Workspace-wide dangling-reference sweep — active app/workflow artifacts
@@ -524,10 +506,12 @@ export declare class LoticsClient {
      * binding drift, and locally modified core artifacts. Read-only; backs
      * `lotics package doctor`. Admin-only.
      */
-    getAppPackageHealth(app_id: string): Promise<{
+    getPackageHealth(app_id: string): Promise<{
         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;
@@ -540,20 +524,106 @@ export declare class LoticsClient {
             kind: string;
             alias: string;
         }>;
+        /** Package-managed knowledge docs whose bound id no longer resolves (recreate/unbind at upgrade). */
+        knowledge_drift: Array<{
+            alias: string;
+            name: string;
+            doc_id: string | null;
+        }>;
+        /** Package-managed knowledge docs the workspace edited since install (apply/keep at upgrade). */
+        knowledge_modified: Array<{
+            alias: string;
+            name: string;
+            doc_id: string | null;
+        }>;
+        /** `knowledge_expects` names the package's agents route to but it does not own (advisory). */
+        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.
      */
-    resetAppPackage(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