@eduardbar/drift 1.2.0 → 1.3.0

package/dist/cli.js

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // drift-ignore-file
 import { Command } from 'commander';
-import { writeFileSync } from 'node:fs';
-import { basename, 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';
@@ -21,13 +21,77 @@ import { applyFixes } 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';
+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';
 const program = new Command();
+function parseOptionalPositiveInt(rawValue, flagName) {
+    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) {
+    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) {
+    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) {
+    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;
+    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) {
+    const normalized = branch?.trim();
+    if (normalized)
+        return normalized;
+    return detectBranchName();
+}
+function printTrustGatePolicyDebug(explanation) {
+    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) {
+    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
+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')
@@ -39,7 +103,7 @@ program
     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);
     if (options.ai) {
@@ -63,24 +127,25 @@ program
     if (minScore > 0 && report.totalScore > minScore) {
         process.exit(1);
     }
-});
-program
+}));
+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, options) => {
     const baseRef = ref ?? 'HEAD~1';
     const projectPath = resolve('.');
+    const analysisOptions = resolveAnalysisOptions(options);
     let tempDir;
     try {
         process.stderr.write(`\nComputing diff: HEAD vs ${baseRef}...\n\n`);
         // 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)
         const baseReport = buildReport(tempDir, baseFiles);
@@ -88,7 +153,7 @@ program
             ...baseReport,
             files: baseReport.files.map(f => ({
                 ...f,
-                path: f.path.replace(tempDir, projectPath),
+                path: resolve(projectPath, relative(tempDir, f.path)),
             })),
         };
         const diff = computeDiff(remappedBase, currentReport, baseRef);
@@ -108,7 +173,7 @@ program
         if (tempDir)
             cleanupTempDir(tempDir);
     }
-});
+}));
 program
     .command('review')
     .description('Review drift against a base ref and output PR markdown')
@@ -136,6 +201,201 @@ program
         process.exit(1);
     }
 });
+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, options) => {
+    let tempDir;
+    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;
+        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;
+        let snapshots;
+        if (options.advancedTrust) {
+            if (options.previousTrust) {
+                const previousTrustPath = resolve(options.previousTrust);
+                const rawPreviousTrust = readFileSync(previousTrustPath, 'utf8');
+                previousTrustReport = JSON.parse(rawPreviousTrust);
+                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);
+                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, options) => {
+    try {
+        const filePath = resolve(trustJsonFile);
+        const raw = readFileSync(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        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 = {
+            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, options) => {
+    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')
@@ -147,7 +407,7 @@ program
     const out = generateArchitectureMap(resolvedPath, options.output, config);
     process.stderr.write(`  Architecture map saved to ${out}\n\n`);
 });
-program
+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')
@@ -155,15 +415,15 @@ program
     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
+}));
+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')
@@ -171,22 +431,22 @@ program
     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
+}));
+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, options) => {
     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);
@@ -194,7 +454,7 @@ program
     if (minScore > 0 && report.totalScore > minScore) {
         process.exit(1);
     }
-});
+}));
 program
     .command('trend [period]')
     .description('Analyze trend of technical debt over time')
@@ -303,7 +563,7 @@ program
         console.log(`\n${applied.length} issue(s) fixed. Re-run drift scan to verify.`);
     }
 });
-program
+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)')
@@ -318,7 +578,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);
     if (opts.diff) {
@@ -330,64 +590,195 @@ program
     const labelStr = entry.label ? ` [${entry.label}]` : '';
     process.stdout.write(`  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');
-cloud
+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, options) => {
-    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`);
-});
+    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,
+            plan: options.plan,
+            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) => {
-    const summary = getSaasSummary({ storeFile: options.store });
-    if (options.json) {
-        process.stdout.write(JSON.stringify(summary, null, 2) + '\n');
-        return;
+    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');
     }
-    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;
+    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) => {
+    try {
+        const change = changeOrganizationPlan({
+            organizationId: options.org,
+            actorUserId: options.actor,
+            newPlan: options.plan,
+            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) => {
+    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) => {
+    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`);
     }
-    for (const [month, runs] of monthly) {
-        process.stdout.write(`  - ${month}: ${runs}\n`);
+    catch (error) {
+        printSaasErrorAndExit(error);
     }
-    process.stdout.write('\n');
 });
 cloud
     .command('dashboard')