@agjs/tsforge 0.1.14 → 0.1.15

package/scripts/benchmark-catalog.ts

@@ -0,0 +1,387 @@
+// The TSForge benchmark catalog — a FIXED pool of production-grade app domains
+// (per ChatGPT's guidance, 2026-06-08) used to drive the headless self-improvement
+// loop. A fixed catalog (not generator-invented prompts) is deliberate: it kills
+// the variety-noise that made the overnight apps converge to one CRUD shape, and
+// every domain is chosen to force complex type relationships, async state, forms,
+// permissions, nested entities and edge cases — where a 27b starts to break down.
+//
+// The generation spec is ChatGPT's stress-test spec RECONCILED to our boringstack
+// per-feature layout (user decision 2026-06-08): the layout differs from ChatGPT's
+// by-layer folders, but the SEPARATION it demands (UI / logic / validation / types)
+// is satisfied per-domain instead of in global folders.
+
+export interface IBenchmarkApp {
+  readonly slug: string;
+  readonly name: string;
+  /** One line on what the app IS — keeps each domain genuinely distinct. */
+  readonly summary: string;
+  /** ≥8 entity types the model must model (the domain's data spine). */
+  readonly entities: readonly string[];
+  /** The concrete user flows that exercise forms / async / edge cases. */
+  readonly flows: readonly string[];
+}
+
+export const BENCHMARK_CATALOG: readonly IBenchmarkApp[] = [
+  {
+    slug: "saas-crm",
+    name: "Multi-tenant SaaS CRM",
+    summary:
+      "A sales CRM scoped to an organization (tenant), with accounts, contacts, deals moving through a pipeline, and per-user roles.",
+    entities: [
+      "Organization (tenant)",
+      "User (with Role: owner | admin | rep)",
+      "Account",
+      "Contact",
+      "Deal (with a Stage discriminated union)",
+      "Activity (call | email | meeting — discriminated)",
+      "Note",
+      "Tag",
+    ],
+    flows: [
+      "Dashboard: pipeline value by stage, win-rate, recent activity",
+      "Accounts list (search/filter/sort/paginate) → account detail with contacts + deals",
+      "Create/edit a deal (nested contact picker, conditional 'lost reason' when stage=lost)",
+      "Log an activity against a contact (discriminated form: fields change by type)",
+      "Optimistic stage change on the deal board with rollback on failure",
+    ],
+  },
+  {
+    slug: "udemy",
+    name: "Online Course Marketplace",
+    summary:
+      "A Udemy-like learning marketplace: instructors publish courses made of sections and lessons; students enrol, track progress, and leave reviews.",
+    entities: [
+      "User (with Role: student | instructor | admin)",
+      "Course",
+      "Section",
+      "Lesson (with Content: video | article | quiz — discriminated)",
+      "Enrollment (with progress)",
+      "Review (rating 1-5)",
+      "Category",
+      "Coupon (with Discount: percentage | fixed — discriminated)",
+    ],
+    flows: [
+      "Catalog: browse/search courses, filter by category + rating + price, paginate",
+      "Course detail: curriculum (sections → lessons), instructor bio, reviews, enrol button",
+      "Instructor studio: create/edit a course, add sections, add lessons (discriminated form — fields change by content type)",
+      "My learning: enrolled courses with progress bars, mark a lesson complete (optimistic) with rollback",
+      "Apply a coupon at enrol (discriminated discount math); leave a review after enrolling",
+    ],
+  },
+  {
+    slug: "pm-platform",
+    name: "Project Management Platform",
+    summary:
+      "A Linear/Jira-like issue tracker: projects contain issues with status, priority, assignees, sub-tasks and comments.",
+    entities: [
+      "Workspace",
+      "Project",
+      "Issue (Status + Priority discriminated)",
+      "SubTask",
+      "User",
+      "Label",
+      "Comment",
+      "Milestone",
+    ],
+    flows: [
+      "Dashboard: issues by status, overdue count, per-assignee load",
+      "Issue list with multi-facet filters (status, priority, assignee, label) + sort + pagination",
+      "Issue detail: edit inline, add sub-tasks, comment thread",
+      "Create issue (conditional fields: estimate only when type=story; due-date validation)",
+      "Optimistic status drag with rollback; cached project data reused across views",
+    ],
+  },
+  {
+    slug: "hospital-scheduling",
+    name: "Hospital Scheduling System",
+    summary:
+      "Schedule patient appointments against clinicians, rooms and shifts, with conflict detection and waitlists.",
+    entities: [
+      "Clinician (with Specialty)",
+      "Patient",
+      "Appointment (Status discriminated)",
+      "Room",
+      "Shift",
+      "Department",
+      "WaitlistEntry",
+      "InsurancePlan",
+    ],
+    flows: [
+      "Dashboard: today's schedule, utilization per room, no-show rate",
+      "Calendar/list of appointments, filterable by department/clinician/status",
+      "Book appointment (validate against clinician shift + room conflict; conditional referral field)",
+      "Reschedule with optimistic update + conflict rollback",
+      "Waitlist promotion when a slot frees up",
+    ],
+  },
+  {
+    slug: "warehouse-inventory",
+    name: "Warehouse Inventory Management",
+    summary:
+      "Track SKUs across warehouses and bins, with stock movements, purchase orders and low-stock reordering.",
+    entities: [
+      "Product (SKU)",
+      "Warehouse",
+      "Bin",
+      "StockLevel",
+      "StockMovement (receipt | transfer | adjustment — discriminated)",
+      "PurchaseOrder (Status discriminated)",
+      "Supplier",
+      "Category",
+    ],
+    flows: [
+      "Dashboard: total stock value, low-stock alerts, movements over time",
+      "Product list with search/filter by category & stock status, sort, paginate",
+      "Product detail: stock by warehouse/bin, movement history",
+      "Create a stock movement (discriminated form; transfer requires from+to bins)",
+      "Raise a purchase order (nested line items, async submit, success/error states)",
+    ],
+  },
+  {
+    slug: "airline-ops",
+    name: "Airline Operations Dashboard",
+    summary:
+      "Monitor flights, aircraft, crew assignments and gates, with delay tracking and disruption handling.",
+    entities: [
+      "Flight (Status discriminated: scheduled | boarding | departed | delayed | cancelled)",
+      "Aircraft",
+      "Airport",
+      "CrewMember (with Role)",
+      "CrewAssignment",
+      "Gate",
+      "Route",
+      "Disruption",
+    ],
+    flows: [
+      "Ops dashboard: on-time %, delays by cause, aircraft utilization",
+      "Flight board with filters (status, route, aircraft) + sort by departure + paginate",
+      "Flight detail: crew roster, gate, timeline; reassign a gate optimistically",
+      "Log a disruption (discriminated by cause; conditional weather/technical fields)",
+      "Crew assignment form with validation (rest-hours rule) + async submit",
+    ],
+  },
+  {
+    slug: "portfolio-manager",
+    name: "Investment Portfolio Manager",
+    summary:
+      "Manage portfolios of holdings across asset classes, with transactions, allocations and performance.",
+    entities: [
+      "Portfolio",
+      "Holding",
+      "Asset (AssetClass discriminated: equity | bond | cash | fund)",
+      "Transaction (buy | sell | dividend — discriminated)",
+      "Account",
+      "Watchlist",
+      "PriceQuote",
+      "AllocationTarget",
+    ],
+    flows: [
+      "Dashboard: total value, allocation pie, gain/loss, top movers",
+      "Holdings table (search/filter by asset class, sort by value/return, paginate)",
+      "Holding detail: transaction history, allocation vs target",
+      "Record a transaction (discriminated form; sell validates against quantity held)",
+      "Rebalance workflow: optimistic allocation edits with cached quotes",
+    ],
+  },
+  {
+    slug: "procurement",
+    name: "Procurement & Vendor Platform",
+    summary:
+      "Manage vendors, requisitions, purchase orders and approvals through an approval chain.",
+    entities: [
+      "Vendor",
+      "Requisition (Status discriminated)",
+      "PurchaseOrder",
+      "LineItem",
+      "ApprovalStep",
+      "Contract",
+      "Budget",
+      "User (with ApprovalRole)",
+    ],
+    flows: [
+      "Dashboard: spend by category, pending approvals, budget burn",
+      "Requisition list with filters (status, requester, budget) + sort + paginate",
+      "Requisition detail: line items, approval chain progress",
+      "Create requisition (nested line items, conditional justification when over budget)",
+      "Approve/reject step with optimistic update + rollback on async failure",
+    ],
+  },
+  {
+    slug: "billing-console",
+    name: "Subscription Billing Console",
+    summary:
+      "Manage customers, subscription plans, invoices and payments, with proration and dunning.",
+    entities: [
+      "Customer",
+      "Plan (BillingInterval discriminated)",
+      "Subscription (Status discriminated: trialing | active | past_due | canceled)",
+      "Invoice (Status discriminated)",
+      "InvoiceLineItem",
+      "Payment (method discriminated: card | bank | credit)",
+      "Coupon",
+      "UsageRecord",
+    ],
+    flows: [
+      "Dashboard: MRR, churn, overdue invoices, revenue trend",
+      "Invoice list (search/filter by status & customer, sort, paginate)",
+      "Customer detail: subscription, invoices, payment methods",
+      "Change plan (proration preview; conditional coupon field; async submit)",
+      "Record a payment (discriminated by method) with optimistic invoice status update",
+    ],
+  },
+  {
+    slug: "ecommerce-admin",
+    name: "E-commerce Admin Suite",
+    summary:
+      "Back-office for an online store: products with variants, orders, fulfilment, customers and discounts.",
+    entities: [
+      "Product",
+      "Variant",
+      "Order (Status discriminated: pending | paid | fulfilled | refunded)",
+      "OrderItem",
+      "Customer",
+      "Discount (type discriminated: percent | fixed | bogo)",
+      "Fulfilment",
+      "Category",
+    ],
+    flows: [
+      "Dashboard: sales today, top products, orders by status, low stock",
+      "Order list with filters (status, customer, date) + sort + paginate",
+      "Order detail: items, fulfilment timeline, refund workflow",
+      "Create/edit a product (nested variants array; conditional inventory per variant)",
+      "Create a discount (discriminated form; optimistic apply with rollback)",
+    ],
+  },
+  {
+    slug: "incident-management",
+    name: "Incident Management Platform",
+    summary:
+      "Track operational incidents, severity, services affected, on-call responders, timelines and postmortems.",
+    entities: [
+      "Incident (Severity + Status discriminated)",
+      "Service",
+      "Responder",
+      "OnCallSchedule",
+      "TimelineEvent (type discriminated)",
+      "Postmortem",
+      "AlertRule",
+      "Team",
+    ],
+    flows: [
+      "Dashboard: open incidents by severity, MTTR, services at risk",
+      "Incident list with filters (severity, status, service, team) + sort + paginate",
+      "Incident detail: timeline, responders, status updates",
+      "Declare incident (conditional fields by severity; async submit; validation)",
+      "Post a timeline update (discriminated event form) with optimistic append + rollback",
+    ],
+  },
+];
+
+/**
+ * The generation spec — ChatGPT's production-grade stress-test, reconciled to our
+ * boringstack per-feature layout. Shared verbatim across every benchmark domain so
+ * results are comparable; only the DOMAIN section (built per app) changes.
+ */
+export const GENERATION_SPEC = `You are building a PRODUCTION-GRADE React + Vite + TypeScript application — not a demo.
+The goal is a real, complete app a company would actually ship. Build the WHOLE thing; do not simplify, stub, or leave anything incomplete.
+
+# Hard rules (the gate enforces these — code that breaks them does not pass)
+FORBIDDEN: \`any\`, \`as\` casts (except \`as const\`), \`@ts-ignore\`/\`@ts-nocheck\`, non-null \`!\`, placeholder/TODO/dead code, fake or partial implementations.
+REQUIRED: strict typing everywhere; interfaces are \`I\`-prefixed (\`IInvoice\`); ONE React component per .tsx file; functional components only.
+
+# Type safety
+Every entity has explicit types. Use discriminated unions, branded IDs where useful, \`readonly\` where appropriate, and EXHAUSTIVE \`switch\` statements to narrow them. Use a \`Result<T, E>\` style ONLY for genuinely fallible RUNTIME ops (e.g. a mock-async service call that can fail) — never for data you already typed.
+There is NO backend, network, or uploaded data in this app: EVERY value originates from your own typed code + seed, so TypeScript has already proven its shape. The TYPE SYSTEM is the validation. NEVER write runtime parsers, entity validators, type-guard functions, or a \`*.validators.ts\` to "check" data the compiler already guarantees — type it correctly at the source and use it directly (\`x satisfies IType\` for a literal). Never use \`any\`, \`Record<string, any>\`, or \`as\` casts.
+
+# UI surface (all of these must exist and work)
+Dashboard · list view · detail view · creation workflow · editing workflow · search · filtering · sorting · pagination · modal workflow · form validation · toast notifications · loading states · error states · empty states.
+
+# State
+local state · derived state · async state · optimistic updates (with rollback on failure) · cached data · filtering/sorting/selection state.
+
+# Forms (≥3)
+Each form: validation · nested fields · conditional fields · async submission · error handling · success handling.
+
+# Async / errors
+Every async workflow handles loading, success, failure AND retry. No silent failures.
+
+# Accessibility
+Keyboard navigation, proper labels, aria attributes, focus management, accessible dialogs.
+
+# Project structure — BORINGSTACK, per-feature (NOT by-layer)
+Co-locate by domain under \`src/features/<domain>/\`:
+  <domain>.types.ts        — entity types, discriminated unions, branded IDs
+  <domain>.constants.ts    — \`as const\` registries / label maps (typed Record<Union, V>)
+  <domain>.service.ts      — async data access (seeded/mock async with latency + failure paths)
+  <domain>.hooks.ts        — ONLY genuine derived/computed state (the data hook is the SDK's useCollection; do NOT write a fetch/query wrapper)
+  <PascalCase>.tsx         — ONE component per file
+  index.ts                 — barrel re-exporting the public surface
+Shared shadcn primitives live in \`src/components/ui/\` (already scaffolded). Routes/pages are TanStack files under \`src/routes/\`.
+This separates UI / business logic / data access / type definitions — colocated per domain, not in global folders.
+
+# Domain complexity (minimum bar)
+≥8 entity types · 20+ interfaces/types · multiple relationships · nested structures · enums-as-const · discriminated unions.
+
+# Deliverables
+Generate ALL files. Imports must resolve. TypeScript must compile (strict). React must render (no blank screen). Every listed user flow must be implemented and reachable in the UI. Do NOT simplify the requirements.`;
+
+/** Compose the full build prompt for one benchmark domain. */
+export function buildBenchmarkPrompt(app: IBenchmarkApp): string {
+  const entities = app.entities.map((e) => `  - ${e}`).join("\n");
+  const flows = app.flows.map((f) => `  - ${f}`).join("\n");
+
+  return `${GENERATION_SPEC}
+
+# THE APP TO BUILD: ${app.name}
+${app.summary}
+
+## Entities to model (at least these)
+${entities}
+
+## User flows to implement
+${flows}
+
+Build this specific application, in full, following every rule above.`;
+}
+
+/** Look up a benchmark app by slug or 1-based catalog index; undefined if absent. */
+export function findBenchmarkApp(selector: string): IBenchmarkApp | undefined {
+  const bySlug = BENCHMARK_CATALOG.find((app) => app.slug === selector);
+
+  if (bySlug !== undefined) {
+    return bySlug;
+  }
+
+  const index = Number(selector);
+
+  if (
+    Number.isInteger(index) &&
+    index >= 1 &&
+    index <= BENCHMARK_CATALOG.length
+  ) {
+    return BENCHMARK_CATALOG[index - 1];
+  }
+
+  return undefined;
+}
+
+/**
+ * The JUDGE rubric (ChatGPT's grading prompt) — for the OFFLINE flagship review of
+ * a built app (never a runtime dependency). Pair with rejudge.ts / a flagship judge
+ * via TSFORGE_JUDGE_*; it grades the diff against the same bar the spec demands.
+ */
+export const JUDGE_RUBRIC = `You are grading a React + Vite + TypeScript application built by a coding system, against a production-grade bar. Be a harsh, specific senior reviewer. Score 1-5 overall and per-dimension, and list concrete defects (file + what's wrong).
+
+Dimensions:
+1. Type safety — discriminated unions, branded IDs, readonly, exhaustive switches, Result<T,E> for genuinely-fallible runtime ops; NO any/as/!/Record<string,any>. PENALIZE runtime parsers/entity-validators/type-guards/*.validators.ts that "check" already-typed seed data — there is no untrusted input, so that is dead ceremony, not type safety.
+2. State management — local/derived/async/optimistic(+rollback)/cached/filter/sort/selection actually present and correct.
+3. Component architecture — one component per file, clean props, no god-components, sensible composition.
+4. Forms — ≥3 with validation, nested + conditional fields, async submit, error AND success handling.
+5. Data modeling — ≥8 entities, 20+ types, real relationships, nested structures.
+6. Error/async handling — every async path handles loading/success/failure/retry; no silent failures.
+7. UI completeness — dashboard, list, detail, create, edit, search, filter, sort, paginate, modal, toasts, loading/error/empty states ALL present and reachable.
+8. Accessibility — keyboard nav, labels, aria, focus management, accessible dialogs.
+9. Runtime robustness — renders (no blank screen), survives interaction, no console/uncaught errors.
+10. Realism — feels like a real company app, not a toy.
+
+For each dimension: score + the single most important defect. Then an overall score and the top 3 things to fix. Penalize HARD for: missing flows, stubbed/placeholder code, type holes, blank-screen or crash-on-interaction.`;

package/scripts/browser-check.ts

@@ -0,0 +1,87 @@
+// Gate-runnable browser check: render an HTML file in headless chromium (served
+// over http) and exit non-zero (printing failures) if it errors or fails its
+// checks. Used as part of a gate for web builds — proves the page actually runs
+// AND behaves.
+//
+//   bun browser-check.ts <htmlFile>                 # render-only (no errors)
+//   bun browser-check.ts <htmlFile> --smoke         # render + generic behaviour smoke
+//   bun browser-check.ts <htmlFile> <checks.json>   # render + interaction checks
+//   bun browser-check.ts <htmlFile> <selector> [text]
+import { readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { renderCheck, parseChecks, type IRenderOptions } from "../src/browser";
+import { crawlableRoutePaths } from "../src/web-routes";
+
+const rawArgs = process.argv.slice(2);
+const smoke = rawArgs.includes("--smoke");
+const crawl = rawArgs.includes("--crawl");
+const [file, arg2, arg3] = rawArgs.filter(
+  (a) => a !== "--smoke" && a !== "--crawl"
+);
+
+if (file === undefined) {
+  process.stderr.write(
+    "usage: browser-check.ts <htmlFile> [--smoke] [--crawl] [checks.json | selector [text]]\n"
+  );
+  process.exit(2);
+}
+
+/** With --crawl, enumerate the app's static routes from `<buildDir>/src/routes/`
+ *  (the build dir is the parent of dist/) so every page — not just the home —
+ *  is render-checked. Dynamic ($param) routes are skipped. */
+async function routesFor(): Promise<string[]> {
+  if (!crawl) {
+    return [];
+  }
+
+  const routesDir = join(dirname(dirname(file ?? ".")), "src", "routes");
+
+  try {
+    const files = await readdir(routesDir);
+
+    return crawlableRoutePaths(files.filter((f) => f.endsWith(".tsx")));
+  } catch {
+    return [];
+  }
+}
+
+async function checksFor(): Promise<Partial<IRenderOptions>> {
+  if (arg2 === undefined) {
+    return {};
+  }
+
+  if (arg2.endsWith(".json")) {
+    const file = Bun.file(arg2);
+
+    // Tolerate a missing checks file → render-only (the model may not write one).
+    if (!(await file.exists())) {
+      return {};
+    }
+
+    return parseChecks(JSON.parse(await file.text()));
+  }
+
+  return {
+    expect: { selector: arg2, ...(arg3 !== undefined ? { text: arg3 } : {}) },
+  };
+}
+
+const result = await renderCheck({
+  file,
+  smoke,
+  routes: await routesFor(),
+  ...(await checksFor()),
+});
+
+if (result.ok) {
+  process.stdout.write(`browser-check: ${file} renders + behaves correctly\n`);
+  process.exit(0);
+}
+
+process.stdout.write(`browser-check FAILED for ${file}:\n`);
+
+for (const error of result.errors) {
+  process.stdout.write(`  - ${error}\n`);
+}
+
+process.exit(1);

package/scripts/build-rule-docs.ts

@@ -0,0 +1,122 @@
+// Offline cache builder: fetch typescript-eslint rule docs from their own
+// source `.mdx`, parse the ❌/✅ examples deterministically, and also scrape
+// tsforge pack rule descriptions, then write the committed cache the repair
+// loop reads. Run when rules change:
+//   bun run packages/core/scripts/build-rule-docs.ts
+import { join } from "node:path";
+import { parseRuleMdx, type IRuleDoc } from "../src/loop/feedback/rule-docs";
+import { RULE_PACKS } from "../src/rule-packs";
+
+const BASE =
+  "https://raw.githubusercontent.com/typescript-eslint/typescript-eslint/main/packages/eslint-plugin/docs/rules";
+
+// The strict-mode rules that actually fire on TypeScript — the ones a repair
+// loop hits. Curated entries in rule-docs.ts override these where they exist.
+const RULES = [
+  "no-explicit-any",
+  "no-unsafe-argument",
+  "no-unsafe-assignment",
+  "no-unsafe-call",
+  "no-unsafe-member-access",
+  "no-unsafe-return",
+  "no-non-null-assertion",
+  "restrict-plus-operands",
+  "restrict-template-expressions",
+  "strict-boolean-expressions",
+  "no-floating-promises",
+  "no-misused-promises",
+  "await-thenable",
+  "no-for-in-array",
+  "prefer-nullish-coalescing",
+  "prefer-optional-chain",
+  "no-unnecessary-condition",
+  "no-unnecessary-type-assertion",
+  "switch-exhaustiveness-check",
+  "consistent-type-assertions",
+  "no-base-to-string",
+  "require-await",
+  "no-confusing-void-expression",
+  "no-redundant-type-constituents",
+  "prefer-reduce-type-parameter",
+];
+
+function getRuleDescription(obj: unknown): string | undefined {
+  const isObject = (val: unknown): val is Record<string, unknown> =>
+    val !== null && typeof val === "object";
+
+  if (!isObject(obj)) {
+    return undefined;
+  }
+
+  const meta = obj.meta;
+
+  if (!isObject(meta)) {
+    return undefined;
+  }
+
+  const docs = meta.docs;
+
+  if (!isObject(docs)) {
+    return undefined;
+  }
+
+  const description = docs.description;
+
+  return typeof description === "string" ? description : undefined;
+}
+
+const out: Record<string, IRuleDoc> = {};
+let ok = 0;
+let missed = 0;
+
+for (const rule of RULES) {
+  const res = await fetch(`${BASE}/${rule}.mdx`);
+
+  if (!res.ok) {
+    process.stdout.write(`  miss ${rule} (HTTP ${res.status})\n`);
+    missed += 1;
+    continue;
+  }
+
+  const doc = parseRuleMdx(await res.text());
+
+  if (doc === null) {
+    process.stdout.write(`  miss ${rule} (unparseable)\n`);
+    missed += 1;
+    continue;
+  }
+
+  out[`@typescript-eslint/${rule}`] = doc;
+  ok += 1;
+}
+
+// Add tsforge pack rules: extract description from rule meta.
+let packRulesAdded = 0;
+
+for (const pack of Object.values(RULE_PACKS)) {
+  for (const [ruleName, ruleModule] of Object.entries(pack.rules)) {
+    const ruleId = `tsforge/${ruleName}`;
+    const description = getRuleDescription(ruleModule) ?? ruleName;
+
+    out[ruleId] = {
+      what: description,
+      bad: `// Example that violates the rule`,
+      good: `// Corrected version`,
+    };
+
+    packRulesAdded += 1;
+  }
+}
+
+const path = join(
+  import.meta.dir,
+  "..",
+  "src",
+  "loop",
+  "rule-docs.generated.json"
+);
+
+await Bun.write(path, `${JSON.stringify(out, null, 2)}\n`);
+process.stdout.write(
+  `\nwrote ${ok} eslint rules (${missed} missed), ${packRulesAdded} pack rules → ${path}\n`
+);