@lotics/cli 0.157.0 → 0.163.0

package/dist/src/client.d.ts

@@ -1,4 +1,3 @@
-import type { ContractConfigEntry, KnowledgeUpgradeEntry, ModifiedArtifact, PackageContentBinding, UpgradeResolutions } from "./package_content_types";
 /** One sort key forwarded to the app query RPC (wire shape of a `TableRecordSort` entry). */
 export interface AppQuerySortKey {
     field_key: string;
@@ -121,22 +120,6 @@ export interface ExtractFinding {
     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. */
@@ -211,8 +194,21 @@ export declare class LoticsClient {
         id: string;
         deleted: boolean;
     }>;
-    login(): Promise<{
+    login(body?: {
+        /**
+         * Return the sign-in link instead of mailing it — the browser handoff.
+         *
+         * Grants nothing new: an API key is member-bound, so the link mints a
+         * session for exactly the identity this client already holds. The returned
+         * URL IS a credential though: one-time, short-lived, and not for anywhere it
+         * persists.
+         */
+        return_link?: boolean;
+        /** Relative path to land on after signing in; server-validated as relative. */
+        redirect_path?: string;
+    }): Promise<{
         email: string;
+        url?: string;
     }>;
     listTools(): Promise<{
         tools: string[];
@@ -307,22 +303,6 @@ export declare class LoticsClient {
             query_aliases?: string[];
             workflow_aliases?: string[];
         }> | null;
-        /**
-         * Installation-level customization config values (the `useConfig()`
-         * source). Null/undefined for a bespoke app. The dev harness serves these
-         * through the `context` op for production parity.
-         */
-        config?: Record<string, string | number | boolean> | null;
-        /** Package registry id this app was installed from; null for a bespoke/ejected app. */
-        package_id?: string | null;
-        /** The installed package version (upgrade pin); null for a bespoke/ejected app. */
-        package_version?: number | null;
-        /**
-         * Package install join — per-namespace alias→id maps (entities/fields/
-         * options/templates/roles) plus the `workflows` artifact registry. Null for
-         * a bespoke app. Used to preview what `package uninstall` will archive.
-         */
-        binding?: Record<string, Record<string, string>> | null;
     }>;
     createApp(body: {
         name: string;
@@ -334,117 +314,6 @@ export declare class LoticsClient {
         workspace_id: string;
         current_version_id: string | null;
     }>;
-    /**
-     * 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.
-     */
-    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<{
-        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 `opctl uninstall`.
-     */
-    uninstallContentPackage(installation_id: string, opts?: {
-        keep_content?: boolean;
-    }): Promise<{
-        installation_id: string;
-        archived_doc_ids: string[];
-        archived_template_ids: string[];
-        deleted: true;
-    }>;
-    /**
-     * 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 `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
-     * (provenance) and nothing else references them. Admin-only.
-     */
-    uninstallAppPackage(app_id: string, body: {
-        archive_tables: boolean;
-    }): Promise<{
-        id: string;
-        uninstalled: boolean;
-        archived_table_ids: string[];
-    }>;
-    /**
-     * 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.
-     */
-    updateAppPackageConfig(app_id: string, body: {
-        config: Record<string, string | number | boolean>;
-    }): Promise<{
-        config: Record<string, string | number | boolean>;
-    }>;
     /**
      * Retire (or `undo` un-retire) a registry package (backs `lotics app
      * unpublish` — the endpoint/audit action keep the `retire` name to avoid API
@@ -460,67 +329,88 @@ export declare class LoticsClient {
         retired_at: string | null;
     }>;
     /**
-     * Eject an installation from its package — re-deploy the pinned version's
-     * source as a workspace-owned app version, then sever the package link
-     * (clears `package_id`/`package_version`, stamps `ejected_at`). One-way: the
-     * app becomes a normal bespoke app and can no longer be upgraded. Returns the
-     * resulting app.
+     * The starters this organization can copy — Lotics-reviewed ones plus its own,
+     * never a catalogue of everything published. The server returns exactly what
+     * instantiate would accept, so the list cannot offer a refusal. Admin-only.
      */
-    ejectPackage(app_id: string): Promise<{
+    listStarters(): Promise<Array<{
         id: string;
         name: string;
-        workspace_id: string;
-        current_version_id: string | null;
-    }>;
+        description: string | null;
+        latest_version: number;
+        is_official: boolean;
+        owned_by_caller?: boolean;
+    }>>;
     /**
-     * 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 `opctl upgrade <package_id>` (fleet).
-     * Admin-only; org-scoped (no workspace header needed).
+     * 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.
+     * Admin-only.
      */
+    instantiateStarter(starter_id: string, body: {
+        version?: number;
+        no_sample_data?: boolean;
+        adopt?: boolean;
+    }): Promise<{
+        app_id: string | null;
+        starter_id: string;
+        version: number;
+        bundle_url: string | null;
+        binding: Record<string, Record<string, string>>;
+        sample_record_ids: Record<string, string[]>;
+        knowledge_warnings: {
+            missing_expected_docs: string[];
+        };
+    }>;
     /**
-     * Yank / unyank a published package version — refuses NEW installs/upgrades/
-     * adopts targeting it; pinned installations keep running. Owner-org
-     * admin-only. Backs `opctl package yank`.
+     * Which starter this app is the origin of. 404 when it has published none.
+     *
+     * The app row carries no pin, so this is the only app→starter direction there
+     * is — provenance lives on the published version. Admin-only.
      */
-    yankPackageVersion(package_id: string, version: number, yanked: boolean): Promise<{
-        package_id: string;
-        version: number;
-        yanked_at: string | null;
+    getAppOriginStarter(app_id: string): Promise<{
+        starter_id: string;
         latest_version: number;
     }>;
-    fleetUpgradePackage(package_id: string, body: {
-        version?: number;
+    /**
+     * Capture live records from this workspace as a starter's sample data.
+     *
+     * The alias-keyed shape is produced SERVER-side, because the contract alias
+     * space is minted by extract and exists nowhere a project can read it. Pure
+     * read — the caller writes the returned files into the project and reviews
+     * them, which matters: these rows are copied verbatim into every workspace
+     * that takes the starter. Admin-only.
+     */
+    captureStarterFixtures(app_id: string, opts?: {
+        entities?: string[];
+        limit?: number;
     }): Promise<{
-        package_id: string;
-        target_version: number;
-        installations: Array<{
-            app_id: string;
-            app_name: string;
-            workspace_id: string;
-            workspace_name: string;
-            from_version: number | null;
-            outcome: "upgraded" | "up_to_date" | "skipped" | "failed";
-            blockers?: {
-                breaking: number;
-                drift: number;
-                modified: number;
-                knowledge: number;
+        app_id: string;
+        available_entity_aliases: string[];
+        captured: Array<{
+            entity_alias: string;
+            content_ref: string;
+            file: {
+                rows: Array<{
+                    ref: string;
+                    fields: Record<string, unknown>;
+                }>;
             };
-            message?: string;
+            notes: 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.
+     * 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<{
         id: string;
         name: string;
         description: string | null;
-        kind: PackageKind;
         latest_version: number;
         is_official: boolean;
         retired_at: string | null;
@@ -539,77 +429,6 @@ export declare class LoticsClient {
             created_at: string;
         }>;
     }>;
-    /**
-     * Upgrade a package installation to a newer published version — extends the
-     * binding additively, re-materializes the target version's
-     * queries/workflows/agents (preserving workspace overlay), prunes dropped
-     * package artifacts, and bumps the pin. `version` omitted upgrades to the
-     * latest. Returns the resulting app. Admin-only.
-     */
-    upgradePackage(app_id: string, body: {
-        version?: number;
-        /**
-         * 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?: UpgradeResolutions;
-    }): Promise<{
-        id: string;
-        name: string;
-        workspace_id: string;
-        package_id: string | null;
-        package_version: number | null;
-        current_version_id: string | null;
-    }>;
-    /**
-     * Preview a package upgrade — the additive plan, informational removals,
-     * breaking contract changes, the binding drift report, and the modified-core
-     * report — with no writes. Admin-only.
-     */
-    previewPackageUpgrade(app_id: string, opts?: {
-        version?: number;
-    }): Promise<{
-        app_id: string;
-        package_id: string;
-        from_version: number;
-        to_version: number;
-        changelog: string | null;
-        diff: {
-            added: Record<string, unknown[]>;
-            removed: Record<string, unknown[]>;
-            breaking: Array<{
-                entity: string;
-                alias: string;
-                kind: "field_type" | "link_target";
-                from: string;
-                to: string;
-            }>;
-            changed: {
-                templates: string[];
-            };
-        };
-        drift: Array<{
-            namespace: string;
-            alias: string;
-            id: string;
-        }>;
-        modified: Array<{
-            kind: string;
-            alias: string;
-            baseline_unknown?: boolean;
-        }>;
-        /**
-         * 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
      * whose prefixed schema ids no longer resolve. Backs
@@ -624,52 +443,6 @@ export declare class LoticsClient {
             name: string;
         };
     }>>;
-    /**
-     * Health check for a package installation — version pin vs. registry latest,
-     * binding drift, and locally modified core artifacts. Read-only; backs
-     * `opctl package doctor`. Admin-only.
-     */
-    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;
-        drift: Array<{
-            namespace: string;
-            alias: string;
-            id: string;
-        }>;
-        modified: Array<{
-            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[];
-        /** Orphan duplicate link fields (unbound links between binding-covered tables). Always empty on an origin. */
-        orphan_duplicate_links: Array<{
-            field_id: string;
-            field_name: string;
-            table_id: string;
-            table_name: string;
-            target_table_id: string;
-        }>;
-    }>;
     /**
      * 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
@@ -686,8 +459,6 @@ 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;
@@ -699,12 +470,6 @@ 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[];
     }>;
     /**
@@ -724,8 +489,6 @@ 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;
@@ -737,12 +500,6 @@ 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 `opctl app publish`
@@ -762,8 +519,6 @@ 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;
@@ -798,8 +553,6 @@ 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;
@@ -883,12 +636,6 @@ export declare class LoticsClient {
             image: string | null;
         }>;
     }>;
-    /** A package installation's alias→id maps (fields/options/roles) — the app's runtime F/OPT resolution. */
-    appBinding(app_id: string): Promise<{
-        fields: Record<string, string>;
-        options: Record<string, string>;
-        roles: Record<string, string>;
-    }>;
     /**
      * Resolve the full option set (key, label, color) of a named query's select
      * columns — the picker companion to `appQuery`. Mirrors