squidcloudctl 1.2.0 → 3.0.0

package/dist/lib/host/server.js

@@ -0,0 +1,240 @@
+import http from 'node:http';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { MicroRedis } from './microredis.js';
+import { authenticateRequest, resolveProfile, generateApiKey } from './security.js';
+const AUDIT_FILE = path.join(os.homedir(), '.squidcloud', 'host-audit.log');
+export async function startHost(opts) {
+    const redis = new MicroRedis();
+    const cfg = resolveProfile(opts.profile, {
+        mode: opts.mode,
+        hmac: !!opts.hmacSecret,
+    });
+    if (opts.hmacSecret)
+        redis.set('host:hmac-secret', opts.hmacSecret);
+    await redis.listen(opts.redisPort, '127.0.0.1');
+    const auditStream = fs.createWriteStream(AUDIT_FILE, { flags: 'a' });
+    const audit = (line) => {
+        auditStream.write(`${new Date().toISOString()} ${line}\n`);
+    };
+    // Seed one local key so keyed modes are usable immediately.
+    if (cfg.requireKey) {
+        const k = generateApiKey();
+        redis.set(`key:${k.hash}`, k.prefix);
+        opts.onBootstrapKey?.(k.key);
+    }
+    const server = http.createServer((req, res) => {
+        collect(req, cfg.maxBodyBytes)
+            .then(async ({ body }) => {
+            const started = Date.now();
+            const auth = authenticateRequest(req, cfg, redis, body.length > 0 ? body : undefined);
+            if (!auth.ok) {
+                audit(`DENY ${req.method} ${req.url} ip=${req.socket.remoteAddress} why=${auth.error}`);
+                return json(res, auth.status ?? 401, { error: auth.error, profile: cfg.profile });
+            }
+            const url = new URL(req.url || '/', 'http://localhost');
+            const route = `${req.method} ${url.pathname}`;
+            try {
+                const handled = await route_(req, res, url, body, cfg, redis, opts);
+                if (!handled)
+                    return json(res, 404, { error: `No route: ${route}`, hint: 'GET /health lists nothing — see docs for routes' });
+                audit(`OK ${route} key=${auth.keyId} ${Date.now() - started}ms`);
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                audit(`ERR ${route} ${message}`);
+                json(res, /not authenticated|login/i.test(message) ? 4401 : 500, { error: message });
+            }
+        })
+            .catch((e) => json(res, 400, { error: e instanceof Error ? e.message : String(e) }));
+    });
+    await new Promise((resolve) => server.listen(opts.port, '127.0.0.1', () => resolve()));
+    return {
+        redis,
+        cfg,
+        port: opts.port,
+        redisPort: opts.redisPort,
+        server,
+        audit,
+        newKey() {
+            const k = generateApiKey();
+            redis.set(`key:${k.hash}`, k.prefix);
+            return k;
+        },
+        close() {
+            server.close();
+            redis.close();
+            auditStream.end();
+        },
+    };
+}
+/* ── routing ── */
+async function route_(req, res, url, body, cfg, redis, opts) {
+    const method = req.method || 'GET';
+    const p = url.pathname.replace(/\/+$/, '') || '/';
+    const seg = p.split('/').filter(Boolean);
+    if (method === 'GET' && p === '/health') {
+        return json(res, 200, {
+            status: 'ok',
+            host: 'squidcloudctl',
+            profile: cfg.profile,
+            mode: cfg.requireKey ? 'keyed' : 'open',
+            redis: { port: opts.redisPort, keys: redis.size() },
+            uptime_s: Math.round(process.uptime()),
+        }), true;
+    }
+    /* files */
+    if (method === 'GET' && p === '/v1/files') {
+        const search = url.searchParams.get('search') || undefined;
+        const cacheKey = `cache:files:${search ?? ''}`;
+        if (cfg.cacheTtlMs > 0) {
+            const hit = redis.get(cacheKey);
+            if (hit)
+                return json(res, 200, JSON.parse(hit)), true;
+        }
+        const { listFiles } = await import('../refs.js');
+        const entries = await listFiles({ search, refresh: true });
+        const payload = { count: entries.length, files: entries };
+        if (cfg.cacheTtlMs > 0)
+            redis.set(cacheKey, JSON.stringify(payload), cfg.cacheTtlMs);
+        return json(res, 200, payload), true;
+    }
+    if (method === 'GET' && seg[0] === 'v1' && seg[1] === 'files' && seg.length === 3) {
+        const { resolveFileRef } = await import('../refs.js');
+        const { apiGet } = await import('../api/client.js');
+        const { entry } = await resolveFileRef(decodeURIComponent(seg[2]));
+        const full = await apiGet(`/files/${entry.id}/metadata`);
+        const file = (full.file || entry);
+        return json(res, 200, { ...file, _resolved_via: entry.id }), true;
+    }
+    if (method === 'DELETE' && seg[0] === 'v1' && seg[1] === 'files' && seg.length === 3) {
+        const { resolveFileRef } = await import('../refs.js');
+        const { apiDelete } = await import('../api/client.js');
+        const { entry } = await resolveFileRef(decodeURIComponent(seg[2]));
+        await apiDelete(`/files/${entry.id}`);
+        redis.del(`cache:files:`);
+        return json(res, 200, { deleted: entry.id, name: entry.name }), true;
+    }
+    if ((method === 'POST' || method === 'PATCH') && seg[0] === 'v1' && seg[1] === 'files' && seg[3] === 'rename') {
+        const parsed = JSON.parse(body.toString('utf8') || '{}');
+        const { resolveFileRef } = await import('../refs.js');
+        const { apiPut } = await import('../api/client.js');
+        const { entry } = await resolveFileRef(decodeURIComponent(seg[2]));
+        await apiPut(`/files/${entry.id}/rename`, { name: String(parsed.name || '') });
+        return json(res, 200, { renamed: entry.id, name: String(parsed.name || '') }), true;
+    }
+    /* upload — raw bytes as body */
+    if (method === 'POST' && p === '/v1/upload') {
+        const filename = url.searchParams.get('filename') || 'upload.bin';
+        const tmp = path.join(os.tmpdir(), `sq-host-${Date.now()}-${Math.random().toString(36).slice(2)}`);
+        fs.writeFileSync(tmp, body);
+        try {
+            const { uploadFile } = await import('../transfer.js');
+            const r = await uploadFile(tmp, { folderId: url.searchParams.get('folder_id'), quiet: true });
+            return json(res, 201, { id: r.id, name: r.name, size: r.size }), true;
+        }
+        finally {
+            fs.rmSync(tmp, { force: true });
+        }
+    }
+    /* download — streams plaintext through this host */
+    if (method === 'GET' && seg[0] === 'v1' && seg[1] === 'download' && seg.length === 3) {
+        const { resolveFileRef } = await import('../refs.js');
+        const { downloadFile } = await import('../transfer.js');
+        const { entry } = await resolveFileRef(decodeURIComponent(seg[2]));
+        const tmp = path.join(os.tmpdir(), `sq-dl-${Date.now()}`);
+        const finalPath = await downloadFile({ id: entry.id, name: entry.name }, tmp);
+        const data = fs.readFileSync(finalPath);
+        fs.rmSync(finalPath, { force: true });
+        res.writeHead(200, {
+            'Content-Type': 'application/octet-stream',
+            'Content-Length': data.length,
+            'X-Squidcloud-File-Id': entry.id,
+            'Content-Disposition': `attachment; filename="${entry.name}"`,
+        });
+        res.end(data);
+        return true;
+    }
+    /* share */
+    if (method === 'POST' && p === '/v1/share') {
+        const parsed = JSON.parse(body.toString('utf8') || '{}');
+        const { apiPost } = await import('../api/client.js');
+        const bodyOut = {};
+        if (parsed.file_ref) {
+            const { resolveFileRef } = await import('../refs.js');
+            bodyOut.file_id = (await resolveFileRef(String(parsed.file_ref))).entry.id;
+        }
+        if (parsed.folder_id)
+            bodyOut.folder_id = parsed.folder_id;
+        if (parsed.expires_at)
+            bodyOut.expires_at = parsed.expires_at;
+        if (parsed.max_downloads !== undefined)
+            bodyOut.max_downloads = Number(parsed.max_downloads);
+        if (parsed.view_only)
+            bodyOut.view_only = true;
+        const r = await apiPost('/shares', bodyOut);
+        return json(res, 201, r), true;
+    }
+    /* secrets (read-only list + create) */
+    if (method === 'GET' && p === '/v1/secrets') {
+        const { apiGet } = await import('../api/client.js');
+        const r = await apiGet('/secrets');
+        return json(res, 200, { secrets: r.secrets || [] }), true;
+    }
+    /* exec bridge — whitelisted read-only ops so applications can extend on
+       top of the exact CLI logic without shelling out. */
+    if (method === 'POST' && p === '/v1/exec') {
+        const parsed = JSON.parse(body.toString('utf8') || '{}');
+        const op = parsed.op || '';
+        const args = parsed.args || {};
+        switch (op) {
+            case 'whoami': {
+                const { apiGet } = await import('../api/client.js');
+                return json(res, 200, await apiGet('/user/whoami')), true;
+            }
+            case 'storage.search': {
+                const { listFiles } = await import('../refs.js');
+                const q = String(args.query || '');
+                const entries = await listFiles({ search: q, refresh: true });
+                return json(res, 200, { matches: entries.length, files: entries }), true;
+            }
+            case 'stats': {
+                const { apiGet } = await import('../api/client.js');
+                return json(res, 200, await apiGet('/user/whoami')), true;
+            }
+            default:
+                return json(res, 400, {
+                    error: `Unknown op '${op}'`,
+                    allowed: ['whoami', 'storage.search', 'stats'],
+                    note: 'exec is deliberately read-only — use the resource routes for mutations',
+                }), true;
+        }
+    }
+    return false;
+}
+/* ── helpers ── */
+function json(res, status, payload) {
+    if (!res.headersSent) {
+        res.writeHead(status, { 'Content-Type': 'application/json' });
+    }
+    res.end(JSON.stringify(payload));
+    return true;
+}
+function collect(req, maxBytes) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (c) => {
+            size += c.length;
+            if (size > maxBytes) {
+                reject(new Error(`Body exceeds limit (${maxBytes} bytes) — tune --max-body`));
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => resolve({ body: Buffer.concat(chunks) }));
+        req.on('error', reject);
+    });
+}

package/dist/lib/output/banner.js

@@ -0,0 +1,36 @@
+import chalk from 'chalk';
+import gradient from 'gradient-string';
+/* ANSI-shadow lettering for SQUIDCLOUD — same letterforms as the website
+   wordmark. Rendered as plain text so it degrades cleanly without TTY. */
+const GLYPHS = {
+    S: ['███████╗', '██╔════╝', '███████╗', '╚════██║', '███████║', '╚══════╝'],
+    Q: [' ██████╗ ', '██╔═══██╗', '██║   ██║', '██║▄▄ ██║', '╚██████╔╝', ' ╚══▀▀═╝ '],
+    U: ['██╗   ██╗', '██║   ██║', '██║   ██║', '██║   ██║', '╚██████╔╝', ' ╚═════╝ '],
+    I: ['██╗', '██║', '██║', '██║', '██║', '╚═╝'],
+    D: ['██████╗ ', '██╔══██╗', '██║  ██║', '██║  ██║', '██████╔╝', '╚═════╝ '],
+    C: [' ██████╗', '██╔════╝', '██║     ', '██║     ', '╚██████╗', ' ╚═════╝'],
+    L: ['██╗     ', '██║     ', '██║     ', '██║     ', '███████╗', '╚══════╝'],
+    O: [' ██████╗ ', '██╔═══██╗', '██║   ██║', '██║   ██║', '╚██████╔╝', ' ╚═════╝ '],
+};
+export function squidAsciiArt(word = 'SQUIDCLOUD') {
+    return [0, 1, 2, 3, 4, 5].map((r) => word.split('').map((ch) => GLYPHS[ch]?.[r] ?? '').join(''));
+}
+const squidGradient = gradient(['#4FC3F7', '#7C4DFF']);
+const fogGradient = gradient(['#e4e4e7', '#a1a1aa']);
+export function renderBanner(opts = {}) {
+    const lines = squidAsciiArt();
+    const colored = lines.map((l) => fogGradient(l));
+    const out = [];
+    out.push('');
+    out.push(...colored);
+    if (opts.tagline !== false) {
+        out.push('');
+        out.push(`   ${squidGradient('SQUIDCLOUD CTL')}  ${chalk.dim('encrypted storage · shares · secrets · pipelines')}`);
+    }
+    out.push('');
+    return out.join('\n');
+}
+/** Compact one-line wordmark for tight contexts. */
+export function renderWordmark() {
+    return squidGradient('■ SQUIDCLOUD CTL');
+}

package/dist/lib/output/brand.js

@@ -0,0 +1,37 @@
+import chalk from 'chalk';
+import gradient from 'gradient-string';
+const squidGradient = gradient(['#4FC3F7', '#7C4DFF']);
+const dimGradient = gradient(['#1a5276', '#4a148c']);
+export const BRAND_MARKER = squidGradient('◆');
+export const SUCCESS_MARK = chalk.hex('#4CAF50')('✓');
+export const ERROR_MARK = chalk.hex('#F44336')('✗');
+export const WARN_MARK = chalk.hex('#FF9800')('⚠');
+export const INFO_MARK = chalk.hex('#4FC3F7')('ℹ');
+export const PROGRESS_MARK = chalk.hex('#7C4DFF')('▸');
+export function brand(text) {
+    return squidGradient(text);
+}
+export function brandDim(text) {
+    return dimGradient(text);
+}
+export function brandLine(text) {
+    return `${BRAND_MARKER} ${brand(text)}`;
+}
+export function success(text) {
+    return `${SUCCESS_MARK} ${chalk.green(text)}`;
+}
+export function error(text) {
+    return `${ERROR_MARK} ${chalk.red(text)}`;
+}
+export function warn(text) {
+    return `${WARN_MARK} ${chalk.hex('#FF9800')(text)}`;
+}
+export function info(text) {
+    return `${INFO_MARK} ${chalk.hex('#4FC3F7')(text)}`;
+}
+export function muted(text) {
+    return chalk.dim(text);
+}
+export function copied(text) {
+    return muted(`(copied to clipboard)`);
+}

package/dist/lib/output/index.js

@@ -0,0 +1,11 @@
+export { renderMascot, renderBrandedMascot } from './mascot.js';
+export { brand, brandDim, brandLine, success, error, warn, info, muted, copied, BRAND_MARKER, SUCCESS_MARK, ERROR_MARK, WARN_MARK, INFO_MARK, PROGRESS_MARK } from './brand.js';
+export { setJsonMode, isJsonMode, log, logSuccess, logError, logWarn, logInfo, logBrand, logRaw, logJSON, logErrorJSON, writeAudit } from './logger.js';
+export { createSpinner } from './spinner.js';
+export { createTable, renderTable, renderCompactTable } from './table.js';
+export function isCI() {
+    return !!(process.env.CI ||
+        process.env.GITHUB_ACTIONS ||
+        process.env.GITLAB_CI ||
+        process.env.CIRCLECI);
+}

package/dist/lib/output/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/lib/output/logger.js

@@ -0,0 +1,114 @@
+import chalk from 'chalk';
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { isCI } from '../utils/ci-detect.js';
+import { BRAND_MARKER, SUCCESS_MARK, ERROR_MARK, WARN_MARK, INFO_MARK } from './brand.js';
+let jsonMode = false;
+export function setJsonMode(mode) {
+    jsonMode = mode;
+}
+export function isJsonMode() {
+    return jsonMode;
+}
+function timestamp() {
+    return chalk.dim(`[${new Date().toISOString()}]`);
+}
+export function log(message, options) {
+    if (jsonMode)
+        return;
+    const prefix = options?.prefix ? `${options.prefix} ` : '';
+    if (isCI()) {
+        console.log(`${timestamp()} ${prefix}${message}`);
+    }
+    else {
+        console.log(`${prefix}${message}`);
+    }
+}
+export function logSuccess(message) {
+    if (jsonMode) {
+        console.log(JSON.stringify({ level: 'success', message }));
+        return;
+    }
+    if (isCI()) {
+        console.log(`${timestamp()} ${SUCCESS_MARK} ${message}`);
+    }
+    else {
+        console.log(`${SUCCESS_MARK} ${chalk.green(message)}`);
+    }
+}
+export function logError(message) {
+    if (jsonMode) {
+        console.error(JSON.stringify({ error: { message } }));
+        return;
+    }
+    if (isCI()) {
+        console.error(`${timestamp()} ${ERROR_MARK} ${chalk.red(message)}`);
+    }
+    else {
+        console.error(`${ERROR_MARK} ${chalk.red(message)}`);
+    }
+}
+export function logWarn(message) {
+    if (jsonMode)
+        return;
+    if (isCI()) {
+        console.warn(`${timestamp()} ${WARN_MARK} ${chalk.hex('#FF9800')(message)}`);
+    }
+    else {
+        console.warn(`${WARN_MARK} ${chalk.hex('#FF9800')(message)}`);
+    }
+}
+export function logInfo(message) {
+    if (jsonMode)
+        return;
+    if (isCI()) {
+        console.log(`${timestamp()} ${INFO_MARK} ${chalk.hex('#4FC3F7')(message)}`);
+    }
+    else {
+        console.log(`${INFO_MARK} ${chalk.hex('#4FC3F7')(message)}`);
+    }
+}
+export function logBrand(message) {
+    if (jsonMode)
+        return;
+    console.log(`${BRAND_MARKER} ${message}`);
+}
+export function logRaw(message) {
+    if (jsonMode)
+        return;
+    console.log(message);
+}
+export function logJSON(data) {
+    if (!jsonMode)
+        return;
+    console.log(JSON.stringify(data));
+}
+export function logErrorJSON(data) {
+    if (!jsonMode) {
+        logError(data.message);
+        return;
+    }
+    console.error(JSON.stringify({ error: data }));
+}
+export const logger = { log, logSuccess, logError, logWarn, logInfo, logBrand, logRaw, logJSON, logErrorJSON, writeAudit, setJsonMode, isJsonMode };
+export function writeAudit(command, args, exitCode) {
+    const auditDir = path.join(os.homedir(), '.squidcloud');
+    const auditFile = path.join(auditDir, 'audit.log');
+    const entry = JSON.stringify({
+        timestamp: new Date().toISOString(),
+        command,
+        args,
+        exitCode,
+        pid: process.pid,
+    }) + '\n';
+    try {
+        if (!fs.existsSync(auditDir)) {
+            fs.mkdirSync(auditDir, { recursive: true, mode: 0o700 });
+        }
+        fs.appendFileSync(auditFile, entry, { encoding: 'utf-8' });
+    }
+    catch {
+        // Silently fail — audit should never crash the CLI
+    }
+}

package/dist/lib/output/mascot.js

@@ -0,0 +1,31 @@
+import chalk from 'chalk';
+const NAVY = '#0A0E1A';
+const BLUE = '#4FC3F7';
+const VIOLET = '#7C4DFF';
+const WHITE = '#FFFFFF';
+const SQUID_ART = [
+    '  ╔═══╗  ',
+    ' ╔╝█ █╚╗ ',
+    ' ║  ◉  ║ ',
+    ' ╚╗   ╔╝ ',
+    '  ║ ╦ ║  ',
+    ' ╔╝ ║ ╚╗ ',
+    ' ║  ║  ║ ',
+    ' ╚╗ ║ ╔╝ ',
+    '  ╚═══╝  ',
+];
+export function renderMascot() {
+    const lines = SQUID_ART.map((line, i) => {
+        const colored = line.replace(/█/g, chalk.hex(VIOLET)('█'))
+            .replace(/◉/g, chalk.hex(BLUE)('◉'))
+            .replace(/[╔╗╚╝═║╦]/g, (m) => chalk.hex(WHITE)(m));
+        return chalk.bgHex(NAVY)(colored);
+    });
+    return lines.join('\n');
+}
+export function renderBrandedMascot() {
+    const mascot = renderMascot();
+    const brand = chalk.hex(BLUE)('SQUID') + chalk.hex(VIOLET)('CLOUD');
+    const tagline = chalk.hex(WHITE).dim('static sites · storage · pipelines');
+    return `${mascot}\n\n  ${brand}  ${tagline}\n`;
+}

package/dist/lib/output/spinner.js

@@ -0,0 +1,44 @@
+import chalk from 'chalk';
+/** Dependency-free spinner — no ora, no native deps, CI-safe. */
+const FRAMES = ['▸   ', '▸▸  ', '▸▸▸ ', '▸▸▸▸', ' ▸▸▸▸', '  ▸▸▸', '   ▸▸', '    ▸'];
+export function createSpinner(text) {
+    const enabled = process.stdout.isTTY && !isCI();
+    let frame = 0;
+    let current = text;
+    let timer = null;
+    const draw = () => {
+        if (!enabled)
+            return;
+        process.stdout.write(`\r\x1b[2K${chalk.cyan(FRAMES[frame % FRAMES.length])} ${current}`);
+        frame++;
+    };
+    if (enabled) {
+        timer = setInterval(draw, 110);
+        draw();
+    }
+    else {
+        console.log(`• ${current}`);
+    }
+    return {
+        text(t) {
+            current = t;
+            draw();
+        },
+        succeed(suffix) {
+            this.stop();
+            console.log(`${enabled ? '\r\x1b[2K' : ''}✓ ${suffix ? `${current} — ${chalk.green(suffix)}` : chalk.green(current)}`);
+        },
+        fail(suffix) {
+            this.stop();
+            console.log(`${enabled ? '\r\x1b[2K' : ''}✗ ${suffix ? `${current} — ${chalk.red(suffix)}` : chalk.red(current)}`);
+        },
+        stop() {
+            if (timer)
+                clearInterval(timer);
+            timer = null;
+        },
+    };
+}
+function isCI() {
+    return !!(process.env.CI || process.env.GITHUB_ACTIONS || process.env.GITLAB_CI || process.env.CIRCLECI);
+}

package/dist/lib/output/table.js

@@ -0,0 +1,81 @@
+import Table from 'cli-table3';
+import chalk from 'chalk';
+import { isJsonMode, logJSON } from './logger.js';
+export function createTable(headers, options = {}) {
+    return new Table({
+        head: headers.map(h => chalk.bold(h)),
+        colAligns: options.colAligns,
+        style: {
+            head: [],
+            border: [],
+            'padding-left': 1,
+            'padding-right': 1,
+            ...options.style,
+        },
+        chars: {
+            top: '─',
+            'top-mid': '┬',
+            'top-left': '┌',
+            'top-right': '┐',
+            bottom: '─',
+            'bottom-mid': '┴',
+            'bottom-left': '└',
+            'bottom-right': '┘',
+            left: '│',
+            'left-mid': '├',
+            mid: '─',
+            'mid-mid': '┼',
+            right: '│',
+            'right-mid': '┤',
+            middle: '│',
+        },
+        ...options.compact ? {
+            chars: {
+                top: '',
+                'top-mid': '',
+                'top-left': '',
+                'top-right': '',
+                bottom: '',
+                'bottom-mid': '',
+                'bottom-left': '',
+                'bottom-right': '',
+                left: '',
+                'left-mid': '',
+                mid: '',
+                'mid-mid': '',
+                right: '',
+                'right-mid': '',
+                middle: '',
+            },
+            style: { 'padding-left': 0, 'padding-right': 2 },
+        } : {},
+    });
+}
+export function renderTable(data, columns) {
+    if (isJsonMode()) {
+        logJSON(data);
+        return '';
+    }
+    const table = createTable(columns.map(c => c.label), { colAligns: columns.map(c => c.align ?? 'left') });
+    for (const row of data) {
+        table.push(columns.map(c => {
+            const val = row[c.key];
+            return c.format ? c.format(val) : String(val ?? '');
+        }));
+    }
+    return table.toString();
+}
+export function renderCompactTable(data, columns) {
+    if (isJsonMode()) {
+        logJSON(data);
+        return '';
+    }
+    const table = createTable(columns.map(c => c.label), { colAligns: columns.map(c => c.align ?? 'left'), compact: true });
+    for (const row of data) {
+        table.push(columns.map(c => {
+            const val = row[c.key];
+            return c.format ? c.format(val) : String(val ?? '');
+        }));
+    }
+    return table.toString();
+}

package/dist/lib/picker.js

@@ -0,0 +1,71 @@
+import readline from 'node:readline';
+import chalk from 'chalk';
+/** Arrow-key numbered picker for ambiguous matches. Dependency-free. */
+export async function pickInteractive(entries, query) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY)
+        return null;
+    const candidates = entries.slice(0, 9);
+    if (candidates.length === 0)
+        return null;
+    const headerLines = [
+        '',
+        `"${query}" matched ${entries.length} files:`,
+        ...candidates.map((e, i) => `  [${i + 1}] ${e.name}  ${chalk.dim(e.id)}`),
+        '  ↑/↓ move · 1-9 jump · enter select · esc cancel',
+        '',
+    ];
+    console.log(chalk.dim(headerLines.join('\n')));
+    let cursor = 0;
+    const baseRow = headerLines.length - 2 + 1;
+    const renderCursor = () => {
+        candidates.forEach((_, i) => {
+            process.stdout.write(`\x1b[${baseRow + i};1H\x1b[2K${i === cursor ? chalk.cyan('→') : ' '}[${i + 1}] ${candidates[i].name}`);
+        });
+        process.stdout.write(`\x1b[${baseRow + candidates.length};1H`);
+    };
+    const wasRaw = process.stdin.isRaw;
+    if (typeof process.stdin.setRawMode === 'function')
+        process.stdin.setRawMode(true);
+    process.stdin.resume();
+    readline.emitKeypressEvents(process.stdin);
+    const choice = await new Promise((resolve) => {
+        const handler = (_ch, key) => {
+            if (!key)
+                return;
+            if (key.name === 'up')
+                cursor = (cursor - 1 + candidates.length) % candidates.length;
+            else if (key.name === 'down')
+                cursor = (cursor + 1) % candidates.length;
+            else if (key.name === 'return' || key.name === 'enter') {
+                cleanup();
+                resolve(cursor);
+                return;
+            }
+            else if (key.name === 'escape' || (key.ctrl && key.name === 'c')) {
+                cleanup();
+                resolve(null);
+                return;
+            }
+            else if (/^[1-9]$/.test(key.sequence || '')) {
+                const idx = Number(key.sequence) - 1;
+                if (idx < candidates.length) {
+                    cleanup();
+                    resolve(idx);
+                    return;
+                }
+            }
+            else
+                return;
+            renderCursor();
+        };
+        const cleanup = () => process.stdin.removeListener('keypress', handler);
+        process.stdin.on('keypress', handler);
+        renderCursor();
+    });
+    if (typeof process.stdin.setRawMode === 'function')
+        process.stdin.setRawMode(!!wasRaw);
+    process.stdin.pause();
+    for (let i = 0; i < candidates.length + 2; i++)
+        process.stdout.write('\x1b[1A\x1b[2K');
+    return choice === null ? null : (candidates[choice] ?? null);
+}

package/dist/lib/refs-types.js

@@ -0,0 +1 @@
+export {};