@lotics/cli 0.83.0 → 0.86.0

package/dist/src/cli.js

@@ -29948,18 +29948,32 @@ var LoticsClient = class {
   /**
    * 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,
+   * 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.
    */
-  async previewPackageRelease(app_id) {
-    return this.request("GET", `/v1/apps/${encodeURIComponent(app_id)}/package-release`);
+  async previewPackageRelease(app_id, opts = {}) {
+    const params = new URLSearchParams();
+    if (opts.knowledge !== void 0 && 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. Error findings from extract surface as a 409. Admin,
+   * 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 `lotics app release --yes`.
    */
   async releasePackage(app_id, body) {
@@ -32085,7 +32099,7 @@ function inputDeclToTsType(decl) {
         }
         return null;
       }).filter((v) => v !== null);
-      const inner = literals.length > 0 ? literals.join(" | ") : "string";
+      const inner = literals.length > 0 ? `${literals.join(" | ")} | (string & {})` : "string";
       return decl.multi === true ? `ReadonlyArray<${inner}>` : inner;
     }
     case "date_range":
@@ -32137,7 +32151,7 @@ function outputDeclToTsType(decl) {
       const literals = options.map(
         (o) => o !== null && typeof o === "object" && "value" in o && typeof o.value === "string" ? JSON.stringify(o.value) : null
       ).filter((v) => v !== null);
-      const inner = literals.length > 0 ? literals.join(" | ") : "string";
+      const inner = literals.length > 0 ? `${literals.join(" | ")} | (string & {})` : "string";
       return decl.multi === true ? `ReadonlyArray<${inner}>` : inner;
     }
     case "object": {
@@ -50215,7 +50229,8 @@ async function packageDoctor(client, args) {
   }
   if (health.modified.length === 0) {
     console.error(
-      health.is_origin ? "  Package artifacts: no changes since the last release." : "  Package artifacts: pristine \u2014 no local edits an upgrade would revert."
+      health.is_origin ? `  Package artifacts: no changes since the last release.
+  (schema additions aren't fingerprinted \u2014 preview them with: lotics app release ${app_id})` : "  Package artifacts: pristine \u2014 no local edits an upgrade would revert."
     );
   } else if (health.is_origin) {
     console.error(
@@ -50410,6 +50425,56 @@ function formatTemplateResolveHint(entry) {
   const note = entry.baseline_unknown ? "   (can't verify the local edit \u2014 older package version; revert overwrites, keep retains)" : "   (a local edit \u2014 revert overwrites it with the package's version; keep retains it)";
   return `    --resolve template.${entry.alias}=revert|keep${note}`;
 }
+async function resolveWorkspaceContentInstallation(client, package_id) {
+  const workspaceId = client.getWorkspaceId();
+  if (!workspaceId) {
+    throw new Error(
+      "No workspace selected. Pass --workspace <ws> (or select one) to operate on its content installation."
+    );
+  }
+  const installations = await client.listContentInstallations(workspaceId);
+  const match = installations.find((inst) => inst.package_id === package_id);
+  if (!match) {
+    throw new Error(
+      `Package ${package_id} is not installed in this workspace \u2014 install it first:  lotics install ${package_id}`
+    );
+  }
+  return match;
+}
+async function redirectContentPciForm(client, pci_id, verb) {
+  console.error(
+    `Content installations are addressed by their PACKAGE id now \u2014 ${pci_id} is a server-internal resource id.`
+  );
+  const workspaceId = client.getWorkspaceId();
+  const match = workspaceId ? (await client.listContentInstallations(workspaceId)).find((inst) => inst.id === pci_id) : void 0;
+  if (match) {
+    console.error(`  Run:  lotics ${verb} ${match.package_id}`);
+  } else {
+    console.error("  Find the package id:  lotics package list-content");
+    console.error(`  Then run:  lotics ${verb} <package_id>`);
+  }
+  process.exit(1);
+}
+async function packageUpgradeByPackageId(client, args) {
+  const pkg2 = await client.getPackage(args.package_id);
+  if (pkg2.kind === "content") {
+    const installation = await resolveWorkspaceContentInstallation(client, args.package_id);
+    await packageUpgradeKnowledge(client, {
+      installation_id: installation.id,
+      package_id: pkg2.id,
+      package_name: pkg2.name,
+      version: args.version,
+      resolve: args.resolve,
+      bind_to: parseBindToFlags(args.bindTo),
+      applyAll: args.applyAll
+    });
+    return;
+  }
+  await packageFleetUpgrade(client, {
+    package_id: args.package_id,
+    ...args.version !== void 0 ? { version: args.version } : {}
+  });
+}
 async function packageUpgradeKnowledge(client, args) {
   const preview = await client.previewContentInstallationUpgrade(args.installation_id, {
     ...args.version !== void 0 ? { version: args.version } : {}
@@ -50422,7 +50487,7 @@ async function packageUpgradeKnowledge(client, args) {
       ...args.version !== void 0 ? { version: args.version } : {},
       resolutions: resolutions2
     });
-    console.error(`Upgraded ${args.installation_id} \u2192 v${updated.package_version}.`);
+    console.error(`Upgraded ${args.package_name} (${args.package_id}) \u2192 v${updated.package_version}.`);
   };
   if (preview.entries.length === 0 && preview.templates.length === 0) {
     if (preview.to_version === preview.from_version) {
@@ -50494,8 +50559,8 @@ function warnMissingExpectedDocs(missing) {
 }
 async function packageInstall(client, args) {
   const pkg2 = await client.getPackage(args.package_id);
-  const kindLabel = pkg2.kind === "content" ? "content package" : "package";
-  console.error(`Installing ${pkg2.name} \u2014 ${trustBadge(pkg2)} (${kindLabel})...`);
+  const kindSuffix = pkg2.kind === "content" ? " (content \u2014 docs/templates, no app)" : "";
+  console.error(`Installing ${pkg2.name} \u2014 ${trustBadge(pkg2)}${kindSuffix}...`);
   const result = await client.installPackage(args.package_id, {
     ...args.version !== void 0 ? { version: args.version } : {},
     ...args.bind_to && Object.keys(args.bind_to).length > 0 ? { bind_to: args.bind_to } : {},
@@ -50506,7 +50571,7 @@ async function packageInstall(client, args) {
     const docs = installation.binding.knowledge;
     const templates = installation.binding.templates;
     console.error(
-      `Installed ${pkg2.name} v${installation.package_version} \u2192 content installation ${installation.id} (workspace ${installation.workspace_id}).`
+      `Installed ${pkg2.name} v${installation.package_version} (workspace ${installation.workspace_id}).`
     );
     const docAliases = Object.keys(docs);
     if (docAliases.length > 0) {
@@ -50521,8 +50586,8 @@ async function packageInstall(client, args) {
       );
     }
     warnMissingExpectedDocs(warnings.missing_expected_docs);
-    console.error(`  Upgrade later:  lotics upgrade ${installation.id}`);
-    console.error(`  Uninstall:      lotics uninstall ${installation.id} [--keep-content]`);
+    console.error(`  Upgrade later:  lotics upgrade ${args.package_id}`);
+    console.error(`  Uninstall:      lotics uninstall ${args.package_id} [--keep-content]`);
     return;
   }
   const { app, knowledge_warnings } = result;
@@ -50535,22 +50600,29 @@ async function packageInstall(client, args) {
   console.error(`  Health / uninstall:         lotics package doctor ${app.id}  \xB7  lotics uninstall ${app.id} [--archive-tables]`);
 }
 async function packageUninstall(client, args) {
-  if (args.id.startsWith("pci_")) {
+  if (args.id.startsWith("apg_")) {
     if (args.archive_tables) {
       throw new Error(
-        "--archive-tables applies only to an app installation (<app_id>). A content installation (pci_) has no scaffolded tables \u2014 use --keep-content to retain its docs/templates."
+        "--archive-tables applies only to an app installation (<app_id>). A content package has no scaffolded tables \u2014 use --keep-content to retain its docs/templates."
       );
     }
-    const result2 = await client.uninstallContentPackage(args.id, {
+    const pkg2 = await client.getPackage(args.id);
+    if (pkg2.kind !== "content") {
+      throw new Error(
+        `Package ${args.id} is an app package \u2014 uninstall an app installation by its app id:  lotics uninstall <app_id>.`
+      );
+    }
+    const installation = await resolveWorkspaceContentInstallation(client, args.id);
+    const result2 = await client.uninstallContentPackage(installation.id, {
       keep_content: args.keep_content
     });
     if (args.keep_content) {
       console.error(
-        `Uninstalled content installation ${result2.installation_id} \u2014 its docs and templates were kept as ordinary workspace content.`
+        `Uninstalled ${pkg2.name} (${pkg2.id}) \u2014 its docs and templates were kept as ordinary workspace content.`
       );
     } else {
       console.error(
-        `Uninstalled content installation ${result2.installation_id} \u2014 archived ${result2.archived_doc_ids.length} doc(s) and ${result2.archived_template_ids.length} template(s).`
+        `Uninstalled ${pkg2.name} (${pkg2.id}) \u2014 archived ${result2.archived_doc_ids.length} doc(s) and ${result2.archived_template_ids.length} template(s).`
       );
       for (const docId of result2.archived_doc_ids) console.error(`    ${docId}`);
       for (const templateId of result2.archived_template_ids) console.error(`    ${templateId}`);
@@ -50559,7 +50631,7 @@ async function packageUninstall(client, args) {
   }
   if (args.keep_content) {
     throw new Error(
-      "--keep-content applies only to a standalone content installation (pci_). An app installation (<app_id>) uses --archive-tables to also archive its scaffolded tables."
+      "--keep-content applies only to a content package (apg_). An app installation (<app_id>) uses --archive-tables to also archive its scaffolded tables."
     );
   }
   const app = await client.getApp(args.id);
@@ -50603,7 +50675,7 @@ async function packageListContent(client) {
     const updateAvailable = inst.package_registry?.update_available ?? false;
     const versionLabel = latest !== void 0 && latest !== inst.package_version ? `v${inst.package_version} \u2192 latest v${latest}` : `v${inst.package_version}`;
     console.error(
-      `  ${inst.id}  ${name}  ${versionLabel}` + (updateAvailable ? "  \u2192 update available" : "")
+      `  ${inst.package_id}  ${name}  ${versionLabel}` + (updateAvailable ? "  \u2192 update available" : "")
     );
   }
 }
@@ -50765,18 +50837,18 @@ Re-run with --yes to publish v1:`);
   console.error(`    lotics app release ${appId} -m "<what changed>"`);
   console.error(`  Install it elsewhere:  lotics install ${result.package_id}`);
 }
-function resolveOriginAppId(projectDir, explicit) {
-  if (explicit !== void 0 && explicit !== ".") return explicit;
-  const local = readLocalAppManifest(projectDir);
-  if (local?.app_id) return local.app_id;
-  throw new Error(
-    "No app id. Run this from a pulled app project (lotics app pull <app_id>), or pass an app id explicitly."
-  );
-}
 async function appRelease(client, args) {
   const projectDir = path6.resolve(args.projectDir ?? process.cwd());
-  const appId = resolveOriginAppId(projectDir, args.app_id);
-  const preview = await client.previewPackageRelease(appId);
+  const local = readLocalAppManifest(projectDir);
+  const explicit = args.app_id !== void 0 && args.app_id !== "." ? args.app_id : void 0;
+  const appId = explicit ?? local?.app_id ?? null;
+  if (appId === null) {
+    throw new Error(
+      "No app id. Run this from a pulled app project (lotics app pull <app_id>), or pass an app id explicitly."
+    );
+  }
+  const knowledge = local && local.app_id === appId && local.knowledge.length > 0 ? local.knowledge : void 0;
+  const preview = await client.previewPackageRelease(appId, { knowledge });
   const { lines, hasError } = formatExtractReport(preview.findings);
   console.error(`Release preview \u2014 ${appId} \u2192 ${preview.package_id} v${preview.version}:`);
   if (preview.added_aliases.length > 0) {
@@ -50785,7 +50857,16 @@ async function appRelease(client, args) {
   if (preview.changed_artifacts.length > 0) {
     console.error(`  Changed (${preview.changed_artifacts.length}): ${preview.changed_artifacts.join(", ")}`);
   }
-  if (preview.added_aliases.length === 0 && preview.changed_artifacts.length === 0) {
+  const k = preview.knowledge ?? { added: [], removed: [], changed: [] };
+  if (k.added.length > 0 || k.removed.length > 0 || k.changed.length > 0) {
+    const parts = [
+      k.added.length > 0 ? `+${k.added.join(", ")}` : null,
+      k.removed.length > 0 ? `dropped ${k.removed.join(", ")}` : null,
+      k.changed.length > 0 ? `changed ${k.changed.join(", ")}` : null
+    ].filter((p) => p !== null);
+    console.error(`  Knowledge: ${parts.join("; ")}`);
+  }
+  if (preview.added_aliases.length === 0 && preview.changed_artifacts.length === 0 && k.added.length === 0 && k.removed.length === 0 && k.changed.length === 0) {
     console.error("  No contract changes since the current version (a fresh code/dist snapshot still ships).");
   }
   if (lines.length > 0) {
@@ -50804,7 +50885,7 @@ Re-run with --yes to publish v${preview.version}:`);
     process.exitCode = 1;
     return;
   }
-  const result = await client.releasePackage(appId, { changelog: args.changelog });
+  const result = await client.releasePackage(appId, { changelog: args.changelog, knowledge });
   console.error(`Released ${result.package_id} v${result.version}.`);
   console.error(`  The origin was re-pinned to v${result.version} \u2014 verify:  lotics package doctor ${appId}`);
 }
@@ -67712,18 +67793,19 @@ COMMANDS
                                        Install a package (app: scaffolds/deploys/materializes,
                                        --config sets its knobs; content: installs the doc corpus,
                                        --bind-to consents to adopt a same-named doc on a collision)
-  lotics uninstall <app_id|pci_id> [--archive-tables] [--keep-content]
+  lotics uninstall <app_id|package_id> [--archive-tables] [--keep-content]
                                        Uninstall \u2014 dispatched by id. App (app_id): archives
                                        artifacts (+ --archive-tables also archives scaffolded
-                                       tables). Content (pci_): archives its package-bound docs
-                                       unless --keep-content
-  lotics upgrade <app_id|pci_id|package_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]
+                                       tables). Content package (apg_): archives its package-bound
+                                       docs unless --keep-content
+  lotics upgrade <app_id|package_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]
                                        Preview-then-apply an upgrade, dispatched by id. App
                                        (app_id): refuses while any drift/modified/bundled-knowledge
-                                       finding lacks a --resolve. Content (pci_): --resolve
-                                       <alias>=apply|keep|archive|recreate|unbind. Package (apg_):
-                                       FLEET \u2014 every installation across your org (clean apply,
-                                       findings skip). --apply-all accepts the package's version
+                                       finding lacks a --resolve. Package (apg_): a CONTENT package
+                                       upgrades THIS workspace's install (--resolve
+                                       <alias>=apply|keep|archive|recreate|unbind); an APP package
+                                       FLEET-upgrades every installation across your org (clean
+                                       apply, findings skip). --apply-all accepts the package's version
   lotics package doctor [app_id]       Installation health: version pin vs latest, binding
                                        drift, locally modified core, knowledge drift/edits
                                        (exit 1 on findings)
@@ -67733,7 +67815,8 @@ COMMANDS
                                        (re-deploys the pinned source as a bespoke app)
   lotics package show <package_id>     Registry metadata + version history
   lotics package list-content          List the workspace's content installations
-                                       (standalone content installs) \u2014 source for a pci_ id
+                                       (standalone content installs) \u2014 each row leads with
+                                       the package id for upgrade/uninstall
   lotics package yank <package_id> <version> [--undo]
                                        Refuse new installs/upgrades of a broken published
                                        version (pinned installations keep running)
@@ -68250,8 +68333,8 @@ async function main() {
     console.error("Usage (low-traffic consumer / registry ops \u2014 author verbs live on `lotics app`):");
     console.error("  The high-traffic consumer verbs are top-level:");
     console.error("    lotics install <package_id> [--version N] [--bind-to <alias>=<kdc_id>] [--config key=value ...]   Install a package (app or content)");
-    console.error("    lotics uninstall <app_id|pci_id> [--archive-tables] [--keep-content]   Uninstall \u2014 dispatched by id (app vs content)");
-    console.error("    lotics upgrade <app_id|pci_id|package_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]   Upgrade \u2014 app / content / whole fleet (apg_)");
+    console.error("    lotics uninstall <app_id|package_id> [--archive-tables] [--keep-content]   Uninstall \u2014 dispatched by id (app vs content)");
+    console.error("    lotics upgrade <app_id|package_id> [--version N] [--resolve <key>=... ] [--bind-to ...] [--apply-all]   Upgrade \u2014 app install / content install / whole app fleet (apg_)");
     console.error("  lotics package doctor [app_id]                   Health: version pin vs latest + binding/knowledge drift");
     console.error("  lotics package config <app_id> [--set key=value ...]   Show or edit an installation's config knobs");
     console.error("  lotics package eject <app_id>                    Sever an installation's package link");
@@ -68429,12 +68512,16 @@ Available workspaces:`);
   if (command === "uninstall") {
     const id = subcommand;
     if (!id) {
-      console.error("Usage: lotics uninstall <app_id|pci_id> [--archive-tables] [--keep-content]");
+      console.error("Usage: lotics uninstall <app_id|package_id> [--archive-tables] [--keep-content]");
       console.error(
-        "Dispatched by id: an app installation (app_id; --archive-tables to also archive its scaffolded tables) or a standalone content installation (pci_ id from `lotics install` / lotics package list-content; --keep-content to retain its docs)."
+        "Dispatched by id: an app installation (app_id; --archive-tables to also archive its scaffolded tables) or a content package (apg_ id from `lotics install` / lotics package list-content; --keep-content to retain its docs)."
       );
       process.exit(1);
     }
+    if (id.startsWith("pci_")) {
+      await redirectContentPciForm(client, id, "uninstall");
+      return;
+    }
     await packageUninstall(client, {
       id,
       keep_content: flags.keepContent,
@@ -68446,10 +68533,10 @@ Available workspaces:`);
     const target = subcommand;
     if (!target) {
       console.error(
-        "Usage: lotics upgrade <app_id | pci_id | package_id> [--version N] [--resolve <key>=... ...] [--bind-to ...] [--apply-all]"
+        "Usage: lotics upgrade <app_id | package_id> [--version N] [--resolve <key>=... ...] [--bind-to ...] [--apply-all]"
       );
       console.error(
-        "Dispatched by id: an app installation (app_id), a standalone content installation (pci_ id), or a package id (apg_ \u2014 fleet-upgrades every installation across your org)."
+        "Dispatched by id: an app installation (app_id), or a package id (apg_) \u2014 a CONTENT package upgrades this workspace's install; an APP package fleet-upgrades every installation across your org."
       );
       process.exit(1);
     }
@@ -68461,16 +68548,16 @@ Available workspaces:`);
         process.exit(1);
       }
     }
-    if (target.startsWith("apg_")) {
-      await packageFleetUpgrade(client, { package_id: target, version: version2 });
+    if (target.startsWith("pci_")) {
+      await redirectContentPciForm(client, target, "upgrade");
       return;
     }
-    if (target.startsWith("pci_")) {
-      await packageUpgradeKnowledge(client, {
-        installation_id: target,
+    if (target.startsWith("apg_")) {
+      await packageUpgradeByPackageId(client, {
+        package_id: target,
         version: version2,
         resolve: flags.resolve,
-        bind_to: parseBindToFlags(flags.bindTo),
+        bindTo: flags.bindTo,
         applyAll: flags.applyAll
       });
       return;
@@ -68541,8 +68628,8 @@ Available workspaces:`);
     }
     const movedVerbs = {
       install: "lotics install <package_id>",
-      uninstall: "lotics uninstall <app_id|pci_id>",
-      upgrade: "lotics upgrade <app_id|pci_id|package_id>",
+      uninstall: "lotics uninstall <app_id|package_id>",
+      upgrade: "lotics upgrade <app_id|package_id>",
       "fleet-upgrade": "lotics upgrade <package_id>"
     };
     if (subcommand !== void 0 && subcommand in movedVerbs) {
@@ -68829,8 +68916,6 @@ ${JSON.stringify(info.input_schema, null, 2)}`);
         console.log(JSON.stringify({ error: result.error }, null, 2));
       } else {
         console.error(result.error);
-        console.error(`
-Hint: run "lotics tools ${toolName}" to see the expected input schema.`);
       }
       process.exit(1);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/cli",
-  "version": "0.83.0",
+  "version": "0.86.0",
   "description": "Lotics SDK and CLI for AI agents",
   "type": "module",
   "bin": {