/** * Live stage progress rendered with `ora` spinners. Consumes the same `PipelineProgressEvent` * stream the SSE endpoint uses (ARCHITECTURE.md §3.11), so the CLI and the web app never drift. */ import chalk, { type ChalkInstance } from "chalk"; import ora, { type Ora } from "ora"; import type { PipelineProgressEvent } from "@yff/core"; const STAGE_LABELS: Record = { "resolve:identity": "Resolving identity", "graph:follows": "Fetching your follows", affinity: "Computing affinity weights", "harvest:created": "Harvesting feeds you created", "harvest:likes": "Harvesting feeds your network liked", "harvest:packs": "Harvesting feeds from starter packs", "harvest:shared": "Harvesting feeds shared in posts", hydrate: "Hydrating feed metadata", confirm: "Confirming endorsements", health: "Probing feed health", categorize: "Categorizing feeds", rank: "Ranking and diversifying", }; function label(stage: string): string { return STAGE_LABELS[stage] ?? stage; } export interface ProgressReporterOptions { verbose: boolean; color: boolean; /** Set true in non-TTY environments (piped output, `--format json`, CI) to skip spinner frames. */ quiet?: boolean; } export class ProgressReporter { private readonly spinner: Ora; private readonly c: ChalkInstance; private readonly active = new Map(); private readonly verbose: boolean; constructor(opts: ProgressReporterOptions) { this.c = chalk; this.verbose = opts.verbose; this.spinner = ora({ isEnabled: !opts.quiet, color: "cyan", stream: process.stderr }); } private refresh(): void { if (this.active.size === 0) return; const names = [...this.active.keys()].map(label).join(", "); const text = `${names}…`; if (this.spinner.isSpinning) this.spinner.text = text; else this.spinner.start(text); } handle = (event: PipelineProgressEvent): void => { switch (event.type) { case "stage:start": { this.active.set(event.stage, Date.now()); this.refresh(); break; } case "stage:done": { this.active.delete(event.stage); const pct = Math.round(event.coverage * 100); const line = `${label(event.stage)} ${this.c.dim(`(${pct}% coverage)`)}`; if (this.spinner.isSpinning) { this.spinner.stopAndPersist({ symbol: this.c.green("✓"), text: line }); } else { console.error(`${this.c.green("✓")} ${line}`); } this.refresh(); break; } case "diagnostic": { if (!this.verbose) break; const wasSpinning = this.spinner.isSpinning; if (wasSpinning) this.spinner.stop(); const prefix = event.level === "error" ? this.c.red("✗") : event.level === "warn" ? this.c.yellow("!") : this.c.dim("i"); console.error(`${prefix} ${this.c.dim(`[${event.code}]`)} ${event.message}`); if (wasSpinning) this.refresh(); break; } case "error": { this.spinner.fail(event.message); break; } case "complete": { if (this.spinner.isSpinning) this.spinner.stop(); break; } case "partial": case "stage:progress": break; } }; }