@kuznai/inception-engine 0.14.1 → 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/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.1",
+  "version": "0.15.0",
   "description": "Deploy AI agent skills from a git repo to user home directories",
   "license": "MIT",
   "author": "Damian Piątkowski",