Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

7.8 KB
Raw Blame
/**
 * The review screen's keys (design 4.7), in raw mode on the person's own
 * terminal. It never keeps anything itself: it resolves with how the person
 * left it, the numbers ticked, and where each item applies.
 *
 * ↑↓ (or k/j) move · space ticks · s opens the item in place (a skill's
 * draft, a guardrail's text, a preference's lines with their dates, read
 * now and shown, never stored) and esc or s closes it · w flips this repo
 * and every repo (no-timeout stays every repo) · r adds a preference to the
 * repo (anything else: later) · enter keeps the ticked · n keeps nothing ·
 * esc, q and Ctrl-C decide later. A closed stdin is esc.
 */
import { draftText, monthDay } from '../skills/compile-words.js';
import type { CompiledSkill } from '../skills/types.js';
import type { RunSheet } from '../trace/types.js';
import { WALLS } from '../trace/walls.js';
import { lineAt } from '../skills/receipts.js';
import { prefText } from './prefs.js';
import { typedAt } from './replay-runs.js';
import { INIT_COPY, screenLines, type ScreenFacts } from './review-screen.js';
import type { InitItem } from './types.js';

export interface ScreenAnswer {
  how: 'enter' | 'n' | 'esc';
  ticked: number[];
  scopes: Record<number, { applies: string; scope: 'personal' | 'repo' }>;
}

interface State { items: InitItem[]; cursor: number; open: number | null; openLines: string[]; note: string }

/** A skill's draft as 1a shows it, headed for a run from the past. */
export function initDraft(c: CompiledSkill): string[] {
  const sheet = { startedAt: c.source.at, endedAt: c.source.at, checked: true } as unknown as RunSheet;
  const lines = draftText(c, sheet).split('\n');
  return [`${c.name} · copied from a run that worked on ${monthDay(c.source.at)}`, ...lines.slice(1)];
}

/** What `s` shows for an item, read now (the person's lines through their pointers, checked by sha). */
export function detailLines(item: InitItem, env: NodeJS.ProcessEnv): string[] {
  if (item.kind === 'skill' && item.skill) return initDraft({ ...item.skill.compiled, name: item.title || item.skill.compiled.name });
  if (item.kind === 'guardrail') return [WALLS.find((w) => w.cls === item.guardrail?.cls)?.guardrail?.text ?? ''];
  if (item.kind === 'preference') {
    const out: string[] = [];
    for (const ref of item.pref?.refs ?? []) {
      const text = typedAt(ref, env);
      if (!text) continue;
      let day = '';
      try {
        const at = (JSON.parse(lineAt(ref.t, ref.o) ?? 'null') as { timestamp?: unknown } | null)?.timestamp;
        day = typeof at === 'string' ? monthDay(at) : '';
      } catch { /* no date */ }
      out.push(`${day ? `${day}: ` : ''}"${prefText(text).slice(0, 120).replace(/"/g, "'")}"`);
    }
    return out.length ? out : ["Trail couldn't read these lines again just now."];
  }
  return [];
}

/** `quit`: Ctrl-C or q, which always leave; `esc` closes an open draft first. */
type Key = 'up' | 'down' | 'space' | 's' | 'w' | 'r' | 'enter' | 'n' | 'esc' | 'quit' | 'other';

/** The keys in one chunk of input, in order. */
export function keysOf(chunk: string): Key[] {
  const out: Key[] = [];
  for (let i = 0; i < chunk.length; i++) {
    const c = chunk[i]!;
    if (c === '\x1b') {
      if (chunk[i + 1] === '[' || chunk[i + 1] === 'O') {
        const k = chunk[i + 2];
        out.push(k === 'A' ? 'up' : k === 'B' ? 'down' : 'other');
        i += 2;
      } else out.push('esc');
    } else if (c === '\x03' || c === 'q' || c === 'Q') out.push('quit');
    else if (c === '\r' || c === '\n') out.push('enter');
    else if (c === ' ') out.push('space');
    else if (c === 'k') out.push('up');
    else if (c === 'j') out.push('down');
    else if (c === 's' || c === 'S') out.push('s');
    else if (c === 'w' || c === 'W') out.push('w');
    else if (c === 'r' || c === 'R') out.push('r');
    else if (c === 'n' || c === 'N') out.push('n');
    else out.push('other');
  }
  return out;
}

/** One key: the new state, or how the screen ends. */
function press(st: State, key: Key, repoKey: string, env: NodeJS.ProcessEnv): ScreenAnswer['how'] | null {
  const item = st.items[st.cursor];
  st.note = '';
  switch (key) {
    case 'up': st.cursor = Math.max(0, st.cursor - 1); st.open = null; return null;
    case 'down': st.cursor = Math.min(st.items.length - 1, st.cursor + 1); st.open = null; return null;
    case 'space': if (item) item.ticked = !item.ticked; return null;
    case 's':
      if (st.open === st.cursor) st.open = null;
      else if (item) {
        st.open = st.cursor;
        st.openLines = detailLines(item, env);
      }
      return null;
    case 'w':
      if (!item || item.kind === 'review' || item.kind === 'claude') return null;
      if (item.kind === 'guardrail' && item.guardrail?.check === 'no-timeout') {
        st.note = INIT_COPY.wNoTimeout!;
        return null;
      }
      item.applies = item.applies === 'every repo' ? repoKey : 'every repo';
      if (item.applies === 'every repo') item.scope = 'personal';
      return null;
    case 'r':
      if (!item) return null;
      if (item.kind !== 'preference') {
        st.note = INIT_COPY.rLater!;
        return null;
      }
      item.scope = item.scope === 'repo' ? 'personal' : 'repo';
      if (item.scope === 'repo') item.applies = repoKey;
      return null;
    case 'enter': return 'enter';
    case 'n': return 'n';
    case 'esc':
      if (st.open !== null) {
        st.open = null;
        return null;
      }
      return 'esc';
    case 'quit': return 'esc';
    default: return null;
  }
}

/** Raw-mode keys (4.7). Resolves on enter, n, esc, q or Ctrl-C. Never keeps anything itself. */
export function runScreen(items: InitItem[], facts: ScreenFacts, io: { stdin: NodeJS.ReadStream; stdout: NodeJS.WriteStream },
  opts: { repoKey: string; env?: NodeJS.ProcessEnv }): Promise<ScreenAnswer> {
  const env = opts.env ?? process.env;
  const st: State = { items: items.map((i) => ({ ...i })), cursor: 0, open: null, openLines: [], note: '' };
  const { stdin, stdout } = io;
  const draw = () => {
    const lines = screenLines(st.items, { cursor: st.cursor, open: st.open, openLines: st.openLines, note: st.note }, facts);
    stdout.write(`\x1b[2J\x1b[H${lines.join('\n')}\n`);
  };
  const answer = (how: ScreenAnswer['how']): ScreenAnswer => ({
    how,
    ticked: st.items.filter((i) => i.ticked).map((i) => i.n),
    scopes: Object.fromEntries(st.items.map((i) => [i.n, { applies: i.applies, scope: i.scope }])),
  });
  return new Promise((resolve) => {
    const wasRaw = (stdin as { isRaw?: boolean }).isRaw === true;
    let done = false;
    /** Raw mode back as it was, on every way out: a key, a closed or broken stdin, a throw, the process ending. */
    const restore = () => {
      try { stdin.setRawMode?.(wasRaw); } catch { /* not a TTY any more */ }
    };
    const finish = (how: ScreenAnswer['how']) => {
      if (done) return;
      done = true;
      stdin.off('data', onData);
      stdin.off('end', onEnd);
      stdin.off('close', onEnd);
      stdin.off('error', onEnd);
      process.off('exit', restore);
      restore();
      try { stdin.pause(); } catch { /* gone */ }
      resolve(answer(how));
    };
    const onData = (b: Buffer | string) => {
      try {
        for (const k of keysOf(typeof b === 'string' ? b : b.toString('utf8'))) {
          const how = press(st, k, opts.repoKey, env);
          if (how) return finish(how);
        }
        draw();
      } catch {
        // A key that can't be shown never leaves the terminal raw or init waiting: it decides later (b6 review).
        finish('esc');
      }
    };
    const onEnd = () => finish('esc');
    process.on('exit', restore);
    try { stdin.setRawMode?.(true); } catch { /* drawn anyway */ }
    stdin.on('data', onData);
    stdin.on('end', onEnd);
    stdin.on('close', onEnd);
    stdin.on('error', onEnd);
    stdin.resume();
    try {
      draw();
    } catch {
      finish('esc');
    }
  });
}