@khanhcan148/mk 0.1.26 → 0.1.28

package/bin/mk.js

@@ -37,6 +37,7 @@ program.command('remove')
 
 program.command('codex')
   .description('Mirror .claude/ to .codex/ for OpenAI Codex CLI (agents converted to TOML; skills + workflows copied)')
+  .option('--global', 'Convert ~/.claude/ to ~/.codex/')
   .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')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khanhcan148/mk",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "CLI to install and manage MyClaudeKit (.claude/) in your projects",
   "type": "module",
   "bin": {
@@ -26,10 +26,9 @@
     "chalk": "^5.0.0",
     "commander": "^12.0.0",
     "fs-extra": "^11.0.0",
-    "js-yaml": "4.1.0",
+    "js-yaml": "^4.1.1",
     "semver": "^7.0.0"
   },
-  "devDependencies": {},
   "keywords": [
     "claude",
     "claude-code",

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

@@ -4,18 +4,19 @@
  *
  * 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.
+ * Emits a Codex-compatible TOML config with 7 command hook handlers.
  *
  * 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 │
+ * │ PreToolUse apply_patch       │ PreToolUse   │ ^(apply_patch)$     │ …/codex-payload-adapter.cjs privacy-block.cjs │
+ * │ PreToolUse apply_patch       │ PreToolUse   │ ^(apply_patch)$     │ …/codex-payload-adapter.cjs credential-scan   │
+ * │ PreToolUse Bash              │ PreToolUse   │ ^(Bash)$            │ …/codex-payload-adapter.cjs privacy-block.cjs │
+ * │ PostToolUse apply_patch      │ PostToolUse  │ ^(apply_patch)$     │ …/codex-payload-adapter.cjs comment-replace   │
+ * │ PostToolUse apply_patch      │ PostToolUse  │ ^(apply_patch)$     │ …/codex-payload-adapter.cjs test-match.cjs    │
+ * │ SessionStart                 │ SessionStart │ clear               │ node ./.codex/hooks/session-init.cjs          │
+ * │ wiki-update-reminder         │ Stop          │ n/a                 │ node ./.codex/hooks/wiki-update-reminder.cjs  │
  * └──────────────────────────────┴──────────────┴─────────────────────┴──────────────────────────────────────────────┘
  *
  * Dropped (emit stderr warning per dropped hook):
@@ -31,7 +32,7 @@
 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';
+import { emitScalar, emitTable } from '../src/lib/toml-emit.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -44,22 +45,66 @@ const DROPPED_HOOKS = [
   { source: 'TaskCompleted', name: 'task-completed-handler' },
 ];
 
+function shellDoubleQuote(s) {
+  return String(s).replace(/(["\\$`])/g, '\\$1');
+}
+
+function rootCommand(command, projectRoot, hookPath) {
+  const fallbackRoot = shellDoubleQuote(projectRoot);
+  return [
+    'r="$(git rev-parse --show-toplevel 2>/dev/null)"',
+    `if [ -n "$r" ] && [ -f "$r/.codex/hooks/${hookPath}" ]; then cd "$r"; else cd "${fallbackRoot}"; fi`,
+    command,
+  ].join('; ');
+}
+
 /**
- * The 6 canonical Codex hook blocks to emit.
+ * The 7 canonical Codex hook blocks to emit.
  * Order is stable/deterministic (used for byte-identical output guarantee).
  */
-function buildHookBlocks() {
+function buildHookBlocks(projectRoot = PACKAGE_ROOT) {
   return {
     'hooks.PreToolUse': {
       __type: 'array',
       items: [
         {
           matcher: '^(apply_patch)$',
-          command: 'node ./.codex/hooks/lib/codex-payload-adapter.cjs privacy-block.cjs',
+          hooks: [
+            {
+              type: 'command',
+              command: rootCommand(
+                'node ./.codex/hooks/lib/codex-payload-adapter.cjs privacy-block.cjs',
+                projectRoot,
+                'lib/codex-payload-adapter.cjs'
+              ),
+            },
+          ],
+        },
+        {
+          matcher: '^(apply_patch)$',
+          hooks: [
+            {
+              type: 'command',
+              command: rootCommand(
+                'node ./.codex/hooks/lib/codex-payload-adapter.cjs credential-scan.cjs',
+                projectRoot,
+                'lib/codex-payload-adapter.cjs'
+              ),
+            },
+          ],
         },
         {
           matcher: '^(Bash)$',
-          command: 'node ./.codex/hooks/lib/codex-payload-adapter.cjs credential-scan.cjs',
+          hooks: [
+            {
+              type: 'command',
+              command: rootCommand(
+                'node ./.codex/hooks/lib/codex-payload-adapter.cjs privacy-block.cjs',
+                projectRoot,
+                'lib/codex-payload-adapter.cjs'
+              ),
+            },
+          ],
         },
       ],
     },
@@ -68,16 +113,29 @@ function buildHookBlocks() {
       items: [
         {
           matcher: '^(apply_patch)$',
-          command: 'node ./.codex/hooks/lib/codex-payload-adapter.cjs comment-replacement.cjs',
+          hooks: [
+            {
+              type: 'command',
+              command: rootCommand(
+                'node ./.codex/hooks/lib/codex-payload-adapter.cjs comment-replacement.cjs',
+                projectRoot,
+                'lib/codex-payload-adapter.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',
+          matcher: '^(apply_patch)$',
+          hooks: [
+            {
+              type: 'command',
+              command: rootCommand(
+                'node ./.codex/hooks/lib/codex-payload-adapter.cjs test-match.cjs',
+                projectRoot,
+                'lib/codex-payload-adapter.cjs'
+              ),
+            },
+          ],
         },
       ],
     },
@@ -86,20 +144,116 @@ function buildHookBlocks() {
       items: [
         {
           matcher: 'clear',
-          command: 'node ./.codex/hooks/session-init.cjs',
+          hooks: [
+            {
+              type: 'command',
+              command: rootCommand(
+                'node ./.codex/hooks/session-init.cjs',
+                projectRoot,
+                'session-init.cjs'
+              ),
+            },
+          ],
+        },
+      ],
+    },
+    'hooks.Stop': {
+      __type: 'array',
+      items: [
+        {
+          hooks: [
+            {
+              type: 'command',
+              command: rootCommand(
+                'node ./.codex/hooks/wiki-update-reminder.cjs',
+                projectRoot,
+                'wiki-update-reminder.cjs'
+              ),
+              statusMessage: 'Checking wiki update reminder',
+              timeout: 10,
+            },
+          ],
         },
       ],
     },
   };
 }
 
+function scalarKeys(obj) {
+  return Object.keys(obj)
+    .filter(k => k !== 'hooks' && k !== '__leadingComments')
+    .sort((a, b) => {
+      const priority = ['matcher'];
+      const ai = priority.includes(a) ? priority.indexOf(a) : priority.length;
+      const bi = priority.includes(b) ? priority.indexOf(b) : priority.length;
+      if (ai !== bi) return ai - bi;
+      return a < b ? -1 : a > b ? 1 : 0;
+    });
+}
+
+function handlerKeys(obj) {
+  return Object.keys(obj)
+    .filter(k => k !== '__leadingComments')
+    .sort((a, b) => {
+      const priority = ['command', 'type'];
+      const ai = priority.includes(a) ? priority.indexOf(a) : priority.length;
+      const bi = priority.includes(b) ? priority.indexOf(b) : priority.length;
+      if (ai !== bi) return ai - bi;
+      return a < b ? -1 : a > b ? 1 : 0;
+    });
+}
+
+function sortHookItems(items) {
+  return Array.from(items).sort((a, b) => {
+    const am = String(a.matcher ?? '');
+    const bm = String(b.matcher ?? '');
+    if (am !== bm) return am < bm ? -1 : 1;
+    const ac = String(a.hooks?.[0]?.command ?? '');
+    const bc = String(b.hooks?.[0]?.command ?? '');
+    return ac < bc ? -1 : ac > bc ? 1 : 0;
+  });
+}
+
+function emitHookGroups(key, items) {
+  const chunks = [];
+  for (const group of sortHookItems(items)) {
+    const lines = [];
+
+    if (group.__leadingComments) {
+      for (const line of group.__leadingComments.split('\n')) {
+        lines.push(line);
+      }
+    }
+
+    lines.push(`[[${key}]]`);
+    for (const scalarKey of scalarKeys(group)) {
+      lines.push(`${scalarKey} = ${emitScalar(group[scalarKey])}`);
+    }
+
+    for (const hook of group.hooks || []) {
+      if (hook.__leadingComments) {
+        for (const line of hook.__leadingComments.split('\n')) {
+          lines.push(line);
+        }
+      }
+      lines.push(`[[${key}.hooks]]`);
+      for (const hookKey of handlerKeys(hook)) {
+        lines.push(`${hookKey} = ${emitScalar(hook[hookKey])}`);
+      }
+    }
+
+    chunks.push(lines.join('\n'));
+  }
+  return chunks.join('\n') + '\n';
+}
+
 /**
  * Copy `.claude/hooks/` tree to `.codex/hooks/`.
  * @param {string} projectRoot
  */
-function copyHooksTree(projectRoot) {
+function copyHooksTree(projectRoot, outputDir) {
   const src = join(projectRoot, '.claude', 'hooks');
-  const dest = join(projectRoot, '.codex', 'hooks');
+  const dest = join(outputDir, 'hooks');
 
   if (!existsSync(src)) {
     return; // Nothing to copy
@@ -127,17 +281,18 @@ function copyHooksTree(projectRoot) {
  * Build TOML document string for the Codex hooks config.
  * @returns {string}
  */
-function buildToml() {
-  const hookBlocks = buildHookBlocks();
+function buildToml(projectRoot = PACKAGE_ROOT) {
+  const hookBlocks = buildHookBlocks(projectRoot);
 
   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),
+    emitHookGroups('hooks.PreToolUse', hookBlocks['hooks.PreToolUse'].items),
+    emitHookGroups('hooks.PostToolUse', hookBlocks['hooks.PostToolUse'].items),
+    emitHookGroups('hooks.SessionStart', hookBlocks['hooks.SessionStart'].items),
+    emitHookGroups('hooks.Stop', hookBlocks['hooks.Stop'].items),
   ];
 
   return parts.join('\n');
@@ -172,20 +327,20 @@ export async function convertHooksToCodex(opts = {}) {
   }
 
   // Count emitted hooks
-  const hookBlocks = buildHookBlocks();
+  const hookBlocks = buildHookBlocks(projectRoot);
   let added = 0;
   for (const section of Object.values(hookBlocks)) {
     if (section.__type === 'array') {
-      added += section.items.length;
+      added += section.items.reduce((sum, item) => sum + (item.hooks || []).length, 0);
     }
   }
 
   // Copy hooks tree
-  copyHooksTree(projectRoot);
+  copyHooksTree(projectRoot, outputDir);
 
   // Write config.toml
   mkdirSync(outputDir, { recursive: true });
-  const tomlContent = buildToml();
+  const tomlContent = buildToml(projectRoot);
   writeFileSync(join(outputDir, 'config.toml'), tomlContent, 'utf-8');
 
   return { added, dropped, warnings };

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

@@ -147,6 +147,113 @@ function transformFrontmatter(content, map) {
   return `---\n${normalizedFm}---\n${body}`;
 }
 
+// ---------------------------------------------------------------------------
+// AskUserQuestion semantic rewrite for Codex
+// ---------------------------------------------------------------------------
+
+/**
+ * The gate section injected into every converted .md file that contains
+ * AskUserQuestion calls. Placed after the closing `---` frontmatter delimiter
+ * for SKILL.md files, or at the start of the file for reference files.
+ */
+const CODEX_GATE_SECTION = `## Codex Interaction Gates
+This skill was converted from Claude Code. Treat every \`AskUserQuestion(...)\` block below as a blocking Codex prompt gate:
+- Render the question, header, and options in normal chat.
+- Stop immediately after presenting the prompt.
+- Wait for the user's next reply before continuing.
+- Do not proceed to later phases until the answer is available.
+- If running in a non-interactive or sub-agent context, use the fallback stated near the prompt.
+`;
+
+/**
+ * Rewrite AskUserQuestion prose phrases outside fenced blocks.
+ * Works line-by-line to track fence state, leaving content inside
+ * triple-backtick fences byte-for-byte unchanged.
+ *
+ * Rewrites applied outside fences:
+ *   "Use AskUserQuestion to"  →  "Use a Codex prompt gate to"
+ *   "If AskUserQuestion unavailable"  →  "If running non-interactively (Codex sub-agent context)"
+ *
+ * @param {string} content  Raw Markdown content
+ * @returns {string}        Rewritten content
+ */
+function rewritePromptGatePhrases(content) {
+  const lines = content.split('\n');
+  let inFence = false;
+  const result = [];
+  for (const line of lines) {
+    // Detect fence boundaries: a line starting with ``` toggles fence state.
+    if (/^```/.test(line)) {
+      inFence = !inFence;
+      result.push(line);
+      continue;
+    }
+    if (inFence) {
+      result.push(line);
+      continue;
+    }
+    // Apply prose rewrites only outside fences.
+    let rewritten = line
+      .replace(/Use AskUserQuestion to/g, 'Use a Codex prompt gate to')
+      .replace(/If AskUserQuestion unavailable/g, 'If running non-interactively (Codex sub-agent context)');
+    result.push(rewritten);
+  }
+  return result.join('\n');
+}
+
+/**
+ * Inject the `## Codex Interaction Gates` section exactly once.
+ *
+ * Injection location:
+ *   - Files with YAML frontmatter (starting with `---`): injected immediately
+ *     after the closing `---\n` delimiter.
+ *   - Files without frontmatter (reference files): injected at the start.
+ *
+ * Idempotent: if the section is already present, returns content unchanged.
+ *
+ * @param {string} content  Raw Markdown content
+ * @returns {string}        Content with gate section injected (exactly once)
+ */
+function injectCodexGateSection(content) {
+  // Idempotency guard. Flat includes is safe here: '## Codex Interaction Gates' is only ever
+  // emitted by this function, never present in source .claude/skills/ files, so a fenced-block
+  // false-positive is impossible in practice.
+  if (content.includes('## Codex Interaction Gates')) {
+    return content;
+  }
+
+  // Has frontmatter: inject after closing `---`.
+  if (/^---\r?\n/.test(content)) {
+    // Find the position right after the closing `---` + newline.
+    const closingRe = /^---\r?\n([\s\S]*?)\r?\n---\r?\n/;
+    const m = content.match(closingRe);
+    if (m) {
+      const insertAt = m[0].length;
+      return content.slice(0, insertAt) + CODEX_GATE_SECTION + '\n' + content.slice(insertAt);
+    }
+  }
+
+  // No frontmatter: inject at start.
+  return CODEX_GATE_SECTION + '\n' + content;
+}
+
+/**
+ * Full AskUserQuestion rewrite pipeline for a single Markdown file:
+ *   1. If the content contains no `AskUserQuestion`, return unchanged.
+ *   2. Inject the `## Codex Interaction Gates` section (idempotent).
+ *   3. Rewrite prose phrases outside fenced blocks.
+ *
+ * @param {string} content  Raw Markdown content
+ * @returns {string}        Transformed content
+ */
+function rewriteAskUserQuestionForCodex(content) {
+  if (!content.includes('AskUserQuestion')) {
+    return content;
+  }
+  const withGate = injectCodexGateSection(content);
+  return rewritePromptGatePhrases(withGate);
+}
+
 // ---------------------------------------------------------------------------
 // Post-copy rewrite walk
 // ---------------------------------------------------------------------------
@@ -159,6 +266,9 @@ function transformFrontmatter(content, map) {
  * Reads each file, applies `rewriteKitPaths`, and writes back only when the
  * content actually changes (avoids touching mtimes unnecessarily).
  *
+ * For `.md` files, also applies `rewriteAskUserQuestionForCodex` to inject
+ * Codex interaction gates and rewrite prose AskUserQuestion references.
+ *
  * @param {string} dir  Absolute path to walk
  */
 const _REWRITE_EXTS = new Set(['.md', '.js', '.cjs', '.mjs', '.ts', '.py']);
@@ -177,7 +287,11 @@ function walkAndRewriteMarkdown(dir) {
     } else if (entry.isFile() && _REWRITE_EXTS.has(extname(entry.name).toLowerCase())) {
       try {
         const original = readFileSync(fullPath, 'utf8');
-        const rewritten = rewriteKitPaths(original);
+        let rewritten = rewriteKitPaths(original);
+        // For Markdown files, additionally apply the AskUserQuestion rewrite.
+        if (extname(entry.name).toLowerCase() === '.md') {
+          rewritten = rewriteAskUserQuestionForCodex(rewritten);
+        }
         if (rewritten !== original) {
           writeFileSync(fullPath, rewritten, 'utf8');
         }

package/src/commands/codex.js

@@ -7,7 +7,7 @@
  *   - .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
+ *   - .codex/config.toml   — emitted with [features] 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
@@ -17,6 +17,7 @@
 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 { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
 import { TOOL_DIR_NAME, COPY_FILTER_PATTERNS } from '../lib/constants.js';
@@ -138,6 +139,20 @@ function mirrorDirWithRewrite(srcDir, destDir, opts = {}) {
   walkAndCopy(srcDir, destDir);
 }
 
+/**
+ * Copy agent support references into `.codex/agents/references/` with the same
+ * path rewriting used for workflows. Agent TOML bodies reference these files at
+ * runtime, so the conversion is incomplete without them.
+ *
+ * @param {string} agentsDir
+ * @param {string} agentsOut
+ */
+function mirrorAgentReferences(agentsDir, agentsOut) {
+  const referencesDir = join(agentsDir, 'references');
+  if (!isDirectory(referencesDir)) return;
+  mirrorDirWithRewrite(referencesDir, join(agentsOut, 'references'));
+}
+
 /** Single-syscall directory check (replaces existsSync+statSync double-stat). */
 function isDirectory(p) {
   try { return statSync(p).isDirectory(); } catch { return false; }
@@ -170,6 +185,12 @@ function isDirectory(p) {
  */
 export async function runCodexConversion(options = {}) {
   const { verbose = true } = options;
+  if (options.global && options.cwd) {
+    const msg = 'error: --global cannot be combined with --cwd';
+    console.error(chalk.red(msg));
+    return { exitCode: 1, errors: [msg] };
+  }
+
   // 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.
@@ -186,7 +207,7 @@ export async function runCodexConversion(options = {}) {
     // (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 projectRoot = resolve(options.global ? homedir() : options.cwd || process.cwd());
   const claudeDir = join(projectRoot, TOOL_DIR_NAME);
   const agentsDir = join(claudeDir, 'agents');
   const skillsDir = join(claudeDir, 'skills');
@@ -300,6 +321,8 @@ export async function runCodexConversion(options = {}) {
     return { exitCode: code, errors };
   }
 
+  mirrorAgentReferences(agentsDir, agentsOut);
+
   // 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.

package/src/lib/toml-emit.js

@@ -170,7 +170,7 @@ export function emitArrayOfTables(key, arr) {
  * ```js
  * {
  *   __leadingComments?: string,   // file-level comments, emitted first
- *   features?: { codex_hooks: boolean, ... },  // [features] table, emitted first among sections
+ *   features?: { hooks: boolean, ... },  // [features] table, emitted first among sections
  *   'hooks.PreToolUse'?: { __type: 'array', items: [...] },  // array-of-tables
  *   'hooks.PostToolUse'?: { __type: 'array', items: [...] },
  *   'hooks.SessionStart'?: { __type: 'array', items: [...] },