@kuznai/inception-engine 0.13.0 → 0.14.1

package/dist/core/deploy.js

@@ -4,9 +4,7 @@ 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 { resolveTargetTemplate } from "./runtime-paths.js";
@@ -82,18 +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 sharedGeminiMd = path.resolve(home, ".gemini", "GEMINI.md");
-        const sharedSettings = path.resolve(home, ".gemini", "settings.json");
-        const targetsShared = actions.some((a) => a.target === sharedGeminiMd || a.target === sharedSettings);
-        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.`,
             });
         }
     }
@@ -151,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) {
@@ -164,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,
             });
@@ -184,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 };
@@ -589,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

@@ -3,6 +3,29 @@ import path from "node:path";
 import { dryRunPrefix, logger } from "../logger.js";
 import { AGENT_IDS } 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 = [
+    {
+        fileNames: ["claude.md", "claude-instructions.md"],
+        agents: ["claude-code"],
+    },
+    {
+        fileNames: ["agents.md", "agents-instructions.md"],
+        agents: ["codex", "opencode"],
+    },
+    {
+        fileNames: ["gemini.md", "gemini-instructions.md"],
+        agents: ["gemini-cli", "antigravity"],
+    },
+    { fileNames: ["copilot-instructions.md"], agents: ["github-copilot"] },
+];
+// Conventional subdirectory names to scan one level deep for .md files.
+const AGENT_RULES_SUBDIRS = [
+    "rules",
+    "instructions",
+    ".github",
+    ".agents/rules",
+];
 async function findSkillDirs(baseDir, dir, found) {
     let entries;
     try {
@@ -52,6 +75,91 @@ function buildSkills(found, agents) {
     }
     return skills;
 }
+function defaultAgentsForFile(fileName, fallback) {
+    const lower = fileName.toLowerCase();
+    for (const { fileNames, agents } of AGENT_RULES_FILE_PATTERNS) {
+        if (fileNames.includes(lower))
+            return agents;
+    }
+    return fallback;
+}
+function isInsideSkillDir(relPath, skillDirRelPaths) {
+    const parentRelPath = path.dirname(relPath).split(path.sep).join("/");
+    if (skillDirRelPaths.has(parentRelPath))
+        return true;
+    return [...skillDirRelPaths].some((sp) => parentRelPath === sp || parentRelPath.startsWith(`${sp}/`));
+}
+function deriveAgentRulesName(relPath, fileName) {
+    const ext = path.extname(fileName).toLowerCase();
+    const baseName = path.basename(fileName, ext);
+    const rawName = baseName.toLowerCase().replace(/[^a-zA-Z0-9._-]/g, "-");
+    if (!SAFE_NAME_RE.test(rawName)) {
+        logger.warn("init", `Skipping "${relPath}": could not derive a valid agentRules name`);
+        return null;
+    }
+    return rawName;
+}
+async function scanDirForMarkdown(dir, baseDir, skillDirRelPaths, seen, candidates) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true, encoding: "utf-8" });
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        const ext = path.extname(entry.name).toLowerCase();
+        if (ext !== ".md" && ext !== ".markdown")
+            continue;
+        const absPath = path.join(dir, entry.name);
+        const relPath = path.relative(baseDir, absPath).split(path.sep).join("/");
+        if (seen.has(relPath) || isInsideSkillDir(relPath, skillDirRelPaths))
+            continue;
+        const name = deriveAgentRulesName(relPath, entry.name);
+        if (name === null)
+            continue;
+        seen.add(relPath);
+        candidates.push({ relPath, name, defaultAgents: [] });
+    }
+}
+async function findAgentRulesCandidates(baseDir, skillDirRelPaths) {
+    const candidates = [];
+    const seen = new Set();
+    await scanDirForMarkdown(baseDir, baseDir, skillDirRelPaths, seen, candidates);
+    for (const subdir of AGENT_RULES_SUBDIRS) {
+        await scanDirForMarkdown(path.join(baseDir, subdir), baseDir, skillDirRelPaths, seen, candidates);
+    }
+    return candidates;
+}
+function buildAgentRules(candidates, activeAgents, skillNamesSeen) {
+    const rules = [];
+    const namesSeen = new Set(skillNamesSeen);
+    for (const { relPath, name: rawName } of candidates) {
+        const fileName = path.basename(relPath);
+        const defaultAgents = defaultAgentsForFile(fileName, activeAgents);
+        // 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;
+        // Resolve name collision with skill names
+        let name = rawName;
+        if (namesSeen.has(name)) {
+            const candidate = `${name}-rules`;
+            if (SAFE_NAME_RE.test(candidate)) {
+                logger.warn("init", `agentRules name "${name}" collides with a skill name; using "${candidate}"`);
+                name = candidate;
+            }
+            else {
+                logger.warn("init", `Skipping "${relPath}": name "${name}" collides with a skill name and fallback is invalid`);
+                continue;
+            }
+        }
+        namesSeen.add(name);
+        rules.push({ name, path: relPath, agents });
+    }
+    return rules;
+}
 async function manifestExists(manifestPath) {
     try {
         await access(manifestPath);
@@ -73,27 +181,38 @@ export async function runInit(options) {
     await findSkillDirs(directory, directory, found);
     if (found.length === 0) {
         logger.info("No skill directories found (looking for directories containing SKILL.md).");
-        return 0;
     }
     const skills = buildSkills(found, agents);
-    if (skills.length === 0) {
-        logger.info("No skills could be added to the manifest.");
-        return 0;
-    }
-    const manifest = { skills, mcpServers: [], agentRules: [] };
+    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 manifest = {
+        skills,
+        files: [],
+        configs: [],
+        mcpServers: [],
+        agentRules,
+    };
     const json = `${JSON.stringify(manifest, null, 2)}\n`;
     if (dryRun) {
-        logger.info(`${dryRunPrefix(true)}Would write ${manifestPath} with ${skills.length} skill(s):`);
+        logger.info(`${dryRunPrefix(true)}Would write ${manifestPath} with ${skills.length} skill(s) and ${agentRules.length} agentRule(s):`);
         logger.info("");
         logger.info(json);
         return 0;
     }
     await writeFile(manifestPath, json, "utf-8");
-    logger.info(`Generated ${manifestPath} with ${skills.length} skill(s).`);
+    logger.info(`Generated ${manifestPath} with ${skills.length} skill(s) and ${agentRules.length} agentRule(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(", ")}]`);
+            }
+        }
     }
     return 0;
 }

package/package.json

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