@khanhcan148/mk 0.1.21 → 0.1.24

package/README.md

@@ -35,8 +35,10 @@ mk init --dry-run
 mk init              Install kit files to current project (./.claude/)
 mk init --global     Install kit globally (~/.claude/)
 mk init --dry-run    Preview what would be installed
-mk update            Update kit files (preserves your edits by default)
+mk update            Update kit files (preserves your edits by default); auto-syncs .codex/ mirror when present
 mk update --force    Update and overwrite user-modified files
+mk codex             Mirror .claude/ to .codex/ for OpenAI Codex CLI (see docs/codex/COMMAND.md)
+mk codex --cwd DIR   Convert a project at a different path
 mk remove            Remove all kit files tracked by manifest
 mk --version         Show installed CLI version
 mk --help            Show help
@@ -89,7 +91,7 @@ cp -r .claude ~/.claude/
 ```
 ├── .claude/
 │   ├── agents/      # 36 agents (5 primary + 31 utility: implementers, quality, docs, specialized, concerns, brainstorm critics)
-│   ├── skills/      # 67 skill packages (SKILL.md + scripts/references/assets)
+│   ├── skills/      # 65 skill packages (SKILL.md + scripts/references/assets)
 │   │   ├── mk-*/    # 20 workflow commands (/mk-audit, /mk-brainstorm, /mk-log-analysis, /mk-overview, /mk-wiki, etc.)
 │   │   └── ...      # Domain skills (frontend, backend, testing, browser automation, etc.)
 │   └── workflows/   # Development protocols
@@ -228,6 +230,8 @@ python .claude/skills/skill-creator/scripts/package_skill.py <path/to/skill-fold
 |----------|-------------|
 | [Skill Index](docs/skill-index.md) | Categorized list of all skills and workflows |
 | [mk-* Workflows & Agents](docs/mk-workflow-agents.md) | How each /mk-* command works and which agents it uses |
+| [`mk codex` Command Guide](docs/codex/COMMAND.md) | Convert .claude/ to .codex/ for OpenAI Codex CLI; auto-sync on mk update |
+| [Codex Migration Guide](docs/codex/MIGRATION.md) | What ports, what's dropped, what gaps remain |
 | [Project Overview & PDR](docs/project-overview-pdr.md) | Requirements, constraints, success metrics |
 | [Project Roadmap](docs/project-roadmap.md) | Phases, milestones, and risk register |
 | [Changelog](docs/changelog.md) | Version history and release notes |
@@ -259,4 +263,6 @@ This kit is designed to work on Windows, macOS, and Linux:
 - **Scripts**: All executable scripts use Python or Node.js (no bash/shell scripts)
 - **Claude Code Bash tool**: Provides a Unix-like shell on all platforms, including Windows — git commands and other Bash tool invocations work everywhere
 - **External tool installs**: Reference files include install instructions for macOS (`brew`), Ubuntu/Debian (`apt-get`), and Windows (`winget`/`choco`) where applicable
-**Supported runtime**: Claude Code CLI. All skills, agents, and workflows are designed for the Claude Code runtime.
+**Supported runtimes**:
+- **Claude Code CLI** (primary): all skills, agents, and workflows are authored for this runtime.
+- **OpenAI Codex CLI** (via `mk codex`): the `.claude/` tree is converted to a `.codex/` mirror — agents become TOML, skills/workflows/hooks are mirrored with kit-paths rewritten, and a `config.toml` is emitted with hook registrations. See [`mk codex` Command Guide](docs/codex/COMMAND.md). After conversion, `mk update` auto-syncs the `.codex/` mirror so it stays coherent.

package/bin/mk.js

@@ -7,6 +7,7 @@ import { initAction } from '../src/commands/init.js';
 import { updateAction } from '../src/commands/update.js';
 import { removeAction } from '../src/commands/remove.js';
 import { loginAction, logoutAction, statusAction } from '../src/commands/auth.js';
+import { codexAction } from '../src/commands/codex.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8'));
@@ -33,6 +34,13 @@ program.command('remove')
   .option('--global', 'Remove global installation from ~/.claude/')
   .action((options) => removeAction(options));
 
+program.command('codex')
+  .description('Mirror .claude/ to .codex/ for OpenAI Codex CLI (agents converted to TOML; skills + workflows copied)')
+  .option('--cwd <dir>', 'Project directory (default: current working directory)')
+  .option('--output <dir>', 'Output directory (default: <cwd>/.codex/agents)')
+  .option('--model-map <toml>', 'Path to a TOML file with [model_map] overrides')
+  .action((options) => codexAction(options));
+
 // Auth command group
 const auth = program.command('auth')
   .description('Manage GitHub authentication for kit downloads');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhcan148/mk",
-  "version": "0.1.21",
+  "version": "0.1.24",
   "description": "CLI to install and manage MyClaudeKit (.claude/) in your projects",
   "type": "module",
   "bin": {
@@ -8,22 +8,28 @@
   },
   "files": [
     "bin/",
-    "src/"
+    "src/",
+    "scripts/"
   ],
   "engines": {
     "node": ">=18.0.0"
   },
   "scripts": {
-    "test": "node --test test/lib/*.test.js test/commands/*.test.js test/integration/*.test.js test/characterization/*.characterization.test.js .claude/hooks/tests/*.test.cjs",
+    "test": "node --test test/lib/*.test.js test/commands/*.test.js test/scripts/*.test.js test/integration/*.test.js test/characterization/*.characterization.test.js .claude/hooks/tests/*.test.cjs",
     "lint": "node --check src/**/*.js bin/**/*.js 2>/dev/null",
-    "selftest": "python3 .claude/skills/mk-selftest/scripts/validate_kit.py"
+    "selftest": "python3 .claude/skills/mk-selftest/scripts/validate_kit.py",
+    "codex:convert": "node bin/mk.js codex",
+    "codex:convert-and-diff": "node scripts/codex-diff-check.js"
   },
   "dependencies": {
+    "@iarna/toml": "3.0.0",
     "chalk": "^5.0.0",
     "commander": "^12.0.0",
     "fs-extra": "^11.0.0",
+    "js-yaml": "4.1.0",
     "semver": "^7.0.0"
   },
+  "devDependencies": {},
   "keywords": [
     "claude",
     "claude-code",

package/scripts/codex-diff-check.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+/**
+ * codex-diff-check.js
+ *
+ * Runs `mk codex` twice with separate output dirs and asserts byte-identical
+ * config.toml output. Exits 0 on match, 1 on mismatch.
+ *
+ * Used by `npm run codex:convert-and-diff` in CI to enforce the determinism
+ * contract (HC #4) without depending on platform-specific `diff` command.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync, existsSync, mkdirSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { tmpdir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..');
+const MK_BIN = join(PACKAGE_ROOT, 'bin', 'mk.js');
+
+function runMkCodex(agentsOut) {
+  const result = spawnSync(process.execPath, [MK_BIN, 'codex', '--output', agentsOut], {
+    stdio: 'inherit',
+    timeout: 60_000,
+  });
+  return result.status ?? 1;
+}
+
+const run1 = mkdtempSync(join(tmpdir(), 'mk-codex-diff1-'));
+const run2 = mkdtempSync(join(tmpdir(), 'mk-codex-diff2-'));
+
+try {
+  const status1 = runMkCodex(join(run1, 'agents'));
+  if (status1 !== 0) {
+    process.stderr.write(`[codex-diff-check] Run 1 failed with exit ${status1}\n`);
+    process.exit(1);
+  }
+
+  const status2 = runMkCodex(join(run2, 'agents'));
+  if (status2 !== 0) {
+    process.stderr.write(`[codex-diff-check] Run 2 failed with exit ${status2}\n`);
+    process.exit(1);
+  }
+
+  const toml1Path = join(run1, 'config.toml');
+  const toml2Path = join(run2, 'config.toml');
+
+  if (!existsSync(toml1Path) || !existsSync(toml2Path)) {
+    process.stderr.write('[codex-diff-check] config.toml missing from one or both runs\n');
+    process.exit(1);
+  }
+
+  const toml1 = readFileSync(toml1Path);
+  const toml2 = readFileSync(toml2Path);
+
+  if (!toml1.equals(toml2)) {
+    process.stderr.write('[codex-diff-check] FAIL: config.toml is NOT byte-identical across two runs\n');
+    process.stderr.write(`  Run 1 (${toml1.length} bytes):\n${toml1.toString()}\n`);
+    process.stderr.write(`  Run 2 (${toml2.length} bytes):\n${toml2.toString()}\n`);
+    process.exit(1);
+  }
+
+  process.stdout.write('[codex-diff-check] PASS: config.toml is byte-identical across two runs\n');
+  process.exit(0);
+} finally {
+  rmSync(run1, { recursive: true, force: true });
+  rmSync(run2, { recursive: true, force: true });
+}

package/scripts/convert-agents-to-codex.js

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+/**
+ * convert-agents-to-codex.js
+ *
+ * Converts Claude Code agent Markdown files (.claude/agents/<name>.md) into
+ * OpenAI Codex CLI TOML sub-agent files (.codex/agents/<name>.toml).
+ *
+ * Usage:
+ *   node scripts/convert-agents-to-codex.js [--input <dir>] [--output <dir>] [--model-map <toml>]
+ *
+ * Options:
+ *   --input <dir>       Directory containing source .md agent files.
+ *                       Default: <kit-root>/.claude/agents
+ *   --output <dir>      Output directory for .toml files.
+ *                       Default: <input-parent>/.codex/agents (or <kit-root>/.codex/agents)
+ *   --model-map <toml>  Path to a TOML file with a [model_map] table that
+ *                       overrides the built-in MODEL_MAP. Optional.
+ *
+ * Compliance
+ * ----------
+ * IAC-1: Scans agent bodies for imperative Claude-only constructs
+ *        (AskUserQuestion, Agent(, TodoWrite, model: opus) and emits
+ *        per-occurrence warnings to stderr. Non-fatal.
+ * IAC-3: Requires TOOL_DIR_NAME to be defined in src/lib/constants.js.
+ *        Exits 1 if undefined (parent path-abstraction PR not yet merged).
+ *        Override with env var MK_FORCE_NO_TOOL_DIR=1 for testing only.
+ * IAC-4: Strips KIT_INTERNAL_SKILLS from skills.config arrays.
+ * R2:    Pre-emit triple-quote escape + post-emit round-trip parse assertion.
+ *        developer_instructions must survive byte-for-byte.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { join, resolve, basename, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import toml from '@iarna/toml';
+import yaml from 'js-yaml';
+import { loadModelMap, resolveModel } from '../src/lib/runtime-codex.js';
+import { KIT_INTERNAL_SKILLS } from '../src/lib/constants.js';
+import { rewriteKitPaths } from '../src/lib/codex-rewrite.js';
+
+// ---------------------------------------------------------------------------
+// IAC-3: TOOL_DIR_NAME gate
+// ---------------------------------------------------------------------------
+
+let TOOL_DIR_NAME;
+if (process.env.MK_FORCE_NO_TOOL_DIR === '1') {
+  // Test-only escape hatch: simulate missing constant
+  process.stderr.write(
+    '[convert-agents-to-codex] ERROR: TOOL_DIR_NAME is undefined.\n' +
+      'The parent path-abstraction PR has not yet merged into src/lib/constants.js.\n' +
+      'Merge that PR first, then re-run the converter.\n' +
+      'Spike reference: docs/spikes/codex-20260509-1801/codex-spike.md\n'
+  );
+  process.exit(1);
+}
+
+try {
+  ({ TOOL_DIR_NAME } = await import('../src/lib/constants.js'));
+  if (!TOOL_DIR_NAME) {
+    throw new Error('TOOL_DIR_NAME is falsy');
+  }
+} catch (err) {
+  process.stderr.write(
+    '[convert-agents-to-codex] ERROR: Cannot import TOOL_DIR_NAME from src/lib/constants.js.\n' +
+      `Details: ${err.message}\n` +
+      'The parent path-abstraction PR has not yet merged.\n' +
+      'Spike reference: docs/spikes/codex-20260509-1801/codex-spike.md\n'
+  );
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+let inputDir;
+let outputDir;
+let modelMapPath;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--input' && args[i + 1]) {
+    inputDir = resolve(args[++i]);
+  } else if (args[i] === '--output' && args[i + 1]) {
+    outputDir = resolve(args[++i]);
+  } else if (args[i] === '--model-map' && args[i + 1]) {
+    modelMapPath = resolve(args[++i]);
+  }
+}
+
+const kitRoot = resolve(fileURLToPath(import.meta.url), '..', '..');
+const agentsDir = inputDir || join(kitRoot, TOOL_DIR_NAME, 'agents');
+if (!outputDir) {
+  // When --input is given, derive output sibling-of-input; else fall back to kit root.
+  outputDir = inputDir
+    ? join(dirname(agentsDir), '..', '.codex', 'agents')
+    : join(kitRoot, '.codex', 'agents');
+  outputDir = resolve(outputDir);
+}
+
+// ---------------------------------------------------------------------------
+// Load model map
+// ---------------------------------------------------------------------------
+
+let modelMap;
+try {
+  modelMap = loadModelMap(modelMapPath);
+} catch (err) {
+  process.stderr.write(`[convert-agents-to-codex] ERROR: ${err.message}\n`);
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// IAC-1 patterns: Claude-only constructs to flag in agent bodies
+// ---------------------------------------------------------------------------
+
+const IAC1_PATTERNS = [
+  { pattern: /AskUserQuestion/g, label: 'AskUserQuestion' },
+  { pattern: /Agent\(/g, label: 'Agent(' },
+  { pattern: /TodoWrite/g, label: 'TodoWrite' },
+  { pattern: /model:\s*opus/g, label: 'model: opus' },
+];
+
+/**
+ * Scan agent body for IAC-1 constructs and emit per-occurrence warnings.
+ * @param {string} agentName
+ * @param {string} body  Raw Markdown body (frontmatter stripped)
+ */
+function checkIac1(agentName, body) {
+  const lines = body.split('\n');
+  for (const { pattern, label } of IAC1_PATTERNS) {
+    for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+      const line = lines[lineIdx];
+      let match;
+      // Reset lastIndex for global patterns each outer pass
+      pattern.lastIndex = 0;
+      while ((match = pattern.exec(line)) !== null) {
+        process.stderr.write(
+          `[IAC-1] ${agentName}: "${label}" at line ${lineIdx + 1} col ${match.index + 1} — ` +
+            `this construct has no Codex equivalent; agent may need manual adaptation.\n`
+        );
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Frontmatter parser
+// ---------------------------------------------------------------------------
+
+/**
+ * Split a Markdown file into frontmatter and body.
+ * @param {string} content  Raw file content
+ * @returns {{ frontmatter: object, body: string }}
+ */
+function parseMd(content) {
+  const fmRegex = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+  const match = content.match(fmRegex);
+  if (!match) {
+    return { frontmatter: {}, body: content };
+  }
+  let frontmatter;
+  try {
+    frontmatter = yaml.load(match[1]) || {};
+  } catch (err) {
+    frontmatter = {};
+  }
+  return { frontmatter, body: match[2] };
+}
+
+// ---------------------------------------------------------------------------
+// IAC-4: filter internal skills from skills.config
+// ---------------------------------------------------------------------------
+
+/**
+ * Filter out KIT_INTERNAL_SKILLS from a skills array.
+ * @param {string[]} skills
+ * @returns {string[]}
+ */
+function filterSkills(skills) {
+  if (!Array.isArray(skills)) return [];
+  return skills.filter((s) => !KIT_INTERNAL_SKILLS.includes(s));
+}
+
+// ---------------------------------------------------------------------------
+// Path rewrite: .claude/{workflows,skills,agents,commands,hooks}/ → .codex/{...}/
+// Delegated to shared helper in src/lib/codex-rewrite.js (imported above).
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// R2: triple-quote escape
+// ---------------------------------------------------------------------------
+
+/**
+ * Escape sequences of 3+ double-quotes within a string to prevent them from
+ * accidentally terminating TOML multi-line basic strings.
+ * Strategy: insert a TOML line-ending backslash continuation before each run
+ * of 3+ double-quotes, splitting them into safe pairs.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+function escapeTripleQuotes(text) {
+  return text.replace(/"""/g, '""\\"');
+}
+
+// ---------------------------------------------------------------------------
+// Converter core
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a single agent .md file to a Codex TOML object.
+ * @param {string} mdPath  Absolute path to the .md file
+ * @returns {{ name: string, tomlStr: string }}
+ */
+function convertAgent(mdPath) {
+  const raw = readFileSync(mdPath, 'utf8');
+  const agentName = basename(mdPath, '.md');
+  const { frontmatter, body } = parseMd(raw);
+
+  // IAC-1 scan
+  checkIac1(agentName, body);
+
+  // Build TOML object
+  const obj = {};
+
+  // name — required
+  obj.name = frontmatter.name || agentName;
+
+  // description — required
+  obj.description = frontmatter.description || '';
+
+  // developer_instructions — rewrite kit paths, then R2 escape
+  const rewrittenBody = rewriteKitPaths(body);
+  const escapedBody = escapeTripleQuotes(rewrittenBody);
+  obj.developer_instructions = escapedBody;
+
+  // model — optional
+  const codexModel = resolveModel(frontmatter.model, modelMap);
+  if (codexModel !== undefined) {
+    obj.model = codexModel;
+  }
+
+  // model_reasoning_effort — optional; effort field on agents is absent per kit policy
+  // (effort is on mk-* skills only). We still support it if present for future proofing.
+  if (frontmatter.effort) {
+    const effort = frontmatter.effort;
+    if (effort === 'high' || effort === 'medium') {
+      obj.model_reasoning_effort = effort;
+    }
+    // never emit xhigh (kit policy)
+  }
+
+  // skills.config — IAC-4 filtered
+  const rawSkills = Array.isArray(frontmatter.skills) ? frontmatter.skills : [];
+  const filteredSkills = filterSkills(rawSkills);
+  if (filteredSkills.length > 0) {
+    obj.skills = {
+      config: filteredSkills.map((s) => ({
+        path: `.codex/skills/${s}`,
+        enabled: true,
+      })),
+    };
+  }
+
+  // Emit TOML
+  const tomlStr = toml.stringify(obj);
+
+  // R2 round-trip assertion
+  let reparsed;
+  try {
+    reparsed = toml.parse(tomlStr);
+  } catch (err) {
+    throw new Error(
+      `[R2] TOML round-trip parse failed for agent "${agentName}": ${err.message}`
+    );
+  }
+  if (reparsed.developer_instructions !== escapedBody) {
+    throw new Error(
+      `[R2] developer_instructions did not survive round-trip for agent "${agentName}". ` +
+        `Original length: ${escapedBody.length}, reparsed length: ${reparsed.developer_instructions?.length}`
+    );
+  }
+
+  return { name: agentName, tomlStr };
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+// Collect .md files (exclude README.md only; implementer.md is Tier-2 and IS converted)
+const EXCLUDED_AGENTS = new Set(['README']);
+
+let mdFiles;
+try {
+  mdFiles = readdirSync(agentsDir)
+    .filter((f) => f.endsWith('.md') && !EXCLUDED_AGENTS.has(basename(f, '.md')))
+    .map((f) => join(agentsDir, f));
+} catch (err) {
+  process.stderr.write(
+    `[convert-agents-to-codex] ERROR: Cannot read agents directory: ${agentsDir}\n${err.message}\n`
+  );
+  process.exit(1);
+}
+
+if (mdFiles.length === 0) {
+  process.stderr.write(
+    `[convert-agents-to-codex] ERROR: No .md agent files found in ${agentsDir}\n`
+  );
+  process.exit(1);
+}
+
+// Ensure output directory exists
+try {
+  mkdirSync(outputDir, { recursive: true });
+} catch (err) {
+  process.stderr.write(
+    `[convert-agents-to-codex] ERROR: Cannot create output directory: ${outputDir}\n${err.message}\n`
+  );
+  process.exit(1);
+}
+
+let successCount = 0;
+let errorCount = 0;
+const errors = [];
+
+for (const mdPath of mdFiles) {
+  const agentName = basename(mdPath, '.md');
+  try {
+    const { name, tomlStr } = convertAgent(mdPath);
+    const outPath = join(outputDir, `${name}.toml`);
+    writeFileSync(outPath, tomlStr, 'utf8');
+    successCount++;
+  } catch (err) {
+    errorCount++;
+    errors.push(`  ${agentName}: ${err.message}`);
+    process.stderr.write(
+      `[convert-agents-to-codex] ERROR converting "${agentName}": ${err.message}\n`
+    );
+  }
+}
+
+process.stdout.write(
+  `[convert-agents-to-codex] Done. ${successCount} converted, ${errorCount} errors.\n`
+);
+process.stdout.write(`[convert-agents-to-codex] Output: ${outputDir}\n`);
+
+if (errors.length > 0) {
+  process.stderr.write(`[convert-agents-to-codex] Errors:\n${errors.join('\n')}\n`);
+  process.exit(1);
+}