@formigio/fazemos-cli 0.10.13 → 0.10.15

package/dist/index.js

@@ -22,6 +22,56 @@ function parseNumber(val) {
         throw new Error(`Invalid number: ${val}`);
     return n;
 }
+/**
+ * OPS-2 — Manual Interventions KPI cell formatter.
+ *
+ * Single source of CLI truth for the tri-state coloring rule encoded in
+ * rul_intervention_chip_thresholds_v1. Mirrors the web InterventionChip
+ * thresholds so the CLI MI column on `pl list`, the header line on
+ * `pl show`, and the `ops interventions` table all render the same way:
+ *
+ *   null  → `—` (no color)  — pre-migration row or unknown state
+ *   0     → green            — clean run
+ *   1-3   → amber            — some operator help
+ *   ≥4    → red              — carried
+ *   >999  → `999+`           — cap per rul_intervention_chip_count_cap_999plus
+ *
+ * Width: 5 chars (right-padded inside the chalk color call so colors don't
+ * count against the visible width). Callers can wrap with additional text
+ * (e.g. `MI:${cell}`) without breaking alignment.
+ */
+function formatManualInterventionCell(count) {
+    if (count === null || count === undefined) {
+        return chalk.gray('—'.padEnd(5));
+    }
+    const display = count > 999 ? '999+' : String(count);
+    const padded = display.padEnd(5);
+    if (count === 0)
+        return chalk.green(padded);
+    if (count <= 3)
+        return chalk.yellow(padded);
+    return chalk.red(padded);
+}
+/**
+ * OPS-2 — parse a duration string ('24h', '7d', '30d', '90d', etc.) into
+ * an ISO-8601 datetime `since` value for the GET /api/ops/manual-interventions
+ * `since` query param.
+ *
+ * Accepted units: `h` (hours), `d` (days), `w` (weeks). Unrecognised values
+ * throw and surface to the operator via the standard error path.
+ */
+function parseSinceDuration(val) {
+    const m = /^(\d+)([hdw])$/.exec(val.trim());
+    if (!m) {
+        throw new Error(`Invalid --since "${val}". Expected forms like 24h, 7d, 30d, 4w.`);
+    }
+    const n = Number(m[1]);
+    const unit = m[2];
+    const ms = unit === 'h' ? n * 3_600_000
+        : unit === 'd' ? n * 86_400_000
+            : n * 604_800_000;
+    return new Date(Date.now() - ms).toISOString();
+}
 function parseStreamSilenceAbortMs(val) {
     const n = Number(val);
     if (!Number.isInteger(n) || n < 30000 || n > 1800000) {
@@ -1340,27 +1390,34 @@ const connections = program.command('connections').alias('conn').description('Gi
  */
 connections
     .command('list')
-    .description('List GitHub Connections in the active organization')
+    .description('List VCS Connections (GitHub + BitBucket) in the active organization')
     .option('-s, --status <status>', 'Filter: active (default), all, pending, suspended, revoked, uninstalled', 'active')
     .action(async (opts) => {
     try {
         const orgId = requireActiveOrgOrExit();
-        const data = await api('GET', `/api/organizations/${orgId}/github/connections?status=${encodeURIComponent(opts.status)}`, undefined, { noProjectHeader: true });
-        const list = data.connections ?? [];
+        // F22 — call the provider-agnostic /vcs/connections endpoint.
+        // The legacy /github/connections alias still works during the
+        // dual-write phase, but `vcs/` returns BOTH providers' rows so
+        // the user sees their full Org Connection list.
+        const data = await api('GET', `/api/organizations/${orgId}/vcs/connections?status=${encodeURIComponent(opts.status)}`, undefined, { noProjectHeader: true });
+        const list = (data.connections ?? []).map(normalizeConnection);
         if (list.length === 0) {
             const orgName = findOrgById(orgId)?.name ?? orgId;
-            console.log(chalk.yellow(`No GitHub connections in ${orgName}.`));
+            console.log(chalk.yellow(`No code platform connections in ${orgName}.`));
             console.log(chalk.gray('Add one with: fazemos connections install'));
             return;
         }
         const orgName = findOrgById(orgId)?.name ?? orgId;
-        console.log(chalk.cyan(`GitHub connections in ${orgName}:`));
+        console.log(chalk.cyan(`Code platform connections in ${orgName}:`));
         console.log('');
         for (const c of list) {
             const statusColor = pickStatusColor(c.status);
             const projects = c.projectCount == null ? '—' : `${c.projectCount} ${c.projectCount === 1 ? 'project' : 'projects'}`;
-            const login = c.githubAccountLogin ?? chalk.gray('—');
-            console.log(`  ${chalk.cyan(c.name)}  ${chalk.gray(login)}  ${statusColor(c.status)}  ${chalk.gray(projects)}`);
+            const login = c.accountLogin ?? chalk.gray('—');
+            const providerLabel = formatProviderLabel(c.provider);
+            // F22 §8.3 item 1: provider column. Renders as a prefix tag so
+            // mixed-provider lists are scannable at a glance.
+            console.log(`  ${chalk.magenta(providerLabel)}  ${chalk.cyan(c.name)}  ${chalk.gray(login)}  ${statusColor(c.status)}  ${chalk.gray(projects)}`);
             console.log(chalk.gray(`    ID: ${c.id}`));
         }
     }
@@ -1375,40 +1432,56 @@ connections
  */
 connections
     .command('show')
-    .description('Show a GitHub Connection in detail')
+    .description('Show a VCS Connection in detail')
     .argument('<id>', 'Connection ID')
     .action(async (id) => {
     try {
         const orgId = requireActiveOrgOrExit();
-        const data = await api('GET', `/api/organizations/${orgId}/github/connections/${id}`, undefined, { noProjectHeader: true });
-        const c = data.connection;
-        console.log(chalk.cyan(c.name));
+        // F22 — provider-agnostic detail endpoint. The serialized shape
+        // includes `provider`, `account_login`, `supports_contents_api`
+        // and (for GitHub) `installation_id` / (BitBucket) `workspace_uuid`.
+        const data = await api('GET', `/api/organizations/${orgId}/vcs/connections/${id}`, undefined, { noProjectHeader: true });
+        const raw = data.connection ?? data;
+        const c = normalizeConnection(raw);
+        console.log(chalk.cyan(c.name ?? '(unnamed connection)'));
         console.log(`  ID:           ${c.id}`);
-        console.log(`  GitHub:       ${c.githubAccountLogin ?? chalk.gray('— (pending)')}`);
-        if (c.githubAccountType)
-            console.log(`  Account type: ${c.githubAccountType}`);
+        // F22 §8.3 item 2 — provider line above account info.
+        console.log(`  Provider:     ${formatProviderLabel(c.provider)}`);
+        console.log(`  Account:      ${c.accountLogin ?? chalk.gray('— (pending)')}`);
+        if (c.accountType)
+            console.log(`  Account type: ${c.accountType}`);
         const statusColor = pickStatusColor(c.status);
         console.log(`  Status:       ${statusColor(c.status)}`);
-        console.log(`  Installed:    ${c.installedAt ? new Date(c.installedAt).toLocaleString() : '(unknown)'}`);
+        if (c.installedAt) {
+            console.log(`  Installed:    ${new Date(c.installedAt).toLocaleString()}`);
+        }
         if (c.lastHealthCheckAt) {
             console.log(`  Last checked: ${new Date(c.lastHealthCheckAt).toLocaleString()}`);
         }
         if (c.lastUsedAt) {
             console.log(`  Last used:    ${new Date(c.lastUsedAt).toLocaleString()}`);
         }
-        if (c.repositorySelection === 'all') {
-            console.log(`  Repos:        All repositories${c.githubAccountLogin ? ` in ${c.githubAccountLogin}` : ''}`);
+        // F22 §6.4 — supports_contents_api is the canonical signal for
+        // "can this Connection back F18 docs surfaces?" Surface it so
+        // users understand why docs may be unavailable on BitBucket.
+        if (typeof c.supportsContentsApi === 'boolean') {
+            const docs = c.supportsContentsApi ? 'yes' : chalk.yellow('no');
+            console.log(`  Docs API:     ${docs}`);
         }
-        else if (Array.isArray(c.repositories)) {
-            console.log(`  Repos:        ${c.repositories.length}${c.repositoriesTruncated ? ' (showing 100)' : ''}`);
-            for (const r of c.repositories) {
-                console.log(chalk.gray(`    · ${r.fullName}`));
+        if (raw.repositorySelection === 'all') {
+            console.log(`  Repos:        All repositories${c.accountLogin ? ` in ${c.accountLogin}` : ''}`);
+        }
+        else if (Array.isArray(raw.repositories)) {
+            console.log(`  Repos:        ${raw.repositories.length}${raw.repositoriesTruncated ? ' (showing 100)' : ''}`);
+            for (const r of raw.repositories) {
+                console.log(chalk.gray(`    · ${r.fullName ?? r.full_name ?? r.name}`));
             }
         }
-        if (Array.isArray(c.boundProjects) && c.boundProjects.length > 0) {
+        const boundProjects = raw.boundProjects ?? raw.bound_projects ?? [];
+        if (Array.isArray(boundProjects) && boundProjects.length > 0) {
             console.log('');
             console.log(chalk.cyan('Projects using this connection:'));
-            for (const p of c.boundProjects) {
+            for (const p of boundProjects) {
                 console.log(`  · ${p.name} (${p.slug})`);
             }
         }
@@ -1429,12 +1502,55 @@ connections
  */
 connections
     .command('install')
-    .description('Add a GitHub Connection. Prints an install URL and waits for a confirmation code.')
-    .action(async () => {
+    .description('Add a VCS Connection (GitHub or BitBucket). Prints an install URL and (for GitHub) waits for a confirmation code.')
+    .option('--provider <provider>', 'VCS provider: github | bitbucket')
+    .action(async (opts) => {
     try {
         const orgId = requireActiveOrgOrExit();
         const orgName = findOrgById(orgId)?.name ?? orgId;
-        const mintData = await api('POST', `/api/organizations/${orgId}/github/connections/install-url`, { source: 'cli', returnTo: null }, { noProjectHeader: true });
+        // F22 §8.3 item 3 — provider selection matrix.
+        // 1) `--provider github|bitbucket` supplied: use directly.
+        // 2) No flag: prompt the user interactively (provider-picker).
+        //    The CLI cannot probe server-side provider configuration, so the
+        //    "exactly one provider configured" auto-select branch of the spec
+        //    is implemented as "user always confirms" — narrower than the
+        //    spec wording but strictly safer (no silent provider choice).
+        let provider = opts.provider?.toLowerCase();
+        if (!provider) {
+            provider = await promptProviderChoice();
+        }
+        if (provider !== 'github' && provider !== 'bitbucket') {
+            console.error(chalk.red(`Invalid --provider: ${provider}. Use 'github' or 'bitbucket'.`));
+            process.exit(1);
+        }
+        // F22 prefers the new provider-agnostic /vcs/connections route, which
+        // expects `provider` in the body. The github-only endpoint is kept
+        // alive but not used here so all new connections flow through one path.
+        const mintData = await api('POST', `/api/organizations/${orgId}/vcs/connections/install-url`, { provider, source: 'cli', returnTo: null }, { noProjectHeader: true });
+        // F22 §8.3 item 8 — BitBucket install is browser-only in v1 (no CLI
+        // confirmation-code exchange counterpart). Print the literal copy
+        // block specified in the spec verbatim, then exit successfully.
+        // The user completes consent in the browser and the /api/bitbucket/
+        // oauth/callback handler finishes the Connection server-side.
+        //
+        // Dex nit N4 — output literal MUST match the spec block exactly so
+        // the acceptance test can assert it.
+        if (provider === 'bitbucket') {
+            console.log('');
+            console.log('BitBucket Connection install — browser required');
+            console.log('');
+            console.log('Open this URL in your browser to authorize Fazemos:');
+            console.log('');
+            console.log(`    ${mintData.url}`);
+            console.log('');
+            console.log('After you authorize, BitBucket will redirect to Fazemos and complete the Connection.');
+            console.log('You can then list your connections with:');
+            console.log('');
+            console.log('    fazemos connections list');
+            console.log('');
+            console.log('This URL expires in 10 minutes.');
+            return;
+        }
         console.log('');
         console.log(`To add a GitHub connection to ${chalk.cyan(orgName)}:`);
         console.log('');
@@ -1523,18 +1639,20 @@ connections
 connections
     .command('revoke')
     .alias('disconnect')
-    .description('Disconnect a GitHub Connection (Fazemos-side; does not uninstall the App from GitHub).')
+    .description('Disconnect a VCS Connection (Fazemos-side; does not uninstall the App from GitHub / revoke the OAuth grant on BitBucket).')
     .argument('<id>', 'Connection ID')
     .option('-f, --force', 'Skip the confirmation prompt', false)
     .action(async (id, opts) => {
     try {
         const orgId = requireActiveOrgOrExit();
         // Fetch the Connection so we can show what we're about to revoke
-        // and how many projects it affects (Sage §8.3 confirmation copy).
-        let connection;
+        // and how many projects it affects (UX §8.3 confirmation copy).
+        // F22 — use the provider-agnostic /vcs/ endpoint so both provider
+        // rows are reachable.
+        let raw;
         try {
-            const detail = await api('GET', `/api/organizations/${orgId}/github/connections/${id}`, undefined, { noProjectHeader: true });
-            connection = detail.connection;
+            const detail = await api('GET', `/api/organizations/${orgId}/vcs/connections/${id}`, undefined, { noProjectHeader: true });
+            raw = detail.connection ?? detail;
         }
         catch (err) {
             if (err instanceof ApiError && err.code === 'CONNECTION_NOT_FOUND') {
@@ -1543,15 +1661,17 @@ connections
             }
             throw err;
         }
-        const boundProjects = connection.boundProjects ?? [];
+        const connection = normalizeConnection(raw);
+        const boundProjects = raw.boundProjects ?? raw.bound_projects ?? [];
+        const providerLabelStr = formatProviderLabel(connection.provider);
         if (!opts.force) {
             console.log('');
-            console.log(`Disconnect ${chalk.cyan(connection.name)}?`);
+            console.log(`Disconnect ${chalk.magenta(providerLabelStr)} ${chalk.cyan(connection.name ?? id)}?`);
             console.log('');
             if (boundProjects.length > 0) {
                 const projectList = boundProjects.map(p => p.name).join(', ');
                 console.log(`  This connection is used by ${boundProjects.length} ${boundProjects.length === 1 ? 'project' : 'projects'}: ${projectList}.`);
-                console.log('  Pipelines in those projects will fail on GitHub steps until');
+                console.log(`  Pipelines in those projects will fail on ${providerLabelStr} steps until`);
                 console.log('  they are bound to a different connection.');
                 console.log('');
             }
@@ -1559,7 +1679,13 @@ connections
                 console.log('  No projects are using this connection.');
                 console.log('');
             }
-            console.log(chalk.gray('  This does not uninstall the Fazemos App from GitHub.'));
+            // Provider-aware caveat: GitHub App vs BitBucket OAuth grant.
+            if (connection.provider === 'bitbucket') {
+                console.log(chalk.gray('  This does not revoke the OAuth grant on BitBucket.'));
+            }
+            else {
+                console.log(chalk.gray('  This does not uninstall the Fazemos App from GitHub.'));
+            }
             console.log('');
             const answer = await promptLine('Disconnect? [y/N]: ');
             if (!answer || !/^y/i.test(answer.trim())) {
@@ -1567,11 +1693,14 @@ connections
                 return;
             }
         }
-        const data = await api('DELETE', `/api/organizations/${orgId}/github/connections/${id}`, undefined, { noProjectHeader: true });
-        console.log(chalk.green(`Disconnected: ${connection.name}`));
-        const affected = data.affectedProjects ?? [];
-        if (affected.length > 0) {
-            console.log(chalk.gray(`  ${affected.length} project${affected.length === 1 ? '' : 's'} unbound.`));
+        const data = await api('DELETE', `/api/organizations/${orgId}/vcs/connections/${id}`, undefined, { noProjectHeader: true });
+        console.log(chalk.green(`Disconnected: ${providerLabelStr} ${connection.name ?? id}`));
+        // F22 response shape: { revoked, secrets_deleted, projects_unbound }.
+        // F16 legacy shape: { affectedProjects: [...] }. Handle both during
+        // the dual-write rollout.
+        const unbound = data.projects_unbound ?? (data.affectedProjects ?? []).length ?? 0;
+        if (unbound > 0) {
+            console.log(chalk.gray(`  ${unbound} project${unbound === 1 ? '' : 's'} unbound.`));
         }
         invalidateAuthMeCache();
     }
@@ -1586,19 +1715,23 @@ connections
  */
 connections
     .command('health-check')
-    .description('Verify a Connection is still healthy on GitHub')
+    .description('Verify a Connection is still healthy on its code platform (GitHub or BitBucket)')
     .argument('<id>', 'Connection ID')
     .action(async (id) => {
     try {
         const orgId = requireActiveOrgOrExit();
-        const data = await api('POST', `/api/organizations/${orgId}/github/connections/${id}/health-check`, {}, { noProjectHeader: true });
-        const c = data.connection;
+        // F22 — provider-aware health-check route on the /vcs/ alias.
+        // The handler dispatches to the right provider (GitHub installation
+        // probe / BitBucket OAuth-refresh + workspace probe).
+        const data = await api('POST', `/api/organizations/${orgId}/vcs/connections/${id}/health-check`, {}, { noProjectHeader: true });
+        const c = normalizeConnection(data.connection ?? data);
         const statusColor = pickStatusColor(c.status);
+        const label = `${formatProviderLabel(c.provider)} ${c.name ?? id}`;
         if (data.changed) {
-            console.log(chalk.yellow(`Status changed: ${c.name} → ${statusColor(c.status)}`));
+            console.log(chalk.yellow(`Status changed: ${label} → ${statusColor(c.status)}`));
         }
         else {
-            console.log(chalk.green(`✓ ${c.name} — ${statusColor(c.status)}`));
+            console.log(chalk.green(`✓ ${label} — ${statusColor(c.status)}`));
         }
     }
     catch (err) {
@@ -1610,6 +1743,53 @@ connections
         process.exit(1);
     }
 });
+export function normalizeConnection(raw) {
+    if (!raw || typeof raw !== 'object') {
+        return {
+            id: '',
+            provider: null,
+            name: null,
+            accountLogin: null,
+            accountType: null,
+            status: 'unknown',
+            installedAt: null,
+            lastHealthCheckAt: null,
+            lastUsedAt: null,
+            supportsContentsApi: null,
+            projectCount: null,
+        };
+    }
+    // Provider — F22 new field. Older /github/ rows always meant github;
+    // default there for back-compat.
+    const provider = raw.provider ?? (raw.githubAccountLogin !== undefined ? 'github' : null);
+    return {
+        id: String(raw.id ?? ''),
+        provider,
+        name: raw.name ?? null,
+        accountLogin: raw.accountLogin ?? raw.account_login ?? raw.githubAccountLogin ?? null,
+        accountType: raw.accountType ?? raw.account_type ?? raw.githubAccountType ?? null,
+        status: raw.status ?? 'unknown',
+        installedAt: raw.installedAt ?? raw.installed_at ?? raw.created_at ?? null,
+        lastHealthCheckAt: raw.lastHealthCheckAt ?? raw.last_health_check_at ?? null,
+        lastUsedAt: raw.lastUsedAt ?? raw.last_used_at ?? null,
+        supportsContentsApi: typeof raw.supportsContentsApi === 'boolean'
+            ? raw.supportsContentsApi
+            : typeof raw.supports_contents_api === 'boolean'
+                ? raw.supports_contents_api
+                : null,
+        projectCount: raw.projectCount ?? raw.project_count ?? null,
+    };
+}
+/**
+ * F22 — Human-friendly provider label used in CLI columns and lines.
+ */
+export function formatProviderLabel(provider) {
+    if (provider === 'github')
+        return 'GitHub';
+    if (provider === 'bitbucket')
+        return 'BitBucket';
+    return '—';
+}
 /**
  * Helper — color a status string per the Sage §2.2 taxonomy.
  */
@@ -1629,6 +1809,30 @@ function pickStatusColor(status) {
             return chalk.white;
     }
 }
+/**
+ * F22 §8.3 item 3 — interactive provider picker. Used by
+ * `fazemos connections install` when no `--provider` flag is supplied
+ * so the user explicitly chooses GitHub or BitBucket before the URL
+ * mint hits the API. Mirrors the web `ProviderPickerModal` choice
+ * without the modal chrome.
+ *
+ * Returns 'github' or 'bitbucket'. Repeats on invalid input.
+ */
+export async function promptProviderChoice() {
+    console.log('');
+    console.log('Which code platform do you want to connect?');
+    console.log('  1. GitHub');
+    console.log('  2. BitBucket');
+    console.log('');
+    while (true) {
+        const ans = (await promptLine('  Choose [1=GitHub / 2=BitBucket]: ')).trim().toLowerCase();
+        if (ans === '1' || ans === 'github' || ans === 'gh')
+            return 'github';
+        if (ans === '2' || ans === 'bitbucket' || ans === 'bb')
+            return 'bitbucket';
+        console.log(chalk.yellow('  Please answer 1 (GitHub) or 2 (BitBucket).'));
+    }
+}
 /**
  * Read a single line of input from stdin. No fancy framing — `readline`
  * is sufficient for the install confirmation-code prompt and the
@@ -4000,7 +4204,18 @@ pipelines
         }
         for (const inst of data.instances) {
             const stepInfo = inst.total_steps ? ` — step ${inst.current_step ?? '?'}/${inst.total_steps}` : '';
-            console.log(`  ${chalk.cyan(inst.name)} (${inst.status})${stepInfo}`);
+            // OPS-2 — Manual Interventions KPI. The MI column renders inline next
+            // to the instance status with the prescribed tri-state coloring:
+            //   null → `—` (no color; pre-migration row or unknown)
+            //   0    → green
+            //   1-3  → amber
+            //   ≥4   → red
+            // Capped per rul_intervention_chip_count_cap_999plus: values > 999
+            // collapse to `999+` while the underlying count remains intact in
+            // the API response and JSON output for scripts.
+            const miCell = formatManualInterventionCell(inst.manual_intervention_count);
+            const envCell = inst.env_tag ? chalk.gray(` [${inst.env_tag}]`) : '';
+            console.log(`  ${chalk.cyan(inst.name)} (${inst.status}) MI:${miCell}${envCell}${stepInfo}`);
             console.log(`    ID: ${inst.id}`);
             if (opts.expand && inst.steps?.length) {
                 for (const s of inst.steps) {
@@ -4029,6 +4244,14 @@ pipelines
         console.log(`  ID:       ${inst.id}`);
         console.log(`  Status:   ${inst.status}`);
         console.log(`  Template: ${inst.template_name || inst.template_id}`);
+        // OPS-2 — Manual Interventions KPI header line. Same coloring rule as
+        // `pl list` (null=—, 0=green, 1-3=amber, 4+=red). env_tag is surfaced
+        // alongside so operators can read prod-vs-dev at a glance (the cycle
+        // exit criterion is prod-only).
+        console.log(`  Manual Interventions: ${formatManualInterventionCell(inst.manual_intervention_count)}`);
+        if (inst.env_tag) {
+            console.log(`  Env Tag:  ${inst.env_tag}`);
+        }
         if (inst.phases?.length) {
             for (const phase of inst.phases) {
                 console.log(chalk.cyan(`\n  Phase: ${phase.name}`));
@@ -6995,6 +7218,156 @@ ops
         process.exit(1);
     }
 });
+// ── OPS-2 — Manual Interventions KPI ─────────────────────────────────
+// Spec: specs/tech/platform/OPS-2-manual-intervention-kpi-tech-spec.md
+//
+// `fazemos ops interventions` has three operating modes:
+//
+//   1. bare        — windowed summary table + current zero-intervention
+//                    streak. Calls GET /api/ops/manual-interventions/summary.
+//                    Prod-only by default (cycle exit criterion is prod);
+//                    --include-dev inverts the env_tag filter for parity
+//                    with the API.
+//   2. --pipeline  — per-pipeline drill. Calls GET /api/pipeline-instances/:id
+//                    (response now carries manual_intervention_count +
+//                    env_tag) and surfaces the count + the env_tag fence so
+//                    operators can read the chip the same way the web does.
+//                    Forensic per-event detail lives behind `fazemos agents
+//                    events --type manual_intervention` (existing surface);
+//                    we print the hint so the operator doesn't have to
+//                    rediscover it.
+//   3. --since     — windowed list. Calls GET /api/ops/manual-interventions
+//                    with the resolved `since` timestamp. Defaults to
+//                    include-dev (false) → prod-only-NO; the GET list
+//                    endpoint defaults exclude_dev=false (the broader view
+//                    is more useful when scanning recent activity). The
+//                    --exclude-dev flag tightens to prod-only.
+//
+// Admin/owner gating is enforced server-side (403 FORBIDDEN); the CLI
+// surfaces the API's error verbatim so non-admin operators see the
+// authoritative reason rather than a stale local guess.
+ops
+    .command('interventions')
+    .description('Manual-intervention KPI. Bare mode shows the windowed summary table + '
+    + 'current zero-intervention streak (prod-only by default). '
+    + '--pipeline <id> drills into one pipeline. '
+    + '--since <duration> lists pipelines started in the window.')
+    .option('-w, --window <window>', 'Summary window: 24h, 7d, 30d', '7d')
+    .option('-p, --pipeline <id>', 'Drill into one pipeline_instance by ID')
+    .option('--since <duration>', 'List mode: filter by started_at >= now - duration (e.g. 24h, 7d, 30d)')
+    .option('-l, --limit <n>', 'List mode: max rows (default 50, max 200)', '50')
+    .option('--include-dev', 'Include dev-tagged pipelines in the summary / list (default: exclude)', false)
+    .option('--exclude-dev', 'Force exclude dev-tagged pipelines (default for summary; opt-in for list)', false)
+    .option('--json', 'Print the raw API response as JSON (machine-readable)')
+    .action(async (opts) => {
+    try {
+        // ── Mode 1: --pipeline <id> drill ────────────────────────────
+        if (opts.pipeline) {
+            const data = await api('GET', `/api/pipeline-instances/${opts.pipeline}`);
+            if (opts.json) {
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            const inst = data.instance;
+            if (!inst) {
+                console.error(chalk.red(`Pipeline ${opts.pipeline} not found`));
+                process.exit(1);
+            }
+            console.log(chalk.cyan(`Manual interventions on ${inst.name}`));
+            console.log(`  ID:        ${inst.id}`);
+            console.log(`  Status:    ${inst.status}`);
+            console.log(`  Env Tag:   ${inst.env_tag ?? chalk.gray('—')}`);
+            console.log(`  Count:     ${formatManualInterventionCell(inst.manual_intervention_count)}`);
+            if (inst.started_at) {
+                console.log(`  Started:   ${new Date(inst.started_at).toLocaleString()}`);
+            }
+            if (inst.completed_at) {
+                console.log(`  Completed: ${new Date(inst.completed_at).toLocaleString()}`);
+            }
+            console.log('');
+            console.log(chalk.gray('  Forensic per-event detail: query agent_events for the assignee/reviewer'));
+            console.log(chalk.gray('  identities that drove each increment. Example:'));
+            console.log(chalk.gray(`    fazemos agents events <agent-id> --type manual_intervention`));
+            return;
+        }
+        // ── Mode 2: --since <duration> windowed list ─────────────────
+        if (opts.since) {
+            const since = parseSinceDuration(opts.since);
+            const params = [`since=${encodeURIComponent(since)}`];
+            // For the list endpoint, the API default is exclude_dev=false (a
+            // broader scan-recent-activity surface). --exclude-dev tightens
+            // to prod-only. --include-dev is a no-op here (the default
+            // already includes dev) but accepted so the flag is symmetric
+            // across modes.
+            if (opts.excludeDev)
+                params.push('exclude_dev=true');
+            const limitN = Math.max(1, Math.min(200, Number(opts.limit) || 50));
+            params.push(`limit=${limitN}`);
+            const qs = `?${params.join('&')}`;
+            const data = await api('GET', `/api/ops/manual-interventions${qs}`);
+            if (opts.json) {
+                console.log(JSON.stringify(data, null, 2));
+                return;
+            }
+            const rows = data.pipelines || [];
+            if (!rows.length) {
+                console.log(chalk.green(`No interventions in window since ${since}`));
+                return;
+            }
+            const scope = opts.excludeDev ? 'prod-only' : 'all envs';
+            console.log(chalk.cyan(`Manual interventions since ${since} (${scope}):`));
+            console.log('');
+            // Columns: MI | Env | Status | Started | Name (ID)
+            for (const r of rows) {
+                const mi = formatManualInterventionCell(r.manual_intervention_count);
+                const env = (r.env_tag ?? '—').padEnd(4);
+                const status = (r.status ?? '').padEnd(10);
+                const started = r.started_at ? new Date(r.started_at).toLocaleString() : '';
+                console.log(`  MI:${mi} ${chalk.gray(env)} ${status} ${chalk.gray(started)}`);
+                console.log(`           ${chalk.cyan(r.name)}  ${chalk.gray(r.pipeline_instance_id)}`);
+            }
+            return;
+        }
+        // ── Mode 3: bare summary ─────────────────────────────────────
+        // The summary endpoint defaults exclude_dev=true (cycle exit
+        // criterion is prod-only by spec). --include-dev inverts. The CLI
+        // is explicit either way so log lines are unambiguous.
+        const excludeDev = opts.includeDev ? false : true;
+        const window = opts.window || '7d';
+        const validWindows = ['24h', '7d', '30d'];
+        if (!validWindows.includes(window)) {
+            console.error(chalk.red(`Invalid --window "${window}". Must be one of: ${validWindows.join(', ')}`));
+            process.exit(1);
+        }
+        const qs = `?window=${window}&exclude_dev=${excludeDev}`;
+        const data = await api('GET', `/api/ops/manual-interventions/summary${qs}`);
+        if (opts.json) {
+            console.log(JSON.stringify(data, null, 2));
+            return;
+        }
+        const scope = excludeDev ? 'prod-only' : 'all envs';
+        console.log(chalk.cyan(`Manual interventions — ${data.window} (${scope})`));
+        console.log('');
+        console.log(`  Total runs:           ${data.total_runs}`);
+        console.log(`  Total interventions:  ${data.total_interventions}`);
+        console.log(`  Avg per run:          ${typeof data.avg_per_run === 'number' ? data.avg_per_run.toFixed(2) : data.avg_per_run}`);
+        console.log(`  p95 per run:          ${data.p95_per_run}`);
+        console.log(`  Zero-intervention:    ${data.zero_intervention_runs} of ${data.total_runs} runs`);
+        // Streak gets the same green/amber/grey emphasis as the web chip:
+        // ≥5 is a celebration moment per Sage's spec; 1-4 amber; 0 grey.
+        const streak = data.zero_intervention_streak ?? 0;
+        const streakDisplay = streak >= 5
+            ? chalk.green(`${streak} 🎉`)
+            : streak >= 1
+                ? chalk.yellow(String(streak))
+                : chalk.gray('0');
+        console.log(`  Current streak:       ${streakDisplay}`);
+    }
+    catch (err) {
+        console.error(chalk.red(err.message));
+        process.exit(1);
+    }
+});
 // ── F18 — Project-scoped docs surface ────────────────────────────────
 // Spec: specs/tech/platform/F18-project-scoped-docs-surface-tech-spec.md §8
 //