@lnai/core 0.6.0 → 0.6.6

package/dist/index.d.ts

@@ -40,6 +40,10 @@ declare class PluginError extends LnaiError {
     readonly pluginId: string;
     constructor(message: string, pluginId: string, cause?: Error);
 }
+declare class InvalidToolError extends LnaiError {
+    readonly invalidTools: string[];
+    constructor(invalidTools: string[], validTools: string[]);
+}
 
 /** MCP Server configuration (Claude format as source of truth) */
 declare const mcpServerSchema: z.ZodObject<{
@@ -202,6 +206,25 @@ interface SyncResult {
     changes: ChangeResult[];
     validation: ValidationResult;
 }
+/** Entry for a single file in the manifest */
+interface ManifestEntry {
+    path: string;
+    type: "json" | "text" | "symlink";
+    hash?: string;
+    target?: string;
+}
+/** Manifest for a single tool's generated files */
+interface ToolManifest {
+    version: 1;
+    tool: ToolId;
+    generatedAt: string;
+    files: ManifestEntry[];
+}
+/** Root manifest tracking all LNAI-generated files */
+interface LnaiManifest {
+    version: 1;
+    tools: Partial<Record<ToolId, ToolManifest>>;
+}
 
 declare function parseFrontmatter(content: string): {
     frontmatter: Record<string, unknown>;
@@ -260,7 +283,7 @@ declare const claudeCodePlugin: Plugin;
  * Output structure:
  * - AGENTS.md (symlink -> .ai/AGENTS.md) [at project root]
  * - <dir>/AGENTS.md (generated from .ai/rules/*.md, per glob directory)
- * - .codex/skills/<name>/ (symlink -> ../../.ai/skills/<name>)
+ * - .agents/skills/<name>/ (symlink -> ../../.ai/skills/<name>)
  * - .codex/config.toml (generated from settings.mcpServers)
  * - .codex/<path> (symlink -> ../.ai/.codex/<path>) for override files
  */
@@ -272,7 +295,7 @@ declare const codexPlugin: Plugin;
  * Output structure:
  * - AGENTS.md (symlink -> .ai/AGENTS.md) [at project root]
  * - .opencode/rules/ (symlink -> ../.ai/rules)
- * - .opencode/skills/<name>/ (symlink -> ../../.ai/skills/<name>)
+ * - .agents/skills/<name>/ (symlink -> ../../.ai/skills/<name>)
  * - opencode.json (generated config merged with .ai/.opencode/opencode.json)
  * - .opencode/<path> (symlink -> ../.ai/.opencode/<path>) for other override files
  */
@@ -298,8 +321,8 @@ interface SyncOptions {
     tools?: ToolId[];
     /** Preview changes without writing files */
     dryRun?: boolean;
-    /** Enable verbose output */
-    verbose?: boolean;
+    /** Skip cleanup of orphaned files */
+    skipCleanup?: boolean;
 }
 /**
  * Run the sync pipeline to export .ai/ config to native tool formats.
@@ -320,9 +343,50 @@ declare function writeFiles(files: OutputFile[], options: WriterOptions): Promis
 /**
  * Update .gitignore with paths that should not be version controlled.
  * Manages a dedicated "lnai-generated" section to avoid conflicts with user entries.
+ * Replaces the managed section on each run so stale paths are removed.
  */
 declare function updateGitignore(rootDir: string, paths: string[]): Promise<void>;
 
+declare const MANIFEST_FILENAME = ".lnai-manifest.json";
+/**
+ * Read the LNAI manifest from the .ai directory.
+ * Returns null if the manifest doesn't exist.
+ */
+declare function readManifest(rootDir: string): Promise<LnaiManifest | null>;
+/**
+ * Write the LNAI manifest to the .ai directory.
+ */
+declare function writeManifest(rootDir: string, manifest: LnaiManifest): Promise<void>;
+/**
+ * Build a tool manifest from output files.
+ */
+declare function buildToolManifest(toolId: ToolId, files: OutputFile[]): ToolManifest;
+/**
+ * Update a single tool's manifest entry.
+ */
+declare function updateToolManifest(manifest: LnaiManifest, toolId: ToolId, files: OutputFile[]): LnaiManifest;
+/**
+ * Create an empty manifest.
+ */
+declare function createEmptyManifest(): LnaiManifest;
+
+/**
+ * Compute which files should be deleted based on previous and current manifest entries.
+ * Returns paths that exist in previous but not in current.
+ */
+declare function computeFilesToDelete(previousFiles: ManifestEntry[], currentFiles: OutputFile[]): string[];
+/**
+ * Delete files that are no longer in the manifest.
+ * Returns ChangeResult[] with action: "delete" for each deleted file.
+ * When dryRun is true, no files are actually deleted.
+ */
+declare function deleteFiles(paths: string[], rootDir: string, dryRun: boolean): Promise<ChangeResult[]>;
+/**
+ * Clean up empty parent directories after file deletion.
+ * Stops at the project root directory.
+ */
+declare function cleanupEmptyParentDirs(filePath: string, rootDir: string): Promise<void>;
+
 interface InitOptions {
     rootDir: string;
     tools?: ToolId[];
@@ -337,4 +401,4 @@ declare function initUnifiedConfig(options: InitOptions): Promise<InitResult>;
 declare function hasUnifiedConfig(rootDir: string): Promise<boolean>;
 declare function generateDefaultConfig(tools?: ToolId[], versionControl?: Record<ToolId, boolean>): Config;
 
-export { CONFIG_DIRS, CONFIG_FILES, type ChangeResult, type Config, FileNotFoundError, type InitOptions, type InitResult, LnaiError, type MarkdownFile, type MarkdownFrontmatter, type McpServer, type OutputFile, ParseError, type PermissionLevel, type Permissions, type Plugin, PluginError, type RuleFrontmatter, type Settings, type SkillFrontmatter, type SkippedFeatureDetail, type SyncOptions, type SyncResult, TOOL_IDS, TOOL_OUTPUT_DIRS, type ToolConfig, type ToolId, UNIFIED_DIR, type UnifiedState, ValidationError, type ValidationErrorDetail, type ValidationResult, type ValidationWarningDetail, WriteError, type WriterOptions, claudeCodePlugin, codexPlugin, computeHash, configSchema, generateDefaultConfig, hasUnifiedConfig, initUnifiedConfig, mcpServerSchema, opencodePlugin, parseFrontmatter, parseUnifiedConfig, permissionsSchema, pluginRegistry, ruleFrontmatterSchema, runSyncPipeline, settingsSchema, skillFrontmatterSchema, toolConfigSchema, toolIdSchema, updateGitignore, validateConfig, validateSettings, validateUnifiedState, writeFiles };
+export { CONFIG_DIRS, CONFIG_FILES, type ChangeResult, type Config, FileNotFoundError, type InitOptions, type InitResult, InvalidToolError, LnaiError, type LnaiManifest, MANIFEST_FILENAME, type ManifestEntry, type MarkdownFile, type MarkdownFrontmatter, type McpServer, type OutputFile, ParseError, type PermissionLevel, type Permissions, type Plugin, PluginError, type RuleFrontmatter, type Settings, type SkillFrontmatter, type SkippedFeatureDetail, type SyncOptions, type SyncResult, TOOL_IDS, TOOL_OUTPUT_DIRS, type ToolConfig, type ToolId, type ToolManifest, UNIFIED_DIR, type UnifiedState, ValidationError, type ValidationErrorDetail, type ValidationResult, type ValidationWarningDetail, WriteError, type WriterOptions, buildToolManifest, claudeCodePlugin, cleanupEmptyParentDirs, codexPlugin, computeFilesToDelete, computeHash, configSchema, createEmptyManifest, deleteFiles, generateDefaultConfig, hasUnifiedConfig, initUnifiedConfig, mcpServerSchema, opencodePlugin, parseFrontmatter, parseUnifiedConfig, permissionsSchema, pluginRegistry, readManifest, ruleFrontmatterSchema, runSyncPipeline, settingsSchema, skillFrontmatterSchema, toolConfigSchema, toolIdSchema, updateGitignore, updateToolManifest, validateConfig, validateSettings, validateUnifiedState, writeFiles, writeManifest };

package/dist/index.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import * as fs3 from 'fs/promises';
+import * as fs4 from 'fs/promises';
 import * as path from 'path';
 import matter from 'gray-matter';
 import * as crypto from 'crypto';
@@ -67,10 +67,10 @@ var ParseError = class extends LnaiError {
 var ValidationError = class extends LnaiError {
   path;
   value;
-  constructor(message, path6, value) {
+  constructor(message, path8, value) {
     super(message, "VALIDATION_ERROR");
     this.name = "ValidationError";
-    this.path = path6;
+    this.path = path8;
     this.value = value;
   }
 };
@@ -104,6 +104,17 @@ var PluginError = class extends LnaiError {
     }
   }
 };
+var InvalidToolError = class extends LnaiError {
+  invalidTools;
+  constructor(invalidTools, validTools) {
+    super(
+      `Invalid tool(s): ${invalidTools.join(", ")}. Valid tools: ${validTools.join(", ")}`,
+      "INVALID_TOOL"
+    );
+    this.name = "InvalidToolError";
+    this.invalidTools = invalidTools;
+  }
+};
 var mcpServerSchema = z.object({
   command: z.string().optional(),
   args: z.array(z.string()).optional(),
@@ -204,7 +215,7 @@ async function parseUnifiedConfig(rootDir) {
 }
 async function fileExists(filePath) {
   try {
-    await fs3.access(filePath);
+    await fs4.access(filePath);
     return true;
   } catch {
     return false;
@@ -212,7 +223,7 @@ async function fileExists(filePath) {
 }
 async function readJsonFile(filePath) {
   try {
-    const content = await fs3.readFile(filePath, "utf-8");
+    const content = await fs4.readFile(filePath, "utf-8");
     return JSON.parse(content);
   } catch (error) {
     if (error.code === "ENOENT") {
@@ -227,7 +238,7 @@ async function readJsonFile(filePath) {
 }
 async function readMarkdownFile(filePath) {
   try {
-    return await fs3.readFile(filePath, "utf-8");
+    return await fs4.readFile(filePath, "utf-8");
   } catch (error) {
     if (error.code === "ENOENT") {
       throw new FileNotFoundError(`File not found: ${filePath}`, filePath);
@@ -244,7 +255,7 @@ async function readMarkdownDirectory(dirPath) {
   if (!await fileExists(dirPath)) {
     return files;
   }
-  const entries = await fs3.readdir(dirPath, { withFileTypes: true });
+  const entries = await fs4.readdir(dirPath, { withFileTypes: true });
   for (const entry of entries) {
     if (entry.isFile() && entry.name.endsWith(".md")) {
       const filePath = path.join(dirPath, entry.name);
@@ -264,7 +275,7 @@ async function readSkillsDirectory(dirPath) {
   if (!await fileExists(dirPath)) {
     return skills;
   }
-  const entries = await fs3.readdir(dirPath, { withFileTypes: true });
+  const entries = await fs4.readdir(dirPath, { withFileTypes: true });
   for (const entry of entries) {
     if (entry.isDirectory()) {
       const skillFile = path.join(dirPath, entry.name, "SKILL.md");
@@ -402,10 +413,43 @@ function validateToolIds(tools) {
   }
   return { valid: true, errors: [], warnings: [], skipped: [] };
 }
+
+// src/utils/agents.ts
+function createRootAgentsMdSymlink(state) {
+  if (!state.agents) {
+    return null;
+  }
+  return {
+    path: "AGENTS.md",
+    type: "symlink",
+    target: `${UNIFIED_DIR}/AGENTS.md`
+  };
+}
+function createSkillSymlinks(state, outputDir) {
+  const depth = outputDir.split("/").length + 1;
+  const prefix = "../".repeat(depth);
+  return state.skills.map((skill) => ({
+    path: `${outputDir}/skills/${skill.path}`,
+    type: "symlink",
+    target: `${prefix}${UNIFIED_DIR}/skills/${skill.path}`
+  }));
+}
+function createNoAgentsMdWarning(outputDescription) {
+  return {
+    path: ["AGENTS.md"],
+    message: `No AGENTS.md found - ${outputDescription} will not be created`
+  };
+}
+function hasPermissionsConfigured(permissions) {
+  if (!permissions) {
+    return false;
+  }
+  return (permissions.allow?.length ?? 0) > 0 || (permissions.ask?.length ?? 0) > 0 || (permissions.deny?.length ?? 0) > 0;
+}
 async function scanOverrideDirectory(rootDir, toolId) {
   const overrideDir = path.join(rootDir, UNIFIED_DIR, OVERRIDE_DIRS[toolId]);
   try {
-    await fs3.access(overrideDir);
+    await fs4.access(overrideDir);
   } catch {
     return [];
   }
@@ -414,7 +458,7 @@ async function scanOverrideDirectory(rootDir, toolId) {
   return files;
 }
 async function scanDir(baseDir, currentDir, files) {
-  const entries = await fs3.readdir(currentDir, { withFileTypes: true });
+  const entries = await fs4.readdir(currentDir, { withFileTypes: true });
   for (const entry of entries) {
     const absolutePath = path.join(currentDir, entry.name);
     if (entry.isDirectory()) {
@@ -446,6 +490,7 @@ async function applyFileOverrides(files, rootDir, toolId) {
 }
 
 // src/plugins/claude-code/index.ts
+var OUTPUT_DIR = TOOL_OUTPUT_DIRS.claudeCode;
 var claudeCodePlugin = {
   id: "claudeCode",
   name: "Claude Code",
@@ -457,28 +502,21 @@ var claudeCodePlugin = {
   },
   async export(state, rootDir) {
     const files = [];
-    const outputDir = TOOL_OUTPUT_DIRS.claudeCode;
     if (state.agents) {
       files.push({
-        path: `${outputDir}/CLAUDE.md`,
+        path: `${OUTPUT_DIR}/CLAUDE.md`,
         type: "symlink",
         target: `../${UNIFIED_DIR}/AGENTS.md`
       });
     }
     if (state.rules.length > 0) {
       files.push({
-        path: `${outputDir}/rules`,
+        path: `${OUTPUT_DIR}/rules`,
         type: "symlink",
         target: `../${UNIFIED_DIR}/rules`
       });
     }
-    for (const skill of state.skills) {
-      files.push({
-        path: `${outputDir}/skills/${skill.path}`,
-        type: "symlink",
-        target: `../../${UNIFIED_DIR}/skills/${skill.path}`
-      });
-    }
+    files.push(...createSkillSymlinks(state, OUTPUT_DIR));
     const settings = {};
     if (state.settings?.permissions) {
       settings["permissions"] = state.settings.permissions;
@@ -488,7 +526,7 @@ var claudeCodePlugin = {
     }
     if (Object.keys(settings).length > 0) {
       files.push({
-        path: `${outputDir}/settings.json`,
+        path: `${OUTPUT_DIR}/settings.json`,
         type: "json",
         content: settings
       });
@@ -498,10 +536,7 @@ var claudeCodePlugin = {
   validate(state) {
     const warnings = [];
     if (!state.agents) {
-      warnings.push({
-        path: ["AGENTS.md"],
-        message: "No AGENTS.md found - .claude/CLAUDE.md will not be created"
-      });
+      warnings.push(createNoAgentsMdWarning(".claude/CLAUDE.md"));
     }
     return { valid: true, errors: [], warnings, skipped: [] };
   }
@@ -510,8 +545,8 @@ function getDirFromGlob(glob) {
   const cleanPath = glob.replace(/(\*\*|\*|\{.*,.*\}).*$/, "");
   const dir = cleanPath.replace(/\/$/, "");
   if (dir === glob) {
-    const dirname4 = path.dirname(dir);
-    return dirname4 === "." && !dir.includes("/") ? "." : dirname4;
+    const dirname5 = path.dirname(dir);
+    return dirname5 === "." && !dir.includes("/") ? "." : dirname5;
   }
   if (!dir) {
     return ".";
@@ -543,6 +578,8 @@ ${rule.content}
 }
 
 // src/plugins/codex/index.ts
+var OUTPUT_DIR2 = TOOL_OUTPUT_DIRS.codex;
+var SKILLS_DIR = ".agents";
 var codexPlugin = {
   id: "codex",
   name: "Codex",
@@ -554,13 +591,9 @@ var codexPlugin = {
   },
   async export(state, rootDir) {
     const files = [];
-    const outputDir = TOOL_OUTPUT_DIRS.codex;
-    if (state.agents) {
-      files.push({
-        path: "AGENTS.md",
-        type: "symlink",
-        target: `${UNIFIED_DIR}/AGENTS.md`
-      });
+    const agentsSymlink = createRootAgentsMdSymlink(state);
+    if (agentsSymlink) {
+      files.push(agentsSymlink);
     }
     const rulesMap = groupRulesByDirectory(state.rules);
     for (const [dir, contents] of rulesMap.entries()) {
@@ -574,17 +607,11 @@ var codexPlugin = {
         content: combinedContent
       });
     }
-    for (const skill of state.skills) {
-      files.push({
-        path: `${outputDir}/skills/${skill.path}`,
-        type: "symlink",
-        target: `../../${UNIFIED_DIR}/skills/${skill.path}`
-      });
-    }
+    files.push(...createSkillSymlinks(state, SKILLS_DIR));
     const configToml = buildCodexConfigToml(state.settings?.mcpServers);
     if (configToml) {
       files.push({
-        path: `${outputDir}/config.toml`,
+        path: `${OUTPUT_DIR2}/config.toml`,
         type: "text",
         content: configToml
       });
@@ -595,10 +622,7 @@ var codexPlugin = {
     const warnings = [];
     const skipped = [];
     if (!state.agents) {
-      warnings.push({
-        path: ["AGENTS.md"],
-        message: "No AGENTS.md found - root AGENTS.md will not be created"
-      });
+      warnings.push(createNoAgentsMdWarning("root AGENTS.md"));
     }
     const rulesMap = groupRulesByDirectory(state.rules);
     if (rulesMap.has(".")) {
@@ -618,14 +642,11 @@ var codexPlugin = {
         }
       }
     }
-    if (state.settings?.permissions) {
-      const hasPermissions = (state.settings.permissions.allow?.length ?? 0) > 0 || (state.settings.permissions.ask?.length ?? 0) > 0 || (state.settings.permissions.deny?.length ?? 0) > 0;
-      if (hasPermissions) {
-        skipped.push({
-          feature: "permissions",
-          reason: "Codex rules are not generated from LNAI permissions"
-        });
-      }
+    if (hasPermissionsConfigured(state.settings?.permissions)) {
+      skipped.push({
+        feature: "permissions",
+        reason: "Codex rules are not generated from LNAI permissions"
+      });
     }
     return { valid: true, errors: [], warnings, skipped };
   }
@@ -684,6 +705,32 @@ function formatTomlInlineTable(values) {
   return `{ ${entries.join(", ")} }`;
 }
 
+// src/utils/mcp.ts
+function validateMcpServers(mcpServers, pathPrefix) {
+  const warnings = [];
+  if (!mcpServers) {
+    return warnings;
+  }
+  for (const [name, server] of Object.entries(mcpServers)) {
+    const isRemote = server.type === "http" || server.type === "sse";
+    const hasCommand = !!server.command;
+    const hasUrl = !!server.url;
+    if (!isRemote && !hasCommand) {
+      warnings.push({
+        path: [...pathPrefix, name],
+        message: `MCP server "${name}" has no command or type - it will be skipped`
+      });
+    }
+    if (isRemote && !hasUrl) {
+      warnings.push({
+        path: [...pathPrefix, name],
+        message: `MCP server "${name}" is remote but has no URL - it will be skipped`
+      });
+    }
+  }
+  return warnings;
+}
+
 // src/utils/transforms.ts
 var ENV_VAR_PATTERN = /\$\{([^}:]+)(:-[^}]*)?\}/g;
 function transformEnvVar(value, format) {
@@ -789,6 +836,7 @@ function transformMcpToCopilot(servers) {
 }
 
 // src/plugins/copilot/index.ts
+var OUTPUT_DIR3 = TOOL_OUTPUT_DIRS.copilot;
 var copilotPlugin = {
   id: "copilot",
   name: "GitHub Copilot",
@@ -800,12 +848,9 @@ var copilotPlugin = {
   },
   async export(state, rootDir) {
     const files = [];
-    if (state.agents) {
-      files.push({
-        path: ".github/copilot-instructions.md",
-        type: "symlink",
-        target: `../${UNIFIED_DIR}/AGENTS.md`
-      });
+    const agentsSymlink = createRootAgentsMdSymlink(state);
+    if (agentsSymlink) {
+      files.push(agentsSymlink);
     }
     for (const rule of state.rules) {
       const transformed = transformRuleToCopilot(rule);
@@ -815,18 +860,12 @@ var copilotPlugin = {
       );
       const outputFilename = rule.path.replace(/\.md$/, ".instructions.md");
       files.push({
-        path: `.github/instructions/${outputFilename}`,
+        path: `${OUTPUT_DIR3}/instructions/${outputFilename}`,
         type: "text",
         content: ruleContent
       });
     }
-    for (const skill of state.skills) {
-      files.push({
-        path: `.github/skills/${skill.path}`,
-        type: "symlink",
-        target: `../../${UNIFIED_DIR}/skills/${skill.path}`
-      });
-    }
+    files.push(...createSkillSymlinks(state, OUTPUT_DIR3));
     const mcpConfig = transformMcpToCopilot(state.settings?.mcpServers);
     if (mcpConfig) {
       files.push({
@@ -841,37 +880,20 @@ var copilotPlugin = {
     const warnings = [];
     const skipped = [];
     if (!state.agents) {
-      warnings.push({
-        path: ["AGENTS.md"],
-        message: "No AGENTS.md found - .github/copilot-instructions.md will not be created"
-      });
+      warnings.push(createNoAgentsMdWarning("root AGENTS.md"));
     }
-    const permissions = state.settings?.permissions;
-    const hasPermissions = permissions && (permissions.allow && permissions.allow.length > 0 || permissions.ask && permissions.ask.length > 0 || permissions.deny && permissions.deny.length > 0);
-    if (hasPermissions) {
+    if (hasPermissionsConfigured(state.settings?.permissions)) {
       skipped.push({
         feature: "permissions",
         reason: "GitHub Copilot does not support declarative permissions"
       });
     }
-    const mcpServers = state.settings?.mcpServers;
-    if (mcpServers) {
-      for (const [name, server] of Object.entries(mcpServers)) {
-        const isRemote = server.type === "http" || server.type === "sse";
-        const hasCommand = !!server.command;
-        if (isRemote && !server.url) {
-          warnings.push({
-            path: ["settings", "mcpServers", name],
-            message: `MCP server "${name}" is type "${server.type}" but has no url - it will be skipped`
-          });
-        } else if (!isRemote && !hasCommand) {
-          warnings.push({
-            path: ["settings", "mcpServers", name],
-            message: `MCP server "${name}" has no command or type - it will be skipped`
-          });
-        }
-      }
-    }
+    warnings.push(
+      ...validateMcpServers(state.settings?.mcpServers, [
+        "settings",
+        "mcpServers"
+      ])
+    );
     return { valid: true, errors: [], warnings, skipped };
   }
 };
@@ -992,6 +1014,7 @@ function transformPermissionRule(rule) {
 }
 
 // src/plugins/cursor/index.ts
+var OUTPUT_DIR4 = TOOL_OUTPUT_DIRS.cursor;
 var cursorPlugin = {
   id: "cursor",
   name: "Cursor",
@@ -1003,13 +1026,9 @@ var cursorPlugin = {
   },
   async export(state, rootDir) {
     const files = [];
-    const outputDir = TOOL_OUTPUT_DIRS.cursor;
-    if (state.agents) {
-      files.push({
-        path: "AGENTS.md",
-        type: "symlink",
-        target: `${UNIFIED_DIR}/AGENTS.md`
-      });
+    const agentsSymlink = createRootAgentsMdSymlink(state);
+    if (agentsSymlink) {
+      files.push(agentsSymlink);
     }
     for (const rule of state.rules) {
       const transformed = transformRuleToCursor(rule);
@@ -1019,22 +1038,16 @@ var cursorPlugin = {
       );
       const outputFilename = rule.path.replace(/\.md$/, ".mdc");
       files.push({
-        path: `${outputDir}/rules/${outputFilename}`,
+        path: `${OUTPUT_DIR4}/rules/${outputFilename}`,
         type: "text",
         content: ruleContent
       });
     }
-    for (const skill of state.skills) {
-      files.push({
-        path: `${outputDir}/skills/${skill.path}`,
-        type: "symlink",
-        target: `../../${UNIFIED_DIR}/skills/${skill.path}`
-      });
-    }
+    files.push(...createSkillSymlinks(state, OUTPUT_DIR4));
     const mcpServers = transformMcpToCursor(state.settings?.mcpServers);
     if (mcpServers) {
       files.push({
-        path: `${outputDir}/mcp.json`,
+        path: `${OUTPUT_DIR4}/mcp.json`,
         type: "json",
         content: { mcpServers }
       });
@@ -1042,7 +1055,7 @@ var cursorPlugin = {
     const cliContent = buildCliContent(state.settings?.permissions);
     if (cliContent) {
       files.push({
-        path: `${outputDir}/cli.json`,
+        path: `${OUTPUT_DIR4}/cli.json`,
         type: "json",
         content: cliContent
       });
@@ -1052,10 +1065,7 @@ var cursorPlugin = {
   validate(state) {
     const warnings = [];
     if (!state.agents) {
-      warnings.push({
-        path: ["AGENTS.md"],
-        message: "No AGENTS.md found - root AGENTS.md will not be created"
-      });
+      warnings.push(createNoAgentsMdWarning("root AGENTS.md"));
     }
     const permissionsResult = transformPermissionsToCursor(
       state.settings?.permissions
@@ -1066,19 +1076,12 @@ var cursorPlugin = {
         message: 'Cursor does not support "ask" permission level - these rules will be treated as "allow"'
       });
     }
-    const mcpServers = state.settings?.mcpServers;
-    if (mcpServers) {
-      for (const [name, server] of Object.entries(mcpServers)) {
-        const isRemote = server.type === "http" || server.type === "sse";
-        const hasCommand = !!server.command;
-        if (!isRemote && !hasCommand) {
-          warnings.push({
-            path: ["settings", "mcpServers", name],
-            message: `MCP server "${name}" has no command or type - it will be skipped`
-          });
-        }
-      }
-    }
+    warnings.push(
+      ...validateMcpServers(state.settings?.mcpServers, [
+        "settings",
+        "mcpServers"
+      ])
+    );
     return { valid: true, errors: [], warnings, skipped: [] };
   }
 };
@@ -1113,6 +1116,7 @@ function transformMcpToGemini(mcpServers) {
 }
 
 // src/plugins/gemini/index.ts
+var OUTPUT_DIR5 = TOOL_OUTPUT_DIRS.gemini;
 var geminiPlugin = {
   id: "gemini",
   name: "Gemini CLI",
@@ -1124,13 +1128,9 @@ var geminiPlugin = {
   },
   async export(state, rootDir) {
     const files = [];
-    const outputDir = TOOL_OUTPUT_DIRS.gemini;
-    if (state.agents) {
-      files.push({
-        path: `${outputDir}/GEMINI.md`,
-        type: "symlink",
-        target: `../${UNIFIED_DIR}/AGENTS.md`
-      });
+    const agentsSymlink = createRootAgentsMdSymlink(state);
+    if (agentsSymlink) {
+      files.push(agentsSymlink);
     }
     const rulesMap = groupRulesByDirectory(state.rules);
     for (const [dir, contents] of rulesMap.entries()) {
@@ -1142,19 +1142,21 @@ var geminiPlugin = {
         content: combinedContent
       });
     }
-    for (const skill of state.skills) {
-      files.push({
-        path: `${outputDir}/skills/${skill.path}`,
-        type: "symlink",
-        target: `../../${UNIFIED_DIR}/skills/${skill.path}`
-      });
-    }
+    files.push(...createSkillSymlinks(state, OUTPUT_DIR5));
     const mcpServers = transformMcpToGemini(state.settings?.mcpServers);
-    if (mcpServers) {
+    const hasAgents = !!state.agents;
+    if (mcpServers || hasAgents) {
+      const settingsContent = {};
+      if (hasAgents) {
+        settingsContent["context"] = { fileName: ["AGENTS.md"] };
+      }
+      if (mcpServers) {
+        settingsContent["mcpServers"] = mcpServers;
+      }
       files.push({
-        path: `${outputDir}/settings.json`,
+        path: `${OUTPUT_DIR5}/settings.json`,
         type: "json",
-        content: { mcpServers }
+        content: settingsContent
       });
     }
     return applyFileOverrides(files, rootDir, "gemini");
@@ -1163,19 +1165,13 @@ var geminiPlugin = {
     const warnings = [];
     const skipped = [];
     if (!state.agents) {
-      warnings.push({
-        path: ["AGENTS.md"],
-        message: "No AGENTS.md found - GEMINI.md will not be created"
-      });
+      warnings.push(createNoAgentsMdWarning("root AGENTS.md"));
     }
-    if (state.settings?.permissions) {
-      const hasPermissions = (state.settings.permissions.allow?.length ?? 0) > 0 || (state.settings.permissions.ask?.length ?? 0) > 0 || (state.settings.permissions.deny?.length ?? 0) > 0;
-      if (hasPermissions) {
-        skipped.push({
-          feature: "permissions",
-          reason: "Gemini CLI does not support declarative permissions - permissions must be granted interactively"
-        });
-      }
+    if (hasPermissionsConfigured(state.settings?.permissions)) {
+      skipped.push({
+        feature: "permissions",
+        reason: "Gemini CLI does not support declarative permissions - permissions must be granted interactively"
+      });
     }
     if (state.rules.length > 0) {
       warnings.push({
@@ -1260,6 +1256,8 @@ function parsePermissionRuleForOpenCode(rule) {
 }
 
 // src/plugins/opencode/index.ts
+var OUTPUT_DIR6 = TOOL_OUTPUT_DIRS.opencode;
+var SKILLS_DIR2 = ".agents";
 var opencodePlugin = {
   id: "opencode",
   name: "OpenCode",
@@ -1271,33 +1269,23 @@ var opencodePlugin = {
   },
   async export(state, rootDir) {
     const files = [];
-    const outputDir = TOOL_OUTPUT_DIRS.opencode;
-    if (state.agents) {
-      files.push({
-        path: "AGENTS.md",
-        type: "symlink",
-        target: `${UNIFIED_DIR}/AGENTS.md`
-      });
+    const agentsSymlink = createRootAgentsMdSymlink(state);
+    if (agentsSymlink) {
+      files.push(agentsSymlink);
     }
     if (state.rules.length > 0) {
       files.push({
-        path: `${outputDir}/rules`,
+        path: `${OUTPUT_DIR6}/rules`,
         type: "symlink",
         target: `../${UNIFIED_DIR}/rules`
       });
     }
-    for (const skill of state.skills) {
-      files.push({
-        path: `${outputDir}/skills/${skill.path}`,
-        type: "symlink",
-        target: `../../${UNIFIED_DIR}/skills/${skill.path}`
-      });
-    }
+    files.push(...createSkillSymlinks(state, SKILLS_DIR2));
     const config = {
       $schema: "https://opencode.ai/config.json"
     };
     if (state.rules.length > 0) {
-      config["instructions"] = [`${outputDir}/rules/*.md`];
+      config["instructions"] = [`${OUTPUT_DIR6}/rules/*.md`];
     }
     const mcp = transformMcpToOpenCode(state.settings?.mcpServers);
     if (mcp) {
@@ -1319,11 +1307,14 @@ var opencodePlugin = {
   validate(state) {
     const warnings = [];
     if (!state.agents) {
-      warnings.push({
-        path: ["AGENTS.md"],
-        message: "No AGENTS.md found - root AGENTS.md will not be created"
-      });
+      warnings.push(createNoAgentsMdWarning("root AGENTS.md"));
     }
+    warnings.push(
+      ...validateMcpServers(state.settings?.mcpServers, [
+        "settings",
+        "mcpServers"
+      ])
+    );
     return { valid: true, errors: [], warnings, skipped: [] };
   }
 };
@@ -1379,6 +1370,7 @@ function serializeWindsurfRule(frontmatter, content) {
 }
 
 // src/plugins/windsurf/index.ts
+var OUTPUT_DIR7 = TOOL_OUTPUT_DIRS.windsurf;
 var windsurfPlugin = {
   id: "windsurf",
   name: "Windsurf",
@@ -1390,13 +1382,9 @@ var windsurfPlugin = {
   },
   async export(state, rootDir) {
     const files = [];
-    const outputDir = TOOL_OUTPUT_DIRS.windsurf;
-    if (state.agents) {
-      files.push({
-        path: "AGENTS.md",
-        type: "symlink",
-        target: `${UNIFIED_DIR}/AGENTS.md`
-      });
+    const agentsSymlink = createRootAgentsMdSymlink(state);
+    if (agentsSymlink) {
+      files.push(agentsSymlink);
     }
     for (const rule of state.rules) {
       const transformed = transformRuleToWindsurf(rule);
@@ -1405,28 +1393,19 @@ var windsurfPlugin = {
         transformed.content
       );
       files.push({
-        path: `${outputDir}/rules/${rule.path}`,
+        path: `${OUTPUT_DIR7}/rules/${rule.path}`,
         type: "text",
         content: ruleContent
       });
     }
-    for (const skill of state.skills) {
-      files.push({
-        path: `${outputDir}/skills/${skill.path}`,
-        type: "symlink",
-        target: `../../${UNIFIED_DIR}/skills/${skill.path}`
-      });
-    }
+    files.push(...createSkillSymlinks(state, OUTPUT_DIR7));
     return applyFileOverrides(files, rootDir, "windsurf");
   },
   validate(state) {
     const warnings = [];
     const skipped = [];
     if (!state.agents) {
-      warnings.push({
-        path: ["AGENTS.md"],
-        message: "No AGENTS.md found - root AGENTS.md will not be created"
-      });
+      warnings.push(createNoAgentsMdWarning("root AGENTS.md"));
     }
     if (state.rules.length > 0) {
       warnings.push({
@@ -1440,14 +1419,11 @@ var windsurfPlugin = {
         reason: "Windsurf uses global MCP config at ~/.codeium/windsurf/mcp_config.json - project-level MCP servers are not exported"
       });
     }
-    if (state.settings?.permissions) {
-      const hasPermissions = (state.settings.permissions.allow?.length ?? 0) > 0 || (state.settings.permissions.ask?.length ?? 0) > 0 || (state.settings.permissions.deny?.length ?? 0) > 0;
-      if (hasPermissions) {
-        skipped.push({
-          feature: "permissions",
-          reason: "Windsurf does not support declarative permissions"
-        });
-      }
+    if (hasPermissionsConfigured(state.settings?.permissions)) {
+      skipped.push({
+        feature: "permissions",
+        reason: "Windsurf does not support declarative permissions"
+      });
     }
     return { valid: true, errors: [], warnings, skipped };
   }
@@ -1461,21 +1437,65 @@ pluginRegistry.register(codexPlugin);
 pluginRegistry.register(opencodePlugin);
 pluginRegistry.register(windsurfPlugin);
 pluginRegistry.register(geminiPlugin);
+function computeFilesToDelete(previousFiles, currentFiles) {
+  const currentPaths = new Set(currentFiles.map((f) => f.path));
+  return previousFiles.map((f) => f.path).filter((p) => !currentPaths.has(p));
+}
+async function deleteFiles(paths, rootDir, dryRun) {
+  const results = [];
+  for (const relativePath of paths) {
+    const fullPath = path.join(rootDir, relativePath);
+    try {
+      await fs4.lstat(fullPath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        continue;
+      }
+      throw error;
+    }
+    if (!dryRun) {
+      await fs4.unlink(fullPath);
+      await cleanupEmptyParentDirs(fullPath, rootDir);
+    }
+    results.push({
+      path: relativePath,
+      action: "delete"
+    });
+  }
+  return results;
+}
+async function cleanupEmptyParentDirs(filePath, rootDir) {
+  let dir = path.dirname(filePath);
+  const normalizedRoot = path.normalize(rootDir);
+  while (dir !== normalizedRoot && dir.startsWith(normalizedRoot + path.sep)) {
+    try {
+      const entries = await fs4.readdir(dir);
+      if (entries.length === 0) {
+        await fs4.rmdir(dir);
+        dir = path.dirname(dir);
+      } else {
+        break;
+      }
+    } catch {
+      break;
+    }
+  }
+}
 function computeHash(content) {
   return crypto.createHash("sha256").update(content, "utf-8").digest("hex");
 }
 async function readExistingFile(filePath) {
   try {
-    return await fs3.readFile(filePath, "utf-8");
+    return await fs4.readFile(filePath, "utf-8");
   } catch {
     return null;
   }
 }
 async function getSymlinkTarget(filePath) {
   try {
-    const stats = await fs3.lstat(filePath);
+    const stats = await fs4.lstat(filePath);
     if (stats.isSymbolicLink()) {
-      return await fs3.readlink(filePath);
+      return await fs4.readlink(filePath);
     }
     return null;
   } catch {
@@ -1483,15 +1503,15 @@ async function getSymlinkTarget(filePath) {
   }
 }
 async function ensureDir(dirPath) {
-  await fs3.mkdir(dirPath, { recursive: true });
+  await fs4.mkdir(dirPath, { recursive: true });
 }
 async function removeIfExists(filePath) {
   try {
-    const stats = await fs3.lstat(filePath);
+    const stats = await fs4.lstat(filePath);
     if (stats.isDirectory() && !stats.isSymbolicLink()) {
-      await fs3.rm(filePath, { recursive: true, force: true });
+      await fs4.rm(filePath, { recursive: true, force: true });
     } else {
-      await fs3.unlink(filePath);
+      await fs4.unlink(filePath);
     }
   } catch (error) {
     if (error.code !== "ENOENT") {
@@ -1503,6 +1523,12 @@ async function writeSingleFile(file, rootDir, dryRun) {
   const fullPath = path.join(rootDir, file.path);
   const dirPath = path.dirname(fullPath);
   if (file.type === "symlink") {
+    if (!file.target) {
+      throw new WriteError(
+        `Symlink file missing target: ${file.path}`,
+        file.path
+      );
+    }
     const target = file.target;
     const existingTarget = await getSymlinkTarget(fullPath);
     if (existingTarget === target) {
@@ -1514,7 +1540,7 @@ async function writeSingleFile(file, rootDir, dryRun) {
     if (!dryRun) {
       await ensureDir(dirPath);
       await removeIfExists(fullPath);
-      await fs3.symlink(target, fullPath);
+      await fs4.symlink(target, fullPath);
     }
     return {
       path: file.path,
@@ -1535,7 +1561,11 @@ async function writeSingleFile(file, rootDir, dryRun) {
   }
   if (!dryRun) {
     await ensureDir(dirPath);
-    await fs3.writeFile(fullPath, content, "utf-8");
+    const existingSymlink = await getSymlinkTarget(fullPath);
+    if (existingSymlink !== null) {
+      await removeIfExists(fullPath);
+    }
+    await fs4.writeFile(fullPath, content, "utf-8");
   }
   return {
     path: file.path,
@@ -1564,19 +1594,101 @@ async function writeFiles(files, options) {
 async function updateGitignore(rootDir, paths) {
   const gitignorePath = path.join(rootDir, ".gitignore");
   let content = "";
+  let hasExistingFile = true;
   try {
-    content = await fs3.readFile(gitignorePath, "utf-8");
+    content = await fs4.readFile(gitignorePath, "utf-8");
   } catch {
+    hasExistingFile = false;
   }
   const marker = "# lnai-generated";
   const endMarker = "# end lnai-generated";
   const markerRegex = new RegExp(`${marker}[\\s\\S]*?${endMarker}\\n?`, "g");
+  const hasManagedSection = new RegExp(`${marker}[\\s\\S]*?${endMarker}`).test(
+    content
+  );
   content = content.replace(markerRegex, "");
-  content = content.trimEnd();
-  const uniquePaths = [...new Set(paths)];
-  const newSection = ["", marker, ...uniquePaths, endMarker, ""].join("\n");
-  content = content + newSection;
-  await fs3.writeFile(gitignorePath, content, "utf-8");
+  const baseContent = content.trimEnd();
+  const uniquePaths = [...new Set(paths)].sort();
+  if (uniquePaths.length === 0) {
+    if (!hasManagedSection && !hasExistingFile) {
+      return;
+    }
+    const cleanedContent = baseContent.length > 0 ? `${baseContent}
+` : baseContent;
+    await fs4.writeFile(gitignorePath, cleanedContent, "utf-8");
+    return;
+  }
+  const managedSection = [marker, ...uniquePaths, endMarker].join("\n");
+  const nextContent = baseContent.length > 0 ? `${baseContent}
+
+${managedSection}
+` : `${managedSection}
+`;
+  await fs4.writeFile(gitignorePath, nextContent, "utf-8");
+}
+
+// src/manifest/index.ts
+var MANIFEST_FILENAME = ".lnai-manifest.json";
+async function readManifest(rootDir) {
+  const manifestPath = path.join(rootDir, UNIFIED_DIR, MANIFEST_FILENAME);
+  try {
+    const content = await fs4.readFile(manifestPath, "utf-8");
+    const manifest = JSON.parse(content);
+    if (manifest.version !== 1) {
+      console.warn(
+        `[lnai] Unknown manifest version ${manifest.version}, skipping cleanup`
+      );
+      return null;
+    }
+    return manifest;
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return null;
+    }
+    console.warn(`[lnai] Failed to read manifest: ${error.message}`);
+    return null;
+  }
+}
+async function writeManifest(rootDir, manifest) {
+  const manifestPath = path.join(rootDir, UNIFIED_DIR, MANIFEST_FILENAME);
+  const content = JSON.stringify(manifest, null, 2) + "\n";
+  await fs4.writeFile(manifestPath, content, "utf-8");
+}
+function buildToolManifest(toolId, files) {
+  const entries = files.map((file) => {
+    const entry = {
+      path: file.path,
+      type: file.type
+    };
+    if (file.type === "symlink") {
+      entry.target = file.target;
+    } else {
+      const content = file.type === "json" ? JSON.stringify(file.content, null, 2) + "\n" : String(file.content);
+      entry.hash = computeHash(content);
+    }
+    return entry;
+  });
+  return {
+    version: 1,
+    tool: toolId,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    files: entries
+  };
+}
+function updateToolManifest(manifest, toolId, files) {
+  return {
+    ...manifest,
+    tools: {
+      ...manifest.tools,
+      [toolId]: buildToolManifest(toolId, files)
+    }
+  };
+}
+function createEmptyManifest() {
+  return {
+    version: 1,
+    tools: {}
+  };
 }
 
 // src/pipeline/index.ts
@@ -1598,7 +1710,12 @@ function getToolsToSync(config, requestedTools) {
   return enabledTools;
 }
 async function runSyncPipeline(options) {
-  const { rootDir, dryRun = false, tools: requestedTools } = options;
+  const {
+    rootDir,
+    dryRun = false,
+    skipCleanup = false,
+    tools: requestedTools
+  } = options;
   if (requestedTools && requestedTools.length > 0) {
     const toolValidation = validateToolIds(requestedTools);
     if (!toolValidation.valid) {
@@ -1624,8 +1741,8 @@ async function runSyncPipeline(options) {
   if (toolsToSync.length === 0) {
     return [];
   }
+  let manifest = await readManifest(rootDir) ?? createEmptyManifest();
   const results = [];
-  const pathsToIgnore = [];
   for (const toolId of toolsToSync) {
     const plugin = pluginRegistry.get(toolId);
     if (!plugin) {
@@ -1633,18 +1750,30 @@ async function runSyncPipeline(options) {
     }
     const validation = plugin.validate(state);
     const outputFiles = await plugin.export(state, rootDir);
-    const changes = await writeFiles(outputFiles, { rootDir, dryRun });
+    let deleteChanges = [];
+    if (!skipCleanup && manifest.tools[toolId]) {
+      const toDelete = computeFilesToDelete(
+        manifest.tools[toolId].files,
+        outputFiles
+      );
+      deleteChanges = await deleteFiles(toDelete, rootDir, dryRun);
+    }
+    const writeChanges = await writeFiles(outputFiles, { rootDir, dryRun });
+    const changes = [...deleteChanges, ...writeChanges];
     results.push({
       tool: toolId,
       changes,
       validation
     });
-    const toolConfig = state.config.tools?.[toolId];
-    if (!toolConfig?.versionControl) {
-      pathsToIgnore.push(...outputFiles.map((f) => f.path));
+    if (!dryRun) {
+      manifest = updateToolManifest(manifest, toolId, outputFiles);
     }
   }
-  if (pathsToIgnore.length > 0 && !dryRun) {
+  if (!dryRun) {
+    await writeManifest(rootDir, manifest);
+    const pathsToIgnore = Object.entries(manifest.tools).flatMap(
+      ([toolId, toolManifest]) => !state.config.tools?.[toolId]?.versionControl && toolManifest?.files ? toolManifest.files.map((file) => file.path) : []
+    );
     await updateGitignore(rootDir, pathsToIgnore);
   }
   return results;
@@ -1669,12 +1798,12 @@ async function initUnifiedConfig(options) {
     );
   }
   if (exists) {
-    await fs3.rm(aiDir, { recursive: true, force: true });
+    await fs4.rm(aiDir, { recursive: true, force: true });
   }
-  await fs3.mkdir(aiDir, { recursive: true });
+  await fs4.mkdir(aiDir, { recursive: true });
   created.push(UNIFIED_DIR);
   const configPath = path.join(aiDir, CONFIG_FILES.config);
-  await fs3.writeFile(
+  await fs4.writeFile(
     configPath,
     JSON.stringify(config, null, 2) + "\n",
     "utf-8"
@@ -1683,10 +1812,10 @@ async function initUnifiedConfig(options) {
   if (!minimal) {
     for (const dir of [CONFIG_DIRS.rules, CONFIG_DIRS.skills]) {
       const dirPath = path.join(aiDir, dir);
-      await fs3.mkdir(dirPath, { recursive: true });
+      await fs4.mkdir(dirPath, { recursive: true });
       created.push(path.join(UNIFIED_DIR, dir));
       const gitkeepPath = path.join(dirPath, ".gitkeep");
-      await fs3.writeFile(gitkeepPath, "", "utf-8");
+      await fs4.writeFile(gitkeepPath, "", "utf-8");
       created.push(path.join(UNIFIED_DIR, dir, ".gitkeep"));
     }
   }
@@ -1695,7 +1824,7 @@ async function initUnifiedConfig(options) {
 async function hasUnifiedConfig(rootDir) {
   const aiDir = path.join(rootDir, UNIFIED_DIR);
   try {
-    const stats = await fs3.stat(aiDir);
+    const stats = await fs4.stat(aiDir);
     return stats.isDirectory();
   } catch {
     return false;
@@ -1724,4 +1853,4 @@ function generateDefaultConfig(tools, versionControl) {
   return { tools: toolsConfig };
 }
 
-export { CONFIG_DIRS, CONFIG_FILES, FileNotFoundError, LnaiError, ParseError, PluginError, TOOL_IDS, TOOL_OUTPUT_DIRS, UNIFIED_DIR, ValidationError, WriteError, claudeCodePlugin, codexPlugin, computeHash, configSchema, generateDefaultConfig, hasUnifiedConfig, initUnifiedConfig, mcpServerSchema, opencodePlugin, parseFrontmatter, parseUnifiedConfig, permissionsSchema, pluginRegistry, ruleFrontmatterSchema, runSyncPipeline, settingsSchema, skillFrontmatterSchema, toolConfigSchema, toolIdSchema, updateGitignore, validateConfig, validateSettings, validateUnifiedState, writeFiles };
+export { CONFIG_DIRS, CONFIG_FILES, FileNotFoundError, InvalidToolError, LnaiError, MANIFEST_FILENAME, ParseError, PluginError, TOOL_IDS, TOOL_OUTPUT_DIRS, UNIFIED_DIR, ValidationError, WriteError, buildToolManifest, claudeCodePlugin, cleanupEmptyParentDirs, codexPlugin, computeFilesToDelete, computeHash, configSchema, createEmptyManifest, deleteFiles, generateDefaultConfig, hasUnifiedConfig, initUnifiedConfig, mcpServerSchema, opencodePlugin, parseFrontmatter, parseUnifiedConfig, permissionsSchema, pluginRegistry, readManifest, ruleFrontmatterSchema, runSyncPipeline, settingsSchema, skillFrontmatterSchema, toolConfigSchema, toolIdSchema, updateGitignore, updateToolManifest, validateConfig, validateSettings, validateUnifiedState, writeFiles, writeManifest };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lnai/core",
-  "version": "0.6.0",
+  "version": "0.6.6",
   "description": "Core library for LNAI - unified AI config management",
   "type": "module",
   "license": "MIT",