@lotics/cli 0.76.1 → 0.86.0

package/dist/package_commands.test.js

@@ -1,357 +1,45 @@
-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 { createHash } from "node:crypto";
-import { parsePackageContract, validatePackageContract, } from "@lotics/shared/schemas/packages";
-import { starterContract, readPackageProject, writePackageManifest, sanitizePackageJsonForSource, stagePackageSource, foldKnowledgeIntoContract, foldTemplateShasIntoContract, foldTemplatesIntoContract, parseResolveFlags, routeContentResolveFlags, parseBindToFlags, routeAppUpgradeResolve, assertDevWorkspace, draftPackageProjectFromApp, parseAdoptBindingFile, formatExtractReport, } from "./package_commands.js";
+import { parseResolveFlags, parseBindToFlags, parseRenameFlags, readLocalAppManifest, formatExtractReport, appRelease, packageUpgradeByPackageId, } from "./package_commands.js";
 import { parseArgs } from "./args.js";
-describe("starterContract", () => {
-    it("scaffolds a structurally + referentially valid contract", () => {
-        const raw = starterContract("Acme CRM");
-        // Structurally valid against the canonical contract schema.
-        const contract = parsePackageContract(raw);
-        // Cross-references (query from_entity, etc.) resolve — zero violations, so the
-        // scaffold publishes without the server's contract validator rejecting it.
-        expect(validatePackageContract(contract)).toEqual([]);
-    });
-    it("uses the package name as the entity label", () => {
-        const contract = parsePackageContract(starterContract("Widgets"));
-        expect(contract.entities[0].label).toBe("Widgets");
-        expect(contract.config[0].default).toBe("Widgets");
-    });
-});
-describe("package manifest round-trip", () => {
-    function makeProject() {
-        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-pkg-test-"));
-        fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({
-            name: "acme-crm",
-            version: "0.0.1",
-            lotics: {
-                package: { id: null, name: "Acme CRM", description: null, version: null, dev: {} },
-            },
-        }, null, 2) + "\n");
-        return dir;
-    }
-    it("reads the package manifest off package.json#lotics.package", () => {
-        const dir = makeProject();
-        try {
-            const { manifest } = readPackageProject(dir);
-            expect(manifest).toEqual({
-                id: null,
-                name: "Acme CRM",
-                description: null,
-                kind: "app",
-                version: null,
-                knowledge: {},
-                templates: {},
-                knowledge_expects: [],
-                dev: {},
-            });
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("persists publish + dev-installation pins and reads them back", () => {
-        const dir = makeProject();
-        try {
-            const project = readPackageProject(dir);
-            project.manifest.id = "apg_test";
-            project.manifest.version = 3;
-            project.manifest.dev["wsp_dev"] = { app_id: "app_dev", version: 3 };
-            writePackageManifest(dir, project);
-            const reread = readPackageProject(dir);
-            expect(reread.manifest.id).toBe("apg_test");
-            expect(reread.manifest.version).toBe(3);
-            expect(reread.manifest.dev).toEqual({ wsp_dev: { app_id: "app_dev", version: 3 } });
-            // Non-lotics package.json fields survive the manifest write.
-            expect(reread.pkgJson.name).toBe("acme-crm");
-            expect(reread.pkgJson.version).toBe("0.0.1");
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("writes the manifest atomically, leaving no temp file behind", () => {
-        const dir = makeProject();
-        try {
-            const project = readPackageProject(dir);
-            project.manifest.id = "apg_atomic";
-            writePackageManifest(dir, project);
-            // The atomic write renames a temp file into place; nothing stray remains.
-            const leftovers = fs.readdirSync(dir).filter((f) => f.startsWith("package.json."));
-            expect(leftovers).toEqual([]);
-            expect(readPackageProject(dir).manifest.id).toBe("apg_atomic");
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-});
-describe("sanitizePackageJsonForSource", () => {
-    it("strips the author-local lotics.package.dev map", () => {
-        const sanitized = sanitizePackageJsonForSource({
-            name: "acme-crm",
-            version: "0.0.1",
-            lotics: {
-                package: {
-                    id: "apg_x",
-                    name: "Acme CRM",
-                    description: "d",
-                    version: 4,
-                    dev: { wsp_dev: { app_id: "app_dev", version: 4 } },
-                },
-            },
-        });
-        const lotics = sanitized.lotics;
-        // The private dev bookkeeping is gone…
-        expect("dev" in lotics.package).toBe(false);
-        // …while the package identity + other fields survive untouched.
-        expect(lotics.package).toEqual({
-            id: "apg_x",
-            name: "Acme CRM",
-            description: "d",
-            version: 4,
-        });
-        expect(sanitized.name).toBe("acme-crm");
-        expect(sanitized.version).toBe("0.0.1");
+describe("parseRenameFlags", () => {
+    it("parses old=new pairs", () => {
+        expect(parseRenameFlags(["item=deal", "don_hang=orders"])).toEqual([
+            { from: "item", to: "deal" },
+            { from: "don_hang", to: "orders" },
+        ]);
+        expect(parseRenameFlags(["e.f=name"])).toEqual([{ from: "e.f", to: "name" }]);
+        expect(parseRenameFlags([])).toEqual([]);
     });
-    it("does not mutate the input package.json", () => {
-        const input = {
-            name: "acme-crm",
-            lotics: { package: { id: "apg_x", name: "Acme CRM", dev: { wsp_dev: { app_id: "a", version: 1 } } } },
-        };
-        sanitizePackageJsonForSource(input);
-        expect(input.lotics.package.dev).toEqual({ wsp_dev: { app_id: "a", version: 1 } });
+    it("rejects a malformed rename", () => {
+        expect(() => parseRenameFlags(["nope"])).toThrow(/expected old=new/);
+        expect(() => parseRenameFlags(["=x"])).toThrow(/expected old=new/);
+        expect(() => parseRenameFlags(["x="])).toThrow(/expected old=new/);
     });
 });
-describe("foldKnowledgeIntoContract", () => {
-    function makeKnowledgeProject(knowledge, knowledge_expects, files) {
-        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-know-test-"));
-        fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({
-            name: "acme-kb",
-            lotics: {
-                // Everything package-related lives under `lotics.package` — including
-                // knowledge_expects (reconciled from the earlier lotics.knowledge_expects).
-                package: {
-                    id: null,
-                    name: "Acme KB",
-                    description: null,
-                    version: null,
-                    knowledge,
-                    knowledge_expects,
-                    dev: {},
-                },
-            },
-        }, null, 2) + "\n");
-        for (const [rel, content] of Object.entries(files)) {
-            const full = path.join(dir, rel);
-            fs.mkdirSync(path.dirname(full), { recursive: true });
-            fs.writeFileSync(full, content);
-        }
-        return dir;
-    }
-    it("emits a contract knowledge namespace with the file's sha256 + canonical content_ref", () => {
-        const content = "# Pricing\n\nHow we price things.\n";
-        const dir = makeKnowledgeProject({ pricing: { name: "Pricing Guide", description: "How we price", active_by_default: false } }, ["Employee Handbook"], { "knowledge/pricing.md": content });
-        try {
-            const project = readPackageProject(dir);
-            const folded = foldKnowledgeIntoContract(dir, project, { entities: [] });
-            const expectedSha = createHash("sha256").update(Buffer.from(content)).digest("hex");
-            expect(folded.knowledge).toEqual({
-                pricing: {
-                    name: "Pricing Guide",
-                    description: "How we price",
-                    content_ref: "knowledge/pricing.md",
-                    content_sha256: expectedSha,
-                    active_by_default: false,
-                },
-            });
-            expect(folded.knowledge_expects).toEqual(["Employee Handbook"]);
-            // The folded contract is valid end-to-end (parse + referential-integrity).
-            const parsed = parsePackageContract(folded);
-            expect(validatePackageContract(parsed)).toEqual([]);
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("defaults active_by_default to true and description to empty when omitted", () => {
-        const dir = makeKnowledgeProject({ policies: { name: "Policies" } }, [], { "knowledge/policies.md": "body" });
-        try {
-            const project = readPackageProject(dir);
-            const folded = foldKnowledgeIntoContract(dir, project, { entities: [] });
-            expect(folded.knowledge.policies.active_by_default).toBe(true);
-            expect(folded.knowledge.policies.description).toBe("");
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("throws when a declared knowledge doc has no content file", () => {
-        const dir = makeKnowledgeProject({ ghost: { name: "Ghost" } }, [], {});
-        try {
-            const project = readPackageProject(dir);
-            expect(() => foldKnowledgeIntoContract(dir, project, { entities: [] })).toThrow(/knowledge\/ghost\.md/);
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("leaves a knowledge-free contract untouched", () => {
-        const dir = makeKnowledgeProject({}, [], {});
-        try {
-            const project = readPackageProject(dir);
-            const contract = { entities: [] };
-            expect(foldKnowledgeIntoContract(dir, project, contract)).toBe(contract);
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("round-trips lotics.package.knowledge through a manifest write (id stamp never drops it)", () => {
-        const dir = makeKnowledgeProject({ pricing: { name: "Pricing Guide", description: "d", active_by_default: true } }, ["Handbook"], { "knowledge/pricing.md": "body" });
+describe("readLocalAppManifest", () => {
+    it("reads app_id + knowledge from a pulled app project", () => {
+        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-app-test-"));
         try {
-            const project = readPackageProject(dir);
-            project.manifest.id = "apg_stamped";
-            writePackageManifest(dir, project);
-            const reread = readPackageProject(dir);
-            expect(reread.manifest.id).toBe("apg_stamped");
-            expect(reread.manifest.knowledge).toEqual({
-                pricing: { name: "Pricing Guide", description: "d", active_by_default: true },
+            fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({
+                name: "crm",
+                lotics: { app_id: "app_x", knowledge: [{ alias: "sop", doc_id: "kdc_1" }] },
+            }));
+            expect(readLocalAppManifest(dir)).toEqual({
+                app_id: "app_x",
+                knowledge: [{ alias: "sop", doc_id: "kdc_1" }],
             });
-            // knowledge_expects now lives under lotics.package and survives the write.
-            expect(reread.manifest.knowledge_expects).toEqual(["Handbook"]);
-            const lotics = reread.pkgJson.lotics;
-            expect(lotics.package.knowledge_expects).toEqual(["Handbook"]);
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-});
-describe("foldTemplateShasIntoContract", () => {
-    it("computes content_sha256 for inline (content) and file-backed (bytes_ref) templates", () => {
-        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-tmpl-test-"));
-        const inlineContent = "<p>{{deal.title}}</p>";
-        const fileBytes = Buffer.from("PK fake xlsx bytes");
-        fs.mkdirSync(path.join(dir, "templates"), { recursive: true });
-        fs.writeFileSync(path.join(dir, "templates", "invoice.xlsx"), fileBytes);
-        try {
-            const contract = {
-                templates: [
-                    { alias: "quote", label: "Quote", type: "html", content: inlineContent },
-                    { alias: "invoice", label: "Invoice", type: "excel", bytes_ref: "templates/invoice.xlsx" },
-                ],
-            };
-            const folded = foldTemplateShasIntoContract(dir, contract);
-            const inlineSha = createHash("sha256").update(Buffer.from(inlineContent, "utf-8")).digest("hex");
-            const fileSha = createHash("sha256").update(fileBytes).digest("hex");
-            expect(folded.templates.find((t) => t.alias === "quote")?.content_sha256).toBe(inlineSha);
-            expect(folded.templates.find((t) => t.alias === "invoice")?.content_sha256).toBe(fileSha);
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("throws when a file-backed template's bytes_ref is missing from the project", () => {
-        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-tmpl-test-"));
-        try {
-            expect(() => foldTemplateShasIntoContract(dir, {
-                templates: [{ alias: "invoice", label: "Invoice", type: "excel", bytes_ref: "templates/missing.xlsx" }],
-            })).toThrow(/templates\/missing\.xlsx/);
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("leaves a template-free contract untouched", () => {
-        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-tmpl-test-"));
-        try {
-            const contract = { entities: [] };
-            expect(foldTemplateShasIntoContract(dir, contract)).toBe(contract);
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-});
-describe("foldTemplatesIntoContract (content-package manifest templates)", () => {
-    function makeTemplateProject(templates, files) {
-        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-ctmpl-test-"));
-        fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({
-            name: "acme-templates",
-            lotics: {
-                package: { id: null, name: "Acme Templates", kind: "content", version: null, templates },
-            },
-        }, null, 2) + "\n");
-        for (const [rel, content] of Object.entries(files)) {
-            const full = path.join(dir, rel);
-            fs.mkdirSync(path.dirname(full), { recursive: true });
-            fs.writeFileSync(full, content);
-        }
-        return dir;
-    }
-    it("folds inline content + file-backed bytes_ref, and the sha fold makes them publish-valid", () => {
-        const inline = "<p>Hello {{customer.name}}</p>";
-        const dir = makeTemplateProject({
-            welcome: { name: "Welcome Email", type: "html", file: "welcome.html" },
-            invoice: { name: "Invoice", type: "excel", file: "invoice.xlsx" },
-        }, { "templates/welcome.html": inline, "templates/invoice.xlsx": "PK fake xlsx" });
-        try {
-            const project = readPackageProject(dir);
-            const folded = foldTemplateShasIntoContract(dir, foldTemplatesIntoContract(dir, project, { entities: [], templates: [] }));
-            const welcome = folded.templates.find((t) => t.alias === "welcome");
-            const invoice = folded.templates.find((t) => t.alias === "invoice");
-            expect(welcome).toMatchObject({ label: "Welcome Email", type: "html", content: inline });
-            expect(invoice).toMatchObject({ label: "Invoice", type: "excel", bytes_ref: "templates/invoice.xlsx" });
-            // The sha fold ran over the manifest-folded templates → both carry a sha.
-            expect(typeof welcome?.content_sha256).toBe("string");
-            expect(typeof invoice?.content_sha256).toBe("string");
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("throws when a declared template file is missing from templates/", () => {
-        const dir = makeTemplateProject({ welcome: { name: "Welcome", type: "html", file: "welcome.html" } }, {});
-        try {
-            const project = readPackageProject(dir);
-            expect(() => foldTemplatesIntoContract(dir, project, { templates: [] })).toThrow(/templates\/welcome\.html/);
         }
         finally {
             fs.rmSync(dir, { recursive: true, force: true });
         }
     });
-    it("rejects a manifest alias that collides with a contract-authored template alias", () => {
-        const dir = makeTemplateProject({ quote: { name: "Quote", type: "html", file: "quote.html" } }, { "templates/quote.html": "<p>q</p>" });
+    it("returns null when the dir has no package.json", () => {
+        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-empty-"));
         try {
-            const project = readPackageProject(dir);
-            expect(() => foldTemplatesIntoContract(dir, project, {
-                templates: [{ alias: "quote", label: "Quote", type: "html", content: "x" }],
-            })).toThrow(/declared in both/);
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-});
-describe("assertDevWorkspace", () => {
-    it("passes a dev workspace", () => {
-        expect(() => assertDevWorkspace({ id: "wsp_d", name: "Dev", is_dev: true })).not.toThrow();
-    });
-    it("fails loud on a non-dev workspace", () => {
-        expect(() => assertDevWorkspace({ id: "wsp_p", name: "Prod", is_dev: false })).toThrow(/not a dev workspace/);
-    });
-    it("fails closed when is_dev is absent (server doesn't serialize it)", () => {
-        expect(() => assertDevWorkspace({ id: "wsp_u", name: "Unknown" })).toThrow(/not a dev workspace/);
-    });
-    it("rejects a directory that is not a package project", () => {
-        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-pkg-test-"));
-        try {
-            fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({ name: "plain-app" }));
-            expect(() => readPackageProject(dir)).toThrow(/not a package project/);
+            expect(readLocalAppManifest(dir)).toBeNull();
         }
         finally {
             fs.rmSync(dir, { recursive: true, force: true });
@@ -377,31 +65,33 @@ describe("parseResolveFlags", () => {
         expect(() => parseResolveFlags(["fields.deal.stage="])).toThrow(/Invalid --resolve/);
     });
 });
-describe("routeContentResolveFlags", () => {
-    const knowledge = new Set(["pricing", "faq", "old", "gone"]);
-    const templates = new Set(["quote", "invoice"]);
-    it("routes each alias to its namespace, validating the value", () => {
-        expect(routeContentResolveFlags(["pricing=apply", "faq=keep", "old=archive", "gone=recreate", "quote=revert", "invoice=keep"], knowledge, templates)).toEqual({
-            knowledge: { pricing: "apply", faq: "keep", old: "archive", gone: "recreate" },
-            templates: { quote: "revert", invoice: "keep" },
+describe("parseResolveFlags — the one namespaced grammar", () => {
+    it("passes knowledge verbs through under knowledge.<alias> keys", () => {
+        expect(parseResolveFlags([
+            "knowledge.pricing=apply",
+            "knowledge.faq=keep",
+            "knowledge.old=archive",
+            "knowledge.gone=recreate",
+            "knowledge.legacy=unbind",
+        ])).toEqual({
+            "knowledge.pricing": "apply",
+            "knowledge.faq": "keep",
+            "knowledge.old": "archive",
+            "knowledge.gone": "recreate",
+            "knowledge.legacy": "unbind",
         });
     });
-    it("rejects a knowledge value outside the knowledge set", () => {
-        expect(() => routeContentResolveFlags(["pricing=revert"], knowledge, templates)).toThrow(/Invalid --resolve value/);
-    });
-    it("rejects a template value outside revert|keep", () => {
-        expect(() => routeContentResolveFlags(["quote=apply"], knowledge, templates)).toThrow(/Invalid --resolve value/);
-    });
-    it("errors loudly on an alias present in BOTH namespaces (no guess)", () => {
-        expect(() => routeContentResolveFlags(["overview=keep"], new Set(["overview"]), new Set(["overview"]))).toThrow(/ambiguous/);
-    });
-    it("errors on an alias in neither namespace", () => {
-        expect(() => routeContentResolveFlags(["nope=keep"], knowledge, templates)).toThrow(/does not name a knowledge doc or template/);
+    it("passes template consents through under template.<alias> keys", () => {
+        expect(parseResolveFlags(["template.quote=revert", "template.invoice=keep"])).toEqual({
+            "template.quote": "revert",
+            "template.invoice": "keep",
+        });
     });
-    it("rejects entries without a key=value shape", () => {
-        expect(() => routeContentResolveFlags(["pricing"], knowledge, templates)).toThrow(/Invalid --resolve/);
-        expect(() => routeContentResolveFlags(["=apply"], knowledge, templates)).toThrow(/Invalid --resolve/);
-        expect(() => routeContentResolveFlags(["pricing="], knowledge, templates)).toThrow(/Invalid --resolve/);
+    it("maps a non-verb value to a bind_to id on any key (roles rebind, knowledge adopt)", () => {
+        expect(parseResolveFlags(["roles.approver=grp_new", "knowledge.faq=kdc_existing"])).toEqual({
+            "roles.approver": { bind_to: "grp_new" },
+            "knowledge.faq": { bind_to: "kdc_existing" },
+        });
     });
 });
 describe("parseBindToFlags", () => {
@@ -417,31 +107,25 @@ describe("parseBindToFlags", () => {
         expect(() => parseBindToFlags(["playbook="])).toThrow(/Invalid --bind-to/);
     });
 });
-describe("parseArgs — content package flags", () => {
-    it("captures --kind, --bind-to (repeatable), --keep-content, --apply-all", () => {
+describe("parseArgs — app publish --rename", () => {
+    it("captures repeated --rename flags with the positional app id", () => {
         const { command, subcommand, toolArgs, flags } = parseArgs([
-            "package",
-            "install",
-            "apg_1",
-            "--bind-to",
-            "playbook=kdc_1",
-            "--bind-to",
-            "faq=kdc_2",
-            "--keep-content",
-            "--apply-all",
-            "--kind",
-            "content",
+            "app",
+            "publish",
+            "app_x",
+            "--rename",
+            "item=deal",
+            "--rename",
+            "e.f=name",
         ]);
-        expect(command).toBe("package");
-        expect(subcommand).toBe("install");
-        expect(toolArgs).toBe("apg_1");
-        expect(flags.bindTo).toEqual(["playbook=kdc_1", "faq=kdc_2"]);
-        expect(flags.keepContent).toBe(true);
-        expect(flags.applyAll).toBe(true);
-        expect(flags.kind).toBe("content");
+        expect(command).toBe("app");
+        expect(subcommand).toBe("publish");
+        expect(toolArgs).toBe("app_x");
+        expect(flags.rename).toEqual(["item=deal", "e.f=name"]);
     });
-    it("throws when --bind-to has no value", () => {
-        expect(() => parseArgs(["package", "install", "apg_1", "--bind-to"])).toThrow(/--bind-to/);
+    it("throws when --rename has no value", () => {
+        expect(() => parseArgs(["app", "publish", "--rename"])).toThrow(/--rename requires a value/);
+        expect(() => parseArgs(["app", "publish", "--rename", "--yes"])).toThrow(/--rename requires a value/);
     });
 });
 describe("parseArgs — package list-content", () => {
@@ -462,128 +146,137 @@ describe("parseArgs — package list-content", () => {
         expect(flags.workspace).toBe("wsp_dev");
     });
 });
-describe("routeAppUpgradeResolve", () => {
-    const kEntry = (alias, change, modified = false) => ({
-        alias,
-        name: alias,
-        change,
-        modified,
-        doc_id: change === "added" ? null : "kdc_x",
-    });
-    it("routes a knowledge-alias --resolve to the knowledge bucket, everything else to core", () => {
-        const { coreResolve, knowledgeResolutions } = routeAppUpgradeResolve(["policy=apply", "fields.deal.stage=recreate", "queries.tasks=keep"], [kEntry("policy", "changed", true)], new Set(["fields.deal.stage", "queries.tasks"]));
-        expect(knowledgeResolutions).toEqual({ policy: "apply" });
-        // Core entries keep their raw <key>=<value> form for parseResolveFlags.
-        expect(coreResolve).toEqual(["fields.deal.stage=recreate", "queries.tasks=keep"]);
-    });
-    it("errors when a --resolve key names BOTH a knowledge doc and a core artifact", () => {
-        expect(() => routeAppUpgradeResolve(["policy=apply"], [kEntry("policy", "changed", true)], new Set(["policy"]))).toThrow(/ambiguous/);
-    });
-    it("rejects a knowledge --resolve value invalid for the doc's change class", () => {
-        // `changed` accepts apply|keep — `revert` is a core value, not a knowledge one.
-        expect(() => routeAppUpgradeResolve(["policy=revert"], [kEntry("policy", "changed", true)], new Set())).toThrow(/Invalid --resolve value "revert" for knowledge doc "policy"/);
-        // `drifted` accepts recreate|unbind, not apply.
-        expect(() => routeAppUpgradeResolve(["gone=apply"], [kEntry("gone", "drifted")], new Set())).toThrow(/expected recreate\|unbind/);
-    });
-    it("rejects a malformed --resolve entry", () => {
-        expect(() => routeAppUpgradeResolve(["policy"], [], new Set())).toThrow(/Invalid --resolve/);
-        expect(() => routeAppUpgradeResolve(["=apply"], [], new Set())).toThrow(/Invalid --resolve/);
-    });
-    it("leaves an unmatched key as a core resolution (the server is the validator)", () => {
-        const { coreResolve, knowledgeResolutions } = routeAppUpgradeResolve(["templates.quote=dtl_abc"], [], new Set());
-        expect(knowledgeResolutions).toEqual({});
-        expect(coreResolve).toEqual(["templates.quote=dtl_abc"]);
-    });
-});
-describe("draftPackageProjectFromApp", () => {
-    it("strips the app manifest and grafts an unpublished package manifest", () => {
-        const project = draftPackageProjectFromApp({
-            name: "acme-crm",
-            version: "0.0.1",
-            dependencies: { "@lotics/app-sdk": "^1.0.0" },
-            lotics: {
-                app_id: "app_x",
-                workspace_id: "wsp_y",
-                current_version_id: "apv_z",
-                workflows: { notify: { workflow_id: "wfl_1" } },
+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 };
             },
-        }, { name: "Acme CRM", description: null });
-        // The app manifest (app_id/workspace_id/workflows) is gone entirely…
-        expect("lotics" in project.pkgJson).toBe(false);
-        // …the package manifest is fresh + unpublished…
-        expect(project.manifest).toEqual({
-            id: null,
-            name: "Acme CRM",
-            description: null,
-            kind: "app",
-            version: null,
-            knowledge: {},
-            templates: {},
-            knowledge_expects: [],
-            dev: {},
+        };
+        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 });
         });
-        // …and non-lotics fields survive verbatim.
-        expect(project.pkgJson.name).toBe("acme-crm");
-        expect(project.pkgJson.version).toBe("0.0.1");
-        expect(project.pkgJson.dependencies).toEqual({ "@lotics/app-sdk": "^1.0.0" });
-    });
-    it("round-trips through writePackageManifest to a valid package project on disk", () => {
-        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-pkg-test-"));
-        try {
-            writePackageManifest(dir, draftPackageProjectFromApp({ name: "acme-crm", lotics: { app_id: "app_x", workspace_id: "wsp_y" } }, { name: "Acme CRM", description: "A CRM" }));
-            // readPackageProject only accepts a real package project (lotics.package).
-            const { manifest, pkgJson } = readPackageProject(dir);
-            expect(manifest).toEqual({
-                id: null,
-                name: "Acme CRM",
-                description: "A CRM",
-                kind: "app",
-                version: null,
-                knowledge: {},
-                templates: {},
-                knowledge_expects: [],
-                dev: {},
-            });
-            // The old app manifest keys never made it to disk.
-            const lotics = pkgJson.lotics;
-            expect("app_id" in lotics).toBe(false);
-            expect("workspace_id" in lotics).toBe(false);
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-        }
-    });
-    it("does not mutate the input package.json", () => {
-        const input = { name: "acme-crm", lotics: { app_id: "app_x", workspace_id: "wsp_y" } };
-        draftPackageProjectFromApp(input, { name: "Acme CRM", description: null });
-        expect(input.lotics).toEqual({ app_id: "app_x", workspace_id: "wsp_y" });
+        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("parseAdoptBindingFile", () => {
-    const validPin = {
-        app_id: "app_x",
-        workspace_id: "wsp_y",
-        binding: { entities: { item: "tbl_1" }, fields: {}, options: {}, templates: {}, roles: {}, workflows: {} },
-    };
-    it("accepts a pin whose app_id matches the app being adopted", () => {
-        const pin = parseAdoptBindingFile(validPin, "app_x");
-        expect(pin.app_id).toBe("app_x");
-        expect(pin.workspace_id).toBe("wsp_y");
-        expect(pin.binding.entities).toEqual({ item: "tbl_1" });
-        // knowledge_binding is optional → defaults to {} when absent.
-        expect(pin.knowledge_binding).toEqual({});
-    });
-    it("carries a knowledge_binding when present", () => {
-        const pin = parseAdoptBindingFile({ ...validPin, knowledge_binding: { playbook: "kdc_1", faq: "kdc_2" } }, "app_x");
-        expect(pin.knowledge_binding).toEqual({ playbook: "kdc_1", faq: "kdc_2" });
-    });
-    it("REFUSES a pin recorded for a different app", () => {
-        expect(() => parseAdoptBindingFile(validPin, "app_OTHER")).toThrow(/records app app_x, but you are adopting app_OTHER/);
-    });
-    it("rejects a malformed pin", () => {
-        expect(() => parseAdoptBindingFile({ app_id: "app_x" }, "app_x")).toThrow(/Malformed/);
-        expect(() => parseAdoptBindingFile(null, "app_x")).toThrow(/Malformed/);
-        expect(() => parseAdoptBindingFile({ app_id: "app_x", workspace_id: "wsp_y" }, "app_x")).toThrow(/Malformed/);
+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", () => {
@@ -614,39 +307,3 @@ describe("formatExtractReport", () => {
         expect(formatExtractReport([])).toEqual({ lines: [], hasError: false });
     });
 });
-describe("stagePackageSource", () => {
-    it("keeps nested dist-named dirs, drops top-level excludes, sanitizes package.json", () => {
-        const dir = fs.mkdtempSync(path.join(tmpdir(), "lotics-stage-test-"));
-        const stage = fs.mkdtempSync(path.join(tmpdir(), "lotics-stage-out-"));
-        try {
-            fs.writeFileSync(path.join(dir, "package.json"), JSON.stringify({
-                name: "pkg",
-                lotics: { package: { id: "apg_x", name: "pkg", version: 3, dev: { wsp_a: "app_1" } } },
-            }));
-            fs.mkdirSync(path.join(dir, "src"));
-            fs.writeFileSync(path.join(dir, "src", "main.tsx"), "export {}");
-            // A nested dir NAMED dist must ship — only the top-level dist is a build output.
-            fs.mkdirSync(path.join(dir, "templates", "dist"), { recursive: true });
-            fs.writeFileSync(path.join(dir, "templates", "dist", "quote.xlsx"), "bytes");
-            fs.mkdirSync(path.join(dir, "dist"));
-            fs.writeFileSync(path.join(dir, "dist", "index.js"), "built");
-            fs.mkdirSync(path.join(dir, "node_modules", "x"), { recursive: true });
-            fs.writeFileSync(path.join(dir, "node_modules", "x", "i.js"), "dep");
-            fs.writeFileSync(path.join(dir, "tsconfig.tsbuildinfo"), "{}");
-            stagePackageSource(dir, stage);
-            expect(fs.existsSync(path.join(stage, "src", "main.tsx"))).toBe(true);
-            expect(fs.existsSync(path.join(stage, "templates", "dist", "quote.xlsx"))).toBe(true);
-            expect(fs.existsSync(path.join(stage, "dist"))).toBe(false);
-            expect(fs.existsSync(path.join(stage, "node_modules"))).toBe(false);
-            expect(fs.existsSync(path.join(stage, "tsconfig.tsbuildinfo"))).toBe(false);
-            // The staged package.json is the sanitized one — dev pins stripped.
-            const staged = JSON.parse(fs.readFileSync(path.join(stage, "package.json"), "utf-8"));
-            expect(staged.lotics.package.dev).toBeUndefined();
-            expect(staged.lotics.package.id).toBe("apg_x");
-        }
-        finally {
-            fs.rmSync(dir, { recursive: true, force: true });
-            fs.rmSync(stage, { recursive: true, force: true });
-        }
-    });
-});