@kuznai/inception-engine 0.5.0 → 0.6.0

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,15 @@ 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`);
         }
+        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 = [];
@@ -45,8 +54,8 @@ export async function executeDeploy(actions, dryRun, verbose, home) {
         try {
             await access(action.source);
         }
-        catch {
-            const msg = `Source not found: ${action.source}`;
+        catch (err) {
+            const msg = sourceAccessError(err, action.source);
             failed.push({ action, error: msg });
             logger.fail(label, msg);
             continue;

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

@@ -31,19 +31,30 @@ export function planRevertAll(manifest, home) {
     }
     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") {
+        if (result.outcome === "fail") {
+            failed.push({ action, error: result.error });
+        }
+        else if (result.outcome === "skip") {
             skipped++;
         }
         else {
             succeeded++;
         }
     }
-    return { succeeded, skipped };
+    return { succeeded, skipped, failed };
 }
 async function executeRevertAction(action, dryRun, verbose, home) {
     const label = `${action.skill} -> ${action.agent}`;
@@ -51,21 +62,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 +95,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.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.core.$strip>;
+export declare const ManifestSchema: z.ZodObject<{
+    skills: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        path: z.ZodString;
+        agents: 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.core.$strip>>;
+    mcpServers: z.ZodCatch<z.ZodArray<z.ZodUnknown>>;
+    agentRules: z.ZodCatch<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,58 @@
+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" }),
+});
+export const ManifestSchema = z.object({
+    skills: z.array(SkillEntrySchema),
+    mcpServers: z.array(z.unknown()).catch([]),
+    agentRules: z.array(z.unknown()).catch([]),
+});
+// 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[];

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.0",
   "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",