@havocrao/picktui 0.1.0 → 0.1.1

package/dist/cjs/tui.js

@@ -1,75 +1,493 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.OFF_ENV = void 0;
 exports.pick = pick;
 exports.menu = menu;
 exports.rawPick = rawPick;
+exports.runTui = runTui;
+exports.mapperScriptMissing = mapperScriptMissing;
 /**
- * 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）。
  */
-const engine_js_1 = require("./engine.js");
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_os_1 = require("node:os");
+const node_path_1 = require("node:path");
+const cand_js_1 = require("./cand.js");
+const confirm_js_1 = require("./confirm.js");
+const filter_js_1 = require("./filter.js");
+const history_js_1 = require("./history.js");
+const model_js_1 = require("./model.js");
+const tty_js_1 = require("./tty.js");
+const types_js_1 = require("./types.js");
+/** 命令名前缀（对齐引擎默认名，宿主品牌对齐不在本包范围）。 */
+const NAME = 'picktui';
+/** 非交互开关环境变量（值为 "off" 时 pick 跳过 TUI）。 */
+exports.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
  */
 async function pick(cands = [], flags = {}) {
-    const args = ['pick'];
-    if (flags.query !== undefined) {
-        args.push('-q', flags.query);
+    const structured = cands.length > 0 ? (0, cand_js_1.toStructuredCands)(cands) : [];
+    return pickFlow({
+        cands: structured,
+        fromCmd: '',
+        mapper: '',
+        flags,
+    });
+}
+/**
+ * menu — 多值缩写 TUI 菜单（数字 1-9 直选）。
+ * @returns 选中值；取消返回 null；参数不足抛 PicktuiError（退出码 2）
+ */
+async function menu(label, cands) {
+    if (cands.length < 1) {
+        const msg = `usage: ${NAME} _menu <label> <cand...>`;
+        throw new types_js_1.PicktuiError(msg, 2, msg);
+    }
+    const tty = (0, tty_js_1.openTty)();
+    if (tty === null) {
+        // 非交互：取首个候选（对齐引擎退化：保证脚本不卡）
+        return cands[0];
+    }
+    try {
+        const res = await runTui((0, model_js_1.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 !== '') {
+            (0, history_js_1.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'])
+ */
+async function rawPick(args) {
+    const parsed = parsePickArgs(args);
+    const structured = parsed.rest.length > 0 ? (0, cand_js_1.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 types_js_1.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 types_js_1.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 types_js_1.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 types_js_1.PicktuiError(`${NAME} pick: ${fromCmd}: ${raw.stderr}`, 1, raw.stderr);
+        }
+        cands = (0, cand_js_1.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 types_js_1.PicktuiError(msg, 1, msg);
     }
+    const label = flags.label ?? '';
+    const off = process.env[exports.OFF_ENV] === 'off';
+    // --auto 自动选中：query 精确命中或唯一前缀命中时直接输出（跳过 TUI）。
+    // 首次匹配该 (label, value) 需用户确认（记录 confirm 记录，之后不再询问）；
+    // off / 无 tty / 无 label 时跳过确认；拒绝确认回退下方 TUI。
+    if (flags.auto && query !== '') {
+        const v = (0, filter_js_1.autoResolve)(cands, query);
+        if (v !== null) {
+            if (label === '' || off || (0, confirm_js_1.isConfirmed)(label, v)) {
+                savePickIfLabeled(label, v);
+                return v;
+            }
+            const tty = (0, tty_js_1.openTty)();
+            if (tty !== null) {
+                try {
+                    const answer = await (0, tty_js_1.promptConfirm)(tty, `\r\n${NAME}: 首次自动匹配 ${label} → ${v}，确认执行？[y/N] `);
+                    if (answer !== null && /^(y|yes)$/i.test(answer.trim())) {
+                        (0, confirm_js_1.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 = (0, filter_js_1.filterCands)(cands, query, filterOpts);
+        if (filtered.length === 1) {
+            savePickIfLabeled(label, filtered[0].value);
+            return filtered[0].value;
+        }
+    }
+    // 非交互开关或无 tty → 退化路径
+    const tty = (0, tty_js_1.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((0, model_js_1.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 !== '') {
+            (0, confirm_js_1.confirm)(label, res.value);
+        }
+        savePickIfLabeled(label, res.value);
+        return res.value;
     }
-    const inv = await (0, engine_js_1.invokeEngine)(args, { input: (0, engine_js_1.serializeCandidates)(cands) });
-    if (inv.exitCode === 130) {
-        return null; // 取消
+    finally {
+        tty.read.destroy();
     }
-    (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;
+/** 非交互模式（对齐引擎 pickNonInteractive）。 */
+function pickNonInteractive(cands, query, opts, label, auto) {
+    if (auto && query !== '') {
+        const v = (0, filter_js_1.autoResolve)(cands, query);
+        if (v !== null) {
+            savePickIfLabeled(label, v);
+            return v;
+        }
+        const msg = `${NAME} pick: no unique match for "${query}"`;
+        throw new types_js_1.PicktuiError(msg, 1, msg);
+    }
+    if (query === '') {
+        const chosen = cands[0].value;
+        savePickIfLabeled(label, chosen);
+        return chosen;
     }
-    (0, engine_js_1.assertSuccess)(inv, 'picktui _menu');
-    return inv.stdout.replace(/\r?\n$/, '');
+    const filtered = (0, filter_js_1.filterCands)(cands, query, opts);
+    if (filtered.length === 0) {
+        const msg = `${NAME} pick: no match for "${query}"`;
+        throw new types_js_1.PicktuiError(msg, 1, msg);
+    }
+    const chosen = filtered[0].value;
+    savePickIfLabeled(label, chosen);
+    return chosen;
+}
+/** label 非空时记录选择记忆（失败不中断主流程，与引擎一致）。 */
+function savePickIfLabeled(label, value) {
+    if (label === '') {
+        return;
+    }
+    try {
+        (0, history_js_1.savePick)(label, value);
+    }
+    catch {
+        // 记忆只是锦上添花，记录失败不影响选中结果
+    }
+}
+/** 选择记忆：仅 query 为空时应用（有预填过滤词说明是精确搜索，不记忆）。 */
+function memoryInitial(label, cands) {
+    if (label === '') {
+        return 0;
+    }
+    try {
+        const last = (0, history_js_1.lastPick)((0, history_js_1.loadPickHistory)(), label);
+        if (last !== '') {
+            for (let i = 0; i < cands.length; i++) {
+                if (cands[i].value === last) {
+                    return i;
+                }
+            }
+        }
+    }
+    catch {
+        // 记忆损坏时静默回退首行
+    }
+    return 0;
+}
+/** 在 tty 上运行 TUI 选择器，返回（取消, 选中值, 多选勾选）。 */
+async function runTui(model, tty) {
+    (0, tty_js_1.enterInteractive)(tty);
+    const reader = new tty_js_1.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 = (0, model_js_1.update)(model, toKeyLike(k));
+                if (model.quit) {
+                    break;
+                }
+            }
+            else {
+                model = { ...model, phase: model.phase ^ 1 };
+            }
+            (0, tty_js_1.renderFrame)(tty, (0, model_js_1.view)(model));
+        }
+    }
+    finally {
+        (0, tty_js_1.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: (0, model_js_1.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 = (0, node_child_process_1.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 types_js_1.PicktuiError(msg, 1, msg);
+    }
+    const res = await runShell(mapper, input);
+    if (!res.ok) {
+        throw new types_js_1.PicktuiError(`${NAME} pick: --map ${mapper}: ${res.stderr}`, 1, res.stderr);
+    }
+    return (0, cand_js_1.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 等合法用法。
  */
-async function rawPick(args) {
-    const inv = await (0, engine_js_1.invokeEngine)(['pick', ...args]);
-    if (inv.exitCode === 130) {
-        return null;
+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 ((0, node_fs_1.existsSync)(p)) {
+            continue;
+        }
+        return p;
+    }
+    return '';
+}
+/** token 是否形如脚本文件路径：/ ./ ../ ~/ 前缀，或带常见脚本扩展名。 */
+function scriptPathLike(tok) {
+    if (tok.startsWith('/') || tok.startsWith('./') || tok.startsWith('../') || tok.startsWith('~/')) {
+        return true;
+    }
+    return isScriptExt((0, node_path_1.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 (0, node_os_1.homedir)();
     }
-    (0, engine_js_1.assertSuccess)(inv, 'picktui pick');
-    return inv.stdout.replace(/\r?\n$/, '');
+    if (p.startsWith('~/')) {
+        return (0, node_path_1.join)((0, node_os_1.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 !== '') {
+    (0, model_js_1.setColorEnabled)(false);
 }

package/dist/esm/cand.js

@@ -0,0 +1,47 @@
+/** 将 `string | Candidate` 输入序列化为协议结构化行（key<TAB>description）。 */
+export function serializeLines(cands) {
+    return cands.map((c) => (typeof c === 'string' ? c : c.desc ? `${c.value}\t${c.desc}` : c.value));
+}
+/** 将原始行列表解析为结构化候选（与 Go StructuredCandidates 同语义）。 */
+export 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 共用入口）。 */
+export function toStructuredCands(cands) {
+    return structuredCandidates(serializeLines(cands));
+}

package/dist/esm/config.js

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