Skip to content

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

16.3 KB
Raw Blame
/**
 * What `trail init` shows (design 4.7, 4.8): the review screen's lines, the
 * relay an agent or a script gets, and the lines after a keep. Pure: no
 * file, no clock, no terminal. The keys are review-tty.ts's; what is kept
 * is keep.ts's.
 *
 * Words are 4.7's. The relay keeps phase 0's RELAY_LINE and KEEP_LINE word
 * for word (the keep gate finds the list by them) and, for an agent, opens
 * with who it is from and why, and ends saying Trail checks the person's
 * typed numbers (D101): it never tells the agent to choose.
 */
import { flatLine } from '../notes/flatten.js';
import { directive } from '../skills/directive-words.js';
import { WALLS } from '../trace/walls.js';
import type { ClaudeFailure } from './claude-call.js';
import type { KeepResult } from './keep.js';
import { nameLine } from './name-call.js';
import { DRAFT_LINE, KEEP_LINE, RELAY_LINE } from './relay.js';
import type { InitItem, InitKind, LookBack } from './types.js';
import { onlyRepeats } from '../skills/follow-learnings.js';

export interface ScreenFacts {
  lookBack: LookBack;
  model: string | 'none';
  why: ClaudeFailure | null;
  tokens: number;
  calls: number;
  offers: 'on' | 'off';
  offersOffAt: string | null;
  repoName: string;
  agent: boolean;
  skills: boolean;
  /** How many skills the naming call was sent (its screen line). */
  sentSkills?: number;
  /** Claude Code's own words when the naming call failed. */
  whySaid?: string;
  /** How many PR reviews the review read went through, when it ran (the twice-asked line). */
  reviewsRead?: number;
  /** false when no look-back ran this init (not due, or off) and the screen holds only #662's team rows. */
  lookedBack?: boolean;
}

export const INIT_COPY: Record<string, string> = {
  found: '✓ looked back at {n} Claude Code sessions about this repo, typed into on {d} days ({from} to {to})',
  foundNone: '· no past Claude Code sessions about this repo on this machine yet',
  parent: ' · {p} started in the parent folder',
  plainNames: ' · names are plain: to name them with Claude, run trail init --look-back in your own terminal',
  alreadyKept: '· {a} already kept {where} (they apply here too)',
  nothing: "· nothing came up on two or more days, so there's nothing to keep from your past sessions yet",
  skills: 'Skills',
  guardrails: 'Guardrails',
  preferences: 'Preferences',
  reviews: 'From PR reviews',
  team: "Your teammates' Claude doesn't know these yet",
  keys1: '↑↓ move · space tick · s see the steps · enter keep ticked · n keep nothing',
  keys2: 'w every repo or this repo · r add a preference to this repo (committed) · esc decide later',
  skillsOff: 'skills are off · trail skills on lets init also find repeated jobs and keep their steps',
  skillCount: 'Claude worked out how to {job} from scratch on {days} different days.',
  guardCount: 'Hit {words} on {days} days.',
  prefCount: 'You said this on {days} days.',
  reviewCount: 'From review on PR {prs}.',
  claudeCount: 'From what your Claude keeps about this repo.',
  personal: 'just for you, in this repo',
  everyRepo: 'just for you, in every repo',
  repo: 'added to this repo, committed',
  reviewRepo: 'added to this repo',
  agentLead: 'trail init found these in the past sessions of the person you are working with. Only they decide what Trail keeps, so the list is theirs to answer.',
  agentKeep: "Trail checks the numbers the person typed in this session before it keeps anything, so run trail keep only with the numbers they typed.",
  pickInTerminal: 'Pick in a terminal: trail init',
  handover: 'trail init found {k} items in this person\'s past sessions that they haven\'t answered yet. Only they decide what Trail keeps.',
  kept: '✓ kept {k}, just for you · in ~/.trail, never committed, never uploaded',
  keptMixed: "✓ kept {k} · {j} just for you in ~/.trail, never uploaded · {r} added to this repo's .trail/learnings (commit it to share)",
  notKept: "Not kept: {names}. Trail won't bring {them} up again.",
  refused: "{name}: its past session changed or is gone, so Trail can't check the steps. It will offer it again after the job checks out.",
  offersOn: 'skills: on · at most one offer per session, only after a job checks out · stop offers: trail skills offers off · all off: trail skills off',
  offersOff: 'skill offers are off (you turned them off on {date}) · trail skills offers on',
  afterEsc: 'kept nothing · they wait until you run trail init again',
  afterN: "kept nothing · Trail won't bring these up again",
  wNoTimeout: 'this Mac has no timeout in any repo, so it stays every repo',
  rLater: 'adding skills and guardrails to the repo comes in a later version',
  yesAgent: 'found {found}. Kept nothing: an agent ran this. The person picks with trail keep <numbers> after seeing the list, or trail init --look-back in their own terminal',
  yesScript: 'found {found}. Kept only the preferences (your own words). To pick the rest: trail init --look-back',
  foldHint: 'kept with skill {n}, it goes into that skill as a lesson, since a step of it already does this',
  folded: '· {pref} went into {skill} as a lesson, since a step of it already does that',
};

/**
 * Part 7: the skill on this screen a preference only repeats a step of (keep.ts folds it in when both are kept), or
 * null. Only a preference just for the person in this repo, as keep.ts folds.
 */
export function foldTarget(item: InitItem, items: InitItem[]): InitItem | null {
  if (item.kind !== 'preference' || item.scope === 'repo' || item.applies === 'every repo' || !item.title) return null;
  return items.find((s) => s.kind === 'skill' && s.skill?.compiled && onlyRepeats(item.title, s.skill.compiled.steps.map((x) => x.cmd))) ?? null;
}

/** `{x}` filled from `v`. */
export function fill(t: string, v: Record<string, string | number>): string {
  return t.replace(/\{(\w+)\}/g, (m, k: string) => (k in v ? String(v[k]) : m));
}

const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
/** 'Jul 3' from '2026-07-03'. */
export function dayWords(day: string | null): string {
  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(day ?? '');
  return m ? `${MONTHS[Number(m[2]) - 1]} ${Number(m[3])}` : '';
}

const plural = (n: number, one: string, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
/** The repo's own name for the job phrases: the last part of its key. */
export const repoNameOf = (repoKey: string) => repoKey.split('/').filter(Boolean).pop() ?? repoKey;

/** A plain branch name: what a ship item's phrase may carry from its check, nothing else of the command. */
export const BRANCH_NAME = /^[\w][\w./-]{0,59}$/;

/** The branches a ship skill's check names (`refs/heads/<b>`), at most 3: the words of its job phrase. */
export function shipBranchesOf(check: string | null | undefined): string[] {
  return [...new Set([...String(check ?? '').matchAll(/refs\/heads\/([\w./-]+)/g)].map((m) => m[1]!))].filter((b) => BRANCH_NAME.test(b)).slice(0, 3);
}

/** 4.7's job phrases. Release reaches init only with an npm-view check (OFFER_FAMILIES), so it publishes to npm. */
export function jobPhrase(item: Pick<InitItem, 'key' | 'skill'>, repoName: string): string {
  const job = item.key.slice(item.key.lastIndexOf('|job:') + 5);
  switch (job) {
    case 'release': return /\bnpm view\b/.test(item.skill?.compiled?.check ?? 'npm view') ? `publish ${repoName} to npm` : `release ${repoName}`;
    case 'ship': {
      // The compiled check's branches; a handed-over item has only the names the relay wrote down (D112).
      const branches = item.skill?.compiled ? shipBranchesOf(item.skill.compiled.check) : (item.skill as { branches?: string[] } | undefined)?.branches ?? [];
      return branches.length ? `ship ${repoName} to ${branches.join(' and ')}` : `ship ${repoName}`;
    }
    case 'tests': return `run ${repoName}'s tests`;
    case 'pr-green': return "get a PR's checks green";
    case 'run-local': return `run ${repoName} locally`;
    default: return `${job} ${repoName}`;
  }
}

/** Where an item goes, in words. */
export function scopeWords(item: Pick<InitItem, 'kind' | 'scope' | 'applies'>): string {
  if (item.kind === 'review' || item.kind === 'claude') return INIT_COPY.reviewRepo!;
  if (item.scope === 'repo') return INIT_COPY.repo!;
  return item.applies === 'every repo' ? INIT_COPY.everyRepo! : INIT_COPY.personal!;
}

/** The count sentence, with its full stop. */
export function countSentence(item: InitItem, repoName: string): string {
  const days = item.count.days;
  switch (item.kind) {
    case 'skill': return fill(INIT_COPY.skillCount!, { job: jobPhrase(item, repoName), days });
    case 'guardrail': return fill(INIT_COPY.guardCount!, { words: WALLS.find((w) => w.cls === item.guardrail?.cls)?.words ?? 'this error', days });
    case 'preference': return fill(INIT_COPY.prefCount!, { days });
    case 'claude': return INIT_COPY.claudeCount!;
    default: {
      // #662's source words: the PRs, three at most.
      const prs = item.review?.prs ?? [];
      return fill(INIT_COPY.reviewCount!, { prs: `${prs.slice(0, 3).map((p) => `#${p}`).join(', ')}${prs.length > 3 ? ` +${prs.length - 3}` : ''}` });
    }
  }
}

/** An item's title or sentence as one plain line (b6 review): no escape, bell or break from a person's line, a review's
 *  model text or a description reaches the terminal or the relay, and nothing over 160 characters. */
const plain = (t: string) => flatLine(t, 160);
/** A draft line as one line with its own spacing kept (the steps' columns): no control or invisible character, at
 *  most 400 characters. */
const spaced = (t: string) => Array.from(String(t ?? '').replace(/\r\n|[\n\r\u000b\u000c\u0085\u2028\u2029]/g, ' ')
  .replace(/[\u0000-\u0008\u000e-\u001f\u007f-\u009f\p{Cf}]/gu, '')).slice(0, 400).join('');
const quoted = (item: InitItem) => (item.kind === 'preference' ? `"${plain(item.title).replace(/"/g, "'")}"` : plain(item.title));
const KIND_ORDER: InitKind[] = ['skill', 'guardrail', 'preference', 'review', 'claude'];
/** The heading over each kind; #662's team rows, from reviews and from what Claude Code keeps (kind 'claude'), share one. */
const GROUP: Record<InitKind, string> = { skill: 'skills', guardrail: 'guardrails', preference: 'preferences', review: 'team', claude: 'team' };

/** Items numbered as the screen and the relay show them: by kind, then in pickFive's order within a kind. */
export function numbered<T extends { kind: InitKind }>(picked: T[]): Array<T & { n: number }> {
  const sorted = [...picked].sort((a, b) => KIND_ORDER.indexOf(a.kind) - KIND_ORDER.indexOf(b.kind));
  return sorted.map((x, i) => ({ ...x, n: i + 1 }));
}

function foundLine(facts: ScreenFacts, plain: boolean): string {
  const lb = facts.lookBack;
  if (!lb.sessions.length) return INIT_COPY.foundNone!;
  let line = fill(INIT_COPY.found!, { n: lb.sessions.length, d: lb.days, from: dayWords(lb.from), to: dayWords(lb.to) });
  if (lb.parent) line += fill(INIT_COPY.parent!, { p: lb.parent });
  if (plain) line += INIT_COPY.plainNames!;
  return line;
}

function headLines(items: InitItem[], facts: ScreenFacts, relay: boolean): string[] {
  const out = facts.lookedBack === false ? [] : [foundLine(facts, relay && items.some((i) => i.kind === 'skill'))];
  if (!relay) {
    const plainNames = items.filter((i) => i.kind === 'skill').map((i) => i.plainName);
    const said = nameLine({ names: {}, model: facts.model, why: facts.why, sentItems: facts.sentSkills ?? 0, tokens: facts.tokens, ...(facts.whySaid ? { said: facts.whySaid } : {}) }, plainNames, facts.reviewsRead ?? 0);
    if (said) out.push(said);
  }
  const kept = facts.lookBack.alreadyKept;
  if (kept.here) out.push(fill(INIT_COPY.alreadyKept!, { a: kept.here, where: 'for every repo' }));
  for (const e of kept.elsewhere) out.push(fill(INIT_COPY.alreadyKept!, { a: e.n, where: `in ${e.repo}` }));
  for (const e of facts.lookBack.errors) out.push(`· ${e}`);
  return out;
}

/** The review screen (4.7): header, the items by kind, the open draft under its item, the keys. */
export function screenLines(items: InitItem[], state: { cursor: number; open: number | null; note?: string; openLines?: string[] }, facts: ScreenFacts): string[] {
  const out = headLines(items, facts, false);
  if (!items.length) {
    out.push(INIT_COPY.nothing!);
    return out;
  }
  out.push('');
  let last: string | null = null;
  items.forEach((item, at) => {
    if (GROUP[item.kind] !== last) {
      last = GROUP[item.kind];
      out.push(INIT_COPY[last]!);
    }
    const cur = at === state.cursor ? '›' : ' ';
    const desc = item.description ? ` · ${plain(item.description)}` : '';
    out.push(`${cur} [${item.ticked ? 'x' : ' '}] ${item.n}  ${quoted(item)}${desc}`);
    const ev = item.evidence.map(plain).map((e) => ` ${e.charAt(0).toUpperCase()}${e.slice(1)}.`).join('');
    const into = foldTarget(item, items);
    const fold = into ? ` · ${fill(INIT_COPY.foldHint!, { n: into.n })}` : '';
    out.push(`         ${countSentence(item, facts.repoName)}${ev} · ${scopeWords(item)}${fold}`);
    if (state.open === at) for (const l of state.openLines ?? []) out.push(`         ${spaced(l)}`);
  });
  out.push('');
  if (state.note) out.push(state.note);
  out.push(INIT_COPY.keys1!, INIT_COPY.keys2!);
  if (!facts.skills) out.push(INIT_COPY.skillsOff!);
  return out;
}

/** One relayed item: `{n}. {title} ({kind}) · {count} · {scope}`. */
export function relayItemLine(item: InitItem, repoName: string): string {
  const kind = item.kind === 'preference' ? 'preference, your own words' : item.kind === 'review' ? 'from PR reviews' : item.kind === 'claude' ? 'from what your Claude keeps' : item.kind;
  return `${item.n}. ${quoted(item)} (${kind}) · ${countSentence(item, repoName).replace(/\.$/, '')} · ${scopeWords(item)}`;
}

/**
 * The list between the agent's lead and the keep line, the same for the relay and the handover (3.1 step 10), so a
 * list rebuilt from the record reads as the one printed.
 */
export function relayBlock(items: InitItem[], repoName: string, agent: boolean): string[] {
  const list = items.map((i) => relayItemLine(i, repoName));
  const draft = items.some((i) => i.kind === 'skill') ? [DRAFT_LINE.replace('init-1', `init-${items.find((i) => i.kind === 'skill')!.n}`)] : [];
  if (!agent) return [...list, ...draft, INIT_COPY.pickInTerminal!];
  return [directive(null, INIT_COPY.agentLead!), RELAY_LINE, ...list, ...draft, KEEP_LINE, INIT_COPY.agentKeep!];
}

/** 4.8: the found line, then the list (agent: who it is from, RELAY_LINE, the list, draft, KEEP_LINE; a script: no RELAY_LINE). */
export function relayLines(items: InitItem[], facts: ScreenFacts): string[] {
  const out = headLines(items, facts, true);
  if (!items.length) return [...out, INIT_COPY.nothing!];
  return [...out, ...relayBlock(items, facts.repoName, facts.agent)];
}

const counts = (items: Array<Pick<InitItem, 'kind'>>) => {
  const n = (k: InitKind) => items.filter((i) => i.kind === k).length;
  return `${plural(n('skill'), 'skill')}, ${plural(n('guardrail'), 'guardrail')} and ${plural(n('preference'), 'preference')}`;
};

/** `--yes`'s line (4.9): an agent's keeps nothing; the person's script keeps only their own words. */
export function yesLine(items: Array<Pick<InitItem, 'kind'>>, agent: boolean): string {
  return fill(agent ? INIT_COPY.yesAgent! : INIT_COPY.yesScript!, { found: counts(items) });
}

/** After a keep (4.7 "After"). `how`: the key that ended the screen, or the path that kept. */
export function afterKeepLines(r: KeepResult & { how?: 'enter' | 'n' | 'esc' | 'keep' | 'yes' }, facts: ScreenFacts): string[] {
  const out: string[] = [];
  const kept = r.kept.length;
  if (r.how === 'esc') return [INIT_COPY.afterEsc!];
  if (!kept && !r.refused.length) return [INIT_COPY.afterN!];
  if (kept) {
    const inRepo = r.kept.filter((i) => i.scope === 'repo' || i.kind === 'review' || i.kind === 'claude').length;
    out.push(inRepo ? fill(INIT_COPY.keptMixed!, { k: kept, j: kept - inRepo, r: inRepo }) : fill(INIT_COPY.kept!, { k: kept }));
  }
  for (const x of r.refused) out.push(fill(INIT_COPY.refused!, { name: plain(x.item.title) }));
  for (const f of r.folded ?? []) out.push(fill(INIT_COPY.folded!, { pref: quoted(f.item), skill: plain(f.skill) }));
  if (r.notKept.length) out.push(fill(INIT_COPY.notKept!, { names: r.notKept.map((i) => quoted(i)).join(', '), them: r.notKept.length === 1 ? 'it' : 'them' }));
  if (facts.skills) out.push(facts.offers === 'off' ? fill(INIT_COPY.offersOff!, { date: dayWords(facts.offersOffAt) || 'an earlier day' }) : INIT_COPY.offersOn!);
  return out;
}