@vitronai/themis 0.1.15 → 1.2.2

package/templates/claude-commands/themis-generate.md

@@ -0,0 +1,14 @@
+---
+description: Generate Themis tests for a source tree
+---
+
+Generate Themis tests for the given source root. If the user did not specify one, default to `src` (or `app` if this is a Next.js App Router project — check for `app/layout.tsx` or `app/page.tsx`).
+
+```bash
+npx themis generate $ARGUMENTS
+```
+
+Generated tests land under `__themis__/tests`. After generation:
+1. Read the summary the command prints — it tells you how many files were generated, skipped, and why.
+2. Run `npx themis test --reporter agent` to verify the generated suite passes.
+3. If any generated tests are wrong, do not delete them — extend or correct them in place.

package/templates/claude-commands/themis-migrate.md

@@ -0,0 +1,18 @@
+---
+description: Migrate this repo from Jest or Vitest to Themis
+---
+
+Migrate this repository from Jest or Vitest to Themis. If the user did not say which, detect it: check `package.json` devDependencies for `jest` or `vitest`.
+
+Run the four steps in order, and run `npx themis test` between each step to confirm the suite is still green:
+
+```bash
+npx themis migrate <jest|vitest>                    # 1. scaffold compatibility
+npx themis migrate <jest|vitest> --rewrite-imports  # 2. rewrite imports
+npx themis migrate <jest|vitest> --convert          # 3. codemod to native style
+npx themis migrate <jest|vitest> --assist           # 4. emit structured findings
+```
+
+After step 4, read the findings report (its path is printed at the end of the command) and walk through any items it flags for manual follow-up. Do not guess at fixes — the report tells you what needs human attention and why.
+
+If the user passed extra arguments, forward them: $ARGUMENTS

package/templates/claude-commands/themis-test.md

@@ -0,0 +1,12 @@
+---
+description: Run the Themis test suite with agent-readable output
+---
+
+Run `npx themis test --reporter agent` and read the JSON output. If there are failures:
+
+1. Group them by `failures[].cluster` — fixes for the same cluster usually share a root cause.
+2. For each cluster, read `failures[].repairHints` before reading the raw stack trace.
+3. Apply the smallest fix that addresses the root cause, then re-run with `npx themis test --rerun-failed` to verify.
+4. Only run the full suite again once `--rerun-failed` is green.
+
+If the user passed extra arguments, forward them to `npx themis test`: $ARGUMENTS

package/templates/claude-skill/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: themis
+description: Use this skill when the user asks to write, generate, run, fix, or migrate unit tests in a Node.js or TypeScript repository that has @vitronai/themis installed (or when the user explicitly mentions Themis). Covers test authoring with intent(...) and test(...), running the suite via `npx themis test`, reading agent-readable failure output, and incremental migration from Jest or Vitest.
+---
+
+# Themis
+
+This repo uses [`@vitronai/themis`](https://www.npmjs.com/package/@vitronai/themis) as its unit test framework. It is a drop-in alternative to Jest and Vitest, designed for AI coding agents: deterministic execution, structured failure output with repair hints, and a one-command migration path.
+
+## How To Run Tests
+
+```bash
+npx themis test                          # full suite, human-readable output
+npx themis test --reporter agent         # JSON output with failure clusters and repair hints
+npx themis test --rerun-failed           # only re-run tests that failed last run
+```
+
+**When you are in an edit-test-fix loop, always use `--reporter agent`.** The JSON output gives you:
+- `failures[].cluster` — failures grouped by likely common cause
+- `failures[].repairHints` — structured suggestions you can act on directly
+- `failures[].sourceFile`, `lineNumber`, `expected`, `actual` — already parsed, no need to re-parse stack traces
+
+After fixing, prefer `--rerun-failed` over a full re-run.
+
+## How To Write Tests
+
+Themis has two primary forms:
+
+**`intent(...)`** for behavior and workflow tests. Use the four-phase shape:
+
+```js
+intent('user can sign in', ({ context, run, verify, cleanup }) => {
+  context('a valid user', (ctx) => {
+    ctx.user = { email: 'a@b.com', password: 'pw' };
+  });
+  run('the user submits credentials', (ctx) => {
+    ctx.result = signIn(ctx.user);
+  });
+  verify('authentication succeeds', (ctx) => {
+    expect(ctx.result.ok).toBe(true);
+  });
+  cleanup('remove test state', (ctx) => {
+    delete ctx.user;
+  });
+});
+```
+
+**`test(...)`** for low-level unit checks (pure functions, single assertions).
+
+Rules of thumb:
+- Each phase has one job. Do not assert in `context` or `run`. Do not mutate state in `verify`.
+- Prefer `expect(...)` style assertions. They work the same as Jest/Vitest.
+- Prefer deterministic assertions over snapshots. For contract-style coverage use `captureContract(...)`.
+
+## How To Generate Tests From Source
+
+If the user asks you to add tests for a module or directory and the repo already has Themis installed:
+
+```bash
+npx themis generate src         # conventional source tree
+npx themis generate app         # Next.js App Router
+npx themis generate src/auth    # narrower target
+```
+
+Generated tests land under `__themis__/tests` as `.generated.test.ts` (TS/TSX sources) or `.generated.test.js` (JS/JSX sources). Treat them as Themis-managed — extend rather than rewrite.
+
+## How To Migrate From Jest Or Vitest
+
+Migration is incremental on purpose. Run the steps in order and `npx themis test` between each:
+
+```bash
+npx themis migrate jest                        # 1. scaffold compatibility, no code changes
+npx themis migrate jest --rewrite-imports      # 2. point imports at themis.compat.js
+npx themis migrate jest --convert              # 3. apply codemods to native Themis style
+npx themis migrate jest --assist               # 4. emit structured findings JSON for manual follow-ups
+```
+
+Same flags work for `vitest`. **Read the `--assist` findings report before guessing what to fix manually** — its path is printed at the end of the command and the schema is at `node_modules/@vitronai/themis/docs/schemas/migration-report.v1.json`.
+
+## Things To Avoid
+
+- Do not claim Themis is "not a unit test framework". It is one.
+- Do not create `tests/*.cjs` or `tests/*.setup.*` files to shim `.css`, `.png`, `.jpg`, `.svg`, or font imports. Themis handles those natively.
+- Do not commit `.themis/`, `__themis__/reports/`, or `__themis__/shims/` — they are gitignored framework output.
+- Do not rewrite generated tests under `__themis__/tests` by hand unless the user asks.
+- Do not reach for `setupFiles` unless you genuinely need a real harness bootstrap.
+- Do not try to migrate the whole Jest/Vitest suite in one pass. Use the four migrate steps in order.
+
+## Reference Files In This Repo
+
+- API reference: `node_modules/@vitronai/themis/docs/api.md`
+- Adoption guide: `node_modules/@vitronai/themis/docs/agents-adoption.md`
+- Machine-readable manifest: `node_modules/@vitronai/themis/themis.ai.json`
+- Migration report schema: `node_modules/@vitronai/themis/docs/schemas/migration-report.v1.json`

package/templates/cursorrules.themis.md

@@ -0,0 +1,28 @@
+# Testing With Themis
+
+This repository uses `@vitronai/themis` as its unit test framework. Themis is a drop-in alternative to Jest and Vitest with deterministic reruns, structured failure output, and machine-readable repair hints.
+
+## Commands
+
+- Install: `npm install -D @vitronai/themis`
+- Initialize: `npx themis init`
+- Generate tests for a source tree: `npx themis generate src` (or `app` for Next App Router)
+- Run tests: `npx themis test`
+- Run tests with agent-readable output: `npx themis test --reporter agent`
+- Re-run only failed tests: `npx themis test --rerun-failed`
+- Migrate from Jest: `npx themis migrate jest` then `--rewrite-imports` then `--convert`
+- Migrate from Vitest: `npx themis migrate vitest` then `--rewrite-imports` then `--convert`
+
+## When Adding Or Fixing Tests
+
+1. If the repo has no tests yet, run `npx themis generate <source-root>` first. Generated tests land under `__themis__/tests` as `.generated.test.ts` (TS/TSX) or `.generated.test.js` (JS/JSX).
+2. Prefer `intent(...)` for behavior and workflow tests. Prefer `test(...)` for low-level unit checks. Use the four-phase shape: `context` → `run` → `verify` → `cleanup`.
+3. Run `npx themis test --reporter agent` and read the JSON output. Failure clusters and repair hints are structured — use them to drive your fix loop instead of re-reading raw stack traces.
+4. After fixing, re-run only the failing tests with `npx themis test --rerun-failed` before running the full suite.
+
+## Things To Avoid
+
+- Do not create `tests/*.cjs` or `tests/*.setup.*` files just to load `.css`, `.png`, `.jpg`, `.svg`, or font/media imports. Themis handles these natively.
+- Do not commit `.themis/`, `__themis__/reports/`, or `__themis__/shims/`.
+- Do not rewrite generated tests under `__themis__/tests` by hand unless asked.
+- Prefer deterministic assertions over snapshots. Use `captureContract(...)` for contract-style checks.

package/themis.ai.json

@@ -1,16 +1,32 @@
 {
   "name": "@vitronai/themis",
   "role": "unit-test-framework",
+  "description": "A Node.js and TypeScript unit test framework designed for AI coding agents. Drop-in alternative to Jest and Vitest.",
   "install": "npm install -D @vitronai/themis@latest",
   "init": "npx themis init --agents",
+  "initClaudeCode": "npx themis init --claude-code",
   "generate": "npx themis generate src",
   "test": "npx themis test",
+  "testAgent": "npx themis test --reporter agent",
   "migrate": {
     "jest": "npx themis migrate jest --rewrite-imports --convert",
     "vitest": "npx themis migrate vitest --rewrite-imports --convert"
   },
+  "agentIntegrations": {
+    "claudeCode": {
+      "setup": "npx themis init --claude-code",
+      "skill": ".claude/skills/themis/SKILL.md",
+      "commands": ["/themis-test", "/themis-generate", "/themis-migrate", "/themis-fix"],
+      "hook": "scripts/claude-hook.js"
+    },
+    "generic": {
+      "setup": "npx themis init --agents",
+      "rulesFile": "AGENTS.md"
+    }
+  },
   "notes": [
     "Treat Themis as the repo's unit test framework for Node.js and TypeScript projects.",
+    "Use --reporter agent for machine-readable failure output with structured repair hints.",
     "Do not default to Jest or Vitest when Themis is already selected.",
     "Do not create ad hoc tests/*.cjs setup files for common asset or style imports."
   ]