prismatica 0.2.0

package/node_modules/@inquirer/core/README.md

@@ -0,0 +1,386 @@
+# `@inquirer/core`
+
+The `@inquirer/core` package is the library enabling the creation of Inquirer prompts.
+
+It aims to implements a lightweight API similar to React hooks - but without JSX.
+
+# Installation
+
+<table>
+<tr>
+  <th>npm</th>
+  <th>yarn</th>
+</tr>
+<tr>
+<td>
+
+```sh
+npm install @inquirer/core
+```
+
+</td>
+<td>
+
+```sh
+yarn add @inquirer/core
+```
+
+</td>
+</tr>
+</table>
+
+# Usage
+
+## Basic concept
+
+Visual terminal apps are at their core strings rendered onto the terminal.
+
+The most basic prompt is a function returning a string that'll be rendered in the terminal. This function will run every time the prompt state change, and the new returned string will replace the previously rendered one. The prompt cursor appears after the string.
+
+Wrapping the rendering function with `createPrompt()` will setup the rendering layer, inject the state management utilities, and wait until the `done` callback is called.
+
+```ts
+import { createPrompt } from '@inquirer/core';
+
+const input = createPrompt((config, done) => {
+  // Implement logic
+
+  return '? My question';
+});
+
+// And it is then called as
+const answer = await input({
+  /* config */
+});
+```
+
+## Hooks
+
+State management and user interactions are handled through hooks. Hooks are common [within the React ecosystem](https://react.dev/reference/react/hooks), and Inquirer reimplement the common ones.
+
+### State hook
+
+State lets a component “remember” information like user input. For example, an input prompt can use state to store the input value, while a list prompt can use state to track the cursor index.
+
+`useState` declares a state variable that you can update directly.
+
+```ts
+import { createPrompt, useState } from '@inquirer/core';
+
+const input = createPrompt((config, done) => {
+  const [index, setIndex] = useState(0);
+
+  // ...
+```
+
+### Keypress hook
+
+Almost all prompts need to react to user actions. In a terminal, this is done through typing.
+
+`useKeypress` allows you to react to keypress events, and access the prompt line.
+
+```ts
+const input = createPrompt((config, done) => {
+  useKeypress((key) => {
+    if (key.name === 'enter') {
+      done(answer);
+    }
+  });
+
+  // ...
+```
+
+Behind the scenes, Inquirer prompts are wrappers around [readlines](https://nodejs.org/api/readline.html). Aside the keypress event object, the hook also pass the active readline instance to the event handler.
+
+```ts
+const input = createPrompt((config, done) => {
+  useKeypress((key, readline) => {
+    setValue(readline.line);
+  });
+
+  // ...
+```
+
+### Ref hook
+
+Refs let a prompt hold some information that isn’t used for rendering, like a class instance or a timeout ID. Unlike with state, updating a ref does not re-render your prompt. Refs are an “escape hatch” from the rendering paradigm.
+
+`useRef` declares a ref. You can hold any value in it, but most often it’s used to hold a timeout ID.
+
+```ts
+const input = createPrompt((config, done) => {
+  const timeout = useRef(null);
+
+  // ...
+```
+
+### Effect Hook
+
+Effects let a prompt connect to and synchronize with external systems. This includes dealing with network or animations.
+
+`useEffect` connects a component to an external system.
+
+```ts
+const chat = createPrompt((config, done) => {
+  useEffect(() => {
+    const connection = createConnection(roomId);
+    connection.connect();
+    return () => connection.disconnect();
+  }, [roomId]);
+
+  // ...
+```
+
+### Performance hook
+
+A common way to optimize re-rendering performance is to skip unnecessary work. For example, you can tell Inquirer to reuse a cached calculation or to skip a re-render if the data has not changed since the previous render.
+
+`useMemo` lets you cache the result of an expensive calculation.
+
+```ts
+const todoSelect = createPrompt((config, done) => {
+  const visibleTodos = useMemo(() => filterTodos(todos, tab), [todos, tab]);
+
+  // ...
+```
+
+### Rendering hooks
+
+#### Prefix / loading
+
+All default prompts, and most custom ones, uses a prefix at the beginning of the prompt line. This helps visually delineate different questions, and provides a convenient area to render a loading spinner.
+
+`usePrefix` is a built-in hook to do this.
+
+```ts
+const input = createPrompt((config, done) => {
+  const prefix = usePrefix({ status });
+
+  return `${prefix} My question`;
+});
+```
+
+#### Pagination
+
+When looping through a long list of options (like in the `select` prompt), paginating the results appearing on the screen at once can be necessary. The `usePagination` hook is the utility used within the `select` and `checkbox` prompts to cycle through the list of options.
+
+Pagination works by taking in the list of options and returning a subset of the rendered items that fit within the page. The hook takes in a few options. It needs a list of options (`items`), and a `pageSize` which is the number of lines to be rendered. The `active` index is the index of the currently selected/selectable item. The `loop` option is a boolean that indicates if the list should loop around when reaching the end: this is the default behavior. The pagination hook renders items only as necessary, so it takes a function that can render an item at an index, including an `active` state, called `renderItem`.
+
+```js
+export default createPrompt((config, done) => {
+  const [active, setActive] = useState(0);
+
+  const allChoices = config.choices.map((choice) => choice.name);
+
+  const page = usePagination({
+    items: allChoices,
+    active: active,
+    renderItem: ({ item, index, isActive }) => `${isActive ? ">" : " "}${index}. ${item.toString()}`
+    pageSize: config.pageSize,
+    loop: config.loop,
+  });
+
+  return `... ${page}`;
+});
+```
+
+## `createPrompt()` API
+
+As we saw earlier, the rendering function should return a string, and eventually call `done` to close the prompt and return the answer.
+
+```ts
+const input = createPrompt((config, done) => {
+  const [value, setValue] = useState();
+
+  useKeypress((key, readline) => {
+    if (key.name === 'enter') {
+      done(answer);
+    } else {
+      setValue(readline.line);
+    }
+  });
+
+  return `? ${config.message} ${value}`;
+});
+```
+
+The rendering function can also return a tuple of 2 string (`[string, string]`.) The first string represents the prompt. The second one is content to render under the prompt, like an error message. The text input cursor will appear after the first string.
+
+```ts
+const number = createPrompt((config, done) => {
+  // Add some logic here
+
+  return [`? My question ${input}`, `! The input must be a number`];
+});
+```
+
+### Typescript
+
+If using typescript, `createPrompt` takes 2 generic arguments.
+
+```ts
+// createPrompt<Value, Config>
+const input = createPrompt<string, { message: string }>(// ...
+```
+
+The first one is the type of the resolved value
+
+```ts
+const answer: string = await input();
+```
+
+The second one is the type of the prompt config; in other words the interface the created prompt will provide to users.
+
+```ts
+const answer = await input({
+  message: 'My question',
+});
+```
+
+## Key utilities
+
+Listening for keypress events inside an inquirer prompt is a very common pattern. To ease this, we export a few utility functions taking in the keypress event object and return a boolean:
+
+- `isEnterKey()`
+- `isBackspaceKey()`
+- `isSpaceKey()`
+- `isUpKey()` - Note: this utility will handle vim and emacs keybindings (up, `k`, and `ctrl+p`)
+- `isDownKey()` - Note: this utility will handle vim and emacs keybindings (down, `j`, and `ctrl+n`)
+- `isNumberKey()` one of 1, 2, 3, 4, 5, 6, 7, 8, 9, 0
+
+Set `INQUIRER_KEYBINDINGS=vim`, `INQUIRER_KEYBINDINGS=emacs`, or `INQUIRER_KEYBINDINGS=vim,emacs` to enable alternative navigation keybindings globally. Prompt-level `theme.keybindings` values override the environment variable.
+
+## Theming
+
+Theming utilities will allow you to expose customization of the prompt style. Inquirer also has a few standard theme values shared across all the official prompts.
+
+To allow standard customization:
+
+```ts
+import { createPrompt, usePrefix, makeTheme, type Theme } from '@inquirer/core';
+import type { PartialDeep } from '@inquirer/type';
+
+type PromptConfig = {
+  theme?: PartialDeep<Theme>;
+};
+
+export default createPrompt<string, PromptConfig>((config, done) => {
+  const theme = makeTheme(config.theme);
+
+  const prefix = usePrefix({ status, theme });
+
+  return `${prefix} ${theme.style.highlight('hello')}`;
+});
+```
+
+To setup a custom theme:
+
+```ts
+import { createPrompt, makeTheme, type Theme } from '@inquirer/core';
+import type { PartialDeep } from '@inquirer/type';
+
+type PromptTheme = {};
+
+const promptTheme: PromptTheme = {
+  icon: '!',
+};
+
+type PromptConfig = {
+  theme?: PartialDeep<Theme<PromptTheme>>;
+};
+
+export default createPrompt<string, PromptConfig>((config, done) => {
+  const theme = makeTheme(promptTheme, config.theme);
+
+  const prefix = usePrefix({ status, theme });
+
+  return `${prefix} ${theme.icon}`;
+});
+```
+
+The [default theme keys cover](https://github.com/SBoudrias/Inquirer.js/blob/main/packages/core/src/lib/theme.ts):
+
+```ts
+type DefaultTheme = {
+  prefix: string | { idle: string; done: string };
+  spinner: {
+    interval: number;
+    frames: string[];
+  };
+  keybindings: readonly ('emacs' | 'vim')[];
+  style: {
+    answer: (text: string) => string;
+    message: (text: string, status: 'idle' | 'done' | 'loading') => string;
+    error: (text: string) => string;
+    defaultAnswer: (text: string) => string;
+    help: (text: string) => string;
+    highlight: (text: string) => string;
+    key: (text: string) => string;
+  };
+};
+```
+
+# Examples
+
+You can refer to any `@inquirer/prompts` prompts for real examples:
+
+- [Confirm Prompt](https://github.com/SBoudrias/Inquirer.js/blob/main/packages/confirm/src/index.ts)
+- [Input Prompt](https://github.com/SBoudrias/Inquirer.js/blob/main/packages/input/src/index.ts)
+- [Password Prompt](https://github.com/SBoudrias/Inquirer.js/blob/main/packages/password/src/index.ts)
+- [Editor Prompt](https://github.com/SBoudrias/Inquirer.js/blob/main/packages/editor/src/index.ts)
+- [Select Prompt](https://github.com/SBoudrias/Inquirer.js/blob/main/packages/select/src/index.ts)
+- [Checkbox Prompt](https://github.com/SBoudrias/Inquirer.js/blob/main/packages/checkbox/src/index.ts)
+- [Rawlist Prompt](https://github.com/SBoudrias/Inquirer.js/blob/main/packages/rawlist/src/index.ts)
+- [Expand Prompt](https://github.com/SBoudrias/Inquirer.js/blob/main/packages/expand/src/index.ts)
+
+```ts
+import { styleText } from 'node:util';
+import {
+  createPrompt,
+  useState,
+  useKeypress,
+  isEnterKey,
+  usePrefix,
+  type Status,
+} from '@inquirer/core';
+
+const confirm = createPrompt<boolean, { message: string; default?: boolean }>(
+  (config, done) => {
+    const [status, setStatus] = useState<Status>('idle');
+    const [value, setValue] = useState('');
+    const prefix = usePrefix({});
+
+    useKeypress((key, rl) => {
+      if (isEnterKey(key)) {
+        const answer = value ? /^y(es)?/i.test(value) : config.default !== false;
+        setValue(answer ? 'yes' : 'no');
+        setStatus('done');
+        done(answer);
+      } else {
+        setValue(rl.line);
+      }
+    });
+
+    let formattedValue = value;
+    let defaultValue = '';
+    if (status === 'done') {
+      formattedValue = styleText('cyan', value);
+    } else {
+      defaultValue = styleText('dim', config.default === false ? ' (y/N)' : ' (Y/n)');
+    }
+
+    const message = styleText('bold', config.message);
+    return `${prefix} ${message}${defaultValue} ${formattedValue}`;
+  },
+);
+
+/**
+ *  Which then can be used like this:
+ */
+const answer = await confirm({ message: 'Do you want to continue?' });
+```
+
+# License
+
+Copyright (c) 2023 Simon Boudrias (twitter: [@vaxilart](https://twitter.com/Vaxilart))<br/>
+Licensed under the MIT license.

package/node_modules/@inquirer/core/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { isUpKey, isDownKey, isSpaceKey, isBackspaceKey, isTabKey, isNumberKey, isEnterKey, isShiftKey, type KeypressEvent, type Keybinding, } from './lib/key.ts';
+export * from './lib/errors.ts';
+export { usePrefix } from './lib/use-prefix.ts';
+export { useState } from './lib/use-state.ts';
+export { useEffect } from './lib/use-effect.ts';
+export { useMemo } from './lib/use-memo.ts';
+export { useRef } from './lib/use-ref.ts';
+export { useKeypress } from './lib/use-keypress.ts';
+export { makeTheme } from './lib/make-theme.ts';
+export type { Theme, Status } from './lib/theme.ts';
+export { usePagination } from './lib/pagination/use-pagination.ts';
+export { createPrompt } from './lib/create-prompt.ts';
+export { Separator } from './lib/Separator.ts';

package/node_modules/@inquirer/core/dist/index.js

@@ -0,0 +1,12 @@
+export { isUpKey, isDownKey, isSpaceKey, isBackspaceKey, isTabKey, isNumberKey, isEnterKey, isShiftKey, } from "./lib/key.js";
+export * from "./lib/errors.js";
+export { usePrefix } from "./lib/use-prefix.js";
+export { useState } from "./lib/use-state.js";
+export { useEffect } from "./lib/use-effect.js";
+export { useMemo } from "./lib/use-memo.js";
+export { useRef } from "./lib/use-ref.js";
+export { useKeypress } from "./lib/use-keypress.js";
+export { makeTheme } from "./lib/make-theme.js";
+export { usePagination } from "./lib/pagination/use-pagination.js";
+export { createPrompt } from "./lib/create-prompt.js";
+export { Separator } from "./lib/Separator.js";

package/node_modules/@inquirer/core/dist/lib/Separator.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Separator object
+ * Used to space/separate choices group
+ */
+export declare class Separator {
+    readonly separator: string;
+    readonly type: string;
+    constructor(separator?: string);
+    static isSeparator(choice: unknown): choice is Separator;
+}

package/node_modules/@inquirer/core/dist/lib/Separator.js

@@ -0,0 +1,21 @@
+import { styleText } from 'node:util';
+import figures from '@inquirer/figures';
+/**
+ * Separator object
+ * Used to space/separate choices group
+ */
+export class Separator {
+    separator = styleText('dim', Array.from({ length: 15 }).join(figures.line));
+    type = 'separator';
+    constructor(separator) {
+        if (separator) {
+            this.separator = separator;
+        }
+    }
+    static isSeparator(choice) {
+        return Boolean(choice &&
+            typeof choice === 'object' &&
+            'type' in choice &&
+            choice.type === 'separator');
+    }
+}

package/node_modules/@inquirer/core/dist/lib/create-prompt.d.ts

@@ -0,0 +1,4 @@
+import { type Prompt, type Prettify } from '@inquirer/type';
+type ViewFunction<Value, Config> = (config: Prettify<Config>, done: (value: Value) => void) => string | [string, string | undefined];
+export declare function createPrompt<Value, Config>(view: ViewFunction<Value, Config>): Prompt<Value, Config>;
+export {};

package/node_modules/@inquirer/core/dist/lib/create-prompt.js

@@ -0,0 +1,165 @@
+import * as readline from 'node:readline';
+import { AsyncResource } from 'node:async_hooks';
+import MuteStream from 'mute-stream';
+import { onExit as onSignalExit } from 'signal-exit';
+import ScreenManager from "./screen-manager.js";
+import { PromisePolyfill } from "./promise-polyfill.js";
+import { withHooks, effectScheduler } from "./hook-engine.js";
+import { AbortPromptError, CancelPromptError, ExitPromptError } from "./errors.js";
+import path from 'node:path';
+// Capture the real setImmediate at module load time so it works even when test
+// frameworks mock timers with vi.useFakeTimers() or similar.
+const nativeSetImmediate = globalThis.setImmediate;
+function getCallSites() {
+    // oxlint-disable-next-line typescript/unbound-method
+    const savedPrepareStackTrace = Error.prepareStackTrace;
+    let result = [];
+    try {
+        Error.prepareStackTrace = (_, callSites) => {
+            const callSitesWithoutCurrent = callSites.slice(1);
+            result = callSitesWithoutCurrent;
+            return callSitesWithoutCurrent;
+        };
+        // oxlint-disable-next-line no-unused-expressions
+        new Error().stack;
+    }
+    catch {
+        // An error will occur if the Node flag --frozen-intrinsics is used.
+        // https://nodejs.org/api/cli.html#--frozen-intrinsics
+        return result;
+    }
+    Error.prepareStackTrace = savedPrepareStackTrace;
+    return result;
+}
+export function createPrompt(view) {
+    const callSites = getCallSites();
+    const prompt = (config, context = {}) => {
+        // Default `input` to stdin
+        const { input = process.stdin, signal } = context;
+        const cleanups = new Set();
+        // Add mute capabilities to the output
+        const output = new MuteStream();
+        output.pipe(context.output ?? process.stdout);
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
+        const rl = readline.createInterface({
+            terminal: true,
+            input,
+            output,
+        });
+        // Mute the output after readline has initialized so readline can perform
+        // any terminal setup writes (e.g. Windows Console API initialization)
+        // before suppressing output. ScreenManager will unmute/mute around each
+        // render call as needed.
+        output.mute();
+        const screen = new ScreenManager(rl);
+        const { promise, resolve, reject } = PromisePolyfill.withResolver();
+        const cancel = () => reject(new CancelPromptError());
+        if (signal) {
+            const abort = () => reject(new AbortPromptError({ cause: signal.reason }));
+            if (signal.aborted) {
+                abort();
+                return Object.assign(promise, { cancel });
+            }
+            signal.addEventListener('abort', abort);
+            cleanups.add(() => signal.removeEventListener('abort', abort));
+        }
+        cleanups.add(onSignalExit((code, signal) => {
+            reject(new ExitPromptError(`User force closed the prompt with ${code} ${signal}`));
+        }));
+        // SIGINT must be explicitly handled by the prompt so the ExitPromptError can be handled.
+        // Otherwise, the prompt will stop and in some scenarios never resolve.
+        // Ref issue #1741
+        const sigint = () => reject(new ExitPromptError(`User force closed the prompt with SIGINT`));
+        rl.on('SIGINT', sigint);
+        cleanups.add(() => rl.removeListener('SIGINT', sigint));
+        return withHooks(rl, (cycle) => {
+            // The close event triggers immediately when the user press ctrl+c. SignalExit on the other hand
+            // triggers after the process is done (which happens after timeouts are done triggering.)
+            // We triggers the hooks cleanup phase on rl `close` so active timeouts can be cleared.
+            const hooksCleanup = AsyncResource.bind(() => effectScheduler.clearAll());
+            rl.on('close', hooksCleanup);
+            cleanups.add(() => rl.removeListener('close', hooksCleanup));
+            const startCycle = () => {
+                // Re-renders only happen when the state change; but the readline cursor could
+                // change position and that also requires a re-render (and a manual one because
+                // we mute the streams). We set the listener after the initial workLoop to avoid
+                // a double render if render triggered by a state change sets the cursor to the
+                // right position.
+                const checkCursorPos = () => screen.checkCursorPos();
+                rl.input.on('keypress', checkCursorPos);
+                cleanups.add(() => rl.input.removeListener('keypress', checkCursorPos));
+                let pendingDone = null;
+                cycle(() => {
+                    let effectsSettled = false;
+                    try {
+                        const nextView = view(config, (value) => {
+                            if (effectsSettled) {
+                                // After the cycle completes (async validation path), the "done"
+                                // render already flushed via setStatus → handleChange, so resolve
+                                // immediately.
+                                resolve(value);
+                            }
+                            else {
+                                pendingDone = { value };
+                            }
+                        });
+                        // Typescript won't allow this, but not all users rely on typescript.
+                        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+                        if (nextView === undefined) {
+                            let callerFilename = callSites[1]?.getFileName();
+                            if (callerFilename && !callerFilename.startsWith('file://')) {
+                                callerFilename = path.resolve(callerFilename);
+                            }
+                            throw new Error(`Prompt functions must return a string.\n    at ${callerFilename}`);
+                        }
+                        const [content, bottomContent] = typeof nextView === 'string' ? [nextView] : nextView;
+                        screen.render(content, bottomContent);
+                        effectScheduler.run();
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                    effectsSettled = true;
+                    if (pendingDone !== null) {
+                        const { value } = pendingDone;
+                        pendingDone = null;
+                        resolve(value);
+                    }
+                });
+            };
+            // Proper Readable streams (like process.stdin) may have OS-level buffered
+            // data that arrives in the poll phase when readline resumes the stream.
+            // Deferring the first render by one setImmediate tick (check phase, after
+            // poll) lets that stale data flow through readline harmlessly—no keypress
+            // handlers are registered yet and the output is muted, so the stale
+            // keystrokes are silently discarded.
+            // Old-style streams (like MuteStream) have no such buffering, so the
+            // render cycle starts immediately.
+            //
+            // @see https://github.com/SBoudrias/Inquirer.js/issues/1303
+            if ('readableFlowing' in input) {
+                nativeSetImmediate(startCycle);
+            }
+            else {
+                startCycle();
+            }
+            return Object.assign(promise
+                .then((answer) => {
+                effectScheduler.clearAll();
+                return answer;
+            }, (error) => {
+                effectScheduler.clearAll();
+                throw error;
+            })
+                // Wait for the promise to settle, then cleanup.
+                .finally(() => {
+                cleanups.forEach((cleanup) => cleanup());
+                screen.done({ clearContent: Boolean(context.clearPromptOnDone) });
+                output.end();
+            })
+                // Once cleanup is done, let the expose promise resolve/reject to the internal one.
+                .then(() => promise), { cancel });
+        });
+    };
+    return prompt;
+}

package/node_modules/@inquirer/core/dist/lib/errors.d.ts

@@ -0,0 +1,20 @@
+export declare class AbortPromptError extends Error {
+    name: string;
+    message: string;
+    constructor(options?: {
+        cause?: unknown;
+    });
+}
+export declare class CancelPromptError extends Error {
+    name: string;
+    message: string;
+}
+export declare class ExitPromptError extends Error {
+    name: string;
+}
+export declare class HookError extends Error {
+    name: string;
+}
+export declare class ValidationError extends Error {
+    name: string;
+}

package/node_modules/@inquirer/core/dist/lib/errors.js

@@ -0,0 +1,21 @@
+export class AbortPromptError extends Error {
+    name = 'AbortPromptError';
+    message = 'Prompt was aborted';
+    constructor(options) {
+        super();
+        this.cause = options?.cause;
+    }
+}
+export class CancelPromptError extends Error {
+    name = 'CancelPromptError';
+    message = 'Prompt was canceled';
+}
+export class ExitPromptError extends Error {
+    name = 'ExitPromptError';
+}
+export class HookError extends Error {
+    name = 'HookError';
+}
+export class ValidationError extends Error {
+    name = 'ValidationError';
+}

package/node_modules/@inquirer/core/dist/lib/hook-engine.d.ts

@@ -0,0 +1,23 @@
+import type { InquirerReadline } from '@inquirer/type';
+export declare function withHooks<T>(rl: InquirerReadline, cb: (cycle: (render: () => void) => void) => T): T;
+export declare function readline(): InquirerReadline;
+export declare function withUpdates<Args extends unknown[], R>(fn: (...args: Args) => R): (...args: Args) => R;
+type SetPointer<Value> = {
+    get(): Value;
+    set(value: Value): void;
+    initialized: true;
+};
+type UnsetPointer<Value> = {
+    get(): void;
+    set(value: Value): void;
+    initialized: false;
+};
+type Pointer<Value> = SetPointer<Value> | UnsetPointer<Value>;
+export declare function withPointer<Value, ReturnValue>(cb: (pointer: Pointer<Value>) => ReturnValue): ReturnValue;
+export declare function handleChange(): void;
+export declare const effectScheduler: {
+    queue(cb: (readline: InquirerReadline) => void | (() => void)): void;
+    run(): void;
+    clearAll(): void;
+};
+export {};