@havocrao/picktui 0.1.0 → 0.1.1

package/dist/types/model.d.ts

@@ -0,0 +1,48 @@
+import type { Candidate, FilterOptions } from './types.js';
+export declare function setColorEnabled(v: boolean): void;
+export declare function isColorEnabled(): boolean;
+/** 过滤选择器配置。 */
+export interface ModelOpts {
+    title: string;
+    subtitle?: string;
+    cands: Candidate[];
+    query: string;
+    filterOpts: FilterOptions;
+    initial: number;
+    jumpKeys: boolean;
+    statusHint: string;
+    multi: boolean;
+    selected: string[];
+}
+/** TUI 状态（不可变更新）。 */
+export interface UiModel {
+    opts: ModelOpts;
+    filtered: Candidate[];
+    query: string;
+    cursor: number;
+    scrollY: number;
+    height: number;
+    width: number;
+    phase: number;
+    cancelled: boolean;
+    quit: boolean;
+    selected: Set<string>;
+}
+/** 按键（数字 '1'...'9'、字母等作为字符串传入）。 */
+export type KeyLike = string | {
+    type: 'char';
+    value: string;
+};
+export declare function newModel(opts: ModelOpts): UiModel;
+/** 多选模式：按 Cands 顺序返回勾选的 Value 列表。 */
+export declare function selectedValues(m: UiModel): string[];
+/** 处理一个按键，返回新模型（不可变；变化时替换字段）。 */
+export declare function update(m: UiModel, key: KeyLike): UiModel;
+/** 渲染整屏画面（带 ANSI 样式）。 */
+export declare function view(m: UiModel): string;
+/** 按显示宽度截断 s，超长末尾补 …。 */
+export declare function truncateWidth(s: string, maxWidth: number): string;
+/** 字符显示宽度（简化 wcwidth：CJK/全角=2，控制符=0，其余=1）。 */
+export declare function charWidth(ch: string): number;
+/** 字符串显示宽度。 */
+export declare function displayWidth(s: string): number;

package/dist/types/toml.d.ts

@@ -0,0 +1,24 @@
+/**
+ * toml — 极简 TOML 子集解析/编码（仅覆盖 history.toml / confirm.toml 所需结构）。
+ *
+ * 兼容 Go 引擎（BurntSushi/toml）写出的文件：
+ *   - 注释行（# …）、空行
+ *   - 表头 `[table]` / `["quoted key"]`
+ *   - `key = "string"`（含基本字符串转义 \n \t \" \\ \r \b \f \uXXXX）
+ *   - `"label" = ["a", "b"]`（字符串数组）
+ * 值仅支持 string / string[]——本包状态文件所需的最小类型集。
+ */
+export type TomlValue = string | string[];
+/** 解析结果：表名 → { key: 值 }（保持文件内出现顺序）。 */
+export type TomlDoc = Map<string, Map<string, TomlValue>>;
+/** 转义字符串内容（写入值时用）。 */
+export declare function escapeTomlString(s: string): string;
+/** 带引号的字符串字面量（含转义）。 */
+export declare function quoteTomlString(s: string): string;
+/** 表头/键名编码：裸 key 直接输出，否则带引号。 */
+export declare function keyLiteral(key: string): string;
+/**
+ * 解析 TOML 子集。无法解析的行跳过（容错：状态文件损坏不阻断主流程）。
+ * 无任何可解析内容时返回 null。
+ */
+export declare function parseToml(text: string): TomlDoc | null;

package/dist/types/tty.d.ts

@@ -0,0 +1,42 @@
+import { ReadStream, WriteStream } from 'node:tty';
+/** 交互终端句柄。 */
+export interface Tty {
+    read: ReadStream;
+    write: WriteStream;
+    /** 终端尺寸（列）。 */
+    columns: number;
+    /** 终端尺寸（行）。 */
+    rows: number;
+}
+/** 按键（对齐引擎 model 的键位集合；数字作为字符处理）。 */
+export type Key = 'enter' | 'esc' | 'up' | 'down' | 'tab' | 'backspace' | 'ctrl+u' | 'ctrl+w' | 'ctrl+c' | 'ctrl+p' | 'ctrl+n' | 'space' | {
+    type: 'char';
+    value: string;
+};
+/** 尝试打开交互终端；不可用返回 null（调用方退化为非交互）。 */
+export declare function openTty(): Tty | null;
+/** 进入交互模式：备用屏幕 + 隐藏光标 + raw input。 */
+export declare function enterInteractive(tty: Tty): void;
+/** 退出交互模式：恢复原始终端状态。 */
+export declare function exitInteractive(tty: Tty): void;
+/** 全量重绘一帧画面。 */
+export declare function renderFrame(tty: Tty, frame: string): void;
+/** 单行确认询问（auto 首次确认）：canonical 输入整行 y/N，超时默认拒绝。 */
+export declare function promptConfirm(tty: Tty, text: string, timeoutMs?: number): Promise<string | null>;
+/**
+ * KeyReader — raw 输入流 → 按键序列解析。
+ *
+ * 支持：ASCII 字符、UTF-8 多字节字符、回车/退格/控制键、CSI 序列
+ * （\x1b[A 上、\x1b[B 下、\x1b[C 右、\x1b[D 左）。
+ */
+export declare class KeyReader {
+    private decoder;
+    private buf;
+    private waiters;
+    private closed;
+    constructor(readStream: ReadStream);
+    /** 取下一个按键；流关闭返回 null。 */
+    next(): Promise<Key | null>;
+    private pumpEnd;
+    private pump;
+}

package/dist/types/tui.d.ts

@@ -1,23 +1,35 @@
+import { type UiModel } from './model.js';
+import { type Tty } from './tty.js';
 import type { Candidate, PickFlags } from './types.js';
+/** 非交互开关环境变量（值为 "off" 时 pick 跳过 TUI）。 */
+export declare const OFF_ENV = "PICKTUI_PICK";
 /**
  * pick — 交互过滤选择（fzf 风格）。
  *
- * @param cands 候选（经 stdin 传入，与位置参数等价且无 argv 长度限制）
- * @param flags 透传引擎 flags（query/label/sep/fuzzy/select1/auto）
- * @returns 选中值；用户取消（esc/ctrl+c，退出码 130）返回 null
+ * @param cands 候选（不传时从宿主 stdin 管道读取）
+ * @param flags query/label/sep/fuzzy/select1/auto
+ * @returns 选中值；用户取消（esc/ctrl+c）返回 null
  */
 export declare function pick(cands?: (string | Candidate)[], flags?: PickFlags): Promise<string | null>;
 /**
  * menu — 多值缩写 TUI 菜单（数字 1-9 直选）。
- *
- * @param label 菜单标题与选择记忆键
- * @param cands 候选（经位置参数传入，注意 argv 长度限制；超长场景用 pick）
- * @returns 选中值；取消返回 null
+ * @returns 选中值；取消返回 null；参数不足抛 PicktuiError（退出码 2）
  */
 export declare function menu(label: string, cands: string[]): Promise<string | null>;
 /**
- * rawPick — 透传任意引擎 pick 参数（--from/--map 等绑定未包装的 flags）。
- *
+ * rawPick — 透传引擎 pick 参数（--from/--map/-q/--label/--sep/--fuzzy/-1/--auto）。
  * @example rawPick(['--from', 'git branch', '--label', 'git co', '-1'])
  */
 export declare function rawPick(args: string[]): Promise<string | null>;
+/** 在 tty 上运行 TUI 选择器，返回（取消, 选中值, 多选勾选）。 */
+export declare function runTui(model: UiModel, tty: Tty): Promise<{
+    cancelled: boolean;
+    value: string;
+    selected: string[];
+}>;
+/**
+ * 扫描 mapper 命令，识别"解释器 + 脚本路径"形态，返回第一个不存在的脚本文件路径。
+ * 保守策略：跳过 flags/引号/变量/管道等 shell 语法，只检查形如路径的 token
+ * （/ ./ ../ ~/ 前缀、带常见脚本扩展名），避免误拦 node -e / python3 -m 等合法用法。
+ */
+export declare function mapperScriptMissing(mapper: string): string;

package/dist/types/types.d.ts

@@ -52,10 +52,3 @@ export declare class PicktuiError extends Error {
 export interface ResolveResult {
     value: string;
 }
-/** 引擎 version 输出（"picktui <semver>"）。 */
-export interface EngineVersion {
-    /** 完整输出行，如 "picktui 0.1.0"。 */
-    raw: string;
-    /** 语义化版本号，如 "0.1.0"。 */
-    version: string;
-}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@havocrao/picktui",
-  "version": "0.1.0",
-  "description": "TUI candidate picker — TS/JS bindings for the picktui engine (protocol v1). Filter / pick / history / confirm, tree-shakable, same behavior as the Go engine.",
+  "version": "0.1.1",
+  "description": "TUI candidate picker — pure TypeScript implementation. Filter / pick / history / confirm, zero runtime dependencies, same semantics as the Go engine (no binary required).",
   "license": "MIT",
   "author": "havoc-rao",
   "keywords": [
@@ -59,7 +59,7 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node scripts/fixup.mjs",
-    "pretest": "node scripts/build-engine.mjs",
+    "pretest": "npm run build",
     "test": "node --test \"test/*.test.mjs\"",
     "test:pack": "npm run build && node scripts/test-pack.mjs",
     "prepack": "npm run build"
@@ -68,4 +68,4 @@
     "@types/node": "^26.4.1",
     "typescript": "^5.5.0"
   }
-}
+}