@agjs/tsforge 0.1.0

package/src/loop/tools/scaffold-ui.ts

@@ -0,0 +1,62 @@
+import { join } from "node:path";
+import { writable, normalizeWorkspacePath } from "../../lib/scope";
+import {
+  materializeComponents,
+  asThemeName,
+  asComponentNames,
+  COMPONENT_NAMES,
+  THEME_NAMES,
+} from "../../web-components";
+import { type IToolContext } from "./tool-context";
+
+/**
+ * `scaffold_ui` — materialize tested, THEMED UI primitives so the model never
+ * authors (or re-authors) a button/card/input/etc. Writes `src/index.css` (the
+ * vibe's design-token block) + the requested `src/components/ui/*.tsx` primitives
+ * with the theme's per-component classes baked in. Overwrites (re-theming is
+ * idempotent). Reports ONE summary event — deliberately NOT per-file `create`
+ * events, so the write-guard doesn't re-check known-good vendored files.
+ */
+export async function doScaffoldUi(
+  args: Record<string, unknown>,
+  ctx: IToolContext
+): Promise<string> {
+  const theme = asThemeName(args.theme);
+
+  if (theme === undefined) {
+    return `scaffold_ui REJECTED: \`theme\` must be one of: ${THEME_NAMES.join(", ")}.`;
+  }
+
+  const components = asComponentNames(args.components);
+
+  if (components.length === 0) {
+    return `scaffold_ui REJECTED: \`components\` must be a non-empty array from: ${COMPONENT_NAMES.join(", ")}.`;
+  }
+
+  const files = materializeComponents(theme, components);
+  const written: string[] = [];
+
+  for (const [rel, content] of Object.entries(files)) {
+    const path = normalizeWorkspacePath(ctx.cwd, rel);
+
+    if (!writable(path, ctx.files)) {
+      continue;
+    }
+
+    await Bun.write(join(ctx.cwd, path), content);
+    written.push(path);
+  }
+
+  ctx.report({
+    kind: "tool",
+    task: ctx.task,
+    message: `scaffold_ui: wrote ${String(written.length)} themed file(s) [${theme}] — ${components.join(", ")}`,
+  });
+
+  return (
+    `scaffold_ui: wrote ${String(written.length)} file(s) with the "${theme}" theme ` +
+    `(${written.join(", ")}). Import these from @/components/ui (e.g. \`import { Button } ` +
+    `from "@/components/ui/button"\`) and COMPOSE them — do NOT re-create any primitive ` +
+    `or edit the files under src/components/ui.`
+  );
+}

package/src/loop/tools/scaffold-web.ts

@@ -0,0 +1,35 @@
+import { str, type IToolContext } from "./tool-context";
+
+/**
+ * `scaffold_web` — the AGENT's decision to turn this workspace into a from-scratch
+ * web app. It calls this ONLY when the request is "build a web app/UI"; for a
+ * question, a CLI script, or editing existing code it just does the work. This
+ * replaces the old up-front classifier (which mis-fired — e.g. "render a table in
+ * the CLI" was scaffolded as a Vite app). The host (interactive CLI) supplies
+ * `ctx.setupWeb`, which scaffolds the stack + deps and switches the session to the
+ * web gate/guidance; here we just invoke it and tell the model how to proceed.
+ */
+export async function doScaffoldWeb(
+  args: Record<string, unknown>,
+  ctx: IToolContext
+): Promise<string> {
+  if (ctx.setupWeb === undefined) {
+    return (
+      "scaffold_web is unavailable here — this workspace isn't set up for " +
+      "interactive scaffolding. Build directly against the existing project."
+    );
+  }
+
+  const requested = str(args, "framework").toLowerCase();
+  const framework = requested === "vanilla" ? "vanilla" : "react";
+
+  await ctx.setupWeb(framework);
+
+  return (
+    `Scaffolded a ${framework} project (stack + deps installed) and switched to ` +
+    "the web gate. Now BUILD it: first write the type contract — each domain's " +
+    "`src/<domain>/<domain>.types.ts` (+ `.constants.ts`) — then implement the " +
+    "routes/features against those types using @/components/ui. Run the gate when " +
+    "done; it confirms the build, types, lint, and a browser render."
+  );
+}

package/src/loop/tools/tool-context.ts

@@ -0,0 +1,126 @@
+import { repairArgs } from "../../agent/tool-repair";
+import type { TsService } from "../../lsp";
+import type { Reporter } from "../loop.types";
+import type { SessionSnapshotStore } from "../../files/hashline";
+
+export interface IToolContext {
+  cwd: string;
+  /** Editable scope — `edit`/`create` outside it are rejected. */
+  files: string[];
+  report: Reporter;
+  task: string;
+  /** In-process TypeScript LanguageService — backs the semantic tools
+   *  (rename/type_at/find_references/symbol_search/diagnostics/organize_imports).
+   *  Null when the project has no tsconfig. */
+  tsService?: TsService | null;
+  /** Cancellation for the in-flight turn — passed to the `run` tool (and search)
+   *  so a model-issued command is killed on Ctrl-C, not left running. */
+  signal?: AbortSignal;
+  /** Turn this workspace into a web project: scaffold the stack + deps and switch
+   *  the session to the web gate/guidance. Wired by the interactive CLI so the
+   *  AGENT decides whether to scaffold (via the `scaffold_web` tool) instead of a
+   *  brittle up-front classifier. Absent where unsupported (headless already
+   *  scaffolds up front), in which case the tool reports it's unavailable. */
+  setupWeb?: (framework: string) => Promise<void>;
+  /** PLAN MODE: mutating tools are rejected at dispatch and `run` only accepts
+   *  read-only commands — the hard guarantee behind the filtered tool list (a
+   *  salvaged/forced call could otherwise still write). */
+  readOnly?: boolean;
+  /** Hashline snapshot store for stale-anchor recovery (per-session, lazily initialized). */
+  snapshotStore?: SessionSnapshotStore;
+}
+
+/** A required string arg, or "" if missing/wrong-type. */
+export function str(args: Record<string, unknown>, key: string): string {
+  const v = args[key];
+
+  return typeof v === "string" ? v : "";
+}
+
+export interface IParseResult<T> {
+  value: T | null;
+  feedback?: string; // L3 feedback when recoverable=false
+}
+
+/**
+ * Parse a tool's args, with VALIDATE-THEN-REPAIR: try the tool's own parser; if
+ * it rejects, apply the repair ladder (L0→L1→L2→L3). Emits telemetry:
+ *   - `repair:L0:<rule>` / `repair:L1:<rule>` / `repair:L2:<rule>` per applied rule
+ *   - `repair:L3` when re-asking (feedback included in result)
+ *   - `tool_input_rejected:<tool>` when (rarely) no parse succeeded
+ * Returns both the parsed value and optional L3 feedback to surface to the model.
+ */
+export function parseOrRepair<T>(
+  raw: Record<string, unknown>,
+  normalize: (a: Record<string, unknown>) => T | null,
+  ctx: IToolContext,
+  tool: string
+): IParseResult<T> {
+  const direct = normalize(raw);
+
+  if (direct !== null) {
+    return { value: direct };
+  }
+
+  const repair = repairArgs(raw);
+
+  if (repair.applied.length > 0) {
+    for (const rule of repair.applied) {
+      ctx.report({
+        kind: "repair",
+        task: ctx.task,
+        message: `${tool}:${rule}`,
+      });
+    }
+  }
+
+  const repaired = repair.applied.length > 0 ? normalize(repair.args) : null;
+
+  if (repaired !== null) {
+    ctx.report({
+      kind: "tool",
+      task: ctx.task,
+      message: `tool_input_repaired:${tool} (${repair.applied.join(", ")})`,
+    });
+
+    return { value: repaired };
+  }
+
+  // L3: If still broken after L0-L2, return feedback if provided (recoverable=false).
+  if (
+    !repair.recoverable &&
+    repair.feedback !== undefined &&
+    repair.feedback.length > 0
+  ) {
+    ctx.report({
+      kind: "repair",
+      task: ctx.task,
+      message: `${tool}:L3-re-ask`,
+    });
+
+    return { value: null, feedback: repair.feedback };
+  }
+
+  ctx.report({
+    kind: "tool",
+    task: ctx.task,
+    message: `tool_input_rejected:${tool}`,
+  });
+
+  return { value: null };
+}
+
+/** Log a tool rejection (scope / size / match failure) so it's measurable. */
+export function reject(
+  ctx: IToolContext,
+  tool: string,
+  reason: string
+): string {
+  ctx.report({
+    kind: "tool",
+    task: ctx.task,
+    message: `tool_rejected:${tool} (${reason})`,
+  });
+
+  return reason;
+}

package/src/loop/ttsr-defaults.ts

@@ -0,0 +1,53 @@
+import type { ITtsrRule } from "./ttsr";
+
+/**
+ * Built-in TTSR rules: code quality patterns to abort and correct.
+ * All scope tool-args (source of the problem), fileGlobs target src/**\/*.ts(x).
+ * Each rule guides the model toward the matching gate rule.
+ */
+export const DEFAULT_TTSR_RULES: readonly ITtsrRule[] = [
+  {
+    name: "no-as-any",
+    condition: [/\bas\s+any\b/],
+    scope: "tool-args",
+    fileGlobs: ["src/**/*.ts", "src/**/*.tsx"],
+    guidance:
+      "Never use 'as any'. If the type is unknown, use 'unknown' or a proper type. " +
+      "If the API is untyped, consider a declaration file.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "no-ts-suppression",
+    condition: [/@ts-(?:ignore|nocheck)/],
+    scope: "tool-args",
+    fileGlobs: ["src/**/*.ts", "src/**/*.tsx"],
+    guidance:
+      "Never suppress TypeScript with @ts-ignore/@ts-nocheck. Fix the real error; " +
+      "if the library is untyped, add a declaration file instead.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "no-empty-catch",
+    condition: [/catch\s*(?:\([^)]*\))?\s*\{\s*\}/],
+    scope: "tool-args",
+    fileGlobs: ["src/**/*.ts", "src/**/*.tsx"],
+    guidance:
+      "Empty catch blocks hide errors. Log them or handle them: " +
+      "catch (e) { console.error(e); } at minimum.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "no-console-log",
+    condition: [/\bconsole\.(?:log|debug)\s*\(/],
+    scope: "tool-args",
+    fileGlobs: ["src/**/*.ts", "src/**/*.tsx"],
+    guidance:
+      "Remove console.log/debug before shipping. Use a logger or remove the line. " +
+      "Tests can call console.log; production code must not.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+];

package/src/loop/ttsr.ts

@@ -0,0 +1,322 @@
+import { isArray, isRecord } from "../lib/guards";
+import { matchesAnyGlobPattern } from "../rule-packs/utils";
+
+/**
+ * A TTSR rule — triggers on matching stream text, aborts generation, and injects
+ * corrective guidance on retry. Rules watch specific channels (prose vs tool args)
+ * and optionally scope to files matching a glob.
+ */
+export interface ITtsrRule {
+  readonly name: string;
+  /** Regex patterns (as source strings for JSON, or RegExp objects for code).
+   *  Compiled once at manager init. Each is OR'd; any match fires. */
+  readonly condition: readonly (string | RegExp)[];
+  /** Which stream channel(s) to monitor: "content" (prose), "tool-args" (tool call
+   *  arguments being assembled), or "both". */
+  readonly scope: "content" | "tool-args" | "both";
+  /** Optional file globs: for tool-args scope, only match when the edit/create
+   *  targets a file path matching one of these globs. */
+  readonly fileGlobs?: readonly string[];
+  /** Guidance text (≤300 chars) appended to the corrective message on retry. */
+  readonly guidance: string;
+  /** "once" = fires at most once per session; "cooldown" = re-arms after repeatGap
+   *  turns without a match. */
+  readonly repeatMode: "once" | "cooldown";
+  /** Gap (in completed turns) before a "cooldown"-mode rule can re-fire. */
+  readonly repeatGap?: number;
+}
+
+/** Match context: information about the stream being monitored. */
+export interface IMatchContext {
+  source: "content" | "tool-args";
+  /** Current file being edited/created (when tool-args scope), if available. */
+  currentFile?: string;
+}
+
+/**
+ * Manages TTSR rule matching and firing. Keeps a rolling buffer per scope/channel
+ * to catch patterns spanning chunk boundaries; respects repeat policy + scope gates.
+ */
+export class TtsrManager {
+  private disabled = false;
+
+  private readonly rules: Map<string, ITtsrRule> = new Map<string, ITtsrRule>();
+  private readonly compiledConditions: Map<string, RegExp[]> = new Map<
+    string,
+    RegExp[]
+  >();
+  private buffers: Record<"content" | "tool-args", string> = {
+    content: "",
+    "tool-args": "",
+  };
+  private readonly turnCounts: Map<string, number> = new Map<string, number>();
+  private messageCount = 0;
+
+  /** Max chars to retain in rolling buffer (patterns spanning ~10 chunks). */
+  private readonly BUFFER_SIZE = 512;
+
+  /**
+   * Register a rule. Validates regex conditions; skips invalid or duplicate rules.
+   * Returns true if registered, false if skipped.
+   */
+  addRule(rule: ITtsrRule): boolean {
+    if (this.rules.has(rule.name)) {
+      return false;
+    }
+
+    const compiled: RegExp[] = [];
+
+    for (const pattern of rule.condition) {
+      try {
+        if (pattern instanceof RegExp) {
+          compiled.push(pattern);
+        } else {
+          compiled.push(new RegExp(pattern));
+        }
+      } catch {
+        // Invalid regex — skip this rule entirely.
+        return false;
+      }
+    }
+
+    if (compiled.length === 0) {
+      return false;
+    }
+
+    this.rules.set(rule.name, rule);
+    this.compiledConditions.set(rule.name, compiled);
+
+    return true;
+  }
+
+  /** Feed a delta into the rolling buffer and check all rules. Returns the first
+   *  matching rule or null. Accumulates text into buffers per source channel. */
+  /** Permanently stop matching (used when the per-task interrupt cap is hit). */
+  disable(): void {
+    this.disabled = true;
+  }
+
+  checkDelta(text: string, context: IMatchContext): ITtsrRule | null {
+    if (this.disabled) {
+      return null;
+    }
+
+    const bufferKey = context.source;
+
+    this.buffers[bufferKey] += text;
+
+    // Trim buffer to max size, keeping the tail (so patterns spanning boundaries match).
+    if (this.buffers[bufferKey].length > this.BUFFER_SIZE) {
+      this.buffers[bufferKey] = this.buffers[bufferKey].slice(
+        -this.BUFFER_SIZE
+      );
+    }
+
+    const buf = this.buffers[bufferKey];
+
+    // Check all rules; return first match that passes repeat policy and scope gates.
+    for (const [ruleName, rule] of this.rules) {
+      if (!this.isScopeActive(rule, context)) {
+        continue;
+      }
+
+      if (!this.isFileScopeSatisfied(rule, context)) {
+        continue;
+      }
+
+      if (!this.isRepeatEligible(ruleName, rule)) {
+        continue;
+      }
+
+      if (this.doesMatch(ruleName, buf)) {
+        return rule;
+      }
+    }
+
+    return null;
+  }
+
+  /** Mark a rule as fired at the current turn (for repeat policy tracking). */
+  markFired(ruleName: string, turn: number): void {
+    this.turnCounts.set(ruleName, turn);
+  }
+
+  /** Increment message count (call on turn_end for cooldown gap accounting). */
+  incrementTurnCount(): void {
+    this.messageCount += 1;
+  }
+
+  /** Reset the rolling buffers (call on turn start so each turn's patterns start fresh). */
+  resetBuffer(): void {
+    this.buffers.content = "";
+    this.buffers["tool-args"] = "";
+  }
+
+  /** fileGlobs constrain tool-args matches to edits of matching files. An
+   *  unknown target (path not yet streamed) holds fire — conservative. */
+  private isFileScopeSatisfied(
+    rule: ITtsrRule,
+    context: IMatchContext
+  ): boolean {
+    if (rule.fileGlobs === undefined || rule.fileGlobs.length === 0) {
+      return true;
+    }
+
+    if (context.source !== "tool-args") {
+      return true;
+    }
+
+    if (context.currentFile === undefined) {
+      return false;
+    }
+
+    return matchesAnyGlobPattern(context.currentFile, rule.fileGlobs);
+  }
+
+  /** Check if a rule's scope includes the current source. */
+  private isScopeActive(rule: ITtsrRule, context: IMatchContext): boolean {
+    if (rule.scope === "both") {
+      return true;
+    }
+
+    return rule.scope === context.source;
+  }
+
+  /** Check if a rule is eligible to fire based on repeat policy. */
+  private isRepeatEligible(ruleName: string, rule: ITtsrRule): boolean {
+    const lastFired = this.turnCounts.get(ruleName);
+
+    if (lastFired === undefined) {
+      return true; // Never fired before.
+    }
+
+    if (rule.repeatMode === "once") {
+      return false; // Fired once, never again.
+    }
+
+    const gap = rule.repeatGap ?? 1;
+
+    return this.messageCount - lastFired >= gap;
+  }
+
+  /** Check if any regex condition matches the buffer. */
+  private doesMatch(ruleName: string, buf: string): boolean {
+    const conditions = this.compiledConditions.get(ruleName);
+
+    if (!conditions) {
+      return false;
+    }
+
+    return conditions.some((re) => re.test(buf));
+  }
+}
+
+/** Extract scope from parsed item, validating the value. */
+function extractScope(scopeValue: unknown): "content" | "tool-args" | "both" {
+  if (
+    scopeValue === "tool-args" ||
+    scopeValue === "content" ||
+    scopeValue === "both"
+  ) {
+    return scopeValue;
+  }
+
+  return "content";
+}
+
+/** Extract conditions (regex patterns) from parsed item. */
+function extractConditions(conditionValue: unknown): string[] {
+  if (isArray(conditionValue)) {
+    return conditionValue.filter((x) => typeof x === "string");
+  }
+
+  if (typeof conditionValue === "string") {
+    return [conditionValue];
+  }
+
+  return [];
+}
+
+/** Extract optional file globs from parsed item. */
+function extractFileGlobs(fileGlobsValue: unknown): string[] | undefined {
+  if (!isArray(fileGlobsValue)) {
+    return undefined;
+  }
+
+  const globs = fileGlobsValue.filter((x) => typeof x === "string");
+
+  return globs.length > 0 ? globs : undefined;
+}
+
+/** Parse .tsforge/rules.json (optional project rules). */
+export function parseProjectRules(content: string): ITtsrRule[] {
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    return [];
+  }
+
+  if (!isArray(parsed)) {
+    return [];
+  }
+
+  const rules: ITtsrRule[] = [];
+
+  for (const item of parsed) {
+    if (!isRecord(item) || typeof item.name !== "string") {
+      continue;
+    }
+
+    const condition = extractConditions(item.condition);
+    const guidance = typeof item.guidance === "string" ? item.guidance : "";
+
+    if (condition.length === 0 || guidance.length === 0) {
+      continue;
+    }
+
+    const scope = extractScope(item.scope);
+    const repeatMode = item.repeatMode === "cooldown" ? "cooldown" : "once";
+    const repeatGap =
+      typeof item.repeatGap === "number" && item.repeatGap >= 0
+        ? Math.floor(item.repeatGap)
+        : undefined;
+    const fileGlobs = extractFileGlobs(item.fileGlobs);
+
+    const rule = createRule(
+      item.name,
+      condition,
+      scope,
+      guidance,
+      repeatMode,
+      repeatGap,
+      fileGlobs
+    );
+
+    rules.push(rule);
+  }
+
+  return rules;
+}
+
+/** Create a rule from parsed/validated components. */
+function createRule(
+  name: string,
+  condition: readonly (string | RegExp)[],
+  scope: "content" | "tool-args" | "both",
+  guidance: string,
+  repeatMode: "once" | "cooldown",
+  repeatGap: number | undefined,
+  fileGlobs: string[] | undefined
+): ITtsrRule {
+  return {
+    name,
+    condition,
+    scope,
+    guidance,
+    repeatMode,
+    ...(fileGlobs && fileGlobs.length > 0 ? { fileGlobs } : {}),
+    ...(repeatGap !== undefined && repeatGap > 0 ? { repeatGap } : {}),
+  };
+}