@formigio/fazemos-cli 0.10.77 → 0.10.79

package/dist/oidc.d.ts

@@ -0,0 +1,111 @@
+/**
+ * OIDC redirect login for the CLI — authorization code + PKCE against the
+ * Cognito hosted UI, with the code caught on a loopback listener.
+ *
+ * ## Why this replaced email/password
+ * `USER_PASSWORD_AUTH` put the operator's password on the CLI's argv (visible
+ * in `ps` and in shell history), could never satisfy an MFA or federated-IdP
+ * challenge, and hardcoded the assumption that Cognito is the only identity
+ * source. The redirect flow moves all of that into the browser, where the
+ * hosted UI already handles it. The CLI's app client has
+ * ALLOW_USER_PASSWORD_AUTH switched off, so this is not merely the preferred
+ * path — it is the only one that works.
+ *
+ * ## Why the ports are a fixed list
+ * RFC 8252 §7.3 says a native app should bind an ephemeral loopback port and
+ * ignore the port when matching. Cognito does not implement that: it compares
+ * redirect_uri byte-for-byte against the registered CallbackURLs and supports
+ * no wildcard. So the ports have to be enumerated on both sides.
+ * LOOPBACK_PORTS below MUST stay identical to CallbackURLs on
+ * CliUserPoolClient in fazemos-api/template.yaml.
+ *
+ * ## What protects the code in transit
+ * PKCE (S256). The verifier never leaves this process, and the authorization
+ * code is worthless without it — which is what makes a plaintext loopback
+ * redirect safe, and why Cognito permits http:// only for localhost. `state`
+ * is checked on the way back to reject a callback this process did not start.
+ */
+/**
+ * Loopback ports the CLI will try, in order.
+ *
+ * MUST match CallbackURLs on CliUserPoolClient in fazemos-api/template.yaml.
+ * Changing this list without redeploying that stack produces a Cognito error
+ * page reading "redirect_mismatch" with no further explanation.
+ */
+export declare const LOOPBACK_PORTS: number[];
+/** Path component of the redirect URI. Also fixed by the registered clients. */
+export declare const CALLBACK_PATH = "/callback";
+/** Scopes requested. Must be a subset of AllowedOAuthScopes on the client. */
+export declare const SCOPES: string[];
+export interface OidcEndpoints {
+    /** Hosted-UI origin, no trailing slash. */
+    hostedUiDomain: string;
+    clientId: string;
+}
+export interface TokenSet {
+    idToken: string;
+    refreshToken: string;
+    /** Seconds until the ID/access tokens expire. */
+    expiresIn: number;
+}
+export declare function createPkcePair(): {
+    verifier: string;
+    challenge: string;
+};
+export declare function createState(): string;
+export declare function buildAuthorizeUrl(opts: {
+    endpoints: OidcEndpoints;
+    redirectUri: string;
+    state: string;
+    codeChallenge: string;
+}): string;
+export declare function buildLogoutUrl(endpoints: OidcEndpoints, redirectUri: string): string;
+export interface CallbackResult {
+    code: string;
+    redirectUri: string;
+}
+/**
+ * Bind the first free loopback port and resolve once the browser hits
+ * CALLBACK_PATH with a matching `state`.
+ *
+ * The server is handed to `onReady` along with the redirect URI it bound, so
+ * the caller can build the authorize URL with the port that was actually
+ * acquired — the URL cannot be constructed before the bind succeeds.
+ */
+export declare function waitForCallback(opts: {
+    state: string;
+    timeoutMs: number;
+    onReady: (redirectUri: string) => void | Promise<void>;
+}): Promise<CallbackResult>;
+/**
+ * Trade the authorization code for tokens at the hosted UI's token endpoint.
+ *
+ * No client secret is sent because the CLI client is public
+ * (GenerateSecret: false) — PKCE is what authenticates the exchange.
+ */
+export declare function exchangeCodeForTokens(opts: {
+    endpoints: OidcEndpoints;
+    code: string;
+    redirectUri: string;
+    codeVerifier: string;
+}): Promise<TokenSet>;
+/**
+ * Read the `email` claim out of an ID token, for display and for the stored
+ * session label.
+ *
+ * This does NOT verify the signature, and must never be used for an
+ * authorization decision. It is safe here because the token came directly
+ * from Cognito's token endpoint over TLS moments earlier, and because the API
+ * verifies it properly on every call.
+ */
+export declare function readEmailClaim(idToken: string): string;
+/**
+ * Open a URL in the user's default browser.
+ *
+ * Returns false when no opener is available (a bare Linux container, a
+ * headless CI box) so the caller can fall back to printing the URL instead of
+ * pretending it worked. stdio is ignored and the child unref'd so a browser
+ * that logs to stdout cannot corrupt the CLI's own output or hold the process
+ * open after login completes.
+ */
+export declare function openBrowser(url: string): boolean;

package/dist/oidc.js

@@ -0,0 +1,283 @@
+/**
+ * OIDC redirect login for the CLI — authorization code + PKCE against the
+ * Cognito hosted UI, with the code caught on a loopback listener.
+ *
+ * ## Why this replaced email/password
+ * `USER_PASSWORD_AUTH` put the operator's password on the CLI's argv (visible
+ * in `ps` and in shell history), could never satisfy an MFA or federated-IdP
+ * challenge, and hardcoded the assumption that Cognito is the only identity
+ * source. The redirect flow moves all of that into the browser, where the
+ * hosted UI already handles it. The CLI's app client has
+ * ALLOW_USER_PASSWORD_AUTH switched off, so this is not merely the preferred
+ * path — it is the only one that works.
+ *
+ * ## Why the ports are a fixed list
+ * RFC 8252 §7.3 says a native app should bind an ephemeral loopback port and
+ * ignore the port when matching. Cognito does not implement that: it compares
+ * redirect_uri byte-for-byte against the registered CallbackURLs and supports
+ * no wildcard. So the ports have to be enumerated on both sides.
+ * LOOPBACK_PORTS below MUST stay identical to CallbackURLs on
+ * CliUserPoolClient in fazemos-api/template.yaml.
+ *
+ * ## What protects the code in transit
+ * PKCE (S256). The verifier never leaves this process, and the authorization
+ * code is worthless without it — which is what makes a plaintext loopback
+ * redirect safe, and why Cognito permits http:// only for localhost. `state`
+ * is checked on the way back to reject a callback this process did not start.
+ */
+import { createServer } from 'http';
+import { createHash, randomBytes } from 'crypto';
+import { spawn } from 'child_process';
+/**
+ * Loopback ports the CLI will try, in order.
+ *
+ * MUST match CallbackURLs on CliUserPoolClient in fazemos-api/template.yaml.
+ * Changing this list without redeploying that stack produces a Cognito error
+ * page reading "redirect_mismatch" with no further explanation.
+ */
+export const LOOPBACK_PORTS = [8976, 8977, 8978, 8979, 8980];
+/** Path component of the redirect URI. Also fixed by the registered clients. */
+export const CALLBACK_PATH = '/callback';
+/** Scopes requested. Must be a subset of AllowedOAuthScopes on the client. */
+export const SCOPES = ['openid', 'email', 'profile'];
+// ── PKCE ────────────────────────────────────────────────────
+/**
+ * base64url per RFC 7636 §A — standard base64 with +/ swapped for -_ and the
+ * padding stripped. Node's 'base64url' encoding does exactly this, but is
+ * spelled out here because a stray '=' silently breaks the S256 comparison
+ * on Cognito's side with a generic invalid_grant.
+ */
+function base64url(buf) {
+    return buf.toString('base64url');
+}
+export function createPkcePair() {
+    // 32 random bytes → 43 base64url chars, comfortably inside RFC 7636's
+    // 43–128 character range for code_verifier.
+    const verifier = base64url(randomBytes(32));
+    const challenge = base64url(createHash('sha256').update(verifier).digest());
+    return { verifier, challenge };
+}
+export function createState() {
+    return base64url(randomBytes(16));
+}
+// ── Authorize URL ───────────────────────────────────────────
+export function buildAuthorizeUrl(opts) {
+    const params = new URLSearchParams({
+        response_type: 'code',
+        client_id: opts.endpoints.clientId,
+        redirect_uri: opts.redirectUri,
+        scope: SCOPES.join(' '),
+        state: opts.state,
+        code_challenge: opts.codeChallenge,
+        code_challenge_method: 'S256',
+    });
+    return `${opts.endpoints.hostedUiDomain.replace(/\/$/, '')}/oauth2/authorize?${params}`;
+}
+export function buildLogoutUrl(endpoints, redirectUri) {
+    const params = new URLSearchParams({
+        client_id: endpoints.clientId,
+        logout_uri: redirectUri,
+    });
+    return `${endpoints.hostedUiDomain.replace(/\/$/, '')}/logout?${params}`;
+}
+// ── Loopback listener ───────────────────────────────────────
+/** A browser-facing page. Deliberately dependency-free and tiny. */
+function resultPage(title, detail) {
+    return `<!doctype html><meta charset="utf-8"><title>${title}</title>
+<style>body{font:16px/1.6 system-ui,-apple-system,sans-serif;margin:16vh auto;max-width:34rem;padding:0 1.5rem;color:#1a1a1a}
+h1{font-size:1.35rem;margin:0 0 .5rem}p{margin:0;color:#555}
+@media(prefers-color-scheme:dark){body{background:#111;color:#eee}p{color:#aaa}}</style>
+<h1>${title}</h1><p>${detail}</p>`;
+}
+/**
+ * Bind the first free loopback port and resolve once the browser hits
+ * CALLBACK_PATH with a matching `state`.
+ *
+ * The server is handed to `onReady` along with the redirect URI it bound, so
+ * the caller can build the authorize URL with the port that was actually
+ * acquired — the URL cannot be constructed before the bind succeeds.
+ */
+export function waitForCallback(opts) {
+    return new Promise((resolve, reject) => {
+        let server;
+        let settled = false;
+        let timer;
+        const finish = (err, result) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            // close() only stops NEW connections; a keep-alive socket keeps the port
+            // bound indefinitely. Every response below sets `Connection: close` and
+            // finish() runs from the res.end() callback, so the body is already
+            // flushed by the time we tear the sockets down — without this a second
+            // login in the same process hits EADDRINUSE on every registered port.
+            server?.close();
+            server?.closeAllConnections?.();
+            if (err)
+                reject(err);
+            else
+                resolve(result);
+        };
+        /** Reply, wait for the bytes to leave, then settle. */
+        const respond = (res, status, body, contentType, done) => {
+            res.writeHead(status, { 'Content-Type': contentType, Connection: 'close' });
+            res.end(body, done);
+        };
+        const tryPort = (index) => {
+            if (index >= LOOPBACK_PORTS.length) {
+                finish(new Error(`Could not bind any of the loopback ports ${LOOPBACK_PORTS.join(', ')}. ` +
+                    `Close whatever is using them and try again — these ports are fixed by ` +
+                    `the redirect URIs registered with Cognito and cannot be chosen freely.`));
+                return;
+            }
+            const port = LOOPBACK_PORTS[index];
+            const s = createServer((req, res) => {
+                // Only the callback path is served. Anything else (a favicon request,
+                // a stray probe) gets a 404 and is ignored, so it cannot settle the
+                // promise or be mistaken for the real redirect.
+                const url = new URL(req.url || '/', `http://localhost:${port}`);
+                if (url.pathname !== CALLBACK_PATH) {
+                    // No `Connection: close` and no finish() — a stray request must not
+                    // end the flow, and the listener stays up for the real redirect.
+                    res.writeHead(404, { 'Content-Type': 'text/plain' });
+                    res.end('Not found');
+                    return;
+                }
+                const error = url.searchParams.get('error');
+                const code = url.searchParams.get('code');
+                const returnedState = url.searchParams.get('state');
+                const HTML = 'text/html; charset=utf-8';
+                if (error) {
+                    const description = url.searchParams.get('error_description') || '';
+                    respond(res, 400, resultPage('Sign-in failed', `${error}. You can close this tab.`), HTML, () => finish(new Error(`Authorization failed: ${error}${description ? ` — ${description}` : ''}`)));
+                    return;
+                }
+                // A mismatched state means this callback belongs to some other flow.
+                // Reject it rather than exchanging a code we did not ask for.
+                if (returnedState !== opts.state) {
+                    respond(res, 400, resultPage('Sign-in failed', 'State mismatch. You can close this tab.'), HTML, () => finish(new Error('Authorization failed: state mismatch (the callback did not come from this login attempt)')));
+                    return;
+                }
+                if (!code) {
+                    respond(res, 400, resultPage('Sign-in failed', 'No authorization code was returned. You can close this tab.'), HTML, () => finish(new Error('Authorization failed: no code in the callback')));
+                    return;
+                }
+                respond(res, 200, resultPage('Signed in to Fazemos', 'You can close this tab and return to your terminal.'), HTML, () => finish(null, { code, redirectUri: `http://localhost:${port}${CALLBACK_PATH}` }));
+            });
+            s.on('error', (err) => {
+                // Port taken (or refused): fall through to the next candidate rather
+                // than failing the whole login.
+                if (err.code === 'EADDRINUSE' || err.code === 'EACCES') {
+                    s.close();
+                    tryPort(index + 1);
+                    return;
+                }
+                finish(err);
+            });
+            // 127.0.0.1, not 0.0.0.0 — the listener must not be reachable from the
+            // network. Binding the wildcard would expose the authorization code to
+            // anything that can reach this host.
+            s.listen(port, '127.0.0.1', () => {
+                server = s;
+                const addr = s.address();
+                const redirectUri = `http://localhost:${addr.port}${CALLBACK_PATH}`;
+                timer = setTimeout(() => finish(new Error('Timed out waiting for the browser redirect. Run the command again.')), opts.timeoutMs);
+                Promise.resolve(opts.onReady(redirectUri)).catch((err) => finish(err));
+            });
+        };
+        tryPort(0);
+    });
+}
+// ── Token exchange ──────────────────────────────────────────
+/**
+ * Trade the authorization code for tokens at the hosted UI's token endpoint.
+ *
+ * No client secret is sent because the CLI client is public
+ * (GenerateSecret: false) — PKCE is what authenticates the exchange.
+ */
+export async function exchangeCodeForTokens(opts) {
+    const body = new URLSearchParams({
+        grant_type: 'authorization_code',
+        client_id: opts.endpoints.clientId,
+        code: opts.code,
+        redirect_uri: opts.redirectUri,
+        code_verifier: opts.codeVerifier,
+    });
+    const res = await fetch(`${opts.endpoints.hostedUiDomain.replace(/\/$/, '')}/oauth2/token`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: body.toString(),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        // Cognito returns {"error":"invalid_grant"} with no detail on the common
+        // failures, so name the likely causes rather than echoing one word.
+        let detail = text;
+        try {
+            const parsed = JSON.parse(text);
+            detail = parsed.error_description || parsed.error || text;
+        }
+        catch { /* keep the raw body */ }
+        throw new Error(`Token exchange failed (${res.status}): ${detail}. ` +
+            `Usual causes: the code was already used, it expired (they last a few minutes), ` +
+            `or redirect_uri did not match the one sent to /oauth2/authorize.`);
+    }
+    const data = JSON.parse(text);
+    if (!data.id_token || !data.refresh_token) {
+        throw new Error('Token exchange succeeded but returned no id_token/refresh_token.');
+    }
+    return {
+        idToken: data.id_token,
+        refreshToken: data.refresh_token,
+        expiresIn: data.expires_in ?? 3600,
+    };
+}
+// ── ID token claims ─────────────────────────────────────────
+/**
+ * Read the `email` claim out of an ID token, for display and for the stored
+ * session label.
+ *
+ * This does NOT verify the signature, and must never be used for an
+ * authorization decision. It is safe here because the token came directly
+ * from Cognito's token endpoint over TLS moments earlier, and because the API
+ * verifies it properly on every call.
+ */
+export function readEmailClaim(idToken) {
+    try {
+        const payload = idToken.split('.')[1];
+        if (!payload)
+            return 'unknown';
+        const claims = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+        return claims.email || claims['cognito:username'] || 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}
+// ── Browser ─────────────────────────────────────────────────
+/**
+ * Open a URL in the user's default browser.
+ *
+ * Returns false when no opener is available (a bare Linux container, a
+ * headless CI box) so the caller can fall back to printing the URL instead of
+ * pretending it worked. stdio is ignored and the child unref'd so a browser
+ * that logs to stdout cannot corrupt the CLI's own output or hold the process
+ * open after login completes.
+ */
+export function openBrowser(url) {
+    const opener = process.platform === 'darwin' ? { cmd: 'open', args: [url] }
+        : process.platform === 'win32' ? { cmd: 'cmd', args: ['/c', 'start', '', url] }
+            : { cmd: 'xdg-open', args: [url] };
+    try {
+        const child = spawn(opener.cmd, opener.args, { stdio: 'ignore', detached: true });
+        child.on('error', () => { });
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=oidc.js.map

package/dist/oidc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc.js","sourceRoot":"","sources":["../src/oidc.ts"],"names":[],"mappings":"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"}

package/dist/wake.d.ts

@@ -56,6 +56,86 @@
  * a future refactor cannot silently reintroduce project scoping.
  */
 import type { Command } from 'commander';
+/** A single schedule entry from GET /api/control-plane/wake. */
+interface WakeScheduleEntry {
+    role: string;
+    auto_wakeable: boolean;
+    allow_listed: boolean;
+    enabled: boolean;
+}
+/** A single wake fire record from GET /api/control-plane/wake (capped at 50). */
+interface WakeFireEntry {
+    id: string;
+    dispatch_id: string;
+    role: string;
+    fire_status: string;
+    suppress_code: string | null;
+    claimed_at: string;
+    fired_at: string | null;
+}
+/**
+ * BUG159-A + addendum 2026-08-26: resolved scope returned by the API so the
+ * CLI can render the header from the response, not from local config.
+ *
+ * - allowlist_scope: always 'global' (SSM-sourced, org-agnostic).
+ * - disables_scope: always 'org' (wake_disables PK is (org_id, role)).
+ *   These are level identifiers, NOT slug values.
+ * - org_slug: the slug rendered in the disables position of the header:
+ *   "allowlist: global | disables: <org_slug>"
+ * - project_slug: the slug rendered in the location part of the header:
+ *   "Wake schedule for <org_slug>/<project_slug> (N entries)"
+ *
+ * NEVER use disables_scope as a display value — it is a level identifier ('org').
+ * ALWAYS use org_slug in the disables position.
+ */
+interface WakeScopeInfo {
+    org_slug: string;
+    project_slug: string;
+    allowlist_scope: 'global';
+    disables_scope: 'org';
+}
+/** A single suppression row from the GET /api/control-plane/wake response (Item 5). */
+interface WakeSuppressionRow {
+    event_type: string;
+    code: string | null;
+    reason: string | null;
+    /** AC-33 (r4): the suppression class, kept beside the human-readable reason. */
+    subreason?: string | null;
+    subject_kind: string | null;
+    subject_id: string | null;
+    project_id: string | null;
+    role: string | null;
+    created_at: string;
+    org_id: string;
+}
+/** Suppressions block returned by the API (Item 5 — additive, may be absent on older API). */
+interface WakeSuppressionsBlock {
+    rows: WakeSuppressionRow[];
+    total_count: number;
+    truncated: boolean;
+    window_start: string;
+}
+export interface WakeGetResponse {
+    schedule: WakeScheduleEntry[];
+    fires: WakeFireEntry[];
+    config?: {
+        wake_allowlist_source: string;
+        auto_wakeable_roles_source: string;
+    };
+    /** BUG159-A: resolved scope from the API. */
+    scope?: WakeScopeInfo;
+    /** Item 5: recent suppression ledger rows. Absent on older API — degrade cleanly. */
+    suppressions?: WakeSuppressionsBlock;
+}
+/**
+ * Render the "Recent suppressions" block of `fazemos wake status` (Item 5 — §3.5.2g).
+ *
+ * Exported so T-5h can drive it directly: an older API omits `suppressions`
+ * entirely, and this MUST render nothing rather than throw. Every field inside a
+ * row is likewise treated as optional — the block degrades, it never crashes a
+ * status read the operator is relying on to diagnose a silent wake.
+ */
+export declare function renderWakeSuppressions(data: WakeGetResponse): void;
 /**
  * Register `wake status`, `wake disable`, and `wake enable` into the root
  * Commander program. Called from index.ts after `program` is created, alongside
@@ -71,3 +151,4 @@ import type { Command } from 'commander';
  *   on status; disable/enable use req.userOrgId from auth context (no project needed).
  */
 export declare function registerWakeCommands(program: Command): void;
+export {};

package/dist/wake.js

@@ -55,6 +55,47 @@ function renderScopeHeader(scope, entryCount) {
     const splitNote = chalk.dim(`(allowlist: ${scope.allowlist_scope} | disables: ${scope.org_slug})`);
     console.log(chalk.bold(`Wake schedule for ${location} ${splitNote} (${entryCount} entries):`));
 }
+/**
+ * Render the "Recent suppressions" block of `fazemos wake status` (Item 5 — §3.5.2g).
+ *
+ * Exported so T-5h can drive it directly: an older API omits `suppressions`
+ * entirely, and this MUST render nothing rather than throw. Every field inside a
+ * row is likewise treated as optional — the block degrades, it never crashes a
+ * status read the operator is relying on to diagnose a silent wake.
+ */
+export function renderWakeSuppressions(data) {
+    // T-5h: older API omits the field — degrade cleanly, render nothing, no error.
+    const suppressions = data?.suppressions;
+    if (!suppressions || !Array.isArray(suppressions.rows) || suppressions.rows.length === 0)
+        return;
+    console.log(chalk.bold(`Recent suppressions (${suppressions.total_count}${suppressions.truncated ? '+' : ''}):`));
+    console.log();
+    for (const row of suppressions.rows) {
+        const roleLabel = row.role ? chalk.cyan(row.role.padEnd(32)) : chalk.dim('(no role)'.padEnd(32));
+        console.log(`  ${roleLabel} ${chalk.yellow(row.event_type)}`);
+        if (row.code) {
+            console.log(`    code:         ${chalk.yellow(row.code)}`);
+        }
+        if (row.reason) {
+            console.log(`    reason:       ${row.reason}`);
+        }
+        // AC-33 (Dex item-5 F7): the CLASS, printed alongside the explanation.
+        // Before r4 the api's `reason` carried the class ('canlaunch_suppressed')
+        // and the explanation was never surfaced at all; now `reason` is the
+        // explanation and this line keeps the class visible. Optional — an older
+        // api omits it and this renders nothing.
+        if (row.subreason) {
+            console.log(`    class:        ${chalk.dim(row.subreason)}`);
+        }
+        if (row.subject_kind && row.subject_id) {
+            console.log(`    subject:      ${row.subject_kind}/${chalk.dim(row.subject_id)}`);
+        }
+        if (row.created_at) {
+            console.log(`    at:           ${new Date(row.created_at).toLocaleString()}`);
+        }
+        console.log();
+    }
+}
 // ── Command registration ───────────────────────────────────────────────────────
 /**
  * Register `wake status`, `wake disable`, and `wake enable` into the root
@@ -212,26 +253,46 @@ export function registerWakeCommands(program) {
                 console.log();
             }
             // ── Recent fires ──────────────────────────────────────────────────────
+            // ── AC-17 / T-5o (Dex item-5 F2) — an empty fires list must NOT
+            // short-circuit the suppression block ────────────────────────────────
+            //
+            // This used to `return` here, so `renderWakeSuppressions(data)` below
+            // never ran. Post-item-5 a canLaunch-suppressed wake does leave a
+            // wake_fires row, so that one class survived the early return — but
+            // EVERY decision-predicate denial returns before the claim and writes
+            // NO wake_fires row at all (wrong_type, self_wake, worker_gated,
+            // not_auto_wakeable, wake_disabled, no_project, no_match_after_ordering,
+            // db_error), and so do launch_suppressed and wake_ceiling_hit. Those
+            // are the MOST COMMON real causes of "I dispatched and the role never
+            // woke" — and for all of them `fires` is empty, so the operator got
+            // "No recent wake fires." with the answer sitting one statement below
+            // the return. That is the BUG177 shape the ledger exists to close.
             if (fires.length === 0) {
                 console.log(chalk.dim('No recent wake fires.'));
-                return;
+                console.log();
             }
-            console.log(chalk.bold(`Recent wake fires (${fires.length}):`));
-            console.log();
-            for (const fire of fires) {
-                const statusLabel = fireStatusLabel(fire.fire_status);
-                console.log(`  ${chalk.cyan(fire.role.padEnd(32))} ${statusLabel}`);
-                if (fire.suppress_code) {
-                    console.log(`    suppressed:   ${chalk.yellow(fire.suppress_code)}`);
-                }
-                console.log(`    claimed:      ${new Date(fire.claimed_at).toLocaleString()}`);
-                if (fire.fired_at) {
-                    console.log(`    fired:        ${new Date(fire.fired_at).toLocaleString()}`);
-                }
-                console.log(`    dispatch_id:  ${chalk.dim(fire.dispatch_id)}`);
-                console.log(`    id:           ${chalk.dim(fire.id)}`);
+            else {
+                console.log(chalk.bold(`Recent wake fires (${fires.length}):`));
                 console.log();
+                for (const fire of fires) {
+                    const statusLabel = fireStatusLabel(fire.fire_status);
+                    console.log(`  ${chalk.cyan(fire.role.padEnd(32))} ${statusLabel}`);
+                    if (fire.suppress_code) {
+                        console.log(`    suppressed:   ${chalk.yellow(fire.suppress_code)}`);
+                    }
+                    console.log(`    claimed:      ${new Date(fire.claimed_at).toLocaleString()}`);
+                    if (fire.fired_at) {
+                        console.log(`    fired:        ${new Date(fire.fired_at).toLocaleString()}`);
+                    }
+                    console.log(`    dispatch_id:  ${chalk.dim(fire.dispatch_id)}`);
+                    console.log(`    id:           ${chalk.dim(fire.id)}`);
+                    console.log();
+                }
             }
+            // ── Recent suppressions (Item 5) ──────────────────────────────────────
+            // Always reached now — AC-17 / T-5o. renderWakeSuppressions degrades on
+            // its own for an absent, null, empty or malformed block.
+            renderWakeSuppressions(data);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);