@kuznai/inception-engine 0.25.0 → 1.0.0

package/dist/test/unit/cli.test.js

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { spawn } from "node:child_process";
-import { mkdir, rm, writeFile } from "node:fs/promises";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { describe, it } from "node:test";
 import { makeTmpDir } from "../helpers/fs.js";
@@ -993,4 +993,60 @@ describe("init command", () => {
             await rm(dir, { recursive: true });
         }
     });
+    it("keeps conventional markdown discovery focused outside discovered skill roots", async () => {
+        const dir = await makeTmpDir();
+        try {
+            await mkdir(path.join(dir, "skills", "alpha"), { recursive: true });
+            await writeFile(path.join(dir, "skills", "alpha", "SKILL.md"), "---\nname: alpha\ndescription: test\n---\n");
+            await writeFile(path.join(dir, "skills", "alpha", "notes.md"), "# direct child in skill\n");
+            await mkdir(path.join(dir, "rules"), { recursive: true });
+            await writeFile(path.join(dir, "rules", "shared.md"), "# shared markdown rule\n");
+            await mkdir(path.join(dir, ".claude", "agents"), { recursive: true });
+            await writeFile(path.join(dir, ".claude", "agents", "reviewer.md"), "---\nname: reviewer\ndescription: test\n---\n# Agent\n");
+            const { code } = await run(["init", dir]);
+            assert.equal(code, 0);
+            const manifest = JSON.parse(await readFile(path.join(dir, "inception.json"), "utf-8"));
+            const discoveredRulePaths = manifest.agentRules.map((entry) => normalizeSlashes(entry.path));
+            assert.ok(!discoveredRulePaths.includes("skills/alpha/notes.md"), "direct markdown child of a skill should be excluded from agentRules");
+            assert.ok(discoveredRulePaths.includes("rules/shared.md"), "supported markdown outside skills should still be scanned");
+            const discoveredDefinitionPaths = manifest.agentDefinitions.map((entry) => normalizeSlashes(entry.path));
+            assert.ok(discoveredDefinitionPaths.includes(".claude/agents/reviewer.md"), "agent definitions outside skills should still be discovered");
+        }
+        finally {
+            await rm(dir, { recursive: true });
+        }
+    });
+    it("keeps skill discovery deterministic and does not descend below discovered skill roots", async () => {
+        const dir = await makeTmpDir();
+        try {
+            for (const skillName of ["charlie", "alpha", "bravo"]) {
+                const skillDir = path.join(dir, "skills", skillName);
+                await mkdir(path.join(skillDir, "deep", "nested"), { recursive: true });
+                await writeFile(path.join(skillDir, "SKILL.md"), `---\nname: ${skillName}\ndescription: test\n---\n`);
+                await writeFile(path.join(skillDir, "deep", "nested", "ignored.md"), "# ignored because it is inside a skill\n");
+                await writeFile(path.join(skillDir, "deep", "nested", "SKILL.md"), "---\nname: ignored\ndescription: nested\n---\n");
+            }
+            await mkdir(path.join(dir, "rules"), { recursive: true });
+            await writeFile(path.join(dir, "rules", "shared.md"), "# shared rule\n");
+            for (let i = 0; i < 24; i++) {
+                const branchDir = path.join(dir, "packages", `pkg-${i}`);
+                await mkdir(path.join(branchDir, "docs"), { recursive: true });
+                await writeFile(path.join(branchDir, "docs", `ignored-${i}.md`), `# package doc ${i}\n`);
+            }
+            await mkdir(path.join(dir, ".claude", "agents"), { recursive: true });
+            await writeFile(path.join(dir, ".claude", "agents", "maintainer.md"), "---\nname: maintainer\ndescription: test\n---\n# Agent\n");
+            const { code } = await run(["init", dir]);
+            assert.equal(code, 0);
+            const manifest = JSON.parse(await readFile(path.join(dir, "inception.json"), "utf-8"));
+            assert.deepEqual(manifest.skills.map((entry) => entry.name), ["alpha", "bravo", "charlie"], "skill ordering should be path-sorted and deterministic");
+            assert.deepEqual(manifest.skills.map((entry) => normalizeSlashes(entry.path)), ["skills/alpha", "skills/bravo", "skills/charlie"]);
+            assert.ok(!manifest.skills.some((entry) => entry.name === "nested"), "nested SKILL.md below a discovered skill should not be treated as a new skill");
+            assert.ok(!manifest.agentRules.some((entry) => normalizeSlashes(entry.path).includes("ignored.md")), "markdown below a discovered skill should be excluded from agentRules");
+            assert.ok(manifest.agentRules.some((entry) => normalizeSlashes(entry.path) === "rules/shared.md"), "documented rule directories should still be scanned for markdown rules");
+            assert.ok(manifest.agentDefinitions.some((entry) => normalizeSlashes(entry.path) === ".claude/agents/maintainer.md"), "agent definitions outside skills should still be discovered");
+        }
+        finally {
+            await rm(dir, { recursive: true });
+        }
+    });
 });

package/dist/test/unit/deploy.test.js

@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import { copyFile, mkdir, readdir, readFile, rename, rm, symlink, writeFile, } from "node:fs/promises";
 import path from "node:path";
 import { describe, it } from "node:test";
+import { setTimeout as delay } from "node:timers/promises";
 import { executeDeploy, planDeploy } from "../../src/core/deploy.js";
 import { lookupDeployment, registerDeployment, } from "../../src/core/ownership.js";
 import { executeRevert, planRevert } from "../../src/core/revert.js";
@@ -955,6 +956,102 @@ describe("planDeploy", () => {
             await rm(sourceDir, { recursive: true });
         }
     });
+    it("runs per-agent structural validation on shared agentDefinitions source (github-copilot missing tools/instructions)", async () => {
+        const sourceDir = await makeTmpDir();
+        // Source missing both `tools` and `instructions` — valid for antigravity,
+        // invalid for github-copilot. The per-agent check must still fire even
+        // though parsing is now shared across agents.
+        const manifest = {
+            skills: [],
+            files: [],
+            configs: [],
+            mcpServers: [],
+            agentRules: [],
+            permissions: [],
+            agentDefinitions: [
+                {
+                    name: "bad-def",
+                    path: "agents/bad.md",
+                    scope: "repo",
+                    agents: ["antigravity", "github-copilot"],
+                },
+            ],
+        };
+        try {
+            await mkdir(path.join(sourceDir, "agents"), { recursive: true });
+            await writeFile(path.join(sourceDir, "agents/bad.md"), "---\nname: bad-def\ndescription: bad\n---\n# body\n");
+            await assert.rejects(() => planDeploy(manifest, sourceDir, ["antigravity", "github-copilot"], "/home/test", "/repo"), (err) => err instanceof UserError &&
+                err.message.includes("github-copilot") &&
+                err.message.includes("tools"), "expected per-agent github-copilot validation to still fire");
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+    it("planning a shared agentDefinitions source succeeds when frontmatter satisfies every targeted agent", async () => {
+        const sourceDir = await makeTmpDir();
+        const manifest = {
+            skills: [],
+            files: [],
+            configs: [],
+            mcpServers: [],
+            agentRules: [],
+            permissions: [],
+            agentDefinitions: [
+                {
+                    name: "shared-def",
+                    path: "agents/shared.md",
+                    scope: "repo",
+                    agents: ["github-copilot", "antigravity"],
+                },
+            ],
+        };
+        try {
+            await mkdir(path.join(sourceDir, "agents"), { recursive: true });
+            await writeFile(path.join(sourceDir, "agents/shared.md"), '---\nname: shared-def\ndescription: shared\ntools: ["Read"]\n---\n# body\n');
+            const { actions } = await planDeploy(manifest, sourceDir, ["github-copilot", "antigravity"], "/home/test", "/repo");
+            const defActions = actions.filter((a) => a.kind === "file-write" && a.skill === "shared-def");
+            // Both agents produce distinct targets — exercises the per-agent
+            // validation loop against a single cached parse result.
+            assert.equal(defActions.length, 2, "expected one file-write action per agent");
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+});
+describe("instruction file parsing helpers", () => {
+    it("parseInstructionDocument reads and parses the source only once per call", async () => {
+        const { parseInstructionDocument } = await import("../../src/core/validation.js");
+        const sourceDir = await makeTmpDir();
+        try {
+            const sourcePath = path.join(sourceDir, "shared.md");
+            await writeFile(sourcePath, "---\nname: shared\ndescription: shared\ntools: []\n---\n# body\n");
+            const parsed = await parseInstructionDocument(sourcePath, "shared.md");
+            assert.equal(parsed.attributes.name, "shared");
+            assert.equal(parsed.attributes.description, "shared");
+            assert.deepEqual(parsed.attributes.tools, []);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+        }
+    });
+    it("validateInstructionAgentRequirements enforces per-agent rules from cached attributes without re-reading", async () => {
+        const { validateInstructionAgentRequirements } = await import("../../src/core/validation.js");
+        // Simulate a cached parse result shared across agents.
+        const attributesMissingTools = {
+            name: "shared",
+            description: "shared",
+        };
+        // antigravity passes (mcp-servers is optional).
+        assert.doesNotThrow(() => validateInstructionAgentRequirements(attributesMissingTools, "shared.md", "antigravity"));
+        // github-copilot fails (requires tools or instructions).
+        assert.throws(() => validateInstructionAgentRequirements(attributesMissingTools, "shared.md", "github-copilot"), (err) => err instanceof UserError &&
+            err.message.includes("github-copilot") &&
+            err.message.includes("tools"));
+        // Agents without instructionFrontmatterRequired are a no-op regardless of attrs.
+        assert.doesNotThrow(() => validateInstructionAgentRequirements({}, "shared.md", "claude-code"));
+    });
 });
 describe("planDeploy path traversal", () => {
     it("throws when skill.path resolves to the repository root itself (.)", async () => {
@@ -1268,6 +1365,110 @@ describe("executeDeploy — file-write", () => {
             await rm(home, { recursive: true, force: true });
         }
     });
+    it("runs independent file-write targets concurrently", async () => {
+        const sourceDir = await makeTmpDir();
+        const home = await makeTmpDir();
+        let inFlight = 0;
+        let maxInFlight = 0;
+        try {
+            const sourceA = path.join(sourceDir, "a.txt");
+            const sourceB = path.join(sourceDir, "b.txt");
+            await writeFile(sourceA, "a");
+            await writeFile(sourceB, "b");
+            const actions = [
+                {
+                    kind: "file-write",
+                    skill: "skill-a",
+                    agent: "claude-code",
+                    source: sourceA,
+                    target: path.join(home, "a.txt"),
+                },
+                {
+                    kind: "file-write",
+                    skill: "skill-b",
+                    agent: "codex",
+                    source: sourceB,
+                    target: path.join(home, "b.txt"),
+                },
+            ];
+            const { succeeded, failed } = await executeDeploy(actions, false, false, home, {
+                fileOps: {
+                    async copyFile(source, target) {
+                        inFlight += 1;
+                        maxInFlight = Math.max(maxInFlight, inFlight);
+                        await delay(25);
+                        await copyFile(source, target);
+                        inFlight -= 1;
+                    },
+                    rename,
+                    rm,
+                    writeFile,
+                },
+            });
+            assert.equal(succeeded, 2);
+            assert.equal(failed.length, 0);
+            assert.equal(maxInFlight, 2);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+            await rm(home, { recursive: true, force: true });
+        }
+    });
+    it("serializes file-write actions that share the same target", async () => {
+        const sourceDir = await makeTmpDir();
+        const home = await makeTmpDir();
+        let inFlight = 0;
+        let maxInFlight = 0;
+        try {
+            const sourceFile = path.join(sourceDir, "file.txt");
+            const targetFile = path.join(home, "shared.txt");
+            await writeFile(sourceFile, "version 1");
+            const action = {
+                kind: "file-write",
+                skill: "test-skill",
+                agent: "claude-code",
+                source: sourceFile,
+                target: targetFile,
+            };
+            await executeDeploy([action], false, false, home, {
+                fileOps: {
+                    async copyFile(source, target) {
+                        inFlight += 1;
+                        maxInFlight = Math.max(maxInFlight, inFlight);
+                        await delay(25);
+                        await copyFile(source, target);
+                        inFlight -= 1;
+                    },
+                    rename,
+                    rm,
+                    writeFile,
+                },
+            });
+            await writeFile(sourceFile, "version 2");
+            const { succeeded, failed } = await executeDeploy([action, action], false, false, home, {
+                fileOps: {
+                    async copyFile(source, target) {
+                        inFlight += 1;
+                        maxInFlight = Math.max(maxInFlight, inFlight);
+                        await delay(25);
+                        await copyFile(source, target);
+                        inFlight -= 1;
+                    },
+                    rename,
+                    rm,
+                    writeFile,
+                },
+            });
+            assert.equal(succeeded, 2);
+            assert.equal(failed.length, 0);
+            assert.equal(maxInFlight, 1);
+            assert.equal(await readFile(targetFile, "utf-8"), "version 2");
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+            await rm(home, { recursive: true, force: true });
+        }
+    });
     it("fails gracefully when source file does not exist", async () => {
         const home = await makeTmpDir();
         try {
@@ -1450,6 +1651,58 @@ describe("executeDeploy — file-write", () => {
             await rm(home, { recursive: true, force: true });
         }
     });
+    it("returns failed actions in input order under concurrent execution", async () => {
+        const sourceDir = await makeTmpDir();
+        const home = await makeTmpDir();
+        try {
+            const sourceA = path.join(sourceDir, "a.txt");
+            const sourceB = path.join(sourceDir, "b.txt");
+            const targetA = path.join(home, "a.txt");
+            const targetB = path.join(home, "b.txt");
+            await writeFile(sourceA, "a");
+            await writeFile(sourceB, "b");
+            const actions = [
+                {
+                    kind: "file-write",
+                    skill: "slow-fail",
+                    agent: "claude-code",
+                    source: sourceA,
+                    target: targetA,
+                },
+                {
+                    kind: "file-write",
+                    skill: "fast-fail",
+                    agent: "codex",
+                    source: sourceB,
+                    target: targetB,
+                },
+            ];
+            const { succeeded, failed } = await executeDeploy(actions, false, false, home, {
+                fileOps: {
+                    async copyFile(_source, target) {
+                        if (target.includes("a.txt")) {
+                            await delay(25);
+                            throw new Error("slow failure");
+                        }
+                        throw new Error("fast failure");
+                    },
+                    rename,
+                    rm,
+                    writeFile,
+                },
+            });
+            assert.equal(succeeded, 0);
+            assert.equal(failed.length, 2);
+            assert.equal(failed[0]?.action.skill, "slow-fail");
+            assert.match(failed[0]?.error ?? "", /slow failure/);
+            assert.equal(failed[1]?.action.skill, "fast-fail");
+            assert.match(failed[1]?.error ?? "", /fast failure/);
+        }
+        finally {
+            await rm(sourceDir, { recursive: true });
+            await rm(home, { recursive: true, force: true });
+        }
+    });
 });
 describe("executeDeploy — config-patch", () => {
     it("applies a JSON merge patch to an existing config file", async () => {

package/dist/test/unit/gemini-north-star.test.js

@@ -4,6 +4,7 @@ import path from "node:path";
 import { describe, it } from "node:test";
 import { compileAgentDefinitionActions } from "../../src/core/adapters/agent-definitions.js";
 import { runPreflight } from "../../src/core/preflight.js";
+import { createSourcePathValidator } from "../../src/core/validation.js";
 import { makeTmpDir } from "../helpers/fs.js";
 import { assertPathEndsWith } from "../helpers/path.js";
 describe("Gemini CLI North Star", () => {
@@ -11,13 +12,13 @@ describe("Gemini CLI North Star", () => {
         const dir = await makeTmpDir();
         try {
             await writeFile(path.join(dir, "my-agent.md"), "---\nname: test-agent\ndescription: test\ntools: []\n---\n# Agent");
-            const realRoot = await realpath(dir);
+            const validateSource = createSourcePathValidator(await realpath(dir));
             const { actions, warnings } = await compileAgentDefinitionActions({
                 name: "my-agent",
                 agents: ["gemini-cli"],
                 path: "my-agent.md",
                 scope: "global",
-            }, dir, dir, realRoot, ["gemini-cli"], "/home/test", "/repo/test");
+            }, dir, dir, validateSource, ["gemini-cli"], "/home/test", "/repo/test");
             assert.equal(warnings.length, 0);
             assert.equal(actions.length, 1);
             const action = actions[0];
@@ -33,13 +34,13 @@ describe("Gemini CLI North Star", () => {
         const dir = await makeTmpDir();
         try {
             await writeFile(path.join(dir, "my-agent.toml"), '[agent]\nname = "my-agent"\ndescription = "test"\n');
-            const realRoot = await realpath(dir);
+            const validateSource = createSourcePathValidator(await realpath(dir));
             const { actions, warnings } = await compileAgentDefinitionActions({
                 name: "my-agent",
                 agents: ["gemini-cli"],
                 path: "my-agent.toml",
                 scope: "global",
-            }, dir, dir, realRoot, ["gemini-cli"], "/home/test", "/repo/test");
+            }, dir, dir, validateSource, ["gemini-cli"], "/home/test", "/repo/test");
             assert.equal(warnings.length, 0);
             assert.equal(actions.length, 1);
             const action = actions[0];
@@ -55,13 +56,13 @@ describe("Gemini CLI North Star", () => {
         const dir = await makeTmpDir();
         try {
             await writeFile(path.join(dir, "my-agent.toml"), '[agent]\nname = "my-agent"\ndescription = "test"\n');
-            const realRoot = await realpath(dir);
+            const validateSource = createSourcePathValidator(await realpath(dir));
             const { actions, warnings } = await compileAgentDefinitionActions({
                 name: "my-agent",
                 agents: ["gemini-cli"],
                 path: "my-agent.toml",
                 scope: "repo",
-            }, dir, dir, realRoot, ["gemini-cli"], "/home/test", "/repo/test");
+            }, dir, dir, validateSource, ["gemini-cli"], "/home/test", "/repo/test");
             assert.equal(warnings.length, 0);
             assert.equal(actions.length, 1);
             const action = actions[0];
@@ -77,14 +78,14 @@ describe("Gemini CLI North Star", () => {
         const dir = await makeTmpDir();
         try {
             await writeFile(path.join(dir, "my-agent.toml"), '[agent]\nname = "my-agent"\ndescription = "test"\n');
-            const realRoot = await realpath(dir);
+            const validateSource = createSourcePathValidator(await realpath(dir));
             // claude-code has no TOML surface — should silently produce no action
             const { actions, warnings } = await compileAgentDefinitionActions({
                 name: "my-agent",
                 agents: ["claude-code"],
                 path: "my-agent.toml",
                 scope: "repo",
-            }, dir, dir, realRoot, ["claude-code"], "/home/test", "/repo/test");
+            }, dir, dir, validateSource, ["claude-code"], "/home/test", "/repo/test");
             assert.equal(actions.length, 0, "expected no action for agent without TOML surface");
             assert.equal(warnings.length, 0, "expected no warnings");
         }

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

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

package/dist/test/unit/init.test.js

@@ -0,0 +1,14 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { isInsideSkillDir } from "../../src/core/init.js";
+describe("isInsideSkillDir", () => {
+    it("matches a file directly inside a discovered skill directory", () => {
+        assert.equal(isInsideSkillDir("skills/alpha/guide.md", new Set(["skills/alpha"])), true);
+    });
+    it("matches a file nested below a discovered skill directory", () => {
+        assert.equal(isInsideSkillDir("skills/alpha/docs/reference/guide.md", new Set(["skills/alpha"])), true);
+    });
+    it("does not match similarly prefixed sibling paths", () => {
+        assert.equal(isInsideSkillDir("skills/alpha-helper/guide.md", new Set(["skills/alpha"])), false);
+    });
+});

package/dist/test/unit/manifest.test.js

@@ -229,6 +229,31 @@ describe("loadManifest", () => {
             await rm(dir, { recursive: true });
         }
     });
+    it("mentions {workspace} in target placeholder validation errors", async () => {
+        const dir = await makeTmpDir();
+        try {
+            await writeFile(path.join(dir, "inception.json"), JSON.stringify({
+                skills: [],
+                files: [
+                    {
+                        name: "bad-target",
+                        path: "files/settings.json",
+                        target: "{invalid}/settings.json",
+                        agents: ["claude-code"],
+                    },
+                ],
+            }));
+            await assert.rejects(loadManifest(dir), (err) => {
+                assert.ok(err instanceof UserError);
+                assert.equal(err.code, "MANIFEST_INVALID");
+                assert.match(err.message, /\{workspace\}/);
+                return true;
+            });
+        }
+        finally {
+            await rm(dir, { recursive: true });
+        }
+    });
     it("throws when agentRules is not an array", async () => {
         const dir = await makeTmpDir();
         try {

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

@@ -51,6 +51,35 @@ describe("runPreflight", () => {
         assert.equal(warnings[0]?.kind, "config-authority");
         assert.match(warnings[0]?.message ?? "", /antigravity/);
     });
+    it("keeps agent-specific warning order aligned with detectedAgents", async () => {
+        const home = await makeTmpDir();
+        try {
+            await mkdir(path.join(home, ".gemini"), { recursive: true });
+            await writeFile(path.join(home, ".gemini", "settings.json"), JSON.stringify({ instructionFilename: "CUSTOM.md" }));
+            const manifest = {
+                ...emptyManifest,
+                agentRules: [
+                    {
+                        name: "gemini-rules",
+                        path: "GEMINI.md",
+                        agents: ["gemini-cli"],
+                        scope: "global",
+                    },
+                ],
+            };
+            const warnings = await runPreflight(baseOptions, manifest, home, [
+                "gemini-cli",
+                "antigravity",
+            ]);
+            assert.equal(warnings.length, 2);
+            assert.match(warnings[0]?.message ?? "", /instructionFilename/);
+            assert.match(warnings[1]?.message ?? "", /antigravity/);
+            assert.match(warnings[1]?.message ?? "", /implementation-only/);
+        }
+        finally {
+            await rm(home, { recursive: true, force: true });
+        }
+    });
     it("emits shared-surface guidance when a skill targets github-copilot without claude-code", async () => {
         const manifest = {
             ...emptyManifest,

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

@@ -1,8 +1,8 @@
 import assert from "node:assert/strict";
-import { chmod, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { 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";
+import { defaultRegistryPersistence, lookupDeployment, registerDeployment, } from "../../src/core/ownership.js";
 import { executeRevert, planRevert, planRevertAll, } from "../../src/core/revert.js";
 import { logger } from "../../src/logger.js";
 import { exists, makeTmpDir } from "../helpers/fs.js";
@@ -257,20 +257,21 @@ describe("executeRevert — copy method (cross-platform)", () => {
                 agent: "claude-code",
                 method: "copy",
             });
-            const registryFile = path.join(home, ".inception-engine", "registry.json");
-            await chmod(registryFile, 0o444);
-            const { succeeded, skipped, failed } = await executeRevert(actions, false, false, home);
+            // Simulate an unwritable registry via a failing RegistryPersistence
+            // instead of relying on chmod, which is not enforced for admin processes
+            // on Windows (e.g. GitHub Actions windows-latest runners).
+            const failingRegistry = {
+                load: (h) => defaultRegistryPersistence.load(h),
+                save: async () => {
+                    throw Object.assign(new Error("EACCES: permission denied, open 'registry.json'"), { code: "EACCES" });
+                },
+            };
+            const { succeeded, skipped, failed } = await executeRevert(actions, false, false, home, { registry: failingRegistry });
             assert.equal(succeeded, 0);
             assert.equal(skipped, 0);
             assert.equal(failed.length, 1);
         }
         finally {
-            try {
-                await chmod(path.join(home, ".inception-engine", "registry.json"), 0o666);
-            }
-            catch {
-                /* best effort */
-            }
             await rm(home, { recursive: true, force: true });
             await rm(sourceDir, { recursive: true, force: true });
         }

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

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

package/dist/test/unit/validation.test.js

@@ -0,0 +1,102 @@
+import assert from "node:assert/strict";
+import { realpath, rm, symlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { describe, it } from "node:test";
+import { createSourcePathValidator } from "../../src/core/validation.js";
+import { UserError } from "../../src/errors.js";
+import { makeTmpDir } from "../helpers/fs.js";
+describe("createSourcePathValidator", () => {
+    it("reports per-entry manifestPath on repeated symlink-escape errors for the same source", async () => {
+        const root = await realpath(await makeTmpDir());
+        const outside = await realpath(await makeTmpDir());
+        try {
+            const src = path.join(root, "escape");
+            await symlink(outside, src, process.platform === "win32" ? "junction" : "dir");
+            const validate = createSourcePathValidator(root);
+            await assert.rejects(() => validate(src, "entry-one", root), (err) => {
+                assert.ok(err instanceof UserError);
+                assert.match(err.message, /entry-one/);
+                assert.match(err.message, /via symlink/);
+                return true;
+            });
+            // Second call hits the cached escape outcome but still surfaces the
+            // current manifestPath, not the one captured on the first call.
+            await assert.rejects(() => validate(src, "entry-two", root), (err) => {
+                assert.ok(err instanceof UserError);
+                assert.match(err.message, /entry-two/);
+                assert.doesNotMatch(err.message, /entry-one/);
+                return true;
+            });
+        }
+        finally {
+            await rm(root, { recursive: true, force: true });
+            await rm(outside, { recursive: true });
+        }
+    });
+    it("memoizes the ok outcome for a missing source across calls", async () => {
+        const root = await realpath(await makeTmpDir());
+        const outside = await realpath(await makeTmpDir());
+        try {
+            const src = path.join(root, "later");
+            const validate = createSourcePathValidator(root);
+            // Missing source: validator swallows ENOENT and caches "ok".
+            await validate(src, "entry-one", root);
+            // Replace the missing source with an escaping symlink. If the first
+            // call's ok outcome is cached, the validator does not re-run
+            // realpath/identity-walk and still passes.
+            await symlink(outside, src, process.platform === "win32" ? "junction" : "dir");
+            await validate(src, "entry-two", root);
+        }
+        finally {
+            await rm(root, { recursive: true, force: true });
+            await rm(outside, { recursive: true });
+        }
+    });
+    it("reuses the cached ok outcome when the same source is validated repeatedly", async () => {
+        const root = await realpath(await makeTmpDir());
+        try {
+            const src = path.join(root, "file.md");
+            await writeFile(src, "# ok");
+            const validate = createSourcePathValidator(root);
+            await validate(src, "entry-one", root);
+            // Deleting the file before the second call would cause a fresh realpath
+            // to return ENOENT and also resolve to ok, so to really observe the
+            // cache we replace it with an escaping symlink.
+            await rm(src);
+            const outside = await realpath(await makeTmpDir());
+            try {
+                await symlink(outside, src, process.platform === "win32" ? "junction" : "dir");
+                // Cache hit: no escape error despite the symlink now pointing outside.
+                await validate(src, "entry-two", root);
+            }
+            finally {
+                await rm(outside, { recursive: true });
+            }
+        }
+        finally {
+            await rm(root, { recursive: true, force: true });
+        }
+    });
+    it("runs the out-of-root string gate per call with the caller's manifestPath", async () => {
+        const root = await realpath(await makeTmpDir());
+        try {
+            const validate = createSourcePathValidator(root);
+            const outside = path.resolve(root, "..", "elsewhere", "thing.md");
+            await assert.rejects(() => validate(outside, "entry-one", root), (err) => {
+                assert.ok(err instanceof UserError);
+                assert.match(err.message, /entry-one/);
+                assert.match(err.message, /resolves outside the repository root/);
+                assert.doesNotMatch(err.message, /via symlink/);
+                return true;
+            });
+            await assert.rejects(() => validate(outside, "entry-two", root), (err) => {
+                assert.ok(err instanceof UserError);
+                assert.match(err.message, /entry-two/);
+                return true;
+            });
+        }
+        finally {
+            await rm(root, { recursive: true, force: true });
+        }
+    });
+});