@pugi/cli 0.1.0-alpha.10

package/dist/core/repl/history-search.js

@@ -0,0 +1,175 @@
+/**
+ * FZF-style history search - Sprint α6.14.
+ *
+ * Powers the Ctrl+R (reverse) / Ctrl+S (forward) interactive search
+ * mode in the REPL input box. Hand-rolled scorer (no dep) tuned for
+ * short query strings (operator typing a few chars) over up to
+ * MAX_HISTORY_ENTRIES candidates.
+ *
+ * Scoring model (mirrors fzf v2 mid-priorities, simplified):
+ *
+ *   - Substring match required. Non-matching candidates score 0.
+ *   - Prefix match: +50
+ *   - Word-boundary start (' ', '/', '-', '_'): +20
+ *   - Camel boundary (`abcD` → 'D'): +10
+ *   - Contiguous run bonus: +5 per consecutive char after the first
+ *   - Distance penalty: -1 per gap char between query characters
+ *   - Recency bonus: +0.5 × (recencyRank / total) so newer entries
+ *     break ties in the operator's favour
+ *
+ * The result is a list of matches ordered by descending score with
+ * the matched character positions preserved so the UI can highlight
+ * them. `cycle` steps the focused match index forward (Ctrl+R again)
+ * or backward (Ctrl+S) modulo the result length.
+ *
+ * Contract:
+ *   - `searchHistory(query, entries, options)` is pure. No I/O.
+ *   - Empty query returns ALL entries newest-first so the operator
+ *     can browse without typing.
+ *   - Matching is case-insensitive on ASCII; non-ASCII characters
+ *     compare as-is.
+ *   - `cycle(state, direction)` is a no-op when there are no matches.
+ */
+const DEFAULT_LIMIT = 50;
+const WORD_BOUNDARIES = new Set([' ', '/', '-', '_', '.', ',', ':', ';', '\t']);
+/**
+ * Score one candidate against the query. Returns `null` when the
+ * query cannot be matched as an in-order substring (not necessarily
+ * contiguous). The matched positions are returned so the UI can
+ * underline them.
+ */
+export function scoreCandidate(query, candidate) {
+    if (query.length === 0) {
+        return { score: 0, positions: [] };
+    }
+    const lowerQuery = query.toLowerCase();
+    const lowerCandidate = candidate.toLowerCase();
+    // Walk the candidate, greedily matching each query char in order.
+    const positions = [];
+    let qIdx = 0;
+    for (let i = 0; i < lowerCandidate.length && qIdx < lowerQuery.length; i += 1) {
+        if (lowerCandidate[i] === lowerQuery[qIdx]) {
+            positions.push(i);
+            qIdx += 1;
+        }
+    }
+    if (qIdx < lowerQuery.length)
+        return null;
+    // Score the match.
+    let score = 0;
+    // Prefix bonus.
+    if (positions[0] === 0)
+        score += 50;
+    // Substring contiguity + boundary bonuses.
+    let lastPos = -2;
+    for (let p = 0; p < positions.length; p += 1) {
+        const pos = positions[p];
+        // Contiguous run.
+        if (pos === lastPos + 1) {
+            score += 5;
+        }
+        else if (lastPos >= 0) {
+            // Distance penalty for non-contiguous matches.
+            score -= pos - lastPos - 1;
+        }
+        // Word-boundary start.
+        if (pos === 0) {
+            // Already counted as prefix.
+        }
+        else {
+            const prev = candidate[pos - 1] ?? '';
+            if (WORD_BOUNDARIES.has(prev)) {
+                score += 20;
+            }
+            else {
+                // Camel boundary: prev is lowercase, current is uppercase.
+                const cur = candidate[pos] ?? '';
+                if (prev === prev.toLowerCase() && cur !== cur.toLowerCase()) {
+                    score += 10;
+                }
+            }
+        }
+        lastPos = pos;
+    }
+    return { score, positions };
+}
+/**
+ * Search a history list for matches. Entries are passed oldest-first
+ * (the format `history.read` returns); the recency bonus uses the
+ * original index so newer entries win ties.
+ */
+export function searchHistory(query, entries, options = {}) {
+    const limit = options.limit ?? DEFAULT_LIMIT;
+    const total = entries.length;
+    if (query.length === 0) {
+        // Empty query - browse mode. Return newest-first up to limit, no
+        // scoring needed.
+        const out = [];
+        for (let i = total - 1; i >= 0 && out.length < limit; i -= 1) {
+            const brief = entries[i];
+            out.push({ brief, positions: [], score: 0, originalIndex: i });
+        }
+        return out;
+    }
+    const candidates = [];
+    for (let i = 0; i < total; i += 1) {
+        const brief = entries[i];
+        const scored = scoreCandidate(query, brief);
+        if (!scored)
+            continue;
+        // Recency bonus: 0..0.5 weight scaled by index/total.
+        const recency = total === 0 ? 0 : (i / total) * 0.5;
+        candidates.push({
+            brief,
+            positions: scored.positions,
+            score: scored.score + recency,
+            originalIndex: i,
+        });
+    }
+    candidates.sort((a, b) => {
+        if (b.score !== a.score)
+            return b.score - a.score;
+        // Tie-breaker: newer first.
+        return b.originalIndex - a.originalIndex;
+    });
+    return candidates.slice(0, limit);
+}
+/**
+ * Initial search state for a fresh Ctrl+R press. Empty query +
+ * focusedIndex 0 over the browse list.
+ */
+export function initialSearchState(entries) {
+    const matches = searchHistory('', entries);
+    return { query: '', matches, focusedIndex: 0 };
+}
+/**
+ * Update the search state when the operator types a new query char or
+ * removes one. The focused index is clamped to the new match list so
+ * the UI never points off-the-end.
+ */
+export function applyQuery(state, query, entries) {
+    const matches = searchHistory(query, entries);
+    const focusedIndex = matches.length === 0 ? 0 : Math.min(state.focusedIndex, matches.length - 1);
+    return { query, matches, focusedIndex };
+}
+/**
+ * Move the focused match. `+1` = next (Ctrl+R repeat), `-1` = previous
+ * (Ctrl+S). Wraps around modulo result length so the operator never
+ * has to chase the end.
+ */
+export function cycle(state, direction) {
+    if (state.matches.length === 0)
+        return state;
+    const len = state.matches.length;
+    const next = (state.focusedIndex + direction + len) % len;
+    return { ...state, focusedIndex: next };
+}
+/**
+ * Pull the brief from the currently focused match, or `null` when
+ * the result list is empty (Enter accepts nothing).
+ */
+export function currentBrief(state) {
+    const match = state.matches[state.focusedIndex];
+    return match ? match.brief : null;
+}
+//# sourceMappingURL=history-search.js.map

package/dist/core/repl/history.js

@@ -0,0 +1,172 @@
+/**
+ * Persistent REPL history (per-workspace) - Sprint α6.14.
+ *
+ * Stores submitted briefs in `~/.pugi/history/<workspace-slug>.jsonl`,
+ * one JSON object per line. The format is line-delimited JSON so the
+ * file can be appended to atomically (single `write(2)` per entry on
+ * Linux/macOS for entries < PIPE_BUF) and tailed by humans without a
+ * parser. Per-workspace separation lets the operator switch repos and
+ * keep brief history contextual: `brief: fix the cabinet sidebar 401`
+ * does not bleed into the agents repo.
+ *
+ * Contract:
+ *
+ *   - `append({ home, workspaceSlug, brief })` writes one line. Dedups
+ *     a brief that is identical to the immediately preceding entry
+ *     (most common operator pattern: Up + Enter to re-run).
+ *   - `read({ home, workspaceSlug })` returns entries oldest-first so
+ *     the caller can navigate with `index = entries.length - 1` for
+ *     "most recent" semantics.
+ *   - The file is capped at MAX_ENTRIES; on overflow we keep the most
+ *     recent slice and rewrite. Cheap because briefs are short text
+ *     and the cap is 1000.
+ *   - `slugForCwd(cwd)` normalises a working directory into a safe
+ *     filename component (alphanumerics + `-`, lowercase, slashes
+ *     collapsed). Empty cwd resolves to `default`.
+ *   - Failures (missing $HOME, disk full, EACCES) NEVER throw. History
+ *     is operator comfort, not a contract surface; degrading to "no
+ *     history this session" is correct.
+ *
+ * Brand voice: file is operator-facing if they `cat` it, so the JSON
+ * keys stay readable English (`brief`, `ts`). No forbidden words.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, renameSync, unlinkSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** Cap on stored entries per workspace. Drops oldest on overflow. */
+export const MAX_HISTORY_ENTRIES = 1000;
+/**
+ * Compute the on-disk path for a given workspace slug. Tests rely on
+ * this to assert per-workspace isolation without re-implementing the
+ * directory math.
+ */
+export function historyPath(io) {
+    const home = io.home ?? homedir();
+    const safe = sanitiseSlug(io.workspaceSlug);
+    return join(home, '.pugi', 'history', `${safe}.jsonl`);
+}
+/**
+ * Append a brief to history. Dedups consecutive identical entries.
+ * Returns the entry that was written, or `null` when the entry was
+ * deduped or the brief was empty.
+ */
+export function append(input) {
+    const brief = input.brief.trim();
+    if (brief.length === 0)
+        return null;
+    const path = historyPath(input);
+    try {
+        ensureDir(dirname(path));
+    }
+    catch {
+        return null;
+    }
+    const existing = read({ home: input.home, workspaceSlug: input.workspaceSlug });
+    const last = existing[existing.length - 1];
+    if (last && last.brief === brief) {
+        return null;
+    }
+    const ts = (input.now ?? (() => new Date()))().toISOString();
+    const entry = { ts, brief };
+    // Overflow path: combined length > cap means we trim before rewrite.
+    // Write to a sibling tmp file and renameSync over the target so
+    // concurrent CLI instances in the same workspace cannot observe a
+    // half-written file or race a parallel appendFileSync into oblivion.
+    // POSIX renameSync is atomic within a directory; on Windows fs.rename
+    // is atomic too as long as both paths are on the same volume (the tmp
+    // sibling guarantees that). P2 fix from PR #335 triple-review.
+    if (existing.length + 1 > MAX_HISTORY_ENTRIES) {
+        const trimmed = [...existing.slice(existing.length + 1 - MAX_HISTORY_ENTRIES), entry];
+        const tmpPath = `${path}.tmp`;
+        try {
+            writeFileSync(tmpPath, trimmed.map(serialize).join('\n') + '\n', { mode: 0o600 });
+            renameSync(tmpPath, path);
+        }
+        catch {
+            // Best-effort cleanup of the orphan tmp file; never throw out.
+            try {
+                unlinkSync(tmpPath);
+            }
+            catch {
+                /* ignore — tmp file may not exist yet */
+            }
+            return null;
+        }
+        return entry;
+    }
+    try {
+        appendFileSync(path, serialize(entry) + '\n', { mode: 0o600 });
+    }
+    catch {
+        return null;
+    }
+    return entry;
+}
+/**
+ * Read history for a workspace, oldest-first. Returns `[]` when the
+ * file is missing, unreadable, or empty. Malformed lines are dropped
+ * silently - one bad line should not nuke the whole history.
+ */
+export function read(io) {
+    const path = historyPath(io);
+    if (!existsSync(path))
+        return [];
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const line of raw.split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed === 'object' &&
+                parsed !== null &&
+                typeof parsed.brief === 'string' &&
+                typeof parsed.ts === 'string') {
+                out.push({
+                    ts: parsed.ts,
+                    brief: parsed.brief,
+                });
+            }
+        }
+        catch {
+            // Drop malformed line.
+        }
+    }
+    return out;
+}
+/**
+ * Normalise a cwd or workspace name into a safe filename component.
+ * Lowercase, alphanumerics + `-` only. Slashes become `-`. Empty input
+ * resolves to `default` so we never produce an empty filename.
+ */
+export function slugForCwd(cwd) {
+    if (!cwd || cwd.trim().length === 0)
+        return 'default';
+    // Strip leading slash so `/Users/foo` becomes `users-foo`.
+    const normalised = cwd
+        .replace(/^[/\\]+/, '')
+        .replace(/[/\\]+/g, '-')
+        .toLowerCase();
+    return sanitiseSlug(normalised);
+}
+function sanitiseSlug(raw) {
+    const cleaned = raw.replace(/[^a-z0-9-]/gi, '-').toLowerCase().replace(/-+/g, '-');
+    const trimmed = cleaned.replace(/^-+|-+$/g, '');
+    return trimmed.length === 0 ? 'default' : trimmed;
+}
+function serialize(entry) {
+    return JSON.stringify(entry);
+}
+function ensureDir(dir) {
+    if (existsSync(dir))
+        return;
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+}
+//# sourceMappingURL=history.js.map

package/dist/core/repl/kill-ring.js

@@ -0,0 +1,138 @@
+/**
+ * Kill ring for the REPL input - Sprint α6.14.
+ *
+ * Tiny LIFO buffer that backs the readline-style kill commands:
+ *
+ *   Ctrl+U  - kill from cursor to line start
+ *   Ctrl+K  - kill from cursor to line end
+ *   Ctrl+W  - kill word backwards (whitespace + punctuation delimiter)
+ *   Ctrl+Y  - yank the most recent kill at the cursor
+ *
+ * The ring is bounded (MAX_RING_ENTRIES = 10) so the operator's
+ * recent kills are reachable without leaking memory across long
+ * sessions. We do NOT implement Meta+Y (cycle yanks) at this layer -
+ * sticking to the most-recent-yank keeps the input box logic small
+ * and matches the bash default for new operators.
+ *
+ * The module is pure functional: every operation returns a NEW ring,
+ * so the input box can stash one in `useState` without mutation
+ * worries. Empty slices are no-ops (we do not push empty strings) so
+ * Ctrl+U at column 0 does not pollute the ring with `""`.
+ */
+export const MAX_RING_ENTRIES = 10;
+export const EMPTY_KILL_RING = { entries: [] };
+/**
+ * Push a slice into the ring. Returns a new ring with the slice at
+ * the front; older entries shift right and the tail is dropped if
+ * the cap is exceeded. Empty / whitespace-only slices are a no-op so
+ * the ring stays meaningful.
+ */
+export function push(ring, slice) {
+    if (slice.length === 0)
+        return ring;
+    const next = [slice, ...ring.entries];
+    return { entries: next.slice(0, MAX_RING_ENTRIES) };
+}
+/**
+ * Read the most-recent entry without mutating the ring. Returns
+ * `null` when the ring is empty so the caller can decide whether to
+ * beep, no-op, or fall through to plain insert.
+ */
+export function yank(ring) {
+    return ring.entries.length > 0 ? ring.entries[0] : null;
+}
+/**
+ * Word delimiter used by Ctrl+W. Whitespace + ASCII punctuation,
+ * matching the readline default. We treat `_` and `-` as part of the
+ * word so kebab-case and snake_case identifiers behave as one token
+ * (the brief frequently mentions filenames + symbols).
+ */
+const WORD_DELIMITERS = new Set([
+    ' ', '\t', '\n',
+    '.', ',', ';', ':',
+    '/', '\\',
+    '!', '?', '@', '#', '$', '%', '^', '&', '*',
+    '(', ')', '[', ']', '{', '}', '<', '>',
+    '"', "'", '`',
+    '=', '+', '|', '~',
+]);
+/**
+ * Compute the start of the previous word given a cursor position.
+ * Walks LEFT from `cursor - 1`, skipping any delimiters that
+ * immediately precede the cursor (so Ctrl+W at the end of `foo `
+ * still kills `foo`), then continues left until it hits the next
+ * delimiter or the start of the line.
+ *
+ * Returns the offset BEFORE which the kill should start (i.e. the
+ * slice to remove is `line.slice(start, cursor)`).
+ */
+export function previousWordStart(line, cursor) {
+    let i = Math.min(cursor, line.length) - 1;
+    // Skip trailing delimiters.
+    while (i >= 0 && WORD_DELIMITERS.has(line[i]))
+        i -= 1;
+    // Walk through the word.
+    while (i >= 0 && !WORD_DELIMITERS.has(line[i]))
+        i -= 1;
+    return i + 1;
+}
+/**
+ * Apply a Ctrl+U kill: from cursor to line start. Returns the new
+ * line + cursor + ring. No-op when cursor is already at column 0.
+ */
+export function killToLineStart(line, cursor, ring) {
+    if (cursor === 0)
+        return { line, cursor, ring };
+    const slice = line.slice(0, cursor);
+    return {
+        line: line.slice(cursor),
+        cursor: 0,
+        ring: push(ring, slice),
+    };
+}
+/**
+ * Apply a Ctrl+K kill: from cursor to line end. Returns the new
+ * line + cursor + ring. No-op when cursor is already past the last
+ * character.
+ */
+export function killToLineEnd(line, cursor, ring) {
+    if (cursor >= line.length)
+        return { line, cursor, ring };
+    const slice = line.slice(cursor);
+    return {
+        line: line.slice(0, cursor),
+        cursor,
+        ring: push(ring, slice),
+    };
+}
+/**
+ * Apply a Ctrl+W kill: from cursor back to the start of the previous
+ * word. Returns the new line + cursor + ring. No-op when cursor is
+ * at column 0.
+ */
+export function killWordBackward(line, cursor, ring) {
+    if (cursor === 0)
+        return { line, cursor, ring };
+    const start = previousWordStart(line, cursor);
+    const slice = line.slice(start, cursor);
+    return {
+        line: line.slice(0, start) + line.slice(cursor),
+        cursor: start,
+        ring: push(ring, slice),
+    };
+}
+/**
+ * Apply a Ctrl+Y yank: insert the most-recent entry at the cursor.
+ * Returns the new line + cursor unchanged when the ring is empty
+ * (the caller decides whether to surface a visual cue).
+ */
+export function yankAtCursor(line, cursor, ring) {
+    const entry = yank(ring);
+    if (entry === null)
+        return { line, cursor };
+    return {
+        line: line.slice(0, cursor) + entry + line.slice(cursor),
+        cursor: cursor + entry.length,
+    };
+}
+//# sourceMappingURL=kill-ring.js.map