@pokit/reporter-clack 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Daniel Grant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# @pokit/reporter-clack
+
+Terminal output adapter for pok using [Clack](https://github.com/natemoo-re/clack).
+
+## Installation
+
+```bash
+bun add @pokit/reporter-clack
+```
+
+## Usage
+
+```typescript
+import { run } from '@pokit/core';
+import { createReporterAdapter } from '@pokit/reporter-clack';
+
+await run(args, {
+  reporterAdapter: createReporterAdapter(),
+  // ...
+});
+```
+
+## Features
+
+- Styled log messages (info, success, warn, error)
+- Progress spinners
+- Grouped output with collapsible sections
+- Activity indicators
+- Unicode and ASCII symbol sets
+
+## Options
+
+```typescript
+createReporterAdapter({
+  plain: false, // Disable colors and spinners
+});
+```
+
+## Exports
+
+```typescript
+// Main adapter
+import { createReporterAdapter } from '@pokit/reporter-clack';
+
+// Symbol customization
+import { getSymbols, UNICODE_SYMBOLS, ASCII_SYMBOLS } from '@pokit/reporter-clack';
+```
+
+## Documentation
+
+See the [full documentation](https://github.com/openpok/pok/blob/main/docs/packages/reporter-clack.md).

package/dist/adapter.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Clack Reporter Adapter
+ *
+ * Implements the ReporterAdapter interface using @clack/prompts.
+ * Consumes CLI events from the EventBus and renders them to the terminal.
+ *
+ * Design principles:
+ * - Groups are visual containers with a bold title (intro) and completion indicator (outro)
+ * - Activities within sequential groups show as spinner items that complete with checkmarks
+ * - Parallel groups use a single spinner that tracks progress, showing completions as they finish
+ * - Logs during an active spinner will pause the spinner, show the log, then resume
+ * - Process output is never interleaved with spinners
+ *
+ * Rendering strategy:
+ * - group:start -> p.intro() with bold label (or plain text in plain mode)
+ * - group:end -> p.outro() with success indicator
+ * - activity:start (sequential) -> spinner.start() (or plain text indicator)
+ * - activity:start (parallel) -> track activity, update combined spinner
+ * - activity:success -> spinner.stop() with checkmark (code 0) or update combined spinner
+ * - activity:failure -> spinner.stop() with X (code 1)
+ * - activity:update -> spinner.message()
+ * - log -> pause spinner if active, p.log.*, resume spinner
+ *
+ * Plain mode (--plain or CI environment):
+ * - When unicode is disabled, uses ASCII symbols and bypasses clack's decorative output
+ * - When color is disabled (--no-color or NO_COLOR env), strips ANSI color codes
+ */
+import type { ReporterAdapter, OutputConfig } from '@pokit/core';
+/**
+ * Options for the reporter adapter
+ */
+export type ReporterAdapterOptions = {
+    /** When true, logs are displayed immediately instead of being buffered during spinners */
+    verbose?: boolean;
+    /** Output configuration (color, unicode, verbose settings) */
+    output?: OutputConfig;
+};
+/**
+ * Create a Clack-based ReporterAdapter
+ *
+ * @param options - Optional configuration for the adapter
+ */
+export declare function createReporterAdapter(options?: ReporterAdapterOptions): ReporterAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAIH,OAAO,KAAK,EACV,eAAe,EAQf,YAAY,EACb,MAAM,aAAa,CAAC;AA+MrB;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,0FAA0F;IAC1F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,sBAAsB,GAAG,eAAe,CA0iBvF"}

package/dist/adapter.js

@@ -0,0 +1,666 @@
+/**
+ * Clack Reporter Adapter
+ *
+ * Implements the ReporterAdapter interface using @clack/prompts.
+ * Consumes CLI events from the EventBus and renders them to the terminal.
+ *
+ * Design principles:
+ * - Groups are visual containers with a bold title (intro) and completion indicator (outro)
+ * - Activities within sequential groups show as spinner items that complete with checkmarks
+ * - Parallel groups use a single spinner that tracks progress, showing completions as they finish
+ * - Logs during an active spinner will pause the spinner, show the log, then resume
+ * - Process output is never interleaved with spinners
+ *
+ * Rendering strategy:
+ * - group:start -> p.intro() with bold label (or plain text in plain mode)
+ * - group:end -> p.outro() with success indicator
+ * - activity:start (sequential) -> spinner.start() (or plain text indicator)
+ * - activity:start (parallel) -> track activity, update combined spinner
+ * - activity:success -> spinner.stop() with checkmark (code 0) or update combined spinner
+ * - activity:failure -> spinner.stop() with X (code 1)
+ * - activity:update -> spinner.message()
+ * - log -> pause spinner if active, p.log.*, resume spinner
+ *
+ * Plain mode (--plain or CI environment):
+ * - When unicode is disabled, uses ASCII symbols and bypasses clack's decorative output
+ * - When color is disabled (--no-color or NO_COLOR env), strips ANSI color codes
+ */
+import * as p from '@clack/prompts';
+import pc from 'picocolors';
+import { CommandError } from '@pokit/core';
+/**
+ * Extract error message and optional output from an error.
+ * If the error is a CommandError with output, includes that in the message.
+ */
+function formatErrorMessage(error) {
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error instanceof CommandError && error.output) {
+        return `${error.message}\n\n${error.output}`;
+    }
+    return error.message;
+}
+import { getSymbols } from './symbols';
+/**
+ * Helper to conditionally apply color.
+ * In no-color mode, returns text unchanged.
+ */
+function colorize(text, colorFn, useColor) {
+    return useColor ? colorFn(text) : text;
+}
+/**
+ * Write a line to stdout.
+ * Uses process.stdout.write to ensure proper capture in all environments.
+ * (Bun's console.log may not be captured by stdout interception)
+ */
+function writeLine(line) {
+    process.stdout.write(line + '\n');
+}
+/** Maximum number of logs to buffer per activity to prevent memory issues */
+const MAX_BUFFERED_LOGS_PER_ACTIVITY = 100;
+/**
+ * Update the parallel spinner message based on current activity states
+ */
+function updateParallelSpinnerMessage(state) {
+    if (!state.parallelSpinner)
+        return;
+    const activities = Array.from(state.parallelActivities.values()).filter((a) => a.groupId === state.parallelSpinnerGroupId);
+    const pending = activities.filter((a) => a.status === 'pending');
+    const completed = activities.filter((a) => a.status !== 'pending');
+    if (pending.length === 0) {
+        // All done - this will be cleaned up by group:end
+        return;
+    }
+    const message = pending.length === 1
+        ? pending[0].label
+        : `Running ${pending.length} tasks (${completed.length}/${activities.length} done)`;
+    state.parallelSpinner.currentMessage = message;
+    state.parallelSpinner.spinner.message(message);
+}
+/**
+ * Display a log message.
+ * Uses clack's log functions in unicode mode, plain console.log in plain mode.
+ *
+ * @param level - The log level
+ * @param message - The message to display
+ * @param state - The adapter state (for output config)
+ * @param indented - Whether to indent the log (for buffered logs inside activity context)
+ */
+function displayLog(level, message, state, indented = false) {
+    const { outputConfig, symbols } = state;
+    // In plain mode (no unicode), use simple console output
+    if (!outputConfig.unicode) {
+        const prefix = indented ? `${symbols.groupLine}  ` : '';
+        const levelPrefix = {
+            info: symbols.info,
+            warn: symbols.warning,
+            error: symbols.error,
+            success: symbols.success,
+            step: symbols.step,
+        }[level];
+        writeLine(`${prefix}${levelPrefix} ${message}`);
+        return;
+    }
+    // Unicode mode - use clack's decorative output
+    const prefix = indented ? '\u2502  ' : ''; // │  for indented logs
+    const formattedMessage = prefix + message;
+    switch (level) {
+        case 'info':
+            p.log.info(formattedMessage);
+            break;
+        case 'warn':
+            p.log.warn(formattedMessage);
+            break;
+        case 'error':
+            p.log.error(formattedMessage);
+            break;
+        case 'success':
+            p.log.success(formattedMessage);
+            break;
+        case 'step':
+            p.log.step(formattedMessage);
+            break;
+    }
+}
+/**
+ * Flush buffered logs for a specific activity.
+ *
+ * @param state - The adapter state
+ * @param activityId - The activity ID whose logs should be flushed
+ */
+function flushLogsForActivity(state, activityId) {
+    // Filter logs for this activity, sorted by timestamp
+    const activityLogs = state.bufferedLogs
+        .filter((log) => log.activityId === activityId)
+        .sort((a, b) => a.timestamp - b.timestamp);
+    // Display each buffered log with indentation
+    for (const log of activityLogs) {
+        displayLog(log.level, log.message, state, true);
+    }
+    // Remove flushed logs from buffer
+    state.bufferedLogs = state.bufferedLogs.filter((log) => log.activityId !== activityId);
+}
+/**
+ * Create a Clack-based ReporterAdapter
+ *
+ * @param options - Optional configuration for the adapter
+ */
+export function createReporterAdapter(options) {
+    // Get output config from options, or use defaults
+    const outputConfig = options?.output ?? {
+        color: true,
+        unicode: true,
+        verbose: options?.verbose ?? false,
+    };
+    // Verbose can be set via options.verbose for backwards compatibility
+    if (options?.verbose !== undefined) {
+        outputConfig.verbose = options.verbose;
+    }
+    const symbols = getSymbols(outputConfig);
+    return {
+        start(bus) {
+            const state = {
+                spinners: new Map(),
+                groups: new Map(),
+                parallelActivities: new Map(),
+                parallelSpinner: null,
+                parallelSpinnerGroupId: null,
+                suspended: false,
+                suspendedActivities: new Map(),
+                bufferedLogs: [],
+                verbose: outputConfig.verbose,
+                outputConfig,
+                symbols,
+            };
+            const handleEvent = (event) => {
+                switch (event.type) {
+                    // Root lifecycle (app-level intro/outro)
+                    case 'root:start':
+                    case 'root:end':
+                        // Handled by the router
+                        break;
+                    // Group lifecycle (command-level intro/outro)
+                    case 'group:start': {
+                        if (state.suspended)
+                            break;
+                        state.groups.set(event.id, {
+                            label: event.label,
+                            layout: event.layout,
+                            hasFailure: false,
+                        });
+                        // In plain mode, use simple bracket notation
+                        if (!state.outputConfig.unicode) {
+                            const label = colorize(event.label, pc.bold, state.outputConfig.color);
+                            writeLine(`${state.symbols.groupStart}${label}${state.symbols.groupEnd}`);
+                        }
+                        else {
+                            p.intro(colorize(event.label, pc.bold, state.outputConfig.color));
+                        }
+                        break;
+                    }
+                    case 'group:end': {
+                        if (state.suspended)
+                            break;
+                        const group = state.groups.get(event.id);
+                        state.groups.delete(event.id);
+                        let hasFailures = group?.hasFailure ?? false;
+                        const deferredErrors = [];
+                        // If this was a parallel group, show completion results and clean up
+                        if (group?.layout === 'parallel') {
+                            // Collect activities for this group
+                            const activities = Array.from(state.parallelActivities.entries()).filter(([, a]) => a.groupId === event.id);
+                            // Sort: successes first, then failures (so failures are more visible at end)
+                            const sorted = activities.sort(([, a], [, b]) => {
+                                if (a.status === 'success' && b.status !== 'success')
+                                    return -1;
+                                if (a.status !== 'success' && b.status === 'success')
+                                    return 1;
+                                return 0;
+                            });
+                            // Stop the parallel spinner - use first success as the message
+                            if (state.parallelSpinner && state.parallelSpinnerGroupId === event.id) {
+                                const firstSuccess = sorted.find(([, a]) => a.status === 'success');
+                                if (firstSuccess) {
+                                    // Show first success via spinner stop
+                                    state.parallelSpinner.spinner.stop(firstSuccess[1].label, 0);
+                                    // Flush buffered logs for this activity
+                                    flushLogsForActivity(state, firstSuccess[0]);
+                                    state.parallelActivities.delete(firstSuccess[0]);
+                                }
+                                else {
+                                    // All failed - show first failure label (not error) via spinner stop
+                                    const firstFailure = sorted[0];
+                                    if (firstFailure) {
+                                        state.parallelSpinner.spinner.stop(firstFailure[1].label, 1);
+                                        hasFailures = true;
+                                        // Defer the error message with remediation to print after outro
+                                        if (firstFailure[1].error) {
+                                            deferredErrors.push({
+                                                error: firstFailure[1].error,
+                                                remediation: firstFailure[1].remediation,
+                                                documentationUrl: firstFailure[1].documentationUrl,
+                                            });
+                                        }
+                                        // Flush buffered logs for this activity
+                                        flushLogsForActivity(state, firstFailure[0]);
+                                        state.parallelActivities.delete(firstFailure[0]);
+                                    }
+                                    else {
+                                        state.parallelSpinner.spinner.stop('Complete', 0);
+                                    }
+                                }
+                                state.parallelSpinner = null;
+                                state.parallelSpinnerGroupId = null;
+                            }
+                            // Show remaining results (only labels inside group, defer errors)
+                            for (const [activityId, activity] of state.parallelActivities) {
+                                if (activity.groupId !== event.id)
+                                    continue;
+                                if (activity.status === 'success') {
+                                    if (!state.outputConfig.unicode) {
+                                        const prefix = colorize(state.symbols.success, pc.green, state.outputConfig.color);
+                                        writeLine(`  ${prefix} ${activity.label}`);
+                                    }
+                                    else {
+                                        p.log.success(activity.label);
+                                    }
+                                }
+                                else if (activity.status === 'failure') {
+                                    hasFailures = true;
+                                    // Show label inside group, defer error message with remediation
+                                    if (!state.outputConfig.unicode) {
+                                        const prefix = colorize(state.symbols.error, pc.red, state.outputConfig.color);
+                                        writeLine(`  ${prefix} ${activity.label}`);
+                                    }
+                                    else {
+                                        p.log.error(activity.label);
+                                    }
+                                    if (activity.error) {
+                                        deferredErrors.push({
+                                            error: activity.error,
+                                            remediation: activity.remediation,
+                                            documentationUrl: activity.documentationUrl,
+                                        });
+                                    }
+                                }
+                                // Flush any buffered logs for this parallel activity
+                                flushLogsForActivity(state, activityId);
+                            }
+                            // Clean up all activities for this group
+                            for (const [id, activity] of [...state.parallelActivities]) {
+                                if (activity.groupId === event.id) {
+                                    state.parallelActivities.delete(id);
+                                }
+                            }
+                        }
+                        // Show appropriate outro based on whether there were failures
+                        if (!state.outputConfig.unicode) {
+                            // Plain mode - simple bracket notation
+                            if (hasFailures) {
+                                const failedText = colorize(state.symbols.failed, pc.red, state.outputConfig.color);
+                                writeLine(`${state.symbols.groupStart}${failedText}${state.symbols.groupEnd}`);
+                            }
+                            else {
+                                const doneText = colorize(state.symbols.done, pc.green, state.outputConfig.color);
+                                writeLine(`${state.symbols.groupStart}${doneText}${state.symbols.groupEnd}`);
+                            }
+                        }
+                        else {
+                            // Unicode mode - use clack's outro
+                            if (hasFailures) {
+                                p.outro(colorize(`${state.symbols.failed} Failed`, pc.red, state.outputConfig.color));
+                            }
+                            else {
+                                p.outro(colorize(`${state.symbols.done} Done`, pc.green, state.outputConfig.color));
+                            }
+                        }
+                        // Print deferred error messages with remediation after the group closes
+                        for (const deferred of deferredErrors) {
+                            if (!state.outputConfig.unicode) {
+                                writeLine(`${state.symbols.error} ${deferred.error}`);
+                            }
+                            else {
+                                p.log.error(deferred.error);
+                            }
+                            // Display remediation steps if available
+                            if (deferred.remediation && deferred.remediation.length > 0) {
+                                writeLine('');
+                                writeLine('  To fix:');
+                                for (const step of deferred.remediation) {
+                                    writeLine(`    - ${step}`);
+                                }
+                            }
+                            // Display documentation link if available
+                            if (deferred.documentationUrl) {
+                                writeLine('');
+                                writeLine(`  More info: ${deferred.documentationUrl}`);
+                            }
+                        }
+                        break;
+                    }
+                    // Activity lifecycle (task-level spinner)
+                    case 'activity:start': {
+                        if (state.suspended)
+                            break;
+                        // Find the parent group to determine layout
+                        const parentGroup = event.parentId ? state.groups.get(event.parentId) : null;
+                        if (parentGroup?.layout === 'parallel') {
+                            // Track this activity for the parallel group
+                            state.parallelActivities.set(event.id, {
+                                label: event.label,
+                                groupId: event.parentId,
+                                status: 'pending',
+                            });
+                            // In plain mode, just track activities - results shown at group:end
+                            if (!state.outputConfig.unicode) {
+                                if (!state.parallelSpinnerGroupId) {
+                                    state.parallelSpinnerGroupId = event.parentId;
+                                    const activities = state.parallelActivities.size;
+                                    writeLine(`  Running ${activities} task${activities > 1 ? 's' : ''}...`);
+                                }
+                            }
+                            else {
+                                // Unicode mode: create or update the parallel spinner
+                                if (!state.parallelSpinner) {
+                                    const spinner = p.spinner();
+                                    state.parallelSpinner = {
+                                        spinner,
+                                        label: event.label,
+                                        currentMessage: event.label,
+                                    };
+                                    state.parallelSpinnerGroupId = event.parentId;
+                                    spinner.start(event.label);
+                                }
+                                updateParallelSpinnerMessage(state);
+                            }
+                        }
+                        else {
+                            // Sequential activity
+                            if (!state.outputConfig.unicode) {
+                                // Plain mode: track activity without spinner - result shown on completion
+                                state.spinners.set(event.id, {
+                                    spinner: null, // Not used in plain mode
+                                    label: event.label,
+                                    currentMessage: event.label,
+                                    parentGroupId: event.parentId,
+                                });
+                            }
+                            else {
+                                // Unicode mode: create individual spinner
+                                const spinner = p.spinner();
+                                state.spinners.set(event.id, {
+                                    spinner,
+                                    label: event.label,
+                                    currentMessage: event.label,
+                                    parentGroupId: event.parentId,
+                                });
+                                spinner.start(event.label);
+                            }
+                        }
+                        break;
+                    }
+                    case 'activity:update': {
+                        if (state.suspended)
+                            break;
+                        // Check if this is a parallel activity
+                        const parallelActivity = state.parallelActivities.get(event.id);
+                        if (parallelActivity) {
+                            // Update the activity label if message provided
+                            if (event.payload.message) {
+                                parallelActivity.label = event.payload.message;
+                                if (state.outputConfig.unicode) {
+                                    updateParallelSpinnerMessage(state);
+                                }
+                            }
+                            break;
+                        }
+                        // Sequential activity
+                        const entry = state.spinners.get(event.id);
+                        if (entry) {
+                            const text = event.payload.message ||
+                                (event.payload.progress !== undefined ? `${event.payload.progress}%` : null);
+                            if (text) {
+                                entry.currentMessage = text;
+                                // Only update spinner in unicode mode
+                                if (state.outputConfig.unicode && entry.spinner) {
+                                    entry.spinner.message(text);
+                                }
+                            }
+                        }
+                        break;
+                    }
+                    case 'activity:success': {
+                        // Check if this is a parallel activity
+                        const parallelActivity = state.parallelActivities.get(event.id);
+                        if (parallelActivity) {
+                            parallelActivity.status = 'success';
+                            if (state.outputConfig.unicode) {
+                                updateParallelSpinnerMessage(state);
+                            }
+                            // Note: For parallel activities, logs will be flushed at group:end
+                            break;
+                        }
+                        // Sequential activity
+                        const entry = state.spinners.get(event.id);
+                        if (entry) {
+                            if (!state.outputConfig.unicode) {
+                                // Plain mode - print success line
+                                const prefix = colorize(state.symbols.success, pc.green, state.outputConfig.color);
+                                writeLine(`  ${prefix} ${entry.label}`);
+                            }
+                            else if (entry.spinner) {
+                                // Unicode mode - stop spinner
+                                entry.spinner.stop(entry.label, 0);
+                            }
+                            state.spinners.delete(event.id);
+                            // Flush any buffered logs for this activity
+                            flushLogsForActivity(state, event.id);
+                        }
+                        else {
+                            // Check if this was a suspended activity
+                            const suspended = state.suspendedActivities.get(event.id);
+                            if (suspended && !state.suspended) {
+                                if (!state.outputConfig.unicode) {
+                                    const prefix = colorize(state.symbols.success, pc.green, state.outputConfig.color);
+                                    writeLine(`  ${prefix} ${suspended.label}`);
+                                }
+                                else {
+                                    p.log.success(suspended.label);
+                                }
+                                state.suspendedActivities.delete(event.id);
+                            }
+                        }
+                        break;
+                    }
+                    case 'activity:failure': {
+                        const errorMessage = formatErrorMessage(event.error);
+                        // Check if this is a parallel activity
+                        const parallelActivity = state.parallelActivities.get(event.id);
+                        if (parallelActivity) {
+                            parallelActivity.status = 'failure';
+                            parallelActivity.error = errorMessage;
+                            parallelActivity.remediation = event.remediation;
+                            parallelActivity.documentationUrl = event.documentationUrl;
+                            // Mark the parent group as having failures
+                            const parentGroup = state.groups.get(parallelActivity.groupId);
+                            if (parentGroup) {
+                                parentGroup.hasFailure = true;
+                            }
+                            if (state.outputConfig.unicode) {
+                                updateParallelSpinnerMessage(state);
+                            }
+                            break;
+                        }
+                        // Sequential activity
+                        const entry = state.spinners.get(event.id);
+                        if (entry) {
+                            // Mark the parent group as having failures
+                            if (entry.parentGroupId) {
+                                const parentGroup = state.groups.get(entry.parentGroupId);
+                                if (parentGroup) {
+                                    parentGroup.hasFailure = true;
+                                }
+                            }
+                            if (!state.outputConfig.unicode) {
+                                // Plain mode - print error line
+                                const prefix = colorize(state.symbols.error, pc.red, state.outputConfig.color);
+                                writeLine(`  ${prefix} ${errorMessage}`);
+                            }
+                            else if (entry.spinner) {
+                                // Unicode mode - stop spinner with error
+                                entry.spinner.stop(errorMessage, 1);
+                            }
+                            state.spinners.delete(event.id);
+                            // Display remediation steps if available
+                            const linePrefix = state.outputConfig.unicode ? '\u2502' : state.symbols.groupLine;
+                            if (event.remediation && event.remediation.length > 0) {
+                                writeLine(linePrefix);
+                                writeLine(`${linePrefix}     To fix:`);
+                                for (const step of event.remediation) {
+                                    writeLine(`${linePrefix}       - ${step}`);
+                                }
+                            }
+                            // Display documentation link if available
+                            if (event.documentationUrl) {
+                                writeLine(linePrefix);
+                                writeLine(`${linePrefix}     More info: ${event.documentationUrl}`);
+                            }
+                            // Flush any buffered logs for this activity
+                            flushLogsForActivity(state, event.id);
+                        }
+                        else {
+                            // Check if this was a suspended activity
+                            const suspended = state.suspendedActivities.get(event.id);
+                            if (suspended && !state.suspended) {
+                                if (!state.outputConfig.unicode) {
+                                    const prefix = colorize(state.symbols.error, pc.red, state.outputConfig.color);
+                                    writeLine(`  ${prefix} ${suspended.label}: ${errorMessage}`);
+                                }
+                                else {
+                                    p.log.error(`${suspended.label}: ${errorMessage}`);
+                                }
+                                state.suspendedActivities.delete(event.id);
+                            }
+                        }
+                        break;
+                    }
+                    // Log events
+                    case 'log': {
+                        if (state.suspended)
+                            break;
+                        // Verbose mode: always display logs immediately
+                        if (state.verbose) {
+                            displayLog(event.level, event.message, state, false);
+                            break;
+                        }
+                        const hasActiveSpinners = state.spinners.size > 0 || state.parallelSpinner !== null;
+                        // Error logs interrupt spinners immediately (only in unicode mode)
+                        if (event.level === 'error' &&
+                            hasActiveSpinners &&
+                            event.activityId &&
+                            state.outputConfig.unicode) {
+                            const spinner = state.spinners.get(event.activityId);
+                            if (spinner && spinner.spinner) {
+                                // Temporarily stop spinner, show error, resume
+                                const currentMessage = spinner.currentMessage;
+                                spinner.spinner.stop(currentMessage, 0);
+                                displayLog(event.level, event.message, state, false);
+                                spinner.spinner.start(currentMessage);
+                            }
+                            else {
+                                // No spinner for this activity, just display
+                                displayLog(event.level, event.message, state, false);
+                            }
+                            break;
+                        }
+                        // Buffer logs during active spinners
+                        if (hasActiveSpinners && event.activityId) {
+                            // Check if we've hit the buffer limit for this activity
+                            const activityLogCount = state.bufferedLogs.filter((log) => log.activityId === event.activityId).length;
+                            if (activityLogCount < MAX_BUFFERED_LOGS_PER_ACTIVITY) {
+                                state.bufferedLogs.push({
+                                    activityId: event.activityId,
+                                    level: event.level,
+                                    message: event.message,
+                                    timestamp: Date.now(),
+                                });
+                            }
+                            // If over limit, silently drop (prevent memory issues)
+                            break;
+                        }
+                        // No active spinners - display immediately
+                        displayLog(event.level, event.message, state, false);
+                        break;
+                    }
+                    // Reporter control events
+                    case 'reporter:suspend': {
+                        state.suspended = true;
+                        // Stop all active spinners and track them for completion messages (only in unicode mode)
+                        if (state.outputConfig.unicode) {
+                            for (const [id, entry] of state.spinners) {
+                                try {
+                                    if (entry.spinner) {
+                                        entry.spinner.stop(entry.label + '...', 0);
+                                    }
+                                    state.suspendedActivities.set(id, { label: entry.label });
+                                }
+                                catch {
+                                    // Spinner may already be stopped
+                                }
+                            }
+                            state.spinners.clear();
+                            // Also stop parallel spinner
+                            if (state.parallelSpinner) {
+                                try {
+                                    state.parallelSpinner.spinner.stop('Paused...', 0);
+                                }
+                                catch {
+                                    // Spinner may already be stopped
+                                }
+                                state.parallelSpinner = null;
+                            }
+                        }
+                        break;
+                    }
+                    case 'reporter:resume': {
+                        state.suspended = false;
+                        break;
+                    }
+                }
+            };
+            const unsubscribe = bus.on(handleEvent);
+            return {
+                stop() {
+                    // Stop all active spinners (only in unicode mode where spinners exist)
+                    if (state.outputConfig.unicode) {
+                        for (const entry of state.spinners.values()) {
+                            try {
+                                if (entry.spinner) {
+                                    entry.spinner.stop('Stopped', 1);
+                                }
+                            }
+                            catch {
+                                // Spinner may already be stopped
+                            }
+                        }
+                        if (state.parallelSpinner) {
+                            try {
+                                state.parallelSpinner.spinner.stop('Stopped', 1);
+                            }
+                            catch {
+                                // Spinner may already be stopped
+                            }
+                        }
+                    }
+                    state.spinners.clear();
+                    state.groups.clear();
+                    state.parallelActivities.clear();
+                    state.parallelSpinner = null;
+                    state.parallelSpinnerGroupId = null;
+                    unsubscribe();
+                },
+            };
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @pokit/reporter-clack
+ *
+ * Clack-based implementation of the ReporterAdapter interface.
+ * Consumes CLI events and renders them using @clack/prompts.
+ */
+export { createReporterAdapter } from './adapter';
+export type { ReporterAdapterOptions } from './adapter';
+export { getSymbols, UNICODE_SYMBOLS, ASCII_SYMBOLS } from './symbols';
+export type { SymbolSet } from './symbols';
+//# 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":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAClD,YAAY,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAGxD,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AACvE,YAAY,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -0,0 +1,9 @@
+/**
+ * @pokit/reporter-clack
+ *
+ * Clack-based implementation of the ReporterAdapter interface.
+ * Consumes CLI events and renders them using @clack/prompts.
+ */
+export { createReporterAdapter } from './adapter';
+// Symbol exports for custom formatting
+export { getSymbols, UNICODE_SYMBOLS, ASCII_SYMBOLS } from './symbols';

package/dist/symbols.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Symbol Sets for CLI Output
+ *
+ * Provides Unicode and ASCII symbol sets for terminal output.
+ * The appropriate set is selected based on OutputConfig.
+ */
+import type { OutputConfig } from '@pokit/core';
+/**
+ * Complete set of symbols used in CLI output
+ */
+export type SymbolSet = {
+    /** Success indicator (e.g., checkmark) */
+    success: string;
+    /** Error indicator (e.g., X mark) */
+    error: string;
+    /** Warning indicator */
+    warning: string;
+    /** Info indicator */
+    info: string;
+    /** Step/progress indicator */
+    step: string;
+    /** Group start (e.g., top-left corner) */
+    groupStart: string;
+    /** Group end (e.g., bottom-left corner) */
+    groupEnd: string;
+    /** Group line (e.g., vertical bar) */
+    groupLine: string;
+    /** Done message */
+    done: string;
+    /** Failed message */
+    failed: string;
+};
+/**
+ * Unicode symbols for rich terminal output
+ * Used when unicode support is detected
+ */
+export declare const UNICODE_SYMBOLS: SymbolSet;
+/**
+ * ASCII symbols for plain text output
+ * Used in CI environments or when unicode is not supported
+ */
+export declare const ASCII_SYMBOLS: SymbolSet;
+/**
+ * Get the appropriate symbol set based on output configuration
+ *
+ * @param config - Output configuration
+ * @returns Symbol set to use
+ */
+export declare function getSymbols(config: OutputConfig): SymbolSet;
+//# sourceMappingURL=symbols.d.ts.map

package/dist/symbols.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbols.d.ts","sourceRoot":"","sources":["../src/symbols.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;GAEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,qCAAqC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,0CAA0C;IAC1C,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,mBAAmB;IACnB,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,eAAe,EAAE,SAW7B,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,aAAa,EAAE,SAW3B,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,CAE1D"}

package/dist/symbols.js

@@ -0,0 +1,47 @@
+/**
+ * Symbol Sets for CLI Output
+ *
+ * Provides Unicode and ASCII symbol sets for terminal output.
+ * The appropriate set is selected based on OutputConfig.
+ */
+/**
+ * Unicode symbols for rich terminal output
+ * Used when unicode support is detected
+ */
+export const UNICODE_SYMBOLS = {
+    success: '\u25C7', // ◇
+    error: '\u25A0', // ■
+    warning: '\u25B2', // ▲
+    info: '\u25CF', // ●
+    step: '\u25C7', // ◇
+    groupStart: '\u250C', // ┌
+    groupEnd: '\u2514', // └
+    groupLine: '\u2502', // │
+    done: '\u2714', // ✔
+    failed: '\u2718', // ✘
+};
+/**
+ * ASCII symbols for plain text output
+ * Used in CI environments or when unicode is not supported
+ */
+export const ASCII_SYMBOLS = {
+    success: '[OK]',
+    error: '[ERR]',
+    warning: '[WARN]',
+    info: '[INFO]',
+    step: '-',
+    groupStart: '[',
+    groupEnd: ']',
+    groupLine: '|',
+    done: 'Done',
+    failed: 'Failed',
+};
+/**
+ * Get the appropriate symbol set based on output configuration
+ *
+ * @param config - Output configuration
+ * @returns Symbol set to use
+ */
+export function getSymbols(config) {
+    return config.unicode ? UNICODE_SYMBOLS : ASCII_SYMBOLS;
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@pokit/reporter-clack",
+  "version": "0.0.1",
+  "description": "Clack-based event reporter for pok CLI applications",
+  "keywords": [
+    "cli",
+    "command-line",
+    "typescript",
+    "bun",
+    "terminal",
+    "pok",
+    "pokjs",
+    "clack",
+    "reporter",
+    "spinner",
+    "progress"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/notation-dev/openpok.git",
+    "directory": "packages/reporter-clack"
+  },
+  "homepage": "https://github.com/notation-dev/openpok#readme",
+  "bugs": {
+    "url": "https://github.com/notation-dev/openpok/issues"
+  },
+  "main": "./src/index.ts",
+  "module": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@pokit/core": "0.0.1"
+  },
+  "peerDependencies": {
+    "@pokit/core": "0.0.1"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,13 @@
+/**
+ * @pokit/reporter-clack
+ *
+ * Clack-based implementation of the ReporterAdapter interface.
+ * Consumes CLI events and renders them using @clack/prompts.
+ */
+
+export { createReporterAdapter } from './adapter';
+export type { ReporterAdapterOptions } from './adapter';
+
+// Symbol exports for custom formatting
+export { getSymbols, UNICODE_SYMBOLS, ASCII_SYMBOLS } from './symbols';
+export type { SymbolSet } from './symbols';