@portaidentity/cli 0.1.0

package/dist/error-handler.js

@@ -0,0 +1,166 @@
+/**
+ * CLI error handler — maps SDK errors to user-friendly output.
+ *
+ * Wraps command handlers with a try/catch that translates the SDK
+ * error hierarchy into appropriate CLI output and exit codes:
+ *
+ * | Exit Code | Meaning             | SDK Error Class          |
+ * |-----------|---------------------|--------------------------|
+ * | 0         | Success             | —                        |
+ * | 1         | General error       | PortaError, unknown      |
+ * | 2         | Authentication error| PortaAuthenticationError |
+ * | 3         | Validation error    | PortaValidationError     |
+ *
+ * In verbose mode (`--verbose`), the full error stack trace and
+ * response body are printed. In normal mode, only the user-friendly
+ * message is shown.
+ *
+ * @module error-handler
+ */
+import { PortaError, PortaHttpError, PortaAuthenticationError, PortaValidationError, PortaForbiddenError, PortaNotFoundError, PortaConflictError, PortaRateLimitError, PortaServerError, } from '@portaidentity/sdk';
+import { error as printError } from './output.js';
+// ---------------------------------------------------------------------------
+// Exit Codes
+// ---------------------------------------------------------------------------
+/** CLI exit codes per AR #99 */
+export const EXIT_SUCCESS = 0;
+export const EXIT_GENERAL_ERROR = 1;
+export const EXIT_AUTH_ERROR = 2;
+export const EXIT_VALIDATION_ERROR = 3;
+// ---------------------------------------------------------------------------
+// Error Handler
+// ---------------------------------------------------------------------------
+/**
+ * Wraps a command handler function with error handling.
+ *
+ * Catches SDK errors and translates them to user-friendly output
+ * with appropriate exit codes. This is the primary error boundary
+ * for all CLI commands.
+ *
+ * @param fn - The async command handler to wrap
+ * @param verbose - Whether to show detailed error output
+ * @returns A wrapped function that handles errors gracefully
+ */
+export function withErrorHandling(fn, verbose = false) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (err) {
+            handleError(err, verbose);
+        }
+    };
+}
+/**
+ * Handles an error by printing a user-friendly message and exiting.
+ *
+ * Maps SDK error types to specific messages and exit codes.
+ * In verbose mode, includes the full stack trace and response body.
+ *
+ * @param err - The caught error
+ * @param verbose - Whether to show detailed output
+ */
+export function handleError(err, verbose = false) {
+    // --- SDK Validation Error (400) ---
+    if (err instanceof PortaValidationError) {
+        printError(`Validation failed: ${err.message}`);
+        if (err.details.length > 0) {
+            for (const detail of err.details) {
+                printError(`  ${detail.path}: ${detail.message}`);
+            }
+        }
+        if (verbose)
+            printVerboseDetails(err);
+        process.exit(EXIT_VALIDATION_ERROR);
+    }
+    // --- SDK Authentication Error (401) ---
+    if (err instanceof PortaAuthenticationError) {
+        printError(`Authentication failed: ${err.message}`);
+        printError('Run "porta login" to authenticate.');
+        if (verbose)
+            printVerboseDetails(err);
+        process.exit(EXIT_AUTH_ERROR);
+    }
+    // --- SDK Forbidden Error (403) ---
+    if (err instanceof PortaForbiddenError) {
+        printError(`Access denied: ${err.message}`);
+        printError('You do not have the required permissions for this operation.');
+        if (verbose)
+            printVerboseDetails(err);
+        process.exit(EXIT_AUTH_ERROR);
+    }
+    // --- SDK Not Found Error (404) ---
+    if (err instanceof PortaNotFoundError) {
+        printError(`Not found: ${err.message}`);
+        if (verbose)
+            printVerboseDetails(err);
+        process.exit(EXIT_GENERAL_ERROR);
+    }
+    // --- SDK Conflict Error (409) ---
+    if (err instanceof PortaConflictError) {
+        printError(`Conflict: ${err.message}`);
+        if (verbose)
+            printVerboseDetails(err);
+        process.exit(EXIT_GENERAL_ERROR);
+    }
+    // --- SDK Rate Limit Error (429) ---
+    if (err instanceof PortaRateLimitError) {
+        const retryMsg = err.retryAfter ? ` Retry after ${err.retryAfter}s.` : '';
+        printError(`Rate limit exceeded: ${err.message}${retryMsg}`);
+        if (verbose)
+            printVerboseDetails(err);
+        process.exit(EXIT_GENERAL_ERROR);
+    }
+    // --- SDK Server Error (5xx) ---
+    if (err instanceof PortaServerError) {
+        printError(`Server error (${err.status}): ${err.message}`);
+        if (verbose)
+            printVerboseDetails(err);
+        process.exit(EXIT_GENERAL_ERROR);
+    }
+    // --- Generic SDK HTTP Error ---
+    if (err instanceof PortaHttpError) {
+        printError(`HTTP ${err.status}: ${err.message}`);
+        if (verbose)
+            printVerboseDetails(err);
+        process.exit(EXIT_GENERAL_ERROR);
+    }
+    // --- Generic SDK Error ---
+    if (err instanceof PortaError) {
+        printError(err.message);
+        if (verbose && err.stack) {
+            console.error('\n' + err.stack);
+        }
+        process.exit(EXIT_GENERAL_ERROR);
+    }
+    // --- Standard Error ---
+    if (err instanceof Error) {
+        printError(err.message);
+        if (verbose && err.stack) {
+            console.error('\n' + err.stack);
+        }
+        process.exit(EXIT_GENERAL_ERROR);
+    }
+    // --- Unknown error ---
+    printError(`An unexpected error occurred: ${String(err)}`);
+    process.exit(EXIT_GENERAL_ERROR);
+}
+// ---------------------------------------------------------------------------
+// Internal Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Prints verbose error details (stack trace and response body).
+ *
+ * @param err - The HTTP error with additional details
+ */
+function printVerboseDetails(err) {
+    if (err.stack) {
+        console.error('\nStack trace:');
+        console.error(err.stack);
+    }
+    if (err.body) {
+        console.error('\nResponse body:');
+        console.error(JSON.stringify(err.body, null, 2));
+    }
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/error-handler.js.map

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

package/dist/global-options.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Global CLI options and server URL resolution.
+ *
+ * Defines the `GlobalOptions` interface shared across all commands,
+ * and the `resolveServerUrl()` function that determines the Porta
+ * server URL using a priority chain:
+ *
+ *   1. `--server` flag (highest priority)
+ *   2. `PORTA_SERVER` environment variable
+ *   3. Server URL from stored credentials file
+ *   4. Error — no server configured
+ *
+ * This resolution chain lets users configure once via `porta login`
+ * and override per-command via flag or env var.
+ *
+ * @module global-options
+ */
+/**
+ * Global options available to all CLI commands.
+ *
+ * These are parsed by yargs from the command line and passed
+ * through to command handlers.
+ */
+export interface GlobalOptions {
+    /** Porta server URL override (e.g., https://porta.example.com) */
+    server?: string;
+    /** Output in JSON format instead of table */
+    json: boolean;
+    /** Show verbose output including stack traces on error */
+    verbose: boolean;
+    /** Skip TLS certificate verification (for self-signed certs) */
+    insecure: boolean;
+    /** Skip confirmation prompts for destructive operations */
+    force: boolean;
+}
+/**
+ * Resolves the Porta server URL using the priority chain.
+ *
+ * Resolution order:
+ *   1. `--server` CLI flag
+ *   2. `PORTA_SERVER` environment variable
+ *   3. Server URL from stored credentials (`~/.porta/credentials.json`)
+ *   4. Throws an error if no server URL is found
+ *
+ * @param options - Global CLI options (may contain `server` flag)
+ * @returns The resolved server URL
+ * @throws Error if no server URL can be determined
+ */
+export declare function resolveServerUrl(options: GlobalOptions): string;
+//# sourceMappingURL=global-options.d.ts.map

package/dist/global-options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-options.d.ts","sourceRoot":"","sources":["../src/global-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,kEAAkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,IAAI,EAAE,OAAO,CAAC;IACd,0DAA0D;IAC1D,OAAO,EAAE,OAAO,CAAC;IACjB,gEAAgE;IAChE,QAAQ,EAAE,OAAO,CAAC;IAClB,2DAA2D;IAC3D,KAAK,EAAE,OAAO,CAAC;CAChB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAsB/D"}

package/dist/global-options.js

@@ -0,0 +1,62 @@
+/**
+ * Global CLI options and server URL resolution.
+ *
+ * Defines the `GlobalOptions` interface shared across all commands,
+ * and the `resolveServerUrl()` function that determines the Porta
+ * server URL using a priority chain:
+ *
+ *   1. `--server` flag (highest priority)
+ *   2. `PORTA_SERVER` environment variable
+ *   3. Server URL from stored credentials file
+ *   4. Error — no server configured
+ *
+ * This resolution chain lets users configure once via `porta login`
+ * and override per-command via flag or env var.
+ *
+ * @module global-options
+ */
+import { loadCredentials } from './credential-store.js';
+// ---------------------------------------------------------------------------
+// Server URL Resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolves the Porta server URL using the priority chain.
+ *
+ * Resolution order:
+ *   1. `--server` CLI flag
+ *   2. `PORTA_SERVER` environment variable
+ *   3. Server URL from stored credentials (`~/.porta/credentials.json`)
+ *   4. Throws an error if no server URL is found
+ *
+ * @param options - Global CLI options (may contain `server` flag)
+ * @returns The resolved server URL
+ * @throws Error if no server URL can be determined
+ */
+export function resolveServerUrl(options) {
+    // Priority 1: --server flag
+    if (options.server) {
+        return normalizeUrl(options.server);
+    }
+    // Priority 2: PORTA_SERVER environment variable
+    const envUrl = process.env.PORTA_SERVER;
+    if (envUrl) {
+        return normalizeUrl(envUrl);
+    }
+    // Priority 3: Credentials file
+    const credentials = loadCredentials();
+    if (credentials?.server) {
+        return normalizeUrl(credentials.server);
+    }
+    // Priority 4: No server configured
+    throw new Error('No Porta server configured. Use --server, set PORTA_SERVER, or run "porta login" first.');
+}
+/**
+ * Normalizes a URL by removing trailing slashes.
+ *
+ * @param url - The URL to normalize
+ * @returns URL without trailing slash
+ */
+function normalizeUrl(url) {
+    return url.replace(/\/+$/, '');
+}
+//# sourceMappingURL=global-options.js.map

package/dist/global-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"global-options.js","sourceRoot":"","sources":["../src/global-options.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAyBxD,8EAA8E;AAC9E,wBAAwB;AACxB,8EAA8E;AAE9E;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAsB;IACrD,4BAA4B;IAC5B,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,OAAO,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,CAAC;IAED,gDAAgD;IAChD,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IACxC,IAAI,MAAM,EAAE,CAAC;QACX,OAAO,YAAY,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAED,+BAA+B;IAC/B,MAAM,WAAW,GAAG,eAAe,EAAE,CAAC;IACtC,IAAI,WAAW,EAAE,MAAM,EAAE,CAAC;QACxB,OAAO,YAAY,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,CAAC;IAED,mCAAmC;IACnC,MAAM,IAAI,KAAK,CACb,yFAAyF,CAC1F,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,YAAY,CAAC,GAAW;IAC/B,OAAO,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+/**
+ * Porta CLI entry point.
+ *
+ * Sets up yargs with global options and registers all command modules.
+ * This is the standalone CLI package — commands use the SDK for all
+ * API communication rather than direct HTTP or database access.
+ *
+ * Usage: porta <command> <subcommand> [options]
+ *
+ * Global options:
+ *   --server     Porta server URL (overrides PORTA_SERVER env and credentials)
+ *   --json       Output in JSON format (default: table)
+ *   --verbose    Show detailed output including stack traces on error
+ *   --insecure   Skip TLS certificate verification (self-signed certs)
+ *   --force      Skip confirmation prompts for destructive operations
+ *
+ * Bootstrap commands (no auth required):
+ *   login        Authenticate with a Porta server via OIDC browser flow
+ *   logout       Clear stored authentication tokens
+ *   whoami       Show current authenticated identity
+ *   version      Show CLI, SDK, and server version information
+ *   doctor       Run diagnostic checks on CLI configuration
+ *   completion   Generate shell completion script
+ *
+ * @module index
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}

package/dist/index.js

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+/**
+ * Porta CLI entry point.
+ *
+ * Sets up yargs with global options and registers all command modules.
+ * This is the standalone CLI package — commands use the SDK for all
+ * API communication rather than direct HTTP or database access.
+ *
+ * Usage: porta <command> <subcommand> [options]
+ *
+ * Global options:
+ *   --server     Porta server URL (overrides PORTA_SERVER env and credentials)
+ *   --json       Output in JSON format (default: table)
+ *   --verbose    Show detailed output including stack traces on error
+ *   --insecure   Skip TLS certificate verification (self-signed certs)
+ *   --force      Skip confirmation prompts for destructive operations
+ *
+ * Bootstrap commands (no auth required):
+ *   login        Authenticate with a Porta server via OIDC browser flow
+ *   logout       Clear stored authentication tokens
+ *   whoami       Show current authenticated identity
+ *   version      Show CLI, SDK, and server version information
+ *   doctor       Run diagnostic checks on CLI configuration
+ *   completion   Generate shell completion script
+ *
+ * @module index
+ */
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { loginCommand } from './commands/login.js';
+import { logoutCommand } from './commands/logout.js';
+import { whoamiCommand } from './commands/whoami.js';
+import { versionCommand } from './commands/version.js';
+import { doctorCommand } from './commands/doctor.js';
+import { completionCommand } from './commands/completion.js';
+import { orgCommand } from './commands/org.js';
+import { appCommand } from './commands/app.js';
+import { clientCommand } from './commands/client.js';
+import { userCommand } from './commands/user.js';
+import { keysCommand } from './commands/keys.js';
+import { configCommand } from './commands/config.js';
+import { auditCommand } from './commands/audit.js';
+import { provisionCommand } from './commands/provision.js';
+import { healthCommand } from './commands/health.js';
+import { sessionsCommand } from './commands/sessions.js';
+import { bulkCommand } from './commands/bulk.js';
+import { statsCommand } from './commands/stats.js';
+import { exportsCommand } from './commands/exports.js';
+/**
+ * Builds and runs the CLI.
+ *
+ * Configures yargs with global options, registers all command modules,
+ * and parses the command line arguments.
+ */
+async function main() {
+    await yargs(hideBin(process.argv))
+        .scriptName('porta')
+        .usage('$0 <command> [options]')
+        .option('server', {
+        type: 'string',
+        describe: 'Porta server URL',
+        global: true,
+    })
+        .option('json', {
+        type: 'boolean',
+        default: false,
+        describe: 'Output in JSON format',
+        global: true,
+    })
+        .option('verbose', {
+        type: 'boolean',
+        default: false,
+        describe: 'Show detailed output',
+        global: true,
+    })
+        .option('insecure', {
+        type: 'boolean',
+        default: false,
+        describe: 'Skip TLS certificate verification',
+        global: true,
+    })
+        .option('force', {
+        type: 'boolean',
+        default: false,
+        describe: 'Skip confirmation prompts',
+        global: true,
+    })
+        // Bootstrap commands (no auth required)
+        .command(loginCommand)
+        .command(logoutCommand)
+        .command(whoamiCommand)
+        .command(versionCommand)
+        .command(doctorCommand)
+        .command(completionCommand)
+        // Domain commands (auth required)
+        .command(orgCommand)
+        .command(appCommand)
+        .command(clientCommand)
+        .command(userCommand)
+        // Infrastructure commands (auth required)
+        .command(keysCommand)
+        .command(configCommand)
+        .command(auditCommand)
+        .command(sessionsCommand)
+        .command(statsCommand)
+        .command(bulkCommand)
+        .command(exportsCommand)
+        .command(provisionCommand)
+        // Unauthenticated commands
+        .command(healthCommand)
+        .demandCommand(1, 'Please specify a command')
+        .strict()
+        .help()
+        .version(false) // Disable default --version; we use a custom version command
+        .completion('completion', false) // Enable yargs completion but hide from help (we have our own command)
+        .parse();
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/output.d.ts

@@ -0,0 +1,75 @@
+/**
+ * CLI output helpers.
+ *
+ * Provides table and JSON formatters, color helpers, and common display
+ * utilities. All commands use these helpers for consistent output across
+ * the CLI.
+ *
+ * Table output uses cli-table3 with bold headers.
+ * JSON output uses formatted (2-space indent) JSON to stdout.
+ * Color helpers use chalk for success/warning/error messages.
+ *
+ * @module output
+ */
+/**
+ * Formats data as a table and prints to stdout.
+ *
+ * Creates a cli-table3 instance with bold headers and prints each row.
+ * Used by list and show commands for human-readable output.
+ *
+ * @param headers - Column header labels (will be bold)
+ * @param rows - Array of row data (each row is an array of cell strings)
+ */
+export declare function printTable(headers: string[], rows: string[][]): void;
+/**
+ * Prints data as formatted JSON to stdout.
+ *
+ * Outputs a 2-space-indented JSON string. Used when `--json` flag is set,
+ * enabling machine-readable output for scripting and piping.
+ *
+ * @param data - Any JSON-serializable value
+ */
+export declare function printJson(data: unknown): void;
+/**
+ * Prints a success message in green.
+ *
+ * @param message - The success message
+ */
+export declare function success(message: string): void;
+/**
+ * Prints a warning message in yellow to stderr.
+ *
+ * @param message - The warning message
+ */
+export declare function warn(message: string): void;
+/**
+ * Prints an error message in red to stderr.
+ *
+ * @param message - The error message
+ */
+export declare function error(message: string): void;
+/**
+ * Prints an info message in blue.
+ *
+ * @param message - The info message
+ */
+export declare function info(message: string): void;
+/**
+ * Formats a date string or Date object for display.
+ *
+ * Returns 'N/A' for null/undefined values.
+ * Uses ISO 8601 format with local timezone.
+ *
+ * @param date - Date string, Date object, or null/undefined
+ * @returns Formatted date string or 'N/A'
+ */
+export declare function formatDate(date: string | Date | null | undefined): string;
+/**
+ * Truncates a string to a maximum length with ellipsis.
+ *
+ * @param str - The string to truncate
+ * @param maxLen - Maximum length (default: 40)
+ * @returns Truncated string with '...' if needed
+ */
+export declare function truncate(str: string, maxLen?: number): string;
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI,CAIpE;AAED;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE7C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE3C;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAE1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAIzE;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,SAAK,GAAG,MAAM,CAGzD"}

package/dist/output.js

@@ -0,0 +1,100 @@
+/**
+ * CLI output helpers.
+ *
+ * Provides table and JSON formatters, color helpers, and common display
+ * utilities. All commands use these helpers for consistent output across
+ * the CLI.
+ *
+ * Table output uses cli-table3 with bold headers.
+ * JSON output uses formatted (2-space indent) JSON to stdout.
+ * Color helpers use chalk for success/warning/error messages.
+ *
+ * @module output
+ */
+import Table from 'cli-table3';
+import chalk from 'chalk';
+/**
+ * Formats data as a table and prints to stdout.
+ *
+ * Creates a cli-table3 instance with bold headers and prints each row.
+ * Used by list and show commands for human-readable output.
+ *
+ * @param headers - Column header labels (will be bold)
+ * @param rows - Array of row data (each row is an array of cell strings)
+ */
+export function printTable(headers, rows) {
+    const table = new Table({ head: headers.map((h) => chalk.bold(h)) });
+    rows.forEach((row) => table.push(row));
+    console.log(table.toString());
+}
+/**
+ * Prints data as formatted JSON to stdout.
+ *
+ * Outputs a 2-space-indented JSON string. Used when `--json` flag is set,
+ * enabling machine-readable output for scripting and piping.
+ *
+ * @param data - Any JSON-serializable value
+ */
+export function printJson(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+/**
+ * Prints a success message in green.
+ *
+ * @param message - The success message
+ */
+export function success(message) {
+    console.log(chalk.green(`✓ ${message}`));
+}
+/**
+ * Prints a warning message in yellow to stderr.
+ *
+ * @param message - The warning message
+ */
+export function warn(message) {
+    console.error(chalk.yellow(`⚠ ${message}`));
+}
+/**
+ * Prints an error message in red to stderr.
+ *
+ * @param message - The error message
+ */
+export function error(message) {
+    console.error(chalk.red(`✗ ${message}`));
+}
+/**
+ * Prints an info message in blue.
+ *
+ * @param message - The info message
+ */
+export function info(message) {
+    console.log(chalk.blue(`ℹ ${message}`));
+}
+/**
+ * Formats a date string or Date object for display.
+ *
+ * Returns 'N/A' for null/undefined values.
+ * Uses ISO 8601 format with local timezone.
+ *
+ * @param date - Date string, Date object, or null/undefined
+ * @returns Formatted date string or 'N/A'
+ */
+export function formatDate(date) {
+    if (!date)
+        return 'N/A';
+    const d = typeof date === 'string' ? new Date(date) : date;
+    return d.toLocaleString();
+}
+/**
+ * Truncates a string to a maximum length with ellipsis.
+ *
+ * @param str - The string to truncate
+ * @param maxLen - Maximum length (default: 40)
+ * @returns Truncated string with '...' if needed
+ */
+export function truncate(str, maxLen = 40) {
+    if (str.length <= maxLen)
+        return str;
+    return str.slice(0, maxLen - 3) + '...';
+}
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,MAAM,YAAY,CAAC;AAC/B,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,OAAiB,EAAE,IAAgB;IAC5D,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IACrE,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACvC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;AAChC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,IAAa;IACrC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AAC7C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,OAAe;IAClC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,KAAK,CAAC,OAAe;IACnC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC;AAC3C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,IAAI,CAAC,OAAe;IAClC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,IAAsC;IAC/D,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,MAAM,CAAC,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC3D,OAAO,CAAC,CAAC,cAAc,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,QAAQ,CAAC,GAAW,EAAE,MAAM,GAAG,EAAE;IAC/C,IAAI,GAAG,CAAC,MAAM,IAAI,MAAM;QAAE,OAAO,GAAG,CAAC;IACrC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,KAAK,CAAC;AAC1C,CAAC"}