@dsalazardev/ai-hub-cli 0.0.0-stage → 0.1.0

package/skills/shared/typescript/SKILL.md

@@ -0,0 +1,225 @@
+---
+name: typescript
+description: "Use when writing or fixing TypeScript type code (.ts/.tsx/.d.ts), modeling data with generics/unions/branded types, diagnosing narrowing failures, or configuring tsconfig and the build toolchain. NOT runtime code, fs/streams/http (that is `nodejs`); NOT component/route typing (that is `react`/`nextjs`); NOT ORM type-gen (that is `drizzle-orm`)."
+tags: [typescript, types, generics, tsconfig, type-safety]
+recommends: [nodejs, secure-coding, drizzle-orm]
+origin: ai-hub
+---
+
+# Idiomatic TypeScript types
+
+Express data and contracts precisely in the TypeScript type system, and configure the
+compiler so the types actually hold.
+
+Targets **TypeScript 5.9** (current stable, Q1 2026): redesigned `tsc --init` defaults
+(`module: nodenext`, `target: esnext`, `moduleDetection: force`, strict on), `import defer`
+for deferred module evaluation, expandable editor hovers. The **TypeScript 7 native
+compiler** (`tsgo`, the Go port) is in preview as `@typescript/native-preview` and
+type-checks roughly 10x faster (VS Code's 1.5M LOC: 89s -> 8.74s) — adopt it for fast
+local checks; stable 7.0 lands early 2026.
+
+## Boundary: language vs runtime vs framework
+
+Three layers, three owners. **Language + compiler config lives here** — generics, narrowing,
+`.d.ts`, `tsconfig`, and the build toolchain (`tsc` vs `tsgo`, `tsx`, resolution mode).
+**Runtime behavior** (how a stream backpressures, how the event loop schedules) is `nodejs`.
+**Framework idioms** (component props, route maps, server-component typing) are
+`react`/`nextjs`/`nestjs` — those *borrow* this skill's type mechanics but own their wiring.
+A `tsconfig` question is here; a "stream backpressure" question is `nodejs`; a "type my
+`useReducer` state" question is `react`. Also delegate: ORM schema-to-type generation ->
+`drizzle-orm` / `prisma-orm`; REST/contract shape design -> `api-design`; test runner and E2E
+setup -> `testing-web` / `e2e-testing`; injection/authz review -> `secure-coding`; Python
+typing -> `python`; Go -> `go`.
+
+## Decision rules
+
+Apply these on every TypeScript edit:
+
+1. **Prefer inference; annotate boundaries.** Let TS infer locals and returns; annotate
+   function parameters, public APIs, and `.d.ts`. Why: redundant annotations drift from
+   reality and suppress the better inferred type.
+2. **`import type` for type-only imports**, with `verbatimModuleSyntax: true`. Why: it
+   prevents emitting type-only imports as runtime `require`s and lets esbuild/swc transpile
+   each file alone.
+3. **Narrow, don't cast.** Reach for type guards, `in`, `typeof`, discriminant checks before
+   `as`; when `as` is unavoidable, only `as <narrower>` or `as unknown as T` at a true I/O
+   boundary. Why: `as` asserts a claim the compiler cannot verify — it is a silenced error,
+   and `as` to a *wider* or unrelated type is almost always a real bug hidden.
+
+## The type-system toolbox
+
+### Generics + constraints, and `const` type parameters
+
+Constrain type parameters so callers get errors at the call site, and use a `const` type
+parameter (TS 5.0+) to preserve literal inference without `as const` everywhere:
+
+```ts
+// Bad: unconstrained T, and the literal "a"|"b" widens to string.
+function pick<T>(obj: T, key: string) { return (obj as any)[key]; }
+
+// Good: K is constrained to obj's keys; const T keeps the literal union.
+function pick<const T, K extends keyof T>(obj: T, key: K): T[K] {
+  return obj[key];
+}
+const r = pick({ a: 1, b: "x" } as const, "b"); // r: "x", not string
+```
+
+### `unknown` over `any` at every boundary
+
+`any` disables checking and silently poisons every downstream type it touches; `unknown`
+forces a narrow before use.
+
+```ts
+// Bad: any flows everywhere, no error ever fires downstream.
+function parse(json: string): any { return JSON.parse(json); }
+
+// Good: unknown forces a narrow before the value is trusted.
+function parse(json: string): unknown { return JSON.parse(json); }
+const data = parse(input);
+if (typeof data === "object" && data && "id" in data) { /* now narrowed */ }
+```
+
+### `satisfies` for config validation without widening
+
+```ts
+type Route = { path: string; method: "GET" | "POST" };
+
+// Bad: annotation widens — routes.home.method is "GET" | "POST", and a typo in
+// a key would only surface far away.
+const a: Record<string, Route> = { home: { path: "/", method: "GET" } };
+
+// Good: satisfies validates each entry AND keeps literal types.
+const routes = {
+  home: { path: "/", method: "GET" },
+} satisfies Record<string, Route>;
+routes.home.method; // "GET" (narrow), and "GE" would error right here
+```
+
+### Discriminated unions + exhaustive `never`
+
+Model state as a discriminated union, not an optional-field bag:
+`{ data?: T; error?: E; loading?: boolean }` permits `loading && error`; a literal discriminant
+makes illegal states unrepresentable. That discriminant must be a **literal** type (not
+`string`), and you must check it **before** destructuring — destructuring first throws away
+the narrowing.
+
+```ts
+type State =
+  | { status: "loading" }
+  | { status: "ok"; data: string }
+  | { status: "error"; message: string };
+
+// Bad: destructured before the check — `data`/`message` are typed as the union.
+function render({ status, data, message }: State) { /* no narrowing */ }
+
+// Good: switch on the literal discriminant, exhaustive never guard at the end.
+function render(s: State): string {
+  switch (s.status) {
+    case "loading": return "...";
+    case "ok": return s.data;
+    case "error": return s.message;
+    default: { const _exhaustive: never = s; return _exhaustive; }
+  }
+}
+```
+
+Add a `"deleted"` member to `State` and the `default` branch fails to compile — that is the
+point.
+
+### Branded (nominal) types
+
+TS is structural, so a `UserId` and a raw `string` are interchangeable unless you brand them:
+
+```ts
+type UserId = string & { readonly __brand: "UserId" };
+const asUserId = (s: string): UserId => s as UserId; // brand only at the validated boundary
+function load(id: UserId) { /* a bare string is now a compile error */ }
+```
+
+### Utility types cheat row
+
+`Partial<T>` `Required<T>` `Readonly<T>` `Pick<T,K>` `Omit<T,K>` `Record<K,V>`
+`Exclude<U,M>` `Extract<U,M>` `NonNullable<T>` `ReturnType<F>` `Parameters<F>`
+`Awaited<T>` `NoInfer<T>` (TS 5.4+, blocks a type param from inferring at one site).
+
+### Mapped / conditional / template-literal one-liners
+
+```ts
+type Mutable<T> = { -readonly [K in keyof T]: T[K] };          // strip readonly
+type Nullable<T> = { [K in keyof T]: T[K] | null };            // mapped transform
+type Unwrap<T> = T extends Promise<infer U> ? U : T;           // conditional + infer
+type EventName<T extends string> = `on${Capitalize<T>}`;       // template literal
+```
+
+Deep recipes (recursive types, declaration merging, variance/`in`-`out`, assertion functions,
+overloads) live in [references/type-system.md](references/type-system.md).
+
+## tsconfig: strict base
+
+Copy-paste base. Every package `extends` this and overrides only paths/references:
+
+```jsonc
+{
+  "compilerOptions": {
+    "strict": true,                    // the whole strict family, non-negotiable
+    "noUncheckedIndexedAccess": true,  // arr[i] / rec[k] are T | undefined
+    "verbatimModuleSyntax": true,      // explicit import type; safe single-file transpile
+    "isolatedModules": true,           // each file transpilable alone (esbuild/swc/babel)
+    "skipLibCheck": true,              // don't type-check node_modules .d.ts (speed)
+    "resolveJsonModule": true,         // import data.json with types
+    "target": "esnext",
+    "module": "nodenext",              // or "esnext" + "moduleResolution": "bundler"
+    "moduleResolution": "nodenext",
+    "moduleDetection": "force",
+    "noEmit": true                     // a bundler/tsc -b emits; the base just checks
+  }
+}
+```
+
+### moduleResolution: bundler vs nodenext
+
+| Aspect | `bundler` | `nodenext` |
+| --- | --- | --- |
+| Use when | Vite / Next / Remix / esbuild build the code | Code runs directly in Node (no bundler) |
+| Relative import extensions | omit (`./util`) | required (`./util.js`) |
+| `package.json` `exports`/`imports` | resolved | resolved |
+| `module` setting | `esnext`/`preserve` | `nodenext` |
+| Emits runnable JS itself | no (the bundler does) | yes |
+
+Pick `bundler` when a bundler owns resolution; pick `nodenext` for libraries and scripts
+that Node executes directly. Field-by-field reference and the full matrix are in
+[references/build-and-monorepo.md](references/build-and-monorepo.md).
+
+## Monorepo & build
+
+Use **project references** so packages type-check independently and in dependency order. A
+shared `tsconfig.base.json` holds the strict flags; each package extends it, sets
+`composite: true`, `outDir`/`rootDir`, and lists upstream packages under `references`. Build
+the graph with `tsc -b` (or `tsgo -b`).
+
+For declaration emit and publishing a library, set `declaration: true`,
+`declarationMap: true`, and an `exports` map in `package.json`. For fast local checks prefer
+`tsgo` (TS7 preview: `npx @typescript/native-preview`); run scripts with `tsx` instead of
+`ts-node`. Depth, build-order graph, path aliases, and the `tsgo` adoption steps are in
+[references/build-and-monorepo.md](references/build-and-monorepo.md).
+
+## Anti-patterns
+
+| Anti-pattern | Why it bites | Do instead |
+| --- | --- | --- |
+| `any` as an escape hatch | disables all checking and spreads silently downstream | `unknown` + narrow, or a precise type / generic |
+| `as` to silence "not assignable" | asserts a claim TS can't verify — hides the real bug | fix the type, or narrow with a guard/`in`/`typeof` |
+| `enum` for a small fixed set | emits runtime code, awkward with `isolatedModules`, no literal subtyping | union of string literals (`"a" \| "b"`) + `as const` |
+| Destructure before the discriminant check | narrowing is lost; fields become the full union | check `obj.kind` first, then read fields |
+| Skipping `noUncheckedIndexedAccess` | `arr[i]`/`rec[k]` typed as `T` but are `undefined` at runtime | enable it; handle the `\| undefined` |
+| `Function` / bare `object` / `{}` types | accept almost anything, no call-signature safety | a precise signature, or `Record<string, unknown>` |
+| No exhaustive `never` guard on unions | a new union member compiles with a missing branch | `default: const _: never = x` in every switch |
+| One giant `tsconfig` for a monorepo | can't express per-package targets; breaks references | `tsconfig.base.json` + per-package `extends` |
+| `// @ts-ignore` | swallows the error even after the line is fixed, masking new ones | `// @ts-expect-error` (errors if the line later type-checks) |
+| Default-importing in a CJS-emit file under `verbatimModuleSyntax` | blocked / wrong emit | use `export =`/named, or set the right `module` |
+
+## Project grounding
+
+When working inside a real workspace, record this project's tsconfig and strictness choices
+(resolution mode, which strict flags are on, the build tool) in the project wiki via
+[../harness/SKILL.md](../harness/SKILL.md) — so the next session does not re-derive them.

package/skills/shared/typescript/evals/README.md

@@ -0,0 +1,15 @@
+# Evals: typescript
+
+`cases.yaml` checks two things. **Routing**: `should_trigger` lists prompts (including
+non-obvious narrowing symptoms and Spanish/Catalan phrasings) that must select this skill, and
+`should_not_trigger` lists adjacent prompts that must route to a named sibling (`nodejs`,
+`react`, `drizzle-orm`, `python`, `testing-web`) instead. **Capability**: the scenario gives a
+loosely-typed module with no tsconfig and grades the output against the `must_include` rubric
+(any -> precise types, discriminated union with a literal discriminant, exhaustive `never`
+guard, a strict tsconfig, `import type` usage, no error-silencing casts).
+
+To run, feed each prompt to the skill router and confirm the trigger/route decision, then run
+the capability scenario through an agent loaded with this skill and score the result by hand
+against the rubric. There is no automated runner here; the rigor is the rubric plus
+`scripts/verify.sh`, which independently proves the toolchain enforces strictness and
+exhaustiveness on a sample project.

package/skills/shared/typescript/evals/cases.yaml

@@ -0,0 +1,46 @@
+skill: typescript
+
+should_trigger:
+  - prompt: "Make this generic function preserve the literal type of its argument instead of widening to string."
+    why: Core type-system work — const type parameters / inference preservation, framework-agnostic.
+  - prompt: "Why won't TypeScript narrow this union inside the switch? The fields still show as the whole union."
+    why: Non-obvious narrowing symptom — discriminant/destructure-before-check, squarely this skill.
+  - prompt: "Set up a strict tsconfig for a Vite + Node monorepo with project references."
+    why: Compiler config, project references, bundler-vs-nodenext fork — owned here.
+  - prompt: "Type X is not assignable to type Y — help me fix the type, not cast it with as."
+    why: Non-obvious phrasing of a pure type-assignability problem; the explicit no-cast ask is this skill's stance.
+  - prompt: "Configura el tsconfig en modo estricto y elimina los any de este modulo."
+    why: Spanish trigger — strict config plus replacing any with precise types, language/compiler scope.
+  - prompt: "Convert these magic-string statuses into a discriminated union with an exhaustiveness check."
+    why: Discriminated unions + never guard, the canonical modeling pattern here.
+  - prompt: "Por que no estrecha el tipo despues del if? sigue siendo string | undefined."
+    why: Catalan/Spanish non-obvious narrowing question — type-system diagnosis.
+
+should_not_trigger:
+  - prompt: "Add an Express route handler that streams a file with backpressure handling."
+    route_to: nodejs
+    why: Runtime/server behavior (streams, http), not the type system.
+  - prompt: "Type my React component props and wire up the useReducer state."
+    route_to: react
+    why: Framework idioms; the type mechanics are borrowed from here but the wiring belongs to react.
+  - prompt: "Generate Drizzle schema types from my Postgres tables."
+    route_to: drizzle-orm
+    why: ORM schema-to-type generation is owned by the ORM skill.
+  - prompt: "Add type hints to this Python function and fix the mypy errors."
+    route_to: python
+    why: Different language; TS skill does not cover Python typing.
+  - prompt: "Set up Vitest with TS path aliases and coverage reporting."
+    route_to: testing-web
+    why: Test runner/coverage setup; tsconfig path-alias knowledge is borrowed but the tooling is the test skill's.
+
+capability:
+  - scenario: >
+      Given a loosely-typed module (any-heavy, string-keyed state object, no tsconfig),
+      produce strict types plus a tsconfig that compiles under `tsc --noEmit`.
+    must_include:
+      - "Replaces every `any` with `unknown`, a generic, or a precise type."
+      - "Models the state as a discriminated union with a literal discriminant (not string)."
+      - "Adds an exhaustive `never` guard so a new union member is a compile error."
+      - "Ships a strict tsconfig: strict, noUncheckedIndexedAccess, verbatimModuleSyntax, isolatedModules."
+      - "Uses `import type` for type-only imports where applicable."
+      - "Uses no `as` casts to silence errors (each remaining `as` is justified, e.g. `as const` or a validated boundary)."

package/skills/shared/typescript/references/build-and-monorepo.md

@@ -0,0 +1,141 @@
+# Build & monorepo config
+
+Field-by-field tsconfig, project references, resolution matrix, `tsgo`/TS7 adoption, and
+declaration publishing. All targets TypeScript 5.9. Read the section you need.
+
+## tsconfig fields that earn their place
+
+| Field | Set to | Why |
+| --- | --- | --- |
+| `strict` | `true` | Turns on the whole family (`noImplicitAny`, `strictNullChecks`, `strictFunctionTypes`, …). Non-negotiable. |
+| `noUncheckedIndexedAccess` | `true` | `arr[i]` / `rec[k]` become `T \| undefined` — the runtime truth. |
+| `verbatimModuleSyntax` | `true` | Forces explicit `import type`; never emits a type-only import as a runtime `require`; blocks `export default` in CJS-emitted modules. |
+| `isolatedModules` | `true` | Guarantees each file transpiles standalone, so esbuild/swc/babel are safe. |
+| `skipLibCheck` | `true` | Skips type-checking `node_modules` `.d.ts` — large build-time win, negligible risk. |
+| `resolveJsonModule` | `true` | Import `*.json` with inferred types. |
+| `moduleDetection` | `force` | Treats every file as a module (no accidental global scripts). |
+| `noEmit` | `true` (apps) | A bundler emits; `tsc` only type-checks. Libraries set it `false` to emit `.d.ts`. |
+| `composite` | `true` (referenced pkgs) | Required for project references; enables incremental `.tsbuildinfo`. |
+
+## bundler vs nodenext matrix
+
+| | `moduleResolution: "bundler"` | `moduleResolution: "nodenext"` |
+| --- | --- | --- |
+| Pair `module` with | `"esnext"` or `"preserve"` | `"nodenext"` |
+| Who runs the output | a bundler (Vite, esbuild, webpack, Next) | Node directly |
+| Relative import extension | omit (`import "./util"`) | required (`import "./util.js"`) |
+| `package.json` `exports`/`imports` | resolved | resolved |
+| Conditional exports honored | yes | yes (per CJS/ESM condition) |
+| Path aliases | resolved at type-check; bundler must mirror them | resolved at type-check; Node needs `imports`/loader to mirror |
+| Choose when | app/library bundled before it ships | library/script Node executes as-is |
+
+Rule of thumb: if anything bundles the code before it runs, use `bundler`. If Node loads the
+`.js` directly, use `nodenext` and write the `.js` extension on relative imports.
+
+## Project references (the monorepo backbone)
+
+Layout: one `tsconfig.base.json` at the root with the strict flags, then per-package configs.
+
+```jsonc
+// tsconfig.base.json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "target": "esnext",
+    "module": "nodenext",
+    "moduleResolution": "nodenext",
+    "declaration": true,
+    "declarationMap": true,
+    "composite": true
+  }
+}
+```
+
+```jsonc
+// packages/app/tsconfig.json
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": { "rootDir": "src", "outDir": "dist" },
+  "references": [{ "path": "../core" }, { "path": "../ui" }]
+}
+```
+
+- Build the whole graph in dependency order: `tsc -b` (or `tsgo -b`). It caches per package via
+  `.tsbuildinfo` and only rebuilds what changed.
+- Each referenced package needs `composite: true` and must emit declarations.
+- A package may only import from packages it lists under `references`; TS enforces the boundary,
+  which kills accidental cross-package coupling.
+
+## Path aliases — and the reality check
+
+```jsonc
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": { "@core/*": ["packages/core/src/*"] }
+  }
+}
+```
+
+`paths` only rewrites types for the **type-checker**. The runtime/bundler must mirror it:
+Vite (`resolve.alias`), Node (`package.json` `imports` with the `#`-prefix subpath convention),
+or a runtime resolver. Aliases that the bundler does not mirror compile fine and crash at
+runtime — prefer `package.json` `imports` (`"#core/*"`) when Node runs the code, since Node
+resolves those natively.
+
+## tsgo / TypeScript 7 adoption
+
+The native (Go) compiler is in preview as `@typescript/native-preview`, ships the `tsgo`
+binary, and type-checks ~10x faster (Microsoft's VS Code repo, 1.5M LOC: 89s -> 8.74s, 10.2x).
+
+```bash
+npm i -D @typescript/native-preview
+npx tsgo --noEmit          # same flags as tsc
+npx tsgo -b                 # build a project-references graph
+```
+
+Adoption steps:
+1. Add it as a dev dependency; keep `typescript` (`tsc`) installed as the stable fallback.
+2. Run `tsgo --noEmit` in CI for the speed win; if a diagnostic differs, fall back to `tsc` for
+   that check and report it — the preview does not yet cover 100% of `tsc` behavior.
+3. Stable TS 7.0 is targeted for 2026; until then treat `tsgo` as the checker, `tsc` as the
+   reference/emitter.
+
+## Declaration emit & publishing a library
+
+```jsonc
+{
+  "compilerOptions": {
+    "declaration": true,        // emit .d.ts
+    "declarationMap": true,     // .d.ts.map so go-to-def lands on source
+    "outDir": "dist",
+    "rootDir": "src"
+  }
+}
+```
+
+```jsonc
+// package.json — modern dual/ESM publish
+{
+  "type": "module",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }
+  },
+  "files": ["dist"]
+}
+```
+
+- `types`/`typesVersions` must point at the emitted `.d.ts`; put `types` **first** in each
+  `exports` condition so resolvers find it.
+- For libraries, do not set `noEmit`; let `tsc -b` (or your bundler with dts plugin) emit.
+- Validate the published surface with a tool like `@arethetypeswrong/cli` before release.
+
+## Running TS without a build
+
+- `tsx file.ts` — fast esbuild-based runner for scripts and dev (replaces `ts-node`).
+- Node `--experimental-strip-types` (Node 22+) runs `.ts` by erasing types; no type-checking.
+- Both *execute*; neither *checks*. Always keep `tsc --noEmit` (or `tsgo --noEmit`) in CI.

package/skills/shared/typescript/references/type-system.md

@@ -0,0 +1,162 @@
+# Type-system deep dives
+
+Recipes the SKILL body points to. All target TypeScript 5.9. Read the relevant section, not
+the whole file.
+
+## Conditional types + `infer`
+
+`infer` introduces a type variable inside the `extends` clause and binds it to whatever
+matched. It is how you destructure types positionally.
+
+```ts
+type ElementOf<T> = T extends readonly (infer U)[] ? U : never;
+type Unwrap<T> = T extends Promise<infer U> ? Unwrap<U> : T; // recursive unwrap of nesting
+type FirstArg<F> = F extends (a: infer A, ...rest: any[]) => any ? A : never;
+```
+
+Distributive conditional types: when the checked type is a *naked* type parameter and the
+input is a union, the conditional distributes over each member. Wrap both sides in a tuple to
+turn it off.
+
+```ts
+type ToArray<T> = T extends any ? T[] : never;
+type A = ToArray<string | number>;   // string[] | number[]  (distributed)
+type NonDist<T> = [T] extends [any] ? T[] : never;
+type B = NonDist<string | number>;   // (string | number)[]  (not distributed)
+```
+
+## Mapped types: key remapping, modifiers
+
+```ts
+// Remap keys with `as` + template literals; filter by mapping to never.
+type Getters<T> = { [K in keyof T as `get${Capitalize<string & K>}`]: () => T[K] };
+type RemoveId<T> = { [K in keyof T as K extends "id" ? never : K]: T[K] };
+
+// Modifiers: + / - add or strip readonly and optional.
+type Mutable<T>  = { -readonly [K in keyof T]: T[K] };
+type Concrete<T> = { [K in keyof T]-?: T[K] }; // strip optionality
+```
+
+## Template-literal types
+
+```ts
+type Route = `/${string}`;                       // any path-ish string
+type Method = "GET" | "POST" | "PUT" | "DELETE";
+type Endpoint = `${Method} ${Route}`;            // "GET /users", ...
+type CSSVar = `--${string}`;
+// Inference inside templates:
+type ParseId<T> = T extends `user_${infer N}` ? N : never; // ParseId<"user_42"> = "42"
+```
+
+## Recursive types (with care)
+
+Recursion is allowed but the depth is bounded by the instantiation-depth limit; deep tuple
+recursion (e.g. length-N tuples) hits it fast. Prefer tail-recursive accumulator patterns.
+
+```ts
+type DeepReadonly<T> = T extends (infer U)[]
+  ? readonly DeepReadonly<U>[]
+  : T extends object
+    ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
+    : T;
+```
+
+## Variance: `in` / `out` annotations
+
+TS infers variance structurally; you can annotate it on type parameters to make intent
+explicit and speed up checking on large generic types.
+
+- **Covariant** (`out T`): T appears only in output position (return types, readonly props).
+- **Contravariant** (`in T`): T appears only in input position (parameters).
+- **Invariant** (`in out T`): both.
+
+```ts
+interface Consumer<in T> { consume(value: T): void; }     // contravariant
+interface Producer<out T> { produce(): T; }               // covariant
+```
+
+Method parameters are checked **bivariantly** by default for legacy reasons;
+`strictFunctionTypes` makes standalone function-type parameters strictly contravariant, but
+**method** shorthand stays bivariant — prefer the `prop: (x: T) => U` arrow form when you
+want strict checking.
+
+## Branded / nominal patterns
+
+Structural typing means two aliases of `string` are interchangeable. Brand to forbid mixing:
+
+```ts
+declare const brand: unique symbol;
+type Brand<T, B> = T & { readonly [brand]: B };
+
+type UserId = Brand<string, "UserId">;
+type Cents  = Brand<number, "Cents">;
+
+const userId = (s: string): UserId => s as UserId; // brand only after validation
+function charge(amount: Cents) {}
+// charge(100);            // error: number is not Cents
+// charge(userId("u1"));   // error: UserId is not Cents
+```
+
+The brand exists only at the type level (zero runtime cost). Apply the cast in exactly one
+validated constructor, never sprinkle `as UserId` across the codebase.
+
+## Declaration merging
+
+Interfaces with the same name merge; this is how you augment third-party or global types.
+
+```ts
+// Augment a module's types without forking it.
+declare module "express" {
+  interface Request { userId?: string; }
+}
+// Augment globals.
+declare global {
+  interface Window { __APP_VERSION__: string; }
+}
+export {}; // make this file a module so `declare global` is allowed
+```
+
+`type` aliases do **not** merge — only `interface` and `namespace` do.
+
+## Function overloads
+
+Provide multiple call signatures, one implementation signature (which is not callable). Order
+overloads most-specific first.
+
+```ts
+function toArray(x: string): string[];
+function toArray(x: number): number[];
+function toArray(x: string | number): (string | number)[] {
+  return [x];
+}
+```
+
+Prefer a single generic or a union return over overloads when the relationship is
+expressible — overloads don't compose and don't infer across each other.
+
+## Type predicates & assertion functions
+
+```ts
+// Type predicate: narrows the argument when it returns true.
+function isString(x: unknown): x is string { return typeof x === "string"; }
+
+// Assertion function: narrows by throwing otherwise (note the `asserts` keyword).
+function assertDefined<T>(x: T): asserts x is NonNullable<T> {
+  if (x == null) throw new Error("expected a value");
+}
+
+const v: string | undefined = maybe();
+assertDefined(v);
+v.toUpperCase(); // v is string here
+```
+
+TS 5.5+ infers type predicates for simple filter callbacks, so
+`arr.filter((x) => x != null)` now narrows to `T[]` without a hand-written predicate in many
+cases — but an explicit predicate is still clearer for non-trivial checks.
+
+## `const` type parameters & `NoInfer`
+
+```ts
+function widen<const T>(x: T): T { return x; }         // keeps literals, no `as const`
+function build<T>(items: T[], fallback: NoInfer<T>) {} // fallback can't drive inference of T
+```

package/skills/shared/typescript/scripts/verify.sh

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# verify.sh — prove the TS toolchain enforces strictness + exhaustiveness.
+# Read-only on the target: writes ONLY to its own temp dir. Exits 0 with a clear
+# message when no TS/node is available (no false failure on a clean machine).
+set -euo pipefail
+
+# Resolve a type-checker: prefer tsgo (TS7 preview), else npx typescript's tsc.
+# Strict flags are passed on the CLI because naming files on the CLI bypasses tsconfig.
+FLAGS="--noEmit --strict --noUncheckedIndexedAccess --target esnext --module nodenext --moduleResolution nodenext"
+if command -v tsgo >/dev/null 2>&1; then
+  CHECK="tsgo"
+elif command -v npx >/dev/null 2>&1; then
+  CHECK="npx -y -p typescript tsc"
+else
+  echo "SKIP: no tsgo and no npx on PATH — cannot type-check. (exit 0)"
+  exit 0
+fi
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+
+# good.ts: exhaustive never guard MUST pass.
+cat > "$TMP/good.ts" <<'TS'
+type S = { k: "a" } | { k: "b" };
+export function f(s: S): number {
+  switch (s.k) {
+    case "a": return 1;
+    case "b": return 2;
+    default: { const _: never = s; return _; }
+  }
+}
+TS
+
+# bad.ts: missing "b" case -> never guard MUST fail to compile.
+cat > "$TMP/bad.ts" <<'TS'
+type S = { k: "a" } | { k: "b" };
+export function f(s: S): number {
+  switch (s.k) {
+    case "a": return 1;
+    default: { const _: never = s; return _; }
+  }
+}
+TS
+
+run() { ( cd "$TMP" && $CHECK $FLAGS "$1" ) >/dev/null 2>&1; }
+
+fail=0
+if run good.ts; then echo "PASS: good.ts type-checks"; else echo "FAIL: good.ts should compile"; fail=1; fi
+if run bad.ts;  then echo "FAIL: bad.ts should NOT compile (exhaustiveness)"; fail=1; else echo "PASS: bad.ts rejected"; fi
+
+if [ "$fail" -ne 0 ]; then echo "verify.sh: FAILED"; exit 1; fi
+echo "verify.sh: OK — strict + exhaustiveness enforced"