@jaimevalasek/aioson 1.4.0 → 1.6.0

package/src/commands/squad-mcp.js

@@ -0,0 +1,270 @@
+'use strict';
+
+const path = require('node:path');
+const { openRuntimeDb, upsertMcpStatus, listMcpStatus, getMcpStatus } = require('../runtime-store');
+const {
+  listBuiltInConnectors,
+  getBuiltInConnector,
+  loadIntegrationConfig,
+  saveIntegrationConfig,
+  listIntegrations,
+  resolveConnectorEnv,
+  runHealthCheck,
+  runAction
+} = require('../mcp-connectors/registry');
+
+async function runSquadMcp({ args, options, logger, t }) {
+  const projectDir = path.resolve(args[0] || options.path || '.');
+  const squadSlug = options.squad;
+  const sub = options.sub || 'status';
+
+  if (!squadSlug) {
+    logger.log(t('squad_mcp.squad_required'));
+    return { ok: false, error: 'squad_required' };
+  }
+
+  if (sub === 'connectors') {
+    return handleConnectors({ logger, t });
+  }
+  if (sub === 'status') {
+    return handleStatus({ projectDir, squadSlug, logger, t });
+  }
+  if (sub === 'configure') {
+    return handleConfigure({ projectDir, squadSlug, options, logger, t });
+  }
+  if (sub === 'test') {
+    return handleTest({ projectDir, squadSlug, options, logger, t });
+  }
+  if (sub === 'call') {
+    return handleCall({ projectDir, squadSlug, options, logger, t });
+  }
+
+  logger.log(t('squad_mcp.unknown_sub', { sub }));
+  return { ok: false, error: 'unknown_sub' };
+}
+
+function handleConnectors({ logger, t }) {
+  const connectors = listBuiltInConnectors();
+  logger.log(t('squad_mcp.connectors_title'));
+  for (const c of connectors) {
+    logger.log(`  ${c.id} — ${c.name}`);
+    logger.log(`    ${t('squad_mcp.actions')}: ${c.actions.join(', ')}`);
+    logger.log(`    ${t('squad_mcp.required_config')}: ${c.requiredConfig.join(', ') || 'none'}`);
+    logger.log('');
+  }
+  return { ok: true, connectors };
+}
+
+async function handleStatus({ projectDir, squadSlug, logger, t }) {
+  const integrations = await listIntegrations(projectDir, squadSlug);
+
+  if (integrations.length === 0) {
+    logger.log(t('squad_mcp.no_integrations', { squad: squadSlug }));
+    return { ok: true, integrations: [] };
+  }
+
+  let handle;
+  try {
+    handle = await openRuntimeDb(projectDir);
+  } catch {
+    handle = null;
+  }
+
+  const results = [];
+  for (const integ of integrations) {
+    const connectorDef = getBuiltInConnector(integ.connector);
+    let status = 'unknown';
+    let missing = [];
+    if (connectorDef) {
+      const env = resolveConnectorEnv(connectorDef, integ.config);
+      status = env.status;
+      missing = env.missing;
+    }
+
+    let dbStatus = null;
+    if (handle) {
+      dbStatus = getMcpStatus(handle.db, squadSlug, integ.slug);
+    }
+
+    const entry = {
+      slug: integ.slug,
+      connector: integ.connector,
+      status: dbStatus ? dbStatus.status : status,
+      missing,
+      calls_total: dbStatus ? dbStatus.calls_total : 0,
+      calls_failed: dbStatus ? dbStatus.calls_failed : 0
+    };
+    results.push(entry);
+
+    const statusIcon = entry.status === 'connected' ? '+' : entry.status === 'configured' ? '~' : '-';
+    logger.log(`  [${statusIcon}] ${integ.slug} (${integ.connector}) — ${entry.status}`);
+    if (missing.length > 0) {
+      logger.log(`      ${t('squad_mcp.missing_config')}: ${missing.join(', ')}`);
+    }
+    if (entry.calls_total > 0) {
+      logger.log(`      ${t('squad_mcp.calls')}: ${entry.calls_total} (${entry.calls_failed} failed)`);
+    }
+  }
+
+  if (handle) handle.db.close();
+  return { ok: true, integrations: results };
+}
+
+async function handleConfigure({ projectDir, squadSlug, options, logger, t }) {
+  const mcpSlug = options.mcp;
+  const connector = options.connector;
+
+  if (!mcpSlug) {
+    logger.log(t('squad_mcp.mcp_required'));
+    return { ok: false, error: 'mcp_required' };
+  }
+  if (!connector) {
+    logger.log(t('squad_mcp.connector_required'));
+    return { ok: false, error: 'connector_required' };
+  }
+
+  const connectorDef = getBuiltInConnector(connector);
+  if (!connectorDef) {
+    logger.log(t('squad_mcp.unknown_connector', { connector }));
+    return { ok: false, error: 'unknown_connector' };
+  }
+
+  // Build config from --key=value options
+  const config = {};
+  for (const [key] of Object.entries(connectorDef.configSchema)) {
+    if (options[key] !== undefined) {
+      config[key] = options[key];
+    }
+  }
+
+  const integrationConfig = { connector, config };
+  await saveIntegrationConfig(projectDir, squadSlug, mcpSlug, integrationConfig);
+
+  // Check resolution
+  const { status, missing } = resolveConnectorEnv(connectorDef, config);
+
+  // Update SQLite status
+  try {
+    const handle = await openRuntimeDb(projectDir);
+    upsertMcpStatus(handle.db, { squadSlug, mcpSlug, connector, status, lastError: null });
+    handle.db.close();
+  } catch { /* SQLite optional */ }
+
+  logger.log(t('squad_mcp.configured', { mcp: mcpSlug, connector, status }));
+  if (missing.length > 0) {
+    logger.log(t('squad_mcp.still_missing', { keys: missing.join(', ') }));
+  }
+  return { ok: true, slug: mcpSlug, connector, status, missing };
+}
+
+async function handleTest({ projectDir, squadSlug, options, logger, t }) {
+  const mcpSlug = options.mcp;
+  if (!mcpSlug) {
+    logger.log(t('squad_mcp.mcp_required'));
+    return { ok: false, error: 'mcp_required' };
+  }
+
+  const config = await loadIntegrationConfig(projectDir, squadSlug, mcpSlug);
+  if (!config) {
+    logger.log(t('squad_mcp.not_configured', { mcp: mcpSlug }));
+    return { ok: false, error: 'not_configured' };
+  }
+
+  const connectorDef = getBuiltInConnector(config.connector);
+  if (!connectorDef) {
+    logger.log(t('squad_mcp.unknown_connector', { connector: config.connector }));
+    return { ok: false, error: 'unknown_connector' };
+  }
+
+  const { resolved, missing, status } = resolveConnectorEnv(connectorDef, config.config);
+
+  if (missing.length > 0) {
+    logger.log(t('squad_mcp.test_missing', { mcp: mcpSlug, keys: missing.join(', ') }));
+
+    try {
+      const handle = await openRuntimeDb(projectDir);
+      upsertMcpStatus(handle.db, { squadSlug, mcpSlug, connector: config.connector, status: 'unconfigured', lastError: `Missing: ${missing.join(', ')}` });
+      handle.db.close();
+    } catch { /* optional */ }
+
+    return { ok: false, error: 'missing_config', missing };
+  }
+
+  logger.log(t('squad_mcp.testing_connection'));
+  const health = await runHealthCheck(config.connector, resolved);
+
+  const healthStatus = health.ok ? 'connected' : 'error';
+  try {
+    const handle = await openRuntimeDb(projectDir);
+    upsertMcpStatus(handle.db, {
+      squadSlug, mcpSlug,
+      connector: config.connector,
+      status: healthStatus,
+      lastCheck: new Date().toISOString(),
+      lastError: health.ok ? null : (health.error || String(health.statusCode))
+    });
+    handle.db.close();
+  } catch { /* optional */ }
+
+  if (health.skipped) {
+    logger.log(t('squad_mcp.health_skipped'));
+    return { ok: true, slug: mcpSlug, status: 'skipped' };
+  }
+  if (health.ok) {
+    logger.log(t('squad_mcp.health_ok', { statusCode: health.statusCode }));
+    return { ok: true, slug: mcpSlug, status: 'connected', statusCode: health.statusCode };
+  }
+  logger.log(t('squad_mcp.health_error', { error: health.error || health.statusCode }));
+  return { ok: false, slug: mcpSlug, status: 'error', error: health.error };
+}
+
+async function handleCall({ projectDir, squadSlug, options, logger, t }) {
+  const mcpSlug = options.mcp;
+  const actionSlug = options.action;
+
+  if (!mcpSlug) {
+    logger.log(t('squad_mcp.mcp_required'));
+    return { ok: false, error: 'mcp_required' };
+  }
+  if (!actionSlug) {
+    logger.log(t('squad_mcp.action_required'));
+    return { ok: false, error: 'action_required' };
+  }
+
+  let input;
+  try {
+    input = JSON.parse(options.input || '{}');
+  } catch {
+    logger.log(t('squad_mcp.invalid_input'));
+    return { ok: false, error: 'invalid_input' };
+  }
+
+  const config = await loadIntegrationConfig(projectDir, squadSlug, mcpSlug);
+  if (!config) {
+    logger.log(t('squad_mcp.not_configured', { mcp: mcpSlug }));
+    return { ok: false, error: 'not_configured' };
+  }
+
+  const connectorDef = getBuiltInConnector(config.connector);
+  if (!connectorDef) {
+    logger.log(t('squad_mcp.unknown_connector', { connector: config.connector }));
+    return { ok: false, error: 'unknown_connector' };
+  }
+
+  const { resolved, missing } = resolveConnectorEnv(connectorDef, config.config);
+  if (missing.length > 0) {
+    logger.log(t('squad_mcp.test_missing', { mcp: mcpSlug, keys: missing.join(', ') }));
+    return { ok: false, error: 'missing_config', missing };
+  }
+
+  const result = await runAction(config.connector, actionSlug, input, resolved);
+
+  if (result.ok) {
+    logger.log(JSON.stringify(result.result, null, 2));
+  } else {
+    logger.log(`Error: ${result.error}`);
+  }
+  return result;
+}
+
+module.exports = { runSquadMcp };

package/src/commands/squad-processes.js

@@ -0,0 +1,56 @@
+'use strict';
+
+const path = require('node:path');
+const { getActiveProcesses, stopProcess, stopSquadProcesses } = require('../squad-dashboard/process-monitor');
+
+function formatElapsed(seconds) {
+  if (seconds == null) return '-';
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m${seconds % 60}s`;
+  return `${Math.floor(seconds / 3600)}h${Math.floor((seconds % 3600) / 60)}m`;
+}
+
+async function runSquadProcesses({ args, options, logger }) {
+  const projectDir = path.resolve(process.cwd(), args[0] || '.');
+  const squadFilter = options.squad || null;
+
+  // --stop <pid>
+  if (options.stop && options.stop !== true) {
+    const result = await stopProcess(projectDir, options.stop);
+    if (result.ok) {
+      logger.log(`Process ${options.stop} stopped.`);
+    } else {
+      logger.error(`Failed to stop ${options.stop}: ${result.error}`);
+    }
+    return result;
+  }
+
+  // --stop-squad <squad>
+  if (options['stop-squad']) {
+    const slug = options['stop-squad'];
+    const results = await stopSquadProcesses(projectDir, slug);
+    const stopped = results.filter(r => r.ok).length;
+    logger.log(`Stopped ${stopped}/${results.length} processes for squad "${slug}".`);
+    return { ok: true, results };
+  }
+
+  // List
+  const processes = await getActiveProcesses(projectDir, squadFilter);
+  if (processes.length === 0) {
+    logger.log(squadFilter ? `No active processes for squad "${squadFilter}".` : 'No active processes.');
+    return { ok: true, processes: [] };
+  }
+
+  logger.log(`Active processes (${processes.length}):`);
+  for (const proc of processes) {
+    const status = proc.alive ? '[*]' : '[ ]';
+    const elapsed = formatElapsed(proc.elapsedSeconds);
+    const ctx = proc.contextPct != null ? ` ctx:${proc.contextPct}%` : '';
+    const url = proc.url ? `  ${proc.url}` : '';
+    logger.log(`  ${status} [${proc.squadSlug}] ${proc.agentSlug}  pid:${proc.pid}  elapsed:${elapsed}${ctx}${url}`);
+  }
+
+  return { ok: true, processes };
+}
+
+module.exports = { runSquadProcesses };

package/src/commands/squad-recovery.js

@@ -0,0 +1,42 @@
+'use strict';
+
+const path = require('node:path');
+const { generateRecovery, readRecovery } = require('../squad/recovery-context');
+
+/**
+ * aioson squad:recovery <project> --squad <squad> --agent <agent> [--show]
+ *
+ * Generates (or re-generates) the recovery-context.md for an agent.
+ * --show: print the generated content to stdout instead of just confirming.
+ */
+async function runSquadRecovery({ args, options, logger }) {
+  const projectDir = path.resolve(process.cwd(), args[0] || '.');
+  const squadSlug = options.squad || args[1];
+  const agentSlug = options.agent || args[2];
+
+  if (!squadSlug || !agentSlug) {
+    logger.error('Usage: aioson squad:recovery <project> --squad <squad> --agent <agent> [--show]');
+    return { ok: false };
+  }
+
+  const result = await generateRecovery(projectDir, squadSlug, agentSlug);
+
+  if (!result.ok) {
+    logger.error(`Failed to generate recovery context: ${result.error}`);
+    return result;
+  }
+
+  logger.log(`Recovery context generated: ${result.path} (~${result.tokens} tokens)`);
+
+  if (options.show) {
+    const content = await readRecovery(projectDir, squadSlug);
+    if (content) {
+      logger.log('');
+      logger.log(content);
+    }
+  }
+
+  return result;
+}
+
+module.exports = { runSquadRecovery };

package/src/commands/squad-roi.js

@@ -0,0 +1,291 @@
+'use strict';
+
+const path = require('node:path');
+const {
+  openRuntimeDb,
+  upsertSquadMetric,
+  listSquadMetrics,
+  upsertROIConfig,
+  getROIConfig
+} = require('../runtime-store');
+
+async function runSquadRoi({ args, options, logger, t }) {
+  const projectDir = path.resolve(args[0] || options.path || '.');
+  const squadSlug = options.squad;
+  const sub = options.sub || 'report';
+
+  if (!squadSlug) {
+    logger.log(t('squad_roi.squad_required'));
+    return { ok: false, error: 'squad_required' };
+  }
+
+  if (sub === 'config') {
+    return handleConfig({ projectDir, squadSlug, options, logger, t });
+  }
+  if (sub === 'metric') {
+    return handleMetric({ projectDir, squadSlug, options, logger, t });
+  }
+  if (sub === 'report') {
+    return handleReport({ projectDir, squadSlug, options, logger, t });
+  }
+  if (sub === 'export') {
+    return handleExport({ projectDir, squadSlug, options, logger, t });
+  }
+
+  logger.log(t('squad_roi.unknown_sub', { sub }));
+  return { ok: false, error: 'unknown_sub' };
+}
+
+async function handleConfig({ projectDir, squadSlug, options, logger, t }) {
+  const handle = await openRuntimeDb(projectDir);
+
+  upsertROIConfig(handle.db, {
+    squadSlug,
+    pricingModel: options.pricing || options.pricing_model,
+    setupFee: options.setup ? parseFloat(options.setup) : undefined,
+    monthlyFee: options.monthly ? parseFloat(options.monthly) : undefined,
+    percentageFee: options.percentage ? parseFloat(options.percentage) : undefined,
+    percentageBase: options.base,
+    currency: options.currency,
+    contractMonths: options.months ? parseInt(options.months, 10) : undefined
+  });
+
+  const config = getROIConfig(handle.db, squadSlug);
+  handle.db.close();
+
+  logger.log(t('squad_roi.config_saved', { squad: squadSlug }));
+  logger.log(`  ${t('squad_roi.pricing_model')}: ${config.pricing_model}`);
+  if (config.setup_fee) logger.log(`  ${t('squad_roi.setup_fee')}: ${config.currency} ${config.setup_fee}`);
+  if (config.monthly_fee) logger.log(`  ${t('squad_roi.monthly_fee')}: ${config.currency} ${config.monthly_fee}`);
+  if (config.percentage_fee) logger.log(`  ${t('squad_roi.percentage')}: ${config.percentage_fee}% (${config.percentage_base || 'n/a'})`);
+  logger.log(`  ${t('squad_roi.contract')}: ${config.contract_months} months`);
+
+  return { ok: true, config };
+}
+
+async function handleMetric({ projectDir, squadSlug, options, logger, t }) {
+  const key = options.key;
+  const value = options.value;
+  const period = options.period;
+
+  if (!key || value === undefined) {
+    logger.log(t('squad_roi.metric_required'));
+    return { ok: false, error: 'metric_required' };
+  }
+
+  const handle = await openRuntimeDb(projectDir);
+  upsertSquadMetric(handle.db, {
+    squadSlug,
+    metricKey: key,
+    value: parseFloat(value),
+    unit: options.unit || null,
+    period: period || null,
+    baseline: options.baseline ? parseFloat(options.baseline) : null,
+    target: options.target ? parseFloat(options.target) : null,
+    source: options.source || 'manual',
+    notes: options.notes || null
+  });
+  handle.db.close();
+
+  logger.log(t('squad_roi.metric_saved', { key, value, squad: squadSlug }));
+  return { ok: true, key, value: parseFloat(value), period };
+}
+
+function calculateROI(metrics, config) {
+  if (!config) return null;
+
+  const improvements = [];
+  for (const m of metrics) {
+    if (m.baseline === null || m.baseline === undefined) continue;
+    const improvement = m.baseline - m.metric_value;
+    improvements.push({
+      key: m.metric_key,
+      baseline: m.baseline,
+      actual: m.metric_value,
+      target: m.target,
+      improvement,
+      unit: m.metric_unit,
+      period: m.period
+    });
+  }
+
+  const monthlyCost = (config.monthly_fee || 0) + ((config.setup_fee || 0) / (config.contract_months || 12));
+
+  return {
+    improvements,
+    monthly_cost: monthlyCost,
+    pricing: {
+      model: config.pricing_model,
+      setup_fee: config.setup_fee,
+      monthly_fee: config.monthly_fee,
+      percentage_fee: config.percentage_fee,
+      currency: config.currency
+    }
+  };
+}
+
+async function handleReport({ projectDir, squadSlug, options, logger, t }) {
+  const handle = await openRuntimeDb(projectDir);
+  const config = getROIConfig(handle.db, squadSlug);
+  const metrics = listSquadMetrics(handle.db, squadSlug);
+  handle.db.close();
+
+  if (metrics.length === 0) {
+    logger.log(t('squad_roi.no_metrics', { squad: squadSlug }));
+    return { ok: true, metrics: [], roi: null };
+  }
+
+  const period = options.period || null;
+  const filtered = period ? metrics.filter(m => m.period === period) : metrics;
+
+  logger.log(t('squad_roi.report_title', { squad: squadSlug }));
+  logger.log('');
+
+  // Group by metric_key
+  const byKey = {};
+  for (const m of filtered) {
+    if (!byKey[m.metric_key]) byKey[m.metric_key] = [];
+    byKey[m.metric_key].push(m);
+  }
+
+  for (const [key, entries] of Object.entries(byKey)) {
+    const latest = entries[entries.length - 1];
+    logger.log(`  ${key}`);
+    if (latest.baseline !== null) {
+      logger.log(`    ${t('squad_roi.baseline')}: ${latest.baseline}${latest.metric_unit || ''}`);
+    }
+    logger.log(`    ${t('squad_roi.actual')}: ${latest.metric_value}${latest.metric_unit || ''}`);
+    if (latest.target !== null) {
+      logger.log(`    ${t('squad_roi.target')}: ${latest.target}${latest.metric_unit || ''}`);
+      // Progress bar
+      if (latest.baseline !== null && latest.baseline !== latest.target) {
+        const totalGap = Math.abs(latest.baseline - latest.target);
+        const achieved = Math.abs(latest.baseline - latest.metric_value);
+        const pct = Math.min(100, Math.round((achieved / totalGap) * 100));
+        const filled = Math.round(pct / 5);
+        const bar = '#'.repeat(filled) + '.'.repeat(20 - filled);
+        logger.log(`    [${bar}] ${pct}%`);
+      }
+    }
+    if (latest.period) {
+      logger.log(`    ${t('squad_roi.period')}: ${latest.period}`);
+    }
+    logger.log('');
+  }
+
+  const roi = calculateROI(filtered, config);
+  if (roi && config) {
+    logger.log(t('squad_roi.cost_section'));
+    logger.log(`  ${t('squad_roi.monthly_cost')}: ${config.currency} ${roi.monthly_cost.toFixed(2)}`);
+  }
+
+  return { ok: true, metrics: filtered, roi };
+}
+
+function renderReportHtml(squadSlug, metrics, config) {
+  const roi = calculateROI(metrics, config);
+  const currency = (config && config.currency) || 'BRL';
+
+  const byKey = {};
+  for (const m of metrics) {
+    if (!byKey[m.metric_key]) byKey[m.metric_key] = [];
+    byKey[m.metric_key].push(m);
+  }
+
+  const metricsHtml = Object.entries(byKey).map(([key, entries]) => {
+    const latest = entries[entries.length - 1];
+    let progressBar = '';
+    if (latest.baseline !== null && latest.target !== null && latest.baseline !== latest.target) {
+      const totalGap = Math.abs(latest.baseline - latest.target);
+      const achieved = Math.abs(latest.baseline - latest.metric_value);
+      const pct = Math.min(100, Math.round((achieved / totalGap) * 100));
+      progressBar = `<div style="background:#333;border-radius:4px;overflow:hidden;height:8px;margin-top:4px">
+        <div style="background:#4ade80;height:100%;width:${pct}%"></div>
+      </div><small>${pct}% of target</small>`;
+    }
+    return `<div style="background:#1e1e2e;padding:16px;border-radius:8px;margin-bottom:12px">
+      <h3 style="margin:0 0 8px">${esc(key)}</h3>
+      ${latest.baseline !== null ? `<p>Baseline: <strong>${latest.baseline}${latest.metric_unit || ''}</strong></p>` : ''}
+      <p>Current: <strong>${latest.metric_value}${latest.metric_unit || ''}</strong></p>
+      ${latest.target !== null ? `<p>Target: <strong>${latest.target}${latest.metric_unit || ''}</strong></p>` : ''}
+      ${progressBar}
+      ${latest.period ? `<small>Period: ${esc(latest.period)}</small>` : ''}
+    </div>`;
+  }).join('\n');
+
+  const costHtml = roi && config ? `
+    <div style="background:#1e1e2e;padding:16px;border-radius:8px;margin-top:16px">
+      <h3>Cost Summary</h3>
+      <p>Pricing: ${esc(config.pricing_model)}</p>
+      ${config.setup_fee ? `<p>Setup: ${currency} ${config.setup_fee}</p>` : ''}
+      ${config.monthly_fee ? `<p>Monthly: ${currency} ${config.monthly_fee}</p>` : ''}
+      <p>Monthly effective cost: <strong>${currency} ${roi.monthly_cost.toFixed(2)}</strong></p>
+    </div>` : '';
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>ROI Report — ${esc(squadSlug)}</title>
+<style>
+  body{font-family:system-ui,sans-serif;background:#0d1117;color:#e6edf3;margin:0;padding:24px}
+  .container{max-width:720px;margin:0 auto}
+  h1{border-bottom:1px solid #30363d;padding-bottom:12px}
+  h3{color:#58a6ff}
+  p{margin:4px 0}
+  small{color:#8b949e}
+</style>
+</head>
+<body>
+<div class="container">
+  <h1>ROI Report — ${esc(squadSlug)}</h1>
+  <p style="color:#8b949e">Generated: ${new Date().toISOString().slice(0, 10)}</p>
+  <h2>Metrics</h2>
+  ${metricsHtml}
+  ${costHtml}
+  <footer style="margin-top:32px;color:#8b949e;font-size:12px">
+    Generated by aioson squad:roi:export
+  </footer>
+</div>
+</body>
+</html>`;
+}
+
+function esc(str) {
+  if (!str) return '';
+  return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+async function handleExport({ projectDir, squadSlug, options, logger, t }) {
+  const format = options.format || 'html';
+  const handle = await openRuntimeDb(projectDir);
+  const config = getROIConfig(handle.db, squadSlug);
+  const metrics = listSquadMetrics(handle.db, squadSlug);
+  handle.db.close();
+
+  if (metrics.length === 0) {
+    logger.log(t('squad_roi.no_metrics', { squad: squadSlug }));
+    return { ok: true, exported: false };
+  }
+
+  const period = options.period || null;
+  const filtered = period ? metrics.filter(m => m.period === period) : metrics;
+
+  if (format === 'json') {
+    const roi = calculateROI(filtered, config);
+    const output = JSON.stringify({ squad: squadSlug, metrics: filtered, roi, config }, null, 2);
+    logger.log(output);
+    return { ok: true, exported: true, format: 'json' };
+  }
+
+  // HTML
+  const html = renderReportHtml(squadSlug, filtered, config);
+  const fs = require('node:fs/promises');
+  const outFile = options.output || `roi-report-${squadSlug}.html`;
+  await fs.writeFile(outFile, html);
+  logger.log(t('squad_roi.exported', { file: outFile, format: 'html' }));
+  return { ok: true, exported: true, format: 'html', file: outFile };
+}
+
+module.exports = { runSquadRoi, calculateROI, renderReportHtml, esc };