@levu/snap 0.3.11 → 0.3.13

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.13] - 2026-03-05
+
+### Changed
+- TUI prompt cancellation (`Esc`) now defaults to step-back behavior when the workflow has a previous step; when already at the first/root step, cancel still exits.
+- Runtime engine now maps root prompt-cancel to exit code `130` (`INTERRUPTED`) instead of internal error.
+- Added prompt lifecycle hooks in `createPromptToolkit` to support cancel/retry navigation handling.
+
+### Added
+- Added regression tests for prompt retry/cancel lifecycle handling and runtime retry/interrupted behavior.
+
+## [0.3.12] - 2026-03-04
+
+### Fixed
+- Added missing runtime dependency `picocolors` to prevent `ERR_MODULE_NOT_FOUND` when consuming password/multiline adapters from published packages.
+- Improved password prompt stability with a raw-mode terminal path to reduce cursor/glyph jitter in interactive input.
+- Added password adapter regression tests and updated component reference keyboard behavior notes.
+
 ## [0.3.11] - 2026-02-28
 
 ### Fixed

package/README.md

@@ -21,6 +21,7 @@ For module/tool authors, Snap also exposes optional DX helper groups:
 - Uses Clack-powered prompt adapters for interactive TUI (`select`, `text`, `confirm`, `multiselect`)
 - Text prompts support clipboard paste and multiline input for pasting multiple lines
 - Supports workflow transitions: `next`, `back`, `jump`, `exit`
+- In TUI mode, pressing `Esc` backs to the previous workflow step by default; pressing `Esc` on the root step exits.
 - Supports resume checkpoints for interrupted flows
 - Produces stable help output hierarchy:
   - `snap -h`

package/dist/runtime/engine.js

@@ -1,6 +1,7 @@
 import { ExitCode } from '../core/errors/framework-errors.js';
 import { createFlowController } from '../dx/runtime/index.js';
 import { createTerminalOutput } from '../dx/terminal/index.js';
+import { isPromptCancelledError, isPromptRetryError } from '../tui/component-adapters/cancel.js';
 import { createPromptToolkit } from '../tui/prompt-toolkit.js';
 import { StateMachine } from './state-machine.js';
 const resolveWorkflowNodes = (action) => {
@@ -36,20 +37,56 @@ export const executeAction = async (input) => {
         args: input.args,
         flow: createFlowController(stateMachine),
         terminal: createTerminalOutput(),
-        prompts: createPromptToolkit(),
+        prompts: createPromptToolkit({
+            onPromptResolved: () => {
+                if (input.mode !== 'tui')
+                    return;
+                stateMachine.transition({ type: 'next' });
+            },
+            onPromptCancelled: () => {
+                if (input.mode !== 'tui')
+                    return 'cancel';
+                if (stateMachine.snapshot().cursor <= 0)
+                    return 'cancel';
+                stateMachine.transition({ type: 'back' });
+                return 'retry';
+            }
+        }),
         stateMachine
     };
     try {
-        const result = await input.action.run(context);
-        if (input.resumeStore) {
-            if (stateMachine.snapshot().exited || result.ok) {
-                await input.resumeStore.clear();
+        while (true) {
+            let result;
+            try {
+                result = await input.action.run(context);
+            }
+            catch (error) {
+                if (isPromptRetryError(error)) {
+                    continue;
+                }
+                if (isPromptCancelledError(error)) {
+                    if (input.resumeStore) {
+                        await input.resumeStore.clear();
+                    }
+                    return {
+                        ok: false,
+                        mode: input.mode,
+                        exitCode: ExitCode.INTERRUPTED,
+                        errorMessage: undefined
+                    };
+                }
+                throw error;
             }
-            else {
-                await input.resumeStore.save(stateMachine.checkpoint());
+            if (input.resumeStore) {
+                if (stateMachine.snapshot().exited || result.ok) {
+                    await input.resumeStore.clear();
+                }
+                else {
+                    await input.resumeStore.save(stateMachine.checkpoint());
+                }
             }
+            return { ...result, mode: input.mode, exitCode: result.exitCode ?? ExitCode.SUCCESS };
         }
-        return { ...result, mode: input.mode, exitCode: result.exitCode ?? ExitCode.SUCCESS };
     }
     catch (error) {
         if (input.resumeStore) {

package/dist/tui/component-adapters/cancel.d.ts

@@ -2,5 +2,10 @@ export declare class PromptCancelledError extends Error {
     readonly isPromptCancelled = true;
     constructor(message?: string);
 }
+export declare class PromptRetryError extends Error {
+    readonly isPromptRetry = true;
+    constructor(message?: string);
+}
 export declare const isPromptCancelledError: (error: unknown) => error is PromptCancelledError;
+export declare const isPromptRetryError: (error: unknown) => error is PromptRetryError;
 export declare const unwrapClackResult: <T>(value: T | symbol, cancelMessage?: string) => T;

package/dist/tui/component-adapters/cancel.js

@@ -6,12 +6,25 @@ export class PromptCancelledError extends Error {
         this.name = 'PromptCancelledError';
     }
 }
+export class PromptRetryError extends Error {
+    isPromptRetry = true;
+    constructor(message = 'Retry prompt workflow.') {
+        super(message);
+        this.name = 'PromptRetryError';
+    }
+}
 export const isPromptCancelledError = (error) => {
     return error instanceof PromptCancelledError || (typeof error === 'object' &&
         error !== null &&
         'isPromptCancelled' in error &&
         error.isPromptCancelled === true);
 };
+export const isPromptRetryError = (error) => {
+    return error instanceof PromptRetryError || (typeof error === 'object' &&
+        error !== null &&
+        'isPromptRetry' in error &&
+        error.isPromptRetry === true);
+};
 export const unwrapClackResult = (value, cancelMessage = 'Cancelled by user.') => {
     if (isCancel(value)) {
         throw new PromptCancelledError(cancelMessage);

package/dist/tui/prompt-toolkit.d.ts

@@ -3,6 +3,7 @@ import type { GroupStep } from './component-adapters/group.js';
 import type { MultiSelectPromptInput } from './component-adapters/multiselect.js';
 import type { SelectPromptInput } from './component-adapters/select.js';
 import type { TextPromptInput } from './component-adapters/text.js';
+import { PromptCancelledError } from './component-adapters/cancel.js';
 import { type CustomPromptInput } from './custom/custom-prompt.js';
 export interface PromptToolkit {
     text(input: TextPromptInput): Promise<string>;
@@ -12,4 +13,19 @@ export interface PromptToolkit {
     group<T = unknown>(steps: GroupStep<T>[]): Promise<Record<string, T>>;
     custom<T>(input: CustomPromptInput<T>): Promise<T>;
 }
-export declare const createPromptToolkit: () => PromptToolkit;
+export type PromptCancelDecision = 'cancel' | 'retry';
+interface PromptToolkitAdapters {
+    text: (input: TextPromptInput) => Promise<string>;
+    confirm: (input: ConfirmPromptInput) => Promise<boolean>;
+    select: (input: SelectPromptInput) => Promise<string>;
+    multiselect: (input: MultiSelectPromptInput) => Promise<string[]>;
+    group: <T = unknown>(steps: GroupStep<T>[]) => Promise<Record<string, T>>;
+    custom: <T>(input: CustomPromptInput<T>) => Promise<T>;
+}
+export interface PromptToolkitOptions {
+    onPromptResolved?: () => void | Promise<void>;
+    onPromptCancelled?: (error: PromptCancelledError) => PromptCancelDecision | void | Promise<PromptCancelDecision | void>;
+    adapters?: Partial<PromptToolkitAdapters>;
+}
+export declare const createPromptToolkit: (options?: PromptToolkitOptions) => PromptToolkit;
+export {};

package/dist/tui/prompt-toolkit.js

@@ -3,15 +3,42 @@ import { runGroupPrompt } from './component-adapters/group.js';
 import { runMultiSelectPrompt } from './component-adapters/multiselect.js';
 import { runSelectPrompt } from './component-adapters/select.js';
 import { runTextPrompt } from './component-adapters/text.js';
+import { isPromptCancelledError, PromptRetryError } from './component-adapters/cancel.js';
 import { createCustomPromptRunner } from './custom/custom-prompt.js';
-export const createPromptToolkit = () => {
+const withPromptLifecycle = (runner, options) => {
+    return async (input) => {
+        try {
+            const value = await runner(input);
+            await options.onPromptResolved?.();
+            return value;
+        }
+        catch (error) {
+            if (isPromptCancelledError(error)) {
+                const decision = await options.onPromptCancelled?.(error);
+                if (decision === 'retry') {
+                    throw new PromptRetryError();
+                }
+            }
+            throw error;
+        }
+    };
+};
+export const createPromptToolkit = (options = {}) => {
     const customRunner = createCustomPromptRunner();
+    const adapters = {
+        text: options.adapters?.text ?? runTextPrompt,
+        confirm: options.adapters?.confirm ?? runConfirmPrompt,
+        select: options.adapters?.select ?? runSelectPrompt,
+        multiselect: options.adapters?.multiselect ?? runMultiSelectPrompt,
+        group: options.adapters?.group ?? runGroupPrompt,
+        custom: options.adapters?.custom ?? customRunner.run
+    };
     return {
-        text: runTextPrompt,
-        confirm: runConfirmPrompt,
-        select: runSelectPrompt,
-        multiselect: runMultiSelectPrompt,
-        group: runGroupPrompt,
-        custom: customRunner.run
+        text: withPromptLifecycle(adapters.text, options),
+        confirm: withPromptLifecycle(adapters.confirm, options),
+        select: withPromptLifecycle(adapters.select, options),
+        multiselect: withPromptLifecycle(adapters.multiselect, options),
+        group: withPromptLifecycle(adapters.group, options),
+        custom: withPromptLifecycle(adapters.custom, options)
     };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@levu/snap",
-  "version": "0.3.11",
+  "version": "0.3.13",
   "type": "module",
   "bin": {
     "snap": "./dist/cli-entry.js"
@@ -12,7 +12,8 @@
     "dev": "tsx src/cli-entry.ts"
   },
   "dependencies": {
-    "@clack/prompts": "^1.0.0"
+    "@clack/prompts": "^1.0.0",
+    "picocolors": "^1.1.1"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",