refacil-sdd-ai 5.2.3 → 5.3.0

package/lib/commands/compact.js

@@ -1,77 +1,210 @@
 'use strict';
 
 const compactTelemetry = require('../compact/telemetry');
+const codegraphTelemetry = require('../codegraph-telemetry');
 
-function showCompactStats() {
-  const s = compactTelemetry.stats();
-  if (s.totalEvents === 0) {
-    console.log('\n  No hay eventos registrados todavia. Ejecuta comandos Bash para generar telemetria de compactacion.\n');
-    return;
+const USD_PER_MTOK = 3;
+
+function formatUsd(tokens) {
+  return ((tokens / 1_000_000) * USD_PER_MTOK).toFixed(2);
+}
+
+function formatK(tokens) {
+  return (tokens / 1000).toFixed(1);
+}
+
+function parseCompactArgs(argv) {
+  const args = { _positional: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!token) continue;
+    if (!token.startsWith('--')) {
+      args._positional.push(token);
+      continue;
+    }
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) {
+      args[key] = true;
+    } else {
+      args[key] = next;
+      i++;
+    }
   }
+  return args;
+}
 
-  const sortedRewrites = Object.entries(s.byRule)
-    .filter(([, data]) => data.rewriteCount > 0)
-    .sort((a, b) => b[1].rewriteSaved - a[1].rewriteSaved);
-  const sortedAlreadyCompact = Object.entries(s.byRule)
-    .filter(([, data]) => data.alreadyCompactCount > 0)
-    .sort((a, b) => b[1].alreadyCompactPotential - a[1].alreadyCompactPotential);
-
-  console.log(`\n  compact-bash stats\n`);
-  console.log(`  Rewrites por hook: ${s.totalRewrites}`);
-  console.log(`  Comandos ya compactos detectados (skill/agente): ${s.totalAlreadyCompact}\n`);
-
-  if (sortedRewrites.length > 0) {
-    console.log('  Ahorro aplicado por hook (rewrite):');
-    for (const [id, data] of sortedRewrites) {
-      const kTokens = (data.rewriteSaved / 1000).toFixed(1);
+function parseBool(value, defaultValue = false) {
+  if (value === undefined || value === null) return defaultValue;
+  if (value === true) return true;
+  const s = String(value).toLowerCase();
+  if (s === 'true' || s === '1' || s === 'yes') return true;
+  if (s === 'false' || s === '0' || s === 'no') return false;
+  return defaultValue;
+}
+
+function showCodegraphSection(cg) {
+  console.log(`\n  CodeGraph — estimated savings by sub-agent\n`);
+  const sortedSkills = Object.entries(cg.bySkill)
+    .filter(([, data]) => data.withGraph.events > 0)
+    .sort((a, b) => b[1].withGraph.tokensSaved - a[1].withGraph.tokensSaved);
+
+  if (sortedSkills.length > 0) {
+    console.log('  With CodeGraph:');
+    for (const [skillId, data] of sortedSkills) {
+      const kTokens = formatK(data.withGraph.tokensSaved);
       console.log(
-        `    ${id.padEnd(18)} ${String(data.rewriteCount).padStart(6)} rewrites   ~${kTokens.padStart(7)}k tokens`,
+        `    ${skillId.padEnd(18)} ${String(data.withGraph.events).padStart(5)} sessions   ` +
+          `${String(data.withGraph.toolCalls).padStart(5)} tool calls   ~${kTokens.padStart(7)}k tokens saved`,
       );
     }
-    const totalHookK = (s.totalSaved / 1000).toFixed(1);
-    const hookUsd = ((s.totalSaved / 1_000_000) * 3).toFixed(2);
+    const totalCgK = formatK(cg.totalTokensSaved);
+    const totalCgUsd = formatUsd(cg.totalTokensSaved);
     console.log(`    ${'-'.repeat(62)}`);
     console.log(
-      `    ${'Total hook'.padEnd(18)} ${String(s.totalRewrites).padStart(6)} rewrites   ~${totalHookK.padStart(7)}k tokens (~$${hookUsd} USD)`,
+      `    ${'Total CodeGraph'.padEnd(18)} ${String(cg.totalEvents).padStart(5)} events     ` +
+        `${String(cg.totalToolCalls).padStart(5)} tool calls   ~${totalCgK.padStart(7)}k tokens (~$${totalCgUsd} USD)`,
     );
-    console.log('');
   }
 
-  if (sortedAlreadyCompact.length > 0) {
-    console.log('  Ahorro potencial ya capturado por skill/agente (sin rewrite):');
-    for (const [id, data] of sortedAlreadyCompact) {
-      const kTokens = (data.alreadyCompactPotential / 1000).toFixed(1);
+  const withoutGraph = Object.entries(cg.bySkill).filter(
+    ([, data]) => data.withoutGraph.events > 0,
+  );
+  if (withoutGraph.length > 0) {
+    console.log('\n  Sessions without graph (baseline):');
+    for (const [skillId, data] of withoutGraph) {
       console.log(
-        `    ${id.padEnd(18)} ${String(data.alreadyCompactCount).padStart(6)} eventos    ~${kTokens.padStart(7)}k tokens potenciales`,
+        `    ${skillId.padEnd(18)} ${String(data.withoutGraph.events).padStart(5)} sessions`,
       );
     }
-    const totalAgentK = (s.totalAlreadyCompactPotential / 1000).toFixed(1);
-    const agentUsd = ((s.totalAlreadyCompactPotential / 1_000_000) * 3).toFixed(2);
+  }
+
+  console.log(`\n  Log: ${codegraphTelemetry.LOG_PATH}`);
+}
+
+function showCompactStats() {
+  const s = compactTelemetry.stats();
+  const cg = codegraphTelemetry.stats();
+  const hasCompact = s.totalEvents > 0;
+  const hasCg = cg.totalEvents > 0;
+
+  if (!hasCompact && !hasCg) {
+    console.log('\n  No hay eventos registrados todavia.');
+    console.log('  - Bash con hook compact-bash → compact.log');
+    console.log(
+      '  - Tras sub-agentes: refacil-sdd-ai compact log-codegraph-event --skill <id> --has-graph true|false --tool-calls N --tokens N\n',
+    );
+    return;
+  }
+
+  if (hasCompact) {
+    const sortedRewrites = Object.entries(s.byRule)
+      .filter(([, data]) => data.rewriteCount > 0)
+      .sort((a, b) => b[1].rewriteSaved - a[1].rewriteSaved);
+    const sortedAlreadyCompact = Object.entries(s.byRule)
+      .filter(([, data]) => data.alreadyCompactCount > 0)
+      .sort((a, b) => b[1].alreadyCompactPotential - a[1].alreadyCompactPotential);
+
+    console.log(`\n  compact-bash stats\n`);
+    console.log(`  Rewrites por hook: ${s.totalRewrites}`);
+    console.log(`  Comandos ya compactos detectados (skill/agente): ${s.totalAlreadyCompact}\n`);
+
+    if (sortedRewrites.length > 0) {
+      console.log('  Ahorro aplicado por hook (rewrite):');
+      for (const [id, data] of sortedRewrites) {
+        const kTokens = formatK(data.rewriteSaved);
+        console.log(
+          `    ${id.padEnd(18)} ${String(data.rewriteCount).padStart(6)} rewrites   ~${kTokens.padStart(7)}k tokens`,
+        );
+      }
+      const totalHookK = formatK(s.totalSaved);
+      const hookUsd = formatUsd(s.totalSaved);
+      console.log(`    ${'-'.repeat(62)}`);
+      console.log(
+        `    ${'Total hook'.padEnd(18)} ${String(s.totalRewrites).padStart(6)} rewrites   ~${totalHookK.padStart(7)}k tokens (~$${hookUsd} USD)`,
+      );
+      console.log('');
+    }
+
+    if (sortedAlreadyCompact.length > 0) {
+      console.log('  Ahorro potencial ya capturado por skill/agente (sin rewrite):');
+      for (const [id, data] of sortedAlreadyCompact) {
+        const kTokens = formatK(data.alreadyCompactPotential);
+        console.log(
+          `    ${id.padEnd(18)} ${String(data.alreadyCompactCount).padStart(6)} eventos    ~${kTokens.padStart(7)}k tokens potenciales`,
+        );
+      }
+      const totalAgentK = formatK(s.totalAlreadyCompactPotential);
+      const agentUsd = formatUsd(s.totalAlreadyCompactPotential);
+      console.log(`    ${'-'.repeat(62)}`);
+      console.log(
+        `    ${'Total skill'.padEnd(18)} ${String(s.totalAlreadyCompact).padStart(6)} eventos    ~${totalAgentK.padStart(7)}k tokens (~$${agentUsd} USD)`,
+      );
+      console.log('');
+    }
+
+    const compactK = formatK(s.totalObservedPotential);
+    const compactUsd = formatUsd(s.totalObservedPotential);
     console.log(`    ${'-'.repeat(62)}`);
     console.log(
-      `    ${'Total skill'.padEnd(18)} ${String(s.totalAlreadyCompact).padStart(6)} eventos    ~${totalAgentK.padStart(7)}k tokens (~$${agentUsd} USD)`,
+      `    ${'Total compact'.padEnd(18)} ${String(s.totalEvents).padStart(6)} eventos    ~${compactK.padStart(7)}k tokens (~$${compactUsd} USD, Sonnet input)`,
     );
-    console.log('');
+    console.log(`\n  Log: ${compactTelemetry.LOG_PATH}`);
+    if (compactTelemetry.isDisabled()) {
+      console.log('  Estado: DESHABILITADO (no se registran nuevos eventos)');
+    }
   }
 
-  const totalK = (s.totalObservedPotential / 1000).toFixed(1);
-  const totalUsd = ((s.totalObservedPotential / 1_000_000) * 3).toFixed(2);
-  console.log(`    ${'-'.repeat(62)}`);
-  console.log(
-    `    ${'Total observado'.padEnd(18)} ${String(s.totalEvents).padStart(6)} eventos    ~${totalK.padStart(7)}k tokens (~$${totalUsd} USD, Sonnet input)`,
-  );
-  console.log(`\n  Log: ${compactTelemetry.LOG_PATH}`);
-  if (compactTelemetry.isDisabled()) {
-    console.log('  Estado: DESHABILITADO (no se registran nuevos eventos)');
+  if (hasCg) {
+    showCodegraphSection(cg);
+  }
+
+  const grandTotal = s.totalObservedPotential + cg.totalTokensSaved;
+  if (hasCompact && hasCg) {
+    const grandK = formatK(grandTotal);
+    const grandUsd = formatUsd(grandTotal);
+    console.log(`\n    ${'-'.repeat(62)}`);
+    console.log(
+      `    ${'Total combinado'.padEnd(18)} compact + CodeGraph   ~${grandK.padStart(7)}k tokens (~$${grandUsd} USD, Sonnet input)`,
+    );
+  } else if (!hasCompact && hasCg && cg.totalTokensSaved > 0) {
+    const grandK = formatK(grandTotal);
+    const grandUsd = formatUsd(grandTotal);
+    console.log(`\n    ${'-'.repeat(62)}`);
+    console.log(
+      `    ${'Total observado'.padEnd(18)} ${String(cg.totalEvents).padStart(6)} eventos    ~${grandK.padStart(7)}k tokens (~$${grandUsd} USD, Sonnet input)`,
+    );
   }
+
   console.log('');
 }
 
-function handleCompact(sub) {
+function cmdLogCodegraphEvent(argv) {
+  const args = parseCompactArgs(argv);
+  const skillId = args.skill || args._positional[0];
+  if (!skillId) {
+    console.error(
+      '  Uso: refacil-sdd-ai compact log-codegraph-event --skill <id> --has-graph true|false [--tool-calls N] [--tokens N]',
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const hasGraph = parseBool(args['has-graph'], false);
+  const toolCalls = Math.max(0, parseInt(args['tool-calls'] || '0', 10) || 0);
+  const tokens = Math.max(0, parseInt(args.tokens || '0', 10) || 0);
+
+  codegraphTelemetry.logEvent(skillId, hasGraph, toolCalls, tokens);
+}
+
+function handleCompact(sub, argv = []) {
   switch (sub) {
     case 'stats':
       showCompactStats();
       break;
+    case 'log-codegraph-event':
+      cmdLogCodegraphEvent(argv);
+      break;
     case 'disable':
       compactTelemetry.disable();
       console.log('  compact-bash deshabilitado. Reactiva con: refacil-sdd-ai compact enable');
@@ -84,9 +217,15 @@ function handleCompact(sub) {
       compactTelemetry.clearLog();
       console.log('  compact.log limpiado.');
       break;
+    case 'codegraph-clear-log':
+      codegraphTelemetry.clearLog();
+      console.log('  codegraph.log limpiado.');
+      break;
     default:
-      console.log('Uso: refacil-sdd-ai compact <stats|disable|enable|clear-log>');
+      console.log(
+        'Uso: refacil-sdd-ai compact <stats|log-codegraph-event|disable|enable|clear-log|codegraph-clear-log>',
+      );
   }
 }
 
-module.exports = { handleCompact };
+module.exports = { handleCompact, showCompactStats, cmdLogCodegraphEvent };

package/lib/commands/read-spec.js

@@ -0,0 +1,352 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { findProjectRoot } = require('./sdd');
+const { parseFile, extractArtifactLanguageMeta } = require('../spec-reader/md-parser');
+const { artifactLanguageToTtsCode } = require('../spec-reader/lang');
+const { writeSession, writeFolderSession } = require('../spec-reader/session');
+const busSpawn = require('../bus/spawn');
+const { openInBrowser } = require('../open-browser');
+const {
+  resolveDefaultTtsLang,
+  isValidTtsLang,
+  detectTtsLangFromContent,
+  DEFAULT_TTS_LANG,
+} = require('../spec-reader/lang');
+const { loadBranchConfigWithSources } = require('../config');
+
+const DEFAULT_LANG = DEFAULT_TTS_LANG;
+const DEFAULT_VOICE = 'M3';
+const DEFAULT_SPEED = 1;
+const VALID_VOICES = new Set(['M1', 'M2', 'M3', 'M4', 'M5', 'F1', 'F2', 'F3', 'F4', 'F5']);
+
+function parseReadSpecArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (!token || !token.startsWith('--')) continue;
+    const key = token.slice(2);
+    const next = argv[i + 1];
+    if (next === undefined || next.startsWith('--')) {
+      args[key] = true;
+    } else {
+      args[key] = next;
+      i++;
+    }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`
+  read-spec — Listen to a Markdown spec in the browser (on-device TTS)
+
+  Usage:
+    refacil-sdd-ai read-spec --file <path> [options]
+    refacil-sdd-ai read-spec --change <changeName> [--select <file.md>] [options]
+
+  Options:
+    --file <path>          Markdown file (must be inside project root)
+    --change <changeName>  Load all SDD artifacts for a change folder
+    --select <file.md>     Pre-select a specific file in folder mode (default: proposal.md)
+    --lang <code>          TTS language (default: SDD artifactLanguage → es/en)
+    --voice <id>           Voice style M1–M5 or F1–F5 (default: ${DEFAULT_VOICE})
+    --speed <n>            Speech speed 0.9–1.5 (default: ${DEFAULT_SPEED})
+    --help                 Show this help
+`);
+}
+
+/**
+ * @param {string} fileArg
+ * @param {string} projectRoot
+ * @returns {string} absolute path
+ */
+function resolveFileWithinProject(fileArg, projectRoot) {
+  const resolved = path.resolve(projectRoot, fileArg);
+  const rootNorm = path.resolve(projectRoot) + path.sep;
+  if (!resolved.startsWith(rootNorm) && resolved !== path.resolve(projectRoot)) {
+    throw new Error('Security: --file must resolve inside the project root');
+  }
+  return resolved;
+}
+
+/**
+ * Canonical ordering for SDD artifact files in a change folder.
+ * Files not in this list are appended alphabetically after.
+ */
+const FOLDER_FILE_ORDER = ['proposal.md', 'design.md', 'tasks.md', 'specs.md'];
+
+/**
+ * Sort .md filenames: canonical order first, then remaining alphabetically.
+ * @param {string[]} names
+ * @returns {string[]}
+ */
+function sortFolderFiles(names) {
+  const canonical = FOLDER_FILE_ORDER.filter((n) => names.includes(n));
+  const rest = names
+    .filter((n) => !FOLDER_FILE_ORDER.includes(n))
+    .sort((a, b) => a.localeCompare(b));
+  return [...canonical, ...rest];
+}
+
+/**
+ * @param {string[]} argv
+ * @param {string} packageRoot
+ * @param {string} [projectRootOverride]
+ */
+async function handleReadSpec(argv, packageRoot, projectRootOverride) {
+  const args = parseReadSpecArgs(argv || []);
+  if (args.help) {
+    printHelp();
+    process.exit(0);
+  }
+
+  // Mutual exclusivity: --change and --file cannot be used together
+  if (args.change && args.file) {
+    console.error('  Error: --change y --file son mutuamente excluyentes. Usa solo uno de los dos.');
+    process.exit(1);
+  }
+
+  // Neither --change nor --file provided
+  if (!args.change && !args.file) {
+    console.error('  Error: --file is required');
+    printHelp();
+    process.exit(1);
+  }
+
+  const projectRoot = projectRootOverride || findProjectRoot();
+
+  // -----------------------------------------------------------------------
+  // FOLDER MODE: --change <changeName>
+  // -----------------------------------------------------------------------
+  if (args.change) {
+    const changeName = String(args.change);
+    const changeFolder = path.join(projectRoot, 'refacil-sdd', 'changes', changeName);
+
+    const changesRoot = path.join(projectRoot, 'refacil-sdd', 'changes') + path.sep;
+    if (!changeFolder.startsWith(changesRoot)) {
+      console.error('  Error: --change must be a simple folder name (no path separators).');
+      process.exit(1);
+    }
+
+    if (!fs.existsSync(changeFolder)) {
+      console.error(`  Error: no se encontró la carpeta de cambio '${changeName}' en refacil-sdd/changes/.`);
+      process.exit(1);
+    }
+
+    // Collect .md files in the change folder
+    let allEntries;
+    try {
+      allEntries = fs.readdirSync(changeFolder);
+    } catch (err) {
+      console.error(`  Error: could not read change folder: ${err.message}`);
+      process.exit(1);
+    }
+    const mdFiles = allEntries.filter((n) => n.endsWith('.md'));
+
+    if (mdFiles.length === 0) {
+      console.error(`  Error: la carpeta '${changeName}' no contiene archivos Markdown.`);
+      process.exit(1);
+    }
+
+    const sortedFiles = sortFolderFiles(mdFiles);
+
+    // Validate --select if provided
+    const selectArg = typeof args.select === 'string' ? args.select : 'proposal.md';
+    const resolvedSelect = sortedFiles.includes(selectArg) ? selectArg : null;
+    if (typeof args.select === 'string' && !resolvedSelect) {
+      console.error(`  Error: el archivo '${args.select}' no existe en la carpeta de cambio '${changeName}'.`);
+      process.exit(1);
+    }
+    if (!resolvedSelect && typeof args.select !== 'string') {
+      console.warn(`  Note: proposal.md not found in '${changeName}', opening '${sortedFiles[0]}' instead.`);
+    }
+    const selectedFile = resolvedSelect || sortedFiles[0];
+
+    const voice = typeof args.voice === 'string' ? args.voice.toUpperCase() : DEFAULT_VOICE;
+    const speedRaw = args.speed !== undefined ? parseFloat(args.speed) : DEFAULT_SPEED;
+
+    if (!VALID_VOICES.has(voice)) {
+      console.error(`  Error: invalid --voice "${args.voice}". Use M1–M5 or F1–F5`);
+      process.exit(1);
+    }
+    if (Number.isNaN(speedRaw) || speedRaw < 0.9 || speedRaw > 1.5) {
+      console.error('  Error: --speed must be between 0.9 and 1.5');
+      process.exit(1);
+    }
+
+    const { artifactLanguage } = loadBranchConfigWithSources(projectRoot);
+    let resolvedLang = typeof args.lang === 'string' ? args.lang : null;
+
+    // Parse each file and collect sections
+    const files = [];
+    const allContents = [];
+    for (const name of sortedFiles) {
+      const absPath = path.join(changeFolder, name);
+      const relPath = path.relative(projectRoot, absPath).replace(/\\/g, '/');
+      let sections;
+      let fileContent;
+      try {
+        fileContent = fs.readFileSync(absPath, 'utf8');
+        sections = parseFile(absPath);
+      } catch (err) {
+        console.error(`  Error parsing ${name}: ${err.message}`);
+        process.exit(1);
+      }
+      // Explicit meta comment takes priority (first file that has one wins)
+      if (!resolvedLang) {
+        const metaFromFile = extractArtifactLanguageMeta(fileContent);
+        if (metaFromFile) {
+          resolvedLang = artifactLanguageToTtsCode(metaFromFile);
+        }
+      }
+      allContents.push(fileContent);
+      files.push({ name, relPath, sections });
+    }
+
+    if (!resolvedLang) {
+      // Content-based detection: inspect heading patterns across all files
+      resolvedLang = detectTtsLangFromContent(allContents.join('\n'));
+    }
+
+    if (!resolvedLang) {
+      resolvedLang = resolveDefaultTtsLang(projectRoot);
+    }
+
+    if (!isValidTtsLang(resolvedLang)) {
+      console.error(`  Error: invalid --lang "${resolvedLang}". Use a Supertonic code (e.g. es, en).`);
+      process.exit(1);
+    }
+
+    const relativeChangeFolder = path.relative(projectRoot, changeFolder).replace(/\\/g, '/');
+
+    const sessionId = writeFolderSession({
+      files,
+      selectedFile,
+      meta: {
+        lang: resolvedLang,
+        voice,
+        speed: speedRaw,
+        changeName,
+        artifactLanguage,
+      },
+      sourcePath: relativeChangeFolder,
+      createdAt: new Date().toISOString(),
+    });
+
+    let info;
+    try {
+      ({ info } = await busSpawn.ensureBroker(packageRoot));
+    } catch (err) {
+      console.error(`  Error: could not start broker: ${err.message}`);
+      process.exit(1);
+    }
+
+    const url = `http://127.0.0.1:${info.port}/read-spec?id=${sessionId}`;
+    console.log(`  read-spec session: ${sessionId}`);
+    console.log(`  Open: ${url}`);
+
+    const opened = openInBrowser(url);
+    if (!opened) {
+      console.log('  (could not open browser automatically — open the URL above manually)');
+    }
+    return;
+  }
+
+  // -----------------------------------------------------------------------
+  // FILE MODE: --file <path>
+  // -----------------------------------------------------------------------
+  let filePath;
+  try {
+    filePath = resolveFileWithinProject(args.file, projectRoot);
+  } catch (err) {
+    console.error(`  Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(filePath)) {
+    console.error(`  Error: file not found: ${args.file}`);
+    process.exit(1);
+  }
+
+  if (path.extname(filePath).toLowerCase() !== '.md') {
+    console.error('  Error: --file must be a .md Markdown file');
+    process.exit(1);
+  }
+
+  const voice = typeof args.voice === 'string' ? args.voice.toUpperCase() : DEFAULT_VOICE;
+  const speedRaw = args.speed !== undefined ? parseFloat(args.speed) : DEFAULT_SPEED;
+
+  if (!VALID_VOICES.has(voice)) {
+    console.error(`  Error: invalid --voice "${args.voice}". Use M1–M5 or F1–F5`);
+    process.exit(1);
+  }
+  if (Number.isNaN(speedRaw) || speedRaw < 0.9 || speedRaw > 1.5) {
+    console.error('  Error: --speed must be between 0.9 and 1.5');
+    process.exit(1);
+  }
+
+  let sections;
+  let fileContent;
+  try {
+    fileContent = fs.readFileSync(filePath, 'utf8');
+    sections = parseFile(filePath);
+  } catch (err) {
+    console.error(`  Error parsing Markdown: ${err.message}`);
+    process.exit(1);
+  }
+
+  const relativeSource = path.relative(projectRoot, filePath).replace(/\\/g, '/');
+  const { artifactLanguage } = loadBranchConfigWithSources(projectRoot);
+  const metaFromFile = extractArtifactLanguageMeta(fileContent);
+  const resolvedLang = typeof args.lang === 'string'
+    ? args.lang
+    : (metaFromFile
+      ? artifactLanguageToTtsCode(metaFromFile)
+      : (detectTtsLangFromContent(fileContent) || resolveDefaultTtsLang(projectRoot)));
+  if (!isValidTtsLang(resolvedLang)) {
+    console.error(`  Error: invalid --lang "${resolvedLang}". Use a Supertonic code (e.g. es, en).`);
+    process.exit(1);
+  }
+
+  const sessionId = writeSession({
+    sections,
+    meta: {
+      lang: resolvedLang,
+      voice,
+      speed: speedRaw,
+      artifactLanguage: metaFromFile || artifactLanguage,
+    },
+    sourcePath: relativeSource,
+    createdAt: new Date().toISOString(),
+  });
+
+  let info;
+  try {
+    ({ info } = await busSpawn.ensureBroker(packageRoot));
+  } catch (err) {
+    console.error(`  Error: could not start broker: ${err.message}`);
+    process.exit(1);
+  }
+
+  const url = `http://127.0.0.1:${info.port}/read-spec?id=${sessionId}`;
+  console.log(`  read-spec session: ${sessionId}`);
+  console.log(`  Open: ${url}`);
+
+  const opened = openInBrowser(url);
+  if (!opened) {
+    console.log('  (could not open browser automatically — open the URL above manually)');
+  }
+}
+
+module.exports = {
+  handleReadSpec,
+  parseReadSpecArgs,
+  sortFolderFiles,
+  FOLDER_FILE_ORDER,
+  printHelp,
+  DEFAULT_LANG,
+  DEFAULT_VOICE,
+  DEFAULT_SPEED,
+};