@kuznai/inception-engine 0.9.0 → 0.10.1

package/README.md

@@ -2,7 +2,9 @@
 
 Plant skills directly into the minds of your installed AI coding agents — Claude Code, Codex, Gemini CLI, Antigravity, OpenCode, and GitHub Copilot. One command. They'll think they thought of it themselves.
 
-Today, inception-engine deploys skills, single files, JSON config patches, MCP server registrations, and agent instruction files to AI coding agents.
+Today, inception-engine works as a cross-agent deployer for skills on all listed agents, plus single-file writes and JSON config patches. It also supports MCP server registration and global rules-file deployment for the subset of agents whose config surfaces are implemented and validated today.
+
+The broader portability layer is the roadmap direction, but this README focuses on what is working now.
 
 ## Quick Start
 
@@ -43,8 +45,10 @@ Managed skills overwrite their previous version. If a target exists but was not
 | Skills (SKILL.md) | All agents via manifest and CLI | All agents |
 | File write | All agents via manifest and CLI | All agents |
 | Config patch (JSON merge) | All agents via manifest and CLI | All agents |
-| MCP Servers | claude-code, gemini-cli; stub warning for other agents | claude-code, gemini-cli |
-| Agent Rules | claude-code, codex, gemini-cli, opencode; stub warning for other agents | claude-code, codex, gemini-cli, opencode |
+| MCP Servers | claude-code, gemini-cli; other agents are warned and skipped | claude-code, gemini-cli |
+| Global Rules Files | claude-code, codex, gemini-cli, opencode; other agents are warned and skipped | claude-code, codex, gemini-cli, opencode |
+
+Features that depend on agent-specific config surfaces are intentionally conservative: if a target path or schema is not implemented with enough confidence, inception-engine warns and skips it rather than guessing.
 
 ## Manifest Format
 
@@ -109,7 +113,7 @@ Each **config** entry applies a [JSON merge patch (RFC 7386)](https://datatracke
 
 - **name** - Unique identifier (same format as skill names)
 - **target** - Config file to patch, using the same placeholder prefix as file entries
-- **patch** - JSON object of keys to set. A `null` value removes the key from the target file. Non-null values are set directly (deep merge is not applied).
+- **patch** - JSON object of keys to set. A `null` value removes the key from the target file. Nested object values are merged recursively; non-object values replace the existing value directly.
 - **agents** - Array of agent IDs to apply this patch to
 
 The engine records an undo-patch for each config-patch deployment so that `revert` can restore the original values.
@@ -122,13 +126,13 @@ Each **mcpServer** entry registers an MCP server into the agent's config file by
 
 MCP server registration is currently supported for `claude-code` (`~/.claude.json`) and `gemini-cli` (`~/.gemini/settings.json`). Other agents emit a warning and are skipped. Revert removes the registered server entry from the config file.
 
-Each **agentRules** entry deploys a Markdown instruction file to the agent's global rules location:
+Each **agentRules** entry deploys a Markdown instruction file to an agent's supported global rules file location:
 
 - **name** - Unique identifier (same format as skill names)
 - **path** - Relative path to the source Markdown file within the repo
 - **agents** - Array of agent IDs to deploy this file to
 
-Agent rules deployment is currently supported for `claude-code` (`~/.claude/CLAUDE.md`), `codex` (`~/.codex/AGENTS.md`), `gemini-cli` (`~/.gemini/GEMINI.md`), and `opencode` (`~/.config/opencode/AGENTS.md`). Other agents emit a warning and are skipped. Revert removes the deployed rules file.
+Global rules-file deployment is currently supported for `claude-code` (`~/.claude/CLAUDE.md`), `codex` (`~/.codex/AGENTS.md`), `gemini-cli` (`~/.gemini/GEMINI.md`), and `opencode` (`~/.config/opencode/AGENTS.md`). Other agents emit a warning and are skipped because their instruction surfaces are different, repo-scoped, or not implemented here yet. Revert removes the deployed rules file.
 
 ## Creating Skills
 
@@ -175,19 +179,19 @@ inception-engine revert <directory> [options]
 
 ```bash
 # Deploy all skills to all detected agents
-npx inception-engine ./my-skills-repo
+npx @kuznai/inception-engine ./my-skills-repo
 
 # Preview what would be deployed
-npx inception-engine ./my-skills-repo --dry-run
+npx @kuznai/inception-engine ./my-skills-repo --dry-run
 
 # Deploy only to Claude Code and Codex
-npx inception-engine ./my-skills-repo --agents claude-code,codex
+npx @kuznai/inception-engine ./my-skills-repo --agents claude-code,codex
 
 # Remove deployed skills
-npx inception-engine revert ./my-skills-repo
+npx @kuznai/inception-engine revert ./my-skills-repo
 
 # Preview what would be removed
-npx inception-engine revert ./my-skills-repo --dry-run
+npx @kuznai/inception-engine revert ./my-skills-repo --dry-run
 ```
 
 ## Sample Skills
@@ -197,7 +201,7 @@ The `limbo/` directory contains exceptional sample skills for testing purposes o
 Try them out:
 
 ```bash
-npx inception-engine limbo --dry-run
+npx @kuznai/inception-engine limbo --dry-run
 ```
 
 ## Agent Detection
@@ -221,11 +225,11 @@ Revert targets all agents listed in the manifest by default (regardless of detec
 
 ### Ownership Tracking and Safe Revert
 
-inception-engine maintains a centralized deployment registry at `~/.inception-engine/registry.json`. Each deploy records the target path, source path, skill name, agent ID, deploy method, and timestamp. No files are written to the source repository.
+inception-engine maintains a centralized deployment registry at `~/.inception-engine/registry.json`. Each deploy records the target path, skill name, agent ID, action-specific provenance (`source`/`method` for skill-dir, `source` for file-write, `patch`/`undoPatch` for config-patch), and timestamp. No files are written to the source repository.
 
 - **Registry-based ownership**: On revert, the registry is checked before removing any target. Only targets with a valid registry entry are removed. On redeploy, unmanaged targets are never replaced.
 
-- **Strong binding**: Each registry entry binds a specific target path to its skill, agent, and action kind, with action-specific provenance fields (`source` and `method` for skill-dir and file-write; `patch` and `undoPatch` for config-patch). A target is only considered managed if all relevant fields match — a stray entry or a different deployment cannot satisfy the check.
+- **Strong binding**: Each registry entry binds a specific target path to its skill, agent, and action kind. For `skill-dir` and `file-write`, ownership checks also require the recorded `source` to match before an existing target is treated as managed. For `config-patch`, overwrite protection is keyed by target path, kind, skill, and agent; the stored `patch` and `undoPatch` are used for revert bookkeeping rather than deploy-time identity checks.
 
 - **Atomic redeploy**: When overwriting an existing managed `skill-dir` target, the engine renames the old target to a backup, creates the new deployment, and only removes the backup on success. If the new deployment fails, the backup is restored. `file-write` and `config-patch` deployments write directly to the target without this backup/rollback model.
 

package/dist/core/adapters/index.d.ts

@@ -1,8 +1,8 @@
-import type { McpServerEntry, AgentRuleEntry } from "../../schemas/manifest.ts";
+import type { AgentRuleEntry, McpServerEntry } from "../../schemas/manifest.ts";
 import type { AgentId, ConfigPatchDeployAction, FileWriteDeployAction, PlanWarning } from "../../types.ts";
 import { compileMcpServerReverts } from "./mcp.ts";
 import { compileAgentRuleReverts } from "./rules.ts";
-export { compileMcpServerReverts, compileAgentRuleReverts };
+export { compileAgentRuleReverts, compileMcpServerReverts };
 export type AdapterAction = ConfigPatchDeployAction | FileWriteDeployAction;
 export interface AdapterResult {
     actions: AdapterAction[];

package/dist/core/adapters/index.js

@@ -1,6 +1,6 @@
 import { compileMcpServerActions, compileMcpServerReverts } from "./mcp.js";
 import { compileAgentRuleActions, compileAgentRuleReverts } from "./rules.js";
-export { compileMcpServerReverts, compileAgentRuleReverts };
+export { compileAgentRuleReverts, compileMcpServerReverts };
 export async function compileAdapterActions(mcpServers, agentRules, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home) {
     const actions = [];
     const warnings = [];

package/dist/core/adapters/rules.js

@@ -6,13 +6,15 @@ export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDi
     const actions = [];
     const warnings = [];
     const platform = getPlatformKey();
+    const targetAgents = entry.agents.filter((agentId) => detectedAgents.includes(agentId));
+    if (targetAgents.length === 0) {
+        return { actions, warnings };
+    }
     // Validate the source file once (before iterating agents) since it is shared.
     const source = path.resolve(sourceDir, entry.path);
     await validateSourcePath(source, entry.path, resolvedSourceDir, realRoot);
     await validateSourceFile(source, entry.path);
-    for (const agentId of entry.agents) {
-        if (!detectedAgents.includes(agentId))
-            continue;
+    for (const agentId of targetAgents) {
         const agent = AGENT_REGISTRY_BY_ID[agentId];
         if (!agent?.agentRulesPath) {
             warnings.push({

package/dist/core/deploy.d.ts

@@ -1,9 +1,10 @@
-import type { AgentId, DeployAction, Manifest, PlannedChange, PlanWarning } from "../types.ts";
+import type { AgentId, DeployAction, Manifest, PlannedChange, PlanWarning, SkillDirDeployAction } from "../types.ts";
+import { type RegistryPersistence } from "./ownership.ts";
 export declare function planDeploy(manifest: Manifest, sourceDir: string, detectedAgents: AgentId[], home: string): Promise<{
     actions: DeployAction[];
     warnings: PlanWarning[];
 }>;
-export declare function executeDeploy(actions: DeployAction[], dryRun: boolean, verbose: boolean, home: string): Promise<{
+export declare function executeDeploy(actions: DeployAction[], dryRun: boolean, verbose: boolean, home: string, deps?: DeployDependencies): Promise<{
     succeeded: number;
     failed: Array<{
         action: DeployAction;
@@ -11,3 +12,22 @@ export declare function executeDeploy(actions: DeployAction[], dryRun: boolean,
     }>;
     planned: PlannedChange[];
 }>;
+interface SkillDirOps {
+    createTarget(action: SkillDirDeployAction): Promise<void>;
+    removeTarget(targetPath: string): Promise<void>;
+}
+interface DeployFileOps {
+    copyFile(source: string, target: string): Promise<void>;
+    rename(source: string, target: string): Promise<void>;
+    rm(targetPath: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<void>;
+    writeFile(filePath: string, content: string, encoding: BufferEncoding): Promise<void>;
+}
+interface DeployDependencies {
+    registry?: RegistryPersistence;
+    skillDirOps?: SkillDirOps;
+    fileOps?: DeployFileOps;
+}
+export {};

package/dist/core/deploy.js

@@ -4,14 +4,15 @@ import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { UserError } from "../errors.js";
 import { logger } from "../logger.js";
-import { lookupDeployment, registerDeployment, verifyDeployment, } from "./ownership.js";
 import { compileAdapterActions } from "./adapters/index.js";
+import { lookupDeployment, registerDeployment, verifyDeployment, } from "./ownership.js";
 import { getDeployMethod, resolveAgentSkillPath } from "./resolve.js";
+import { resolveTargetTemplate } from "./runtime-paths.js";
 import { sourceAccessError, validateSourceFile, validateSourcePath, } from "./validation.js";
 function isPlainObject(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
-async function readJsonConfig(filePath) {
+async function readJsonConfigFile(filePath) {
     let rawContent;
     try {
         rawContent = await readFile(filePath, "utf-8");
@@ -62,15 +63,6 @@ function applyMergePatch(original, patch) {
     }
     return patched;
 }
-function resolveTargetTemplate(template, home) {
-    const appdata = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
-    const xdgRaw = process.env.XDG_CONFIG_HOME;
-    const xdgConfig = xdgRaw && path.isAbsolute(xdgRaw) ? xdgRaw : path.join(home, ".config");
-    return template
-        .replace("{home}", home)
-        .replace("{appdata}", appdata)
-        .replace("{xdg_config}", xdgConfig);
-}
 function detectCollisions(actions) {
     const seen = new Map();
     const warnings = [];
@@ -103,12 +95,13 @@ async function planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realR
     const method = getDeployMethod();
     const actions = [];
     for (const skill of manifest.skills) {
+        const targetAgents = skill.agents.filter((agentId) => detectedAgents.includes(agentId));
+        if (targetAgents.length === 0)
+            continue;
         const source = path.resolve(sourceDir, skill.path);
         await validateSourcePath(source, skill.path, resolvedSourceDir, realRoot);
         await validateSkillContract(source, skill.path);
-        for (const agentId of skill.agents) {
-            if (!detectedAgents.includes(agentId))
-                continue;
+        for (const agentId of targetAgents) {
             const agent = AGENT_REGISTRY_BY_ID[agentId];
             if (!agent)
                 continue;
@@ -128,12 +121,13 @@ async function planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realR
 async function planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home) {
     const actions = [];
     for (const fileEntry of manifest.files ?? []) {
+        const targetAgents = fileEntry.agents.filter((agentId) => detectedAgents.includes(agentId));
+        if (targetAgents.length === 0)
+            continue;
         const source = path.resolve(sourceDir, fileEntry.path);
         await validateSourcePath(source, fileEntry.path, resolvedSourceDir, realRoot);
         await validateSourceFile(source, fileEntry.path);
-        for (const agentId of fileEntry.agents) {
-            if (!detectedAgents.includes(agentId))
-                continue;
+        for (const agentId of targetAgents) {
             const agent = AGENT_REGISTRY_BY_ID[agentId];
             if (!agent)
                 continue;
@@ -193,14 +187,14 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
     ];
     return { actions, warnings };
 }
-export async function executeDeploy(actions, dryRun, verbose, home) {
+export async function executeDeploy(actions, dryRun, verbose, home, deps = {}) {
     let succeeded = 0;
     const failed = [];
     const planned = [];
     for (const action of actions) {
         switch (action.kind) {
             case "skill-dir": {
-                const result = await deploySkillDir(action, dryRun, verbose, home, planned);
+                const result = await deploySkillDir(action, dryRun, verbose, home, planned, deps);
                 if (result.error === null) {
                     succeeded++;
                 }
@@ -210,7 +204,7 @@ export async function executeDeploy(actions, dryRun, verbose, home) {
                 break;
             }
             case "file-write": {
-                const result = await deployFileWrite(action, dryRun, verbose, home, planned);
+                const result = await deployFileWrite(action, dryRun, verbose, home, planned, deps);
                 if (result.error === null) {
                     succeeded++;
                 }
@@ -220,7 +214,7 @@ export async function executeDeploy(actions, dryRun, verbose, home) {
                 break;
             }
             case "config-patch": {
-                const result = await deployConfigPatch(action, dryRun, verbose, home, planned);
+                const result = await deployConfigPatch(action, dryRun, verbose, home, planned, deps);
                 if (result.error === null) {
                     succeeded++;
                 }
@@ -236,7 +230,114 @@ export async function executeDeploy(actions, dryRun, verbose, home) {
     }
     return { succeeded, failed, planned };
 }
-async function deploySkillDir(action, dryRun, verbose, home, planned) {
+const defaultSkillDirOps = {
+    async createTarget(action) {
+        if (action.method === "symlink") {
+            await symlink(action.source, action.target, "dir");
+        }
+        else {
+            await cp(action.source, action.target, { recursive: true });
+        }
+    },
+    async removeTarget(targetPath) {
+        const stat = await lstat(targetPath);
+        if (stat.isSymbolicLink()) {
+            await unlink(targetPath);
+        }
+        else {
+            await rm(targetPath, { recursive: true });
+        }
+    },
+};
+const defaultDeployFileOps = {
+    copyFile,
+    rename,
+    rm,
+    writeFile,
+};
+async function removeFileSystemTarget(targetPath) {
+    const stat = await lstat(targetPath);
+    if (stat.isDirectory() && !stat.isSymbolicLink()) {
+        await rm(targetPath, { recursive: true });
+    }
+    else {
+        await unlink(targetPath);
+    }
+}
+async function backupManagedFileWriteTarget(action, home, deps) {
+    try {
+        await lstat(action.target);
+    }
+    catch {
+        return null;
+    }
+    const isOwned = await verifyDeployment(home, action.target, {
+        kind: "file-write",
+        source: action.source,
+        skill: action.skill,
+        agent: action.agent,
+    }, deps.registry);
+    if (!isOwned) {
+        throw new Error(`Target "${action.target}" exists but is not managed by inception-engine — refusing to overwrite`);
+    }
+    const backupPath = `${action.target}.inception-backup`;
+    await (deps.fileOps ?? defaultDeployFileOps).rm(backupPath, {
+        recursive: true,
+        force: true,
+    });
+    await (deps.fileOps ?? defaultDeployFileOps).rename(action.target, backupPath);
+    return backupPath;
+}
+function createAtomicTempPath(targetPath) {
+    return `${targetPath}.inception-tmp-${process.pid}-${Date.now()}-${Math.random()
+        .toString(36)
+        .slice(2)}`;
+}
+async function replaceFileAtomically(targetPath, deps, stageTempFile, prepareBackup, commit) {
+    const fileOps = deps.fileOps ?? defaultDeployFileOps;
+    const tempPath = createAtomicTempPath(targetPath);
+    let backupPath = null;
+    let replacedTarget = false;
+    try {
+        await mkdir(path.dirname(targetPath), { recursive: true });
+        await stageTempFile(tempPath, fileOps);
+        backupPath = await prepareBackup();
+        await fileOps.rename(tempPath, targetPath);
+        replacedTarget = true;
+        await commit();
+    }
+    catch (writeErr) {
+        if (replacedTarget) {
+            try {
+                await removeFileSystemTarget(targetPath);
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+        }
+        else {
+            try {
+                await fileOps.rm(tempPath, { recursive: true, force: true });
+            }
+            catch {
+                /* best-effort cleanup */
+            }
+        }
+        if (backupPath) {
+            try {
+                await fileOps.rename(backupPath, targetPath);
+            }
+            catch {
+                /* best-effort rollback */
+            }
+        }
+        throw writeErr;
+    }
+    if (backupPath) {
+        await fileOps.rm(backupPath, { recursive: true, force: true });
+    }
+}
+async function deploySkillDir(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     try {
         await access(action.source);
@@ -260,7 +361,7 @@ async function deploySkillDir(action, dryRun, verbose, home, planned) {
         return { error: null };
     }
     try {
-        await executeDeployAction(action, verbose, home);
+        await executeDeployAction(action, verbose, home, deps);
         return { error: null };
     }
     catch (err) {
@@ -269,7 +370,7 @@ async function deploySkillDir(action, dryRun, verbose, home, planned) {
         return { error: msg };
     }
 }
-async function deployFileWrite(action, dryRun, verbose, home, planned) {
+async function deployFileWrite(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     try {
         await access(action.source);
@@ -291,32 +392,12 @@ async function deployFileWrite(action, dryRun, verbose, home, planned) {
         return { error: null };
     }
     try {
-        // Check if target exists — only allow overwrite if we own it
-        try {
-            await lstat(action.target);
-            const isOwned = await verifyDeployment(home, action.target, {
-                kind: "file-write",
-                source: action.source,
-                skill: action.skill,
-                agent: action.agent,
-            });
-            if (!isOwned) {
-                throw new Error(`Target "${action.target}" exists but is not managed by inception-engine — refusing to overwrite`);
-            }
-        }
-        catch (err) {
-            if (err instanceof Error && err.message.includes("refusing to overwrite"))
-                throw err;
-            // ENOENT — target doesn't exist, fine to create
-        }
-        await mkdir(path.dirname(action.target), { recursive: true });
-        await copyFile(action.source, action.target);
-        await registerDeployment(home, action.target, {
+        await replaceFileAtomically(action.target, deps, (tempPath, fileOps) => fileOps.copyFile(action.source, tempPath), () => backupManagedFileWriteTarget(action, home, deps), () => registerDeployment(home, action.target, {
             kind: "file-write",
             source: action.source,
             skill: action.skill,
             agent: action.agent,
-        });
+        }, deps.registry));
         logger.ok(label);
         if (verbose) {
             logger.detail(`write-file: ${action.source} -> ${action.target}`);
@@ -329,7 +410,7 @@ async function deployFileWrite(action, dryRun, verbose, home, planned) {
         return { error: msg };
     }
 }
-async function deployConfigPatch(action, dryRun, verbose, home, planned) {
+async function deployConfigPatch(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     if (!isPlainObject(action.patch)) {
         const msg = `Config patch for skill "${action.skill}" must be a plain object`;
@@ -350,23 +431,30 @@ async function deployConfigPatch(action, dryRun, verbose, home, planned) {
     }
     try {
         // Guard against double-patching by a different skill/agent
-        const existingEntry = await lookupDeployment(home, action.target);
+        const existingEntry = await lookupDeployment(home, action.target, deps.registry);
         if (existingEntry &&
             (existingEntry.skill !== action.skill ||
                 existingEntry.agent !== action.agent)) {
             throw new Error(`Config "${action.target}" is already patched by skill "${existingEntry.skill}" for agent "${existingEntry.agent}" — refusing to double-patch`);
         }
-        const original = await readJsonConfig(action.target);
+        const original = await readJsonConfigFile(action.target);
         const undoPatch = computeUndoPatch(original, patch);
         const patched = applyMergePatch(original, patch);
-        await writeFile(action.target, `${JSON.stringify(patched, null, 2)}\n`, "utf-8");
-        await registerDeployment(home, action.target, {
+        await replaceFileAtomically(action.target, deps, (tempPath, fileOps) => fileOps.writeFile(tempPath, `${JSON.stringify(patched, null, 2)}\n`, "utf-8"), async () => {
+            const backupPath = `${action.target}.inception-backup`;
+            await (deps.fileOps ?? defaultDeployFileOps).rm(backupPath, {
+                recursive: true,
+                force: true,
+            });
+            await (deps.fileOps ?? defaultDeployFileOps).rename(action.target, backupPath);
+            return backupPath;
+        }, () => registerDeployment(home, action.target, {
             kind: "config-patch",
             patch,
             undoPatch,
             skill: action.skill,
             agent: action.agent,
-        });
+        }, deps.registry));
         logger.ok(label);
         if (verbose) {
             logger.detail(`patch-config: applied ${Object.keys(patch).length} key(s) to ${action.target}`);
@@ -429,38 +517,35 @@ async function assertTargetAbsent(targetPath) {
         // ENOENT is expected — target should not exist after backup
     }
 }
-async function createDeployTarget(action, home) {
-    if (action.method === "symlink") {
-        await symlink(action.source, action.target, "dir");
-    }
-    else {
-        await cp(action.source, action.target, { recursive: true });
-    }
+async function createDeployTarget(action, home, deps) {
+    await (deps.skillDirOps ?? defaultSkillDirOps).createTarget(action);
     await registerDeployment(home, action.target, {
         kind: action.kind,
         source: action.source,
         skill: action.skill,
         agent: action.agent,
         method: action.method,
-    });
+    }, deps.registry);
 }
-async function executeDeployAction(action, verbose, home) {
+async function executeDeployAction(action, verbose, home, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     const backupPath = await backupExisting(action.target, verbose, home, {
         kind: action.kind,
         source: action.source,
         skill: action.skill,
         agent: action.agent,
-    });
+    }, deps);
     await mkdir(path.dirname(action.target), { recursive: true });
     try {
         await assertTargetAbsent(action.target);
-        await createDeployTarget(action, home);
+        await createDeployTarget(action, home, deps);
     }
     catch (createErr) {
         if (backupPath) {
             try {
-                await removeTarget(action.target).catch(() => {
+                await (deps.skillDirOps ?? defaultSkillDirOps)
+                    .removeTarget(action.target)
+                    .catch(() => {
                     /* best-effort cleanup */
                 });
                 await rename(backupPath, action.target);
@@ -472,14 +557,14 @@ async function executeDeployAction(action, verbose, home) {
         throw createErr;
     }
     if (backupPath) {
-        await removeTarget(backupPath);
+        await (deps.skillDirOps ?? defaultSkillDirOps).removeTarget(backupPath);
     }
     logger.ok(label);
     if (verbose) {
         logger.detail(`${action.method}: ${action.source} -> ${action.target}`);
     }
 }
-async function backupExisting(targetPath, verbose, home, expected) {
+async function backupExisting(targetPath, verbose, home, expected, deps) {
     try {
         await lstat(targetPath);
     }
@@ -491,7 +576,7 @@ async function backupExisting(targetPath, verbose, home, expected) {
         source: expected.source,
         skill: expected.skill,
         agent: expected.agent,
-    }))) {
+    }, deps.registry))) {
         throw new Error(`Target "${targetPath}" exists but is not managed by inception-engine — refusing to overwrite`);
     }
     const backupPath = `${targetPath}.inception-backup`;
@@ -507,12 +592,3 @@ async function backupExisting(targetPath, verbose, home, expected) {
     await rename(targetPath, backupPath);
     return backupPath;
 }
-async function removeTarget(targetPath) {
-    const stat = await lstat(targetPath);
-    if (stat.isSymbolicLink()) {
-        await unlink(targetPath);
-    }
-    else {
-        await rm(targetPath, { recursive: true });
-    }
-}

package/dist/core/ownership.d.ts

@@ -1,6 +1,10 @@
-import { type ConfigPatchRegistryEntry, type FileWriteRegistryEntry, type RegistryEntry, type SkillDirRegistryEntry } from "../schemas/registry.ts";
+import { type ConfigPatchRegistryEntry, type FileWriteRegistryEntry, type Registry, type RegistryEntry, type SkillDirRegistryEntry } from "../schemas/registry.ts";
 import type { AgentId } from "../types.ts";
 export type { RegistryEntry } from "../schemas/registry.ts";
+export interface RegistryPersistence {
+    load(home: string): Promise<Registry>;
+    save(home: string, registry: Registry): Promise<void>;
+}
 export type VerifyExpected = {
     kind: "skill-dir";
     source: string;
@@ -17,8 +21,9 @@ export type VerifyExpected = {
     agent: AgentId;
 };
 export declare function registryPath(home: string): string;
+export declare const defaultRegistryPersistence: RegistryPersistence;
 export type RegisterEntry = Omit<SkillDirRegistryEntry, "deployed"> | Omit<FileWriteRegistryEntry, "deployed"> | Omit<ConfigPatchRegistryEntry, "deployed">;
-export declare function registerDeployment(home: string, targetPath: string, entry: RegisterEntry): Promise<void>;
-export declare function unregisterDeployment(home: string, targetPath: string): Promise<void>;
-export declare function lookupDeployment(home: string, targetPath: string): Promise<RegistryEntry | null>;
-export declare function verifyDeployment(home: string, targetPath: string, expected: VerifyExpected): Promise<RegistryEntry | null>;
+export declare function registerDeployment(home: string, targetPath: string, entry: RegisterEntry, persistence?: RegistryPersistence): Promise<void>;
+export declare function unregisterDeployment(home: string, targetPath: string, persistence?: RegistryPersistence): Promise<void>;
+export declare function lookupDeployment(home: string, targetPath: string, persistence?: RegistryPersistence): Promise<RegistryEntry | null>;
+export declare function verifyDeployment(home: string, targetPath: string, expected: VerifyExpected, persistence?: RegistryPersistence): Promise<RegistryEntry | null>;

package/dist/core/ownership.js

@@ -24,6 +24,10 @@ async function saveRegistry(home, registry) {
     await writeFile(filePath, `${JSON.stringify(registry, null, 2)}\n`);
     await setFilePermissions(filePath);
 }
+export const defaultRegistryPersistence = {
+    load: loadRegistry,
+    save: saveRegistry,
+};
 /**
  * Ensure the file is not world-writable regardless of umask.
  * On Windows, the OS inherits ACLs from the parent directory — no-op is correct.
@@ -36,27 +40,27 @@ async function setFilePermissions(filePath) {
 function emptyRegistry() {
     return { version: 1, deployments: {} };
 }
-export async function registerDeployment(home, targetPath, entry) {
-    const registry = await loadRegistry(home);
+export async function registerDeployment(home, targetPath, entry, persistence = defaultRegistryPersistence) {
+    const registry = await persistence.load(home);
     registry.deployments[targetPath] = {
         ...entry,
         deployed: new Date().toISOString(),
     };
-    await saveRegistry(home, registry);
+    await persistence.save(home, registry);
 }
-export async function unregisterDeployment(home, targetPath) {
-    const registry = await loadRegistry(home);
+export async function unregisterDeployment(home, targetPath, persistence = defaultRegistryPersistence) {
+    const registry = await persistence.load(home);
     if (!(targetPath in registry.deployments))
         return;
     delete registry.deployments[targetPath];
-    await saveRegistry(home, registry);
+    await persistence.save(home, registry);
 }
-export async function lookupDeployment(home, targetPath) {
-    const registry = await loadRegistry(home);
+export async function lookupDeployment(home, targetPath, persistence = defaultRegistryPersistence) {
+    const registry = await persistence.load(home);
     return registry.deployments[targetPath] ?? null;
 }
-export async function verifyDeployment(home, targetPath, expected) {
-    const entry = await lookupDeployment(home, targetPath);
+export async function verifyDeployment(home, targetPath, expected, persistence = defaultRegistryPersistence) {
+    const entry = await lookupDeployment(home, targetPath, persistence);
     if (!entry)
         return null;
     if (entry.kind !== expected.kind)

package/dist/core/resolve.js

@@ -1,8 +1,8 @@
 import { execFileSync } from "node:child_process";
 import { readFileSync } from "node:fs";
 import os from "node:os";
-import path from "node:path";
 import { UserError } from "../errors.js";
+import { getPathApi, resolveRuntimePaths } from "./runtime-paths.js";
 export function resolveHome() {
     if (process.platform === "win32") {
         return os.homedir();
@@ -97,13 +97,12 @@ export function resolveAgentDetectPath(agent, home) {
     return resolveAgentDetectPathFor(agent, home, getPlatformKey());
 }
 export function resolvePlaceholders(segments, skillName, home) {
-    const appdata = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
-    const xdgRaw = process.env.XDG_CONFIG_HOME;
-    const xdgConfig = xdgRaw && path.isAbsolute(xdgRaw) ? xdgRaw : path.join(home, ".config");
+    const { appdata, xdgConfig } = resolveRuntimePaths(home);
     const resolved = segments.map((seg) => seg
         .replace("{home}", home)
         .replace("{name}", skillName)
         .replace("{appdata}", appdata)
         .replace("{xdg_config}", xdgConfig));
-    return path.join(...resolved);
+    const root = resolved.find((segment) => segment.length > 0) ?? home;
+    return getPathApi(root).join(...resolved);
 }

package/dist/core/revert.d.ts

@@ -1,7 +1,8 @@
 import type { AgentId, Manifest, PlannedChange, RevertAction } from "../types.ts";
+import { type RegistryPersistence } from "./ownership.ts";
 export declare function planRevert(manifest: Manifest, detectedAgents: AgentId[], home: string): RevertAction[];
 export declare function planRevertAll(manifest: Manifest, home: string): RevertAction[];
-export declare function executeRevert(actions: RevertAction[], dryRun: boolean, verbose: boolean, home: string): Promise<{
+export declare function executeRevert(actions: RevertAction[], dryRun: boolean, verbose: boolean, home: string, deps?: RevertDependencies): Promise<{
     succeeded: number;
     skipped: number;
     failed: Array<{
@@ -10,3 +11,7 @@ export declare function executeRevert(actions: RevertAction[], dryRun: boolean,
     }>;
     planned: PlannedChange[];
 }>;
+interface RevertDependencies {
+    registry?: RegistryPersistence;
+}
+export {};

package/dist/core/revert.js

@@ -1,19 +1,10 @@
 import { lstat, readFile, rm, unlink, writeFile } from "node:fs/promises";
-import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { logger } from "../logger.js";
-import { compileMcpServerReverts, compileAgentRuleReverts, } from "./adapters/index.js";
-import { lookupDeployment, unregisterDeployment } from "./ownership.js";
+import { compileAgentRuleReverts, compileMcpServerReverts, } from "./adapters/index.js";
+import { lookupDeployment, unregisterDeployment, } from "./ownership.js";
 import { resolveAgentSkillPath } from "./resolve.js";
-function resolveTargetTemplate(template, home) {
-    const appdata = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
-    const xdgRaw = process.env.XDG_CONFIG_HOME;
-    const xdgConfig = xdgRaw && path.isAbsolute(xdgRaw) ? xdgRaw : path.join(home, ".config");
-    return template
-        .replace("{home}", home)
-        .replace("{appdata}", appdata)
-        .replace("{xdg_config}", xdgConfig);
-}
+import { resolveTargetTemplate } from "./runtime-paths.js";
 function buildSkillDirReverts(manifest, home, agentFilter) {
     const actions = [];
     for (const skill of manifest.skills) {
@@ -139,7 +130,7 @@ function lstatOutcome(err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { outcome: "fail", error: msg };
 }
-export async function executeRevert(actions, dryRun, verbose, home) {
+export async function executeRevert(actions, dryRun, verbose, home, deps = {}) {
     let succeeded = 0;
     let skipped = 0;
     const failed = [];
@@ -149,13 +140,13 @@ export async function executeRevert(actions, dryRun, verbose, home) {
         let result;
         switch (action.kind) {
             case "skill-dir":
-                result = await executeRevertAction(action, dryRun, verbose, home, planned);
+                result = await executeRevertAction(action, dryRun, verbose, home, planned, deps);
                 break;
             case "file-write":
-                result = await revertFileWrite(action, dryRun, verbose, home, planned);
+                result = await revertFileWrite(action, dryRun, verbose, home, planned, deps);
                 break;
             case "config-patch":
-                result = await revertConfigPatch(action, dryRun, verbose, home, planned);
+                result = await revertConfigPatch(action, dryRun, verbose, home, planned, deps);
                 break;
             default:
                 throw new Error(`Unhandled revert action kind: ${action}`);
@@ -166,7 +157,7 @@ export async function executeRevert(actions, dryRun, verbose, home) {
     skipped = counts.skipped;
     return { succeeded, skipped, failed, planned };
 }
-async function executeRevertAction(action, dryRun, verbose, home, planned) {
+async function executeRevertAction(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     try {
         await lstat(action.target);
@@ -180,7 +171,7 @@ async function executeRevertAction(action, dryRun, verbose, home, planned) {
         logger.fail(label, result.error);
         return result;
     }
-    const entry = await lookupDeployment(home, action.target);
+    const entry = await lookupDeployment(home, action.target, deps.registry);
     if (!entry || entry.skill !== action.skill || entry.agent !== action.agent) {
         logger.warn(label, `skipping: ${action.target} is not in the deployment registry — not managed by inception-engine`);
         return { outcome: "skip" };
@@ -205,7 +196,7 @@ async function executeRevertAction(action, dryRun, verbose, home, planned) {
         else {
             await rm(action.target, { recursive: true });
         }
-        await unregisterDeployment(home, action.target);
+        await unregisterDeployment(home, action.target, deps.registry);
         logger.ok(label);
         if (verbose) {
             logger.detail(`removed: ${action.target}`);
@@ -223,7 +214,7 @@ async function executeRevertAction(action, dryRun, verbose, home, planned) {
         return { outcome: "fail", error: msg };
     }
 }
-async function revertFileWrite(action, dryRun, verbose, home, planned) {
+async function revertFileWrite(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     try {
         await lstat(action.target);
@@ -237,7 +228,7 @@ async function revertFileWrite(action, dryRun, verbose, home, planned) {
         logger.fail(label, result.error);
         return result;
     }
-    const entry = await lookupDeployment(home, action.target);
+    const entry = await lookupDeployment(home, action.target, deps.registry);
     if (!entry || entry.skill !== action.skill || entry.agent !== action.agent) {
         logger.warn(label, `skipping: ${action.target} is not in the deployment registry — not managed by inception-engine`);
         return { outcome: "skip" };
@@ -257,7 +248,7 @@ async function revertFileWrite(action, dryRun, verbose, home, planned) {
         // removal window; handle the case where the file has since disappeared.
         await lstat(action.target);
         await unlink(action.target);
-        await unregisterDeployment(home, action.target);
+        await unregisterDeployment(home, action.target, deps.registry);
         logger.ok(label);
         if (verbose) {
             logger.detail(`removed: ${action.target}`);
@@ -274,7 +265,7 @@ async function revertFileWrite(action, dryRun, verbose, home, planned) {
         return { outcome: "fail", error: msg };
     }
 }
-async function revertConfigPatch(action, dryRun, verbose, home, planned) {
+async function revertConfigPatch(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     try {
         await lstat(action.target);
@@ -288,7 +279,7 @@ async function revertConfigPatch(action, dryRun, verbose, home, planned) {
         logger.fail(label, result.error);
         return result;
     }
-    const entry = await lookupDeployment(home, action.target);
+    const entry = await lookupDeployment(home, action.target, deps.registry);
     if (!entry ||
         entry.kind !== "config-patch" ||
         entry.skill !== action.skill ||
@@ -312,7 +303,7 @@ async function revertConfigPatch(action, dryRun, verbose, home, planned) {
         const current = await readJsonConfig(action.target);
         const restored = applyUndoPatch(current, configPatchEntry.undoPatch);
         await writeFile(action.target, `${JSON.stringify(restored, null, 2)}\n`, "utf-8");
-        await unregisterDeployment(home, action.target);
+        await unregisterDeployment(home, action.target, deps.registry);
         logger.ok(label);
         if (verbose) {
             logger.detail(`unapplied patch from: ${action.target}`);

package/dist/core/runtime-paths.d.ts

@@ -0,0 +1,8 @@
+import path from "node:path";
+export interface RuntimePaths {
+    appdata: string;
+    xdgConfig: string;
+}
+export declare function getPathApi(root: string): typeof path.posix | typeof path.win32;
+export declare function resolveRuntimePaths(home: string): RuntimePaths;
+export declare function resolveTargetTemplate(template: string, home: string): string;

package/dist/core/runtime-paths.js

@@ -0,0 +1,57 @@
+import path from "node:path";
+const TARGET_TEMPLATE_RE = /^\{(home|appdata|xdg_config)\}(?<suffix>(?:[\\/].*)?)$/;
+export function getPathApi(root) {
+    if (root.includes("\\") || /^[a-zA-Z]:/.test(root)) {
+        return path.win32;
+    }
+    if (root.startsWith("/")) {
+        return path.posix;
+    }
+    return process.platform === "win32" ? path.win32 : path.posix;
+}
+function normalizePathForComparison(candidate, pathApi) {
+    const normalized = pathApi.normalize(candidate);
+    return pathApi === path.win32 ? normalized.toLowerCase() : normalized;
+}
+function isSameOrDescendantPath(candidate, root) {
+    const pathApi = getPathApi(root);
+    const normalizedCandidate = normalizePathForComparison(candidate, pathApi);
+    const normalizedRoot = normalizePathForComparison(root, pathApi);
+    return (normalizedCandidate === normalizedRoot ||
+        normalizedCandidate.startsWith(normalizedRoot + pathApi.sep));
+}
+export function resolveRuntimePaths(home) {
+    const appdataRaw = process.env.APPDATA;
+    const homePathApi = getPathApi(home);
+    const appdata = appdataRaw && getPathApi(appdataRaw).isAbsolute(appdataRaw)
+        ? appdataRaw
+        : homePathApi.join(home, "AppData", "Roaming");
+    const xdgRaw = process.env.XDG_CONFIG_HOME;
+    const xdgConfig = xdgRaw && getPathApi(xdgRaw).isAbsolute(xdgRaw)
+        ? xdgRaw
+        : homePathApi.join(home, ".config");
+    return { appdata, xdgConfig };
+}
+export function resolveTargetTemplate(template, home) {
+    const { appdata, xdgConfig } = resolveRuntimePaths(home);
+    const match = TARGET_TEMPLATE_RE.exec(template);
+    if (!match) {
+        throw new Error(`Invalid target template: ${template}`);
+    }
+    const baseByRoot = {
+        home,
+        appdata,
+        xdg_config: xdgConfig,
+    };
+    const root = match[1];
+    const suffix = match.groups?.suffix ?? "";
+    const segments = suffix.split(/[\\/]+/).filter(Boolean);
+    const pathApi = getPathApi(baseByRoot[root]);
+    const resolved = segments.length === 0
+        ? baseByRoot[root]
+        : pathApi.join(baseByRoot[root], ...segments);
+    if (!isSameOrDescendantPath(resolved, baseByRoot[root])) {
+        throw new Error(`Target template resolves outside its placeholder root: ${template}`);
+    }
+    return suffix === "" ? baseByRoot[root] : `${baseByRoot[root]}${suffix}`;
+}

package/dist/core/validation.js

@@ -1,4 +1,4 @@
-import { lstat, realpath } from "node:fs/promises";
+import { lstat, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import { UserError } from "../errors.js";
 export function sourceAccessError(err, sourcePath) {
@@ -10,14 +10,39 @@ export function sourceAccessError(err, sourcePath) {
     const detail = err instanceof Error ? err.message : String(err);
     return `Failed to access source ${sourcePath}: ${detail}`;
 }
+function normalizePathForComparison(candidate) {
+    const normalized = path.normalize(candidate);
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function isSameOrDescendantPath(candidate, root) {
+    const normalizedCandidate = normalizePathForComparison(candidate);
+    const normalizedRoot = normalizePathForComparison(root);
+    return (normalizedCandidate === normalizedRoot ||
+        normalizedCandidate.startsWith(normalizedRoot + path.sep));
+}
+async function isSameFileSystemLocation(a, b) {
+    const [aStat, bStat] = await Promise.all([stat(a), stat(b)]);
+    return aStat.dev === bStat.dev && aStat.ino === bStat.ino;
+}
+async function isWithinRootByIdentity(candidate, root) {
+    let current = candidate;
+    while (true) {
+        if (await isSameFileSystemLocation(current, root))
+            return true;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
 export async function validateSourcePath(source, skillPath, resolvedSourceDir, realRoot) {
     if (!source.startsWith(resolvedSourceDir + path.sep)) {
         throw new UserError("DEPLOY_FAILED", `Skill path "${skillPath}" resolves outside the repository root: ${source}`);
     }
     try {
         const realSource = await realpath(source);
-        if (realSource !== realRoot &&
-            !realSource.startsWith(realRoot + path.sep)) {
+        if (!(isSameOrDescendantPath(realSource, realRoot) ||
+            (await isWithinRootByIdentity(realSource, realRoot)))) {
             throw new UserError("DEPLOY_FAILED", `Skill path "${skillPath}" resolves outside the repository root via symlink: ${source} -> ${realSource}`);
         }
     }

package/dist/schemas/manifest.js

@@ -10,9 +10,10 @@ const AGENT_IDS = [
 ];
 export { AGENT_IDS };
 const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-// Target templates must start with a known placeholder to prevent raw absolute
-// paths or directory traversal. e.g. "{home}/.claude/settings.json" is valid.
-const TARGET_TEMPLATE_RE = /^\{(home|appdata|xdg_config)\}/;
+// Target templates must be rooted at a known placeholder and may only add
+// descendant path segments beneath that root. e.g. "{home}/.claude/settings.json"
+// is valid, while "{home}/../.ssh/config" is rejected.
+const TARGET_TEMPLATE_RE = /^\{(home|appdata|xdg_config)\}(?:[\\/].*)?$/;
 // Standalone schema used for type derivation and single-ID validation (e.g. index.ts).
 export const AgentIdSchema = z.enum(AGENT_IDS);
 // Used inside SkillEntrySchema.agents so that enum failures embed the received
@@ -53,6 +54,9 @@ const targetTemplateField = z
     .min(1, { message: "target must be a non-empty string" })
     .refine((t) => TARGET_TEMPLATE_RE.test(t), {
     message: "target must start with a known placeholder: {home}, {appdata}, or {xdg_config}",
+})
+    .refine((t) => !t.split(/[\\/]+/).includes(".."), {
+    message: "target must not escape its placeholder root",
 });
 export const SkillEntrySchema = z.object({
     name: nameField,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",
@@ -38,11 +38,13 @@
     "typecheck": "tsc --noEmit",
     "fmt": "biome format --write .",
     "lint": "biome lint . --max-diagnostics none",
+    "lint:fix": "biome lint . --max-diagnostics none --write --unsafe",
     "predev": "node scripts/assert-direct-ts-node.mjs",
     "dev": "node src/index.ts",
     "pretest": "node scripts/assert-direct-ts-node.mjs",
-    "test": "node --test test/*.test.ts",
-    "prepublishOnly": "npm run typecheck && npm run lint && npm run build"
+    "test": "node --test --test-isolation=none test/**/*.test.ts",
+    "test:windows": "node --test --test-isolation=none test/unit/*.test.ts test/os/cross-platform/*.test.ts test/os/windows/*.test.ts",
+    "test:posix": "node --test --test-isolation=none test/unit/*.test.ts test/os/cross-platform/*.test.ts test/os/posix/*.test.ts"
   },
   "dependencies": {
     "zod": "^4.0.0"