@khanhcan148/mk 0.1.20 → 0.1.22

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

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+/**
+ * convert-hooks-to-codex.js
+ *
+ * Reads `.claude/settings.json` → extracts hooks array.
+ * Copies `.claude/hooks/` (including lib/) to `.codex/hooks/`.
+ * Emits a Codex-compatible TOML config fragment with 6 hook blocks.
+ *
+ * Hook mapping (Claude → Codex):
+ * ┌──────────────────────────────┬──────────────┬─────────────────────┬──────────────────────────────────────────────┐
+ * │ Claude hook                  │ Codex event  │ matcher             │ command                                      │
+ * ├──────────────────────────────┼──────────────┼─────────────────────┼──────────────────────────────────────────────┤
+ * │ PreToolUse Edit/Write        │ PreToolUse   │ ^(apply_patch)$     │ …/codex-payload-adapter.cjs privacy-block.cjs│
+ * │ PreToolUse Bash              │ PreToolUse   │ ^(Bash)$            │ …/codex-payload-adapter.cjs credential-scan  │
+ * │ PostToolUse Edit/Write       │ PostToolUse  │ ^(apply_patch)$     │ …/codex-payload-adapter.cjs comment-replace  │
+ * │ PostToolUse test-match Bash  │ PostToolUse  │ ^(Bash)$            │ …/codex-payload-adapter.cjs test-match.cjs   │
+ * │ SessionStart                 │ SessionStart │ clear               │ node ./.codex/hooks/session-init.cjs         │
+ * │ wiki-update-reminder         │ PostToolUse  │ ^$                  │ node ./.codex/hooks/wiki-update-reminder.cjs │
+ * └──────────────────────────────┴──────────────┴─────────────────────┴──────────────────────────────────────────────┘
+ *
+ * Dropped (emit stderr warning per dropped hook):
+ *   - team-context-inject    (SubagentStart — no Codex equivalent)
+ *   - teammate-idle-handler  (TeammateIdle  — no Codex equivalent)
+ *   - task-completed-handler (TaskCompleted — no Codex equivalent)
+ *
+ * Returns: { added: number, dropped: string[], warnings: string[] }
+ *
+ * Uses src/lib/toml-emit.js for TOML emission (no @iarna/toml runtime dep).
+ */
+
+import { existsSync, cpSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { emitToml, emitArrayOfTables, emitTable } from '../src/lib/toml-emit.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const PACKAGE_ROOT = resolve(__dirname, '..');
+
+// Dropped Claude-only hook event types (no Codex equivalent)
+const DROPPED_HOOKS = [
+  { source: 'SubagentStart', name: 'team-context-inject' },
+  { source: 'TeammateIdle', name: 'teammate-idle-handler' },
+  { source: 'TaskCompleted', name: 'task-completed-handler' },
+];
+
+/**
+ * The 6 canonical Codex hook blocks to emit.
+ * Order is stable/deterministic (used for byte-identical output guarantee).
+ */
+function buildHookBlocks() {
+  return {
+    'hooks.PreToolUse': {
+      __type: 'array',
+      items: [
+        {
+          matcher: '^(apply_patch)$',
+          command: 'node ./.codex/hooks/lib/codex-payload-adapter.cjs privacy-block.cjs',
+        },
+        {
+          matcher: '^(Bash)$',
+          command: 'node ./.codex/hooks/lib/codex-payload-adapter.cjs credential-scan.cjs',
+        },
+      ],
+    },
+    'hooks.PostToolUse': {
+      __type: 'array',
+      items: [
+        {
+          matcher: '^(apply_patch)$',
+          command: 'node ./.codex/hooks/lib/codex-payload-adapter.cjs comment-replacement.cjs',
+        },
+        {
+          matcher: '^(Bash)$',
+          command: 'node ./.codex/hooks/lib/codex-payload-adapter.cjs test-match.cjs',
+        },
+        {
+          __leadingComments: '# coverage-gap: matcher never fires in Codex (no AskUserQuestion equivalent)',
+          matcher: '^$',
+          command: 'node ./.codex/hooks/wiki-update-reminder.cjs',
+        },
+      ],
+    },
+    'hooks.SessionStart': {
+      __type: 'array',
+      items: [
+        {
+          matcher: 'clear',
+          command: 'node ./.codex/hooks/session-init.cjs',
+        },
+      ],
+    },
+  };
+}
+
+/**
+ * Copy `.claude/hooks/` tree to `.codex/hooks/`.
+ * @param {string} projectRoot
+ */
+function copyHooksTree(projectRoot) {
+  const src = join(projectRoot, '.claude', 'hooks');
+  const dest = join(projectRoot, '.codex', 'hooks');
+
+  if (!existsSync(src)) {
+    return; // Nothing to copy
+  }
+
+  // Wipe dest first so stale entries from prior runs (e.g. tests/ that were
+  // previously copied before the filter was added) don't survive a fresh
+  // conversion. cpSync's filter only blocks NEW writes; it doesn't delete.
+  if (existsSync(dest)) {
+    rmSync(dest, { recursive: true, force: true });
+  }
+  mkdirSync(dest, { recursive: true });
+  cpSync(src, dest, {
+    recursive: true,
+    force: true,
+    filter: (s) => {
+      const base = basename(s);
+      // Exclude test directories and test files — Codex runtime doesn't need them
+      return base !== 'tests' && !base.endsWith('.test.cjs');
+    },
+  });
+}
+
+/**
+ * Build TOML document string for the Codex hooks config.
+ * @returns {string}
+ */
+function buildToml() {
+  const hookBlocks = buildHookBlocks();
+
+  const parts = [
+    '# codex >=0.129.0 <0.140.0',
+    '',
+    emitTable('features', { codex_hooks: true }),
+    '',
+    emitArrayOfTables('hooks.PreToolUse', hookBlocks['hooks.PreToolUse'].items),
+    emitArrayOfTables('hooks.PostToolUse', hookBlocks['hooks.PostToolUse'].items),
+    emitArrayOfTables('hooks.SessionStart', hookBlocks['hooks.SessionStart'].items),
+  ];
+
+  return parts.join('\n');
+}
+
+/**
+ * Main export: convert Claude hooks to Codex TOML config.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.projectRoot]  Root directory containing .claude/ (default: PACKAGE_ROOT)
+ * @param {string} [opts.outputDir]    Directory to write config.toml (default: <projectRoot>/.codex)
+ * @returns {{ added: number, dropped: string[], warnings: string[] }}
+ */
+export async function convertHooksToCodex(opts = {}) {
+  const projectRoot = opts.projectRoot ? resolve(opts.projectRoot) : PACKAGE_ROOT;
+  const outputDir = opts.outputDir ? resolve(opts.outputDir) : join(projectRoot, '.codex');
+
+  const warnings = [];
+  const dropped = [];
+
+  // Emit warnings for dropped hooks
+  for (const { source, name } of DROPPED_HOOKS) {
+    const msg = `[convert-hooks-to-codex] WARNING: Dropping ${name} (${source} event has no Codex equivalent)`;
+    warnings.push(msg);
+    dropped.push(name);
+    process.stderr.write(msg + '\n');
+  }
+
+  // Count emitted hooks
+  const hookBlocks = buildHookBlocks();
+  let added = 0;
+  for (const section of Object.values(hookBlocks)) {
+    if (section.__type === 'array') {
+      added += section.items.length;
+    }
+  }
+
+  // Copy hooks tree
+  copyHooksTree(projectRoot);
+
+  // Write config.toml
+  mkdirSync(outputDir, { recursive: true });
+  const tomlContent = buildToml();
+  writeFileSync(join(outputDir, 'config.toml'), tomlContent, 'utf-8');
+
+  return { added, dropped, warnings };
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point (when run directly)
+// ---------------------------------------------------------------------------
+
+if (process.argv[1] === __filename || process.argv[1]?.endsWith('convert-hooks-to-codex.js')) {
+  try {
+    const result = await convertHooksToCodex();
+    process.stdout.write(
+      `[convert-hooks-to-codex] Done. ${result.added} hooks emitted, ${result.dropped.length} dropped.\n`
+    );
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`[convert-hooks-to-codex] ERROR: ${err.message}\n`);
+    process.exit(1);
+  }
+}

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

@@ -0,0 +1,347 @@
+#!/usr/bin/env node
+/**
+ * convert-skills-to-codex.js
+ *
+ * Strips Claude-only frontmatter keys (model, effort, argument-hint) from
+ * .claude/skills/<name>/SKILL.md before mirroring into .codex/skills/<name>/SKILL.md.
+ *
+ * Codex 0.130's quick_validate.py hard-allowlists exactly:
+ *   {name, description, license, allowed-tools, metadata}
+ * and rejects any other YAML key. Source files are read-only.
+ *
+ * Usage:
+ *   node scripts/convert-skills-to-codex.js [--input <dir>] [--output <dir>]
+ *
+ * Compliance
+ * ----------
+ * SKL-1: model: value is mapped via MODEL_MAP (opus→gpt-5, sonnet→gpt-5-mini); effort and
+ *         argument-hint are stripped (no Codex skill-level equivalent).
+ * SKL-2: Round-trip determinism — two consecutive runs produce byte-identical output
+ * SKL-3: Body bytes pass through unchanged; only frontmatter is rewritten
+ * R2:    Post-emit round-trip assertion — regex-check output SKILL.md and confirm
+ *        none of {effort, argument-hint} appear as line-anchored YAML keys.
+ */
+
+import {
+  readFileSync,
+  writeFileSync,
+  mkdirSync,
+  rmSync,
+  readdirSync,
+  existsSync,
+  cpSync,
+} from 'node:fs';
+import { join, resolve, dirname, relative, extname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { KIT_INTERNAL_SKILLS, COPY_FILTER_PATTERNS } from '../src/lib/constants.js';
+import { loadModelMap } from '../src/lib/runtime-codex.js';
+import { rewriteKitPaths } from '../src/lib/codex-rewrite.js';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const LOG_PREFIX = '[convert-skills-to-codex]';
+
+/**
+ * Keys stripped from frontmatter (no Codex skill-level equivalent).
+ * `model` is NOT in this set — it is transformed via MODEL_MAP instead.
+ */
+const STRIP_KEYS = new Set(['effort', 'argument-hint']);
+
+/**
+ * Frontmatter regex: captures (fm_block, body) where fm_block is between the
+ * two `---` delimiters. Supports both LF and CRLF line endings.
+ */
+const FM_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/s;
+
+/**
+ * Per-line strip regex: removes lines whose key is in STRIP_KEYS.
+ * Anchored at start-of-line (`m` flag). Handles trailing CRLF or LF.
+ */
+const STRIP_RE = /^(effort|argument-hint):[^\n]*(?:\r?\n|$)/gm;
+
+/**
+ * Regex to locate the model: line for value substitution.
+ * Captures: prefix (key + colon + spaces), value (first non-space token), trailing (rest of line).
+ */
+const MODEL_LINE_RE = /^(model:\s*)(\S+)([^\n]*)$/m;
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+const args = process.argv.slice(2);
+let inputDirArg;
+let outputDirArg;
+let modelMapPath;
+
+for (let i = 0; i < args.length; i++) {
+  if (args[i] === '--input' && args[i + 1]) {
+    inputDirArg = resolve(args[++i]);
+  } else if (args[i] === '--output' && args[i + 1]) {
+    outputDirArg = resolve(args[++i]);
+  } else if (args[i] === '--model-map' && args[i + 1]) {
+    modelMapPath = resolve(args[++i]);
+  }
+}
+
+const modelMap = loadModelMap(modelMapPath);
+
+const kitRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const inputDir = inputDirArg || join(kitRoot, '.claude', 'skills');
+const outputDir = outputDirArg || join(kitRoot, '.codex', 'skills');
+
+// ---------------------------------------------------------------------------
+// Core: transform Claude-only frontmatter keys for Codex
+// ---------------------------------------------------------------------------
+
+/**
+ * Replace the `model:` line value using MODEL_MAP.
+ * Preserves prefix whitespace and any trailing inline comment.
+ * If the value is not in modelMap, logs a warning and keeps the original.
+ *
+ * @param {string} fm       Raw frontmatter block (between --- delimiters)
+ * @param {object} map      MODEL_MAP or user override
+ * @returns {string}
+ */
+function transformModelLine(fm, map) {
+  return fm.replace(MODEL_LINE_RE, (match, prefix, value, trailing) => {
+    const mapped = map[value];
+    if (mapped === undefined) {
+      process.stderr.write(
+        `${LOG_PREFIX} Warning: unknown model "${value}" — keeping original value\n`
+      );
+      return match;
+    }
+    return `${prefix}${mapped}${trailing}`;
+  });
+}
+
+/**
+ * Transform a SKILL.md content string for Codex:
+ *   - model: <claude-tier>  →  model: <codex-id>  (via MODEL_MAP)
+ *   - effort: …             →  stripped (no Codex skill-level equivalent)
+ *   - argument-hint: …      →  stripped (Claude Code slash-command UI only)
+ * Body is passed through byte-identical.
+ *
+ * @param {string} content  Raw SKILL.md content
+ * @param {object} map      MODEL_MAP or user override
+ * @returns {string}
+ */
+function transformFrontmatter(content, map) {
+  const match = content.match(FM_RE);
+  if (!match) return content; // no frontmatter — pass through unchanged
+
+  const [, fm, body] = match;
+  let transformed = fm.replace(STRIP_RE, '');    // strip effort + argument-hint
+  transformed = transformModelLine(transformed, map); // map model value
+  // FM_RE consumes the \n before the closing --- delimiter, so transformed may
+  // not end with \n. Always add it to keep the closing --- on its own line.
+  const normalizedFm = transformed.endsWith('\n') ? transformed : transformed + '\n';
+  return `---\n${normalizedFm}---\n${body}`;
+}
+
+// ---------------------------------------------------------------------------
+// Post-copy rewrite walk
+// ---------------------------------------------------------------------------
+
+/**
+ * Recursively walk `dir` and rewrite kit-path references in every text file.
+ * Covers `.md` (skill prose) AND `.js`/`.cjs`/`.mjs`/`.ts` (skill scripts that
+ * register hooks or reference sibling scripts via `.claude/skills/X/scripts/Y`
+ * paths — under Codex runtime those paths resolve under `.codex/`).
+ * Reads each file, applies `rewriteKitPaths`, and writes back only when the
+ * content actually changes (avoids touching mtimes unnecessarily).
+ *
+ * @param {string} dir  Absolute path to walk
+ */
+const _REWRITE_EXTS = new Set(['.md', '.js', '.cjs', '.mjs', '.ts', '.py']);
+
+function walkAndRewriteMarkdown(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return; // directory vanished — skip
+  }
+  for (const entry of entries) {
+    const fullPath = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      walkAndRewriteMarkdown(fullPath);
+    } else if (entry.isFile() && _REWRITE_EXTS.has(extname(entry.name).toLowerCase())) {
+      try {
+        const original = readFileSync(fullPath, 'utf8');
+        const rewritten = rewriteKitPaths(original);
+        if (rewritten !== original) {
+          writeFileSync(fullPath, rewritten, 'utf8');
+        }
+      } catch {
+        // Non-fatal: if a single file can't be read/written, continue the walk
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Path safety
+// ---------------------------------------------------------------------------
+
+/**
+ * Validate that a relative path does not escape the base directory.
+ * @param {string} rel  Relative path from path.relative()
+ * @returns {boolean}
+ */
+function isSafePath(rel) {
+  return rel !== '' && !rel.startsWith('..') && !rel.startsWith('/') && !rel.startsWith('\\');
+}
+
+// ---------------------------------------------------------------------------
+// Copy filter
+// ---------------------------------------------------------------------------
+
+/**
+ * cpSync filter that excludes paths matching COPY_FILTER_PATTERNS.
+ * @param {string} src
+ * @returns {boolean}
+ */
+function copyFilter(src) {
+  const name = src.split(/[\\/]/).pop() || '';
+  return !COPY_FILTER_PATTERNS.some((pat) => name === pat || name.endsWith(pat));
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+let successCount = 0;
+let errorCount = 0;
+const errors = [];
+
+function logInfo(msg) {
+  process.stderr.write(`${LOG_PREFIX} ${msg}\n`);
+}
+
+function logError(msg) {
+  process.stderr.write(`${LOG_PREFIX} ERROR: ${msg}\n`);
+}
+
+// H1: Guard against --output resolving to the filesystem root (rm-rf blast radius).
+// A directory is its own parent only at the filesystem root (e.g. / on Unix, C:\ on Windows).
+// Allows external temp dirs used by tests; blocks the most dangerous case.
+{
+  const resolvedOut = resolve(outputDir);
+  if (resolvedOut === resolve(dirname(resolvedOut))) {
+    logError(`outputDir "${outputDir}" is the filesystem root. Refusing to run.`);
+    process.exit(1);
+  }
+}
+
+// Destroy and recreate output directory (destructive semantics = deterministic output).
+try {
+  rmSync(outputDir, { recursive: true, force: true });
+  mkdirSync(outputDir, { recursive: true });
+} catch (err) {
+  logError(`Cannot prepare output directory: ${outputDir}\n${err.message}`);
+  process.exit(1);
+}
+
+// Walk input directory (one level deep).
+let skillDirs;
+try {
+  skillDirs = readdirSync(inputDir, { withFileTypes: true }).filter((d) => d.isDirectory());
+} catch (err) {
+  logError(`Cannot read input directory: ${inputDir}\n${err.message}`);
+  process.exit(1);
+}
+
+for (const dirent of skillDirs) {
+  const skillName = dirent.name;
+
+  // SKL-4: Skip KIT_INTERNAL_SKILLS.
+  if (KIT_INTERNAL_SKILLS.includes(skillName)) {
+    logInfo(`Skipping internal skill: ${skillName}`);
+    continue;
+  }
+
+  const skillSrc = join(inputDir, skillName);
+  const skillDest = join(outputDir, skillName);
+  const topLevelSkillMd = join(skillSrc, 'SKILL.md');
+
+  // Skip if no top-level SKILL.md exists.
+  if (!existsSync(topLevelSkillMd)) {
+    logInfo(`Skipping ${skillName}: no SKILL.md found`);
+    continue;
+  }
+
+  logInfo(`Converting skill: ${skillName}`);
+
+  try {
+    // Path safety check.
+    const relToInput = relative(inputDir, skillSrc);
+    if (!isSafePath(relToInput)) {
+      throw new Error(`Path traversal detected for skill "${skillName}": ${relToInput}`);
+    }
+
+    // Create skill output directory.
+    mkdirSync(skillDest, { recursive: true });
+
+    // Copy entire skill directory (includes references/, scripts/, assets/, etc.).
+    cpSync(skillSrc, skillDest, {
+      recursive: true,
+      force: true,
+      filter: copyFilter,
+    });
+
+    // Now overwrite the top-level SKILL.md with the transformed version.
+    const rawContent = readFileSync(topLevelSkillMd, 'utf8');
+    const strippedContent = transformFrontmatter(rawContent, modelMap);
+
+    const outSkillMd = join(skillDest, 'SKILL.md');
+    writeFileSync(outSkillMd, strippedContent, 'utf8');
+
+    // Rewrite all .md files in the skill dest tree (references/, SKILL.md body, etc.)
+    // so `.claude/<subdir>/` references become `.codex/<subdir>/`.
+    // Runs AFTER the frontmatter-transformed SKILL.md is written so the single
+    // pass covers both body and reference files.
+    walkAndRewriteMarkdown(skillDest);
+
+    // R2 round-trip assertion: confirm stripped keys are absent after write.
+    // Uses line-anchored regex (same as STRIP_RE) rather than yaml.load, because
+    // some skill descriptions contain ': ' sequences that make js-yaml refuse to
+    // parse the frontmatter block (the source YAML is valid but ambiguous per
+    // js-yaml's strict mode). The regex check is sufficient for our purposes.
+    const written = readFileSync(outSkillMd, 'utf8');
+    const fmMatch = written.match(FM_RE);
+    // H4: Fail-closed — if the output SKILL.md has no valid frontmatter block
+    // the write succeeded but the content is corrupt; treat as a hard error so
+    // the skill is counted as failed rather than silently "passing" R2.
+    if (!fmMatch) {
+      throw new Error(`R2: output SKILL.md has no valid frontmatter: ${outSkillMd}`);
+    }
+    const writtenFm = fmMatch[1];
+    for (const key of STRIP_KEYS) {
+      const keyRe = new RegExp(`^${key.replace(/-/g, '\\-')}:`, 'm');
+      if (keyRe.test(writtenFm)) {
+        throw new Error(`R2 violation: key '${key}' survived strip in ${outSkillMd}`);
+      }
+    }
+
+    logInfo(`R2 assertion passed for: ${skillName}`);
+    successCount++;
+  } catch (err) {
+    errorCount++;
+    errors.push(`  ${skillName}: ${err.message}`);
+    logError(`Converting "${skillName}": ${err.message}`);
+  }
+}
+
+process.stdout.write(
+  `${LOG_PREFIX} Done. ${successCount} converted, ${errorCount} errors.\n`
+);
+process.stdout.write(`${LOG_PREFIX} Output: ${outputDir}\n`);
+
+if (errors.length > 0) {
+  process.stderr.write(`${LOG_PREFIX} Errors:\n${errors.join('\n')}\n`);
+  process.exit(1);
+}