@havocrao/picktui 0.1.0 → 0.1.1

package/dist/esm/tui.js

@@ -1,70 +1,485 @@
 /**
- * tui — 交互选择 / 菜单（引擎跑 TUI，宿主零渲染）。
+ * tui — pick / menu / rawPick（纯 TS 实现，零引擎依赖）。
  *
- * 交互渲染与按键输入走引擎的 /dev/tty；本模块的 stdout 仅收选中值——
- * 与 `$(picktui pick ...)` 同样的安全语义。无 TTY 时引擎自动退化
- * （无 query 取首个、有 query 过滤取首），绑定无需分支。
+ * 交互渲染与按键输入走 /dev/tty（posix）或宿主 stdio（Windows fallback），
+ * 宿主 stdout 只承载选中值——与引擎协议相同的安全语义。无 TTY 时自动退化
+ * （无 query 取首个、有 query 过滤取首），调用方无需分支；取消返回 null。
+ *
+ * 流程对齐 Go 引擎 pickWith/menuWith：--auto 确认链、-1 自动选中、
+ * 非交互开关（$PICKTUI_PICK=off）、选择记忆（--label）、候选来源
+ * （位置参数/stdin/--from/--map）。
  */
-import { assertSuccess, invokeEngine, serializeCandidates } from './engine.js';
+import { exec } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { extname, join } from 'node:path';
+import { toStructuredCands } from './cand.js';
+import { confirm, isConfirmed } from './confirm.js';
+import { autoResolve, filterCands } from './filter.js';
+import { lastPick, loadPickHistory, savePick } from './history.js';
+import { newModel, selectedValues, setColorEnabled, update, view, } from './model.js';
+import { KeyReader, enterInteractive, exitInteractive, openTty, promptConfirm, renderFrame, } from './tty.js';
+import { PicktuiError } from './types.js';
+/** 命令名前缀（对齐引擎默认名，宿主品牌对齐不在本包范围）。 */
+const NAME = 'picktui';
+/** 非交互开关环境变量（值为 "off" 时 pick 跳过 TUI）。 */
+export const OFF_ENV = 'PICKTUI_PICK';
+/** shell 候选来源/转换器超时（对齐引擎 10s）。 */
+const CMD_TIMEOUT_MS = 10_000;
+/** 光标闪烁周期（对齐引擎 500ms）。 */
+const TICK_MS = 500;
 /**
  * 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 async function pick(cands = [], flags = {}) {
-    const args = ['pick'];
-    if (flags.query !== undefined) {
-        args.push('-q', flags.query);
+    const structured = cands.length > 0 ? toStructuredCands(cands) : [];
+    return pickFlow({
+        cands: structured,
+        fromCmd: '',
+        mapper: '',
+        flags,
+    });
+}
+/**
+ * menu — 多值缩写 TUI 菜单（数字 1-9 直选）。
+ * @returns 选中值；取消返回 null；参数不足抛 PicktuiError（退出码 2）
+ */
+export async function menu(label, cands) {
+    if (cands.length < 1) {
+        const msg = `usage: ${NAME} _menu <label> <cand...>`;
+        throw new PicktuiError(msg, 2, msg);
+    }
+    const tty = openTty();
+    if (tty === null) {
+        // 非交互：取首个候选（对齐引擎退化：保证脚本不卡）
+        return cands[0];
+    }
+    try {
+        const res = await runTui(newModel({
+            title: `${NAME} ${label}`,
+            subtitle: '多值缩写',
+            cands: cands.map((v) => ({ value: v, desc: '' })),
+            query: '',
+            filterOpts: { mode: 'substring' },
+            initial: memoryInitial(label, cands.map((v) => ({ value: v, desc: '' }))),
+            jumpKeys: true,
+            statusHint: 'type to filter · ↑↓ move · 1-9 jump · enter confirm · esc cancel',
+            multi: false,
+            selected: [],
+        }), tty);
+        if (res.cancelled) {
+            return null;
+        }
+        if (label !== '') {
+            savePick(label, res.value);
+        }
+        return res.value;
     }
-    if (flags.label !== undefined) {
-        args.push('--label', flags.label);
+    finally {
+        tty.read.destroy();
+    }
+}
+/**
+ * rawPick — 透传引擎 pick 参数（--from/--map/-q/--label/--sep/--fuzzy/-1/--auto）。
+ * @example rawPick(['--from', 'git branch', '--label', 'git co', '-1'])
+ */
+export async function rawPick(args) {
+    const parsed = parsePickArgs(args);
+    const structured = parsed.rest.length > 0 ? toStructuredCands(parsed.rest) : [];
+    return pickFlow({
+        cands: structured,
+        fromCmd: parsed.from,
+        mapper: parsed.mapper,
+        flags: parsed.flags,
+    });
+}
+/** 解析 pick 参数（对齐引擎 flags：--query=、--from=、--map= 等长格式均支持）。 */
+function parsePickArgs(args) {
+    const flags = {};
+    let from = '';
+    let mapper = '';
+    const rest = [];
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        const take = (name) => {
+            if (i + 1 < args.length) {
+                i++;
+                return args[i];
+            }
+            throw new PicktuiError(`${NAME} pick: ${name} 缺少参数`, 2, '');
+        };
+        if (a === '-q' || a === '--query') {
+            flags.query = take('--query');
+        }
+        else if (a.startsWith('--query=')) {
+            flags.query = a.slice('--query='.length);
+        }
+        else if (a === '--from') {
+            from = take('--from');
+        }
+        else if (a.startsWith('--from=')) {
+            from = a.slice('--from='.length);
+        }
+        else if (a === '--map') {
+            mapper = take('--map');
+        }
+        else if (a.startsWith('--map=')) {
+            mapper = a.slice('--map='.length);
+        }
+        else if (a === '--label') {
+            flags.label = take('--label');
+        }
+        else if (a.startsWith('--label=')) {
+            flags.label = a.slice('--label='.length);
+        }
+        else if (a === '--sep') {
+            flags.sep = take('--sep');
+        }
+        else if (a.startsWith('--sep=')) {
+            flags.sep = a.slice('--sep='.length);
+        }
+        else if (a === '--fuzzy') {
+            flags.fuzzy = true;
+        }
+        else if (a === '-1' || a === '--select-1') {
+            flags.select1 = true;
+        }
+        else if (a === '--auto') {
+            flags.auto = true;
+        }
+        else if (a.startsWith('-') && a !== '-') {
+            const msg = `${NAME} pick: 未知参数 ${a}`;
+            throw new PicktuiError(msg, 2, msg);
+        }
+        else {
+            rest.push(a);
+        }
     }
-    if (flags.sep !== undefined) {
-        args.push('--sep', flags.sep);
+    return { flags, from, mapper, rest };
+}
+/** pick 全流程（对齐引擎 pickWith）。 */
+async function pickFlow(params) {
+    const { flags, fromCmd, mapper } = params;
+    const query = flags.query ?? '';
+    if (mapper !== '' && params.cands.length > 0) {
+        const msg = `${NAME} pick: --map 只与 --from 配合，不能与位置参数同用`;
+        throw new PicktuiError(msg, 2, msg);
     }
+    // 构造 FilterOptions（对齐引擎：--fuzzy 优先，--sep 切 token 模式）
+    const filterOpts = { mode: 'substring' };
     if (flags.fuzzy) {
-        args.push('--fuzzy');
+        filterOpts.mode = 'fuzzy';
+    }
+    else if (flags.sep) {
+        filterOpts.mode = 'token';
+        filterOpts.sep = flags.sep;
+    }
+    // 候选来源：显式候选（参数）或 --from 命令执行。
+    // 注意：不读宿主进程自身的 stdin——宿主 stdin 是宿主自己的输入流，
+    // 由库消费会造成半开 pipe 阻塞并侵入宿主输入（对齐旧版绑定行为）。
+    let cands = params.cands;
+    if (fromCmd !== '') {
+        const raw = await runShell(fromCmd, '');
+        if (!raw.ok) {
+            throw new PicktuiError(`${NAME} pick: ${fromCmd}: ${raw.stderr}`, 1, raw.stderr);
+        }
+        cands = toStructuredCands(raw.stdout.split('\n'));
+        // --map 转换器：接收 --from 原始输出
+        if (mapper !== '') {
+            cands = await runMapper(mapper, raw.stdout);
+        }
+    }
+    if (cands.length === 0) {
+        const msg = `${NAME} pick: no candidates`;
+        throw new PicktuiError(msg, 1, msg);
     }
+    const label = flags.label ?? '';
+    const off = process.env[OFF_ENV] === 'off';
+    // --auto 自动选中：query 精确命中或唯一前缀命中时直接输出（跳过 TUI）。
+    // 首次匹配该 (label, value) 需用户确认（记录 confirm 记录，之后不再询问）；
+    // off / 无 tty / 无 label 时跳过确认；拒绝确认回退下方 TUI。
+    if (flags.auto && query !== '') {
+        const v = autoResolve(cands, query);
+        if (v !== null) {
+            if (label === '' || off || isConfirmed(label, v)) {
+                savePickIfLabeled(label, v);
+                return v;
+            }
+            const tty = openTty();
+            if (tty !== null) {
+                try {
+                    const answer = await promptConfirm(tty, `\r\n${NAME}: 首次自动匹配 ${label} → ${v}，确认执行？[y/N] `);
+                    if (answer !== null && /^(y|yes)$/i.test(answer.trim())) {
+                        confirm(label, v);
+                        savePickIfLabeled(label, v);
+                        return v;
+                    }
+                    // 用户拒绝确认：回退到下方 TUI 选择（query 预填过滤）
+                }
+                finally {
+                    tty.read.destroy();
+                }
+            }
+            else {
+                // 无 /dev/tty：非交互环境跳过确认，保持确定性执行
+                savePickIfLabeled(label, v);
+                return v;
+            }
+        }
+    }
+    // -1 自动选中（仅一个匹配时）
     if (flags.select1) {
-        args.push('-1');
+        const filtered = filterCands(cands, query, filterOpts);
+        if (filtered.length === 1) {
+            savePickIfLabeled(label, filtered[0].value);
+            return filtered[0].value;
+        }
+    }
+    // 非交互开关或无 tty → 退化路径
+    const tty = openTty();
+    if (off || tty === null) {
+        return pickNonInteractive(cands, query, filterOpts, label, flags.auto === true);
     }
-    if (flags.auto) {
-        args.push('--auto');
+    try {
+        const res = await runTui(newModel({
+            title: `${NAME} pick`,
+            subtitle: label,
+            cands,
+            query,
+            filterOpts,
+            initial: memoryInitial(label, cands),
+            jumpKeys: false,
+            statusHint: 'type to filter · ↑↓ move · enter select · esc cancel',
+            multi: false,
+            selected: [],
+        }), tty);
+        if (res.cancelled) {
+            return null;
+        }
+        // 自动解析流程中用户从 TUI 显式选中 → 视为对该解析的确认
+        if (flags.auto && label !== '') {
+            confirm(label, res.value);
+        }
+        savePickIfLabeled(label, res.value);
+        return res.value;
     }
-    const inv = await invokeEngine(args, { input: serializeCandidates(cands) });
-    if (inv.exitCode === 130) {
-        return null; // 取消
+    finally {
+        tty.read.destroy();
     }
-    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;
+/** 非交互模式（对齐引擎 pickNonInteractive）。 */
+function pickNonInteractive(cands, query, opts, label, auto) {
+    if (auto && query !== '') {
+        const v = autoResolve(cands, query);
+        if (v !== null) {
+            savePickIfLabeled(label, v);
+            return v;
+        }
+        const msg = `${NAME} pick: no unique match for "${query}"`;
+        throw new PicktuiError(msg, 1, msg);
+    }
+    if (query === '') {
+        const chosen = cands[0].value;
+        savePickIfLabeled(label, chosen);
+        return chosen;
     }
-    assertSuccess(inv, 'picktui _menu');
-    return inv.stdout.replace(/\r?\n$/, '');
+    const filtered = filterCands(cands, query, opts);
+    if (filtered.length === 0) {
+        const msg = `${NAME} pick: no match for "${query}"`;
+        throw new PicktuiError(msg, 1, msg);
+    }
+    const chosen = filtered[0].value;
+    savePickIfLabeled(label, chosen);
+    return chosen;
+}
+/** label 非空时记录选择记忆（失败不中断主流程，与引擎一致）。 */
+function savePickIfLabeled(label, value) {
+    if (label === '') {
+        return;
+    }
+    try {
+        savePick(label, value);
+    }
+    catch {
+        // 记忆只是锦上添花，记录失败不影响选中结果
+    }
+}
+/** 选择记忆：仅 query 为空时应用（有预填过滤词说明是精确搜索，不记忆）。 */
+function memoryInitial(label, cands) {
+    if (label === '') {
+        return 0;
+    }
+    try {
+        const last = lastPick(loadPickHistory(), label);
+        if (last !== '') {
+            for (let i = 0; i < cands.length; i++) {
+                if (cands[i].value === last) {
+                    return i;
+                }
+            }
+        }
+    }
+    catch {
+        // 记忆损坏时静默回退首行
+    }
+    return 0;
+}
+/** 在 tty 上运行 TUI 选择器，返回（取消, 选中值, 多选勾选）。 */
+export async function runTui(model, tty) {
+    enterInteractive(tty);
+    const reader = new KeyReader(tty.read);
+    const onResize = () => {
+        model.width = tty.write.columns > 0 ? tty.write.columns : model.width;
+        model.height = tty.write.rows > 0 ? tty.write.rows : model.height;
+    };
+    tty.write.on('resize', onResize);
+    onResize();
+    let pending = null;
+    const nextKey = () => {
+        if (pending === null) {
+            pending = reader.next().finally(() => {
+                pending = null;
+            });
+        }
+        return pending;
+    };
+    try {
+        for (;;) {
+            const [kind, value] = await Promise.race([
+                nextKey().then((k) => ['key', k]),
+                sleep(TICK_MS).then(() => ['tick', null]),
+            ]);
+            if (kind === 'key') {
+                const k = value;
+                if (k === null) {
+                    break; // 输入流关闭（EOF）
+                }
+                model = update(model, toKeyLike(k));
+                if (model.quit) {
+                    break;
+                }
+            }
+            else {
+                model = { ...model, phase: model.phase ^ 1 };
+            }
+            renderFrame(tty, view(model));
+        }
+    }
+    finally {
+        exitInteractive(tty);
+        tty.write.removeListener('resize', onResize);
+        tty.write.write('\x1b[2J\x1b[H');
+    }
+    if (model.cancelled || model.filtered.length === 0) {
+        return { cancelled: true, value: '', selected: [] };
+    }
+    if (model.opts.multi) {
+        return {
+            cancelled: false,
+            value: model.filtered[model.cursor].value,
+            selected: selectedValues(model),
+        };
+    }
+    return { cancelled: false, value: model.filtered[model.cursor].value, selected: [] };
+}
+/** 归一化按键：可打印字符转字符串（'k'/'j' 等移动键语义由 model 处理）。 */
+function toKeyLike(k) {
+    if (typeof k === 'object') {
+        return k.value === '' ? 'x' : k.value; // 左右方向键等忽略键映射为无操作
+    }
+    return k;
+}
+/** 执行 shell 命令（10s 超时，input 喂 stdin）；失败时附带 stderr 诊断。 */
+function runShell(cmd, input) {
+    return new Promise((resolve) => {
+        const child = exec(cmd, {
+            timeout: CMD_TIMEOUT_MS,
+            maxBuffer: 64 * 1024 * 1024,
+            windowsHide: true,
+        }, (err, stdout) => {
+            if (err) {
+                const stderr = err.stderr ?? '';
+                resolve({ ok: false, stderr: stderr.trim() || err.message });
+                return;
+            }
+            resolve({ ok: true, stdout: stdout ?? '' });
+        });
+        child.stdin?.end(input);
+    });
+}
+/** 执行 --map 转换器：stdin 喂 input，输出按结构化候选解析；脚本缺失 fail-fast。 */
+async function runMapper(mapper, input) {
+    const missing = mapperScriptMissing(mapper);
+    if (missing !== '') {
+        const msg = `map 脚本文件不存在: ${missing}\n  → 脚本可能已被移动、删除或重命名`;
+        throw new PicktuiError(msg, 1, msg);
+    }
+    const res = await runShell(mapper, input);
+    if (!res.ok) {
+        throw new PicktuiError(`${NAME} pick: --map ${mapper}: ${res.stderr}`, 1, res.stderr);
+    }
+    return toStructuredCands(res.stdout.split('\n'));
 }
 /**
- * rawPick — 透传任意引擎 pick 参数（--from/--map 等绑定未包装的 flags）。
- *
- * @example rawPick(['--from', 'git branch', '--label', 'git co', '-1'])
+ * 扫描 mapper 命令，识别"解释器 + 脚本路径"形态，返回第一个不存在的脚本文件路径。
+ * 保守策略：跳过 flags/引号/变量/管道等 shell 语法，只检查形如路径的 token
+ * （/ ./ ../ ~/ 前缀、带常见脚本扩展名），避免误拦 node -e / python3 -m 等合法用法。
  */
-export async function rawPick(args) {
-    const inv = await invokeEngine(['pick', ...args]);
-    if (inv.exitCode === 130) {
-        return null;
+export function mapperScriptMissing(mapper) {
+    const fields = mapper.trim().split(/\s+/).filter(Boolean);
+    if (fields.length < 2) {
+        return '';
+    }
+    for (const tok of fields.slice(1)) {
+        if (tok.startsWith('-')) {
+            continue;
+        }
+        if (/['"`${}|;&<>?*=]/.test(tok)) {
+            continue;
+        }
+        if (!scriptPathLike(tok)) {
+            continue;
+        }
+        const p = expandTilde(tok);
+        if (existsSync(p)) {
+            continue;
+        }
+        return p;
+    }
+    return '';
+}
+/** token 是否形如脚本文件路径：/ ./ ../ ~/ 前缀，或带常见脚本扩展名。 */
+function scriptPathLike(tok) {
+    if (tok.startsWith('/') || tok.startsWith('./') || tok.startsWith('../') || tok.startsWith('~/')) {
+        return true;
+    }
+    return isScriptExt(extname(tok).toLowerCase());
+}
+/** 常见脚本解释器可直接执行的文件扩展名。 */
+function isScriptExt(ext) {
+    return [
+        '.mjs', '.cjs', '.js', '.ts', '.py', '.sh', '.bash', '.zsh', '.fish',
+        '.pl', '.rb', '.php', '.lua', '.exs', '.r',
+    ].includes(ext);
+}
+/** 展开 ~ 与 ~/ 前缀为用户主目录。 */
+function expandTilde(p) {
+    if (p === '~') {
+        return homedir();
     }
-    assertSuccess(inv, 'picktui pick');
-    return inv.stdout.replace(/\r?\n$/, '');
+    if (p.startsWith('~/')) {
+        return join(homedir(), p.slice(2));
+    }
+    return p;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// 颜色开关：NO_COLOR 环境变量时降级纯文本
+if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== '') {
+    setColorEnabled(false);
 }

package/dist/types/cand.d.ts

@@ -0,0 +1,17 @@
+/**
+ * cand — 结构化候选：key<TAB>description 拆分与清洗（纯函数，对齐协议总览）。
+ *
+ * 过滤只匹配 key，TUI 展示 description，选中输出 key——"展示与选中分离"。
+ * 行为与 Go 引擎 StructuredCandidates 完全一致：
+ *   1. 先按 TAB 拆 key<TAB>description（无 TAB 则整行为 key）；
+ *   2. key 部分 trim → 去 "* "/"+ " 前缀（git branch 标记）→ 再 trim；
+ *   3. 跳空 key；按 key 去重保序——后到行可为先到同名 key 补缺失描述；
+ *   4. description 部分 trim（key 为空的行——如行首 TAB——直接跳过）。
+ */
+import type { Candidate } from './types.js';
+/** 将 `string | Candidate` 输入序列化为协议结构化行（key<TAB>description）。 */
+export declare function serializeLines(cands: (string | Candidate)[]): string[];
+/** 将原始行列表解析为结构化候选（与 Go StructuredCandidates 同语义）。 */
+export declare function structuredCandidates(lines: string[]): Candidate[];
+/** 输入候选统一解析为结构化候选（filter/resolve/pick 共用入口）。 */
+export declare function toStructuredCands(cands: (string | Candidate)[]): Candidate[];

package/dist/types/config.d.ts

@@ -0,0 +1,2 @@
+/** 状态文件目录（history.toml / confirm.toml 所在）。 */
+export declare function dataDir(): string;

package/dist/types/confirm.d.ts

@@ -1,7 +1,16 @@
+/** 自动匹配确认记录文件名。 */
+export declare const CONFIRM_FILE = "confirm.toml";
+/** 返回确认记录文件路径。 */
+export declare function confirmPath(): string;
+/** 解码 confirm.toml 为 label → 已确认值列表；缺失/损坏时返回空 Map。 */
+export declare function loadConfirmed(): Map<string, string[]>;
+/** 报告 (label, value) 是否已被确认过；label 为空时恒为 false。 */
+export declare function isConfirmed(label: string, value: string): boolean;
+/** 记录 (label, value) 为已确认（幂等；label 为空不落盘）。 */
+export declare function confirm(label: string, value: string): void;
+/** 解析确认回答：y/yes（大小写不敏感，容忍首尾空白）为确认。 */
+export declare function parseConfirmAnswer(s: string): boolean;
 /** 报告 (label, value) 是否已被确认过。 */
 export declare function confirmCheck(label: string, value: string): Promise<boolean>;
-/**
- * 记录 (label, value) 为已确认（幂等）。
- * @returns 确认后的实际状态（label 为空时不落盘 → false）
- */
+/** 记录 (label, value) 为已确认（幂等）；返回确认后的实际状态。 */
 export declare function confirmAdd(label: string, value: string): Promise<boolean>;

package/dist/types/filter.d.ts

@@ -1,16 +1,48 @@
-import type { Candidate, FilterOptions, FilteredCandidate } from './types.js';
+import type { Candidate, FilteredCandidate, FilterMode, FilterOptions } from './types.js';
+/** 将查询字符串拆分为小写关键字列表（空格分词、小写化、过滤空串）。 */
+export declare function splitKeywords(query: string): string[];
+/** 子串 AND：所有关键字都需作为子串出现（大小写不敏感）。 */
+export declare function matchSubstringAll(s: string, kws: string[]): boolean;
+/** token 前缀：按分隔符集合切 token，每关键字须匹配某 token 的前缀。 */
+export declare function matchTokenPrefixAll(s: string, kws: string[], sep: string): boolean;
+/** 子序列模糊：所有关键字都需作为子序列出现（大小写不敏感）。 */
+export declare function matchFuzzyAll(s: string, kws: string[]): boolean;
+/** pat 是否为 s 的子序列（不要求连续）。 */
+export declare function isSubsequence(pat: string, s: string): boolean;
+/** 排序并合并重叠的 [start, end) 区间（与 Go mergeRanges 一致）。 */
+export declare function mergeRanges(ranges: [number, number][]): [number, number][];
+/**
+ * highlightRanges 返回 s 中匹配关键字的 [start, end) rune 索引区间（已排序合并）。
+ * 空查询返回 []。
+ */
+export declare function highlightRanges(s: string, query: string, opts?: FilterOptions): [number, number][];
+/** 匹配模式分派：单候选是否命中全部关键字。 */
+export declare function matchCandidate(s: string, kws: string[], opts?: FilterOptions): boolean;
+export interface FilterOptsNormalized {
+    mode: FilterMode;
+    sep: string;
+}
+/** 归一化 FilterOptions（对齐协议 --mode/--sep 语义）。 */
+export declare function normalizeOpts(opts?: FilterOptions): FilterOptsNormalized;
+/**
+ * filterCands — 过滤 + 高亮区间（纯同步，保留输入顺序）。
+ * 描述不参与过滤——过滤永远针对"选中什么"而非"展示什么"。空查询返回全部。
+ */
+export declare function filterCands(cands: Candidate[], query: string, opts?: FilterOptions): FilteredCandidate[];
+/**
+ * autoResolve — 把查询字符串解析为唯一候选（供 --auto 自动选中）：
+ *   1. 精确匹配（大小写敏感）直接命中；
+ *   2. 否则大小写不敏感的唯一前缀匹配；
+ * 无匹配或多个前缀匹配时返回 null。
+ */
+export declare function autoResolve(cands: Candidate[], query: string): string | null;
 /**
  * filter — 过滤候选并返回命中项（保留输入顺序）+ 高亮区间。
- *
- * @param cands 候选（字符串或结构化 Candidate）
- * @param query 过滤关键字（空格分词，空串返回全部）
- * @param opts  匹配模式（默认 substring）
- * @returns 命中候选，`ranges` 为命中的 rune 区间（空查询恒为 []）
+ * 与协议 filter --json 等价；空查询返回全部（ranges 恒为 []）。
  */
 export declare function filter(cands: (string | Candidate)[], query?: string, opts?: FilterOptions): Promise<FilteredCandidate[]>;
 /**
  * resolve — 把 query 解析为唯一候选（精确 → 唯一前缀，大小写不敏感前缀）。
- *
- * @returns 解析出的选中值；无匹配/多个前缀匹配返回 null（引擎退出码 1）
+ * @returns 解析出的选中值；无匹配/多个前缀匹配/空 query 返回 null
  */
-export declare function resolve(cands: (string | Candidate)[], query: string, opts?: FilterOptions): Promise<string | null>;
+export declare function resolve(cands: (string | Candidate)[], query: string, _opts?: FilterOptions): Promise<string | null>;

package/dist/types/history.d.ts

@@ -1,4 +1,16 @@
+/** 选择记忆文件名；曾用名 picks.toml 因易与 pick 命令混淆而弃用。 */
+export declare const HISTORY_FILE = "history.toml";
+/** 旧版文件名，仅用于首次读取时自动迁移。 */
+export declare const LEGACY_HISTORY_FILE = "picks.toml";
+/** 返回选择记忆文件路径。 */
+export declare function historyPath(): string;
+/** history.toml 原始内容（label → { last }），与引擎同一份。 */
+export declare function loadPickHistory(): Map<string, string>;
+/** 取回 label 上次选中的值；无记录返回 ""。 */
+export declare function lastPick(raw: Map<string, string>, label: string): string;
+/** 记录 label 的上次选中值（保留其它 label 的记忆后写回）。 */
+export declare function savePick(label: string, value: string): void;
 /** 读取 label 上次选中的值；无记录返回 ""。 */
 export declare function histGet(label: string): Promise<string>;
-/** 记录 label 的上次选中值（成功无输出；失败抛 PicktuiError）。 */
+/** 记录 label 的上次选中值（失败抛 PicktuiError，含退出码 1）。 */
 export declare function histSet(label: string, value: string): Promise<void>;

package/dist/types/index.d.ts

@@ -4,8 +4,9 @@
  *   import { pick } from '@havocrao/picktui/tui'
  *   import { histGet } from '@havocrao/picktui/history'
  */
+/** 本 TS 实现的语义版本（对齐 npm 包版本号）。 */
+export declare const VERSION = "0.1.0";
 export * from './types.js';
-export * from './engine.js';
 export * from './filter.js';
 export * from './tui.js';
 export * from './history.js';