@agjs/tsforge 0.1.18 → 0.2.0

package/src/config/profiles.ts

@@ -0,0 +1,150 @@
+import type { ProfileId } from "../rule-packs/rule-catalog.types";
+
+export type { ProfileId };
+
+export interface IProfileDefinition {
+  readonly id: ProfileId;
+  readonly label: string;
+  readonly description: string;
+  /** Extra packs to include beyond stack detection (deduped at resolve time). */
+  readonly extraPacks?: readonly string[];
+  /** Rule severity overrides keyed by bare rule name. */
+  readonly ruleOverrides?: Readonly<Record<string, "error" | "warn" | "off">>;
+  /** Meta-rule ids to elevate to error in this profile. */
+  readonly metaRulesAtError?: readonly string[];
+}
+
+/** Architecture-tier rules enabled only in the opinionated profile. */
+export const ARCHITECTURE_RULES = [
+  "component-folder-structure",
+  "no-state-in-component-body",
+  "no-inline-jsx-functions",
+  "index-must-reexport-default",
+  "forwardref-display-name",
+  "max-hooks-per-file",
+] as const;
+
+const architectureOffOverrides = Object.fromEntries(
+  ARCHITECTURE_RULES.map((rule) => [rule, "off" as const])
+);
+
+export const PROFILE_DEFINITIONS: Readonly<
+  Record<ProfileId, IProfileDefinition>
+> = {
+  recommended: {
+    id: "recommended",
+    label: "Recommended",
+    description:
+      "Safety + framework packs from stack detection; architecture opinions off by default.",
+    ruleOverrides: {
+      ...architectureOffOverrides,
+      "prefer-early-return": "warn",
+    },
+  },
+  strict: {
+    id: "strict",
+    label: "Strict",
+    description:
+      "Recommended plus CI/supply-chain meta-rules at error and type-aware async rules.",
+    extraPacks: ["typescript-core"],
+    ruleOverrides: {
+      ...architectureOffOverrides,
+      "prefer-early-return": "warn",
+    },
+    metaRulesAtError: [
+      "workflow-permissions-explicit",
+      "lockfile-required",
+      "single-package-manager",
+    ],
+  },
+  security: {
+    id: "security",
+    label: "Security",
+    description:
+      "Recommended plus runtime-boundaries and experimental authorization heuristics.",
+    extraPacks: ["runtime-boundaries", "authorization"],
+    ruleOverrides: architectureOffOverrides,
+  },
+  frontend: {
+    id: "frontend",
+    label: "Frontend",
+    description: "Recommended with React/Next architecture rules at warn.",
+    ruleOverrides: {
+      "no-html-img-element": "warn",
+      "no-anonymous-useEffect": "warn",
+      "no-derived-state-in-effect": "warn",
+      ...architectureOffOverrides,
+    },
+  },
+  backend: {
+    id: "backend",
+    label: "Backend",
+    description:
+      "Recommended; stack detection adds Fastify/Elysia/Drizzle/BullMQ packs.",
+    ruleOverrides: architectureOffOverrides,
+  },
+  opinionated: {
+    id: "opinionated",
+    label: "Opinionated",
+    description:
+      "Full house-style architecture rules including component folder structure.",
+    ruleOverrides: {
+      "component-folder-structure": "error",
+      "no-state-in-component-body": "error",
+      "no-inline-jsx-functions": "warn",
+      "index-must-reexport-default": "error",
+      "forwardref-display-name": "error",
+      "max-hooks-per-file": "warn",
+      "prefer-early-return": "error",
+    },
+  },
+};
+
+export const DEFAULT_PROFILE: ProfileId = "recommended";
+
+export function isProfileId(value: string): value is ProfileId {
+  return value in PROFILE_DEFINITIONS;
+}
+
+/** Merge profile overrides with user config overrides (user wins). */
+export function resolveProfileRuleOverrides(
+  profileId: ProfileId | undefined
+): Record<string, "error" | "warn" | "off"> {
+  const id = profileId ?? DEFAULT_PROFILE;
+  const profile = PROFILE_DEFINITIONS[id];
+
+  return { ...(profile.ruleOverrides ?? {}) };
+}
+
+export function resolveProfileExtraPacks(
+  profileId: ProfileId | undefined
+): readonly string[] {
+  const id = profileId ?? DEFAULT_PROFILE;
+  const profile = PROFILE_DEFINITIONS[id];
+
+  return profile.extraPacks ?? [];
+}
+
+export function resolveProfileMetaRuleOverrides(
+  profileId: ProfileId | undefined
+): Record<string, "error"> {
+  const id = profileId ?? DEFAULT_PROFILE;
+  const profile = PROFILE_DEFINITIONS[id];
+  const result: Record<string, "error"> = {};
+
+  for (const ruleId of profile.metaRulesAtError ?? []) {
+    result[ruleId] = "error";
+  }
+
+  return result;
+}
+
+export function mergeRuleOverrides(
+  profileId: ProfileId | undefined,
+  userOverrides: Readonly<Record<string, "error" | "warn" | "off">>
+): Record<string, "error" | "warn" | "off"> {
+  return {
+    ...resolveProfileRuleOverrides(profileId),
+    ...userOverrides,
+  };
+}

package/src/config/tsforge-config.ts

@@ -3,6 +3,14 @@ import { isRecord } from "../lib/guards";
 import { PACK_REGISTRY } from "../stack-detection";
 import { parseMcpServers, type IMcpServerConfig } from "../mcp";
 import { parsePlugins, type IExternalPlugin } from "./external-plugins";
+import {
+  DEFAULT_PROFILE,
+  isProfileId,
+  mergeRuleOverrides,
+  resolveProfileExtraPacks,
+  resolveProfileMetaRuleOverrides,
+  type ProfileId,
+} from "./profiles";
 
 /**
  * User-defined configuration from tsforge.config.json
@@ -10,6 +18,9 @@ import { parsePlugins, type IExternalPlugin } from "./external-plugins";
  * include/exclude packs, and tune rule severities (eslint packs + meta-rules).
  */
 export interface ITsforgeProjectConfig {
+  /** Rule profile: recommended (default), strict, security, frontend, backend, opinionated. */
+  readonly profile?: ProfileId;
+
   /** Force-enable a stack by name (skip detection heuristics, force-add its packs). */
   readonly stack?: string;
 
@@ -100,6 +111,31 @@ function warnUnknownPackInInclude(packId: string): void {
   warnConfig(msg);
 }
 
+function warnInvalidProfile(profileValue: unknown): void {
+  warnConfig(
+    `tsforge.config.json: "profile" must be one of recommended, strict, security, frontend, backend, opinionated — got "${String(profileValue)}"`
+  );
+}
+
+/** Validate and extract profile field. */
+function validateProfile(parsed: unknown): ProfileId | undefined {
+  if (typeof parsed !== "string") {
+    if (parsed !== undefined) {
+      warnInvalidProfile(parsed);
+    }
+
+    return undefined;
+  }
+
+  if (isProfileId(parsed)) {
+    return parsed;
+  }
+
+  warnInvalidProfile(parsed);
+
+  return undefined;
+}
+
 /** Validate and extract stack field. */
 function validateStack(parsed: unknown): string | undefined {
   if (typeof parsed === "string") {
@@ -181,6 +217,7 @@ function buildConfigFields(
   parsed: Record<string, unknown>
 ): ITsforgeProjectConfig {
   const configFields: {
+    profile?: ProfileId;
     stack?: string;
     packs?: { include?: readonly string[]; exclude?: readonly string[] };
     rules?: Record<string, "error" | "warn" | "off">;
@@ -188,6 +225,14 @@ function buildConfigFields(
     plugins?: readonly IExternalPlugin[];
   } = {};
 
+  if (parsed.profile !== undefined) {
+    const profile = validateProfile(parsed.profile);
+
+    if (profile !== undefined) {
+      configFields.profile = profile;
+    }
+  }
+
   if (parsed.stack !== undefined) {
     const stack = validateStack(parsed.stack);
 
@@ -290,6 +335,13 @@ export function resolveActivePacks(
     packs.add(config.stack);
   }
 
+  // Profile extra packs (runtime-boundaries, authorization, typescript-core, …)
+  for (const packId of resolveProfileExtraPacks(config.profile)) {
+    if (packId in PACK_REGISTRY) {
+      packs.add(packId);
+    }
+  }
+
   // Include: add packs (unknown ids are kept out of the registry lookup warning only)
   for (const packId of config.packs?.include ?? []) {
     if (packId.length === 0) {
@@ -324,11 +376,9 @@ function isSeverityOverride(value: unknown): value is "error" | "warn" | "off" {
 export function normalizeRuleOverrides(
   config: ITsforgeProjectConfig
 ): Record<string, "error" | "warn" | "off"> {
-  const normalized: Record<string, "error" | "warn" | "off"> = {};
+  const userOverrides: Record<string, "error" | "warn" | "off"> = {};
 
   for (const [key, severity] of Object.entries(config.rules ?? {})) {
-    // Runtime data can violate the declared union (hand-built configs in tests,
-    // partially validated JSON) — re-check before trusting it.
     if (!isSeverityOverride(severity)) {
       continue;
     }
@@ -336,9 +386,18 @@ export function normalizeRuleOverrides(
     const bareKey = key.startsWith("tsforge/") ? key.slice(8) : key;
 
     if (bareKey.length > 0) {
-      normalized[bareKey] = severity;
+      userOverrides[bareKey] = severity;
     }
   }
 
-  return normalized;
+  return {
+    ...resolveProfileMetaRuleOverrides(config.profile),
+    ...mergeRuleOverrides(config.profile, userOverrides),
+  };
+}
+
+export function resolveProjectProfile(
+  config: ITsforgeProjectConfig
+): ProfileId {
+  return config.profile ?? DEFAULT_PROFILE;
 }

package/src/detect-gate.ts

@@ -63,6 +63,11 @@ const ESLINT_BIN = resolveToolBin("eslint");
 const TSC_BIN = resolveToolBin("tsc");
 const PRETTIER_BIN = resolveToolBin("prettier");
 const STRICT_CONFIG = join(import.meta.dir, "..", "strict.eslint.config.mjs");
+const TYPE_AWARE_CONFIG = join(
+  import.meta.dir,
+  "..",
+  "strict.type-aware.eslint.config.mjs"
+);
 const BROWSER_CHECK = join(
   import.meta.dir,
   "..",
@@ -86,6 +91,8 @@ const STRICT_TSCONFIG = `{
     "noUncheckedIndexedAccess": true,
     "noImplicitOverride": true,
     "noFallthroughCasesInSwitch": true,
+    "useUnknownInCatchVariables": true,
+    "erasableSyntaxOnly": true,
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "skipLibCheck": true,
@@ -108,6 +115,8 @@ const STRICT_TSCONFIG_OVERRIDE = `{
     "noUncheckedIndexedAccess": true,
     "noImplicitOverride": true,
     "noFallthroughCasesInSwitch": true,
+    "useUnknownInCatchVariables": true,
+    "erasableSyntaxOnly": true,
     "skipLibCheck": true,
     "noEmit": true
   }
@@ -458,7 +467,8 @@ export function prettierWriteCommand(): string {
 export async function buildGate(
   cwd: string,
   packs?: readonly string[],
-  ruleOverrides?: Readonly<Record<string, "error" | "warn" | "off">>
+  ruleOverrides?: Readonly<Record<string, "error" | "warn" | "off">>,
+  options?: { enableTypeAware?: boolean }
 ): Promise<IGate> {
   const parts: string[] = [];
   const labels: string[] = [];
@@ -475,6 +485,15 @@ export async function buildGate(
   parts.push(lint.command);
   labels.push(lint.label);
 
+  if (options?.enableTypeAware === true) {
+    const typeAware = await typeAwareLintPart(cwd);
+
+    if (typeAware !== null) {
+      parts.push(typeAware.command);
+      labels.push(typeAware.label);
+    }
+  }
+
   return { command: parts.join(" && "), label: labels.join(" + ") };
 }
 
@@ -538,3 +557,17 @@ function lintPart(
     label: "strict TypeScript (tsforge)",
   };
 }
+
+/** Optional type-aware async rules — only when target has tsconfig.json. */
+async function typeAwareLintPart(cwd: string): Promise<IGate | null> {
+  const hasTsconfig = await Bun.file(join(cwd, "tsconfig.json")).exists();
+
+  if (!hasTsconfig) {
+    return null;
+  }
+
+  return {
+    command: `bun "${ESLINT_BIN}" --no-config-lookup -c "${TYPE_AWARE_CONFIG}" --format json .`,
+    label: "type-aware async (tsforge)",
+  };
+}

package/src/inference/inference.types.ts

@@ -8,6 +8,10 @@ export interface IChatMessage {
   toolCalls?: IToolCall[];
   /** Tool messages only: the id of the call this message is the result of. */
   toolCallId?: string;
+  /** Assistant only: the model's chain-of-thought. DeepSeek's thinking mode
+   *  REQUIRES the prior turn's `reasoning_content` to be replayed, so it's kept
+   *  on the message and re-sent (for the deepseek reasoning style). */
+  reasoningContent?: string;
 }
 
 /** A parsed tool call from the model (name + decoded JSON arguments). */
@@ -29,6 +33,10 @@ export interface ITokenUsage {
 export interface IModelResponse {
   content: string;
   toolCalls: IToolCall[];
+  /** The model's chain-of-thought (`reasoning`/`reasoning_content`), when it
+   *  produced any. Stored on the assistant message for providers (DeepSeek) that
+   *  require it replayed on the next turn. */
+  reasoning?: string;
   /** Server-reported token usage for this call, when available. `promptTokens`
    *  is the full context the model just saw — what auto-compaction will watch. */
   usage?: ITokenUsage;

package/src/inference/request.ts

@@ -99,9 +99,13 @@ export function buildRequestBody(
   const omitTemperature =
     style(cfg) === "openai" || opts.temperature === undefined;
 
+  // DeepSeek's thinking mode requires each prior assistant turn's
+  // `reasoning_content` replayed; other providers don't want it.
+  const includeReasoning = style(cfg) === "deepseek";
+
   return {
     model: cfg.model,
-    messages: messages.map(toWire),
+    messages: messages.map((m) => toWire(m, includeReasoning)),
     ...tokenCapField(cfg),
     ...(omitTemperature ? {} : { temperature: opts.temperature }),
     ...(cfg.repetitionPenalty === undefined

package/src/inference/stream.ts

@@ -35,6 +35,7 @@ export async function streamResponse(
     calls: new Map(),
     guard: new StreamGuard(),
     content: "",
+    reasoning: "",
     ttsr: ttsrManager,
     ttsrFired: null,
   };
@@ -88,6 +89,7 @@ interface IStreamAcc {
   calls: Map<number, IStreamingCall>;
   guard: StreamGuard;
   content: string;
+  reasoning: string;
   usage?: ITokenUsage;
   ttsr?: ITtsrWatcher;
   ttsrFired: { readonly name: string; readonly guidance: string } | null;
@@ -137,6 +139,7 @@ function consumeLines(
     // less, not by hiding it from the log.)
     if (delta.reasoning !== undefined && delta.reasoning.length > 0) {
       onToken(delta.reasoning, "reasoning");
+      acc.reasoning += delta.reasoning;
 
       if (acc.guard.observe(delta.reasoning, "reasoning")) {
         return true;
@@ -163,6 +166,8 @@ function consumeLines(
 
 function assemble(acc: IStreamAcc, degenerated: boolean): IModelResponse {
   const usage = acc.usage === undefined ? {} : { usage: acc.usage };
+  const reasoning =
+    acc.reasoning.length > 0 ? { reasoning: acc.reasoning } : {};
   const toolCalls: IToolCall[] = [...acc.calls.values()].map((c) => ({
     id: c.id,
     name: c.name,
@@ -181,8 +186,21 @@ function assemble(acc: IStreamAcc, degenerated: boolean): IModelResponse {
 
   if (toolCalls.length > 0) {
     return degenerated
-      ? { content: acc.content, toolCalls, degenerated, ...ttsrFired, ...usage }
-      : { content: acc.content, toolCalls, ...ttsrFired, ...usage };
+      ? {
+          content: acc.content,
+          toolCalls,
+          degenerated,
+          ...reasoning,
+          ...ttsrFired,
+          ...usage,
+        }
+      : {
+          content: acc.content,
+          toolCalls,
+          ...reasoning,
+          ...ttsrFired,
+          ...usage,
+        };
   }
 
   const salvaged = salvageToolCalls(acc.content);
@@ -192,6 +210,7 @@ function assemble(acc: IStreamAcc, degenerated: boolean): IModelResponse {
     toolCalls: salvaged,
     salvaged: salvaged.length,
     ...(degenerated ? { degenerated } : {}),
+    ...reasoning,
     ...ttsrFired,
     ...usage,
   };

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

@@ -11,6 +11,30 @@ export const META_RULE_DOCS: Record<string, string> = {
   "no-overlapping-libs":
     "Remove duplicate or conflicting library versions from the dependency tree; only one canonical version per library is allowed.",
 
+  "fastify-security-plugins":
+    "Add @fastify/helmet, @fastify/cors, and @fastify/rate-limit when using fastify in production.",
+
+  "lockfile-required":
+    "Commit the lockfile for your package manager (package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb) and keep it in sync with package.json.",
+
+  "single-package-manager":
+    "Remove extra lockfiles — use one package manager and delete lockfiles from other tools.",
+
+  "package-manager-field-required":
+    'Add a "packageManager" field to package.json (e.g. "bun@1.3.14") so installs are reproducible across environments.',
+
+  "no-git-or-tarball-dependencies":
+    "Replace git+, git:, or HTTP tarball dependency URLs with registry versions from npm.",
+
+  "dependency-overrides-require-comment":
+    "Add a comment next to overrides/resolutions in package.json explaining why each override is needed.",
+
+  "production-must-not-use-drizzle-push":
+    "Replace `drizzle-kit push` in scripts and CI with checked-in SQL migrations and `drizzle-kit migrate`.",
+
+  "migrations-must-be-checked-in":
+    "Add a drizzle/ or migrations/ folder with generated SQL migration files when using Drizzle ORM.",
+
   // Source text
   "no-eslint-disable-comments":
     "Remove `// eslint-disable` comments — they hide warnings. Fix the underlying violation or refactor the code.",
@@ -25,6 +49,18 @@ export const META_RULE_DOCS: Record<string, string> = {
   "tsconfig-strict":
     "Enable all strict mode flags in tsconfig.json (strict: true or all strict flags individually).",
 
+  "tsconfig-recommended-flags":
+    "Enable useUnknownInCatchVariables, erasableSyntaxOnly, exactOptionalPropertyTypes, verbatimModuleSyntax, and noPropertyAccessFromIndexSignature in tsconfig.json compilerOptions.",
+
+  "next-proxy-over-middleware":
+    "Migrate middleware.ts to proxy.ts for Next.js 16 early request interception.",
+
+  "next-instrumentation-present":
+    "Add instrumentation.ts with registerOTel for OpenTelemetry tracing in Next.js apps.",
+
+  "next-image-remote-patterns-no-wildcards":
+    "Remove `**` hostname wildcards from next.config remotePatterns — allowlist specific image hostnames.",
+
   // Testing
   "test-sibling-required":
     "Add a test file for each source file; follow naming conventions (foo.ts → foo.test.ts or foo.spec.ts).",
@@ -38,4 +74,16 @@ export const META_RULE_DOCS: Record<string, string> = {
 
   "workflow-timeout-required":
     "Add a timeout-minutes setting to each GitHub Actions job to prevent hanging workflows.",
+
+  "workflow-permissions-explicit":
+    "Add a top-level permissions: block or job-level permissions to every GitHub Actions workflow.",
+
+  "workflow-permissions-least-privilege":
+    "Avoid workflow-level contents: write or id-token: write — scope write permissions to the job that needs them.",
+
+  "no-pull-request-target-untrusted-checkout":
+    "Do not combine pull_request_target with checkout of the PR head ref — use pull_request or checkout the base ref.",
+
+  "no-github-context-in-shell":
+    "Pass github.event values through env: instead of interpolating them directly in run: shell scripts.",
 };

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

@@ -154,6 +154,156 @@ const RULE_DOCS: Record<string, IRuleDoc> = {
     bad: "<button onClick={() => doThing(id)} />",
     good: "const onClickRow = useCallback(() => doThing(id), [id]); <button onClick={onClickRow} />",
   },
+  "tsforge/no-throw-literal": {
+    what: "Throw `Error` instances, not string or number literals.",
+    bad: "throw 'Unauthorized';",
+    good: "throw new Error('Unauthorized');",
+  },
+  "tsforge/no-react-fc": {
+    what: "Do not use React.FC — type props on the function parameter.",
+    bad: "const Button: React.FC<IButtonProps> = ({ onClick }) => <button onClick={onClick} />;",
+    good: "function Button({ onClick }: IButtonProps) { return <button onClick={onClick} />; }",
+  },
+  "tsforge/no-component-invocation": {
+    what: "Render components as JSX, not function calls.",
+    bad: "<div>{Header()}</div>",
+    good: "<div><Header /></div>",
+  },
+  "tsforge/no-nested-component": {
+    what: "Declare components at module scope, not inside another component.",
+    bad: "function App() { function Inner() { return <span />; } return <Inner />; }",
+    good: "function Inner() { return <span />; } function App() { return <Inner />; }",
+  },
+  "tsforge/dangerous-html-requires-sanitize": {
+    what: "Sanitize HTML before dangerouslySetInnerHTML — import DOMPurify.",
+    bad: "<div dangerouslySetInnerHTML={{ __html: rawHtml }} />",
+    good: "import DOMPurify from 'isomorphic-dompurify'; <div dangerouslySetInnerHTML={{ __html: DOMPurify.sanitize(rawHtml) }} />",
+  },
+  "tsforge/no-child-process-exec": {
+    what: "Do not use child_process.exec/execSync — shell execution enables command injection.",
+    bad: "import { exec } from 'child_process'; exec(`rm -rf ${dir}`);",
+    good: "import { execFile } from 'child_process'; execFile('rm', ['-rf', dir], callback);",
+  },
+  "tsforge/no-spawn-with-shell": {
+    what: "Do not pass `{ shell: true }` to spawn/spawnSync.",
+    bad: "spawn('sh', ['-c', cmd], { shell: true });",
+    good: "spawn('node', ['script.js', arg]);",
+  },
+  "tsforge/no-dynamic-regexp": {
+    what: "Do not build RegExp from runtime input — ReDoS risk.",
+    bad: "const re = new RegExp(userPattern);",
+    good: "const re = /^fixed-pattern$/;",
+  },
+  "tsforge/no-inner-html-assignment": {
+    what: "Do not assign to innerHTML — XSS risk in vanilla DOM code.",
+    bad: "el.innerHTML = userHtml;",
+    good: "el.textContent = userText;",
+  },
+  "tsforge/catch-must-handle": {
+    what: "Catch blocks must log, rethrow, or return a typed error — not silently mask failure.",
+    bad: "catch (e) { return null; }",
+    good: "catch (e) { logger.error(e); throw e; }",
+  },
+  "tsforge/no-react-in-services": {
+    what: "Service/data modules must not import React — keep business logic decoupled from UI.",
+    bad: "import { useMemo } from 'react'; // in src/services/users.ts",
+    good: "Move React hooks to components; keep services as plain TypeScript.",
+  },
+  "tsforge/no-anonymous-useEffect": {
+    what: "Pass a named function to useEffect for debuggable stack traces.",
+    bad: "useEffect(() => { sync(); }, [id]);",
+    good: "useEffect(function syncOnIdChange() { sync(); }, [id]);",
+  },
+  "tsforge/no-derived-state-in-effect": {
+    what: "Do not set local state inside useEffect when the value can be derived during render.",
+    bad: "useEffect(() => { setFullName(first + ' ' + last); }, [first, last]);",
+    good: "const fullName = `${first} ${last}`;",
+  },
+  "tsforge/no-internal-api-fetch": {
+    what: "Server Components must not fetch the app's own /api routes.",
+    bad: "await fetch('/api/users');",
+    good: "import { listUsers } from '@/services/users'; const users = await listUsers();",
+  },
+  "tsforge/await-dynamic-request-apis": {
+    what: "Await Next.js dynamic request APIs in Server Components.",
+    bad: "const jar = cookies();",
+    good: "const jar = await cookies();",
+  },
+  "tsforge/error-boundary-require-use-client": {
+    what: "error.tsx and global-error.tsx must be Client Components.",
+    bad: "export default function Error() { return <div />; }",
+    good: "'use client'; export default function Error() { return <div />; }",
+  },
+  "tsforge/no-html-img-element": {
+    what: "Prefer next/image over raw img elements.",
+    bad: "<img src='/hero.jpg' alt='hero' />",
+    good: "import Image from 'next/image'; <Image src='/hero.jpg' alt='hero' width={800} height={400} />",
+  },
+  "tsforge/no-sensitive-next-public-env": {
+    what: "NEXT_PUBLIC_* vars are exposed in the client bundle — never use for secrets.",
+    bad: "process.env.NEXT_PUBLIC_STRIPE_SECRET",
+    good: "process.env.STRIPE_SECRET_KEY // server-only, no NEXT_PUBLIC prefix",
+  },
+  "tsforge/prefer-lazy-use-state-init": {
+    what: "Use lazy useState when parsing localStorage on mount.",
+    bad: "useState(JSON.parse(localStorage.getItem('cfg') ?? '{}'))",
+    good: "useState(() => JSON.parse(localStorage.getItem('cfg') ?? '{}'))",
+  },
+  "tsforge/no-auth-token-in-storage": {
+    what: "Never store auth tokens in localStorage/sessionStorage.",
+    bad: "localStorage.setItem('auth_token', token);",
+    good: "Set an httpOnly session cookie on the server instead.",
+  },
+  "tsforge/fetch-must-check-ok": {
+    what: "Check response.ok before calling .json() on fetch results.",
+    bad: "const data = await fetch(url).then(r => r.json());",
+    good: "const res = await fetch(url); if (!res.ok) { throw new Error('fetch failed'); } const data = await res.json();",
+  },
+  "tsforge/json-parse-must-validate": {
+    what: "Parse external JSON through a schema library, not bare JSON.parse.",
+    bad: "const body = JSON.parse(raw);",
+    good: "const body = UserSchema.parse(JSON.parse(raw));",
+  },
+  "tsforge/no-unsafe-boundary-cast": {
+    what: "Do not cast untrusted parsed input with `as` — validate at the boundary.",
+    bad: "const user = (await req.json()) as IUser;",
+    good: "const user = UserSchema.parse(await req.json());",
+  },
+  "tsforge/no-user-controlled-redirect": {
+    what: "Redirect URLs must be string literals or allowlisted helpers — not user input.",
+    bad: "redirect(searchParams.get('next')!);",
+    good: "redirect('/dashboard');",
+  },
+  "tsforge/no-user-controlled-fetch-url": {
+    what: "fetch/axios URLs must be literals or pass through an allowlisted URL builder.",
+    bad: "await fetch(userSuppliedUrl);",
+    good: "await fetch('https://api.example.com/v1/status');",
+  },
+  "tsforge/no-prototype-polluting-merge": {
+    what: "Do not merge request body/query/params into objects wholesale.",
+    bad: "Object.assign(config, req.body);",
+    good: "const name = UserSchema.parse(req.body).name; config.name = name;",
+  },
+  "tsforge/server-only-modules-import-server-only": {
+    what: "Server-only modules importing DB/env must include `import 'server-only'`.",
+    bad: "import { db } from '@/lib/db'; // in lib/admin.ts",
+    good: "import 'server-only'; import { db } from '@/lib/db';",
+  },
+  "tsforge/server-action-requires-authz-and-validation": {
+    what: "Server actions must validate input and call authz before mutations.",
+    bad: "'use server'; export async function deleteUser(id: string) { await db.delete(users).where(eq(users.id, id)); }",
+    good: "'use server'; export async function deleteUser(raw: unknown) { const user = await requireUser(); const { id } = IdSchema.parse(raw); await authorize(user, id); ... }",
+  },
+  "tsforge/require-route-schema": {
+    what: "Fastify routes need a schema object with input validation.",
+    bad: "fastify.post('/users', async () => ({ ok: true }));",
+    good: "fastify.post('/users', { schema: { body: UserSchema } }, async () => ({ ok: true }));",
+  },
+  "tsforge/require-plugin-name": {
+    what: "fastify-plugin wrappers need a name option.",
+    bad: "export default fp(dbPlugin);",
+    good: "export default fp(dbPlugin, { name: 'db-connector', fastify: '5.x' });",
+  },
 };
 
 /**