@agjs/tsforge 0.1.0

package/src/render/ansi.ts

@@ -0,0 +1,289 @@
+import type { IRenderOptions, IStatusInfo } from "./render.types";
+import type { ILoopEvent } from "../loop";
+import type { IChatMessage } from "../inference";
+import { STYLE, paint } from "./style";
+import { box, GLYPH } from "./box";
+import { renderMarkdown, highlightCode } from "./markdown";
+import { StreamingMarkdown } from "./stream-markdown";
+
+/** Split highlighted/plain text into the body-line array a box expects. */
+function bodyLines(text: string): string[] {
+  return text.replace(/\n$/, "").split("\n");
+}
+
+/** A single glyph-prefixed line — the compact form for events with no body. */
+function glyphLine(
+  glyph: string,
+  text: string,
+  accent: string,
+  color: boolean
+): string {
+  return `\n  ${paint(`${glyph} ${text}`, `${accent}${STYLE.bold}`, color)}\n`;
+}
+
+/** Compact token count: 1234 → "1.2k", 14000 → "14k". */
+function humanCount(n: number): string {
+  if (n < 1000) {
+    return String(n);
+  }
+
+  const k = n / 1000;
+
+  return `${k < 10 ? k.toFixed(1) : Math.round(k)}k`;
+}
+
+/** Compact duration: 9000 → "9s", 84000 → "1m24s". */
+function humanDuration(ms: number): string {
+  const total = Math.round(ms / 1000);
+
+  if (total < 60) {
+    return `${total}s`;
+  }
+
+  return `${Math.floor(total / 60)}m${String(total % 60).padStart(2, "0")}s`;
+}
+
+/**
+ * The post-turn status line — model, context-window usage, turns, elapsed, last
+ * outcome, scope — the at-a-glance summary modern CLIs keep on screen. Dim, one
+ * line, printed after a turn settles.
+ */
+export function renderStatus(
+  info: IStatusInfo,
+  opts: IRenderOptions = {}
+): string {
+  const color = opts.color ?? true;
+  const pct =
+    info.contextWindow > 0
+      ? Math.round((info.contextTokens / info.contextWindow) * 100)
+      : 0;
+  const bits = [
+    info.model,
+    `ctx ~${humanCount(info.contextTokens)}/${humanCount(info.contextWindow)} ${pct}%`,
+  ];
+
+  // Only show turn/elapsed once a turn has actually run (skip the "0 turns · 0s"
+  // noise on the very first prompt).
+  if (info.turns > 0) {
+    bits.push(
+      `${info.turns} turn${info.turns === 1 ? "" : "s"}`,
+      humanDuration(info.elapsedMs)
+    );
+  }
+
+  bits.push(info.status, info.scope);
+
+  return `${paint(`  ⎯ ${bits.join(" · ")}`, STYLE.dim, color)}\n`;
+}
+
+/**
+ * Replay one stored conversation message — used to show the prior transcript on
+ * `--continue`. User turns are echoed at the prompt marker, assistant answers
+ * get markdown/code highlighting, tool calls collapse to a one-line summary, and
+ * the system prompt + raw tool output are omitted (context, not conversation).
+ */
+export function renderMessage(
+  message: IChatMessage,
+  opts: IRenderOptions = {}
+): string {
+  const color = opts.color ?? true;
+
+  if (message.role === "system" || message.role === "tool") {
+    return "";
+  }
+
+  if (message.role === "user") {
+    return `\n${paint("›", STYLE.brand + STYLE.bold, color)} ${message.content}\n`;
+  }
+
+  const parts: string[] = [];
+
+  if (message.content.length > 0) {
+    parts.push(renderMarkdown(message.content, color));
+  }
+
+  if (message.toolCalls !== undefined && message.toolCalls.length > 0) {
+    const names = message.toolCalls.map((c) => c.name).join(", ");
+
+    parts.push(paint(`  · used ${names}`, STYLE.dim, color));
+  }
+
+  return parts.length > 0 ? `\n${parts.join("\n")}\n` : "";
+}
+
+function highlightTs(code: string, color: boolean): string {
+  return highlightCode(code, "typescript", color);
+}
+
+function diff(oldString: string, newString: string, color: boolean): string {
+  const minus = oldString
+    .split("\n")
+    .map((l) => paint(`- ${l}`, STYLE.red, color))
+    .join("\n");
+  const plus = newString
+    .split("\n")
+    .map((l) => paint(`+ ${l}`, STYLE.green, color))
+    .join("\n");
+
+  return `${minus}\n${plus}`;
+}
+
+/**
+ * Format a loop event for a terminal (ANSI) or a plain log (`color: false`).
+ * The library emits structured events; this renderer is the only place that
+ * knows about colors/layout — a web UI could render the same events differently.
+ */
+/** Latch so a run of `reasoning` tokens collapses to ONE "thinking…" line
+ *  instead of streaming the model's full chain-of-thought. Reset by any other
+ *  event (a tool marker, gate output, a message), so the next thinking burst
+ *  re-announces. The raw reasoning is still written verbatim to the --log. */
+let thinkingShown = false;
+
+/** Live answer stream — content tokens render incrementally through this; the
+ *  settled `message` event then skips its duplicate full render (sawContent). */
+const stream = new StreamingMarkdown();
+
+/** Render a streamed token. The answer (channel `content`) streams live through
+ *  the incremental markdown renderer; the chain-of-thought (`reasoning`)
+ *  collapses to a compact indicator (on a TTY the CLI spinner owns it); tool
+ *  markers (✎) and gate output print normally. */
+function renderToken(event: ILoopEvent, color: boolean): string {
+  if (event.channel === "reasoning") {
+    // On a live TTY the CLI's animated spinner is the thinking indicator; the
+    // static one-time line is for piped color output and plain logs.
+    if (color && process.stdout.isTTY) {
+      return "";
+    }
+
+    if (thinkingShown) {
+      return "";
+    }
+
+    thinkingShown = true;
+
+    return `\n  ${paint("⋯ thinking", STYLE.dim, color)}`;
+  }
+
+  if (event.channel === "content") {
+    // Plain/log mode stays quiet here — the consolidated `message` event is
+    // the log's record, so agent.log keeps its exact pre-streaming shape.
+    return color ? stream.push(event.message, true) : "";
+  }
+
+  return paint(event.message, STYLE.dim, color);
+}
+
+/** A shell-command event as a box — exit status drives the accent + glyph (a
+ *  non-zero exit goes red ✗); no output → a one-liner. */
+function renderRun(event: ILoopEvent, color: boolean): string {
+  const ok = event.exitCode === undefined || event.exitCode === 0;
+  const title =
+    event.exitCode === undefined
+      ? event.message
+      : `${event.message} (exit ${event.exitCode})`;
+  const accent = ok ? STYLE.yellow : STYLE.red;
+  const glyph = ok ? GLYPH.run : GLYPH.fail;
+
+  if (event.output === undefined || event.output.length === 0) {
+    return glyphLine(glyph, title, accent, color);
+  }
+
+  return `\n${box(title, bodyLines(event.output), { glyph, accent, color })}\n`;
+}
+
+export function renderEvent(
+  event: ILoopEvent,
+  opts: IRenderOptions = {}
+): string {
+  const color = opts.color ?? true;
+
+  // Any event that is NOT a reasoning token ends the current thinking burst.
+  if (event.kind !== "token" || event.channel !== "reasoning") {
+    thinkingShown = false;
+  }
+
+  // Any event that is NOT a content token first flushes the live answer stream
+  // (the closing table/fence, or a partial line on abort) so nothing is lost.
+  const isContentToken = event.kind === "token" && event.channel === "content";
+  const pending = color && !isContentToken ? stream.flush(true) : "";
+
+  return pending + renderEventBody(event, color);
+}
+
+function renderEventBody(event: ILoopEvent, color: boolean): string {
+  switch (event.kind) {
+    case "token":
+      return renderToken(event, color);
+
+    case "message":
+      // The model's actual answer. When it already streamed live (content
+      // tokens), emit just a closing separator — the text is on screen; the
+      // full render here would print it twice. Without streamed content
+      // (non-streaming provider, replayed events, plain logs) render in full.
+      if (color && stream.sawContent) {
+        stream.reset();
+
+        return "\n";
+      }
+
+      return event.message.length > 0
+        ? `\n${renderMarkdown(event.message, color)}\n`
+        : "";
+
+    case "start":
+    case "fix":
+      return `\n${paint(event.message, STYLE.dim, color)}\n`;
+
+    case "cycle":
+      // On screen the turn divider is just noise (the status line carries the
+      // count); keep a minimal boundary only in the plain log for `tail -f`.
+      return color
+        ? ""
+        : `\n── ${event.message.replace(/:?\s*asking model\s*$/i, "")} ──\n`;
+
+    case "create":
+      return event.content === undefined
+        ? glyphLine(GLYPH.create, event.message, STYLE.green, color)
+        : `\n${box(event.message, bodyLines(highlightTs(event.content, color)), { glyph: GLYPH.create, accent: STYLE.green, color })}\n`;
+
+    case "edit": {
+      if (event.oldString === undefined || event.newString === undefined) {
+        return glyphLine(GLYPH.edit, event.message, STYLE.brand, color);
+      }
+
+      const body = bodyLines(diff(event.oldString, event.newString, color));
+
+      return `\n${box(event.message, body, { glyph: GLYPH.edit, accent: STYLE.brand, color })}\n`;
+    }
+
+    case "red":
+    case "stuck":
+      return `\n${paint(`${GLYPH.fail} ${event.message}`, STYLE.red + STYLE.bold, color)}\n`;
+
+    case "validated":
+      return event.passed === true
+        ? `${paint(`  ${GLYPH.done} ${event.message}`, STYLE.green, color)}\n`
+        : `${paint(`  ${GLYPH.bullet} ${event.message}`, STYLE.yellow, color)}\n`;
+
+    case "done":
+      return `\n${paint(`${GLYPH.done} ${event.message}`, STYLE.green + STYLE.bold, color)}\n`;
+
+    case "run":
+      return renderRun(event, color);
+
+    case "usage":
+      // Logged for the metrics analyzer, but not shown — the status line already
+      // surfaces context usage on screen.
+      return "";
+
+    case "tool":
+      return `  ${paint(event.message, STYLE.dim, color)}\n`;
+
+    case "timing":
+      // Noise on screen (the status line shows turns + elapsed); log only.
+      return color ? "" : `  ${event.message}\n`;
+
+    default:
+      return `\n${event.message}\n`;
+  }
+}

package/src/render/banner.ts

@@ -0,0 +1,113 @@
+import { STYLE, paint } from "./style";
+
+/**
+ * Welcome banner for the interactive CLI — solid forge emblem, wordmark,
+ * model/endpoint. Centering uses visible (un-painted) length.
+ */
+export interface IBannerInfo {
+  model: string;
+  endpoint: string;
+  color?: boolean;
+}
+
+/** Chars between the two vertical borders. */
+const INNER = 58;
+
+interface ISegment {
+  text: string;
+  code?: string;
+}
+
+interface ILine {
+  text?: string;
+  code?: string;
+  segments?: readonly ISegment[];
+}
+
+const BLANK: ILine = { text: "" };
+
+/** Compact solid anvil — filled blocks, horn + face + base (~9 cols). */
+const EMBLEM: readonly ILine[] = [
+  { text: "· ✦ ✦ ·", code: STYLE.brandLight },
+  { text: "▄▀▀▀▄", code: STYLE.brandLight + STYLE.bold },
+  { text: "███████", code: STYLE.brand + STYLE.bold },
+  { text: "▀▀▀▀▀▀▀▀▀", code: STYLE.brandDark + STYLE.bold },
+];
+
+/** Split wordmark under the emblem. */
+const WORDMARK: ILine = {
+  segments: [
+    { text: "ts", code: STYLE.brandLight + STYLE.bold },
+    { text: "forge", code: STYLE.brand + STYLE.bold },
+  ],
+};
+
+export function welcomeBanner(info: IBannerInfo): string {
+  const color = info.color ?? true;
+
+  const lines: ILine[] = [
+    BLANK,
+    ...EMBLEM,
+    BLANK,
+    WORDMARK,
+    BLANK,
+    { text: "strict TypeScript, gate-driven", code: STYLE.dim },
+    BLANK,
+    { text: info.model, code: STYLE.brand + STYLE.bold },
+    { text: info.endpoint, code: STYLE.dim },
+    BLANK,
+  ];
+
+  const body = lines.map((line) => boxLine(line, color)).join("\n");
+
+  return `${topBorder(color)}\n${body}\n${bottomBorder()}\n`;
+}
+
+function topBorder(color: boolean): string {
+  const label = "─── tsforge ";
+  const fill = "─".repeat(Math.max(0, INNER - label.length));
+  const frame = `╭${label}${fill}╮`;
+
+  return color
+    ? paint("╭", STYLE.dim, color) +
+        paint(label, STYLE.brandDark, color) +
+        paint(fill + "╮", STYLE.dim, color)
+    : frame;
+}
+
+function bottomBorder(): string {
+  return `╰${"─".repeat(INNER)}╯`;
+}
+
+function visibleText(line: ILine): string {
+  if (line.segments !== undefined) {
+    return line.segments.map((s) => s.text).join("");
+  }
+
+  return line.text ?? "";
+}
+
+function renderContent(line: ILine, color: boolean): string {
+  if (line.segments !== undefined) {
+    return line.segments
+      .map((s) =>
+        s.code === undefined ? s.text : paint(s.text, s.code, color)
+      )
+      .join("");
+  }
+
+  const text = line.text ?? "";
+
+  return line.code === undefined ? text : paint(text, line.code, color);
+}
+
+/** Center `line` within INNER and frame it with the vertical borders. */
+function boxLine(line: ILine, color: boolean): string {
+  const visible = visibleText(line);
+  const pad = Math.max(0, INNER - visible.length);
+  const left = Math.floor(pad / 2);
+  const right = pad - left;
+  const content = renderContent(line, color);
+
+  return `│${" ".repeat(left)}${content}${" ".repeat(right)}│`;
+}

package/src/render/box.ts

@@ -0,0 +1,134 @@
+import { STYLE, paint } from "./style";
+
+/**
+ * Terminal drawing primitives — title-tabbed boxes and box-drawn tables, the look
+ * a modern coding CLI uses to make tool output legible. Pure string→string (no
+ * cursor control, no streaming, no readline interaction), so they render discrete
+ * events ONLY and can never disturb input. `color: false` (logs / non-TTY)
+ * degrades to plain indented text.
+ */
+
+/** One source of truth for status → glyph, so every event renders consistently. */
+export const GLYPH = {
+  done: "✓",
+  fail: "✗",
+  warn: "⚠",
+  info: "●",
+  run: "→",
+  create: "✚",
+  edit: "✎",
+  bullet: "•",
+} as const;
+
+const DEFAULT_WIDTH = 80;
+const MIN_WIDTH = 48;
+const MAX_WIDTH = 100;
+
+/** Terminal width, clamped to a sane band — a stable default off a TTY. */
+function termWidth(): number {
+  const cols = process.stdout.columns;
+
+  return Number.isFinite(cols)
+    ? Math.max(MIN_WIDTH, Math.min(MAX_WIDTH, cols))
+    : DEFAULT_WIDTH;
+}
+
+export interface IBoxOptions {
+  glyph?: string;
+  accent?: string;
+  color?: boolean;
+  width?: number;
+}
+
+/**
+ * A title-tabbed block: a top rule that opens with `┌─ <glyph> <title> ` and runs
+ * to the terminal width, each body line on a `│ ` gutter, closed by a `└` rule.
+ * Body lines may already contain ANSI — the right edge is never padded, so no
+ * fragile visible-width math is needed.
+ */
+export function box(
+  title: string,
+  bodyLines: readonly string[],
+  opts: IBoxOptions = {}
+): string {
+  const {
+    glyph = "",
+    accent = STYLE.brand,
+    color = true,
+    width = termWidth(),
+  } = opts;
+  const head = glyph.length > 0 ? `${glyph} ${title}` : title;
+
+  if (!color) {
+    const body = bodyLines.map((l) => `      ${l}`).join("\n");
+
+    return bodyLines.length > 0 ? `  ${head}\n${body}` : `  ${head}`;
+  }
+
+  const opener = "┌─ ";
+  const rule = "─".repeat(Math.max(0, width - opener.length - head.length - 1));
+  const top = `${paint(opener, STYLE.dim, color)}${paint(head, `${accent}${STYLE.bold}`, color)} ${paint(rule, STYLE.dim, color)}`;
+  const bar = paint("│", STYLE.dim, color);
+  const bottom = paint(
+    `└${"─".repeat(Math.max(0, width - 1))}`,
+    STYLE.dim,
+    color
+  );
+
+  if (bodyLines.length === 0) {
+    return `${top}\n${bottom}`;
+  }
+
+  const body = bodyLines.map((l) => `${bar} ${l}`).join("\n");
+
+  return `${top}\n${body}\n${bottom}`;
+}
+
+/**
+ * Render rows as a real box-drawn table — `rows[0]` is the header. Columns auto-
+ * size to their widest cell; the header is accented. The model answers with GFM
+ * markdown tables constantly, which print as raw `|` soup otherwise.
+ */
+export function table(
+  rows: readonly (readonly string[])[],
+  color = true
+): string {
+  if (rows.length === 0) {
+    return "";
+  }
+
+  const cols = Math.max(...rows.map((r) => r.length));
+  const widths = Array.from({ length: cols }, (_, c) =>
+    Math.max(1, ...rows.map((r) => (r[c] ?? "").length))
+  );
+  const bar = paint("│", STYLE.dim, color);
+
+  const rule = (left: string, mid: string, right: string): string =>
+    paint(
+      `${left}${widths.map((w) => "─".repeat(w + 2)).join(mid)}${right}`,
+      STYLE.dim,
+      color
+    );
+
+  const renderRow = (cells: readonly string[], header: boolean): string => {
+    const inner = widths
+      .map((w, c) => {
+        const cell = (cells[c] ?? "").padEnd(w);
+
+        return ` ${header ? paint(cell, `${STYLE.brand}${STYLE.bold}`, color) : cell} `;
+      })
+      .join(bar);
+
+    return `${bar}${inner}${bar}`;
+  };
+
+  const [header, ...body] = rows;
+
+  return [
+    rule("┌", "┬", "┐"),
+    renderRow(header ?? [], true),
+    rule("├", "┼", "┤"),
+    ...body.map((r) => renderRow(r, false)),
+    rule("└", "┴", "┘"),
+  ].join("\n");
+}

package/src/render/index.ts

@@ -0,0 +1,7 @@
+export * from "./render.types";
+export { renderEvent, renderMessage, renderStatus } from "./ansi";
+export { welcomeBanner, type IBannerInfo } from "./banner";
+export { box, table, GLYPH } from "./box";
+export { renderMarkdown, formatTables, highlightCode } from "./markdown";
+export { StreamingMarkdown } from "./stream-markdown";
+export { STYLE, RESET, paint } from "./style";

package/src/render/markdown.ts

@@ -0,0 +1,123 @@
+import { highlight } from "cli-highlight";
+import { STYLE, paint } from "./style";
+import { table } from "./box";
+
+/**
+ * Markdown → terminal formatting, shared by the settled-message renderer
+ * (ansi.ts) and the live streaming renderer (stream-markdown.ts) so a streamed
+ * answer and a re-rendered one look identical.
+ */
+
+/**
+ * Render an assistant message: fenced ```code``` blocks syntax-highlighted, and
+ * GitHub-flavored markdown TABLES drawn as real box tables (the model answers with
+ * `| a | b |` tables constantly — raw they're unreadable pipe soup). Other prose
+ * passes through.
+ */
+export function renderMarkdown(text: string, color: boolean): string {
+  return text
+    .split(/(```[\s\S]*?```)/g)
+    .map((part) => {
+      const fence = /^```([\w-]*)\n?([\s\S]*?)\n?```$/.exec(part);
+
+      if (fence === null) {
+        return formatTables(part, color);
+      }
+
+      const lang =
+        fence[1] !== undefined && fence[1].length > 0 ? fence[1] : "typescript";
+
+      return highlightCode(fence[2] ?? "", lang, color);
+    })
+    .join("");
+}
+
+/** A markdown table separator row, e.g. `|----|:--:|---|`. */
+function isTableSeparator(line: string | undefined): boolean {
+  return (
+    line !== undefined &&
+    line.includes("|") &&
+    line.includes("-") &&
+    /^\s*\|?[\s:|-]*-[\s:|-]*\|?\s*$/.test(line)
+  );
+}
+
+/** Split a `| a | b |` row into trimmed cells (tolerates missing edge pipes). */
+function tableCells(line: string): string[] {
+  return line
+    .trim()
+    .replace(/^\|/, "")
+    .replace(/\|$/, "")
+    .split("|")
+    .map((c) => c.trim());
+}
+
+/** Replace each GFM table block in `text` with a box-drawn table; leave the rest. */
+export function formatTables(text: string, color: boolean): string {
+  const lines = text.split("\n");
+  const out: string[] = [];
+
+  for (let i = 0; i < lines.length; ) {
+    const header = lines[i];
+
+    if (
+      header !== undefined &&
+      header.includes("|") &&
+      isTableSeparator(lines[i + 1])
+    ) {
+      const rows: string[][] = [tableCells(header)];
+      let j = i + 2;
+
+      while (j < lines.length && (lines[j]?.includes("|") ?? false)) {
+        rows.push(tableCells(lines[j] ?? ""));
+        j += 1;
+      }
+
+      out.push(table(rows, color));
+      i = j;
+    } else {
+      out.push(header ?? "");
+      i += 1;
+    }
+  }
+
+  return out.join("\n");
+}
+
+export function highlightCode(
+  code: string,
+  lang: string,
+  color: boolean
+): string {
+  if (!color) {
+    return code;
+  }
+
+  try {
+    return highlight(code, { language: lang, ignoreIllegals: true });
+  } catch {
+    return code;
+  }
+}
+
+/** Cheap inline styling for one streamed prose line — `#` headings and
+ *  `**bold**` brighten, `code` spans use brand light. No-op without color. */
+export function styleInline(line: string, color: boolean): string {
+  if (!color) {
+    return line;
+  }
+
+  const heading = /^#{1,6}\s+(.*)$/.exec(line);
+
+  if (heading !== null) {
+    return paint(heading[1] ?? "", STYLE.bold, color);
+  }
+
+  return line
+    .replace(/\*\*([^*]+)\*\*/g, (_m: string, t: string) =>
+      paint(t, STYLE.bold, color)
+    )
+    .replace(/`([^`]+)`/g, (_m: string, t: string) =>
+      paint(t, STYLE.brandLight, color)
+    );
+}

package/src/render/render.types.ts

@@ -0,0 +1,21 @@
+export interface IRenderOptions {
+  /** Emit ANSI color codes (terminal) vs plain text (log files). Default true. */
+  color?: boolean;
+}
+
+/** A compact post-turn status line — the "where am I" summary modern CLIs show. */
+export interface IStatusInfo {
+  model: string;
+  /** Estimated tokens of conversation context currently held. */
+  contextTokens: number;
+  /** The model's context window (for the used/total ratio). */
+  contextWindow: number;
+  /** Turns the last send took. */
+  turns: number;
+  /** Wall-clock of the last send, in ms. */
+  elapsedMs: number;
+  /** Outcome of the last send (responded / done / stuck / interrupted). */
+  status: string;
+  /** Editable scope label. */
+  scope: string;
+}