@kuznai/inception-engine 0.3.0 → 0.4.1

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,15 @@ 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.
 
-- **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.
+- **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.
 
-- **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`.
+- **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.
 
-> **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.
+- **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.
 
 ## Running with Privilege Escalation
 

package/dist/config/manifest.js

@@ -1,7 +1,7 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
-import { AGENT_IDS } from "../types.js";
 import { UserError } from "../errors.js";
+import { AGENT_IDS } from "../types.js";
 export async function loadManifest(directory) {
     const manifestPath = path.join(directory, "inception.json");
     let raw;
@@ -28,41 +28,45 @@ function validateManifest(data, filePath) {
     if (!Array.isArray(obj.skills)) {
         throw new UserError("MANIFEST_INVALID", `${filePath}: "skills" must be an array`);
     }
-    const skills = obj.skills.map((entry, i) => {
-        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-            throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}] must be an object`);
-        }
-        const skill = entry;
-        if (typeof skill.name !== "string" || skill.name.length === 0) {
-            throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].name must be a non-empty string`);
-        }
-        const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-        if (!SAFE_NAME_RE.test(skill.name)) {
-            throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].name must contain only letters, digits, hyphens, underscores, and dots, and must not start with a dot`);
-        }
-        if (typeof skill.path !== "string" || skill.path.length === 0) {
-            throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].path must be a non-empty string`);
-        }
-        if (path.isAbsolute(skill.path)) {
-            throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].path must be a relative path`);
-        }
-        if (!Array.isArray(skill.agents) || skill.agents.length === 0) {
-            throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].agents must be a non-empty array`);
-        }
-        for (const agent of skill.agents) {
-            if (!AGENT_IDS.includes(agent)) {
-                throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].agents contains unknown agent "${agent}". Valid agents: ${AGENT_IDS.join(", ")}`);
-            }
-        }
-        return {
-            name: skill.name,
-            path: skill.path,
-            agents: skill.agents,
-        };
-    });
+    const skills = obj.skills.map((entry, i) => validateSkillEntry(entry, i, filePath));
     return {
         skills,
         mcpServers: Array.isArray(obj.mcpServers) ? obj.mcpServers : [],
         agentRules: Array.isArray(obj.agentRules) ? obj.agentRules : [],
     };
 }
+const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+function validateSkillEntry(entry, i, filePath) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}] must be an object`);
+    }
+    const skill = entry;
+    if (typeof skill.name !== "string" || skill.name.length === 0) {
+        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].name must be a non-empty string`);
+    }
+    if (!SAFE_NAME_RE.test(skill.name)) {
+        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].name must contain only letters, digits, hyphens, underscores, and dots, and must not start with a dot`);
+    }
+    if (typeof skill.path !== "string" || skill.path.length === 0) {
+        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].path must be a non-empty string`);
+    }
+    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`);
+    }
+    for (const agent of skill.agents) {
+        if (!AGENT_IDS.includes(agent)) {
+            throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].agents contains unknown agent "${agent}". Valid agents: ${AGENT_IDS.join(", ")}`);
+        }
+    }
+    return {
+        name: skill.name,
+        path: skill.path,
+        agents: skill.agents,
+    };
+}

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,24 @@
-import { access, lstat, mkdir, symlink, cp, unlink, rm, writeFile } from "node:fs/promises";
+import { access, cp, lstat, mkdir, realpath, rename, rm, symlink, unlink, } 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";
+import { getDeployMethod, resolveAgentSkillPath } from "./resolve.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)) {
-            throw new UserError("DEPLOY_FAILED", `Skill path "${skill.path}" resolves outside the repository root: ${source}`);
-        }
+        await validateSourcePath(source, skill.path, resolvedSourceDir, realRoot);
         for (const agentId of skill.agents) {
             if (!detectedAgents.includes(agentId))
                 continue;
@@ -20,7 +26,13 @@ export function planDeploy(manifest, sourceDir, detectedAgents, home) {
             if (!agent)
                 continue;
             const target = resolveAgentSkillPath(agent, skill.name, home);
-            actions.push({ skill: skill.name, agent: agentId, source, target, method });
+            actions.push({
+                skill: skill.name,
+                agent: agentId,
+                source,
+                target,
+                method,
+            });
         }
     }
     return actions;
@@ -48,19 +60,7 @@ export async function executeDeploy(actions, dryRun, verbose) {
             continue;
         }
         try {
-            await removeExisting(action.target, verbose);
-            await mkdir(path.dirname(action.target), { recursive: true });
-            if (action.method === "symlink") {
-                await symlink(action.source, action.target, "dir");
-            }
-            else {
-                await cp(action.source, action.target, { recursive: true });
-                await writeFile(path.join(action.target, ".inception-totem"), "inception-engine\n");
-            }
-            logger.ok(label);
-            if (verbose) {
-                logger.detail(`${action.method}: ${action.source} -> ${action.target}`);
-            }
+            await executeDeployAction(action, verbose);
             succeeded++;
         }
         catch (err) {
@@ -71,24 +71,111 @@ export async function executeDeploy(actions, dryRun, verbose) {
     }
     return { succeeded, failed };
 }
-async function removeExisting(targetPath, verbose) {
+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)) {
+            throw new UserError("DEPLOY_FAILED", `Skill path "${skillPath}" 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
+    }
+}
+async function assertTargetAbsent(targetPath) {
+    try {
+        await lstat(targetPath);
+        throw new Error(`Target path appeared unexpectedly after backup: ${targetPath}`);
+    }
+    catch (err) {
+        if (err instanceof Error && err.message.startsWith("Target path appeared"))
+            throw err;
+        // ENOENT is expected — target should not exist after backup
+    }
+}
+async function createDeployTarget(action) {
+    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,
+        });
+    }
+}
+async function executeDeployAction(action, verbose) {
+    const label = `${action.skill} -> ${action.agent}`;
+    const backupPath = await backupExisting(action.target, verbose);
+    await mkdir(path.dirname(action.target), { recursive: true });
+    try {
+        await assertTargetAbsent(action.target);
+        await createDeployTarget(action);
+    }
+    catch (createErr) {
+        if (backupPath) {
+            try {
+                await rename(backupPath, action.target);
+            }
+            catch {
+                // Best-effort rollback
+            }
+        }
+        throw createErr;
+    }
+    if (backupPath) {
+        await removeTarget(backupPath);
+    }
+    logger.ok(label);
+    if (verbose) {
+        logger.detail(`${action.method}: ${action.source} -> ${action.target}`);
+    }
+}
+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/detect.js

@@ -1,5 +1,5 @@
-import { access } from "node:fs/promises";
 import { execFile } from "node:child_process";
+import { access } from "node:fs/promises";
 import { promisify } from "node:util";
 import { AGENT_REGISTRY } from "../config/agents.js";
 import { resolveAgentDetectPath } from "./resolve.js";
@@ -19,7 +19,9 @@ async function isAgentInstalled(agent, home) {
         await access(detectPath);
         return true;
     }
-    catch { }
+    catch {
+        // path does not exist — fall through to binary detection
+    }
     if (agent.detectBinary) {
         return isBinaryInPath(agent.detectBinary);
     }

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, chmod, readFile, readlink, writeFile } 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/resolve.js

@@ -7,41 +7,58 @@ export function resolveHome() {
     if (process.platform === "win32") {
         return os.homedir();
     }
-    const sudoUser = process.env["SUDO_USER"];
+    const sudoUser = process.env.SUDO_USER;
     if (sudoUser) {
         return lookupHomeForUser(sudoUser);
     }
     return os.homedir();
 }
 export function lookupHomeForUserWith(username, platform, execFileFn, readFileFn) {
-    // Method 1: getent passwd (Linux/POSIX — handles LDAP, NIS, local via NSS)
     if (platform !== "darwin") {
-        try {
-            const out = execFileFn("getent", ["passwd", username], {
-                encoding: "utf8",
-                stdio: ["ignore", "pipe", "ignore"],
-            }).trim();
-            const home = out.split(":")[5];
-            if (typeof home === "string" && home.startsWith("/"))
-                return home;
-        }
-        catch {
-            // getent unavailable or user not found — try next method
-        }
+        const home = lookupViaGetent(username, execFileFn);
+        if (home)
+            return home;
     }
-    // Method 2: dscl (macOS directory services)
     if (platform === "darwin") {
-        try {
-            const out = execFileFn("dscl", [".", "-read", `/Users/${username}`, "NFSHomeDirectory"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
-            const home = out.replace(/^NFSHomeDirectory:\s*/, "").trim();
-            if (home.startsWith("/"))
-                return home;
-        }
-        catch {
-            // dscl unavailable or user record not found — try next method
-        }
+        const home = lookupViaDscl(username, execFileFn);
+        if (home)
+            return home;
     }
-    // Method 3: parse /etc/passwd directly (universal POSIX fallback)
+    const home = lookupViaEtcPasswd(username, readFileFn);
+    if (home)
+        return home;
+    throw new UserError("RESOLVE_FAILED", `Cannot determine home directory for user "${username}". ` +
+        `Tried getent, dscl, and /etc/passwd. ` +
+        `Run without sudo, or set HOME to the correct path before invoking with sudo.`);
+}
+function lookupViaGetent(username, execFileFn) {
+    try {
+        const out = execFileFn("getent", ["passwd", username], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+        const home = out.split(":")[5];
+        if (typeof home === "string" && home.startsWith("/"))
+            return home;
+    }
+    catch {
+        // getent unavailable or user not found
+    }
+    return null;
+}
+function lookupViaDscl(username, execFileFn) {
+    try {
+        const out = execFileFn("dscl", [".", "-read", `/Users/${username}`, "NFSHomeDirectory"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+        const home = out.replace(/^NFSHomeDirectory:\s*/, "").trim();
+        if (home.startsWith("/"))
+            return home;
+    }
+    catch {
+        // dscl unavailable or user record not found
+    }
+    return null;
+}
+function lookupViaEtcPasswd(username, readFileFn) {
     try {
         const passwd = readFileFn("/etc/passwd", "utf8");
         for (const line of passwd.split("\n")) {
@@ -54,11 +71,9 @@ export function lookupHomeForUserWith(username, platform, execFileFn, readFileFn
         }
     }
     catch {
-        // /etc/passwd unavailable — fall through to error
+        // /etc/passwd unavailable
     }
-    throw new UserError("RESOLVE_FAILED", `Cannot determine home directory for user "${username}". ` +
-        `Tried getent, dscl, and /etc/passwd. ` +
-        `Run without sudo, or set HOME to the correct path before invoking with sudo.`);
+    return null;
 }
 function lookupHomeForUser(username) {
     return lookupHomeForUserWith(username, process.platform, execFileSync, readFileSync);
@@ -82,7 +97,7 @@ export function resolveAgentDetectPath(agent, home) {
     return resolveAgentDetectPathFor(agent, home, getPlatformKey());
 }
 function resolvePlaceholders(segments, skillName, home) {
-    const appdata = process.env["APPDATA"] ?? path.join(home, "AppData", "Roaming");
+    const appdata = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
     const resolved = segments.map((seg) => seg
         .replace("{home}", home)
         .replace("{name}", skillName)

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 { lstat, rm, unlink } from "node:fs/promises";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
-import { resolveAgentSkillPath } from "./resolve.js";
 import { logger } from "../logger.js";
+import { isOwnedByInceptionEngine } from "./ownership.js";
+import { resolveAgentSkillPath } from "./resolve.js";
 export function planRevert(manifest, detectedAgents, home) {
     const actions = [];
     for (const skill of manifest.skills) {
@@ -18,72 +18,70 @@ 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;
     for (const action of actions) {
-        const label = `${action.skill} -> ${action.agent}`;
-        let stat;
-        try {
-            stat = await lstat(action.target);
-        }
-        catch {
-            logger.skip(label, "(not found, skipping)");
-            skipped++;
-            continue;
-        }
-        if (!(await isOwnedByInceptionEngine(action.target, stat))) {
-            logger.warn(label, `skipping: ${action.target} does not have inception-engine ownership proof — not managed by inception-engine`);
+        const result = await executeRevertAction(action, dryRun, verbose);
+        if (result === "skip") {
             skipped++;
-            continue;
         }
-        if (dryRun) {
-            logger.plan(label);
-            if (verbose) {
-                logger.detail(`would remove: ${action.target}`);
-            }
+        else {
             succeeded++;
-            continue;
-        }
-        try {
-            if (stat.isSymbolicLink()) {
-                await unlink(action.target);
-            }
-            else {
-                await rm(action.target, { recursive: true });
-            }
-            logger.ok(label);
-            if (verbose) {
-                logger.detail(`removed: ${action.target}`);
-            }
-            succeeded++;
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            logger.fail(label, msg);
         }
     }
     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;
+async function executeRevertAction(action, dryRun, verbose) {
+    const label = `${action.skill} -> ${action.agent}`;
+    let stat;
+    try {
+        stat = await lstat(action.target);
+    }
+    catch {
+        logger.skip(label, "(not found, skipping)");
+        return "skip";
+    }
+    if (!(await isOwnedByInceptionEngine(action.target, stat))) {
+        logger.warn(label, `skipping: ${action.target} does not have inception-engine ownership proof — not managed by inception-engine`);
+        return "skip";
+    }
+    if (dryRun) {
+        logger.plan(label);
+        if (verbose) {
+            logger.detail(`would remove: ${action.target}`);
         }
+        return "ok";
     }
-    else {
-        try {
-            await access(path.join(targetPath, ".inception-totem"));
-            return true;
+    try {
+        if (stat.isSymbolicLink()) {
+            await unlink(action.target);
+        }
+        else {
+            await rm(action.target, { recursive: true });
         }
-        catch {
-            return false;
+        logger.ok(label);
+        if (verbose) {
+            logger.detail(`removed: ${action.target}`);
         }
+        return "ok";
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.fail(label, msg);
+        return "skip";
     }
 }

package/dist/index.js

@@ -1,15 +1,15 @@
 #!/usr/bin/env node
 import path from "node:path";
 import { parseArgs } from "node:util";
-import { AGENT_IDS } from "./types.js";
-import { loadManifest } from "./config/manifest.js";
 import { AGENT_REGISTRY } from "./config/agents.js";
-import { resolveHome } from "./core/resolve.js";
+import { loadManifest } from "./config/manifest.js";
+import { executeDeploy, planDeploy } from "./core/deploy.js";
 import { detectInstalledAgents } from "./core/detect.js";
-import { planDeploy, executeDeploy } from "./core/deploy.js";
-import { planRevert, executeRevert } from "./core/revert.js";
+import { resolveHome } from "./core/resolve.js";
+import { executeRevert, planRevert, planRevertAll } from "./core/revert.js";
 import { UserError } from "./errors.js";
-import { logger, dryRunPrefix } from "./logger.js";
+import { dryRunPrefix, logger } from "./logger.js";
+import { AGENT_IDS } from "./types.js";
 const USAGE = `
 inception-engine - Deploy AI agent skills
 
@@ -30,7 +30,14 @@ Supported agents:
 function parseCLI(argv) {
     const args = argv.slice(2);
     if (args.length === 0) {
-        return { command: "help", directory: "", dryRun: false, agents: null, verbose: false, debug: false };
+        return {
+            command: "help",
+            directory: "",
+            dryRun: false,
+            agents: null,
+            verbose: false,
+            debug: false,
+        };
     }
     let parsed;
     try {
@@ -39,10 +46,10 @@ function parseCLI(argv) {
             allowPositionals: true,
             options: {
                 "dry-run": { type: "boolean", default: false },
-                "verbose": { type: "boolean", default: false },
-                "debug": { type: "boolean", default: false },
-                "help": { type: "boolean", default: false },
-                "agents": { type: "string" },
+                verbose: { type: "boolean", default: false },
+                debug: { type: "boolean", default: false },
+                help: { type: "boolean", default: false },
+                agents: { type: "string" },
             },
         });
     }
@@ -51,7 +58,14 @@ function parseCLI(argv) {
     }
     const { values, positionals } = parsed;
     if (values.help) {
-        return { command: "help", directory: "", dryRun: false, agents: null, verbose: false, debug: false };
+        return {
+            command: "help",
+            directory: "",
+            dryRun: false,
+            agents: null,
+            verbose: false,
+            debug: false,
+        };
     }
     let command = "deploy";
     let pos = positionals;
@@ -93,6 +107,12 @@ async function main() {
     }
     const manifest = await loadManifest(options.directory);
     const home = resolveHome();
+    if (options.command === "deploy") {
+        return runDeploy(options, manifest, home);
+    }
+    return runRevert(options, manifest, home);
+}
+async function runDeploy(options, manifest, home) {
     let detectedAgents;
     if (options.agents) {
         detectedAgents = options.agents;
@@ -111,37 +131,36 @@ async function main() {
             logger.info(`Detected agents: ${detectedAgents.join(", ")}`);
         }
     }
-    if (options.command === "deploy") {
-        const actions = planDeploy(manifest, options.directory, detectedAgents, home);
-        if (actions.length === 0) {
-            logger.info("No skills to deploy for detected agents.");
-            return 0;
-        }
-        logger.info(`${dryRunPrefix(options.dryRun)}Deploying ${actions.length} skill(s):`);
-        const { succeeded, failed } = await executeDeploy(actions, options.dryRun, options.verbose);
-        logger.info("");
-        if (failed.length > 0) {
-            logger.info(`${succeeded} succeeded, ${failed.length} failed`);
-            return 1;
-        }
-        else {
-            logger.info(`${succeeded} skill(s) deployed${options.dryRun ? " (dry-run)" : ""}`);
-        }
+    const actions = await planDeploy(manifest, options.directory, detectedAgents, home);
+    if (actions.length === 0) {
+        logger.info("No skills to deploy for detected agents.");
+        return 0;
     }
-    else {
-        const actions = planRevert(manifest, detectedAgents, home);
-        if (actions.length === 0) {
-            logger.info("No skills to revert for detected agents.");
-            return 0;
-        }
-        logger.info(`${dryRunPrefix(options.dryRun)}Reverting ${actions.length} skill(s):`);
-        const { succeeded, skipped } = await executeRevert(actions, options.dryRun, options.verbose);
-        logger.info("");
-        const parts = [`${succeeded} removed`];
-        if (skipped > 0)
-            parts.push(`${skipped} skipped`);
-        logger.info(`${parts.join(", ")}${options.dryRun ? " (dry-run)" : ""}`);
+    logger.info(`${dryRunPrefix(options.dryRun)}Deploying ${actions.length} skill(s):`);
+    const { succeeded, failed } = await executeDeploy(actions, options.dryRun, options.verbose);
+    logger.info("");
+    if (failed.length > 0) {
+        logger.info(`${succeeded} succeeded, ${failed.length} failed`);
+        return 1;
+    }
+    logger.info(`${succeeded} skill(s) deployed${options.dryRun ? " (dry-run)" : ""}`);
+    return 0;
+}
+async function runRevert(options, manifest, home) {
+    const actions = options.agents
+        ? planRevert(manifest, options.agents, home)
+        : planRevertAll(manifest, home);
+    if (actions.length === 0) {
+        logger.info("No skills to revert.");
+        return 0;
     }
+    logger.info(`${dryRunPrefix(options.dryRun)}Reverting ${actions.length} skill(s):`);
+    const { succeeded, skipped } = await executeRevert(actions, options.dryRun, options.verbose);
+    logger.info("");
+    const parts = [`${succeeded} removed`];
+    if (skipped > 0)
+        parts.push(`${skipped} skipped`);
+    logger.info(`${parts.join(", ")}${options.dryRun ? " (dry-run)" : ""}`);
     return 0;
 }
 const USER_ERROR_EXIT = {

package/dist/logger.js

@@ -57,5 +57,5 @@ export const logger = createLogger();
 export function dryRunPrefix(dryRun) {
     if (!dryRun)
         return "";
-    return Boolean(process.stdout.isTTY) ? `\x1b[36m[dry-run]\x1b[0m ` : `[dry-run] `;
+    return process.stdout.isTTY ? `\x1b[36m[dry-run]\x1b[0m ` : `[dry-run] `;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",
@@ -36,12 +36,15 @@
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
+    "format": "biome format --write .",
+    "lint": "biome lint . --max-diagnostics none",
     "dev": "node src/index.ts",
     "test": "node --test test/*.test.ts",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run build"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
     "@types/node": "^25.5.0",
-    "typescript": "^5.8.0"
+    "typescript": "^6.0.2"
   }
 }