@pokit/terminal 0.2.0

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/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @pokit/terminal
+ *
+ * The default terminal UI for pok CLI applications, built on clack. Bundles the
+ * three UI surfaces — reporter (event rendering), prompter (interactive input),
+ * and navigator (menu presentation policy) — behind a single factory so an app
+ * wires them in with one call.
+ */
+import type { OutputConfig, ReporterAdapter, Prompter, Navigator } from '@pokit/core';
+export type { OutputConfig, ReporterAdapter, Prompter, Navigator } from '@pokit/core';
+/**
+ * Options for creating the terminal UI.
+ */
+export type TerminalUIOptions = {
+    /** When true, logs are displayed immediately instead of being buffered during spinners */
+    verbose?: boolean;
+    /** Output configuration (color, unicode, interactive). Detected from args/env when omitted. */
+    output?: OutputConfig;
+};
+/**
+ * The bundled terminal UI surfaces.
+ */
+export type TerminalUI = {
+    reporter: ReporterAdapter;
+    prompter: Prompter;
+    navigator: Navigator;
+};
+/**
+ * Create the default terminal UI.
+ *
+ * Returns the reporter adapter, prompter, and navigator, all sharing a single
+ * screen so loading indicators and rendering are owned in one place.
+ */
+export declare function createTerminalUI(options?: TerminalUIOptions): TerminalUI;
+//# 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;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,YAAY,EACZ,eAAe,EACf,QAAQ,EACR,SAAS,EACV,MAAM,aAAa,CAAC;AAKrB,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAEtF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,0FAA0F;IAC1F,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,eAAe,CAAC;IAC1B,QAAQ,EAAE,QAAQ,CAAC;IACnB,SAAS,EAAE,SAAS,CAAC;CACtB,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,iBAAiB,GAAG,UAAU,CAexE"}

package/dist/index.js

@@ -0,0 +1,32 @@
+/**
+ * @pokit/terminal
+ *
+ * The default terminal UI for pok CLI applications, built on clack. Bundles the
+ * three UI surfaces — reporter (event rendering), prompter (interactive input),
+ * and navigator (menu presentation policy) — behind a single factory so an app
+ * wires them in with one call.
+ */
+import { detectOutputConfig, createMenuNavigator } from '@pokit/core';
+import { createReporterAdapter } from './reporter/adapter.js';
+import { createPrompter } from './prompter/prompter.js';
+import { createScreen } from './screen.js';
+/**
+ * Create the default terminal UI.
+ *
+ * Returns the reporter adapter, prompter, and navigator, all sharing a single
+ * screen so loading indicators and rendering are owned in one place.
+ */
+export function createTerminalUI(options) {
+    const outputConfig = options?.output ?? detectOutputConfig(process.argv.slice(2));
+    if (outputConfig.interactive === undefined) {
+        outputConfig.interactive = true;
+    }
+    if (options?.verbose !== undefined) {
+        outputConfig.verbose = options.verbose;
+    }
+    const screen = createScreen(outputConfig);
+    const reporter = createReporterAdapter({ output: outputConfig });
+    const prompter = createPrompter(screen);
+    const navigator = createMenuNavigator(prompter);
+    return { reporter, prompter, navigator };
+}

package/dist/prompter/autocomplete-prompt.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Patched autocomplete function
+ *
+ * Copies the autocomplete function from @clack/prompts but uses a patched
+ * AutocompletePrompt that wraps the cursor instead of clamping it.
+ *
+ * Upstream tracking: https://github.com/bombshell-dev/clack/issues
+ * TODO: Remove this file once cursor wrapping is available upstream.
+ */
+import type { Writable } from 'node:stream';
+interface Option<Value> {
+    value: Value;
+    label?: string;
+    hint?: string;
+}
+export interface AutocompleteOpts<Value> {
+    message: string;
+    options: Option<Value>[];
+    maxItems?: number;
+    placeholder?: string;
+    initialValue?: Value;
+    initialUserInput?: string;
+    validate?: (value: Value | Value[] | undefined) => string | Error | undefined;
+    filter?: (search: string, option: Option<Value>) => boolean;
+    signal?: AbortSignal;
+    input?: import('node:stream').Readable;
+    output?: Writable;
+}
+export declare const patchedAutocomplete: <Value>(opts: AutocompleteOpts<Value>) => Promise<Value | symbol>;
+export {};
+//# sourceMappingURL=autocomplete-prompt.d.ts.map

package/dist/prompter/autocomplete-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autocomplete-prompt.d.ts","sourceRoot":"","sources":["../../src/prompter/autocomplete-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAuL5C,UAAU,MAAM,CAAC,KAAK;IACpB,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAyBD,MAAM,WAAW,gBAAgB,CAAC,KAAK;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,EAAE,GAAG,SAAS,KAAK,MAAM,GAAG,KAAK,GAAG,SAAS,CAAC;IAC9E,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,KAAK,OAAO,CAAC;IAC5D,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,aAAa,EAAE,QAAQ,CAAC;IACvC,MAAM,CAAC,EAAE,QAAQ,CAAC;CACnB;AAED,eAAO,MAAM,mBAAmB,GAAI,KAAK,EAAE,MAAM,gBAAgB,CAAC,KAAK,CAAC,KAuG5C,OAAO,CAAC,KAAK,GAAG,MAAM,CACjD,CAAC"}

package/dist/prompter/autocomplete-prompt.js

@@ -0,0 +1,266 @@
+/**
+ * Patched autocomplete function
+ *
+ * Copies the autocomplete function from @clack/prompts but uses a patched
+ * AutocompletePrompt that wraps the cursor instead of clamping it.
+ *
+ * Upstream tracking: https://github.com/bombshell-dev/clack/issues
+ * TODO: Remove this file once cursor wrapping is available upstream.
+ */
+import { Prompt } from '@clack/core';
+import { limitOptions, symbol, S_BAR, S_BAR_END, S_RADIO_ACTIVE, S_RADIO_INACTIVE, } from '@clack/prompts';
+import color from 'picocolors';
+function getCursorForValue(selected, items) {
+    if (selected === undefined || items.length === 0) {
+        return 0;
+    }
+    const index = items.findIndex((item) => item.value === selected);
+    return index !== -1 ? index : 0;
+}
+function defaultFilter(input, option) {
+    const label = option.label ?? String(option.value);
+    return label.toLowerCase().includes(input.toLowerCase());
+}
+class PatchedAutocompletePrompt extends Prompt {
+    filteredOptions;
+    multiple;
+    isNavigating = false;
+    selectedValues = [];
+    focusedValue;
+    #cursor = 0;
+    #lastUserInput = '';
+    #filterFn;
+    #options;
+    get cursor() {
+        return this.#cursor;
+    }
+    get userInputWithCursor() {
+        if (!this.userInput) {
+            return color.inverse(color.hidden('_'));
+        }
+        if (this._cursor >= this.userInput.length) {
+            return `${this.userInput}█`;
+        }
+        const s1 = this.userInput.slice(0, this._cursor);
+        const [s2, ...s3] = this.userInput.slice(this._cursor);
+        return `${s1}${color.inverse(s2)}${s3.join('')}`;
+    }
+    get options() {
+        if (typeof this.#options === 'function') {
+            return this.#options();
+        }
+        return this.#options;
+    }
+    constructor(opts) {
+        super(opts);
+        this.#options = opts.options;
+        const options = this.options;
+        this.filteredOptions = [...options];
+        this.multiple = opts.multiple === true;
+        this.#filterFn = opts.filter ?? defaultFilter;
+        let initialValues;
+        if (opts.initialValue && Array.isArray(opts.initialValue)) {
+            initialValues = this.multiple ? opts.initialValue : opts.initialValue.slice(0, 1);
+        }
+        else if (!this.multiple && this.options.length > 0) {
+            initialValues = [this.options[0].value];
+        }
+        if (initialValues) {
+            for (const selectedValue of initialValues) {
+                const selectedIndex = options.findIndex((opt) => opt.value === selectedValue);
+                if (selectedIndex !== -1) {
+                    this.toggleSelected(selectedValue);
+                    this.#cursor = selectedIndex;
+                }
+            }
+        }
+        this.focusedValue = this.options[this.#cursor]?.value;
+        this.on('key', (char, key) => this.#onKey(char, key));
+        this.on('userInput', (value) => this.#onUserInputChanged(value));
+    }
+    _isActionKey(char, key) {
+        return (char === '\t' ||
+            (this.multiple &&
+                this.isNavigating &&
+                key.name === 'space' &&
+                char !== undefined &&
+                char !== ''));
+    }
+    #onKey(_char, key) {
+        const isUpKey = key.name === 'up';
+        const isDownKey = key.name === 'down';
+        const isReturnKey = key.name === 'return';
+        if (isUpKey || isDownKey) {
+            const length = this.filteredOptions.length;
+            if (length > 0) {
+                this.#cursor = (((this.#cursor + (isUpKey ? -1 : 1)) % length) + length) % length;
+            }
+            this.focusedValue = this.filteredOptions[this.#cursor]?.value;
+            if (!this.multiple) {
+                this.selectedValues = [this.focusedValue];
+            }
+            this.isNavigating = true;
+        }
+        else if (isReturnKey) {
+            this.value = this.multiple ? this.selectedValues : this.selectedValues[0];
+        }
+        else {
+            if (this.multiple) {
+                if (this.focusedValue !== undefined &&
+                    (key.name === 'tab' || (this.isNavigating && key.name === 'space'))) {
+                    this.toggleSelected(this.focusedValue);
+                }
+                else {
+                    this.isNavigating = false;
+                }
+            }
+            else {
+                if (this.focusedValue) {
+                    this.selectedValues = [this.focusedValue];
+                }
+                this.isNavigating = false;
+            }
+        }
+    }
+    deselectAll() {
+        this.selectedValues = [];
+    }
+    toggleSelected(value) {
+        if (this.filteredOptions.length === 0)
+            return;
+        if (this.multiple) {
+            if (this.selectedValues.includes(value)) {
+                this.selectedValues = this.selectedValues.filter((v) => v !== value);
+            }
+            else {
+                this.selectedValues = [...this.selectedValues, value];
+            }
+        }
+        else {
+            this.selectedValues = [value];
+        }
+    }
+    #onUserInputChanged(value) {
+        if (value !== this.#lastUserInput) {
+            this.#lastUserInput = value;
+            const options = this.options;
+            this.filteredOptions = value
+                ? options.filter((opt) => this.#filterFn(value, opt))
+                : [...options];
+            this.#cursor = getCursorForValue(this.focusedValue, this.filteredOptions);
+            this.focusedValue = this.filteredOptions[this.#cursor]?.value;
+            if (!this.multiple) {
+                if (this.focusedValue !== undefined) {
+                    this.toggleSelected(this.focusedValue);
+                }
+                else {
+                    this.deselectAll();
+                }
+            }
+        }
+    }
+}
+function getLabel(option) {
+    return option.label ?? String(option.value ?? '');
+}
+function getFilteredOption(searchText, option) {
+    if (!searchText)
+        return true;
+    const label = (option.label ?? String(option.value ?? '')).toLowerCase();
+    const hint = (option.hint ?? '').toLowerCase();
+    const value = String(option.value).toLowerCase();
+    const term = searchText.toLowerCase();
+    return label.includes(term) || hint.includes(term) || value.includes(term);
+}
+function getSelectedOptions(values, options) {
+    const results = [];
+    for (const option of options) {
+        if (values.includes(option.value)) {
+            results.push(option);
+        }
+    }
+    return results;
+}
+export const patchedAutocomplete = (opts) => {
+    const prompt = new PatchedAutocompletePrompt({
+        options: opts.options,
+        initialValue: opts.initialValue ? [opts.initialValue] : undefined,
+        initialUserInput: opts.initialUserInput,
+        filter: opts.filter ?? ((search, opt) => getFilteredOption(search, opt)),
+        signal: opts.signal,
+        input: opts.input,
+        output: opts.output,
+        validate: opts.validate,
+        render() {
+            const headings = [`${color.gray(S_BAR)}`, `${symbol(this.state)}  ${opts.message}`];
+            const userInput = this.userInput;
+            const options = this.options;
+            const placeholder = opts.placeholder;
+            const showPlaceholder = userInput === '' && placeholder !== undefined;
+            switch (this.state) {
+                case 'submit': {
+                    const selected = getSelectedOptions(this.selectedValues, options);
+                    const label = selected.length > 0 ? `  ${color.dim(selected.map(getLabel).join(', '))}` : '';
+                    return `${headings.join('\n')}\n${color.gray(S_BAR)}${label}`;
+                }
+                case 'cancel': {
+                    const userInputText = userInput ? `  ${color.strikethrough(color.dim(userInput))}` : '';
+                    return `${headings.join('\n')}\n${color.gray(S_BAR)}${userInputText}`;
+                }
+                default: {
+                    const barColor = this.state === 'error' ? color.yellow : color.cyan;
+                    const guidePrefix = `${barColor(S_BAR)}  `;
+                    const guidePrefixEnd = barColor(S_BAR_END);
+                    let searchText = '';
+                    if (this.isNavigating || showPlaceholder) {
+                        const searchTextValue = showPlaceholder ? placeholder : userInput;
+                        searchText = searchTextValue !== '' ? ` ${color.dim(searchTextValue)}` : '';
+                    }
+                    else {
+                        searchText = ` ${this.userInputWithCursor}`;
+                    }
+                    const matches = this.filteredOptions.length !== options.length
+                        ? color.dim(` (${this.filteredOptions.length} match${this.filteredOptions.length === 1 ? '' : 'es'})`)
+                        : '';
+                    const noResults = this.filteredOptions.length === 0 && userInput
+                        ? [`${guidePrefix}${color.yellow('No matches found')}`]
+                        : [];
+                    const validationError = this.state === 'error' ? [`${guidePrefix}${color.yellow(this.error)}`] : [];
+                    headings.push(`${guidePrefix.trimEnd()}`);
+                    headings.push(`${guidePrefix}${color.dim('Search:')}${searchText}${matches}`, ...noResults, ...validationError);
+                    const instructions = [
+                        `${color.dim('↑/↓')} to select`,
+                        `${color.dim('Enter:')} confirm`,
+                        `${color.dim('Type:')} to search`,
+                    ];
+                    const footers = [`${guidePrefix}${instructions.join(' • ')}`, guidePrefixEnd];
+                    const displayOptions = this.filteredOptions.length === 0
+                        ? []
+                        : limitOptions({
+                            cursor: this.cursor,
+                            options: this.filteredOptions,
+                            columnPadding: 3,
+                            rowPadding: headings.length + footers.length,
+                            style: (option, active) => {
+                                const label = getLabel(option);
+                                const hint = option.hint && option.value === this.focusedValue
+                                    ? color.dim(` (${option.hint})`)
+                                    : '';
+                                return active
+                                    ? `${color.green(S_RADIO_ACTIVE)} ${label}${hint}`
+                                    : `${color.dim(S_RADIO_INACTIVE)} ${color.dim(label)}${hint}`;
+                            },
+                            maxItems: opts.maxItems,
+                            output: opts.output,
+                        });
+                    return [
+                        ...headings,
+                        ...displayOptions.map((option) => `${guidePrefix}${option}`),
+                        ...footers,
+                    ].join('\n');
+                }
+            }
+        },
+    });
+    return prompt.prompt();
+};

package/dist/prompter/prompter.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Clack Prompter Implementation
+ *
+ * Implements the Prompter interface using @clack/prompts.
+ *
+ * Dynamic selects no longer spawn their own spinners: loading is routed through
+ * the shared terminal Screen, keeping a single screen owner. Filtering is
+ * handled client-side by the autocomplete prompt once options are loaded.
+ */
+import type { Prompter } from '@pokit/core';
+import type { Screen } from '../screen.js';
+/**
+ * Create a Prompter using @clack/prompts, sharing the terminal Screen.
+ */
+export declare function createPrompter(screen: Screen): Prompter;
+//# sourceMappingURL=prompter.d.ts.map

package/dist/prompter/prompter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompter.d.ts","sourceRoot":"","sources":["../../src/prompter/prompter.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EACV,QAAQ,EAQT,MAAM,aAAa,CAAC;AAGrB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAoI3C;;GAEG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CA4GvD"}

package/dist/prompter/prompter.js

@@ -0,0 +1,206 @@
+/**
+ * Clack Prompter Implementation
+ *
+ * Implements the Prompter interface using @clack/prompts.
+ *
+ * Dynamic selects no longer spawn their own spinners: loading is routed through
+ * the shared terminal Screen, keeping a single screen owner. Filtering is
+ * handled client-side by the autocomplete prompt once options are loaded.
+ */
+import * as p from '@clack/prompts';
+import { isDynamicOptions, CancelError } from '@pokit/core';
+import { patchedAutocomplete } from './autocomplete-prompt.js';
+/**
+ * Show error recovery prompt. Returns 'retry' or 'cancel'.
+ */
+async function showErrorRecovery(errorMessage) {
+    const result = await p.select({
+        message: `Error: ${errorMessage}`,
+        options: [
+            { value: 'retry', label: 'Retry', hint: 'Try loading again' },
+            { value: 'cancel', label: 'Cancel', hint: 'Abort selection' },
+        ],
+    });
+    if (p.isCancel(result)) {
+        return 'cancel';
+    }
+    return result;
+}
+// =============================================================================
+// Dynamic Select Implementation
+// =============================================================================
+/**
+ * Handle a dynamic select: load the option set via the provider (loading shown
+ * through the shared screen), then present them with type-ahead filtering.
+ */
+async function handleDynamicSelect(dynamicOptions, screen) {
+    const loadingMessage = dynamicOptions.loadingMessage ?? 'Loading...';
+    let options;
+    try {
+        options = await screen.withLoading(loadingMessage, (signal) => dynamicOptions.provider(undefined, signal));
+    }
+    catch (error) {
+        const errorMessage = dynamicOptions.errorMessage ??
+            (error instanceof Error ? error.message : 'Failed to load options');
+        const action = await showErrorRecovery(errorMessage);
+        if (action === 'cancel') {
+            p.cancel('Cancelled');
+            throw new CancelError('Cancelled');
+        }
+        // Retry
+        return handleDynamicSelect(dynamicOptions, screen);
+    }
+    if (options.length === 0) {
+        p.cancel('No options available');
+        throw new CancelError('No options available');
+    }
+    const result = await patchedAutocomplete({
+        message: dynamicOptions.message,
+        options: options.map((opt) => ({
+            value: opt.value,
+            label: opt.label,
+            hint: opt.hint,
+        })),
+    });
+    if (p.isCancel(result)) {
+        throw new CancelError('Cancelled');
+    }
+    return result;
+}
+// =============================================================================
+// Grouped Options Helpers
+// =============================================================================
+/**
+ * Organize flat options into a group → options record for clack's groupMultiselect.
+ * Options without a group are placed under an empty-string key.
+ */
+function toGroupedRecord(options) {
+    const groups = {};
+    for (const opt of options) {
+        const key = opt.group ?? '';
+        if (!groups[key])
+            groups[key] = [];
+        groups[key].push({ value: opt.value, label: opt.label, hint: opt.hint });
+    }
+    return groups;
+}
+/**
+ * Sort options by group order (preserving insertion order of first occurrence)
+ * and add group name as label prefix for visual separation in a flat select.
+ */
+function flattenGroupedForSelect(options) {
+    const groupOrder = [];
+    for (const opt of options) {
+        const key = opt.group ?? '';
+        if (!groupOrder.includes(key))
+            groupOrder.push(key);
+    }
+    const result = [];
+    for (const group of groupOrder) {
+        const groupOpts = options.filter((opt) => (opt.group ?? '') === group);
+        for (const opt of groupOpts) {
+            result.push({
+                value: opt.value,
+                label: group ? `${group} › ${opt.label}` : opt.label,
+                hint: opt.hint,
+            });
+        }
+    }
+    return result;
+}
+// =============================================================================
+// Main Prompter Factory
+// =============================================================================
+/**
+ * Create a Prompter using @clack/prompts, sharing the terminal Screen.
+ */
+export function createPrompter(screen) {
+    return {
+        async select(options) {
+            // Handle dynamic options via the shared screen
+            if (isDynamicOptions(options)) {
+                return handleDynamicSelect(options, screen);
+            }
+            // Static options - handle grouped or flat
+            const opts = options.options;
+            const clackOptions = opts.some((o) => o.group)
+                ? flattenGroupedForSelect(opts)
+                : opts.map((opt) => ({ value: opt.value, label: opt.label, hint: opt.hint }));
+            const result = await p.select({
+                message: options.message,
+                options: clackOptions,
+                initialValue: options.initialValue,
+            });
+            if (p.isCancel(result)) {
+                throw new CancelError('Cancelled');
+            }
+            return result;
+        },
+        async multiselect(options) {
+            // Use groupMultiselect when options have groups
+            const msOpts = options.options;
+            if (msOpts.some((o) => o.group)) {
+                const grouped = toGroupedRecord(msOpts);
+                const result = await p.groupMultiselect({
+                    message: options.message,
+                    options: grouped,
+                    required: options.required,
+                });
+                if (p.isCancel(result)) {
+                    throw new CancelError('Cancelled');
+                }
+                return result;
+            }
+            const result = await p.multiselect({
+                message: options.message,
+                options: options.options,
+                initialValues: options.initialValues,
+                required: options.required,
+            });
+            if (p.isCancel(result)) {
+                throw new CancelError('Cancelled');
+            }
+            return result;
+        },
+        async confirm(options) {
+            const result = await p.confirm({
+                message: options.message,
+                initialValue: options.initialValue,
+            });
+            if (p.isCancel(result)) {
+                throw new CancelError('Cancelled');
+            }
+            return result;
+        },
+        async text(options) {
+            const result = await p.text({
+                message: options.message,
+                placeholder: options.placeholder,
+                initialValue: options.initialValue,
+                validate: options.validate
+                    ? (value) => options.validate(value ?? '')
+                    : undefined,
+            });
+            if (p.isCancel(result)) {
+                throw new CancelError('Cancelled');
+            }
+            return result;
+        },
+        async autocomplete(options) {
+            const result = await patchedAutocomplete({
+                message: options.message,
+                options: options.options.map((opt) => ({
+                    value: opt.value,
+                    label: opt.label,
+                    hint: opt.hint,
+                })),
+                placeholder: options.placeholder,
+                maxItems: options.maxItems,
+            });
+            if (p.isCancel(result)) {
+                throw new CancelError('Cancelled');
+            }
+            return result;
+        },
+    };
+}

package/dist/reporter/adapter.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 line-based output)
+ * - group:end -> p.outro() with success indicator
+ * - activity:start (sequential) -> spinner.start() (or line-based output)
+ * - 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
+ *
+ * Non-interactive output (--no-tty/NO_TTY/CI):
+ * - Uses line-based output without spinners or clack decorative UI
+ * - Unicode symbols are controlled separately with --no-unicode/NO_UNICODE
+ * - Color is controlled separately with --no-color/NO_COLOR
+ */
+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/reporter/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/reporter/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EACV,eAAe,EAQf,YAAY,EACb,MAAM,aAAa,CAAC;AAmNrB;;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,CAgevF"}