@ciphrix/cli 0.1.0

package/dist/config.js

@@ -0,0 +1,56 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** Public client identifier registered with the Ciphrix device-authorization endpoint. */
+export const CLI_CLIENT_ID = 'ciphrix-cli';
+/** Production API base. Override with `--api-url` or `CIPHRIX_API_URL`. */
+export const DEFAULT_API_BASE_URL = 'https://global.api.ciphrix.app/api';
+let cliAllowsInsecureHttp = false;
+/** Used by the CLI hooks to scope the command-line opt-in to one command invocation. */
+export const setCliInsecureHttpOptIn = (allowed) => {
+    cliAllowsInsecureHttp = allowed;
+};
+export const normalizeBaseUrl = (value) => {
+    const trimmed = value.trim();
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        throw new Error(`Invalid API URL: ${value}`);
+    }
+    const authority = trimmed.match(/^[a-z][a-z0-9+.-]*:\/\/([^/?#]*)/i)?.[1] ?? '';
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new Error('Invalid API URL: only HTTPS URLs are supported (HTTP requires explicit opt-in)');
+    }
+    if (!url.hostname ||
+        authority.includes('@') ||
+        url.username ||
+        url.password ||
+        url.search ||
+        url.hash ||
+        trimmed.includes('?') ||
+        trimmed.includes('#')) {
+        throw new Error('Invalid API URL: provide a hostname and optional path without credentials, query, or fragment');
+    }
+    url.pathname = url.pathname.replace(/\/+$/, '') || '/';
+    return url
+        .toString()
+        .replace(/\/$/, url.pathname === '/' ? '' : '/')
+        .replace(/\/$/, '');
+};
+export const resolveApiBaseUrl = ({ flag, env = process.env, } = {}) => {
+    const candidate = flag || env.CIPHRIX_API_URL || DEFAULT_API_BASE_URL;
+    const normalized = normalizeBaseUrl(candidate);
+    const parsed = new URL(normalized);
+    const envAllowsInsecureHttp = env.CIPHRIX_ALLOW_INSECURE_HTTP === '1' ||
+        env.CIPHRIX_ALLOW_INSECURE_HTTP?.toLowerCase() === 'true';
+    if (parsed.protocol === 'http:' && !envAllowsInsecureHttp && !cliAllowsInsecureHttp) {
+        throw new Error('Refusing to send credentials or data over HTTP. Use HTTPS, or explicitly opt in for local testing with --allow-insecure-http or CIPHRIX_ALLOW_INSECURE_HTTP=true.');
+    }
+    return normalized;
+};
+export const configDir = (env = process.env) => {
+    const xdg = env.XDG_CONFIG_HOME;
+    const base = xdg && xdg.trim() !== '' ? xdg : join(homedir(), '.config');
+    return join(base, 'ciphrix');
+};

package/dist/constants.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Product identity for the CLI. Kept in one place so commands, help text and
+ * the banner never drift from each other.
+ */
+export declare const CLI_NAME = "ciphrix";
+export declare const CLI_TAGLINE = "Ciphrix compliance platform CLI";
+export declare const CLI_VERSION = "0.1.0";

package/dist/constants.js

@@ -0,0 +1,7 @@
+/**
+ * Product identity for the CLI. Kept in one place so commands, help text and
+ * the banner never drift from each other.
+ */
+export const CLI_NAME = 'ciphrix';
+export const CLI_TAGLINE = 'Ciphrix compliance platform CLI';
+export const CLI_VERSION = '0.1.0';

package/dist/credentials.d.ts

@@ -0,0 +1,19 @@
+export interface Credential {
+    apiUrl: string;
+    token: string;
+}
+export interface CredentialStore {
+    get(apiUrl: string): Promise<Credential | null>;
+    set(credential: Credential): Promise<void>;
+    clear(apiUrl: string): Promise<void>;
+}
+export interface CredentialStoreOptions {
+    directory?: string;
+    forceFile?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Uses the OS keychain by default. The less secure file store is only used when
+ * explicitly selected with `CIPHRIX_CREDENTIAL_STORE=file` or `forceFile`.
+ */
+export declare const createCredentialStore: (options?: CredentialStoreOptions) => Promise<CredentialStore>;

package/dist/credentials.js

@@ -0,0 +1,182 @@
+import { constants } from 'node:fs';
+import { chmod, lstat, mkdir, open, rename, rm } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { configDir } from './config.js';
+const KEYRING_SERVICE = 'ciphrix-cli';
+const keychainError = () => new Error('The OS keychain is unavailable or could not be accessed. No credential was read, saved, or removed. ' +
+    'For local or headless testing only, explicitly set CIPHRIX_CREDENTIAL_STORE=file to use the ' +
+    'permission-restricted file store.');
+const loadEntryFactory = async () => {
+    try {
+        const keyring = await import('@napi-rs/keyring');
+        return (service, account) => new keyring.Entry(service, account);
+    }
+    catch {
+        throw keychainError();
+    }
+};
+const createKeyringStore = (entryFactory) => ({
+    get: (apiUrl) => {
+        try {
+            const token = entryFactory(KEYRING_SERVICE, apiUrl).getPassword();
+            return Promise.resolve(token ? { apiUrl, token } : null);
+        }
+        catch {
+            return Promise.reject(keychainError());
+        }
+    },
+    set: (credential) => {
+        try {
+            entryFactory(KEYRING_SERVICE, credential.apiUrl).setPassword(credential.token);
+            return Promise.resolve();
+        }
+        catch {
+            return Promise.reject(keychainError());
+        }
+    },
+    clear: (apiUrl) => {
+        try {
+            entryFactory(KEYRING_SERVICE, apiUrl).deletePassword();
+            return Promise.resolve();
+        }
+        catch {
+            return Promise.reject(keychainError());
+        }
+    },
+});
+const fileStoreError = (action) => new Error(`Unable to ${action} the credential file. Check its permissions and integrity.`);
+const ensurePrivateDirectory = async (directory) => {
+    try {
+        await mkdir(directory, { recursive: true, mode: 0o700 });
+        const info = await lstat(directory);
+        if (info.isSymbolicLink() || !info.isDirectory())
+            throw fileStoreError('access');
+        await chmod(directory, 0o700);
+    }
+    catch {
+        throw fileStoreError('secure');
+    }
+};
+const isMissing = (error) => typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT';
+const parseCredentials = (contents) => {
+    let parsed;
+    try {
+        parsed = JSON.parse(contents);
+    }
+    catch {
+        throw fileStoreError('read');
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw fileStoreError('read');
+    }
+    const credentials = Object.create(null);
+    for (const [apiUrl, value] of Object.entries(parsed)) {
+        if (apiUrl.length === 0 ||
+            typeof value !== 'object' ||
+            value === null ||
+            Array.isArray(value) ||
+            typeof value.token !== 'string' ||
+            value.token.length === 0) {
+            throw fileStoreError('read');
+        }
+        Object.defineProperty(credentials, apiUrl, {
+            value: { token: value.token },
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return credentials;
+};
+const createFileStore = (directory) => {
+    const path = join(directory, 'credentials.json');
+    let operationQueue = Promise.resolve();
+    const serialized = (operation) => {
+        const result = operationQueue.then(operation);
+        operationQueue = result.then(() => undefined, () => undefined);
+        return result;
+    };
+    const read = async () => {
+        await ensurePrivateDirectory(dirname(path));
+        let file;
+        try {
+            try {
+                const pathInfo = await lstat(path);
+                if (pathInfo.isSymbolicLink() || !pathInfo.isFile())
+                    throw fileStoreError('read');
+            }
+            catch (error) {
+                if (!isMissing(error))
+                    throw error;
+            }
+            const noFollow = constants.O_NOFOLLOW ?? 0;
+            file = await open(path, constants.O_RDONLY | noFollow);
+            const info = await file.stat();
+            if (!info.isFile())
+                throw fileStoreError('read');
+            await file.chmod(0o600);
+            return parseCredentials(await file.readFile('utf8'));
+        }
+        catch (error) {
+            if (isMissing(error))
+                return Object.create(null);
+            throw fileStoreError('read');
+        }
+        finally {
+            await file?.close().catch(() => undefined);
+        }
+    };
+    const write = async (data) => {
+        await ensurePrivateDirectory(dirname(path));
+        const temporaryPath = join(dirname(path), `.credentials-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.tmp`);
+        let handle;
+        try {
+            handle = await open(temporaryPath, 'wx', 0o600);
+            await handle.writeFile(`${JSON.stringify(data, null, 2)}\n`, 'utf8');
+            await handle.sync();
+            await handle.close();
+            handle = undefined;
+            await rename(temporaryPath, path);
+        }
+        catch {
+            await handle?.close().catch(() => undefined);
+            await rm(temporaryPath, { force: true }).catch(() => undefined);
+            throw fileStoreError('write');
+        }
+    };
+    return {
+        get: (apiUrl) => serialized(async () => {
+            const entry = (await read())[apiUrl];
+            return entry ? { apiUrl, token: entry.token } : null;
+        }),
+        set: (credential) => serialized(async () => {
+            if (!credential.apiUrl || !credential.token)
+                throw fileStoreError('write');
+            const data = await read();
+            Object.defineProperty(data, credential.apiUrl, {
+                value: { token: credential.token },
+                enumerable: true,
+                configurable: true,
+                writable: true,
+            });
+            await write(data);
+        }),
+        clear: (apiUrl) => serialized(async () => {
+            const data = await read();
+            if (!Object.hasOwn(data, apiUrl))
+                return;
+            delete data[apiUrl];
+            await write(data);
+        }),
+    };
+};
+/**
+ * Uses the OS keychain by default. The less secure file store is only used when
+ * explicitly selected with `CIPHRIX_CREDENTIAL_STORE=file` or `forceFile`.
+ */
+export const createCredentialStore = async (options = {}) => {
+    const { directory = configDir(options.env), forceFile = false, env = process.env } = options;
+    if (forceFile || env.CIPHRIX_CREDENTIAL_STORE === 'file')
+        return createFileStore(directory);
+    return createKeyringStore(await loadEntryFactory());
+};

package/dist/deviceFlow.d.ts

@@ -0,0 +1,32 @@
+import { type ApiClient } from './api.js';
+import type { DeviceIdentity } from './deviceInfo.js';
+export declare const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+export declare const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+export declare const MIN_POLL_INTERVAL_SECONDS = 1;
+export declare const MAX_INITIAL_POLL_INTERVAL_SECONDS = 60;
+export declare const MAX_POLL_INTERVAL_SECONDS = 300;
+export declare const MAX_DEVICE_CODE_LIFETIME_SECONDS = 3600;
+export interface DeviceCodeRequest {
+    deviceCode: string;
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete: string | null;
+    intervalSeconds: number;
+    expiresInSeconds: number;
+}
+export declare const requestDeviceCode: (client: ApiClient, clientId?: string, identity?: DeviceIdentity) => Promise<DeviceCodeRequest>;
+export interface PollOptions {
+    client: ApiClient;
+    deviceCode: string;
+    intervalSeconds: number;
+    expiresInSeconds: number;
+    clientId?: string;
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    onPoll?: () => void;
+}
+/**
+ * Polls the token endpoint until the user approves, the code expires, or the
+ * request is denied. Honours `authorization_pending` and `slow_down` per RFC 8628.
+ */
+export declare const pollForToken: ({ client, deviceCode, intervalSeconds, expiresInSeconds, clientId, sleep, now, onPoll, }: PollOptions) => Promise<string>;

package/dist/deviceFlow.js

@@ -0,0 +1,115 @@
+import { ApiError } from './api.js';
+import { CLI_CLIENT_ID } from './config.js';
+export const DEVICE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
+export const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+export const MIN_POLL_INTERVAL_SECONDS = 1;
+export const MAX_INITIAL_POLL_INTERVAL_SECONDS = 60;
+export const MAX_POLL_INTERVAL_SECONDS = 300;
+export const MAX_DEVICE_CODE_LIFETIME_SECONDS = 3600;
+const asRecord = (value) => value && typeof value === 'object' ? value : {};
+const asString = (value, fallback = '') => typeof value === 'string' ? value : fallback;
+const boundedInteger = (value, label, min, max, fallback, clampMaximum = true) => {
+    if (value === undefined && fallback !== undefined)
+        return fallback;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < min) {
+        throw new Error(`The server returned an invalid ${label}.`);
+    }
+    if (value > max && !clampMaximum)
+        throw new Error(`The server returned an unsupported ${label}.`);
+    return Math.min(value, max);
+};
+const verificationUrl = (value, label) => {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`The server returned an invalid ${label}.`);
+    }
+    const isLoopback = url.hostname === 'localhost' ||
+        url.hostname === '[::1]' ||
+        /^127(?:\.\d{1,3}){3}$/.test(url.hostname);
+    if ((url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopback)) ||
+        url.username ||
+        url.password) {
+        throw new Error(`The server returned an invalid ${label}.`);
+    }
+    return url.href;
+};
+export const requestDeviceCode = async (client, clientId = CLI_CLIENT_ID, identity = {}) => {
+    const body = { client_id: clientId };
+    if (identity.deviceName)
+        body.device_name = identity.deviceName;
+    if (identity.devicePlatform)
+        body.device_platform = identity.devicePlatform;
+    const data = asRecord(await client.request('/auth/device/code', { method: 'POST', body }));
+    const deviceCode = asString(data.device_code);
+    const userCode = asString(data.user_code);
+    const rawVerificationUri = asString(data.verification_uri);
+    if (!deviceCode || !userCode || !rawVerificationUri) {
+        throw new Error('The server did not return a device code.');
+    }
+    const verificationUri = verificationUrl(rawVerificationUri, 'verification URL');
+    const rawVerificationUriComplete = asString(data.verification_uri_complete);
+    const verificationUriComplete = rawVerificationUriComplete
+        ? verificationUrl(rawVerificationUriComplete, 'complete verification URL')
+        : null;
+    const intervalSeconds = boundedInteger(data.interval, 'polling interval', MIN_POLL_INTERVAL_SECONDS, MAX_INITIAL_POLL_INTERVAL_SECONDS, DEFAULT_POLL_INTERVAL_SECONDS, false);
+    // RFC 8628 requires expires_in. There is no protocol default, so reject a missing or malformed
+    // lifetime instead of guessing and potentially polling after the authorization code expires.
+    const expiresInSeconds = boundedInteger(data.expires_in, 'device-code lifetime', 1, MAX_DEVICE_CODE_LIFETIME_SECONDS);
+    return {
+        deviceCode,
+        userCode,
+        verificationUri,
+        verificationUriComplete,
+        intervalSeconds,
+        expiresInSeconds,
+    };
+};
+/**
+ * Polls the token endpoint until the user approves, the code expires, or the
+ * request is denied. Honours `authorization_pending` and `slow_down` per RFC 8628.
+ */
+export const pollForToken = async ({ client, deviceCode, intervalSeconds, expiresInSeconds, clientId = CLI_CLIENT_ID, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), now = () => Date.now(), onPoll, }) => {
+    const safeInterval = boundedInteger(intervalSeconds, 'polling interval', MIN_POLL_INTERVAL_SECONDS, MAX_INITIAL_POLL_INTERVAL_SECONDS, undefined, false);
+    const safeLifetime = boundedInteger(expiresInSeconds, 'device-code lifetime', 1, MAX_DEVICE_CODE_LIFETIME_SECONDS);
+    const deadline = now() + safeLifetime * 1000;
+    let interval = safeInterval;
+    while (now() < deadline) {
+        const remainingMs = deadline - now();
+        if (remainingMs <= 0)
+            break;
+        await sleep(Math.min(interval * 1000, remainingMs));
+        if (now() >= deadline)
+            break;
+        try {
+            const data = asRecord(await client.request('/auth/device/token', {
+                method: 'POST',
+                body: { grant_type: DEVICE_GRANT_TYPE, device_code: deviceCode, client_id: clientId },
+            }));
+            if (now() >= deadline)
+                break;
+            const token = asString(data.access_token);
+            if (!token)
+                throw new Error('The server did not return an access token.');
+            return token;
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.code === 'authorization_pending') {
+                onPoll?.();
+                continue;
+            }
+            if (error instanceof ApiError && error.code === 'slow_down') {
+                if (interval + 5 > MAX_POLL_INTERVAL_SECONDS) {
+                    throw new Error('The authorization server is asking the CLI to poll too slowly. Run `ciphrix login` again later.', { cause: error });
+                }
+                interval += 5;
+                onPoll?.();
+                continue;
+            }
+            throw error;
+        }
+    }
+    throw new Error('The device code expired before it was approved. Run `ciphrix login` again.');
+};

package/dist/deviceInfo.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A friendly default device name derived from the machine hostname, so a fresh
+ * login is recognisable on the approval page without any setup.
+ */
+export declare const defaultDeviceName: () => string;
+export declare const defaultDevicePlatform: () => string;
+export interface DeviceIdentity {
+    deviceName?: string | undefined;
+    devicePlatform?: string | undefined;
+}
+export declare const resolveDeviceIdentity: (deviceName?: string) => Required<DeviceIdentity>;

package/dist/deviceInfo.js

@@ -0,0 +1,25 @@
+import { hostname, platform } from 'node:os';
+const PLATFORM_LABELS = {
+    darwin: 'macOS',
+    win32: 'Windows',
+    linux: 'Linux',
+};
+/**
+ * A friendly default device name derived from the machine hostname, so a fresh
+ * login is recognisable on the approval page without any setup.
+ */
+export const defaultDeviceName = () => {
+    const raw = hostname()
+        .replace(/\.local$/i, '')
+        .replace(/[-_]+/g, ' ')
+        .trim();
+    return raw === '' ? 'This device' : raw;
+};
+export const defaultDevicePlatform = () => {
+    const label = PLATFORM_LABELS[platform()] ?? platform();
+    return `${label} · ${process.arch}`;
+};
+export const resolveDeviceIdentity = (deviceName) => ({
+    deviceName: deviceName?.trim() || defaultDeviceName(),
+    devicePlatform: defaultDevicePlatform(),
+});

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from './cli.js';
+const exitCode = await main(process.argv);
+process.exitCode = exitCode;

package/dist/io.d.ts

@@ -0,0 +1,46 @@
+import { type Theme } from './theme.js';
+/**
+ * Output targets for the CLI. Commands receive this rather than touching
+ * `process` directly, so they can be tested with captured streams.
+ */
+export interface CliIO {
+    readonly stdout: NodeJS.WriteStream;
+    readonly stderr: NodeJS.WriteStream;
+    readonly theme: Theme;
+}
+export declare const createDefaultIO: () => CliIO;
+export declare const writeLine: (stream: NodeJS.WriteStream, text?: string) => void;
+/** Writes a local, intentionally multiline block such as the fixed CLI banner. */
+export declare const writeBlock: (stream: NodeJS.WriteStream, text: string) => void;
+export declare const renderTerminalText: (text: string) => string;
+/**
+ * Remove terminal controls from untrusted text.
+ * Newlines and carriage returns become spaces so a server value cannot forge extra output lines.
+ */
+export declare const sanitizeTerminalText: (value: string) => string;
+/**
+ * Renders an aligned table. Column widths follow the content; the last column may overflow gracefully.
+ */
+export declare const writeTable: (io: CliIO, headers: string[], rows: string[][]) => void;
+/**
+ * Prints a pagination footer for a list. Makes truncation explicit and shows the next page command.
+ */
+export declare const writePageFooter: (io: CliIO, { shown, total, page, limit, hasMore, }: {
+    shown: number;
+    total: number;
+    page: number;
+    limit: number;
+    hasMore: boolean;
+}) => void;
+/**
+ * One dim line naming the drill-down for what was just listed, so the next step is obvious rather than
+ * guessed. Callers pass the concrete command; nothing is printed when there is nothing to drill into.
+ */
+export declare const writeNextHint: (io: CliIO, command: string | null | undefined) => void;
+/** Clips a value to a column-friendly width. Asset names are often long cloud ARNs. */
+export declare const clip: (value: string, max?: number) => string;
+/**
+ * Asks a yes/no question. Returns false when there is no interactive terminal,
+ * so a non-`--yes` write never applies in a pipe or CI by accident.
+ */
+export declare const promptConfirm: (io: CliIO, question: string) => Promise<boolean>;

package/dist/io.js

@@ -0,0 +1,99 @@
+import { createInterface } from 'node:readline/promises';
+import { createTheme, renderThemeStyles } from './theme.js';
+export const createDefaultIO = () => ({
+    stdout: process.stdout,
+    stderr: process.stderr,
+    theme: createTheme(),
+});
+export const writeLine = (stream, text = '') => {
+    stream.write(`${safeOutputText(text)}\n`);
+};
+/** Writes a local, intentionally multiline block such as the fixed CLI banner. */
+export const writeBlock = (stream, text) => {
+    stream.write(text
+        .split(/\r\n|[\r\n]/)
+        .map(safeOutputText)
+        .join('\n'));
+};
+const safeOutputText = (text) => {
+    try {
+        JSON.parse(text);
+        // JSON.stringify leaves C1 code points literal. Escape them in the serialized representation so
+        // consumers recover the original values while terminals never interpret them as controls.
+        return text.replace(/[\u0080-\u009F]/g, (character) => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+    }
+    catch {
+        return renderTerminalText(text);
+    }
+};
+export const renderTerminalText = (text) => renderThemeStyles(sanitizeTerminalText(text));
+/**
+ * Remove terminal controls from untrusted text.
+ * Newlines and carriage returns become spaces so a server value cannot forge extra output lines.
+ */
+export const sanitizeTerminalText = (value) => {
+    // OSC, DCS, SOS, PM and APC strings may end with BEL or ST (7-bit or 8-bit).
+    const withoutStrings = value.replace(/(?:\u001B\][\s\S]*?(?:\u0007|\u001B\\|\u009C)|\u009D[\s\S]*?(?:\u0007|\u001B\\|\u009C)|\u001B[P^_X][\s\S]*?(?:\u001B\\|\u009C)|[\u0090\u0098\u009E\u009F][\s\S]*?(?:\u001B\\|\u009C))/g, '');
+    // Theme styling uses private markers that are restored only after sanitization. Remove every
+    // actual CSI and ESC sequence here, including SGR sequences supplied by untrusted data.
+    const withoutControls = withoutStrings
+        .replace(/\u001B\[[0-?]*[ -/]*[@-~]/g, '')
+        .replace(/\u009B[0-?]*[ -/]*[@-~]/g, '')
+        .replace(/\u001B(?!\[)[ -/]*[0-~]/g, '')
+        .replace(/\u001B(?!\[[0-9;]*m)/g, '')
+        .replace(/[\u0000-\u0009\u000B\u000C\u000E-\u001A\u001C-\u001F\u007F-\u009F]/g, '');
+    return withoutControls.replace(/\r\n|[\r\n]/g, ' ');
+};
+/**
+ * Renders an aligned table. Column widths follow the content; the last column may overflow gracefully.
+ */
+export const writeTable = (io, headers, rows) => {
+    const safeHeaders = headers.map(sanitizeTerminalText);
+    const safeRows = rows.map((row) => row.map(sanitizeTerminalText));
+    const widths = safeHeaders.map((header, index) => Math.max(stripAnsi(header).length, ...safeRows.map((row) => stripAnsi(row[index] ?? '').length)));
+    const render = (cells) => cells
+        .map((cell, index) => index === cells.length - 1 ? cell : cell.padEnd((widths[index] ?? 0) + 2))
+        .join('');
+    writeLine(io.stdout, io.theme.dim(render(safeHeaders)));
+    for (const row of safeRows)
+        writeLine(io.stdout, render(row));
+};
+const stripAnsi = (value) => sanitizeTerminalText(value).replace(/\u001B\[[0-9;]*m/g, '');
+/**
+ * Prints a pagination footer for a list. Makes truncation explicit and shows the next page command.
+ */
+export const writePageFooter = (io, { shown, total, page, limit, hasMore, }) => {
+    if (total <= 0)
+        return;
+    const first = (page - 1) * limit + 1;
+    const last = Math.min(first + shown - 1, total);
+    const range = shown === 0 ? '0' : `${first}–${last}`;
+    writeLine(io.stdout, io.theme.dim(`showing ${range} of ${total}${hasMore ? ` · next: --page ${page + 1}` : ''}`));
+};
+/**
+ * One dim line naming the drill-down for what was just listed, so the next step is obvious rather than
+ * guessed. Callers pass the concrete command; nothing is printed when there is nothing to drill into.
+ */
+export const writeNextHint = (io, command) => {
+    if (!command)
+        return;
+    writeLine(io.stdout, io.theme.dim(`next: ${command}`));
+};
+/** Clips a value to a column-friendly width. Asset names are often long cloud ARNs. */
+export const clip = (value, max = 60) => value.length > max ? `${value.slice(0, max - 1)}\u2026` : value;
+/**
+ * Asks a yes/no question. Returns false when there is no interactive terminal,
+ * so a non-`--yes` write never applies in a pipe or CI by accident.
+ */
+export const promptConfirm = async (io, question) => {
+    if (io.stdout.isTTY !== true)
+        return false;
+    const rl = createInterface({ input: process.stdin, output: io.stdout });
+    try {
+        const answer = await rl.question(`${sanitizeTerminalText(question)} [y/N] `);
+        return /^y(es)?$/i.test(answer.trim());
+    }
+    finally {
+        rl.close();
+    }
+};

package/dist/output.d.ts

@@ -0,0 +1,14 @@
+import type { Theme } from './theme.js';
+/**
+ * A small, honest status vocabulary shared by every command. `unknown` exists
+ * so a check that cannot be determined is never reported as success.
+ */
+export declare const STATUSES: readonly ["ok", "fail", "caution", "unknown"];
+export type Status = (typeof STATUSES)[number];
+export interface Output {
+    line(text?: string): void;
+    status(status: Status, label?: string): void;
+    row(name: string, detail: string, status: Status): void;
+    detail(text: string): void;
+}
+export declare const createOutput: (theme: Theme, stream?: NodeJS.WriteStream) => Output;

package/dist/output.js

@@ -0,0 +1,37 @@
+import { renderTerminalText } from './io.js';
+/**
+ * A small, honest status vocabulary shared by every command. `unknown` exists
+ * so a check that cannot be determined is never reported as success.
+ */
+export const STATUSES = ['ok', 'fail', 'caution', 'unknown'];
+const LABELS = {
+    ok: 'ok',
+    fail: 'fail',
+    caution: 'caution',
+    unknown: 'unknown',
+};
+export const createOutput = (theme, stream = process.stdout) => {
+    const write = (text) => {
+        stream.write(`${renderTerminalText(text)}\n`);
+    };
+    const paint = (status, label) => {
+        switch (status) {
+            case 'ok':
+                return theme.green(label);
+            case 'fail':
+                return theme.red(label);
+            case 'caution':
+                return theme.yellow(label);
+            case 'unknown':
+                return theme.grey(label);
+        }
+    };
+    return {
+        line: (text = '') => write(text),
+        status: (status, label = LABELS[status]) => write(paint(status, label)),
+        row: (name, detail, status) => {
+            write(`${theme.bold(name)}\n  ${theme.dim(detail)}  ${paint(status, LABELS[status])}`);
+        },
+        detail: (text) => write(`  ${theme.dim(`↳ ${text}`)}`),
+    };
+};