@eduardbar/drift 1.2.0 → 1.4.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';
@@ -14,6 +14,7 @@ import { printConsole, printDiff } from './printer.js';
 import { loadConfig } from './config.js';
 import { extractFilesAtRef, cleanupTempDir } from './git.js';
 import { computeDiff } from './diff.js';
+import { runGuard } from './guard.js';
 import { generateHtmlReport } from './report.js';
 import { generateBadge } from './badge.js';
 import { emitCIAnnotations, printCISummary } from './ci.js';
@@ -21,16 +22,157 @@ 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';
+import { runBenchmarkCli } from './benchmark.js';
+import { runInit, INIT_PRESETS } from './init.js';
+import { runDoctor } from './doctor.js';
+import { resolveOutputFormat } from './format.js';
+import { toSarif, diffToSarif } from './sarif.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 parseOptionalNumber(rawValue, flagName) {
+    if (rawValue == null)
+        return undefined;
+    const value = Number(rawValue);
+    if (!Number.isFinite(value)) {
+        throw new Error(`${flagName} must be a valid number`);
+    }
+    return value;
+}
+function parseBySeverity(rawValue) {
+    if (rawValue == null)
+        return undefined;
+    const spec = rawValue.trim();
+    if (!spec) {
+        throw new Error('--by-severity must not be empty. Expected format: error=0,warning=2,info=5');
+    }
+    const thresholds = {};
+    const seen = new Set();
+    for (const segment of spec.split(',')) {
+        const pair = segment.trim();
+        if (!pair)
+            continue;
+        const equalIndex = pair.indexOf('=');
+        if (equalIndex <= 0 || equalIndex === pair.length - 1) {
+            throw new Error(`Invalid --by-severity entry '${pair}'. Expected key=value (e.g. warning=2).`);
+        }
+        const key = pair.slice(0, equalIndex).trim().toLowerCase();
+        const rawThreshold = pair.slice(equalIndex + 1).trim();
+        if (key !== 'error' && key !== 'warning' && key !== 'info') {
+            throw new Error(`Invalid --by-severity key '${key}'. Allowed keys: error, warning, info.`);
+        }
+        if (seen.has(key)) {
+            throw new Error(`Duplicate --by-severity key '${key}'.`);
+        }
+        const threshold = Number(rawThreshold);
+        if (!Number.isFinite(threshold)) {
+            throw new Error(`Invalid --by-severity value for '${key}': '${rawThreshold}'. Must be a valid number.`);
+        }
+        const severityKey = key;
+        thresholds[severityKey] = threshold;
+        seen.add(severityKey);
+    }
+    if (seen.size === 0) {
+        throw new Error('--by-severity must include at least one threshold. Example: error=0,warning=2');
+    }
+    return thresholds;
+}
+function formatSigned(value) {
+    return value > 0 ? `+${value}` : `${value}`;
+}
+function printGuardSummary(result) {
+    const modeLabel = result.mode === 'diff' ? `diff (${result.baseRef ?? 'unknown base'})` : 'baseline';
+    const statusLabel = result.passed ? 'PASS' : 'FAIL';
+    process.stdout.write('\n');
+    process.stdout.write(`Guard mode: ${modeLabel}\n`);
+    process.stdout.write(`Result: ${statusLabel}\n`);
+    process.stdout.write(`Score delta: ${formatSigned(result.metrics.scoreDelta)}\n`);
+    process.stdout.write(`Total issues delta: ${formatSigned(result.metrics.totalIssuesDelta)}\n`);
+    process.stdout.write(`Severity delta: error=${formatSigned(result.metrics.severityDelta.error)}, warning=${formatSigned(result.metrics.severityDelta.warning)}, info=${formatSigned(result.metrics.severityDelta.info)}\n`);
+    if (result.mode === 'baseline' && result.baselinePath) {
+        process.stdout.write(`Baseline file: ${result.baselinePath}\n`);
+    }
+    if (result.checks.length === 0) {
+        process.stdout.write('Checks: none configured\n');
+        return;
+    }
+    process.stdout.write('Checks:\n');
+    for (const check of result.checks) {
+        process.stdout.write(`  - [${check.passed ? 'PASS' : 'FAIL'}] ${check.id}: ${check.message} (actual=${check.actual}, limit=${check.limit})\n`);
+    }
+}
+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')
+    .option('--format <type>', 'Output format: console|json|markdown|ai|sarif')
     .option('--json', 'Output raw JSON report')
     .option('--ai', 'Output AI-optimized JSON for LLM consumption')
     .option('--fix', 'Show fix suggestions for each issue')
@@ -39,18 +181,36 @@ 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) {
+    const format = resolveOutputFormat({
+        command: 'scan',
+        format: options.format,
+        supported: ['console', 'json', 'markdown', 'ai', 'sarif'],
+        legacyAliases: [
+            { flag: 'json', used: options.json, mapsTo: 'json' },
+            { flag: 'ai', used: options.ai, mapsTo: 'ai' },
+        ],
+        onWarning: (message) => process.stderr.write(`${message}\n`),
+    });
+    if (format === 'sarif') {
+        process.stdout.write(`${JSON.stringify(toSarif(report), null, 2)}\n`);
+        return;
+    }
+    if (format === 'ai') {
         const aiOutput = formatAIOutput(report);
         process.stdout.write(JSON.stringify(aiOutput, null, 2));
         return;
     }
-    if (options.json) {
+    if (format === 'json') {
         process.stdout.write(JSON.stringify(report, null, 2));
         return;
     }
+    if (format === 'markdown') {
+        process.stdout.write(`${formatMarkdown(report)}\n`);
+        return;
+    }
     printConsole(report, { showFix: options.fix });
     if (options.output) {
         const md = formatMarkdown(report);
@@ -63,24 +223,54 @@ program
     if (minScore > 0 && report.totalScore > minScore) {
         process.exit(1);
     }
-});
+}));
 program
+    .command('init')
+    .description('Initialize drift configuration with presets and scaffolding')
+    .option('--preset <type>', `Scaffold config with preset: ${INIT_PRESETS.join(', ')}`)
+    .option('--ci', 'Generate GitHub Actions workflow for drift review')
+    .option('--baseline', 'Create drift-baseline.json with current project score')
+    .action(async (options) => {
+    const projectRoot = resolve('.');
+    try {
+        await runInit(projectRoot, {
+            preset: options.preset,
+            ci: options.ci,
+            baseline: options.baseline,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`\n  Error: ${message}\n\n`);
+        process.exit(1);
+    }
+});
+addResourceOptions(program
     .command('diff [ref]')
     .description('Compare current state against a git ref (default: HEAD~1)')
+    .option('--format <type>', 'Output format: console|json|markdown|ai|sarif')
     .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`);
+        const format = resolveOutputFormat({
+            command: 'diff',
+            format: options.format,
+            supported: ['console', 'json', 'sarif'],
+            legacyAliases: [{ flag: 'json', used: options.json, mapsTo: 'json' }],
+            onWarning: (message) => process.stderr.write(`${message}\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,11 +278,14 @@ 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);
-        if (options.json) {
+        if (format === 'sarif') {
+            process.stdout.write(`${JSON.stringify(diffToSarif(diff), null, 2)}\n`);
+        }
+        else if (format === 'json') {
             process.stdout.write(JSON.stringify(diff, null, 2) + '\n');
         }
         else {
@@ -108,22 +301,82 @@ program
         if (tempDir)
             cleanupTempDir(tempDir);
     }
+}));
+addResourceOptions(program
+    .command('guard [path]')
+    .description('Evaluate drift guard thresholds against diff or baseline')
+    .option('--base <ref>', 'Git base ref for diff guard mode')
+    .option('--baseline <file>', 'Baseline file path (default: drift-baseline.json)')
+    .option('--budget <n>', 'Allowed score delta budget')
+    .option('--by-severity <spec>', 'Severity thresholds: error=0,warning=2,info=5')
+    .option('--json', 'Output raw JSON guard result')
+    .action(async (targetPath, options) => {
+    try {
+        const resolvedPath = resolve(targetPath ?? '.');
+        const budget = parseOptionalNumber(options.budget, '--budget');
+        const bySeverity = parseBySeverity(options.bySeverity);
+        const result = await runGuard(resolvedPath, {
+            baseRef: options.base,
+            baselinePath: options.baseline,
+            budget,
+            bySeverity,
+            analysis: resolveAnalysisOptions(options),
+        });
+        if (options.json) {
+            process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+        }
+        else {
+            printGuardSummary(result);
+        }
+        if (!result.passed) {
+            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);
+    }
+}));
+program
+    .command('benchmark')
+    .description('Run benchmark harness for scan/review/trust commands')
+    .allowUnknownOption(true)
+    .action(async () => {
+    await runBenchmarkCli(process.argv.slice(3));
 });
 program
     .command('review')
     .description('Review drift against a base ref and output PR markdown')
     .option('--base <ref>', 'Git base ref to compare against', 'origin/main')
+    .option('--format <type>', 'Output format: console|json|markdown|ai|sarif')
     .option('--json', 'Output structured review JSON')
     .option('--comment', 'Output markdown comment body')
     .option('--fail-on <n>', 'Exit with code 1 if score delta is >= n')
     .action(async (options) => {
     try {
         const review = await generateReview(resolve('.'), options.base);
-        if (options.json) {
+        const format = resolveOutputFormat({
+            command: 'review',
+            format: options.format,
+            supported: ['console', 'json', 'markdown', 'sarif'],
+            legacyAliases: [
+                { flag: 'json', used: options.json, mapsTo: 'json' },
+                { flag: 'comment', used: options.comment, mapsTo: 'markdown' },
+            ],
+            onWarning: (message) => process.stderr.write(`${message}\n`),
+        });
+        if (format === 'sarif') {
+            process.stdout.write(`${JSON.stringify(diffToSarif(review.diff), null, 2)}\n`);
+        }
+        else if (format === 'json') {
             process.stdout.write(JSON.stringify(review, null, 2) + '\n');
         }
+        else if (format === 'markdown') {
+            process.stdout.write(`${review.markdown}\n`);
+        }
         else {
-            process.stdout.write((options.comment ? review.markdown : `${review.summary}\n\n${review.markdown}`) + '\n');
+            process.stdout.write(`${review.summary}\n\n${review.markdown}\n`);
         }
         const failOn = options.failOn ? Number(options.failOn) : undefined;
         if (typeof failOn === 'number' && !Number.isNaN(failOn) && review.totalDelta >= failOn) {
@@ -136,6 +389,231 @@ 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('--format <type>', 'Output format: console|json|markdown|ai|sarif')
+    .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 format = resolveOutputFormat({
+            command: 'trust',
+            format: options.format,
+            supported: ['console', 'json', 'markdown', 'sarif'],
+            legacyAliases: [
+                { flag: 'json', used: options.json, mapsTo: 'json' },
+                { flag: 'markdown', used: options.markdown, mapsTo: 'markdown' },
+            ],
+            onWarning: (message) => process.stderr.write(`${message}\n`),
+        });
+        const rendered = format === 'sarif'
+            ? `${JSON.stringify(toSarif(report), null, 2)}\n`
+            : `${renderTrustOutput(trust, {
+                json: format === 'json',
+                markdown: format === 'markdown',
+            })}\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('doctor')
+    .description('Run project environment diagnostics')
+    .option('--json', 'Output structured doctor JSON')
+    .action(async (opts) => {
+    try {
+        await runDoctor(process.cwd(), { json: opts.json });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`\n  Error: ${message}\n\n`);
+        process.exitCode = 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 +625,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 +633,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,30 +649,47 @@ 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('--format <type>', 'Output format: console|json|markdown|ai|sarif')
+    .option('--json', 'Output raw JSON report (legacy alias for --format json)')
     .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);
+    const format = resolveOutputFormat({
+        command: 'ci',
+        format: options.format,
+        supported: ['console', 'json', 'sarif'],
+        legacyAliases: [{ flag: 'json', used: options.json, mapsTo: 'json' }],
+        onWarning: (message) => process.stderr.write(`${message}\n`),
+    });
+    if (format === 'sarif') {
+        process.stdout.write(`${JSON.stringify(toSarif(report), null, 2)}\n`);
+    }
+    else if (format === 'json') {
+        process.stdout.write(JSON.stringify(report, null, 2) + '\n');
+    }
+    else {
+        emitCIAnnotations(report);
+        printCISummary(report);
+    }
     const minScore = Number(options.minScore);
     if (minScore > 0 && report.totalScore > minScore) {
         process.exit(1);
     }
-});
+}));
 program
     .command('trend [period]')
     .description('Analyze trend of technical debt over time')
@@ -303,7 +798,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 +813,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 +825,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);
     }
-    for (const [month, runs] of monthly) {
-        process.stdout.write(`  - ${month}: ${runs}\n`);
+});
+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`);
+    }
+    catch (error) {
+        printSaasErrorAndExit(error);
     }
-    process.stdout.write('\n');
 });
 cloud
     .command('dashboard')