@kuznai/inception-engine 0.2.4 → 0.3.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.
@@ -151,6 +151,16 @@ 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 uses different ownership proofs depending on the deploy method so that `revert` never removes content it did not create:
+
+- **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)**: 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`.
+
+> **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.
+
 ## 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 +169,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,57 @@
-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 (!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 executeDeploy(actions: DeployAction[], dryRun: boolean, verbose: boolean): Promise<{
     succeeded: number;
     failed: Array<{
         action: DeployAction;
         error: string;
     }>;
-};
+}>;

package/dist/core/deploy.js

@@ -1,8 +1,9 @@
-import { existsSync, lstatSync, mkdirSync, rmSync, symlinkSync, cpSync, unlinkSync, } from "node:fs";
+import { access, lstat, mkdir, symlink, cp, unlink, rm, writeFile } 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";
+import { logger } from "../logger.js";
 export function planDeploy(manifest, sourceDir, detectedAgents, home) {
     const method = getDeployMethod();
     const actions = [];
@@ -10,12 +11,12 @@ export function planDeploy(manifest, sourceDir, detectedAgents, home) {
     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}`);
+            throw new UserError("DEPLOY_FAILED", `Skill path "${skill.path}" resolves outside the repository root: ${source}`);
         }
         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 +25,70 @@ 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 });
+            await removeExisting(action.target, verbose);
+            await mkdir(path.dirname(action.target), { recursive: true });
             if (action.method === "symlink") {
-                symlinkSync(action.source, action.target, "dir");
+                await symlink(action.source, action.target, "dir");
             }
             else {
-                cpSync(action.source, action.target, { recursive: true });
+                await cp(action.source, action.target, { recursive: true });
+                await writeFile(path.join(action.target, ".inception-totem"), "inception-engine\n");
             }
-            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))
+async function removeExisting(targetPath, verbose) {
+    let stat;
+    try {
+        stat = await lstat(targetPath);
+    }
+    catch {
         return;
-    if (isSymlink(targetPath)) {
+    }
+    if (stat.isSymbolicLink()) {
         if (verbose) {
-            console.log(`    removing existing symlink: ${targetPath}`);
+            logger.detail(`removing existing symlink: ${targetPath}`);
         }
-        unlinkSync(targetPath);
+        await unlink(targetPath);
     }
     else {
         if (verbose) {
-            console.log(`    \x1b[33m!\x1b[0m replacing existing directory: ${targetPath}`);
+            logger.warn(targetPath, "replacing existing directory");
         }
-        rmSync(targetPath, { recursive: true });
-    }
-}
-function isSymlink(p) {
-    try {
-        return lstatSync(p).isSymbolicLink();
-    }
-    catch {
-        return false;
+        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/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,6 @@
 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 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 { access, lstat, unlink, rm, readlink } from "node:fs/promises";
+import path from "node:path";
+import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { resolveAgentSkillPath } from "./resolve.js";
+import { logger } from "../logger.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,72 @@ export function planRevert(manifest, detectedAgents, home) {
     }
     return actions;
 }
-export function executeRevert(actions, dryRun, verbose) {
+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();
+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;
+        }
     }
-    catch {
-        return false;
+    else {
+        try {
+            await access(path.join(targetPath, ".inception-totem"));
+            return true;
+        }
+        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,5 +1,6 @@
 #!/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";
@@ -8,6 +9,7 @@ import { detectInstalledAgents } from "./core/detect.js";
 import { planDeploy, executeDeploy } from "./core/deploy.js";
 import { planRevert, 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,146 @@ 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++;
-    }
-    if (!directory) {
-        throw new UserError("Missing required <directory> argument");
+        agents = ids;
     }
-    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(", ")}`);
+            logger.info(`Using specified agents: ${detectedAgents.join(", ")}`);
         }
     }
     else {
-        detectedAgents = detectInstalledAgents(home);
+        detectedAgents = await 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(", ")}`);
+            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) {
-            console.log(`Detected agents: ${detectedAgents.join(", ")}`);
+            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);
         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);
         if (actions.length === 0) {
-            console.log("No skills to revert for detected agents.");
+            logger.info("No skills to revert for detected agents.");
             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.3.0",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",