@kuznai/inception-engine 0.14.0 → 0.15.0

package/README.md

@@ -8,7 +8,7 @@ GitHub Copilot is no longer treated as a separate instruction or skill target in
 
 The broader portability layer is the roadmap direction, but this README focuses on what is working now.
 
-`init` is available as a bootstrap command, but what works today is intentionally narrow: it scans for directories containing `SKILL.md` and generates starter `skills` entries plus empty `mcpServers` and `agentRules` arrays. It does not infer `files`, `configs`, MCP server definitions, or rules files from the repository yet.
+`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`. `files` and `configs` remain empty — `init` emits guidance when it detects a `files/` or `configs/` directory.
 
 ## Quick Start
 
@@ -50,7 +50,7 @@ Managed skills overwrite their previous version. If a target exists but was not
 | Config patch (JSON merge) | All agents via manifest and CLI | All agents |
 | MCP Servers | claude-code, gemini-cli, codex, antigravity, opencode; github-copilot repo-scoped surfaces are warned and skipped | claude-code, gemini-cli, codex, antigravity, opencode |
 | Global/Repo Rules Files | All agents (antigravity uses repo-local `.agents/rules/`); github-copilot reads CLAUDE.md natively (deploy via claude-code) | All agents |
-| `init` manifest generation | Scans `SKILL.md` directories and writes starter `skills` entries | N/A |
+| `init` manifest generation | Scans `SKILL.md` directories (`skills`), `.md` files with Claude-first agent mapping (`agentRules`), and `mcp-servers.json` (`mcpServers`); emits hints for `files/` and `configs/` directories | N/A |
 
 Features that depend on agent-specific config surfaces are intentionally conservative: if a target path or schema is not implemented with enough confidence, inception-engine warns and skips it rather than guessing.
 
@@ -164,7 +164,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 skill folders. It recursively scans the target directory, treats any directory containing `SKILL.md` as a skill, 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`.
 
 Current `init` behavior:
 
@@ -173,12 +173,30 @@ Current `init` behavior:
 - Applies either the `--agents` list or all currently known agent IDs
 - Refuses to overwrite an existing `inception.json` unless `--force` is provided
 - Supports `--dry-run` so you can inspect the generated manifest before writing it
+- Discovers agent-rules Markdown files in the root and conventional subdirectories (`rules/`, `instructions/`, `.github/`, `.agents/rules/`), mapping them to agents using Claude-first portability conventions: `copilot-instructions.md` maps to `claude-code` (Copilot reads `CLAUDE.md` natively), and the fallback for unrecognized files excludes agents whose agentRules surface is unsupported
+- Reads `mcp-servers.json` from the repo root (if present) and generates `mcpServers` entries; invalid entries are warned and skipped
+- Emits guidance when a `files/` or `configs/` directory is detected at the repo root
 
 Current `init` limitations:
 
 - It does not reconcile generated manifest entries against `SKILL.md` frontmatter values
-- It does not infer `files`, `configs`, `mcpServers`, or `agentRules`
-- It does not reconcile generated output with the longer-term Claude-first portability direction
+- `files` and `configs` entries cannot be inferred automatically since deployment targets are system-specific; add them manually after `init`
+
+### Repo Conventions Recognized by `init`
+
+Place a `mcp-servers.json` file at the repo root to have `init` populate the `mcpServers` section automatically. The file must be a JSON array of MCP server entries using the same schema as the `mcpServers` field in `inception.json`:
+
+```json
+[
+  {
+    "name": "my-server",
+    "agents": ["claude-code", "gemini-cli"],
+    "config": { "command": "npx", "args": ["-y", "my-mcp-server"] }
+  }
+]
+```
+
+Invalid entries are warned and skipped; the rest are written into the generated manifest verbatim.
 
 ## CLI Reference
 

package/dist/core/deploy.js

@@ -4,12 +4,10 @@ import path from "node:path";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { UserError } from "../errors.js";
 import { logger } from "../logger.js";
-import { writeFrontmatterFile } from "./adapters/frontmatter.js";
 import { compileAdapterActions } from "./adapters/index.js";
-import { applyTomlMcpPatch } from "./adapters/toml.js";
 import { lookupDeployment, registerDeployment, verifyDeployment, } from "./ownership.js";
 import { getDeployMethod, resolveAgentSkillPath } from "./resolve.js";
-import { getPathApi, resolveTargetTemplate } from "./runtime-paths.js";
+import { resolveTargetTemplate } from "./runtime-paths.js";
 import { sourceAccessError, validateSkillDefinitionFile, validateSourceFile, validateSourcePath, } from "./validation.js";
 function isPlainObject(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
@@ -82,28 +80,26 @@ function detectCollisions(actions) {
     }
     return warnings;
 }
-function detectAmbiguities(detectedAgents, actions, home) {
+function detectAmbiguities(detectedAgents, manifest) {
     const warnings = [];
-    const hasGeminiCli = detectedAgents.includes("gemini-cli");
-    const hasAntigravity = detectedAgents.includes("antigravity");
-    if (hasGeminiCli && hasAntigravity) {
-        const homePathApi = getPathApi(home);
-        const sharedGeminiMd = homePathApi.join(home, ".gemini", "GEMINI.md");
-        const sharedSettings = homePathApi.join(home, ".gemini", "settings.json");
-        // Normalize paths for comparison to handle case-insensitivity on Windows
-        const normalize = (pathStr) => homePathApi === path.win32
-            ? pathStr.toLowerCase()
-            : pathStr;
-        const normalizedGeminiMd = normalize(sharedGeminiMd);
-        const normalizedSettings = normalize(sharedSettings);
-        const targetsShared = actions.some((a) => {
-            const normalizedTarget = normalize(a.target);
-            return normalizedTarget === normalizedGeminiMd || normalizedTarget === normalizedSettings;
-        });
-        if (targetsShared) {
+    if (!(detectedAgents.includes("gemini-cli") &&
+        detectedAgents.includes("antigravity"))) {
+        return warnings;
+    }
+    const bothAgents = (agents) => agents.includes("gemini-cli") && agents.includes("antigravity");
+    for (const entry of manifest.agentRules ?? []) {
+        if (bothAgents(entry.agents)) {
+            warnings.push({
+                kind: "ambiguity",
+                message: `Both "gemini-cli" and "antigravity" are listed in agentRules entry "${entry.name}". They share a GEMINI.md-backed instruction shared surface — verify that deploying to both does not create conflicting behavior.`,
+            });
+        }
+    }
+    for (const entry of manifest.mcpServers ?? []) {
+        if (bothAgents(entry.agents)) {
             warnings.push({
                 kind: "ambiguity",
-                message: "Both 'gemini-cli' and 'antigravity' are active, and a deployment targets a shared surface (~/.gemini/GEMINI.md or settings.json). Because Antigravity treats GEMINI.md as an Agent Blueprint, changes intended for one runtime may unexpectedly affect the other.",
+                message: `Both "gemini-cli" and "antigravity" are listed in mcpServers entry "${entry.name}". "gemini-cli" writes to ~/.gemini/settings.json as a shared surface — verify that deploying to both does not produce conflicting MCP server behavior.`,
             });
         }
     }
@@ -161,7 +157,7 @@ async function planFileWriteActions(manifest, sourceDir, resolvedSourceDir, real
     }
     return actions;
 }
-function planConfigPatchActions(manifest, detectedAgents, home, repo) {
+function planConfigPatchActions(manifest, detectedAgents, home) {
     const actions = [];
     for (const configEntry of manifest.configs ?? []) {
         for (const agentId of configEntry.agents) {
@@ -174,7 +170,7 @@ function planConfigPatchActions(manifest, detectedAgents, home, repo) {
                 kind: "config-patch",
                 skill: configEntry.name,
                 agent: agentId,
-                target: resolveTargetTemplate(configEntry.target, home, repo),
+                target: resolveTargetTemplate(configEntry.target, home),
                 patch: configEntry.patch,
                 confidence: agent.provenance.skills,
             });
@@ -194,44 +190,56 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
     const actions = [
         ...(await planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home)),
         ...(await planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home)),
-        ...planConfigPatchActions(manifest, detectedAgents, home, resolvedSourceDir),
+        ...planConfigPatchActions(manifest, detectedAgents, home),
     ];
-    const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, resolvedSourceDir);
+    const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home);
     actions.push(...adapterResult.actions);
     const warnings = [
-        ...detectAmbiguities(detectedAgents, actions, home),
+        ...detectAmbiguities(detectedAgents, manifest),
         ...detectCollisions(actions),
         ...adapterResult.warnings,
     ];
     return { actions, warnings };
 }
-async function dispatchDeployAction(action, dryRun, verbose, home, planned, deps) {
-    switch (action.kind) {
-        case "skill-dir":
-            return deploySkillDir(action, dryRun, verbose, home, planned, deps);
-        case "file-write":
-            return deployFileWrite(action, dryRun, verbose, home, planned, deps);
-        case "config-patch":
-            return deployConfigPatch(action, dryRun, verbose, home, planned, deps);
-        case "toml-patch":
-            return deployTomlPatch(action, dryRun, verbose, home, planned, deps);
-        case "frontmatter-emit":
-            return deployFrontmatterEmit(action, dryRun, verbose, home, planned, deps);
-        default:
-            throw new Error(`Unhandled deploy action kind: ${action.kind}`);
-    }
-}
 export async function executeDeploy(actions, dryRun, verbose, home, deps = {}) {
     let succeeded = 0;
     const failed = [];
     const planned = [];
     for (const action of actions) {
-        const result = await dispatchDeployAction(action, dryRun, verbose, home, planned, deps);
-        if (result.error === null) {
-            succeeded++;
-        }
-        else {
-            failed.push({ action, error: result.error });
+        switch (action.kind) {
+            case "skill-dir": {
+                const result = await deploySkillDir(action, dryRun, verbose, home, planned, deps);
+                if (result.error === null) {
+                    succeeded++;
+                }
+                else {
+                    failed.push({ action, error: result.error });
+                }
+                break;
+            }
+            case "file-write": {
+                const result = await deployFileWrite(action, dryRun, verbose, home, planned, deps);
+                if (result.error === null) {
+                    succeeded++;
+                }
+                else {
+                    failed.push({ action, error: result.error });
+                }
+                break;
+            }
+            case "config-patch": {
+                const result = await deployConfigPatch(action, dryRun, verbose, home, planned, deps);
+                if (result.error === null) {
+                    succeeded++;
+                }
+                else {
+                    failed.push({ action, error: result.error });
+                }
+                break;
+            }
+            default: {
+                throw new Error(`Unhandled deploy action kind: ${action}`);
+            }
         }
     }
     return { succeeded, failed, planned };
@@ -599,87 +607,3 @@ async function backupExisting(targetPath, verbose, home, expected, deps) {
     await rename(targetPath, backupPath);
     return backupPath;
 }
-async function deployTomlPatch(action, dryRun, verbose, home, planned, deps) {
-    const label = `${action.skill} -> ${action.agent}`;
-    if (dryRun) {
-        planned.push({
-            verb: "patch-toml",
-            kind: "toml-patch",
-            skill: action.skill,
-            agent: action.agent,
-            target: action.target,
-            confidence: action.confidence,
-        });
-        return { error: null };
-    }
-    try {
-        // Guard against double-patching by a different skill/agent.
-        const existingEntry = await lookupDeployment(home, action.target, deps.registry);
-        if (existingEntry &&
-            (existingEntry.skill !== action.skill ||
-                existingEntry.agent !== action.agent)) {
-            throw new Error(`Config "${action.target}" is already patched by skill "${existingEntry.skill}" for agent "${existingEntry.agent}" — refusing to double-patch`);
-        }
-        await applyTomlMcpPatch(action.target, action.skill, action.config);
-        await registerDeployment(home, action.target, {
-            kind: "config-patch",
-            patch: { mcpServers: { [action.skill]: action.config } },
-            undoPatch: { mcpServers: { [action.skill]: null } },
-            skill: action.skill,
-            agent: action.agent,
-        }, deps.registry);
-        logger.ok(label);
-        if (verbose) {
-            logger.detail(`patch-toml: wrote [mcpServers.${action.skill}] to ${action.target}`);
-        }
-        return { error: null };
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        logger.fail(label, msg);
-        return { error: msg };
-    }
-}
-async function deployFrontmatterEmit(action, dryRun, verbose, home, planned, deps) {
-    const label = `${action.skill} -> ${action.agent}`;
-    if (dryRun) {
-        planned.push({
-            verb: "emit-frontmatter",
-            kind: "frontmatter-emit",
-            skill: action.skill,
-            agent: action.agent,
-            target: action.target,
-            frontmatter: action.frontmatter,
-            confidence: action.confidence,
-        });
-        return { error: null };
-    }
-    try {
-        // Guard against double-patching by a different skill/agent.
-        const existingEntry = await lookupDeployment(home, action.target, deps.registry);
-        if (existingEntry &&
-            (existingEntry.skill !== action.skill ||
-                existingEntry.agent !== action.agent)) {
-            throw new Error(`File "${action.target}" is already managed by skill "${existingEntry.skill}" for agent "${existingEntry.agent}" — refusing to overwrite`);
-        }
-        await writeFrontmatterFile(action.target, action.frontmatter, {
-            preserveBody: true,
-        });
-        await registerDeployment(home, action.target, {
-            kind: "file-write",
-            source: action.target,
-            skill: action.skill,
-            agent: action.agent,
-        }, deps.registry);
-        logger.ok(label);
-        if (verbose) {
-            logger.detail(`emit-frontmatter: wrote ${action.target}`);
-        }
-        return { error: null };
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        logger.fail(label, msg);
-        return { error: msg };
-    }
-}

package/dist/core/init.js

@@ -1,7 +1,8 @@
-import { access, readdir, writeFile } from "node:fs/promises";
+import { access, readFile, readdir, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { dryRunPrefix, logger } from "../logger.js";
-import { AGENT_IDS } from "../schemas/manifest.js";
+import { AGENT_IDS, McpServerEntrySchema } from "../schemas/manifest.js";
 const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 // Ordered list: first match wins. Catch-all is applied at call site.
 const AGENT_RULES_FILE_PATTERNS = [
@@ -17,7 +18,7 @@ const AGENT_RULES_FILE_PATTERNS = [
         fileNames: ["gemini.md", "gemini-instructions.md"],
         agents: ["gemini-cli", "antigravity"],
     },
-    { fileNames: ["copilot-instructions.md"], agents: ["github-copilot"] },
+    { fileNames: ["copilot-instructions.md"], agents: ["claude-code"] },
 ];
 // Conventional subdirectory names to scan one level deep for .md files.
 const AGENT_RULES_SUBDIRS = [
@@ -142,6 +143,9 @@ function buildAgentRules(candidates, activeAgents, skillNamesSeen) {
         // Intersect with active agents; fall back to full active list if empty
         const intersection = defaultAgents.filter((a) => activeAgents.includes(a));
         const agents = intersection.length > 0 ? intersection : activeAgents;
+        // Skip if no capable agents remain (e.g. --agents github-copilot only)
+        if (agents.length === 0)
+            continue;
         // Resolve name collision with skill names
         let name = rawName;
         if (namesSeen.has(name)) {
@@ -160,6 +164,53 @@ function buildAgentRules(candidates, activeAgents, skillNamesSeen) {
     }
     return rules;
 }
+async function loadMcpServers(baseDir) {
+    const filePath = path.join(baseDir, "mcp-servers.json");
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        logger.warn("init", "mcp-servers.json: invalid JSON, skipping");
+        return [];
+    }
+    if (!Array.isArray(parsed)) {
+        logger.warn("init", "mcp-servers.json: expected a JSON array, skipping");
+        return [];
+    }
+    const results = [];
+    for (let i = 0; i < parsed.length; i++) {
+        const result = McpServerEntrySchema.safeParse(parsed[i]);
+        if (result.success) {
+            results.push(result.data);
+        }
+        else {
+            logger.warn("init", `mcp-servers.json: entry[${i}] invalid, skipping`);
+        }
+    }
+    return results;
+}
+async function emitDirectoryHints(baseDir) {
+    for (const [dir, section] of [
+        ["files", "files"],
+        ["configs", "configs"],
+    ]) {
+        try {
+            await access(path.join(baseDir, dir));
+            logger.info(`Detected ${dir}/ directory — add ${section} entries manually to the generated manifest with target paths.`);
+        }
+        catch {
+            // directory does not exist — silent
+        }
+    }
+}
 async function manifestExists(manifestPath) {
     try {
         await access(manifestPath);
@@ -169,9 +220,27 @@ async function manifestExists(manifestPath) {
         return false;
     }
 }
+function logVerboseManifest(skills, agentRules, mcpServers) {
+    for (const s of skills) {
+        logger.detail(`${s.name}  →  ${s.path}`);
+    }
+    if (agentRules.length > 0) {
+        logger.detail("agentRules:");
+        for (const r of agentRules) {
+            logger.detail(`  ${r.name}  →  ${r.path}  [${r.agents.join(", ")}]`);
+        }
+    }
+    if (mcpServers.length > 0) {
+        logger.detail("mcpServers:");
+        for (const m of mcpServers) {
+            logger.detail(`  ${m.name}  [${m.agents.join(", ")}]`);
+        }
+    }
+}
 export async function runInit(options) {
     const { directory, dryRun, force, verbose } = options;
     const agents = options.agents ?? [...AGENT_IDS];
+    const agentRulesCapableAgents = agents.filter((id) => AGENT_REGISTRY_BY_ID[id].agentRulesSupport?.status !== "unsupported");
     const manifestPath = path.join(directory, "inception.json");
     if (!dryRun && (await manifestExists(manifestPath)) && !force) {
         logger.error(`Error: ${manifestPath} already exists. Use --force to overwrite.`);
@@ -186,33 +255,28 @@ export async function runInit(options) {
     const skillNamesSeen = new Set(skills.map((s) => s.name));
     const skillDirRelPaths = new Set(found.map((f) => f.relPath));
     const agentRulesCandidates = await findAgentRulesCandidates(directory, skillDirRelPaths);
-    const agentRules = buildAgentRules(agentRulesCandidates, agents, skillNamesSeen);
+    const agentRules = buildAgentRules(agentRulesCandidates, agentRulesCapableAgents, skillNamesSeen);
+    const mcpServers = await loadMcpServers(directory);
     const manifest = {
         skills,
         files: [],
         configs: [],
-        mcpServers: [],
+        mcpServers,
         agentRules,
     };
     const json = `${JSON.stringify(manifest, null, 2)}\n`;
     if (dryRun) {
-        logger.info(`${dryRunPrefix(true)}Would write ${manifestPath} with ${skills.length} skill(s) and ${agentRules.length} agentRule(s):`);
+        logger.info(`${dryRunPrefix(true)}Would write ${manifestPath} with ${skills.length} skill(s), ${agentRules.length} agentRule(s), and ${mcpServers.length} mcpServer(s):`);
         logger.info("");
         logger.info(json);
+        await emitDirectoryHints(directory);
         return 0;
     }
     await writeFile(manifestPath, json, "utf-8");
-    logger.info(`Generated ${manifestPath} with ${skills.length} skill(s) and ${agentRules.length} agentRule(s).`);
+    logger.info(`Generated ${manifestPath} with ${skills.length} skill(s), ${agentRules.length} agentRule(s), and ${mcpServers.length} mcpServer(s).`);
     if (verbose) {
-        for (const s of skills) {
-            logger.detail(`${s.name}  →  ${s.path}`);
-        }
-        if (agentRules.length > 0) {
-            logger.detail("agentRules:");
-            for (const r of agentRules) {
-                logger.detail(`  ${r.name}  →  ${r.path}  [${r.agents.join(", ")}]`);
-            }
-        }
+        logVerboseManifest(skills, agentRules, mcpServers);
     }
+    await emitDirectoryHints(directory);
     return 0;
 }

package/package.json

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