@kuznai/inception-engine 0.25.1 → 1.0.0

package/README.md

@@ -10,6 +10,27 @@ The broader portability layer is the roadmap direction, but this README focuses
 
 `init` is available as a bootstrap command. It scans for directories containing `SKILL.md`, discovers agent-rules Markdown files using the Claude-first portability conventions, and reads `mcp-servers.json` from the repo root to populate `mcpServers`. Shared surfaces now default to the primary deploy target in generated manifests: for example, `init` emits `claude-code` rather than `github-copilot` for shared Claude-native skills and rules, and emits `gemini-cli` rather than `antigravity` for shared `GEMINI.md` rules surfaces. `files` and `configs` remain empty — `init` emits guidance when it detects a `files/` or `configs/` directory.
 
+## SBOM
+
+This repo can generate an SPDX SBOM without adding any new runtime dependency by using npm's built-in `sbom` command:
+
+```bash
+npm ci
+npm sbom --sbom-format spdx --omit dev > sbom.spdx.json
+```
+
+`--omit dev` keeps the SBOM focused on the published CLI's runtime dependency graph.
+
+For GitHub Actions, the repository includes [`.github/workflows/sbom.yml`](.github/workflows/sbom.yml). It:
+
+- installs dependencies and runs the normal release checks
+- creates the npm package tarball with `npm pack`
+- generates `dist-artifacts/sbom.spdx.json` via `npm sbom`
+- uploads both the tarball and SBOM as workflow artifacts
+- creates a GitHub artifact attestation that binds the SBOM to the packaged tarball
+
+Run it manually with `workflow_dispatch`, or let it run automatically when a GitHub Release is published.
+
 ## Quick Start
 
 ```bash
@@ -28,6 +49,7 @@ inception-engine reads a manifest file (`inception.json`) from the target direct
 Managed skills overwrite their previous version. If a target exists but was not created by inception-engine, deployment refuses to replace it. On POSIX systems, symlinks mean updates to the source repo are reflected immediately.
 
 Before executing, the deploy command runs preflight analysis on instruction files and capability planning inputs. It validates that `agentRules` and `agentDefinitions` for targets requiring specific structure (like `github-copilot` and `antigravity`) include valid YAML frontmatter with `name` and `description` fields. For `github-copilot`, it further ensures either `tools` or `instructions` are defined; for `antigravity`, it validates the shape of any `mcp-servers` or `mcpServers` defined in the frontmatter. It also warns when a manifest targets a surface that is implementation-only, planned, unsupported, or shared through another agent, when the same agent will have multiple `agentRules` scopes active simultaneously, when the same source file is deployed to multiple scopes (duplicate-content risk), when `agentRules` or `agentDefinitions` source files exceed 50 KB (context-budget risk), and when GitHub Copilot appears to be running under enterprise-managed policy that may override local configuration. Warnings are printed but do not block deployment; structural validation failures block deployment for the affected targets.
+Agent-specific preflight reads and deploy actions targeting distinct files now run with bounded concurrency, while warning order, dry-run output, and deploy result ordering remain deterministic.
 
 ## Agent Compatibility Matrix
 
@@ -183,7 +205,7 @@ Each **file** entry deploys a single file to an agent's configuration location:
 
 - **name** - Unique identifier (same format as skill names)
 - **path** - Relative path to the source file within the repo
-- **target** - Destination path using a placeholder prefix: `{home}`, `{appdata}` (Windows), or `{xdg_config}` (Linux). For example: `{home}/.claude/settings.json`
+- **target** - Destination path using a placeholder prefix: `{home}`, `{appdata}`, `{xdg_config}`, `{repo}`, or `{workspace}`. For example: `{home}/.claude/settings.json`
 - **agents** - Array of agent IDs to deploy this file to
 
 Each **config** entry applies a [JSON merge patch (RFC 7386)](https://datatracker.ietf.org/doc/html/rfc7386) to an existing agent config file:
@@ -230,6 +252,7 @@ Each **agentRules** entry deploys a Markdown instruction file to an agent's supp
   - `"workspace"` — deploys to the workspace-root instruction file when an agent exposes one (e.g., `{workspace}/CLAUDE.md` for `claude-code`); when unsupported, deployment is skipped with a warning
   - `"copilot-repo"` — deploys to GitHub Copilot's native repo-level instruction file at `{repo}/.github/copilot-instructions.md` (`github-copilot` only; other agents are warned and skipped)
   - `"copilot-scoped"` — deploys to `{repo}/.github/instructions/{name}.instructions.md` where `{name}` is the manifest entry name (`github-copilot` only; other agents are warned and skipped)
+- **targetDir** - Optional relative subdirectory under the selected `{repo}` or `{workspace}` root. Only valid with `scope: "repo"` or `scope: "workspace"`. This lets one manifest entry target nested workspaces such as `apps/frontend/CLAUDE.md` without changing the source file path.
 
 Instruction rule deployment is supported for implemented global, repo, and workspace surfaces. The target path depends on the agent and the `scope`:
 
@@ -256,7 +279,7 @@ Each **permissions** entry deploys execution and safety-oriented configuration t
 - **agents** - Array of agent IDs to deploy this entry to
 - **config** - Permission config payload; shape is validated per agent (see below)
 
-Permission deployment is currently supported for `claude-code` and `codex`. Other agents emit a warning and are skipped.
+Permission deployment is currently supported for `claude-code`, `codex`, and `opencode`. Other agents emit a warning and are skipped.
 
 For `claude-code`, the config is merged into `~/.claude/settings.json`. Only the `permissions` key is accepted:
 
@@ -289,6 +312,24 @@ For `codex`, the config is merged into `~/.codex/config.toml`. Only the `approva
 
 Valid `approval_policy` values are `"auto"`, `"manual"`, `"suggest"`, and `"on-failure"`.
 
+For `opencode`, the config is merged into `~/.config/opencode/opencode.json` on POSIX or `%APPDATA%\\opencode\\opencode.json` on Windows. Only the `permissions` key is accepted:
+
+```json
+{
+  "name": "opencode-permissions",
+  "agents": ["opencode"],
+  "config": {
+    "permissions": {
+      "allow": ["Read", "Glob"],
+      "ask": ["Bash(git push:*)"],
+      "deny": ["Bash(rm:*)"]
+    }
+  }
+}
+```
+
+`allow`, `ask`, and `deny` are optional string arrays.
+
 Revert restores the previous config values using the undo patch recorded at deploy time.
 
 Each **hooks** entry deploys lifecycle-binding configurations to an agent's execution hook surface:
@@ -325,6 +366,29 @@ For `claude-code`, the config is merged into `~/.claude/settings.json`. Only the
 
 Revert restores the previous config values using the undo patch recorded at deploy time.
 
+Each **executionConfigs** entry deploys agent execution or safety settings to an agent's modeled runtime config surface:
+
+- **name** - Unique identifier (same format as skill names)
+- **agents** - Array of agent IDs to deploy this entry to
+- **config** - Raw execution-config payload; today this is modeled for `gemini-cli` and patched into its settings file
+
+Execution-config deployment is currently supported for `gemini-cli`. Other agents emit a warning and are skipped. Because this surface is still treated as provisional, preflight emits a config-authority warning when you target it so you can sanity-check the current upstream behavior.
+
+For `gemini-cli`, the config is merged into `~/.gemini/settings.json`:
+
+```json
+{
+  "name": "gemini-safety",
+  "agents": ["gemini-cli"],
+  "config": {
+    "safeMode": true,
+    "sandbox": "workspace-write"
+  }
+}
+```
+
+Values are passed through as a JSON merge patch so the tool can model emerging Gemini CLI execution settings without inventing a separate schema for each key. Revert restores the previous config values using the undo patch recorded at deploy time.
+
 Each **agentDefinitions** entry deploys an agent-definition file to the agent-definition directory of each targeted agent. `scope: "repo"` is the default, and some agents also support `scope: "global"`:
 
 - **name** - Unique identifier (same format as skill names); used as the definition filename
@@ -371,7 +435,7 @@ The `name` and `description` fields in the frontmatter are used by most agents.
 
 ## `init` Command
 
-`init` is meant to bootstrap a repository that already has skills and related manifest assets. It recursively scans the target directory, treats any directory containing `SKILL.md` as a skill, discovers supported instruction and MCP conventions, and writes a starter `inception.json`.
+`init` is meant to bootstrap a repository that already has skills and related manifest assets. It recursively scans the target directory, treats any directory containing `SKILL.md` as a skill, discovers supported instruction and MCP conventions, and writes a starter `inception.json`. The scan uses a bounded-concurrency streaming directory walk so large repositories scale more predictably without changing discovery behavior.
 
 Current `init` behavior:
 

package/dist/src/core/adapters/agent-definitions.d.ts

@@ -1,8 +1,9 @@
 import type { AgentDefinitionEntry } from "../../schemas/manifest.ts";
 import type { AgentId, FileWriteDeployAction, FileWriteRevertAction, PlanWarning } from "../../types.ts";
+import { type SourcePathValidator } from "../validation.ts";
 export interface AgentDefinitionsAdapterResult {
     actions: FileWriteDeployAction[];
     warnings: PlanWarning[];
 }
-export declare function compileAgentDefinitionActions(entry: AgentDefinitionEntry, sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string, workspace?: string): Promise<AgentDefinitionsAdapterResult>;
+export declare function compileAgentDefinitionActions(entry: AgentDefinitionEntry, sourceDir: string, resolvedSourceDir: string, validateSource: SourcePathValidator, detectedAgents: AgentId[], home: string, repo?: string, workspace?: string): Promise<AgentDefinitionsAdapterResult>;
 export declare function compileAgentDefinitionReverts(entry: AgentDefinitionEntry, agentFilter: AgentId[] | null, home: string, repo?: string, workspace?: string): FileWriteRevertAction[];

package/dist/src/core/adapters/agent-definitions.js

@@ -2,7 +2,7 @@ import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
 import { planCapabilityForDeploy, resolveCapabilitySurface, } from "../capabilities.js";
 import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
-import { validateAgentRuleMarkdownPath, validateInstructionFileRequirements, validateSourceFile, validateSourcePath, } from "../validation.js";
+import { instructionRequiresFrontmatter, parseInstructionDocument, validateAgentRuleMarkdownPath, validateInstructionAgentRequirements, validateSourceFile, } from "../validation.js";
 /**
  * Compiles deploy actions for agentDefinitions manifest entries.
  *
@@ -93,11 +93,20 @@ function resolveSupportedTargets(entry, targetAgents, home, repo, workspace) {
 async function createAgentDefinitionActions(entry, source, supportedTargets, home, repo, workspace) {
     const actions = [];
     const isToml = path.extname(entry.path).toLowerCase() === ".toml";
+    // Parse the shared source document once when any supported target requires
+    // frontmatter validation, then reuse the attributes for per-agent checks.
+    const needsFrontmatter = !isToml &&
+        supportedTargets.some((target) => instructionRequiresFrontmatter(target.agentId));
+    const parsedAttributes = needsFrontmatter
+        ? (await parseInstructionDocument(source, entry.path)).attributes
+        : null;
     for (const target of supportedTargets) {
         // TOML definition files have no YAML frontmatter — skip Markdown validation.
         if (!isToml) {
             validateAgentRuleMarkdownPath(entry.path, target.agentId);
-            await validateInstructionFileRequirements(source, entry.path, target.agentId);
+            if (parsedAttributes !== null) {
+                validateInstructionAgentRequirements(parsedAttributes, entry.path, target.agentId);
+            }
         }
         let migratedFrom;
         if (target.agentId === "github-copilot") {
@@ -117,7 +126,7 @@ async function createAgentDefinitionActions(entry, source, supportedTargets, hom
     }
     return actions;
 }
-export async function compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace) {
+export async function compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, validateSource, detectedAgents, home, repo, workspace) {
     const targetAgents = entry.agents.filter((agentId) => detectedAgents.includes(agentId));
     if (targetAgents.length === 0) {
         return { actions: [], warnings: [] };
@@ -128,7 +137,7 @@ export async function compileAgentDefinitionActions(entry, sourceDir, resolvedSo
     }
     // Validate the shared source file only when at least one target is active.
     const source = path.resolve(sourceDir, entry.path);
-    await validateSourcePath(source, entry.path, resolvedSourceDir, realRoot);
+    await validateSource(source, entry.path, resolvedSourceDir);
     await validateSourceFile(source, entry.path);
     const actions = await createAgentDefinitionActions(entry, source, supportedTargets, home, repo, workspace);
     return { actions, warnings };

package/dist/src/core/adapters/index.d.ts

@@ -1,5 +1,6 @@
 import type { AgentDefinitionEntry, AgentRuleEntry, ExecutionConfigEntry, HookEntry, McpServerEntry, PermissionsEntry } from "../../schemas/manifest.ts";
 import type { AgentId, ConfigPatchDeployAction, FileWriteDeployAction, FrontmatterEmitDeployAction, PlanWarning, TomlPatchDeployAction } from "../../types.ts";
+import type { SourcePathValidator } from "../validation.ts";
 import { compileAgentDefinitionReverts } from "./agent-definitions.ts";
 import { compileExecutionConfigReverts } from "./execution-config.ts";
 import { compileHookReverts } from "./hooks.ts";
@@ -12,4 +13,4 @@ export interface AdapterResult {
     actions: AdapterAction[];
     warnings: PlanWarning[];
 }
-export declare function compileAdapterActions(mcpServers: McpServerEntry[], agentRules: AgentRuleEntry[], permissions: PermissionsEntry[], sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string, agentDefinitions?: AgentDefinitionEntry[], workspace?: string, hooks?: HookEntry[], executionConfigs?: ExecutionConfigEntry[]): Promise<AdapterResult>;
+export declare function compileAdapterActions(mcpServers: McpServerEntry[], agentRules: AgentRuleEntry[], permissions: PermissionsEntry[], sourceDir: string, resolvedSourceDir: string, validateSource: SourcePathValidator, detectedAgents: AgentId[], home: string, repo?: string, agentDefinitions?: AgentDefinitionEntry[], workspace?: string, hooks?: HookEntry[], executionConfigs?: ExecutionConfigEntry[]): Promise<AdapterResult>;

package/dist/src/core/adapters/index.js

@@ -12,14 +12,14 @@ async function compileAll(entries, fn) {
         warnings: results.flatMap((r) => r.warnings),
     };
 }
-export async function compileAdapterActions(mcpServers, agentRules, permissions, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, agentDefinitions, workspace, hooks = [], executionConfigs = []) {
+export async function compileAdapterActions(mcpServers, agentRules, permissions, sourceDir, resolvedSourceDir, validateSource, detectedAgents, home, repo, agentDefinitions, workspace, hooks = [], executionConfigs = []) {
     const actions = [];
     const warnings = [];
     const [mcp, rules, perms, defs, hookResults, execResults] = await Promise.all([
         compileAll(mcpServers, (entry) => compileMcpServerActions(entry, detectedAgents, home, repo, workspace)),
-        compileAll(agentRules, (entry) => compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace)),
+        compileAll(agentRules, (entry) => compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, validateSource, detectedAgents, home, repo, workspace)),
         compileAll(permissions, (entry) => compilePermissionsActions(entry, detectedAgents, home)),
-        compileAll(agentDefinitions ?? [], (entry) => compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace)),
+        compileAll(agentDefinitions ?? [], (entry) => compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, validateSource, detectedAgents, home, repo, workspace)),
         compileAll(hooks, (entry) => compileHookActions(entry, detectedAgents, home)),
         compileAll(executionConfigs, (entry) => compileExecutionConfigActions(entry, detectedAgents, home)),
     ]);

package/dist/src/core/adapters/rules.d.ts

@@ -1,8 +1,9 @@
 import type { AgentRuleEntry } from "../../schemas/manifest.ts";
 import type { AgentId, FileWriteDeployAction, FileWriteRevertAction, PlanWarning } from "../../types.ts";
+import { type SourcePathValidator } from "../validation.ts";
 export interface RulesAdapterResult {
     actions: FileWriteDeployAction[];
     warnings: PlanWarning[];
 }
-export declare function compileAgentRuleActions(entry: AgentRuleEntry, sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string, workspace?: string): Promise<RulesAdapterResult>;
+export declare function compileAgentRuleActions(entry: AgentRuleEntry, sourceDir: string, resolvedSourceDir: string, validateSource: SourcePathValidator, detectedAgents: AgentId[], home: string, repo?: string, workspace?: string): Promise<RulesAdapterResult>;
 export declare function compileAgentRuleReverts(entry: AgentRuleEntry, agentFilter: AgentId[] | null, home: string, repo?: string, workspace?: string): FileWriteRevertAction[];

package/dist/src/core/adapters/rules.js

@@ -1,7 +1,7 @@
 import path from "node:path";
 import { planCapabilityForDeploy, resolveCapabilitySurface, } from "../capabilities.js";
 import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
-import { validateAgentRuleMarkdownPath, validateInstructionFileRequirements, validateSourceFile, validateSourcePath, } from "../validation.js";
+import { instructionRequiresFrontmatter, parseInstructionDocument, validateAgentRuleMarkdownPath, validateInstructionAgentRequirements, validateSourceFile, } from "../validation.js";
 function requiresRepoPath(scope) {
     return (scope === "repo" || scope === "copilot-repo" || scope === "copilot-scoped");
 }
@@ -72,7 +72,7 @@ function resolveAgentTarget(agentId, entry, home, repo, platform, workspace, all
         target: resolvePlaceholders(injectTargetDir(support?.path[platform] ?? [], entry.targetDir), entry.name, home, repo, workspace),
     };
 }
-export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace) {
+export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, validateSource, detectedAgents, home, repo, workspace) {
     const actions = [];
     const warnings = [];
     const platform = getPlatformKey();
@@ -103,17 +103,24 @@ export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDi
     // Validate the shared source file only when at least one target uses the
     // current rules adapter surface.
     const source = path.resolve(sourceDir, entry.path);
-    await validateSourcePath(source, entry.path, resolvedSourceDir, realRoot);
+    await validateSource(source, entry.path, resolvedSourceDir);
     await validateSourceFile(source, entry.path);
     // Native Copilot instruction files (.github/copilot-instructions.md and
     // .github/instructions/*.instructions.md) are plain markdown and do not
     // require agent-definition-style frontmatter (tools/instructions keys).
     // Skip the instructionFrontmatterRequired check for these scopes.
     const skipFrontmatterValidation = entry.scope === "copilot-repo" || entry.scope === "copilot-scoped";
+    // Parse the shared source document once when any deduped target requires
+    // frontmatter validation, then reuse the attributes for per-agent checks.
+    const needsFrontmatter = !skipFrontmatterValidation &&
+        dedupedTargets.some((target) => instructionRequiresFrontmatter(target.agentId));
+    const parsedAttributes = needsFrontmatter
+        ? (await parseInstructionDocument(source, entry.path)).attributes
+        : null;
     for (const target of dedupedTargets) {
         validateAgentRuleMarkdownPath(entry.path, target.agentId);
-        if (!skipFrontmatterValidation) {
-            await validateInstructionFileRequirements(source, entry.path, target.agentId);
+        if (!skipFrontmatterValidation && parsedAttributes !== null) {
+            validateInstructionAgentRequirements(parsedAttributes, entry.path, target.agentId);
         }
         actions.push({
             kind: "file-write",

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

@@ -0,0 +1,5 @@
+export declare const DEFAULT_BOUNDED_CONCURRENCY: number;
+export declare function mapConcurrentOrdered<T, R>(items: readonly T[], worker: (item: T, index: number) => Promise<R>, options?: {
+    concurrency?: number;
+    signal?: AbortSignal;
+}): Promise<Array<R | undefined>>;

package/dist/src/core/concurrency.js

@@ -0,0 +1,19 @@
+import os from "node:os";
+export const DEFAULT_BOUNDED_CONCURRENCY = Math.max(1, Math.min(8, os.availableParallelism()));
+export async function mapConcurrentOrdered(items, worker, options = {}) {
+    const { signal } = options;
+    const concurrency = Math.max(1, Math.min(options.concurrency ?? DEFAULT_BOUNDED_CONCURRENCY, items.length));
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    async function runWorker() {
+        while (nextIndex < items.length) {
+            if (signal?.aborted)
+                return;
+            const index = nextIndex;
+            nextIndex += 1;
+            results[index] = await worker(items[index], index);
+        }
+    }
+    await Promise.all(Array.from({ length: concurrency }, () => runWorker()));
+    return results;
+}