@kuznai/inception-engine 0.18.0 → 0.20.0

package/dist/test/unit/toml.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/test/unit/toml.test.js

@@ -0,0 +1,55 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, it } from "node:test";
+import { applyTomlMcpPatch, revertTomlMcpPatch, } from "../../src/core/adapters/toml.js";
+describe("TOML Adapter", () => {
+    let tmpDir;
+    beforeEach(async () => {
+        tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "inception-toml-test-"));
+    });
+    afterEach(async () => {
+        await fs.rm(tmpDir, { recursive: true, force: true });
+    });
+    it("applies an MCP server patch to a new TOML file", async () => {
+        const target = path.join(tmpDir, "config.toml");
+        const config = { command: "npx", args: ["serve"] };
+        await applyTomlMcpPatch(target, "my-skill", config);
+        const content = await fs.readFile(target, "utf-8");
+        assert.match(content, /\[mcpServers\.my-skill\]/);
+        assert.match(content, /command = "npx"/);
+        assert.match(content, /args = \[ "serve" \]/);
+    });
+    it("applies an MCP server patch to an existing TOML file preserving other keys", async () => {
+        const target = path.join(tmpDir, "config.toml");
+        await fs.writeFile(target, 'title = "My App"\n\n[mcpServers.other]\ncommand = "ls"\n');
+        const config = { command: "npx", args: ["serve"] };
+        await applyTomlMcpPatch(target, "my-skill", config);
+        const content = await fs.readFile(target, "utf-8");
+        assert.match(content, /title = "My App"/);
+        assert.match(content, /\[mcpServers\.other\]/);
+        assert.match(content, /\[mcpServers\.my-skill\]/);
+        assert.match(content, /command = "npx"/);
+    });
+    it("reverts an MCP server patch", async () => {
+        const target = path.join(tmpDir, "config.toml");
+        await fs.writeFile(target, '[mcpServers.other]\ncommand = "ls"\n\n[mcpServers.my-skill]\ncommand = "npx"\n');
+        await revertTomlMcpPatch(target, "my-skill");
+        const content = await fs.readFile(target, "utf-8");
+        assert.match(content, /\[mcpServers\.other\]/);
+        assert.doesNotMatch(content, /my-skill/);
+    });
+    it("cleans up [mcpServers] table if it becomes empty after revert", async () => {
+        const target = path.join(tmpDir, "config.toml");
+        await fs.writeFile(target, '[mcpServers.my-skill]\ncommand = "npx"\n');
+        await revertTomlMcpPatch(target, "my-skill");
+        const content = await fs.readFile(target, "utf-8");
+        assert.strictEqual(content.trim(), "");
+    });
+    it("throws error if config.toml is invalid TOML", async () => {
+        const target = path.join(tmpDir, "config.toml");
+        await fs.writeFile(target, 'this is not = toml "bad"');
+        await assert.rejects(() => applyTomlMcpPatch(target, "any", {}), /Invalid TOML document/);
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kuznai/inception-engine",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",

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

@@ -1,20 +0,0 @@
-import type { AgentDefinitionEntry } from "../../schemas/manifest.ts";
-import type { AgentId, FileWriteDeployAction, FileWriteRevertAction, PlanWarning } from "../../types.ts";
-export interface AgentDefinitionsAdapterResult {
-    actions: FileWriteDeployAction[];
-    warnings: PlanWarning[];
-}
-/**
- * Compiles deploy actions for agentDefinitions manifest entries.
- *
- * Agent definition files are Markdown files (typically with YAML frontmatter)
- * that define custom agents or subagents for a given platform. Unlike
- * agentRules (which target a single shared global file per agent), each
- * definition entry produces a separate file named after the entry in the
- * agent's dedicated agent-definitions directory (repo-local).
- *
- * Target paths use the `{repo}` placeholder so definitions land in the
- * repository being deployed, not the user's home directory.
- */
-export declare function compileAgentDefinitionActions(entry: AgentDefinitionEntry, sourceDir: string, resolvedSourceDir: string, realRoot: string, detectedAgents: AgentId[], home: string, repo?: string): Promise<AgentDefinitionsAdapterResult>;
-export declare function compileAgentDefinitionReverts(entry: AgentDefinitionEntry, agentFilter: AgentId[] | null, home: string, repo?: string): FileWriteRevertAction[];

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

@@ -1,90 +0,0 @@
-import path from "node:path";
-import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
-import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
-import { validateAgentRuleMarkdownPath, validateSourceFile, validateSourcePath, } from "../validation.js";
-/**
- * Compiles deploy actions for agentDefinitions manifest entries.
- *
- * Agent definition files are Markdown files (typically with YAML frontmatter)
- * that define custom agents or subagents for a given platform. Unlike
- * agentRules (which target a single shared global file per agent), each
- * definition entry produces a separate file named after the entry in the
- * agent's dedicated agent-definitions directory (repo-local).
- *
- * Target paths use the `{repo}` placeholder so definitions land in the
- * repository being deployed, not the user's home directory.
- */
-export async function compileAgentDefinitionActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo) {
-    const actions = [];
-    const warnings = [];
-    const platform = getPlatformKey();
-    const targetAgents = entry.agents.filter((agentId) => detectedAgents.includes(agentId));
-    const supportedTargets = [];
-    if (targetAgents.length === 0) {
-        return { actions, warnings };
-    }
-    for (const agentId of targetAgents) {
-        const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = agent?.agentDefinitionsSupport;
-        if (!support || support.status === "unsupported") {
-            warnings.push({
-                kind: "confidence",
-                message: `agentDefinitions: agent "${agentId}" uses ${support?.schemaLabel ?? "an unsupported agent-definition schema"} and ${support?.status === "unsupported" ? support.reason : "does not expose a supported agent-definitions adapter"} — skipping "${entry.name}"`,
-            });
-            continue;
-        }
-        if (support.status === "planned") {
-            warnings.push({
-                kind: "confidence",
-                message: `agentDefinitions: agent "${agentId}" agent-definitions support is planned via ${support.plannedSurface} — skipping "${entry.name}" until that surface is implemented`,
-            });
-            continue;
-        }
-        supportedTargets.push({
-            agentId,
-            confidence: agent.provenance.agentDefinitions ?? "provisional",
-            target: resolvePlaceholders(support.path[platform], entry.name, home, repo),
-        });
-    }
-    if (supportedTargets.length === 0) {
-        return { actions, warnings };
-    }
-    // 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 validateSourceFile(source, entry.path);
-    for (const target of supportedTargets) {
-        validateAgentRuleMarkdownPath(entry.path, target.agentId);
-        actions.push({
-            kind: "file-write",
-            skill: entry.name,
-            agent: target.agentId,
-            source,
-            target: target.target,
-            confidence: target.confidence,
-        });
-    }
-    return { actions, warnings };
-}
-export function compileAgentDefinitionReverts(entry, agentFilter, home, repo) {
-    const actions = [];
-    const platform = getPlatformKey();
-    for (const agentId of entry.agents) {
-        if (agentFilter && !agentFilter.includes(agentId))
-            continue;
-        const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = agent?.agentDefinitionsSupport;
-        if (!support ||
-            support.status === "unsupported" ||
-            support.status === "planned")
-            continue;
-        const target = resolvePlaceholders(support.path[platform], entry.name, home, repo);
-        actions.push({
-            kind: "file-write",
-            skill: entry.name,
-            agent: agentId,
-            target,
-        });
-    }
-    return actions;
-}

package/dist/core/adapters/rules.js

@@ -1,103 +0,0 @@
-import path from "node:path";
-import { AGENT_REGISTRY_BY_ID } from "../../config/agents.js";
-import { getPlatformKey, resolvePlaceholders } from "../resolve.js";
-import { validateAgentRuleMarkdownPath, validateSourceFile, validateSourcePath, } from "../validation.js";
-function resolveRulesSupport(agentId, scope) {
-    const agent = AGENT_REGISTRY_BY_ID[agentId];
-    if (scope === "repo") {
-        return agent?.agentRulesRepoSupport ?? agent?.agentRulesSupport;
-    }
-    return agent?.agentRulesSupport;
-}
-function resolveAgentTarget(agentId, entry, home, repo, platform) {
-    const support = resolveRulesSupport(agentId, entry.scope);
-    if (!support || support.status === "unsupported") {
-        return {
-            kind: "confidence",
-            message: `agentRules: agent "${agentId}" uses ${support?.schemaLabel ?? "an unsupported instruction schema"} and ${support?.status === "unsupported" ? support.reason : "does not expose a supported rules adapter"} — skipping "${entry.name}"`,
-        };
-    }
-    if (support.status === "planned") {
-        return {
-            kind: "confidence",
-            message: `agentRules: agent "${agentId}" rules support is planned via ${support.plannedSurface} — skipping "${entry.name}" until that surface is implemented`,
-        };
-    }
-    if (entry.scope === "repo" && !repo) {
-        return {
-            kind: "confidence",
-            message: `agentRules: scope "repo" requires a repository path but none was resolved — skipping "${entry.name}" for agent "${agentId}"`,
-        };
-    }
-    const agent = AGENT_REGISTRY_BY_ID[agentId];
-    return {
-        agentId,
-        confidence: agent?.provenance.agentRules ?? "provisional",
-        target: resolvePlaceholders(support.path[platform], entry.name, home, repo),
-    };
-}
-export async function compileAgentRuleActions(entry, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo) {
-    const actions = [];
-    const warnings = [];
-    const platform = getPlatformKey();
-    const targetAgents = entry.agents.filter((agentId) => detectedAgents.includes(agentId));
-    const supportedTargets = [];
-    if (targetAgents.length === 0) {
-        return { actions, warnings };
-    }
-    for (const agentId of targetAgents) {
-        const result = resolveAgentTarget(agentId, entry, home, repo, platform);
-        if ("kind" in result) {
-            warnings.push(result);
-        }
-        else {
-            supportedTargets.push(result);
-        }
-    }
-    if (supportedTargets.length === 0) {
-        return { actions, warnings };
-    }
-    // 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 validateSourceFile(source, entry.path);
-    for (const target of supportedTargets) {
-        validateAgentRuleMarkdownPath(entry.path, target.agentId);
-        actions.push({
-            kind: "file-write",
-            skill: entry.name,
-            agent: target.agentId,
-            source,
-            target: target.target,
-            confidence: target.confidence,
-        });
-    }
-    return { actions, warnings };
-}
-export function compileAgentRuleReverts(entry, agentFilter, home, repo) {
-    const actions = [];
-    const platform = getPlatformKey();
-    for (const agentId of entry.agents) {
-        if (agentFilter && !agentFilter.includes(agentId))
-            continue;
-        const agent = AGENT_REGISTRY_BY_ID[agentId];
-        const support = entry.scope === "repo"
-            ? (agent?.agentRulesRepoSupport ?? agent?.agentRulesSupport)
-            : agent?.agentRulesSupport;
-        if (!support ||
-            support.status === "unsupported" ||
-            support.status === "planned")
-            continue;
-        if (entry.scope === "repo" && !repo)
-            continue;
-        const target = resolvePlaceholders(support.path[platform], entry.name, home, repo);
-        actions.push({
-            kind: "file-write",
-            skill: entry.name,
-            agent: agentId,
-            target,
-        });
-    }
-    return actions;
-}

package/dist/core/preflight.js

@@ -1,98 +0,0 @@
-import { stat } from "node:fs/promises";
-import path from "node:path";
-import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
-const BUDGET_WARN_BYTES = 50 * 1024; // 50 KB
-function detectInstructionPrecedence(detectedAgents, manifest) {
-    const warnings = [];
-    for (const agentId of detectedAgents) {
-        const rulesForAgent = (manifest.agentRules ?? []).filter((e) => e.agents.includes(agentId));
-        const globalEntries = rulesForAgent.filter((e) => (e.scope ?? "global") === "global");
-        const repoEntries = rulesForAgent.filter((e) => e.scope === "repo");
-        if (globalEntries.length === 0 || repoEntries.length === 0)
-            continue;
-        const globalPaths = new Set(globalEntries.map((e) => e.path));
-        for (const entry of repoEntries) {
-            if (globalPaths.has(entry.path)) {
-                warnings.push({
-                    kind: "precedence",
-                    message: `Agent "${agentId}" has agentRules entry "${entry.name}" deployed to both global and repo scope from the same source path "${entry.path}". The file will be written to two distinct targets — verify this is intentional and not a copy-paste mistake.`,
-                });
-            }
-        }
-        const nonOverlapRepo = repoEntries.filter((e) => !globalPaths.has(e.path));
-        if (nonOverlapRepo.length > 0) {
-            const globalNames = globalEntries.map((e) => `"${e.name}"`).join(", ");
-            const repoNames = nonOverlapRepo.map((e) => `"${e.name}"`).join(", ");
-            warnings.push({
-                kind: "precedence",
-                message: `Agent "${agentId}" will have both global and repo instruction files active simultaneously: global [${globalNames}] and repo [${repoNames}]. Both will be loaded by the agent — ensure the content is intended to stack and does not conflict.`,
-            });
-        }
-    }
-    return warnings;
-}
-async function detectInstructionBudgetRisk(detectedAgents, manifest, sourceDir) {
-    const warnings = [];
-    const checkedPaths = new Set();
-    async function checkEntry(entryPath, label, agentIds) {
-        if (!agentIds.some((id) => detectedAgents.includes(id)))
-            return;
-        const sourcePath = path.resolve(sourceDir, entryPath);
-        if (checkedPaths.has(sourcePath))
-            return;
-        checkedPaths.add(sourcePath);
-        try {
-            const fileStat = await stat(sourcePath);
-            if (fileStat.size > BUDGET_WARN_BYTES) {
-                const sizeKb = (fileStat.size / 1024).toFixed(1);
-                warnings.push({
-                    kind: "budget",
-                    message: `${label} source "${entryPath}" is ${sizeKb} KB — large instruction files risk crowding out code context in the agent's context window. Consider splitting into smaller focused files.`,
-                });
-            }
-        }
-        catch (err) {
-            const code = err.code;
-            if (code !== "ENOENT" && code !== "EACCES" && code !== "EPERM")
-                throw err;
-            // Missing/unreadable files are silently skipped; compileAgentRuleActions
-            // will produce the proper UserError during action compilation.
-        }
-    }
-    for (const entry of manifest.agentRules ?? []) {
-        await checkEntry(entry.path, "agentRules", entry.agents);
-    }
-    for (const entry of manifest.agentDefinitions ?? []) {
-        await checkEntry(entry.path, "agentDefinitions", entry.agents);
-    }
-    return warnings;
-}
-export async function runPreflight(options, manifest, _home, detectedAgents) {
-    const warnings = [];
-    for (const agentId of detectedAgents) {
-        const agent = AGENT_REGISTRY_BY_ID[agentId];
-        if (!agent)
-            continue;
-        if (agent.provenance.skills === "implementation-only") {
-            warnings.push({
-                kind: "config-authority",
-                message: `Agent "${agentId}" skill support is implementation-only: paths are derived from source inspection, not published documentation.`,
-            });
-        }
-        else if (agent.provenance.skills === "provisional") {
-            warnings.push({
-                kind: "config-authority",
-                message: `Agent "${agentId}" skill support is provisional: behavior has not been independently verified.`,
-            });
-        }
-        if (agent.policyNote) {
-            warnings.push({
-                kind: "policy",
-                message: `Agent "${agentId}": ${agent.policyNote}`,
-            });
-        }
-    }
-    warnings.push(...detectInstructionPrecedence(detectedAgents, manifest));
-    warnings.push(...(await detectInstructionBudgetRisk(detectedAgents, manifest, options.directory)));
-    return warnings;
-}

package/dist/logger.js

@@ -1,61 +0,0 @@
-import process from "node:process";
-const C = {
-    red: "\x1b[31m",
-    green: "\x1b[32m",
-    yellow: "\x1b[33m",
-    cyan: "\x1b[36m",
-    reset: "\x1b[0m",
-};
-export function createLogger() {
-    let silent = false;
-    const tty = Boolean(process.stdout.isTTY);
-    const errTTY = Boolean(process.stderr.isTTY);
-    const c = (col, text, onTTY) => onTTY ? `${C[col]}${text}${C.reset}` : text;
-    return {
-        fail(label, msg) {
-            if (!silent)
-                process.stderr.write(`  ${c("red", "✗", errTTY)} ${label}: ${msg}\n`);
-        },
-        ok(label) {
-            if (!silent)
-                process.stdout.write(`  ${c("green", "✓", tty)} ${label}\n`);
-        },
-        skip(label, note) {
-            if (!silent)
-                process.stdout.write(`  ${c("yellow", "-", tty)} ${label} ${note}\n`);
-        },
-        plan(label) {
-            if (!silent)
-                process.stdout.write(`  ${c("cyan", "○", tty)} ${label}\n`);
-        },
-        warn(label, msg) {
-            if (!silent)
-                process.stdout.write(`  ${c("yellow", "!", tty)} ${label}: ${msg}\n`);
-        },
-        info(msg) {
-            if (!silent)
-                process.stdout.write(`${msg}\n`);
-        },
-        error(msg) {
-            if (!silent)
-                process.stderr.write(`${msg}\n`);
-        },
-        errorRaw(value) {
-            if (!silent)
-                console.error(value);
-        },
-        detail(msg) {
-            if (!silent)
-                process.stdout.write(`    ${msg}\n`);
-        },
-        silence() {
-            silent = true;
-        },
-    };
-}
-export const logger = createLogger();
-export function dryRunPrefix(dryRun) {
-    if (!dryRun)
-        return "";
-    return process.stdout.isTTY ? `\x1b[36m[dry-run]\x1b[0m ` : `[dry-run] `;
-}