@kuznai/inception-engine 0.11.1 → 0.13.0

package/dist/core/adapters/toml.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Reads and parses a TOML file. Returns an empty object if the file does not
+ * exist (treat a missing config.toml as an empty config).
+ */
+export declare function readTomlConfig(filePath: string): Promise<Record<string, unknown>>;
+/**
+ * Merges a named MCP server entry into `config.toml`'s `[mcpServers]` table.
+ * Returns the undo record (the previous value under that key, or null if it
+ * was absent) so revert can restore the exact prior state.
+ */
+export declare function applyTomlMcpPatch(filePath: string, name: string, config: Record<string, unknown>): Promise<{
+    previousValue: unknown | null;
+}>;
+/**
+ * Removes a named MCP server entry from `config.toml`'s `[mcpServers]` table.
+ * If the entry is absent, this is a no-op. If the table becomes empty after
+ * removal, the `mcpServers` key itself is removed from the document.
+ */
+export declare function revertTomlMcpPatch(filePath: string, name: string): Promise<void>;

package/dist/core/adapters/toml.js

@@ -0,0 +1,96 @@
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parse, stringify } from "smol-toml";
+/**
+ * Reads and parses a TOML file. Returns an empty object if the file does not
+ * exist (treat a missing config.toml as an empty config).
+ */
+export async function readTomlConfig(filePath) {
+    let raw;
+    try {
+        raw = await readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return {};
+        throw err;
+    }
+    const parsed = parse(raw);
+    return parsed;
+}
+function createAtomicTempPath(targetPath) {
+    return `${targetPath}.inception-tmp-${process.pid}-${Date.now()}-${Math.random()
+        .toString(36)
+        .slice(2)}`;
+}
+async function writeTomlConfigAtomic(filePath, obj) {
+    const tempPath = createAtomicTempPath(filePath);
+    try {
+        await mkdir(path.dirname(filePath), { recursive: true });
+        await writeFile(tempPath, stringify(obj), "utf-8");
+        await rename(tempPath, filePath);
+    }
+    catch (err) {
+        try {
+            await rm(tempPath, { force: true });
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+        throw err;
+    }
+}
+/**
+ * Merges a named MCP server entry into `config.toml`'s `[mcpServers]` table.
+ * Returns the undo record (the previous value under that key, or null if it
+ * was absent) so revert can restore the exact prior state.
+ */
+export async function applyTomlMcpPatch(filePath, name, config) {
+    const current = await readTomlConfig(filePath);
+    const mcpServers = typeof current.mcpServers === "object" &&
+        current.mcpServers !== null &&
+        !Array.isArray(current.mcpServers)
+        ? current.mcpServers
+        : {};
+    const previousValue = Object.hasOwn(mcpServers, name)
+        ? mcpServers[name]
+        : null;
+    const patched = {
+        ...current,
+        mcpServers: { ...mcpServers, [name]: config },
+    };
+    await writeTomlConfigAtomic(filePath, patched);
+    return { previousValue };
+}
+/**
+ * Removes a named MCP server entry from `config.toml`'s `[mcpServers]` table.
+ * If the entry is absent, this is a no-op. If the table becomes empty after
+ * removal, the `mcpServers` key itself is removed from the document.
+ */
+export async function revertTomlMcpPatch(filePath, name) {
+    let current;
+    try {
+        current = await readTomlConfig(filePath);
+    }
+    catch {
+        // File gone — nothing to revert.
+        return;
+    }
+    const mcpServers = typeof current.mcpServers === "object" &&
+        current.mcpServers !== null &&
+        !Array.isArray(current.mcpServers)
+        ? current.mcpServers
+        : {};
+    if (!Object.hasOwn(mcpServers, name))
+        return; // already absent
+    const { [name]: _removed, ...remainingServers } = mcpServers;
+    const reverted = { ...current };
+    if (Object.keys(remainingServers).length === 0) {
+        delete reverted.mcpServers;
+    }
+    else {
+        reverted.mcpServers = remainingServers;
+    }
+    await writeTomlConfigAtomic(filePath, reverted);
+}

package/dist/core/deploy.js

@@ -4,11 +4,13 @@ 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";
-import { sourceAccessError, validateSourceFile, validateSourcePath, } from "./validation.js";
+import { sourceAccessError, validateSkillDefinitionFile, validateSourceFile, validateSourcePath, } from "./validation.js";
 function isPlainObject(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v);
 }
@@ -80,14 +82,20 @@ function detectCollisions(actions) {
     }
     return warnings;
 }
-function detectAmbiguities(detectedAgents) {
+function detectAmbiguities(detectedAgents, actions, home) {
     const warnings = [];
-    if (detectedAgents.includes("gemini-cli") &&
-        detectedAgents.includes("antigravity")) {
-        warnings.push({
-            kind: "ambiguity",
-            message: 'Both "gemini-cli" and "antigravity" share the ~/.gemini/ base directory. antigravity skill support is implementation-only. Verify that deployed skill paths do not conflict.',
-        });
+    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) {
+            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.",
+            });
+        }
     }
     return warnings;
 }
@@ -143,7 +151,7 @@ async function planFileWriteActions(manifest, sourceDir, resolvedSourceDir, real
     }
     return actions;
 }
-function planConfigPatchActions(manifest, detectedAgents, home) {
+function planConfigPatchActions(manifest, detectedAgents, home, repo) {
     const actions = [];
     for (const configEntry of manifest.configs ?? []) {
         for (const agentId of configEntry.agents) {
@@ -156,7 +164,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),
                 patch: configEntry.patch,
                 confidence: agent.provenance.skills,
             });
@@ -176,56 +184,44 @@ 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),
+        ...planConfigPatchActions(manifest, detectedAgents, home, resolvedSourceDir),
     ];
-    const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home);
+    const adapterResult = await compileAdapterActions(manifest.mcpServers, manifest.agentRules, sourceDir, resolvedSourceDir, realRoot, detectedAgents, home, resolvedSourceDir);
     actions.push(...adapterResult.actions);
     const warnings = [
-        ...detectAmbiguities(detectedAgents),
+        ...detectAmbiguities(detectedAgents, actions, home),
         ...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) {
-        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 };
@@ -505,6 +501,7 @@ async function validateSkillContract(source, skillPath) {
         }
         throw new UserError("DEPLOY_FAILED", `Skill "${skillPath}" source is missing SKILL.md: ${source}`);
     }
+    await validateSkillDefinitionFile(path.join(source, "SKILL.md"), skillPath);
 }
 async function assertTargetAbsent(targetPath) {
     try {
@@ -592,3 +589,87 @@ 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/resolve.d.ts

@@ -9,4 +9,4 @@ export declare function resolveAgentSkillPathFor(agent: AgentConfig, skillName:
 export declare function resolveAgentDetectPathFor(agent: AgentConfig, home: string, platform: "posix" | "windows"): string;
 export declare function resolveAgentSkillPath(agent: AgentConfig, skillName: string, home: string): string;
 export declare function resolveAgentDetectPath(agent: AgentConfig, home: string): string;
-export declare function resolvePlaceholders(segments: string[], skillName: string, home: string): string;
+export declare function resolvePlaceholders(segments: string[], skillName: string, home: string, repo?: string): string;

package/dist/core/resolve.js

@@ -96,13 +96,14 @@ export function resolveAgentSkillPath(agent, skillName, home) {
 export function resolveAgentDetectPath(agent, home) {
     return resolveAgentDetectPathFor(agent, home, getPlatformKey());
 }
-export function resolvePlaceholders(segments, skillName, home) {
+export function resolvePlaceholders(segments, skillName, home, repo) {
     const { appdata, xdgConfig } = resolveRuntimePaths(home);
     const resolved = segments.map((seg) => seg
         .replace("{home}", home)
         .replace("{name}", skillName)
         .replace("{appdata}", appdata)
-        .replace("{xdg_config}", xdgConfig));
+        .replace("{xdg_config}", xdgConfig)
+        .replace("{repo}", repo ?? ""));
     const root = resolved.find((segment) => segment.length > 0) ?? home;
     return getPathApi(root).join(...resolved);
 }

package/dist/core/revert.d.ts

@@ -1,7 +1,7 @@
 import type { AgentId, Manifest, PlannedChange, RevertAction } from "../types.ts";
 import { type RegistryPersistence } from "./ownership.ts";
-export declare function planRevert(manifest: Manifest, detectedAgents: AgentId[], home: string): RevertAction[];
-export declare function planRevertAll(manifest: Manifest, home: string): RevertAction[];
+export declare function planRevert(manifest: Manifest, detectedAgents: AgentId[], home: string, repo?: string): RevertAction[];
+export declare function planRevertAll(manifest: Manifest, home: string, repo?: string): RevertAction[];
 export declare function executeRevert(actions: RevertAction[], dryRun: boolean, verbose: boolean, home: string, deps?: RevertDependencies): Promise<{
     succeeded: number;
     skipped: number;

package/dist/core/revert.js

@@ -2,6 +2,7 @@ import { lstat, readFile, rm, unlink, writeFile } from "node:fs/promises";
 import { AGENT_REGISTRY_BY_ID } from "../config/agents.js";
 import { logger } from "../logger.js";
 import { compileAgentRuleReverts, compileMcpServerReverts, } from "./adapters/index.js";
+import { revertTomlMcpPatch } from "./adapters/toml.js";
 import { lookupDeployment, unregisterDeployment, } from "./ownership.js";
 import { resolveAgentSkillPath } from "./resolve.js";
 import { resolveTargetTemplate } from "./runtime-paths.js";
@@ -62,22 +63,22 @@ function buildConfigPatchReverts(manifest, home, agentFilter) {
     }
     return actions;
 }
-export function planRevert(manifest, detectedAgents, home) {
+export function planRevert(manifest, detectedAgents, home, repo) {
     return [
         ...buildSkillDirReverts(manifest, home, detectedAgents),
         ...buildFileWriteReverts(manifest, home, detectedAgents),
         ...buildConfigPatchReverts(manifest, home, detectedAgents),
-        ...(manifest.mcpServers ?? []).flatMap((e) => compileMcpServerReverts(e, detectedAgents, home)),
-        ...(manifest.agentRules ?? []).flatMap((e) => compileAgentRuleReverts(e, detectedAgents, home)),
+        ...(manifest.mcpServers ?? []).flatMap((e) => compileMcpServerReverts(e, detectedAgents, home, repo)),
+        ...(manifest.agentRules ?? []).flatMap((e) => compileAgentRuleReverts(e, detectedAgents, home, repo)),
     ];
 }
-export function planRevertAll(manifest, home) {
+export function planRevertAll(manifest, home, repo) {
     return [
         ...buildSkillDirReverts(manifest, home, null),
         ...buildFileWriteReverts(manifest, home, null),
         ...buildConfigPatchReverts(manifest, home, null),
-        ...(manifest.mcpServers ?? []).flatMap((e) => compileMcpServerReverts(e, null, home)),
-        ...(manifest.agentRules ?? []).flatMap((e) => compileAgentRuleReverts(e, null, home)),
+        ...(manifest.mcpServers ?? []).flatMap((e) => compileMcpServerReverts(e, null, home, repo)),
+        ...(manifest.agentRules ?? []).flatMap((e) => compileAgentRuleReverts(e, null, home, repo)),
     ];
 }
 function recordOutcome(result, action, counts, failed) {
@@ -148,8 +149,21 @@ export async function executeRevert(actions, dryRun, verbose, home, deps = {}) {
             case "config-patch":
                 result = await revertConfigPatch(action, dryRun, verbose, home, planned, deps);
                 break;
+            case "toml-patch":
+                result = await revertTomlPatch(action, dryRun, verbose, home, planned, deps);
+                break;
+            case "frontmatter-emit":
+                // Frontmatter-emit files are fully managed by inception — revert
+                // deletes the file, same as a file-write revert.
+                result = await revertFileWrite({
+                    kind: "file-write",
+                    skill: action.skill,
+                    agent: action.agent,
+                    target: action.target,
+                }, dryRun, verbose, home, planned, deps);
+                break;
             default:
-                throw new Error(`Unhandled revert action kind: ${action}`);
+                throw new Error(`Unhandled revert action kind: ${action.kind}`);
         }
         recordOutcome(result, action, counts, failed);
     }
@@ -316,3 +330,50 @@ async function revertConfigPatch(action, dryRun, verbose, home, planned, deps) {
         return { outcome: "fail", error: msg };
     }
 }
+async function revertTomlPatch(action, dryRun, verbose, home, planned, deps) {
+    const label = `${action.skill} -> ${action.agent}`;
+    try {
+        await lstat(action.target);
+    }
+    catch (err) {
+        const result = lstatOutcome(err);
+        if (result.outcome === "skip") {
+            logger.skip(label, "(not found, skipping)");
+            return result;
+        }
+        logger.fail(label, result.error);
+        return result;
+    }
+    const entry = await lookupDeployment(home, action.target, deps.registry);
+    if (!entry ||
+        entry.kind !== "config-patch" ||
+        entry.skill !== action.skill ||
+        entry.agent !== action.agent) {
+        logger.warn(label, `skipping: ${action.target} is not in the deployment registry — not managed by inception-engine`);
+        return { outcome: "skip" };
+    }
+    if (dryRun) {
+        planned.push({
+            verb: "unapply-patch",
+            kind: "toml-patch",
+            skill: action.skill,
+            agent: action.agent,
+            target: action.target,
+        });
+        return { outcome: "ok" };
+    }
+    try {
+        await revertTomlMcpPatch(action.target, action.skill);
+        await unregisterDeployment(home, action.target, deps.registry);
+        logger.ok(label);
+        if (verbose) {
+            logger.detail(`removed [mcpServers.${action.skill}] from: ${action.target}`);
+        }
+        return { outcome: "ok" };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.fail(label, msg);
+        return { outcome: "fail", error: msg };
+    }
+}

package/dist/core/runtime-paths.d.ts

@@ -5,4 +5,4 @@ export interface RuntimePaths {
 }
 export declare function getPathApi(root: string): typeof path.posix | typeof path.win32;
 export declare function resolveRuntimePaths(home: string): RuntimePaths;
-export declare function resolveTargetTemplate(template: string, home: string): string;
+export declare function resolveTargetTemplate(template: string, home: string, repo?: string): string;

package/dist/core/runtime-paths.js

@@ -1,5 +1,5 @@
 import path from "node:path";
-const TARGET_TEMPLATE_RE = /^\{(home|appdata|xdg_config)\}(?<suffix>(?:[\\/].*)?)$/;
+const TARGET_TEMPLATE_RE = /^\{(home|appdata|xdg_config|repo)\}(?<suffix>(?:[\\/].*)?)$/;
 export function getPathApi(root) {
     if (root.includes("\\") || /^[a-zA-Z]:/.test(root)) {
         return path.win32;
@@ -32,18 +32,31 @@ export function resolveRuntimePaths(home) {
         : homePathApi.join(home, ".config");
     return { appdata, xdgConfig };
 }
-export function resolveTargetTemplate(template, home) {
+export function resolveTargetTemplate(template, home, repo) {
     const { appdata, xdgConfig } = resolveRuntimePaths(home);
     const match = TARGET_TEMPLATE_RE.exec(template);
     if (!match) {
         throw new Error(`Invalid target template: ${template}`);
     }
+    const root = match[1];
+    if (root === "repo") {
+        if (!repo) {
+            throw new Error(`Target template uses {repo} but no manifest directory was provided: ${template}`);
+        }
+        const suffix = match.groups?.suffix ?? "";
+        const segments = suffix.split(/[\\/]+/).filter(Boolean);
+        const repoPathApi = getPathApi(repo);
+        const resolved = segments.length === 0 ? repo : repoPathApi.join(repo, ...segments);
+        if (!isSameOrDescendantPath(resolved, repo)) {
+            throw new Error(`Target template resolves outside its placeholder root: ${template}`);
+        }
+        return suffix === "" ? repo : `${repo}${suffix}`;
+    }
     const baseByRoot = {
         home,
         appdata,
         xdg_config: xdgConfig,
     };
-    const root = match[1];
     const suffix = match.groups?.suffix ?? "";
     const segments = suffix.split(/[\\/]+/).filter(Boolean);
     const pathApi = getPathApi(baseByRoot[root]);

package/dist/core/validation.d.ts

@@ -1,3 +1,6 @@
 export declare function sourceAccessError(err: unknown, sourcePath: string): string;
 export declare function validateSourcePath(source: string, skillPath: string, resolvedSourceDir: string, realRoot: string): Promise<void>;
 export declare function validateSourceFile(sourcePath: string, manifestPath: string): Promise<void>;
+export declare function validateMcpServerConfigShape(config: Record<string, unknown>, entryName: string, agentId: string): void;
+export declare function validateAgentRuleMarkdownPath(manifestPath: string, agentId: string): void;
+export declare function validateSkillDefinitionFile(sourcePath: string, manifestPath: string): Promise<void>;

package/dist/core/validation.js

@@ -1,4 +1,4 @@
-import { lstat, realpath, stat } from "node:fs/promises";
+import { lstat, readFile, realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import { UserError } from "../errors.js";
 export function sourceAccessError(err, sourcePath) {
@@ -64,3 +64,99 @@ export async function validateSourceFile(sourcePath, manifestPath) {
         throw new UserError("DEPLOY_FAILED", `Source is not a file: ${manifestPath}`);
     }
 }
+function isRecordOfStrings(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        Object.values(value).every((entry) => typeof entry === "string"));
+}
+function validateNonEmptyStringField(value, field, entryName, agentId) {
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new UserError("DEPLOY_FAILED", `mcpServers entry "${entryName}" for agent "${agentId}" must define "${field}" as a non-empty string`);
+    }
+}
+export function validateMcpServerConfigShape(config, entryName, agentId) {
+    const hasCommand = Object.hasOwn(config, "command");
+    const hasUrl = Object.hasOwn(config, "url");
+    if (!(hasCommand || hasUrl)) {
+        throw new UserError("DEPLOY_FAILED", `mcpServers entry "${entryName}" for agent "${agentId}" must define either a non-empty "command" or "url"`);
+    }
+    if (hasCommand) {
+        validateNonEmptyStringField(config.command, "command", entryName, agentId);
+    }
+    if (hasUrl) {
+        validateNonEmptyStringField(config.url, "url", entryName, agentId);
+    }
+    if (Object.hasOwn(config, "args") &&
+        (!Array.isArray(config.args) ||
+            config.args.some((arg) => typeof arg !== "string"))) {
+        throw new UserError("DEPLOY_FAILED", `mcpServers entry "${entryName}" for agent "${agentId}" must define "args" as an array of strings when present`);
+    }
+    if (Object.hasOwn(config, "env") && !isRecordOfStrings(config.env)) {
+        throw new UserError("DEPLOY_FAILED", `mcpServers entry "${entryName}" for agent "${agentId}" must define "env" as an object of string values when present`);
+    }
+}
+export function validateAgentRuleMarkdownPath(manifestPath, agentId) {
+    const extension = path.extname(manifestPath).toLowerCase();
+    if (extension !== ".md" && extension !== ".markdown") {
+        throw new UserError("DEPLOY_FAILED", `agentRules entry "${manifestPath}" for agent "${agentId}" must point to a Markdown source file`);
+    }
+}
+function trimMatchingQuotes(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1).trim();
+    }
+    return value;
+}
+function parseSimpleFrontmatterValue(field, rawValue, manifestPath) {
+    const value = trimMatchingQuotes(rawValue.trim());
+    if (value.length === 0) {
+        throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md frontmatter field "${field}" must be a non-empty string`);
+    }
+    if (rawValue.trim() === "|" || rawValue.trim() === ">") {
+        throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md frontmatter field "${field}" must be a single-line string`);
+    }
+    return value;
+}
+export async function validateSkillDefinitionFile(sourcePath, manifestPath) {
+    await validateSourceFile(sourcePath, `${manifestPath}/SKILL.md`);
+    let raw;
+    try {
+        raw = await readFile(sourcePath, "utf-8");
+    }
+    catch (err) {
+        throw new UserError("DEPLOY_FAILED", sourceAccessError(err, `${manifestPath}/SKILL.md`));
+    }
+    const lines = raw.split(/\r?\n/);
+    if (lines[0]?.trim() !== "---") {
+        throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md must start with YAML frontmatter delimited by ---`);
+    }
+    const closingIndex = lines.findIndex((line, index) => index > 0 && line.trim() === "---");
+    if (closingIndex === -1) {
+        throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md is missing the closing --- frontmatter delimiter`);
+    }
+    let name = null;
+    let description = null;
+    for (const line of lines.slice(1, closingIndex)) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0 || trimmed.startsWith("#"))
+            continue;
+        const match = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const [, key, rawValue] = match;
+        if (key === "name") {
+            name = parseSimpleFrontmatterValue("name", rawValue, manifestPath);
+        }
+        else if (key === "description") {
+            description = parseSimpleFrontmatterValue("description", rawValue, manifestPath);
+        }
+    }
+    if (name === null) {
+        throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md frontmatter must include a non-empty "name" field`);
+    }
+    if (description === null) {
+        throw new UserError("DEPLOY_FAILED", `Skill "${manifestPath}" SKILL.md frontmatter must include a non-empty "description" field`);
+    }
+}