@khanhcan148/mk 0.1.20 → 0.1.22

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;
+}

package/src/lib/toml-emit.js

@@ -0,0 +1,219 @@
+/**
+ * toml-emit.js — Inline TOML serialiser (no @iarna/toml runtime dependency).
+ *
+ * Scope: top-level table + array-of-tables ([[key]]) + string + boolean + number.
+ * Does NOT support inline arrays of mixed types or nested tables beyond
+ * array-of-tables — throws a TypeError for unsupported shapes.
+ *
+ * Hard constraints met:
+ *   HC #2: no @iarna/toml runtime import.
+ *   HC #4: in-table key order = matcher first, command second, remaining lex-sorted.
+ *          Array-of-tables blocks sorted by (matcher, command) lex.
+ *           Always uses Array.from(...).sort() — never raw Object.keys iteration.
+ *
+ * @iarna/toml remains a devDep used ONLY in test round-trip assertions.
+ */
+
+/**
+ * Escape a raw string value to a TOML basic-string literal (without wrapping quotes).
+ * Handles TOML 1.0 required escapes: \\ \" \b \f \n \r \t \uXXXX for control chars.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+function escapeString(s) {
+  let out = '';
+  for (let i = 0; i < s.length; i++) {
+    const ch = s[i];
+    const cp = s.charCodeAt(i);
+    if (ch === '\\') { out += '\\\\'; }
+    else if (ch === '"') { out += '\\"'; }
+    else if (ch === '\b') { out += '\\b'; }
+    else if (ch === '\f') { out += '\\f'; }
+    else if (ch === '\n') { out += '\\n'; }
+    else if (ch === '\r') { out += '\\r'; }
+    else if (ch === '\t') { out += '\\t'; }
+    else if (cp < 0x20 || cp === 0x7f) {
+      out += '\\u' + cp.toString(16).padStart(4, '0');
+    } else {
+      out += ch;
+    }
+  }
+  return out;
+}
+
+/**
+ * Emit a scalar value as a TOML RHS token.
+ *
+ * @param {string|boolean|number|null|undefined} val
+ * @returns {string}
+ */
+export function emitScalar(val) {
+  if (val === null || val === undefined) {
+    throw new TypeError(`[toml-emit] null/undefined is not a valid TOML scalar`);
+  }
+  if (typeof val === 'boolean') return val ? 'true' : 'false';
+  if (typeof val === 'number') return String(val);
+  if (typeof val === 'string') return `"${escapeString(val)}"`;
+  throw new TypeError(`[toml-emit] Unsupported scalar type: ${typeof val} (${String(val)})`);
+}
+
+/**
+ * Sort keys in the canonical order:
+ *   1. matcher (first)
+ *   2. command (second)
+ *   3. all other keys, lexicographically sorted
+ *
+ * @param {string[]} keys
+ * @returns {string[]}
+ */
+function sortKeys(keys) {
+  const filtered = Array.from(keys).filter(k => k !== '__leadingComments');
+  const priority = ['matcher', 'command'];
+  const fixed = priority.filter(k => filtered.includes(k));
+  const rest = Array.from(filtered)
+    .filter(k => !priority.includes(k))
+    .sort((a, b) => a < b ? -1 : a > b ? 1 : 0);
+  return [...fixed, ...rest];
+}
+
+/**
+ * Emit a TOML table section: `[key]` header + key=value lines.
+ *
+ * Respects `__leadingComments` synthetic key: if present, emits those comment
+ * lines (verbatim) before the section header; the key itself is NOT emitted.
+ *
+ * @param {string} key   Section header name (e.g. "features", "hooks.PreToolUse")
+ * @param {object} obj   Key-value pairs; values must be scalars.
+ * @returns {string}
+ */
+export function emitTable(key, obj) {
+  const lines = [];
+
+  if (obj.__leadingComments) {
+    for (const line of obj.__leadingComments.split('\n')) {
+      lines.push(line);
+    }
+  }
+
+  lines.push(`[${key}]`);
+
+  for (const k of sortKeys(Object.keys(obj))) {
+    const v = obj[k];
+    if (typeof v === 'object' && v !== null) {
+      throw new TypeError(
+        `[toml-emit] emitTable does not support nested objects. Key "${k}" in table "${key}" ` +
+        `has type object. Use emitArrayOfTables for array-of-tables sections.`
+      );
+    }
+    lines.push(`${k} = ${emitScalar(v)}`);
+  }
+
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Emit an array-of-tables section: multiple `[[key]]` blocks.
+ *
+ * Each block is sorted by `(matcher, command)` lex before emission.
+ * Within each block, key order follows the canonical sort: matcher, command, rest lex.
+ *
+ * @param {string} key    Section header name (e.g. "hooks.PreToolUse")
+ * @param {object[]} arr  Array of objects; each object is one [[key]] block.
+ * @returns {string}
+ */
+export function emitArrayOfTables(key, arr) {
+  // Sort by (matcher, command) — both fields optional but present in hooks usage
+  const sorted = Array.from(arr).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.command ?? '');
+    const bc = String(b.command ?? '');
+    return ac < bc ? -1 : ac > bc ? 1 : 0;
+  });
+
+  const chunks = [];
+  for (const block of sorted) {
+    const lines = [];
+
+    // Block-level leading comment
+    if (block.__leadingComments) {
+      for (const line of block.__leadingComments.split('\n')) {
+        lines.push(line);
+      }
+    }
+
+    lines.push(`[[${key}]]`);
+
+    for (const k of sortKeys(Object.keys(block))) {
+      const v = block[k];
+      if (typeof v === 'object' && v !== null) {
+        throw new TypeError(
+          `[toml-emit] emitArrayOfTables does not support nested objects. ` +
+          `Key "${k}" in [[${key}]] has type object.`
+        );
+      }
+      lines.push(`${k} = ${emitScalar(v)}`);
+    }
+
+    chunks.push(lines.join('\n'));
+  }
+
+  return chunks.join('\n') + '\n';
+}
+
+/**
+ * Emit a complete TOML document from a structured descriptor object.
+ *
+ * Document descriptor shape:
+ * ```js
+ * {
+ *   __leadingComments?: string,   // file-level comments, emitted first
+ *   features?: { codex_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: [...] },
+ *   // other plain table keys
+ * }
+ * ```
+ *
+ * Emission order:
+ *   1. File-level `__leadingComments`
+ *   2. `[features]` block (if present)
+ *   3. All other sections in insertion order (caller controls order)
+ *
+ * @param {object} doc
+ * @returns {string}
+ */
+export function emitToml(doc) {
+  const parts = [];
+
+  // File-level leading comments
+  if (doc.__leadingComments) {
+    parts.push(doc.__leadingComments + '\n');
+  }
+
+  // [features] always first among sections
+  if (doc.features) {
+    parts.push(emitTable('features', doc.features));
+  }
+
+  // Remaining sections in iteration order (caller sorts)
+  for (const key of Object.keys(doc)) {
+    if (key === '__leadingComments' || key === 'features') continue;
+
+    const val = doc[key];
+    if (val && typeof val === 'object' && val.__type === 'array') {
+      parts.push(emitArrayOfTables(key, val.items));
+    } else if (val && typeof val === 'object') {
+      parts.push(emitTable(key, val));
+    } else {
+      throw new TypeError(
+        `[toml-emit] Unsupported document-level value for key "${key}": expected object or array-descriptor`
+      );
+    }
+  }
+
+  return parts.join('\n');
+}