@kood/claude-code 0.7.9 → 0.7.10

package/dist/index.js

@@ -23,7 +23,7 @@ var banner = () => {
 
 // src/commands/init.ts
 import fs9 from "fs-extra";
-import os from "os";
+import os2 from "os";
 import path11 from "path";
 
 // src/features/templates/template-path-resolver.ts
@@ -690,7 +690,7 @@ async function promptScopeSelection(options) {
   return { scope: response.value };
 }
 async function promptCodexSync(options) {
-  const { providedSyncCodex, codexSkillsPath } = options;
+  const { providedSyncCodex, codexPath } = options;
   if (providedSyncCodex !== void 0) {
     return { syncCodex: providedSyncCodex };
   }
@@ -698,7 +698,7 @@ async function promptCodexSync(options) {
     return { syncCodex: false };
   }
   logger.blank();
-  const pathHint = codexSkillsPath ? ` (${codexSkillsPath})` : "";
+  const pathHint = codexPath ? ` (${codexPath})` : "";
   const result = await promptConfirm(
     `Also sync with Codex now?${pathHint}`,
     false
@@ -786,8 +786,15 @@ async function updateGitignore(targetDir, options = {}) {
 
 // src/features/codex-sync/codex-sync.ts
 import fs8 from "fs-extra";
+import os from "os";
 import path10 from "path";
 var RESERVED_CODEX_SKILL_DIRS = /* @__PURE__ */ new Set([".system", "claude-commands"]);
+var COMMAND_INSTRUCTION_PREFIX_REGEX = /^@\.\.\/instructions\//gm;
+var COMMAND_INSTRUCTION_PREFIX_REPLACEMENT = "@../../../instructions/";
+var MAX_REFERENCE_ISSUE_SAMPLES = 10;
+var CLAUDE_STATE_FILE = ".claude.json";
+var CLAUDE_LOCAL_MCP_FILE = ".mcp.json";
+var CODEX_CONFIG_FILE = "config.toml";
 function normalizeLineEndings(content) {
   return content.replace(/\r\n/g, "\n");
 }
@@ -816,6 +823,10 @@ function extractDescriptionFromFrontmatter(markdown) {
 function buildCommandSkillContent(commandPath, commandRaw) {
   const commandName = path10.basename(commandPath, ".md");
   const normalizedCommand = normalizeLineEndings(commandRaw).trim();
+  const rewrittenCommand = normalizedCommand.replace(
+    COMMAND_INSTRUCTION_PREFIX_REGEX,
+    COMMAND_INSTRUCTION_PREFIX_REPLACEMENT
+  );
   const sourcePath = path10.resolve(commandPath);
   const description = extractDescriptionFromFrontmatter(normalizedCommand) || `${commandName} command imported from .claude/commands`;
   return `---
@@ -830,18 +841,344 @@ resolve them from the current workspace first; if missing, ask for the intended
 
 ---
 
-${normalizedCommand}
+${rewrittenCommand}
 `;
 }
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function asStringArray(value) {
+  if (!Array.isArray(value)) {
+    return void 0;
+  }
+  const items = value.filter(
+    (item) => typeof item === "string"
+  );
+  return items.length > 0 ? items : void 0;
+}
+function asStringRecord(value) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const entries = Object.entries(value).filter(
+    (entry) => typeof entry[1] === "string"
+  );
+  if (entries.length === 0) {
+    return void 0;
+  }
+  return Object.fromEntries(entries);
+}
+function normalizeClaudeMcpServer(value) {
+  if (!isRecord(value)) {
+    return void 0;
+  }
+  const type = typeof value.type === "string" ? value.type : void 0;
+  const command = typeof value.command === "string" ? value.command : void 0;
+  const args = asStringArray(value.args);
+  const env = asStringRecord(value.env);
+  const cwd = typeof value.cwd === "string" ? value.cwd : void 0;
+  const url = typeof value.url === "string" ? value.url : void 0;
+  const headers = asStringRecord(value.headers);
+  const bearerTokenEnvVar = typeof value.bearerTokenEnvVar === "string" ? value.bearerTokenEnvVar : typeof value.bearer_token_env_var === "string" ? value.bearer_token_env_var : void 0;
+  const envHttpHeaders = asStringRecord(value.envHttpHeaders) || asStringRecord(value.env_http_headers);
+  return {
+    type,
+    command,
+    args,
+    env,
+    cwd,
+    url,
+    headers,
+    bearerTokenEnvVar,
+    envHttpHeaders
+  };
+}
+function normalizeClaudeMcpServers(value) {
+  if (!isRecord(value)) {
+    return {};
+  }
+  const normalizedEntries = Object.entries(value).map(([name, server]) => [name, normalizeClaudeMcpServer(server)]).filter((entry) => Boolean(entry[1]));
+  return Object.fromEntries(normalizedEntries);
+}
+function getProjectState(claudeState, targetDir) {
+  const projects = claudeState.projects;
+  if (!isRecord(projects)) {
+    return void 0;
+  }
+  const normalizedTarget = path10.resolve(targetDir);
+  for (const [projectPath, projectState] of Object.entries(projects)) {
+    if (path10.resolve(projectPath) !== normalizedTarget) {
+      continue;
+    }
+    if (isRecord(projectState)) {
+      return projectState;
+    }
+  }
+  return void 0;
+}
+function filterMcpJsonServersByProjectState(servers, projectState) {
+  if (!projectState) {
+    return servers;
+  }
+  const enabled = asStringArray(projectState.enabledMcpjsonServers) || [];
+  const disabled = new Set(
+    asStringArray(projectState.disabledMcpjsonServers) || []
+  );
+  const enabledSet = new Set(enabled);
+  const hasEnabledFilter = enabledSet.size > 0;
+  const filteredEntries = Object.entries(servers).filter(([name]) => {
+    if (hasEnabledFilter && !enabledSet.has(name)) {
+      return false;
+    }
+    if (disabled.has(name)) {
+      return false;
+    }
+    return true;
+  });
+  return Object.fromEntries(filteredEntries);
+}
+async function readJsonFile(filePath) {
+  if (!await fs8.pathExists(filePath)) {
+    return void 0;
+  }
+  try {
+    const raw = await fs8.readFile(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (!isRecord(parsed)) {
+      return void 0;
+    }
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+function toCodexMcpServer(server) {
+  const serverType = server.type?.toLowerCase();
+  const isHttp = serverType === "http" || Boolean(server.url);
+  if (isHttp) {
+    if (!server.url) {
+      return void 0;
+    }
+    return {
+      kind: "http",
+      url: server.url,
+      bearerTokenEnvVar: server.bearerTokenEnvVar,
+      httpHeaders: server.headers,
+      envHttpHeaders: server.envHttpHeaders
+    };
+  }
+  if (!server.command) {
+    return void 0;
+  }
+  return {
+    kind: "stdio",
+    command: server.command,
+    args: server.args,
+    env: server.env,
+    cwd: server.cwd
+  };
+}
+function tomlQuote(value) {
+  return `"${value.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+}
+function tomlKey(value) {
+  return /^[A-Za-z0-9_-]+$/.test(value) ? value : tomlQuote(value);
+}
+function parseTomlPath(input) {
+  const pathInput = input.trim();
+  if (!pathInput) {
+    return void 0;
+  }
+  const segments = [];
+  let current = "";
+  let inQuotes = false;
+  let escaped = false;
+  for (const char of pathInput) {
+    if (inQuotes) {
+      if (escaped) {
+        current += char;
+        escaped = false;
+        continue;
+      }
+      if (char === "\\") {
+        escaped = true;
+        continue;
+      }
+      if (char === '"') {
+        inQuotes = false;
+        continue;
+      }
+      current += char;
+      continue;
+    }
+    if (char === '"') {
+      inQuotes = true;
+      continue;
+    }
+    if (char === ".") {
+      const value = current.trim();
+      if (!value) {
+        return void 0;
+      }
+      segments.push(value);
+      current = "";
+      continue;
+    }
+    current += char;
+  }
+  if (inQuotes || escaped) {
+    return void 0;
+  }
+  const tail = current.trim();
+  if (!tail) {
+    return void 0;
+  }
+  segments.push(tail);
+  return segments;
+}
+function stripCodexMcpSections(configToml) {
+  const lines = normalizeLineEndings(configToml).split("\n");
+  const kept = [];
+  let droppingMcpSection = false;
+  for (const line of lines) {
+    const headerMatch = line.match(/^\s*\[([^\]]+)\]\s*$/);
+    if (headerMatch) {
+      const headerPath = parseTomlPath(headerMatch[1]);
+      droppingMcpSection = Boolean(
+        headerPath && headerPath.length > 0 && headerPath[0] === "mcp_servers"
+      );
+    }
+    if (!droppingMcpSection) {
+      kept.push(line);
+    }
+  }
+  return kept.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd();
+}
+function renderTomlStringArray(values) {
+  if (!values || values.length === 0) {
+    return void 0;
+  }
+  return `[${values.map((value) => tomlQuote(value)).join(", ")}]`;
+}
+function renderTomlStringTable(header, values) {
+  if (!values || Object.keys(values).length === 0) {
+    return void 0;
+  }
+  const lines = Object.entries(values).sort((a, b) => a[0].localeCompare(b[0])).map(([key, value]) => `${tomlKey(key)} = ${tomlQuote(value)}`);
+  return `${header}
+${lines.join("\n")}`;
+}
+function renderCodexMcpServer(name, server) {
+  const sectionRoot = `[mcp_servers.${tomlKey(name)}]`;
+  const lines = [sectionRoot];
+  if (server.kind === "http") {
+    lines.push(`url = ${tomlQuote(server.url ?? "")}`);
+    if (server.bearerTokenEnvVar) {
+      lines.push(
+        `bearer_token_env_var = ${tomlQuote(server.bearerTokenEnvVar)}`
+      );
+    }
+  } else {
+    lines.push(`command = ${tomlQuote(server.command ?? "")}`);
+    const args = renderTomlStringArray(server.args);
+    if (args) {
+      lines.push(`args = ${args}`);
+    }
+    if (server.cwd) {
+      lines.push(`cwd = ${tomlQuote(server.cwd)}`);
+    }
+  }
+  const envSection = server.kind === "stdio" ? renderTomlStringTable(`[mcp_servers.${tomlKey(name)}.env]`, server.env) : void 0;
+  const httpHeadersSection = server.kind === "http" ? renderTomlStringTable(
+    `[mcp_servers.${tomlKey(name)}.http_headers]`,
+    server.httpHeaders
+  ) : void 0;
+  const envHttpHeadersSection = server.kind === "http" ? renderTomlStringTable(
+    `[mcp_servers.${tomlKey(name)}.env_http_headers]`,
+    server.envHttpHeaders
+  ) : void 0;
+  const sections = [
+    lines.join("\n"),
+    envSection,
+    httpHeadersSection,
+    envHttpHeadersSection
+  ].filter((section) => Boolean(section));
+  return sections.join("\n\n");
+}
+function mergeCodexConfigToml(existingToml, renderedMcpBlocks) {
+  const base = stripCodexMcpSections(existingToml);
+  const mcp = renderedMcpBlocks.trim();
+  if (!base) {
+    return mcp;
+  }
+  if (!mcp) {
+    return base;
+  }
+  return `${base}
+
+${mcp}`;
+}
+async function loadClaudeMcpServers(targetDir) {
+  const homeDir = path10.resolve(os.homedir());
+  const normalizedTarget = path10.resolve(targetDir);
+  const isUserScope = normalizedTarget === homeDir;
+  const claudeStatePath = path10.join(homeDir, CLAUDE_STATE_FILE);
+  const claudeState = await readJsonFile(claudeStatePath);
+  if (isUserScope) {
+    return {
+      scope: "global",
+      servers: normalizeClaudeMcpServers(claudeState?.mcpServers)
+    };
+  }
+  const projectState = claudeState ? getProjectState(claudeState, normalizedTarget) : void 0;
+  const projectServers = normalizeClaudeMcpServers(projectState?.mcpServers);
+  const localMcpPath = path10.join(normalizedTarget, CLAUDE_LOCAL_MCP_FILE);
+  const localMcpState = await readJsonFile(localMcpPath);
+  const localMcpServers = filterMcpJsonServersByProjectState(
+    normalizeClaudeMcpServers(localMcpState?.mcpServers),
+    projectState
+  );
+  return {
+    scope: "local",
+    servers: {
+      ...localMcpServers,
+      ...projectServers
+    }
+  };
+}
+async function syncMcpServers(targetDir) {
+  const homeDir = path10.resolve(os.homedir());
+  const normalizedTarget = path10.resolve(targetDir);
+  const isUserScope = normalizedTarget === homeDir;
+  const codexBaseDir = isUserScope ? path10.join(homeDir, ".codex") : path10.join(normalizedTarget, ".codex");
+  const codexMcpConfigPath = path10.join(codexBaseDir, CODEX_CONFIG_FILE);
+  const { scope, servers } = await loadClaudeMcpServers(normalizedTarget);
+  const codexServers = Object.entries(servers).map(([name, server]) => [name, toCodexMcpServer(server)]).filter((entry) => Boolean(entry[1])).sort((a, b) => a[0].localeCompare(b[0]));
+  const renderedMcpBlocks = codexServers.map(([name, server]) => renderCodexMcpServer(name, server)).join("\n\n");
+  const existingConfig = await fs8.pathExists(codexMcpConfigPath) ? await fs8.readFile(codexMcpConfigPath, "utf8") : "";
+  const nextConfig = mergeCodexConfigToml(existingConfig, renderedMcpBlocks);
+  await fs8.ensureDir(codexBaseDir);
+  await fs8.writeFile(codexMcpConfigPath, `${nextConfig.trimEnd()}
+`);
+  return {
+    codexMcpConfigPath,
+    syncedMcpServers: codexServers.length,
+    scope
+  };
+}
 async function syncSkills(claudeSkillsDir, codexSkillsDir) {
   await fs8.ensureDir(codexSkillsDir);
   let sourceSkillNames = [];
   if (await fs8.pathExists(claudeSkillsDir)) {
-    const sourceEntries = await fs8.readdir(claudeSkillsDir, { withFileTypes: true });
+    const sourceEntries = await fs8.readdir(claudeSkillsDir, {
+      withFileTypes: true
+    });
     sourceSkillNames = sourceEntries.filter((entry) => entry.isDirectory()).map((entry) => entry.name).filter((name) => name !== ".system");
   }
   const sourceSkillSet = new Set(sourceSkillNames);
-  const codexEntries = await fs8.readdir(codexSkillsDir, { withFileTypes: true });
+  const codexEntries = await fs8.readdir(codexSkillsDir, {
+    withFileTypes: true
+  });
   for (const entry of codexEntries) {
     if (!entry.isDirectory()) {
       continue;
@@ -883,26 +1220,126 @@ async function syncCommands(claudeCommandsDir, codexCommandsDir) {
     const skillDir = path10.join(codexCommandsDir, commandName);
     const skillPath = path10.join(skillDir, "SKILL.md");
     await fs8.ensureDir(skillDir);
-    await fs8.writeFile(skillPath, buildCommandSkillContent(commandPath, commandRaw));
+    await fs8.writeFile(
+      skillPath,
+      buildCommandSkillContent(commandPath, commandRaw)
+    );
   }
   return commandFiles.length;
 }
+async function syncInstructions(claudeInstructionsDir, codexInstructionsDir) {
+  if (!await fs8.pathExists(claudeInstructionsDir)) {
+    await fs8.remove(codexInstructionsDir);
+    return 0;
+  }
+  await fs8.remove(codexInstructionsDir);
+  await fs8.ensureDir(codexInstructionsDir);
+  const counter = { files: 0, directories: 0 };
+  await copyRecursive(claudeInstructionsDir, codexInstructionsDir, counter);
+  return counter.files;
+}
+function extractReferenceCandidate(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("@")) {
+    return void 0;
+  }
+  const [candidate] = trimmed.slice(1).split(/\s+/);
+  if (!candidate || candidate.startsWith("#") || candidate.includes("://")) {
+    return void 0;
+  }
+  const looksLikePath = candidate.startsWith("./") || candidate.startsWith("../") || candidate.startsWith("/") || candidate.includes("/") || /\.[a-z0-9]+$/i.test(candidate);
+  if (!looksLikePath) {
+    return void 0;
+  }
+  return candidate;
+}
+async function collectSkillMarkdownFiles(rootDir, collector = []) {
+  if (!await fs8.pathExists(rootDir)) {
+    return collector;
+  }
+  const entries = await fs8.readdir(rootDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path10.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      await collectSkillMarkdownFiles(fullPath, collector);
+      continue;
+    }
+    if (entry.isFile() && entry.name === "SKILL.md") {
+      collector.push(fullPath);
+    }
+  }
+  return collector;
+}
+async function validateSkillReferences(codexSkillsDir) {
+  const skillFiles = await collectSkillMarkdownFiles(codexSkillsDir);
+  let count = 0;
+  const samples = [];
+  for (const skillFile of skillFiles) {
+    const content = await fs8.readFile(skillFile, "utf8");
+    const lines = normalizeLineEndings(content).split("\n");
+    for (const line of lines) {
+      const candidate = extractReferenceCandidate(line);
+      if (!candidate) {
+        continue;
+      }
+      const referencePath = candidate.split(/[?#]/, 1)[0];
+      if (!referencePath) {
+        continue;
+      }
+      const resolvedPath = path10.resolve(path10.dirname(skillFile), referencePath);
+      if (await fs8.pathExists(resolvedPath)) {
+        continue;
+      }
+      count += 1;
+      if (samples.length < MAX_REFERENCE_ISSUE_SAMPLES) {
+        samples.push({
+          skillPath: skillFile,
+          reference: candidate,
+          resolvedPath
+        });
+      }
+    }
+  }
+  return { count, samples };
+}
 async function syncWithCodex(targetDir) {
   const codexHome = path10.resolve(targetDir, ".codex");
   const codexSkillsDir = path10.join(codexHome, "skills");
   const codexCommandsDir = path10.join(codexSkillsDir, "claude-commands");
+  const codexInstructionsDir = path10.join(codexHome, "instructions");
   await fs8.ensureDir(codexSkillsDir);
   const claudeRootDir = path10.join(targetDir, ".claude");
   const claudeSkillsDir = path10.join(claudeRootDir, "skills");
   const claudeCommandsDir = path10.join(claudeRootDir, "commands");
+  const claudeInstructionsDir = path10.join(claudeRootDir, "instructions");
   const syncedSkills = await syncSkills(claudeSkillsDir, codexSkillsDir);
-  const syncedCommands = await syncCommands(claudeCommandsDir, codexCommandsDir);
+  const syncedInstructions = await syncInstructions(
+    claudeInstructionsDir,
+    codexInstructionsDir
+  );
+  const syncedCommands = await syncCommands(
+    claudeCommandsDir,
+    codexCommandsDir
+  );
+  const {
+    codexMcpConfigPath,
+    syncedMcpServers,
+    scope: mcpScope
+  } = await syncMcpServers(targetDir);
+  const { count: referenceIssueCount, samples: referenceIssueSamples } = await validateSkillReferences(codexSkillsDir);
   return {
     codexHome,
     codexSkillsDir,
     codexCommandsDir,
+    codexInstructionsDir,
     syncedSkills,
-    syncedCommands
+    syncedCommands,
+    syncedInstructions,
+    codexMcpConfigPath,
+    syncedMcpServers,
+    mcpScope,
+    referenceIssueCount,
+    referenceIssueSamples
   };
 }
 
@@ -1056,7 +1493,7 @@ var init = async (options) => {
   const { scope } = await promptScopeSelection({
     providedScope: options.scope
   });
-  const targetDir = scope === "user" ? os.homedir() : projectDir;
+  const targetDir = scope === "user" ? os2.homedir() : projectDir;
   const isUserScope = scope === "user";
   if (isUserScope) {
     logger.blank();
@@ -1102,14 +1539,14 @@ var init = async (options) => {
     hasScripts,
     scope
   );
-  const codexSkillsPath = path11.join(targetDir, ".codex", "skills");
+  const codexSyncPath = path11.join(targetDir, ".codex");
   const { syncCodex } = await promptCodexSync({
     providedSyncCodex: options.syncCodex,
-    codexSkillsPath
+    codexPath: codexSyncPath
   });
   if (syncCodex) {
     logger.blank();
-    logger.info("Syncing .claude skills/commands to Codex...");
+    logger.info("Syncing .claude skills/commands/instructions/MCP to Codex...");
     try {
       const result = await syncWithCodex(targetDir);
       if (result.syncedSkills > 0) {
@@ -1118,12 +1555,33 @@ var init = async (options) => {
       if (result.syncedCommands > 0) {
         logger.step(`Commands synced: ${result.syncedCommands}`);
       }
-      if (result.syncedSkills === 0 && result.syncedCommands === 0) {
+      if (result.syncedInstructions > 0) {
+        logger.step(`Instructions synced: ${result.syncedInstructions}`);
+      }
+      if (result.syncedMcpServers > 0) {
+        logger.step(
+          `MCP servers synced (${result.mcpScope}): ${result.syncedMcpServers}`
+        );
+      }
+      if (result.syncedSkills === 0 && result.syncedCommands === 0 && result.syncedInstructions === 0 && result.syncedMcpServers === 0) {
         logger.warn(
-          "Nothing was synced. .claude/skills and .claude/commands were not found."
+          "Nothing was synced. .claude/skills, .claude/commands, .claude/instructions, and Claude MCP settings were not found."
         );
       } else {
         logger.success(`Codex sync complete: ${result.codexSkillsDir}`);
+        logger.step(`Codex MCP config: ${result.codexMcpConfigPath}`);
+        if (result.referenceIssueCount > 0) {
+          logger.warn(
+            `Codex skill reference issues found: ${result.referenceIssueCount} (showing up to ${result.referenceIssueSamples.length})`
+          );
+          for (const issue of result.referenceIssueSamples) {
+            const skillPath = path11.relative(targetDir, issue.skillPath);
+            const resolvedPath = path11.relative(targetDir, issue.resolvedPath);
+            logger.step(
+              `${skillPath} -> @${issue.reference} (missing: ${resolvedPath})`
+            );
+          }
+        }
       }
     } catch (error) {
       logger.warn(
@@ -1144,13 +1602,13 @@ var init = async (options) => {
 
 // src/index.ts
 var program = new Command();
-program.name("claude-code").description("Claude Code documentation installer for projects").version("0.7.9");
+program.name("claude-code").description("Claude Code documentation installer for projects").version("0.7.10");
 program.option(
   "-t, --template <names>",
   "template names (comma-separated: tanstack-start,hono)"
 ).option("-f, --force", "overwrite existing files without prompting").option("--cwd <path>", "target directory (default: current directory)").option("--list", "list available templates").option("-s, --skills", "install skills to .claude/skills/").option("-c, --commands", "install commands to .claude/commands/").option("-a, --agents", "install agents to .claude/agents/").option(
   "--sync-codex",
-  "sync installed .claude skills/commands to selected-scope .codex/skills/"
+  "sync installed .claude skills/commands/instructions and Claude MCP settings to selected-scope .codex/"
 ).option("--scope <scope>", "installation scope (project|user)").action(async (options) => {
   banner();
   if (options.list) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kood/claude-code",
-  "version": "0.7.9",
+  "version": "0.7.10",
   "description": "Claude Code documentation installer for projects",
   "type": "module",
   "bin": "./dist/index.js",