cvc-tui 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jai Kumar Meena
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# cvc-tui
+
+The **Cognitive Version Control** terminal UI — a React + [Ink](https://github.com/vadimdemedes/ink) app that runs in your terminal and talks to the CVC Python core through a JSON-RPC gateway.
+
+This package is a **sidecar** to the Python `cvc` wheel. It is built once with `bun build --compile` and the resulting single binary is embedded in the wheel (Slice 13). Users never `npm install` it directly.
+
+## Status
+
+| Slice | What's in this package |
+| ----- | ---------------------- |
+| **Slice 11 (this scaffold)** | Build pipeline, banner, layout shell, store skeleton, gateway *stub*. |
+| Slice 12 | Streaming markdown renderer, slash commands, history. |
+| Slice 13 | Real JSON-RPC GatewayClient over stdio + `bun --compile` packaging. |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  entry.tsx                                                  │
+│   ├─ TTY check → fallback to plain banner                   │
+│   ├─ GatewayClient.connect()    (stub today)                │
+│   └─ render(<App/>) via Ink                                 │
+│                                                             │
+│  app.tsx                                                    │
+│   └─ <AppLayout>                                            │
+│        ├─ <Branding/>          banner + version + model     │
+│        ├─ <TranscriptArea/>    nanostores: $messages        │
+│        └─ <InputLine/>         <Thinking/> when busy        │
+│                                                             │
+│  app/uiStore.ts          ← terminal dims, focus, busy       │
+│  app/turnStore.ts        ← messages, current turn lifecycle │
+│  gateway/client.ts       ← STUB until Slice 11 wraps up     │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Why Ink + React 19?
+
+- **Ink 6** gives us flex layout, mouse, focus, raw-mode input, all over node streams.
+- **React 19** + the new compiler removes 90% of `useMemo`/`useCallback` ceremony.
+- **nanostores** for state — zero boilerplate, surgical re-renders, no provider tree.
+
+### Why Bun?
+
+- 3-5× faster cold start than `tsx` for the same TS sources.
+- `bun build --compile` produces a single ~50 MB binary we ship inside the wheel.
+- We still keep an `npm`/`tsx` fallback so contributors without Bun can hack on it.
+
+### CVC theme
+
+| Token   | Value     | Usage |
+| ------- | --------- | ----- |
+| primary | `#e63946` | banner, prompt arrow, assistant role tag |
+| dark    | `#0d1b2a` | reserved for backgrounds when supported |
+| accent  | `#4a9eff` | tagline, user role tag, secondary highlights |
+| dim     | `#6b7280` | placeholders, separators |
+
+Assumes the user's terminal font is **JetBrains Mono** (or any Nerd Font with box-drawing + braille).
+
+## Scripts
+
+```bash
+bun install                # or: npm install
+bun run dev                # or: npm run dev   (watches & reloads)
+bun run build              # or: npm run build (compiles to dist/)
+bun run test               # or: npm run test  (vitest)
+bun run lint
+bun run fmt
+```
+
+If `bun` is not on `PATH`, every script silently falls back to `tsx` / `tsc`.
+
+## Layout
+
+```
+src/
+├── entry.tsx                # process bootstrap
+├── app.tsx                  # root component tree
+├── banner.ts                # CVC ASCII art + colour tokens
+├── types.ts                 # shared TS types + theme constants
+├── app/
+│   ├── uiStore.ts           # nanostores: ui state
+│   └── turnStore.ts         # nanostores: turn / transcript
+├── components/
+│   ├── appLayout.tsx        # flex root + resize tracking
+│   ├── branding.tsx         # banner panel
+│   ├── textInput.tsx        # ink-text-input wrapper
+│   ├── streamingMarkdown.tsx# placeholder renderer (Slice 12)
+│   └── thinking.tsx         # animated spinner
+├── config/
+│   └── timing.ts            # spinner / throttle constants
+├── gateway/
+│   └── client.ts            # JSON-RPC client STUB
+└── __tests__/
+    └── banner.test.ts
+```
+
+## Beating Hermes
+
+Where Hermes' `ui-tui/` mixes a `packages/hermes-ink` workspace + Babel + a separate compile step, `cvc-tui` is **a single Bun-built binary**. No workspaces, no Babel pipeline, no `tsx --watch` in production. Cold start drops from ~700 ms (Hermes) to ~120 ms (target).
+
+## License
+
+Same as the parent `cvc` project.

package/dist/app/completion.js

@@ -0,0 +1,98 @@
+// Tab-completion logic. Pure functions where possible, with one
+// fs-touching helper for path expansion.
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { listCommandNames } from './slash/registry.js';
+/**
+ * Find the token under the cursor: a maximal run of non-whitespace ending at
+ * `cursor`. Returns null when no token (cursor on whitespace at boundary).
+ */
+export function tokenAtCursor(text, cursor) {
+    if (cursor < 0)
+        cursor = 0;
+    if (cursor > text.length)
+        cursor = text.length;
+    let s = cursor;
+    while (s > 0 && !/\s/.test(text[s - 1]))
+        s--;
+    const tok = text.slice(s, cursor);
+    if (!tok)
+        return null;
+    const isSlash = tok.startsWith('/') && s === firstNonSpaceOnLine(text, s);
+    const isPath = !isSlash && (tok.startsWith('~/') || tok.startsWith('./') || tok.startsWith('../') || tok.startsWith('/'));
+    return { start: s, token: tok, isSlash, isPath };
+}
+function firstNonSpaceOnLine(text, off) {
+    // Walk back to start of logical line, then forward over spaces/tabs.
+    const lineStart = text.lastIndexOf('\n', off - 1) + 1;
+    let i = lineStart;
+    while (i < text.length && (text[i] === ' ' || text[i] === '\t'))
+        i++;
+    return i;
+}
+/** Slash-command candidates whose name starts with `prefix`. */
+export function slashCandidates(prefix) {
+    return listCommandNames()
+        .filter((n) => n.startsWith(prefix))
+        .sort();
+}
+/**
+ * Path candidates for `prefix`. Reads the parent directory and returns
+ * matching entries (files + dirs, dirs suffixed with `/`).
+ *
+ * Side-effect: touches the filesystem (fs.readdirSync).
+ */
+export function pathCandidates(prefix) {
+    let abs = prefix;
+    let displayPrefix = prefix;
+    if (prefix.startsWith('~/')) {
+        abs = path.join(os.homedir(), prefix.slice(2));
+    }
+    // Decide directory + leaf to filter by.
+    const lastSlash = abs.lastIndexOf('/');
+    let dirAbs;
+    let dirDisplay;
+    let leaf;
+    if (lastSlash < 0) {
+        dirAbs = '.';
+        dirDisplay = '';
+        leaf = abs;
+    }
+    else {
+        dirAbs = abs.slice(0, lastSlash + 1) || '/';
+        dirDisplay = displayPrefix.slice(0, lastSlash + 1);
+        leaf = abs.slice(lastSlash + 1);
+    }
+    let entries;
+    try {
+        entries = fs.readdirSync(dirAbs, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const e of entries) {
+        if (!e.name.startsWith(leaf))
+            continue;
+        if (leaf === '' && e.name.startsWith('.'))
+            continue; // skip hidden when no leaf
+        out.push(dirDisplay + e.name + (e.isDirectory() ? '/' : ''));
+    }
+    return out.sort();
+}
+/** Compute candidates for the given context. */
+export function candidatesFor(ctx) {
+    if (ctx.isSlash)
+        return slashCandidates(ctx.token);
+    if (ctx.isPath)
+        return pathCandidates(ctx.token);
+    return [];
+}
+/** Apply a candidate to the buffer at the given start offset (replacing token). */
+export function applyCandidate(text, start, tokenLen, candidate) {
+    const before = text.slice(0, start);
+    const after = text.slice(start + tokenLen);
+    const next = before + candidate + after;
+    return { text: next, cursor: start + candidate.length };
+}

package/dist/app/historyStore.js

@@ -0,0 +1,119 @@
+// History store — persists user input to ~/.cvc/agent_history.
+// One entry per line, dedup against immediate previous, max 10000.
+import { atom } from 'nanostores';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+export const HISTORY_MAX = 10000;
+function defaultHistoryPath() {
+    return path.join(os.homedir(), '.cvc', 'agent_history');
+}
+let historyPath = defaultHistoryPath();
+/** Used by tests to redirect persistence. */
+export function setHistoryPath(p) {
+    historyPath = p;
+}
+export function getHistoryPath() {
+    return historyPath;
+}
+export const $history = atom([]);
+/**
+ * Cursor pointing into history while user is browsing with Up/Down.
+ * `null` means "not browsing" (i.e. at the live edit buffer).
+ */
+export const $historyCursor = atom(null);
+/** Snapshot of the live buffer so we can restore it after browsing. */
+export const $historyDraft = atom('');
+export function loadHistory() {
+    try {
+        if (!fs.existsSync(historyPath)) {
+            $history.set([]);
+            return [];
+        }
+        const raw = fs.readFileSync(historyPath, 'utf8');
+        // Drop empty trailing line, ignore blank lines.
+        const lines = raw.split('\n').filter((l) => l.length > 0);
+        $history.set(lines);
+        return lines;
+    }
+    catch {
+        $history.set([]);
+        return [];
+    }
+}
+/** Append an entry, dedup-against-previous, cap at HISTORY_MAX, persist. */
+export function pushHistory(entry) {
+    const trimmed = entry.replace(/\s+$/g, '');
+    if (!trimmed)
+        return;
+    const cur = $history.get();
+    if (cur.length > 0 && cur[cur.length - 1] === trimmed) {
+        // Dedup consecutive duplicates without rewriting the file.
+        return;
+    }
+    let next = [...cur, trimmed];
+    if (next.length > HISTORY_MAX) {
+        next = next.slice(next.length - HISTORY_MAX);
+    }
+    $history.set(next);
+    persist();
+}
+export function persist() {
+    try {
+        fs.mkdirSync(path.dirname(historyPath), { recursive: true });
+        fs.writeFileSync(historyPath, $history.get().join('\n') + '\n', 'utf8');
+    }
+    catch {
+        // Best-effort — never crash the UI on history I/O failure.
+    }
+}
+/**
+ * Reverse-incremental search. Returns up to `limit` matches, most-recent-first.
+ */
+export function searchHistory(query, limit = 50) {
+    if (!query)
+        return [];
+    const q = query.toLowerCase();
+    const out = [];
+    const cur = $history.get();
+    for (let i = cur.length - 1; i >= 0 && out.length < limit; i--) {
+        if (cur[i].toLowerCase().includes(q))
+            out.push(cur[i]);
+    }
+    return out;
+}
+/** Move history cursor toward older entries; returns the entry text or null. */
+export function historyPrev(currentDraft) {
+    const h = $history.get();
+    if (h.length === 0)
+        return null;
+    let idx = $historyCursor.get();
+    if (idx === null) {
+        $historyDraft.set(currentDraft);
+        idx = h.length - 1;
+    }
+    else if (idx > 0) {
+        idx -= 1;
+    }
+    $historyCursor.set(idx);
+    return h[idx];
+}
+/** Move history cursor toward newer entries; returns the entry text or null on fall-through. */
+export function historyNext() {
+    const h = $history.get();
+    const idx = $historyCursor.get();
+    if (idx === null)
+        return null;
+    if (idx >= h.length - 1) {
+        // Fell off the end: restore draft.
+        $historyCursor.set(null);
+        return $historyDraft.get();
+    }
+    const next = idx + 1;
+    $historyCursor.set(next);
+    return h[next];
+}
+export function resetHistoryBrowse() {
+    $historyCursor.set(null);
+    $historyDraft.set('');
+}

package/dist/app/inputBuffer.js

@@ -0,0 +1,116 @@
+// Pure text-buffer helpers for the multi-line composer.
+// Kept side-effect-free so they can be unit-tested without Ink/React.
+export function emptyBuffer() {
+    return { text: '', cursor: 0 };
+}
+export function insert(buf, s) {
+    const text = buf.text.slice(0, buf.cursor) + s + buf.text.slice(buf.cursor);
+    return { text, cursor: buf.cursor + s.length };
+}
+export function backspace(buf) {
+    if (buf.cursor === 0)
+        return buf;
+    const text = buf.text.slice(0, buf.cursor - 1) + buf.text.slice(buf.cursor);
+    return { text, cursor: buf.cursor - 1 };
+}
+export function del(buf) {
+    if (buf.cursor >= buf.text.length)
+        return buf;
+    const text = buf.text.slice(0, buf.cursor) + buf.text.slice(buf.cursor + 1);
+    return { text, cursor: buf.cursor };
+}
+export function moveLeft(buf) {
+    return { ...buf, cursor: Math.max(0, buf.cursor - 1) };
+}
+export function moveRight(buf) {
+    return { ...buf, cursor: Math.min(buf.text.length, buf.cursor + 1) };
+}
+export function moveHome(buf) {
+    // Move to start of current logical line.
+    const before = buf.text.slice(0, buf.cursor);
+    const nl = before.lastIndexOf('\n');
+    return { ...buf, cursor: nl < 0 ? 0 : nl + 1 };
+}
+export function moveEnd(buf) {
+    const after = buf.text.slice(buf.cursor);
+    const nl = after.indexOf('\n');
+    return { ...buf, cursor: nl < 0 ? buf.text.length : buf.cursor + nl };
+}
+/** Lines split on \n (keeps empty trailing line). */
+export function lines(text) {
+    return text.split('\n');
+}
+/** Convert cursor offset to {row, col} on logical lines. */
+export function cursorRowCol(buf) {
+    const before = buf.text.slice(0, buf.cursor);
+    const ls = before.split('\n');
+    return { row: ls.length - 1, col: ls[ls.length - 1].length };
+}
+/** Move cursor up one logical line, preserving column when possible. */
+export function moveUp(buf) {
+    const { row, col } = cursorRowCol(buf);
+    if (row === 0)
+        return buf;
+    const ls = lines(buf.text);
+    const targetCol = Math.min(col, ls[row - 1].length);
+    // Compute new offset: sum of lines 0..row-2 + their newlines + targetCol.
+    let off = 0;
+    for (let i = 0; i < row - 1; i++)
+        off += ls[i].length + 1;
+    off += targetCol;
+    return { ...buf, cursor: off };
+}
+export function moveDown(buf) {
+    const { row, col } = cursorRowCol(buf);
+    const ls = lines(buf.text);
+    if (row >= ls.length - 1)
+        return buf;
+    const targetCol = Math.min(col, ls[row + 1].length);
+    let off = 0;
+    for (let i = 0; i < row + 1; i++)
+        off += ls[i].length + 1;
+    off += targetCol;
+    return { ...buf, cursor: off };
+}
+/** True when the cursor is on the first logical line. */
+export function onFirstLine(buf) {
+    return cursorRowCol(buf).row === 0;
+}
+/** True when the cursor is on the last logical line. */
+export function onLastLine(buf) {
+    return cursorRowCol(buf).row === lines(buf.text).length - 1;
+}
+/**
+ * Word-wrap a logical line into visual rows of width `cols`.
+ * Returns array of strings (each ≤ cols chars). Tries to break at spaces.
+ */
+export function wrapLine(line, cols) {
+    if (cols <= 0)
+        return [line];
+    if (line.length <= cols)
+        return [line];
+    const out = [];
+    let rest = line;
+    while (rest.length > cols) {
+        let cut = cols;
+        // Look for a space to break at, within a small window.
+        const window = rest.slice(0, cols);
+        const lastSpace = window.lastIndexOf(' ');
+        if (lastSpace > Math.floor(cols * 0.5)) {
+            cut = lastSpace + 1;
+        }
+        out.push(rest.slice(0, cut));
+        rest = rest.slice(cut);
+    }
+    if (rest.length)
+        out.push(rest);
+    return out;
+}
+/** Wrap the full text, returning visual rows. */
+export function wrapText(text, cols) {
+    return text.split('\n').flatMap((l) => (l.length === 0 ? [''] : wrapLine(l, cols)));
+}
+/** Stats for the dim status footer. */
+export function bufferStats(text) {
+    return { chars: text.length, lineCount: text.split('\n').length };
+}

package/dist/app/inputStore.js

@@ -0,0 +1,24 @@
+// Composer state — kept in a nanostore so any subsystem can read/write
+// without prop-drilling. Holds the active text buffer + completion state.
+import { atom } from 'nanostores';
+import { emptyBuffer } from './inputBuffer.js';
+export const $buffer = atom(emptyBuffer());
+export const $completion = atom({
+    active: false,
+    prefix: '',
+    candidates: [],
+    index: 0,
+    start: 0,
+});
+export function resetCompletion() {
+    $completion.set({ active: false, prefix: '', candidates: [], index: 0, start: 0 });
+}
+export function setBuffer(b) {
+    $buffer.set(b);
+    // Any non-Tab edit should reset the completion cycle.
+    resetCompletion();
+}
+/** Direct setter that does not reset completion (used by the cycle itself). */
+export function setBufferRaw(b) {
+    $buffer.set(b);
+}

package/dist/app/promptStore.js

@@ -0,0 +1,40 @@
+// Prompt store — confirmation + secret prompts requested by any subsystem.
+// The composer hides while a prompt is active; the prompt overlay owns input.
+import { atom } from 'nanostores';
+export const $prompt = atom(null);
+let counter = 0;
+function nextId() {
+    counter += 1;
+    return `prompt_${Date.now()}_${counter}`;
+}
+/** Request a yes/no confirmation. Resolves with `true`/`false`, or `null` on Esc. */
+export function requestConfirm(prompt, opts = {}) {
+    return new Promise((resolve) => {
+        $prompt.set({
+            id: nextId(),
+            kind: 'confirm',
+            prompt,
+            destructive: opts.destructive,
+            resolve: (v) => resolve(v),
+        });
+    });
+}
+/** Request a secret. Resolves with the entered string, or `null` on Esc. */
+export function requestSecret(prompt, opts = {}) {
+    return new Promise((resolve) => {
+        $prompt.set({
+            id: nextId(),
+            kind: 'secret',
+            prompt,
+            mask: opts.mask !== false,
+            resolve: (v) => resolve(v),
+        });
+    });
+}
+export function resolveActivePrompt(value) {
+    const cur = $prompt.get();
+    if (!cur)
+        return;
+    cur.resolve(value);
+    $prompt.set(null);
+}

package/dist/app/queueStore.js

@@ -0,0 +1,21 @@
+// Queue store — submissions made while a turn is streaming are queued
+// and flushed when the active turn ends. Composer shows `[queued: N]`.
+import { atom } from 'nanostores';
+export const $queue = atom([]);
+export function enqueue(text) {
+    const t = text.replace(/\s+$/g, '');
+    if (!t)
+        return;
+    $queue.set([...$queue.get(), t]);
+}
+export function dequeueAll() {
+    const cur = $queue.get();
+    $queue.set([]);
+    return cur;
+}
+export function queueLength() {
+    return $queue.get().length;
+}
+export function clearQueue() {
+    $queue.set([]);
+}