@kuznai/inception-engine 0.5.0 → 0.6.2

package/dist/config/manifest.d.ts

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

package/dist/config/manifest.js

@@ -1,15 +1,24 @@
 import { readFile } from "node:fs/promises";
 import path from "node:path";
+import { formatZodPath } from "../schemas/errors.js";
+import { ManifestSchema } from "../schemas/manifest.js";
 import { UserError } from "../errors.js";
-import { AGENT_IDS } from "../types.js";
 export async function loadManifest(directory) {
     const manifestPath = path.join(directory, "inception.json");
     let raw;
     try {
         raw = await readFile(manifestPath, "utf-8");
     }
-    catch {
-        throw new UserError("MANIFEST_INVALID", `No inception.json found in ${directory}. Are you pointing to the right repo?`);
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            throw new UserError("MANIFEST_INVALID", `No inception.json found in ${directory}. Are you pointing to the right repo?`);
+        }
+        if (code === "EACCES" || code === "EPERM") {
+            throw new UserError("MANIFEST_INVALID", `Permission denied reading ${manifestPath}. Check file permissions.`);
+        }
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new UserError("MANIFEST_INVALID", `Failed to read ${manifestPath}: ${detail}`);
     }
     let parsed;
     try {
@@ -21,52 +30,20 @@ export async function loadManifest(directory) {
     return validateManifest(parsed, manifestPath);
 }
 function validateManifest(data, filePath) {
-    if (typeof data !== "object" || data === null || Array.isArray(data)) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: manifest must be a JSON object`);
-    }
-    const obj = data;
-    if (!Array.isArray(obj.skills)) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: "skills" must be an array`);
-    }
-    const skills = obj.skills.map((entry, i) => validateSkillEntry(entry, i, filePath));
-    return {
-        skills,
-        mcpServers: Array.isArray(obj.mcpServers) ? obj.mcpServers : [],
-        agentRules: Array.isArray(obj.agentRules) ? obj.agentRules : [],
-    };
-}
-const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
-function validateSkillEntry(entry, i, filePath) {
-    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}] must be an object`);
-    }
-    const skill = entry;
-    if (typeof skill.name !== "string" || skill.name.length === 0) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].name must be a non-empty string`);
-    }
-    if (!SAFE_NAME_RE.test(skill.name)) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].name must contain only letters, digits, hyphens, underscores, and dots, and must not start with a dot`);
-    }
-    if (typeof skill.path !== "string" || skill.path.length === 0) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].path must be a non-empty string`);
-    }
-    if (path.isAbsolute(skill.path)) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].path must be a relative path`);
-    }
-    if (path.normalize(skill.path).startsWith("..")) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].path must not escape the repository root`);
-    }
-    if (!Array.isArray(skill.agents) || skill.agents.length === 0) {
-        throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].agents must be a non-empty array`);
-    }
-    for (const agent of skill.agents) {
-        if (!AGENT_IDS.includes(agent)) {
-            throw new UserError("MANIFEST_INVALID", `${filePath}: skills[${i}].agents contains unknown agent "${agent}". Valid agents: ${AGENT_IDS.join(", ")}`);
+    const result = ManifestSchema.safeParse(data);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        const issuePath = issue.path;
+        // Top-level "skills" key: missing or wrong type → uniform message
+        if (issuePath.length === 1 && issuePath[0] === "skills") {
+            throw new UserError("MANIFEST_INVALID", `${filePath}: "skills" must be an array`);
+        }
+        // Top-level "mcpServers" or "agentRules": wrong type → uniform message
+        if (issuePath.length === 1 &&
+            (issuePath[0] === "mcpServers" || issuePath[0] === "agentRules")) {
+            throw new UserError("MANIFEST_INVALID", `${filePath}: "${issuePath[0]}" must be an array`);
         }
+        throw new UserError("MANIFEST_INVALID", `${filePath}: ${formatZodPath(issuePath)}${issue.message}`);
     }
-    return {
-        name: skill.name,
-        path: skill.path,
-        agents: skill.agents,
-    };
+    return result.data;
 }

package/dist/core/deploy.js

@@ -5,6 +5,15 @@ import { UserError } from "../errors.js";
 import { logger } from "../logger.js";
 import { registerDeployment, verifyDeployment } from "./ownership.js";
 import { getDeployMethod, resolveAgentSkillPath } from "./resolve.js";
+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}`;
+}
 export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
     const method = getDeployMethod();
     const actions = [];
@@ -19,6 +28,7 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
     for (const skill of manifest.skills) {
         const source = path.resolve(sourceDir, skill.path);
         await validateSourcePath(source, skill.path, resolvedSourceDir, realRoot);
+        await validateSkillContract(source, skill.path);
         for (const agentId of skill.agents) {
             if (!detectedAgents.includes(agentId))
                 continue;
@@ -27,6 +37,7 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
                 continue;
             const target = resolveAgentSkillPath(agent, skill.name, home);
             actions.push({
+                kind: "skill-dir",
                 skill: skill.name,
                 agent: agentId,
                 source,
@@ -41,36 +52,52 @@ export async function executeDeploy(actions, dryRun, verbose, home) {
     let succeeded = 0;
     const failed = [];
     for (const action of actions) {
-        const label = `${action.skill} -> ${action.agent}`;
-        try {
-            await access(action.source);
-        }
-        catch {
-            const msg = `Source not found: ${action.source}`;
-            failed.push({ action, error: msg });
-            logger.fail(label, msg);
-            continue;
-        }
-        if (dryRun) {
-            logger.plan(label);
-            if (verbose) {
-                logger.detail(`${action.method}: ${action.source} -> ${action.target}`);
+        switch (action.kind) {
+            case "skill-dir": {
+                const result = await deploySkillDir(action, dryRun, verbose, home);
+                if (result.error === null) {
+                    succeeded++;
+                }
+                else {
+                    failed.push({ action, error: result.error });
+                }
+                break;
+            }
+            default: {
+                const _ = action.kind;
+                throw new Error(`Unhandled deploy action kind: ${_}`);
             }
-            succeeded++;
-            continue;
-        }
-        try {
-            await executeDeployAction(action, verbose, home);
-            succeeded++;
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            failed.push({ action, error: msg });
-            logger.fail(label, msg);
         }
     }
     return { succeeded, failed };
 }
+async function deploySkillDir(action, dryRun, verbose, home) {
+    const label = `${action.skill} -> ${action.agent}`;
+    try {
+        await access(action.source);
+    }
+    catch (err) {
+        const msg = sourceAccessError(err, action.source);
+        logger.fail(label, msg);
+        return { error: msg };
+    }
+    if (dryRun) {
+        logger.plan(label);
+        if (verbose) {
+            logger.detail(`${action.method}: ${action.source} -> ${action.target}`);
+        }
+        return { error: null };
+    }
+    try {
+        await executeDeployAction(action, verbose, home);
+        return { error: null };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.fail(label, msg);
+        return { error: msg };
+    }
+}
 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}`);
@@ -88,6 +115,31 @@ async function validateSourcePath(source, skillPath, resolvedSourceDir, realRoot
         // Source doesn't exist yet — will be caught during execute
     }
 }
+async function validateSkillContract(source, skillPath) {
+    let stat;
+    try {
+        stat = await lstat(source);
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT") {
+            throw new UserError("DEPLOY_FAILED", `Skill "${skillPath}" source not found: ${source}`);
+        }
+        if (code === "EACCES" || code === "EPERM") {
+            throw new UserError("DEPLOY_FAILED", `Permission denied accessing skill "${skillPath}" source: ${source}`);
+        }
+        throw new UserError("DEPLOY_FAILED", `Cannot access skill "${skillPath}" source: ${source}`);
+    }
+    if (!stat.isDirectory()) {
+        throw new UserError("DEPLOY_FAILED", `Skill "${skillPath}" source is not a directory: ${source}`);
+    }
+    try {
+        await access(path.join(source, "SKILL.md"));
+    }
+    catch {
+        throw new UserError("DEPLOY_FAILED", `Skill "${skillPath}" source is missing SKILL.md: ${source}`);
+    }
+}
 async function assertTargetAbsent(targetPath) {
     try {
         await lstat(targetPath);

package/dist/core/detect.d.ts

@@ -1,2 +1,7 @@
 import type { AgentId } from "../types.ts";
+export type ExecFn = (cmd: string, args: readonly string[]) => Promise<void>;
 export declare function detectInstalledAgents(home: string): Promise<AgentId[]>;
+export declare function isBinaryInPath(binary: string, execFn?: ExecFn): Promise<boolean>;
+export declare function isBinaryViaWhereExe(binary: string, execFn?: ExecFn): Promise<boolean>;
+export declare function isBinaryViaCommandV(binary: string): Promise<boolean>;
+export declare function isBinaryViaWhich(binary: string, execFn?: ExecFn): Promise<boolean>;

package/dist/core/detect.js

@@ -4,6 +4,9 @@ import { promisify } from "node:util";
 import { AGENT_REGISTRY } from "../config/agents.js";
 import { resolveAgentDetectPath } from "./resolve.js";
 const execFileAsync = promisify(execFile);
+const defaultExecFn = async (cmd, args) => {
+    await execFileAsync(cmd, args);
+};
 export async function detectInstalledAgents(home) {
     const detected = [];
     for (const agent of AGENT_REGISTRY) {
@@ -27,18 +30,12 @@ async function isAgentInstalled(agent, home) {
     }
     return false;
 }
-async function isBinaryInPath(binary) {
+export async function isBinaryInPath(binary, execFn = defaultExecFn) {
     if (process.platform === "win32") {
-        try {
-            await execFileAsync("where.exe", [binary]);
-            return true;
-        }
-        catch {
-            return false;
-        }
+        return isBinaryViaWhereExe(binary, execFn);
     }
     try {
-        await execFileAsync("which", [binary]);
+        await execFn("which", [binary]);
         return true;
     }
     catch (err) {
@@ -49,9 +46,19 @@ async function isBinaryInPath(binary) {
         return false;
     }
 }
+// Windows-only: use where.exe to check if a binary is in PATH.
+export async function isBinaryViaWhereExe(binary, execFn = defaultExecFn) {
+    try {
+        await execFn("where.exe", [binary]);
+        return true;
+    }
+    catch {
+        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) {
+export async function isBinaryViaCommandV(binary) {
     try {
         // Pass binary as a positional arg ($1) to avoid any shell-injection risk.
         await execFileAsync("sh", ["-c", 'command -v "$1"', "--", binary]);
@@ -61,6 +68,16 @@ async function isBinaryViaCommandV(binary) {
         return false;
     }
 }
+// POSIX: use `which` to check if a binary is in PATH.
+export async function isBinaryViaWhich(binary, execFn = defaultExecFn) {
+    try {
+        await execFn("which", [binary]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function isENOENT(err) {
     return (typeof err === "object" &&
         err !== null &&

package/dist/core/ownership.d.ts

@@ -1,11 +1,6 @@
+import { type RegistryEntry } from "../schemas/registry.ts";
 import type { AgentId } from "../types.ts";
-export interface RegistryEntry {
-    source: string;
-    skill: string;
-    agent: AgentId;
-    method: "symlink" | "copy";
-    deployed: string;
-}
+export type { RegistryEntry } from "../schemas/registry.ts";
 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>;

package/dist/core/ownership.js

@@ -1,5 +1,6 @@
 import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { RegistrySchema, } from "../schemas/registry.js";
 const REGISTRY_DIR = ".inception-engine";
 const REGISTRY_FILE = "registry.json";
 export function registryPath(home) {
@@ -9,14 +10,8 @@ async function loadRegistry(home) {
     try {
         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();
+        const result = RegistrySchema.safeParse(parsed);
+        return result.success ? result.data : emptyRegistry();
     }
     catch {
         return emptyRegistry();

package/dist/core/preflight.d.ts

@@ -0,0 +1,6 @@
+import type { CliOptions, Manifest } from "../types.ts";
+export interface PreflightWarning {
+    kind: "policy" | "config-authority" | "info";
+    message: string;
+}
+export declare function runPreflight(_options: CliOptions, _manifest: Manifest, _home: string): Promise<PreflightWarning[]>;

package/dist/core/preflight.js

@@ -0,0 +1,6 @@
+export async function runPreflight(_options, _manifest, _home) {
+    // Extension point for future enterprise policy checks.
+    // Future additions: check for local-config overrides, policy files,
+    // agent version constraints, etc.
+    return [];
+}

package/dist/core/revert.d.ts

@@ -4,4 +4,8 @@ export declare function planRevertAll(manifest: Manifest, home: string): RevertA
 export declare function executeRevert(actions: RevertAction[], dryRun: boolean, verbose: boolean, home: string): Promise<{
     succeeded: number;
     skipped: number;
+    failed: Array<{
+        action: RevertAction;
+        error: string;
+    }>;
 }>;

package/dist/core/revert.js

@@ -13,7 +13,12 @@ export function planRevert(manifest, detectedAgents, home) {
             if (!agent)
                 continue;
             const target = resolveAgentSkillPath(agent, skill.name, home);
-            actions.push({ skill: skill.name, agent: agentId, target });
+            actions.push({
+                kind: "skill-dir",
+                skill: skill.name,
+                agent: agentId,
+                target,
+            });
         }
     }
     return actions;
@@ -26,24 +31,49 @@ export function planRevertAll(manifest, home) {
             if (!agent)
                 continue;
             const target = resolveAgentSkillPath(agent, skill.name, home);
-            actions.push({ skill: skill.name, agent: agentId, target });
+            actions.push({
+                kind: "skill-dir",
+                skill: skill.name,
+                agent: agentId,
+                target,
+            });
         }
     }
     return actions;
 }
+function lstatOutcome(err) {
+    if (err.code === "ENOENT") {
+        return { outcome: "skip" };
+    }
+    const msg = err instanceof Error ? err.message : String(err);
+    return { outcome: "fail", error: msg };
+}
 export async function executeRevert(actions, dryRun, verbose, home) {
     let succeeded = 0;
     let skipped = 0;
+    const failed = [];
     for (const action of actions) {
-        const result = await executeRevertAction(action, dryRun, verbose, home);
-        if (result === "skip") {
-            skipped++;
-        }
-        else {
-            succeeded++;
+        switch (action.kind) {
+            case "skill-dir": {
+                const result = await executeRevertAction(action, dryRun, verbose, home);
+                if (result.outcome === "fail") {
+                    failed.push({ action, error: result.error });
+                }
+                else if (result.outcome === "skip") {
+                    skipped++;
+                }
+                else {
+                    succeeded++;
+                }
+                break;
+            }
+            default: {
+                const _ = action.kind;
+                throw new Error(`Unhandled revert action kind: ${_}`);
+            }
         }
     }
-    return { succeeded, skipped };
+    return { succeeded, skipped, failed };
 }
 async function executeRevertAction(action, dryRun, verbose, home) {
     const label = `${action.skill} -> ${action.agent}`;
@@ -51,21 +81,26 @@ async function executeRevertAction(action, dryRun, verbose, home) {
     try {
         stat = await lstat(action.target);
     }
-    catch {
-        logger.skip(label, "(not found, skipping)");
-        return "skip";
+    catch (err) {
+        const result = lstatOutcome(err);
+        if (result.outcome === "skip") {
+            logger.skip(label, "(not found, skipping)");
+            return result;
+        }
+        logger.fail(label, result.error);
+        return result;
     }
     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";
+        return { outcome: "skip" };
     }
     if (dryRun) {
         logger.plan(label);
         if (verbose) {
             logger.detail(`would remove: ${action.target}`);
         }
-        return "ok";
+        return { outcome: "ok" };
     }
     try {
         if (stat.isSymbolicLink()) {
@@ -79,11 +114,11 @@ async function executeRevertAction(action, dryRun, verbose, home) {
         if (verbose) {
             logger.detail(`removed: ${action.target}`);
         }
-        return "ok";
+        return { outcome: "ok" };
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
         logger.fail(label, msg);
-        return "skip";
+        return { outcome: "fail", error: msg };
     }
 }

package/dist/index.js

@@ -6,10 +6,11 @@ import { loadManifest } from "./config/manifest.js";
 import { executeDeploy, planDeploy } from "./core/deploy.js";
 import { detectInstalledAgents } from "./core/detect.js";
 import { resolveHome } from "./core/resolve.js";
+import { runPreflight } from "./core/preflight.js";
 import { executeRevert, planRevert, planRevertAll } from "./core/revert.js";
 import { UserError } from "./errors.js";
 import { dryRunPrefix, logger } from "./logger.js";
-import { AGENT_IDS } from "./types.js";
+import { AgentListSchema } from "./schemas/manifest.js";
 const USAGE = `
 inception-engine - Deploy AI agent skills
 
@@ -82,13 +83,11 @@ function parseCLI(argv) {
     }
     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(", ")}`);
-            }
+        const r = AgentListSchema.safeParse(values.agents);
+        if (!r.success) {
+            throw new UserError("INVALID_ARGS", r.error.issues[0].message);
         }
-        agents = ids;
+        agents = r.data;
     }
     return {
         command,
@@ -107,6 +106,10 @@ async function main() {
     }
     const manifest = await loadManifest(options.directory);
     const home = resolveHome();
+    const preflightWarnings = await runPreflight(options, manifest, home);
+    for (const w of preflightWarnings) {
+        logger.warn("preflight", w.message);
+    }
     if (options.command === "deploy") {
         return runDeploy(options, manifest, home);
     }
@@ -155,8 +158,16 @@ 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, home);
+    const { succeeded, skipped, failed } = await executeRevert(actions, options.dryRun, options.verbose, home);
     logger.info("");
+    if (failed.length > 0) {
+        const parts = [`${succeeded} removed`];
+        if (skipped > 0)
+            parts.push(`${skipped} skipped`);
+        parts.push(`${failed.length} failed`);
+        logger.info(`${parts.join(", ")}${options.dryRun ? " (dry-run)" : ""}`);
+        return 1;
+    }
     const parts = [`${succeeded} removed`];
     if (skipped > 0)
         parts.push(`${skipped} skipped`);

package/dist/schemas/errors.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Shared helpers for mapping Zod parse errors to user-facing messages.
+ */
+export declare function formatZodPath(path: (string | number)[]): string;

package/dist/schemas/errors.js

@@ -0,0 +1,14 @@
+/**
+ * Shared helpers for mapping Zod parse errors to user-facing messages.
+ */
+export function formatZodPath(path) {
+    if (path.length === 0)
+        return "";
+    return `${path
+        .map((seg, i) => {
+        if (typeof seg === "number")
+            return `[${seg}]`;
+        return i === 0 ? seg : `.${seg}`;
+    })
+        .join("")} `;
+}

package/dist/schemas/manifest.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+declare const AGENT_IDS: readonly ["claude-code", "codex", "gemini-cli", "antigravity", "opencode", "github-copilot"];
+export { AGENT_IDS };
+export declare const AgentIdSchema: z.ZodEnum<{
+    "claude-code": "claude-code";
+    codex: "codex";
+    "gemini-cli": "gemini-cli";
+    antigravity: "antigravity";
+    opencode: "opencode";
+    "github-copilot": "github-copilot";
+}>;
+export type AgentId = z.output<typeof AgentIdSchema>;
+export declare const SkillEntrySchema: z.ZodObject<{
+    name: z.ZodString;
+    path: z.ZodString;
+    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")[]>>;
+}, z.core.$strip>;
+export declare const ManifestSchema: z.ZodObject<{
+    skills: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        path: z.ZodString;
+        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")[]>>;
+    }, z.core.$strip>>;
+    mcpServers: z.ZodDefault<z.ZodArray<z.ZodUnknown>>;
+    agentRules: z.ZodDefault<z.ZodArray<z.ZodUnknown>>;
+}, z.core.$strip>;
+export type SkillEntry = z.infer<typeof SkillEntrySchema>;
+export type Manifest = z.infer<typeof ManifestSchema>;
+export declare const AgentListSchema: z.ZodPipe<z.ZodPipe<z.ZodString, z.ZodTransform<string[], string>>, 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";
+}>>>>;

package/dist/schemas/manifest.js

@@ -0,0 +1,71 @@
+import nodePath from "node:path";
+import { z } from "zod";
+const AGENT_IDS = [
+    "claude-code",
+    "codex",
+    "gemini-cli",
+    "antigravity",
+    "opencode",
+    "github-copilot",
+];
+export { AGENT_IDS };
+const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+// 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
+// value in the message (Zod 4's invalid_value issue omits the received value).
+// The .pipe(AgentIdSchema) at the end provides the AgentId output type.
+const agentIdElement = z
+    .string()
+    .superRefine((v, ctx) => {
+    if (!AGENT_IDS.includes(v)) {
+        ctx.addIssue({
+            code: "custom",
+            message: `unknown agent "${v}". Valid agents: ${AGENT_IDS.join(", ")}`,
+        });
+    }
+})
+    .pipe(AgentIdSchema);
+export const SkillEntrySchema = z.object({
+    name: z
+        .string({ message: "name must be a non-empty string" })
+        .min(1, { message: "name must be a non-empty string" })
+        .regex(SAFE_NAME_RE, {
+        message: "name must contain only letters, digits, hyphens, underscores, and dots, and must not start with a dot",
+    }),
+    path: z
+        .string({ message: "path must be a non-empty string" })
+        .min(1, { message: "path must be a non-empty string" })
+        .refine((p) => !nodePath.isAbsolute(p), {
+        message: "path must be a relative path",
+    })
+        .refine((p) => !nodePath.normalize(p).startsWith(".."), {
+        message: "path must not escape the repository root",
+    }),
+    agents: z
+        .array(agentIdElement, { message: "agents must be a non-empty array" })
+        .min(1, { message: "agents must be a non-empty array" })
+        .transform((arr) => [...new Set(arr)]),
+});
+export const ManifestSchema = z.object({
+    skills: z.array(SkillEntrySchema).superRefine((skills, ctx) => {
+        const seen = new Set();
+        for (const [i, skill] of skills.entries()) {
+            if (seen.has(skill.name)) {
+                ctx.addIssue({
+                    code: "custom",
+                    path: [i, "name"],
+                    message: `duplicate skill name "${skill.name}"`,
+                });
+            }
+            seen.add(skill.name);
+        }
+    }),
+    mcpServers: z.array(z.unknown()).default([]),
+    agentRules: z.array(z.unknown()).default([]),
+});
+// Parses the --agents CLI flag: comma-separated agent IDs → AgentId[]
+export const AgentListSchema = z
+    .string()
+    .transform((s) => s.split(",").map((id) => id.trim()))
+    .pipe(z.array(agentIdElement).min(1, { message: "agent list must not be empty" }));

package/dist/schemas/registry.d.ts

@@ -0,0 +1,40 @@
+import { z } from "zod";
+export declare const RegistryEntrySchema: z.ZodObject<{
+    source: z.ZodString;
+    skill: z.ZodString;
+    agent: z.ZodEnum<{
+        "claude-code": "claude-code";
+        codex: "codex";
+        "gemini-cli": "gemini-cli";
+        antigravity: "antigravity";
+        opencode: "opencode";
+        "github-copilot": "github-copilot";
+    }>;
+    method: z.ZodEnum<{
+        symlink: "symlink";
+        copy: "copy";
+    }>;
+    deployed: z.ZodString;
+}, z.core.$strip>;
+export declare const RegistrySchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    deployments: z.ZodRecord<z.ZodString, z.ZodObject<{
+        source: z.ZodString;
+        skill: z.ZodString;
+        agent: z.ZodEnum<{
+            "claude-code": "claude-code";
+            codex: "codex";
+            "gemini-cli": "gemini-cli";
+            antigravity: "antigravity";
+            opencode: "opencode";
+            "github-copilot": "github-copilot";
+        }>;
+        method: z.ZodEnum<{
+            symlink: "symlink";
+            copy: "copy";
+        }>;
+        deployed: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type RegistryEntry = z.infer<typeof RegistryEntrySchema>;
+export type Registry = z.infer<typeof RegistrySchema>;

package/dist/schemas/registry.js

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { AgentIdSchema } from "./manifest.js";
+export const RegistryEntrySchema = z.object({
+    source: z.string(),
+    skill: z.string(),
+    agent: AgentIdSchema,
+    method: z.enum(["symlink", "copy"]),
+    deployed: z.string(),
+});
+export const RegistrySchema = z.object({
+    version: z.literal(1),
+    deployments: z.record(z.string(), RegistryEntrySchema),
+});

package/dist/types.d.ts

@@ -1,15 +1,5 @@
-export type AgentId = "claude-code" | "codex" | "gemini-cli" | "antigravity" | "opencode" | "github-copilot";
-export declare const AGENT_IDS: readonly AgentId[];
-export interface SkillEntry {
-    name: string;
-    path: string;
-    agents: AgentId[];
-}
-export interface Manifest {
-    skills: SkillEntry[];
-    mcpServers: unknown[];
-    agentRules: unknown[];
-}
+import type { AgentId } from "./schemas/manifest.ts";
+export type { AgentId, Manifest, SkillEntry } from "./schemas/manifest.ts";
 export interface AgentPaths {
     posix: string[];
     windows: string[];
@@ -28,18 +18,22 @@ export interface AgentConfig {
     detectBinary: string | null;
     provenance: AgentProvenance;
 }
-export interface DeployAction {
+export interface SkillDirDeployAction {
+    kind: "skill-dir";
     skill: string;
     agent: AgentId;
     source: string;
     target: string;
     method: "symlink" | "copy";
 }
-export interface RevertAction {
+export type DeployAction = SkillDirDeployAction;
+export interface SkillDirRevertAction {
+    kind: "skill-dir";
     skill: string;
     agent: AgentId;
     target: string;
 }
+export type RevertAction = SkillDirRevertAction;
 export interface CliOptions {
     command: "deploy" | "revert" | "help";
     directory: string;

package/dist/types.js

@@ -1,8 +1 @@
-export const AGENT_IDS = [
-    "claude-code",
-    "codex",
-    "gemini-cli",
-    "antigravity",
-    "opencode",
-    "github-copilot",
-];
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.5.0",
+  "version": "0.6.2",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",
@@ -42,6 +42,9 @@
     "test": "node --test test/*.test.ts",
     "prepublishOnly": "npm run typecheck && npm run lint && npm run build"
   },
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
   "devDependencies": {
     "@biomejs/biome": "^2.4.8",
     "@types/node": "^25.5.0",