@mrciphersmith/keryx 0.2.163 → 0.3.0

package/src/gdskills/bundled/stacks/ts-js-node/skills/nodejs-code-review/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: nodejs-code-review
+description: "Use when reviewing a TypeScript or JavaScript Node.js change (a diff on a server, library, or CLI) for floating promises, unhandled rejections, `any` leaks, event-loop-blocking sync calls, resource cleanup gaps, and dependency risk. Read-only -- judges the diff and reports findings, never edits or authors source. Not for React component review, general architecture review, or security-only audits (use review-security-code for a broader OWASP pass)."
+triggers:
+  - "review this Node.js diff before merging"
+  - "check this TypeScript diff for floating promises"
+  - "review this Node.js route handler change for resource cleanup"
+  - "audit this Node server for blocking calls"
+  - "review this npm package change for dependency risk"
+  - "check this async function for unhandled rejections"
+metadata:
+  origin: authored
+  category: review
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Node.js code review (TypeScript/JavaScript)
+
+Review a TypeScript or JavaScript Node.js change -- server, library, or CLI
+code -- for the failure modes generic review misses: floating promises,
+unhandled rejections, `any` leaking into a typed codebase, event-loop
+blocking, resource leaks, and risky new dependencies. Read-only: this
+skill reports findings and never edits code. See `rules/security.mdc` and
+`rules/patterns.mdc` for the underlying rule set.
+
+## Workflow
+
+### Step 1: Scope the diff
+
+1. Identify the changed/added files under this pack's extensions
+   (`.ts`, `.js`, `.mjs`, `.cjs`) -- skip `.tsx`/`.jsx` component files,
+   those belong to the `react` pack's reviewer.
+2. Read enough surrounding context (the calling module, the function's
+   existing callers) to judge whether a change is actually reachable with
+   attacker- or user-controlled input, not just in isolation.
+
+### Step 2: Check each changed file against the focus list
+
+- **Floating promises**: every `Promise`-returning call is awaited,
+  returned, or explicitly `void`-ed. A bare `doAsyncThing();` statement
+  with no `await`/`return`/`void` and no `.catch()` is a floating promise.
+- **Unhandled rejections**: an async chain with no `.catch()`/`try-catch`
+  anywhere along it, or a `Promise.all([...])` where one rejection is not
+  handled -- especially inside an event handler or a fire-and-forget call.
+- **`any` leaks**: a new or widened `any` on a changed exported signature,
+  or a cast (`as any`, `as unknown as X`) that erases a narrower type the
+  code already had available.
+- **Event-loop blocking**: synchronous `fs`/`crypto`/`zlib` calls
+  (`readFileSync`, `execSync`, `scryptSync`, `gzipSync`) on a path that
+  handles requests or runs in a hot loop, instead of the async/`/promises`
+  variant.
+- **Resource cleanup**: an opened file handle, DB connection, timer,
+  event listener, or child process that is not closed/cleared on every
+  exit path, including the error path (missing `finally`, missing
+  `close()`/`removeListener()`/`clearTimeout()`).
+- **Dependency risk**: a new `package.json` dependency added for
+  something Node's built-ins or an existing dependency already cover, or
+  with no clear justification in the diff/PR description.
+
+### Step 3: Classify and report findings
+
+For each finding, cite the file, line, and a one-line fix direction (not a
+patch -- this skill does not edit code). Group by severity:
+
+- **Blocking**: unhandled rejection reachable from user input, resource
+  leak in a long-lived process, sync blocking call on a hot path.
+- **Should fix**: floating promise with no downstream effect on
+  correctness but silent-failure risk, `any` leak on an internal-only
+  signature, an unjustified new dependency.
+- **Note**: style-level deviations from `rules/coding-style.mdc` already
+  covered by lint but visible in the diff.
+
+### Step 4: Report
+
+```
+Reviewed: src/routes/orders.ts, src/lib/orderQueue.ts (2 files)
+
+Blocking (1):
+- src/lib/orderQueue.ts:42 -- `processQueue()` called with no await/void/catch
+  in the request handler; a rejection here becomes an unhandled rejection
+  that can crash the process. Await it or attach `.catch()`.
+
+Should fix (2):
+- ...
+
+Note (1):
+- ...
+```
+
+## Rules
+
+- NEVER edit source files -- this skill only produces findings.
+- Cross-check every "blocking" finding against `rules/security.mdc` for
+  Node-specific risk (child_process, path traversal, prototype pollution,
+  SSRF, eval/vm, ReDoS, secrets in logs) before finalizing severity.
+- Do not flag a floating promise that is deliberately `void`-ed with a
+  comment explaining why -- that is the correct pattern for genuine
+  fire-and-forget.
+- Do not re-flag something the project's own lint config already catches
+  and enforces in CI (check for an eslint rule covering it) unless the
+  diff bypasses it with a disable comment.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "This is just a review, I'll fix the obvious floating promise myself" | Review skills are read-only; fixing code here bypasses the author's own review of the change |
+| "The `any` cast is only in a test helper, skip it" | Still worth a Note-level finding -- an `any` in shared test infrastructure spreads into every test that imports it |
+| "No resource cleanup finding needed, the process restarts often anyway" | A process restart schedule is an operational mitigation, not a reason to skip a genuine leak; report it |
+| "The new dependency is small, no need to flag it" | Size is not the risk -- an unvetted dependency (however small) adds a supply-chain surface; flag it and let the author justify it |
+
+## Verification
+
+Do not report the review done until all of the following hold:
+
+- Every changed `.ts`/`.js`/`.mjs`/`.cjs` file in the diff was checked
+  against all six focus areas in Step 2.
+- Every finding cites a file and line, not a vague "somewhere in this
+  file".
+- No source file was modified -- `git status` (or the diff tool's own
+  state) shows zero changes from this skill's run.
+- Findings are grouped by severity (Blocking / Should fix / Note).

package/src/gdskills/bundled/stacks/ts-js-node/skills/nodejs-code-review/evals.json

@@ -0,0 +1,74 @@
+{
+  "triggers": {
+    "positive": [
+      "Review this Node.js pull request for floating promises and unhandled rejections",
+      "Check this TypeScript diff for any `any` leaks and blocking synchronous calls",
+      "Audit this Express route handler change for resource cleanup issues",
+      "Review this npm package change and flag any risky new dependencies",
+      "Check this async order-processing function for unhandled promise rejections",
+      "Review this Node service diff for event-loop-blocking file reads"
+    ],
+    "negative": [
+      "Review this React component for unnecessary re-renders",
+      "Implement the fix for the floating promise you found in this file",
+      "Write tests for this Node.js service's new endpoint",
+      "Do a full OWASP security audit of this Node application's auth flow",
+      "Fix this tsc type error that's blocking the build",
+      "Review this Python Flask service for SQL injection risk"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "flag-floating-promise",
+      "prompt": "Review this Node.js code for issues:\n```ts\nfunction handleOrder(req, res) {\n  processOrder(req.body);\n  res.status(202).send();\n}\n```\nwhere processOrder is an async function.",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct review identifies that processOrder(req.body) is called with no await, return, void, or .catch(), and flags this as a floating promise / unhandled-rejection risk in the request handler.",
+          "pass_criteria": [
+            "Explicitly names processOrder(req.body) (or the line calling it) as unawaited -- no await/return/void/.catch -- not just 'there might be an async issue'",
+            "States the concrete consequence: an async failure inside processOrder becomes an unhandled promise rejection that can crash the process or leave the 202 response misleading",
+            "Names a concrete fix direction: await it, or attach .catch(...) (optionally with void), not just 'handle the promise properly'"
+          ],
+          "fail_criteria": [
+            "Fails to identify the missing await/void/catch on processOrder as an issue at all",
+            "Rewrites/edits the handler itself instead of reporting the finding, since this skill is read-only"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Finding -- Blocking: handleOrder calls processOrder(req.body) without await, return, void, or a .catch(). Since processOrder is async, this is a floating promise: if it rejects, nothing in this function observes the rejection, so it becomes an unhandled rejection that can crash the process (or at minimum leaves the client believing the order succeeded via res.status(202) when it may not have). Fix direction: either await processOrder(req.body) before responding if the caller should wait for completion, or, if genuinely fire-and-forget, attach processOrder(req.body).catch(err => { ... }) (or void processOrder(req.body).catch(...)) so the rejection is observed and logged, with a comment explaining why it's intentionally not awaited. I'm not making this change myself since this is a read-only review -- flagging it as a Blocking finding for the author to address before merge.",
+        "known_wrong": "This looks fine to me -- processOrder(req.body) runs, and the handler responds with 202 right away, which is actually the correct pattern for a fire-and-forget background job so the client doesn't have to wait on it. No changes needed here; returning 202 before the async work finishes is standard for this kind of endpoint. If you're worried about errors, processOrder almost certainly has its own internal error handling, so nothing needs to change in this handler.",
+        "vague": "There's an async call here that isn't being handled properly, which could cause problems if it fails. Worth cleaning up before this merges.",
+        "subtle_wrong": "processOrder(req.body) should probably have some error handling around it. I'd wrap the handler body in a try/catch so any errors from processOrder get caught and logged instead of crashing the process, then keep sending the 202 response as before."
+      }
+    },
+    {
+      "id": "read-only-no-edits",
+      "prompt": "Review this Node.js diff for a synchronous fs.readFileSync call inside an Express request handler. Should you fix it yourself in this review?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer says the reviewer should flag/report the synchronous fs.readFileSync call as an event-loop-blocking finding, not fix it, and names the async replacement (fs/promises) as the fix direction for the author -- without claiming to have made the change.",
+          "pass_criteria": [
+            "States plainly that this review is read-only and the reviewer must not edit the code, only report the finding",
+            "Names fs.readFileSync inside the Express handler specifically as the event-loop-blocking issue, not a vague 'this could be slow'",
+            "Names the concrete async replacement -- fs/promises / await readFile(...) -- as the fix direction, without claiming to have applied it"
+          ],
+          "fail_criteria": [
+            "Claims to have fixed/edited the code itself instead of reporting it as a finding for the author",
+            "Fails to flag the synchronous call as blocking at all"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "No -- this skill is read-only, so I should flag it, not fix it myself. Finding -- Blocking: this handler calls fs.readFileSync synchronously inside a request path, which blocks the Node.js event loop for every other in-flight request while the file read completes -- worse under load or with a large file. Fix direction for the author: replace it with the async fs/promises API (import { readFile } from 'fs/promises'; const data = await readFile(path)) inside the handler, which frees the event loop while the I/O is pending. I'm reporting this as a Blocking finding with the file/line and the suggested direction; changing the source here would bypass the author's own review of their diff, so I'm leaving the actual edit to them.",
+        "known_wrong": "No need to just flag it -- I went ahead and fixed it directly in the diff, swapping fs.readFileSync for await fs.promises.readFile in the handler. I fixed it so the PR is ready to merge as-is; the blocking read is gone and everything should behave the same otherwise. Let me know if you want me to also fix any other sync calls I spot while I'm in here.",
+        "vague": "This synchronous file read isn't great in a request handler -- worth pointing out, though of course I wouldn't make the change myself since this is a review.",
+        "subtle_wrong": "No, I'm not editing this myself -- it's read-only. Finding: fs.readFileSync blocks the event loop in this handler. As a workaround, the author could just read this file once at server startup and cache the contents in memory instead of touching it per-request; that avoids the sync read without necessarily needing to touch the fs/promises API right now."
+      }
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/ts-js-node/skills/nodejs-esm-migration/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: nodejs-esm-migration
+description: "Use when migrating a Node.js package or app from CommonJS to ES modules -- package.json type/exports map changes, adding file extensions to relative imports, replacing __dirname/__filename with import.meta.dirname/filename, fixing require() of an ESM-only dependency, dual-package hazards, and the resulting Jest/tsconfig adjustments. Not for a greenfield ESM project (use nodejs-implementation) or a general dependency upgrade (use dependency-update)."
+triggers:
+  - "migrate this package from CommonJS to ESM"
+  - "convert require to import in this Node project"
+  - "fix require() of ES module error"
+  - "add type module to package.json"
+  - "replace __dirname with import.meta"
+  - "this package is dual CJS/ESM, fix the exports map"
+metadata:
+  origin: authored
+  category: migrate
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Node.js CommonJS -> ESM migration
+
+Migrate a Node.js package or application from CommonJS to ES modules.
+Covers the `package.json` fields that change, the syntax changes each
+file needs, and the test/build tooling adjustments the migration usually
+breaks. See `rules/coding-style.mdc` for the ESM import conventions the
+migrated code should end up following.
+
+## Workflow
+
+### Step 1: Assess the current state
+
+1. Read `package.json`: current `"type"` (absent/`"commonjs"` means CJS),
+   `"main"`/`"exports"`, `engines.node`, and every dependency's own module
+   type (many packages ship ESM-only in recent majors -- check their
+   `package.json` `"type"`/`"exports"` before assuming a `require()` of
+   them will keep working).
+2. Grep the codebase for `require(`, `module.exports`, `exports.`,
+   `__dirname`, `__filename` to size the migration.
+3. Check `tsconfig.json` (if TypeScript) for `module`/`moduleResolution`,
+   and any Jest/build config that assumes CJS (`babel-jest` CJS transform,
+   `ts-jest` with `module: commonjs`).
+
+### Step 2: Plan the `package.json` changes
+
+- Add `"type": "module"` once every file in the package is converted (a
+  mixed package needs `.cjs`/`.mjs` extensions instead, see Step 4's
+  dual-package note) -- do not flip `"type"` before the conversion is
+  done, or every remaining `.js` file with `require()` breaks at once.
+- Define an `"exports"` map for anything the package publishes as a
+  library, naming exact subpaths rather than relying on the old
+  `"main"` fallback resolution -- a consumer importing an undeclared
+  subpath now gets `ERR_PACKAGE_PATH_NOT_EXPORTED` instead of silently
+  resolving.
+- Set `moduleResolution: "nodenext"` (or `"bundler"` if the project is
+  bundled rather than run directly by Node) in `tsconfig.json` to match.
+
+### Step 3: Convert each file
+
+1. `require("pkg")` -> `import pkg from "pkg"` (or named imports, matching
+   what the dependency actually exports); `module.exports = x` ->
+   `export default x`; `exports.foo = ...` -> `export function foo() {...}`
+   / `export const foo = ...`.
+2. `__dirname`/`__filename` -> `import.meta.dirname`/`import.meta.filename`
+   (Node 20.11+/22+; for older targets, derive from
+   `fileURLToPath(import.meta.url)`).
+3. Add explicit file extensions to relative imports
+   (`import { x } from "./util.js"`, even when the source is `.ts` --
+   Node's ESM resolver needs the emitted `.js` extension, not the
+   source's `.ts`) when `moduleResolution: nodenext` requires it.
+4. JSON imports need an import attribute:
+   `import data from "./data.json" with { type: "json" }`.
+
+### Step 4: Handle interop hazards
+
+- **`require()` of an ESM-only dependency**: on Node 20.19+/22.12+,
+  `require()` can load a synchronous ES module directly (no flag needed) --
+  try that first when `engines.node` in `package.json` allows it. It fails
+  with `ERR_REQUIRE_ASYNC_MODULE` if the target module (or one of its
+  dependencies) has a top-level `await`; in that case, or on an older
+  `engines.node` floor, convert the importing file to ESM too, or use a
+  dynamic `await import("pkg")` inside an async context if the file
+  genuinely cannot become ESM yet.
+- **Dual-package hazard**: if the package must ship both CJS and ESM
+  builds simultaneously (a published library with CJS consumers), use
+  explicit `.cjs`/`.mjs` extensions per file rather than a single
+  `"type"` field, and mirror both in the `"exports"` map's `"require"`/
+  `"import"` conditions -- a class exported from both builds must resolve
+  to the same instance to avoid `instanceof` failing across the boundary.
+- **Named vs default export mismatch**: some CJS packages only interop
+  cleanly as a default import (`import pkgDefault from "cjs-pkg"`) even
+  when their types suggest named exports -- verify at runtime, not just
+  against the type declarations.
+
+### Step 5: Fix the tooling
+
+- Jest: either migrate to Vitest (native ESM) or configure Jest's ESM
+  support (`"type": "module"` + `NODE_OPTIONS=--experimental-vm-modules`,
+  or `ts-jest` with `useESM: true`) -- check the project's own test
+  runner choice before assuming Jest config changes are the right move.
+- Update any build script that assumed `require.resolve` or CJS-only
+  bundler settings.
+
+### Step 6: Verify and report
+
+```bash
+npx tsc --noEmit
+node --test   # or the project's configured test command
+npx eslint .
+```
+
+```
+Migrated: packages/order-lib (CommonJS -> ESM)
+  - package.json: type: module, exports map for ./client and ./server
+  - 14 files converted: require/module.exports -> import/export
+  - __dirname replaced with import.meta.dirname in 2 files
+  - tsconfig moduleResolution: commonjs -> nodenext
+  - tsc --noEmit: clean, tests: 42 passing
+```
+
+## Rules
+
+- Follow `rules/coding-style.mdc` for the resulting import conventions
+  (`node:` prefix, import ordering, `import type`).
+- Convert a package's files together, not incrementally left half-CJS/
+  half-ESM with `"type": "module"` already flipped -- that breaks every
+  unconverted `.js` file that still uses `require()`.
+- Verify a CJS dependency's actual runtime export shape before writing the
+  import -- its type declarations can disagree with its runtime
+  `module.exports` shape.
+- NEVER silently drop a published package's CJS `"exports"` condition
+  without confirming no consumer still needs it (check the package's own
+  changelog/major-version policy, or ask if unclear).
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll add `type: module` first, then convert the files" | Every remaining `require()`-using `.js` file breaks immediately once `type: module` flips; convert first, flip the field last |
+| "`__dirname` isn't available in ESM, I'll just hardcode the path" | `import.meta.dirname` (or `fileURLToPath(import.meta.url)` on older Node) replaces it correctly; a hardcoded path breaks the moment the package is installed elsewhere |
+| "This dependency's types show named exports, I'll import it that way" | CJS interop can differ from the type declarations at runtime; verify the actual shape before trusting the `.d.ts` |
+| "I'll drop the CJS exports condition, ESM is the future" | Breaks every CJS consumer still depending on `require()`; only drop it with confirmation that nothing needs it |
+
+## Verification
+
+Do not report the migration done until all of the following hold:
+
+- No remaining `require(`/`module.exports`/`exports.` in a file the
+  migration covers (dynamic `await import()` for a documented interop
+  exception is fine and should be called out).
+- `package.json`'s `"type"` and `"exports"` reflect the final module shape.
+- `npx tsc --noEmit` (or the project's build) exits 0.
+- The project's test command exits 0 with every test passing.
+- `git status` shows only the files the migration actually touched.

package/src/gdskills/bundled/stacks/ts-js-node/skills/nodejs-esm-migration/evals.json

@@ -0,0 +1,71 @@
+{
+  "triggers": {
+    "positive": [
+      "Migrate this Node.js package from CommonJS to ES modules",
+      "Convert all the require() calls in this project to ESM imports",
+      "Fix this 'require() of ES Module not supported' error",
+      "Add type: module to package.json and fix everything that breaks",
+      "Replace __dirname with import.meta in this codebase during our ESM migration",
+      "This library needs a dual CJS/ESM exports map, help fix it"
+    ],
+    "negative": [
+      "Implement a brand new Node.js service from scratch using ESM from the start",
+      "Upgrade this npm dependency to its latest major version",
+      "Fix this eslint no-unused-vars warning in a single utility function",
+      "Review this diff for floating promises",
+      "Write tests for this already-ESM Node service",
+      "Migrate this Python 2 codebase to Python 3"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "convert-before-flip-type",
+      "prompt": "I'm migrating this Node.js package to ES modules. Should the package.json \"type\" field become \"module\" before I convert the require() calls in each file, or only once every file is done?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer says to convert the require()/module.exports usages in each file to import/export first, and only add \"type\": \"module\" to package.json once every file in the package is converted -- flipping it first breaks every remaining CommonJS file at once.",
+          "pass_criteria": [
+            "States the concrete ordering: convert each file's require()/module.exports to import/export first, and only then add or flip \"type\": \"module\" in package.json once every file in the package is converted -- not just 'convert first, flip second' without naming the field",
+            "Explains the concrete failure mode: flipping \"type\": \"module\" before every file is converted breaks every remaining file that still calls require(), because Node then parses it as ESM"
+          ],
+          "fail_criteria": [
+            "Says to add/flip \"type\": \"module\" before converting the require() calls, or treats the order as not mattering"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Convert the files first, flip \"type\": \"module\" last. Node decides how to interpret every .js file in the package by that field: once it says \"module\", every remaining file that still has require()/module.exports breaks immediately, because Node now parses it as ESM where require isn't defined. So the safe order is: (1) convert each file's require(...) to import, module.exports = to export default, exports.foo = to export const foo/export function foo, one file (or a small batch) at a time, running tsc --noEmit/tests after each batch; (2) only once every file in the package has been converted -- no require()/module.exports left -- add \"type\": \"module\" to package.json and fix whatever the flip still reveals (missing file extensions on relative imports, __dirname usage, etc). Doing it in this order means the package stays runnable throughout the migration instead of breaking wholesale partway through.",
+        "known_wrong": "I'd just add \"type\": \"module\" to package.json right away -- that declares the intent up front and Node/tools will immediately tell you (via errors) which files still need converting, which is actually a faster way to find everything that needs fixing than grepping for require( manually. Then go through and fix each require()/module.exports as the errors point them out, file by file, until it all runs again. It doesn't really matter which order you do it in as long as you get to the same end state.",
+        "vague": "You should convert everything over to the new module system before flipping the switch in package.json, otherwise you'll run into problems partway through the migration.",
+        "subtle_wrong": "Convert most of the require()/module.exports usage to import/export first, then flip \"type\": \"module\" in package.json. A couple of legacy internal scripts still use require() and module.exports, but since they're not part of the public entry points and rarely touched, it should be fine to flip the type field before getting to those -- if something breaks there later it'll surface quickly enough to fix."
+      }
+    },
+    {
+      "id": "dirname-replacement",
+      "prompt": "In this Node.js file being migrated to ESM, __dirname is undefined. What should replace it?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer replaces __dirname with import.meta.dirname (Node 20.11+/22+), or a fileURLToPath(import.meta.url)-derived equivalent for older Node targets -- not a hardcoded path.",
+          "pass_criteria": [
+            "Names import.meta.dirname (Node 20.11+/22+) or shows the fileURLToPath(import.meta.url)-derived equivalent for an older Node floor as the concrete replacement -- not just 'use the import.meta API' in the abstract",
+            "Ties the choice to the project's actual Node version floor (engines.node) rather than assuming one Node version applies"
+          ],
+          "fail_criteria": [
+            "Suggests hardcoding the directory path as the fix -- mentioning hardcoding only to warn against it, as part of a correct answer using import.meta.dirname or fileURLToPath, does not count as this failure"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "__dirname doesn't exist in ESM, but import.meta.dirname replaces it directly on Node 20.11+/22+ -- no import needed, just swap __dirname for import.meta.dirname everywhere it's used in this file. If the package's engines.node floor is older than that, use the classic derivation instead: import { fileURLToPath } from 'node:url'; import { dirname } from 'node:path'; const __dirname = dirname(fileURLToPath(import.meta.url)); near the top of the file, which gives you an equivalent __dirname binding without relying on the newer import.meta.dirname shortcut. Either way, check engines.node first so the fix actually runs on every Node version this package claims to support -- don't hardcode the path as a shortcut, since that breaks the moment the package is installed or run from a different location.",
+        "known_wrong": "Since __dirname is undefined in ESM and this is annoying to work around properly, easiest fix is to just hardcode the path this file expects, e.g. const dirname = '/app/src/lib', and use that constant wherever __dirname was referenced. That sidesteps the whole import.meta API and works immediately without worrying about which Node version supports import.meta.dirname.",
+        "vague": "You shouldn't hardcode the path -- there's a modern replacement for __dirname available in ESM that you should use instead, depending on what Node version this project supports.",
+        "subtle_wrong": "Just replace every __dirname with import.meta.dirname -- it's the direct ESM equivalent and reads almost the same. No need to check the Node version floor for this, import.meta.dirname has been broadly available for a while now and this codebase is presumably on a reasonably current Node anyway."
+      },
+      "anti_patterns": ["hardcode"]
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/ts-js-node/skills/nodejs-implementation/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: nodejs-implementation
+description: "Use when implementing or extending a feature in a Node.js service, library, or CLI written in TypeScript or JavaScript -- covers tsconfig strictness, ESM/node: protocol imports, async/await with AbortSignal, error handling with cause, and input validation at process boundaries. Not for UI markup/rendering code (use the matching UI framework pack) or writing/fixing tests (use nodejs-testing)."
+triggers:
+  - "implement this Node.js endpoint"
+  - "add a feature to this TypeScript service"
+  - "write a CLI command in Node"
+  - "build this Node.js library function"
+  - "implement async handler with AbortSignal"
+  - "add input validation to this API route"
+  - "implement this Express route handler"
+  - "build this Node.js order processing function"
+metadata:
+  origin: authored
+  category: implement
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Node.js implementation (TypeScript/JavaScript)
+
+Implement or extend a feature in a Node.js service, library, or CLI written
+in TypeScript or JavaScript -- server-side and shared/library code, not
+UI markup/rendering code (that is the matching UI framework pack's job
+once it extends this one). See `rules/coding-style.mdc` and
+`rules/patterns.mdc` for the full rule set this skill draws its checks
+from.
+
+## Workflow
+
+### Step 1: Discover the project's own conventions
+
+1. Read `tsconfig.json` (or `jsconfig.json`): `strict`, `moduleResolution`
+   (`nodenext` vs `bundler`), `target`, path aliases (`paths`/`baseUrl`).
+2. Read `package.json`: `"type"` (`module` vs `commonjs`, or absent =
+   commonjs), `engines.node`, the `exports` map if the project publishes a
+   package, and which HTTP/validation/DB libraries are already dependencies
+   -- reuse them rather than introducing a competing one.
+3. Read 1-2 neighboring modules that already do something similar (a sibling
+   route handler, a sibling exported function) for import order, error
+   handling shape, and whether the project favors classes or plain
+   functions.
+
+### Step 2: Plan the change
+
+- Identify every external input the new code touches (HTTP body/query/
+  params, CLI args, env vars, a file, a queue message) -- each one gets
+  validated at the point it enters the function, per `rules/patterns.mdc`.
+- Identify every async boundary (a DB call, an outbound `fetch`, a
+  filesystem read) and decide how it is cancelled/timed-out: pass an
+  `AbortSignal` through rather than adding a bespoke timeout mechanism.
+- Decide the error contract: does a failure throw, or return a
+  discriminated result? Match what the surrounding code in the same module
+  already does.
+
+### Step 3: Implement
+
+1. Use `node:` prefixed imports for Node built-ins
+   (`import { readFile } from "node:fs/promises"`).
+2. Type every new/changed exported function signature; use `unknown` (not
+   `any`) for data whose shape is not yet validated, and narrow it with a
+   validator or a type guard before use.
+3. Use `async`/`await`; thread an `AbortSignal` into `fetch` and any other
+   cancelable call (`AbortSignal.timeout(ms)` for a fixed budget, or a
+   caller-supplied signal for a request-scoped one).
+4. On failure, throw an `Error` (or a project error class) with a message
+   naming what failed and the relevant identifier; chain the original
+   cause with `new Error("...", { cause })` when wrapping a lower-level
+   error.
+5. Validate external input at the boundary (schema library if the project
+   has one, explicit checks if not) before it reaches business logic.
+
+### Step 4: Verify
+
+```bash
+npx tsc --noEmit
+npx eslint .
+```
+
+Run the project's own build/lint scripts from `package.json` if they
+differ from the above. Do not hand test-writing to this skill -- once the
+feature compiles and lints clean, hand off to `nodejs-testing` for test
+coverage, or write tests yourself following `rules/testing.mdc` if asked to
+do both in one pass.
+
+### Step 5: Report
+
+```
+Implemented: src/routes/orders.ts
+  - POST /orders handler, validates body with zod, calls OrderService.create
+  - tsc --noEmit: clean
+  - eslint: clean
+```
+
+## Rules
+
+- Follow `rules/coding-style.mdc` for typing, module shape, naming, and
+  import order; `rules/patterns.mdc` for validation-at-boundary, DI, and
+  the anti-patterns to avoid.
+- NEVER introduce a new runtime dependency for something the project's
+  existing dependencies (or Node's own built-ins) already cover.
+- NEVER leave a floating promise -- await it, return it, or `void` it
+  explicitly when fire-and-forget is genuinely intended.
+- NEVER do synchronous filesystem/crypto work on a request-handling path;
+  use the `fs/promises`/async variant.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll type this as `any` for now and fix it later" | `any` disables the type checker for everything downstream of it; use `unknown` and narrow instead, even under time pressure |
+| "This fetch doesn't need a timeout, the server is reliable" | An unbounded outbound call with no `AbortSignal` can hang the request indefinitely if the dependency stalls |
+| "I'll validate the input inside the service layer, not the route handler" | Unvalidated data crossing into business logic is the boundary rule's whole point -- validate where it enters the process, not two layers deeper |
+| "console.log the error and move on, it's not critical" | Swallowing an error without rethrowing or returning a typed failure hides the failure from every caller |
+
+## Verification
+
+Do not report the work done until all of the following hold:
+
+- `npx tsc --noEmit` (or the project's own type-check script) exits 0.
+- `npx eslint .` (or the project's own lint script) exits 0 with no new
+  `any`, no new eslint-disable comments added to silence a real finding.
+- Every external input the new code accepts is validated before use.
+- Every `Promise` created by the new code is awaited, returned, or
+  explicitly `void`-ed.
+- `git status` shows only the files the change actually needed.

package/src/gdskills/bundled/stacks/ts-js-node/skills/nodejs-implementation/evals.json

@@ -0,0 +1,72 @@
+{
+  "triggers": {
+    "positive": [
+      "Implement this Express route handler for creating an order, including request body validation",
+      "Add a new async function to this Node.js library that reads a config file and returns parsed settings",
+      "Write a CLI command in our Node.js CLI tool that lists pending jobs from the queue",
+      "Implement async handler with AbortSignal for this outbound fetch call so it doesn't hang",
+      "Add input validation to this Node.js API route before it reaches the service layer",
+      "Build this Node.js order processing function that totals line items and applies discounts"
+    ],
+    "negative": [
+      "Write pytest tests for this Django view",
+      "Review this pull request for floating promises and unhandled rejections",
+      "Migrate this package from CommonJS to ESM",
+      "Fix this tsc type error about incompatible generic instantiation",
+      "Implement a new React component that renders the order list with pagination",
+      "Add fake timers to this Vitest test for the debounce function"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "validate-and-abort-signal",
+      "prompt": "Implement a Node.js function `fetchOrder(id: string)` that calls an internal orders API over fetch and should not hang forever if the API is slow.",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct implementation threads an AbortSignal (e.g. AbortSignal.timeout(ms) or a caller-supplied signal) into the fetch call so a slow orders API cannot hang the function forever, and handles the resulting abort/timeout as a typed failure.",
+          "pass_criteria": [
+            "Shows or names the concrete mechanism: passes { signal } into the fetch call using AbortSignal.timeout(ms) (naming a concrete budget) or an equivalent caller-supplied/composed signal -- not just 'add a timeout' without naming the API",
+            "Shows or names explicit abort/timeout handling (e.g. catching the resulting TimeoutError/AbortError and re-throwing a typed error) rather than leaving an unbounded await with no handling"
+          ],
+          "fail_criteria": [
+            "Leaves the fetch call with no signal/timeout at all, relying on the API being reliable",
+            "Implements a bespoke manual timeout (e.g. racing a setTimeout Promise) instead of using AbortSignal, when nothing in the prompt rules out AbortSignal"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "async function fetchOrder(id: string): Promise<Order> { const signal = AbortSignal.timeout(5000); try { const res = await fetch(`/internal/orders/${id}`, { signal }); if (!res.ok) { throw new Error(`fetchOrder failed: ${res.status}`, { cause: await res.text() }); } return (await res.json()) as Order; } catch (err) { if (err instanceof DOMException && err.name === 'TimeoutError') { throw new Error(`fetchOrder timed out for id=${id}`, { cause: err }); } throw new Error(`fetchOrder failed for id=${id}`, { cause: err }); } } AbortSignal.timeout(5000) gives the request a fixed 5s budget and aborts the underlying request automatically if the internal orders API stalls, instead of the caller waiting indefinitely. The abort surfaces as a TimeoutError which is caught and re-thrown as a typed error with the original cause chained, so callers get a clear, bounded failure rather than a hang.",
+        "known_wrong": "async function fetchOrder(id: string) { const res = await fetch(`/internal/orders/${id}`); return res.json(); } The internal orders API is generally reliable and on the same network, so a timeout isn't really necessary here -- if it does hang occasionally, that's more of an infra problem than something this function needs to handle. Keeping it simple like this is easier to read and there's less to go wrong; if timeouts become an actual issue in practice we can always add one later.",
+        "vague": "Make sure the fetch call can't hang forever -- add some kind of timeout so a slow API doesn't block the function indefinitely.",
+        "subtle_wrong": "async function fetchOrder(id: string): Promise<Order> { const timeout = new Promise<never>((_, reject) => setTimeout(() => reject(new Error('fetchOrder timed out')), 5000)); const res = await Promise.race([fetch(`/internal/orders/${id}`), timeout]); return res.json(); } This bounds the wait to 5 seconds using a simple race against a timer, so the caller never hangs indefinitely even if the orders API stalls."
+      }
+    },
+    {
+      "id": "unknown-over-any",
+      "prompt": "I'm implementing a Node.js handler that parses an untrusted JSON request body before passing it to business logic. What type should the parsed body have before I validate it?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer types the not-yet-validated parsed JSON body as unknown, to be narrowed by a validator or type guard before use, and rejects typing it as any.",
+          "pass_criteria": [
+            "States concretely that the parsed body should be typed unknown (not left implicit/any) before validation -- names the type explicitly",
+            "Names the narrowing mechanism (a schema validator like zod/safeParse, or an explicit type guard) that must run before the value reaches business logic, not just 'validate it first' in the abstract"
+          ],
+          "fail_criteria": [
+            "Recommends typing the parsed body as `any` -- mentioning `any` only to warn against it, as part of a correct answer using unknown, does not count as this failure"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Type it as unknown, not any. JSON.parse's result (or whatever your body parser hands you) has no verified shape yet -- unknown keeps the compiler forcing you to prove the shape before you use any property on it, whereas any would silently disable type checking on everything downstream, including deep into business logic where a malformed request could slip through unnoticed. Concretely: function parseBody(raw: unknown): OrderInput { const result = orderInputSchema.safeParse(raw); if (!result.success) throw new Error('invalid order body', { cause: result.error }); return result.data; } Only after safeParse (or an equivalent type guard) narrows it should the value be passed into business logic as a properly typed OrderInput. It's tempting to just type it as any to unblock the handler quickly, but that removes the compiler's help for every consumer of this value, not just this one call site.",
+        "known_wrong": "Simplest option: just type the parsed body as `any` at the top of the handler -- const body: any = JSON.parse(raw) -- and access whatever fields you need directly. Since request bodies vary and you're going to validate the important fields with an if check anyway before using them in business logic, `any` avoids fighting the compiler over a type that's going to get validated by hand regardless. You can always tighten it to a real interface later once the endpoint's shape stabilizes.",
+        "vague": "Don't just trust the parsed JSON body -- give it a safe type and make sure it's checked before it's used anywhere important.",
+        "subtle_wrong": "Type the incoming body as unknown at the parse boundary -- that's safer than any. Then when you need a specific field for business logic, just narrow it at the point of use with a quick cast, e.g. (body as { total: unknown }).total as number, rather than writing a full schema for the whole payload up front. It keeps the entry point honest as unknown without the overhead of a validator library."
+      },
+      "anti_patterns": ["`any`"]
+    }
+  ]
+}