@hegemonart/get-design-done 1.25.0 → 1.26.0

package/scripts/lib/install/parse-runtime-models.cjs

@@ -0,0 +1,267 @@
+'use strict';
+/**
+ * parse-runtime-models.cjs — pure parser for reference/runtime-models.md.
+ *
+ * Reads the per-runtime tier→model adapter source-of-truth (Phase 26 D-01..D-03)
+ * and returns a structured object with one entry per runtime. Used by:
+ *
+ *   - scripts/lib/install/installer.cjs (26-03) at install time to emit
+ *     `models.json` per runtime config-dir.
+ *   - scripts/lib/tier-resolver.cjs (26-02) at runtime to resolve
+ *     (runtime, tier) → model.
+ *
+ * Pure-JS validation against the strict schema at
+ * `reference/schemas/runtime-models.schema.json`. No optional dependencies.
+ *
+ * Public API:
+ *   parseRuntimeModels({ cwd? }) → {
+ *     runtimes: [{ id, tier_to_model, reasoning_class_to_model, provenance, single_tier? }, ...],
+ *     schema_version: 1
+ *   }
+ *   parseRuntimeModelsFromString(markdown) → same shape
+ *
+ * Throws an Error with a specific message on the first validation failure
+ * (fail-fast: install-time validation catches typos before runtime).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const DEFAULT_PATH = path.join(REPO_ROOT, 'reference', 'runtime-models.md');
+
+// Mirrors scripts/lib/install/runtimes.cjs RUNTIMES list (Phase 24 D-02 lock).
+// Re-declared rather than imported to keep this parser dependency-free for
+// downstream consumers that may want to call it from outside the install/ tree.
+// Round-trip tested by tests/parse-runtime-models.test.cjs against the canonical
+// runtimes.cjs list.
+const KNOWN_RUNTIME_IDS = Object.freeze([
+  'claude',
+  'codex',
+  'gemini',
+  'qwen',
+  'kilo',
+  'copilot',
+  'cursor',
+  'windsurf',
+  'antigravity',
+  'augment',
+  'trae',
+  'codebuddy',
+  'cline',
+  'opencode',
+]);
+
+const TIER_KEYS = Object.freeze(['opus', 'sonnet', 'haiku']);
+const REASONING_CLASS_KEYS = Object.freeze(['high', 'medium', 'low']);
+
+/**
+ * Extract every ```json ... ``` fenced block from a markdown string.
+ * Returns an array of { raw, lineNumber } objects.
+ */
+function extractJsonBlocks(markdown) {
+  const blocks = [];
+  const re = /```json\s*\n([\s\S]*?)\n```/g;
+  let m;
+  while ((m = re.exec(markdown)) !== null) {
+    // Compute 1-indexed line number of the fence opening for error messages.
+    const lineNumber = markdown.slice(0, m.index).split('\n').length;
+    blocks.push({ raw: m[1], lineNumber });
+  }
+  return blocks;
+}
+
+function validateModelRow(row, where) {
+  if (!row || typeof row !== 'object' || Array.isArray(row)) {
+    throw new Error(`${where}: expected object, got ${typeof row}`);
+  }
+  if (typeof row.model !== 'string' || row.model.length === 0) {
+    throw new Error(`${where}: 'model' must be a non-empty string`);
+  }
+  const allowedKeys = new Set(['model', 'provider_model_id']);
+  for (const k of Object.keys(row)) {
+    if (!allowedKeys.has(k)) {
+      throw new Error(`${where}: unknown key '${k}' (allowed: ${[...allowedKeys].join(', ')})`);
+    }
+  }
+  if (row.provider_model_id !== undefined) {
+    if (typeof row.provider_model_id !== 'string' || row.provider_model_id.length === 0) {
+      throw new Error(`${where}: 'provider_model_id' must be a non-empty string when present`);
+    }
+  }
+}
+
+function validateProvenance(arr, where) {
+  if (!Array.isArray(arr) || arr.length < 1) {
+    throw new Error(`${where}: 'provenance' must be a non-empty array`);
+  }
+  arr.forEach((row, i) => {
+    const w = `${where}[${i}]`;
+    if (!row || typeof row !== 'object' || Array.isArray(row)) {
+      throw new Error(`${w}: expected object`);
+    }
+    for (const required of ['source_url', 'retrieved_at', 'last_validated_cycle']) {
+      if (typeof row[required] !== 'string' || row[required].length === 0) {
+        throw new Error(`${w}: '${required}' must be a non-empty string`);
+      }
+    }
+    // ISO-8601 sanity check (Date.parse accepts the canonical form we emit).
+    if (Number.isNaN(Date.parse(row.retrieved_at))) {
+      throw new Error(`${w}: 'retrieved_at' must be a valid ISO 8601 timestamp (got ${JSON.stringify(row.retrieved_at)})`);
+    }
+    const allowedKeys = new Set(['source_url', 'retrieved_at', 'last_validated_cycle', 'note']);
+    for (const k of Object.keys(row)) {
+      if (!allowedKeys.has(k)) {
+        throw new Error(`${w}: unknown key '${k}' (allowed: ${[...allowedKeys].join(', ')})`);
+      }
+    }
+    if (row.note !== undefined && typeof row.note !== 'string') {
+      throw new Error(`${w}: 'note' must be a string when present`);
+    }
+  });
+}
+
+function validateRuntimeEntry(entry, where) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+    throw new Error(`${where}: expected object`);
+  }
+  // Required keys
+  for (const required of ['id', 'tier_to_model', 'reasoning_class_to_model', 'provenance']) {
+    if (!(required in entry)) {
+      throw new Error(`${where}: missing required key '${required}'`);
+    }
+  }
+  // id enum check
+  if (typeof entry.id !== 'string' || !KNOWN_RUNTIME_IDS.includes(entry.id)) {
+    throw new Error(
+      `${where}: 'id' must be one of ${KNOWN_RUNTIME_IDS.join('|')} (got ${JSON.stringify(entry.id)})`,
+    );
+  }
+  // No unknown top-level keys
+  const allowedKeys = new Set(['id', 'single_tier', 'tier_to_model', 'reasoning_class_to_model', 'provenance']);
+  for (const k of Object.keys(entry)) {
+    if (!allowedKeys.has(k)) {
+      throw new Error(`${where}: unknown key '${k}' (allowed: ${[...allowedKeys].join(', ')})`);
+    }
+  }
+  if (entry.single_tier !== undefined && typeof entry.single_tier !== 'boolean') {
+    throw new Error(`${where}: 'single_tier' must be a boolean when present`);
+  }
+
+  // tier_to_model: requires opus/sonnet/haiku
+  if (!entry.tier_to_model || typeof entry.tier_to_model !== 'object' || Array.isArray(entry.tier_to_model)) {
+    throw new Error(`${where}.tier_to_model: expected object`);
+  }
+  for (const tier of TIER_KEYS) {
+    if (!(tier in entry.tier_to_model)) {
+      throw new Error(`${where}.tier_to_model: missing required tier '${tier}'`);
+    }
+  }
+  for (const k of Object.keys(entry.tier_to_model)) {
+    if (!TIER_KEYS.includes(k)) {
+      throw new Error(`${where}.tier_to_model: unknown tier '${k}' (allowed: ${TIER_KEYS.join('|')})`);
+    }
+    validateModelRow(entry.tier_to_model[k], `${where}.tier_to_model.${k}`);
+  }
+
+  // reasoning_class_to_model: requires high/medium/low
+  if (!entry.reasoning_class_to_model || typeof entry.reasoning_class_to_model !== 'object' || Array.isArray(entry.reasoning_class_to_model)) {
+    throw new Error(`${where}.reasoning_class_to_model: expected object`);
+  }
+  for (const klass of REASONING_CLASS_KEYS) {
+    if (!(klass in entry.reasoning_class_to_model)) {
+      throw new Error(`${where}.reasoning_class_to_model: missing required class '${klass}'`);
+    }
+  }
+  for (const k of Object.keys(entry.reasoning_class_to_model)) {
+    if (!REASONING_CLASS_KEYS.includes(k)) {
+      throw new Error(`${where}.reasoning_class_to_model: unknown class '${k}' (allowed: ${REASONING_CLASS_KEYS.join('|')})`);
+    }
+    validateModelRow(entry.reasoning_class_to_model[k], `${where}.reasoning_class_to_model.${k}`);
+  }
+
+  validateProvenance(entry.provenance, `${where}.provenance`);
+}
+
+function parseRuntimeModelsFromString(markdown, sourceLabel) {
+  const label = sourceLabel || '<runtime-models markdown>';
+  if (typeof markdown !== 'string' || markdown.length === 0) {
+    throw new Error(`${label}: empty or non-string input`);
+  }
+
+  const blocks = extractJsonBlocks(markdown);
+  if (blocks.length < 2) {
+    // We expect at least the schema-version block + 1 runtime block.
+    throw new Error(`${label}: expected at least one schema-version block and one runtime block, found ${blocks.length} fenced json blocks`);
+  }
+
+  // First block MUST be the { "$schema_version": <int> } header.
+  let schemaVersion = null;
+  let firstParsed;
+  try {
+    firstParsed = JSON.parse(blocks[0].raw);
+  } catch (err) {
+    throw new Error(`${label}: first json block (line ${blocks[0].lineNumber}) failed to parse: ${err.message}`);
+  }
+  if (
+    !firstParsed ||
+    typeof firstParsed !== 'object' ||
+    Array.isArray(firstParsed) ||
+    !('$schema_version' in firstParsed) ||
+    Object.keys(firstParsed).length !== 1
+  ) {
+    throw new Error(`${label}: first json block (line ${blocks[0].lineNumber}) must be { "$schema_version": <int> } and nothing else`);
+  }
+  if (firstParsed.$schema_version !== 1) {
+    throw new Error(
+      `${label}: $schema_version must be 1 (got ${JSON.stringify(firstParsed.$schema_version)}). Bump the parser when the schema breaks forward.`,
+    );
+  }
+  schemaVersion = firstParsed.$schema_version;
+
+  // Remaining blocks are runtime entries.
+  const runtimes = [];
+  const seenIds = new Set();
+  for (let i = 1; i < blocks.length; i++) {
+    const block = blocks[i];
+    let parsed;
+    try {
+      parsed = JSON.parse(block.raw);
+    } catch (err) {
+      throw new Error(`${label}: json block at line ${block.lineNumber} failed to parse: ${err.message}`);
+    }
+    const where = `${label}#runtimes[${i - 1}] (line ${block.lineNumber})`;
+    validateRuntimeEntry(parsed, where);
+    if (seenIds.has(parsed.id)) {
+      throw new Error(`${where}: duplicate runtime id '${parsed.id}' (already seen earlier in the file)`);
+    }
+    seenIds.add(parsed.id);
+    runtimes.push(parsed);
+  }
+
+  return { schema_version: schemaVersion, runtimes };
+}
+
+function parseRuntimeModels({ cwd } = {}) {
+  const filePath = cwd ? path.join(cwd, 'reference', 'runtime-models.md') : DEFAULT_PATH;
+  let markdown;
+  try {
+    markdown = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    const wrapped = new Error(
+      `parse-runtime-models: cannot read ${filePath}\n  ${err.message}`,
+    );
+    wrapped.code = 'EPARSE_RUNTIME_MODELS_READ';
+    wrapped.path = filePath;
+    throw wrapped;
+  }
+  return parseRuntimeModelsFromString(markdown, filePath);
+}
+
+module.exports = {
+  parseRuntimeModels,
+  parseRuntimeModelsFromString,
+  KNOWN_RUNTIME_IDS,
+  TIER_KEYS,
+  REASONING_CLASS_KEYS,
+};

package/scripts/lib/install/runtimes.cjs

@@ -161,6 +161,47 @@ function listRuntimeIds() {
   return RUNTIMES.map((r) => r.id);
 }
 
+// Phase 26 D-06 — `tier_to_model` lookup helper.
+//
+// `getRuntimeModels(runtimeId, { cwd? })` resolves the per-runtime tier→model
+// adapter from `reference/runtime-models.md` via `parse-runtime-models.cjs`.
+// Returns `null` when the runtime has no entry in runtime-models.md (i.e.,
+// the data source ships rows for fewer than 14 runtimes during the rolling
+// research tail described in CONTEXT D-02). Caller is responsible for
+// degrading gracefully (e.g., installer skips models.json emission when null).
+//
+// The parsed payload is cached per `cwd` to avoid re-reading the markdown
+// on each runtime in a multi-runtime install loop.
+
+const _modelsCache = new Map();
+
+function getParsedRuntimeModels(opts) {
+  const cwd = (opts && opts.cwd) || null;
+  const cacheKey = cwd || '<default>';
+  if (_modelsCache.has(cacheKey)) return _modelsCache.get(cacheKey);
+  // Lazy require avoids a hard dep cycle if runtimes.cjs is imported in
+  // contexts that don't ship the reference/ tree (theoretical — not used today).
+  const { parseRuntimeModels } = require('./parse-runtime-models.cjs');
+  const parsed = parseRuntimeModels(cwd ? { cwd } : {});
+  _modelsCache.set(cacheKey, parsed);
+  return parsed;
+}
+
+function getRuntimeModels(runtimeId, opts) {
+  // Validate the runtime id up-front — this catches typos in the installer
+  // entry rather than silently returning null for "claud" vs "claude".
+  getRuntime(runtimeId);
+  const parsed = getParsedRuntimeModels(opts);
+  const entry = parsed.runtimes.find((r) => r.id === runtimeId);
+  return entry || null;
+}
+
+// Test-only hook: drop the cached parse result. Used by tests that mutate
+// the source markdown between assertions.
+function _resetRuntimeModelsCache() {
+  _modelsCache.clear();
+}
+
 module.exports = {
   RUNTIMES,
   REPO,
@@ -169,4 +210,6 @@ module.exports = {
   getRuntime,
   listRuntimes,
   listRuntimeIds,
+  getRuntimeModels,
+  _resetRuntimeModelsCache,
 };

package/scripts/lib/runtime-detect.cjs

@@ -0,0 +1,96 @@
+// scripts/lib/runtime-detect.cjs
+//
+// Plan 26-02 — runtime detection from env-vars.
+//
+// Identifies which AI-coding-CLI host process the current Node script is
+// running inside, by reading the same `*_CONFIG_DIR` / `*_HOME` env-vars
+// the Phase 24 installer uses to decide where to drop runtime files.
+//
+// The env-var → runtime-ID mapping is owned by Phase 24's
+// `scripts/lib/install/runtimes.cjs`. This module imports `RUNTIMES` from
+// there and derives the lookup table — DO NOT duplicate the mapping
+// (D-05). Adding a new runtime to runtimes.cjs automatically extends
+// detection here.
+//
+// Lookup order is the runtimes.cjs declaration order. When a host
+// happens to set multiple env-vars (e.g. a parent CLI spawns a child CLI
+// and inherits env), the first-declared runtime wins. Phase 24's order
+// puts Claude Code first, then OpenCode, Gemini, Kilo, Codex, …; that's
+// also the order this module returns for ambiguous hosts.
+//
+// Pure module — no top-level side effects. Reads `process.env` only when
+// `detect()` is called. Returns null when no recognized env-var is set
+// (e.g. running tests in CI matrix, or a bare Node script invoked outside
+// any of the 14 runtime hosts).
+//
+// `.cjs` extension matches existing Phase 22 primitives and lets both
+// `.cjs` callers and `.ts` callers (under --experimental-strip-types)
+// require it without ESM-interop friction.
+
+'use strict';
+
+const { RUNTIMES } = require('./install/runtimes.cjs');
+
+/**
+ * Build the env-var → runtime-ID lookup map at module load. Frozen so
+ * accidental mutation by callers can't drift the map away from the
+ * Phase 24 source of truth.
+ *
+ * Shape: `[{ env: 'CLAUDE_CONFIG_DIR', id: 'claude' }, …]` — array of
+ * pairs to preserve declaration order from RUNTIMES (Map / Object key
+ * order is guaranteed by spec but the array form documents intent).
+ */
+const ENV_TO_RUNTIME = Object.freeze(
+  RUNTIMES.map((r) => Object.freeze({ env: r.configDirEnv, id: r.id })),
+);
+
+/**
+ * Detect which runtime host the current process is running inside, by
+ * scanning `process.env` for the runtime-ID env-vars in declaration
+ * order and returning the first match.
+ *
+ * The env-var must be a non-empty string to count as set — runtime
+ * harnesses that export an empty value (`CLAUDE_CONFIG_DIR=`) are
+ * treated as unset, since the empty string is not a usable config-dir
+ * path and likely indicates "exported but not assigned".
+ *
+ * @returns {string | null} runtime-ID (e.g. 'claude', 'codex') or null
+ *   when no recognized env-var is set in the current environment.
+ *
+ * @example
+ *   process.env.CLAUDE_CONFIG_DIR = '/Users/me/.claude';
+ *   detect(); // → 'claude'
+ *
+ * @example
+ *   // No runtime env-var set:
+ *   detect(); // → null
+ */
+function detect() {
+  const env = process.env;
+  for (const { env: name, id } of ENV_TO_RUNTIME) {
+    const v = env[name];
+    if (typeof v === 'string' && v.length > 0) {
+      return id;
+    }
+  }
+  return null;
+}
+
+/**
+ * Return the env-var → runtime-ID map as a plain array of pairs. Useful
+ * for diagnostic logging and tests that want to verify the mapping
+ * matches Phase 24 without depending on `runtimes.cjs` internals.
+ *
+ * The returned array is a fresh copy; mutating it has no effect on
+ * future `detect()` calls.
+ *
+ * @returns {Array<{env: string, id: string}>}
+ */
+function envVarMap() {
+  return ENV_TO_RUNTIME.map((p) => ({ env: p.env, id: p.id }));
+}
+
+module.exports = {
+  detect,
+  envVarMap,
+};