@kuznai/inception-engine 0.8.0 → 0.10.1

package/dist/core/revert.js

@@ -1,18 +1,10 @@
 import { lstat, readFile, rm, unlink, writeFile } from "node:fs/promises";
-import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { logger } from "../logger.js";
-import { lookupDeployment, unregisterDeployment } from "./ownership.js";
+import { compileAgentRuleReverts, compileMcpServerReverts, } from "./adapters/index.js";
+import { lookupDeployment, unregisterDeployment, } from "./ownership.js";
 import { resolveAgentSkillPath } from "./resolve.js";
-function resolveTargetTemplate(template, 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");
-    return template
-        .replace("{home}", home)
-        .replace("{appdata}", appdata)
-        .replace("{xdg_config}", xdgConfig);
-}
+import { resolveTargetTemplate } from "./runtime-paths.js";
 function buildSkillDirReverts(manifest, home, agentFilter) {
     const actions = [];
     for (const skill of manifest.skills) {
@@ -75,6 +67,8 @@ export function planRevert(manifest, detectedAgents, home) {
         ...buildSkillDirReverts(manifest, home, detectedAgents),
         ...buildFileWriteReverts(manifest, home, detectedAgents),
         ...buildConfigPatchReverts(manifest, home, detectedAgents),
+        ...(manifest.mcpServers ?? []).flatMap((e) => compileMcpServerReverts(e, detectedAgents, home)),
+        ...(manifest.agentRules ?? []).flatMap((e) => compileAgentRuleReverts(e, detectedAgents, home)),
     ];
 }
 export function planRevertAll(manifest, home) {
@@ -82,6 +76,8 @@ export function planRevertAll(manifest, home) {
         ...buildSkillDirReverts(manifest, home, null),
         ...buildFileWriteReverts(manifest, home, null),
         ...buildConfigPatchReverts(manifest, home, null),
+        ...(manifest.mcpServers ?? []).flatMap((e) => compileMcpServerReverts(e, null, home)),
+        ...(manifest.agentRules ?? []).flatMap((e) => compileAgentRuleReverts(e, null, home)),
     ];
 }
 function recordOutcome(result, action, counts, failed) {
@@ -109,12 +105,18 @@ async function readJsonConfig(filePath) {
     }
     return parsed;
 }
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
 function applyUndoPatch(current, undoPatch) {
     const restored = { ...current };
     for (const [key, originalValue] of Object.entries(undoPatch)) {
         if (originalValue === null) {
             delete restored[key];
         }
+        else if (isPlainObject(originalValue) && isPlainObject(restored[key])) {
+            restored[key] = applyUndoPatch(restored[key], originalValue);
+        }
         else {
             restored[key] = originalValue;
         }
@@ -128,7 +130,7 @@ function lstatOutcome(err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { outcome: "fail", error: msg };
 }
-export async function executeRevert(actions, dryRun, verbose, home) {
+export async function executeRevert(actions, dryRun, verbose, home, deps = {}) {
     let succeeded = 0;
     let skipped = 0;
     const failed = [];
@@ -138,13 +140,13 @@ export async function executeRevert(actions, dryRun, verbose, home) {
         let result;
         switch (action.kind) {
             case "skill-dir":
-                result = await executeRevertAction(action, dryRun, verbose, home, planned);
+                result = await executeRevertAction(action, dryRun, verbose, home, planned, deps);
                 break;
             case "file-write":
-                result = await revertFileWrite(action, dryRun, verbose, home, planned);
+                result = await revertFileWrite(action, dryRun, verbose, home, planned, deps);
                 break;
             case "config-patch":
-                result = await revertConfigPatch(action, dryRun, verbose, home, planned);
+                result = await revertConfigPatch(action, dryRun, verbose, home, planned, deps);
                 break;
             default:
                 throw new Error(`Unhandled revert action kind: ${action}`);
@@ -155,7 +157,7 @@ export async function executeRevert(actions, dryRun, verbose, home) {
     skipped = counts.skipped;
     return { succeeded, skipped, failed, planned };
 }
-async function executeRevertAction(action, dryRun, verbose, home, planned) {
+async function executeRevertAction(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     try {
         await lstat(action.target);
@@ -169,7 +171,7 @@ async function executeRevertAction(action, dryRun, verbose, home, planned) {
         logger.fail(label, result.error);
         return result;
     }
-    const entry = await lookupDeployment(home, action.target);
+    const entry = await lookupDeployment(home, action.target, deps.registry);
     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 { outcome: "skip" };
@@ -194,7 +196,7 @@ async function executeRevertAction(action, dryRun, verbose, home, planned) {
         else {
             await rm(action.target, { recursive: true });
         }
-        await unregisterDeployment(home, action.target);
+        await unregisterDeployment(home, action.target, deps.registry);
         logger.ok(label);
         if (verbose) {
             logger.detail(`removed: ${action.target}`);
@@ -212,7 +214,7 @@ async function executeRevertAction(action, dryRun, verbose, home, planned) {
         return { outcome: "fail", error: msg };
     }
 }
-async function revertFileWrite(action, dryRun, verbose, home, planned) {
+async function revertFileWrite(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     try {
         await lstat(action.target);
@@ -226,7 +228,7 @@ async function revertFileWrite(action, dryRun, verbose, home, planned) {
         logger.fail(label, result.error);
         return result;
     }
-    const entry = await lookupDeployment(home, action.target);
+    const entry = await lookupDeployment(home, action.target, deps.registry);
     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 { outcome: "skip" };
@@ -246,7 +248,7 @@ async function revertFileWrite(action, dryRun, verbose, home, planned) {
         // removal window; handle the case where the file has since disappeared.
         await lstat(action.target);
         await unlink(action.target);
-        await unregisterDeployment(home, action.target);
+        await unregisterDeployment(home, action.target, deps.registry);
         logger.ok(label);
         if (verbose) {
             logger.detail(`removed: ${action.target}`);
@@ -263,7 +265,7 @@ async function revertFileWrite(action, dryRun, verbose, home, planned) {
         return { outcome: "fail", error: msg };
     }
 }
-async function revertConfigPatch(action, dryRun, verbose, home, planned) {
+async function revertConfigPatch(action, dryRun, verbose, home, planned, deps) {
     const label = `${action.skill} -> ${action.agent}`;
     try {
         await lstat(action.target);
@@ -277,7 +279,7 @@ async function revertConfigPatch(action, dryRun, verbose, home, planned) {
         logger.fail(label, result.error);
         return result;
     }
-    const entry = await lookupDeployment(home, action.target);
+    const entry = await lookupDeployment(home, action.target, deps.registry);
     if (!entry ||
         entry.kind !== "config-patch" ||
         entry.skill !== action.skill ||
@@ -301,7 +303,7 @@ async function revertConfigPatch(action, dryRun, verbose, home, planned) {
         const current = await readJsonConfig(action.target);
         const restored = applyUndoPatch(current, configPatchEntry.undoPatch);
         await writeFile(action.target, `${JSON.stringify(restored, null, 2)}\n`, "utf-8");
-        await unregisterDeployment(home, action.target);
+        await unregisterDeployment(home, action.target, deps.registry);
         logger.ok(label);
         if (verbose) {
             logger.detail(`unapplied patch from: ${action.target}`);

package/dist/core/runtime-paths.d.ts

@@ -0,0 +1,8 @@
+import path from "node:path";
+export interface RuntimePaths {
+    appdata: string;
+    xdgConfig: string;
+}
+export declare function getPathApi(root: string): typeof path.posix | typeof path.win32;
+export declare function resolveRuntimePaths(home: string): RuntimePaths;
+export declare function resolveTargetTemplate(template: string, home: string): string;

package/dist/core/runtime-paths.js

@@ -0,0 +1,57 @@
+import path from "node:path";
+const TARGET_TEMPLATE_RE = /^\{(home|appdata|xdg_config)\}(?<suffix>(?:[\\/].*)?)$/;
+export function getPathApi(root) {
+    if (root.includes("\\") || /^[a-zA-Z]:/.test(root)) {
+        return path.win32;
+    }
+    if (root.startsWith("/")) {
+        return path.posix;
+    }
+    return process.platform === "win32" ? path.win32 : path.posix;
+}
+function normalizePathForComparison(candidate, pathApi) {
+    const normalized = pathApi.normalize(candidate);
+    return pathApi === path.win32 ? normalized.toLowerCase() : normalized;
+}
+function isSameOrDescendantPath(candidate, root) {
+    const pathApi = getPathApi(root);
+    const normalizedCandidate = normalizePathForComparison(candidate, pathApi);
+    const normalizedRoot = normalizePathForComparison(root, pathApi);
+    return (normalizedCandidate === normalizedRoot ||
+        normalizedCandidate.startsWith(normalizedRoot + pathApi.sep));
+}
+export function resolveRuntimePaths(home) {
+    const appdataRaw = process.env.APPDATA;
+    const homePathApi = getPathApi(home);
+    const appdata = appdataRaw && getPathApi(appdataRaw).isAbsolute(appdataRaw)
+        ? appdataRaw
+        : homePathApi.join(home, "AppData", "Roaming");
+    const xdgRaw = process.env.XDG_CONFIG_HOME;
+    const xdgConfig = xdgRaw && getPathApi(xdgRaw).isAbsolute(xdgRaw)
+        ? xdgRaw
+        : homePathApi.join(home, ".config");
+    return { appdata, xdgConfig };
+}
+export function resolveTargetTemplate(template, home) {
+    const { appdata, xdgConfig } = resolveRuntimePaths(home);
+    const match = TARGET_TEMPLATE_RE.exec(template);
+    if (!match) {
+        throw new Error(`Invalid target template: ${template}`);
+    }
+    const baseByRoot = {
+        home,
+        appdata,
+        xdg_config: xdgConfig,
+    };
+    const root = match[1];
+    const suffix = match.groups?.suffix ?? "";
+    const segments = suffix.split(/[\\/]+/).filter(Boolean);
+    const pathApi = getPathApi(baseByRoot[root]);
+    const resolved = segments.length === 0
+        ? baseByRoot[root]
+        : pathApi.join(baseByRoot[root], ...segments);
+    if (!isSameOrDescendantPath(resolved, baseByRoot[root])) {
+        throw new Error(`Target template resolves outside its placeholder root: ${template}`);
+    }
+    return suffix === "" ? baseByRoot[root] : `${baseByRoot[root]}${suffix}`;
+}

package/dist/core/validation.d.ts

@@ -0,0 +1,3 @@
+export declare function sourceAccessError(err: unknown, sourcePath: string): string;
+export declare function validateSourcePath(source: string, skillPath: string, resolvedSourceDir: string, realRoot: string): Promise<void>;
+export declare function validateSourceFile(sourcePath: string, manifestPath: string): Promise<void>;

package/dist/core/validation.js

@@ -0,0 +1,66 @@
+import { lstat, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+import { UserError } from "../errors.js";
+export function sourceAccessError(err, sourcePath) {
+    const code = err.code;
+    if (code === "ENOENT")
+        return `Source not found: ${sourcePath}`;
+    if (code === "EACCES" || code === "EPERM")
+        return `Permission denied accessing source: ${sourcePath}`;
+    const detail = err instanceof Error ? err.message : String(err);
+    return `Failed to access source ${sourcePath}: ${detail}`;
+}
+function normalizePathForComparison(candidate) {
+    const normalized = path.normalize(candidate);
+    return process.platform === "win32" ? normalized.toLowerCase() : normalized;
+}
+function isSameOrDescendantPath(candidate, root) {
+    const normalizedCandidate = normalizePathForComparison(candidate);
+    const normalizedRoot = normalizePathForComparison(root);
+    return (normalizedCandidate === normalizedRoot ||
+        normalizedCandidate.startsWith(normalizedRoot + path.sep));
+}
+async function isSameFileSystemLocation(a, b) {
+    const [aStat, bStat] = await Promise.all([stat(a), stat(b)]);
+    return aStat.dev === bStat.dev && aStat.ino === bStat.ino;
+}
+async function isWithinRootByIdentity(candidate, root) {
+    let current = candidate;
+    while (true) {
+        if (await isSameFileSystemLocation(current, root))
+            return true;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return false;
+        current = parent;
+    }
+}
+export async function validateSourcePath(source, skillPath, resolvedSourceDir, realRoot) {
+    if (!source.startsWith(resolvedSourceDir + path.sep)) {
+        throw new UserError("DEPLOY_FAILED", `Skill path "${skillPath}" resolves outside the repository root: ${source}`);
+    }
+    try {
+        const realSource = await realpath(source);
+        if (!(isSameOrDescendantPath(realSource, realRoot) ||
+            (await isWithinRootByIdentity(realSource, realRoot)))) {
+            throw new UserError("DEPLOY_FAILED", `Skill path "${skillPath}" resolves outside the repository root via symlink: ${source} -> ${realSource}`);
+        }
+    }
+    catch (err) {
+        if (err instanceof UserError)
+            throw err;
+        // Source doesn't exist yet — will be caught during execute
+    }
+}
+export async function validateSourceFile(sourcePath, manifestPath) {
+    let stat;
+    try {
+        stat = await lstat(sourcePath);
+    }
+    catch (err) {
+        throw new UserError("DEPLOY_FAILED", sourceAccessError(err, manifestPath));
+    }
+    if (!stat.isFile()) {
+        throw new UserError("DEPLOY_FAILED", `Source is not a file: ${manifestPath}`);
+    }
+}

package/dist/schemas/manifest.d.ts

@@ -50,10 +50,28 @@ export declare const ConfigEntrySchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const McpServerEntrySchema: z.ZodObject<{
     name: z.ZodString;
-}, z.core.$loose>;
+    agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+        "gemini-cli": "gemini-cli";
+        antigravity: "antigravity";
+        opencode: "opencode";
+        "github-copilot": "github-copilot";
+    }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
+    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
 export declare const AgentRuleEntrySchema: z.ZodObject<{
     name: z.ZodString;
-}, z.core.$loose>;
+    agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+        "gemini-cli": "gemini-cli";
+        antigravity: "antigravity";
+        opencode: "opencode";
+        "github-copilot": "github-copilot";
+    }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
+    path: z.ZodString;
+}, z.core.$strip>;
 export declare const ManifestSchema: z.ZodObject<{
     skills: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
@@ -95,10 +113,28 @@ export declare const ManifestSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     mcpServers: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
-    }, z.core.$loose>>>;
+        agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+            "gemini-cli": "gemini-cli";
+            antigravity: "antigravity";
+            opencode: "opencode";
+            "github-copilot": "github-copilot";
+        }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
+        config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>>;
     agentRules: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
-    }, z.core.$loose>>>;
+        agents: z.ZodPipe<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+            "gemini-cli": "gemini-cli";
+            antigravity: "antigravity";
+            opencode: "opencode";
+            "github-copilot": "github-copilot";
+        }>>>, z.ZodTransform<("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[], ("claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot")[]>>;
+        path: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export type SkillEntry = z.infer<typeof SkillEntrySchema>;
 export type FileEntry = z.infer<typeof FileEntrySchema>;

package/dist/schemas/manifest.js

@@ -10,9 +10,10 @@ const AGENT_IDS = [
 ];
 export { AGENT_IDS };
 const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-// Target templates must start with a known placeholder to prevent raw absolute
-// paths or directory traversal. e.g. "{home}/.claude/settings.json" is valid.
-const TARGET_TEMPLATE_RE = /^\{(home|appdata|xdg_config)\}/;
+// Target templates must be rooted at a known placeholder and may only add
+// descendant path segments beneath that root. e.g. "{home}/.claude/settings.json"
+// is valid, while "{home}/../.ssh/config" is rejected.
+const TARGET_TEMPLATE_RE = /^\{(home|appdata|xdg_config)\}(?:[\\/].*)?$/;
 // Standalone schema used for type derivation and single-ID validation (e.g. index.ts).
 export const AgentIdSchema = z.enum(AGENT_IDS);
 // Used inside SkillEntrySchema.agents so that enum failures embed the received
@@ -53,6 +54,9 @@ const targetTemplateField = z
     .min(1, { message: "target must be a non-empty string" })
     .refine((t) => TARGET_TEMPLATE_RE.test(t), {
     message: "target must start with a known placeholder: {home}, {appdata}, or {xdg_config}",
+})
+    .refine((t) => !t.split(/[\\/]+/).includes(".."), {
+    message: "target must not escape its placeholder root",
 });
 export const SkillEntrySchema = z.object({
     name: nameField,
@@ -71,20 +75,19 @@ export const ConfigEntrySchema = z.object({
     patch: z.record(z.string(), z.unknown()),
     agents: agentsField,
 });
-export const McpServerEntrySchema = z
-    .object({
-    name: z
-        .string({ message: "mcpServers entry name must be a non-empty string" })
-        .min(1, { message: "mcpServers entry name must be a non-empty string" }),
-})
-    .passthrough();
-export const AgentRuleEntrySchema = z
-    .object({
-    name: z
-        .string({ message: "agentRules entry name must be a non-empty string" })
-        .min(1, { message: "agentRules entry name must be a non-empty string" }),
-})
-    .passthrough();
+export const McpServerEntrySchema = z.object({
+    name: nameField,
+    agents: agentsField,
+    // Raw server descriptor passed verbatim to each agent adapter.
+    // Adapters are responsible for validating the shape they need.
+    config: z.record(z.string(), z.unknown()),
+});
+export const AgentRuleEntrySchema = z.object({
+    name: nameField,
+    agents: agentsField,
+    // Relative path to the rules/instruction file within the source bundle.
+    path: sourcePathField,
+});
 export const ManifestSchema = z.object({
     skills: z.array(SkillEntrySchema).superRefine((skills, ctx) => {
         const seen = new Set();

package/dist/types.d.ts

@@ -9,6 +9,8 @@ export interface AgentProvenance {
     skills: Confidence;
     detectPaths: Confidence;
     detectBinary: Confidence;
+    mcpConfig?: Confidence;
+    agentRules?: Confidence;
 }
 export interface AgentConfig {
     id: AgentId;
@@ -17,6 +19,8 @@ export interface AgentConfig {
     detectPaths: AgentPaths;
     detectBinary: string | null;
     provenance: AgentProvenance;
+    mcpConfigPath?: AgentPaths;
+    agentRulesPath?: AgentPaths;
     policyNote?: string;
 }
 export interface PlanWarning {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.8.0",
+  "version": "0.10.1",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",
@@ -38,11 +38,13 @@
     "typecheck": "tsc --noEmit",
     "fmt": "biome format --write .",
     "lint": "biome lint . --max-diagnostics none",
+    "lint:fix": "biome lint . --max-diagnostics none --write --unsafe",
     "predev": "node scripts/assert-direct-ts-node.mjs",
     "dev": "node src/index.ts",
     "pretest": "node scripts/assert-direct-ts-node.mjs",
-    "test": "node --test test/*.test.ts",
-    "prepublishOnly": "npm run typecheck && npm run lint && npm run build"
+    "test": "node --test --test-isolation=none test/**/*.test.ts",
+    "test:windows": "node --test --test-isolation=none test/unit/*.test.ts test/os/cross-platform/*.test.ts test/os/windows/*.test.ts",
+    "test:posix": "node --test --test-isolation=none test/unit/*.test.ts test/os/cross-platform/*.test.ts test/os/posix/*.test.ts"
   },
   "dependencies": {
     "zod": "^4.0.0"