@agjs/tsforge 0.1.0

package/src/stack-detection/packs.ts

@@ -0,0 +1,174 @@
+import type { IRulePackDescriptor } from "./stack-detection.types";
+
+/**
+ * Registry of all available rule packs. This is the source of truth for which packs
+ * exist and under what conditions they are enabled during stack detection.
+ */
+export const PACK_REGISTRY = {
+  "generic-ts": {
+    id: "generic-ts",
+    label: "TypeScript Fundamentals",
+    description:
+      "Core TypeScript safety rules for all projects (strict mode, index safety, no casts)",
+    category: "language",
+    appliesWhen: { always: true },
+    guidance: "Enforce strict TypeScript rules on all projects.",
+  } as const satisfies IRulePackDescriptor,
+
+  react: {
+    id: "react",
+    label: "React",
+    description: "React component patterns and hooks usage",
+    category: "framework",
+    appliesWhen: { allDeps: ["react", "react-dom"] },
+    guidance: "Follow React best practices for component composition.",
+  } as const satisfies IRulePackDescriptor,
+
+  "react-component-architecture": {
+    id: "react-component-architecture",
+    label: "React Component Architecture",
+    description:
+      "Component structure, composition, and file organization for React",
+    category: "framework",
+    appliesWhen: { allDeps: ["react"] },
+    guidance: "Organize React components with clear separation of concerns.",
+  } as const satisfies IRulePackDescriptor,
+
+  "tanstack-query": {
+    id: "tanstack-query",
+    label: "TanStack Query",
+    description: "Patterns for data fetching with TanStack Query",
+    category: "library",
+    appliesWhen: { anyDeps: ["@tanstack/react-query"] },
+    guidance: "Use TanStack Query for async state management.",
+  } as const satisfies IRulePackDescriptor,
+
+  drizzle: {
+    id: "drizzle",
+    label: "Drizzle ORM",
+    description: "Database access patterns using Drizzle ORM",
+    category: "library",
+    appliesWhen: { anyDeps: ["drizzle-orm"] },
+    guidance: "Use Drizzle ORM type-safely for database queries.",
+  } as const satisfies IRulePackDescriptor,
+
+  elysia: {
+    id: "elysia",
+    label: "Elysia",
+    description: "HTTP server patterns with Elysia framework",
+    category: "framework",
+    appliesWhen: { anyDeps: ["elysia"] },
+    guidance: "Follow Elysia patterns for HTTP routing and middleware.",
+  } as const satisfies IRulePackDescriptor,
+
+  bullmq: {
+    id: "bullmq",
+    label: "BullMQ",
+    description: "Job queue patterns with BullMQ",
+    category: "library",
+    appliesWhen: { anyDeps: ["bullmq"] },
+    guidance: "Use BullMQ for reliable async job processing.",
+  } as const satisfies IRulePackDescriptor,
+
+  "test-conventions": {
+    id: "test-conventions",
+    label: "Test Conventions",
+    description:
+      "Testing patterns and file structure for vitest, jest, or Bun tests",
+    category: "testing",
+    appliesWhen: {
+      anyDeps: ["vitest", "jest", "bun-types"],
+      files: ["vitest.config.*", "jest.config.*"],
+    },
+    guidance: "Follow consistent test organization and naming.",
+  } as const satisfies IRulePackDescriptor,
+
+  "env-access": {
+    id: "env-access",
+    label: "Environment Variables",
+    description:
+      "Safe environment variable access patterns (validation and typing)",
+    category: "infra",
+    appliesWhen: { always: true },
+    guidance: "Always validate and type environment variables.",
+  } as const satisfies IRulePackDescriptor,
+
+  "module-boundaries": {
+    id: "module-boundaries",
+    label: "Module Boundaries",
+    description: "Enforce clear module boundaries and layering",
+    category: "infra",
+    appliesWhen: { always: true },
+    guidance:
+      "Maintain clean module boundaries to avoid circular dependencies.",
+  } as const satisfies IRulePackDescriptor,
+
+  "code-flow": {
+    id: "code-flow",
+    label: "Code Flow",
+    description: "Control flow clarity and early returns",
+    category: "language",
+    appliesWhen: { always: true },
+    guidance: "Keep control flow clear and readable with early returns.",
+  } as const satisfies IRulePackDescriptor,
+
+  "comment-hygiene": {
+    id: "comment-hygiene",
+    label: "Comment Hygiene",
+    description: "Meaningful comments and documentation standards",
+    category: "language",
+    appliesWhen: { always: true },
+    guidance: "Write comments that explain intent, not what the code does.",
+  } as const satisfies IRulePackDescriptor,
+
+  "structured-logging": {
+    id: "structured-logging",
+    label: "Structured Logging",
+    description: "Logging patterns using Pino, Winston, or structured loggers",
+    category: "infra",
+    appliesWhen: { anyDeps: ["pino", "winston"] },
+    guidance: "Use structured logging with consistent JSON output.",
+  } as const satisfies IRulePackDescriptor,
+
+  "jwt-cookies": {
+    id: "jwt-cookies",
+    label: "JWT & Cookies",
+    description: "Secure JWT and cookie handling patterns",
+    category: "library",
+    appliesWhen: { anyDeps: ["jsonwebtoken", "jose"] },
+    guidance: "Implement JWT and cookies securely.",
+  } as const satisfies IRulePackDescriptor,
+
+  "oauth-security": {
+    id: "oauth-security",
+    label: "OAuth Security",
+    description: "OAuth and OpenID patterns and security considerations",
+    category: "library",
+    appliesWhen: { anyDeps: ["arctic", "openid-client", "passport"] },
+    guidance: "Follow OAuth/OpenID best practices.",
+  } as const satisfies IRulePackDescriptor,
+
+  "i18n-keys": {
+    id: "i18n-keys",
+    label: "i18n Keys",
+    description: "Internationalization key management and translation patterns",
+    category: "library",
+    appliesWhen: { anyDeps: ["i18next", "react-i18next"] },
+    guidance: "Keep i18n keys organized and validated.",
+  } as const satisfies IRulePackDescriptor,
+} as const;
+
+/** Ordered list of always-on pack IDs (for deterministic ordering). */
+export const ALWAYS_ON_PACKS = [
+  "generic-ts",
+  "env-access",
+  "module-boundaries",
+  "code-flow",
+  "comment-hygiene",
+] as const;
+
+/** Type-safe record of all pack descriptors. */
+export type IPackRegistry = typeof PACK_REGISTRY;
+
+/** Type-safe pack ID type. */
+export type IPackId = keyof IPackRegistry;

package/src/stack-detection/stack-detection.types.ts

@@ -0,0 +1,47 @@
+/** A detected technology stack profile that determines which rule packs to enable. */
+export interface IStackProfile {
+  /** Friendly stack name: "react", "node-backend", "generic", or combined like "react+drizzle". */
+  readonly name: string;
+
+  /** Enabled rule pack IDs, always includes "generic-ts" and other always-on packs. */
+  readonly packs: readonly string[];
+
+  /** How confident the detection is: "certain" (deps found), "likely" (files exist), "guess" (fallback). */
+  readonly confidence: "certain" | "likely" | "guess";
+
+  /** Human-readable reason for the profile, e.g., "react + drizzle-orm in package.json". */
+  readonly reason: string;
+}
+
+/** Metadata for a rule pack that determines when it should be enabled. */
+export interface IRulePackDescriptor {
+  /** Unique identifier for the pack, used in enabled lists. */
+  readonly id: string;
+
+  /** Human-readable label. */
+  readonly label: string;
+
+  /** Short description of what the pack covers. */
+  readonly description: string;
+
+  /** Category for UI/filtering: "language" | "framework" | "library" | "infra" | "testing". */
+  readonly category: "language" | "framework" | "library" | "infra" | "testing";
+
+  /** Conditions under which this pack should be enabled. */
+  readonly appliesWhen: {
+    /** Enable if ANY of these deps (in dependencies or devDependencies) are present. */
+    readonly anyDeps?: readonly string[];
+
+    /** Enable only if ALL of these deps are present. */
+    readonly allDeps?: readonly string[];
+
+    /** Enable if any of these file paths/globs exist. */
+    readonly files?: readonly string[];
+
+    /** Enable this pack unconditionally (used for always-on packs like generic-ts). */
+    readonly always?: boolean;
+  };
+
+  /** Short guidance text injected into system prompt when pack is active (populated in later tasks). */
+  readonly guidance?: string;
+}

package/src/validate/accept.ts

@@ -0,0 +1,49 @@
+import type { ITask } from "../spec";
+import { runShellCommand } from "../lib/fs";
+
+import type { IAcceptResult } from "./validate.types";
+
+/** Default kill-timeout for the GATE (ms). More generous than the `run` tool —
+ *  a web gate is `vite build` + headless chromium, legitimately slow — but still
+ *  bounded so a stuck build can't wedge the harness. TSFORGE_GATE_TIMEOUT_MS to
+ *  override (0 = no timeout). */
+const DEFAULT_GATE_TIMEOUT_MS = 600_000;
+
+function gateTimeoutMs(): number {
+  const env = Number(process.env.TSFORGE_GATE_TIMEOUT_MS);
+
+  return Number.isFinite(env) && env >= 0 ? env : DEFAULT_GATE_TIMEOUT_MS;
+}
+
+/** Optional knobs for `runAccept`: stream the output live (`onChunk`) and/or
+ *  cancel it (`signal`). */
+export interface IAcceptOptions {
+  onChunk?: (text: string) => void;
+  signal?: AbortSignal;
+}
+
+/**
+ * Run a task's `accept:` command in `cwd`. This is the deterministic oracle in
+ * miniature — pass/fail comes from the exit code, never from model judgment.
+ * Pass `onChunk` to stream the command's output live (the CLI does, so a slow
+ * gate like `vite build` + browser isn't silent); omit it and output is just
+ * captured (the eval path). Cancellable via `signal`, and killed after the gate
+ * timeout so a hung build can't wedge the harness.
+ */
+export async function runAccept(
+  task: ITask,
+  cwd: string,
+  opts: IAcceptOptions = {}
+): Promise<IAcceptResult> {
+  const run = await runShellCommand(cwd, task.accept, {
+    timeoutMs: gateTimeoutMs(),
+    ...(opts.onChunk === undefined ? {} : { onChunk: opts.onChunk }),
+    ...(opts.signal === undefined ? {} : { signal: opts.signal }),
+  });
+
+  const note = run.timedOut
+    ? `\n[gate killed after ${gateTimeoutMs()}ms timeout — TSFORGE_GATE_TIMEOUT_MS to change]`
+    : "";
+
+  return { passed: run.exitCode === 0, output: run.stdout + run.stderr + note };
+}

package/src/validate/errors.ts

@@ -0,0 +1,35 @@
+import type { ErrorSet, IErrorDiff } from "./validate.types";
+
+/** What changed between two cycles — the gradient the model descends. */
+export function diffErrorSets(prev: ErrorSet, next: ErrorSet): IErrorDiff {
+  const prevKeys = new Set(prev.map((e) => e.key));
+  const nextKeys = new Set(next.map((e) => e.key));
+
+  return {
+    fixed: prev.filter((e) => !nextKeys.has(e.key)),
+    introduced: next.filter((e) => !prevKeys.has(e.key)),
+    remaining: next.filter((e) => prevKeys.has(e.key)),
+  };
+}
+
+/** Progress = fewer errors than last cycle. */
+export function shrank(prev: ErrorSet, next: ErrorSet): boolean {
+  return next.length < prev.length;
+}
+
+/**
+ * True when two cycles produced the EXACT same error set (same keys). This —
+ * not "didn't shrink" — is the honest signal of a stuck model: it's spinning
+ * without changing the gate outcome at all. Any difference (fewer, more, or a
+ * different mix) means the model is still moving the problem and we keep going.
+ */
+export function sameErrorSet(prev: ErrorSet, next: ErrorSet): boolean {
+  if (prev.length !== next.length) {
+    return false;
+  }
+
+  const a = prev.map((e) => e.key).sort();
+  const b = next.map((e) => e.key).sort();
+
+  return a.every((key, i) => key === b[i]);
+}

package/src/validate/index.ts

@@ -0,0 +1,12 @@
+export * from "./validate.types";
+export { validate } from "./validate";
+export {
+  parseTsc,
+  genericErrors,
+  parseEslintJson,
+  combinedParser,
+  parserFor,
+} from "./parse";
+export { diffErrorSets, shrank, sameErrorSet } from "./errors";
+export { runTests, isRealRed } from "./run-tests";
+export { runAccept } from "./accept";

package/src/validate/parse.ts

@@ -0,0 +1,148 @@
+import type { IErrorItem, ErrorParserFn } from "./validate.types";
+import { isArray, isRecord } from "../lib/guards";
+
+const TSC = /^(.+?)\((\d+),(\d+)\): error (TS\d+): (.+)$/;
+
+/** Parse `tsc` output into a structured error set (one item per diagnostic). */
+export function parseTsc(output: string): IErrorItem[] {
+  const items: IErrorItem[] = [];
+
+  for (const line of output.split("\n")) {
+    const m = TSC.exec(line);
+
+    if (!m) {
+      continue;
+    }
+
+    const [, file, lineStr, , rule, message] = m;
+
+    if (
+      file === undefined ||
+      lineStr === undefined ||
+      rule === undefined ||
+      message === undefined
+    ) {
+      continue;
+    }
+
+    items.push({
+      key: `${file}:${lineStr}:${rule}`,
+      file,
+      line: Number(lineStr),
+      rule,
+      message: message.trim(),
+    });
+  }
+
+  return items;
+}
+
+/** Fallback when we have no tool-specific parser: the whole output is one error. */
+export function genericErrors(output: string): IErrorItem[] {
+  const text = output.trim();
+
+  return text.length > 0 ? [{ key: "raw", message: text.slice(0, 500) }] : [];
+}
+
+/**
+ * Parse `eslint --format json`. Errors (severity 2) only; warnings ignored.
+ * Carries the `ruleId` — including custom plugin rules like
+ * `@boring-stack/structured-logging` — so the repair loop sees exactly which
+ * rule failed. Narrowed with guards (no type assertions).
+ */
+export function parseEslintJson(output: string): IErrorItem[] {
+  let data: unknown;
+
+  try {
+    data = JSON.parse(output);
+  } catch {
+    return [];
+  }
+
+  if (!isArray(data)) {
+    return [];
+  }
+
+  return data.flatMap(eslintFileItems);
+}
+
+/** Error items from one eslint JSON file entry (severity-2 messages only). */
+function eslintFileItems(file: unknown): IErrorItem[] {
+  if (!isRecord(file)) {
+    return [];
+  }
+
+  const filePath = typeof file.filePath === "string" ? file.filePath : "";
+  const messages = file.messages;
+
+  if (!isArray(messages)) {
+    return [];
+  }
+
+  const items: IErrorItem[] = [];
+
+  for (const m of messages) {
+    if (!isRecord(m) || m.severity !== 2) {
+      continue;
+    }
+
+    const rule = typeof m.ruleId === "string" ? m.ruleId : "syntax";
+    const lineNo = typeof m.line === "number" ? m.line : undefined;
+    const message = typeof m.message === "string" ? m.message : "";
+
+    items.push({
+      key: `${filePath}:${lineNo ?? 0}:${rule}`,
+      file: filePath,
+      line: lineNo,
+      rule,
+      message: message.trim(),
+    });
+  }
+
+  return items;
+}
+
+/**
+ * For chained gates like `tsc -p … && eslint --format json … && bun test`,
+ * `&&` short-circuits: when tsc fails the output is tsc's TEXT (eslint never
+ * ran), and when it passes the output is eslint's JSON. A single tool-specific
+ * parser is wrong for both phases — pick eslint-json and tsc-text output parses
+ * to nothing (so the whole wall dumps as one blob); pick tsc and eslint's JSON
+ * is missed. Run BOTH and union: their formats don't overlap (tsc-text vs JSON),
+ * and only one is ever present at a time, so this is lossless either way.
+ */
+export function combinedParser(output: string): IErrorItem[] {
+  const merged = [...parseTsc(output), ...parseEslintJson(output)];
+  const seen = new Set<string>();
+
+  return merged.filter((e) => {
+    if (seen.has(e.key)) {
+      return false;
+    }
+
+    seen.add(e.key);
+
+    return true;
+  });
+}
+
+/** Pick a parser from the command. Add tools here as we support them. */
+export function parserFor(command: string): ErrorParserFn {
+  const hasTsc = /\btsc\b/.test(command);
+  const hasEslint = /\beslint\b/.test(command);
+
+  // A chained tsc+eslint gate needs the combined parser (see above).
+  if (hasTsc && hasEslint) {
+    return combinedParser;
+  }
+
+  if (hasEslint) {
+    return parseEslintJson;
+  }
+
+  if (hasTsc) {
+    return parseTsc;
+  }
+
+  return genericErrors;
+}

package/src/validate/run-tests.ts

@@ -0,0 +1,59 @@
+/**
+ * Run a single test file and report how many tests the runner collected.
+ *
+ * This is the deterministic answer to "are these real, runnable tests?" — we let
+ * `bun test` be the oracle rather than counting `test(` calls by regex. The
+ * load-bearing fact: an empty/vacuous file EXITS 0, so the exit code lies; only
+ * the collected count (`total >= 1`) proves the suite actually asserts anything.
+ */
+import { runArgvCommand } from "../lib/fs";
+
+import type { IRunTestsResult } from "./validate.types";
+
+export async function runTests(
+  testFile: string,
+  cwd: string
+): Promise<IRunTestsResult> {
+  // Route through the shared runner, which drains stdout/stderr CONCURRENTLY
+  // with the process. Awaiting `proc.exited` before reading (the old code) can
+  // deadlock when a chatty test fills the pipe buffer — the child blocks on a
+  // full pipe while we wait for an exit that never arrives.
+  const run = await runArgvCommand(cwd, ["bun", "test", testFile]);
+  const output = run.stdout + run.stderr;
+
+  return { ...countTests(output), output };
+}
+
+/**
+ * The deterministic "real, runnable, RED suite" predicate: loads cleanly, has
+ * tests, and every one fails against a do-nothing stub. Shared by test
+ * generation and review so "acceptable suite" means one thing everywhere.
+ */
+export function isRealRed(run: IRunTestsResult): boolean {
+  return run.errors === 0 && run.total >= 1 && run.pass === 0;
+}
+
+function countTests(output: string): {
+  pass: number;
+  fail: number;
+  total: number;
+  errors: number;
+} {
+  const pass = firstNumber(/(\d+)\s+pass/.exec(output));
+  const fail = firstNumber(/(\d+)\s+fail/.exec(output));
+  const ran = /Ran\s+(\d+)\s+tests?/.exec(output);
+  const total = ran !== null ? firstNumber(ran) : pass + fail;
+
+  const counted = firstNumber(/(\d+)\s+error/.exec(output));
+  // bun sometimes prints the banner without a count; treat it as one error.
+  const errors =
+    counted > 0 || !output.includes("Unhandled error") ? counted : 1;
+
+  return { pass, fail, total, errors };
+}
+
+function firstNumber(match: RegExpExecArray | null): number {
+  const raw = match?.[1];
+
+  return raw === undefined ? 0 : Number(raw);
+}

package/src/validate/validate.ts

@@ -0,0 +1,40 @@
+import type { ITask } from "../spec";
+import type { ErrorParser, ErrorSet, IValidateResult } from "./validate.types";
+import { runAccept, type IAcceptOptions } from "./accept";
+import { parserFor } from "./parse";
+
+/**
+ * Run a task's gate and turn the result into a structured error set. When no
+ * parser is given, one is auto-picked from the command (tsc/eslint/generic).
+ * `opts` forwards live-output streaming (`onChunk`) and cancellation (`signal`)
+ * down to the gate process.
+ */
+export async function validate(
+  task: ITask,
+  cwd: string,
+  parse?: ErrorParser,
+  opts: IAcceptOptions = {}
+): Promise<IValidateResult> {
+  const parser = parse ?? parserFor(task.accept);
+  const r = await runAccept(task, cwd, opts);
+
+  if (r.passed) {
+    return { passed: true, errors: [], output: r.output };
+  }
+
+  // A failing gate must surface at least one error, even with empty output.
+  const parsed = parser(r.output);
+  const trimmed = r.output.trim();
+  const fallback: ErrorSet = [
+    {
+      key: "nonzero",
+      message: trimmed.length > 0 ? trimmed : "command exited non-zero",
+    },
+  ];
+
+  return {
+    passed: false,
+    errors: parsed.length > 0 ? parsed : fallback,
+    output: r.output,
+  };
+}

package/src/validate/validate.types.ts

@@ -0,0 +1,52 @@
+/** One failure from the gate, with a stable key so we can diff across cycles. */
+export interface IErrorItem {
+  key: string;
+  file?: string;
+  line?: number;
+  rule?: string;
+  message: string;
+}
+
+export type ErrorSet = IErrorItem[];
+
+export interface IErrorDiff {
+  fixed: ErrorSet;
+  introduced: ErrorSet;
+  remaining: ErrorSet;
+}
+
+/** Parse raw gate output (tsc/eslint/test) into a structured error set. */
+export type ErrorParser = (output: string) => IErrorItem[];
+
+/** Alias kept for the parser-registry call sites. */
+export type ErrorParserFn = ErrorParser;
+
+export interface IValidateResult {
+  passed: boolean;
+  errors: ErrorSet;
+  output: string;
+}
+
+export interface IRunTestsResult {
+  /** Tests that passed. */
+  pass: number;
+  /** Tests that failed. */
+  fail: number;
+  /** Total tests the runner collected. 0 means empty/unparseable/vacuous. */
+  total: number;
+  /**
+   * Load/parse errors (missing import, syntax error). bun reports these as a
+   * failing "test", so `errors > 0` tells "ran and some assertions failed"
+   * (RED) from "the file never loaded".
+   */
+  errors: number;
+  /** Combined stdout + stderr, for feeding a failure back to the model. */
+  output: string;
+}
+
+export interface IAcceptResult {
+  /** True when the command exits 0. */
+  passed: boolean;
+  /** Combined stdout + stderr, for feeding back into the loop. */
+  output: string;
+}