@agjs/tsforge 0.3.4 → 0.5.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@agjs/tsforge",
   "type": "module",
-  "version": "0.3.4",
+  "version": "0.5.0",
   "license": "MIT",
   "description": "TypeScript coding harness with a deterministic gate, stack-aware guardrails, and stream-level correction.",
   "repository": {
@@ -38,6 +38,7 @@
     "eslint-plugin-react": "^7.37.5",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-sonarjs": "4.0.3",
     "eslint": "10.4.0",
     "prettier": "3.8.3",
     "typescript": "6.0.3",

package/scripts/boot-check.ts

@@ -0,0 +1,106 @@
+// Gate-runnable BOOT oracle: actually start the built server and confirm it comes
+// up and answers a request without a 5xx. This is "does it RUN", a class of
+// failure tsc/eslint/unit-tests never catch — a server that throws on boot
+// (bad env wiring, a port clash, a top-level await that rejects) still type-checks
+// and lints clean. Mirrors the web browser smoke, for backends.
+//
+// OPT-IN: wired into the gate only when TSFORGE_BOOT is set to the start command
+// (e.g. `TSFORGE_BOOT="bun run start"`). TSFORGE_BOOT_URL (default
+// http://localhost:3000/) and TSFORGE_BOOT_TIMEOUT (ms, default 15000) tune it.
+//
+//   TSFORGE_BOOT="bun run start" TSFORGE_BOOT_URL=http://localhost:3000/health bun boot-check.ts
+
+export interface IBootConfig {
+  readonly command: string;
+  readonly url: string;
+  readonly timeoutMs: number;
+}
+
+/** Read the boot config from env; null when TSFORGE_BOOT is not set. */
+export function bootConfig(
+  env: Record<string, string | undefined>
+): IBootConfig | null {
+  const command = env.TSFORGE_BOOT;
+
+  if (command === undefined || command.trim().length === 0) {
+    return null;
+  }
+
+  const timeoutRaw = Number(env.TSFORGE_BOOT_TIMEOUT);
+
+  return {
+    command,
+    url: env.TSFORGE_BOOT_URL ?? "http://localhost:3000/",
+    timeoutMs:
+      Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : 15000,
+  };
+}
+
+/** Poll `url` until it answers with status < 500, or the deadline passes.
+ *  Returns the status code on success, or null on timeout. */
+export async function pollUntilReady(
+  url: string,
+  timeoutMs: number,
+  now: () => number = () => performance.now(),
+  sleep: (ms: number) => Promise<void> = (ms) =>
+    new Promise((r) => setTimeout(r, ms))
+): Promise<number | null> {
+  const deadline = now() + timeoutMs;
+
+  while (now() < deadline) {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(2000) });
+
+      if (res.status < 500) {
+        return res.status;
+      }
+    } catch {
+      // not up yet
+    }
+
+    await sleep(250);
+  }
+
+  return null;
+}
+
+async function main(): Promise<number> {
+  const cfg = bootConfig(process.env);
+
+  if (cfg === null) {
+    return 0; // not configured — nothing to do
+  }
+
+  const child = Bun.spawn(["sh", "-c", cfg.command], {
+    cwd: process.cwd(),
+    stdout: "pipe",
+    stderr: "pipe",
+    env: process.env,
+  });
+
+  try {
+    const status = await pollUntilReady(cfg.url, cfg.timeoutMs);
+
+    if (status === null) {
+      const err = await new Response(child.stderr).text();
+
+      process.stderr.write(
+        `boot-check: server did not answer ${cfg.url} within ${cfg.timeoutMs}ms (or only returned 5xx). It must boot and serve a non-5xx response.\n${err.slice(0, 800)}\n`
+      );
+
+      return 1;
+    }
+
+    process.stdout.write(
+      `boot-check: server answered ${cfg.url} with ${status}. OK\n`
+    );
+
+    return 0;
+  } finally {
+    child.kill();
+  }
+}
+
+if (import.meta.main) {
+  process.exit(await main());
+}

package/scripts/build-rule-docs.ts

@@ -98,10 +98,13 @@ for (const pack of Object.values(RULE_PACKS)) {
     const ruleId = `tsforge/${ruleName}`;
     const description = getRuleDescription(ruleModule) ?? ruleName;
 
+    // No fake placeholders: leave bad/good empty so the feedback renderer shows
+    // just the description. Real worked examples come from curated RULE_DOCS,
+    // which take precedence over this generated cache.
     out[ruleId] = {
       what: description,
-      bad: `// Example that violates the rule`,
-      good: `// Corrected version`,
+      bad: "",
+      good: "",
     };
 
     packRulesAdded += 1;

package/scripts/build-rules-md.ts

@@ -131,6 +131,7 @@ const categoryOrder = [
   "testing",
   "stack-layout",
   "ci",
+  "container",
 ] as const;
 
 const rulesByCategory = new Map<string, (typeof META_RULES)[number][]>();
@@ -172,9 +173,11 @@ out.push(
   "- GraphQL/WebSocket/OpenAPI contract rules (until OpenAPI dep + parser)"
 );
 out.push(
-  "- Container/Kubernetes YAML hardening (future meta-rules when Dockerfile/k8s detected)"
+  "- Kubernetes / Compose YAML hardening (Dockerfile hardening now ships as container meta-rules)"
+);
+out.push(
+  "- MCP-server security pack (the AI-SDK pack now covers `ai`/`openai`/Anthropic clients)"
 );
-out.push("- LLM/MCP security packs (opt-in when AI SDK deps detected)");
 out.push("- FSD layer DAG / full authorization taint tracking");
 out.push("- Lighthouse / bundle-analyzer CI gates");
 out.push("- Violation ratcheting / baseline snapshots (Phase 5)");

package/scripts/test-coverage-check.ts

@@ -0,0 +1,138 @@
+// Gate-runnable TEST-COVERAGE oracle: run the project's tests with lcov coverage
+// and fail if line coverage falls below a floor. Proves the tests don't just
+// *pass* but actually *exercise* the code — closing the "added code, added no
+// test" gap (a test suite can be green and assert almost nothing).
+//
+// OPT-IN: only wired into the gate when TSFORGE_COVERAGE is set (a percent, e.g.
+// `TSFORGE_COVERAGE=80`). Skips cleanly (exit 0) when the project has no tests or
+// the coverage report can't be produced — it never blocks a project that simply
+// has nothing to measure yet.
+//
+//   TSFORGE_COVERAGE=80 bun test-coverage-check.ts
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface ICoverage {
+  readonly lineFound: number; // LF
+  readonly lineHit: number; // LH
+  readonly funcFound: number; // FNF
+  readonly funcHit: number; // FNH
+  readonly linePct: number; // 0..100
+  readonly funcPct: number; // 0..100
+  /** The weaker of line/function coverage — the floor is checked against this so
+   *  an uncovered FUNCTION can't hide behind line counts (bun marks a one-line
+   *  arrow's declaration line "hit" even when the function is never called). */
+  readonly pct: number;
+}
+
+function sumPrefixed(text: string, prefix: string): number {
+  let total = 0;
+
+  for (const line of text.split("\n")) {
+    if (line.startsWith(prefix)) {
+      const n = Number(line.slice(prefix.length).trim());
+
+      total += Number.isNaN(n) ? 0 : n;
+    }
+  }
+
+  return total;
+}
+
+/** Sum line (LF/LH) and function (FNF/FNH) coverage across an lcov.info report. */
+export function parseLcovCoverage(text: string): ICoverage {
+  const lineFound = sumPrefixed(text, "LF:");
+  const lineHit = sumPrefixed(text, "LH:");
+  const funcFound = sumPrefixed(text, "FNF:");
+  const funcHit = sumPrefixed(text, "FNH:");
+  const linePct = lineFound === 0 ? 100 : (lineHit / lineFound) * 100;
+  const funcPct = funcFound === 0 ? 100 : (funcHit / funcFound) * 100;
+
+  return {
+    lineFound,
+    lineHit,
+    funcFound,
+    funcHit,
+    linePct,
+    funcPct,
+    pct: Math.min(linePct, funcPct),
+  };
+}
+
+/** The configured floor: TSFORGE_COVERAGE as a percent, default 80 when set
+ *  truthy-but-not-a-useful-number (e.g. `=1`). */
+export function coverageFloor(raw: string | undefined): number {
+  if (raw === undefined) {
+    return 80;
+  }
+
+  const n = Number(raw);
+
+  return Number.isFinite(n) && n > 1 && n <= 100 ? n : 80;
+}
+
+async function main(): Promise<number> {
+  const floor = coverageFloor(process.env.TSFORGE_COVERAGE);
+  const covDir = mkdtempSync(join(tmpdir(), "tsforge-cov-"));
+
+  try {
+    const proc = Bun.spawn(
+      [
+        "bun",
+        "test",
+        "--coverage",
+        "--coverage-reporter=lcov",
+        `--coverage-dir=${covDir}`,
+      ],
+      { cwd: process.cwd(), stdout: "pipe", stderr: "pipe" }
+    );
+
+    await proc.exited;
+
+    const lcovPath = join(covDir, "lcov.info");
+
+    if (!existsSync(lcovPath)) {
+      process.stdout.write(
+        "test-coverage-check: no lcov report produced (no tests?) — skipping.\n"
+      );
+
+      return 0;
+    }
+
+    const cov = parseLcovCoverage(readFileSync(lcovPath, "utf8"));
+
+    if (cov.lineFound === 0 && cov.funcFound === 0) {
+      process.stdout.write(
+        "test-coverage-check: nothing instrumented — skipping.\n"
+      );
+
+      return 0;
+    }
+
+    const pct = cov.pct.toFixed(1);
+
+    if (cov.pct + 1e-9 < floor) {
+      process.stderr.write(
+        `test-coverage-check: coverage ${pct}% is below the ${floor}% floor ` +
+          `(lines ${cov.lineHit}/${cov.lineFound}, functions ${cov.funcHit}/${cov.funcFound}). ` +
+          `Add tests that actually call the uncovered code.\n`
+      );
+
+      return 1;
+    }
+
+    process.stdout.write(
+      `test-coverage-check: ${pct}% >= ${floor}% floor ` +
+        `(lines ${cov.lineHit}/${cov.lineFound}, functions ${cov.funcHit}/${cov.funcFound}). OK\n`
+    );
+
+    return 0;
+  } finally {
+    rmSync(covDir, { recursive: true, force: true });
+  }
+}
+
+if (import.meta.main) {
+  process.exit(await main());
+}

package/src/cli.ts

@@ -774,7 +774,7 @@ async function baseGate(
   }
 
   if (args.web) {
-    const web = buildWebGate("react");
+    const web = buildWebGate("react", undefined, args.dir);
 
     return { accept: web.command, gateLabel: web.label };
   }
@@ -980,7 +980,7 @@ async function repl(args: ICliArgs): Promise<number> {
       `\n  ↳ scaffolding a ${frameworkLabel(framework)} project\n`
     );
     await setUpWebProject(args.dir, framework);
-    session.setGate(buildWebGate(framework).command);
+    session.setGate(buildWebGate(framework, undefined, args.dir).command);
     session.setFix(buildWebFix(framework));
     session.setIncrementalCheck(buildWebTscCheck());
     session.guide(webGuidance(framework));

package/src/detect-gate.ts

@@ -77,6 +77,13 @@ const BROWSER_CHECK = join(
 );
 
 const STUB_CHECK = join(import.meta.dir, "..", "scripts", "stub-check.ts");
+const TEST_COVERAGE_CHECK = join(
+  import.meta.dir,
+  "..",
+  "scripts",
+  "test-coverage-check.ts"
+);
+const BOOT_CHECK = join(import.meta.dir, "..", "scripts", "boot-check.ts");
 
 // The strict tsconfig tsforge brings to a greenfield project — strict + the
 // index-safety the local model is weakest at, with DOM + JSX libs so browser /
@@ -442,7 +449,8 @@ function packEnvPrefix(
 
 export function buildWebGate(
   framework: WebFramework,
-  packs: readonly string[] = WEB_PACKS
+  packs: readonly string[] = WEB_PACKS,
+  cwd: string = process.cwd()
 ): IGate {
   const template = WEB_TEMPLATES[framework];
   const ignores = template.eslintIgnore
@@ -478,8 +486,21 @@ export function buildWebGate(
   // fails fast.
   const stubs = `bun "${STUB_CHECK}" .`;
 
+  // Type-aware async correctness (no-floating-promises / no-misused-promises) —
+  // the CORE gate already runs this via typeAwareLintPart(), but the web gate
+  // historically did not, so a dropped `await` in a handler/effect/mutation passed.
+  // Splice it in after the syntactic lint when the scaffold has a tsconfig (it
+  // always does), reusing the SHIPPED strict.type-aware config verbatim.
+  const typeAware = existsSync(join(cwd, "tsconfig.json"))
+    ? `bun "${ESLINT_BIN}" --no-config-lookup -c "${TYPE_AWARE_CONFIG}" ${ignores} --format json .`.replace(
+        /\s+/g,
+        " "
+      )
+    : null;
+  const lintChain = typeAware === null ? lint : `${lint} && ${typeAware}`;
+
   return {
-    command: `${build} && ${tsc} && ${lint} && ${stubs} && ${format} && ${render}`,
+    command: `${build} && ${tsc} && ${lintChain} && ${stubs} && ${format} && ${render}`,
     label: `${template.label} (build + behaviour smoke)`,
   };
 }
@@ -663,9 +684,34 @@ export async function buildGate(
     }
   }
 
+  appendOptInOracles(parts, labels, process.env);
+
   return { command: parts.join(" && "), label: labels.join(" + ") };
 }
 
+/**
+ * Opt-in quality oracles (default OFF, mirroring the web a11y/screenshot flags).
+ * They run AFTER tests and read their own config from env, so the gate command
+ * stays free of shell-quoting:
+ *   - TSFORGE_COVERAGE=<pct> — fail if line coverage is below the floor.
+ *   - TSFORGE_BOOT="<start cmd>" — boot the server and require a non-5xx response.
+ */
+function appendOptInOracles(
+  parts: string[],
+  labels: string[],
+  env: Record<string, string | undefined>
+): void {
+  if (env.TSFORGE_COVERAGE !== undefined && env.TSFORGE_COVERAGE.length > 0) {
+    parts.push(`bun "${TEST_COVERAGE_CHECK}"`);
+    labels.push("test coverage");
+  }
+
+  if (env.TSFORGE_BOOT !== undefined && env.TSFORGE_BOOT.trim().length > 0) {
+    parts.push(`bun "${BOOT_CHECK}"`);
+    labels.push("boot smoke");
+  }
+}
+
 /** The npm-init placeholder test script — running it always fails, so it must
  *  NOT count as "the project has tests". */
 const PLACEHOLDER_TEST = /no test specified/i;

package/src/loop/feedback/meta-rule-docs.ts

@@ -32,6 +32,12 @@ export const META_RULE_DOCS: Record<string, string> = {
   "production-must-not-use-drizzle-push":
     "Replace `drizzle-kit push` in scripts and CI with checked-in SQL migrations and `drizzle-kit migrate`.",
 
+  "no-undeclared-dependencies":
+    "Add the imported package to package.json (dependencies or devDependencies) — relying on a hoisted/transitive copy breaks on a clean install.",
+
+  "no-circular-imports":
+    "Break the import cycle by extracting the shared code both modules need into a third module they each import (one-way edges only).",
+
   "migrations-must-be-checked-in":
     "Add a drizzle/ or migrations/ folder with generated SQL migration files when using Drizzle ORM.",
 
@@ -86,4 +92,14 @@ export const META_RULE_DOCS: Record<string, string> = {
 
   "no-github-context-in-shell":
     "Pass github.event values through env: instead of interpolating them directly in run: shell scripts.",
+
+  // Container
+  "dockerfile-base-image-pinned":
+    "Pin every Dockerfile FROM to an explicit non-latest tag (e.g. node:24.3.0-bookworm) or a @sha256: digest; build-stage references and scratch are exempt.",
+
+  "dockerfile-non-root-user":
+    "Add a non-root USER instruction (after the install steps) so the container process does not run as root.",
+
+  "dockerfile-no-secrets-in-env-arg":
+    "Do not assign secret-looking ENV/ARG literals (names ending in _KEY/_TOKEN/_SECRET/_PASSWORD) — they bake into image layers; inject them at runtime via --env-file, a secret manager, or a BuildKit --secret mount.",
 };

package/src/loop/feedback/rule-docs.ts

@@ -25,6 +25,39 @@ const GENERATED: Record<string, IRuleDoc> = generatedJson;
  * failure beats making the model re-derive the fix from scratch.
  */
 const RULE_DOCS: Record<string, IRuleDoc> = {
+  // --- Type-aware: implicit-`any` containment (no `any` token to see) ---
+  // (no-unsafe-assignment / -member-access / -return are curated further below)
+  "@typescript-eslint/no-unsafe-call": {
+    what: "Calling an `any`-typed value. Type the callee so the call is checked.",
+    bad: "const fn = lib.run; fn(); // lib is any",
+    good: "const fn: () => void = lib.run; fn();",
+  },
+  "@typescript-eslint/no-unsafe-argument": {
+    what: "Passing an `any` into a typed parameter. Validate/narrow before the call.",
+    bad: "save(JSON.parse(body));",
+    good: "save(UserSchema.parse(JSON.parse(body)));",
+  },
+  "sonarjs/cognitive-complexity": {
+    what: "Function is too tangled (cognitive complexity > 20). Extract named helper functions for the inner branches/loops — don't suppress.",
+    bad: "function handle(x) { /* many nested if/for/switch in one body */ }",
+    good: "function handle(x) { return isA(x) ? doA(x) : doB(x); } // branches extracted",
+  },
+  // --- AI-SDK pack ---
+  "tsforge/no-api-key-in-client": {
+    what: "An AI provider client constructed in a `'use client'` file ships the API key to the browser. Call the model from a server route/action.",
+    bad: "'use client';\nconst client = new OpenAI({ apiKey: process.env.KEY });",
+    good: "// server action / route handler:\nconst client = new OpenAI({ apiKey: process.env.KEY });",
+  },
+  "tsforge/require-completion-token-limit": {
+    what: "AI completion calls must bound output tokens to cap cost/latency.",
+    bad: "await generateText({ model, prompt });",
+    good: "await generateText({ model, prompt, maxTokens: 512 });",
+  },
+  "tsforge/no-user-input-in-system-prompt": {
+    what: "Don't splice request/user data into the system prompt (injection). Keep the system prompt constant; pass user input as a user message.",
+    bad: "generateText({ system: `You are ${role}`, prompt });",
+    good: "generateText({ system: SYSTEM_PROMPT, messages: [{ role: 'user', content: userInput }] });",
+  },
   TS2532: {
     what: "Indexed access is `T | undefined` (noUncheckedIndexedAccess). Bind and guard before use; never `!`.",
     bad: "total += arr[i];",
@@ -416,7 +449,17 @@ export function ruleHelp(errors: ErrorSet): string {
     }
 
     seen.add(e.rule);
-    blocks.push(`${e.rule}: ${doc.what}\n  ✗ ${doc.bad}\n  ✓ ${doc.good}`);
+
+    // Only show the ✗/✓ pair when there is a REAL worked example. Generated-only
+    // entries (pack rules without a curated example) carry just `what` — a fake
+    // "// Example that violates the rule" placeholder is worse than nothing.
+    const hasExample = doc.bad.length > 0 && doc.good.length > 0;
+
+    blocks.push(
+      hasExample
+        ? `${e.rule}: ${doc.what}\n  ✗ ${doc.bad}\n  ✓ ${doc.good}`
+        : `${e.rule}: ${doc.what}`
+    );
   }
 
   return blocks.join("\n");

package/src/loop/prompt/prompt.ts

@@ -15,6 +15,7 @@ export const SYSTEM = [
   "The harness also AUTO-FIXES mechanical formatting on every file you write — blank lines, braces, quotes, semicolons, import order, `prefer-template`. NEVER hand-fix or chase those, and do NOT run `tsc`/`eslint`/the gate yourself to look for them. Fix only what the gate explicitly hands back (`as`/`any`/`!`, `I`-prefix, real type errors), then stop.",
   "Test hypotheses by RUNNING them, never by reasoning them out. Unsure about an edge case, rounding, or ordering (`Math.floor(100/3)`, largest-remainder ties)? `run` a quick `bun -e '…console.log(…)'`, or write a throwaway `scratch/check.ts` importing your impl and `run` it. `scratch/` is yours — the gate ignores it.",
   "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.",
+  "Keep functions small: the gate caps cognitive complexity at 20 and nesting depth at 4. If a function grows long or deeply nested, extract named helpers instead of one sprawling block. Always `await` promises (or `void` them deliberately) — a floating promise is a gate error.",
 ].join("\n");
 
 /** Appended to SYSTEM for from-scratch, NON-web utility builds when the simplicity