@agjs/tsforge 0.2.6 → 0.2.7

package/package.json

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

package/src/cli.ts

@@ -2,13 +2,7 @@
 import { join, isAbsolute } from "node:path";
 import { appendFileSync, mkdirSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
-import {
-  runTask,
-  RUN_STATUS,
-  Session,
-  PLAN_APPROVED_NOTE,
-  LOOP_LIMITS,
-} from "./loop";
+import { runTask, RUN_STATUS, Session, PLAN_APPROVED_NOTE } from "./loop";
 import {
   PROVIDER_LIMITS,
   PROVIDER_DEFAULTS,
@@ -997,9 +991,10 @@ async function repl(args: ICliArgs): Promise<number> {
     session.setFix(buildWebFix(framework));
     session.setIncrementalCheck(buildWebTscCheck());
     session.guide(webGuidance(framework));
-    // A from-scratch web build needs the big turn budget — the default cap was
-    // measured to cut a todo app off mid-write, before its gate ever ran.
-    session.setMaxTurns(LOOP_LIMITS.webMaxTurns);
+    // A from-scratch web build legitimately needs many turns. Don't pin a low
+    // ceiling here — the interactive session already rides the high runaway
+    // backstop (interactiveBackstopTurns) and stops on the progress guards, so a
+    // long, converging build is never cut off mid-write.
   };
 
   // The `scaffold_web` tool invokes this when the AGENT decides to build a web app

package/src/loop/loop.constants.ts

@@ -31,17 +31,31 @@ export const LOOP_LIMITS = {
    */
   maxEditLines: 50,
   /**
-   * Give up after the gate shows the EXACT same error set this many edits in a
-   * row (genuine spinning). Generous; the turn cap is the real backstop.
+   * Give up after the gate shows the EXACT same error SET this many edits in a
+   * row (genuine spinning) — the coarse net. The finer `samePersist` guard
+   * (below) usually trips first; this catches a stable-but-shuffling set.
    */
-  gateStuckRepeats: 10,
+  gateStuckRepeats: 6,
+  /**
+   * The PRIMARY no-progress guard: give up when a SINGLE error — same (file,rule)
+   * key — survives this many consecutive gate cycles, i.e. the model keeps failing
+   * at the same thing N attempts running, even while OTHER errors churn around it.
+   * This (not a raw turn count) is how the loop decides it's genuinely stuck.
+   */
+  samePersist: 5,
   /**
    * Above this many chars of combined file content, the seed prompt sends a
    * navigable project MAP instead of full dumps. Below it, full dumps.
    */
   mapThresholdChars: 12000,
-  /** Hard backstop on model turns per task. */
+  /** Hard backstop on model turns per HEADLESS task (eval/cron — no human to
+   *  intervene). Interactive sessions use `interactiveBackstopTurns` instead. */
   maxTurns: 40,
+  /** Interactive runaway safety only — NOT the primary stop. A human is present
+   *  and can interrupt, and the progress guards (`samePersist` / `gateStuckRepeats`)
+   *  pull the agent out the moment it stops converging, so this is set high enough
+   *  that normal long, productive back-and-forth never trips it. */
+  interactiveBackstopTurns: 250,
   /** Turn budget for a from-scratch WEB build (heavy gate, many files): used by
    *  headless web builds AND applied when an interactive session scaffolds via
    *  `scaffold_web` — measured: a todo app was still WRITING components when it

package/src/loop/loop.types.ts

@@ -37,6 +37,8 @@ export interface ILoopEvent {
    *  reads to tell a type error from a lint rule, not just a count. */
   rules?: readonly string[];
   passed?: boolean;
+  /** For `stuck` events: a human-readable blocker diagnosis. */
+  detail?: string;
   file?: string;
   /** For `create` events: the new file's content (rendered as a code block). */
   content?: string;
@@ -82,6 +84,9 @@ export interface IRunResult {
   /** Model turns used. */
   cycles: number;
   reason?: StuckReason;
+  /** When stuck: a human-readable blocker diagnosis (the persistent rule/file +
+   *  last error) so an interactive session can hand back something actionable. */
+  detail?: string;
   /** Edits/creates applied to editable files (measure edit churn). */
   edits?: number;
   /** Times an edit RAISED the gate error count (regressions). */

package/src/loop/rule-docs.generated.json

@@ -109,6 +109,21 @@
     "bad": "[1, 2, 3].reduce((arr, num) => arr.concat(num * 2), [] as number[]);\n\n['a', 'b'].reduce(\n  (accumulator, name) => ({\n    ...accumulator,\n    [name]: true,\n  }),\n  {} as Record<string, boolean>,",
     "good": "[1, 2, 3].reduce<number[]>((arr, num) => arr.concat(num * 2), []);\n\n['a', 'b'].reduce<Record<string, boolean>>(\n  (accumulator, name) => ({\n    ...accumulator,\n    [name]: true,\n  }),\n  {},"
   },
+  "tsforge/id-param-requires-object-authz": {
+    "what": "Warn when a handler reads `params.id` and queries the database without an authorization check in the same function.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/mutating-route-requires-authz": {
+    "what": "POST/PUT/PATCH/DELETE route handlers must call an authorization helper before mutating state.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/server-action-requires-authz": {
+    "what": "Files with `\"use server\"` that perform database mutations must call an authorization helper in the same function.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/job-name-must-be-constant": {
     "what": "Disallow string-literal job names in `<queue>.add(name, ...)` calls — use a constant identifier so all consumers share one source of truth.",
     "bad": "// Example that violates the rule",
@@ -219,6 +234,16 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/update-delete-account-scoped-must-filter-scope": {
+    "what": "Require Drizzle `.update()` / `.delete()` against account-scoped tables to filter by a scope column in `.where()`.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/update-delete-must-have-where": {
+    "what": "Require every Drizzle `.update()` and `.delete()` call to include a `.where()` clause — unscoped writes affect every row.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/consistent-status-via-set": {
     "what": "Inside Elysia route handlers, set HTTP status via `set.status = N`, not by returning a `new Response(body, { status: N })`.",
     "bad": "// Example that violates the rule",
@@ -319,11 +344,26 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/auth-cookie-must-set-maxage-or-expires": {
+    "what": "Auth-cookie writes should set `maxAge` or `expires` so session cookies do not live forever by default.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/auth-cookie-must-set-samesite": {
+    "what": "Auth-cookie writes must set `sameSite` (`strict` or `lax`) — missing SameSite allows cross-site cookie delivery.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/bcrypt-rounds-min": {
     "what": "Disallow `bcrypt.hash` / `bcrypt.hashSync` calls with a numeric-literal rounds value below the configured minimum (default 10).",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/jwt-must-verify-not-decode": {
+    "what": "Disallow `jwt.decode` / `decodeJwt` — decoding without verification accepts forged tokens. Use `jwt.verify` or `jwtVerify` instead.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-import-build-output": {
     "what": "Disallow importing from build/output directories within the project. Source must import source, not compiled artifacts, to avoid stale-code drift and broken module boundaries.",
     "bad": "// Example that violates the rule",
@@ -354,6 +394,11 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/mutation-should-revalidate-cache": {
+    "what": "After database mutations in server actions or route handlers, call `revalidatePath` or `revalidateTag` so cached pages reflect the change.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-html-img-element": {
     "what": "Prefer next/image over raw <img> elements for optimized responsive images and Core Web Vitals.",
     "bad": "// Example that violates the rule",
@@ -374,6 +419,11 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-secret-props-to-client": {
+    "what": "Warn when Server Components pass secret-looking props to JSX — values may cross the client boundary.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-sensitive-next-public-env": {
     "what": "Disallow NEXT_PUBLIC_* env vars whose names suggest secrets — public build-time vars are visible in the client bundle.",
     "bad": "// Example that violates the rule",
@@ -384,6 +434,16 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/server-action-requires-authz-and-validation": {
+    "what": "Server actions (`\"use server\"`) that mutate the database must call authorization helpers and validate input with `.parse()` / `.safeParse()`.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/server-only-modules-import-server-only": {
+    "what": "App-router server modules must import `\"server-only\"` so accidental client bundling fails at build time.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/pkce-required-for-oidc": {
     "what": "OIDC providers must use PKCE: `buildAuthorizationURL` must call `generateCodeVerifier()` and pass it to `createAuthorizationURL`.",
     "bad": "// Example that violates the rule",
@@ -399,8 +459,13 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/component-file-purity": {
+    "what": "A component .tsx contains only imports and the component itself — types go to <feature>.types.ts, constants to <feature>.constants.ts, helpers to src/lib",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/component-folder-structure": {
-    "what": "Enforce required sibling files in component folders (hooks, types, stories, test, index)",
+    "what": "A component .tsx must live in src/views/<Feature>/components/ (feature component), src/components/ui/ (shared primitive), or be the view root src/views/<Feature>/index.tsx",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
@@ -469,6 +534,31 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-prototype-polluting-merge": {
+    "what": "Disallow merging request body/query/params into objects — enables prototype pollution.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-user-controlled-fetch-url": {
+    "what": "Disallow fetch/axios requests to non-literal URLs — dynamic URLs enable SSRF.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-user-controlled-redirect": {
+    "what": "Disallow redirects to non-literal URLs — user-controlled redirects enable open redirects.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/upload-must-set-limits": {
+    "what": "Multipart upload handlers should declare `limits` or `maxFileSize` to bound request size.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/webhook-must-verify-signature-before-parse": {
+    "what": "Webhook handlers must verify signatures before calling `.json()` on the request body.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/catch-must-handle": {
     "what": "Catch blocks must log, rethrow, or propagate errors — not silently return empty defaults on failure.",
     "bad": "// Example that violates the rule",
@@ -499,6 +589,16 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/caught-error-log-requires-cause": {
+    "what": "When logging a caught error, include a `cause` field in the structured payload so downstream tools preserve the error chain.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/logger-not-console": {
+    "what": "Service modules should use the structured logger instead of `console.*` — console output is unstructured and hard to search.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/mask-pii-fields": {
     "what": "Disallow unmasked PII (email, phone, password, token, ...) in structured-logger payloads — the #1 way data leaks quietly.",
     "bad": "// Example that violates the rule",
@@ -519,14 +619,49 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/fake-timers-must-be-restored": {
+    "what": "When a test file calls `useFakeTimers()`, it must also call `useRealTimers()` so later tests are not affected.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-conditional-expect": {
+    "what": "Disallow `expect()` inside conditionals — tests must fail when assertions are skipped.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-focused-tests": {
     "what": "Disallow focused tests (`test.only`, `it.only`, `fdescribe`, ...) — the canonical 'I forgot to remove this before committing' leak.",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-real-network-in-unit-tests": {
+    "what": "Unit tests should not perform real network I/O — mock HTTP clients or move the test to an integration suite.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/test-file-mirrors-source": {
     "what": "Every test file under `tests/` must mirror a source file under `src/`. Catches orphaned tests left behind after refactors and renames.",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
+  },
+  "tsforge/exported-functions-require-return-type": {
+    "what": "Exported functions should declare an explicit return type at module boundaries.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/fetch-must-check-ok": {
+    "what": "HTTP fetch responses must check `.ok` or status before calling `.json()`.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/json-parse-must-validate": {
+    "what": "Disallow bare JSON.parse on untrusted input — validate through a schema library.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-unsafe-boundary-cast": {
+    "what": "Disallow type assertions immediately after parsing untrusted boundary input.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
   }
 }

package/src/loop/run.ts

@@ -330,6 +330,7 @@ export async function runTask(
   const state: ILoopState = {
     prevGateErrors: red.errors,
     gateNoProgress: 0,
+    errorAge: new Map(),
     lastGateCount: -1,
     edits: 0,
     regressions: 0,

package/src/loop/session.ts

@@ -446,6 +446,7 @@ export class Session {
     this.state = {
       prevGateErrors: [],
       gateNoProgress: 0,
+      errorAge: new Map(),
       lastGateCount: -1,
       edits: 0,
       regressions: 0,
@@ -698,8 +699,13 @@ export class Session {
    */
   async send(text: string, opts: ISendOptions = {}): Promise<ISendResult> {
     const { ctx, report } = this;
+    // Interactive ceiling is a RUNAWAY backstop, not the primary stop — the
+    // progress guards (samePersist / gateNoProgress) pull the agent out the moment
+    // it stops converging. Set high so normal long back-and-forth never trips it.
     const maxTurns =
-      this.maxTurnsOverride ?? this.cfg.maxTurns ?? LOOP_LIMITS.maxTurns;
+      this.maxTurnsOverride ??
+      this.cfg.maxTurns ??
+      LOOP_LIMITS.interactiveBackstopTurns;
     const sendStart = performance.now();
 
     // Thread cancellation to the tool `run` commands and the gate (not just the
@@ -1505,7 +1511,7 @@ export class Session {
       kind: "stuck",
       task: SESSION_ID,
       cycles: maxTurns,
-      message: `stuck (hit ${maxTurns}-turn cap)`,
+      message: `stuck (hit the ${maxTurns}-turn runaway backstop — progress guards never tripped, which is unusual; re-steer or narrow the task)`,
     });
 
     return { status: "stuck", turns: maxTurns };

package/src/loop/turn.ts

@@ -8,6 +8,7 @@ import {
   sameErrorSet,
   type ErrorParser,
   type ErrorSet,
+  type IErrorItem,
 } from "../validate";
 import { isInScope } from "../lib/scope";
 import { fileExists, resolveScopeFiles } from "../lib/fs";
@@ -126,6 +127,9 @@ export interface ILoopCtx {
 export interface ILoopState {
   prevGateErrors: ErrorSet;
   gateNoProgress: number;
+  /** Per-error-key (file:rule) survival count: how many consecutive gate cycles
+   *  each error has persisted. Drives the primary `samePersist` no-progress stop. */
+  errorAge: Map<string, number>;
   lastGateCount: number;
   edits: number;
   regressions: number;
@@ -688,6 +692,46 @@ function autoFixNotice(files: string[]): string {
   );
 }
 
+/**
+ * Advance each error's per-(file:rule) survival count and return the first error
+ * that has now persisted for `samePersist` consecutive gate cycles — the model
+ * keeps failing at the SAME thing — or null. Rebuilds the map from the CURRENT
+ * keys, so a fixed error's age drops out (no stale growth) and an error that
+ * comes back later starts fresh. Catches "stuck on X" even while OTHER errors
+ * churn around it (which the whole-set `gateNoProgress` guard misses).
+ */
+export function trackErrorAges(
+  state: ILoopState,
+  gateErrors: ErrorSet
+): IErrorItem | null {
+  const next = new Map<string, number>();
+  let stuck: IErrorItem | null = null;
+
+  for (const e of gateErrors) {
+    const age = (state.errorAge.get(e.key) ?? 0) + 1;
+
+    next.set(e.key, age);
+
+    if (age >= LOOP_LIMITS.samePersist && stuck === null) {
+      stuck = e;
+    }
+  }
+
+  state.errorAge = next;
+
+  return stuck;
+}
+
+/** The blocker diagnosis surfaced when a single error persists too long — names
+ *  the rule + file + attempt count + the last message, so an interactive session
+ *  hands back something the user can act on. */
+export function persistDetail(e: IErrorItem): string {
+  const where = e.file !== undefined ? ` in ${e.file}` : "";
+  const rule = e.rule ?? "the same error";
+
+  return `stuck on ${rule}${where} after ${String(LOOP_LIMITS.samePersist)} attempts (last: ${e.message.slice(0, 140)})`;
+}
+
 /**
  * The deterministic gate — the only authority on "done". Auto-fix, run the
  * optional fix command, validate, and return a terminal result (done/stuck) or
@@ -817,17 +861,47 @@ export async function settleGate(
     };
   }
 
+  // PRIMARY no-progress stop: the model keeps failing at the SAME (file,rule)
+  // for `samePersist` cycles running — even if other errors churn. Hand back a
+  // concrete blocker rather than spinning to a raw turn cap.
+  const persisted = trackErrorAges(state, gateErrors);
+
+  if (persisted !== null) {
+    const detail = persistDetail(persisted);
+
+    report({
+      kind: "stuck",
+      task: task.id,
+      cycles: turn,
+      detail,
+      message: `task ${task.id}: ${detail}`,
+    });
+
+    return {
+      task: task.id,
+      redConfirmed: true,
+      status: RUN_STATUS.stuck,
+      cycles: turn,
+      reason: STUCK_REASON.stalled,
+      detail,
+    };
+  }
+
+  // Coarser secondary net: the WHOLE error set unchanged this many cycles.
   state.gateNoProgress = sameErrorSet(state.prevGateErrors, gateErrors)
     ? state.gateNoProgress + 1
     : 0;
   state.prevGateErrors = gateErrors;
 
   if (state.gateNoProgress >= LOOP_LIMITS.gateStuckRepeats) {
+    const detail = `gate unchanged ${String(LOOP_LIMITS.gateStuckRepeats)} cycles (${String(gateErrors.length)} error(s) not converging)`;
+
     report({
       kind: "stuck",
       task: task.id,
       cycles: turn,
-      message: `task ${task.id}: stuck (gate unchanged ${LOOP_LIMITS.gateStuckRepeats}x)`,
+      detail,
+      message: `task ${task.id}: stuck — ${detail}`,
     });
 
     return {
@@ -836,6 +910,7 @@ export async function settleGate(
       status: RUN_STATUS.stuck,
       cycles: turn,
       reason: STUCK_REASON.stalled,
+      detail,
     };
   }