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)

npm library / CLI publishing - Hivemind (secondary case, clearly labeled)

Hard rules

SvelteKit / general case (primary)

npm library / CLI publishing - Hivemind (secondary case)

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

Output paths

Reports land in the host repo's library/ tree, never inside this Stinger. There is no reports/ subfolder in the Stinger.

• Standalone reviews / audits -> library/requirements/reports/typescript/<date>-<topic>.md
• Feature-tied -> library/requirements/<lifecycle>/prd-<###>-<title>/reports/<date>-<type>-report.md
• Issue-tied -> library/issues/<lifecycle>/ird-<###>-<title>/reports/<date>-<type>-report.md
• ADRs -> library/knowledge/private/architecture/ADR-<n>-<topic>.md

Guides

Numbered so order is obvious. Read 00-principles.md on every invocation - its "First move" section routes you to the right set below.

SvelteKit / general (primary case):

• guides/00-principles.md - project-type classification, first-move checklist, severity rubric, cross-Drone boundaries.
• guides/02-project-layout-esm.md - SvelteKit src/routes/src/lib layout and its ESM import rules, alongside the Wasp Nestmind src/ layout for contrast.
• guides/08-async-concurrency.md - async/await correctness, batching, concurrency bounding (applies to both cases).
• guides/09-error-handling.md - narrow, surface, never swallow (applies to both cases).
• guides/12-strict-types-and-zod.md - strict TS, no any at boundaries, zod vs valibot including the 2026 update for this stack.
• guides/16-node22-runtime.md - Node runtime features (applies to both cases); see 29 for the Vercel-specific version policy.
• guides/22-common-failure-modes.md - the Wasp Nestmind-era footgun catalog, cross-referencing the SvelteKit-case "Common findings" sections in 23-29.
• guides/23-tsconfig-for-sveltekit.md - moduleResolution: "bundler", verbatimModuleSyntax, why SvelteKit's generated tsconfig looks the way it does.
• guides/24-typing-sveltekit-load-actions-endpoints.md - load return-type inference, form action typing, +server.ts, App.Locals/App.PageData.
• guides/25-drizzle-type-inference-patterns.md - $inferSelect/$inferInsert, the relational query builder's typing rules; links to neon-drizzle-stinger for schema/migrations.
• guides/26-vitest-playwright-for-sveltekit.md - vitest-browser-svelte/@testing-library/svelte component testing, Playwright e2e, the mocked-vs-unmocked split.
• guides/27-biome-vs-eslint-prettier.md - the current tradeoff and this skill's default for a Svelte-first codebase.
• guides/28-pnpm-and-monorepo-options.md - pnpm as default, Turborepo vs Nx and when each earns its place.
• guides/29-node-version-policy-on-vercel.md - which Node majors Vercel supports, engines.node pinning, the Node 20 deprecation timeline.

npm library / CLI publishing - Hivemind (secondary case, clearly labeled in each guide):

• guides/01-stack-enforcement.md - ESM + Node 22 + tsconfig Node16/ES2022/strict; the Wasp Nestmind dependency set; substitution policy.
• guides/03-deeplake-sql-api.md - the Deep Lake SQL-API client: query(), retry, Semaphore(5), batching.
• guides/04-esbuild-bundling.md - the multi-harness bundle model, sync-versions.mjs, esbuild define version inlining.
• guides/05-mcp-sdk-tools.md - McpServer.registerTool, zod/v3 inputSchema, the search/read/index tool shape.
• guides/06-just-bash-vfs.md - just-bash as the VFS shell engine over Deep Lake.
• guides/07-harness-model.md - the per-harness packaging model.
• guides/10-vitest-discipline.md - vitest run, coverage-v8, tests/ mirroring harnesses/.
• guides/11-vitest-async-fixtures.md - mocking the Deep Lake client, fixtures, temp-dir patterns.
• guides/13-jscpd-and-quality-gate.md - jscpd threshold 7, npm run ci, no ESLint/Prettier by design.
• guides/14-npm-and-publishing.md - npm (not pnpm here), the files allowlist, scoped publish.
• guides/15-deeplake-schema-healing.md - ColumnDef, buildCreateTableSql, healMissingColumns.
• guides/17-secrets-and-sql-guards.md - tokens via env/config only; sqlStr/sqlLike/sqlIdent.
• guides/18-publish-and-pack-check.md - prebuild -> build -> prepack, pack-check.mjs.
• guides/19-tree-sitter-graph.md - tree-sitter + grammars as optional deps for the codebase graph.
• guides/20-cli-and-scripts.md - the hivemind bin, yargs-parser CLI, scripts/*.mjs.
• guides/21-deeplake-sdk-and-hf.md - the deeplake SDK, @huggingface/transformers as an optional dep.

Templates

templates/tsconfig.json (the Wasp Nestmind-case canonical compiler config - not the SvelteKit case, which extends its own generated config per guides/23), templates/vitest.config.ts, templates/schema.ts (a zod boundary module), templates/esbuild-entry.mjs, templates/example.test.ts, templates/husky-pre-commit + templates/lint-staged.config, templates/package-scripts.json. All Hivemind-case artifacts; no SvelteKit-case templates exist yet in this Stinger.

Scripts

scripts/audit-untyped-boundaries.mjs, scripts/audit-unbatched-queries.mjs, scripts/audit-hardcoded-secrets.mjs, scripts/audit-swallowed-catch.mjs, scripts/audit-schema-drift.mjs, scripts/check-esm-node22.mjs. All Hivemind-case tooling (invocation instructions in scripts/README.md); several (audit-untyped-boundaries.mjs, audit-hardcoded-secrets.mjs, audit-swallowed-catch.mjs) are general enough to run against SvelteKit-app TypeScript too - verify their glob targets src/ correctly for a SvelteKit layout before relying on them there.

Examples

examples/01-zod-validated-mcp-tool.md, examples/02-deeplake-query-with-retry-and-semaphore.md, examples/03-vitest-suite-for-a-recall-function.md, examples/05-add-a-column-via-healmissingcolumns.md, examples/06-wire-a-new-harness-install-path.md, examples/08-add-an-esbuild-bundle-entry.md. All Hivemind-case worked examples; no SvelteKit-case examples exist yet in this Stinger.

References (the alternatives we don't pick, or the current open tradeoff)

references/README.md, references/tsc-vs-babel.md, references/vitest-vs-jest.md, references/esbuild-vs-tsup.md, references/zod-vs-valibot.md, references/npm-vs-pnpm.md - all Hivemind-era demoted-alternatives docs, preserved as-is. Active SvelteKit-case recommendations live in guides/23-29, including the still-open 2026 tradeoffs (Biome vs ESLint, zod vs valibot, pnpm vs alternatives, Turborepo vs Nx) - these are decision guides with a stated default, not settled "we don't pick this" verdicts the way the Wasp Nestmind-era references are.

Research

Two research trails, kept separate:

• Source research archive (not shipped with the plugin): the shipped distillation summarizes it; do not require it.
• research/research-plan.md (source-repository research, not shipped with the plugin) + dated notes - the original 2026-06-16 Hivemind-era pass. Every Hivemind-case guide cites this trail. Untouched by this pass.

Output conventions

• All file paths in findings are absolute when referencing project files. Relative when referencing guides in this Stinger.
• Every claim is sourced. Either a guide section, a references/research/raw/ (source-repository research, not shipped with the plugin) file, or a file in the repo.
• Do not invent versions. Read them from package.json.
• Never approve a PR that breaks a Hard Rule above - but only block on Must-fix severity.

When in doubt

• Unfamiliar pattern in the repo? Read the actual source before asserting.
• New pattern from a blog post? Mark it "experimental" and cite the source.
• Hand off the moment a question crosses a boundary in the cross-Drone table.
• Not sure which case applies? Re-run the classification in guides/00-principles.md's "First move" section rather than guessing.

Quality bar

A TypeScript/Node task run through this skill is done when: the project type was classified correctly (SvelteKit app vs npm library/CLI) before any guide was applied, the relevant guide(s) were read in the right set (not mixing a Hivemind-case rule into the SvelteKit case or vice versa), every factual claim used in the output traces to the source research archive (not shipped; the shipped distillation summarizes it) for the SvelteKit case (or research/ [source-repository research, not shipped with the plugin] for the Wasp Nestmind case), and - for anything development-focused - the Ship Gate below completed with user approval before commit or push.

Critical Directive

• You must read all files and context contained within your skill.
• In the event your core knowledge does not provide sufficient guidance you must make every attempt to search the internet, related knowledge base documentation files, and other available resources to supplement your knowledge prior to proceeding with your task.
• Additional related skills can be found here:
  • vercel-stinger - Vercel deploy/build specifics, Node version selection on Vercel, ISR/caching. Consult for anything beyond the engines.node field this skill owns.
  • neon-drizzle-stinger - Drizzle schema design, migrations, connection pooling, RLS. This skill covers the TypeScript patterns AROUND Drizzle, not Drizzle itself.
  • svelte-stinger - Svelte 5 runes and component authoring. This skill covers the TypeScript/Node fundamentals underpinning SvelteKit, not component markup itself.
  • doppler-stinger - secrets/env handling mechanics. Consult for the Doppler side of the env-typing guidance in this skill.
  • security-stinger - Security audit pass, first gate of the Ship Gate pipeline below.
  • quality-stinger - Post-implementation QA pass, second gate of the Ship Gate pipeline below.
  • github-repo-health-stinger - Repo hygiene audit, orchestrator-level final Ship Gate step below.
  • tanstack-stinger - TanStack Query/Table/Form usage in the same SvelteKit stack, when a page's data layer uses TanStack alongside SvelteKit's own load/remote functions.

Ship Gate

Prior to committing any code to the repository you must utilize in order the security-stinger, quality-stinger, and github-repo-health-stinger. After each thorough pass you will prepare an appropriate report in the repository's relevant library directory associated with the agent and skill. All medium or above findings must be resolved followed by another thorough re-evaluation of the updated code prior to proceeding to the next step. The last step of loading the skill github-repo-health-stinger is an orchestrator level task. The sub-agent should make every effort to reinforce to the orchestrating agent to load this skill prior to committing or pushing code to the repository. The user should have an opportunity to review the reports, agent summary, and approve committing and pushing to the repository prior to doing so.

Part of The Wasp Nest, curated by [Mario Aldayuz a.k.a @thenotoriousllama].