@kuznai/inception-engine 0.18.0 → 0.20.0

package/dist/{core → src/core}/deploy.js

@@ -1,17 +1,16 @@
 import { constants } from "node:fs";
 import { access, copyFile, cp, lstat, mkdir, readFile, realpath, rename, rm, symlink, unlink, writeFile, } from "node:fs/promises";
 import path from "node:path";
-import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
+import { AGENT_REGISTRY, AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { UserError } from "../errors.js";
 import { logger } from "../logger.js";
 import { compileAdapterActions } from "./adapters/index.js";
+import { planCapabilityForDeploy } from "./capabilities.js";
+import { applyMergePatch, computeUndoPatch, isPlainObject, } from "./merge-patch.js";
 import { lookupDeployment, registerDeployment, verifyDeployment, } from "./ownership.js";
 import { getDeployMethod, resolveAgentSkillPath } from "./resolve.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);
-}
 async function readJsonConfigFile(filePath) {
     let rawContent;
     try {
@@ -35,34 +34,6 @@ async function readJsonConfigFile(filePath) {
     }
     return parsed;
 }
-function computeUndoPatch(original, patch) {
-    const undoPatch = {};
-    for (const key of Object.keys(patch)) {
-        const patchVal = patch[key];
-        if (isPlainObject(patchVal) && isPlainObject(original[key])) {
-            undoPatch[key] = computeUndoPatch(original[key], patchVal);
-        }
-        else {
-            undoPatch[key] = key in original ? original[key] : null;
-        }
-    }
-    return undoPatch;
-}
-function applyMergePatch(original, patch) {
-    const patched = { ...original };
-    for (const [key, value] of Object.entries(patch)) {
-        if (value === null) {
-            delete patched[key];
-        }
-        else if (isPlainObject(value) && isPlainObject(patched[key])) {
-            patched[key] = applyMergePatch(patched[key], value);
-        }
-        else {
-            patched[key] = value;
-        }
-    }
-    return patched;
-}
 function detectCollisions(actions) {
     const seen = new Map();
     const warnings = [];
@@ -80,47 +51,156 @@ function detectCollisions(actions) {
     }
     return warnings;
 }
-function detectAmbiguities(detectedAgents, manifest) {
-    const warnings = [];
-    if (!(detectedAgents.includes("gemini-cli") &&
-        detectedAgents.includes("antigravity"))) {
-        return warnings;
+/**
+ * Finds all (primary, rider) pairs among detected agents where the rider has
+ * at least one surface annotated as `shared-via` the primary and the primary
+ * is also detected. Used to drive ambiguity warnings without hardcoding agent
+ * IDs.
+ */
+function findSharedSurfacePairs(detectedAgents) {
+    const pairs = [];
+    for (const agent of AGENT_REGISTRY) {
+        if (!detectedAgents.includes(agent.id))
+            continue;
+        const surfaces = [
+            agent.agentRulesSupport,
+            agent.agentRulesRepoSupport,
+            agent.agentRulesWorkspaceSupport,
+            agent.mcpSupport,
+            agent.agentDefinitionsSupport,
+        ];
+        for (const surface of surfaces) {
+            if (surface?.status === "supported" &&
+                surface.surfaceKind?.kind === "shared-via") {
+                const via = surface.surfaceKind.via;
+                if (detectedAgents.includes(via) &&
+                    !pairs.some((p) => p.primary === via && p.rider === agent.id)) {
+                    pairs.push({ primary: via, rider: agent.id });
+                }
+            }
+        }
     }
-    const bothAgents = (agents) => agents.includes("gemini-cli") && agents.includes("antigravity");
+    return pairs;
+}
+function resolveAgentRulesSupportForScope(agentId, scope) {
+    const agent = AGENT_REGISTRY_BY_ID[agentId];
+    if (scope === "repo")
+        return agent?.agentRulesRepoSupport ?? agent?.agentRulesSupport;
+    if (scope === "workspace") {
+        return (agent?.agentRulesWorkspaceSupport ??
+            agent?.agentRulesRepoSupport ??
+            agent?.agentRulesSupport);
+    }
+    return agent?.agentRulesSupport;
+}
+function checkPairAgentRuleAmbiguities(manifest, primary, rider) {
+    const warnings = [];
     for (const entry of manifest.agentRules ?? []) {
-        if (bothAgents(entry.agents)) {
+        if (!(entry.agents.includes(primary) && entry.agents.includes(rider)))
+            continue;
+        const primarySupport = resolveAgentRulesSupportForScope(primary, entry.scope);
+        const riderSupport = resolveAgentRulesSupportForScope(rider, entry.scope);
+        if (primarySupport?.status === "supported" &&
+            riderSupport?.status === "supported" &&
+            JSON.stringify(primarySupport.path) === JSON.stringify(riderSupport.path)) {
             warnings.push({
                 kind: "ambiguity",
-                message: `Both "gemini-cli" and "antigravity" are listed in agentRules entry "${entry.name}". They write to distinct surfaces ("gemini-cli" → ~/.gemini/GEMINI.md, "antigravity" → {repo}/.agents/rules/${entry.name}.md) from the same source file — verify that deploying to both produces the intended behavior on each agent.`,
+                message: `Both "${primary}" and "${rider}" are listed in agentRules entry "${entry.name}". Both target the same surface — listing both is redundant but harmless; deduplication ensures only one write action is emitted.`,
             });
         }
     }
+    return warnings;
+}
+function checkPairMcpAmbiguities(manifest, primary, rider) {
+    const warnings = [];
+    const primaryMcp = AGENT_REGISTRY_BY_ID[primary]?.mcpSupport;
+    const riderMcp = AGENT_REGISTRY_BY_ID[rider]?.mcpSupport;
+    if (primaryMcp?.status !== "supported" || riderMcp?.status !== "supported")
+        return warnings;
+    for (const entry of manifest.mcpServers ?? []) {
+        if (!(entry.agents.includes(primary) && entry.agents.includes(rider)))
+            continue;
+        warnings.push({
+            kind: "ambiguity",
+            message: `Both "${primary}" and "${rider}" are listed in mcpServers entry "${entry.name}". "${primary}" writes to a shared MCP surface — verify that deploying to both does not produce conflicting MCP server behavior.`,
+        });
+    }
+    return warnings;
+}
+function checkPairAgentDefinitionAmbiguities(manifest, primary, rider) {
+    const warnings = [];
+    for (const entry of manifest.agentDefinitions ?? []) {
+        if (!(entry.agents.includes(primary) && entry.agents.includes(rider)))
+            continue;
+        warnings.push({
+            kind: "ambiguity",
+            message: `Both "${primary}" and "${rider}" are listed in agentDefinitions entry "${entry.name}". They write to distinct surfaces — verify that this behavioral divergence is intended.`,
+        });
+    }
+    return warnings;
+}
+function detectAmbiguities(detectedAgents, manifest) {
+    const pairs = findSharedSurfacePairs(detectedAgents);
+    if (pairs.length === 0)
+        return [];
+    const warnings = [];
+    for (const { primary, rider } of pairs) {
+        warnings.push(...checkPairAgentRuleAmbiguities(manifest, primary, rider));
+        warnings.push(...checkPairMcpAmbiguities(manifest, primary, rider));
+        warnings.push(...checkPairAgentDefinitionAmbiguities(manifest, primary, rider));
+    }
+    return warnings;
+}
+function checkAntigravityPathCollisions(manifest) {
+    const warnings = [];
+    const defNames = new Set((manifest.agentDefinitions ?? [])
+        .filter((e) => e.agents.includes("antigravity"))
+        .map((e) => e.name));
     for (const entry of manifest.mcpServers ?? []) {
-        if (bothAgents(entry.agents)) {
+        if (!entry.agents.includes("antigravity"))
+            continue;
+        if (defNames.has(entry.name)) {
             warnings.push({
-                kind: "ambiguity",
-                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.`,
+                kind: "collision",
+                message: `agentDefinitions entry "${entry.name}" and mcpServers entry "${entry.name}" for agent "antigravity" both resolve to {repo}/.agents/rules/${entry.name}.md — one will silently overwrite the other; use different names or remove one entry`,
             });
         }
     }
     return warnings;
 }
+function assertNoAntigravityPathCollisions(manifest) {
+    const collisions = checkAntigravityPathCollisions(manifest);
+    if (collisions.length === 0)
+        return;
+    throw new UserError("MANIFEST_INVALID", collisions.map((warning) => warning.message).join("; "));
+}
 async function planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home) {
     const method = getDeployMethod();
     const actions = [];
-    for (const skill of manifest.skills) {
+    const warnings = [];
+    async function planSkillEntry(skill) {
         const targetAgents = skill.agents.filter((agentId) => detectedAgents.includes(agentId));
         if (targetAgents.length === 0)
-            continue;
+            return;
         const source = path.resolve(sourceDir, skill.path);
         await validateSourcePath(source, skill.path, resolvedSourceDir, realRoot);
         await validateSkillContract(source, skill.path);
         for (const agentId of targetAgents) {
+            const plan = planCapabilityForDeploy({
+                agentId,
+                capability: "skills",
+                entryName: skill.name,
+                targetAgentIds: targetAgents,
+            });
+            if (plan.outcome === "warn") {
+                warnings.push(plan.warning);
+                continue;
+            }
+            if (plan.outcome === "native" || plan.outcome === "redundant")
+                continue;
             const agent = AGENT_REGISTRY_BY_ID[agentId];
             if (!agent)
                 continue;
-            if (!agent.skills)
-                continue;
             actions.push({
                 kind: "skill-dir",
                 skill: skill.name,
@@ -128,13 +208,16 @@ async function planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realR
                 source,
                 target: resolveAgentSkillPath(agent, skill.name, home),
                 method,
-                confidence: agent.provenance.skills ?? "provisional",
+                confidence: plan.confidence ?? "provisional",
             });
         }
     }
-    return actions;
+    for (const skill of manifest.skills) {
+        await planSkillEntry(skill);
+    }
+    return { actions, warnings };
 }
-async function planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home) {
+async function planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repo, workspace) {
     const actions = [];
     for (const fileEntry of manifest.files ?? []) {
         const targetAgents = fileEntry.agents.filter((agentId) => detectedAgents.includes(agentId));
@@ -152,14 +235,14 @@ async function planFileWriteActions(manifest, sourceDir, resolvedSourceDir, real
                 skill: fileEntry.name,
                 agent: agentId,
                 source,
-                target: resolveTargetTemplate(fileEntry.target, home),
+                target: resolveTargetTemplate(fileEntry.target, home, repo, workspace),
                 confidence: agent.provenance.skills,
             });
         }
     }
     return actions;
 }
-function planConfigPatchActions(manifest, detectedAgents, home) {
+function planConfigPatchActions(manifest, detectedAgents, home, repo, workspace) {
     const actions = [];
     for (const configEntry of manifest.configs ?? []) {
         for (const agentId of configEntry.agents) {
@@ -172,7 +255,7 @@ function planConfigPatchActions(manifest, detectedAgents, home) {
                 kind: "config-patch",
                 skill: configEntry.name,
                 agent: agentId,
-                target: resolveTargetTemplate(configEntry.target, home),
+                target: resolveTargetTemplate(configEntry.target, home, repo, workspace),
                 patch: configEntry.patch,
                 confidence: agent.provenance.skills,
             });
@@ -180,7 +263,8 @@ function planConfigPatchActions(manifest, detectedAgents, home) {
     }
     return actions;
 }
-export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
+export async function planDeploy(manifest, sourceDir, detectedAgents, home, repo, workspace) {
+    assertNoAntigravityPathCollisions(manifest);
     const resolvedSourceDir = path.resolve(sourceDir);
     let realRoot;
     try {
@@ -189,15 +273,19 @@ export async function planDeploy(manifest, sourceDir, detectedAgents, home) {
     catch {
         realRoot = resolvedSourceDir;
     }
+    const repoDir = repo ?? realRoot;
+    const skillPlan = await planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home);
     const actions = [
-        ...(await planSkillDirActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home)),
-        ...(await planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home)),
-        ...planConfigPatchActions(manifest, detectedAgents, home),
+        ...skillPlan.actions,
+        ...(await planFileWriteActions(manifest, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repoDir, workspace)),
+        ...planConfigPatchActions(manifest, detectedAgents, home, repoDir, workspace),
     ];
-    const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, manifest.permissions ?? [], sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, undefined, manifest.agentDefinitions ?? []);
+    const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, manifest.permissions ?? [], sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, repoDir, manifest.agentDefinitions ?? [], workspace);
     actions.push(...adapterResult.actions);
     const warnings = [
+        ...skillPlan.warnings,
         ...detectAmbiguities(detectedAgents, manifest),
+        ...checkAntigravityPathCollisions(manifest),
         ...detectCollisions(actions),
         ...adapterResult.warnings,
     ];
@@ -208,44 +296,32 @@ export async function executeDeploy(actions, dryRun, verbose, home, deps = {}) {
     const failed = [];
     const planned = [];
     for (const action of actions) {
-        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}`);
-            }
+        const result = await dispatchDeployAction(action, dryRun, verbose, home, planned, deps);
+        if (result.error === null) {
+            succeeded++;
+        }
+        else {
+            failed.push({ action, error: result.error });
         }
     }
     return { succeeded, failed, planned };
 }
+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}`);
+    }
+}
 const defaultSkillDirOps = {
     async createTarget(action) {
         if (action.method === "symlink") {
@@ -413,6 +489,7 @@ async function deployFileWrite(action, dryRun, verbose, home, planned, deps) {
             source: action.source,
             skill: action.skill,
             agent: action.agent,
+            migratedFrom: action.migratedFrom,
         }, deps.registry));
         logger.ok(label);
         if (verbose) {
@@ -483,6 +560,110 @@ async function deployConfigPatch(action, dryRun, verbose, home, planned, deps) {
         return { error: msg };
     }
 }
+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,
+            patch: action.config,
+        });
+        return { error: null };
+    }
+    try {
+        const { previousValue } = await (deps.registry
+            ? Promise.resolve({ previousValue: null })
+            : (await import("./adapters/toml.js")).applyTomlMcpPatch(action.target, action.skill, action.config));
+        // Note: To truly support custom deps here we'd need to refactor toml adapter to accept deps.
+        // For now we assume standard adapter for TOML.
+        await registerDeployment(home, action.target, {
+            kind: "config-patch",
+            patch: action.config,
+            undoPatch: { mcpServers: { [action.skill]: previousValue } },
+            skill: action.skill,
+            agent: action.agent,
+        }, deps.registry);
+        logger.ok(label);
+        if (verbose) {
+            logger.detail(`patch-toml: ${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 (!isPlainObject(action.frontmatter)) {
+        const msg = `Frontmatter patch for skill "${action.skill}" must be a plain object`;
+        logger.fail(label, msg);
+        return { error: msg };
+    }
+    if (dryRun) {
+        planned.push({
+            verb: "emit-frontmatter",
+            kind: "frontmatter-emit",
+            skill: action.skill,
+            agent: action.agent,
+            target: action.target,
+            frontmatter: action.frontmatter,
+        });
+        return { error: null };
+    }
+    try {
+        const existingEntry = await lookupDeployment(home, action.target, deps.registry);
+        if (existingEntry &&
+            (existingEntry.kind !== "frontmatter-emit" ||
+                existingEntry.skill !== action.skill ||
+                existingEntry.agent !== action.agent)) {
+            throw new Error(`Frontmatter target "${action.target}" is already patched by skill "${existingEntry.skill}" for agent "${existingEntry.agent}" — refusing to double-patch`);
+        }
+        const frontmatterAdapter = await import("./adapters/frontmatter.js");
+        const existing = await frontmatterAdapter.readFrontmatterDocumentFile(action.target);
+        const undoPatch = computeUndoPatch(existing.attributes, action.frontmatter);
+        const patchedFrontmatter = applyMergePatch(existing.attributes, action.frontmatter);
+        const content = frontmatterAdapter.buildMarkdownDocument(patchedFrontmatter, existing.body, { hasFrontmatter: true });
+        await replaceFileAtomically(action.target, deps, (tempPath, fileOps) => fileOps.writeFile(tempPath, content, "utf-8"), async () => {
+            try {
+                await lstat(action.target);
+            }
+            catch {
+                return null;
+            }
+            const backupPath = `${action.target}.inception-backup`;
+            await (deps.fileOps ?? defaultDeployFileOps).rm(backupPath, {
+                recursive: true,
+                force: true,
+            });
+            await (deps.fileOps ?? defaultDeployFileOps).rename(action.target, backupPath);
+            return backupPath;
+        }, () => registerDeployment(home, action.target, {
+            kind: "frontmatter-emit",
+            patch: action.frontmatter,
+            undoPatch,
+            created: !existing.exists,
+            hadFrontmatter: existing.hasFrontmatter,
+            skill: action.skill,
+            agent: action.agent,
+        }, deps.registry));
+        logger.ok(label);
+        if (verbose) {
+            logger.detail(`emit-frontmatter: ${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 validateSkillContract(source, skillPath) {
     let stat;
     try {