@eduardbar/drift 1.1.0 → 1.3.0

package/src/cli.ts

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 // drift-ignore-file
 import { Command } from 'commander'
-import { writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { readFileSync, writeFileSync } from 'node:fs'
+import { basename, relative, 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,28 +21,130 @@ 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 {
+  changeOrganizationPlan,
+  generateSaasDashboardHtml,
+  getOrganizationEffectiveLimits,
+  getOrganizationUsageSnapshot,
+  getSaasSummary,
+  ingestSnapshotFromReport,
+  listOrganizationPlanChanges,
+} from './saas.js'
+import {
+  buildTrustReport,
+  explainTrustGatePolicy,
+  formatTrustGatePolicyExplanation,
+  formatTrustJson,
+  renderTrustOutput,
+  shouldFailTrustGate,
+  normalizeMergeRiskLevel,
+  MERGE_RISK_ORDER,
+  detectBranchName,
+} from './trust.js'
+import { computeTrustKpis, formatTrustKpiConsole, formatTrustKpiJson } from './trust-kpi.js'
+import type { DriftDiff, DriftTrustReport, DriftAnalysisOptions, MergeRiskLevel } from './types.js'
+import type { TrustGatePolicyExplanation } from './trust.js'
+import type { SnapshotHistory } from './snapshot.js'
 
 const program = new Command()
 
+type ResourceOptionFlags = {
+  lowMemory?: boolean
+  chunkSize?: string
+  maxFiles?: string
+  maxFileSizeKb?: string
+  withSemanticDuplication?: boolean
+}
+
+function parseOptionalPositiveInt(rawValue: string | undefined, flagName: string): number | undefined {
+  if (rawValue == null) return undefined
+  const value = Number(rawValue)
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`${flagName} must be a non-negative integer`)
+  }
+  return value
+}
+
+function resolveAnalysisOptions(options: ResourceOptionFlags): DriftAnalysisOptions {
+  return {
+    lowMemory: options.lowMemory,
+    chunkSize: parseOptionalPositiveInt(options.chunkSize, '--chunk-size'),
+    maxFiles: parseOptionalPositiveInt(options.maxFiles, '--max-files'),
+    maxFileSizeKb: parseOptionalPositiveInt(options.maxFileSizeKb, '--max-file-size-kb'),
+    includeSemanticDuplication: options.withSemanticDuplication ? true : undefined,
+  }
+}
+
+function addResourceOptions(command: Command): Command {
+  return command
+    .option('--low-memory', 'Reduce peak memory usage by chunking AST analysis')
+    .option('--chunk-size <n>', 'Files per chunk in low-memory mode (default: 40)')
+    .option('--max-files <n>', 'Maximum files to analyze before soft-skipping extras')
+    .option('--max-file-size-kb <n>', 'Skip files above this size and report diagnostics')
+    .option('--with-semantic-duplication', 'Keep semantic-duplication rule enabled in low-memory mode')
+}
+
+function parseTrustGateOverrides(options: { minTrust?: string; maxRisk?: string }): { minTrust?: number; maxRisk?: MergeRiskLevel } {
+  const cliMinTrust = options.minTrust ? Number(options.minTrust) : undefined
+  if (options.minTrust && Number.isNaN(cliMinTrust)) {
+    process.stderr.write('\n  Error: --min-trust must be a valid number\n\n')
+    process.exit(1)
+  }
+
+  let cliMaxRisk: MergeRiskLevel | undefined
+  if (options.maxRisk) {
+    cliMaxRisk = normalizeMergeRiskLevel(options.maxRisk)
+    if (!cliMaxRisk) {
+      process.stderr.write(`\n  Error: --max-risk must be one of ${MERGE_RISK_ORDER.join(', ')}\n\n`)
+      process.exit(1)
+    }
+  }
+
+  return {
+    minTrust: typeof cliMinTrust === 'number' ? cliMinTrust : undefined,
+    maxRisk: cliMaxRisk,
+  }
+}
+
+function resolveBranchFromOption(branch?: string): string | undefined {
+  const normalized = branch?.trim()
+  if (normalized) return normalized
+  return detectBranchName()
+}
+
+function printTrustGatePolicyDebug(explanation: TrustGatePolicyExplanation): void {
+  process.stderr.write(`${formatTrustGatePolicyExplanation(explanation)}\n`)
+  if (explanation.invalidPolicyPack) {
+    process.stderr.write(`Warning: policy pack '${explanation.invalidPolicyPack}' was not found. Falling back to base/preset policy.\n`)
+  }
+}
+
+function printSaasErrorAndExit(error: unknown): never {
+  const message = error instanceof Error ? error.message : String(error)
+  process.stderr.write(`\n  Error: ${message}\n\n`)
+  process.exit(1)
+}
+
 program
   .name('drift')
-  .description('Detect silent technical debt left by AI-generated code')
+  .description('AI Code Audit CLI for merge trust in AI-assisted PRs')
   .version(VERSION)
 
-program
-  .command('scan [path]', { isDefault: true })
+addResourceOptions(
+  program
+    .command('scan [path]', { isDefault: true })
   .description('Scan a directory for vibe coding drift')
   .option('-o, --output <file>', 'Write report to a Markdown file')
   .option('--json', 'Output raw JSON report')
   .option('--ai', 'Output AI-optimized JSON for LLM consumption')
   .option('--fix', 'Show fix suggestions for each issue')
   .option('--min-score <n>', 'Exit with code 1 if overall score exceeds this threshold', '0')
-  .action(async (targetPath: string | undefined, options: { output?: string; json?: boolean; ai?: boolean; fix?: boolean; minScore: string }) => {
+  .action(async (targetPath: string | undefined, options: { output?: string; json?: boolean; ai?: boolean; fix?: boolean; minScore: string } & ResourceOptionFlags) => {
     const resolvedPath = resolve(targetPath ?? '.')
 
     process.stderr.write(`\nScanning ${resolvedPath}...\n`)
     const config = await loadConfig(resolvedPath)
-    const files = analyzeProject(resolvedPath, config)
+    const files = analyzeProject(resolvedPath, config, resolveAnalysisOptions(options))
     process.stderr.write(`  Found ${files.length} TypeScript file(s)\n\n`)
     const report = buildReport(resolvedPath, files)
 
@@ -69,15 +173,18 @@ program
     if (minScore > 0 && report.totalScore > minScore) {
       process.exit(1)
     }
-  })
+  }),
+)
 
-program
-  .command('diff [ref]')
+addResourceOptions(
+  program
+    .command('diff [ref]')
   .description('Compare current state against a git ref (default: HEAD~1)')
   .option('--json', 'Output raw JSON diff')
-  .action(async (ref: string | undefined, options: { json?: boolean }) => {
+  .action(async (ref: string | undefined, options: { json?: boolean } & ResourceOptionFlags) => {
     const baseRef = ref ?? 'HEAD~1'
     const projectPath = resolve('.')
+    const analysisOptions = resolveAnalysisOptions(options)
 
     let tempDir: string | undefined
 
@@ -86,12 +193,12 @@ program
 
       // Scan current state
       const config = await loadConfig(projectPath)
-      const currentFiles = analyzeProject(projectPath, config)
+      const currentFiles = analyzeProject(projectPath, config, analysisOptions)
       const currentReport = buildReport(projectPath, currentFiles)
 
       // Extract base state from git
       tempDir = extractFilesAtRef(projectPath, baseRef)
-      const baseFiles = analyzeProject(tempDir, config)
+      const baseFiles = analyzeProject(tempDir, config, analysisOptions)
 
       // Remap base file paths to match current project paths
       // (temp dir paths → project paths for accurate comparison)
@@ -100,7 +207,7 @@ program
         ...baseReport,
         files: baseReport.files.map(f => ({
           ...f,
-          path: f.path.replace(tempDir!, projectPath),
+          path: resolve(projectPath, relative(tempDir!, f.path)),
         })),
       }
 
@@ -118,7 +225,8 @@ program
     } finally {
       if (tempDir) cleanupTempDir(tempDir)
     }
-  })
+  }),
+)
 
 program
   .command('review')
@@ -148,6 +256,239 @@ program
     }
   })
 
+addResourceOptions(
+  program
+    .command('trust [path]')
+  .description('Compute merge trust baseline from drift signals')
+  .option('--base <ref>', 'Git base ref for diff-aware trust scoring')
+  .option('--json', 'Output structured trust JSON')
+  .option('--markdown', 'Output trust report as markdown (PR comment ready)')
+  .option('-o, --output <file>', 'Write trust output to file')
+  .option('--json-output <file>', 'Write structured trust JSON to file without changing stdout format')
+  .option('--min-trust <n>', 'Exit with code 1 if trust score is below threshold')
+  .option('--max-risk <level>', 'Exit with code 1 if merge risk exceeds level (LOW|MEDIUM|HIGH|CRITICAL)')
+  .option('--branch <name>', 'Branch name for trust policy matching (default: auto-detect from CI env)')
+  .option('--policy-pack <name>', 'Trust policy pack from drift.config trustGate.policyPacks')
+  .option('--explain-policy', 'Print effective trust gate policy resolution to stderr')
+  .option('--advanced-trust', 'Enable advanced trust mode with historical comparison and team guidance')
+  .option('--previous-trust <file>', 'Previous trust JSON file to compare against (used in advanced mode)')
+  .option('--history-file <file>', 'Snapshot history JSON file (default: <path>/drift-history.json) for advanced mode')
+  .action(async (
+    targetPath: string | undefined,
+    options: {
+      base?: string
+      json?: boolean
+      markdown?: boolean
+      output?: string
+      jsonOutput?: string
+      minTrust?: string
+      maxRisk?: string
+      branch?: string
+      policyPack?: string
+      explainPolicy?: boolean
+      advancedTrust?: boolean
+      previousTrust?: string
+      historyFile?: string
+    } & ResourceOptionFlags,
+  ) => {
+    let tempDir: string | undefined
+
+    try {
+      const resolvedPath = resolve(targetPath ?? '.')
+      const analysisOptions = resolveAnalysisOptions(options)
+
+      process.stderr.write(`\nScanning ${resolvedPath} for trust signals...\n`)
+      const config = await loadConfig(resolvedPath)
+      const files = analyzeProject(resolvedPath, config, analysisOptions)
+      process.stderr.write(`  Found ${files.length} TypeScript file(s)\n\n`)
+
+      const report = buildReport(resolvedPath, files)
+      const branchName = resolveBranchFromOption(options.branch)
+      const policyExplanation = explainTrustGatePolicy(config, {
+        branchName,
+        policyPack: options.policyPack,
+        overrides: parseTrustGateOverrides(options),
+      })
+      const policy = policyExplanation.effectivePolicy
+
+      if (options.explainPolicy) {
+        printTrustGatePolicyDebug(policyExplanation)
+      } else if (policyExplanation.invalidPolicyPack) {
+        process.stderr.write(`Warning: policy pack '${policyExplanation.invalidPolicyPack}' was not found. Falling back to base/preset policy.\n`)
+      }
+
+      let diff: DriftDiff | undefined
+      if (options.base) {
+        process.stderr.write(`Computing diff signals against ${options.base}...\n`)
+        tempDir = extractFilesAtRef(resolvedPath, options.base)
+        const baseFiles = analyzeProject(tempDir, config, analysisOptions)
+        const baseReport = buildReport(tempDir, baseFiles)
+        const remappedBase = {
+          ...baseReport,
+          files: baseReport.files.map((file) => ({
+            ...file,
+            path: resolve(resolvedPath, relative(tempDir!, file.path)),
+          })),
+        }
+        diff = computeDiff(remappedBase, report, options.base)
+        process.stderr.write(`  Diff: ${diff.totalDelta >= 0 ? '+' : ''}${diff.totalDelta} score, +${diff.newIssuesCount} new / -${diff.resolvedIssuesCount} resolved\n\n`)
+      }
+
+      let previousTrustReport: Partial<DriftTrustReport> | undefined
+      let snapshots: SnapshotHistory['snapshots'] | undefined
+      if (options.advancedTrust) {
+        if (options.previousTrust) {
+          const previousTrustPath = resolve(options.previousTrust)
+          const rawPreviousTrust = readFileSync(previousTrustPath, 'utf8')
+          previousTrustReport = JSON.parse(rawPreviousTrust) as Partial<DriftTrustReport>
+          process.stderr.write(`Advanced trust: loaded previous trust JSON from ${previousTrustPath}\n`)
+        }
+
+        if (options.historyFile) {
+          const historyPath = resolve(options.historyFile)
+          const rawHistory = readFileSync(historyPath, 'utf8')
+          const history = JSON.parse(rawHistory) as SnapshotHistory
+          snapshots = history.snapshots
+          process.stderr.write(`Advanced trust: loaded snapshot history from ${historyPath}\n`)
+        } else {
+          snapshots = loadHistory(resolvedPath).snapshots
+        }
+      }
+
+      const trust = buildTrustReport(report, {
+        diff,
+        advanced: {
+          enabled: options.advancedTrust,
+          previousTrust: previousTrustReport,
+          snapshots,
+        },
+      })
+
+      const rendered = `${renderTrustOutput(trust, options)}\n`
+
+      process.stdout.write(rendered)
+
+      if (options.output) {
+        const outPath = resolve(options.output)
+        writeFileSync(outPath, rendered, 'utf8')
+        process.stderr.write(`Trust output saved to ${outPath}\n`)
+      }
+
+      if (options.jsonOutput) {
+        const jsonOutPath = resolve(options.jsonOutput)
+        writeFileSync(jsonOutPath, `${formatTrustJson(trust)}\n`, 'utf8')
+        process.stderr.write(`Trust JSON saved to ${jsonOutPath}\n`)
+      }
+
+      if (policy.enabled === false) {
+        process.stderr.write(`Trust gate skipped by policy${branchName ? ` (branch: ${branchName})` : ''}\n`)
+        return
+      }
+
+      if (shouldFailTrustGate(trust, policy)) {
+        process.exit(1)
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      process.stderr.write(`\n  Error: ${message}\n\n`)
+      process.exit(1)
+    } finally {
+      if (tempDir) cleanupTempDir(tempDir)
+    }
+  }),
+)
+
+program
+  .command('trust-gate <trustJsonFile>')
+  .description('Evaluate trust gate thresholds from an existing trust JSON file')
+  .option('--min-trust <n>', 'Fail if trust score is below threshold')
+  .option('--max-risk <level>', 'Fail if merge risk exceeds level (LOW|MEDIUM|HIGH|CRITICAL)')
+  .option('--branch <name>', 'Branch name for trust policy matching (default: auto-detect from CI env)')
+  .option('--policy-pack <name>', 'Trust policy pack from drift.config trustGate.policyPacks')
+  .option('--explain-policy', 'Print effective trust gate policy resolution to stderr')
+  .action(async (trustJsonFile: string, options: { minTrust?: string; maxRisk?: string; branch?: string; policyPack?: string; explainPolicy?: boolean }) => {
+    try {
+      const filePath = resolve(trustJsonFile)
+      const raw = readFileSync(filePath, 'utf8')
+      const parsed = JSON.parse(raw) as Partial<DriftTrustReport>
+      const config = await loadConfig(resolve('.'))
+      const branchName = resolveBranchFromOption(options.branch)
+      const policyExplanation = explainTrustGatePolicy(config, {
+        branchName,
+        policyPack: options.policyPack,
+        overrides: parseTrustGateOverrides(options),
+      })
+      const policy = policyExplanation.effectivePolicy
+
+      if (options.explainPolicy) {
+        printTrustGatePolicyDebug(policyExplanation)
+      } else if (policyExplanation.invalidPolicyPack) {
+        process.stderr.write(`Warning: policy pack '${policyExplanation.invalidPolicyPack}' was not found. Falling back to base/preset policy.\n`)
+      }
+
+      if (typeof parsed.trust_score !== 'number') {
+        process.stderr.write('\n  Error: trust JSON is missing numeric trust_score\n\n')
+        process.exit(1)
+      }
+
+      if (typeof parsed.merge_risk !== 'string') {
+        process.stderr.write('\n  Error: trust JSON is missing merge_risk\n\n')
+        process.exit(1)
+      }
+
+      const actualRisk = normalizeMergeRiskLevel(parsed.merge_risk)
+      if (!actualRisk) {
+        process.stderr.write(`\n  Error: trust JSON merge_risk must be one of ${MERGE_RISK_ORDER.join(', ')}\n\n`)
+        process.exit(1)
+      }
+
+      const trust: DriftTrustReport = {
+        scannedAt: parsed.scannedAt ?? new Date().toISOString(),
+        targetPath: parsed.targetPath ?? '.',
+        trust_score: parsed.trust_score,
+        merge_risk: actualRisk,
+        top_reasons: parsed.top_reasons ?? [],
+        fix_priorities: parsed.fix_priorities ?? [],
+        diff_context: parsed.diff_context,
+      }
+
+      if (policy.enabled === false) {
+        process.stdout.write(`Trust gate skipped by policy${branchName ? ` (branch: ${branchName})` : ''}\n`)
+        return
+      }
+
+      if (shouldFailTrustGate(trust, policy)) {
+        process.exit(1)
+      }
+
+      process.stdout.write(`Trust gate passed: trust=${trust.trust_score} risk=${trust.merge_risk}\n`)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      process.stderr.write(`\n  Error: ${message}\n\n`)
+      process.exit(1)
+    }
+  })
+
+program
+  .command('kpi <path>')
+  .description('Aggregate trust KPIs from trust JSON artifacts')
+  .option('--no-summary', 'Disable console KPI summary in stderr')
+  .action((targetPath: string, options: { summary?: boolean }) => {
+    try {
+      const kpi = computeTrustKpis(targetPath)
+
+      if (options.summary !== false) {
+        process.stderr.write(`${formatTrustKpiConsole(kpi)}\n`)
+      }
+
+      process.stdout.write(`${formatTrustKpiJson(kpi)}\n`)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      process.stderr.write(`\n  Error: ${message}\n\n`)
+      process.exit(1)
+    }
+  })
+
 program
   .command('map [path]')
   .description('Generate architecture.svg with simple layer dependencies')
@@ -155,52 +496,58 @@ 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`)
   })
 
-program
-  .command('report [path]')
+addResourceOptions(
+  program
+    .command('report [path]')
   .description('Generate a self-contained HTML report')
   .option('-o, --output <file>', 'Output file path (default: drift-report.html)', 'drift-report.html')
-  .action(async (targetPath: string | undefined, options: { output: string }) => {
+  .action(async (targetPath: string | undefined, options: { output: string } & ResourceOptionFlags) => {
     const resolvedPath = resolve(targetPath ?? '.')
     process.stderr.write(`\nScanning ${resolvedPath}...\n`)
     const config = await loadConfig(resolvedPath)
-    const files = analyzeProject(resolvedPath, config)
+    const files = analyzeProject(resolvedPath, config, resolveAnalysisOptions(options))
     process.stderr.write(`  Found ${files.length} TypeScript file(s)\n\n`)
     const report = buildReport(resolvedPath, files)
     const html = generateHtmlReport(report)
     const outPath = resolve(options.output)
     writeFileSync(outPath, html, 'utf8')
     process.stderr.write(`  Report saved to ${outPath}\n\n`)
-  })
+  }),
+)
 
-program
-  .command('badge [path]')
+addResourceOptions(
+  program
+    .command('badge [path]')
   .description('Generate a badge.svg with the current drift score')
   .option('-o, --output <file>', 'Output file path (default: badge.svg)', 'badge.svg')
-  .action(async (targetPath: string | undefined, options: { output: string }) => {
+  .action(async (targetPath: string | undefined, options: { output: string } & ResourceOptionFlags) => {
     const resolvedPath = resolve(targetPath ?? '.')
     process.stderr.write(`\nScanning ${resolvedPath}...\n`)
     const config = await loadConfig(resolvedPath)
-    const files = analyzeProject(resolvedPath, config)
+    const files = analyzeProject(resolvedPath, config, resolveAnalysisOptions(options))
     const report = buildReport(resolvedPath, files)
     const svg = generateBadge(report.totalScore)
     const outPath = resolve(options.output)
     writeFileSync(outPath, svg, 'utf8')
     process.stderr.write(`  Badge saved to ${outPath}\n`)
     process.stderr.write(`  Score: ${report.totalScore}/100\n\n`)
-  })
+  }),
+)
 
-program
-  .command('ci [path]')
+addResourceOptions(
+  program
+    .command('ci [path]')
   .description('Emit GitHub Actions annotations and step summary')
   .option('--min-score <n>', 'Exit with code 1 if overall score exceeds this threshold', '0')
-  .action(async (targetPath: string | undefined, options: { minScore: string }) => {
+  .action(async (targetPath: string | undefined, options: { minScore: string } & ResourceOptionFlags) => {
     const resolvedPath = resolve(targetPath ?? '.')
     const config = await loadConfig(resolvedPath)
-    const files = analyzeProject(resolvedPath, config)
+    const files = analyzeProject(resolvedPath, config, resolveAnalysisOptions(options))
     const report = buildReport(resolvedPath, files)
     emitCIAnnotations(report)
     printCISummary(report)
@@ -208,7 +555,8 @@ program
     if (minScore > 0 && report.totalScore > minScore) {
       process.exit(1)
     }
-  })
+  }),
+)
 
 program
   .command('trend [period]')
@@ -259,12 +607,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,
@@ -310,15 +684,16 @@ program
     }
   })
 
-program
-  .command('snapshot [path]')
+addResourceOptions(
+  program
+    .command('snapshot [path]')
   .description('Record a score snapshot to drift-history.json')
   .option('-l, --label <label>', 'label for this snapshot (e.g. sprint name, version)')
   .option('--history', 'show all recorded snapshots')
   .option('--diff', 'compare current score vs last snapshot')
   .action(async (
     targetPath: string | undefined,
-    opts: { label?: string; history?: boolean; diff?: boolean },
+    opts: { label?: string; history?: boolean; diff?: boolean } & ResourceOptionFlags,
   ) => {
     const resolvedPath = resolve(targetPath ?? '.')
 
@@ -330,7 +705,7 @@ program
 
     process.stderr.write(`\nScanning ${resolvedPath}...\n`)
     const config = await loadConfig(resolvedPath)
-    const files = analyzeProject(resolvedPath, config)
+    const files = analyzeProject(resolvedPath, config, resolveAnalysisOptions(opts))
     process.stderr.write(`  Found ${files.length} TypeScript file(s)\n\n`)
     const report = buildReport(resolvedPath, files)
 
@@ -346,6 +721,223 @@ program
       `  Snapshot recorded${labelStr}: score ${entry.score} (${entry.grade}) — ${entry.totalIssues} issues across ${entry.files} files\n`,
     )
     process.stdout.write(`  Saved to drift-history.json\n\n`)
+  }),
+)
+
+const cloud = program
+  .command('cloud')
+  .description('Local SaaS foundations: ingest, summary, and dashboard')
+
+addResourceOptions(
+  cloud
+    .command('ingest [path]')
+  .description('Scan path, build report, and store cloud snapshot')
+  .option('--org <id>', 'Organization id (default: default-org)', 'default-org')
+  .requiredOption('--workspace <id>', 'Workspace id')
+  .requiredOption('--user <id>', 'User id')
+  .option('--role <role>', 'Role hint (owner|member|viewer)')
+  .option('--plan <plan>', 'Organization plan (free|sponsor|team|business)')
+  .option('--repo <name>', 'Repo name (default: basename of scanned path)')
+  .option('--actor <user>', 'Actor user id for permission checks (local-only authz context)')
+  .option('--store <file>', 'Store file path (default: .drift-cloud/store.json)')
+  .action(async (targetPath: string | undefined, options: { org: string; workspace: string; user: string; role?: string; plan?: string; repo?: string; actor?: string; store?: string } & ResourceOptionFlags) => {
+    try {
+      const resolvedPath = resolve(targetPath ?? '.')
+      process.stderr.write(`\nScanning ${resolvedPath} for cloud ingest...\n`)
+      const config = await loadConfig(resolvedPath)
+      const files = analyzeProject(resolvedPath, config, resolveAnalysisOptions(options))
+      const report = buildReport(resolvedPath, files)
+
+      const snapshot = ingestSnapshotFromReport(report, {
+        organizationId: options.org,
+        workspaceId: options.workspace,
+        userId: options.user,
+        role: options.role as 'owner' | 'member' | 'viewer' | undefined,
+        plan: options.plan as 'free' | 'sponsor' | 'team' | 'business' | undefined,
+        repoName: options.repo ?? basename(resolvedPath),
+        actorUserId: options.actor,
+        storeFile: options.store,
+        policy: config?.saas,
+      })
+
+      process.stdout.write(`Ingested snapshot ${snapshot.id}\n`)
+      process.stdout.write(`Organization: ${snapshot.organizationId}  Workspace: ${snapshot.workspaceId}  Repo: ${snapshot.repoName}\n`)
+      process.stdout.write(`Role: ${snapshot.role}  Plan: ${snapshot.plan}\n`)
+      process.stdout.write(`Score: ${snapshot.totalScore}/100  Issues: ${snapshot.totalIssues}\n\n`)
+    } catch (error) {
+      printSaasErrorAndExit(error)
+    }
+  }),
+)
+
+cloud
+  .command('summary')
+  .description('Show SaaS usage metrics and free threshold status')
+  .option('--json', 'Output raw JSON summary')
+  .option('--org <id>', 'Filter summary by organization id')
+  .option('--workspace <id>', 'Filter summary by workspace id')
+  .option('--actor <user>', 'Actor user id for permission checks (local-only authz context)')
+  .option('--store <file>', 'Store file path (default: .drift-cloud/store.json)')
+  .action((options: { json?: boolean; org?: string; workspace?: string; actor?: string; store?: string }) => {
+    try {
+      const summary = getSaasSummary({
+        storeFile: options.store,
+        organizationId: options.org,
+        workspaceId: options.workspace,
+        actorUserId: options.actor,
+      })
+
+      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')
+    } catch (error) {
+      printSaasErrorAndExit(error)
+    }
+  })
+
+cloud
+  .command('plan-set')
+  .description('Set organization plan (owner role required when actor is provided)')
+  .requiredOption('--org <id>', 'Organization id')
+  .requiredOption('--plan <plan>', 'New organization plan (free|sponsor|team|business)')
+  .requiredOption('--actor <user>', 'Actor user id used for owner-gated billing writes')
+  .option('--reason <text>', 'Optional reason for audit trail')
+  .option('--store <file>', 'Store file path (default: .drift-cloud/store.json)')
+  .option('--json', 'Output raw JSON plan change')
+  .action((options: { org: string; plan: string; actor: string; reason?: string; store?: string; json?: boolean }) => {
+    try {
+      const change = changeOrganizationPlan({
+        organizationId: options.org,
+        actorUserId: options.actor,
+        newPlan: options.plan as 'free' | 'sponsor' | 'team' | 'business',
+        reason: options.reason,
+        storeFile: options.store,
+      })
+
+      if (options.json) {
+        process.stdout.write(JSON.stringify(change, null, 2) + '\n')
+        return
+      }
+
+      process.stdout.write(`Plan updated for org '${change.organizationId}': ${change.fromPlan} -> ${change.toPlan}\n`)
+      process.stdout.write(`Changed by: ${change.changedByUserId} at ${change.changedAt}\n`)
+      if (change.reason) process.stdout.write(`Reason: ${change.reason}\n`)
+    } catch (error) {
+      printSaasErrorAndExit(error)
+    }
+  })
+
+cloud
+  .command('plan-changes')
+  .description('List organization plan change audit trail')
+  .requiredOption('--org <id>', 'Organization id')
+  .requiredOption('--actor <user>', 'Actor user id used for billing read permissions')
+  .option('--store <file>', 'Store file path (default: .drift-cloud/store.json)')
+  .option('--json', 'Output raw JSON plan changes')
+  .action((options: { org: string; actor: string; store?: string; json?: boolean }) => {
+    try {
+      const changes = listOrganizationPlanChanges({
+        organizationId: options.org,
+        actorUserId: options.actor,
+        storeFile: options.store,
+      })
+
+      if (options.json) {
+        process.stdout.write(JSON.stringify(changes, null, 2) + '\n')
+        return
+      }
+
+      if (changes.length === 0) {
+        process.stdout.write(`No plan changes found for org '${options.org}'.\n`)
+        return
+      }
+
+      process.stdout.write(`Plan changes for org '${options.org}':\n`)
+      for (const change of changes) {
+        const reasonSuffix = change.reason ? ` reason='${change.reason}'` : ''
+        process.stdout.write(`- ${change.changedAt}: ${change.fromPlan} -> ${change.toPlan} by ${change.changedByUserId}${reasonSuffix}\n`)
+      }
+    } catch (error) {
+      printSaasErrorAndExit(error)
+    }
+  })
+
+cloud
+  .command('usage')
+  .description('Show organization usage and effective limits')
+  .requiredOption('--org <id>', 'Organization id')
+  .requiredOption('--actor <user>', 'Actor user id used for billing read permissions')
+  .option('--month <yyyy-mm>', 'Month filter for runCountThisMonth (default: current UTC month)')
+  .option('--store <file>', 'Store file path (default: .drift-cloud/store.json)')
+  .option('--json', 'Output usage and limits as raw JSON')
+  .action((options: { org: string; actor: string; month?: string; store?: string; json?: boolean }) => {
+    try {
+      const usage = getOrganizationUsageSnapshot({
+        organizationId: options.org,
+        actorUserId: options.actor,
+        month: options.month,
+        storeFile: options.store,
+      })
+      const limits = getOrganizationEffectiveLimits({
+        organizationId: options.org,
+        storeFile: options.store,
+      })
+
+      if (options.json) {
+        process.stdout.write(JSON.stringify({ usage, limits }, null, 2) + '\n')
+        return
+      }
+
+      process.stdout.write(`Organization: ${usage.organizationId}\n`)
+      process.stdout.write(`Plan: ${usage.plan}\n`)
+      process.stdout.write(`Captured at: ${usage.capturedAt}\n`)
+      process.stdout.write(`Workspace count: ${usage.workspaceCount}\n`)
+      process.stdout.write(`Repo count: ${usage.repoCount}\n`)
+      process.stdout.write(`Runs total: ${usage.runCount}\n`)
+      process.stdout.write(`Runs this month: ${usage.runCountThisMonth}\n`)
+      process.stdout.write('Effective limits:\n')
+      process.stdout.write(`  - maxWorkspaces: ${limits.maxWorkspaces}\n`)
+      process.stdout.write(`  - maxReposPerWorkspace: ${limits.maxReposPerWorkspace}\n`)
+      process.stdout.write(`  - maxRunsPerWorkspacePerMonth: ${limits.maxRunsPerWorkspacePerMonth}\n`)
+      process.stdout.write(`  - retentionDays: ${limits.retentionDays}\n`)
+    } catch (error) {
+      printSaasErrorAndExit(error)
+    }
+  })
+
+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()