@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/js-ts/checks/zod-string-needs-max.json

@@ -0,0 +1,25 @@
+{
+  "id": "zod-string-needs-max",
+  "why": "An unbounded z.string() accepts a 16 MB value into the document and the $jsonSchema derived from it has no maxLength either. Every string carries .max().",
+  "rule": ".claude/rules/schema-single-source-of-truth.md",
+  "concepts": [
+    "schemas"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**"
+  ],
+  "code": true,
+  "flags": "",
+  "pattern": "(?<!\\bz\\.record\\(\\s*)(?<!\\w_id:\\s{0,4})(?<!\\b_id:\\s{0,4})\\bz\\.string\\(\\)(?:\\.(?!(?:max|length|regex|uuid|datetime|email|url|ip|enum)\\b)\\w+\\([^()]*\\))*\\s*[,)\\]}]",
+  "bad": "cwd: z.string().min(1),\nhost: z.string(),",
+  "good": "cwd: z.string().min(1).max(4096),\nhost: z.string().max(253),\nhex: z.string().regex(HEX),\n_id: z.string(),\nsession_id: z.string(),\nfacts: z.record(z.string(), z.unknown()),"
+}

package/packs/js-ts/checks/zod-v4-formats.json

@@ -0,0 +1,23 @@
+{
+  "id": "zod-v4-formats",
+  "why": "z.string().email()/.uuid()/.url()/.datetime()/.ip() are the deprecated Zod 3 spellings. Zod 4 has z.email(), z.uuid(), z.url(), z.iso.datetime(), z.ipv4().",
+  "rule": ".claude/rules/schema-single-source-of-truth.md",
+  "concepts": [
+    "js"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    ".claude/**",
+    "**/.claude/**"
+  ],
+  "code": true,
+  "pattern": "\\bz\\.string\\(\\)\\s*\\.(email|uuid|url|datetime|date|time|ip|ipv4|ipv6|emoji|cuid|ulid|base64)\\s*\\(",
+  "bad": "at: z.string().datetime(),\nmail: z.string().email(),",
+  "good": "at: z.iso.datetime(),\nmail: z.email(),",
+  "whenDep": {
+    "zod": 4
+  }
+}

package/packs/js-ts/pack.json

@@ -0,0 +1,84 @@
+{
+  "name": "js-ts",
+  "version": "1.0.0",
+  "description": "JavaScript and TypeScript: strict types, no any, errors never swallowed, every promise handled, process lifecycle, schemas as the one source of truth, JSON only through one helper.",
+  "type": "stock",
+  "author": "claude-packs",
+  "license": "MIT",
+  "homepage": "https://github.com/TheDecipherist/claude-packs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheDecipherist/claude-packs.git",
+    "directory": "packs/js-ts"
+  },
+  "keywords": [
+    "javascript",
+    "typescript"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "folders": {},
+  "concepts": {
+    "js": [
+      "**/*.js",
+      "**/*.mjs",
+      "**/*.cjs",
+      "**/*.ts",
+      "**/*.tsx",
+      "**/*.jsx"
+    ],
+    "ts": [
+      "**/*.ts",
+      "**/*.tsx"
+    ],
+    "js-tests": [
+      "**/*.test.ts",
+      "**/*.test.tsx",
+      "**/*.spec.ts",
+      "**/*.test.js",
+      "**/*.test.mjs"
+    ],
+    "tsconfig": [
+      "**/tsconfig*.json"
+    ],
+    "routes": [
+      "**/routes/**/*.ts",
+      "**/server/**/*.ts",
+      "**/app.ts",
+      "**/server.ts"
+    ],
+    "entry": [
+      "**/server.ts",
+      "**/server.js",
+      "**/server.mjs",
+      "**/src/index.ts",
+      "**/src/index.js",
+      "**/src/main.ts",
+      "**/src/app.ts",
+      "**/index.ts",
+      "**/bin/**",
+      "**/worker/**/index.*",
+      "**/*.worker.ts",
+      "**/lifecycle.*"
+    ],
+    "schemas": [
+      "**/schemas/**",
+      "**/schema/**",
+      "**/*.schema.ts",
+      "**/*.schema.js",
+      "**/models/**",
+      "**/types/**"
+    ],
+    "handlers": [
+      "**/routes/**",
+      "**/handlers/**",
+      "**/adapters/**",
+      "**/services/**",
+      "**/controllers/**",
+      "**/app/api/**"
+    ]
+  },
+  "skillsIn": null,
+  "hooks": {}
+}

package/packs/js-ts/rules/await-handled-at-a-boundary.md

@@ -0,0 +1,66 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# Every await is handled somewhere on purpose: at a boundary, for cleanup, or to recover
+
+A `try/catch` around every `await` is not the goal. One that only logs and rethrows doubles every log line, and one that returns `null` hides the failure. The goal is that **no rejection is ever unhandled**, and that each one is handled **in the one place that can do something about it**.
+
+<constraints>
+Always do:
+- **Boundaries with no catcher of their own get a `try/catch` that logs with context and ends the unit of work cleanly:**
+  - `setTimeout`, `setInterval` and `setImmediate` callbacks;
+  - event handlers (`.on`, `.once`, `addEventListener`, stream and socket events);
+  - queue and change-stream consumers, cron jobs, MCP tool handlers (check what your SDK version does with a throw), CLI `main()`.
+  Wrap these with the project's `guarded(fn, log, what)` helper (`lib/guarded.ts`: create it if the project has none), which is the only place that writes that `try/catch`.
+- **Boundaries that do catch** stay thin: Fastify route handlers just `await` and `throw`. Fastify's error handler (`setErrorHandler`) maps the error to a response and logs it once.
+- **A resource that must be released** (a session, a lock, a file handle, a Mongo transaction, a Chrome) gets `try { … } finally { release }`, or `await using` when the resource supports it.
+- **An operation you can actually recover from** (retry, fallback, a default for a missing optional) catches **only the error it can recover from**, narrowed with `instanceof` or a code, and rethrows everything else.
+- **The process has a last line:** the entrypoint registers `process.on('unhandledRejection')` and `process.on('uncaughtException')`, which log with pino and exit non-zero, so a missed rejection is loud, never silent.
+
+Never do:
+- Pass an `async` function where nobody awaits it (`setInterval(async …)`, `emitter.on('x', async …)`, `arr.forEach(async …)`). The `async-callback-unguarded` check refuses it; wrap it in `guarded(…)`.
+- Swallow: an empty `catch {}`, `.catch(() => {})`, `.catch(() => null)`. The `no-swallowed-errors` check refuses them.
+- Wrap an await in `try/catch` only to log and rethrow. The boundary logs it.
+</constraints>
+
+```ts
+// lib/guarded.ts: the one place a "log and carry on" catch is written
+export function guarded<A extends unknown[]>(fn: (...a: A) => Promise<unknown>, log: Logger, what: string) {
+  return (...a: A): void => {
+    let pending: Promise<unknown>;
+    try { pending = fn(...a); }                       // a sync throw before the first await
+    catch (err: unknown) { log.error({ err, what }, 'background task failed'); return; }
+    pending.catch((err: unknown) => log.error({ err, what }, 'background task failed'));
+  };
+}
+export function exitOnUnhandled(log: Logger): void {  // call once, in the entrypoint
+  for (const ev of ['unhandledRejection', 'uncaughtException'] as const)
+    process.on(ev, (err: unknown) => { log.error({ err }, ev); process.exit(1); });
+}
+
+// NO: a rejection here is unhandled and, since Node 15, kills the process
+setInterval(async () => { await sweepExpired(db); }, 60_000);
+
+// YES
+setInterval(guarded(() => sweepExpired(db), log, 'sweep expired sessions'), 60_000);
+
+// Cleanup, not catching
+const session = client.startSession();
+try { await session.withTransaction(() => moveFunds(session, from, to, amount)); }
+finally { await session.endSession(); }
+
+// Recover from one thing only
+try { return await cache.get(key); }
+catch (err: unknown) {
+  if (err instanceof CacheUnavailableError) return await loadFromDb(key);
+  throw err;
+}
+```
+
+## Checks
+- `async-callback-unguarded`: an `async` function passed to a timer, an event handler or `forEach`.
+- `no-swallowed-errors`: an empty `catch`, `.catch(() => {})`, `.catch(() => null | undefined)`.
+- `no-floating-promises` (type-aware ESLint) catches the rest, which a regex can't see. Wire it into the edit hook where the project has ESLint.

package/packs/js-ts/rules/env-through-config.md

@@ -0,0 +1,36 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# Environment variables only through one validated config
+
+## The law
+`process.env` is read in exactly one file, `src/config.ts`. That file parses it with Zod at startup and exports a typed, frozen `config`. A missing or malformed variable crashes the boot with a clear message rather than failing later at the first request.
+
+```ts
+// src/config.ts
+const Env = z.object({
+  MONGODB_URI: z.string().url(),
+  PORT: z.coerce.number().int().default(3000),
+  GROVE_API_KEY: z.string().min(1),
+});
+export const config = Object.freeze(Env.parse(process.env));
+
+// anywhere else
+import { config } from './config.js';
+```
+
+## Never
+- Hardcode a secret, key, token or connection string in source, even "temporarily".
+- Read `process.env.X` inline elsewhere.
+
+## Check
+```js
+// eslint-plugin-n
+'n/no-process-env': 'error',
+// override for the one allowed file:
+{ files: ['src/config.ts'], rules: { 'n/no-process-env': 'off' } },
+```
+Secrets: run `gitleaks git --pre-commit --staged` in the pre-commit hook.

package/packs/js-ts/rules/errors-never-swallowed.md

@@ -0,0 +1,33 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# Errors are typed, thrown as Error, and never swallowed
+
+## The law
+- Catch variables are `unknown`; narrow with `instanceof` before reading `.message`.
+- Throw only `Error` instances (or subclasses), never strings or plain objects.
+- A `catch` block either handles the error meaningfully, rethrows it with context (`new Error('...', { cause: err })`), or logs and rethrows. An empty catch is never allowed.
+- In Fastify, throw and let the error handler map it to a response; don't build error responses ad hoc in every handler.
+
+```ts
+try {
+  await saveOrder(order);
+} catch (err: unknown) {
+  throw new Error(`saveOrder failed for ${order.id}`, { cause: err });
+}
+```
+
+## Check
+**Enforced:** the `no-swallowed-errors` lesson check refuses an empty `catch`, `.catch(() => {})` and `.catch(() => null)` at edit time. Where errors are handled at all, see `await-handled-at-a-boundary`.
+
+ESLint, where the project has it:
+```js
+'no-empty': 'error',
+'@typescript-eslint/only-throw-error': 'error',
+'@typescript-eslint/use-unknown-in-catch-callback-variable': 'error',
+'prefer-promise-reject-errors': 'error',
+```
+`useUnknownInCatchVariables` comes with `strict` in tsconfig (see tsconfig-strict).

package/packs/js-ts/rules/files-under-300-lines.md

@@ -0,0 +1,18 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# No source file over 300 lines
+
+## The law
+A file holds one module with one responsibility, and never more than 300 lines. Before a file reaches the limit, split it by responsibility (types, schema, helpers, the main logic) into a folder with an `index.ts` that re-exports. Never split it arbitrarily into part1 and part2.
+
+(The downloaded templates allowed 800 lines; this house limit replaces that.)
+
+## Check
+```js
+'max-lines': ['error', { max: 300, skipBlankLines: false, skipComments: false }],
+```
+The existing edit hook that refuses oversized files remains the hard stop.

package/packs/js-ts/rules/guard-clauses-over-nesting.md

@@ -0,0 +1,34 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# Guard clauses over nesting
+
+## The law
+Handle the invalid, empty and error cases first with early returns or throws. Then the main path runs unindented at the bottom. Max nesting depth is 3.
+
+```ts
+// NO
+function ship(order?: Order) {
+  if (order) {
+    if (order.paid) {
+      if (order.items.length) { return dispatch(order); }
+    }
+  }
+}
+
+// YES
+function ship(order?: Order) {
+  if (!order) throw new Error('no order');
+  if (!order.paid) throw new Error('unpaid');
+  if (!order.items.length) return;
+  return dispatch(order);
+}
+```
+
+## Check
+```js
+'max-depth': ['error', 3],
+```

package/packs/js-ts/rules/js-repeats-become-templates.md

@@ -0,0 +1,26 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# Anything repeated in JS or TS becomes a template: pick the form that fits the repeat
+
+<constraints>
+Always do:
+- Match the repeat to its form:
+  - Markup used twice: one component, with what differs as props.
+  - A block with the same statements and other names: one function, with what differs as its parameters. `template-law` and `scan` list what differs.
+  - Handlers alike but for a few lines: one factory that returns the handler, each kind passing what is its own.
+  - The same wrapping around many functions (auth, retry, timing): one higher-order function.
+  - One call repeated with other arguments: an array of rows and one loop, typed with `satisfies`.
+  - Stateful logic shared between components: one hook.
+- Export a helper from the module its users already import, and import it. Search before writing one.
+
+Never do:
+- Define `sleep`, `escapeHtml`, `formatDate` or the like again in a new file.
+- Copy a route, a handler or a page to change a few lines.
+</constraints>
+
+## Check
+`template-law` refuses a new copy, a near copy or a function the repo already has. `make-it-a-template` walks the change.

package/packs/js-ts/rules/json-only-through-one-helper.md

@@ -0,0 +1,62 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# JSON goes in and out through one helper; a logger never throws
+
+`JSON.stringify` **throws** on a circular reference, a `BigInt` or a `toJSON()` that throws. It silently turns an `Error` into `{}` and drops `undefined`. `JSON.parse` throws on any bad input. Data typed `unknown` (log fields, request bodies, Mongo documents, API responses) can contain any of these. A raw call is a crash waiting for the one value that triggers it, and a logger that crashes takes the request down with it.
+
+<constraints>
+Always do:
+- **Logs:** use the structured logger, never `console` plus `JSON.stringify`. In Fastify that is pino: `request.log` / `fastify.log`, `log.info({ fields }, 'message')`, with errors under the `err` key so pino records name, message and stack. Pino serializes safely and never throws on odd values.
+- **Everything else:** one file per project, `lib/json.ts` (create it if the project has none), holds the only `JSON.parse` and `JSON.stringify` calls:
+  - `toJson(value)` uses `safe-stable-stringify`: circular references become `"[Circular]"`, `BigInt` becomes a string, `Error` becomes `{ name, message, stack, cause }`. It returns a string and never throws.
+  - `parseJson(text, schema)` wraps `JSON.parse` in `try` and validates with the Zod schema. It returns `{ ok: true, value } | { ok: false, error }` and never throws.
+- Check the current version of `safe-stable-stringify` and `pino` with `latest-versions` before adding them.
+
+Never do:
+- Call `JSON.parse` or `JSON.stringify` anywhere but `lib/json.ts` (tests and config files excepted). The `json-only-through-helper` check refuses it.
+- Write a logger, error handler or response path that can throw. If logging fails, the request must still finish.
+</constraints>
+
+```ts
+// NO: throws on a BigInt, a circular object or a throwing toJSON; turns errors into {}
+export function logLine(level: 'info' | 'warn' | 'error', fields: Record<string, unknown>): void {
+  console.log(JSON.stringify({ ts: new Date().toISOString(), level, service: 'admiralmcp-api', ...fields }));
+}
+
+// YES, in a Fastify service: the framework's logger
+const app = Fastify({ logger: { base: { service: 'admiralmcp-api' } } });
+request.log.warn({ jobId, err }, 'job retry');
+
+// YES, outside Fastify: lib/json.ts is the only file that touches JSON
+import { configure } from 'safe-stable-stringify';
+const stringify = configure({ bigint: true, circularValue: '[Circular]' });
+const errorsAsObjects = (_k: string, v: unknown) =>
+  v instanceof Error ? { name: v.name, message: v.message, stack: v.stack, cause: v.cause } : v;
+
+export function toJson(value: unknown): string {
+  try {
+    return stringify(value, errorsAsObjects) ?? 'null';
+  } catch (err) {
+    return `{"unserializable":true,"reason":${JSON.stringify(String(err))}}`;
+  }
+}
+
+export type Parsed<T> = { ok: true; value: T } | { ok: false; error: string };
+export function parseJson<T>(text: string, schema: z.ZodType<T>): Parsed<T> {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (err) {
+    return { ok: false, error: `not JSON: ${err instanceof Error ? err.message : String(err)}` };
+  }
+  const r = schema.safeParse(raw);
+  return r.success ? { ok: true, value: r.data } : { ok: false, error: r.error.message };
+}
+```
+
+## Check
+`.claude/checks/json-only-through-helper.json` refuses an edit that adds `JSON.parse(` or `JSON.stringify(` outside `**/lib/json.*`, tests and config files. If a raw call slips in by another route (`Response.json()` on unknown input, `structuredClone` of an unknown value, a `toJSON` that throws), add that shape to the check.

package/packs/js-ts/rules/named-constants-not-magic-numbers.md

@@ -0,0 +1,34 @@
+---
+# concepts: ts
+paths:
+  - "placeholder"
+---
+
+# Named constants, not magic numbers
+
+## The law
+Any number with meaning (a timeout, limit, threshold, retry count, status code) gets a named constant that says what it is and its unit.
+
+```ts
+// NO
+setTimeout(retry, 30000);
+if (items.length > 100) paginate();
+
+// YES
+const RETRY_DELAY_MS = 30_000;
+const MAX_PAGE_SIZE = 100;
+```
+
+## Check
+```js
+'@typescript-eslint/no-magic-numbers': ['error', {
+  ignore: [-1, 0, 1, 2],
+  ignoreArrayIndexes: true,
+  ignoreEnums: true,
+  ignoreNumericLiteralTypes: true,
+  ignoreReadonlyClassProperties: true,
+  ignoreTypeIndexes: true,
+}],
+{ files: ['**/*.test.*', '**/*.spec.*'], rules: { '@typescript-eslint/no-magic-numbers': 'off' } },
+```
+Turn off core `no-magic-numbers` when enabling the TS version.

package/packs/js-ts/rules/no-any.md

@@ -0,0 +1,34 @@
+---
+# concepts: ts
+paths:
+  - "placeholder"
+---
+
+# No `any`
+
+## The law
+Never type anything as `any`. Use `unknown` for data you don't control yet, then narrow it (Zod parse, `instanceof`, type guard). Use a generic when the type depends on the caller.
+
+```ts
+// NO
+function handle(data: any) { return data.id; }
+
+// YES
+function handle(data: unknown) {
+  const { id } = IdSchema.parse(data);
+  return id;
+}
+```
+
+## Exceptions
+- Third-party type gaps: wrap the untyped call once in a typed adapter, put the single `any` there, and add an eslint-disable comment that gives the reason.
+
+## Check
+```js
+'@typescript-eslint/no-explicit-any': 'error',
+'@typescript-eslint/no-unsafe-assignment': 'error',
+'@typescript-eslint/no-unsafe-member-access': 'error',
+```
+
+## Enforced
+`.claude/checks/no-any.json` refuses new `: any`, `as any`, `<any>`, `any[]` and `Record<…, any>` in TypeScript (tests and `.d.ts` excepted).

package/packs/js-ts/rules/no-console.md

@@ -0,0 +1,30 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# No `console.*` in application code
+
+## The law
+Log through the app logger (Fastify's built-in pino: `request.log` in handlers, `app.log` elsewhere). That gives you levels, structured JSON and request IDs. Never leave `console.log` debugging behind.
+
+```ts
+// NO
+console.log('user created', user.id);
+
+// YES
+request.log.info({ userId: user.id }, 'user created');
+```
+
+## Exceptions
+- CLI scripts and build tooling (`scripts/**`, `bin/**`), where stdout is the interface.
+
+## Check
+```js
+'no-console': 'error',
+{ files: ['scripts/**', 'bin/**'], rules: { 'no-console': 'off' } },
+```
+
+## Enforced
+`.claude/checks/no-console-in-app.json` refuses new `console.*` calls in application code (tests, `bin/`, `scripts/`, `tools/` and CLIs excepted).

package/packs/js-ts/rules/no-floating-promises.md

@@ -0,0 +1,31 @@
+---
+# concepts: ts
+paths:
+  - "placeholder"
+---
+
+# Every promise is awaited, returned or explicitly voided
+
+## The law
+A promise that is neither awaited, returned, nor handled is a silent failure: its rejection is lost and the code after it runs before it finishes. If fire-and-forget is truly intended, write `void task().catch(log)` so the intent is visible.
+
+Never pass an async function where a sync callback is expected (`forEach`, event emitters, `setTimeout`), because its rejections vanish.
+
+```ts
+// NO
+users.forEach(async (u) => await notify(u));
+saveAudit(entry);
+
+// YES
+await Promise.all(users.map((u) => notify(u)));
+await saveAudit(entry);
+```
+
+## Check
+**Enforced:** the `async-callback-unguarded` lesson check refuses an `async` function passed to a timer, an event handler or `forEach` (wrap it in `guarded(…)`, see `await-handled-at-a-boundary`). A promise that is simply not awaited needs types to see, so that part is ESLint's.
+
+Needs type-aware linting (`parserOptions.projectService: true`):
+```js
+'@typescript-eslint/no-floating-promises': 'error',
+'@typescript-eslint/no-misused-promises': 'error',
+```

package/packs/js-ts/rules/no-param-mutation.md

@@ -0,0 +1,28 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# Never mutate a function's inputs
+
+## The law
+A function must not change the objects or arrays passed to it. Return a new value instead. Callers should never have their data changed under them.
+
+```ts
+// NO
+function rename(user: User, name: string) { user.name = name; return user; }
+
+// YES
+function rename(user: Readonly<User>, name: string): User {
+  return { ...user, name };
+}
+```
+
+## Not covered
+Building up a local array or object that the function itself created is fine. This law is about *inputs*, not a blanket ban on mutation (the source templates said "never mutate anything", which is impractical and was dropped).
+
+## Check
+```js
+'no-param-reassign': ['error', { props: true }],
+```

package/packs/js-ts/rules/no-unsafe-assertions.md

@@ -0,0 +1,30 @@
+---
+# concepts: ts
+paths:
+  - "placeholder"
+---
+
+# No non-null `!` and no casting object literals
+
+## The law
+- Never use the non-null assertion `x!`. Handle the `null`/`undefined` case with a guard, or throw.
+- Never cast an object literal into a type (`{...} as User`). Annotate it instead (`const u: User = {...}`) so missing fields are caught.
+- `as` on anything else needs a one-line comment saying why the compiler can't see it. Prefer a Zod parse or a type guard.
+
+```ts
+// NO
+const user = await findUser(id);
+send(user!.email);
+
+// YES
+const user = await findUser(id);
+if (!user) throw new Error(`user ${id} not found`);
+send(user.email);
+```
+
+## Check
+```js
+'@typescript-eslint/no-non-null-assertion': 'error',
+'@typescript-eslint/consistent-type-assertions': ['error',
+  { assertionStyle: 'as', objectLiteralTypeAssertions: 'never' }],
+```

package/packs/js-ts/rules/one-logger.md

@@ -0,0 +1,24 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# One logger, configured once, with a request id on every line
+
+"Log it" is not a standard. Without one, `console.error` satisfies every instruction and the deployment gets stderr soup with no level, no fields and no way to tie a 500 line to the response the user got.
+
+<constraints>
+Always do:
+- One logger module per service (pino; Fastify's own `app.log`/`request.log` in a Fastify service) exporting a configured instance. Nothing else constructs a logger or imports the logging library.
+- Structured JSON to stdout: level, timestamp, service name, request id. Stdout is what gets collected; file transports are wrong in a container.
+- The request id is generated at ingress (or taken from the incoming header) and travels: every line in a request's lifetime carries it, and the 500 body returns it as the correlation id.
+- Errors log under the `err` key so the stack is recorded, not only the message.
+- Every suppressed-repeat path ("log once and go quiet") keeps a counter somewhere visible (a metric, a periodic re-log with the count, a health field): a subsystem broken for a week must not look like a quiet week.
+- The logger never throws (`json-only-through-one-helper`): if logging fails, the request still finishes.
+
+Never do:
+- `console.*` in application code (`no-console-in-app`). Two exemptions, each marked with a comment so nobody deletes the rule: crash handlers (`uncaughtException`/`unhandledRejection`, where an async logger may not flush before exit) and pre-init boot lines that run before the logger exists.
+- What a user typed at info level (query strings, form fields): attack forensics go to a dedicated level or field with retention thought through.
+- A second logger instance, or a wrapper that swallows the level.
+</constraints>

package/packs/js-ts/rules/outbound-calls-have-a-limit.md

@@ -0,0 +1,20 @@
+---
+# concepts: js
+paths:
+  - "placeholder"
+---
+
+# Every outbound call has a deadline, and a server stops cleanly
+
+<constraints>
+Always do:
+- Pass `signal: AbortSignal.timeout(ms)` to `fetch`, and a timeout to every client.
+- Give the work the deadline, so it stops when the wait does.
+- Await `server.close()` before exit.
+
+Never do:
+- Use `Promise.race` as a timeout: it ends the wait, not the work.
+</constraints>
+
+## Check
+`fetch-needs-timeout`, `race-leaves-work-running`, `server-close-awaited`.