@agjs/tsforge 0.1.18 → 0.2.0

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

@@ -154,6 +154,11 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-throw-literal": {
+    "what": "Disallow throwing primitive literals (strings, numbers) — throw Error instances so error handlers can propagate status and stack traces correctly.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/prefer-early-return": {
     "what": "Prefer guard clauses (early return) over wrapping the function body in a multi-statement `if` without an `else`.",
     "bad": "// Example that violates the rule",
@@ -255,7 +260,37 @@
     "good": "// Corrected version"
   },
   "tsforge/require-plugin-name": {
-    "what": "Exported Elysia plugin instances must declare `new Elysia({ name: '...' })` so the runtime can deduplicate plugin re-imports.",
+    "what": "fastify-plugin (fp) wrappers must include a `name` option so Fastify can deduplicate plugin registration.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/error-handler-must-set-status": {
+    "what": "Custom Fastify setErrorHandler callbacks must call reply.code() or reply.status() — automatic status mapping is disabled when a custom handler is registered.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/prefer-return-over-reply-send": {
+    "what": "Inside Fastify route handlers, prefer `return data` over `return reply.send(data)` so fast-json-stringify can serialize responses.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/require-fp-for-shared-plugins": {
+    "what": "Fastify plugins that call fastify.decorate, fastify.addHook, or fastify.register must be wrapped in fastify-plugin (fp) to break encapsulation and share state.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/require-response-schema": {
+    "what": "Fastify routes should declare schema.response for compiled fast-json-stringify serialization.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/require-route-schema": {
+    "what": "Fastify POST/PUT/PATCH routes must declare schema.body; GET/DELETE routes must declare schema.querystring or schema.params.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/test-inject-must-close-app": {
+    "what": "Test files using fastify.inject must register teardown that calls app.close() to drain connections.",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
@@ -299,11 +334,36 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-react-in-services": {
+    "what": "Service and data-fetch modules must not import React — keep business logic decoupled from the view layer.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/await-dynamic-request-apis": {
+    "what": "Require awaiting Next.js dynamic request APIs (cookies, headers, draftMode) in app-router Server Components.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/client-hooks-require-use-client": {
     "what": "Require the 'use client' directive in app-router page/layout/template files that call client-only hooks. Server Components cannot use state/effect/navigation hooks — doing so crashes at runtime.",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/error-boundary-require-use-client": {
+    "what": "Require 'use client' in app-router error.tsx and global-error.tsx — Next.js error boundaries must be Client Components.",
+    "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",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-internal-api-fetch": {
+    "what": "Disallow Server Components from fetching the app's own /api routes — import services or ORM modules directly to avoid loopback HTTP overhead.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-next-head-in-app": {
     "what": "Disallow importing 'next/head' in app-router files. The <Head> component is a no-op under app/ — use the Metadata API (export const metadata / generateMetadata) instead.",
     "bad": "// Example that violates the rule",
@@ -314,6 +374,16 @@
     "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",
+    "good": "// Corrected version"
+  },
+  "tsforge/prefer-lazy-use-state-init": {
+    "what": "Prefer lazy useState initializers when parsing localStorage/sessionStorage — avoids re-parsing on every render.",
+    "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",
@@ -334,6 +404,11 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/dangerous-html-requires-sanitize": {
+    "what": "dangerouslySetInnerHTML requires a sanitization library (DOMPurify or equivalent) imported in the same file.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/forwardref-display-name": {
     "what": "forwardRef components must have displayName set",
     "bad": "// Example that violates the rule",
@@ -349,11 +424,26 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-anonymous-useEffect": {
+    "what": "Disallow anonymous arrow functions passed to useEffect — use a named function for debuggable stack traces.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-component-invocation": {
+    "what": "Disallow invoking React components as plain functions — use JSX (`<Header />`) instead of `{Header()}`.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-cross-feature-imports": {
     "what": "Prevent imports across different features",
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-derived-state-in-effect": {
+    "what": "Disallow setting local state inside useEffect when the value can be derived during render (or memoized with useMemo).",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-inline-jsx-functions": {
     "what": "Disallow inline function expressions in JSX attributes",
     "bad": "// Example that violates the rule",
@@ -364,11 +454,51 @@
     "bad": "// Example that violates the rule",
     "good": "// Corrected version"
   },
+  "tsforge/no-nested-component": {
+    "what": "Disallow declaring React components inside another component body — nested components reset state on every parent render.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-react-fc": {
+    "what": "Disallow React.FC / FunctionComponent — type props explicitly on the function parameter instead.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
   "tsforge/no-state-in-component-body": {
     "what": "State hooks must be in .hooks.ts files, not directly in components",
     "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",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-auth-token-in-storage": {
+    "what": "Disallow storing or reading auth tokens from localStorage/sessionStorage — use httpOnly cookies instead.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-child-process-exec": {
+    "what": "Disallow child_process.exec/execSync — they run commands in a shell. Use execFile or spawn without shell instead.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-dynamic-regexp": {
+    "what": "Disallow new RegExp(non-literal) — dynamic patterns enable ReDoS. Use string-literal regexes or a safe engine like re2.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-inner-html-assignment": {
+    "what": "Disallow assigning to innerHTML — use textContent/innerText or sanitize with DOMPurify before injecting HTML.",
+    "bad": "// Example that violates the rule",
+    "good": "// Corrected version"
+  },
+  "tsforge/no-spawn-with-shell": {
+    "what": "Disallow child_process.spawn/spawnSync with shell: true — shell execution enables command injection.",
+    "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",

package/src/loop/run.ts

@@ -366,6 +366,9 @@ export async function runTask(
       role: "assistant",
       content: res.content,
       toolCalls: res.toolCalls,
+      ...(res.reasoning === undefined
+        ? {}
+        : { reasoningContent: res.reasoning }),
     });
 
     // Every model call advances cooldown accounting — including interrupted

package/src/loop/session.ts

@@ -144,6 +144,17 @@ export interface ISendOptions {
 
 const SESSION_ID = "session";
 
+/** Build the assistant history message, carrying `reasoningContent` when the
+ *  model produced it (DeepSeek's thinking mode requires it replayed). */
+function assistantMessage(res: IModelResponse): IChatMessage {
+  return {
+    role: "assistant",
+    content: res.content,
+    toolCalls: res.toolCalls,
+    ...(res.reasoning === undefined ? {} : { reasoningContent: res.reasoning }),
+  };
+}
+
 /** Default share of the context window that triggers auto-compaction. */
 const AUTO_COMPACT_AT = 0.8;
 
@@ -1054,11 +1065,7 @@ export class Session {
       });
     }
 
-    ctx.messages.push({
-      role: "assistant",
-      content: res.content,
-      toolCalls: res.toolCalls,
-    });
+    ctx.messages.push(assistantMessage(res));
 
     if (res.salvaged !== undefined && res.salvaged > 0) {
       report({

package/src/loop/ttsr-defaults.ts

@@ -1,5 +1,8 @@
 import type { ITtsrRule } from "./ttsr";
 
+const SRC_TS_GLOBS = ["src/**/*.ts", "src/**/*.tsx"] as const;
+const SRC_TSX_GLOBS = ["src/**/*.tsx"] as const;
+
 /**
  * Built-in TTSR rules: code quality patterns to abort and correct.
  * All scope tool-args (source of the problem), fileGlobs target src/**\/*.ts(x).
@@ -10,7 +13,7 @@ export const DEFAULT_TTSR_RULES: readonly ITtsrRule[] = [
     name: "no-as-any",
     condition: [/\bas\s+any\b/],
     scope: "tool-args",
-    fileGlobs: ["src/**/*.ts", "src/**/*.tsx"],
+    fileGlobs: [...SRC_TS_GLOBS],
     guidance:
       "Never use 'as any'. If the type is unknown, use 'unknown' or a proper type. " +
       "If the API is untyped, consider a declaration file.",
@@ -21,7 +24,7 @@ export const DEFAULT_TTSR_RULES: readonly ITtsrRule[] = [
     name: "no-ts-suppression",
     condition: [/@ts-(?:ignore|nocheck)/],
     scope: "tool-args",
-    fileGlobs: ["src/**/*.ts", "src/**/*.tsx"],
+    fileGlobs: [...SRC_TS_GLOBS],
     guidance:
       "Never suppress TypeScript with @ts-ignore/@ts-nocheck. Fix the real error; " +
       "if the library is untyped, add a declaration file instead.",
@@ -32,7 +35,7 @@ export const DEFAULT_TTSR_RULES: readonly ITtsrRule[] = [
     name: "no-empty-catch",
     condition: [/catch\s*(?:\([^)]*\))?\s*\{\s*\}/],
     scope: "tool-args",
-    fileGlobs: ["src/**/*.ts", "src/**/*.tsx"],
+    fileGlobs: [...SRC_TS_GLOBS],
     guidance:
       "Empty catch blocks hide errors. Log them or handle them: " +
       "catch (e) { console.error(e); } at minimum.",
@@ -43,11 +46,179 @@ export const DEFAULT_TTSR_RULES: readonly ITtsrRule[] = [
     name: "no-console-log",
     condition: [/\bconsole\.(?:log|debug)\s*\(/],
     scope: "tool-args",
-    fileGlobs: ["src/**/*.ts", "src/**/*.tsx"],
+    fileGlobs: [...SRC_TS_GLOBS],
     guidance:
       "Remove console.log/debug before shipping. Use a logger or remove the line. " +
       "Tests can call console.log; production code must not.",
     repeatMode: "cooldown",
     repeatGap: 5,
   },
+  {
+    name: "no-react-fc",
+    condition: [
+      /React\.(?:FC|FunctionComponent|VFC)\b/,
+      /\bFunctionComponent\s*</,
+    ],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TSX_GLOBS],
+    guidance:
+      "Do not use React.FC — type props explicitly on the function parameter instead.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "no-throw-literal",
+    condition: [/throw\s+['"`]/, /throw\s+\d+/],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TS_GLOBS],
+    guidance:
+      "Do not throw string/number literals — throw `new Error('...')` so error handlers propagate correctly.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "dangerous-html-unsanitized",
+    condition: [/dangerouslySetInnerHTML/],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TSX_GLOBS],
+    guidance:
+      "dangerouslySetInnerHTML requires sanitizing with DOMPurify (or isomorphic-dompurify) before rendering.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "no-child-process-exec",
+    condition: [/\bchild_process\.exec\b/, /\bexecSync\s*\(/],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TS_GLOBS],
+    guidance:
+      "Do not use child_process.exec/execSync — use execFile or spawn without shell to avoid command injection.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "no-inner-html-assignment",
+    condition: [/\.innerHTML\s*=/],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TS_GLOBS],
+    guidance:
+      "Do not assign to innerHTML — use textContent for plain text or sanitize with DOMPurify first.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "no-dynamic-regexp",
+    condition: [/new RegExp\s*\(\s*(?!['"`])/],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TS_GLOBS],
+    guidance:
+      "Do not construct RegExp from runtime values — use a string-literal pattern or a safe regex library to avoid ReDoS.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "no-internal-api-fetch",
+    condition: [/fetch\s*\(\s*['"`]\/api/],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TS_GLOBS],
+    guidance:
+      "Server Components must not fetch /api routes — import the service or ORM module directly.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "no-unawaited-cookies",
+    condition: [/(?<![\w.])cookies\s*\(\s*\)/],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TS_GLOBS],
+    guidance:
+      "Await dynamic request APIs: `const jar = await cookies()` in Server Components.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "no-html-img",
+    condition: [/<img[\s/>]/],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TSX_GLOBS],
+    guidance:
+      "Use next/image `<Image />` instead of raw `<img>` for optimized responsive images.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "no-sensitive-next-public-env",
+    condition: [
+      /NEXT_PUBLIC_(?:.*(?:SECRET|PRIVATE|PASSWORD|TOKEN|DATABASE|STRIPE|KEY))/i,
+    ],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TS_GLOBS],
+    guidance:
+      "Never prefix secret env vars with NEXT_PUBLIC_ — they are embedded in the client bundle.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "no-auth-token-in-storage",
+    condition: [
+      /localStorage\.(?:setItem|getItem).*(?:token|session|auth|jwt)/i,
+      /sessionStorage\.(?:setItem|getItem).*(?:token|session|auth|jwt)/i,
+    ],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TS_GLOBS],
+    guidance:
+      "Do not store auth tokens in localStorage — use httpOnly secure cookies instead.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "no-user-controlled-redirect",
+    condition: [/redirect\s*\(\s*(?!['"`])/],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TS_GLOBS],
+    guidance:
+      "Do not redirect to a runtime URL — use a string literal path or an allowlisted helper.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "fetch-without-ok-check",
+    condition: [/\.json\s*\(\s*\)/],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TS_GLOBS],
+    guidance:
+      "Check response.ok (or status) before calling .json() on a fetch response.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "server-only-missing",
+    condition: [/from\s+['"]@\/lib\/(?:db|database|auth)/],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TS_GLOBS],
+    guidance:
+      "Add `import 'server-only';` at the top of modules that import DB or auth internals.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "server-action-without-parse",
+    condition: [/"use server"[\s\S]{0,200}(?:update|insert|delete)\s*\(/],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TS_GLOBS],
+    guidance:
+      "Server actions must call `.parse(` or `.safeParse(` on input before database writes.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
+  {
+    name: "no-secret-props-to-client",
+    condition: [/(?:token|session|password|secret)=\{/i],
+    scope: "tool-args",
+    fileGlobs: [...SRC_TSX_GLOBS],
+    guidance:
+      "Do not pass session/token/password props from Server Components to Client Components.",
+    repeatMode: "cooldown",
+    repeatGap: 5,
+  },
 ];

package/src/meta-rules/registry.ts

@@ -1,14 +1,30 @@
 import type { IMetaRule } from "./meta-rules.types";
 import { packageExactDepsRule } from "./rules/supply-chain/package-exact-deps";
+import { fastifySecurityPluginsRule } from "./rules/supply-chain/fastify-security-plugins";
 import { noOverlappingLibsRule } from "./rules/supply-chain/no-overlapping-libs";
+import { lockfileRequiredRule } from "./rules/supply-chain/lockfile-required";
+import { singlePackageManagerRule } from "./rules/supply-chain/single-package-manager";
+import { packageManagerFieldRequiredRule } from "./rules/supply-chain/package-manager-field-required";
+import { noGitOrTarballDependenciesRule } from "./rules/supply-chain/no-git-or-tarball-dependencies";
+import { dependencyOverridesRequireCommentRule } from "./rules/supply-chain/dependency-overrides-require-comment";
+import { productionMustNotUseDrizzlePushRule } from "./rules/supply-chain/production-must-not-use-drizzle-push";
+import { migrationsMustBeCheckedInRule } from "./rules/supply-chain/migrations-must-be-checked-in";
 import { noEslintDisableCommentsRule } from "./rules/source-text/no-eslint-disable-comments";
 import { noTsSuppressionRule } from "./rules/source-text/no-ts-suppressions";
+import { nextImageRemotePatternsNoWildcardsRule } from "./rules/config/next-image-remote-patterns-no-wildcards";
+import { nextInstrumentationPresentRule } from "./rules/config/next-instrumentation-present";
+import { nextProxyOverMiddlewareRule } from "./rules/config/next-proxy-over-middleware";
 import { tsconfigPathsExistRule } from "./rules/config/tsconfig-paths-exist";
+import { tsconfigRecommendedFlagsRule } from "./rules/config/tsconfig-recommended-flags";
 import { tsconfigStrictRule } from "./rules/config/tsconfig-strict";
 import { testSiblingRequiredRule } from "./rules/testing/test-sibling-required";
 import { workflowActionsPinnedRule } from "./rules/ci/workflow-actions-pinned";
 import { workflowRunnerPinnedRule } from "./rules/ci/workflow-runner-pinned";
 import { workflowTimeoutRequiredRule } from "./rules/ci/workflow-timeout-required";
+import { workflowPermissionsExplicitRule } from "./rules/ci/workflow-permissions-explicit";
+import { workflowPermissionsLeastPrivilegeRule } from "./rules/ci/workflow-permissions-least-privilege";
+import { noPullRequestTargetUntrustedCheckoutRule } from "./rules/ci/no-pull-request-target-untrusted-checkout";
+import { noGithubContextInShellRule } from "./rules/ci/no-github-context-in-shell";
 
 /**
  * All available meta-rules, ordered by category for readability.
@@ -17,7 +33,15 @@ import { workflowTimeoutRequiredRule } from "./rules/ci/workflow-timeout-require
 export const META_RULES: readonly IMetaRule[] = [
   // Supply chain
   packageExactDepsRule,
+  fastifySecurityPluginsRule,
   noOverlappingLibsRule,
+  lockfileRequiredRule,
+  singlePackageManagerRule,
+  packageManagerFieldRequiredRule,
+  noGitOrTarballDependenciesRule,
+  dependencyOverridesRequireCommentRule,
+  productionMustNotUseDrizzlePushRule,
+  migrationsMustBeCheckedInRule,
 
   // Source text
   noEslintDisableCommentsRule,
@@ -25,7 +49,11 @@ export const META_RULES: readonly IMetaRule[] = [
 
   // Config
   tsconfigPathsExistRule,
+  tsconfigRecommendedFlagsRule,
   tsconfigStrictRule,
+  nextProxyOverMiddlewareRule,
+  nextInstrumentationPresentRule,
+  nextImageRemotePatternsNoWildcardsRule,
 
   // Testing
   testSiblingRequiredRule,
@@ -34,4 +62,8 @@ export const META_RULES: readonly IMetaRule[] = [
   workflowActionsPinnedRule,
   workflowRunnerPinnedRule,
   workflowTimeoutRequiredRule,
+  workflowPermissionsExplicitRule,
+  workflowPermissionsLeastPrivilegeRule,
+  noPullRequestTargetUntrustedCheckoutRule,
+  noGithubContextInShellRule,
 ];

package/src/meta-rules/rules/ci/no-github-context-in-shell.ts

@@ -0,0 +1,40 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+const RUN_WITH_GITHUB_EVENT = /^ {4,}-?\s*run:\s.*\$\{\{\s*github\.event/u;
+
+export const noGithubContextInShellRule: IMetaRule = {
+  id: "no-github-context-in-shell",
+  category: "ci",
+  description:
+    "Do not interpolate github.event context directly in run: shell steps — pass values through env: first.",
+  severity: "warn",
+  run({ workflowFiles, readFile }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    for (const file of workflowFiles) {
+      const text = readFile(file);
+
+      if (text === null) {
+        continue;
+      }
+
+      const lines = text.split("\n");
+
+      for (const line of lines) {
+        if (!RUN_WITH_GITHUB_EVENT.test(line)) {
+          continue;
+        }
+
+        violations.push({
+          file,
+          ruleId: "no-github-context-in-shell",
+          severity: "warn",
+          message:
+            "Shell `run:` step interpolates `${{ github.event... }}` directly — assign the value to an `env:` entry and reference the env var in the script to avoid injection.",
+        });
+      }
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/ci/no-pull-request-target-untrusted-checkout.ts

@@ -0,0 +1,42 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+
+const PULL_REQUEST_TARGET_PATTERN = /(?:^|\s)pull_request_target(?:\s|:|$)/u;
+const UNTRUSTED_CHECKOUT_PATTERN =
+  /github\.event\.pull_request\.head\.(?:sha|ref)/u;
+
+export const noPullRequestTargetUntrustedCheckoutRule: IMetaRule = {
+  id: "no-pull-request-target-untrusted-checkout",
+  category: "ci",
+  description:
+    "Disallow pull_request_target workflows that checkout the PR head ref (untrusted code with write token).",
+  severity: "warn",
+  run({ workflowFiles, readFile }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    for (const file of workflowFiles) {
+      const text = readFile(file);
+
+      if (text === null) {
+        continue;
+      }
+
+      if (!PULL_REQUEST_TARGET_PATTERN.test(text)) {
+        continue;
+      }
+
+      if (!UNTRUSTED_CHECKOUT_PATTERN.test(text)) {
+        continue;
+      }
+
+      violations.push({
+        file,
+        ruleId: "no-pull-request-target-untrusted-checkout",
+        severity: "warn",
+        message:
+          "`pull_request_target` combined with checkout of `github.event.pull_request.head.*` runs untrusted PR code with elevated workflow permissions — use `pull_request` or checkout the base ref instead.",
+      });
+    }
+
+    return violations;
+  },
+};

package/src/meta-rules/rules/ci/workflow-permissions-explicit.ts

@@ -0,0 +1,49 @@
+import type { IMetaRule, IMetaRuleViolation } from "../../meta-rules.types";
+import {
+  collectJobBlocks,
+  hasWorkflowLevelPermissions,
+} from "../../utils/workflow-yaml";
+
+export const workflowPermissionsExplicitRule: IMetaRule = {
+  id: "workflow-permissions-explicit",
+  category: "ci",
+  description:
+    "GitHub Actions workflows must declare permissions at the workflow or job level.",
+  severity: "warn",
+  run({ workflowFiles, readFile }) {
+    const violations: IMetaRuleViolation[] = [];
+
+    for (const file of workflowFiles) {
+      const text = readFile(file);
+
+      if (text === null) {
+        continue;
+      }
+
+      if (hasWorkflowLevelPermissions(text)) {
+        continue;
+      }
+
+      const jobs = collectJobBlocks(text);
+      const jobsMissingPermissions = jobs.filter(
+        (job) =>
+          !job.lines.some((line) => /^ {4}permissions:\s*(?:#.*)?$/u.test(line))
+      );
+
+      if (jobsMissingPermissions.length === 0) {
+        continue;
+      }
+
+      const jobNames = jobsMissingPermissions.map((job) => job.name).join(", ");
+
+      violations.push({
+        file,
+        ruleId: "workflow-permissions-explicit",
+        severity: "warn",
+        message: `Workflow is missing top-level \`permissions:\` and jobs without job-level permissions: ${jobNames}. Declare least-privilege permissions at workflow or job scope.`,
+      });
+    }
+
+    return violations;
+  },
+};