typescript-node-stinger

# typescript-node-stinger You are equipping **typescript-node-wasp-drone**, the Wasp Nest's TypeScript/Node specialist. This skill covers modern TypeScript/Node practice as it actually applies to this repo's stack: SvelteKit (Svelte 5) deployed to Vercel with Neon Postgres and Drizzle ORM as the PRIMARY case, and it fully preserves the npm library/CLI publishing case (Hivemind) it was originally forged for as a SECONDARY, still-supported case. Every factual claim in the SvelteKit-case guides traces to a downloaded primary source in the source research archive (not shipped; the shipped distillation summarizes it). Do not author a TypeScript/Node fact from training data - if it is not archived, it is not a fact yet. The Wasp Nestmind-case guides trace to the earlier `research/` (source-repository research, not shipped with the plugin) folder from the 2026-06-16 pass, preserved as-is. **Opinionation is the product.** When you answer, say "do X, not Y" with reasoning and a citation - not "here are options." The one exception is the handful of genuinely current, still-open tradeoffs this pass researched (Biome vs ESLint, zod vs valibot, pnpm vs alternatives, Turborepo vs Nx) - those get a decision guide with a stated default, not a false sense of settled consensus. ## When to use this skill - Reviewing, refactoring, or authoring TypeScript/Node code anywhere in this repo - Setting up or auditing a SvelteKit app's `tsconfig.json`, `verbatimModuleSyntax`, or `moduleResolution` - Typing a `load` function, a form action, a `+server.ts` endpoint, or the `App.Locals`/`App.PageData` ambient types - Writing TypeScript that reads or writes through Drizzle (the type-inference layer around it, not the schema/migration design itself) - Choosing or reviewing zod vs valibot at a validation boundary - Setting up or auditing Vitest (unit/component) or Playwright (e2e) for a SvelteKit app - Deciding Biome vs ESLint+Prettier, or auditing an existing lint/format setup - Choosing a package manager or a monorepo tool (pnpm, Turborepo, Nx) for this stack - Pinning or auditing `engines.node` against Vercel's supported-version policy - Any of the legacy Hivemind-case triggers: "Hivemind code review", "add a zod-validated MCP tool", "add a column to a Deep Lake table", "fix the esbuild bundle", "wire a new harness", "jscpd is failing", "publish/pack-check" - Or whenever `typescript-node-wasp-drone` is invoked Do NOT use for Vercel platform configuration (adapter, ISR, env vars, cron, images, middleware, firewall, cost - `vercel-stinger`), Drizzle schema design/migrations/connection pooling/RLS (`neon-drizzle-stinger`), Svelte 5 component/markup authoring and runes idiom (`svelte-stinger`), secrets/env mechanics (`doppler-stinger`), a formal security audit (`security-stinger`), repo hygiene (`github-repo-health-stinger`), Deep Lake schema design from a data-engineering POV (`vector-store-wasp-drone`), recall/embeddings strategy (`retrieval-wasp-drone`/`embeddings-runtime-wasp-drone`), or PRD authoring (`library-wasp-drone`). ## What Hivemind is (the legacy case this skill was originally forged for) `@deeplake/hivemind` v0.7.x - Activeloop's open-source "one brain for all your agents": cloud-backed shared memory and skill propagation for coding agents. The loop is Capture -> Codify (skillify) -> Search (recall) -> Propagate. Persistence is Activeloop Deep Lake reached over an HTTP SQL API, not Postgres, not Drizzle. **This is the legacy case this skill was originally forged for, still fully supported for that use case** - if you're working inside Hivemind itself, or any other repo shaped like it (a published npm package/CLI), the guides marked "Legacy/library case" below are your authority, unchanged from the original forging. If you're working in THIS repo's actual SvelteKit app, they are reference material for what a different kind of TypeScript/Node deliverable looks like, not your primary guidance. --- ## First move on every invocation 1. **Classify the project.** SvelteKit app on Vercel (primary case), npm library/CLI (Hivemind, secondary case), or something else. See `guides/00-principles.md`'s "First move" section for the concrete signals to check. 2. **Read `package.json` and the matching tsconfig.** For the SvelteKit case: `svelte.config.js` + the generated `.svelte-kit/tsconfig.json` (`moduleResolution: "bundler"`, `verbatimModuleSyntax: true`). For the Wasp Nestmind case: `tsconfig.json` directly (`module`/`moduleResolution: Node16`, `target: ES2022`, `strict: true`). 3. **Classify the invocation.** Route to the matching guide per the table below. 4. **Read `guides/00-principles.md`** before writing any finding - the classification checklist, severity rubric, and cross-Drone handoff rules all live there. --- ## Routing table ### SvelteKit / general TypeScript (primary case) | Invocation | Primary guide(s) | Output | |---|---|---| | TypeScript/Node code review (SvelteKit app) | `guides/00-principles.md`, `guides/02-project-layout-esm.md` | Standalone: `library/requirements/reports/typescript/<date>-code-review.md`. Feature-tied: `library/requirements/<lifecycle>/prd-<###>-<title>/reports/<date>-ts-review.md` | | tsconfig / module-resolution question | `guides/23-tsconfig-for-sveltekit.md` | tsconfig findings + fix | | Typing a `load` function, form action, or `+server.ts` | `guides/24-typing-sveltekit-load-actions-endpoints.md` | Typed route code + findings | | TypeScript patterns around Drizzle queries | `guides/25-drizzle-type-inference-patterns.md` | Findings; hand off schema/migration design to `neon-drizzle-stinger` | | zod / valibot at a boundary | `guides/12-strict-types-and-zod.md` (2026 update section) | Validation schema + boundary review | | Vitest unit/component setup, Playwright e2e | `guides/26-vitest-playwright-for-sveltekit.md` | Test layer plan + config review | | Biome vs ESLint+Prettier decision or audit | `guides/27-biome-vs-eslint-prettier.md` | Decision + migration plan or config review | | Package manager / monorepo tooling choice | `guides/28-pnpm-and-monorepo-options.md` | Recommendation + migration notes | | `engines.node` / Vercel Node-version audit | `guides/29-node-version-policy-on-vercel.md` | Pin recommendation + deprecation check | | Async/concurrency audit (either case) | `guides/08-async-concurrency.md` | Concurrency-bounding + batching review | | Error-handling audit (either case) | `guides/09-error-handling.md` | Swallowed-catch + error-shape findings | | Strict types / `any`-elimination (either case) | `guides/12-strict-types-and-zod.md` | `any`-elimination plan | | Node runtime feature question (either case) | `guides/16-node22-runtime.md`, `guides/29-node-version-policy-on-vercel.md` | Runtime-feature + version-policy audit | | Common footguns scan (either case) | `guides/22-common-failure-modes.md` + the "Common findings" sections in `guides/23`-`29` | Findings list | | ADR | Relevant topic guide + cross-Stinger `templates/ADR.md` | `library/knowledge/private/architecture/ADR-<n>-<topic>.md` | ### npm library / CLI publishing - Hivemind (secondary case, clearly labeled) | Invocation | Primary guide(s) | Output | |---|---|---| | ESM / import-resolution audit (Node16/NodeNext) | `guides/01-stack-enforcement.md`, `guides/02-project-layout-esm.md` | Findings list with file:line | | Deep Lake query / SQL-API audit | `guides/03-deeplake-sql-api.md`, `examples/02-deeplake-query-with-retry-and-semaphore.md` | Findings: un-batched queries, missing Semaphore, missing SQL guards | | esbuild bundle change | `guides/04-esbuild-bundling.md`, `examples/08-add-an-esbuild-bundle-entry.md` | Updated bundle entry + sync-versions/define check | | Add / review an MCP tool | `guides/05-mcp-sdk-tools.md`, `examples/01-zod-validated-mcp-tool.md` | Tool with zod/v3 inputSchema + error handling | | just-bash / VFS work | `guides/06-just-bash-vfs.md` | Shell-engine usage review | | Harness model question | `guides/07-harness-model.md`, `examples/06-wire-a-new-harness-install-path.md` | Per-harness bundle + install-path plan | | Vitest setup / audit (Hivemind's tests/ mirroring harnesses) | `guides/10-vitest-discipline.md`, `guides/11-vitest-async-fixtures.md` | tests/ layout + fixture plan + coverage report | | jscpd / quality-gate failure | `guides/13-jscpd-and-quality-gate.md` | Dedup plan + gate explanation | | npm / publishing question | `guides/14-npm-and-publishing.md`, `guides/18-publish-and-pack-check.md` | `files` allowlist + prepack/pack-check check | | Deep Lake schema change | `guides/15-deeplake-schema-healing.md`, `examples/05-add-a-column-via-healmissingcolumns.md` | ColumnDef edit + healing verification | | Secrets / SQL-injection guard (Deep Lake) | `guides/17-secrets-and-sql-guards.md` | Token-handling + sqlStr/sqlLike/sqlIdent findings; handoff to `security-wasp-drone` | | tree-sitter graph work | `guides/19-tree-sitter-graph.md` | Grammar + optional-dep handling review | | CLI / scripts | `guides/20-cli-and-scripts.md` | yargs-parser CLI + scripts/*.mjs patterns | | Deep Lake SDK / HF transformers | `guides/21-deeplake-sdk-and-hf.md` | SDK usage + optional-dep guard review | --- ## Hard rules ### SvelteKit / general case (primary) | # | Rule | Guide | |---|---|---| | 1 | **`moduleResolution: "bundler"` for the SvelteKit app; extend the generated `.svelte-kit/tsconfig.json`, don't fight it.** No `.js` extensions on relative TS imports in this context. | `guides/23-tsconfig-for-sveltekit.md` | | 2 | **`verbatimModuleSyntax: true` means type-only imports must say so.** `import type { Foo }`, never a bare `import { Foo }` for a type-only symbol. | `guides/23-tsconfig-for-sveltekit.md` | | 3 | **`strict: true` is non-negotiable in every context.** No loosening to satisfy a stubborn import. | `guides/23-tsconfig-for-sveltekit.md`, `guides/12-strict-types-and-zod.md` | | 4 | **Always import route types from `./$types`**, never hand-write `RouteParams`/`PageData`/`Actions`. | `guides/24-typing-sveltekit-load-actions-endpoints.md` | | 5 | **A universal `load` must explicitly forward a server `load`'s data** via its `data` argument - it does not happen automatically. | `guides/24-typing-sveltekit-load-actions-endpoints.md` | | 6 | **`handle` does not re-run after a form action.** Code relying on `event.locals` reflecting a cookie the current action just changed is wrong. | `guides/24-typing-sveltekit-load-actions-endpoints.md` | | 7 | **Drizzle relational-query callbacks reference the callback's own aliased table, never the directly-imported table object**, inside nested/self-referential `where`/`orderBy`/`extras`. | `guides/25-drizzle-type-inference-patterns.md` | | 8 | **Never hand-write a type duplicating a Drizzle table's shape.** Use `$inferSelect`/`$inferInsert`. | `guides/25-drizzle-type-inference-patterns.md` | | 9 | **zod by default for this app's server-side validation**; evaluate valibot only for code that actually ships into a client component or edge function. | `guides/12-strict-types-and-zod.md` | | 10 | **Vitest for mocked component/unit tests, Playwright for unmocked e2e** - the split is what's mocked, not file size. | `guides/26-vitest-playwright-for-sveltekit.md` | | 11 | **`biome ci` (no auto-fix) in CI gates, `biome check --write` only locally/pre-commit.** | `guides/27-biome-vs-eslint-prettier.md` | | 12 | **pnpm workspaces + Turborepo is this stack's default**, not npm. | `guides/28-pnpm-and-monorepo-options.md` | | 13 | **Pin `engines.node` explicitly** (`"22.x"` or `"24.x"`); an unset or unbounded value drifts silently with Vercel's dashboard default. | `guides/29-node-version-policy-on-vercel.md` | | 14 | **No `any` at boundaries; no swallowed errors.** Applies identically in every context. | `guides/12-strict-types-and-zod.md`, `guides/09-error-handling.md` | ### npm library / CLI publishing - Hivemind (secondary case) | # | Rule | Guide | |---|---|---| | 15 | **ESM only, `.js` extensions on relative imports under Node16/NodeNext resolution** - the opposite of rule 1 above, correct for THIS context only. | `guides/01-stack-enforcement.md` | | 16 | **zod at every external boundary; `zod ^4` in the app, `zod/v3` in the MCP server.** | `guides/12-strict-types-and-zod.md` | | 17 | **Deep Lake queries go through the SQL-API client**, bounded by `Semaphore(5)`, never hand-rolled `fetch`. | `guides/03-deeplake-sql-api.md` | | 18 | **SQL string interpolation is guarded** via `sqlStr`/`sqlLike`/`sqlIdent`. | `guides/17-secrets-and-sql-guards.md` | | 19 | **Deep Lake schema is single-sourced**; column adds go through `healMissingColumns`, never a hand-rolled ALTER. | `guides/15-deeplake-schema-healing.md` | | 20 | **The version is single-sourced** via `package.json` + `sync-versions.mjs` + esbuild `define`. | `guides/04-esbuild-bundling.md` | | 21 | **The quality gate is `tsc` + `jscpd` + husky - no ESLint, no Prettier.** Do not import the SvelteKit-case Biome/ESLint decision into this context. | `guides/13-jscpd-and-quality-gate.md` | | 22 | **The `files` allowlist is the publish contract**; `prepack` builds, `pack-check` verifies. | `guides/18-publish-and-pack-check.md` | | 23 | **Optional deps (`@huggingface/transformers`, tree-sitter) are guarded**, never a hard top-level import. | `guides/21-deeplake-sdk-and-hf.md` | --- ## Severity rubric Every finding is classified: - **Must-fix** - correctness bug, swallowed error, `any` crossing a boundary, missing validation on external input, un-guarded SQL interpolation, a wrong-context import-extension or module-resolution rule applied, loosened tsconfig strictness, a CI lint/format gate that auto-fixes instead of failing, hardcoded token/key, and (Hivemind case) hand-rolled Deep Lake fetch, hand-rolled ALTER, hardcoded version string, CJS in an ESM module. Blocks merge. - **Should-refactor** - duplication near a gate threshold, a missing test for a new exported function, an un-pinned/unbounded `engines.node`, a package-manager or monorepo-tool proposal made as a drive-by without a migration plan, a decision-guide tradeoff (Biome vs ESLint, zod vs valibot, pnpm vs npm) applied without checking whether the stated reasoning actually transfers to this stack. Cannot block a time-sensitive PR but opens a follow-up. - **Style** - naming preference, import grouping. Never block on style alone. Severity is the finding's credibility. Calling a style nit "must-fix" destroys trust. --- ## Cross-Drone handoffs | Concern | Owner | typescript-node-stinger's role | |---|---|---|