@kuznai/inception-engine 0.4.1 → 0.5.0

package/README.md

@@ -2,6 +2,8 @@
 
 Plant skills directly into the minds of your installed AI coding agents — Claude Code, Codex, Gemini CLI, Antigravity, OpenCode, and GitHub Copilot. One command. They'll think they thought of it themselves.
 
+Today, inception-engine is a skills deployer. It does not yet manage persistent instruction files, MCP configuration, subagents, or agent-specific config patching.
+
 ## Quick Start
 
 ```bash
@@ -26,10 +28,12 @@ Managed skills overwrite their previous version. If a target exists but was not
 | Claude Code | `claude-code` | `~/.claude/skills/` | Yes | Yes | Yes |
 | OpenAI Codex | `codex` | `~/.codex/skills/` | Yes | Yes | Yes |
 | Gemini CLI | `gemini-cli` | `~/.gemini/skills/` | Yes | Yes | Yes |
-| Antigravity | `antigravity` | `~/.gemini/antigravity/skills/` | Yes | Yes | Yes |
+| Antigravity | `antigravity` | `~/.gemini/antigravity/skills/` | Yes* | Yes* | Yes* |
 | OpenCode | `opencode` | `~/.config/opencode/skills/` | Yes | Yes | Yes* |
 | GitHub Copilot | `github-copilot` | `~/.copilot/skills/` | Yes | Yes | Yes |
 
+\* Antigravity support is currently based on the implementation's registry path assumptions and local validation, not a strong official doc set equivalent to the other agents.
+
 \* OpenCode on Windows uses `%APPDATA%\opencode\skills\`.
 
 ### Feature Support
@@ -37,8 +41,8 @@ Managed skills overwrite their previous version. If a target exists but was not
 | Feature | Status |
 |---|---|
 | Skills (SKILL.md) | Supported |
-| MCP Servers | Planned |
-| Agent Rules | Planned |
+| MCP Servers | Accepted in manifest, not implemented |
+| Agent Rules | Accepted in manifest, not implemented |
 
 ## Manifest Format
 
@@ -60,10 +64,12 @@ Create an `inception.json` file at the root of your skills directory:
 
 Each skill entry has:
 
-- **name** - Unique skill identifier (lowercase, hyphens allowed)
+- **name** - Unique skill identifier using letters, digits, dots, underscores, or hyphens; it must not start with a dot
 - **path** - Relative path to the skill directory within the repo
 - **agents** - Array of agent IDs to deploy this skill to. If an agent isn't installed, it's skipped.
 
+`mcpServers` and `agentRules` are currently parsed for forward compatibility, but the deployment engine ignores them today.
+
 ## Creating Skills
 
 Each skill is a directory containing at minimum a `SKILL.md` file with YAML frontmatter:
@@ -155,16 +161,16 @@ Revert targets all agents listed in the manifest by default (regardless of detec
 
 ### 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.
+inception-engine maintains a centralized deployment registry at `~/.inception-engine/registry.json`. Each deploy records the target path, source path, skill name, agent ID, deploy method, and timestamp. No files are written to the source repository.
 
-- **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.
+- **Registry-based ownership**: On revert, the registry is checked before removing any target. Only targets with a valid registry entry are removed. On redeploy, unmanaged targets are never replaced.
 
-- **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.
+- **Strong binding**: Each registry entry binds a specific target path to its source, skill, agent, and deploy method. A target is only considered managed if all fields match — a stray entry or a different deployment cannot satisfy the check.
 
 - **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.
 
+- **Cross-platform**: The registry uses the same resolved home directory as the rest of the tool, including sudo scenarios on POSIX and elevated PowerShell on Windows.
+
 ## 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.
@@ -179,7 +185,11 @@ On Windows, `os.homedir()` correctly resolves even in elevated PowerShell or cmd
 
 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.
+`SUDO_USER` is only consulted when the process is actually running as root (UID 0). If `SUDO_USER` is present in the environment but the process is not root — for example, as a stale shell variable from a prior `sudo` session or an externally injected value in automation — it is ignored and the standard home directory is used instead.
+
+### XDG_CONFIG_HOME support
+
+On POSIX, agents whose config lives under `~/.config/` (currently OpenCode) honor `$XDG_CONFIG_HOME` when it is set to an absolute path. If the variable is unset or contains a relative path (which the XDG Base Directory Specification disallows), the tool falls back to the standard `~/.config` default. This has no effect on Windows.
 
 ### Windows %APPDATA% fallback
 
@@ -187,7 +197,7 @@ On Windows, `%APPDATA%` is used to locate agent config directories (currently on
 
 ### 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.
+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.
 
 ## Requirements
 

package/dist/config/agents.js

@@ -11,6 +11,11 @@ export const AGENT_REGISTRY = [
             windows: ["{home}", ".claude"],
         },
         detectBinary: "claude",
+        provenance: {
+            skills: "documented",
+            detectPaths: "documented",
+            detectBinary: "documented",
+        },
     },
     {
         id: "codex",
@@ -24,6 +29,11 @@ export const AGENT_REGISTRY = [
             windows: ["{home}", ".codex"],
         },
         detectBinary: "codex",
+        provenance: {
+            skills: "documented",
+            detectPaths: "documented",
+            detectBinary: "documented",
+        },
     },
     {
         id: "gemini-cli",
@@ -37,6 +47,11 @@ export const AGENT_REGISTRY = [
             windows: ["{home}", ".gemini"],
         },
         detectBinary: "gemini",
+        provenance: {
+            skills: "documented",
+            detectPaths: "documented",
+            detectBinary: "documented",
+        },
     },
     {
         id: "antigravity",
@@ -50,19 +65,29 @@ export const AGENT_REGISTRY = [
             windows: ["{home}", ".gemini", "antigravity"],
         },
         detectBinary: null,
+        provenance: {
+            skills: "implementation-only",
+            detectPaths: "implementation-only",
+            detectBinary: "provisional",
+        },
     },
     {
         id: "opencode",
         displayName: "OpenCode",
         skills: {
-            posix: ["{home}", ".config", "opencode", "skills", "{name}"],
+            posix: ["{xdg_config}", "opencode", "skills", "{name}"],
             windows: ["{appdata}", "opencode", "skills", "{name}"],
         },
         detectPaths: {
-            posix: ["{home}", ".config", "opencode"],
+            posix: ["{xdg_config}", "opencode"],
             windows: ["{appdata}", "opencode"],
         },
         detectBinary: "opencode",
+        provenance: {
+            skills: "documented",
+            detectPaths: "documented",
+            detectBinary: "documented",
+        },
     },
     {
         id: "github-copilot",
@@ -76,6 +101,11 @@ export const AGENT_REGISTRY = [
             windows: ["{home}", ".copilot"],
         },
         detectBinary: "github-copilot",
+        provenance: {
+            skills: "documented",
+            detectPaths: "documented",
+            detectBinary: "documented",
+        },
     },
 ];
 export const AGENT_REGISTRY_BY_ID = Object.fromEntries(AGENT_REGISTRY.map((a) => [a.id, a]));

package/dist/core/deploy.d.ts

@@ -1,6 +1,6 @@
 import type { AgentId, DeployAction, Manifest } from "../types.ts";
 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<{
+export declare function executeDeploy(actions: DeployAction[], dryRun: boolean, verbose: boolean, home: string): Promise<{
     succeeded: number;
     failed: Array<{
         action: DeployAction;

package/dist/core/deploy.js

@@ -3,7 +3,7 @@ import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { UserError } from "../errors.js";
 import { logger } from "../logger.js";
-import { isOwnedByInceptionEngine, writeTotem } from "./ownership.js";
+import { registerDeployment, verifyDeployment } from "./ownership.js";
 import { getDeployMethod, resolveAgentSkillPath } from "./resolve.js";
 export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
     const method = getDeployMethod();
@@ -37,7 +37,7 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
     }
     return actions;
 }
-export async function executeDeploy(actions, dryRun, verbose) {
+export async function executeDeploy(actions, dryRun, verbose, home) {
     let succeeded = 0;
     const failed = [];
     for (const action of actions) {
@@ -60,7 +60,7 @@ export async function executeDeploy(actions, dryRun, verbose) {
             continue;
         }
         try {
-            await executeDeployAction(action, verbose);
+            await executeDeployAction(action, verbose, home);
             succeeded++;
         }
         catch (err) {
@@ -99,31 +99,31 @@ async function assertTargetAbsent(targetPath) {
         // ENOENT is expected — target should not exist after backup
     }
 }
-async function createDeployTarget(action) {
+async function createDeployTarget(action, home) {
     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,
-        });
     }
+    await registerDeployment(home, action.target, {
+        source: action.source,
+        skill: action.skill,
+        agent: action.agent,
+        method: action.method,
+    });
 }
-async function executeDeployAction(action, verbose) {
+async function executeDeployAction(action, verbose, home) {
     const label = `${action.skill} -> ${action.agent}`;
-    const backupPath = await backupExisting(action.target, verbose);
+    const backupPath = await backupExisting(action.target, verbose, home, {
+        source: action.source,
+        skill: action.skill,
+        agent: action.agent,
+    });
     await mkdir(path.dirname(action.target), { recursive: true });
     try {
         await assertTargetAbsent(action.target);
-        await createDeployTarget(action);
+        await createDeployTarget(action, home);
     }
     catch (createErr) {
         if (backupPath) {
@@ -144,15 +144,14 @@ async function executeDeployAction(action, verbose) {
         logger.detail(`${action.method}: ${action.source} -> ${action.target}`);
     }
 }
-async function backupExisting(targetPath, verbose) {
-    let stat;
+async function backupExisting(targetPath, verbose, home, expected) {
     try {
-        stat = await lstat(targetPath);
+        await lstat(targetPath);
     }
     catch {
         return null;
     }
-    if (!(await isOwnedByInceptionEngine(targetPath, stat))) {
+    if (!(await verifyDeployment(home, targetPath, expected))) {
         throw new Error(`Target "${targetPath}" exists but is not managed by inception-engine — refusing to overwrite`);
     }
     const backupPath = `${targetPath}.inception-backup`;

package/dist/core/ownership.d.ts

@@ -1,10 +1,17 @@
-import type { Stats } from "node:fs";
 import type { AgentId } from "../types.ts";
-export interface TotemData {
+export interface RegistryEntry {
     source: string;
     skill: string;
     agent: AgentId;
+    method: "symlink" | "copy";
+    deployed: string;
 }
-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>;
+export declare function registryPath(home: string): string;
+export declare function registerDeployment(home: string, targetPath: string, entry: Omit<RegistryEntry, "deployed">): Promise<void>;
+export declare function unregisterDeployment(home: string, targetPath: string): Promise<void>;
+export declare function lookupDeployment(home: string, targetPath: string): Promise<RegistryEntry | null>;
+export declare function verifyDeployment(home: string, targetPath: string, expected: {
+    source: string;
+    skill: string;
+    agent: AgentId;
+}): Promise<RegistryEntry | null>;

package/dist/core/ownership.js

@@ -1,44 +1,73 @@
-import { access, chmod, readFile, readlink, writeFile } from "node:fs/promises";
+import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
-const TOTEM_FILE = ".inception-totem";
-const TOTEM_HEADER = "inception-engine";
-export function formatTotem(data) {
-    const lines = [
-        TOTEM_HEADER,
-        `source=${data.source}`,
-        `skill=${data.skill}`,
-        `agent=${data.agent}`,
-        `deployed=${new Date().toISOString()}`,
-    ];
-    return `${lines.join("\n")}\n`;
-}
-export async function writeTotem(directory, data) {
-    const totemPath = path.join(directory, TOTEM_FILE);
-    await writeFile(totemPath, formatTotem(data));
-    await chmod(totemPath, 0o644);
-}
-export async function isOwnedByInceptionEngine(targetPath, stat) {
-    const totemLocation = stat.isSymbolicLink()
-        ? await resolveSymlinkTotemPath(targetPath)
-        : path.join(targetPath, TOTEM_FILE);
-    if (!totemLocation)
-        return false;
+const REGISTRY_DIR = ".inception-engine";
+const REGISTRY_FILE = "registry.json";
+export function registryPath(home) {
+    return path.join(home, REGISTRY_DIR, REGISTRY_FILE);
+}
+async function loadRegistry(home) {
     try {
-        const content = await readFile(totemLocation, "utf-8");
-        return content.startsWith(TOTEM_HEADER);
+        const content = await readFile(registryPath(home), "utf-8");
+        const parsed = JSON.parse(content);
+        if (parsed &&
+            typeof parsed === "object" &&
+            parsed.version === 1 &&
+            parsed.deployments &&
+            typeof parsed.deployments === "object") {
+            return parsed;
+        }
+        return emptyRegistry();
     }
     catch {
-        return false;
+        return emptyRegistry();
     }
 }
-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);
+async function saveRegistry(home, registry) {
+    const dir = path.join(home, REGISTRY_DIR);
+    await mkdir(dir, { recursive: true });
+    const filePath = registryPath(home);
+    await writeFile(filePath, `${JSON.stringify(registry, null, 2)}\n`);
+    await setFilePermissions(filePath);
+}
+/**
+ * Ensure the file is not world-writable regardless of umask.
+ * On Windows, the OS inherits ACLs from the parent directory — no-op is correct.
+ */
+async function setFilePermissions(filePath) {
+    if (process.platform !== "win32") {
+        await chmod(filePath, 0o644);
     }
-    catch {
+}
+function emptyRegistry() {
+    return { version: 1, deployments: {} };
+}
+export async function registerDeployment(home, targetPath, entry) {
+    const registry = await loadRegistry(home);
+    registry.deployments[targetPath] = {
+        ...entry,
+        deployed: new Date().toISOString(),
+    };
+    await saveRegistry(home, registry);
+}
+export async function unregisterDeployment(home, targetPath) {
+    const registry = await loadRegistry(home);
+    if (!(targetPath in registry.deployments))
+        return;
+    delete registry.deployments[targetPath];
+    await saveRegistry(home, registry);
+}
+export async function lookupDeployment(home, targetPath) {
+    const registry = await loadRegistry(home);
+    return registry.deployments[targetPath] ?? null;
+}
+export async function verifyDeployment(home, targetPath, expected) {
+    const entry = await lookupDeployment(home, targetPath);
+    if (!entry)
+        return null;
+    if (entry.source !== expected.source ||
+        entry.skill !== expected.skill ||
+        entry.agent !== expected.agent) {
         return null;
     }
+    return entry;
 }

package/dist/core/resolve.js

@@ -8,7 +8,7 @@ export function resolveHome() {
         return os.homedir();
     }
     const sudoUser = process.env.SUDO_USER;
-    if (sudoUser) {
+    if (sudoUser && process.getuid?.() === 0) {
         return lookupHomeForUser(sudoUser);
     }
     return os.homedir();
@@ -98,9 +98,12 @@ export function resolveAgentDetectPath(agent, home) {
 }
 function resolvePlaceholders(segments, skillName, home) {
     const appdata = process.env.APPDATA ?? path.join(home, "AppData", "Roaming");
+    const xdgRaw = process.env.XDG_CONFIG_HOME;
+    const xdgConfig = xdgRaw && path.isAbsolute(xdgRaw) ? xdgRaw : path.join(home, ".config");
     const resolved = segments.map((seg) => seg
         .replace("{home}", home)
         .replace("{name}", skillName)
-        .replace("{appdata}", appdata));
+        .replace("{appdata}", appdata)
+        .replace("{xdg_config}", xdgConfig));
     return path.join(...resolved);
 }

package/dist/core/revert.d.ts

@@ -1,7 +1,7 @@
 import type { AgentId, Manifest, RevertAction } from "../types.ts";
 export declare function planRevert(manifest: Manifest, detectedAgents: AgentId[], home: string): RevertAction[];
 export declare function planRevertAll(manifest: Manifest, home: string): RevertAction[];
-export declare function executeRevert(actions: RevertAction[], dryRun: boolean, verbose: boolean): Promise<{
+export declare function executeRevert(actions: RevertAction[], dryRun: boolean, verbose: boolean, home: string): Promise<{
     succeeded: number;
     skipped: number;
 }>;

package/dist/core/revert.js

@@ -1,7 +1,7 @@
 import { lstat, rm, unlink } from "node:fs/promises";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { logger } from "../logger.js";
-import { isOwnedByInceptionEngine } from "./ownership.js";
+import { lookupDeployment, unregisterDeployment } from "./ownership.js";
 import { resolveAgentSkillPath } from "./resolve.js";
 export function planRevert(manifest, detectedAgents, home) {
     const actions = [];
@@ -31,11 +31,11 @@ export function planRevertAll(manifest, home) {
     }
     return actions;
 }
-export async function executeRevert(actions, dryRun, verbose) {
+export async function executeRevert(actions, dryRun, verbose, home) {
     let succeeded = 0;
     let skipped = 0;
     for (const action of actions) {
-        const result = await executeRevertAction(action, dryRun, verbose);
+        const result = await executeRevertAction(action, dryRun, verbose, home);
         if (result === "skip") {
             skipped++;
         }
@@ -45,7 +45,7 @@ export async function executeRevert(actions, dryRun, verbose) {
     }
     return { succeeded, skipped };
 }
-async function executeRevertAction(action, dryRun, verbose) {
+async function executeRevertAction(action, dryRun, verbose, home) {
     const label = `${action.skill} -> ${action.agent}`;
     let stat;
     try {
@@ -55,8 +55,9 @@ async function executeRevertAction(action, dryRun, verbose) {
         logger.skip(label, "(not found, skipping)");
         return "skip";
     }
-    if (!(await isOwnedByInceptionEngine(action.target, stat))) {
-        logger.warn(label, `skipping: ${action.target} does not have inception-engine ownership proof — not managed by inception-engine`);
+    const entry = await lookupDeployment(home, action.target);
+    if (!entry || entry.skill !== action.skill || entry.agent !== action.agent) {
+        logger.warn(label, `skipping: ${action.target} is not in the deployment registry — not managed by inception-engine`);
         return "skip";
     }
     if (dryRun) {
@@ -73,6 +74,7 @@ async function executeRevertAction(action, dryRun, verbose) {
         else {
             await rm(action.target, { recursive: true });
         }
+        await unregisterDeployment(home, action.target);
         logger.ok(label);
         if (verbose) {
             logger.detail(`removed: ${action.target}`);

package/dist/index.js

@@ -137,7 +137,7 @@ async function runDeploy(options, manifest, home) {
         return 0;
     }
     logger.info(`${dryRunPrefix(options.dryRun)}Deploying ${actions.length} skill(s):`);
-    const { succeeded, failed } = await executeDeploy(actions, options.dryRun, options.verbose);
+    const { succeeded, failed } = await executeDeploy(actions, options.dryRun, options.verbose, home);
     logger.info("");
     if (failed.length > 0) {
         logger.info(`${succeeded} succeeded, ${failed.length} failed`);
@@ -155,7 +155,7 @@ async function runRevert(options, manifest, home) {
         return 0;
     }
     logger.info(`${dryRunPrefix(options.dryRun)}Reverting ${actions.length} skill(s):`);
-    const { succeeded, skipped } = await executeRevert(actions, options.dryRun, options.verbose);
+    const { succeeded, skipped } = await executeRevert(actions, options.dryRun, options.verbose, home);
     logger.info("");
     const parts = [`${succeeded} removed`];
     if (skipped > 0)

package/dist/types.d.ts

@@ -14,12 +14,19 @@ export interface AgentPaths {
     posix: string[];
     windows: string[];
 }
+export type Confidence = "documented" | "implementation-only" | "provisional";
+export interface AgentProvenance {
+    skills: Confidence;
+    detectPaths: Confidence;
+    detectBinary: Confidence;
+}
 export interface AgentConfig {
     id: AgentId;
     displayName: string;
     skills: AgentPaths;
     detectPaths: AgentPaths;
     detectBinary: string | null;
+    provenance: AgentProvenance;
 }
 export interface DeployAction {
     skill: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",
@@ -36,7 +36,7 @@
   "scripts": {
     "build": "tsc",
     "typecheck": "tsc --noEmit",
-    "format": "biome format --write .",
+    "fmt": "biome format --write .",
     "lint": "biome lint . --max-diagnostics none",
     "dev": "node src/index.ts",
     "test": "node --test test/*.test.ts",