@agjs/tsforge 0.3.3 → 0.3.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agjs/tsforge",
   "type": "module",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "license": "MIT",
   "description": "TypeScript coding harness with a deterministic gate, stack-aware guardrails, and stream-level correction.",
   "repository": {

package/src/cli/commands.ts

@@ -0,0 +1,97 @@
+/**
+ * The single source of truth for the REPL's slash commands — drives BOTH the
+ * `/help` text and the interactive `/` palette, so they can never drift and the
+ * user never has to memorize what exists. The executor stays the `command()`
+ * switch in cli.ts; `commandVerbs()` lets a test assert the two stay in sync.
+ */
+export interface ICommandSpec {
+  /** Full token incl. leading slash, e.g. "/gate". */
+  readonly name: string;
+  /** Argument hint shown after the name (e.g. "<cmd>", "[name]"); omitted if none. */
+  readonly arg?: string;
+  /** One-line description. */
+  readonly summary: string;
+}
+
+export const COMMANDS: readonly ICommandSpec[] = [
+  { name: "/help", summary: "show this help" },
+  {
+    name: "/compact",
+    summary: "summarize the conversation to free up context",
+  },
+  {
+    name: "/clear",
+    summary: "reset the conversation (keeps the workspace + gate)",
+  },
+  {
+    name: "/plan",
+    summary:
+      "toggle plan mode (explore → clarify → plan; 'approve' implements)",
+  },
+  {
+    name: "/gate",
+    arg: "<cmd>",
+    summary: "set the gate command (empty to clear)",
+  },
+  {
+    name: "/files",
+    arg: "<globs>",
+    summary: "set the editable scope (comma-separated; empty = all)",
+  },
+  {
+    name: "/model",
+    arg: "[name]",
+    summary: "list configured models (★ active), or switch to <name>",
+  },
+  { name: "/sessions", summary: "list saved sessions" },
+  { name: "/cost", summary: "rough conversation size (messages + ~tokens)" },
+  {
+    name: "/metrics",
+    summary: "token totals + generation rate (tok/s) this session",
+  },
+  {
+    name: "/memory",
+    arg: "[forget]",
+    summary: "show learned failure→fix lessons (forget to clear)",
+  },
+  { name: "/exit", summary: "leave the session" },
+] as const;
+
+/** True when the spec takes an argument — the palette prefills `"<name> "` and
+ *  lets the user type instead of running immediately. */
+export function takesArg(spec: ICommandSpec): boolean {
+  return spec.arg !== undefined;
+}
+
+/** Command verbs (no slash) that MUST have an executor case, incl. the `/quit`
+ *  alias that isn't listed in the palette. Used by the registry↔switch parity test. */
+export const COMMAND_VERBS: readonly string[] = [
+  ...COMMANDS.map((c) => c.name.slice(1)),
+  "quit",
+];
+
+/** The `/help` body — the command table (from the registry) plus the footer. */
+export function formatHelp(): string {
+  const width = Math.max(
+    ...COMMANDS.map(
+      (c) => c.name.length + (c.arg === undefined ? 0 : c.arg.length + 1)
+    )
+  );
+  const rows = COMMANDS.map((c) => {
+    const left = c.arg === undefined ? c.name : `${c.name} ${c.arg}`;
+
+    return `  ${left.padEnd(width)}   ${c.summary}`;
+  });
+
+  return [
+    "Commands:",
+    ...rows,
+    "  /quit              alias for /exit",
+    "",
+    "Press / for an interactive menu (↑/↓ to select, type to filter, Enter to run).",
+    "Anything else is sent to the agent. It works with its tools; when it stops,",
+    'the gate (if set) confirms "done".',
+    "While it's working: type a message to STEER the next turn (e.g. 'use Tailwind');",
+    "Ctrl-C interrupts the current run.",
+  ].join("\n");
+}

package/src/cli.ts

@@ -2,6 +2,9 @@
 import { join, isAbsolute } from "node:path";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
+import { emitKeypressEvents } from "node:readline";
+import { formatHelp, takesArg } from "./cli/commands";
+import { pickCommand } from "./render/command-menu";
 import { runTask, RUN_STATUS, Session, PLAN_APPROVED_NOTE } from "./loop";
 import {
   PROVIDER_LIMITS,
@@ -664,26 +667,9 @@ export function isPlanApproval(line: string): boolean {
   return /^(approve|approved|go|lgtm|implement)[.!]?$/i.test(line.trim());
 }
 
-const HELP = [
-  "Commands:",
-  "  /help            show this help",
-  "  /compact         summarize the conversation to free up context",
-  "  /clear           reset the conversation (keeps the workspace + gate)",
-  "  /plan            toggle plan mode (read-only: explore → clarify → plan; 'approve' implements)",
-  "  /gate <cmd>      set the gate command (empty to clear)",
-  "  /files <globs>   set the editable scope (comma-separated; empty = all)",
-  "  /model [name]    list configured models (★ active), or switch to <name>",
-  "  /sessions        list saved sessions (resume one with: tsforge --resume <id>)",
-  "  /cost            rough conversation size (messages + ~tokens)",
-  "  /metrics         token totals + generation rate (tok/s) this session",
-  "  /memory          show learned failure→fix lessons (/memory forget to clear)",
-  "  /exit, /quit     leave the session",
-  "",
-  "Anything else is sent to the agent. It works with its tools; when it stops,",
-  'the gate (if set) confirms "done".',
-  "While it's working: type a message to STEER the next turn (e.g. 'use Tailwind');",
-  "Ctrl-C interrupts the current run.",
-].join("\n");
+// The /help body is generated from the command registry (src/cli/commands.ts) so
+// the help text and the interactive `/` palette can never drift.
+const HELP = formatHelp();
 
 /** The session status line — distinguishes off / new / resumed. */
 function sessionLine(id: string, resumed: ISessionRecord | null): string {
@@ -1191,6 +1177,7 @@ async function repl(args: ICliArgs): Promise<number> {
         session.setPlanMode(planMode); // a /clear must not silently drop the mode
         planDiscussed = false;
         await persist();
+        clearScreen(); // wipe the visible terminal + scrollback, not just the state
         process.stdout.write("conversation cleared\n");
         break;
 
@@ -1356,6 +1343,23 @@ async function repl(args: ICliArgs): Promise<number> {
     statusBar.teardown();
   });
 
+  // Wipe the visible terminal + scrollback (2J + 3J + home), re-pinning the status
+  // bar around it so its scroll region stays correct. Used by /clear so the screen
+  // is a clean slate, not just the conversation state.
+  const clearScreen = (): void => {
+    const wasActive = statusBar.active;
+
+    if (wasActive) {
+      statusBar.teardown();
+    }
+
+    process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
+
+    if (wasActive) {
+      statusBar.install(statusInfo());
+    }
+  };
+
   // The prompt. With the bar pinned it repaints the bar and shows only the
   // input marker; otherwise it prints the inline status line above the marker.
   const prompt = (): void => {
@@ -1374,6 +1378,7 @@ async function repl(args: ICliArgs): Promise<number> {
   await new Promise<void>((resolveLoop) => {
     let busy = false;
     let closed = false;
+    let paletteOpen = false;
 
     // Finish the loop only when stdin has closed AND no run is in flight — so a
     // stdin EOF (piped input / Ctrl-D) never kills a build mid-turn.
@@ -1417,6 +1422,50 @@ async function repl(args: ICliArgs): Promise<number> {
       }
     };
 
+    // Open the interactive `/` command palette: pick a command from a navigable
+    // list, then either run it (no-arg) or prefill the line so the user types the
+    // argument. Cancel ⇒ back to a clean prompt. Only meaningful on a TTY.
+    const openPalette = async (): Promise<void> => {
+      paletteOpen = true;
+
+      try {
+        rl.write(null, { ctrl: true, name: "u" }); // clear the typed "/"
+
+        const picked = await pickCommand(process.stdout.isTTY);
+
+        // The palette ran on the alternate screen; exiting it restored the prompt
+        // verbatim, so don't re-draw it (that left stray `›` lines). On cancel,
+        // nothing to do; for an arg command, prefill so the user types the value.
+        if (picked !== null) {
+          if (takesArg(picked)) {
+            rl.write(`${picked.name} `);
+          } else {
+            void runLine(picked.name);
+          }
+        }
+      } finally {
+        paletteOpen = false;
+      }
+    };
+
+    // Press `/` on an empty line ⇒ open the palette. setImmediate lets readline
+    // finish inserting the slash first, so `rl.line === "/"` confirms it's a fresh
+    // command start (not a slash mid-text). No-op while busy or already open.
+    if (process.stdin.isTTY) {
+      emitKeypressEvents(process.stdin);
+      process.stdin.on("keypress", (str: string | undefined) => {
+        if (busy || paletteOpen || str !== "/") {
+          return;
+        }
+
+        setImmediate(() => {
+          if (!busy && !paletteOpen && rl.line === "/") {
+            void openPalette();
+          }
+        });
+      });
+    }
+
     // Event-driven (not for-await) so stdin is read DURING a run: a line typed
     // mid-run is queued to steer the next turn (or, if "/exit", aborts). This is
     // what makes it feel like a real harness — you can redirect without waiting.

package/src/render/command-menu.ts

@@ -0,0 +1,174 @@
+import { emitKeypressEvents } from "node:readline";
+import { STYLE, paint } from "./style";
+import { COMMANDS, type ICommandSpec } from "../cli/commands";
+
+const ESC = String.fromCharCode(27);
+// Render the palette on the terminal's ALTERNATE screen buffer: enter on open,
+// clear+home before each frame, exit on close — which restores the previous screen
+// (conversation + status bar) verbatim. This avoids in-place cursor math fighting
+// the status bar's scroll region (which caused frames to stack instead of redraw).
+const ENTER_ALT = `${ESC}[?1049h${ESC}[r`; // alt screen + reset scroll margins
+const EXIT_ALT = `${ESC}[?1049l`;
+const HIDE_CURSOR = `${ESC}[?25l`;
+const SHOW_CURSOR = `${ESC}[?25h`;
+const CLEAR_HOME = `${ESC}[2J${ESC}[H`;
+
+/** Filter commands by a query (the text typed after `/`). Leading slash and case
+ *  are ignored; matches commands whose name contains the query. Empty ⇒ all. */
+export function filterCommands(
+  commands: readonly ICommandSpec[],
+  query: string
+): ICommandSpec[] {
+  const q = query.replace(/^\//u, "").toLowerCase();
+
+  if (q.length === 0) {
+    return [...commands];
+  }
+
+  return commands.filter((c) => c.name.slice(1).toLowerCase().includes(q));
+}
+
+/** Keep `selected` within `[0, count)` (wraps), so ↑/↓ never points off-list. */
+export function clampIndex(selected: number, count: number): number {
+  if (count <= 0) {
+    return 0;
+  }
+
+  return ((selected % count) + count) % count;
+}
+
+/** Render the palette as a block of lines (no trailing newline). The header echoes
+ *  the current filter + key hints; the selected row is brand-highlighted. */
+export function renderMenu(
+  items: readonly ICommandSpec[],
+  selected: number,
+  query: string,
+  color: boolean
+): string {
+  const header =
+    paint(`/${query}`, STYLE.brand, color) +
+    paint(
+      "  ↑/↓ select · type to filter · enter run · esc cancel",
+      STYLE.dim,
+      color
+    );
+
+  if (items.length === 0) {
+    return `${header}\n  ${paint("no matching command", STYLE.dim, color)}`;
+  }
+
+  const rows = items.map((c, i) => {
+    const active = i === selected;
+    const gutter = active ? paint("›", STYLE.brand, color) : " ";
+    const label = c.arg === undefined ? c.name : `${c.name} ${c.arg}`;
+    const name = paint(label, active ? STYLE.brand : STYLE.bold, color);
+
+    return `${gutter} ${name}  ${paint(c.summary, STYLE.dim, color)}`;
+  });
+
+  return [header, ...rows].join("\n");
+}
+
+/** One keypress, as decoded by readline's `emitKeypressEvents`. */
+interface IKeyInfo {
+  readonly name?: string;
+  readonly ctrl?: boolean;
+}
+
+/**
+ * The interactive `/` palette. Owns `keypress` input for its lifetime — it detaches
+ * the existing keypress listeners (readline's line editor + the REPL's `/` trigger)
+ * so they don't also react, renders a navigable list, and resolves to the chosen
+ * command or null (Esc / Ctrl-C / backspace-past-empty). `finish()` ALWAYS restores
+ * the saved listeners, so input returns to normal. No-ops to null off a TTY.
+ *
+ * Note: stdin stays in the raw, flowing mode readline already set — we only swap
+ * WHO listens, never toggle raw mode, so the terminal can't be left wedged.
+ */
+export function pickCommand(
+  color: boolean,
+  out: (s: string) => void = (s) => process.stdout.write(s)
+): Promise<ICommandSpec | null> {
+  const stdin = process.stdin;
+
+  if (!stdin.isTTY) {
+    return Promise.resolve(null);
+  }
+
+  return new Promise((resolve) => {
+    let query = "";
+    let selected = 0;
+
+    emitKeypressEvents(stdin);
+
+    // Take over keypress for the palette's lifetime: stash + detach the current
+    // listeners (readline's editor + the REPL `/` trigger) so only `onKey` reacts;
+    // restored in finish().
+    const saved = stdin.rawListeners("keypress");
+
+    stdin.removeAllListeners("keypress");
+
+    const draw = (): void => {
+      const items = filterCommands(COMMANDS, query);
+
+      selected = clampIndex(selected, items.length);
+
+      out(`${CLEAR_HOME}${renderMenu(items, selected, query, color)}`);
+    };
+
+    const finish = (result: ICommandSpec | null): void => {
+      stdin.removeListener("keypress", onKey);
+      out(`${SHOW_CURSOR}${EXIT_ALT}`); // restore the previous screen verbatim
+
+      // Restore the listeners we detached (readline's editor + the REPL trigger),
+      // forwarding through a thin wrapper so we don't fight the Function[] type.
+      for (const l of saved) {
+        stdin.on("keypress", (...args: unknown[]) => {
+          Reflect.apply(l, stdin, args);
+        });
+      }
+
+      resolve(result);
+    };
+
+    const onKey = (str: string | undefined, key: IKeyInfo): void => {
+      try {
+        if ((key.ctrl === true && key.name === "c") || key.name === "escape") {
+          finish(null);
+
+          return;
+        }
+
+        const items = filterCommands(COMMANDS, query);
+
+        if (key.name === "return" || key.name === "enter") {
+          finish(items[clampIndex(selected, items.length)] ?? null);
+        } else if (key.name === "up") {
+          selected -= 1;
+          draw();
+        } else if (key.name === "down") {
+          selected += 1;
+          draw();
+        } else if (key.name === "backspace") {
+          if (query.length === 0) {
+            finish(null); // backspace past the slash closes the palette
+          } else {
+            query = query.slice(0, -1);
+            selected = 0;
+            draw();
+          }
+        } else if (key.ctrl !== true && str?.length === 1 && str >= " ") {
+          query += str;
+          selected = 0;
+          draw();
+        }
+      } catch {
+        finish(null); // never let a render error wedge input
+      }
+    };
+
+    stdin.on("keypress", onKey);
+    out(`${ENTER_ALT}${HIDE_CURSOR}`);
+    draw();
+  });
+}