@khanhcan148/mk 0.1.21 → 0.1.24

package/src/commands/codex.js

@@ -0,0 +1,315 @@
+/**
+ * codex.js — `mk codex` subcommand.
+ *
+ * Mirrors the current project's `.claude/` kit assets into `.codex/` for
+ * OpenAI Codex CLI consumption:
+ *   - .claude/agents/*.md  → .codex/agents/*.toml  (via converter script)
+ *   - .claude/skills/      → .codex/skills/        (via skills converter, Claude-only FM keys stripped)
+ *   - .claude/workflows/   → .codex/workflows/     (recursive copy)
+ *   - .claude/hooks/       → .codex/hooks/         (via hooks converter)
+ *   - .codex/config.toml   — emitted with [features] codex_hooks=true + 6 hook blocks
+ *
+ * The converter is the source of truth for IAC-1/3/4 + R2 compliance; this
+ * command is a thin wrapper that supplies cwd-derived paths and handles the
+ * skills/workflows copy that the converter intentionally does not.
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync, cpSync, rmSync, statSync, writeFileSync, mkdirSync, readdirSync, readFileSync } from 'node:fs';
+import { join, resolve, dirname, basename, sep, parse as pathParse, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import chalk from 'chalk';
+import { TOOL_DIR_NAME, COPY_FILTER_PATTERNS } from '../lib/constants.js';
+import { convertHooksToCodex } from '../../scripts/convert-hooks-to-codex.js';
+import { rewriteKitPaths } from '../lib/codex-rewrite.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = resolve(__dirname, '..', '..');
+const CONVERTER_SCRIPT = join(PACKAGE_ROOT, 'scripts', 'convert-agents-to-codex.js');
+const SKILLS_CONVERTER_SCRIPT = join(PACKAGE_ROOT, 'scripts', 'convert-skills-to-codex.js');
+
+/**
+ * Copy a directory tree, excluding nested filenames matching COPY_FILTER_PATTERNS
+ * and (when provided) top-level directory segments listed in `excludeNames`.
+ *
+ * Replaces destDir wholesale (rm -rf semantics) so stale entries from a
+ * previous run do not linger.
+ *
+ * @param {string} srcDir
+ * @param {string} destDir
+ * @param {{ excludeNames?: string[] }} [opts]
+ */
+function mirrorDir(srcDir, destDir, opts = {}) {
+  const excludeNames = new Set(opts.excludeNames ?? []);
+
+  if (existsSync(destDir)) {
+    rmSync(destDir, { recursive: true, force: true });
+  }
+
+  cpSync(srcDir, destDir, {
+    recursive: true,
+    force: true,
+    filter: (src) => {
+      const name = basename(src);
+      if (COPY_FILTER_PATTERNS.some((pat) => name === pat || name.endsWith(pat))) {
+        return false;
+      }
+      // Top-level directory exclusion (e.g. KIT_INTERNAL_SKILLS).
+      // Only match immediate children of srcDir, not nested directories
+      // that happen to share a name.
+      if (excludeNames.size > 0) {
+        const rel = src.slice(srcDir.length).replace(/^[\\/]+/, '');
+        if (rel && !rel.includes(sep) && excludeNames.has(rel)) {
+          return false;
+        }
+      }
+      return true;
+    },
+  });
+}
+
+/**
+ * Mirror a directory tree like `mirrorDir`, but also rewrite kit-path references
+ * in text files so `.claude/<subdir>/` becomes `.codex/<subdir>/`.
+ *
+ * Text files (extensions in `textExtensions`) are read, rewritten, and written;
+ * binary/other files are copied byte-identical via cpSync per-file.
+ *
+ * Destructive: removes destDir wholesale before copying so stale entries from
+ * a previous run do not linger (same rm-rf semantics as mirrorDir).
+ *
+ * @param {string} srcDir
+ * @param {string} destDir
+ * @param {{
+ *   excludeNames?: string[],
+ *   textExtensions?: string[],
+ *   rewriter?: (text: string) => string,
+ * }} [opts]
+ */
+function mirrorDirWithRewrite(srcDir, destDir, opts = {}) {
+  const excludeNames = new Set(opts.excludeNames ?? []);
+  const textExtensions = new Set(opts.textExtensions ?? ['.md', '.txt', '.toml']);
+  const rewriter = opts.rewriter ?? rewriteKitPaths;
+
+  if (existsSync(destDir)) {
+    rmSync(destDir, { recursive: true, force: true });
+  }
+
+  function walkAndCopy(src, dest) {
+    mkdirSync(dest, { recursive: true });
+    let entries;
+    try {
+      entries = readdirSync(src, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const name = entry.name;
+      // Apply COPY_FILTER_PATTERNS exclusion
+      if (COPY_FILTER_PATTERNS.some((pat) => name === pat || name.endsWith(pat))) {
+        continue;
+      }
+      // Apply top-level excludeNames (only immediate children of srcDir)
+      if (excludeNames.size > 0 && src === srcDir && excludeNames.has(name)) {
+        continue;
+      }
+      const srcPath = join(src, name);
+      const destPath = join(dest, name);
+      if (entry.isDirectory()) {
+        walkAndCopy(srcPath, destPath);
+      } else if (entry.isFile()) {
+        const ext = extname(name).toLowerCase();
+        if (textExtensions.has(ext)) {
+          try {
+            const original = readFileSync(srcPath, 'utf8');
+            const rewritten = rewriter(original);
+            writeFileSync(destPath, rewritten, 'utf8');
+          } catch {
+            // Fall back to binary copy on read/write failure
+            cpSync(srcPath, destPath, { force: true });
+          }
+        } else {
+          cpSync(srcPath, destPath, { force: true });
+        }
+      }
+    }
+  }
+
+  walkAndCopy(srcDir, destDir);
+}
+
+/** Single-syscall directory check (replaces existsSync+statSync double-stat). */
+function isDirectory(p) {
+  try { return statSync(p).isDirectory(); } catch { return false; }
+}
+
+/**
+ * Run the full Codex conversion pipeline for a project root.
+ *
+ * Unlike `codexAction`, this function never calls `process.exit`. It returns
+ * a result object so callers (e.g. `maybeSyncCodex` in update.js) can inspect
+ * the outcome and decide how to handle failures.
+ *
+ * @param {object} [options]
+ * @param {string} [options.cwd]      - Project root (default: process.cwd()).
+ *                                      Trusted-caller-only: callers must supply a
+ *                                      validated path. If set, any `..` segment
+ *                                      after resolution is rejected so an injected
+ *                                      path can never traverse outside its parent.
+ * @param {string} [options.output]   - Override for agents output dir
+ * @param {string} [options.modelMap] - Path to custom model-map JSON
+ * @returns {Promise<{ exitCode: number, hooksResult?: object, errors: string[] }>}
+ */
+export async function runCodexConversion(options = {}) {
+  // S1: Reject `..` segments AFTER resolve to catch encoded traversal attempts
+  // (e.g. "foo/../../../etc"). A full homedir-bound would break legitimate
+  // `mk codex --cwd /tmp/…` invocations, so we use the lighter ..‑segment check.
+  if (options.cwd) {
+    const resolvedCwd = resolve(options.cwd);
+    // Check the original (pre-resolve) string for '..' path segments
+    const parts = options.cwd.replace(/\\/g, '/').split('/');
+    if (parts.some((p) => p === '..')) {
+      const msg = 'error: --cwd must not contain ".." path traversal segments';
+      console.error(chalk.red(msg));
+      return { exitCode: 1, errors: [msg] };
+    }
+    // Also verify that resolve didn't collapse to a shorter path unexpectedly
+    // (defence in depth: covers OS-level symlink chains that embed traversal)
+    void resolvedCwd; // used only for the side-effect check above
+  }
+  const projectRoot = resolve(options.cwd || process.cwd());
+  const claudeDir = join(projectRoot, TOOL_DIR_NAME);
+  const agentsDir = join(claudeDir, 'agents');
+  const skillsDir = join(claudeDir, 'skills');
+  const workflowsDir = join(claudeDir, 'workflows');
+
+  // Two-mode path resolution:
+  //   --output set:  codexRoot = parent(output), agentsOut = output (output IS agents dir)
+  //   --output unset: codexRoot = <projectRoot>/.codex, agentsOut = <codexRoot>/agents
+  // Tests pass --output to write into a tmpdir; CLI users normally omit it.
+  const codexRoot = options.output
+    ? resolve(options.output, '..')
+    : join(projectRoot, '.codex');
+  const agentsOut = options.output ? resolve(options.output) : join(codexRoot, 'agents');
+  const skillsOut = join(codexRoot, 'skills');
+  const workflowsOut = join(codexRoot, 'workflows');
+
+  const errors = [];
+
+  // H2: Guard against --output resolving to the filesystem root (rm-rf blast radius).
+  // S2: Use pathParse().root === codexRoot instead of comparing against resolve(sep),
+  // because Windows has multiple drive roots (C:\, D:\) and UNC paths — resolve(sep)
+  // only covers the current drive, while pathParse().root covers ALL canonical roots.
+  if (pathParse(codexRoot).root === codexRoot) {
+    const msg = 'error: --output must not resolve to the filesystem root';
+    console.error(chalk.red(msg));
+    errors.push(msg);
+    return { exitCode: 1, errors };
+  }
+
+  if (!existsSync(agentsDir)) {
+    const msg = `error: ${agentsDir} does not exist`;
+    console.error(chalk.red(msg));
+    console.error(chalk.dim(`run \`mk init\` first, or pass --cwd <project-with-.claude>`));
+    errors.push(msg);
+    return { exitCode: 1, errors };
+  }
+
+  if (!existsSync(CONVERTER_SCRIPT)) {
+    const msg = `error: converter script not found at ${CONVERTER_SCRIPT}`;
+    console.error(chalk.red(msg));
+    errors.push(msg);
+    return { exitCode: 1, errors };
+  }
+
+  // Skills and agents converters run in parallel to reduce wall-clock time.
+  // Progress lines are emitted before the Promise.all so they appear immediately.
+  // workflowsDir mirror is synchronous and runs after both converters complete.
+
+  // Guard skills converter script availability before starting any spawns.
+  if (isDirectory(skillsDir) && !existsSync(SKILLS_CONVERTER_SCRIPT)) {
+    const msg = `error: skills converter not found at ${SKILLS_CONVERTER_SCRIPT}`;
+    console.error(chalk.red(msg));
+    errors.push(msg);
+    return { exitCode: 1, errors };
+  }
+
+  // Emit progress lines upfront (before awaiting) so the user sees intent immediately.
+  if (isDirectory(skillsDir)) {
+    console.log(chalk.cyan(`Converting ${skillsDir}`));
+    console.log(chalk.cyan(`        → ${skillsOut}`));
+  }
+
+  const args = [CONVERTER_SCRIPT, '--input', agentsDir, '--output', agentsOut];
+  if (options.modelMap) {
+    args.push('--model-map', resolve(options.modelMap));
+  }
+  console.log(chalk.cyan(`Converting ${agentsDir}`));
+  console.log(chalk.cyan(`        → ${agentsOut}`));
+
+  // Start both spawns concurrently.
+  const skillsPromise = isDirectory(skillsDir)
+    ? new Promise((resolveExit) => {
+        const child = spawn(
+          process.execPath,
+          [SKILLS_CONVERTER_SCRIPT, '--input', skillsDir, '--output', skillsOut],
+          { stdio: 'inherit' }
+        );
+        child.on('close', (exitCode) => resolveExit(exitCode ?? 1));
+        child.on('error', (err) => {
+          console.error(chalk.red(`error: failed to spawn skills converter: ${err.message}`));
+          resolveExit(1);
+        });
+      })
+    : Promise.resolve(0);
+
+  const agentsPromise = new Promise((resolveExit) => {
+    const child = spawn(process.execPath, args, { stdio: 'inherit' });
+    child.on('close', (exitCode) => resolveExit(exitCode ?? 1));
+    child.on('error', (err) => {
+      console.error(chalk.red(`error: failed to spawn converter: ${err.message}`));
+      resolveExit(1);
+    });
+  });
+
+  const [skillsCode, code] = await Promise.all([skillsPromise, agentsPromise]);
+
+  if (skillsCode !== 0) {
+    errors.push(`skills converter exited with code ${skillsCode}`);
+    return { exitCode: skillsCode, errors };
+  }
+
+  if (code !== 0) {
+    errors.push(`agent converter exited with code ${code}`);
+    return { exitCode: code, errors };
+  }
+
+  // Mirror workflows synchronously after both converters succeed.
+  // Uses mirrorDirWithRewrite so .claude/<subdir>/ refs in .md/.txt/.toml files
+  // are rewritten to .codex/<subdir>/ for Codex-runtime resolution.
+  if (isDirectory(workflowsDir)) {
+    console.log(chalk.cyan(`Mirroring  ${workflowsDir}`));
+    console.log(chalk.cyan(`        → ${workflowsOut}`));
+    mirrorDirWithRewrite(workflowsDir, workflowsOut);
+  }
+
+  const hooksResult = await convertHooksToCodex({ projectRoot, outputDir: codexRoot });
+  if (hooksResult.dropped.length > 0) {
+    console.warn(
+      chalk.yellow(
+        `Warning: dropped ${hooksResult.dropped.length} hooks (SubagentStart/TeammateIdle/TaskCompleted have no Codex equivalent)`
+      )
+    );
+  }
+  console.log(chalk.green('✓ codex conversion complete'));
+  return { exitCode: 0, hooksResult, errors };
+}
+
+/**
+ * `mk codex` CLI entry point — thin wrapper around runCodexConversion.
+ * Calls process.exit with the result exit code.
+ */
+export async function codexAction(options = {}) {
+  const result = await runCodexConversion(options);
+  process.exit(result.exitCode);
+}

package/src/commands/update.js

@@ -1,7 +1,9 @@
 import chalk from 'chalk';
 import { createInterface } from 'node:readline';
-import { existsSync, unlinkSync, copyFileSync, mkdirSync, readFileSync, rmdirSync } from 'node:fs';
+import { existsSync, unlinkSync, copyFileSync, mkdirSync, readFileSync, rmdirSync, readdirSync } from 'node:fs';
 import { join, dirname, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+import { runCodexConversion } from './codex.js';
 import { fileURLToPath } from 'node:url';
 import { readManifest, updateManifest, diffManifest } from '../lib/manifest.js';
 import { computeChecksum } from '../lib/checksum.js';
@@ -40,6 +42,98 @@ export function stripTerminalEscapes(str) {
     .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f]/g, '');  // raw control chars (preserve \t \n \r)
 }
 
+// ---------------------------------------------------------------------------
+// Security: redact secrets and paths from error messages before surfacing them
+// ---------------------------------------------------------------------------
+
+/**
+ * Scrub sensitive values from a string before writing it to stderr/stdout.
+ *
+ * S3: Redacts GitHub personal-access tokens (gh[pousr]_… pattern) and any
+ *     stored token obtained via readStoredToken(), so credentials cannot leak
+ *     into terminal output or CI logs.
+ * S4: Replaces the user's home directory prefix with `~` and the current
+ *     working directory prefix with `.` to avoid leaking absolute paths.
+ *
+ * @param {string} message         - Raw error/warning message to sanitise.
+ * @param {{ storedToken?: string|null }} [ctx]
+ * @returns {string}
+ */
+export function redactSecrets(message, ctx = {}) {
+  let out = message;
+
+  // S4: Path redaction — replace absolute path prefixes with short aliases.
+  // Apply homedir first (longer prefix) before cwd to avoid partial replacement.
+  const home = homedir();
+  const cwd = process.cwd();
+  // Replace homedir occurrences with '~'
+  if (home && out.includes(home)) {
+    out = out.split(home).join('~');
+  }
+  // Replace cwd occurrences with '.' (only when cwd != home to avoid double-replace)
+  if (cwd && cwd !== home && out.includes(cwd)) {
+    out = out.split(cwd).join('.');
+  }
+
+  // S3: Redact explicit stored token if provided
+  if (ctx.storedToken && out.includes(ctx.storedToken)) {
+    out = out.split(ctx.storedToken).join('[REDACTED-TOKEN]');
+  }
+
+  // S3: Redact any GitHub token-shaped substring (belt-and-braces)
+  out = out.replace(/gh[pousr]_[A-Za-z0-9_]{30,}/g, '[REDACTED-TOKEN]');
+
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Codex auto-sync helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns true if `codexDir` looks like a real Codex install — i.e. it exists
+ * and contains at least one of the indicator children emitted by `mk codex`.
+ *
+ * Returns false when the directory is absent (not installed) or empty (no
+ * conversion has been run yet), so `maybeSyncCodex` can silently skip.
+ *
+ * @param {string} codexDir  - Absolute path to the `.codex/` directory
+ * @returns {boolean}
+ */
+export function hasCodexInstall(codexDir) {
+  let entries;
+  try { entries = readdirSync(codexDir); } catch { return false; }
+  if (entries.length === 0) return false;
+  const indicators = new Set(['agents', 'skills', 'workflows', 'hooks', 'config.toml']);
+  return entries.some((name) => indicators.has(name));
+}
+
+/**
+ * If a Codex install is detected alongside the updated `.claude/`, re-run the
+ * Codex conversion pipeline so the `.codex/` mirror stays coherent.
+ *
+ * Silent no-op when `.codex/` is absent or empty (no prior conversion).
+ * Throws a tagged error (`.codexSyncFailure = true`) on conversion failure so
+ * callers can distinguish a codex-only problem from a core update failure.
+ *
+ * @param {{ projectRoot: string, codexRunner: Function }} opts
+ * @param {string}   opts.projectRoot  - Absolute path to the project root
+ * @param {Function} opts.codexRunner  - DI-injectable; defaults to runCodexConversion
+ */
+export async function maybeSyncCodex({ projectRoot, codexRunner }) {
+  const codexDir = join(projectRoot, '.codex');
+  if (!hasCodexInstall(codexDir)) return; // silent skip — no codex install detected
+  process.stdout.write(chalk.cyan('Syncing .codex/ mirror…\n'));
+  const result = await codexRunner({ cwd: projectRoot });
+  if (result.exitCode !== 0) {
+    const err = new Error(
+      'Codex sync failed after .claude/ update completed. Retry manually: `mk codex`'
+    );
+    err.codexSyncFailure = true;
+    throw err;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Prompt helper
 // ---------------------------------------------------------------------------
@@ -314,7 +408,8 @@ export async function updateAction(options = {}, deps = {}) {
     promptUser = defaultPromptUser,
     // Injectable for tests — allows overriding resolved paths without touching CWD
     manifestPath: injectedManifestPath,
-    targetDir: injectedTargetDir
+    targetDir: injectedTargetDir,
+    runCodexConversion: codexRunner = runCodexConversion
   } = deps;
 
   // Read local package version (used as fallback when manifest has no version)
@@ -324,6 +419,9 @@ export async function updateAction(options = {}, deps = {}) {
 
   const targetDir = injectedTargetDir ?? resolveTargetDir(options);
   const manifestPath = injectedManifestPath ?? resolveManifestPath(options);
+  // targetDir is always <root>/.claude (resolveTargetDir returns join(root, '.claude'));
+  // dirname yields the project root for project mode and homedir() for global mode.
+  const projectRoot = dirname(targetDir);
 
   let tempDir = null;
   try {
@@ -374,6 +472,7 @@ export async function updateAction(options = {}, deps = {}) {
         // before hooks were added to the kit or if it was manually edited.
         // resolveSourceDir() points to the CLI package's own .claude/ — no download needed.
         mergeSettingsJson(resolveSourceDir(), targetDir);
+        await maybeSyncCodex({ projectRoot, codexRunner });
         return;
       }
 
@@ -444,8 +543,13 @@ export async function updateAction(options = {}, deps = {}) {
         }
       }
     }
+    await maybeSyncCodex({ projectRoot, codexRunner });
   } catch (err) {
-    process.stderr.write(chalk.red(`Error: ${err.message}\n`));
+    // S3+S4: scrub tokens and absolute paths from error messages before surfacing
+    let storedToken = null;
+    try { storedToken = readStoredToken(); } catch { /* ignore — token may not be stored */ }
+    const safeMessage = redactSecrets(err.message ?? String(err), { storedToken });
+    process.stderr.write(chalk.red(`Error: ${safeMessage}\n`));
     process.exit(1);
   } finally {
     if (tempDir) {

package/src/lib/codex-rewrite.js

@@ -0,0 +1,36 @@
+/**
+ * codex-rewrite.js — Shared kit-path rewriter for Codex conversion pipeline.
+ *
+ * Rewrites kit-relative `.claude/<subdir>/` references to `.codex/<subdir>/`
+ * so that Codex-runtime skill/workflow/agent prose resolves correctly under
+ * `.codex/` rather than the source `.claude/` tree.
+ *
+ * Covered subdirectories: workflows, skills, agents, commands, hooks.
+ *
+ * Properties guaranteed:
+ *   - Idempotent: rewriteKitPaths(rewriteKitPaths(x)) === rewriteKitPaths(x)
+ *     because the output `.codex/` prefix never matches the input pattern.
+ *   - CRLF-safe: uses String.prototype.replace only (no split/join).
+ *   - Allowlist-scoped: only the 5 listed subdirs match. Bare
+ *     `.claude/settings.json` (no subdir) is untouched. Global-install
+ *     paths like `~/.claude/skills/X` ARE rewritten to `~/.codex/skills/X`
+ *     because under Codex runtime the global install lives at `~/.codex/`,
+ *     not `~/.claude/`. Hook scripts (`.cjs`/`.js`) bypass this pipeline
+ *     entirely (the hooks converter byte-copies them), so intentional
+ *     `.claude/hooks/.logs/` runtime constants survive untouched.
+ */
+
+// Substring match is intentional: `~/.claude/skills/X` becomes
+// `~/.codex/skills/X`. No prefix anchor (handles backtick, quote, space,
+// start-of-string, and ~/ uniformly).
+const _KIT_PATH_RE = /\.claude\/(workflows|skills|agents|commands|hooks)\//g;
+
+/**
+ * Rewrite `.claude/<subdir>/` references to `.codex/<subdir>/` in `text`.
+ *
+ * @param {string} text - Input text (may contain multiple refs across multiple lines).
+ * @returns {string}    - Text with all kit-internal path references rewritten.
+ */
+export function rewriteKitPaths(text) {
+  return text.replace(_KIT_PATH_RE, '.codex/$1/');
+}

package/src/lib/constants.js

@@ -24,6 +24,7 @@ export const COPY_FILTER_PATTERNS = [
   '.pytest_cache',
   '.pyc',
   '.pyo',
+  '.coverage',
   'node_modules',
   '.DS_Store',
   'package-lock.json',
@@ -45,3 +46,28 @@ export const GITHUB_API = 'https://api.github.com';
  * Kit repository (owner/repo)
  */
 export const KIT_REPO = 'khanhtran148/mk-kit';
+
+/**
+ * The Claude Code tool directory name (the `.claude/` folder).
+ * Used by the Codex converter to locate agent + skill source files.
+ * NOTE: A parent path-abstraction PR is planned to make this configurable
+ * via env var. Until that PR lands, this constant provides the default value.
+ */
+export const TOOL_DIR_NAME = '.claude';
+
+/**
+ * Codex SKILL.md frontmatter allowlist used by kit validators.
+ * Includes `model` because convert-skills-to-codex.js writes a mapped model value
+ * (Claude tier → Codex model ID via MODEL_MAP). The strict Codex quick_validate.py
+ * allowlist omits `model`, but the kit writes it intentionally for runtime guidance.
+ * Cross-reference: CLAUDE_ONLY_SKILL_FM_KEYS (denylist for keys that are stripped).
+ */
+export const CODEX_SKILL_FM_ALLOWED = Object.freeze(['name', 'description', 'license', 'allowed-tools', 'metadata', 'model']);
+
+/**
+ * Claude-Code-only SKILL.md frontmatter keys that are stripped (not transformed)
+ * when mirroring to .codex/skills/ — they have no Codex skill-level equivalent.
+ * Note: `model` is NOT in this set; it is transformed via MODEL_MAP instead.
+ * Cross-reference: CODEX_SKILL_FM_ALLOWED (allowlist on validate).
+ */
+export const CLAUDE_ONLY_SKILL_FM_KEYS = Object.freeze(['effort', 'argument-hint']);

package/src/lib/runtime-codex.js

@@ -0,0 +1,148 @@
+/**
+ * runtime-codex.js — MODEL_MAP and model resolution helpers for the Codex converter.
+ *
+ * Provides:
+ *   MODEL_MAP       — frozen default map of Claude model tiers → Codex model IDs
+ *   loadModelMap()  — merge user override TOML over the frozen default
+ *   resolveModel()  — look up a Claude model name in a model map; warn on miss
+ *
+ * Design notes
+ * ------------
+ * K3=3a: hardcoded MODEL_MAP with per-invocation --model-map override flag.
+ * The default map is intentionally small and frozen; future model IDs arrive
+ * via the override TOML, not via source edits.
+ *
+ * ARP-02: unknown model names produce a console.warn (non-fatal) and return
+ * undefined so the caller may omit the `model` field from the emitted TOML.
+ */
+
+import { readFileSync } from 'node:fs';
+
+/**
+ * Minimal TOML parser for the model-map override format.
+ * Supports only [section] headers and `key = "string"` entries.
+ * Throws on unrecognised syntax.
+ * @param {string} raw
+ * @returns {{ [section: string]: { [key: string]: string } }}
+ */
+function parseModelMapToml(raw) {
+  const result = {};
+  let section = null;
+  for (const rawLine of raw.split('\n')) {
+    const line = rawLine.replace(/\r$/, '').trim();
+    if (!line || line.startsWith('#')) continue;
+    const sectionMatch = line.match(/^\[([^\]]+)\]$/);
+    if (sectionMatch) {
+      section = sectionMatch[1].trim();
+      result[section] = {};
+      continue;
+    }
+    const kvMatch = line.match(/^([A-Za-z0-9_-]+)\s*=\s*"([^"]*)"$/);
+    if (kvMatch && section) {
+      result[section][kvMatch[1]] = kvMatch[2];
+      continue;
+    }
+    throw new Error(`Unrecognised TOML line: ${line}`);
+  }
+  return result;
+}
+
+/**
+ * Default mapping from Claude model-tier short names to Codex model IDs.
+ * Keys are the values that appear in agent YAML frontmatter `model:` fields.
+ * @type {Readonly<{[claudeModel: string]: string}>}
+ */
+export const MODEL_MAP = Object.freeze({
+  opus: 'gpt-5',
+  sonnet: 'gpt-5-mini',
+});
+
+/**
+ * Load a model map, optionally merging a user-supplied TOML override.
+ *
+ * @param {string|undefined} overridePath  Absolute path to a TOML file that
+ *   contains a `[model_map]` table, e.g.:
+ *   ```toml
+ *   [model_map]
+ *   opus   = "gpt-5"
+ *   sonnet = "gpt-5-mini"
+ *   haiku  = "gpt-4o-mini"
+ *   ```
+ *   When `undefined`, returns the frozen default MODEL_MAP.
+ * @returns {Readonly<{[claudeModel: string]: string}>}
+ * @throws {Error} If `overridePath` is provided but the file cannot be read
+ *   or parsed, or if it does not contain a `[model_map]` table.
+ */
+export function loadModelMap(overridePath) {
+  if (overridePath === undefined) {
+    return MODEL_MAP;
+  }
+
+  let raw;
+  try {
+    raw = readFileSync(overridePath, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `[runtime-codex] Cannot read model-map override file: ${overridePath}\n${err.message}`
+    );
+  }
+
+  let parsed;
+  try {
+    parsed = parseModelMapToml(raw);
+  } catch (err) {
+    throw new Error(
+      `[runtime-codex] Failed to parse model-map override TOML: ${overridePath}\n${err.message}`
+    );
+  }
+
+  if (!parsed.model_map || typeof parsed.model_map !== 'object') {
+    throw new Error(
+      `[runtime-codex] Override TOML must contain a [model_map] table: ${overridePath}`
+    );
+  }
+
+  // H3: Validate model-map values to prevent TOML/YAML injection via crafted
+  // model names that contain whitespace, colons, or newlines.
+  const MODEL_VALUE_RE = /^[A-Za-z0-9._-]+$/;
+  for (const [k, v] of Object.entries(parsed.model_map)) {
+    if (!MODEL_VALUE_RE.test(String(v))) {
+      throw new Error(
+        `[runtime-codex] Invalid model-map value for "${k}": "${v}". ` +
+        'Values must match /^[A-Za-z0-9._-]+$/ (no whitespace, colons, or newlines).'
+      );
+    }
+  }
+
+  return Object.freeze({ ...MODEL_MAP, ...parsed.model_map });
+}
+
+/**
+ * Resolve a Claude model-tier name to a Codex model ID.
+ *
+ * @param {string|undefined} claudeModel  Value from agent frontmatter `model:` field.
+ *   May be undefined (agent has no `model:` declaration).
+ * @param {Readonly<{[claudeModel: string]: string}>} modelMap  Map returned by
+ *   `loadModelMap()`.
+ * @returns {string|undefined}  Codex model ID, or `undefined` when:
+ *   - `claudeModel` is undefined (caller should omit the `model` field)
+ *   - `claudeModel` is not in the map (ARP-02: warn emitted to stderr)
+ */
+export function resolveModel(claudeModel, modelMap) {
+  if (claudeModel === undefined) {
+    return undefined;
+  }
+
+  const codexModel = modelMap[claudeModel];
+  if (codexModel === undefined) {
+    // ARP-02: unknown model — non-fatal, let caller omit the field
+    process.stderr.write(
+      `[runtime-codex] Warning: unknown model tier "${claudeModel}" — ` +
+        `model field will be omitted from emitted TOML. ` +
+        `Add an entry to your --model-map override file to suppress this warning.\n`
+    );
+    return undefined;
+  }
+
+  return codexModel;
+}