@lotics/cli 0.83.0 → 0.86.1

package/dist/package_commands.js

@@ -138,7 +138,8 @@ export 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: no changes since the last release.\n" +
+                `  (schema additions aren't fingerprinted — preview them with: lotics app release ${app_id})`
             : "  Package artifacts: pristine — no local edits an upgrade would revert.");
     }
     else if (health.is_origin) {
@@ -375,6 +376,79 @@ function formatTemplateResolveHint(entry) {
         : "   (a local edit — revert overwrites it with the package's version; keep retains it)";
     return `    --resolve template.${entry.alias}=revert|keep${note}`;
 }
+/**
+ * Resolve a STANDALONE content package's installation in the CURRENT workspace
+ * from its PACKAGE id. `UNIQUE (workspace_id, package_id)` means the package id
+ * fully determines the anchor row, so consumers address content by package id and
+ * the `pci_` resource id never surfaces (the server keeps it — resource identity —
+ * and the CLI resolves it here through the list endpoint; zero backend change).
+ * Throws a clear "not installed" error (pointing at `lotics install`) when the
+ * package has no content installation in this workspace.
+ */
+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 — install it first:  lotics install ${package_id}`);
+    }
+    return match;
+}
+/**
+ * CLEAN BREAK for an explicit `pci_` argument on `upgrade` / `uninstall`: the
+ * `pci_` resource id is retired from human sight — content installs are addressed
+ * by their PACKAGE id. Prints a loud redirect, best-effort resolving the `pci_`
+ * back to its package id (via list-content) so the exact command is spelled out.
+ * The header prints synchronously first, so the redirect is observable even when
+ * the best-effort resolution can't reach the registry.
+ */
+export async function redirectContentPciForm(client, pci_id, verb) {
+    console.error(`Content installations are addressed by their PACKAGE id now — ${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)
+        : undefined;
+    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);
+}
+/**
+ * `lotics upgrade <apg_>` — the package-id upgrade path, kind-branched. `kind` is a
+ * DERIVED display hint (`contractHasAppSurface`): `'content'` means no app surface.
+ *   - a CONTENT package upgrades THIS workspace's standalone content installation
+ *     (resolved from the package id — the anchor is unique per workspace, so the
+ *     `pci_` never surfaces), through the same content review gate.
+ *   - an APP-surface package FLEET-upgrades every installation across the org
+ *     (unchanged) — the resolve/bind/apply-all flags don't apply to a fleet run.
+ */
+export async function packageUpgradeByPackageId(client, args) {
+    const pkg = await client.getPackage(args.package_id);
+    if (pkg.kind === "content") {
+        const installation = await resolveWorkspaceContentInstallation(client, args.package_id);
+        await packageUpgradeKnowledge(client, {
+            installation_id: installation.id,
+            package_id: pkg.id,
+            package_name: pkg.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 !== undefined ? { version: args.version } : {}),
+    });
+}
 /**
  * Preview-then-apply a STANDALONE content installation upgrade — knowledge docs
  * AND document templates behind one review gate. Prints the per-alias plan;
@@ -388,7 +462,7 @@ function formatTemplateResolveHint(entry) {
  * resolve entries individually — the ONE namespaced grammar, passed to the
  * server verbatim.
  */
-export async function packageUpgradeKnowledge(client, args) {
+async function packageUpgradeKnowledge(client, args) {
     const preview = await client.previewContentInstallationUpgrade(args.installation_id, {
         ...(args.version !== undefined ? { version: args.version } : {}),
     });
@@ -399,7 +473,7 @@ export async function packageUpgradeKnowledge(client, args) {
             ...(args.version !== undefined ? { version: args.version } : {}),
             resolutions,
         });
-        console.error(`Upgraded ${args.installation_id} → v${updated.package_version}.`);
+        console.error(`Upgraded ${args.package_name} (${args.package_id}) → v${updated.package_version}.`);
     };
     if (preview.entries.length === 0 && preview.templates.length === 0) {
         if (preview.to_version === preview.from_version) {
@@ -472,8 +546,10 @@ export async function packageInstall(client, args) {
     // Surface the trust badge at the consent point: installing materializes the
     // package's workflows/agents (or its doc corpus) under YOUR authority.
     const pkg = await client.getPackage(args.package_id);
-    const kindLabel = pkg.kind === "content" ? "content package" : "package";
-    console.error(`Installing ${pkg.name} — ${trustBadge(pkg)} (${kindLabel})...`);
+    // The kind hint only earns a mention when it adds information (content —
+    // no app materializes); "(package)" after "third-party package" is noise.
+    const kindSuffix = pkg.kind === "content" ? " (content — docs/templates, no app)" : "";
+    console.error(`Installing ${pkg.name} — ${trustBadge(pkg)}${kindSuffix}...`);
     const result = await client.installPackage(args.package_id, {
         ...(args.version !== undefined ? { version: args.version } : {}),
         ...(args.bind_to && Object.keys(args.bind_to).length > 0 ? { bind_to: args.bind_to } : {}),
@@ -483,8 +559,7 @@ export async function packageInstall(client, args) {
         const { installation, warnings } = result;
         const docs = installation.binding.knowledge;
         const templates = installation.binding.templates;
-        console.error(`Installed ${pkg.name} v${installation.package_version} → content installation ${installation.id} ` +
-            `(workspace ${installation.workspace_id}).`);
+        console.error(`Installed ${pkg.name} v${installation.package_version} (workspace ${installation.workspace_id}).`);
         const docAliases = Object.keys(docs);
         if (docAliases.length > 0) {
             console.error(`  ${docAliases.length} doc(s) live: ${docAliases.map((a) => `${a}→${docs[a]}`).join(", ")}`);
@@ -494,8 +569,8 @@ export async function packageInstall(client, args) {
             console.error(`  ${templateAliases.length} template(s) live: ${templateAliases.map((a) => `${a}→${templates[a]}`).join(", ")}`);
         }
         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;
@@ -511,9 +586,11 @@ export async function packageInstall(client, args) {
     console.error(`  Health / uninstall:         lotics package doctor ${app.id}  ·  lotics uninstall ${app.id} [--archive-tables]`);
 }
 /**
- * `lotics uninstall <app_id|pci_id>` — ONE top-level command over both installation
- * kinds, dispatched by the id form (mirrors `lotics upgrade`):
- *   - a `pci_` id → a STANDALONE CONTENT installation: deletes the row and (unless
+ * `lotics uninstall <app_id|package_id>` — ONE top-level command over both
+ * installation kinds, dispatched by the id form (mirrors `lotics upgrade`):
+ *   - a package id (`apg_`) → THIS workspace's STANDALONE CONTENT installation
+ *     (content installs are addressed by package id, UNIQUE per workspace, so the
+ *     `pci_` resource id never surfaces): deletes the row and (unless
  *     `--keep-content`) archives its package-bound docs AND templates, listing each
  *     archived id.
  *   - anything else (an `app_id`) → an APP installation: archives its workflow
@@ -522,19 +599,25 @@ export async function packageInstall(client, args) {
  * A flag used on the wrong path is a loud error, never silently ignored.
  */
 export 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 — use --keep-content to retain its docs/templates.");
+            throw new Error("--archive-tables applies only to an app installation (<app_id>). A content package " +
+                "has no scaffolded tables — use --keep-content to retain its docs/templates.");
+        }
+        const pkg = await client.getPackage(args.id);
+        // kind is a DERIVED display hint (contractHasAppSurface): 'content' = no app.
+        if (pkg.kind !== "content") {
+            throw new Error(`Package ${args.id} is an app package — uninstall an app installation by its app id:  lotics uninstall <app_id>.`);
         }
-        const result = await client.uninstallContentPackage(args.id, {
+        const installation = await resolveWorkspaceContentInstallation(client, args.id);
+        const result = await client.uninstallContentPackage(installation.id, {
             keep_content: args.keep_content,
         });
         if (args.keep_content) {
-            console.error(`Uninstalled content installation ${result.installation_id} — its docs and templates were kept as ordinary workspace content.`);
+            console.error(`Uninstalled ${pkg.name} (${pkg.id}) — its docs and templates were kept as ordinary workspace content.`);
         }
         else {
-            console.error(`Uninstalled content installation ${result.installation_id} — archived ` +
+            console.error(`Uninstalled ${pkg.name} (${pkg.id}) — archived ` +
                 `${result.archived_doc_ids.length} doc(s) and ${result.archived_template_ids.length} template(s).`);
             for (const docId of result.archived_doc_ids)
                 console.error(`    ${docId}`);
@@ -544,7 +627,7 @@ export async function packageUninstall(client, args) {
         return;
     }
     if (args.keep_content) {
-        throw new Error("--keep-content applies only to a standalone content installation (pci_). An app installation " +
+        throw new Error("--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);
@@ -571,8 +654,9 @@ export async function packageUninstall(client, args) {
  * `lotics package list-content` — list the selected workspace's STANDALONE
  * content installations (an app-bundled corpus rides its app's
  * `binding.knowledge` and shows on the Apps surface instead), each with its
- * registry status. The read surface that surfaces a `pci_` id for
- * `upgrade` / `uninstall` (install prints it once; nothing else did before).
+ * registry status. The what-is-installed listing: each row leads with the PACKAGE
+ * id — the address for `lotics upgrade <package_id>` / `lotics uninstall
+ * <package_id>` (the `pci_` resource id stays hidden).
  */
 export async function packageListContent(client) {
     const workspaceId = client.getWorkspaceId();
@@ -592,7 +676,7 @@ export async function packageListContent(client) {
         const versionLabel = latest !== undefined && latest !== inst.package_version
             ? `v${inst.package_version} → latest v${latest}`
             : `v${inst.package_version}`;
-        console.error(`  ${inst.id}  ${name}  ${versionLabel}` +
+        console.error(`  ${inst.package_id}  ${name}  ${versionLabel}` +
             (updateAvailable ? "  → update available" : ""));
     }
 }
@@ -793,34 +877,35 @@ export async function appPublish(client, args) {
     console.error(`    lotics app release ${appId} -m "<what changed>"`);
     console.error(`  Install it elsewhere:  lotics install ${result.package_id}`);
 }
-/**
- * Resolve the release/publish target app id: an explicit `<app_id>` wins; `.` (or
- * no positional) resolves the local app project manifest's `lotics.app_id` — the
- * project `lotics app pull` writes — so a release from the pulled app dir needs
- * no id.
- */
-function resolveOriginAppId(projectDir, explicit) {
-    if (explicit !== undefined && 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.");
-}
 /**
  * `lotics app release [app_id|.] -m <changelog> [--yes]` — snapshot an
  * adopted/installed origin app into its next registry version (docs/packages.md
  * § Promotion). The origin is the permanent working copy; a release binding-aware-
  * extracts it (stable aliases), repackages its DEPLOYED source + dist as the
  * bundle, publishes the next version, and re-pins the origin. Prints the preview
- * first (next version, new + changed aliases, findings); applies only with
- * `--yes`, else exits 1 so a review step can't be skipped. An `error` finding
- * blocks the apply.
+ * first (next version, new + changed aliases, the bundled-knowledge delta,
+ * findings); applies only with `--yes`, else exits 1 so a review step can't be
+ * skipped. An `error` finding blocks the apply.
+ *
+ * Run from the pulled app project, the manifest's `lotics.knowledge` (alias →
+ * doc_id) is the bundle DECLARATION — it re-declares which docs the package owns
+ * (add/drop/re-snapshot). Forwarded only when non-empty; empty (or a bare id from
+ * elsewhere) sends nothing, so the current corpus is reconstructed from the pin
+ * (never silently dropped).
  */
 export async function appRelease(client, args) {
     const projectDir = path.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 !== undefined && args.app_id !== "." ? args.app_id : undefined;
+    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.");
+    }
+    // Forward the manifest's knowledge DECLARATION only from this app's own project
+    // AND only when it lists docs — an empty/absent declaration is "no change"
+    // (reconstruct from the pin), never "drop the bundle".
+    const knowledge = local && local.app_id === appId && local.knowledge.length > 0 ? local.knowledge : undefined;
+    const preview = await client.previewPackageRelease(appId, { knowledge });
     const { lines, hasError } = formatExtractReport(preview.findings);
     console.error(`Release preview — ${appId} → ${preview.package_id} v${preview.version}:`);
     if (preview.added_aliases.length > 0) {
@@ -829,7 +914,21 @@ export 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) {
+    // Deploy-skew boundary: a pre-knowledge-declaration server omits the field.
+    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) {
@@ -848,7 +947,7 @@ export async function appRelease(client, args) {
         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} — verify:  lotics package doctor ${appId}`);
 }
@@ -876,7 +975,7 @@ export async function packageYank(client, args) {
  * installations are reported per line and the process exits 1 so a release
  * script can gate on "fleet fully current".
  */
-export async function packageFleetUpgrade(client, args) {
+async function packageFleetUpgrade(client, args) {
     const result = await client.fleetUpgradePackage(args.package_id, {
         ...(args.version !== undefined ? { version: args.version } : {}),
     });

package/dist/package_commands.test.js

@@ -1,8 +1,8 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import { tmpdir } from "node:os";
-import { parseResolveFlags, parseBindToFlags, parseRenameFlags, readLocalAppManifest, formatExtractReport, } from "./package_commands.js";
+import { parseResolveFlags, parseBindToFlags, parseRenameFlags, readLocalAppManifest, formatExtractReport, appRelease, packageUpgradeByPackageId, } from "./package_commands.js";
 import { parseArgs } from "./args.js";
 describe("parseRenameFlags", () => {
     it("parses old=new pairs", () => {
@@ -146,6 +146,139 @@ describe("parseArgs — package list-content", () => {
         expect(flags.workspace).toBe("wsp_dev");
     });
 });
+describe("appRelease — knowledge declaration forwarding", () => {
+    const previewResult = {
+        package_id: "apg_1",
+        version: 2,
+        added_aliases: [],
+        changed_artifacts: [],
+        knowledge: { added: ["guide"], removed: [], changed: [] },
+        findings: [],
+    };
+    /** A mock client capturing the knowledge forwarded to preview + release. */
+    function mockClient() {
+        const preview = [];
+        const release = [];
+        const client = {
+            previewPackageRelease: async (app_id, opts = {}) => {
+                preview.push({ app_id, opts });
+                return previewResult;
+            },
+            releasePackage: async (app_id, body) => {
+                release.push({ app_id, body });
+                return { ...previewResult, findings: undefined };
+            },
+        };
+        return { client, preview, release };
+    }
+    function withManifestDir(lotics, fn) {
+        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-rel-"));
+        fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({ name: "app", lotics }));
+        return fn(dir).finally(() => fs.rmSync(dir, { recursive: true, force: true }));
+    }
+    it("forwards the manifest's knowledge declaration from the app's own project", async () => {
+        vi.spyOn(console, "error").mockImplementation(() => undefined);
+        const { client, preview, release } = mockClient();
+        await withManifestDir({ app_id: "app_x", knowledge: [{ alias: "guide", doc_id: "kdc_1" }] }, async (dir) => {
+            await appRelease(client, { app_id: ".", changelog: "ship", yes: true, projectDir: dir });
+        });
+        expect(preview[0]).toEqual({ app_id: "app_x", opts: { knowledge: [{ alias: "guide", doc_id: "kdc_1" }] } });
+        expect(release[0].body).toEqual({ changelog: "ship", knowledge: [{ alias: "guide", doc_id: "kdc_1" }] });
+        vi.restoreAllMocks();
+    });
+    it("omits knowledge (reconstruct from the pin) when the manifest declares none", async () => {
+        vi.spyOn(console, "error").mockImplementation(() => undefined);
+        const { client, preview, release } = mockClient();
+        await withManifestDir({ app_id: "app_x" }, async (dir) => {
+            await appRelease(client, { app_id: ".", changelog: "ship", yes: true, projectDir: dir });
+        });
+        expect(preview[0].opts).toEqual({ knowledge: undefined });
+        expect(release[0].body).toEqual({ changelog: "ship", knowledge: undefined });
+        vi.restoreAllMocks();
+    });
+    it("omits knowledge for a bare app id whose manifest is a DIFFERENT app", async () => {
+        vi.spyOn(console, "error").mockImplementation(() => undefined);
+        const { client, preview } = mockClient();
+        await withManifestDir({ app_id: "app_other", knowledge: [{ alias: "guide", doc_id: "kdc_1" }] }, async (dir) => {
+            await appRelease(client, { app_id: "app_x", changelog: "ship", yes: true, projectDir: dir });
+        });
+        expect(preview[0]).toEqual({ app_id: "app_x", opts: { knowledge: undefined } });
+        vi.restoreAllMocks();
+    });
+});
+describe("packageUpgradeByPackageId — kind-branched by the package read", () => {
+    /**
+     * A mock client recording which upgrade path a `lotics upgrade <apg_>` takes.
+     * `kind` drives the branch: a content package resolves THIS workspace's content
+     * installation from the package id (the `pci_` never surfaces) and runs the
+     * content upgrade; an app package fleet-upgrades the org.
+     */
+    function mockClient(opts) {
+        const calls = { previewContent: [], fleet: [], listedWorkspaces: [] };
+        const client = {
+            getPackage: async (package_id) => ({
+                id: package_id,
+                name: "Ops corpus",
+                kind: opts.kind,
+                latest_version: 3,
+                is_official: false,
+                retired_at: null,
+            }),
+            getWorkspaceId: () => "wsp_1",
+            listContentInstallations: async (workspace_id) => {
+                calls.listedWorkspaces.push(workspace_id);
+                return (opts.installations ?? []).map((i) => ({
+                    ...i,
+                    workspace_id,
+                    package_version: 2,
+                    app_id: null,
+                    binding: { knowledge: {}, templates: {} },
+                    installed_by: null,
+                    created_at: "",
+                    updated_at: "",
+                    package_registry: null,
+                }));
+            },
+            previewContentInstallationUpgrade: async (installation_id) => {
+                calls.previewContent.push(installation_id);
+                return { from_version: 2, to_version: 2, entries: [], templates: [] };
+            },
+            fleetUpgradePackage: async (package_id) => {
+                calls.fleet.push(package_id);
+                return { package_id, target_version: 3, installations: [] };
+            },
+        };
+        return { client, calls };
+    }
+    const args = { version: undefined, resolve: [], bindTo: [], applyAll: false };
+    it("routes a CONTENT package to this workspace's content installation (resolved from the package id)", async () => {
+        vi.spyOn(console, "error").mockImplementation(() => undefined);
+        const { client, calls } = mockClient({
+            kind: "content",
+            installations: [{ id: "pci_1", package_id: "apg_content" }],
+        });
+        await packageUpgradeByPackageId(client, { package_id: "apg_content", ...args });
+        expect(calls.listedWorkspaces).toEqual(["wsp_1"]);
+        expect(calls.previewContent).toEqual(["pci_1"]); // resolved apg_ → pci_ client-side
+        expect(calls.fleet).toEqual([]); // never a fleet run for content
+        vi.restoreAllMocks();
+    });
+    it("routes an APP package to the org fleet upgrade", async () => {
+        vi.spyOn(console, "error").mockImplementation(() => undefined);
+        const { client, calls } = mockClient({ kind: "app" });
+        await packageUpgradeByPackageId(client, { package_id: "apg_app", ...args });
+        expect(calls.fleet).toEqual(["apg_app"]);
+        expect(calls.previewContent).toEqual([]);
+        expect(calls.listedWorkspaces).toEqual([]); // no content resolution for an app package
+        vi.restoreAllMocks();
+    });
+    it("errors clearly when a content package is not installed in this workspace", async () => {
+        vi.spyOn(console, "error").mockImplementation(() => undefined);
+        const { client } = mockClient({ kind: "content", installations: [] });
+        await expect(packageUpgradeByPackageId(client, { package_id: "apg_content", ...args })).rejects.toThrow(/not installed in this workspace[\s\S]*lotics install apg_content/);
+        vi.restoreAllMocks();
+    });
+});
 describe("formatExtractReport", () => {
     it("groups findings errors → warnings → info and formats each line", () => {
         const { lines, hasError } = formatExtractReport([