@opencoven/coven-code 0.0.1

package/docs/superpowers/specs/2026-05-25-coven-code-panel-tui-design.md

@@ -0,0 +1,235 @@
+# Coven Code Panel TUI Design
+
+Date: 2026-05-25
+Status: Approved for implementation planning
+Project: `OpenCoven/coven-code`
+
+## Summary
+
+Bare `coven-code` should open a full-screen terminal UI instead of the current plain readline prompt. The TUI should make Coven Code feel like a real interactive coding surface while preserving the existing command engine, noninteractive modes, and slash-command behavior.
+
+The selected direction is a panel-based TUI:
+
+- Chat transcript as the main pane
+- Composer at the bottom
+- Status and shortcuts rail on the side
+- Tabs for chat, tools, threads, config, and help
+- Command palette for discoverable actions
+
+## Goals
+
+- Make interactive `coven-code` feel intentional, keyboard-first, and product-grade.
+- Preserve current CLI compatibility for scripts, tests, and docs.
+- Reuse existing command handlers rather than rewriting tool, thread, config, and skill behavior.
+- Keep the first implementation focused on a strong single-session experience, not a multi-session orchestration cockpit.
+- Leave clear seams for later streaming, tool event inspection, approval prompts, and multi-session control.
+
+## Non-Goals
+
+- Do not change `coven-code -x`, `--execute`, `--stream-json`, `--stream-json-input`, stdin piping, or command subcommands.
+- Do not build the full multi-session control console in this pass.
+- Do not introduce remote service dependencies.
+- Do not replace the local deterministic runtime.
+- Do not add decorative UI elements that do not improve operation or comprehension.
+
+## Current State
+
+The current interactive mode lives in `src/cli/repl.mjs` and uses Node's `readline/promises`.
+
+It already supports:
+
+- Plain prompt turns through `runInteractiveTurn`
+- Slash commands
+- `/mode`
+- `/reasoning`
+- `/queue`
+- `/new`
+- `/continue`
+- `/editor`
+- `/edit`
+- Thread archive and visibility commands
+- Skill and plugin command aliases
+- REPL history
+
+The TUI should keep those behaviors and adapt presentation/input handling around them.
+
+## Proposed Architecture
+
+Add a new TUI layer, likely `src/cli/tui.mjs`, that owns terminal rendering and keyboard interaction. It should call shared REPL/session operations instead of duplicating command logic.
+
+Recommended structure:
+
+- `src/cli/interactive-core.mjs`
+  - Shared state transitions and command execution currently embedded in `repl.mjs`
+  - Handles turns, slash commands, queue draining, mode/reasoning updates, and thread selection
+- `src/cli/repl.mjs`
+  - Keeps readline behavior as a fallback and for simple terminal environments
+  - Delegates shared behavior to `interactive-core.mjs`
+- `src/cli/tui.mjs`
+  - Full-screen TUI renderer
+  - Owns layout, focus, keybindings, palette, transcript rendering, status rail, and composer behavior
+- `src/main.mjs`
+  - Routes bare TTY interactive sessions to the TUI by default
+  - Preserves existing execute and command routing
+
+The TUI library should be small and terminal-focused. `blessed` is acceptable if it works cleanly with ESM and Node 20. If it creates friction, use a similarly small maintained package rather than hand-rolling terminal control.
+
+## Default Routing
+
+Interactive routing should become:
+
+- If `parsed.execute` is true: use `runExecute`
+- If stdin is piped and stdout is not a TTY: use `runExecute`
+- If a command is provided: use `runCommand`
+- If stdin/stdout are TTYs: use `runTuiInteractive`
+- If TUI initialization fails or `NO_COLOR`/minimal terminal constraints make full-screen mode unsuitable: fall back to `runInteractive`
+
+Add an escape hatch:
+
+- `COVEN_CODE_REPL=1 coven-code` starts the existing readline REPL
+
+This keeps the new UI default while preserving a debugging path.
+
+## TUI Layout
+
+The first implementation should have one primary screen with these areas:
+
+### Header
+
+Shows:
+
+- Product name and version
+- Mode
+- Reasoning effort
+- Runtime label
+- Current thread status
+
+### Tabs
+
+Tabs are visual/focus regions, not separate command modes:
+
+- `chat`: transcript and composer
+- `tools`: available tools summary
+- `threads`: active/latest thread controls
+- `config`: current relevant settings
+- `help`: keybindings and slash commands
+
+### Transcript
+
+Shows user prompts, assistant responses, command output, and errors in a scrollable main pane.
+
+Transcript entries should distinguish:
+
+- User messages
+- Assistant messages
+- Slash command results
+- Tool or command output
+- Errors
+
+### Status Rail
+
+Shows compact operational state:
+
+- Thread id or "new thread"
+- Mode
+- Reasoning effort
+- Queue count
+- Tool count
+- Config path or profile summary when useful
+
+### Composer
+
+Supports:
+
+- Single-line prompt entry
+- Multi-line entry when users insert newline intentionally
+- Slash commands
+- Submitting queued prompts after the current turn
+- Clear status while a turn is running
+
+## Keybindings
+
+Minimum keybindings:
+
+- `Enter`: submit composer
+- `Shift-Enter` or `Alt-Enter`: insert newline if supported by the library/terminal
+- `Tab`: cycle tabs or focus regions
+- `Ctrl-P`: open command palette
+- `Ctrl-N`: new thread
+- `Ctrl-R`: cycle reasoning effort
+- `Ctrl-M`: cycle mode
+- `Ctrl-E`: open editor flow
+- `Esc`: close palette or overlay
+- `Ctrl-C`: graceful quit confirmation or immediate quit when idle
+
+Slash commands remain available and should behave consistently with the old REPL.
+
+## Command Palette
+
+The command palette should expose common actions without forcing users to memorize slash commands:
+
+- New thread
+- Continue latest thread
+- Open editor
+- Edit previous prompt
+- Toggle/cycle mode
+- Toggle/cycle reasoning effort
+- List tools
+- List skills
+- List plugins
+- Open help
+- Archive thread and quit
+
+Palette commands should call the same shared command handlers used by slash commands.
+
+## Error Handling
+
+- Slash command errors should render in the transcript and keep the TUI alive.
+- TUI initialization failure should fall back to readline with a concise warning.
+- Terminal resize should redraw without losing transcript or composer contents.
+- Command execution exceptions should preserve the current thread state when possible.
+- Editor flow cancellation should return to the composer without submitting an empty prompt.
+
+## Accessibility and Terminal Constraints
+
+- Avoid emoji and decorative glyphs in the UI.
+- Use text labels and simple ASCII-safe separators by default.
+- Do not rely on color alone; labels must carry meaning.
+- Keep all text readable on narrow terminals by truncating low-priority status fields before prompt or transcript text.
+- Respect `NO_COLOR` by using plain styling if the selected library supports it.
+
+## Testing Strategy
+
+Use test-first implementation.
+
+Required tests:
+
+- Bare TTY routing chooses the TUI path.
+- `COVEN_CODE_REPL=1` chooses the readline REPL path.
+- Execute mode still prints `4` for `what is 2+2?`.
+- `--stream-json` behavior is unchanged.
+- Command subcommands still dispatch before interactive routing.
+- Shared interactive command handling preserves `/mode`, `/reasoning`, `/queue`, `/new`, and `/continue` behavior.
+- TUI command palette actions call the same underlying handlers as slash commands.
+
+If the selected TUI library supports stable rendering in tests, add a lightweight layout smoke test. If not, test the TUI controller/state model instead of brittle terminal screenshots.
+
+## Documentation Updates
+
+Update:
+
+- `README.md` interactive usage section
+- `docs/CLI.md`
+- `docs/DEVELOPMENT.md` if new test or TUI development instructions are needed
+
+Docs should mention:
+
+- Bare `coven-code` opens the TUI
+- `COVEN_CODE_REPL=1 coven-code` starts the classic readline REPL
+- Noninteractive command behavior is unchanged
+
+## Implementation Plan Entry Point
+
+The implementation plan should start by extracting shared interactive behavior from `src/cli/repl.mjs` into a testable module. After that, add TTY routing tests, introduce the TUI layer, and only then wire bare `coven-code` to the panel UI.
+
+This avoids building the TUI around duplicated command logic and keeps the old REPL available as a fallback.

package/docs/superpowers/specs/2026-05-26-slash-first-tui-review.md

@@ -0,0 +1,63 @@
+# Slash-First TUI Implementation Review
+
+Date: 2026-05-26
+Project: Coven Code
+Status: Implemented and locally verified
+
+## Bottom Line
+
+This is a strong v1, not the best possible solution in the absolute sense. It is the right conservative solution for this branch because it keeps the existing Node/neo-blessed CLI stack, reuses the shared interactive command engine, preserves Coven-only branding, and adds focused coverage around the new slash-first behavior.
+
+The main things to reconsider are future maintainability and deeper UX polish, not whether the current patch satisfies the requested interaction model.
+
+## What Changed
+
+- Added `src/cli/slash-commands.mjs` as the shared slash catalog source for built-ins, top-level shortcuts, plugin commands, and discovered skills.
+- Extended `src/cli/interactive-core.mjs` so catalog-backed slash commands execute through the existing handler path.
+- Made skill slash entries real: `/<skill>` shows skill details and `/<skill> <prompt>` submits a skill-guided prompt.
+- Reworked `src/cli/tui.mjs` into a chat-first TTY experience with header, transcript, composer, compact status line, slash list, and command details overlay.
+- Added slash menu state for open/close, filtering, selected index, details, completion, acceptance, cursor movement, and multiline composer behavior.
+- Replaced placeholder TUI tab output with real summaries for tools, threads, config, and help.
+- Updated skill discovery to support cwd-specific roots.
+- Normalized early downstream pipe close handling with a SIGPIPE exit path.
+- Adjusted local-agent prompt routing so global guidance containing review language does not override explicit codename/system-prompt tests.
+- Updated README and CLI/development docs for the slash-first TUI behavior and manual smoke flow.
+- Expanded tests for catalog construction, plugin visibility/availability, temp skill roots, TUI slash interaction, details rendering, narrow frames, tab summaries, and interactive-core slash behavior.
+
+## Why This Is A Good Solution
+
+- It matches the requested slash-first interaction model without copying outside branding.
+- It avoids a runtime stack rewrite and honors the plan's no-new-dependency assumption.
+- It centralizes slash command metadata so TUI and REPL help do not drift.
+- It keeps command execution behind the existing shared interactive handler instead of creating a parallel command runner.
+- It makes plugin and skill entries discoverable while respecting hidden and disabled command behavior.
+- It is covered by both deterministic tests and a real manual TTY smoke path.
+
+## Where To Reconsider
+
+- `src/cli/tui.mjs` is now large and mixes model state, rendering, blessed wiring, summaries, and execution glue. If more TUI work lands, split it into model/controller/render/live-adapter modules.
+- The dynamic slash catalog is rebuilt at launch and through the interactive-core safety path. That is fine now, but plugin-heavy setups may want explicit caching and invalidation.
+- Skill execution currently injects skill guidance into the prompt. That is real and useful, but a future structured skill invocation contract could be more efficient and easier to reason about.
+- Disabled plugin commands are visible and blocked, but the live UI could make disabled availability clearer with stronger styling and status text.
+- Very small PTYs need more graceful fallback behavior. The manual smoke had to set rows and columns because expect defaults to a tiny pseudo-terminal.
+- Long `/help` or detail output can push useful transcript context out of view. A future scroll/collapse affordance would improve dense command discovery.
+- The current render tests are text-based and stable, but they do not replace periodic manual visual smoke tests for terminal layout drift.
+- If Coven wants the richest possible terminal UX later, it may be worth evaluating Ink/react-blessed or a custom renderer. That should be a separate decision, because the current neo-blessed path is intentionally conservative.
+
+## Verification Completed
+
+- `git diff --check`
+- `node --check` on touched runtime modules
+- `node ./bin/coven-code.mjs --help`
+- `node ./bin/coven-code.mjs -x "what is 2+2?"`
+- `npm test -- --test-name-pattern "tui|slash|interactive core"`
+- `npm test`
+- Manual TTY smoke for `/`, `/mo`, arrows, Enter, Esc, `/help`, and `/exit`
+
+## Recommended Follow-Ups
+
+1. Keep this implementation as the v1 unless real user testing exposes a workflow miss.
+2. Split TUI internals before adding another major interactive surface.
+3. Add catalog caching only if plugin or skill discovery becomes measurably slow.
+4. Design a structured skill invocation contract before expanding skill slash behavior further.
+5. Add a tiny-terminal fallback and a lightweight visual smoke checklist for future TUI changes.

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@opencoven/coven-code",
+  "version": "0.0.1",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OpenCoven/coven-code.git"
+  },
+  "exports": {
+    ".": "./src/sdk.mjs"
+  },
+  "bin": {
+    "coven-code": "./bin/coven-code.mjs",
+    "coven-code-sdk": "./bin/coven-code-sdk.mjs"
+  },
+  "files": [
+    "bin/",
+    "docs/",
+    "src/",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test 'test/*.test.mjs'",
+    "start": "node ./bin/coven-code.mjs",
+    "coven-code": "node ./bin/coven-code.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "neo-blessed": "0.2.0"
+  }
+}

package/src/agent/lane.mjs

@@ -0,0 +1,136 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+export const LANE_HARNESSES = ['smart', 'deep', 'rush', 'large'];
+
+export function defaultLaneState(options = {}) {
+  return {
+    worktree: options.worktree ?? process.cwd(),
+    branch: options.branch ?? 'unknown',
+    baseBranch: options.baseBranch ?? 'main',
+    harness: normalizeLaneHarness(options.harness),
+    status: options.status ?? 'unknown',
+    changedFiles: options.changedFiles ?? [],
+    diffSummary: options.diffSummary ?? '',
+    verification: {
+      command: options.verification?.command ?? verificationCommandFor(options.worktree ?? process.cwd()),
+      status: options.verification?.status ?? 'not run',
+    },
+    terminalLines: options.terminalLines ?? [],
+    pullRequest: options.pullRequest ?? 'not opened',
+    merge: options.merge ?? 'not merged',
+    cleanup: options.cleanup ?? 'pending',
+  };
+}
+
+export async function inspectLane(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const runner = options.gitRunner ?? runGit;
+  const root = gitText(runner, cwd, ['rev-parse', '--show-toplevel']) || cwd;
+  const branch = gitText(runner, root, ['branch', '--show-current'])
+    || detachedBranchLabel(runner, root)
+    || 'unknown';
+  const baseBranch = gitText(runner, root, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'])
+    || options.baseBranch
+    || 'main';
+  const statusResult = runner(root, ['status', '--short']);
+  const statusLines = splitLines(statusResult.stdout);
+  const changedFiles = statusLines.map(statusFileName).filter(Boolean);
+  const diffSummary = gitText(runner, root, ['diff', '--stat', '--', '.']);
+  const unavailable = !gitText(runner, cwd, ['rev-parse', '--git-dir']);
+
+  return defaultLaneState({
+    ...options,
+    worktree: root,
+    branch,
+    baseBranch,
+    status: unavailable ? 'unavailable' : changedFiles.length > 0 ? 'dirty' : 'ready',
+    changedFiles,
+    diffSummary,
+    verification: {
+      command: verificationCommandFor(root),
+      status: options.verification?.status ?? 'not run',
+    },
+    terminalLines: [
+      '$ git status --short',
+      ...(statusLines.length > 0 ? statusLines : ['clean']),
+    ],
+  });
+}
+
+export async function runLaneVerification(lane, options = {}) {
+  const cwd = lane.worktree ?? process.cwd();
+  const command = lane.verification?.command ?? verificationCommandFor(cwd);
+  const runner = options.runner ?? runShell;
+  const result = runner(command, cwd);
+  return {
+    ...lane,
+    verification: {
+      command,
+      status: result.status === 0 ? 'passed' : 'failed',
+    },
+    terminalLines: [
+      ...(lane.terminalLines ?? []).slice(-20),
+      `$ ${command}`,
+      ...splitLines(result.stdout),
+      ...splitLines(result.stderr),
+      `exit: ${result.status}`,
+    ].slice(-40),
+  };
+}
+
+export function normalizeLaneHarness(value) {
+  return LANE_HARNESSES.includes(value) ? value : 'smart';
+}
+
+export function nextLaneHarness(current) {
+  const index = LANE_HARNESSES.indexOf(normalizeLaneHarness(current));
+  return LANE_HARNESSES[(index + 1) % LANE_HARNESSES.length];
+}
+
+function verificationCommandFor(cwd) {
+  if (existsSync(path.join(cwd, 'package.json'))) return 'npm test';
+  if (existsSync(path.join(cwd, 'Cargo.toml'))) return 'cargo test';
+  return 'git diff --check';
+}
+
+function runGit(cwd, args) {
+  const result = spawnSync('git', args, { cwd, encoding: 'utf8' });
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+function runShell(command, cwd) {
+  const result = spawnSync(command, { cwd, encoding: 'utf8', shell: true });
+  return {
+    status: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+function gitText(runner, cwd, args) {
+  const result = runner(cwd, args);
+  if (result.status !== 0) return '';
+  return result.stdout.trim();
+}
+
+function detachedBranchLabel(runner, cwd) {
+  const sha = gitText(runner, cwd, ['rev-parse', '--short', 'HEAD']);
+  return sha ? `detached:${sha}` : '';
+}
+
+function statusFileName(line) {
+  const file = line.slice(3).trim();
+  if (!file) return '';
+  const rename = file.split(' -> ');
+  return rename.at(-1) ?? file;
+}
+
+function splitLines(text = '') {
+  return String(text).split(/\r?\n/).filter(Boolean);
+}

package/src/agent/local.mjs

@@ -0,0 +1,95 @@
+import { existsSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+
+export function localAgentResponse(prompt, stdin) {
+  const text = prompt.trim();
+  const lower = text.toLowerCase();
+
+  if (lower.includes('now add') && lower.includes('to that')) {
+    const addend = Number([...lower.matchAll(/now add\s+(\d+)\s+to that/g)].at(-1)?.[1] ?? 0);
+    const prior = Number([...text.matchAll(/^assistant:\s*(\d+)\s*$/gim)].at(-1)?.[1] ?? 0);
+    if (addend && prior) return String(prior + addend);
+  }
+  if (/\b2\s*\+\s*2\b/.test(lower)) return '4';
+  if (lower.includes('markdown') && lower.includes('filename')) {
+    return readdirSync(process.cwd())
+      .filter((entry) => entry.toLowerCase().endsWith('.md'))
+      .sort((a, b) => a.localeCompare(b))
+      .join('\n');
+  }
+  if (lower.includes('colorscheme')) {
+    const match = text.match(/^\s*colorscheme\s+([^\s#]+)/mi);
+    return match ? `The colorscheme used is ${match[1]}.` : 'No colorscheme declaration found.';
+  }
+  if (lower.includes('package manager')) {
+    return detectPackageManager();
+  }
+  if (lower.includes('what did the shell command output')) {
+    return extractShellOutput(text) || 'No shell output is available from the captured context.';
+  }
+  if (lower.includes('image') && lower.includes('[image:')) {
+    const match = text.match(/\[image:([^\]\r\n]+)\]\nmedia_type:\s*([^\r\n]+)\nbytes:\s*(\d+)/);
+    if (match) return `${path.basename(match[1])} ${match[2]} ${match[3]} bytes`;
+    return 'No image was found.';
+  }
+  if (lower.includes('codename') && lower.includes('[thread:')) {
+    const match = text.match(/codename is ([a-z0-9_-]+)/i);
+    return match ? match[1] : 'No codename was found in the referenced thread.';
+  }
+  if (lower.includes('codename') && lower.includes('[file:')) {
+    const matches = [...text.matchAll(/codename:\s*([a-z0-9_-]+)/gi)].map((m) => m[1]);
+    if (lower.includes('codenames') && matches.length > 0) return matches.join('\n');
+    return matches[0] || 'No codename was found in the referenced file.';
+  }
+  if (lower.includes('codename')) {
+    const match = text.match(/codename:\s*([a-z0-9_-]+)/i);
+    if (match) return match[1];
+  }
+  if (lower.includes('codename')) {
+    return 'No codename was found.';
+  }
+  if (lower.includes('review')) {
+    return 'No automated review findings in the local deterministic recreation.';
+  }
+  if (stdin.trim()) {
+    return `Received ${stdin.trim().split(/\s+/).length} input words and prompt: ${parsedSummary(text)}`;
+  }
+  return `Coven Code local runtime received: ${parsedSummary(text)}`;
+}
+
+export function detectPackageManager() {
+  const checks = [
+    ['pnpm-lock.yaml', 'pnpm'],
+    ['bun.lockb', 'bun'],
+    ['bun.lock', 'bun'],
+    ['yarn.lock', 'yarn'],
+    ['package-lock.json', 'npm'],
+    ['Cargo.lock', 'cargo'],
+  ];
+  for (const [file, manager] of checks) {
+    if (existsSync(path.join(process.cwd(), file))) return manager;
+  }
+  return 'unknown';
+}
+
+export function extractShellOutput(text) {
+  const match = text.match(/\[shell\]\n\$ .+\n([\s\S]*?)(?:\n[^\n]*\?|$)/);
+  return match?.[1]?.trim() ?? '';
+}
+
+export function parsedSummary(text) {
+  return text.length > 160 ? `${text.slice(0, 157)}...` : text || '(empty message)';
+}
+
+export function estimateUsage(input, output) {
+  return {
+    input_tokens: estimateTokenCount(input),
+    output_tokens: estimateTokenCount(output),
+    max_tokens: 968000,
+    service_tier: 'local-recreation',
+  };
+}
+
+export function estimateTokenCount(text) {
+  return Math.max(1, Math.ceil(String(text).length / 4));
+}

package/src/cli/dispatch.mjs

@@ -0,0 +1,66 @@
+import { printHelp } from './help.mjs';
+import { UsageError } from './parse.mjs';
+import { runLogin } from '../commands/login.mjs';
+import { runUpdate } from '../commands/update.mjs';
+import { runReview } from '../commands/review.mjs';
+import { runUsage } from '../commands/usage.mjs';
+import { runTools } from '../commands/tools.mjs';
+import { runPermissions } from '../commands/permissions.mjs';
+import { runConfig } from '../commands/config.mjs';
+import { runAgents } from '../commands/agents.mjs';
+import { runPlugins } from '../commands/plugins.mjs';
+import { runMcp } from '../commands/mcp.mjs';
+import { runSkill } from '../commands/skill.mjs';
+import { runThreads } from '../commands/threads.mjs';
+import { runIde } from '../commands/ide.mjs';
+
+export async function runCommand(command, args, parsed, stdin) {
+  switch (command) {
+    case 'help':
+      printHelp();
+      break;
+    case 'login':
+      await runLogin(args);
+      break;
+    case 'update':
+      runUpdate(parsed);
+      break;
+    case 'review':
+      runReview();
+      break;
+    case 'usage':
+      runUsage(parsed);
+      break;
+    case 'tools':
+      await runTools(args, stdin, parsed);
+      break;
+    case 'permissions':
+      await runPermissions(args, stdin, parsed);
+      break;
+    case 'config':
+      await runConfig(args, parsed);
+      break;
+    case 'agents':
+    case 'agents-md':
+      await runAgents(args);
+      break;
+    case 'plugins':
+      await runPlugins(args);
+      break;
+    case 'mcp':
+      await runMcp(args, parsed);
+      break;
+    case 'skill':
+      await runSkill(args, parsed);
+      break;
+    case 'threads':
+      await runThreads(args, parsed, stdin);
+      break;
+    case 'ide':
+      runIde(args);
+      break;
+    default:
+      if (parsed.help) printHelp();
+      else throw new UsageError(`Unknown command: ${command}`);
+  }
+}