@eduardbar/drift 1.1.0 → 1.2.0

package/docs/PRD.md

@@ -1,208 +1,157 @@
 # PRD - drift
 
-Version: 1.1-draft  
-Estado: Draft  
+Version: 1.2.0  
+Estado: Activo  
 Producto: `@eduardbar/drift`
 
 ## 1) Contexto
 
-`drift` es un CLI de analisis estatico para TypeScript que detecta deuda tecnica asociada a codigo generado por IA y calcula un score de calidad por archivo y por repositorio.
+`drift` es un CLI de analisis estatico para TypeScript que detecta deuda tecnica asociada a codigo generado por IA y calcula score por archivo y por repositorio.
 
-Hoy el producto ya cubre escaneo AST, score, reportes y comandos operativos (`scan`, `fix`, `report`, `ci`, `diff`, `badge`, `snapshot`, `trend`, `blame`).
+Con release `v1.2.0`, el producto entrega comandos operativos, analisis AST, reglas de arquitectura configurables, salida accionable, workflow CI para PR comments, y foundations SaaS (`drift cloud ingest|summary|dashboard`) con politica free-until-7500.
 
-Este PRD define la evolucion para convertir a drift en una plataforma de calidad de codigo AI-first, con foco en revision de PRs, reglas de arquitectura y accionabilidad.
+## 2) Vision de producto
 
-## 2) Vision de Producto
+Ser la herramienta de referencia para equipos que usan IA para programar y necesitan detectar, priorizar y corregir deuda tecnica antes de mergear a produccion.
 
-Ser la herramienta de referencia para equipos que usan IA para programar y necesitan detectar, priorizar y corregir deuda tecnica antes de que llegue a produccion.
-
-## 3) Killer Feature
+## 3) Killer feature
 
 ## AI Code Smell Detector
 
-El diferencial principal de drift es detectar patrones de olor tecnico vinculados a codigo IA, estimar probabilidad de origen IA y traducir hallazgos en acciones concretas (fixes, comentarios de PR, reglas de arquitectura y reportes).
-
-## 4) Objetivos de Negocio y Producto
-
-- Reducir riesgo de mantenimiento en repos con alto volumen de codigo IA.
-- Dar feedback accionable en el punto de trabajo (CLI, PR y editor).
-- Estandarizar calidad arquitectonica con reglas configurables por equipo.
-- Escalar desde CLI local a experiencia organizacional (dashboard SaaS).
-
-## 5) Alcance MVP por Feature (sin humo)
-
-Cada feature incluye objetivo, alcance MVP y criterios de aceptacion.
-
-### 5.1 Detector de codigo generado por IA
-
-- Objetivo: estimar `ai_likelihood` por archivo y listar `files_suspected`.
-- Alcance MVP:
-  - Exponer `ai_likelihood` (0-100) dentro de salida JSON/AI.
-  - Agregar lista ordenada de archivos sospechados con score y reglas disparadas.
-  - No hacer afirmaciones absolutas; reportar como probabilidad.
-- Criterios de aceptacion:
-  - `drift scan <path> --ai` incluye `ai_likelihood` por archivo.
-  - Reporte global incluye `files_suspected` y top N archivos.
-  - Tests cubren serializacion y orden de prioridad.
-
-### 5.2 PR reviewer automatico (`drift review` + comentario en PR)
-
-- Objetivo: revisar cambios de PR y publicar feedback tecnico automatico.
-- Alcance MVP:
-  - Nuevo comando `drift review` para analizar diff contra base branch.
-  - Salida markdown apta para comentario de PR.
-  - Integracion base via GitHub CLI (`gh`) en CI.
-- Criterios de aceptacion:
-  - `drift review --base main` devuelve score de PR y top issues.
-  - En workflow CI se publica un comentario unico actualizable.
-  - Si score supera umbral configurable, CI falla.
-
-### 5.3 Reglas de arquitectura configurables
-
-- Objetivo: habilitar reglas de arquitectura de negocio definidas por el equipo.
-- Alcance MVP:
-  - Soporte en `drift.config.ts` para:
-    - `controller-no-db`
-    - `service-no-http`
-    - `max-function-lines`
-  - Mensajes de error claros con ubicacion y recomendacion.
-- Criterios de aceptacion:
-  - Config valida y tipada.
-  - Reglas activas afectan score y aparecen en reporte.
-  - Fixtures de test para casos validos e invalidos.
-
-### 5.4 Score de calidad por repo con breakdown
-
-- Objetivo: mostrar salud del repo en forma ejecutiva y tecnica.
-- Alcance MVP:
-  - Score global del repo.
-  - Breakdown por severidad, regla y carpeta.
-  - Tendencia minima (ultimos snapshots locales).
-- Criterios de aceptacion:
-  - `drift scan` muestra score repo + breakdown resumido.
-  - `--json` expone estructura consumible por CI/dashboard.
-
-### 5.5 Mapa de arquitectura automatico (`drift map` -> `architecture.svg`)
-
-- Objetivo: visualizar dependencias y violaciones de capas.
-- Alcance MVP:
-  - Nuevo comando `drift map`.
-  - Genera `architecture.svg` desde imports y modulos detectados.
-  - Marca ciclos y violaciones de capas.
-- Criterios de aceptacion:
-  - `drift map ./src` crea `architecture.svg` sin edicion manual.
-  - El SVG es legible en repos medianos (ej. <= 300 archivos TS).
-
-### 5.6 VSCode extension con feedback en tiempo real
-
-- Objetivo: bajar el tiempo entre error y correccion.
-- Alcance MVP:
-  - Diagnosticos por archivo al guardar.
-  - Score visible por archivo.
-  - Quick actions para sugerencias simples.
-- Criterios de aceptacion:
-  - La extension muestra issues drift en panel Problems.
-  - La latencia por archivo en save se mantiene en nivel usable.
-
-### 5.7 Fix automatico (`drift fix`) con ejemplo antes/despues
-
-- Objetivo: convertir hallazgos en cambios concretos de bajo riesgo.
-- Alcance MVP:
-  - `drift fix` aplica fixes seguros en reglas seleccionadas.
-  - Modo preview con diff antes/despues.
-  - Modo write con confirmacion.
-- Criterios de aceptacion:
-  - `drift fix --preview` imprime diff legible.
-  - `drift fix --write` modifica solo reglas soportadas.
-  - Tests de no-regresion para no romper sintaxis TS.
-
-Ejemplo (antes/despues):
-
-```ts
-// Antes
-console.log(userData)
-
-// Despues (sugerencia simple)
-// Removed debug leftover; use structured logger if needed.
-```
-
-### 5.8 Reporte tecnico (`drift report` -> `drift-report.html`)
-
-- Objetivo: entregar reporte compartible para devs, tech leads y QA.
-- Alcance MVP:
-  - Salida HTML `drift-report.html` con score, breakdown y top issues.
-  - Secciones por archivo con snippets y sugerencias.
-- Criterios de aceptacion:
-  - `drift report ./src --html` genera archivo navegable.
-  - El reporte puede adjuntarse en CI artifacts.
-
-### 5.9 Metricas de riesgo de mantenimiento (hotspots)
-
-- Objetivo: priorizar deuda por impacto real.
-- Alcance MVP:
-  - Hotspots combinando score + frecuencia de cambios + criticidad.
-  - Ranking de archivos para plan de refactor.
-- Criterios de aceptacion:
-  - `drift trend` o salida dedicada muestra top hotspots.
-  - Metodo de ranking documentado y testeado.
-
-### 5.10 Plugin system (`drift-plugin-*`)
-
-- Objetivo: extender drift sin tocar el core.
-- Alcance MVP:
-  - Carga de plugins por convension `drift-plugin-*`.
-  - API minima para registrar reglas y metadata.
-  - Aislamiento de errores de plugins para no romper scan completo.
-- Criterios de aceptacion:
-  - Plugin de ejemplo funcional en repo de ejemplo.
-  - Si un plugin falla, drift sigue ejecutando y reporta el error.
-
-## 6) Roadmap Realista
-
-### v1.1
-
-- `drift review` para PR comments.
-- Score de PR y score de repo con breakdown minimo.
-
-### v1.2
+Detectar patrones de olor tecnico vinculados a codigo IA, estimar probabilidad de origen IA y traducir hallazgos en acciones concretas (fixes, review de PR, reglas de arquitectura y reportes).
+
+## 4) Estado de cumplimiento (actualizado)
+
+### Entregado
+
+- `drift review` en CLI para analizar diff contra base y producir markdown usable en PR.
+- `drift map` basico para generar `architecture.svg`.
+- Senial de IA en salida (`ai_likelihood` y `files_suspected`).
+- Reglas de arquitectura configurables via `drift.config.ts`.
+- Score y breakdown por dimensiones para lectura ejecutiva y tecnica.
+- Metricas de maintenance risk/hotspots.
+- Plugin system MVP (`drift-plugin-*`) con aislamiento de errores.
+- `drift fix` con modos preview/write.
+- Workflow CI para comentario automatico unico y actualizable de `drift review`.
+- `drift map` con marcado de cycle edges y layer violations en el SVG.
+- VSCode quick actions para fixes de bajo riesgo.
+- Confirmacion interactiva para `drift fix --write` (con `--yes` para CI/no-interactive).
+- `drift report` HTML (`drift-report.html`) sin flag extra.
+- Documentacion y tests del release.
+
+### Parcial
+
+- Consolidacion/hardening de API de plugins para ecosistema externo amplio.
+
+### Pendiente
+
+- Hardening del contrato de plugins para ecosistema externo amplio.
+- Evolucion del dashboard SaaS foundations a experiencia multi-tenant full (auth, permisos por rol y billing activo post-umbral).
+
+## 5) Criterios de aceptacion vigentes
+
+### 5.1 Entregables cerrados en v1.1.0
+
+- `drift review --base <ref>` devuelve score delta de PR, issues nuevos/resueltos y markdown.
+- `drift scan --ai` incluye `ai_likelihood` y ranking `files_suspected`.
+- `drift map <path>` genera `architecture.svg` utilizable sin edicion manual.
+- `drift report [path]` genera HTML self-contained (no requiere `--html`).
+- `drift fix --preview` muestra antes/despues y `drift fix --write` aplica reglas soportadas.
+
+### 5.1.b Entregables cerrados en v1.2 (scope tecnico)
+
+- Workflow CI publica/actualiza comentario unico en PR para `drift review`.
+- `drift map` marca visualmente ciclos y violaciones por capa.
+- Extension VSCode expone quick actions para `debug-leftover` y `catch-swallow`.
+- `drift fix --write` pide confirmacion interactiva por defecto y admite `--yes`.
+
+### 5.2 Objetivos aun abiertos (CI/editor/UX)
+
+- Hardening del contrato de plugins para compatibilidad de largo plazo (versionado/migraciones).
+
+## 6) Roadmap actualizado
+
+### v1.1 (completado - release 1.1.0)
+
+Prioridades cerradas:
+- CLI de review para PR, mapa basico, salida AI, reglas configurables, report HTML, fix preview/write, hotspots, plugin MVP.
+
+Done del bloque:
+- Features documentadas.
+- Tests de paths principales.
+- Salidas CLI/JSON/AI consistentes para uso local y CI.
+
+### v1.2 (completado - cierre de pendientes tecnicos)
+
+Prioridades cerradas:
+- Comentario automatico actualizable en PR desde workflow CI.
+- Mejora de `drift map` para destacar ciclos y violaciones.
+- UX de seguridad para `drift fix --write` con confirmacion interactiva.
+
+Done del bloque:
+- Flujo CI reproducible con comentario unico por PR.
+- Visualizaciones verificables en SVG sobre repos medianos.
+- Confirmacion interactiva implementada para write mode.
+
+### v2 (prioridad: experiencia de editor + extensibilidad)
+
+Prioridades:
+- Consolidacion de API de plugins y hardening de compatibilidad.
+- Reglas de plugin versionadas y validacion de contrato avanzada.
+
+Criterio de done:
+- Plugins con contrato estable y manejo de errores robusto.
+- Documentacion de versionado para autores de plugins.
 
-- Reglas de arquitectura configurables.
-- `drift map` y generacion de `architecture.svg`.
+### v3 (fundations completadas en v1.2.0)
 
-### v2
+Prioridades cerradas:
+- Base de datos local de snapshots para cloud MVP.
+- Ingestion de reportes en storage local SaaS-like.
+- Summary de uso/threshold y dashboard HTML inicial.
+- Guardrails de fase gratuita por workspace + politica free-until-7500.
 
-- VSCode extension con feedback en tiempo real.
-- `drift fix` con preview/write y fixes seguros.
+Siguiente incremento (v3.x):
+- Auth real multi-tenant, permisos por equipo y backend remoto persistente.
+- Activacion de billing cuando el umbral de 7.500 usuarios se cumpla.
 
-### v3
+## 6.1) Estrategia de monetizacion (aprobada)
 
-- SaaS dashboard para historico, equipos y gobierno de calidad.
+- Fase gratuita: Drift SaaS gratis hasta alcanzar 7.500 usuarios registrados.
+- Trigger de monetizacion: al alcanzar 7.500 usuarios, activar planes pagos para nuevos usuarios y definir politica de migracion para cohortes gratuitas.
+- Objetivo: priorizar adopcion y proof-of-value temprano sin friccion comercial inicial.
+- Guardrails durante fase gratuita:
+  - Limites tecnicos por workspace (runs/mes, retencion de historial, repositorios activos).
+  - Instrumentacion de uso desde el dia 1 para evitar abuso y medir unit economics.
+  - Feature flags de pricing listas antes del trigger para evitar corte abrupto.
 
-## 7) Fuera de Alcance (por ahora)
+## 7) Fuera de alcance actual
 
 - Soporte multi-lenguaje completo fuera de TypeScript/JS.
-- Autofix de reglas de alto riesgo sin confirmacion.
+- Autofix de reglas de alto riesgo sin confirmacion explicita.
 - Integraciones propietarias cerradas sin API estable.
 
-## 8) KPIs de Exito
+## 8) KPIs de exito
 
 - Reduccion de score promedio en repos activos.
 - % de PRs con feedback drift resuelto antes de merge.
 - Tiempo medio desde deteccion hasta fix aplicado.
-- Adopcion de reglas de arquitectura por equipo.
+- Adopcion de reglas de arquitectura configurables por equipo.
 
-## 9) Dependencias y Riesgos
+## 9) Dependencias y riesgos
 
-- Performance en repos grandes (AST + analisis cross-file).
-- Calidad de senial en `ai_likelihood` (riesgo de falsos positivos).
-- Compatibilidad de integraciones CI/PR entre plataformas.
-- Diseno de API de plugins sin romper backward compatibility.
+- Performance en repos grandes (AST + cross-file).
+- Calidad de senial en `ai_likelihood` (falsos positivos/negativos).
+- Variabilidad de entornos CI para publicar comentarios de PR.
+- Evolucion de API de plugins sin romper backward compatibility.
 
-## 10) Definicion de Done (global)
+## 10) Definition of Done por release
 
-Una feature del roadmap se considera terminada cuando:
+Checklist minimo por release:
 
-- Tiene comando/flujo usable y documentado.
-- Tiene tests automatizados de casos base y borde.
-- Tiene salida estable en CLI/JSON para CI.
-- Tiene criterios de aceptacion de esta PRD cumplidos.
+- [ ] Scope del release cerrado y trazable a este PRD.
+- [ ] Comandos/flujo documentados con ejemplos reales.
+- [ ] Tests de regresion en paths principales y casos borde.
+- [ ] Salidas CLI/JSON/AI estables para automatizacion.
+- [ ] Criterios de aceptacion del bloque marcados como cumplidos o movidos a pendiente.
+- [ ] Riesgos y tradeoffs explicitados en notas de release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eduardbar/drift",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Detect silent technical debt left by AI-generated code",
   "type": "module",
   "main": "dist/index.js",

package/packages/vscode-drift/src/code-actions.ts

@@ -0,0 +1,53 @@
+import * as vscode from 'vscode'
+
+function buildRemoveLineEdit(document: vscode.TextDocument, line: number): vscode.WorkspaceEdit {
+  const edit = new vscode.WorkspaceEdit()
+  const targetLine = document.lineAt(line)
+  const start = targetLine.range.start
+  const end = line < document.lineCount - 1
+    ? document.lineAt(line + 1).range.start
+    : targetLine.range.end
+  edit.delete(document.uri, new vscode.Range(start, end))
+  return edit
+}
+
+function buildCatchTodoEdit(document: vscode.TextDocument, line: number): vscode.WorkspaceEdit {
+  const edit = new vscode.WorkspaceEdit()
+  const targetLine = document.lineAt(line)
+  const baseIndent = targetLine.text.match(/^\s*/)?.[0] ?? ''
+  const indent = `${baseIndent}  `
+  edit.insert(document.uri, new vscode.Position(line + 1, 0), `${indent}// TODO: handle error\n`)
+  return edit
+}
+
+export class DriftCodeActionProvider implements vscode.CodeActionProvider {
+  provideCodeActions(
+    document: vscode.TextDocument,
+    _range: vscode.Range,
+    context: vscode.CodeActionContext,
+  ): vscode.CodeAction[] {
+    const actions: vscode.CodeAction[] = []
+
+    for (const diagnostic of context.diagnostics) {
+      if (diagnostic.source !== 'drift') continue
+      const rule = String(diagnostic.code ?? '')
+      const line = diagnostic.range.start.line
+
+      if (rule === 'debug-leftover') {
+        const quickFix = new vscode.CodeAction('drift: remove debug leftover line', vscode.CodeActionKind.QuickFix)
+        quickFix.diagnostics = [diagnostic]
+        quickFix.edit = buildRemoveLineEdit(document, line)
+        actions.push(quickFix)
+      }
+
+      if (rule === 'catch-swallow') {
+        const quickFix = new vscode.CodeAction('drift: add TODO in empty catch', vscode.CodeActionKind.QuickFix)
+        quickFix.diagnostics = [diagnostic]
+        quickFix.edit = buildCatchTodoEdit(document, line)
+        actions.push(quickFix)
+      }
+    }
+
+    return actions
+  }
+}

package/packages/vscode-drift/src/extension.ts

@@ -5,6 +5,7 @@ import { analyzeFilePath } from './analyzer'
 import { DriftDiagnosticsProvider } from './diagnostics'
 import { DriftTreeProvider } from './treeview'
 import { DriftStatusBarItem } from './statusbar'
+import { DriftCodeActionProvider } from './code-actions'
 import type { FileReport } from '@eduardbar/drift'
 
 const SUPPORTED_LANGUAGES = ['typescript', 'typescriptreact', 'javascript', 'javascriptreact']
@@ -87,6 +88,7 @@ export function activate(context: vscode.ExtensionContext): void {
   const diagnostics = new DriftDiagnosticsProvider()
   const treeProvider = new DriftTreeProvider()
   const statusBar = new DriftStatusBarItem()
+  const codeActions = new DriftCodeActionProvider()
 
   const treeView = vscode.window.createTreeView('driftIssues', {
     treeDataProvider: treeProvider,
@@ -121,6 +123,14 @@ export function activate(context: vscode.ExtensionContext): void {
     }
   )
 
+  const codeActionRegistration = vscode.languages.registerCodeActionsProvider(
+    SUPPORTED_LANGUAGES.map((language) => ({ language })),
+    codeActions,
+    {
+      providedCodeActionKinds: [vscode.CodeActionKind.QuickFix],
+    },
+  )
+
   context.subscriptions.push(
     { dispose: () => diagnostics.dispose() },
     { dispose: () => statusBar.dispose() },
@@ -129,6 +139,7 @@ export function activate(context: vscode.ExtensionContext): void {
     scanCmd,
     clearCmd,
     goToCmd,
+    codeActionRegistration,
   )
 }
 

package/src/cli.ts

@@ -2,8 +2,10 @@
 // drift-ignore-file
 import { Command } from 'commander'
 import { writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { basename, resolve } from 'node:path'
 import { createRequire } from 'node:module'
+import { createInterface } from 'node:readline/promises'
+import { stdin as input, stdout as output } from 'node:process'
 const require = createRequire(import.meta.url)
 const { version: VERSION } = require('../package.json') as { version: string }
 import { analyzeProject, analyzeFile, TrendAnalyzer, BlameAnalyzer } from './analyzer.js'
@@ -19,6 +21,7 @@ import { applyFixes, type FixResult } from './fix.js'
 import { loadHistory, saveSnapshot, printHistory, printSnapshotDiff } from './snapshot.js'
 import { generateReview } from './review.js'
 import { generateArchitectureMap } from './map.js'
+import { ingestSnapshotFromReport, getSaasSummary, generateSaasDashboardHtml } from './saas.js'
 
 const program = new Command()
 
@@ -155,7 +158,8 @@ program
   .action(async (targetPath: string | undefined, options: { output: string }) => {
     const resolvedPath = resolve(targetPath ?? '.')
     process.stderr.write(`\nBuilding architecture map for ${resolvedPath}...\n`)
-    const out = generateArchitectureMap(resolvedPath, options.output)
+    const config = await loadConfig(resolvedPath)
+    const out = generateArchitectureMap(resolvedPath, options.output, config)
     process.stderr.write(`  Architecture map saved to ${out}\n\n`)
   })
 
@@ -259,12 +263,38 @@ program
   .option('--preview', 'Preview changes without writing files')
   .option('--write', 'Write fixes to disk')
   .option('--dry-run', 'Show what would change without writing files')
-  .action(async (targetPath: string | undefined, options: { rule?: string; dryRun?: boolean; preview?: boolean; write?: boolean }) => {
+  .option('-y, --yes', 'Skip interactive confirmation for --write')
+  .action(async (targetPath: string | undefined, options: { rule?: string; dryRun?: boolean; preview?: boolean; write?: boolean; yes?: boolean }) => {
     const resolvedPath = resolve(targetPath ?? '.')
     const config = await loadConfig(resolvedPath)
     const previewMode = Boolean(options.preview || options.dryRun)
     const writeMode = options.write ?? !previewMode
 
+    if (writeMode && !options.yes) {
+      const previewResults = await applyFixes(resolvedPath, config, {
+        rule: options.rule,
+        dryRun: true,
+        preview: true,
+        write: false,
+      })
+
+      if (previewResults.length === 0) {
+        console.log('No fixable issues found.')
+        return
+      }
+
+      const files = new Set(previewResults.map((result) => result.file)).size
+      const prompt = `Apply ${previewResults.length} fix(es) across ${files} file(s)? [y/N] `
+      const rl = createInterface({ input, output })
+      const answer = (await rl.question(prompt)).trim().toLowerCase()
+      rl.close()
+
+      if (answer !== 'y' && answer !== 'yes') {
+        console.log('Aborted. No files were modified.')
+        return
+      }
+    }
+
     const results = await applyFixes(resolvedPath, config, {
       rule: options.rule,
       dryRun: previewMode,
@@ -348,4 +378,83 @@ program
     process.stdout.write(`  Saved to drift-history.json\n\n`)
   })
 
+const cloud = program
+  .command('cloud')
+  .description('Local SaaS foundations: ingest, summary, and dashboard')
+
+cloud
+  .command('ingest [path]')
+  .description('Scan path, build report, and store cloud snapshot')
+  .requiredOption('--workspace <id>', 'Workspace id')
+  .requiredOption('--user <id>', 'User id')
+  .option('--repo <name>', 'Repo name (default: basename of scanned path)')
+  .option('--store <file>', 'Store file path (default: .drift-cloud/store.json)')
+  .action(async (targetPath: string | undefined, options: { workspace: string; user: string; repo?: string; store?: string }) => {
+    const resolvedPath = resolve(targetPath ?? '.')
+    process.stderr.write(`\nScanning ${resolvedPath} for cloud ingest...\n`)
+    const config = await loadConfig(resolvedPath)
+    const files = analyzeProject(resolvedPath, config)
+    const report = buildReport(resolvedPath, files)
+
+    const snapshot = ingestSnapshotFromReport(report, {
+      workspaceId: options.workspace,
+      userId: options.user,
+      repoName: options.repo ?? basename(resolvedPath),
+      storeFile: options.store,
+      policy: config?.saas,
+    })
+
+    process.stdout.write(`Ingested snapshot ${snapshot.id}\n`)
+    process.stdout.write(`Workspace: ${snapshot.workspaceId}  Repo: ${snapshot.repoName}\n`)
+    process.stdout.write(`Score: ${snapshot.totalScore}/100  Issues: ${snapshot.totalIssues}\n\n`)
+  })
+
+cloud
+  .command('summary')
+  .description('Show SaaS usage metrics and free threshold status')
+  .option('--json', 'Output raw JSON summary')
+  .option('--store <file>', 'Store file path (default: .drift-cloud/store.json)')
+  .action((options: { json?: boolean; store?: string }) => {
+    const summary = getSaasSummary({ storeFile: options.store })
+
+    if (options.json) {
+      process.stdout.write(JSON.stringify(summary, null, 2) + '\n')
+      return
+    }
+
+    process.stdout.write('\n')
+    process.stdout.write(`Phase: ${summary.phase.toUpperCase()}\n`)
+    process.stdout.write(`Users registered: ${summary.usersRegistered}\n`)
+    process.stdout.write(`Active workspaces (30d): ${summary.workspacesActive}\n`)
+    process.stdout.write(`Active repos (30d): ${summary.reposActive}\n`)
+    process.stdout.write(`Total snapshots: ${summary.totalSnapshots}\n`)
+    process.stdout.write(`Free user threshold: ${summary.policy.freeUserThreshold}\n`)
+    process.stdout.write(`Threshold reached: ${summary.thresholdReached ? 'yes' : 'no'}\n`)
+    process.stdout.write(`Free users remaining: ${summary.freeUsersRemaining}\n`)
+    process.stdout.write('Runs per month:\n')
+
+    const monthly = Object.entries(summary.runsPerMonth).sort(([a], [b]) => a.localeCompare(b))
+    if (monthly.length === 0) {
+      process.stdout.write('  - none\n\n')
+      return
+    }
+
+    for (const [month, runs] of monthly) {
+      process.stdout.write(`  - ${month}: ${runs}\n`)
+    }
+    process.stdout.write('\n')
+  })
+
+cloud
+  .command('dashboard')
+  .description('Generate an HTML dashboard with trends and hotspots')
+  .option('-o, --output <file>', 'Output HTML file', 'drift-cloud-dashboard.html')
+  .option('--store <file>', 'Store file path (default: .drift-cloud/store.json)')
+  .action((options: { output: string; store?: string }) => {
+    const html = generateSaasDashboardHtml({ storeFile: options.store })
+    const outPath = resolve(options.output)
+    writeFileSync(outPath, html, 'utf8')
+    process.stdout.write(`Dashboard saved to ${outPath}\n`)
+  })
+
 program.parse()

package/src/index.ts

@@ -17,3 +17,18 @@ export type {
 } from './types.js'
 export { loadHistory, saveSnapshot } from './snapshot.js'
 export type { SnapshotEntry, SnapshotHistory } from './snapshot.js'
+export {
+  DEFAULT_SAAS_POLICY,
+  defaultSaasStorePath,
+  resolveSaasPolicy,
+  ingestSnapshotFromReport,
+  getSaasSummary,
+  generateSaasDashboardHtml,
+} from './saas.js'
+export type {
+  SaasPolicy,
+  SaasStore,
+  SaasSummary,
+  SaasSnapshot,
+  IngestOptions,
+} from './saas.js'