@mrciphersmith/keryx 0.2.164 → 0.3.1

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

@@ -0,0 +1,134 @@
+---
+name: nodejs-testing
+description: "Use when a Node.js project's test suite (node:test, Vitest, Jest, or bun test) needs writing, extending, or fixing for TypeScript or JavaScript server/library/CLI code -- covers discovering the project's actual runner, mocking at process boundaries, fake timers, and deterministic async assertions. Not for pytest/Python tests, and not for auditing test conventions without changing test files (that is review-testing-practices)."
+triggers:
+  - "write vitest tests for this service"
+  - "add node:test coverage"
+  - "fix failing jest test in this repo"
+  - "mock fetch in this test"
+  - "fake timers for this async test"
+  - "add test coverage for this CLI command"
+metadata:
+  origin: authored
+  category: test
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Node.js testing (node:test / Vitest / Jest / bun test)
+
+Write, extend, or fix a Node.js project's test suite for TypeScript or
+JavaScript server, library, or CLI code. The runner varies per project --
+`node:test`, Vitest, Jest, and `bun test` are all in active use and are
+not interchangeable in import source or config, so Step 1 always discovers
+which one this project actually uses before anything is written. See
+`rules/testing.mdc` for the full rule set.
+
+## Workflow
+
+### Step 1: Discover the project's test runner and conventions
+
+1. Read `package.json`'s `scripts.test` and `devDependencies`
+   (`vitest`, `jest`, or neither -> `node:test`/`bun test`), plus any
+   `vitest.config.*`/`jest.config.*`.
+2. Find the test layout: co-located `*.test.ts`/`*.spec.ts`, or a parallel
+   `test/`/`__tests__/` tree. Match whichever the project already uses.
+3. Read 1-2 neighboring test files for: import source of `describe`/`it`/
+   `test`/`expect`/`assert`, mocking style, and how async tests are
+   structured.
+
+### Step 2: Plan mocks before test cases
+
+- Mock at the process boundary only: network calls, filesystem, a DB
+  client, `Date.now`/timers -- never an internal function one module away,
+  which only checks two mocks agree with each other.
+- For timer-dependent code, use the runner's fake timers (`node:test`'s
+  `mock.timers`, Vitest's `vi.useFakeTimers()`, Jest's
+  `jest.useFakeTimers()`) instead of a real `setTimeout` wait.
+- Decide per dependency whether a hand-written stub or the runner's own
+  mock helper (`mock.fn()`/`mock.method()`, `vi.fn()`, `jest.fn()`) is a
+  better fit for the assertions needed.
+
+### Step 3: Plan test cases
+
+**Functions/handlers:** happy path, edge cases (empty/`null`/`undefined`/
+boundary values), error cases asserting the specific thrown error type or
+message (not just that something threw).
+
+**Async code:** every assertion-relevant `await` present; a test that
+returns before its promises settle reports green regardless of what the
+assertions found.
+
+**CLI commands:** exit code, stdout/stderr content, and behavior on
+missing/invalid arguments.
+
+**Cancelable operations:** pass the test's own `AbortSignal` (`t.signal` in
+`node:test`, or the runner's equivalent) into any `fetch`/cancelable call
+the test makes.
+
+### Step 4: Write
+
+1. Create/extend the test file at the project's own convention path and
+   import source.
+2. One assertion concept per test; a multi-assertion test states in its
+   name the single behavior it verifies.
+3. Each test sets up and tears down its own state -- no dependency on
+   execution order or state a previous test left behind.
+
+### Step 5: Run and fix
+
+```bash
+keryx test run --changed --strict
+```
+
+`src/testing/service.ts` detects the project's own configured runner from
+its lockfile/scripts -- do not hard-code a runner's flags here beyond what
+Step 1 already discovered. With no keryx testing config, run the project's
+own configured test script instead (`npm test`, `npx vitest run`, `npx
+jest`, `node --test`).
+
+Fix failing tests (max 3 iterations) -- fix the test, not the source under
+test.
+
+### Step 6: Report
+
+```
+Generated: src/orders/orders.test.ts
+  - 7 test cases (2 with fake timers), all passing
+```
+
+## Rules
+
+- ALWAYS match the project's existing runner, layout, and mocking
+  conventions found in Step 1-2, not a different project's test style.
+- NEVER modify source code -- only test files (and test config/setup files
+  when the change genuinely requires it).
+- Mock external dependencies (network, filesystem, other services, the
+  clock), not internal modules under the same package.
+- If no test runner is configured at all, suggest adding one; do not add
+  it unasked.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "This async test doesn't need an await, the assertion is inside a `.then()`" | If the test function returns before the promise settles, the runner marks it passed regardless of what the assertion found |
+| "I'll wait a real 2 seconds instead of mocking the timer" | Slow and, under load or CI contention, flaky; use the runner's fake timers |
+| "The test keeps failing; I'll patch the source to make it pass" | This skill writes test files only -- a source change buried in a test-authoring run is an unreviewed fix that also hides the real bug |
+| "I'll mock the internal helper so the test is simpler" | Mock external dependencies, not internal ones -- a test whose internal collaborators are all mocked only checks that the mocks agree with each other |
+| "Still failing after three iterations; I'll loosen the assertion or skip it" | A loosened or skipped assertion covers nothing while reporting coverage. After 3 iterations, stop and report the failing case instead |
+
+## Verification
+
+Do not report the work done until all of the following hold:
+
+- The test file sits at the project's own convention path, matching the
+  runner and mocking style read in Step 1-2.
+- `keryx test run --changed --strict` -- or, with no keryx testing config,
+  the project's own discovered test command -- exits 0 with every
+  generated test passing.
+- No test depends on a real timer wait or on another test's leftover
+  state.
+- `git status` shows only test files (and test config, if genuinely
+  touched) added or modified; no source file under test changed.

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

@@ -0,0 +1,70 @@
+{
+  "triggers": {
+    "positive": [
+      "Write Vitest tests for this order calculation function in our TypeScript service",
+      "Add node:test coverage for the new CLI command in this Node project",
+      "Fix this failing Jest test that's timing out on the debounce logic",
+      "Mock the fetch call in this node:test file so it doesn't hit the real API",
+      "Add fake timers to this test for the setInterval-based polling function",
+      "Extend the test suite for this Node library's exported parseConfig function"
+    ],
+    "negative": [
+      "Write pytest fixtures for this Flask view function",
+      "Implement the new order creation handler in this Express service",
+      "Review this diff for resource cleanup and dependency risk",
+      "Migrate this test suite's imports from CommonJS to ESM",
+      "Fix this tsc type error in the test helper module",
+      "Write Playwright end-to-end tests for the checkout page in this React app"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "discover-runner-first",
+      "prompt": "This Node.js TypeScript repo's test setup isn't described here. Write a test for a function `sumOrderTotals(orders)`. What should you check before writing the test file?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer says to first discover which test runner and conventions this project actually uses (package.json scripts.test/devDependencies, config files, and existing test file layout/imports) before writing the test file.",
+          "pass_criteria": [
+            "Names the concrete places to check: package.json's scripts.test/devDependencies, or a vitest.config.*/jest.config.* file -- not just 'check the project setup' in the abstract",
+            "Says to open an existing test file to read its actual import source (e.g. from vitest, jest, or node:test) and layout convention, and match it, rather than assuming a runner"
+          ],
+          "fail_criteria": [
+            "Picks a specific runner (e.g. Jest, Vitest) and writes the test immediately without first checking what the project actually uses"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Before writing anything, find out what this project actually runs. Check package.json's scripts.test and devDependencies for vitest, jest, or neither (which usually means node:test or bun test), and look for a vitest.config.* / jest.config.* file. Then find the existing test layout -- co-located *.test.ts files next to source, or a parallel test/ / __tests__/ tree -- and open one or two existing test files to see the import source for describe/it/expect (or assert), the mocking style already in use, and how async tests are structured there. Only once that's established should the sumOrderTotals test file be created, at the same path convention and with the same runner's imports, so it matches the rest of the suite instead of introducing a second, inconsistent test style.",
+        "known_wrong": "Vitest is the standard choice for a TypeScript project these days, so I'll just write the test using vi and describe/it from vitest and put it at src/orders/sumOrderTotals.test.ts. That's the most common modern setup so it's a safe default even without checking what's already configured here -- if the project actually uses something else, the imports are easy enough to swap afterward.",
+        "vague": "Before writing the test, it's a good idea to check how this project's tests are usually set up so the new test fits in.",
+        "subtle_wrong": "First I'd check package.json's devDependencies to see whether vitest or jest is installed, and use whichever one shows up -- say it's vitest, then I'd write the test with import { describe, it, expect } from 'vitest' at src/orders/sumOrderTotals.test.ts, which is the standard co-located layout for a TS project. No need to dig through an existing test file first since the devDependency already tells you which runner, and the standard path/import style follows from that."
+      }
+    },
+    {
+      "id": "mock-boundary-not-internal",
+      "prompt": "I'm writing a test for a function that calls an internal helper `formatOrder` and also calls out to a network client `httpClient.get`. What should I mock?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer says to mock the network client (httpClient.get), the process boundary, and explicitly says NOT to mock the internal helper formatOrder, since mocking internal collaborators only checks the mocks agree with each other.",
+          "pass_criteria": [
+            "Names httpClient.get specifically as the thing to mock (the network client / external boundary) -- not just 'mock the network call' in the abstract",
+            "Explicitly says NOT to mock formatOrder, naming it as an internal helper in the same package that should run for real"
+          ],
+          "fail_criteria": [
+            "Recommends mocking the internal helper formatOrder -- mentioning formatOrder only to say it should NOT be mocked, as part of a correct answer, does not count as this failure"
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Mock httpClient.get -- that's the process boundary, a real network call to another service, which is exactly what should be mocked in a unit test so it's deterministic and doesn't hit the network. Don't mock formatOrder: it's an internal helper living in the same package, so let it run for real. If you mock it too, the test degenerates into checking that your mock of formatOrder agrees with your mock of httpClient.get -- it stops verifying that the function under test actually formats and fetches correctly together, and it'll keep passing even if formatOrder's real behavior regresses. So: stub/mock httpClient.get to return canned response data, call the function under test normally (letting it call the real formatOrder), and assert on the final output.",
+        "known_wrong": "Mock both -- mock the internal helper formatOrder so you can control exactly what it returns without depending on its real implementation, and also mock httpClient.get for the network call. Mocking formatOrder makes the test simpler and more isolated since you don't need to worry about its internals changing the assertions; you're testing the function's orchestration logic, not formatOrder itself, so stubbing it out keeps the test focused and easy to reason about.",
+        "vague": "Mock the external call so the test stays isolated and deterministic, and be careful about which other pieces you decide to mock too.",
+        "subtle_wrong": "Mock httpClient.get since that's the real network boundary -- stub it to return canned response data. For formatOrder, I'd normally let it run for real, but since it has some locale-dependent formatting that's noisy to set up deterministically in this environment, I'd mock it too just for this test so the output is stable and the assertions aren't fighting with formatting differences."
+      }
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/vue/agent-refs.json

@@ -0,0 +1,4 @@
+{
+  "agents": [],
+  "note": "honest gate (flow 318, T13; attribution corrected in R1 review PR #719, minor-3): vue-build-fix fails -- falsePositive=1 (trigger-negative-1, \"fix this tsc error in a plain typescript service file\": a CROSS-pack collision with ts-js-node/nodejs-build-fix, not a same-pack near-miss) and its template-union-type-narrowing behavior scenario scores 0.4, below the 0.8 PACK_BEHAVIOR_PASS_FLOOR, even though every other vue skill (implementation, testing, code-review, vue2-to-vue3-migration) clears the gate cleanly. See src/gdskills/bundled/stacks/vue/governance/eval.json. Stays experimental; no generated agent pair."
+}