shakers-cli-beta 0.8.0-beta.0

package/src/tier-analysis.js

@@ -0,0 +1,126 @@
+'use strict';
+
+const { computeTierResult, setupLevelForTier, SETUP_LEVELS, TIERS } = require('./tier-engine');
+
+// One entry per tier BOUNDARY (T(n-1) -> Tn), in ladder order.
+const CRITERIA = [
+  {
+    toTier: 1,
+    met: (s) => s.totalDetected >= 1,
+    metText: (s, tt) => tt.criterion.t1Met(s.totalDetected),
+    blockingText: (s, tt) => tt.criterion.t1Blocking(s.totalDetected),
+  },
+  {
+    toTier: 2,
+    met: (s) => s.context >= 1,
+    metText: (s, tt) => tt.criterion.t2Met(s.context),
+    blockingText: (s, tt) => tt.criterion.t2Blocking(s.context),
+  },
+  {
+    toTier: 3,
+    met: (s) => s.mcp >= 1,
+    metText: (s, tt) => tt.criterion.t3Met(s.mcp),
+    blockingText: (s, tt) => tt.criterion.t3Blocking(s.mcp),
+  },
+  {
+    toTier: 4,
+    met: (s) => s.custom >= 1,
+    metText: (s, tt) => tt.criterion.t4Met(s.custom),
+    blockingText: (s, tt) => tt.criterion.t4Blocking(s.custom),
+  },
+  {
+    toTier: 5,
+    met: (s) => s.hasAgentic && s.mcp >= 1 && s.custom >= 1,
+    metText: (s, tt) => tt.criterion.t5Met(s.hasAgentic, s.mcp, s.custom),
+    blockingText: (s, tt) => tt.criterion.t5Blocking(s.hasAgentic, s.mcp, s.custom),
+  },
+  {
+    toTier: 6,
+    met: (s) => s.agentCount >= 2,
+    metText: (s, tt) => tt.criterion.t6Met(s.agentCount),
+    blockingText: (s, tt) => tt.criterion.t6Blocking(s.agentCount),
+  },
+  {
+    toTier: 7,
+    met: (s) => s.hooks >= 1,
+    metText: (s, tt) => tt.criterion.t7Met(s.hooks),
+    blockingText: (s, tt) => tt.criterion.t7Blocking(s.hooks),
+  },
+];
+
+// Builds the full analysis for a report: `{ tier, tierKey, tierName, band, signals, metCriteria, blockingCriterion }`.
+function analyzeTier(report, t) {
+  const tt = t.tierAnalysis;
+  const result = computeTierResult(report || {});
+  const { signals, tier } = result;
+
+  const tierName = (t.tierNames && t.tierNames[result.tierKey]) || result.tierName;
+
+  const metCriteria = CRITERIA.filter((c) => c.toTier <= tier).map((c) => ({
+    toTier: c.toTier,
+    text: c.metText(signals, tt),
+  }));
+
+  const blockingEntry = tier < 7 ? CRITERIA.find((c) => c.toTier === tier + 1) : null;
+  const blockingCriterion = blockingEntry ? blockingEntry.blockingText(signals, tt) : null;
+
+  return { ...result, tierName, metCriteria, blockingCriterion };
+}
+
+function buildLadder(report, t) {
+  const tt = t.tierAnalysis;
+  const ld = t.ladder;
+  const result = computeTierResult(report || {});
+  const { signals, tier } = result;
+  const currentSetupRank = setupLevelForTier(tier).rank;
+
+  const statusFor = (index, current) =>
+    index < current ? 'done' : index === current ? 'current' : 'pending';
+
+  const tierNode = (meta) => {
+    const status = statusFor(meta.tier, tier);
+    // Pending tiers carry the exact criterion that unlocks them (reused from the
+    // tier-analysis CRITERIA, already localized). done/current show none.
+    let unlock = null;
+    if (status === 'pending') {
+      const crit = CRITERIA.find((c) => c.toTier === meta.tier);
+      unlock = crit ? crit.blockingText(signals, tt) : null;
+    }
+    return {
+      tier: meta.tier,
+      tierKey: meta.key,
+      name: (t.tierNames && t.tierNames[meta.key]) || meta.name,
+      description: (ld && ld.tierDesc && ld.tierDesc[meta.key]) || '',
+      status,
+      unlock,
+    };
+  };
+
+  // NESTED ladder: each SETUP LEVEL groups the TIERS that compose it.
+  const tiersBySetup = new Map();
+  for (const meta of TIERS) {
+    const key = setupLevelForTier(meta.tier).key;
+    if (!tiersBySetup.has(key)) tiersBySetup.set(key, []);
+    tiersBySetup.get(key).push(tierNode(meta));
+  }
+
+  const setupLevels = SETUP_LEVELS.map((meta) => {
+    const tiers = (tiersBySetup.get(meta.key) || []).sort((a, b) => a.tier - b.tier);
+    const copy = (t.setupLevels && t.setupLevels[meta.key]) || {};
+    return {
+      key: meta.key,
+      code: meta.code,
+      rank: meta.rank,
+      emoji: meta.emoji,
+      label: copy.label || meta.key,
+      description: copy.desc || '',
+      status: statusFor(meta.rank, currentSetupRank),
+      tierKeys: tiers.map((x) => x.tierKey),
+      tiers,
+    };
+  });
+
+  return { currentTier: tier, currentSetupRank, setupLevels };
+}
+
+module.exports = { analyzeTier, buildLadder, CRITERIA };

package/src/tier-engine.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const TIERS = [
+  { tier: 0, key: 'T0', name: 'Banco vacío', means: 'No AI tools detected yet' },
+  { tier: 1, key: 'T1', name: 'Primera herramienta', means: 'At least one AI tool in use' },
+  { tier: 2, key: 'T2', name: 'Banco con notas', means: 'AI tools plus project context (instructions, config, rules)' },
+  { tier: 3, key: 'T3', name: 'Banco conectado', means: 'Adds an MCP server integration' },
+  { tier: 4, key: 'T4', name: 'Herramienta propia', means: 'Adds your own customization (skills, commands, rules)' },
+  { tier: 5, key: 'T5', name: 'Operador agéntico', means: 'An agentic tool wired with MCP and customization' },
+  { tier: 6, key: 'T6', name: 'Multi-agente', means: 'Two or more custom agents' },
+  { tier: 7, key: 'T7', name: 'Taller orquestado', means: 'Custom agents plus automation hooks (orchestrated)' },
+];
+
+function tierLadder() {
+  return TIERS.map((t) => ({ key: t.key, name: t.name, means: t.means }));
+}
+
+const AGENTIC_IDS = ['claude-code', 'aider', 'gemini-cli', 'codex-cli', 'amazon-q-developer'];
+
+// Band 0-4 derived from tier (level-model.md, single source of truth): index = tier -> band.
+const BAND_BY_TIER = [0, 1, 2, 3, 3, 4, 4, 4];
+
+// Setup Level (Talent Certification Framework, ADR-016): the 3-value rollup that REPLACES the retired 0-4 band on every display surface.
+const SETUP_LEVELS = [
+  { key: 'none', code: null, rank: 0, emoji: '○' },
+  { key: 'S1', code: 'S1', rank: 1, emoji: '◔' },
+  { key: 'S2', code: 'S2', rank: 2, emoji: '◑' },
+  { key: 'S3', code: 'S3', rank: 3, emoji: '●' },
+];
+
+// tier -> setup-level key.
+const SETUP_LEVEL_BY_TIER = ['none', 'S1', 'S1', 'S2', 'S2', 'S3', 'S3', 'S3'];
+
+function setupLevelForTier(tier) {
+  const key = SETUP_LEVEL_BY_TIER[tier] ?? 'none';
+  return SETUP_LEVELS.find((s) => s.key === key) || SETUP_LEVELS[0];
+}
+
+// Aggregates the raw signals the ladder needs, straight from the report's existing fields — not a new detector, only a sum over what scanner.js already produces.
+function aggregateTierSignals(report) {
+  const tools = report && Array.isArray(report.tools) ? report.tools : [];
+  const detected = tools.filter((t) => t && t.detected);
+
+  let context = 0; // instructions + config + rules (T2)
+  let mcp = 0; // configured MCP servers (T3)
+  let custom = 0; // skills + commands + rules, own assets (T4)
+  let hooks = 0; // hook-based automation (T7)
+
+  for (const t of detected) {
+    const d = t.depth || {};
+    context += (d.instructions || 0) + (d.config || 0) + (d.rules || 0);
+    mcp += d.mcpServers || 0;
+    custom += (d.skills || 0) + (d.commands || 0) + (d.rules || 0);
+    hooks += d.hooks || 0;
+  }
+
+  const hasAgentic = detected.some((t) => AGENTIC_IDS.includes(t.id));
+  const agentCount =
+    report && report.agentCounts && typeof report.agentCounts.agents === 'number'
+      ? report.agentCounts.agents
+      : 0;
+
+  // THE MCP SIGNAL IS THE DEDUPED SET THE REPORT SHOWS (issue 112).
+  const mcpTotal =
+    report && report.mcp && typeof report.mcp.total === 'number' ? report.mcp.total : mcp;
+
+  return { totalDetected: detected.length, context, mcp: mcpTotal, custom, hooks, hasAgentic, agentCount };
+}
+
+function computeTier(signals) {
+  let tier = 0;
+  if (signals.totalDetected >= 1) tier = 1;
+  if (tier === 1 && signals.context >= 1) tier = 2;
+  if (tier === 2 && signals.mcp >= 1) tier = 3;
+  if (tier === 3 && signals.custom >= 1) tier = 4;
+  if (tier === 4 && signals.hasAgentic && signals.mcp >= 1 && signals.custom >= 1) tier = 5;
+  if (tier === 5 && signals.agentCount >= 2) tier = 6;
+  if (tier === 6 && signals.hooks >= 1) tier = 7;
+  return tier;
+}
+
+function bandForTier(tier) {
+  return BAND_BY_TIER[tier] ?? 0;
+}
+
+// Computes the full tier result for a report: {tier, tierKey, tierName, band, signals}.
+function computeTierResult(report) {
+  const signals = aggregateTierSignals(report || {});
+  const tier = computeTier(signals);
+  const meta = TIERS[tier];
+  return {
+    tier: meta.tier,
+    tierKey: meta.key,
+    tierName: meta.name,
+    band: bandForTier(tier),
+    // Setup Level (ADR-016) — the shown rollup. `{key, code, rank, emoji}`;
+    // the label is resolved from i18n by `key` at the render layer.
+    setupLevel: setupLevelForTier(tier),
+    signals,
+  };
+}
+
+module.exports = {
+  computeTierResult,
+  tierLadder,
+  computeTier,
+  aggregateTierSignals,
+  bandForTier,
+  setupLevelForTier,
+  SETUP_LEVELS,
+  SETUP_LEVEL_BY_TIER,
+  AGENTIC_IDS,
+  TIERS,
+};

package/src/tier-projection.js

@@ -0,0 +1,117 @@
+'use strict';
+
+const { classify } = require('./maturity');
+const { computeTierResult, aggregateTierSignals, computeTier } = require('./tier-engine');
+
+// Where this roadmap leaves you, computed with the REAL engine (issue 084).
+
+// One entry per TARGET tier: the smallest report-shape changes that satisfy that tier's criterion.
+const AGENTIC_TOOL_ID = 'claude-code';
+
+function cloneReport(report) {
+  return JSON.parse(JSON.stringify(report));
+}
+
+function detectedTools(r) {
+  return (Array.isArray(r.tools) ? r.tools : []).filter((t) => t && t.detected);
+}
+
+// Every depth bump needs SOME detected tool to hang off, because the engine only aggregates depth over detected tools.
+function ensureDetectedTool(r, { agentic = false } = {}) {
+  if (!Array.isArray(r.tools)) r.tools = [];
+  const existing = detectedTools(r);
+  const wanted = agentic ? existing.find((t) => t.id === AGENTIC_TOOL_ID) : existing[0];
+  if (wanted) {
+    if (!wanted.depth || typeof wanted.depth !== 'object') wanted.depth = {};
+    return wanted;
+  }
+  const tool = {
+    id: agentic ? AGENTIC_TOOL_ID : 'projected-tool',
+    name: agentic ? 'Claude Code' : 'AI tool',
+    detected: true,
+    depth: {},
+    footprint: null,
+    recency: { lastModified: null, daysSinceModified: null, bucket: null },
+  };
+  r.tools.push(tool);
+  return tool;
+}
+
+const bumpDepth = (field) => (r) => {
+  const tool = ensureDetectedTool(r);
+  tool.depth[field] = (tool.depth[field] || 0) + 1;
+};
+
+// "Configure one MCP server" needs its own delta, and the reason is a collision worth recording (issue 112 landing after issue 084).
+const addMcpServer = (r) => {
+  const tool = ensureDetectedTool(r);
+  tool.depth.mcpServers = (tool.depth.mcpServers || 0) + 1;
+  if (!r.mcp || typeof r.mcp !== 'object') r.mcp = { servers: [], countsByCategory: {}, total: 0, byTool: {} };
+  r.mcp.total = (typeof r.mcp.total === 'number' ? r.mcp.total : 0) + 1;
+};
+
+const DELTAS = {
+  1: [(r) => { ensureDetectedTool(r); }],
+  2: [bumpDepth('instructions')],
+  3: [addMcpServer],
+  4: [bumpDepth('skills')],
+  5: [
+    (r) => { ensureDetectedTool(r, { agentic: true }); },
+    addMcpServer,
+    bumpDepth('skills'),
+  ],
+  6: [(r) => {
+    if (!r.agentCounts || typeof r.agentCounts !== 'object') r.agentCounts = {};
+    r.agentCounts.agents = Math.max(2, (r.agentCounts.agents || 0) + 1);
+  }],
+  7: [bumpDepth('hooks')],
+};
+
+const MAX_TIER = 7;
+
+function projectNextTier(report) {
+  if (!report || typeof report !== 'object') return null;
+
+  const currentTierResult = computeTierResult(report);
+  const currentTier = currentTierResult.tier;
+  if (currentTier >= MAX_TIER) return null;
+
+  const deltas = DELTAS[currentTier + 1];
+  if (!deltas) return null;
+
+  let projectedReport;
+  try {
+    projectedReport = cloneReport(report);
+    for (const apply of deltas) apply(projectedReport);
+  } catch {
+    // A report shape this cannot clone or mutate is a report this must not
+    // guess about: no projection is better than a made-up one.
+    return null;
+  }
+
+  const projectedTierResult = computeTierResult(projectedReport);
+  // Guard against a delta that no longer satisfies its criterion (a ladder
+  // change): under-projecting silently would be worse than saying nothing.
+  if (projectedTierResult.tier <= currentTier) return null;
+
+  const currentMaturity = classify(report);
+  const projectedMaturity = classify(projectedReport);
+
+  return {
+    current: {
+      tier: currentTier,
+      tierKey: currentTierResult.tierKey,
+      setupLevelKey: currentTierResult.setupLevel.key,
+      score: currentMaturity.score,
+    },
+    projected: {
+      tier: projectedTierResult.tier,
+      tierKey: projectedTierResult.tierKey,
+      setupLevelKey: projectedTierResult.setupLevel.key,
+      score: projectedMaturity.score,
+    },
+    cascaded: projectedTierResult.tier > currentTier + 1,
+  };
+}
+
+module.exports = { projectNextTier, DELTAS, aggregateTierSignals, computeTier };

package/src/transcript-turns.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const { iterateSessionObjects } = require('./session-scan');
+
+// Human-turn reader for the steering/decisions extractors (hybrid evaluation, Slice 2).
+
+function isHumanTurn(obj) {
+  if (!obj || typeof obj !== 'object') return false;
+  const role = obj.message && obj.message.role;
+  return obj.type === 'user' || role === 'user';
+}
+
+function messageOf(obj) {
+  return obj.message && typeof obj.message === 'object' ? obj.message : obj;
+}
+
+function* textsFromContent(content) {
+  if (typeof content === 'string') {
+    yield content;
+    return;
+  }
+  if (!Array.isArray(content)) return;
+  for (const part of content) {
+    if (part && part.type === 'text' && typeof part.text === 'string') {
+      yield part.text;
+    }
+  }
+}
+
+// Yields each human-authored text turn from a SINGLE already-parsed session object.
+function* humanTextsFromObject(obj, { minLength = 4 } = {}) {
+  if (!isHumanTurn(obj)) return;
+  for (const text of textsFromContent(messageOf(obj).content)) {
+    const trimmed = text.trim();
+    if (trimmed.length < minLength) continue;
+    if (trimmed.startsWith('<')) continue;
+    yield trimmed;
+  }
+}
+
+// Yields each human-authored text turn across every AI-tool session on this machine, walking the shared bounded jsonl inventory.
+function* eachHumanText(env = process.env, { minLength = 4, selectedCwds = null } = {}) {
+  for (const { obj, cwd } of iterateSessionObjects(env)) {
+    if (selectedCwds !== null && (cwd === null || !selectedCwds.has(cwd))) continue;
+    yield* humanTextsFromObject(obj, { minLength });
+  }
+}
+
+module.exports = { eachHumanText, humanTextsFromObject };

package/src/translations-client.js

@@ -0,0 +1,84 @@
+'use strict';
+
+// Static-data i18n resolver. The hub stores skill (and other static-data) names
+// as KEYS (staticDataSkillsSkill_N); `GET translations?namespace=static-data`
+// returns every key with its per-language text. We fetch it ONCE (cached per
+// language for the process — MCP is long-lived) and resolve keys to names.
+
+const { postJsonWithTimeout } = require('./backend-request');
+const { reasonForError } = require('./onboarding-client');
+
+const DEFAULT_TIMEOUT_MS = 20000;
+const cache = new Map(); // langKey -> Map(key -> text)
+
+function parseJson(raw) {
+  try {
+    return raw ? JSON.parse(raw) : null;
+  } catch {
+    return null;
+  }
+}
+
+function bearerHeaders(accessToken) {
+  const headers = {};
+  if (typeof accessToken === 'string' && accessToken) headers.Authorization = `Bearer ${accessToken}`;
+  return headers;
+}
+
+async function requestTranslations({ hubAccessToken } = {}, { endpoint, namespace = 'static-data', timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  if (!endpoint) return { ok: false, reason: 'no-endpoint' };
+  if (!hubAccessToken) return { ok: false, reason: 'no-hub-token' };
+  const url = `${endpoint}${endpoint.includes('?') ? '&' : '?'}namespace=${encodeURIComponent(namespace)}`;
+  let res;
+  try {
+    res = await postJsonWithTimeout(url, null, timeoutMs, 'GET', null, bearerHeaders(hubAccessToken));
+  } catch (e) {
+    return { ok: false, reason: (e && e.kind) || 'network-error' };
+  }
+  if (res.status < 200 || res.status >= 300) return { ok: false, reason: reasonForError(res.status, res.raw) };
+  const env = parseJson(res.raw);
+  const data = env && env.status === 'OK' ? env.data : env;
+  const rows = Array.isArray(data) ? data : (Array.isArray(data && data.items) ? data.items : null);
+  if (!rows) return { ok: false, reason: 'bad-response' };
+  return { ok: true, rows };
+}
+
+// Returns `{ ok, map }`. On failure `map` is null (callers degrade to the raw
+// value rather than blocking the whole listing on a translations outage).
+async function fetchTranslationMap(deps = {}, { hubAccessToken, lang = 'en', timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const key = lang === 'es' ? 'es' : 'en';
+  if (cache.has(key)) return { ok: true, map: cache.get(key) };
+  const getEndpoint = deps.getTranslationsEndpoint || require('./config').getTranslationsEndpoint;
+  const request = deps.requestTranslations || requestTranslations;
+  const endpoint = getEndpoint();
+  if (!endpoint) return { ok: false, map: null, reason: 'no-endpoint' };
+  const res = await request({ hubAccessToken }, { endpoint, timeoutMs });
+  if (!res.ok) return { ok: false, map: null, reason: res.reason };
+  const map = new Map();
+  for (const r of res.rows) {
+    if (r && typeof r.key === 'string') {
+      const text = r[key] || r.en || r.es || null;
+      if (text) map.set(r.key, text);
+    }
+  }
+  cache.set(key, map);
+  return { ok: true, map };
+}
+
+// Resolve a name: if the map holds it (a static-data key) -> readable text;
+// otherwise return it unchanged (already-plain names, or unknown keys).
+function resolveName(map, name) {
+  if (!name || !map) return name;
+  return map.has(name) ? map.get(name) : name;
+}
+
+function clearCache() {
+  cache.clear();
+}
+
+module.exports = {
+  requestTranslations,
+  fetchTranslationMap,
+  resolveName,
+  clearCache,
+};

package/src/typewriter.js

@@ -0,0 +1,154 @@
+'use strict';
+
+const { isInteractive } = require('./terminal-progress');
+
+// Progressive reveal of text that is ALREADY IN HAND (talents-ai-score, camino A).
+
+// 60fps. Fine enough that the reveal reads as continuous, coarse enough that a
+// 700ms budget is ~43 writes rather than one per character.
+const TICK_MS = 16;
+
+// The hard ceiling on what this can add, for ANY length.
+const MAX_TOTAL_MS = 700;
+
+// How many code points to reveal per tick so that `length` finishes within `maxTicks`.
+function charsPerTick(length, maxTicks) {
+  if (!(length > 0)) return 0;
+  if (!(maxTicks > 0)) return length;
+  return Math.max(1, Math.ceil(length / maxTicks));
+}
+
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+// Writes `text` to `stream`, progressively in a TTY and in one write otherwise.
+async function typeOut(text, { stream, tickMs = TICK_MS, maxTotalMs = MAX_TOTAL_MS, sleep = defaultSleep } = {}) {
+  const s = typeof text === 'string' ? text : '';
+  if (!s || !stream || typeof stream.write !== 'function') return;
+  if (!isInteractive(stream)) {
+    stream.write(s);
+    return;
+  }
+  const chars = Array.from(s);
+  const maxTicks = Math.max(1, Math.floor((maxTotalMs > 0 ? maxTotalMs : 0) / (tickMs > 0 ? tickMs : TICK_MS)));
+  const step = charsPerTick(chars.length, maxTicks);
+  for (let i = 0; i < chars.length; i += step) {
+    stream.write(chars.slice(i, i + step).join(''));
+    // AFTER the write, and skipped on the last slice: the reveal ends when the
+    // text is on screen, never one idle tick later.
+    if (i + step < chars.length) await sleep(tickMs);
+  }
+}
+
+// Total for the WHOLE output, same order of magnitude as the typewriter's.
+const REVEAL_TOTAL_MS = 600;
+// A floor, so a two-section report still reads as a reveal rather than a blink, and
+// a ceiling, so a very long one never feels like waiting for the tool.
+const REVEAL_MIN_STEP_MS = 24;
+const REVEAL_MAX_STEP_MS = 120;
+const RULE_RE = /^[\s]*[\u2500\u2501\u2508\u2509-]{20,}[\s]*$/;
+
+// Splits rendered output into reveal chunks on BLANK LINES, holding everything between two horizontal rules together (the copyable block).
+function splitSections(text) {
+  const s = typeof text === 'string' ? text : '';
+  if (!s) return [];
+  const parts = s.split('\n');
+  const last = parts.length - 1;
+  const out = [];
+  let current = '';
+  let held = false;
+  for (let i = 0; i <= last; i++) {
+    const line = parts[i];
+    // The newline that FOLLOWED this line in the input belongs to this chunk, or the concatenation would lose it.
+    current += line + (i < last ? '\n' : '');
+    if (RULE_RE.test(line)) { held = !held; continue; }
+    if (line.trim() === '' && !held && current.length) {
+      out.push(current);
+      current = '';
+    }
+  }
+  if (current.length) out.push(current);
+  return out;
+}
+
+function revealEnabled({ stream = process.stdout, env = process.env, animate = null } = {}) {
+  if (animate === false) return false;
+  const flag = env ? env.NO_ANIMATION : undefined;
+  if (typeof flag === 'string' && flag.length > 0) return false;
+  return isInteractive(stream);
+}
+
+// Writes `text` to `stream`, one section at a time when the reveal is on and in a SINGLE write otherwise.
+async function revealText(text, { stream = process.stdout, env = process.env, animate = null, sleep = defaultSleep, totalMs = REVEAL_TOTAL_MS } = {}) {
+  const s = typeof text === 'string' ? text : '';
+  if (!s || !stream || typeof stream.write !== 'function') return;
+  if (!revealEnabled({ stream, env, animate })) {
+    stream.write(s);
+    return;
+  }
+  const sections = splitSections(s);
+  if (sections.length <= 1) {
+    stream.write(s);
+    return;
+  }
+  // THE FLOOR MUST NOT BREAK THE CEILING, and getting this wrong is the whole failure mode the issue warns about.
+  const maxPauses = Math.max(1, Math.floor(totalMs / REVEAL_MIN_STEP_MS));
+  const groups = [];
+  const perGroup = Math.ceil(sections.length / (maxPauses + 1));
+  for (let i = 0; i < sections.length; i += perGroup) groups.push(sections.slice(i, i + perGroup).join(''));
+  const step = Math.min(REVEAL_MAX_STEP_MS, Math.max(REVEAL_MIN_STEP_MS, Math.floor(totalMs / groups.length)));
+  for (let i = 0; i < groups.length; i++) {
+    stream.write(groups[i]);
+    // After the write and never after the last one: the reveal ends when the report
+    // is on screen, not one step later.
+    if (i < groups.length - 1) await sleep(step);
+  }
+}
+
+// Backlog we tolerate before speeding up the reveal: at TICK_MS this bounds how
+// far behind the stream the animation can lag (~STREAM_CATCHUP_TICKS * tickMs).
+const STREAM_CATCHUP_TICKS = 50;
+
+// A STREAMING typewriter for text that arrives in chunks over time (Alma's NDJSON
+// deltas). Same pacing + gate as the report's reveal: char-by-char in a TTY,
+// plain pass-through otherwise (non-TTY / NO_ANIMATION). `push(text)` feeds the
+// queue; a single loop drains it at `tickMs`, revealing more per tick when the
+// queue backs up so a big chunk animates continuously instead of dumping at once.
+// `end()` flushes whatever is left and resolves.
+function makeStreamReveal({ stream = process.stdout, env = process.env, animate = null, tickMs = TICK_MS, sleep = defaultSleep, catchupTicks = STREAM_CATCHUP_TICKS } = {}) {
+  const canWrite = stream && typeof stream.write === 'function';
+  if (!canWrite || !revealEnabled({ stream, env, animate })) {
+    // Plain: write each chunk as it arrives, no pacing (matches the report's
+    // non-TTY degradation).
+    return { push: (t) => { if (t && canWrite) stream.write(String(t)); }, end: async () => {} };
+  }
+  const queue = [];
+  let ended = false;
+  let draining = null;
+  const drain = async () => {
+    for (;;) {
+      if (queue.length === 0) {
+        if (ended) return;
+        await sleep(tickMs); // wait for more input without busy-spinning
+        continue;
+      }
+      const step = Math.max(1, Math.ceil(queue.length / catchupTicks));
+      stream.write(queue.splice(0, step).join(''));
+      if (queue.length > 0 || !ended) await sleep(tickMs);
+    }
+  };
+  return {
+    push: (t) => {
+      if (!t) return;
+      for (const ch of String(t)) queue.push(ch);
+      if (!draining) draining = drain();
+    },
+    end: async () => { ended = true; if (draining) await draining; },
+  };
+}
+
+module.exports = {
+  typeOut, charsPerTick, TICK_MS, MAX_TOTAL_MS,
+  revealText, splitSections, revealEnabled,
+  makeStreamReveal, STREAM_CATCHUP_TICKS,
+  REVEAL_TOTAL_MS, REVEAL_MIN_STEP_MS, REVEAL_MAX_STEP_MS,
+};