@pokit/terminal 0.2.0

package/dist/reporter/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/dist/screen.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Shared terminal screen state.
+ *
+ * The terminal UI is a single screen owner. Loading indicators (spinners) are
+ * created here rather than ad-hoc inside individual prompts, so the prompter
+ * does not spawn its own competing clack spinners for dynamic selects. The
+ * reporter adapter and the prompter both belong to the same terminal UI and
+ * share this screen.
+ */
+import type { OutputConfig } from '@pokit/core';
+export interface Screen {
+    /**
+     * Run `fn` while showing a loading indicator. The indicator is the single
+     * screen-owned spinner; the prompter never creates its own.
+     */
+    withLoading<T>(message: string, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
+}
+/**
+ * Create the shared screen for a terminal UI instance.
+ */
+export declare function createScreen(outputConfig: OutputConfig): Screen;
+//# sourceMappingURL=screen.d.ts.map

package/dist/screen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screen.d.ts","sourceRoot":"","sources":["../src/screen.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,MAAM,WAAW,MAAM;IACrB;;;OAGG;IACH,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACtF;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,YAAY,GAAG,MAAM,CAwB/D"}

package/dist/screen.js

@@ -0,0 +1,39 @@
+/**
+ * Shared terminal screen state.
+ *
+ * The terminal UI is a single screen owner. Loading indicators (spinners) are
+ * created here rather than ad-hoc inside individual prompts, so the prompter
+ * does not spawn its own competing clack spinners for dynamic selects. The
+ * reporter adapter and the prompter both belong to the same terminal UI and
+ * share this screen.
+ */
+import * as p from '@clack/prompts';
+function canUseInteractiveUI(outputConfig) {
+    return outputConfig.unicode && outputConfig.interactive;
+}
+/**
+ * Create the shared screen for a terminal UI instance.
+ */
+export function createScreen(outputConfig) {
+    const interactive = canUseInteractiveUI(outputConfig);
+    return {
+        async withLoading(message, fn) {
+            const controller = new AbortController();
+            if (!interactive) {
+                return fn(controller.signal);
+            }
+            const spinner = p.spinner();
+            spinner.start(message);
+            try {
+                const result = await fn(controller.signal);
+                spinner.stop(message);
+                return result;
+            }
+            catch (error) {
+                controller.abort();
+                spinner.stop('Failed to load');
+                throw error;
+            }
+        },
+    };
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@pokit/terminal",
+  "version": "0.2.0",
+  "description": "Terminal UI (reporter + prompter + navigator) for pok CLI applications, built on clack",
+  "keywords": [
+    "cli",
+    "command-line",
+    "typescript",
+    "bun",
+    "terminal",
+    "pok",
+    "pokjs",
+    "clack",
+    "reporter",
+    "prompter",
+    "interactive"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/djgrant/pok.git",
+    "directory": "packages/terminal"
+  },
+  "homepage": "https://github.com/djgrant/pok#readme",
+  "bugs": {
+    "url": "https://github.com/djgrant/pok/issues"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/core": "^1.0.0",
+    "@clack/prompts": "^1.0.0",
+    "picocolors": "^1.1.1"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@pokit/core": "0.2.0",
+    "@pokit/test-utils": "0.0.0"
+  },
+  "peerDependencies": {
+    "@pokit/core": "0.2.0"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+/**
+ * @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 type {
+  OutputConfig,
+  ReporterAdapter,
+  Prompter,
+  Navigator,
+} from '@pokit/core';
+import { createReporterAdapter } from './reporter/adapter.js';
+import { createPrompter } from './prompter/prompter.js';
+import { createScreen } from './screen.js';
+
+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 function createTerminalUI(options?: TerminalUIOptions): TerminalUI {
+  const outputConfig: 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/src/prompter/autocomplete-prompt.ts

@@ -0,0 +1,352 @@
+/**
+ * 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 { Key } from 'node:readline';
+import { Prompt, type PromptOptions, settings } from '@clack/core';
+import {
+  isCancel,
+  limitOptions,
+  symbol,
+  S_BAR,
+  S_BAR_END,
+  S_RADIO_ACTIVE,
+  S_RADIO_INACTIVE,
+} from '@clack/prompts';
+import type { Writable } from 'node:stream';
+import color from 'picocolors';
+
+interface OptionLike {
+  value: unknown;
+  label?: string;
+}
+
+type FilterFunction<T extends OptionLike> = (search: string, opt: T) => boolean;
+
+function getCursorForValue<T extends OptionLike>(
+  selected: T['value'] | undefined,
+  items: T[]
+): number {
+  if (selected === undefined || items.length === 0) {
+    return 0;
+  }
+  const index = items.findIndex((item) => item.value === selected);
+  return index !== -1 ? index : 0;
+}
+
+function defaultFilter<T extends OptionLike>(input: string, option: T): boolean {
+  const label = option.label ?? String(option.value);
+  return label.toLowerCase().includes(input.toLowerCase());
+}
+
+interface AutocompletePromptOptions<T extends OptionLike> extends PromptOptions<
+  T['value'] | T['value'][],
+  PatchedAutocompletePrompt<T>
+> {
+  options: T[] | ((this: PatchedAutocompletePrompt<T>) => T[]);
+  filter?: FilterFunction<T>;
+  multiple?: boolean;
+}
+
+class PatchedAutocompletePrompt<T extends OptionLike> extends Prompt<T['value'] | T['value'][]> {
+  filteredOptions: T[];
+  multiple: boolean;
+  isNavigating = false;
+  selectedValues: Array<T['value']> = [];
+  focusedValue: T['value'] | undefined;
+  #cursor = 0;
+  #lastUserInput = '';
+  #filterFn: FilterFunction<T>;
+  #options: T[] | (() => T[]);
+
+  get cursor(): number {
+    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(): T[] {
+    if (typeof this.#options === 'function') {
+      return this.#options();
+    }
+    return this.#options;
+  }
+
+  constructor(opts: AutocompletePromptOptions<T>) {
+    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: unknown[] | undefined;
+    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));
+  }
+
+  protected override _isActionKey(char: string | undefined, key: Key): boolean {
+    return (
+      char === '\t' ||
+      (this.multiple &&
+        this.isNavigating &&
+        key.name === 'space' &&
+        char !== undefined &&
+        char !== '')
+    );
+  }
+
+  #onKey(_char: string | undefined, key: Key): void {
+    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: T['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: string): void {
+    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();
+        }
+      }
+    }
+  }
+}
+
+interface Option<Value> {
+  value: Value;
+  label?: string;
+  hint?: string;
+}
+
+function getLabel<T>(option: Option<T>) {
+  return option.label ?? String(option.value ?? '');
+}
+
+function getFilteredOption<T>(searchText: string, option: Option<T>): boolean {
+  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<T>(values: T[], options: Option<T>[]): Option<T>[] {
+  const results: Option<T>[] = [];
+  for (const option of options) {
+    if (values.includes(option.value)) {
+      results.push(option);
+    }
+  }
+  return results;
+}
+
+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 const patchedAutocomplete = <Value>(opts: AutocompleteOpts<Value>) => {
+  const prompt = new PatchedAutocompletePrompt({
+    options: opts.options,
+    initialValue: opts.initialValue ? [opts.initialValue] : undefined,
+    initialUserInput: opts.initialUserInput,
+    filter: opts.filter ?? ((search: string, opt: Option<Value>) => 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: Option<Value>, active: boolean) => {
+                    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: string) => `${guidePrefix}${option}`),
+            ...footers,
+          ].join('\n');
+        }
+      }
+    },
+  });
+
+  return prompt.prompt() as Promise<Value | symbol>;
+};