@cspeach/cli 0.6.0

package/dist/repl/bracketed-paste.js

@@ -0,0 +1,284 @@
+/**
+ * Bracketed-paste decoder for the CSPeach REPL.
+ *
+ * Why this exists: Node's `readline` treats `\n` as a hard line terminator
+ * and submits a line the instant it sees one. When a user pastes prose
+ * that contains newlines, the first line fires `rl.question()` and the
+ * remaining lines go to the next prompt (or get eaten by a sub-prompt).
+ * We observed this in the wild: a ~260-char pasted prompt reached
+ * `runTurn` as 88 chars (the first wrapped line only), silently losing
+ * the package and transport the user had stated.
+ *
+ * Modern terminals support "bracketed paste mode": when enabled, pastes
+ * arrive wrapped in the escape sequences `\x1b[200~` (start) and
+ * `\x1b[201~` (end). Newlines *inside* those markers are part of the
+ * paste, not line terminators.
+ *
+ * This module provides:
+ *  - `enableBracketedPaste()` / `disableBracketedPaste()` — emits the
+ *    DEC control sequences that ask the terminal to wrap future pastes.
+ *  - `BracketedPasteDecoder` — a `Transform` stream you pipe stdin
+ *    through. When it sees the paste-start marker, it buffers until the
+ *    paste-end marker, then emits the buffer as a single chunk with
+ *    internal `\r\n` / `\n` replaced by a single space. Outside paste
+ *    mode, data passes through untouched.
+ *
+ * Wiring: repl.tsx pipes `process.stdin -> decoder` and passes `decoder`
+ * as the `input` option to `readline.createInterface`. Readline's
+ * line-splitting logic operates on the post-decode stream, which no
+ * longer contains mid-paste newlines.
+ *
+ * Caveats:
+ *  - Not all terminals support bracketed paste (e.g. basic Windows
+ *    cmd.exe without Windows Terminal, some ssh clients). If the terminal
+ *    ignores our `\x1b[?2004h` request, pastes still arrive as raw text;
+ *    the decoder never sees a start marker so the stream is pass-through.
+ *    Users on old terminals are no worse off than before — they still
+ *    have the line-split behavior, not a new failure.
+ *  - Ink has its own stdin handling. This decoder is only for the
+ *    classic REPL path (non-Ink). Ink mode uses its own input component.
+ */
+import { Transform } from 'node:stream';
+/** DEC Private Mode 2004 — enable bracketed paste. */
+export const BRACKETED_PASTE_ENABLE = '\x1b[?2004h';
+/** DEC Private Mode 2004 — disable bracketed paste. */
+export const BRACKETED_PASTE_DISABLE = '\x1b[?2004l';
+const START_MARKER = Buffer.from('\x1b[200~', 'ascii');
+const END_MARKER = Buffer.from('\x1b[201~', 'ascii');
+/**
+ * Ask the terminal to wrap future pastes with the 2004 control sequences.
+ * Safe to call when the terminal doesn't support bracketed paste — the
+ * sequence is simply ignored.
+ */
+export function enableBracketedPaste(stream = process.stdout) {
+    if (stream.isTTY)
+        stream.write(BRACKETED_PASTE_ENABLE);
+}
+/** Reverse of enableBracketedPaste. Call on REPL shutdown. */
+export function disableBracketedPaste(stream = process.stdout) {
+    if (stream.isTTY)
+        stream.write(BRACKETED_PASTE_DISABLE);
+}
+/**
+ * Transform stream that collapses the content between `\x1b[200~` and
+ * `\x1b[201~` into a single line (newlines replaced with spaces). The
+ * markers themselves are stripped. All other bytes pass through
+ * unchanged, including keystrokes, arrow-key escape sequences, and
+ * terminal responses — these are not affected because they never contain
+ * the paste markers.
+ *
+ * The implementation uses Buffer operations (not string concat) to avoid
+ * splitting multi-byte UTF-8 sequences at chunk boundaries when a paste
+ * spans multiple `data` events.
+ */
+export class BracketedPasteDecoder extends Transform {
+    /**
+     * Readline with `terminal: true` inspects `input.isTTY` and calls
+     * `input.setRawMode(true)` so arrow keys, history navigation, and
+     * Ctrl-C work. A plain Transform has neither flag nor method, so
+     * readline would silently fall back to non-TTY line mode and the user
+     * would lose history and keyboard shortcuts.
+     *
+     * We present as a TTY and forward the raw-mode toggle and the size
+     * getters to the real `process.stdin` / `process.stdout`.
+     */
+    // eslint-disable-next-line @typescript-eslint/naming-convention
+    isTTY = true;
+    setRawMode(mode) {
+        if (typeof process.stdin.setRawMode === 'function')
+            process.stdin.setRawMode(mode);
+        return this;
+    }
+    get columns() {
+        return process.stdout.columns;
+    }
+    get rows() {
+        return process.stdout.rows;
+    }
+    inPaste = false;
+    pasteBuf = Buffer.alloc(0);
+    /**
+     * Carry-over bytes from the tail of the previous chunk. Used when a
+     * chunk ends mid-marker (e.g. the chunk finishes with `\x1b[20` and the
+     * next starts with `0~`). We stash up to 5 trailing bytes (marker is 6
+     * bytes, so max 5 can ambiguously be a partial match) and prepend them
+     * on the next chunk.
+     */
+    carry = Buffer.alloc(0);
+    /**
+     * Timer that flushes the carry buffer if no follow-up bytes arrive.
+     *
+     * 2026-05-02: without this, a bare Esc keystroke (single byte 0x1B)
+     * was held forever — the decoder couldn't tell whether more bytes
+     * (forming `\x1b[200~`) were coming. Esc never reached readline,
+     * so our keypress handler (and any user expecting Esc to do
+     * anything) was permanently blocked.
+     *
+     * Real escape sequences arrive as a burst — ~ms apart at most. A
+     * bare keystroke has a much larger gap before the next event. 50ms
+     * is well above any sensible burst latency and well below any
+     * latency the user would notice on a deliberate keypress.
+     */
+    carryTimer = null;
+    static CARRY_FLUSH_MS = 50;
+    _transform(chunk, _enc, cb) {
+        if (this.carryTimer) {
+            clearTimeout(this.carryTimer);
+            this.carryTimer = null;
+        }
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        const combined = Buffer.concat([this.carry, buf]);
+        this.carry = Buffer.alloc(0);
+        try {
+            this.process(combined);
+            this.scheduleCarryFlush();
+            cb();
+        }
+        catch (err) {
+            cb(err);
+        }
+    }
+    /**
+     * Arm the carry-flush timer. If no new data arrives within
+     * CARRY_FLUSH_MS, emit whatever's in `this.carry` so a bare Esc
+     * (or any other prefix-of-marker keystroke without a follow-up)
+     * isn't permanently held back. Only relevant when not currently
+     * inside a paste — paste content is buffered separately.
+     */
+    scheduleCarryFlush() {
+        if (this.inPaste)
+            return;
+        if (this.carry.length === 0)
+            return;
+        this.carryTimer = setTimeout(() => {
+            this.carryTimer = null;
+            if (this.carry.length > 0 && !this.inPaste) {
+                const flushed = this.carry;
+                this.carry = Buffer.alloc(0);
+                this.push(flushed);
+            }
+        }, BracketedPasteDecoder.CARRY_FLUSH_MS);
+        this.carryTimer.unref?.();
+    }
+    _flush(cb) {
+        if (this.carryTimer) {
+            clearTimeout(this.carryTimer);
+            this.carryTimer = null;
+        }
+        // End of stream. If we were still inside a paste (unterminated),
+        // flush the buffered content as a single line so it's not lost.
+        if (this.inPaste && this.pasteBuf.length > 0) {
+            this.push(this.collapseNewlines(this.pasteBuf));
+            this.pasteBuf = Buffer.alloc(0);
+            this.inPaste = false;
+        }
+        if (this.carry.length > 0) {
+            this.push(this.carry);
+            this.carry = Buffer.alloc(0);
+        }
+        cb();
+    }
+    process(data) {
+        let i = 0;
+        while (i < data.length) {
+            if (this.inPaste) {
+                const endIdx = data.indexOf(END_MARKER, i);
+                if (endIdx === -1) {
+                    // Whole remainder is paste content; check if the tail might be
+                    // a partial end-marker and carry it.
+                    const safe = this.safeSliceLength(data, i);
+                    this.pasteBuf = Buffer.concat([this.pasteBuf, data.subarray(i, safe)]);
+                    this.carry = data.subarray(safe);
+                    return;
+                }
+                this.pasteBuf = Buffer.concat([this.pasteBuf, data.subarray(i, endIdx)]);
+                this.push(this.collapseNewlines(this.pasteBuf));
+                // Append a newline so readline commits the pasted line as a
+                // single input — otherwise the user would still have to press
+                // Enter after the paste.
+                this.push(Buffer.from('\n'));
+                this.pasteBuf = Buffer.alloc(0);
+                this.inPaste = false;
+                i = endIdx + END_MARKER.length;
+            }
+            else {
+                const startIdx = data.indexOf(START_MARKER, i);
+                if (startIdx === -1) {
+                    const safe = this.safeSliceLength(data, i);
+                    this.push(data.subarray(i, safe));
+                    this.carry = data.subarray(safe);
+                    return;
+                }
+                if (startIdx > i)
+                    this.push(data.subarray(i, startIdx));
+                this.inPaste = true;
+                i = startIdx + START_MARKER.length;
+            }
+        }
+    }
+    /**
+     * Return the index up to which it's safe to emit bytes without risk of
+     * splitting a paste marker across chunks. If the tail of `data` could
+     * be a prefix of either marker, hold those bytes back.
+     */
+    safeSliceLength(data, from) {
+        const tail = data.length - from;
+        if (tail === 0)
+            return data.length;
+        const markerLen = START_MARKER.length; // both markers are 6 bytes
+        const windowStart = Math.max(from, data.length - (markerLen - 1));
+        for (let k = windowStart; k < data.length; k++) {
+            if (isPrefixOfMarker(data, k, data.length))
+                return k;
+        }
+        return data.length;
+    }
+    collapseNewlines(buf) {
+        // Replace \r\n, \n, and \r with a single space. Fast path: if there
+        // are no newlines, return the buffer as-is.
+        const hasNewline = buf.includes(0x0a) || buf.includes(0x0d);
+        if (!hasNewline)
+            return buf;
+        const out = Buffer.alloc(buf.length);
+        let o = 0;
+        for (let i = 0; i < buf.length; i++) {
+            const b = buf[i];
+            if (b === 0x0d) {
+                // Swallow \r and, if followed by \n, the \n too. Emit a single space.
+                if (i + 1 < buf.length && buf[i + 1] === 0x0a)
+                    i++;
+                out[o++] = 0x20;
+            }
+            else if (b === 0x0a) {
+                out[o++] = 0x20;
+            }
+            else {
+                out[o++] = b;
+            }
+        }
+        return out.subarray(0, o);
+    }
+}
+/**
+ * True when `data[start..end)` is a strict prefix of either the start or
+ * end paste marker (i.e. too short to decide yet, but could become one).
+ */
+function isPrefixOfMarker(data, start, end) {
+    const len = end - start;
+    if (len === 0)
+        return false;
+    if (len >= START_MARKER.length)
+        return false; // full-length matches handled elsewhere
+    for (const marker of [START_MARKER, END_MARKER]) {
+        let match = true;
+        for (let k = 0; k < len; k++) {
+            if (data[start + k] !== marker[k]) {
+                match = false;
+                break;
+            }
+        }
+        if (match)
+            return true;
+    }
+    return false;
+}

package/dist/repl/current-transport.js

@@ -0,0 +1,46 @@
+/**
+ * Session-scoped current-transport state. Set by:
+ *   - successful sap_transport_create
+ *   - explicit slash command /transport <trkorr>
+ * Cleared by:
+ *   - explicit slash command /transport clear
+ * Read by:
+ *   - tool handlers via ctx.currentTransport.get() (3-tier fallback when LLM omits transport arg)
+ *
+ * Rule 9 (transport isolation) — keeps all writes in one session attached to the
+ * same dedicated transport. The LLM can still override per-call by passing
+ * `transport` explicitly; in that case the handler logs a warning if the
+ * passed transport differs from session current-transport.
+ *
+ * Module-scope singleton per CLI process. Tests must call clearCurrentTransport()
+ * in beforeEach to avoid leakage across Vitest test files.
+ */
+let currentTransport = null;
+export function setCurrentTransport(trkorr) {
+    currentTransport = trkorr;
+}
+export function getCurrentTransport() {
+    return currentTransport;
+}
+export function clearCurrentTransport() {
+    currentTransport = null;
+}
+/**
+ * Handles the `/transport [<trkorr>|clear]` slash command. Returns user-facing
+ * status text. Mirrors the shape of handleSafetyModeCommand in safety-mode-state.ts.
+ */
+export function handleTransportCommand(arg) {
+    const trimmed = arg.trim();
+    if (trimmed === '') {
+        const cur = getCurrentTransport();
+        return cur === null
+            ? 'No current transport set. Use `/transport <TRKORR>` to attach one.'
+            : `Current transport: ${cur}`;
+    }
+    if (trimmed.toLowerCase() === 'clear') {
+        clearCurrentTransport();
+        return 'Current transport cleared.';
+    }
+    setCurrentTransport(trimmed);
+    return `Current transport set to ${trimmed}.`;
+}

package/dist/repl/diff-display.js

@@ -0,0 +1,41 @@
+/**
+ * Renders a unified diff between two ABAP source strings for terminal display.
+ * Used as the preview gate before any sap_update_method call so the user sees
+ * exactly what's about to change in SAP, with green +adds / red -removes.
+ *
+ * Pure function: no I/O, no side effects. The REPL composes this with an
+ * @inquirer/prompts.confirm gate (see update-method-intercept.ts).
+ */
+import { createPatch } from 'diff';
+import chalk from 'chalk';
+const NO_CHANGES_PREFIX = 'No changes';
+export function renderDiff(currentSource, proposedSource, opts) {
+    if (currentSource === proposedSource) {
+        return `${NO_CHANGES_PREFIX} for ${opts.label}.`;
+    }
+    const patch = createPatch(opts.label, currentSource, proposedSource, '(current)', '(proposed)');
+    if (!opts.syntaxHighlight)
+        return patch;
+    return colorizeUnified(patch);
+}
+/**
+ * Colorises a unified-diff string. Lines starting with `+` (but not `+++`) get
+ * green; lines starting with `-` (but not `---`) get red; `@@` hunk headers get
+ * cyan; everything else passes through unchanged.
+ */
+function colorizeUnified(patch) {
+    return patch
+        .split('\n')
+        .map((line) => {
+        if (line.startsWith('+++') || line.startsWith('---'))
+            return line;
+        if (line.startsWith('+'))
+            return chalk.green(line);
+        if (line.startsWith('-'))
+            return chalk.red(line);
+        if (line.startsWith('@@'))
+            return chalk.cyan(line);
+        return line;
+    })
+        .join('\n');
+}

package/dist/repl/file-picker.js

@@ -0,0 +1,219 @@
+/**
+ * Two-step interactive picker for `.cspeach.json` files in the workspace.
+ *
+ * UX:
+ *   1. Search-as-you-type list of files (filename + artefactType + version)
+ *   2. Action menu tailored to the picked artefactType — pick one of:
+ *        spec-gap → --status, --from /abap-design
+ *        design   → --status, --from /abap-estimate
+ *        estimate → --status only
+ *        unknown  → all --status variants
+ *
+ * Returns the fully-formed slash command (e.g. "/abap-design --from
+ * @<filename>"), or null if the user cancelled at either step.
+ *
+ * Uses the same withInquirer guard / cancel-sentinel pattern as
+ * slash-picker.ts so cancellation in either step doesn't drop the user
+ * back to the parent shell.
+ */
+import { search, select } from '@inquirer/prompts';
+import { withInquirer } from './inquirer-guard.js';
+import { listProjectFiles, detectDesignShape } from '../projects/workspace.js';
+const CANCEL_VALUE = '__cspeach_cancel__';
+/**
+ * Compute the menu of valid actions for an envelope of a given
+ * artefactType. Order: most-common first.
+ *
+ * For `design` envelopes, the BUILD-skill recommendation depends on
+ * what the design actually contains. RAP-shaped designs (BDEF /
+ * Behavior Pool / Service Binding present) recommend `/abap-rap`;
+ * classic designs (report / class / function module) recommend
+ * `/abap-generate`. Estimate is always demoted to a side option —
+ * it's optional, not the canonical next step. `designShape` defaults
+ * to 'unknown' so non-design call sites pass nothing.
+ */
+function envelopeActionsFor(type, designShape = 'unknown') {
+    if (type === 'spec-gap') {
+        return [
+            { label: '/abap-design --from         (promote → design)', command: '/abap-design --from' },
+            { label: '/abap-spec-gap --status     (inspect)', command: '/abap-spec-gap --status' },
+        ];
+    }
+    if (type === 'design') {
+        const ALL = {
+            rap: { label: '/abap-rap --from           (build the RAP stack — recommended)', command: '/abap-rap --from' },
+            gen: { label: '/abap-generate --from      (build the objects)', command: '/abap-generate --from' },
+            status: { label: '/abap-design --status      (inspect)', command: '/abap-design --status' },
+            est: { label: '/abap-estimate --from      (effort estimate — optional)', command: '/abap-estimate --from' },
+        };
+        if (designShape === 'rap') {
+            return [
+                ALL.rap,
+                { ...ALL.gen, label: '/abap-generate --from      (build as classic — alternative)' },
+                ALL.status,
+                ALL.est,
+            ];
+        }
+        if (designShape === 'classic') {
+            return [
+                { ...ALL.gen, label: '/abap-generate --from      (build the objects — recommended)' },
+                { ...ALL.rap, label: '/abap-rap --from           (build as RAP — alternative)' },
+                ALL.status,
+                ALL.est,
+            ];
+        }
+        // unknown shape — neutral order, no recommendation badge
+        return [ALL.gen, ALL.rap, ALL.status, ALL.est];
+    }
+    if (type === 'estimate') {
+        return [
+            { label: '/abap-estimate --status     (inspect)', command: '/abap-estimate --status' },
+        ];
+    }
+    if (type === 'upgrade-scan') {
+        return [
+            { label: '/abap-upgrade-fix --from    (start remediation — recommended)', command: '/abap-upgrade-fix --from' },
+            { label: '/abap-upgrade-scan --status (inspect findings)', command: '/abap-upgrade-scan --status' },
+        ];
+    }
+    if (type === 'upgrade-progress') {
+        return [
+            { label: '/abap-upgrade-verify --from (run formal verification — recommended)', command: '/abap-upgrade-verify --from' },
+            { label: '/abap-upgrade-fix --from    (continue remediation)', command: '/abap-upgrade-fix --from' },
+            { label: '/abap-upgrade-fix --status  (inspect progress)', command: '/abap-upgrade-fix --status' },
+        ];
+    }
+    if (type === 'upgrade-report') {
+        // Terminal artefact — verification is sign-off.
+        return [
+            { label: '/abap-upgrade-verify --status (inspect final report)', command: '/abap-upgrade-verify --status' },
+        ];
+    }
+    if (type === 'cca-assessment') {
+        // v0.7 — cca-assessment is NO LONGER terminal in the --from chain.
+        // It fans out into three specialist skills (test, upgrade-fix,
+        // modernize), each consuming the same assessment for its own
+        // workstream. Order surfaces the recommended sequence: lock
+        // behaviour with tests first, fix syntax second, modernize last.
+        return [
+            { label: '/abap-test --from          (lock current behaviour first — recommended)', command: '/abap-test --from' },
+            { label: '/abap-upgrade-fix --from   (mechanical ATC fixes, fast)', command: '/abap-upgrade-fix --from' },
+            { label: '/abap-modernize --from     (structural Clean Core + REDESIGN work)', command: '/abap-modernize --from' },
+            { label: '/abap-cca --status         (inspect classifications)', command: '/abap-cca --status' },
+            { label: '/abap-cca --resume         (continue where left off)', command: '/abap-cca --resume' },
+        ];
+    }
+    if (type === 'modernize-result') {
+        return [
+            { label: '/abap-modernize --status   (inspect what was modernized)', command: '/abap-modernize --status' },
+        ];
+    }
+    if (type === 'test-coverage') {
+        return [
+            { label: '/abap-test --status        (inspect generated test coverage)', command: '/abap-test --status' },
+        ];
+    }
+    // Unknown / cca / incident — fall back to inspection only across all
+    // three known status renderers; the renderer auto-detects the type.
+    return [
+        { label: '/abap-spec-gap --status     (inspect)', command: '/abap-spec-gap --status' },
+        { label: '/abap-design --status       (inspect)', command: '/abap-design --status' },
+        { label: '/abap-estimate --status     (inspect)', command: '/abap-estimate --status' },
+    ];
+}
+/**
+ * Action menu for a TEXT input file (.txt / .md). The user's intent
+ * is to feed the file contents to a skill as the requirement / spec.
+ * The CLI reads the file at runtime and substitutes its content into
+ * the prompt (see expandTextFileAttachments in workspace.ts).
+ *
+ * Order: most-common skills for "I have a requirement, do something
+ * with it" — start with spec-gap (the canonical entry point) then the
+ * downstream skills in case the user wants to skip a step.
+ */
+function textActionsFor() {
+    return [
+        { label: '/abap-spec-gap              (find missing questions in this spec)', command: '/abap-spec-gap' },
+        { label: '/abap-design                (design directly from this spec)', command: '/abap-design' },
+        { label: '/abap-estimate              (effort estimate from this spec)', command: '/abap-estimate' },
+        { label: '/abap-explain               (plain-language explanation)', command: '/abap-explain' },
+    ];
+}
+/**
+ * Open the picker. Returns one of three tagged outcomes — see
+ * `FilePickerResult`. Caller is responsible for dispatching the
+ * picked command and for choosing whether to print a file listing
+ * (only on 'empty', never on 'cancelled').
+ *
+ * Both inquirer prompts (file search + action select) run inside ONE
+ * `withInquirer` block. Two consecutive `withInquirer` calls would
+ * race: the first call's `process.nextTick(() => setSuppress(false))`
+ * clears the close-suppress flag BEFORE the second call's pause arms
+ * it again, and the spurious 'close' inquirer emits between calls
+ * slips through and exits the REPL silently. One guard around the
+ * whole flow avoids that gap.
+ */
+export async function openFilePicker() {
+    const files = await listProjectFiles();
+    if (files.length === 0) {
+        return { kind: 'empty' };
+    }
+    try {
+        return await withInquirer(async () => {
+            // Step 1 — pick a file.
+            const fileResult = await search({
+                message: 'Pick a project file',
+                source: async (input) => {
+                    const filter = (input ?? '').toLowerCase();
+                    const filtered = filter.length === 0
+                        ? files
+                        : files.filter((f) => f.filename.toLowerCase().includes(filter));
+                    const cancelChoice = {
+                        name: '← Cancel',
+                        value: CANCEL_VALUE,
+                        short: 'cancel',
+                    };
+                    const choices = filtered.map((f) => ({
+                        name: `${f.filename}  [${f.artefactType} v${f.version ?? '?'}]`,
+                        value: f.filename,
+                        short: f.filename,
+                    }));
+                    return [cancelChoice, ...choices];
+                },
+            });
+            if (fileResult === CANCEL_VALUE)
+                return { kind: 'cancelled' };
+            const pickedFile = files.find((f) => f.filename === fileResult);
+            if (!pickedFile)
+                return { kind: 'cancelled' };
+            // Step 2 — pick an action for the file. Action menu depends on
+            // file kind: envelopes get promote/inspect, text files get the
+            // skill-input commands that ingest the file contents. For design
+            // envelopes, additionally inspect the object list to pick the
+            // right BUILD skill recommendation (RAP vs classic).
+            const designShape = pickedFile.artefactType === 'design'
+                ? detectDesignShape(pickedFile.path)
+                : 'unknown';
+            const actionsList = pickedFile.kind === 'text'
+                ? textActionsFor()
+                : envelopeActionsFor(pickedFile.artefactType, designShape);
+            const action = await select({
+                message: `What with ${pickedFile.filename}?`,
+                choices: [
+                    ...actionsList.map((a) => ({
+                        name: a.label,
+                        value: a.command,
+                    })),
+                    { name: '← Cancel', value: CANCEL_VALUE },
+                ],
+            });
+            if (action === CANCEL_VALUE)
+                return { kind: 'cancelled' };
+            return { kind: 'command', command: `${action} @${pickedFile.filename}` };
+        });
+    }
+    catch {
+        // Ctrl+C inside either prompt — treat as cancellation.
+        return { kind: 'cancelled' };
+    }
+}