@kuznai/inception-engine 0.23.0 → 0.24.0

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

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

package/dist/test/unit/formatters.test.js

@@ -0,0 +1,74 @@
+import assert from "node:assert/strict";
+import { stripVTControlCharacters } from "node:util";
+import { describe, it } from "node:test";
+import { formatDryRunPlan } from "../../src/formatters.js";
+function stripAnsi(value) {
+    return stripVTControlCharacters(value);
+}
+describe("formatDryRunPlan", () => {
+    it("returns an empty string when there are no planned changes", () => {
+        assert.equal(formatDryRunPlan([]), "");
+    });
+    it("groups changes by agent, sorts groups, and renders supported detail fields", () => {
+        const plan = [
+            {
+                agent: "opencode",
+                kind: "config-patch",
+                skill: "beta",
+                target: "/targets/opencode.json",
+                verb: "patch-config",
+                patch: { enabled: true },
+            },
+            {
+                agent: "claude-code",
+                kind: "file-write",
+                skill: "alpha",
+                source: "/source/alpha.md",
+                target: "/targets/alpha.md",
+                verb: "write-file",
+            },
+            {
+                agent: "claude-code",
+                kind: "config-patch",
+                skill: "gamma",
+                target: "/targets/gamma.json",
+                verb: "unapply-patch",
+                patch: { enabled: null },
+            },
+            {
+                agent: "claude-code",
+                kind: "toml-patch",
+                skill: "delta",
+                target: "/targets/delta.toml",
+                verb: "patch-toml",
+                patch: { approval_policy: "suggest" },
+            },
+            {
+                agent: "claude-code",
+                kind: "frontmatter-emit",
+                skill: "epsilon",
+                target: "/targets/epsilon.md",
+                verb: "emit-frontmatter",
+                frontmatter: { tools: ["github"] },
+            },
+            {
+                agent: "claude-code",
+                kind: "file-write",
+                skill: "zeta",
+                target: "/targets/zeta.md",
+                verb: "remove",
+            },
+        ];
+        const output = stripAnsi(formatDryRunPlan(plan));
+        assert.match(output, /^claude-code\n(?:[\s\S]*?)\nopencode\n/m, `expected claude-code group before opencode, got:\n${output}`);
+        assert.match(output, /write-file alpha/);
+        assert.match(output, /source: \/source\/alpha\.md/);
+        assert.match(output, /target: \/targets\/alpha\.md/);
+        assert.match(output, /undo:\s+\{"enabled":null\}/);
+        assert.match(output, /patch:\s+\{"approval_policy":"suggest"\}/);
+        assert.match(output, /frontmatter: \{"tools":\["github"\]\}/);
+        assert.match(output, /remove zeta/);
+        assert.doesNotMatch(output, /source: \/targets\/zeta\.md/);
+        assert.match(output, /patch-config beta/);
+    });
+});

package/dist/test/unit/ownership.test.js

@@ -1,8 +1,8 @@
 import assert from "node:assert/strict";
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { describe, it } from "node:test";
-import { defaultRegistryPersistence, lookupDeployment, registerDeployment, registryPath, unregisterDeployment, verifyDeployment, } from "../../src/core/ownership.js";
+import { defaultRegistryPersistence, lookupDeployment, registerDeployment, registryDirPath, registryPath, unregisterDeployment, verifyDeployment, } from "../../src/core/ownership.js";
 import { exists, makeTmpDir } from "../helpers/fs.js";
 describe("registerDeployment", () => {
     it("creates registry file and adds entry", async () => {
@@ -56,7 +56,7 @@ describe("registerDeployment", () => {
             await rm(home, { recursive: true });
         }
     });
-    it("sets registry file permissions to 0o644 on POSIX", {
+    it("sets registry file permissions to 0o600 on POSIX", {
         skip: process.platform === "win32",
     }, async () => {
         const home = await makeTmpDir();
@@ -70,7 +70,27 @@ describe("registerDeployment", () => {
             });
             const { stat } = await import("node:fs/promises");
             const statResult = await stat(registryPath(home));
-            assert.equal(statResult.mode & 0o777, 0o644);
+            assert.equal(statResult.mode & 0o777, 0o600);
+        }
+        finally {
+            await rm(home, { recursive: true });
+        }
+    });
+    it("sets registry directory permissions to 0o700 on POSIX", {
+        skip: process.platform === "win32",
+    }, async () => {
+        const home = await makeTmpDir();
+        try {
+            await registerDeployment(home, "/fake/target", {
+                kind: "skill-dir",
+                source: "/fake/source",
+                skill: "my-skill",
+                agent: "claude-code",
+                method: "symlink",
+            });
+            const { stat } = await import("node:fs/promises");
+            const statResult = await stat(registryDirPath(home));
+            assert.equal(statResult.mode & 0o777, 0o700);
         }
         finally {
             await rm(home, { recursive: true });
@@ -121,6 +141,26 @@ describe("registerDeployment", () => {
             await rm(home, { recursive: true, force: true });
         }
     });
+    it("refuses to write the registry through a symlinked state directory", {
+        skip: process.platform === "win32",
+    }, async () => {
+        const home = await makeTmpDir();
+        const elsewhere = await makeTmpDir();
+        try {
+            await symlink(elsewhere, registryDirPath(home), "dir");
+            await assert.rejects(registerDeployment(home, "/fake/target", {
+                kind: "skill-dir",
+                source: "/fake/source",
+                skill: "my-skill",
+                agent: "claude-code",
+                method: "copy",
+            }), /Refusing to use registry directory symlink/);
+        }
+        finally {
+            await rm(home, { recursive: true, force: true });
+            await rm(elsewhere, { recursive: true, force: true });
+        }
+    });
 });
 describe("unregisterDeployment", () => {
     it("removes the entry for the given target", async () => {
@@ -219,6 +259,23 @@ describe("lookupDeployment", () => {
             await rm(home, { recursive: true });
         }
     });
+    it("returns null when the registry file path is a symlink", {
+        skip: process.platform === "win32",
+    }, async () => {
+        const home = await makeTmpDir();
+        const elsewhere = await makeTmpDir();
+        try {
+            await mkdir(registryDirPath(home), { recursive: true });
+            await writeFile(path.join(elsewhere, "registry.json"), "{}");
+            await symlink(path.join(elsewhere, "registry.json"), registryPath(home), "file");
+            const entry = await lookupDeployment(home, "/anything");
+            assert.equal(entry, null);
+        }
+        finally {
+            await rm(home, { recursive: true, force: true });
+            await rm(elsewhere, { recursive: true, force: true });
+        }
+    });
 });
 describe("verifyDeployment", () => {
     it("returns entry when all fields match", async () => {

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

@@ -124,6 +124,65 @@ describe("runPreflight", () => {
         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}`);
     });
+    it("emits shared-surface config-authority guidance when github-copilot agentRules ride through claude-code", async () => {
+        const manifest = {
+            ...emptyManifest,
+            agentRules: [
+                {
+                    name: "shared-rules",
+                    path: "CLAUDE.md",
+                    agents: ["claude-code", "github-copilot"],
+                    scope: "repo",
+                },
+            ],
+        };
+        const warnings = await runPreflight(baseOptions, manifest, "/home/test", [
+            "claude-code",
+            "github-copilot",
+        ]);
+        const warning = warnings.find((w) => w.kind === "config-authority" &&
+            w.message.includes('shared through "claude-code"'));
+        assert.ok(warning, `expected shared-surface warning, got: ${JSON.stringify(warnings)}`);
+        assert.match(warning.message, /requires the primary target to deploy/);
+    });
+    it("emits shared-surface config-authority guidance for antigravity repo rules", async () => {
+        const manifest = {
+            ...emptyManifest,
+            agentRules: [
+                {
+                    name: "gemini-rules",
+                    path: "GEMINI.md",
+                    agents: ["antigravity"],
+                    scope: "repo",
+                },
+            ],
+        };
+        const warnings = await runPreflight(baseOptions, manifest, "/home/test", [
+            "antigravity",
+        ]);
+        const warning = warnings.find((w) => w.kind === "config-authority" &&
+            w.message.includes('shared through "gemini-cli"'));
+        assert.ok(warning, `expected antigravity shared-via warning, got: ${JSON.stringify(warnings)}`);
+        assert.doesNotMatch(warning.message, /requires the primary target to deploy/);
+    });
+    it("emits provisional config-authority warning for supported gemini executionConfigs", async () => {
+        const manifest = {
+            ...emptyManifest,
+            executionConfigs: [
+                {
+                    name: "safe-mode",
+                    agents: ["gemini-cli"],
+                    config: { sandbox: "workspace-write" },
+                },
+            ],
+        };
+        const warnings = await runPreflight(baseOptions, manifest, "/home/test", [
+            "gemini-cli",
+        ]);
+        const capabilityWarning = warnings.find((w) => w.kind === "config-authority" && /execution-config/.test(w.message));
+        assert.ok(capabilityWarning, `expected executionConfig warning, got: ${JSON.stringify(warnings)}`);
+        assert.match(capabilityWarning.message, /provisional/);
+    });
 });
 describe("github-copilot devcontainer support", () => {
     it("emits no capability warning for devcontainer MCP when Copilot is detected and devcontainer scope is targeted", async () => {

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

@@ -4,7 +4,7 @@ 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 { resolveRuntimePaths, resolveTargetTemplate, } from "../../src/core/runtime-paths.js";
 import { UserError } from "../../src/errors.js";
 const posixJoin = path.posix.join;
 function getAgent(id) {
@@ -113,7 +113,73 @@ describe("resolveTargetTemplate", () => {
         const result = resolveTargetTemplate("{home}/.claude/settings.json", home);
         assert.equal(result, `${home}/.claude/settings.json`);
     });
+    it("resolves appdata, local_appdata, xdg_config, repo, and workspace roots", () => {
+        const savedAppData = process.env.APPDATA;
+        const savedLocalAppData = process.env.LOCALAPPDATA;
+        const savedXdg = process.env.XDG_CONFIG_HOME;
+        try {
+            process.env.APPDATA = "/env/appdata";
+            process.env.LOCALAPPDATA = "/env/local";
+            process.env.XDG_CONFIG_HOME = "/env/xdg";
+            assert.equal(resolveTargetTemplate("{appdata}/opencode/opencode.json", "/home/user"), "/env/appdata/opencode/opencode.json");
+            assert.equal(resolveTargetTemplate("{local_appdata}/Temp/config.json", "/home/user"), "/env/local/Temp/config.json");
+            assert.equal(resolveTargetTemplate("{xdg_config}/opencode/config.json", "/home/user"), "/env/xdg/opencode/config.json");
+            assert.equal(resolveTargetTemplate("{repo}/.claude/mcp.json", "/home/user", "/repo"), "/repo/.claude/mcp.json");
+            assert.equal(resolveTargetTemplate("{workspace}/CLAUDE.md", "/home/user", "/repo"), "/repo/CLAUDE.md");
+            assert.equal(resolveTargetTemplate("{workspace}/CLAUDE.md", "/home/user", "/repo", "/workspace"), "/workspace/CLAUDE.md");
+            assert.equal(resolveTargetTemplate("{home}", "/home/user"), "/home/user");
+        }
+        finally {
+            if (savedAppData === undefined)
+                delete process.env.APPDATA;
+            else
+                process.env.APPDATA = savedAppData;
+            if (savedLocalAppData === undefined)
+                delete process.env.LOCALAPPDATA;
+            else
+                process.env.LOCALAPPDATA = savedLocalAppData;
+            if (savedXdg === undefined)
+                delete process.env.XDG_CONFIG_HOME;
+            else
+                process.env.XDG_CONFIG_HOME = savedXdg;
+        }
+    });
+    it("throws for invalid templates and missing repo or workspace roots", () => {
+        assert.throws(() => resolveTargetTemplate("relative/path.txt", "/home/user"), /Invalid target template/);
+        assert.throws(() => resolveTargetTemplate("{repo}/x", "/home/user"), /no repo directory was provided/);
+        assert.throws(() => resolveTargetTemplate("{workspace}/x", "/home/user"), /no workspace directory was provided/);
+    });
     it("throws when the template escapes the placeholder root", () => {
         assert.throws(() => resolveTargetTemplate("{home}/../.ssh/config", "/home/user"), /outside its placeholder root/);
     });
 });
+describe("resolveRuntimePaths", () => {
+    it("uses absolute env vars and ignores relative overrides", () => {
+        const savedAppData = process.env.APPDATA;
+        const savedLocalAppData = process.env.LOCALAPPDATA;
+        const savedXdg = process.env.XDG_CONFIG_HOME;
+        try {
+            process.env.APPDATA = "/custom/appdata";
+            process.env.LOCALAPPDATA = "relative/local";
+            process.env.XDG_CONFIG_HOME = "relative/xdg";
+            const paths = resolveRuntimePaths("/home/user");
+            assert.equal(paths.appdata, "/custom/appdata");
+            assert.equal(paths.localAppdata, "/home/user/AppData/Local");
+            assert.equal(paths.xdgConfig, "/home/user/.config");
+        }
+        finally {
+            if (savedAppData === undefined)
+                delete process.env.APPDATA;
+            else
+                process.env.APPDATA = savedAppData;
+            if (savedLocalAppData === undefined)
+                delete process.env.LOCALAPPDATA;
+            else
+                process.env.LOCALAPPDATA = savedLocalAppData;
+            if (savedXdg === undefined)
+                delete process.env.XDG_CONFIG_HOME;
+            else
+                process.env.XDG_CONFIG_HOME = savedXdg;
+        }
+    });
+});

package/dist/test/unit/revert.test.js

@@ -1,5 +1,5 @@
 import assert from "node:assert/strict";
-import { chmod, mkdir, readFile, rm, symlink, writeFile, } from "node:fs/promises";
+import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { describe, it } from "node:test";
 import { lookupDeployment, registerDeployment, } from "../../src/core/ownership.js";
@@ -153,192 +153,28 @@ describe("planRevertAll", () => {
             action.skill === "gemini-safety"), "expected planRevertAll to include Gemini execution config revert action");
     });
 });
-describe("executeRevert", { skip: process.platform === "win32" }, () => {
-    it("removes a symlink registered in the deployment registry", async () => {
+describe("executeRevert reserved state protections", () => {
+    it("refuses to modify inception-engine state paths from manifest-managed actions", async () => {
         const home = await makeTmpDir();
-        const sourceDir = await makeTmpDir();
         try {
-            const actions = planRevert(testManifest, ["claude-code"], home);
-            const target = actions[0]?.target;
-            // Create symlink and register in registry
+            const target = path.join(home, ".inception-engine", "registry.json");
             await mkdir(path.dirname(target), { recursive: true });
-            await symlink(sourceDir, target, "dir");
-            await registerDeployment(home, target, {
-                kind: "skill-dir",
-                source: sourceDir,
-                skill: "test-skill",
-                agent: "claude-code",
-                method: "symlink",
-            });
-            assert.ok(await exists(target));
-            const { succeeded, skipped } = await executeRevert(actions, false, false, home);
-            assert.equal(succeeded, 1);
-            assert.equal(skipped, 0);
-            assert.ok(!(await exists(target)));
-            // Registry entry should be removed
-            const entry = await lookupDeployment(home, target);
-            assert.equal(entry, null);
-        }
-        finally {
-            await rm(home, { recursive: true, force: true });
-            await rm(sourceDir, { recursive: true });
-        }
-    });
-    it("removes a copied directory registered in the deployment registry", async () => {
-        const home = await makeTmpDir();
-        try {
-            const actions = planRevert(testManifest, ["claude-code"], home);
-            const target = actions[0]?.target;
-            await mkdir(target, { recursive: true });
-            await writeFile(path.join(target, "SKILL.md"), "test");
-            await registerDeployment(home, target, {
-                kind: "skill-dir",
-                source: "/original/source",
-                skill: "test-skill",
-                agent: "claude-code",
-                method: "copy",
-            });
-            const { succeeded, skipped } = await executeRevert(actions, false, false, home);
-            assert.equal(succeeded, 1);
-            assert.equal(skipped, 0);
-            assert.ok(!(await exists(target)));
-            // Registry entry should be removed
-            const entry = await lookupDeployment(home, target);
-            assert.equal(entry, null);
-        }
-        finally {
-            await rm(home, { recursive: true, force: true });
-        }
-    });
-    it("skips missing targets", async () => {
-        const home = await makeTmpDir();
-        try {
-            const actions = planRevert(testManifest, ["claude-code"], home);
-            const { succeeded, skipped } = await executeRevert(actions, false, false, home);
-            assert.equal(succeeded, 0);
-            assert.equal(skipped, 1);
-        }
-        finally {
-            await rm(home, { recursive: true });
-        }
-    });
-    it("records a failure when removal is blocked by permissions", async () => {
-        const home = await makeTmpDir();
-        const sourceDir = await makeTmpDir();
-        const actions = planRevert(testManifest, ["claude-code"], home);
-        const target = actions[0]?.target ?? "";
-        const targetParent = path.dirname(target);
-        try {
-            // Create the target directory and register it
-            await mkdir(target, { recursive: true });
-            await writeFile(path.join(target, "SKILL.md"), "test");
-            await registerDeployment(home, target, {
-                kind: "skill-dir",
-                source: sourceDir,
-                skill: "test-skill",
-                agent: "claude-code",
-                method: "copy",
-            });
-            // Make the parent directory non-writable so rm() fails
-            await chmod(targetParent, 0o555);
-            const { succeeded, skipped, failed } = await executeRevert(actions, false, false, home);
+            await writeFile(target, "{}");
+            const { failed, succeeded } = await executeRevert([
+                {
+                    kind: "file-write",
+                    skill: "state-target",
+                    agent: "claude-code",
+                    target,
+                },
+            ], false, false, home);
             assert.equal(succeeded, 0);
-            assert.equal(skipped, 0);
             assert.equal(failed.length, 1);
-        }
-        finally {
-            await chmod(targetParent, 0o755);
-            await rm(home, { recursive: true, force: true });
-            await rm(sourceDir, { recursive: true, force: true });
-        }
-    });
-    it("does not remove in dry-run mode", async () => {
-        const home = await makeTmpDir();
-        const sourceDir = await makeTmpDir();
-        try {
-            const actions = planRevert(testManifest, ["claude-code"], home);
-            const target = actions[0]?.target;
-            await mkdir(path.dirname(target), { recursive: true });
-            await symlink(sourceDir, target, "dir");
-            await registerDeployment(home, target, {
-                kind: "skill-dir",
-                source: sourceDir,
-                skill: "test-skill",
-                agent: "claude-code",
-                method: "symlink",
-            });
-            const { succeeded } = await executeRevert(actions, true, false, home);
-            assert.equal(succeeded, 1);
-            assert.ok(await exists(target), "symlink should still exist after dry-run");
-            // Registry entry should still exist after dry-run
-            const entry = await lookupDeployment(home, target);
-            assert.ok(entry, "registry entry should still exist after dry-run");
-        }
-        finally {
-            await rm(home, { recursive: true, force: true });
-            await rm(sourceDir, { recursive: true });
-        }
-    });
-    it("skips target that exists but is not in registry", async () => {
-        const home = await makeTmpDir();
-        const sourceDir = await makeTmpDir();
-        try {
-            const actions = planRevert(testManifest, ["claude-code"], home);
-            const target = actions[0]?.target;
-            // Create symlink but do NOT register — should be treated as unmanaged
-            await writeFile(path.join(sourceDir, "SKILL.md"), "---");
-            await mkdir(path.dirname(target), { recursive: true });
-            await symlink(sourceDir, target, "dir");
-            const { succeeded, skipped } = await executeRevert(actions, false, false, home);
-            assert.equal(succeeded, 0);
-            assert.equal(skipped, 1);
-            assert.ok(await exists(target), "symlink should still exist — not managed");
-        }
-        finally {
-            await rm(home, { recursive: true, force: true });
-            await rm(sourceDir, { recursive: true });
-        }
-    });
-    it("skips directory that exists but is not in registry", async () => {
-        const home = await makeTmpDir();
-        try {
-            const actions = planRevert(testManifest, ["claude-code"], home);
-            const target = actions[0]?.target;
-            await mkdir(target, { recursive: true });
-            await writeFile(path.join(target, "SKILL.md"), "user content");
-            const { succeeded, skipped } = await executeRevert(actions, false, false, home);
-            assert.equal(succeeded, 0);
-            assert.equal(skipped, 1);
-            assert.ok(await exists(target), "directory should still exist — not in registry");
-        }
-        finally {
-            await rm(home, { recursive: true, force: true });
-        }
-    });
-    it("skips target whose registry entry has mismatched skill or agent", async () => {
-        const home = await makeTmpDir();
-        const sourceDir = await makeTmpDir();
-        try {
-            const actions = planRevert(testManifest, ["claude-code"], home);
-            const target = actions[0]?.target;
-            // Create symlink and register under a different skill/agent
-            await mkdir(path.dirname(target), { recursive: true });
-            await symlink(sourceDir, target, "dir");
-            await registerDeployment(home, target, {
-                kind: "skill-dir",
-                source: sourceDir,
-                skill: "different-skill",
-                agent: "codex",
-                method: "symlink",
-            });
-            const { succeeded, skipped } = await executeRevert(actions, false, false, home);
-            assert.equal(succeeded, 0);
-            assert.equal(skipped, 1);
-            assert.ok(await exists(target), "symlink should still exist — registry entry does not match");
+            assert.match(failed[0]?.error ?? "", /Refusing to modify inception-engine state directory/);
+            assert.equal(await readFile(target, "utf-8"), "{}");
         }
         finally {
             await rm(home, { recursive: true, force: true });
-            await rm(sourceDir, { recursive: true });
         }
     });
 });
@@ -905,9 +741,7 @@ describe("planRevertAll — mcpServers and agentRules", () => {
         assert.ok(agents.includes("codex"));
     });
 });
-describe("executeRevert — mcpServer and agentRule integration", {
-    skip: process.platform === "win32",
-}, () => {
+describe("executeRevert — mcpServer and agentRule integration", () => {
     it("reverts a deployed mcpServer config-patch and unregisters it", async () => {
         const home = await makeTmpDir();
         try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",