@agjs/tsforge 0.3.2 → 0.3.4

package/package.json

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

package/scripts/sweep.ts

@@ -87,6 +87,8 @@ function variantToEnvVars(variant: IFeatureVariant): Record<string, string> {
       envVars.TSFORGE_HASHLINE = state === "1" ? "1" : "0";
     } else if (dim === "lsp_write_feedback") {
       envVars.TSFORGE_LSP_WRITE_FEEDBACK = state === "1" ? "1" : "0";
+    } else if (dim === "simplicity") {
+      envVars.TSFORGE_SIMPLICITY = state === "1" ? "1" : "0";
     }
     // else: unknown dimension, skip
   }

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/config/config.constants.ts

@@ -6,4 +6,5 @@ export const ENV_FLAG = {
   legacyFeedback: "TSFORGE_LEGACY_FEEDBACK",
   noAstgrep: "TSFORGE_NO_ASTGREP",
   forceTools: "TSFORGE_FORCE_TOOLS",
+  simplicity: "TSFORGE_SIMPLICITY",
 } as const;

package/src/config/flags.ts

@@ -29,4 +29,8 @@ export const flags = {
    *  (A/B control, default ON — set to "0" to disable). */
   lspWriteFeedback: (): boolean =>
     process.env.TSFORGE_LSP_WRITE_FEEDBACK !== "0",
+  /** Scratch-utility simplicity guidance — appends a "shortest correct solution"
+   *  block to the build prompt for from-scratch, non-web tasks (A/B control,
+   *  default OFF until a sweep validates it). */
+  simplicity: (): boolean => isOn(ENV_FLAG.simplicity),
 };

package/src/loop/prompt/index.ts

@@ -1,2 +1,9 @@
-export { SYSTEM, CHAT_SYSTEM, COMPACT_SYSTEM, seedPrompt } from "./prompt";
+export {
+  SYSTEM,
+  CHAT_SYSTEM,
+  COMPACT_SYSTEM,
+  SCRATCH_SIMPLICITY_GUIDANCE,
+  buildSystemPrompt,
+  seedPrompt,
+} from "./prompt";
 export { renderFileSection, exportedSymbols } from "./project-map";

package/src/loop/prompt/prompt.ts

@@ -1,7 +1,8 @@
 import type { ITask } from "../../spec";
 import type { IFileView } from "../../lib/fs";
-import { PACK_REGISTRY } from "../../stack-detection";
+import { PACK_REGISTRY, isWebStack } from "../../stack-detection";
 import type { IStackProfile } from "../../stack-detection";
+import { flags } from "../../config";
 import { renderFileSection } from "./project-map";
 
 /** The implement-agent system prompt: who it is, the tools, and the strict-TS
@@ -16,6 +17,40 @@ export const SYSTEM = [
   "The gate is `tsc` strict + eslint with every rule an error, so write TypeScript that satisfies it: interfaces are `I`-prefixed; `===`; no `var`; never the non-null `!` — guard index access (`const x = arr[i]; if (x === undefined) {...}`); no `any` and no `as` — type every parameter (e.g. `.reduce((acc: number, r: number) => …, 0)`); explicit boolean conditions. When the gate flags errors in read-only files (tests/types), they come from your editable file being missing or wrong-shaped and vanish once it's correct — don't edit them.",
 ].join("\n");
 
+/** Appended to SYSTEM for from-scratch, NON-web utility builds when the simplicity
+ *  flag is on. Pushes the model toward the shortest correct solution — the axis the
+ *  gate is blind to (it checks correctness, never concision). Carve-outs keep it
+ *  from fighting the gate's hard rules. NOT for web builds (the views/components
+ *  architecture legitimately needs many small files). */
+export const SCRATCH_SIMPLICITY_GUIDANCE = [
+  "SIMPLICITY — write the SHORTEST correct solution that passes the gate:",
+  "  • The task's `files:` are the ceiling — do NOT add modules, classes, or",
+  "    abstractions the task didn't ask for. One focused implementation.",
+  "  • Prefer built-ins and a direct expression over step-by-step temporaries:",
+  "    chain the transforms (`xs.filter(...).map(...)`) instead of naming each",
+  "    intermediate, when it stays readable.",
+  "  • NO narration/step comments ('// Step 1', '// first we…') — the code is the",
+  "    explanation. A comment earns its place only for a non-obvious WHY.",
+  "  • This NEVER overrides the gate: keep `I`-prefixed interfaces, no `as`/`any`/`!`,",
+  "    real validation at trust boundaries, and any test siblings the gate requires.",
+].join("\n");
+
+/** SYSTEM + the simplicity block when it applies, else SYSTEM unchanged. Gated on
+ *  the `simplicity` flag AND a from-scratch (`!hasExistingCode`) NON-web build —
+ *  so it never touches existing-repo edits or web/UI apps. */
+export function buildSystemPrompt(
+  hasExistingCode: boolean,
+  stack: IStackProfile | undefined
+): string {
+  const webish = stack !== undefined && isWebStack(stack);
+
+  if (!flags.simplicity() || hasExistingCode || webish) {
+    return SYSTEM;
+  }
+
+  return `${SYSTEM}\n\n${SCRATCH_SIMPLICITY_GUIDANCE}`;
+}
+
 /**
  * The INTERACTIVE assistant prompt (the CLI's `Session`). Unlike `SYSTEM` — which
  * drives a single task to a gate and is told to "keep going until green" — this

package/src/loop/run.ts

@@ -17,7 +17,7 @@ import type {
 } from "./loop.types";
 import { mineLessons, consolidate as consolidateMemory } from "./memory";
 import { flags } from "../config";
-import { SYSTEM, seedPrompt } from "./prompt";
+import { buildSystemPrompt, seedPrompt } from "./prompt";
 import { detectStack } from "../stack-detection";
 import type { TtsrManager } from "./ttsr";
 import {
@@ -295,17 +295,23 @@ export async function runTask(
 
   const editable = await readFiles(cwd, task.files);
   const context = await readFiles(cwd, task.context ?? []);
+
+  // Existing code to navigate? (editable files already have content). Only then
+  // do the LSP nav tools earn their decision-surface cost — see toolsFor(). Also
+  // gates the scratch-simplicity guidance (from-scratch builds only).
+  const hasExistingCode = editable.some((f) => f.content.trim().length > 0);
+
   const messages: IChatMessage[] = [
-    { role: "system", content: SYSTEM },
+    {
+      role: "system",
+      content: buildSystemPrompt(hasExistingCode, stackProfile),
+    },
     {
       role: "user",
       content: seedPrompt(task, editable, context, stackProfile),
     },
   ];
 
-  // Existing code to navigate? (editable files already have content). Only then
-  // do the LSP nav tools earn their decision-surface cost — see toolsFor().
-  const hasExistingCode = editable.some((f) => f.content.trim().length > 0);
   const tools = toolsFor(hasExistingCode);
 
   // Mode-aware reasoning cap: scratch tasks over-think unbounded, so default

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();
+  });
+}

package/src/stack-detection/detect.ts

@@ -9,6 +9,21 @@ import {
   type IPackId,
 } from "./packs";
 
+/** The pack ids that identify a WEB (browser UI) build. Used to scope behaviours
+ *  that must NOT apply to web apps (e.g. the scratch-simplicity prompt, whose
+ *  "shortest solution / no extra files" advice fights the views/components
+ *  architecture the web scaffold requires). */
+const WEB_PACK_IDS: readonly string[] = [
+  "react",
+  "react-component-architecture",
+  "tanstack-query",
+];
+
+/** True when the detected stack is a web/browser UI build. */
+export function isWebStack(profile: IStackProfile): boolean {
+  return profile.packs.some((p) => WEB_PACK_IDS.includes(p));
+}
+
 /** Parse package.json and extract deps/devDeps, tolerating missing/invalid JSON. */
 async function loadPackageDeps(cwd: string): Promise<{
   deps: Set<string>;

package/src/stack-detection/index.ts

@@ -1,3 +1,3 @@
 export * from "./stack-detection.types";
-export { detectStack } from "./detect";
+export { detectStack, isWebStack } from "./detect";
 export { PACK_REGISTRY, ALWAYS_ON_PACKS } from "./packs";