@lotics/cli 0.76.0 → 0.76.1

package/dist/package_commands.test.js

@@ -2,19 +2,21 @@ import { describe, it, expect } from "vitest";
 import fs from "node:fs";
 import path from "node:path";
 import { tmpdir } from "node:os";
-import { parseAppPackageContract, validateAppPackageContract, } from "@lotics/shared/schemas/app_packages";
-import { starterContract, readPackageProject, writePackageManifest, sanitizePackageJsonForSource, stagePackageSource, parseResolveFlags, assertDevWorkspace, draftPackageProjectFromApp, parseAdoptBindingFile, formatExtractReport, } from "./package_commands.js";
+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 { 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 = parseAppPackageContract(raw);
+        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(validateAppPackageContract(contract)).toEqual([]);
+        expect(validatePackageContract(contract)).toEqual([]);
     });
     it("uses the package name as the entity label", () => {
-        const contract = parseAppPackageContract(starterContract("Widgets"));
+        const contract = parsePackageContract(starterContract("Widgets"));
         expect(contract.entities[0].label).toBe("Widgets");
         expect(contract.config[0].default).toBe("Widgets");
     });
@@ -39,7 +41,11 @@ describe("package manifest round-trip", () => {
                 id: null,
                 name: "Acme CRM",
                 description: null,
+                kind: "app",
                 version: null,
+                knowledge: {},
+                templates: {},
+                knowledge_expects: [],
                 dev: {},
             });
         }
@@ -120,6 +126,217 @@ describe("sanitizePackageJsonForSource", () => {
         expect(input.lotics.package.dev).toEqual({ wsp_dev: { app_id: "a", version: 1 } });
     });
 });
+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" });
+        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 },
+            });
+            // 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>" });
+        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();
@@ -160,6 +377,124 @@ 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" },
+        });
+    });
+    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("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/);
+    });
+});
+describe("parseBindToFlags", () => {
+    it("maps each alias to its consent doc id", () => {
+        expect(parseBindToFlags(["playbook=kdc_1", "faq=kdc_2"])).toEqual({
+            playbook: "kdc_1",
+            faq: "kdc_2",
+        });
+    });
+    it("rejects entries without an alias=id shape", () => {
+        expect(() => parseBindToFlags(["playbook"])).toThrow(/Invalid --bind-to/);
+        expect(() => parseBindToFlags(["=kdc_1"])).toThrow(/Invalid --bind-to/);
+        expect(() => parseBindToFlags(["playbook="])).toThrow(/Invalid --bind-to/);
+    });
+});
+describe("parseArgs — content package flags", () => {
+    it("captures --kind, --bind-to (repeatable), --keep-content, --apply-all", () => {
+        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",
+        ]);
+        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");
+    });
+    it("throws when --bind-to has no value", () => {
+        expect(() => parseArgs(["package", "install", "apg_1", "--bind-to"])).toThrow(/--bind-to/);
+    });
+});
+describe("parseArgs — package list-content", () => {
+    it("parses the list-content subcommand with no positional", () => {
+        const { command, subcommand, toolArgs } = parseArgs(["package", "list-content"]);
+        expect(command).toBe("package");
+        expect(subcommand).toBe("list-content");
+        expect(toolArgs).toBeUndefined();
+    });
+    it("captures --workspace for a scoped list-content", () => {
+        const { subcommand, flags } = parseArgs([
+            "package",
+            "list-content",
+            "--workspace",
+            "wsp_dev",
+        ]);
+        expect(subcommand).toBe("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({
@@ -180,7 +515,11 @@ describe("draftPackageProjectFromApp", () => {
             id: null,
             name: "Acme CRM",
             description: null,
+            kind: "app",
             version: null,
+            knowledge: {},
+            templates: {},
+            knowledge_expects: [],
             dev: {},
         });
         // …and non-lotics fields survive verbatim.
@@ -198,7 +537,11 @@ describe("draftPackageProjectFromApp", () => {
                 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.
@@ -227,6 +570,12 @@ describe("parseAdoptBindingFile", () => {
         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/);