@kuznai/inception-engine 0.25.0 → 1.0.0

package/dist/src/core/revert.js

@@ -186,7 +186,18 @@ export async function executeRevert(actions, dryRun, verbose, home, deps = {}, s
         registry: runRegistry,
     };
     if (!dryRun) {
-        await runRegistry.preflight(home);
+        try {
+            await runRegistry.preflight(home);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                succeeded: 0,
+                skipped: 0,
+                failed: actions.map((action) => ({ action, error: message })),
+                planned,
+            };
+        }
     }
     for (const action of actions) {
         if (signal?.aborted)

package/dist/src/core/validation.d.ts

@@ -1,6 +1,18 @@
 import type { AgentId } from "../schemas/manifest.ts";
 export declare function sourceAccessError(err: unknown, sourcePath: string): string;
 export declare function validateSourcePath(source: string, skillPath: string, resolvedSourceDir: string, realRoot: string): Promise<void>;
+export type SourcePathValidator = (source: string, manifestPath: string, resolvedSourceDir: string) => Promise<void>;
+/**
+ * Returns a memoizing source-path validator bound to a single `realRoot`.
+ *
+ * The cheap out-of-root string gate still runs on every call so per-entry
+ * `manifestPath` error messages remain accurate. The realpath resolution and
+ * the identity-based ancestor walk are memoized per resolved `source`, which
+ * eliminates repeated syscalls when the same source is referenced across
+ * multiple manifest sections or fans out to multiple agents within one
+ * `planDeploy` invocation.
+ */
+export declare function createSourcePathValidator(realRoot: string): SourcePathValidator;
 export declare function validateSourceFile(sourcePath: string, manifestPath: string): Promise<void>;
 export declare function validateMcpServerConfigShape(config: Record<string, unknown>, entryName: string, agentId: string): void;
 export declare function validatePermissionsConfigShape(config: Record<string, unknown>, entryName: string, agentId: string): void;
@@ -11,7 +23,23 @@ export declare function validateSkillDefinitionFile(sourcePath: string, manifest
     body: string;
 }>;
 /**
- * Validates that an instruction file (agentRules or agentDefinitions) meets
- * the structural requirements of the target agent.
+ * Returns true when the agent requires its instruction-file source to expose
+ * structural YAML frontmatter. Used by adapters to decide whether to parse
+ * the source document before per-agent validation.
+ */
+export declare function instructionRequiresFrontmatter(agentId: AgentId): boolean;
+/**
+ * Reads and parses an instruction file's YAML frontmatter once. Callers that
+ * fan out to multiple target agents should invoke this at most once per
+ * source file and reuse the returned attributes for each
+ * `validateInstructionAgentRequirements` call.
+ */
+export declare function parseInstructionDocument(sourcePath: string, manifestPath: string): Promise<{
+    attributes: Record<string, unknown>;
+    body: string;
+}>;
+/**
+ * Runs the per-agent structural checks against an already-parsed instruction
+ * document. Agents without frontmatter requirements are a no-op.
  */
-export declare function validateInstructionFileRequirements(sourcePath: string, manifestPath: string, agentId: AgentId): Promise<void>;
+export declare function validateInstructionAgentRequirements(attributes: Record<string, unknown>, manifestPath: string, agentId: AgentId): void;

package/dist/src/core/validation.js

@@ -54,6 +54,47 @@ export async function validateSourcePath(source, skillPath, resolvedSourceDir, r
         // Source doesn't exist yet — will be caught during execute
     }
 }
+/**
+ * Returns a memoizing source-path validator bound to a single `realRoot`.
+ *
+ * The cheap out-of-root string gate still runs on every call so per-entry
+ * `manifestPath` error messages remain accurate. The realpath resolution and
+ * the identity-based ancestor walk are memoized per resolved `source`, which
+ * eliminates repeated syscalls when the same source is referenced across
+ * multiple manifest sections or fans out to multiple agents within one
+ * `planDeploy` invocation.
+ */
+export function createSourcePathValidator(realRoot) {
+    const cache = new Map();
+    const resolveOutcome = async (source) => {
+        try {
+            const realSource = await realpath(source);
+            if (isSameOrDescendantPath(realSource, realRoot) ||
+                (await isWithinRootByIdentity(realSource, realRoot))) {
+                return { kind: "ok" };
+            }
+            return { kind: "escape", realSource };
+        }
+        catch {
+            // Source doesn't exist yet — will be caught during execute
+            return { kind: "ok" };
+        }
+    };
+    return async (source, manifestPath, resolvedSourceDir) => {
+        if (!source.startsWith(resolvedSourceDir + path.sep)) {
+            throw new UserError("DEPLOY_FAILED", `Skill path "${manifestPath}" resolves outside the repository root: ${source}`);
+        }
+        let pending = cache.get(source);
+        if (!pending) {
+            pending = resolveOutcome(source);
+            cache.set(source, pending);
+        }
+        const outcome = await pending;
+        if (outcome.kind === "escape") {
+            throw new UserError("DEPLOY_FAILED", `Skill path "${manifestPath}" resolves outside the repository root via symlink: ${source} -> ${outcome.realSource}`);
+        }
+    };
+}
 export async function validateSourceFile(sourcePath, manifestPath) {
     let stat;
     try {
@@ -308,24 +349,37 @@ function validateAntigravityRequirements(attributes, manifestPath) {
     }
 }
 /**
- * Validates that an instruction file (agentRules or agentDefinitions) meets
- * the structural requirements of the target agent.
+ * Returns true when the agent requires its instruction-file source to expose
+ * structural YAML frontmatter. Used by adapters to decide whether to parse
+ * the source document before per-agent validation.
  */
-export async function validateInstructionFileRequirements(sourcePath, manifestPath, agentId) {
-    const requiresFrontmatter = AGENT_REGISTRY_BY_ID[agentId]?.instructionFrontmatterRequired === true;
-    if (!requiresFrontmatter)
-        return;
-    let attributes;
+export function instructionRequiresFrontmatter(agentId) {
+    return AGENT_REGISTRY_BY_ID[agentId]?.instructionFrontmatterRequired === true;
+}
+/**
+ * Reads and parses an instruction file's YAML frontmatter once. Callers that
+ * fan out to multiple target agents should invoke this at most once per
+ * source file and reuse the returned attributes for each
+ * `validateInstructionAgentRequirements` call.
+ */
+export async function parseInstructionDocument(sourcePath, manifestPath) {
     try {
-        const result = await validateSkillDefinitionFile(sourcePath, manifestPath);
-        attributes = result.attributes;
+        return await validateSkillDefinitionFile(sourcePath, manifestPath);
     }
     catch (err) {
         if (err instanceof UserError) {
-            throw new UserError("DEPLOY_FAILED", `Instruction file "${manifestPath}" for agent "${agentId}" failed structural validation: ${err.message}`);
+            throw new UserError("DEPLOY_FAILED", `Instruction file "${manifestPath}" failed structural validation: ${err.message}`, { cause: err });
         }
         throw err;
     }
+}
+/**
+ * Runs the per-agent structural checks against an already-parsed instruction
+ * document. Agents without frontmatter requirements are a no-op.
+ */
+export function validateInstructionAgentRequirements(attributes, manifestPath, agentId) {
+    if (!instructionRequiresFrontmatter(agentId))
+        return;
     if (agentId === "github-copilot") {
         validateGithubCopilotRequirements(attributes, manifestPath);
     }

package/dist/src/schemas/manifest.js

@@ -55,7 +55,7 @@ const targetTemplateField = z
     .string({ message: "target must be a non-empty string" })
     .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}, {xdg_config}, or {repo}",
+    message: "target must start with a known placeholder: {home}, {appdata}, {xdg_config}, {repo}, or {workspace}",
 })
     .refine((t) => !t.split(/[\\/]+/).includes(".."), {
     message: "target must not escape its placeholder root",

package/dist/src/types.d.ts

@@ -120,7 +120,7 @@ export interface AgentConfig {
     unsupportedSurfaces?: AgentSurfaceSupport[];
     /**
      * When true, instruction files deployed to this agent must include valid
-     * YAML frontmatter. Drives validateInstructionFileRequirements without
+     * YAML frontmatter. Drives instructionRequiresFrontmatter without
      * hardcoded agent-ID checks.
      */
     instructionFrontmatterRequired?: boolean;

package/dist/test/os/windows/deploy.test.js

@@ -1,9 +1,9 @@
 import assert from "node:assert/strict";
-import { chmod, mkdir, rm, writeFile } from "node:fs/promises";
+import { mkdir, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { describe, it } from "node:test";
 import { executeDeploy, planDeploy } from "../../../src/core/deploy.js";
-import { lookupDeployment, registerDeployment, } from "../../../src/core/ownership.js";
+import { defaultRegistryPersistence, lookupDeployment, registerDeployment, } from "../../../src/core/ownership.js";
 import { UserError } from "../../../src/errors.js";
 import { exists, makeTmpDir } from "../../helpers/fs.js";
 import { createSkillSource, testSkillManifest, } from "../../helpers/skill-dir.js";
@@ -215,9 +215,16 @@ describe("atomic redeploy behavior (Windows)", {
             const backupPath = `${target}.inception-backup`;
             const { succeeded: firstSucceeded } = await executeDeploy(actions, false, false, home);
             assert.equal(firstSucceeded, 1);
-            const registryFile = path.join(home, ".inception-engine", "registry.json");
-            await chmod(registryFile, 0o444);
-            const { succeeded, failed } = await executeDeploy(actions, false, false, home);
+            // Simulate an unwritable registry via a failing RegistryPersistence
+            // instead of relying on chmod, which is not enforced for admin processes
+            // on Windows (e.g. GitHub Actions windows-latest runners).
+            const failingRegistry = {
+                load: (h) => defaultRegistryPersistence.load(h),
+                save: async () => {
+                    throw Object.assign(new Error("EACCES: permission denied, open 'registry.json'"), { code: "EACCES" });
+                },
+            };
+            const { succeeded, failed } = await executeDeploy(actions, false, false, home, { registry: failingRegistry });
             assert.equal(succeeded, 0);
             assert.equal(failed.length, 1);
             assert.ok(!(await exists(backupPath)));
@@ -225,12 +232,6 @@ describe("atomic redeploy behavior (Windows)", {
             assert.ok(await exists(path.join(target, "SKILL.md")));
         }
         finally {
-            try {
-                await chmod(path.join(home, ".inception-engine", "registry.json"), 0o666);
-            }
-            catch {
-                // best effort
-            }
             await rm(sourceDir, { recursive: true, force: true });
             await rm(home, { recursive: true, force: true });
         }