@kuznai/inception-engine 0.3.0 → 0.4.0

package/README.md

@@ -17,7 +17,7 @@ inception-engine reads a manifest file (`inception.json`) from the target direct
 - **POSIX (macOS, Linux)**: creates symlinks from the source skill directory to each agent's skill path
 - **Windows**: copies skill directories to each agent's skill path
 
-Skills always overwrite their previous version. On POSIX systems, symlinks mean updates to the source repo are reflected immediately.
+Managed skills overwrite their previous version. If a target exists but was not created by inception-engine, deployment refuses to replace it. On POSIX systems, symlinks mean updates to the source repo are reflected immediately.
 
 ## Agent Compatibility Matrix
 
@@ -93,14 +93,14 @@ inception-engine revert <directory> [options]
 | Command | Description |
 |---|---|
 | `<directory>` | Deploy skills from the manifest in the given directory |
-| `revert <directory>` | Remove all skills declared in the manifest |
+| `revert <directory>` | Remove previously deployed skills declared in the manifest |
 
 ### Options
 
 | Option | Description |
 |---|---|
 | `--dry-run` | Show what would be done without making changes |
-| `--agents <list>` | Comma-separated list of agent IDs to target (skips detection) |
+| `--agents <list>` | Comma-separated list of agent IDs to target (overrides deploy detection; restricts revert) |
 | `--verbose` | Show detailed output including file paths |
 | `--debug` | Show full error stack traces |
 | `--help` | Show help message |
@@ -141,7 +141,9 @@ inception-engine automatically detects which agents are installed by checking:
 1. Whether the agent's config directory exists (e.g., `~/.claude/` for Claude Code)
 2. Whether the agent's binary is in your PATH (e.g., `claude`, `codex`, `gemini`)
 
-If an agent isn't detected, its skills are skipped. Use `--agents` to override detection.
+If an agent isn't detected, its skills are skipped during deploy. Use `--agents` to override detection.
+
+Revert targets all agents listed in the manifest by default (regardless of detection) so that previously deployed skills are cleaned up even if the agent has since been uninstalled. Use `--agents` to restrict revert to specific agents.
 
 ## Cross-Platform Behavior
 
@@ -153,13 +155,17 @@ If an agent isn't detected, its skills are skipped. Use `--agents` to override d
 
 ### Ownership Tracking and Safe Revert
 
-inception-engine uses different ownership proofs depending on the deploy method so that `revert` never removes content it did not create:
+inception-engine writes a structured `.inception-totem` marker file during every deploy so that `revert` and future deploys never touch content they did not create. The totem contains metadata (source path, skill name, agent ID, deploy timestamp) and is validated on both revert and redeploy.
+
+- **POSIX (symlink)**: `.inception-totem` is written inside the skill source directory. On revert, the tool resolves the symlink target and checks for a valid `.inception-totem` there. Only symlinks whose resolved target contains a valid totem are removed.
+
+- **Windows (copy)**: `.inception-totem` is written inside each deployed skill directory. On revert, this file must be present and valid for the directory to be removed.
 
-- **POSIX (symlink)**: The symlink itself is the proof of ownership. On revert, the tool reads the symlink target with `readlink` and verifies it points to a directory containing a `SKILL.md`. Only symlinks that resolve to a valid skill source are removed.
+- **Deploy safety**: Before overwriting an existing target, the engine checks for a valid `.inception-totem`. If the target exists but is not managed by inception-engine, the deploy is skipped with an error — the unmanaged content is never removed.
 
-- **Windows (copy)**: A marker file `.inception-totem` is written inside each deployed skill directory. On revert, this file must be present for the directory to be removed. Directories that lack `.inception-totem` are skipped with a warning, even if they contain a `SKILL.md`.
+- **Atomic redeploy**: When overwriting an existing managed 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.
 
-> **Note:** Skills deployed before this ownership tracking was introduced (Windows only) will lack `.inception-totem` and must be re-deployed before `revert` can remove them.
+> **Note:** Skills deployed before `.inception-totem` was introduced must be re-deployed before `revert` can remove them.
 
 ## Running with Privilege Escalation
 

package/dist/config/manifest.js

@@ -46,6 +46,9 @@ function validateManifest(data, filePath) {
         if (path.isAbsolute(skill.path)) {
             throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].path must be a relative path`);
         }
+        if (path.normalize(skill.path).startsWith("..")) {
+            throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].path must not escape the repository root`);
+        }
         if (!Array.isArray(skill.agents) || skill.agents.length === 0) {
             throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].agents must be a non-empty array`);
         }

package/dist/core/deploy.d.ts

@@ -1,5 +1,5 @@
 import type { AgentId, DeployAction, Manifest } from "../types.ts";
-export declare function planDeploy(manifest: Manifest, sourceDir: string, detectedAgents: AgentId[], home: string): DeployAction[];
+export declare function planDeploy(manifest: Manifest, sourceDir: string, detectedAgents: AgentId[], home: string): Promise<DeployAction[]>;
 export declare function executeDeploy(actions: DeployAction[], dryRun: boolean, verbose: boolean): Promise<{
     succeeded: number;
     failed: Array<{

package/dist/core/deploy.js

@@ -1,18 +1,37 @@
-import { access, lstat, mkdir, symlink, cp, unlink, rm, writeFile } from "node:fs/promises";
+import { access, lstat, mkdir, symlink, cp, unlink, rm, rename, realpath } from "node:fs/promises";
 import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { resolveAgentSkillPath, getDeployMethod } from "./resolve.js";
 import { UserError } from "../errors.js";
 import { logger } from "../logger.js";
-export function planDeploy(manifest, sourceDir, detectedAgents, home) {
+import { isOwnedByInceptionEngine, writeTotem } from "./ownership.js";
+export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
     const method = getDeployMethod();
     const actions = [];
     const resolvedSourceDir = path.resolve(sourceDir);
+    let realRoot;
+    try {
+        realRoot = await realpath(resolvedSourceDir);
+    }
+    catch {
+        realRoot = resolvedSourceDir;
+    }
     for (const skill of manifest.skills) {
         const source = path.resolve(sourceDir, skill.path);
-        if (source !== resolvedSourceDir && !source.startsWith(resolvedSourceDir + path.sep)) {
+        if (!source.startsWith(resolvedSourceDir + path.sep)) {
             throw new UserError("DEPLOY_FAILED", `Skill path "${skill.path}" resolves outside the repository root: ${source}`);
         }
+        try {
+            const realSource = await realpath(source);
+            if (realSource !== realRoot && !realSource.startsWith(realRoot + path.sep)) {
+                throw new UserError("DEPLOY_FAILED", `Skill path "${skill.path}" resolves outside the repository root via symlink: ${source} -> ${realSource}`);
+            }
+        }
+        catch (err) {
+            if (err instanceof UserError)
+                throw err;
+            // Source doesn't exist yet — will be caught during execute
+        }
         for (const agentId of skill.agents) {
             if (!detectedAgents.includes(agentId))
                 continue;
@@ -48,14 +67,43 @@ export async function executeDeploy(actions, dryRun, verbose) {
             continue;
         }
         try {
-            await removeExisting(action.target, verbose);
+            const backupPath = await backupExisting(action.target, verbose);
             await mkdir(path.dirname(action.target), { recursive: true });
-            if (action.method === "symlink") {
-                await symlink(action.source, action.target, "dir");
+            try {
+                // Final TOCTOU check: ensure nothing appeared at the target after backup
+                try {
+                    await lstat(action.target);
+                    throw new Error(`Target path appeared unexpectedly after backup: ${action.target}`);
+                }
+                catch (err) {
+                    if (err instanceof Error && err.message.startsWith("Target path appeared"))
+                        throw err;
+                    // ENOENT is expected — target should not exist after backup
+                }
+                if (action.method === "symlink") {
+                    await symlink(action.source, action.target, "dir");
+                    await writeTotem(action.source, { source: action.source, skill: action.skill, agent: action.agent });
+                }
+                else {
+                    await cp(action.source, action.target, { recursive: true });
+                    await writeTotem(action.target, { source: action.source, skill: action.skill, agent: action.agent });
+                }
+            }
+            catch (createErr) {
+                // Rollback: restore backup if creation failed
+                if (backupPath) {
+                    try {
+                        await rename(backupPath, action.target);
+                    }
+                    catch {
+                        // Best-effort rollback
+                    }
+                }
+                throw createErr;
             }
-            else {
-                await cp(action.source, action.target, { recursive: true });
-                await writeFile(path.join(action.target, ".inception-totem"), "inception-engine\n");
+            // Success: remove backup
+            if (backupPath) {
+                await removeTarget(backupPath);
             }
             logger.ok(label);
             if (verbose) {
@@ -71,24 +119,38 @@ export async function executeDeploy(actions, dryRun, verbose) {
     }
     return { succeeded, failed };
 }
-async function removeExisting(targetPath, verbose) {
+async function backupExisting(targetPath, verbose) {
     let stat;
     try {
         stat = await lstat(targetPath);
     }
     catch {
-        return;
+        return null;
     }
+    if (!(await isOwnedByInceptionEngine(targetPath, stat))) {
+        throw new Error(`Target "${targetPath}" exists but is not managed by inception-engine — refusing to overwrite`);
+    }
+    const backupPath = targetPath + ".inception-backup";
+    // Clean up any stale backup from a previous failed attempt
+    try {
+        await lstat(backupPath);
+        await removeTarget(backupPath);
+    }
+    catch {
+        // No stale backup — expected
+    }
+    if (verbose) {
+        logger.detail(`backing up existing target: ${targetPath}`);
+    }
+    await rename(targetPath, backupPath);
+    return backupPath;
+}
+async function removeTarget(targetPath) {
+    const stat = await lstat(targetPath);
     if (stat.isSymbolicLink()) {
-        if (verbose) {
-            logger.detail(`removing existing symlink: ${targetPath}`);
-        }
         await unlink(targetPath);
     }
     else {
-        if (verbose) {
-            logger.warn(targetPath, "replacing existing directory");
-        }
         await rm(targetPath, { recursive: true });
     }
 }

package/dist/core/ownership.d.ts

@@ -0,0 +1,10 @@
+import type { Stats } from "node:fs";
+import type { AgentId } from "../types.ts";
+export interface TotemData {
+    source: string;
+    skill: string;
+    agent: AgentId;
+}
+export declare function formatTotem(data: TotemData): string;
+export declare function writeTotem(directory: string, data: TotemData): Promise<void>;
+export declare function isOwnedByInceptionEngine(targetPath: string, stat: Stats): Promise<boolean>;

package/dist/core/ownership.js

@@ -0,0 +1,44 @@
+import { access, readlink, readFile, writeFile, chmod } from "node:fs/promises";
+import path from "node:path";
+const TOTEM_FILE = ".inception-totem";
+const TOTEM_HEADER = "inception-engine";
+export function formatTotem(data) {
+    const lines = [
+        TOTEM_HEADER,
+        `source=${data.source}`,
+        `skill=${data.skill}`,
+        `agent=${data.agent}`,
+        `deployed=${new Date().toISOString()}`,
+    ];
+    return lines.join("\n") + "\n";
+}
+export async function writeTotem(directory, data) {
+    const totemPath = path.join(directory, TOTEM_FILE);
+    await writeFile(totemPath, formatTotem(data));
+    await chmod(totemPath, 0o644);
+}
+export async function isOwnedByInceptionEngine(targetPath, stat) {
+    const totemLocation = stat.isSymbolicLink()
+        ? await resolveSymlinkTotemPath(targetPath)
+        : path.join(targetPath, TOTEM_FILE);
+    if (!totemLocation)
+        return false;
+    try {
+        const content = await readFile(totemLocation, "utf-8");
+        return content.startsWith(TOTEM_HEADER);
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveSymlinkTotemPath(targetPath) {
+    try {
+        const linkTarget = await readlink(targetPath);
+        const resolved = path.resolve(path.dirname(targetPath), linkTarget);
+        await access(resolved);
+        return path.join(resolved, TOTEM_FILE);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/revert.d.ts

@@ -1,5 +1,6 @@
 import type { AgentId, Manifest, RevertAction } from "../types.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): Promise<{
     succeeded: number;
     skipped: number;

package/dist/core/revert.js

@@ -1,8 +1,8 @@
-import { access, lstat, unlink, rm, readlink } from "node:fs/promises";
-import path from "node:path";
-import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
+import { lstat, unlink, rm } from "node:fs/promises";
+import { AGENT_REGISTRY, AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { resolveAgentSkillPath } from "./resolve.js";
 import { logger } from "../logger.js";
+import { isOwnedByInceptionEngine } from "./ownership.js";
 export function planRevert(manifest, detectedAgents, home) {
     const actions = [];
     for (const skill of manifest.skills) {
@@ -18,6 +18,19 @@ export function planRevert(manifest, detectedAgents, home) {
     }
     return actions;
 }
+export function planRevertAll(manifest, home) {
+    const actions = [];
+    for (const skill of manifest.skills) {
+        for (const agentId of skill.agents) {
+            const agent = AGENT_REGISTRY_BY_ID[agentId];
+            if (!agent)
+                continue;
+            const target = resolveAgentSkillPath(agent, skill.name, home);
+            actions.push({ skill: skill.name, agent: agentId, target });
+        }
+    }
+    return actions;
+}
 export async function executeRevert(actions, dryRun, verbose) {
     let succeeded = 0;
     let skipped = 0;
@@ -65,25 +78,3 @@ export async function executeRevert(actions, dryRun, verbose) {
     }
     return { succeeded, skipped };
 }
-async function isOwnedByInceptionEngine(targetPath, stat) {
-    if (stat.isSymbolicLink()) {
-        try {
-            const linkTarget = await readlink(targetPath);
-            const resolved = path.resolve(path.dirname(targetPath), linkTarget);
-            await access(path.join(resolved, "SKILL.md"));
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-    else {
-        try {
-            await access(path.join(targetPath, ".inception-totem"));
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-}

package/dist/index.js

@@ -7,7 +7,7 @@ import { AGENT_REGISTRY } from "./config/agents.js";
 import { resolveHome } from "./core/resolve.js";
 import { detectInstalledAgents } from "./core/detect.js";
 import { planDeploy, executeDeploy } from "./core/deploy.js";
-import { planRevert, executeRevert } from "./core/revert.js";
+import { planRevert, planRevertAll, executeRevert } from "./core/revert.js";
 import { UserError } from "./errors.js";
 import { logger, dryRunPrefix } from "./logger.js";
 const USAGE = `
@@ -93,26 +93,26 @@ async function main() {
     }
     const manifest = await loadManifest(options.directory);
     const home = resolveHome();
-    let detectedAgents;
-    if (options.agents) {
-        detectedAgents = options.agents;
-        if (options.verbose) {
-            logger.info(`Using specified agents: ${detectedAgents.join(", ")}`);
-        }
-    }
-    else {
-        detectedAgents = await detectInstalledAgents(home);
-        if (detectedAgents.length === 0) {
-            logger.info("No supported AI agents detected on this system.");
-            logger.info(`Install one of: ${AGENT_REGISTRY.map((a) => a.displayName).join(", ")}`);
-            return 0;
+    if (options.command === "deploy") {
+        let detectedAgents;
+        if (options.agents) {
+            detectedAgents = options.agents;
+            if (options.verbose) {
+                logger.info(`Using specified agents: ${detectedAgents.join(", ")}`);
+            }
         }
-        if (options.verbose) {
-            logger.info(`Detected agents: ${detectedAgents.join(", ")}`);
+        else {
+            detectedAgents = await detectInstalledAgents(home);
+            if (detectedAgents.length === 0) {
+                logger.info("No supported AI agents detected on this system.");
+                logger.info(`Install one of: ${AGENT_REGISTRY.map((a) => a.displayName).join(", ")}`);
+                return 0;
+            }
+            if (options.verbose) {
+                logger.info(`Detected agents: ${detectedAgents.join(", ")}`);
+            }
         }
-    }
-    if (options.command === "deploy") {
-        const actions = planDeploy(manifest, options.directory, detectedAgents, home);
+        const actions = await planDeploy(manifest, options.directory, detectedAgents, home);
         if (actions.length === 0) {
             logger.info("No skills to deploy for detected agents.");
             return 0;
@@ -129,9 +129,11 @@ async function main() {
         }
     }
     else {
-        const actions = planRevert(manifest, detectedAgents, home);
+        const actions = options.agents
+            ? planRevert(manifest, options.agents, home)
+            : planRevertAll(manifest, home);
         if (actions.length === 0) {
-            logger.info("No skills to revert for detected agents.");
+            logger.info("No skills to revert.");
             return 0;
         }
         logger.info(`${dryRunPrefix(options.dryRun)}Reverting ${actions.length} skill(s):`);

package/package.json

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