@cspeach/cli 0.6.0

package/dist/renderer/tool-widget.js

@@ -0,0 +1,199 @@
+import chalk from 'chalk';
+import { PEACH } from './banners.js';
+/**
+ * Tool-dispatch renderer — CC-style two-line format with peach spinner.
+ *
+ *   ⏺ tool_name(arg-summary)        ← printed at dispatch start
+ *     ⠋ slicing peach…              ← spinner, in place, while dispatch runs
+ *     ⎿ ✓ result-summary · 1.2s     ← overwrites the spinner on completion
+ *
+ * Top line (renderToolCallTop) prints at content_block_stop, before the
+ * dispatch fires. The spinner is started immediately after and runs until
+ * the bottom line (renderToolCallBottom) replaces it. The bottom line
+ * uses ANSI cursor-up + erase-line to consume the spinner row, leaving
+ * just the dispatch + result rows in scrollback.
+ *
+ * Color discipline:
+ *   - Peach (PEACH) for the identity glyphs (⏺ dispatch, ⎿ result, spinner).
+ *   - Default white/bold for the tool name.
+ *   - Dim grey for arg-summary inside parens, timing, the spinner's verb.
+ *   - Green (✓) on success, red (✗ + body) on error.
+ *   - No cyan, no rainbow, no boxes.
+ */
+const peach = (s) => chalk.hex(PEACH)(s);
+const ARG_SUMMARY_MAX = 64;
+const RESULT_SUMMARY_MAX = 96;
+/** Braille spinner — 8 frames at 80ms each gives a smooth rotation that
+ *  reads as "still working" without being distracting. */
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const SPINNER_TICK_MS = 80;
+/** Vibe verbs — picked once per dispatch so the indicator feels alive
+ *  without thrashing. Default is `slicing peach` per the brand bit. */
+const SPINNER_VERBS = ['slicing peach', 'mashing pulp', 'pitting', 'pressing', 'simmering', 'plating'];
+/** LLM-think verbs — different pool from tool-dispatch so the user can
+ *  tell at a glance whether we're waiting on the model or running a
+ *  tool. Tool dispatch = peach-cooking metaphor; thinking = peach-growing
+ *  metaphor (a beat slower in pacing). */
+const THINKING_VERBS = ['thinking', 'ripening', 'steeping', 'marinating', 'pondering', 'considering'];
+/**
+ * Module-level reference to the currently-running spinner's stop function.
+ * Set by startToolSpinner; cleared on stop. Lets unrelated subsystems
+ * (e.g. inquirer-guard, when an inquirer prompt is about to open) silence
+ * the spinner so it doesn't fight inquirer for stdout/cursor.
+ */
+let activeSpinnerStop = null;
+export function clearActiveSpinner() {
+    if (activeSpinnerStop) {
+        activeSpinnerStop();
+        activeSpinnerStop = null;
+    }
+}
+export function renderToolCallTop(params) {
+    const { name, args, chunkEmitter } = params;
+    const write = (s) => {
+        if (chunkEmitter)
+            chunkEmitter.emit('chunk', s);
+        else
+            process.stdout.write(s);
+    };
+    const summary = argSummary(name, args);
+    const wrapped = summary ? chalk.gray('(') + chalk.gray(summary) + chalk.gray(')') : '';
+    const line = `${peach('⏺')} ${chalk.bold(name)}${wrapped}`;
+    write('\n' + line + '\n');
+}
+/**
+ * Animated peach-themed indicator while we wait on the LLM (between
+ * `provider.createStream` and the first content event). Same visual
+ * shape as the tool spinner but pulls from THINKING_VERBS so the user
+ * can distinguish "model is thinking" from "tool is running" at a
+ * glance. Wired from agent/loop.ts immediately before the await on
+ * createStream; stopped on the first content_block_start (or on
+ * error). Also stopped by clearActiveSpinner (e.g. when an inquirer
+ * prompt opens, same as tool spinner).
+ */
+export function startThinkingSpinner(params) {
+    return startSpinnerWithVerbs(params, THINKING_VERBS, 'thinking');
+}
+export function startToolSpinner(params) {
+    return startSpinnerWithVerbs(params, SPINNER_VERBS, 'slicing peach');
+}
+function startSpinnerWithVerbs(params, verbs, defaultVerb) {
+    const { chunkEmitter } = params;
+    const disabled = chunkEmitter !== undefined ||
+        !process.stdout.isTTY ||
+        process.env['CI'] === '1' ||
+        process.env['TERM'] === 'dumb';
+    if (disabled)
+        return { stop: () => undefined };
+    // Pick one verb per dispatch so the indicator doesn't churn.
+    const verb = verbs[Math.floor(Math.random() * verbs.length)] ?? defaultVerb;
+    let frameIdx = 0;
+    let stopped = false;
+    const paint = () => {
+        if (stopped)
+            return;
+        const frame = SPINNER_FRAMES[frameIdx];
+        frameIdx = (frameIdx + 1) % SPINNER_FRAMES.length;
+        // Erase current line + reprint. First call appends a fresh line; later
+        // calls cursor-up to the spinner row and overwrite in place.
+        const line = `  ${peach(frame)} ${chalk.dim(verb + '…')}`;
+        process.stdout.write(`\x1B[2K\r${line}`);
+    };
+    // Hide the terminal cursor while the spinner animates so it doesn't blink
+    // mid-frame and confuse the user about whether their typing went through.
+    process.stdout.write('\x1B[?25l');
+    // Print the initial spinner line.
+    process.stdout.write('\r');
+    paint();
+    const interval = setInterval(paint, SPINNER_TICK_MS);
+    interval.unref?.();
+    const stopFn = () => {
+        if (stopped)
+            return;
+        stopped = true;
+        clearInterval(interval);
+        // Erase the spinner line so the result row paints in its place.
+        // \r → start of line, \x1B[2K → erase entire line. No newline so the
+        // bottom renderer's \n keeps the spacing correct.
+        // Also re-show the cursor (\x1B[?25h) — paired with the hide above.
+        process.stdout.write('\r\x1B[2K\x1B[?25h');
+        // Clear the global handle if it's still pointing at us. (If a newer
+        // spinner already replaced us, leave its registration alone.)
+        if (activeSpinnerStop === stopFn)
+            activeSpinnerStop = null;
+    };
+    // Defensive: if a previous spinner is somehow still active when we start
+    // (shouldn't happen — agent loop stops the previous one before next
+    // dispatch — but easy to guarantee here), stop it before claiming the slot.
+    if (activeSpinnerStop)
+        activeSpinnerStop();
+    activeSpinnerStop = stopFn;
+    return { stop: stopFn };
+}
+export function renderToolCallBottom(params) {
+    const { durationMs, isError, resultSummary, chunkEmitter } = params;
+    const write = (s) => {
+        if (chunkEmitter)
+            chunkEmitter.emit('chunk', s);
+        else
+            process.stdout.write(s);
+    };
+    const icon = isError ? chalk.red('✗') : chalk.green('✓');
+    const detailRaw = resultSummary ? truncate(resultSummary, RESULT_SUMMARY_MAX) : '';
+    const detail = detailRaw
+        ? (isError ? chalk.red(detailRaw) : chalk.gray(detailRaw))
+        : '';
+    const timing = chalk.dim(formatDuration(durationMs));
+    const sep = chalk.dim('·');
+    let line = `  ${peach('⎿')} ${icon}`;
+    if (detail)
+        line += ` ${detail} ${sep} ${timing}`;
+    else
+        line += ` ${timing}`;
+    write(line + '\n');
+}
+/**
+ * Compact one-liner describing the most informative parts of the dispatch
+ * arguments. Per-tool aware: pulls LLM-supplied summary first, then the
+ * common (name, type, package) triple, then specific keys for known tools.
+ * Falls back to a truncated JSON dump.
+ */
+function argSummary(toolName, args) {
+    if (!args || Object.keys(args).length === 0)
+        return '';
+    const a = args;
+    // request_approval / ask_question — surface the LLM-supplied summary text.
+    if (typeof a['summary'] === 'string') {
+        return truncate(a['summary'], ARG_SUMMARY_MAX);
+    }
+    if (typeof a['question'] === 'string') {
+        return truncate(a['question'], ARG_SUMMARY_MAX);
+    }
+    // Class.method shorthand for sap_update_method.
+    if (typeof a['class_name'] === 'string' && typeof a['method_name'] === 'string') {
+        return truncate(`${a['class_name']}.${a['method_name']}`, ARG_SUMMARY_MAX);
+    }
+    // Common (name, type, package) for SAP object tools.
+    const parts = [];
+    if (typeof a['name'] === 'string')
+        parts.push(a['name']);
+    if (typeof a['type'] === 'string' && a['type'] !== a['name'])
+        parts.push(a['type']);
+    if (typeof a['package'] === 'string')
+        parts.push(`in ${a['package']}`);
+    if (parts.length > 0)
+        return truncate(parts.join(' '), ARG_SUMMARY_MAX);
+    // Search query / SQL.
+    if (typeof a['query'] === 'string')
+        return truncate(a['query'], ARG_SUMMARY_MAX);
+    // Fallback — short JSON.
+    return truncate(JSON.stringify(args), ARG_SUMMARY_MAX);
+}
+function truncate(s, max) {
+    return s.length > max ? s.substring(0, max - 1) + '…' : s;
+}
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    return `${(ms / 1000).toFixed(1)}s`;
+}

package/dist/renderer/tty.js

@@ -0,0 +1,66 @@
+// C:\Users\Admin\ClaudeProjects\ABAPForge\cspeach-cli\src\renderer\tty.ts
+/**
+ * TTY / mode detection helpers.
+ */
+import * as os from 'node:os';
+/** True when stdout is an interactive terminal (not piped / redirected). */
+export function isTTY() {
+    return process.stdout.isTTY === true;
+}
+/**
+ * True when the CLI was invoked with a positional argument (one-shot mode)
+ * or with the --one-shot flag.
+ * e.g. `cspeach "/radar ZTTT_GAME"` vs interactive REPL.
+ */
+export function isOneShot() {
+    const args = process.argv.slice(2);
+    return args.some((a) => a === '--one-shot') || args.some((a) => !a.startsWith('-'));
+}
+let renderingOverride = 'classic';
+/** Set the rendering mode override. Call once at startup after loadConfig(). */
+export function setRenderingOverride(mode) {
+    renderingOverride = mode;
+}
+/** Get the current rendering override (for debugging / status display). */
+export function getRenderingOverride() {
+    return renderingOverride;
+}
+/**
+ * True when the Ink UI frame should be mounted.
+ *
+ * Decision order:
+ *   1. If override === 'classic', never use Ink (explicit opt-out)
+ *   2. If override === 'ink', use Ink when a TTY is available; otherwise
+ *      fall back — Ink cannot render on a pipe regardless of user preference
+ *   3. If override === 'auto' (default), use Ink when interactive TTY +
+ *      not one-shot + CI=unset
+ *
+ * v0.3+: pipeline.ts and approvals/render.ts branch on this.
+ */
+export function shouldUseInk() {
+    if (renderingOverride === 'classic')
+        return false;
+    if (renderingOverride === 'ink')
+        return isTTY();
+    // auto
+    return isTTY() && !isOneShot() && !process.env['CI'];
+}
+/**
+ * Stub for v0.3 Windows ConPTY / CI TTY hinting.
+ *
+ * On Windows, ConPTY sets WT_SESSION; GitHub Actions sets CI=true.
+ * Returns undefined when no hint is available.
+ */
+export function ciTtyHint() {
+    return undefined;
+}
+/** True when running on Windows without a capable terminal (no WT or iTerm/wezterm). */
+export function isWindowsLegacyTerminal() {
+    return (os.platform() === 'win32' &&
+        !process.env['WT_SESSION'] &&
+        !process.env['TERM_PROGRAM']);
+}
+/** Use full Unicode box-drawing chars only when NOT on a legacy Windows terminal. */
+export function shouldUseUnicodeBoxChars() {
+    return !isWindowsLegacyTerminal();
+}

package/dist/renderer/widget-extractor.js

@@ -0,0 +1,87 @@
+const OPEN_RE = /^```cspeach-widget:(\S+)\s*$/;
+// CLOSE_RE matches a bare ``` on a line — which means a widget payload
+// containing ``` (e.g. a diff-viewer unified diff inside JSON strings) would
+// prematurely close the fence. LLMs emit widget JSON as single-line payloads
+// per the widget-emit contract (spec §4.3) — if this invariant breaks, the
+// renderer will need a more sophisticated parser (stack-based with string-
+// literal awareness inside JSON).
+const CLOSE_RE = /^```\s*$/;
+const SENTINEL = '<!-- widget-real -->';
+export function extractWidgets(text) {
+    const segments = [];
+    let pos = 0;
+    let i = 0;
+    // Index of first line NOT yet emitted as passthrough. Any line between this
+    // index and the current position that isn't a widget-open needs to surface as
+    // passthrough so the pipeline can still render non-widget markdown.
+    let passStart = 0;
+    const lines = text.split('\n');
+    const flushPassthrough = (upToExclusive) => {
+        if (passStart >= upToExclusive)
+            return;
+        // Reassemble the raw text for these lines. We lost the original line-break
+        // info when we split, but rebuilding with `\n` between lines and a trailing
+        // `\n` if the region extends to end-of-input matches how renderChunk's
+        // passthrough helper already expects its input.
+        const slice = lines.slice(passStart, upToExclusive);
+        const tail = upToExclusive < lines.length ? '\n' : '';
+        const rawText = slice.join('\n') + tail;
+        if (rawText.length === 0) {
+            passStart = upToExclusive;
+            return;
+        }
+        const spanStart = pos;
+        const spanEnd = spanStart + rawText.length;
+        pos += rawText.length;
+        segments.push({ type: 'passthrough', rawText, span: [spanStart, spanEnd] });
+        passStart = upToExclusive;
+    };
+    while (i < lines.length) {
+        const m = OPEN_RE.exec(lines[i]);
+        if (!m) {
+            i++;
+            continue;
+        }
+        // Found opening fence — first flush any preceding passthrough region.
+        flushPassthrough(i);
+        const openLine = i;
+        const widgetType = m[1];
+        const bodyLines = [];
+        i++;
+        let closed = false;
+        while (i < lines.length) {
+            if (CLOSE_RE.test(lines[i])) {
+                closed = true;
+                i++;
+                break;
+            }
+            bodyLines.push(lines[i]);
+            i++;
+        }
+        if (!closed) {
+            // Stream-incomplete: return buffered sentinel so caller waits.
+            return [...segments, { type: 'buffered' }];
+        }
+        // Compute raw span in original string (approximate by line offset).
+        const spanStart = pos;
+        const blockText = lines.slice(openLine, i).join('\n') + '\n';
+        const spanEnd = spanStart + blockText.length;
+        pos += blockText.length;
+        passStart = i;
+        // Sentinel check — compare on trimmed values so leading/trailing whitespace
+        // around `<!-- widget-real -->` is tolerated.
+        const firstContent = bodyLines.find((l) => l.trim() !== '');
+        if (firstContent?.trim() !== SENTINEL) {
+            segments.push({ type: 'passthrough', rawText: blockText, span: [spanStart, spanEnd] });
+            continue;
+        }
+        // Strip the sentinel line AND any empty lines before the JSON (again, trim-aware).
+        const jsonLines = bodyLines.filter((l) => l.trim() !== '' && l.trim() !== SENTINEL);
+        const rawJson = jsonLines.join('\n');
+        segments.push({ type: 'widget', widgetType, rawJson, span: [spanStart, spanEnd] });
+    }
+    // Flush trailing passthrough (lines after the last widget or the entire input
+    // if no widget fence was ever opened).
+    flushPassthrough(lines.length);
+    return segments;
+}

package/dist/renderer/widget-fallback.js

@@ -0,0 +1,78 @@
+import chalk from 'chalk';
+// Inner content width — the box becomes content+4 total width.
+const CONTENT_WIDTH = 55;
+const TOTAL_WIDTH = CONTENT_WIDTH + 4; // left "┃ " + content + " ┃"
+function padLine(s) {
+    // Pad to CONTENT_WIDTH visible chars, preserve ANSI codes if any
+    const ANSI = /\x1B\[[0-9;]*[mGKHFABCDsuJSTfrl]/g;
+    const visible = s.replace(ANSI, '');
+    const padding = Math.max(0, CONTENT_WIDTH - visible.length);
+    return s + ' '.repeat(padding);
+}
+function wrap(text, width) {
+    if (text.length <= width)
+        return [text];
+    const words = text.split(/\s+/);
+    const lines = [];
+    let current = '';
+    for (const word of words) {
+        if (current.length === 0) {
+            current = word;
+        }
+        else if (current.length + 1 + word.length <= width) {
+            current += ' ' + word;
+        }
+        else {
+            lines.push(current);
+            current = word;
+        }
+    }
+    if (current.length > 0)
+        lines.push(current);
+    return lines;
+}
+/**
+ * Render a question widget as a heavy-bordered chalk card for classic-mode
+ * REPL output. Called by the pipeline's widget-fallback path when
+ * shouldUseInk() is false OR when we're rendering the default text
+ * fallback for the widget system.
+ *
+ * Uses heavy box-drawing chars (┏ ┓ ┗ ┛ ━ ┃) so the question card
+ * visually distinguishes from the light-bordered tool-widget boxes.
+ */
+export function renderQuestionCard(widget) {
+    const border = chalk.cyan;
+    const dim = chalk.dim;
+    const top = border('┏━ ' + chalk.cyan.bold(`Question: ${widget.id}`) + ' ' + '━'.repeat(Math.max(0, CONTENT_WIDTH - widget.id.length - 12)) + '━┓');
+    const bottom = border('┗' + '━'.repeat(TOTAL_WIDTH - 2) + '┛');
+    const lines = [top];
+    lines.push(border('┃ ') + padLine('') + border(' ┃'));
+    // Question text (wrapped)
+    for (const line of wrap(widget.question, CONTENT_WIDTH)) {
+        lines.push(border('┃ ') + padLine(chalk.bold(line)) + border(' ┃'));
+    }
+    // Optional context
+    if (widget.context) {
+        lines.push(border('┃ ') + padLine('') + border(' ┃'));
+        for (const line of wrap(`Context: ${widget.context}`, CONTENT_WIDTH)) {
+            lines.push(border('┃ ') + padLine(dim(line)) + border(' ┃'));
+        }
+    }
+    // Choice list for choice/multi kinds
+    if (widget.kind === 'choice' || widget.kind === 'multi') {
+        lines.push(border('┃ ') + padLine('') + border(' ┃'));
+        const header = widget.kind === 'choice' ? 'Pick one:' : 'Pick any (comma-separate):';
+        lines.push(border('┃ ') + padLine(chalk.bold(header)) + border(' ┃'));
+        const choices = widget.choices ?? [];
+        for (let i = 0; i < choices.length; i++) {
+            const choice = choices[i];
+            const line = `[${i + 1}] ${choice.label}`;
+            for (const wrapped of wrap(line, CONTENT_WIDTH)) {
+                lines.push(border('┃ ') + padLine(wrapped) + border(' ┃'));
+            }
+        }
+    }
+    lines.push(border('┃ ') + padLine('') + border(' ┃'));
+    lines.push(bottom);
+    return '\n' + lines.join('\n') + '\n';
+}

package/dist/renderer/widget-schemas.js

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+export const depGraphSchema = z.object({
+    root: z.string(),
+    children: z.array(z.object({
+        name: z.string(),
+        type: z.string(),
+        relation: z.string(),
+    })),
+});
+export const barChartSchema = z.array(z.object({
+    label: z.string(),
+    value: z.number(),
+    color: z.string().optional(),
+}));
+export const stackFramesSchema = z.array(z.object({
+    frame: z.number(),
+    program: z.string(),
+    line: z.number(),
+    code: z.string(),
+    type: z.enum(['error', 'context']),
+}));
+export const diffSchema = z.object({ unified: z.string() });
+export const questionSchema = z
+    .object({
+    id: z.string(),
+    question: z.string(),
+    context: z.string().optional(),
+    kind: z.enum(['text', 'choice', 'multi']),
+    choices: z
+        .array(z.object({
+        value: z.string(),
+        label: z.string(),
+    }))
+        .optional(),
+})
+    .refine((data) => data.kind === 'text' || (data.choices !== undefined && data.choices.length > 0), { message: 'choice/multi kinds require non-empty choices[]' });
+export const WIDGET_SCHEMAS = {
+    'dep-graph': depGraphSchema,
+    'bar-chart': barChartSchema,
+    'stack-frames': stackFramesSchema,
+    'diff-viewer': diffSchema,
+    question: questionSchema, // NEW
+};

package/dist/repl/at-completer.js

@@ -0,0 +1,64 @@
+/**
+ * Tab-completion for `@<filename>` tokens in the REPL.
+ *
+ * UX contract:
+ *   - User types `@` then Tab        → all .cspeach.json files in workspace
+ *   - User types `@b9b` then Tab     → 1 match auto-completes; many lists
+ *   - Mid-line: `/abap-design --status @b9b<Tab>`
+ *                                    → completes only the @-token, line tail preserved
+ *   - No `@` on the line             → atCompleter returns null; caller
+ *                                      falls through to the next completer
+ *
+ * Backed by readline's native `completer`, like slashCompleter — same
+ * `[string[], string]` shape so a thin wrapper can dispatch between the two.
+ *
+ * Performance: the workspace folder is read on every call but cached for
+ * a few seconds so per-keystroke listing doesn't thrash the filesystem.
+ * The cache TTL is short enough that newly-saved files appear within a
+ * few seconds of their save without manual refresh.
+ */
+import { ensureWorkspaceSync, listProjectFilesSync } from '../projects/workspace.js';
+const CACHE_TTL_MS = 3000;
+let cache = null;
+function getCachedFiles() {
+    const now = Date.now();
+    if (!cache || now - cache.at > CACHE_TTL_MS) {
+        try {
+            const ws = ensureWorkspaceSync();
+            cache = { files: listProjectFilesSync(ws), at: now };
+        }
+        catch {
+            cache = { files: [], at: now };
+        }
+    }
+    return cache.files;
+}
+/**
+ * readline-style completer for `@<token>`. Returns `null` when the cursor
+ * is NOT inside an @-token, so the caller knows to delegate.
+ *
+ * `line` is the full input up to the cursor (Node's readline contract).
+ * We anchor on the rightmost `@<word>` because the @-token always sits
+ * at the cursor end during typing.
+ */
+export function atCompleter(line) {
+    const m = /@(\S*)$/.exec(line);
+    if (!m)
+        return null;
+    const token = m[1] ?? '';
+    const lineBefore = line.slice(0, m.index);
+    const lower = token.toLowerCase();
+    const files = getCachedFiles();
+    const matched = files.filter((f) => lower === '' || f.filename.toLowerCase().includes(lower));
+    if (matched.length === 0) {
+        // Return an empty hit list (not null) so readline knows we OWNED this
+        // completion — emitting "no matches" beep instead of falling through.
+        return [[], line];
+    }
+    const hits = matched.map((f) => `${lineBefore}@${f.filename}`);
+    return [hits, line];
+}
+/** Test-only: invalidate the cache so unit tests see fresh fs state. */
+export function _resetAtCompleterCache() {
+    cache = null;
+}

package/dist/repl/at-picker.js

@@ -0,0 +1,122 @@
+/**
+ * Live picker for `@<filename>` workspace tokens. Opens when the user
+ * presses Enter on a line that ends in a partial / unresolved @-token —
+ * mirrors openSlashPicker but for files instead of slash commands.
+ *
+ * UX contract:
+ *   - User types `... @` then Enter        → picker shows ALL workspace files
+ *   - User types `... @b9b` then Enter     → picker pre-filtered to those
+ *     files matching `b9b`. User can refine further or pick.
+ *   - User types `... @<exact-filename>` then Enter → no picker; the line
+ *     is treated as already-resolved (existing @-token resolution path).
+ *   - User cancels (Esc / Ctrl-C inside picker) → returns null; caller
+ *     restores the original line so the user can edit it.
+ *
+ * Pairs with at-completer.ts (Tab completion for the same tokens).
+ * Tab vs Enter is the user's choice: Tab when they want a quick list
+ * without screen takeover, Enter when they want a full search-as-you-type
+ * picker. Same backing data, different UI.
+ */
+import { search } from '@inquirer/prompts';
+import { withInquirer } from './inquirer-guard.js';
+import { inquirerTheme } from './inquirer-theme.js';
+import { ensureWorkspaceSync, listProjectFilesSync } from '../projects/workspace.js';
+const CANCEL_VALUE = '__cspeach_cancel__';
+/**
+ * Open the at-picker pre-filtered to `prefix`. Returns the picked
+ * filename (no leading @), or null on cancel / empty-workspace.
+ *
+ * `prefix` is whatever the user typed AFTER the @ — e.g. for line
+ * `/abap-rap --from @b9b<Enter>` the prefix is `b9b`. Empty prefix
+ * (bare `@`) seeds the picker with all workspace files.
+ */
+export async function openAtPicker(prefix) {
+    let allFiles;
+    try {
+        const ws = ensureWorkspaceSync();
+        allFiles = listProjectFilesSync(ws).map((f) => ({ filename: f.filename, mtimeMs: f.mtimeMs }));
+    }
+    catch {
+        allFiles = [];
+    }
+    if (allFiles.length === 0) {
+        return null;
+    }
+    const lowerPrefix = prefix.trim().toLowerCase();
+    const seeded = lowerPrefix.length === 0
+        ? allFiles
+        : allFiles.filter((f) => f.filename.toLowerCase().includes(lowerPrefix));
+    // Single unique match — short-circuit, save the user a keystroke. Same
+    // shortcut openSlashPicker uses.
+    if (seeded.length === 1) {
+        return seeded[0].filename;
+    }
+    // Empty filter result → fall back to all files so the user can correct
+    // their prefix rather than seeing an empty picker.
+    const choicesForPicker = seeded.length === 0 ? allFiles : seeded;
+    try {
+        const picked = await withInquirer(() => search({
+            message: 'Pick a workspace file',
+            theme: inquirerTheme,
+            source: async (input) => {
+                const filter = (input ?? '').toLowerCase();
+                const filtered = filter.length === 0
+                    ? choicesForPicker
+                    : choicesForPicker.filter((f) => f.filename.toLowerCase().includes(filter));
+                const cancelChoice = {
+                    name: '← Cancel — keep my typed text and let me edit it',
+                    value: CANCEL_VALUE,
+                    short: 'cancel',
+                };
+                const choices = filtered.map((f) => ({
+                    name: f.filename,
+                    value: f.filename,
+                    short: f.filename,
+                }));
+                return [cancelChoice, ...choices];
+            },
+        }));
+        if (picked === CANCEL_VALUE)
+            return null;
+        return typeof picked === 'string' ? picked : null;
+    }
+    catch {
+        // Ctrl+C inside the picker — treat as cancellation.
+        return null;
+    }
+}
+/**
+ * Quick check: does `trimmed` end with an @-token whose value (the part
+ * after @) doesn't already exactly match a workspace file? Used by the
+ * REPL to decide between "pass through to existing @-token resolution"
+ * and "open picker for ambiguous input".
+ *
+ * Returns the rightmost @-token's prefix (the chars typed after @), or
+ * null when the line doesn't end with an @-token or the token already
+ * resolves exactly.
+ */
+export function pendingAtTokenPrefix(trimmed) {
+    // Match the rightmost @<word> at the end of the line. \S+ means
+    // non-whitespace only — `@filename with space` is not auto-detected
+    // (user can quote with `@"name with space"` for those, handled by
+    // the existing parseFromFlag / resolveAtToken paths).
+    const m = /@(\S*)$/.exec(trimmed);
+    if (!m)
+        return null;
+    const prefix = m[1] ?? '';
+    // If the prefix already exactly matches a workspace filename, the
+    // existing @-resolution will pick it up — don't open the picker.
+    if (prefix.length > 0) {
+        try {
+            const ws = ensureWorkspaceSync();
+            const files = listProjectFilesSync(ws);
+            const exact = files.some((f) => f.filename === prefix);
+            if (exact)
+                return null;
+        }
+        catch {
+            // Fall through — open picker as a safe default.
+        }
+    }
+    return prefix;
+}