@kuznai/inception-engine 0.18.0 → 0.20.0

package/dist/test/unit/preflight.test.js

@@ -0,0 +1,501 @@
+import assert from "node:assert/strict";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { describe, it } from "node:test";
+import { runPreflight } from "../../src/core/preflight.js";
+import { logger } from "../../src/logger.js";
+import { makeTmpDir } from "../helpers/fs.js";
+import { normalizeSlashes } from "../helpers/path.js";
+logger.silence();
+const baseOptions = {
+    command: "deploy",
+    directory: "/tmp",
+    dryRun: false,
+    agents: null,
+    verbose: false,
+    debug: false,
+    force: false,
+};
+const emptyManifest = {
+    skills: [],
+    files: [],
+    configs: [],
+    mcpServers: [],
+    agentRules: [],
+    permissions: [],
+    agentDefinitions: [],
+};
+describe("runPreflight", () => {
+    it("returns empty for empty detected agents list", async () => {
+        const warnings = await runPreflight(baseOptions, emptyManifest, "/home/test", []);
+        assert.equal(warnings.length, 0);
+    });
+    it("returns empty for documented agents without policy notes", async () => {
+        const warnings = await runPreflight(baseOptions, emptyManifest, "/home/test", ["claude-code", "codex", "gemini-cli", "opencode"]);
+        assert.equal(warnings.length, 0);
+    });
+    it("returns empty for standard github-copilot without enterprise markers", async () => {
+        const warnings = await runPreflight(baseOptions, emptyManifest, "/home/test", ["github-copilot"]);
+        assert.equal(warnings.length, 0);
+    });
+    it("emits config-authority warning for antigravity (implementation-only skills)", async () => {
+        const warnings = await runPreflight(baseOptions, emptyManifest, "/home/test", ["antigravity"]);
+        assert.equal(warnings.length, 1);
+        assert.equal(warnings[0]?.kind, "config-authority");
+        assert.match(warnings[0]?.message ?? "", /antigravity/);
+        assert.match(warnings[0]?.message ?? "", /implementation-only/);
+    });
+    it("emits one warning per non-documented agent", async () => {
+        const warnings = await runPreflight(baseOptions, emptyManifest, "/home/test", ["claude-code", "antigravity"]);
+        assert.equal(warnings.length, 1);
+        assert.equal(warnings[0]?.kind, "config-authority");
+        assert.match(warnings[0]?.message ?? "", /antigravity/);
+    });
+    it("emits shared-surface guidance when a skill targets github-copilot without claude-code", async () => {
+        const manifest = {
+            ...emptyManifest,
+            skills: [
+                {
+                    name: "my-skill",
+                    path: "skills/my-skill",
+                    agents: ["github-copilot"],
+                },
+            ],
+        };
+        const warnings = await runPreflight(baseOptions, manifest, "/home/test", [
+            "github-copilot",
+        ]);
+        const info = warnings.find((w) => w.kind === "info");
+        assert.ok(info, "expected a shared-surface info warning");
+        assert.match(info?.message ?? "", /via "claude-code"/);
+    });
+    it("emits unsupported warning when manifest uses github-copilot MCP with global scope", async () => {
+        const manifest = {
+            ...emptyManifest,
+            mcpServers: [
+                {
+                    name: "my-mcp",
+                    agents: ["github-copilot"],
+                    config: { command: "npx", args: ["-y", "my-mcp"] },
+                    scope: "global",
+                },
+            ],
+        };
+        const warnings = await runPreflight(baseOptions, manifest, "/home/test", [
+            "github-copilot",
+        ]);
+        const info = warnings.find((w) => w.kind === "info");
+        assert.ok(info, "expected an unsupported-surface info warning");
+        assert.match(info?.message ?? "", /unsupported/);
+    });
+    it("emits no capability warning when manifest uses github-copilot MCP with scope: repo", async () => {
+        const manifest = {
+            ...emptyManifest,
+            mcpServers: [
+                {
+                    name: "my-mcp",
+                    agents: ["github-copilot"],
+                    config: { command: "npx", args: ["-y", "my-mcp"] },
+                    scope: "repo",
+                },
+            ],
+        };
+        const warnings = await runPreflight(baseOptions, manifest, "/home/test", [
+            "github-copilot",
+        ]);
+        const capabilityWarning = warnings.find((w) => w.kind === "info" && /mcpServers/.test(w.message));
+        assert.equal(capabilityWarning, undefined, `expected no MCP capability warning, got: ${capabilityWarning?.message}`);
+    });
+    it("emits no config-authority warning for gemini-cli agentDefinitions (surface is now documented)", async () => {
+        const manifest = {
+            ...emptyManifest,
+            agentDefinitions: [
+                {
+                    name: "my-agent",
+                    path: "agents/my-agent.md",
+                    agents: ["gemini-cli"],
+                    scope: "repo",
+                },
+            ],
+        };
+        const warnings = await runPreflight(baseOptions, manifest, "/home/test", [
+            "gemini-cli",
+        ]);
+        const implementationOnlyWarning = warnings.find((w) => w.kind === "config-authority" && /implementation-only/.test(w.message));
+        assert.equal(implementationOnlyWarning, undefined, `expected no implementation-only warning, got: ${implementationOnlyWarning?.message}`);
+    });
+});
+describe("instruction precedence warnings", () => {
+    it("emits duplicate-content precedence warning when same source used in both global and repo scope for an agent", async () => {
+        const sourceDir = await makeTmpDir();
+        try {
+            await writeFile(path.join(sourceDir, "CLAUDE.md"), "# Rules");
+            const manifest = {
+                ...emptyManifest,
+                agentRules: [
+                    {
+                        name: "global-rules",
+                        path: "CLAUDE.md",
+                        agents: ["claude-code"],
+                        scope: "global",
+                    },
+                    {
+                        name: "repo-rules",
+                        path: "CLAUDE.md",
+                        agents: ["claude-code"],
+                        scope: "repo",
+                    },
+                ],
+            };
+            const warnings = await runPreflight({ ...baseOptions, directory: sourceDir }, manifest, "/home/test", ["claude-code"]);
+            const precedenceWarnings = warnings.filter((w) => w.kind === "precedence");
+            assert.ok(precedenceWarnings.length > 0, "expected a precedence warning");
+            assert.ok(precedenceWarnings.some((w) => w.message.includes("claude-code") &&
+                w.message.includes("CLAUDE.md")));
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+    it("emits stacking advisory when different source files in global and repo scope for an agent", async () => {
+        const sourceDir = await makeTmpDir();
+        try {
+            await writeFile(path.join(sourceDir, "global.md"), "# Global");
+            await writeFile(path.join(sourceDir, "repo.md"), "# Repo");
+            const manifest = {
+                ...emptyManifest,
+                agentRules: [
+                    {
+                        name: "global-rules",
+                        path: "global.md",
+                        agents: ["claude-code"],
+                        scope: "global",
+                    },
+                    {
+                        name: "repo-rules",
+                        path: "repo.md",
+                        agents: ["claude-code"],
+                        scope: "repo",
+                    },
+                ],
+            };
+            const warnings = await runPreflight({ ...baseOptions, directory: sourceDir }, manifest, "/home/test", ["claude-code"]);
+            const precedenceWarnings = warnings.filter((w) => w.kind === "precedence");
+            assert.ok(precedenceWarnings.length > 0, "expected a precedence warning");
+            assert.ok(precedenceWarnings.some((w) => w.message.includes("claude-code") &&
+                w.message.includes("simultaneously")));
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+    it("emits no precedence warning when agent only has global entries", async () => {
+        const sourceDir = await makeTmpDir();
+        try {
+            await writeFile(path.join(sourceDir, "CLAUDE.md"), "# Rules");
+            const manifest = {
+                ...emptyManifest,
+                agentRules: [
+                    {
+                        name: "global-rules",
+                        path: "CLAUDE.md",
+                        agents: ["claude-code"],
+                        scope: "global",
+                    },
+                ],
+            };
+            const warnings = await runPreflight({ ...baseOptions, directory: sourceDir }, manifest, "/home/test", ["claude-code"]);
+            assert.equal(warnings.filter((w) => w.kind === "precedence").length, 0);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+    it("emits no precedence warning when agent only has repo entries", async () => {
+        const sourceDir = await makeTmpDir();
+        try {
+            await writeFile(path.join(sourceDir, "CLAUDE.md"), "# Rules");
+            const manifest = {
+                ...emptyManifest,
+                agentRules: [
+                    {
+                        name: "repo-rules",
+                        path: "CLAUDE.md",
+                        agents: ["claude-code"],
+                        scope: "repo",
+                    },
+                ],
+            };
+            const warnings = await runPreflight({ ...baseOptions, directory: sourceDir }, manifest, "/home/test", ["claude-code"]);
+            assert.equal(warnings.filter((w) => w.kind === "precedence").length, 0);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+    it("emits no precedence warning for agents not in detectedAgents", async () => {
+        const sourceDir = await makeTmpDir();
+        try {
+            await writeFile(path.join(sourceDir, "CLAUDE.md"), "# Rules");
+            const manifest = {
+                ...emptyManifest,
+                agentRules: [
+                    {
+                        name: "global-rules",
+                        path: "CLAUDE.md",
+                        agents: ["claude-code"],
+                        scope: "global",
+                    },
+                    {
+                        name: "repo-rules",
+                        path: "CLAUDE.md",
+                        agents: ["claude-code"],
+                        scope: "repo",
+                    },
+                ],
+            };
+            const warnings = await runPreflight({ ...baseOptions, directory: sourceDir }, manifest, "/home/test", ["codex"]);
+            assert.equal(warnings.filter((w) => w.kind === "precedence").length, 0);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+});
+describe("instruction budget warnings", () => {
+    it("emits budget warning for agentRules source file exceeding 50 KB", async () => {
+        const sourceDir = await makeTmpDir();
+        try {
+            await writeFile(path.join(sourceDir, "big.md"), Buffer.alloc(51 * 1024, "x"));
+            const manifest = {
+                ...emptyManifest,
+                agentRules: [
+                    {
+                        name: "big-rules",
+                        path: "big.md",
+                        agents: ["claude-code"],
+                        scope: "global",
+                    },
+                ],
+            };
+            const warnings = await runPreflight({ ...baseOptions, directory: sourceDir }, manifest, "/home/test", ["claude-code"]);
+            const budgetWarnings = warnings.filter((w) => w.kind === "budget");
+            assert.ok(budgetWarnings.length > 0, "expected a budget warning");
+            assert.ok(budgetWarnings.some((w) => w.message.includes("big.md") && w.message.includes("KB")));
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+    it("emits budget warning for agentDefinitions source file exceeding 50 KB", async () => {
+        const sourceDir = await makeTmpDir();
+        try {
+            await mkdir(path.join(sourceDir, "agents"), { recursive: true });
+            await writeFile(path.join(sourceDir, "agents", "big-agent.md"), Buffer.alloc(51 * 1024, "x"));
+            const manifest = {
+                ...emptyManifest,
+                agentDefinitions: [
+                    {
+                        name: "big-agent",
+                        path: "agents/big-agent.md",
+                        agents: ["claude-code"],
+                        scope: "repo",
+                    },
+                ],
+            };
+            const warnings = await runPreflight({ ...baseOptions, directory: sourceDir }, manifest, "/home/test", ["claude-code"]);
+            const budgetWarnings = warnings.filter((w) => w.kind === "budget");
+            assert.ok(budgetWarnings.length > 0, "expected a budget warning");
+            assert.ok(budgetWarnings.some((w) => normalizeSlashes(w.message).includes("agents/big-agent.md")));
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+    it("emits no budget warning for files at or below 50 KB", async () => {
+        const sourceDir = await makeTmpDir();
+        try {
+            await writeFile(path.join(sourceDir, "small.md"), Buffer.alloc(49 * 1024, "x"));
+            const manifest = {
+                ...emptyManifest,
+                agentRules: [
+                    {
+                        name: "small-rules",
+                        path: "small.md",
+                        agents: ["claude-code"],
+                        scope: "global",
+                    },
+                ],
+            };
+            const warnings = await runPreflight({ ...baseOptions, directory: sourceDir }, manifest, "/home/test", ["claude-code"]);
+            assert.equal(warnings.filter((w) => w.kind === "budget").length, 0);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+    it("emits no budget warning when entry's agents are not in detectedAgents", async () => {
+        const sourceDir = await makeTmpDir();
+        try {
+            await writeFile(path.join(sourceDir, "big.md"), Buffer.alloc(51 * 1024, "x"));
+            const manifest = {
+                ...emptyManifest,
+                agentRules: [
+                    {
+                        name: "big-rules",
+                        path: "big.md",
+                        agents: ["codex"],
+                        scope: "global",
+                    },
+                ],
+            };
+            const warnings = await runPreflight({ ...baseOptions, directory: sourceDir }, manifest, "/home/test", ["claude-code"]);
+            assert.equal(warnings.filter((w) => w.kind === "budget").length, 0);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+    it("deduplicates budget warnings when the same source path appears in two entries", async () => {
+        const sourceDir = await makeTmpDir();
+        try {
+            await writeFile(path.join(sourceDir, "big.md"), Buffer.alloc(51 * 1024, "x"));
+            const manifest = {
+                ...emptyManifest,
+                agentRules: [
+                    {
+                        name: "rules-a",
+                        path: "big.md",
+                        agents: ["claude-code"],
+                        scope: "global",
+                    },
+                    {
+                        name: "rules-b",
+                        path: "big.md",
+                        agents: ["claude-code"],
+                        scope: "global",
+                    },
+                ],
+            };
+            const warnings = await runPreflight({ ...baseOptions, directory: sourceDir }, manifest, "/home/test", ["claude-code"]);
+            assert.equal(warnings.filter((w) => w.kind === "budget").length, 1);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+    it("silently skips missing source files without emitting a budget warning", async () => {
+        const sourceDir = await makeTmpDir();
+        try {
+            const manifest = {
+                ...emptyManifest,
+                agentRules: [
+                    {
+                        name: "missing-rules",
+                        path: "does-not-exist.md",
+                        agents: ["claude-code"],
+                        scope: "global",
+                    },
+                ],
+            };
+            const warnings = await runPreflight({ ...baseOptions, directory: sourceDir }, manifest, "/home/test", ["claude-code"]);
+            assert.equal(warnings.filter((w) => w.kind === "budget").length, 0);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+    it("emits precedence warnings for triple overlap (global, repo, workspace) for an agent", async () => {
+        const sourceDir = await makeTmpDir();
+        try {
+            const manifest = {
+                ...emptyManifest,
+                agentRules: [
+                    { name: "g", path: "g.md", agents: ["claude-code"], scope: "global" },
+                    { name: "r", path: "r.md", agents: ["claude-code"], scope: "repo" },
+                    {
+                        name: "w",
+                        path: "w.md",
+                        agents: ["claude-code"],
+                        scope: "workspace",
+                    },
+                ],
+            };
+            await writeFile(path.join(sourceDir, "g.md"), "# G");
+            await writeFile(path.join(sourceDir, "r.md"), "# R");
+            await writeFile(path.join(sourceDir, "w.md"), "# W");
+            const warnings = await runPreflight(baseOptions, manifest, "/home/test", [
+                "claude-code",
+            ]);
+            const precedence = warnings.filter((w) => w.kind === "precedence");
+            assert.equal(precedence.length, 1);
+            const msg = precedence[0]?.message ?? "";
+            assert.match(msg, /global/);
+            assert.match(msg, /repo/);
+            assert.match(msg, /workspace/);
+            assert.match(msg, /active simultaneously/);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+    it("emits duplicate-content warning for workspace overlap (global vs workspace)", async () => {
+        const sourceDir = await makeTmpDir();
+        try {
+            const manifest = {
+                ...emptyManifest,
+                agentRules: [
+                    {
+                        name: "global",
+                        path: "SHARED.md",
+                        agents: ["claude-code"],
+                        scope: "global",
+                    },
+                    {
+                        name: "workspace",
+                        path: "SHARED.md",
+                        agents: ["claude-code"],
+                        scope: "workspace",
+                    },
+                ],
+            };
+            await writeFile(path.join(sourceDir, "SHARED.md"), "# Shared");
+            const warnings = await runPreflight(baseOptions, manifest, "/home/test", [
+                "claude-code",
+            ]);
+            const duplicate = warnings.find((w) => w.kind === "precedence" && w.message.includes("distinct targets"));
+            assert.ok(duplicate, "expected duplicate target warning");
+            assert.match(duplicate.message, /global and workspace/);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+    it("detects precedence overlaps for Gemini CLI combinations", async () => {
+        const sourceDir = await makeTmpDir();
+        try {
+            const manifest = {
+                skills: [],
+                files: [],
+                configs: [],
+                mcpServers: [],
+                agentRules: [
+                    { name: "g", path: "r1.md", agents: ["gemini-cli"], scope: "global" },
+                    { name: "r", path: "r1.md", agents: ["gemini-cli"], scope: "repo" },
+                ],
+                permissions: [],
+                agentDefinitions: [],
+            };
+            await writeFile(path.join(sourceDir, "r1.md"), "# R1");
+            const warnings = await runPreflight(baseOptions, manifest, "/home/test", [
+                "gemini-cli",
+            ]);
+            const precedence = warnings.filter((w) => w.kind === "precedence");
+            // Expect 2: one for duplicate path, one for simultaneous load
+            assert.equal(precedence.length, 2);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+});

package/dist/test/unit/resolve.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/unit/resolve.test.js

@@ -0,0 +1,119 @@
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { describe, it } from "node:test";
+import { AGENT_REGISTRY } from "../../src/config/agents.js";
+import { resolveAgentDetectPath, resolveAgentSkillPath, resolveHome, } from "../../src/core/resolve.js";
+import { resolveTargetTemplate } from "../../src/core/runtime-paths.js";
+import { UserError } from "../../src/errors.js";
+const posixJoin = path.posix.join;
+function getAgent(id) {
+    const agent = AGENT_REGISTRY.find((a) => a.id === id);
+    assert.ok(agent, `agent "${id}" not found in AGENT_REGISTRY`);
+    return agent;
+}
+describe("resolveAgentSkillPath", () => {
+    it("resolves Claude Code skill path", () => {
+        const claude = getAgent("claude-code");
+        const result = resolveAgentSkillPath(claude, "my-skill", "/Users/test");
+        assert.equal(result, posixJoin("/Users/test", ".claude", "skills", "my-skill"));
+    });
+    it("resolves OpenCode skill path with home", () => {
+        const opencode = getAgent("opencode");
+        const result = resolveAgentSkillPath(opencode, "test-skill", "/home/user");
+        // On non-Windows the posix template is used; cross-platform template tests live in cross-platform.test.ts
+        assert.ok(result.includes("opencode") && result.includes("test-skill"));
+    });
+    it("resolves Antigravity nested path", () => {
+        const antigravity = getAgent("antigravity");
+        const result = resolveAgentSkillPath(antigravity, "my-skill", "/home/user");
+        assert.equal(result, posixJoin("/home/user", ".gemini", "antigravity", "skills", "my-skill"));
+    });
+    it("throws with a shared-via hint for github-copilot (no skills field)", () => {
+        const copilot = getAgent("github-copilot");
+        assert.throws(() => resolveAgentSkillPath(copilot, "my-skill", "/home/user"), (err) => {
+            assert.ok(err.message.includes("claude-code"), `expected hint referencing claude-code, got: ${err.message}`);
+            return true;
+        });
+    });
+});
+describe("resolveAgentDetectPath", () => {
+    it("resolves detect path for each agent", () => {
+        for (const agent of AGENT_REGISTRY) {
+            const result = resolveAgentDetectPath(agent, "/home/user");
+            assert.ok(path.isAbsolute(result), `expected absolute path, got: ${result}`);
+            assert.ok(!result.includes("{home}"));
+            assert.ok(!result.includes("{name}"));
+        }
+    });
+});
+describe("resolveHome", () => {
+    it("returns os.homedir() when SUDO_USER is not set", () => {
+        const saved = process.env.SUDO_USER;
+        try {
+            delete process.env.SUDO_USER;
+            assert.equal(resolveHome(), os.homedir());
+        }
+        finally {
+            if (saved === undefined) {
+                delete process.env.SUDO_USER;
+            }
+            else {
+                process.env.SUDO_USER = saved;
+            }
+        }
+    });
+    it("ignores SUDO_USER when not running as root and returns os.homedir()", {
+        skip: process.getuid?.() === 0,
+    }, () => {
+        const currentUser = process.env.USER ?? os.userInfo().username;
+        if (!currentUser)
+            return;
+        const saved = process.env.SUDO_USER;
+        try {
+            process.env.SUDO_USER = currentUser;
+            const result = resolveHome();
+            assert.equal(result, os.homedir());
+        }
+        finally {
+            if (saved === undefined) {
+                delete process.env.SUDO_USER;
+            }
+            else {
+                process.env.SUDO_USER = saved;
+            }
+        }
+    });
+    it("throws UserError when SUDO_USER is a non-existent user (only when running as root)", {
+        skip: process.getuid?.() !== 0,
+    }, () => {
+        const saved = process.env.SUDO_USER;
+        try {
+            process.env.SUDO_USER = "__nonexistent_user_inception_engine_test__";
+            assert.throws(() => resolveHome(), (err) => {
+                assert.ok(err instanceof UserError);
+                assert.equal(err.code, "RESOLVE_FAILED");
+                assert.match(err.message, /Cannot determine home directory/);
+                return true;
+            });
+        }
+        finally {
+            if (saved === undefined) {
+                delete process.env.SUDO_USER;
+            }
+            else {
+                process.env.SUDO_USER = saved;
+            }
+        }
+    });
+});
+describe("resolveTargetTemplate", () => {
+    it("resolves a descendant path under the placeholder root", () => {
+        const home = path.join(path.sep, "home", "user");
+        const result = resolveTargetTemplate("{home}/.claude/settings.json", home);
+        assert.equal(result, `${home}/.claude/settings.json`);
+    });
+    it("throws when the template escapes the placeholder root", () => {
+        assert.throws(() => resolveTargetTemplate("{home}/../.ssh/config", "/home/user"), /outside its placeholder root/);
+    });
+});

package/dist/test/unit/revert.test.d.ts

@@ -0,0 +1 @@
+export {};