@kuznai/inception-engine 0.2.4 → 0.4.0

package/README.md

@@ -5,7 +5,7 @@ Plant skills directly into the minds of your installed AI coding agents — Clau
 ## Quick Start
 
 ```bash
-npx inception-engine <directory>
+npx @kuznai/inception-engine <directory>
 ```
 
 Where `<directory>` is a repo (or subdirectory) containing an `inception.json` manifest and skill files.
@@ -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
 
@@ -151,6 +153,20 @@ If an agent isn't detected, its skills are skipped. Use `--agents` to override d
 | Linux | Symlink | Source changes are reflected immediately |
 | Windows | Copy | Source must be re-deployed after changes |
 
+### Ownership Tracking and Safe Revert
+
+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.
+
+- **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.
+
+- **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 `.inception-totem` was introduced must be re-deployed before `revert` can remove them.
+
 ## Running with Privilege Escalation
 
 The tool works without elevated privileges. If run with `sudo` on POSIX systems, it looks up the real user's home directory from the OS directory services (`getent passwd` on Linux, `dscl` on macOS, `/etc/passwd` as a universal fallback) so skills are deployed to the correct location regardless of where home directories are stored — standard `/home/<user>`, LDAP/NIS paths, enterprise layouts, or otherwise.
@@ -159,6 +175,22 @@ If the real home cannot be determined, the tool exits with an error rather than
 
 On Windows, `os.homedir()` correctly resolves even in elevated PowerShell or cmd.
 
+## Security & Compatibility Notes
+
+### SUDO_USER handling
+
+When run under `sudo` on POSIX, `SUDO_USER` is read as an advisory signal to identify the real user. The username is validated through OS directory services (`getent passwd` on Linux, `dscl` on macOS, `/etc/passwd` as a fallback) — it is never used as a raw path. This is standard practice for sudo-aware CLI tools.
+
+Automation edge case: if the tool runs inside a pipeline where `SUDO_USER` has been set externally in the environment before the process starts, the tool will look up that username's home directory. To avoid this in automation, either run without `sudo` or set `HOME` explicitly before invoking the tool.
+
+### Windows %APPDATA% fallback
+
+On Windows, `%APPDATA%` is used to locate agent config directories (currently only OpenCode). When `%APPDATA%` is unset — which can happen in some service or minimal sandbox contexts — the tool falls back to `AppData\Roaming` under the resolved home directory. This fallback is intentional and correct for interactive user sessions and elevated PowerShell. Running as a Windows service account is outside the supported use case for this tool.
+
+### Future: mixed asset layouts on Windows
+
+Windows deployment currently uses directory-level copy (one `cp -r` per skill). This works correctly for the present skill model where each skill is a single directory. If file-based assets or mixed (file + directory) skill layouts are added in the future, the copy strategy in `src/core/deploy.ts` will need revisiting — including `.inception-totem` placement and revert logic.
+
 ## Requirements
 
 - Node.js >= 23.6.0

package/dist/config/agents.d.ts

@@ -1,2 +1,3 @@
-import type { AgentConfig } from "../types.ts";
+import type { AgentConfig, AgentId } from "../types.ts";
 export declare const AGENT_REGISTRY: readonly AgentConfig[];
+export declare const AGENT_REGISTRY_BY_ID: Readonly<Record<AgentId, AgentConfig>>;

package/dist/config/agents.js

@@ -3,12 +3,12 @@ export const AGENT_REGISTRY = [
         id: "claude-code",
         displayName: "Claude Code",
         skills: {
-            posix: "{home}/.claude/skills/{name}",
-            windows: "{home}\\.claude\\skills\\{name}",
+            posix: ["{home}", ".claude", "skills", "{name}"],
+            windows: ["{home}", ".claude", "skills", "{name}"],
         },
         detectPaths: {
-            posix: "{home}/.claude",
-            windows: "{home}\\.claude",
+            posix: ["{home}", ".claude"],
+            windows: ["{home}", ".claude"],
         },
         detectBinary: "claude",
     },
@@ -16,12 +16,12 @@ export const AGENT_REGISTRY = [
         id: "codex",
         displayName: "OpenAI Codex",
         skills: {
-            posix: "{home}/.codex/skills/{name}",
-            windows: "{home}\\.codex\\skills\\{name}",
+            posix: ["{home}", ".codex", "skills", "{name}"],
+            windows: ["{home}", ".codex", "skills", "{name}"],
         },
         detectPaths: {
-            posix: "{home}/.codex",
-            windows: "{home}\\.codex",
+            posix: ["{home}", ".codex"],
+            windows: ["{home}", ".codex"],
         },
         detectBinary: "codex",
     },
@@ -29,12 +29,12 @@ export const AGENT_REGISTRY = [
         id: "gemini-cli",
         displayName: "Gemini CLI",
         skills: {
-            posix: "{home}/.gemini/skills/{name}",
-            windows: "{home}\\.gemini\\skills\\{name}",
+            posix: ["{home}", ".gemini", "skills", "{name}"],
+            windows: ["{home}", ".gemini", "skills", "{name}"],
         },
         detectPaths: {
-            posix: "{home}/.gemini",
-            windows: "{home}\\.gemini",
+            posix: ["{home}", ".gemini"],
+            windows: ["{home}", ".gemini"],
         },
         detectBinary: "gemini",
     },
@@ -42,12 +42,12 @@ export const AGENT_REGISTRY = [
         id: "antigravity",
         displayName: "Antigravity",
         skills: {
-            posix: "{home}/.gemini/antigravity/skills/{name}",
-            windows: "{home}\\.gemini\\antigravity\\skills\\{name}",
+            posix: ["{home}", ".gemini", "antigravity", "skills", "{name}"],
+            windows: ["{home}", ".gemini", "antigravity", "skills", "{name}"],
         },
         detectPaths: {
-            posix: "{home}/.gemini/antigravity",
-            windows: "{home}\\.gemini\\antigravity",
+            posix: ["{home}", ".gemini", "antigravity"],
+            windows: ["{home}", ".gemini", "antigravity"],
         },
         detectBinary: null,
     },
@@ -55,12 +55,12 @@ export const AGENT_REGISTRY = [
         id: "opencode",
         displayName: "OpenCode",
         skills: {
-            posix: "{home}/.config/opencode/skills/{name}",
-            windows: "{appdata}\\opencode\\skills\\{name}",
+            posix: ["{home}", ".config", "opencode", "skills", "{name}"],
+            windows: ["{appdata}", "opencode", "skills", "{name}"],
         },
         detectPaths: {
-            posix: "{home}/.config/opencode",
-            windows: "{appdata}\\opencode",
+            posix: ["{home}", ".config", "opencode"],
+            windows: ["{appdata}", "opencode"],
         },
         detectBinary: "opencode",
     },
@@ -68,13 +68,14 @@ export const AGENT_REGISTRY = [
         id: "github-copilot",
         displayName: "GitHub Copilot",
         skills: {
-            posix: "{home}/.copilot/skills/{name}",
-            windows: "{home}\\.copilot\\skills\\{name}",
+            posix: ["{home}", ".copilot", "skills", "{name}"],
+            windows: ["{home}", ".copilot", "skills", "{name}"],
         },
         detectPaths: {
-            posix: "{home}/.copilot",
-            windows: "{home}\\.copilot",
+            posix: ["{home}", ".copilot"],
+            windows: ["{home}", ".copilot"],
         },
         detectBinary: "github-copilot",
     },
 ];
+export const AGENT_REGISTRY_BY_ID = Object.fromEntries(AGENT_REGISTRY.map((a) => [a.id, a]));

package/dist/config/manifest.d.ts

@@ -1,2 +1,2 @@
 import type { Manifest } from "../types.ts";
-export declare function loadManifest(directory: string): Manifest;
+export declare function loadManifest(directory: string): Promise<Manifest>;

package/dist/config/manifest.js

@@ -1,57 +1,60 @@
-import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { AGENT_IDS } from "../types.js";
 import { UserError } from "../errors.js";
-export function loadManifest(directory) {
+export async function loadManifest(directory) {
     const manifestPath = path.join(directory, "inception.json");
     let raw;
     try {
-        raw = readFileSync(manifestPath, "utf-8");
+        raw = await readFile(manifestPath, "utf-8");
     }
     catch {
-        throw new UserError(`No inception.json found in ${directory}. Are you pointing to the right repo?`);
+        throw new UserError("MANIFEST_INVALID", `No inception.json found in ${directory}. Are you pointing to the right repo?`);
     }
     let parsed;
     try {
         parsed = JSON.parse(raw);
     }
     catch {
-        throw new UserError(`Invalid JSON in ${manifestPath}`);
+        throw new UserError("MANIFEST_INVALID", `Invalid JSON in ${manifestPath}`);
     }
     return validateManifest(parsed, manifestPath);
 }
 function validateManifest(data, filePath) {
     if (typeof data !== "object" || data === null || Array.isArray(data)) {
-        throw new UserError(`${filePath}: manifest must be a JSON object`);
+        throw new UserError("MANIFEST_INVALID", `${filePath}: manifest must be a JSON object`);
     }
     const obj = data;
     if (!Array.isArray(obj.skills)) {
-        throw new UserError(`${filePath}: "skills" must be an array`);
+        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(`${filePath}: skills[${i}] must be an object`);
+            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(`${filePath}: skills[${i}].name must be a non-empty string`);
+            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(`${filePath}: skills[${i}].name must contain only letters, digits, hyphens, underscores, and dots, and must not start with a dot`);
+            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(`${filePath}: skills[${i}].path must be a non-empty string`);
+            throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].path must be a non-empty string`);
         }
         if (path.isAbsolute(skill.path)) {
-            throw new UserError(`${filePath}: skills[${i}].path must be a relative 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(`${filePath}: skills[${i}].agents must be a non-empty array`);
+            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(`${filePath}: skills[${i}].agents contains unknown agent "${agent}". Valid agents: ${AGENT_IDS.join(", ")}`);
+                throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].agents contains unknown agent "${agent}". Valid agents: ${AGENT_IDS.join(", ")}`);
             }
         }
         return {

package/dist/core/deploy.d.ts

@@ -1,9 +1,9 @@
 import type { AgentId, DeployAction, Manifest } from "../types.ts";
-export declare function planDeploy(manifest: Manifest, sourceDir: string, detectedAgents: AgentId[], home: string): DeployAction[];
-export declare function executeDeploy(actions: DeployAction[], dryRun: boolean, verbose: boolean): {
+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<{
         action: DeployAction;
         error: string;
     }>;
-};
+}>;

package/dist/core/deploy.js

@@ -1,21 +1,41 @@
-import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync, cpSync, unlinkSync, } from "node:fs";
+import { access, lstat, mkdir, symlink, cp, unlink, rm, rename, realpath } from "node:fs/promises";
 import path from "node:path";
-import { AGENT_REGISTRY } from "../config/agents.js";
+import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { resolveAgentSkillPath, getDeployMethod } from "./resolve.js";
 import { UserError } from "../errors.js";
-export function planDeploy(manifest, sourceDir, detectedAgents, home) {
+import { logger } from "../logger.js";
+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)) {
-            throw new UserError(`Skill path "${skill.path}" resolves outside the repository root: ${source}`);
+        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;
-            const agent = AGENT_REGISTRY.find((a) => a.id === agentId);
+            const agent = AGENT_REGISTRY_BY_ID[agentId];
             if (!agent)
                 continue;
             const target = resolveAgentSkillPath(agent, skill.name, home);
@@ -24,69 +44,113 @@ export function planDeploy(manifest, sourceDir, detectedAgents, home) {
     }
     return actions;
 }
-export function executeDeploy(actions, dryRun, verbose) {
+export async function executeDeploy(actions, dryRun, verbose) {
     let succeeded = 0;
     const failed = [];
     for (const action of actions) {
         const label = `${action.skill} -> ${action.agent}`;
-        if (!existsSync(action.source)) {
+        try {
+            await access(action.source);
+        }
+        catch {
             const msg = `Source not found: ${action.source}`;
             failed.push({ action, error: msg });
-            console.error(`  \x1b[31m✗\x1b[0m ${label}: ${msg}`);
+            logger.fail(label, msg);
             continue;
         }
         if (dryRun) {
-            console.log(`  \x1b[36m○\x1b[0m ${label}`);
+            logger.plan(label);
             if (verbose) {
-                console.log(`    ${action.method}: ${action.source} -> ${action.target}`);
+                logger.detail(`${action.method}: ${action.source} -> ${action.target}`);
             }
             succeeded++;
             continue;
         }
         try {
-            removeExisting(action.target, verbose);
-            mkdirSync(path.dirname(action.target), { recursive: true });
-            if (action.method === "symlink") {
-                symlinkSync(action.source, action.target, "dir");
+            const backupPath = await backupExisting(action.target, verbose);
+            await mkdir(path.dirname(action.target), { recursive: true });
+            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 {
-                cpSync(action.source, action.target, { recursive: true });
+            // Success: remove backup
+            if (backupPath) {
+                await removeTarget(backupPath);
             }
-            console.log(`  \x1b[32m✓\x1b[0m ${label}`);
+            logger.ok(label);
             if (verbose) {
-                console.log(`    ${action.method}: ${action.source} -> ${action.target}`);
+                logger.detail(`${action.method}: ${action.source} -> ${action.target}`);
             }
             succeeded++;
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
             failed.push({ action, error: msg });
-            console.error(`  \x1b[31m✗\x1b[0m ${label}: ${msg}`);
+            logger.fail(label, msg);
         }
     }
     return { succeeded, failed };
 }
-function removeExisting(targetPath, verbose) {
-    if (!existsSync(targetPath) && !isSymlink(targetPath))
-        return;
-    if (isSymlink(targetPath)) {
-        if (verbose) {
-            console.log(`    removing existing symlink: ${targetPath}`);
-        }
-        unlinkSync(targetPath);
+async function backupExisting(targetPath, verbose) {
+    let stat;
+    try {
+        stat = await lstat(targetPath);
     }
-    else {
-        if (verbose) {
-            console.log(`    \x1b[33m!\x1b[0m replacing existing directory: ${targetPath}`);
-        }
-        rmSync(targetPath, { recursive: true });
+    catch {
+        return null;
     }
-}
-function isSymlink(p) {
+    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 {
-        return lstatSync(p).isSymbolicLink();
+        await lstat(backupPath);
+        await removeTarget(backupPath);
     }
     catch {
-        return false;
+        // 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()) {
+        await unlink(targetPath);
+    }
+    else {
+        await rm(targetPath, { recursive: true });
     }
 }

package/dist/core/detect.d.ts

@@ -1,2 +1,2 @@
 import type { AgentId } from "../types.ts";
-export declare function detectInstalledAgents(home: string): AgentId[];
+export declare function detectInstalledAgents(home: string): Promise<AgentId[]>;

package/dist/core/detect.js

@@ -1,33 +1,66 @@
-import { existsSync } from "node:fs";
-import { execFileSync } from "node:child_process";
+import { access } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
 import { AGENT_REGISTRY } from "../config/agents.js";
 import { resolveAgentDetectPath } from "./resolve.js";
-export function detectInstalledAgents(home) {
+const execFileAsync = promisify(execFile);
+export async function detectInstalledAgents(home) {
     const detected = [];
     for (const agent of AGENT_REGISTRY) {
-        if (isAgentInstalled(agent, home)) {
+        if (await isAgentInstalled(agent, home)) {
             detected.push(agent.id);
         }
     }
     return detected;
 }
-function isAgentInstalled(agent, home) {
+async function isAgentInstalled(agent, home) {
     const detectPath = resolveAgentDetectPath(agent, home);
-    if (existsSync(detectPath)) {
+    try {
+        await access(detectPath);
         return true;
     }
+    catch { }
     if (agent.detectBinary) {
         return isBinaryInPath(agent.detectBinary);
     }
     return false;
 }
-function isBinaryInPath(binary) {
-    const command = process.platform === "win32" ? "where.exe" : "which";
+async function isBinaryInPath(binary) {
+    if (process.platform === "win32") {
+        try {
+            await execFileAsync("where.exe", [binary]);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    try {
+        await execFileAsync("which", [binary]);
+        return true;
+    }
+    catch (err) {
+        // `which` itself is not installed — fall back to the POSIX shell built-in
+        if (isENOENT(err)) {
+            return isBinaryViaCommandV(binary);
+        }
+        return false;
+    }
+}
+// Used only when `which` is absent (e.g. minimal Alpine containers).
+// `command -v` is a POSIX shell built-in available wherever /bin/sh is.
+async function isBinaryViaCommandV(binary) {
     try {
-        execFileSync(command, [binary], { stdio: "ignore" });
+        // Pass binary as a positional arg ($1) to avoid any shell-injection risk.
+        await execFileAsync("sh", ["-c", 'command -v "$1"', "--", binary]);
         return true;
     }
     catch {
         return false;
     }
 }
+function isENOENT(err) {
+    return (typeof err === "object" &&
+        err !== null &&
+        err.code === "ENOENT");
+}

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/resolve.d.ts

@@ -1,6 +1,11 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
 import type { AgentConfig } from "../types.ts";
 export declare function resolveHome(): string;
+export declare function lookupHomeForUserWith(username: string, platform: NodeJS.Platform, execFileFn: typeof execFileSync, readFileFn: typeof readFileSync): string;
 export declare function getPlatformKey(): "posix" | "windows";
 export declare function getDeployMethod(): "symlink" | "copy";
+export declare function resolveAgentSkillPathFor(agent: AgentConfig, skillName: string, home: string, platform: "posix" | "windows"): string;
+export declare function resolveAgentDetectPathFor(agent: AgentConfig, home: string, platform: "posix" | "windows"): string;
 export declare function resolveAgentSkillPath(agent: AgentConfig, skillName: string, home: string): string;
 export declare function resolveAgentDetectPath(agent: AgentConfig, home: string): string;

package/dist/core/resolve.js

@@ -13,11 +13,11 @@ export function resolveHome() {
     }
     return os.homedir();
 }
-function lookupHomeForUser(username) {
+export function lookupHomeForUserWith(username, platform, execFileFn, readFileFn) {
     // Method 1: getent passwd (Linux/POSIX — handles LDAP, NIS, local via NSS)
-    if (process.platform !== "darwin") {
+    if (platform !== "darwin") {
         try {
-            const out = execFileSync("getent", ["passwd", username], {
+            const out = execFileFn("getent", ["passwd", username], {
                 encoding: "utf8",
                 stdio: ["ignore", "pipe", "ignore"],
             }).trim();
@@ -30,9 +30,9 @@ function lookupHomeForUser(username) {
         }
     }
     // Method 2: dscl (macOS directory services)
-    if (process.platform === "darwin") {
+    if (platform === "darwin") {
         try {
-            const out = execFileSync("dscl", [".", "-read", `/Users/${username}`, "NFSHomeDirectory"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim();
+            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;
@@ -43,7 +43,7 @@ function lookupHomeForUser(username) {
     }
     // Method 3: parse /etc/passwd directly (universal POSIX fallback)
     try {
-        const passwd = readFileSync("/etc/passwd", "utf8");
+        const passwd = readFileFn("/etc/passwd", "utf8");
         for (const line of passwd.split("\n")) {
             const parts = line.split(":");
             if (parts[0] === username) {
@@ -56,32 +56,36 @@ function lookupHomeForUser(username) {
     catch {
         // /etc/passwd unavailable — fall through to error
     }
-    throw new UserError(`Cannot determine home directory for user "${username}". ` +
+    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 lookupHomeForUser(username) {
+    return lookupHomeForUserWith(username, process.platform, execFileSync, readFileSync);
+}
 export function getPlatformKey() {
     return process.platform === "win32" ? "windows" : "posix";
 }
 export function getDeployMethod() {
     return process.platform === "win32" ? "copy" : "symlink";
 }
+export function resolveAgentSkillPathFor(agent, skillName, home, platform) {
+    return resolvePlaceholders(agent.skills[platform], skillName, home);
+}
+export function resolveAgentDetectPathFor(agent, home, platform) {
+    return resolvePlaceholders(agent.detectPaths[platform], "", home);
+}
 export function resolveAgentSkillPath(agent, skillName, home) {
-    const platform = getPlatformKey();
-    const template = agent.skills[platform];
-    return resolvePlaceholders(template, skillName, home);
+    return resolveAgentSkillPathFor(agent, skillName, home, getPlatformKey());
 }
 export function resolveAgentDetectPath(agent, home) {
-    const platform = getPlatformKey();
-    const template = agent.detectPaths[platform];
-    return resolvePlaceholders(template, "", home);
+    return resolveAgentDetectPathFor(agent, home, getPlatformKey());
 }
-function resolvePlaceholders(template, skillName, home) {
-    let result = template.replace("{home}", home);
-    result = result.replace("{name}", skillName);
-    if (result.includes("{appdata}")) {
-        const appdata = process.env["APPDATA"] ?? path.join(home, "AppData", "Roaming");
-        result = result.replace("{appdata}", appdata);
-    }
-    return result;
+function resolvePlaceholders(segments, skillName, home) {
+    const appdata = process.env["APPDATA"] ?? path.join(home, "AppData", "Roaming");
+    const resolved = segments.map((seg) => seg
+        .replace("{home}", home)
+        .replace("{name}", skillName)
+        .replace("{appdata}", appdata));
+    return path.join(...resolved);
 }

package/dist/core/revert.d.ts

@@ -1,6 +1,7 @@
 import type { AgentId, Manifest, RevertAction } from "../types.ts";
 export declare function planRevert(manifest: Manifest, detectedAgents: AgentId[], home: string): RevertAction[];
-export declare function executeRevert(actions: RevertAction[], dryRun: boolean, verbose: boolean): {
+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,13 +1,15 @@
-import { existsSync, lstatSync, unlinkSync, rmSync } from "node:fs";
-import { AGENT_REGISTRY } 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) {
         for (const agentId of skill.agents) {
             if (!detectedAgents.includes(agentId))
                 continue;
-            const agent = AGENT_REGISTRY.find((a) => a.id === agentId);
+            const agent = AGENT_REGISTRY_BY_ID[agentId];
             if (!agent)
                 continue;
             const target = resolveAgentSkillPath(agent, skill.name, home);
@@ -16,49 +18,63 @@ export function planRevert(manifest, detectedAgents, home) {
     }
     return actions;
 }
-export function executeRevert(actions, dryRun, verbose) {
+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}`;
-        if (!existsSync(action.target) && !isSymlink(action.target)) {
-            console.log(`  \x1b[33m-\x1b[0m ${label} (not found, skipping)`);
+        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`);
             skipped++;
             continue;
         }
         if (dryRun) {
-            console.log(`  \x1b[36m○\x1b[0m ${label}`);
+            logger.plan(label);
             if (verbose) {
-                console.log(`    would remove: ${action.target}`);
+                logger.detail(`would remove: ${action.target}`);
             }
             succeeded++;
             continue;
         }
         try {
-            if (isSymlink(action.target)) {
-                unlinkSync(action.target);
+            if (stat.isSymbolicLink()) {
+                await unlink(action.target);
             }
             else {
-                rmSync(action.target, { recursive: true });
+                await rm(action.target, { recursive: true });
             }
-            console.log(`  \x1b[32m✓\x1b[0m ${label}`);
+            logger.ok(label);
             if (verbose) {
-                console.log(`    removed: ${action.target}`);
+                logger.detail(`removed: ${action.target}`);
             }
             succeeded++;
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            console.error(`  \x1b[31m✗\x1b[0m ${label}: ${msg}`);
+            logger.fail(label, msg);
         }
     }
     return { succeeded, skipped };
 }
-function isSymlink(p) {
-    try {
-        return lstatSync(p).isSymbolicLink();
-    }
-    catch {
-        return false;
-    }
-}

package/dist/errors.d.ts

@@ -1,3 +1,5 @@
+export type ErrorCode = "INVALID_ARGS" | "MANIFEST_INVALID" | "DEPLOY_FAILED" | "RESOLVE_FAILED";
 export declare class UserError extends Error {
-    constructor(message: string);
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
 }

package/dist/errors.js

@@ -1,6 +1,8 @@
 export class UserError extends Error {
-    constructor(message) {
+    code;
+    constructor(code, message) {
         super(message);
         this.name = "UserError";
+        this.code = code;
     }
 }

package/dist/index.js

@@ -1,13 +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 { 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 = `
 inception-engine - Deploy AI agent skills
 
@@ -25,136 +27,148 @@ Options:
 Supported agents:
   ${AGENT_REGISTRY.map((a) => `${a.id} (${a.displayName})`).join(", ")}
 `.trim();
-function parseArgs(argv) {
+function parseCLI(argv) {
     const args = argv.slice(2);
-    if (args.length === 0 || args.includes("--help")) {
+    if (args.length === 0) {
+        return { command: "help", directory: "", dryRun: false, agents: null, verbose: false, debug: false };
+    }
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args,
+            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" },
+            },
+        });
+    }
+    catch (err) {
+        throw new UserError("INVALID_ARGS", err.message);
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
         return { command: "help", directory: "", dryRun: false, agents: null, verbose: false, debug: false };
     }
     let command = "deploy";
-    let directory = "";
-    let dryRun = false;
-    let agents = null;
-    let verbose = false;
-    let debug = false;
-    let i = 0;
-    if (args[0] === "revert") {
+    let pos = positionals;
+    if (pos[0] === "revert") {
         command = "revert";
-        i = 1;
+        pos = pos.slice(1);
     }
-    while (i < args.length) {
-        const arg = args[i];
-        if (arg === "--dry-run") {
-            dryRun = true;
-        }
-        else if (arg === "--verbose") {
-            verbose = true;
-        }
-        else if (arg === "--debug") {
-            debug = true;
-        }
-        else if (arg === "--agents") {
-            i++;
-            const next = args[i];
-            if (!next) {
-                throw new UserError("--agents requires a comma-separated list");
-            }
-            const ids = next.split(",").map((s) => s.trim());
-            for (const id of ids) {
-                if (!AGENT_IDS.includes(id)) {
-                    throw new UserError(`Unknown agent: "${id}". Valid agents: ${AGENT_IDS.join(", ")}`);
-                }
+    if (pos.length > 1) {
+        throw new UserError("INVALID_ARGS", `Unexpected argument: ${pos[1]}`);
+    }
+    const rawDir = pos[0];
+    if (!rawDir) {
+        throw new UserError("INVALID_ARGS", "Missing required <directory> argument");
+    }
+    let agents = null;
+    if (typeof values.agents === "string") {
+        const ids = values.agents.split(",").map((s) => s.trim());
+        for (const id of ids) {
+            if (!AGENT_IDS.includes(id)) {
+                throw new UserError("INVALID_ARGS", `Unknown agent: "${id}". Valid agents: ${AGENT_IDS.join(", ")}`);
             }
-            agents = ids;
-        }
-        else if (arg.startsWith("--")) {
-            throw new UserError(`Unknown option: ${arg}`);
-        }
-        else if (!directory) {
-            directory = arg;
-        }
-        else {
-            throw new UserError(`Unexpected argument: ${arg}`);
         }
-        i++;
+        agents = ids;
     }
-    if (!directory) {
-        throw new UserError("Missing required <directory> argument");
-    }
-    return { command, directory: path.resolve(directory), dryRun, agents, verbose, debug };
+    return {
+        command,
+        directory: path.resolve(rawDir),
+        dryRun: values["dry-run"],
+        agents,
+        verbose: values.verbose,
+        debug: values.debug,
+    };
 }
-function main() {
-    const options = parseArgs(process.argv);
+async function main() {
+    const options = parseCLI(process.argv);
     if (options.command === "help") {
         console.log(USAGE);
         return 0;
     }
-    const manifest = loadManifest(options.directory);
+    const manifest = await loadManifest(options.directory);
     const home = resolveHome();
-    let detectedAgents;
-    if (options.agents) {
-        detectedAgents = options.agents;
-        if (options.verbose) {
-            console.log(`Using specified agents: ${detectedAgents.join(", ")}`);
-        }
-    }
-    else {
-        detectedAgents = detectInstalledAgents(home);
-        if (detectedAgents.length === 0) {
-            console.log("No supported AI agents detected on this system.");
-            console.log(`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) {
-            console.log(`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(", ")}`);
+            }
         }
-    }
-    const prefix = options.dryRun ? "\x1b[36m[dry-run]\x1b[0m " : "";
-    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) {
-            console.log("No skills to deploy for detected agents.");
+            logger.info("No skills to deploy for detected agents.");
             return 0;
         }
-        console.log(`${prefix}Deploying ${actions.length} skill(s):`);
-        const { succeeded, failed } = executeDeploy(actions, options.dryRun, options.verbose);
-        console.log();
+        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) {
-            console.log(`${succeeded} succeeded, ${failed.length} failed`);
+            logger.info(`${succeeded} succeeded, ${failed.length} failed`);
             return 1;
         }
         else {
-            console.log(`${succeeded} skill(s) deployed${options.dryRun ? " (dry-run)" : ""}`);
+            logger.info(`${succeeded} skill(s) deployed${options.dryRun ? " (dry-run)" : ""}`);
         }
     }
     else {
-        const actions = planRevert(manifest, detectedAgents, home);
+        const actions = options.agents
+            ? planRevert(manifest, options.agents, home)
+            : planRevertAll(manifest, home);
         if (actions.length === 0) {
-            console.log("No skills to revert for detected agents.");
+            logger.info("No skills to revert.");
             return 0;
         }
-        console.log(`${prefix}Reverting ${actions.length} skill(s):`);
-        const { succeeded, skipped } = executeRevert(actions, options.dryRun, options.verbose);
-        console.log();
+        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`);
-        console.log(`${parts.join(", ")}${options.dryRun ? " (dry-run)" : ""}`);
+        logger.info(`${parts.join(", ")}${options.dryRun ? " (dry-run)" : ""}`);
     }
     return 0;
 }
+const USER_ERROR_EXIT = {
+    INVALID_ARGS: 2,
+    MANIFEST_INVALID: 3,
+    DEPLOY_FAILED: 1,
+    RESOLVE_FAILED: 1,
+};
 const debugMode = process.argv.includes("--debug");
 try {
-    process.exit(main());
+    process.exit(await main());
 }
 catch (err) {
     if (err instanceof UserError) {
-        console.error(`Error: ${err.message}`);
+        logger.error(`Error: ${err.message}`);
+        if (debugMode) {
+            logger.errorRaw(err);
+        }
+        process.exit(USER_ERROR_EXIT[err.code]);
     }
     else {
-        console.error("Unexpected error. Run with --debug for details.");
-    }
-    if (debugMode) {
-        console.error(err);
+        logger.error("Unexpected error. Run with --debug for details.");
+        if (debugMode) {
+            logger.errorRaw(err);
+        }
+        process.exit(1);
     }
-    process.exit(1);
 }

package/dist/logger.d.ts

@@ -0,0 +1,15 @@
+export interface Logger {
+    fail(label: string, msg: string): void;
+    ok(label: string): void;
+    skip(label: string, note: string): void;
+    plan(label: string): void;
+    warn(label: string, msg: string): void;
+    info(msg: string): void;
+    error(msg: string): void;
+    errorRaw(value: unknown): void;
+    detail(msg: string): void;
+    silence(): void;
+}
+export declare function createLogger(): Logger;
+export declare const logger: Logger;
+export declare function dryRunPrefix(dryRun: boolean): string;

package/dist/logger.js

@@ -0,0 +1,61 @@
+import process from "node:process";
+const C = {
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    cyan: "\x1b[36m",
+    reset: "\x1b[0m",
+};
+export function createLogger() {
+    let silent = false;
+    const tty = Boolean(process.stdout.isTTY);
+    const errTTY = Boolean(process.stderr.isTTY);
+    const c = (col, text, onTTY) => onTTY ? `${C[col]}${text}${C.reset}` : text;
+    return {
+        fail(label, msg) {
+            if (!silent)
+                process.stderr.write(`  ${c("red", "✗", errTTY)} ${label}: ${msg}\n`);
+        },
+        ok(label) {
+            if (!silent)
+                process.stdout.write(`  ${c("green", "✓", tty)} ${label}\n`);
+        },
+        skip(label, note) {
+            if (!silent)
+                process.stdout.write(`  ${c("yellow", "-", tty)} ${label} ${note}\n`);
+        },
+        plan(label) {
+            if (!silent)
+                process.stdout.write(`  ${c("cyan", "○", tty)} ${label}\n`);
+        },
+        warn(label, msg) {
+            if (!silent)
+                process.stdout.write(`  ${c("yellow", "!", tty)} ${label}: ${msg}\n`);
+        },
+        info(msg) {
+            if (!silent)
+                process.stdout.write(`${msg}\n`);
+        },
+        error(msg) {
+            if (!silent)
+                process.stderr.write(`${msg}\n`);
+        },
+        errorRaw(value) {
+            if (!silent)
+                console.error(value);
+        },
+        detail(msg) {
+            if (!silent)
+                process.stdout.write(`    ${msg}\n`);
+        },
+        silence() {
+            silent = true;
+        },
+    };
+}
+export const logger = createLogger();
+export function dryRunPrefix(dryRun) {
+    if (!dryRun)
+        return "";
+    return Boolean(process.stdout.isTTY) ? `\x1b[36m[dry-run]\x1b[0m ` : `[dry-run] `;
+}

package/dist/types.d.ts

@@ -11,8 +11,8 @@ export interface Manifest {
     agentRules: unknown[];
 }
 export interface AgentPaths {
-    posix: string;
-    windows: string;
+    posix: string[];
+    windows: string[];
 }
 export interface AgentConfig {
     id: AgentId;

package/package.json

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