@havocrao/picktui 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @havocrao/picktui — TS/JS 绑定
+
+薄绑定：只做「候选传入、结果取回」，渲染/按键/匹配全部在 Go 引擎
+（`../go/cmd/picktui`）内完成，效果与 Go 宿主逐像素一致。
+同份源码构建 esm + cjs + d.ts，TS 与 JS 共用。
+
+## 安装
+
+```console
+$ npm install @havocrao/picktui
+```
+
+引擎发现顺序：`$PICKTUI_BIN` → `$PATH` 中的 `picktui`。交互 TUI 由引擎跑在
+`/dev/tty`，本包 stdout 只回选中值。无 TTY 时引擎自动退化
+（无 query 取首个、有 query 过滤取首），绑定无需分支；
+取消（esc/ctrl+c）返回 `null`；协议错误抛出 `PicktuiError`（含 exitCode/stderr）。
+
+## API
+
+```ts
+import { filter, resolve } from '@havocrao/picktui/filter'
+import { pick, menu, rawPick } from '@havocrao/picktui/tui'
+import { histGet, histSet } from '@havocrao/picktui/history'
+import { confirmCheck, confirmAdd } from '@havocrao/picktui/confirm'
+import type { Candidate, FilterOptions, FilteredCandidate, PickFlags } from '@havocrao/picktui/types'
+import { engineVersion, assertEngineVersion } from '@havocrao/picktui'
+```
+
+| 函数 | 说明 |
+|---|---|
+| `filter(cands, query?, opts?)` | 过滤 + 高亮区间（ranges 为 rune 区间，空查询恒 `[]`） |
+| `resolve(cands, query)` | 精确/唯一前缀解析；无唯一解返回 `null` |
+| `pick(cands?, flags?)` | 交互过滤选择；`flags` 透传 `-q/--label/--sep/--fuzzy/-1/--auto` |
+| `menu(label, cands)` | 多值缩写菜单（数字 1-9 直选） |
+| `rawPick([...args])` | 透传引擎 pick 参数（`--from`/`--map` 等） |
+| `histGet(label)` / `histSet(label, value)` | 选择记忆 |
+| `confirmCheck` / `confirmAdd` | 自动匹配首次确认（add 幂等） |
+| `assertEngineVersion(min?)` | 校验引擎版本不低于绑定声明的最低版本 |
+
+## 开发
+
+```console
+$ npm install            # 安装 devDependencies（typescript）
+$ npm run build          # tsc 双输出：dist/esm + dist/cjs + dist/types
+$ npm test               # pretest 自动构建引擎二进制 → node:test 集成测试
+$ npm run test:pack      # npm pack → 干净目录安装 → import/require 冒烟
+```
+
+测试均为对真实引擎二进制的 JSON 往返（无 TTY 依赖）。交互 TUI 路径
+由引擎侧 model 级测试覆盖。

package/dist/cjs/confirm.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.confirmCheck = confirmCheck;
+exports.confirmAdd = confirmAdd;
+/**
+ * confirm — 自动匹配首次确认（文件状态，直调引擎 confirm 子命令）。
+ *
+ * 状态文件位于引擎数据目录，与 pick --auto 的确认记录同一份：
+ * 首次自动匹配某 (label, value) 需确认，确认后不再询问。
+ */
+const engine_js_1 = require("./engine.js");
+/** 报告 (label, value) 是否已被确认过。 */
+async function confirmCheck(label, value) {
+    const inv = await (0, engine_js_1.invokeEngine)(['confirm', 'check', label, value]);
+    (0, engine_js_1.assertSuccess)(inv, 'picktui confirm check');
+    const parsed = (0, engine_js_1.parseJSON)(inv.stdout, 'picktui confirm check');
+    return parsed.confirmed;
+}
+/**
+ * 记录 (label, value) 为已确认（幂等）。
+ * @returns 确认后的实际状态（label 为空时不落盘 → false）
+ */
+async function confirmAdd(label, value) {
+    const inv = await (0, engine_js_1.invokeEngine)(['confirm', 'add', label, value]);
+    (0, engine_js_1.assertSuccess)(inv, 'picktui confirm add');
+    const parsed = (0, engine_js_1.parseJSON)(inv.stdout, 'picktui confirm add');
+    return parsed.confirmed;
+}

package/dist/cjs/engine.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MIN_ENGINE_VERSION = void 0;
+exports.engineBin = engineBin;
+exports.invokeEngine = invokeEngine;
+exports.assertSuccess = assertSuccess;
+exports.parseJSON = parseJSON;
+exports.engineVersion = engineVersion;
+exports.versionAtLeast = versionAtLeast;
+exports.assertEngineVersion = assertEngineVersion;
+exports.serializeCandidates = serializeCandidates;
+/**
+ * engine — 引擎发现与进程调用（薄绑定核心，零渲染逻辑）。
+ *
+ * 引擎发现顺序（对齐 docs/integration/protocol.md）：
+ *   1. $PICKTUI_BIN
+ *   2. $PATH 中的 picktui / picktui.exe
+ *
+ * 渲染/按键/匹配全部在引擎内完成；本模块只负责 spawn + stdout/stderr 收集，
+ * 保证宿主 stdout 不被污染（交互 TUI 走引擎的 /dev/tty）。
+ */
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const types_js_1 = require("./types.js");
+/** 绑定声明的最低引擎版本（协议 v1）。 */
+exports.MIN_ENGINE_VERSION = '0.1.0';
+/** 引擎二进制名（win32 带 .exe 后缀）。 */
+function binName() {
+    return process.platform === 'win32' ? 'picktui.exe' : 'picktui';
+}
+/** 解析引擎二进制绝对路径；找不到时抛出带指引的错误。 */
+async function engineBin() {
+    const fromEnv = process.env.PICKTUI_BIN;
+    if (fromEnv) {
+        return fromEnv;
+    }
+    const name = binName();
+    const dirs = (process.env.PATH ?? '').split(node_path_1.delimiter).filter(Boolean);
+    for (const dir of dirs) {
+        const candidate = (0, node_path_1.join)(dir, name);
+        if ((0, node_fs_1.existsSync)(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error(`picktui 引擎未找到：请设置 PICKTUI_BIN 指向引擎二进制，或将 ${name} 加入 PATH。` +
+        `（引擎即本仓库 Go 模块的 cmd/picktui，` +
+        `见 README「引擎二进制」一节；` +
+        `纯数据场景可设 PICKTUI_NO_BIN=1 使用内嵌 JS 过滤实现——该实现尚未提供，请先安装引擎。）`);
+}
+/** 调用引擎子命令：数据走 stdin，结果回 stdout/stderr（无 TTY 依赖）。 */
+async function invokeEngine(args, opts = {}) {
+    const bin = await engineBin();
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const fail = (err) => {
+            if (!settled) {
+                settled = true;
+                reject(err);
+            }
+        };
+        const done = (inv) => {
+            if (!settled) {
+                settled = true;
+                resolve(inv);
+            }
+        };
+        const child = (0, node_child_process_1.spawn)(bin, args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env, ...opts.env },
+            // 引擎自身通过 /dev/tty 完成交互渲染与输入；这里不需要终端
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => (stdout += chunk));
+        child.stderr.on('data', (chunk) => (stderr += chunk));
+        child.on('error', fail);
+        child.on('close', (code) => done({ exitCode: code ?? -1, stdout, stderr }));
+        if (opts.input !== undefined) {
+            child.stdin.end(opts.input);
+        }
+        else {
+            child.stdin.end();
+        }
+    });
+}
+/** 引擎调用约定：退出码 0 成功 / 1 运行错误 / 2 用法错误 / 130 取消。 */
+function assertSuccess(inv, what) {
+    if (inv.exitCode === 0) {
+        return;
+    }
+    const detail = inv.stderr.trim() || `exit code ${inv.exitCode}`;
+    throw new types_js_1.PicktuiError(`${what}失败：${detail}`, inv.exitCode, inv.stderr);
+}
+/** 解析 stdout 为 JSON（协议输出恒为 JSON）；失败抛 PicktuiError。 */
+function parseJSON(stdout, what) {
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        throw new types_js_1.PicktuiError(`${what}输出不是合法 JSON：${stdout.slice(0, 200)}`, -1, stdout);
+    }
+}
+/** 读取引擎版本（"picktui <semver>"）。 */
+async function engineVersion() {
+    const bin = await engineBin();
+    const inv = await invokeEngine(['version']);
+    assertSuccess(inv, 'picktui version');
+    const match = /^picktui\s+(\d+\.\d+\.\d+)/.exec(inv.stdout.trim());
+    if (!match) {
+        throw new types_js_1.PicktuiError(`无法解析引擎版本：${inv.stdout.trim()}`, inv.exitCode, inv.stdout);
+    }
+    return match[1];
+}
+/** 比较两个 x.y.z 版本号：a >= b。 */
+function versionAtLeast(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x !== y) {
+            return x > y;
+        }
+    }
+    return true;
+}
+/** 校验引擎版本不低于绑定声明的最低版本；不满足时抛错。 */
+async function assertEngineVersion(min = exports.MIN_ENGINE_VERSION) {
+    const v = await engineVersion();
+    if (!versionAtLeast(v, min)) {
+        throw new types_js_1.PicktuiError(`picktui 引擎版本 ${v} 低于绑定要求的最低版本 ${min}（请升级引擎或设置 PICKTUI_BIN）`, -1, '');
+    }
+    return v;
+}
+/** 将候选列表序列化为协议结构化行（key<TAB>description）。 */
+function serializeCandidates(cands) {
+    return cands
+        .map((c) => (typeof c === 'string' ? c : c.desc ? `${c.value}\t${c.desc}` : c.value))
+        .join('\n') + '\n';
+}

package/dist/cjs/filter.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.filter = filter;
+exports.resolve = resolve;
+/**
+ * filter / resolve — 纯函数数据面（直调引擎 filter/resolve --json）。
+ *
+ * 过滤与高亮区间由引擎权威计算；本模块只做「候选传入、JSON 取回」，
+ * 禁止重实现匹配（详见 docs/integration/protocol.md 兼容性承诺）。
+ */
+const engine_js_1 = require("./engine.js");
+/** 将 FilterOptions 转为引擎参数。 */
+function modeArgs(opts) {
+    const args = [];
+    if (opts.mode && opts.mode !== 'substring') {
+        args.push('--mode', opts.mode);
+    }
+    if (opts.mode === 'token' && opts.sep) {
+        args.push('--sep', opts.sep);
+    }
+    return args;
+}
+/**
+ * filter — 过滤候选并返回命中项（保留输入顺序）+ 高亮区间。
+ *
+ * @param cands 候选（字符串或结构化 Candidate）
+ * @param query 过滤关键字（空格分词，空串返回全部）
+ * @param opts  匹配模式（默认 substring）
+ * @returns 命中候选，`ranges` 为命中的 rune 区间（空查询恒为 []）
+ */
+async function filter(cands, query = '', opts = {}) {
+    const inv = await (0, engine_js_1.invokeEngine)(['filter', '--json', '--query', query, ...modeArgs(opts)], { input: (0, engine_js_1.serializeCandidates)(cands) });
+    (0, engine_js_1.assertSuccess)(inv, 'picktui filter');
+    return (0, engine_js_1.parseJSON)(inv.stdout, 'picktui filter');
+}
+/**
+ * resolve — 把 query 解析为唯一候选（精确 → 唯一前缀，大小写不敏感前缀）。
+ *
+ * @returns 解析出的选中值；无匹配/多个前缀匹配返回 null（引擎退出码 1）
+ */
+async function resolve(cands, query, opts = {}) {
+    const inv = await (0, engine_js_1.invokeEngine)(['resolve', '--json', '--query', query, ...modeArgs(opts)], { input: (0, engine_js_1.serializeCandidates)(cands) });
+    if (inv.exitCode === 1) {
+        return null; // 协议：无唯一解 → stdout 空 + 退出码 1
+    }
+    (0, engine_js_1.assertSuccess)(inv, 'picktui resolve');
+    const parsed = (0, engine_js_1.parseJSON)(inv.stdout, 'picktui resolve');
+    return parsed.value;
+}

package/dist/cjs/history.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.histGet = histGet;
+exports.histSet = histSet;
+/**
+ * history — 选择记忆（文件状态，直调引擎 hist 子命令）。
+ *
+ * 状态文件位于引擎数据目录（$PICKTUI_CONFIG_DIR → $XDG_CONFIG_HOME/picktui →
+ * ~/.config/picktui），与 pick --label 的 TUI 记忆同一份。
+ */
+const engine_js_1 = require("./engine.js");
+/** 读取 label 上次选中的值；无记录返回 ""。 */
+async function histGet(label) {
+    const inv = await (0, engine_js_1.invokeEngine)(['hist', 'get', label]);
+    (0, engine_js_1.assertSuccess)(inv, 'picktui hist get');
+    const parsed = (0, engine_js_1.parseJSON)(inv.stdout, 'picktui hist get');
+    return parsed.last ?? '';
+}
+/** 记录 label 的上次选中值（成功无输出；失败抛 PicktuiError）。 */
+async function histSet(label, value) {
+    const inv = await (0, engine_js_1.invokeEngine)(['hist', 'set', label, value]);
+    (0, engine_js_1.assertSuccess)(inv, 'picktui hist set');
+}

package/dist/cjs/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * index — 聚合导出；亦支持按模块 import（tree-shakable）：
+ *   import { filter } from '@havocrao/picktui/filter'
+ *   import { pick } from '@havocrao/picktui/tui'
+ *   import { histGet } from '@havocrao/picktui/history'
+ */
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./engine.js"), exports);
+__exportStar(require("./filter.js"), exports);
+__exportStar(require("./tui.js"), exports);
+__exportStar(require("./history.js"), exports);
+__exportStar(require("./confirm.js"), exports);

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/tui.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pick = pick;
+exports.menu = menu;
+exports.rawPick = rawPick;
+/**
+ * tui — 交互选择 / 菜单（引擎跑 TUI，宿主零渲染）。
+ *
+ * 交互渲染与按键输入走引擎的 /dev/tty；本模块的 stdout 仅收选中值——
+ * 与 `$(picktui pick ...)` 同样的安全语义。无 TTY 时引擎自动退化
+ * （无 query 取首个、有 query 过滤取首），绑定无需分支。
+ */
+const engine_js_1 = require("./engine.js");
+/**
+ * pick — 交互过滤选择（fzf 风格）。
+ *
+ * @param cands 候选（经 stdin 传入，与位置参数等价且无 argv 长度限制）
+ * @param flags 透传引擎 flags（query/label/sep/fuzzy/select1/auto）
+ * @returns 选中值；用户取消（esc/ctrl+c，退出码 130）返回 null
+ */
+async function pick(cands = [], flags = {}) {
+    const args = ['pick'];
+    if (flags.query !== undefined) {
+        args.push('-q', flags.query);
+    }
+    if (flags.label !== undefined) {
+        args.push('--label', flags.label);
+    }
+    if (flags.sep !== undefined) {
+        args.push('--sep', flags.sep);
+    }
+    if (flags.fuzzy) {
+        args.push('--fuzzy');
+    }
+    if (flags.select1) {
+        args.push('-1');
+    }
+    if (flags.auto) {
+        args.push('--auto');
+    }
+    const inv = await (0, engine_js_1.invokeEngine)(args, { input: (0, engine_js_1.serializeCandidates)(cands) });
+    if (inv.exitCode === 130) {
+        return null; // 取消
+    }
+    (0, engine_js_1.assertSuccess)(inv, 'picktui pick');
+    return inv.stdout.replace(/\r?\n$/, '');
+}
+/**
+ * menu — 多值缩写 TUI 菜单（数字 1-9 直选）。
+ *
+ * @param label 菜单标题与选择记忆键
+ * @param cands 候选（经位置参数传入，注意 argv 长度限制；超长场景用 pick）
+ * @returns 选中值；取消返回 null
+ */
+async function menu(label, cands) {
+    const inv = await (0, engine_js_1.invokeEngine)(['_menu', label, ...cands]);
+    if (inv.exitCode === 130) {
+        return null;
+    }
+    (0, engine_js_1.assertSuccess)(inv, 'picktui _menu');
+    return inv.stdout.replace(/\r?\n$/, '');
+}
+/**
+ * rawPick — 透传任意引擎 pick 参数（--from/--map 等绑定未包装的 flags）。
+ *
+ * @example rawPick(['--from', 'git branch', '--label', 'git co', '-1'])
+ */
+async function rawPick(args) {
+    const inv = await (0, engine_js_1.invokeEngine)(['pick', ...args]);
+    if (inv.exitCode === 130) {
+        return null;
+    }
+    (0, engine_js_1.assertSuccess)(inv, 'picktui pick');
+    return inv.stdout.replace(/\r?\n$/, '');
+}

package/dist/cjs/types.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * types — 与 docs/integration/protocol.md 对齐的纯类型（零依赖）。
+ *
+ * 字段名/形状是协议 v1 的一部分，任何改动需同步 protocol.md 与 Go 引擎。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PicktuiError = void 0;
+/** 引擎调用失败（退出码非预期）时抛出的错误。 */
+class PicktuiError extends Error {
+    exitCode;
+    stderr;
+    constructor(message, exitCode, stderr) {
+        super(message);
+        this.name = 'PicktuiError';
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+    }
+}
+exports.PicktuiError = PicktuiError;

package/dist/esm/confirm.js

@@ -0,0 +1,24 @@
+/**
+ * confirm — 自动匹配首次确认（文件状态，直调引擎 confirm 子命令）。
+ *
+ * 状态文件位于引擎数据目录，与 pick --auto 的确认记录同一份：
+ * 首次自动匹配某 (label, value) 需确认，确认后不再询问。
+ */
+import { assertSuccess, invokeEngine, parseJSON } from './engine.js';
+/** 报告 (label, value) 是否已被确认过。 */
+export async function confirmCheck(label, value) {
+    const inv = await invokeEngine(['confirm', 'check', label, value]);
+    assertSuccess(inv, 'picktui confirm check');
+    const parsed = parseJSON(inv.stdout, 'picktui confirm check');
+    return parsed.confirmed;
+}
+/**
+ * 记录 (label, value) 为已确认（幂等）。
+ * @returns 确认后的实际状态（label 为空时不落盘 → false）
+ */
+export async function confirmAdd(label, value) {
+    const inv = await invokeEngine(['confirm', 'add', label, value]);
+    assertSuccess(inv, 'picktui confirm add');
+    const parsed = parseJSON(inv.stdout, 'picktui confirm add');
+    return parsed.confirmed;
+}

package/dist/esm/engine.js

@@ -0,0 +1,133 @@
+/**
+ * engine — 引擎发现与进程调用（薄绑定核心，零渲染逻辑）。
+ *
+ * 引擎发现顺序（对齐 docs/integration/protocol.md）：
+ *   1. $PICKTUI_BIN
+ *   2. $PATH 中的 picktui / picktui.exe
+ *
+ * 渲染/按键/匹配全部在引擎内完成；本模块只负责 spawn + stdout/stderr 收集，
+ * 保证宿主 stdout 不被污染（交互 TUI 走引擎的 /dev/tty）。
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { PicktuiError } from './types.js';
+/** 绑定声明的最低引擎版本（协议 v1）。 */
+export const MIN_ENGINE_VERSION = '0.1.0';
+/** 引擎二进制名（win32 带 .exe 后缀）。 */
+function binName() {
+    return process.platform === 'win32' ? 'picktui.exe' : 'picktui';
+}
+/** 解析引擎二进制绝对路径；找不到时抛出带指引的错误。 */
+export async function engineBin() {
+    const fromEnv = process.env.PICKTUI_BIN;
+    if (fromEnv) {
+        return fromEnv;
+    }
+    const name = binName();
+    const dirs = (process.env.PATH ?? '').split(delimiter).filter(Boolean);
+    for (const dir of dirs) {
+        const candidate = join(dir, name);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error(`picktui 引擎未找到：请设置 PICKTUI_BIN 指向引擎二进制，或将 ${name} 加入 PATH。` +
+        `（引擎即本仓库 Go 模块的 cmd/picktui，` +
+        `见 README「引擎二进制」一节；` +
+        `纯数据场景可设 PICKTUI_NO_BIN=1 使用内嵌 JS 过滤实现——该实现尚未提供，请先安装引擎。）`);
+}
+/** 调用引擎子命令：数据走 stdin，结果回 stdout/stderr（无 TTY 依赖）。 */
+export async function invokeEngine(args, opts = {}) {
+    const bin = await engineBin();
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const fail = (err) => {
+            if (!settled) {
+                settled = true;
+                reject(err);
+            }
+        };
+        const done = (inv) => {
+            if (!settled) {
+                settled = true;
+                resolve(inv);
+            }
+        };
+        const child = spawn(bin, args, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            env: { ...process.env, ...opts.env },
+            // 引擎自身通过 /dev/tty 完成交互渲染与输入；这里不需要终端
+            windowsHide: true,
+        });
+        let stdout = '';
+        let stderr = '';
+        child.stdout.setEncoding('utf8');
+        child.stderr.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => (stdout += chunk));
+        child.stderr.on('data', (chunk) => (stderr += chunk));
+        child.on('error', fail);
+        child.on('close', (code) => done({ exitCode: code ?? -1, stdout, stderr }));
+        if (opts.input !== undefined) {
+            child.stdin.end(opts.input);
+        }
+        else {
+            child.stdin.end();
+        }
+    });
+}
+/** 引擎调用约定：退出码 0 成功 / 1 运行错误 / 2 用法错误 / 130 取消。 */
+export function assertSuccess(inv, what) {
+    if (inv.exitCode === 0) {
+        return;
+    }
+    const detail = inv.stderr.trim() || `exit code ${inv.exitCode}`;
+    throw new PicktuiError(`${what}失败：${detail}`, inv.exitCode, inv.stderr);
+}
+/** 解析 stdout 为 JSON（协议输出恒为 JSON）；失败抛 PicktuiError。 */
+export function parseJSON(stdout, what) {
+    try {
+        return JSON.parse(stdout);
+    }
+    catch {
+        throw new PicktuiError(`${what}输出不是合法 JSON：${stdout.slice(0, 200)}`, -1, stdout);
+    }
+}
+/** 读取引擎版本（"picktui <semver>"）。 */
+export async function engineVersion() {
+    const bin = await engineBin();
+    const inv = await invokeEngine(['version']);
+    assertSuccess(inv, 'picktui version');
+    const match = /^picktui\s+(\d+\.\d+\.\d+)/.exec(inv.stdout.trim());
+    if (!match) {
+        throw new PicktuiError(`无法解析引擎版本：${inv.stdout.trim()}`, inv.exitCode, inv.stdout);
+    }
+    return match[1];
+}
+/** 比较两个 x.y.z 版本号：a >= b。 */
+export function versionAtLeast(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < 3; i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (x !== y) {
+            return x > y;
+        }
+    }
+    return true;
+}
+/** 校验引擎版本不低于绑定声明的最低版本；不满足时抛错。 */
+export async function assertEngineVersion(min = MIN_ENGINE_VERSION) {
+    const v = await engineVersion();
+    if (!versionAtLeast(v, min)) {
+        throw new PicktuiError(`picktui 引擎版本 ${v} 低于绑定要求的最低版本 ${min}（请升级引擎或设置 PICKTUI_BIN）`, -1, '');
+    }
+    return v;
+}
+/** 将候选列表序列化为协议结构化行（key<TAB>description）。 */
+export function serializeCandidates(cands) {
+    return cands
+        .map((c) => (typeof c === 'string' ? c : c.desc ? `${c.value}\t${c.desc}` : c.value))
+        .join('\n') + '\n';
+}

package/dist/esm/filter.js

@@ -0,0 +1,45 @@
+/**
+ * filter / resolve — 纯函数数据面（直调引擎 filter/resolve --json）。
+ *
+ * 过滤与高亮区间由引擎权威计算；本模块只做「候选传入、JSON 取回」，
+ * 禁止重实现匹配（详见 docs/integration/protocol.md 兼容性承诺）。
+ */
+import { assertSuccess, invokeEngine, parseJSON, serializeCandidates, } from './engine.js';
+/** 将 FilterOptions 转为引擎参数。 */
+function modeArgs(opts) {
+    const args = [];
+    if (opts.mode && opts.mode !== 'substring') {
+        args.push('--mode', opts.mode);
+    }
+    if (opts.mode === 'token' && opts.sep) {
+        args.push('--sep', opts.sep);
+    }
+    return args;
+}
+/**
+ * filter — 过滤候选并返回命中项（保留输入顺序）+ 高亮区间。
+ *
+ * @param cands 候选（字符串或结构化 Candidate）
+ * @param query 过滤关键字（空格分词，空串返回全部）
+ * @param opts  匹配模式（默认 substring）
+ * @returns 命中候选，`ranges` 为命中的 rune 区间（空查询恒为 []）
+ */
+export async function filter(cands, query = '', opts = {}) {
+    const inv = await invokeEngine(['filter', '--json', '--query', query, ...modeArgs(opts)], { input: serializeCandidates(cands) });
+    assertSuccess(inv, 'picktui filter');
+    return parseJSON(inv.stdout, 'picktui filter');
+}
+/**
+ * resolve — 把 query 解析为唯一候选（精确 → 唯一前缀，大小写不敏感前缀）。
+ *
+ * @returns 解析出的选中值；无匹配/多个前缀匹配返回 null（引擎退出码 1）
+ */
+export async function resolve(cands, query, opts = {}) {
+    const inv = await invokeEngine(['resolve', '--json', '--query', query, ...modeArgs(opts)], { input: serializeCandidates(cands) });
+    if (inv.exitCode === 1) {
+        return null; // 协议：无唯一解 → stdout 空 + 退出码 1
+    }
+    assertSuccess(inv, 'picktui resolve');
+    const parsed = parseJSON(inv.stdout, 'picktui resolve');
+    return parsed.value;
+}

package/dist/esm/history.js

@@ -0,0 +1,19 @@
+/**
+ * history — 选择记忆（文件状态，直调引擎 hist 子命令）。
+ *
+ * 状态文件位于引擎数据目录（$PICKTUI_CONFIG_DIR → $XDG_CONFIG_HOME/picktui →
+ * ~/.config/picktui），与 pick --label 的 TUI 记忆同一份。
+ */
+import { assertSuccess, invokeEngine, parseJSON } from './engine.js';
+/** 读取 label 上次选中的值；无记录返回 ""。 */
+export async function histGet(label) {
+    const inv = await invokeEngine(['hist', 'get', label]);
+    assertSuccess(inv, 'picktui hist get');
+    const parsed = parseJSON(inv.stdout, 'picktui hist get');
+    return parsed.last ?? '';
+}
+/** 记录 label 的上次选中值（成功无输出；失败抛 PicktuiError）。 */
+export async function histSet(label, value) {
+    const inv = await invokeEngine(['hist', 'set', label, value]);
+    assertSuccess(inv, 'picktui hist set');
+}

package/dist/esm/index.js

@@ -0,0 +1,12 @@
+/**
+ * index — 聚合导出；亦支持按模块 import（tree-shakable）：
+ *   import { filter } from '@havocrao/picktui/filter'
+ *   import { pick } from '@havocrao/picktui/tui'
+ *   import { histGet } from '@havocrao/picktui/history'
+ */
+export * from './types.js';
+export * from './engine.js';
+export * from './filter.js';
+export * from './tui.js';
+export * from './history.js';
+export * from './confirm.js';

package/dist/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/dist/esm/tui.js

@@ -0,0 +1,70 @@
+/**
+ * tui — 交互选择 / 菜单（引擎跑 TUI，宿主零渲染）。
+ *
+ * 交互渲染与按键输入走引擎的 /dev/tty；本模块的 stdout 仅收选中值——
+ * 与 `$(picktui pick ...)` 同样的安全语义。无 TTY 时引擎自动退化
+ * （无 query 取首个、有 query 过滤取首），绑定无需分支。
+ */
+import { assertSuccess, invokeEngine, serializeCandidates } from './engine.js';
+/**
+ * pick — 交互过滤选择（fzf 风格）。
+ *
+ * @param cands 候选（经 stdin 传入，与位置参数等价且无 argv 长度限制）
+ * @param flags 透传引擎 flags（query/label/sep/fuzzy/select1/auto）
+ * @returns 选中值；用户取消（esc/ctrl+c，退出码 130）返回 null
+ */
+export async function pick(cands = [], flags = {}) {
+    const args = ['pick'];
+    if (flags.query !== undefined) {
+        args.push('-q', flags.query);
+    }
+    if (flags.label !== undefined) {
+        args.push('--label', flags.label);
+    }
+    if (flags.sep !== undefined) {
+        args.push('--sep', flags.sep);
+    }
+    if (flags.fuzzy) {
+        args.push('--fuzzy');
+    }
+    if (flags.select1) {
+        args.push('-1');
+    }
+    if (flags.auto) {
+        args.push('--auto');
+    }
+    const inv = await invokeEngine(args, { input: serializeCandidates(cands) });
+    if (inv.exitCode === 130) {
+        return null; // 取消
+    }
+    assertSuccess(inv, 'picktui pick');
+    return inv.stdout.replace(/\r?\n$/, '');
+}
+/**
+ * menu — 多值缩写 TUI 菜单（数字 1-9 直选）。
+ *
+ * @param label 菜单标题与选择记忆键
+ * @param cands 候选（经位置参数传入，注意 argv 长度限制；超长场景用 pick）
+ * @returns 选中值；取消返回 null
+ */
+export async function menu(label, cands) {
+    const inv = await invokeEngine(['_menu', label, ...cands]);
+    if (inv.exitCode === 130) {
+        return null;
+    }
+    assertSuccess(inv, 'picktui _menu');
+    return inv.stdout.replace(/\r?\n$/, '');
+}
+/**
+ * rawPick — 透传任意引擎 pick 参数（--from/--map 等绑定未包装的 flags）。
+ *
+ * @example rawPick(['--from', 'git branch', '--label', 'git co', '-1'])
+ */
+export async function rawPick(args) {
+    const inv = await invokeEngine(['pick', ...args]);
+    if (inv.exitCode === 130) {
+        return null;
+    }
+    assertSuccess(inv, 'picktui pick');
+    return inv.stdout.replace(/\r?\n$/, '');
+}

package/dist/esm/types.js

@@ -0,0 +1,16 @@
+/**
+ * types — 与 docs/integration/protocol.md 对齐的纯类型（零依赖）。
+ *
+ * 字段名/形状是协议 v1 的一部分，任何改动需同步 protocol.md 与 Go 引擎。
+ */
+/** 引擎调用失败（退出码非预期）时抛出的错误。 */
+export class PicktuiError extends Error {
+    exitCode;
+    stderr;
+    constructor(message, exitCode, stderr) {
+        super(message);
+        this.name = 'PicktuiError';
+        this.exitCode = exitCode;
+        this.stderr = stderr;
+    }
+}

package/dist/types/confirm.d.ts

@@ -0,0 +1,7 @@
+/** 报告 (label, value) 是否已被确认过。 */
+export declare function confirmCheck(label: string, value: string): Promise<boolean>;
+/**
+ * 记录 (label, value) 为已确认（幂等）。
+ * @returns 确认后的实际状态（label 为空时不落盘 → false）
+ */
+export declare function confirmAdd(label: string, value: string): Promise<boolean>;

package/dist/types/engine.d.ts

@@ -0,0 +1,27 @@
+/** 绑定声明的最低引擎版本（协议 v1）。 */
+export declare const MIN_ENGINE_VERSION = "0.1.0";
+/** 解析引擎二进制绝对路径；找不到时抛出带指引的错误。 */
+export declare function engineBin(): Promise<string>;
+/** 引擎调用的原始结果。 */
+export interface EngineInvocation {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/** 调用引擎子命令：数据走 stdin，结果回 stdout/stderr（无 TTY 依赖）。 */
+export declare function invokeEngine(args: string[], opts?: {
+    input?: string;
+    env?: NodeJS.ProcessEnv;
+}): Promise<EngineInvocation>;
+/** 引擎调用约定：退出码 0 成功 / 1 运行错误 / 2 用法错误 / 130 取消。 */
+export declare function assertSuccess(inv: EngineInvocation, what: string): void;
+/** 解析 stdout 为 JSON（协议输出恒为 JSON）；失败抛 PicktuiError。 */
+export declare function parseJSON<T>(stdout: string, what: string): T;
+/** 读取引擎版本（"picktui <semver>"）。 */
+export declare function engineVersion(): Promise<string>;
+/** 比较两个 x.y.z 版本号：a >= b。 */
+export declare function versionAtLeast(a: string, b: string): boolean;
+/** 校验引擎版本不低于绑定声明的最低版本；不满足时抛错。 */
+export declare function assertEngineVersion(min?: string): Promise<string>;
+/** 将候选列表序列化为协议结构化行（key<TAB>description）。 */
+export declare function serializeCandidates(cands: (string | import('./types.js').Candidate)[]): string;

package/dist/types/filter.d.ts

@@ -0,0 +1,16 @@
+import type { Candidate, FilterOptions, FilteredCandidate } from './types.js';
+/**
+ * filter — 过滤候选并返回命中项（保留输入顺序）+ 高亮区间。
+ *
+ * @param cands 候选（字符串或结构化 Candidate）
+ * @param query 过滤关键字（空格分词，空串返回全部）
+ * @param opts  匹配模式（默认 substring）
+ * @returns 命中候选，`ranges` 为命中的 rune 区间（空查询恒为 []）
+ */
+export declare function filter(cands: (string | Candidate)[], query?: string, opts?: FilterOptions): Promise<FilteredCandidate[]>;
+/**
+ * resolve — 把 query 解析为唯一候选（精确 → 唯一前缀，大小写不敏感前缀）。
+ *
+ * @returns 解析出的选中值；无匹配/多个前缀匹配返回 null（引擎退出码 1）
+ */
+export declare function resolve(cands: (string | Candidate)[], query: string, opts?: FilterOptions): Promise<string | null>;

package/dist/types/history.d.ts

@@ -0,0 +1,4 @@
+/** 读取 label 上次选中的值；无记录返回 ""。 */
+export declare function histGet(label: string): Promise<string>;
+/** 记录 label 的上次选中值（成功无输出；失败抛 PicktuiError）。 */
+export declare function histSet(label: string, value: string): Promise<void>;

package/dist/types/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * index — 聚合导出；亦支持按模块 import（tree-shakable）：
+ *   import { filter } from '@havocrao/picktui/filter'
+ *   import { pick } from '@havocrao/picktui/tui'
+ *   import { histGet } from '@havocrao/picktui/history'
+ */
+export * from './types.js';
+export * from './engine.js';
+export * from './filter.js';
+export * from './tui.js';
+export * from './history.js';
+export * from './confirm.js';

package/dist/types/tui.d.ts

@@ -0,0 +1,23 @@
+import type { Candidate, PickFlags } from './types.js';
+/**
+ * pick — 交互过滤选择（fzf 风格）。
+ *
+ * @param cands 候选（经 stdin 传入，与位置参数等价且无 argv 长度限制）
+ * @param flags 透传引擎 flags（query/label/sep/fuzzy/select1/auto）
+ * @returns 选中值；用户取消（esc/ctrl+c，退出码 130）返回 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
+ */
+export declare function menu(label: string, cands: string[]): Promise<string | null>;
+/**
+ * rawPick — 透传任意引擎 pick 参数（--from/--map 等绑定未包装的 flags）。
+ *
+ * @example rawPick(['--from', 'git branch', '--label', 'git co', '-1'])
+ */
+export declare function rawPick(args: string[]): Promise<string | null>;

package/dist/types/types.d.ts

@@ -0,0 +1,61 @@
+/**
+ * types — 与 docs/integration/protocol.md 对齐的纯类型（零依赖）。
+ *
+ * 字段名/形状是协议 v1 的一部分，任何改动需同步 protocol.md 与 Go 引擎。
+ */
+/** 结构化候选：value 为选中值，desc 仅供展示（来自 key<TAB>description 拆分）。 */
+export interface Candidate {
+    value: string;
+    desc?: string;
+}
+/** 过滤模式（对齐引擎 --mode）。 */
+export type FilterMode = 'substring' | 'token' | 'fuzzy';
+/** 过滤选项（对齐引擎 filter --json 的 --mode/--sep）。 */
+export interface FilterOptions {
+    mode?: FilterMode;
+    /** 仅 token 模式：分隔符集合，默认 "_"，可多字符如 ":_"。 */
+    sep?: string;
+}
+/** filter 协议输出：命中候选 + 高亮 rune 区间 [start, end)。 */
+export interface FilteredCandidate {
+    value: string;
+    desc: string;
+    /** 无 query 时恒为 []（非 null）。 */
+    ranges: [number, number][];
+}
+/**
+ * pick 命令透传 flags（对齐协议 pick 子命令）。
+ * 注意：--from/--map 属于引擎侧候选来源，绑定层不额外包装——需要时请用
+ * rawPick([...args]) 或直接调用引擎二进制。
+ */
+export interface PickFlags {
+    /** 预填查询；非交互时过滤后取首个匹配。 */
+    query?: string;
+    /** token 前缀模式分隔符集合（默认 "_"）。 */
+    sep?: string;
+    /** 子序列模糊匹配。 */
+    fuzzy?: boolean;
+    /** 选择记忆键（history.toml）。 */
+    label?: string;
+    /** 仅一个匹配时自动选中。 */
+    select1?: boolean;
+    /** 配合 query：精确或唯一前缀自动选中（首次需引擎侧确认）。 */
+    auto?: boolean;
+}
+/** 引擎调用失败（退出码非预期）时抛出的错误。 */
+export declare class PicktuiError extends Error {
+    readonly exitCode: number;
+    readonly stderr: string;
+    constructor(message: string, exitCode: number, stderr: string);
+}
+/** resolve 协议输出。 */
+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

@@ -0,0 +1,71 @@
+{
+  "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.",
+  "license": "MIT",
+  "author": "havoc-rao",
+  "keywords": [
+    "tui",
+    "picker",
+    "fzf",
+    "filter",
+    "select",
+    "menu"
+  ],
+  "main": "./dist/cjs/index.js",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/esm/index.js",
+      "require": "./dist/cjs/index.js"
+    },
+    "./filter": {
+      "types": "./dist/types/filter.d.ts",
+      "import": "./dist/esm/filter.js",
+      "require": "./dist/cjs/filter.js"
+    },
+    "./tui": {
+      "types": "./dist/types/tui.d.ts",
+      "import": "./dist/esm/tui.js",
+      "require": "./dist/cjs/tui.js"
+    },
+    "./history": {
+      "types": "./dist/types/history.d.ts",
+      "import": "./dist/esm/history.js",
+      "require": "./dist/cjs/history.js"
+    },
+    "./confirm": {
+      "types": "./dist/types/confirm.d.ts",
+      "import": "./dist/esm/confirm.js",
+      "require": "./dist/cjs/confirm.js"
+    },
+    "./types": {
+      "types": "./dist/types/types.d.ts",
+      "import": "./dist/esm/types.js",
+      "require": "./dist/cjs/types.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && node scripts/fixup.mjs",
+    "pretest": "node scripts/build-engine.mjs",
+    "test": "node --test \"test/*.test.mjs\"",
+    "test:pack": "npm run build && node scripts/test-pack.mjs",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.1",
+    "typescript": "^5.5.0"
+  }
+}