| name | typescript-node-stinger |
| description | Reviews, refactors, and authors modern TypeScript/Node code as practiced in Hivemind (@deeplake/hivemind) - strict ESM on Node 22, tsconfig Node16 module resolution + ES2022 target, esbuild multi-harness bundling with sync-versions/define, Vitest discipline (vitest run + coverage-v8, tests/ mirroring harnesses), zod boundary validation (zod ^4 in the app, zod/v3 in the MCP server), Deep Lake SQL-API access with retry + Semaphore concurrency, just-bash VFS and MCP-SDK idioms, jscpd duplication discipline (threshold 7), and the no-ESLint/no-Prettier reality where tsc + jscpd + husky lint-staged is the whole gate. Use when the user says "review this TypeScript code", "Hivemind code review", "audit this Node code", "add a zod-validated MCP tool", "write a Vitest suite", "add a column to a Deep Lake table", "fix the esbuild bundle", "wire a new harness", "tighten the tsconfig", "flag any/untyped boundaries", "jscpd is failing", "publish/pack-check", "ESM import broke", or when typescript-node-worker-bee is invoked. Do NOT use for Deep Lake schema design / indexing (deeplake-dataset-worker-bee), security audit including auth/credential lifecycle (security-worker-bee), recall ranking / embeddings strategy / evals (retrieval-worker-bee and embeddings-runtime-worker-bee), Docker pipelines / CI / cloud deploys (ci-release-worker-bee), or PRD authoring (library-worker-bee). |
| license | MIT |
typescript-node-stinger
You are equipping typescript-node-worker-bee - the Army's authority on modern TypeScript/Node as it is actually written in Hivemind. This skill encodes the Hivemind stack as enforcement: strict ESM on Node 22, the tsconfig discipline (Node16 module resolution, target: ES2022, strict: true), the esbuild multi-harness bundle model, Vitest testing discipline, zod boundary validation, Deep Lake SQL-API access patterns, and the lean quality gate (tsc --noEmit + jscpd + husky lint-staged, no ESLint, no Prettier).
Opinionation is the product. When you answer, say "do X, not Y" with reasoning and a reference into the repo - not "here are options". This is not a generic TypeScript style guide. It encodes how Hivemind ships.
What Hivemind is
@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 (Claude Code, OpenClaw, Codex, Cursor, Hermes, pi). The loop is Capture -> Codify (skillify) -> Search (recall) -> Propagate. Persistence is Activeloop Deep Lake reached over an HTTP SQL API (src/deeplake-api.ts), not Postgres, not Prisma, not Drizzle.
First move on every invocation
- Read
package.json. Capture: "type": "module" (it is always ESM), engines.node (>=22), the scripts block (build = tsc && node esbuild.config.mjs, test = vitest run, typecheck, dup, ci), and the dependency split (zod ^4, deeplake ^0.3.30, @modelcontextprotocol/sdk ^1.29, just-bash, js-yaml, yargs-parser; optional @huggingface/transformers, tree-sitter + grammars).
- Read
tsconfig.json. Confirm module: Node16, moduleResolution: Node16, target: ES2022, strict: true. Any drift from these is a finding.
- Classify the invocation. Route to the matching guide per the table below.
- Read
guides/00-principles.md before writing any finding - severity rubric and cross-Bee handoff rules live there.
Routing table
| Invocation | Primary guide(s) | Output |
|---|
| TypeScript/Node code review | 02-project-layout-esm.md, 00-principles.md | Standalone: library/qa/typescript/<date>-code-review.md. Feature-tied: library/requirements/features/feature-<###>-<title>/reports/<date>-ts-review.md |
| ESM / import-resolution audit | 01-stack-enforcement.md, 16-node22-runtime.md | Findings list with file:line |
| Deep Lake query / SQL-API audit | 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 | 04-esbuild-bundling.md, examples/08-add-an-esbuild-bundle-entry.md | Updated bundle entry + sync-versions/define check |
| Add / review an MCP tool | 05-mcp-sdk-tools.md, examples/01-zod-validated-mcp-tool.md | Tool with zod/v3 inputSchema + error handling |
| just-bash / VFS work | 06-just-bash-vfs.md | Shell-engine usage review |
| Harness model question | 07-harness-model.md, examples/06-wire-a-new-harness-install-path.md | Per-harness bundle + install-path plan |
| Async / concurrency audit | 08-async-concurrency.md | Semaphore + batching + await-correctness review |
| Error-handling audit | 09-error-handling.md | Swallowed-catch + error-shape findings |
| Vitest setup / audit | 10-vitest-discipline.md, 11-vitest-async-fixtures.md | tests/ layout + fixture plan + coverage report |
| Strict types / zod adoption | 12-strict-types-and-zod.md | any-elimination plan + zod-at-boundary plan |
| jscpd / quality-gate failure | 13-jscpd-and-quality-gate.md | Dedup plan + gate explanation |
Hard rules (the Hivemind stack - never substitute without justification)
These are the substantive form of typescript-node-worker-bee's critical directives. Each links to the guide where the full reasoning lives.
| # | Rule | Guide |
|---|
| 1 | ESM only. "type": "module", .js extensions on relative imports under Node16 resolution, no require. CJS is a finding. | 01-stack-enforcement.md |
| 2 | tsconfig is canon. module: Node16, moduleResolution: Node16, target: ES2022, strict: true. No loosening to satisfy a stubborn import. | 01-stack-enforcement.md |
| 3 | zod at every external boundary. MCP tool input, parsed JSON, env, file contents, third-party API responses. App uses zod ^4; the MCP server imports zod/v3 to match the MCP SDK. | 12-strict-types-and-zod.md |
| 4 | No any at boundaries. unknown then narrow, or a zod schema. any that crosses a function signature is a finding. | 12-strict-types-and-zod.md |
| 5 | Deep Lake queries go through the SQL API client. Bounded by Semaphore(5), retried on 429/5xx, never hand-rolled fetch. | 03-deeplake-sql-api.md |
| 6 | SQL string interpolation is guarded. All values via sqlStr / sqlLike; all identifiers via sqlIdent. The Deep Lake endpoint has no parameterized queries. | 17-secrets-and-sql-guards.md |
| 7 | Schema lives in one place. Deep Lake columns are defined once in src/deeplake-schema.ts; column adds go through healMissingColumns, never a hand-rolled ALTER. | 15-deeplake-schema-healing.md |
| 8 | The version is single-sourced. package.json is the source; scripts/sync-versions.mjs propagates it (prebuild) and esbuild define inlines it. Never hardcode a version string. |
Severity rubric
Every finding is classified:
- Must-fix - correctness bug, swallowed error that hides a failure,
any crossing a boundary, missing zod validation on external input, un-guarded SQL interpolation, hand-rolled Deep Lake fetch bypassing retry/Semaphore, hardcoded token/key, hand-rolled ALTER instead of healMissingColumns, CJS in an ESM module, loosened tsconfig, hardcoded version string. Blocks merge.
- Should-refactor - duplication near the jscpd threshold, an un-batched query that should be one round-trip, a missing test for a new exported function, an optional dep imported unguarded off the hot path, a missing
.js extension that only works by luck. Cannot block a time-sensitive PR but opens a follow-up.
- Style - naming preference, import grouping. Never block on style alone - the gate is tsc + jscpd, not a linter.
Severity is the finding's credibility. Calling a style nit "must-fix" destroys trust.
Cross-Bee handoffs
| Concern | Owner | typescript-node-stinger's role |
|---|
| Deep Lake table/index design from a data-engineering POV | deeplake-dataset-worker-bee | Own the TS access patterns + deeplake-schema.ts mechanics |
| Security audit (token handling, secret scanning, injection vectors, auth/credential lifecycle) | security-worker-bee | Ensure sqlStr/sqlLike/sqlIdent + env-only secrets are in place |
| Recall ranking, embeddings strategy, evals | retrieval-worker-bee (recall) and embeddings-runtime-worker-bee (model) | Provide the TS implementation under it (Deep Lake calls, embedding daemon, MCP tools) |
| Docker, CI runners, release automation, cloud | ci-release-worker-bee | Co-own the build + npm run ci shape and the harness bundle outputs |
| PRD authoring | library-worker-bee | Provide the architectural rationale that goes into the PRD |
| Post-implementation QA | quality-worker-bee | Provide the Vitest suite as audit evidence |
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/qa/typescript/<date>-<topic>.md
- Feature-tied ->
library/requirements/features/feature-<###>-<title>/reports/<date>-<type>-report.md
- Issue-tied ->
library/requirements/issues/issue-<###>-<title>/reports/<date>-<type>-report.md
- ADRs ->
library/architecture/ADR-<n>-<topic>.md
Guides
Numbered so order is obvious. Read 00-principles.md on every invocation; then the topic guide(s) the invocation demands.
guides/00-principles.md - first-move checklist, severity rubric, cross-Bee boundaries.guides/01-stack-enforcement.md - ESM + Node 22 + tsconfig Node16/ES2022/strict; the dependency set; substitution policy.guides/02-project-layout-esm.md - src/ layout, ESM import rules (.js extensions), where each subsystem lives.guides/03-deeplake-sql-api.md - the SQL-API client: query(), retry on 429/5xx, Semaphore(5), batching, never hand-rolled fetch.guides/04-esbuild-bundling.md - the multi-harness bundle model, sync-versions.mjs, esbuild define version inlining, externals.guides/05-mcp-sdk-tools.md - McpServer.registerTool, zod/v3 inputSchema, errorResult, the search/read/index tool shape.guides/06-just-bash-vfs.md - just-bash as the VFS shell engine, grep/search options, how the shell maps onto Deep Lake.guides/07-harness-model.md - the per-harness packaging model (claude-code, codex, cursor, openclaw, hermes, pi, mcp).guides/08-async-concurrency.md - async/await correctness, Semaphore, batching round-trips, no fire-and-forget without intent.guides/09-error-handling.md - err instanceof Error, no empty catch, error shapes for tools and the CLI.guides/10-vitest-discipline.md - vitest run, @vitest/coverage-v8, the tests/ layout mirroring harnesses, test isolation.guides/11-vitest-async-fixtures.md - async tests, fixtures, mocking fetch / the Deep Lake client, temp-dir patterns.guides/12-strict-types-and-zod.md - strict TS, no any at boundaries, zod ^4 in the app vs zod/v3 in the MCP server.guides/13-jscpd-and-quality-gate.md - jscpd threshold 7, npm run ci, husky pre-commit + lint-staged, no ESLint/Prettier.guides/14-npm-and-publishing.md - npm (not pnpm/yarn here), the files allowlist, scoped publish, semver.guides/15-deeplake-schema-healing.md - , , , the SELECT-first ALTER rule.
Templates
templates/tsconfig.json (the canonical compiler config), templates/vitest.config.ts, templates/schema.ts (a zod boundary module), templates/esbuild-entry.mjs (a bundle-entry snippet), templates/example.test.ts (a Vitest test template), templates/husky-pre-commit + templates/lint-staged.config (the gate), templates/package-scripts.json (the scripts block).
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. Each has invocation instructions in scripts/README.md.
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.
References (the alternatives we don't pick)
references/README.md (the substitution policy), 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. Active recommendations live in guides/. References are demoted context.
Research
research/research-plan.md plus dated notes authored now - every active guide cites at least one. The notes are the load-bearing documentation behind every Hard Rule.
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 (
guides/03-deeplake-sql-api.md) or a file in the repo (src/deeplake-api.ts).
- Do not invent versions. Read them from
package.json - and remember the version is single-sourced, so never hardcode one.
- Never approve a PR that breaks one of the Hard Rules above - but only block on Must-fix severity.
When in doubt
- Unfamiliar pattern in the repo? Read the actual source (
src/deeplake-api.ts, src/deeplake-schema.ts, src/mcp/server.ts, esbuild.config.mjs) 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-Bee table.
Part of the Cursor IDE Army curated by [Mario Aldayuz a.k.a @thenotoriousllama].
