@havocrao/picktui 0.1.0 → 0.1.1

package/README.md

@@ -1,7 +1,8 @@
-# @havocrao/picktui — TS/JS 绑定
+# @havocrao/picktui — TUI 候选选择器（纯 TypeScript）
 
-薄绑定：只做「候选传入、结果取回」，渲染/按键/匹配全部在 Go 引擎
-（`../go/cmd/picktui`）内完成，效果与 Go 宿主逐像素一致。
+纯 TS 实现：过滤/匹配/交互选择/记忆全部在 JS 内完成，**零运行时依赖、
+无需任何引擎二进制**，安装即用。行为与 Go 引擎（`../go/cmd/picktui`）语义
+逐项对齐（匹配算法、高亮区间、非交互退化、状态文件格式互兼容）。
 同份源码构建 esm + cjs + d.ts，TS 与 JS 共用。
 
 ## 安装
@@ -10,10 +11,10 @@
 $ npm install @havocrao/picktui
 ```
 
-引擎发现顺序：`$PICKTUI_BIN` → `$PATH` 中的 `picktui`。交互 TUI 由引擎跑在
-`/dev/tty`，本包 stdout 只回选中值。无 TTY 时引擎自动退化
-（无 query 取首个、有 query 过滤取首），绑定无需分支；
-取消（esc/ctrl+c）返回 `null`；协议错误抛出 `PicktuiError`（含 exitCode/stderr）。
+交互 TUI 由本包渲染：POSIX 上打开 `/dev/tty`（宿主 stdout 干净，`$(...)`
+安全）；无 `/dev/tty` 的环境（如 Windows）退化为宿主 stdio。无 TTY 时
+自动退化（无 query 取首个、有 query 过滤取首）；取消（esc/ctrl+c）
+返回 `null`；错误抛 `PicktuiError`（含 exitCode/stderr 诊断）。
 
 ## API
 
@@ -23,7 +24,7 @@ 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'
+import { VERSION } from '@havocrao/picktui'
 ```
 
 | 函数 | 说明 |
@@ -32,19 +33,21 @@ import { engineVersion, assertEngineVersion } from '@havocrao/picktui'
 | `resolve(cands, query)` | 精确/唯一前缀解析；无唯一解返回 `null` |
 | `pick(cands?, flags?)` | 交互过滤选择；`flags` 透传 `-q/--label/--sep/--fuzzy/-1/--auto` |
 | `menu(label, cands)` | 多值缩写菜单（数字 1-9 直选） |
-| `rawPick([...args])` | 透传引擎 pick 参数（`--from`/`--map` 等） |
+| `rawPick([...args])` | 透传 pick 参数（`--from`/`--map` 等） |
 | `histGet(label)` / `histSet(label, value)` | 选择记忆 |
 | `confirmCheck` / `confirmAdd` | 自动匹配首次确认（add 幂等） |
-| `assertEngineVersion(min?)` | 校验引擎版本不低于绑定声明的最低版本 |
+| `VERSION` | 本实现语义版本 |
+
+注：`pick` 候选来自参数（不读宿主进程自身 stdin）；需要命令/管道来源时用
+`rawPick(['--from', '<cmd>', ...])`（10s 超时，失败带 stderr 诊断）。
 
 ## 开发
 
 ```console
-$ npm install            # 安装 devDependencies（typescript）
+$ npm install            # 安装 devDependencies（typescript，无运行时依赖）
 $ npm run build          # tsc 双输出：dist/esm + dist/cjs + dist/types
-$ npm test               # pretest 自动构建引擎二进制 → node:test 集成测试
+$ npm test               # node:test 全量测试（filter/history/confirm/tui/model）
 $ npm run test:pack      # npm pack → 干净目录安装 → import/require 冒烟
 ```
 
-测试均为对真实引擎二进制的 JSON 往返（无 TTY 依赖）。交互 TUI 路径
-由引擎侧 model 级测试覆盖。
+测试均为纯 JS 断言，无需二进制或 TTY：交互 TUI 的按键行为由 model 级测试覆盖。

package/dist/cjs/cand.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeLines = serializeLines;
+exports.structuredCandidates = structuredCandidates;
+exports.toStructuredCands = toStructuredCands;
+/** 将 `string | Candidate` 输入序列化为协议结构化行（key<TAB>description）。 */
+function serializeLines(cands) {
+    return cands.map((c) => (typeof c === 'string' ? c : c.desc ? `${c.value}\t${c.desc}` : c.value));
+}
+/** 将原始行列表解析为结构化候选（与 Go StructuredCandidates 同语义）。 */
+function structuredCandidates(lines) {
+    const idx = new Map();
+    const out = [];
+    for (const line of lines) {
+        let value = line;
+        let desc = '';
+        const tab = line.indexOf('\t');
+        if (tab >= 0) {
+            value = line.slice(0, tab);
+            desc = line.slice(tab + 1);
+        }
+        value = value.trim();
+        if (value === '') {
+            continue;
+        }
+        if (value.startsWith('* ')) {
+            value = value.slice(2);
+        }
+        else if (value.startsWith('+ ')) {
+            value = value.slice(2);
+        }
+        value = value.trim();
+        if (value === '') {
+            continue;
+        }
+        desc = desc.trim();
+        const j = idx.get(value);
+        if (j !== undefined) {
+            if (out[j].desc === '' && desc !== '') {
+                out[j] = { value, desc };
+            }
+            continue;
+        }
+        idx.set(value, out.length);
+        out.push({ value, desc });
+    }
+    return out;
+}
+/** 输入候选统一解析为结构化候选（filter/resolve/pick 共用入口）。 */
+function toStructuredCands(cands) {
+    return structuredCandidates(serializeLines(cands));
+}

package/dist/cjs/config.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dataDir = dataDir;
+/**
+ * config — 数据目录解析（对齐协议：hist/confirm/pick --label 状态文件所在）。
+ *
+ * 优先级：$PICKTUI_CONFIG_DIR → $XDG_CONFIG_HOME/picktui → ~/.config/picktui。
+ */
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+/** 状态文件目录（history.toml / confirm.toml 所在）。 */
+function dataDir() {
+    const explicit = process.env.PICKTUI_CONFIG_DIR;
+    if (explicit) {
+        return explicit;
+    }
+    const base = process.env.XDG_CONFIG_HOME || (0, node_path_1.join)((0, node_os_1.homedir)(), '.config');
+    return (0, node_path_1.join)(base, 'picktui');
+}

package/dist/cjs/confirm.js

@@ -1,28 +1,105 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONFIRM_FILE = void 0;
+exports.confirmPath = confirmPath;
+exports.loadConfirmed = loadConfirmed;
+exports.isConfirmed = isConfirmed;
+exports.confirm = confirm;
+exports.parseConfirmAnswer = parseConfirmAnswer;
 exports.confirmCheck = confirmCheck;
 exports.confirmAdd = confirmAdd;
 /**
- * confirm — 自动匹配首次确认（文件状态，直调引擎 confirm 子命令）。
+ * confirm — 自动匹配的首次用户确认记录（confirm.toml）。
  *
- * 状态文件位于引擎数据目录，与 pick --auto 的确认记录同一份：
- * 首次自动匹配某 (label, value) 需确认，确认后不再询问。
+ * 文件格式与 Go 引擎 BurntSushi/toml 输出完全兼容：
+ *
+ *	# picktui confirm — user-confirmed auto resolutions (auto-managed)
+ *	[confirmed]
+ *	"npm run" = ["release", "dev"]
+ *
+ * label 为空时不做任何落盘（返回 false）。文件不存在或损坏 → 空记录
+ * （确认记录只是安全辅助，缺失最多导致首次匹配再次询问）。
  */
-const engine_js_1 = require("./engine.js");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const config_js_1 = require("./config.js");
+const toml_js_1 = require("./toml.js");
+const types_js_1 = require("./types.js");
+/** 自动匹配确认记录文件名。 */
+exports.CONFIRM_FILE = 'confirm.toml';
+/** 注释头（对齐引擎输出）。 */
+const HEADER = '# picktui confirm — user-confirmed auto resolutions (auto-managed)';
+/** 返回确认记录文件路径。 */
+function confirmPath() {
+    return (0, node_path_1.join)((0, config_js_1.dataDir)(), exports.CONFIRM_FILE);
+}
+/** 解码 confirm.toml 为 label → 已确认值列表；缺失/损坏时返回空 Map。 */
+function loadConfirmed() {
+    const p = confirmPath();
+    if (!(0, node_fs_1.existsSync)(p)) {
+        return new Map();
+    }
+    const doc = (0, toml_js_1.parseToml)((0, node_fs_1.readFileSync)(p, 'utf8'));
+    if (doc === null) {
+        return new Map();
+    }
+    const confirmed = doc.get('confirmed');
+    if (!confirmed) {
+        return new Map();
+    }
+    const out = new Map();
+    for (const [label, values] of confirmed) {
+        if (Array.isArray(values)) {
+            out.set(label, values.map(String));
+        }
+    }
+    return out;
+}
+/** 报告 (label, value) 是否已被确认过；label 为空时恒为 false。 */
+function isConfirmed(label, value) {
+    if (label === '') {
+        return false;
+    }
+    return (loadConfirmed().get(label) ?? []).includes(value);
+}
+/** 记录 (label, value) 为已确认（幂等；label 为空不落盘）。 */
+function confirm(label, value) {
+    if (label === '') {
+        return;
+    }
+    const m = loadConfirmed();
+    const list = m.get(label) ?? [];
+    if (list.includes(value)) {
+        return;
+    }
+    list.push(value);
+    m.set(label, list);
+    const lines = [HEADER, '[confirmed]'];
+    const labels = [...m.keys()].sort();
+    for (const l of labels) {
+        const values = (m.get(l) ?? []).map(toml_js_1.escapeTomlString).map((v) => `"${v}"`);
+        lines.push(`${(0, toml_js_1.keyLiteral)(l)} = [${values.join(', ')}]`);
+    }
+    const p = confirmPath();
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(p), { recursive: true });
+        (0, node_fs_1.writeFileSync)(p, lines.join('\n') + '\n', { mode: 0o644 });
+    }
+    catch (err) {
+        throw new types_js_1.PicktuiError(`写入确认记录失败：${err instanceof Error ? err.message : String(err)}`, 1, '');
+    }
+}
+/** 解析确认回答：y/yes（大小写不敏感，容忍首尾空白）为确认。 */
+function parseConfirmAnswer(s) {
+    const t = s.trim().toLowerCase();
+    return t === 'y' || t === 'yes';
+}
 /** 报告 (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;
+    return isConfirmed(label, value);
 }
-/**
- * 记录 (label, value) 为已确认（幂等）。
- * @returns 确认后的实际状态（label 为空时不落盘 → false）
- */
+/** 记录 (label, value) 为已确认（幂等）；返回确认后的实际状态。 */
 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;
+    confirm(label, value);
+    return isConfirmed(label, value);
 }

package/dist/cjs/filter.js

@@ -1,49 +1,312 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitKeywords = splitKeywords;
+exports.matchSubstringAll = matchSubstringAll;
+exports.matchTokenPrefixAll = matchTokenPrefixAll;
+exports.matchFuzzyAll = matchFuzzyAll;
+exports.isSubsequence = isSubsequence;
+exports.mergeRanges = mergeRanges;
+exports.highlightRanges = highlightRanges;
+exports.matchCandidate = matchCandidate;
+exports.normalizeOpts = normalizeOpts;
+exports.filterCands = filterCands;
+exports.autoResolve = autoResolve;
 exports.filter = filter;
 exports.resolve = resolve;
 /**
- * filter / resolve — 纯函数数据面（直调引擎 filter/resolve --json）。
+ * filter / resolve — 纯 TS 过滤匹配引擎（对齐 Go filter.go，零依赖）。
  *
- * 过滤与高亮区间由引擎权威计算；本模块只做「候选传入、JSON 取回」，
- * 禁止重实现匹配（详见 docs/integration/protocol.md 兼容性承诺）。
+ * 三种匹配模式（与协议一致）：
+ *   - 子串 AND（默认）：空格分关键字，全部命中才保留，大小写不敏感
+ *   - token 前缀（--sep <chars>）：按分隔符集合切 token（默认 _，可多字符如 ":_"），
+ *     每关键字匹配某 token 前缀
+ *   - 子序列模糊（--fuzzy）：关键字为子序列
+ *
+ * 高亮区间为 rune（code point）索引 [start, end)，排序合并；空查询恒 []。
  */
-const engine_js_1 = require("./engine.js");
-/** 将 FilterOptions 转为引擎参数。 */
-function modeArgs(opts) {
-    const args = [];
-    if (opts.mode && opts.mode !== 'substring') {
-        args.push('--mode', opts.mode);
+const cand_js_1 = require("./cand.js");
+/** 默认分隔符集合（token 模式）。 */
+const DEFAULT_SEP = '_';
+/** 将查询字符串拆分为小写关键字列表（空格分词、小写化、过滤空串）。 */
+function splitKeywords(query) {
+    const fields = query.trim().split(/\s+/).filter(Boolean);
+    return fields.map((f) => f.toLowerCase());
+}
+/** 按 rune 切分字符串为 code point 数组（与 Go []rune 对齐）。 */
+function toRunes(s) {
+    return [...s];
+}
+/** 某 rune 是否在分隔符集合中。 */
+function sepSetOf(sep) {
+    return new Set(toRunes(sep));
+}
+/** 按分隔符集合切分 runes，返回每个非空 token 的 [start, end) rune 索引区间。 */
+function splitRuneRanges(runes, seps) {
+    if (seps.size === 0) {
+        return runes.length > 0 ? [[0, runes.length]] : [];
+    }
+    const ranges = [];
+    let start = 0;
+    for (let i = 0; i < runes.length; i++) {
+        if (seps.has(runes[i])) {
+            if (i > start) {
+                ranges.push([start, i]);
+            }
+            start = i + 1;
+        }
+    }
+    if (start < runes.length) {
+        ranges.push([start, runes.length]);
+    }
+    return ranges;
+}
+/** 按分隔符集合切分字符串为 token 列表（供匹配用）。 */
+function splitTokens(s, seps) {
+    if (seps.size === 0) {
+        return [s];
+    }
+    const tokens = [];
+    let cur = '';
+    for (const r of s) {
+        if (seps.has(r)) {
+            if (cur !== '') {
+                tokens.push(cur);
+                cur = '';
+            }
+        }
+        else {
+            cur += r;
+        }
+    }
+    if (cur !== '') {
+        tokens.push(cur);
+    }
+    return tokens;
+}
+/** 子串 AND：所有关键字都需作为子串出现（大小写不敏感）。 */
+function matchSubstringAll(s, kws) {
+    const lower = s.toLowerCase();
+    return kws.every((kw) => lower.includes(kw));
+}
+/** token 前缀：按分隔符集合切 token，每关键字须匹配某 token 的前缀。 */
+function matchTokenPrefixAll(s, kws, sep) {
+    const seps = sepSetOf(sep === '' ? DEFAULT_SEP : sep);
+    const tokens = splitTokens(s.toLowerCase(), seps);
+    return kws.every((kw) => tokens.some((tok) => tok.startsWith(kw)));
+}
+/** 子序列模糊：所有关键字都需作为子序列出现（大小写不敏感）。 */
+function matchFuzzyAll(s, kws) {
+    const lower = s.toLowerCase();
+    return kws.every((kw) => isSubsequence(kw, lower));
+}
+/** pat 是否为 s 的子序列（不要求连续）。 */
+function isSubsequence(pat, s) {
+    if (pat === '') {
+        return true;
     }
-    if (opts.mode === 'token' && opts.sep) {
-        args.push('--sep', opts.sep);
+    let pi = 0;
+    for (let si = 0; si < s.length && pi < pat.length; si++) {
+        if (s[si] === pat[pi]) {
+            pi++;
+        }
     }
-    return args;
+    return pi === pat.length;
+}
+/** rune 索引：在 s 中查找 substr 的首个出现位置，未找到返回 -1。 */
+function runeIndex(s, substr) {
+    if (substr.length === 0 || substr.length > s.length) {
+        return -1;
+    }
+    for (let i = 0; i <= s.length - substr.length; i++) {
+        let match = true;
+        for (let j = 0; j < substr.length; j++) {
+            if (s[i + j] !== substr[j]) {
+                match = false;
+                break;
+            }
+        }
+        if (match) {
+            return i;
+        }
+    }
+    return -1;
+}
+/** 排序并合并重叠的 [start, end) 区间（与 Go mergeRanges 一致）。 */
+function mergeRanges(ranges) {
+    if (ranges.length === 0) {
+        return [];
+    }
+    const sorted = [...ranges].sort((a, b) => (a[0] !== b[0] ? a[0] - b[0] : a[1] - b[1]));
+    const merged = [sorted[0]];
+    for (let i = 1; i < sorted.length; i++) {
+        const last = merged[merged.length - 1];
+        const r = sorted[i];
+        if (r[0] <= last[1]) {
+            if (r[1] > last[1]) {
+                last[1] = r[1];
+            }
+        }
+        else {
+            merged.push(r);
+        }
+    }
+    return merged;
+}
+/**
+ * highlightRanges 返回 s 中匹配关键字的 [start, end) rune 索引区间（已排序合并）。
+ * 空查询返回 []。
+ */
+function highlightRanges(s, query, opts = {}) {
+    const kws = splitKeywords(query);
+    if (kws.length === 0) {
+        return [];
+    }
+    const lowerRunes = toRunes(s.toLowerCase());
+    const ranges = [];
+    const mode = opts.mode ?? 'substring';
+    if (mode === 'token') {
+        const seps = sepSetOf(opts.sep === undefined || opts.sep === '' ? DEFAULT_SEP : opts.sep);
+        const tokRanges = splitRuneRanges(lowerRunes, seps);
+        for (const kw of kws) {
+            const kwRunes = toRunes(kw);
+            if (kwRunes.length === 0) {
+                continue;
+            }
+            for (const tr of tokRanges) {
+                const tok = lowerRunes.slice(tr[0], tr[1]);
+                if (hasRunePrefix(tok, kwRunes)) {
+                    ranges.push([tr[0], tr[0] + kwRunes.length]);
+                    break;
+                }
+            }
+        }
+    }
+    else if (mode === 'fuzzy') {
+        for (const kw of kws) {
+            const positions = subsequenceRunePositions(toRunes(kw), lowerRunes);
+            for (const p of positions) {
+                ranges.push([p, p + 1]);
+            }
+        }
+    }
+    else {
+        for (const kw of kws) {
+            const kwRunes = toRunes(kw);
+            if (kwRunes.length === 0) {
+                continue;
+            }
+            const idx = runeIndex(lowerRunes, kwRunes);
+            if (idx >= 0) {
+                ranges.push([idx, idx + kwRunes.length]);
+            }
+        }
+    }
+    return mergeRanges(ranges);
+}
+function hasRunePrefix(s, prefix) {
+    if (prefix.length > s.length) {
+        return false;
+    }
+    for (let i = 0; i < prefix.length; i++) {
+        if (s[i] !== prefix[i]) {
+            return false;
+        }
+    }
+    return true;
+}
+/** 返回 pat 作为 s 子序列匹配时的各字符 rune 位置；不完整匹配返回 []。 */
+function subsequenceRunePositions(pat, s) {
+    if (pat.length === 0) {
+        return [];
+    }
+    const positions = [];
+    let pi = 0;
+    for (let si = 0; si < s.length && pi < pat.length; si++) {
+        if (s[si] === pat[pi]) {
+            positions.push(si);
+            pi++;
+        }
+    }
+    if (pi < pat.length) {
+        return [];
+    }
+    return positions;
+}
+/** 匹配模式分派：单候选是否命中全部关键字。 */
+function matchCandidate(s, kws, opts = {}) {
+    switch (opts.mode ?? 'substring') {
+        case 'token':
+            return matchTokenPrefixAll(s, kws, opts.sep ?? '');
+        case 'fuzzy':
+            return matchFuzzyAll(s, kws);
+        default:
+            return matchSubstringAll(s, kws);
+    }
+}
+/** 归一化 FilterOptions（对齐协议 --mode/--sep 语义）。 */
+function normalizeOpts(opts = {}) {
+    return { mode: opts.mode ?? 'substring', sep: opts.sep ?? '' };
+}
+/**
+ * filterCands — 过滤 + 高亮区间（纯同步，保留输入顺序）。
+ * 描述不参与过滤——过滤永远针对"选中什么"而非"展示什么"。空查询返回全部。
+ */
+function filterCands(cands, query, opts = {}) {
+    const kws = splitKeywords(query);
+    if (kws.length === 0) {
+        return cands.map((c) => ({ value: c.value, desc: c.desc ?? '', ranges: [] }));
+    }
+    const norm = normalizeOpts(opts);
+    const out = [];
+    for (const c of cands) {
+        if (matchCandidate(c.value, kws, norm)) {
+            out.push({
+                value: c.value,
+                desc: c.desc ?? '',
+                ranges: highlightRanges(c.value, query, norm),
+            });
+        }
+    }
+    return out;
+}
+/**
+ * autoResolve — 把查询字符串解析为唯一候选（供 --auto 自动选中）：
+ *   1. 精确匹配（大小写敏感）直接命中；
+ *   2. 否则大小写不敏感的唯一前缀匹配；
+ * 无匹配或多个前缀匹配时返回 null。
+ */
+function autoResolve(cands, query) {
+    if (query === '') {
+        return null;
+    }
+    for (const c of cands) {
+        if (c.value === query) {
+            return c.value;
+        }
+    }
+    const lq = query.toLowerCase();
+    let only = null;
+    for (const c of cands) {
+        if (c.value.toLowerCase().startsWith(lq)) {
+            if (only !== null && only !== c.value) {
+                return null; // 多个前缀匹配，无法唯一确定
+            }
+            only = c.value;
+        }
+    }
+    return only;
 }
 /**
  * filter — 过滤候选并返回命中项（保留输入顺序）+ 高亮区间。
- *
- * @param cands 候选（字符串或结构化 Candidate）
- * @param query 过滤关键字（空格分词，空串返回全部）
- * @param opts  匹配模式（默认 substring）
- * @returns 命中候选，`ranges` 为命中的 rune 区间（空查询恒为 []）
+ * 与协议 filter --json 等价；空查询返回全部（ranges 恒为 []）。
  */
-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');
+function filter(cands, query = '', opts = {}) {
+    return Promise.resolve(filterCands((0, cand_js_1.toStructuredCands)(cands), query, opts));
 }
 /**
  * resolve — 把 query 解析为唯一候选（精确 → 唯一前缀，大小写不敏感前缀）。
- *
- * @returns 解析出的选中值；无匹配/多个前缀匹配返回 null（引擎退出码 1）
+ * @returns 解析出的选中值；无匹配/多个前缀匹配/空 query 返回 null
  */
-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;
+function resolve(cands, query, _opts = {}) {
+    return Promise.resolve(autoResolve((0, cand_js_1.toStructuredCands)(cands), query));
 }