@vitronai/themis 0.1.15 → 1.2.2

package/scripts/claude-hook.js

@@ -0,0 +1,153 @@
+#!/usr/bin/env node
+
+// Themis Claude Code PostToolUse hook.
+//
+// This script is invoked by Claude Code after Edit/Write/MultiEdit tool calls.
+// It reads the tool input from stdin, decides whether the edit is worth
+// re-running tests for, and if so runs `themis test --reporter agent` (using
+// --rerun-failed when there is a prior failed-tests artifact). When tests
+// fail, the JSON failure payload is written to stderr and the script exits
+// with code 2 — Claude Code feeds that back into the model so it can fix
+// failures using the structured `failures[].cluster` and
+// `failures[].repairHints` fields.
+//
+// Wire it up in `.claude/settings.json`:
+//
+// {
+//   "hooks": {
+//     "PostToolUse": [
+//       {
+//         "matcher": "Edit|Write|MultiEdit",
+//         "hooks": [
+//           { "type": "command", "command": "node node_modules/@vitronai/themis/scripts/claude-hook.js" }
+//         ]
+//       }
+//     ]
+//   }
+// }
+//
+// Disable temporarily by setting THEMIS_HOOK_DISABLED=1 in your environment.
+// Disable permanently by removing the entry from .claude/settings.json.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const SOURCE_EXT = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
+const IGNORED_PATH_SEGMENTS = ['.themis', '__themis__', 'node_modules', '.git'];
+
+function exitSilent() {
+  process.exit(0);
+}
+
+function readStdinSync() {
+  try {
+    return fs.readFileSync(0, 'utf8');
+  } catch (_err) {
+    return '';
+  }
+}
+
+function parsePayload(raw) {
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch (_err) {
+    return null;
+  }
+}
+
+function extractFilePath(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  const input = payload.tool_input;
+  if (!input || typeof input !== 'object') return null;
+  if (typeof input.file_path === 'string') return input.file_path;
+  // MultiEdit nests edits in an array but still uses the top-level file_path.
+  return null;
+}
+
+function isWorthRerunning(filePath, cwd) {
+  if (!filePath) return false;
+  const normalized = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+  const relative = path.relative(cwd, normalized);
+  if (relative.startsWith('..')) return false;
+
+  const segments = relative.split(path.sep);
+  for (const segment of segments) {
+    if (IGNORED_PATH_SEGMENTS.includes(segment)) return false;
+  }
+
+  const ext = path.extname(normalized).toLowerCase();
+  if (!SOURCE_EXT.has(ext)) return false;
+
+  return true;
+}
+
+function hasFailedTestsArtifact(cwd) {
+  const candidates = [
+    path.join(cwd, '.themis', 'runs', 'failed-tests.json'),
+    path.join(cwd, '.themis', 'failed-tests.json')
+  ];
+  return candidates.some((candidate) => fs.existsSync(candidate));
+}
+
+function findThemisBin(cwd) {
+  // Prefer the locally installed bin so the hook does not depend on `npx`
+  // resolution behavior or network state.
+  const localBin = path.join(cwd, 'node_modules', '.bin', 'themis');
+  if (fs.existsSync(localBin)) return { command: localBin, args: [] };
+  const localScript = path.join(cwd, 'node_modules', '@vitronai', 'themis', 'bin', 'themis.js');
+  if (fs.existsSync(localScript)) return { command: process.execPath, args: [localScript] };
+  return { command: 'npx', args: ['--no-install', 'themis'] };
+}
+
+function main() {
+  if (process.env.THEMIS_HOOK_DISABLED) exitSilent();
+
+  const raw = readStdinSync();
+  const payload = parsePayload(raw);
+  const cwd = (payload && typeof payload.cwd === 'string' && payload.cwd) || process.cwd();
+  const filePath = extractFilePath(payload);
+
+  if (!isWorthRerunning(filePath, cwd)) exitSilent();
+
+  const themis = findThemisBin(cwd);
+  const args = [...themis.args, 'test', '--reporter', 'agent'];
+  if (hasFailedTestsArtifact(cwd)) args.push('--rerun-failed');
+
+  const result = spawnSync(themis.command, args, {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: process.env,
+    maxBuffer: 32 * 1024 * 1024
+  });
+
+  if (result.error) {
+    // Hook itself failed (binary not found, etc). Stay silent rather than
+    // blocking the user's edit loop on infrastructure problems.
+    exitSilent();
+  }
+
+  const stdout = (result.stdout || Buffer.alloc(0)).toString('utf8');
+  const stderr = (result.stderr || Buffer.alloc(0)).toString('utf8');
+
+  if (result.status === 0) {
+    exitSilent();
+  }
+
+  // Tests failed. Surface the agent JSON payload (or stderr fallback) to
+  // Claude via stderr + exit 2 so it lands in the model's context.
+  process.stderr.write('Themis tests failed after edit. Use failures[].cluster and failures[].repairHints below to fix:\n');
+  if (stdout.trim().length > 0) {
+    process.stderr.write(stdout);
+    if (!stdout.endsWith('\n')) process.stderr.write('\n');
+  } else if (stderr.trim().length > 0) {
+    process.stderr.write(stderr);
+    if (!stderr.endsWith('\n')) process.stderr.write('\n');
+  }
+  process.exit(2);
+}
+
+main();

package/src/cli.js

@@ -24,13 +24,54 @@ async function main(argv) {
     const initFlags = parseInitFlags(argv.slice(1));
     const initResult = runInit(cwd, initFlags);
     console.log('Themis initialized. Next: npx themis generate <source-root> && npx themis test');
-    if (initFlags.agents) {
-      if (initResult && initResult.path && initResult.created) {
-        console.log(`Agents: created ${formatCliPath(cwd, initResult.path)} from the Themis downstream template.`);
+    if (initResult.autoDetected) {
+      const detected = [];
+      if (initResult.agents) detected.push('AGENTS.md');
+      if (initResult.claudeCode) detected.push('Claude Code');
+      if (initResult.cursor) detected.push('Cursor');
+      if (detected.length > 0) {
+        console.log(`Auto-detected: ${detected.join(', ')}`);
+      }
+    }
+    if (initFlags.agents || initResult.agents) {
+      const agents = initResult.agents;
+      if (agents && agents.created) {
+        console.log(`Agents: created ${formatCliPath(cwd, agents.path)} from the Themis downstream template.`);
       } else {
         console.log('Agents: skipped AGENTS.md scaffold because one already exists.');
       }
     }
+    if (initResult.cursor) {
+      const cur = initResult.cursor;
+      if (cur.created) {
+        console.log(`Cursor: created ${formatCliPath(cwd, cur.path)} from the Themis Cursor template.`);
+      } else if (cur.appended) {
+        console.log(`Cursor: appended Themis section to ${formatCliPath(cwd, cur.path)}.`);
+      } else {
+        console.log(`Cursor: skipped .cursorrules update (already mentions @vitronai/themis).`);
+      }
+    }
+    if (initResult.claudeCode) {
+      const cc = initResult.claudeCode;
+      if (cc.claudeMd.created) {
+        console.log(`Claude Code: created ${formatCliPath(cwd, cc.claudeMd.path)} from the Themis Claude template.`);
+      } else if (cc.claudeMd.appended) {
+        console.log(`Claude Code: appended Themis section to ${formatCliPath(cwd, cc.claudeMd.path)}.`);
+      } else {
+        console.log(`Claude Code: skipped CLAUDE.md update (already mentions @vitronai/themis).`);
+      }
+      if (cc.skill.created) {
+        console.log(`Claude Code: installed skill at ${formatCliPath(cwd, cc.skill.path)}.`);
+      } else {
+        console.log(`Claude Code: skipped skill (${formatCliPath(cwd, cc.skill.path)} already exists).`);
+      }
+      if (cc.commands.written.length > 0) {
+        console.log(`Claude Code: installed ${cc.commands.written.length} slash command(s) under ${formatCliPath(cwd, cc.commands.dir)}.`);
+      }
+      if (cc.commands.skipped.length > 0) {
+        console.log(`Claude Code: skipped ${cc.commands.skipped.length} existing slash command file(s).`);
+      }
+    }
     return;
   }
 
@@ -95,6 +136,17 @@ async function main(argv) {
     if (result.convertedFiles && result.convertedFiles.length > 0) {
       console.log(`Codemods: converted ${result.convertedFiles.length} file(s) to Themis-native patterns.`);
     }
+    if (result.assist) {
+      console.log(`Assistant: analyzed ${result.assistSummary.analyzedFiles} migrated file(s).`);
+      if (result.assistSummary.findings.length > 0) {
+        console.log(
+          `Assistant: flagged ${result.assistSummary.findings.length} manual follow-up item(s) across ${result.assistSummary.unresolvedFiles.length} file(s).`
+        );
+      } else {
+        console.log('Assistant: no unsupported Jest/Vitest-only patterns detected in migrated files.');
+      }
+      console.log(`Report: ${formatCliPath(cwd, result.reportPath)}`);
+    }
     console.log('Runtime compatibility is enabled for @jest/globals, vitest, and @testing-library/react imports.');
     console.log('Next: run npx themis test or npm run test:themis');
     return;
@@ -500,7 +552,8 @@ function parseMigrateFlags(args) {
   const flags = {
     source: args[0],
     rewriteImports: false,
-    convert: false
+    convert: false,
+    assist: false
   };
 
   for (let i = 1; i < args.length; i += 1) {
@@ -511,6 +564,16 @@ function parseMigrateFlags(args) {
     }
     if (token === '--convert') {
       flags.convert = true;
+      continue;
+    }
+    if (token === '--assist') {
+      flags.assist = true;
+      flags.rewriteImports = true;
+      flags.convert = true;
+      continue;
+    }
+    if (token.startsWith('-')) {
+      throw new Error(`Unsupported migrate option: ${token}`);
     }
   }
 
@@ -519,7 +582,9 @@ function parseMigrateFlags(args) {
 
 function parseInitFlags(args) {
   const flags = {
-    agents: false
+    agents: false,
+    claudeCode: false,
+    cursor: false
   };
 
   for (let i = 0; i < args.length; i += 1) {
@@ -528,6 +593,14 @@ function parseInitFlags(args) {
       flags.agents = true;
       continue;
     }
+    if (token === '--claude-code' || token === '--claude') {
+      flags.claudeCode = true;
+      continue;
+    }
+    if (token === '--cursor') {
+      flags.cursor = true;
+      continue;
+    }
     if (token.startsWith('-')) {
       throw new Error(`Unsupported init option: ${token}`);
     }
@@ -741,7 +814,7 @@ function printUsage() {
   console.log('  generate [path]         Scan source files and generate Themis contract tests');
   console.log('                         Options: [--json] [--plan] [--output path] [--files a,b] [--match-source regex] [--match-export regex] [--scenario name] [--min-confidence level] [--require-confidence level] [--include regex] [--exclude regex] [--review] [--update] [--clean] [--changed] [--force] [--strict] [--write-hints] [--fail-on-skips] [--fail-on-conflicts]');
   console.log('  scan [path]             Alias for generate');
-  console.log('  migrate <jest|vitest> [--rewrite-imports] [--convert]   Scaffold an incremental migration bridge for existing suites');
+  console.log('  migrate <jest|vitest> [--rewrite-imports] [--convert] [--assist]   Scaffold an incremental migration bridge for existing suites');
   console.log('  test [--json] [--agent] [--next] [--reporter spec|next|json|agent|html] [--workers N] [--stability N] [--environment node|jsdom] [--isolation worker|in-process] [--cache] [--update-contracts] [--fix] [-w|--watch] [--html-output path] [--match regex] [--rerun-failed] [--no-memes] [--lexicon classic|themis]');
 }
 

package/src/init.js

@@ -3,17 +3,36 @@ const path = require('path');
 const { initConfig } = require('./config');
 const { ensureGitignoreEntries } = require('./gitignore');
 
-const AGENTS_TEMPLATE_PATH = path.join(__dirname, '..', 'templates', 'AGENTS.themis.md');
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+const AGENTS_TEMPLATE_PATH = path.join(TEMPLATES_DIR, 'AGENTS.themis.md');
+const CLAUDE_TEMPLATE_PATH = path.join(TEMPLATES_DIR, 'CLAUDE.themis.md');
+const CLAUDE_SKILL_TEMPLATE_PATH = path.join(TEMPLATES_DIR, 'claude-skill', 'SKILL.md');
+const CLAUDE_COMMANDS_TEMPLATE_DIR = path.join(TEMPLATES_DIR, 'claude-commands');
+const CURSOR_TEMPLATE_PATH = path.join(TEMPLATES_DIR, 'cursorrules.themis.md');
 
 function runInit(cwd, options = {}) {
   initConfig(cwd);
   ensureGitignoreEntries(cwd, ['.themis/', '__themis__/reports/', '__themis__/shims/']);
 
-  if (options.agents) {
-    return ensureAgentsTemplate(cwd);
+  const hasExplicitFlags = options.agents || options.claudeCode || options.cursor;
+  const detected = hasExplicitFlags ? options : detectAgents(cwd, options);
+
+  const result = {};
+
+  if (detected.agents) {
+    result.agents = ensureAgentsTemplate(cwd);
+  }
+
+  if (detected.claudeCode) {
+    result.claudeCode = ensureClaudeCodeAssets(cwd);
+  }
+
+  if (detected.cursor) {
+    result.cursor = writeCursorRules(cwd);
   }
 
-  return null;
+  result.autoDetected = !hasExplicitFlags;
+  return result;
 }
 
 function ensureAgentsTemplate(cwd) {
@@ -33,6 +52,105 @@ function ensureAgentsTemplate(cwd) {
   };
 }
 
+function ensureClaudeCodeAssets(cwd) {
+  const result = {
+    claudeMd: writeClaudeMd(cwd),
+    skill: writeClaudeSkill(cwd),
+    commands: writeClaudeCommands(cwd)
+  };
+  return result;
+}
+
+function writeClaudeMd(cwd) {
+  const targetPath = path.join(cwd, 'CLAUDE.md');
+  const source = fs.readFileSync(CLAUDE_TEMPLATE_PATH, 'utf8');
+
+  if (!fs.existsSync(targetPath)) {
+    fs.writeFileSync(targetPath, source, 'utf8');
+    return { path: targetPath, created: true, appended: false };
+  }
+
+  const existing = fs.readFileSync(targetPath, 'utf8');
+  if (existing.includes('@vitronai/themis')) {
+    return { path: targetPath, created: false, appended: false };
+  }
+
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+  fs.writeFileSync(targetPath, existing + separator + source, 'utf8');
+  return { path: targetPath, created: false, appended: true };
+}
+
+function writeClaudeSkill(cwd) {
+  const targetDir = path.join(cwd, '.claude', 'skills', 'themis');
+  const targetPath = path.join(targetDir, 'SKILL.md');
+  if (fs.existsSync(targetPath)) {
+    return { path: targetPath, created: false };
+  }
+  fs.mkdirSync(targetDir, { recursive: true });
+  const source = fs.readFileSync(CLAUDE_SKILL_TEMPLATE_PATH, 'utf8');
+  fs.writeFileSync(targetPath, source, 'utf8');
+  return { path: targetPath, created: true };
+}
+
+function writeClaudeCommands(cwd) {
+  const targetDir = path.join(cwd, '.claude', 'commands');
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const entries = fs.readdirSync(CLAUDE_COMMANDS_TEMPLATE_DIR);
+  const written = [];
+  const skipped = [];
+
+  for (const entry of entries) {
+    if (!entry.endsWith('.md')) continue;
+    const sourcePath = path.join(CLAUDE_COMMANDS_TEMPLATE_DIR, entry);
+    const targetPath = path.join(targetDir, entry);
+    if (fs.existsSync(targetPath)) {
+      skipped.push(targetPath);
+      continue;
+    }
+    const source = fs.readFileSync(sourcePath, 'utf8');
+    fs.writeFileSync(targetPath, source, 'utf8');
+    written.push(targetPath);
+  }
+
+  return { dir: targetDir, written, skipped };
+}
+
+function detectAgents(cwd) {
+  const flags = { agents: true, claudeCode: false, cursor: false };
+
+  // Claude Code: .claude/ dir or CLAUDE.md exists
+  if (fs.existsSync(path.join(cwd, '.claude')) || fs.existsSync(path.join(cwd, 'CLAUDE.md'))) {
+    flags.claudeCode = true;
+  }
+
+  // Cursor: .cursorrules or .cursor/ dir exists
+  if (fs.existsSync(path.join(cwd, '.cursorrules')) || fs.existsSync(path.join(cwd, '.cursor'))) {
+    flags.cursor = true;
+  }
+
+  return flags;
+}
+
+function writeCursorRules(cwd) {
+  const targetPath = path.join(cwd, '.cursorrules');
+  const source = fs.readFileSync(CURSOR_TEMPLATE_PATH, 'utf8');
+
+  if (!fs.existsSync(targetPath)) {
+    fs.writeFileSync(targetPath, source, 'utf8');
+    return { path: targetPath, created: true, appended: false };
+  }
+
+  const existing = fs.readFileSync(targetPath, 'utf8');
+  if (existing.includes('@vitronai/themis')) {
+    return { path: targetPath, created: false, appended: false };
+  }
+
+  const separator = existing.endsWith('\n') ? '\n' : '\n\n';
+  fs.writeFileSync(targetPath, existing + separator + source, 'utf8');
+  return { path: targetPath, created: false, appended: true };
+}
+
 module.exports = {
   runInit
 };

package/src/migrate.js

@@ -10,6 +10,40 @@ const THEMIS_COMPAT_FILE = 'themis.compat.js';
 const MIGRATION_REPORT_FILE = ARTIFACT_RELATIVE_PATHS.migrationReport;
 const SCANNABLE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
 const IGNORED_DIRECTORIES = new Set(['node_modules', '.git', '.themis']);
+const MIGRATION_ASSIST_PATTERNS = Object.freeze([
+  {
+    id: 'remaining-framework-import',
+    category: 'remaining-framework-import',
+    severity: 'warning',
+    pattern: /(?:import\s+[^;]*?from\s+['"](?:@jest\/globals|vitest|@testing-library\/react)['"]|import\s*\(\s*['"](?:@jest\/globals|vitest|@testing-library\/react)['"]\s*\)|require\(\s*['"](?:@jest\/globals|vitest|@testing-library\/react)['"]\s*\))/,
+    message: 'Framework-specific imports are still present after migration scaffolding.',
+    suggestion: 'Rewrite or remove remaining framework imports so the suite only depends on Themis-compatible entry points.'
+  },
+  {
+    id: 'unsupported-helper',
+    category: 'unsupported-helper',
+    severity: 'warning',
+    pattern: /\b(?:jest|vi)\.(?:mocked|doMock|dontMock|setMock|requireActual|requireMock|createMockFromModule|isolateModules|isolateModulesAsync|unstable_mockModule|importActual|importMock)\s*\(/,
+    message: 'Unsupported Jest/Vitest helper detected.',
+    suggestion: 'Replace the helper with an explicit Themis mock, fixture, or project-local test utility before relying on the migrated suite.'
+  },
+  {
+    id: 'async-matcher-chain',
+    category: 'async-matcher-chain',
+    severity: 'warning',
+    pattern: /\.\s*(?:resolves|rejects)\b/,
+    message: 'Promise matcher chains remain in the migrated file.',
+    suggestion: 'Rewrite promise assertions to explicit await-based checks so they run under Themis without framework-specific matcher chaining.'
+  },
+  {
+    id: 'focused-alias',
+    category: 'focused-alias',
+    severity: 'warning',
+    pattern: /\b(?:fit|xit|fdescribe|xdescribe)\s*\(/,
+    message: 'Focused or excluded Jest/Vitest aliases remain in the migrated file.',
+    suggestion: 'Replace focused aliases with Themis-supported describe/test forms before running the migrated suite broadly.'
+  }
+]);
 
 function runMigrate(cwd, framework, options = {}) {
   const source = String(framework || '').trim().toLowerCase();
@@ -66,7 +100,14 @@ function runMigrate(cwd, framework, options = {}) {
   const conversionSummary = options.convert
     ? convertMigrationFiles(projectRoot, scan.matches)
     : { convertedFiles: [], convertedAssertions: 0, removedImports: 0 };
-  const report = buildMigrationReport(projectRoot, source, scan.matches, rewriteSummary, conversionSummary);
+  const assistSummary = analyzeMigrationAssist(projectRoot, scan.matches, {
+    enabled: Boolean(options.assist)
+  });
+  const report = buildMigrationReport(projectRoot, source, scan.matches, rewriteSummary, conversionSummary, assistSummary, {
+    rewriteImports: Boolean(options.rewriteImports),
+    convert: Boolean(options.convert),
+    assist: Boolean(options.assist)
+  });
   fs.mkdirSync(path.dirname(reportPath), { recursive: true });
   fs.writeFileSync(reportPath, `${JSON.stringify(report, null, 2)}\n`, 'utf8');
 
@@ -84,7 +125,9 @@ function runMigrate(cwd, framework, options = {}) {
     rewriteImports: Boolean(options.rewriteImports),
     rewrittenFiles: rewriteSummary.rewrittenFiles,
     convert: Boolean(options.convert),
-    convertedFiles: conversionSummary.convertedFiles
+    convertedFiles: conversionSummary.convertedFiles,
+    assist: Boolean(options.assist),
+    assistSummary
   };
 }
 
@@ -170,12 +213,20 @@ function buildMigrationReport(
   source,
   matches,
   rewriteSummary = { rewrittenFiles: [], rewrittenImports: 0 },
-  conversionSummary = { convertedFiles: [], convertedAssertions: 0, removedImports: 0 }
+  conversionSummary = { convertedFiles: [], convertedAssertions: 0, removedImports: 0 },
+  assistSummary = buildEmptyAssistSummary(false),
+  mode = { rewriteImports: false, convert: false, assist: false }
 ) {
+  const effectiveAssistSummary = normalizeAssistSummary(assistSummary, Boolean(mode.assist));
   return {
     schema: 'themis.migration.report.v1',
     source,
     createdAt: new Date().toISOString(),
+    mode: {
+      rewriteImports: Boolean(mode.rewriteImports),
+      convert: Boolean(mode.convert),
+      assist: Boolean(mode.assist)
+    },
     summary: {
       matchedFiles: matches.length,
       jestGlobals: matches.filter((entry) => entry.imports.includes('@jest/globals')).length,
@@ -185,11 +236,18 @@ function buildMigrationReport(
       rewrittenImports: Number(rewriteSummary.rewrittenImports || 0),
       convertedFiles: Array.isArray(conversionSummary.convertedFiles) ? conversionSummary.convertedFiles.length : 0,
       convertedAssertions: Number(conversionSummary.convertedAssertions || 0),
-      removedImports: Number(conversionSummary.removedImports || 0)
+      removedImports: Number(conversionSummary.removedImports || 0),
+      assistedFiles: Number(effectiveAssistSummary.analyzedFiles || 0),
+      unresolvedFiles: Array.isArray(effectiveAssistSummary.unresolvedFiles) ? effectiveAssistSummary.unresolvedFiles.length : 0,
+      findings: Array.isArray(effectiveAssistSummary.findings) ? effectiveAssistSummary.findings.length : 0,
+      unsupportedPatterns: Number(effectiveAssistSummary.unsupportedPatterns || 0)
     },
     files: matches,
     nextActions: [
       'Run npx themis test to execute migrated suites under the Themis runtime.',
+      ...(effectiveAssistSummary.findings.length > 0
+        ? ['Resolve assistant findings in the migration report before relying on the migrated suite in CI.']
+        : []),
       'Replace any unsupported Jest/Vitest-only helpers with Themis built-ins or project setup utilities.',
       'Use npx themis generate src for source-driven unit-layer coverage alongside migrated suites.'
     ],
@@ -198,7 +256,71 @@ function buildMigrationReport(
       : [],
     conversions: Array.isArray(conversionSummary.convertedFiles)
       ? conversionSummary.convertedFiles
-      : []
+      : [],
+    assistant: effectiveAssistSummary
+  };
+}
+
+function analyzeMigrationAssist(projectRoot, matches, options = {}) {
+  const enabled = Boolean(options.enabled);
+  if (!enabled) {
+    return buildEmptyAssistSummary(false);
+  }
+
+  const findings = [];
+  const unresolvedFiles = new Set();
+
+  for (const match of matches) {
+    const absoluteFile = path.join(projectRoot, match.file);
+    const sourceText = fs.readFileSync(absoluteFile, 'utf8');
+
+    for (const definition of MIGRATION_ASSIST_PATTERNS) {
+      if (!definition.pattern.test(sourceText)) {
+        continue;
+      }
+      unresolvedFiles.add(match.file);
+      findings.push({
+        file: match.file,
+        category: definition.category,
+        severity: definition.severity,
+        pattern: definition.id,
+        message: definition.message,
+        suggestion: definition.suggestion
+      });
+    }
+  }
+
+  return normalizeAssistSummary(
+    {
+      enabled: true,
+      analyzedFiles: matches.length,
+      findings,
+      unresolvedFiles: Array.from(unresolvedFiles).sort(),
+      unsupportedPatterns: findings.length
+    },
+    true
+  );
+}
+
+function buildEmptyAssistSummary(enabled) {
+  return {
+    enabled: Boolean(enabled),
+    analyzedFiles: 0,
+    findings: [],
+    unresolvedFiles: [],
+    unsupportedPatterns: 0
+  };
+}
+
+function normalizeAssistSummary(summary, enabled) {
+  const findings = Array.isArray(summary && summary.findings) ? summary.findings : [];
+  const unresolvedFiles = Array.isArray(summary && summary.unresolvedFiles) ? summary.unresolvedFiles : [];
+  return {
+    enabled: Boolean(enabled),
+    analyzedFiles: Number((summary && summary.analyzedFiles) || 0),
+    findings,
+    unresolvedFiles,
+    unsupportedPatterns: Number((summary && summary.unsupportedPatterns) || findings.length)
   };
 }
 

package/templates/CLAUDE.themis.md

@@ -0,0 +1,43 @@
+# Testing With Themis
+
+This repository uses [`@vitronai/themis`](https://www.npmjs.com/package/@vitronai/themis) as its unit test framework. Themis is a drop-in alternative to Jest and Vitest, designed for AI coding agents like Claude Code: 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 and emit 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 You Are Asked To Add Or Fix 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). Use them as a starting point — do not delete or rewrite them wholesale.
+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.
+
+## When You Are Asked To Migrate From Jest Or Vitest
+
+1. Run `npx themis migrate jest` (or `vitest`) — this scaffolds compatibility, no rewrites yet.
+2. Run `npx themis migrate jest --rewrite-imports` to point imports at `themis.compat.js`.
+3. Run `npx themis migrate jest --convert` to apply codemods toward native Themis style.
+4. Run `npx themis migrate jest --assist` to get a structured findings report of files that still need manual follow-up. The report path is printed at the end of the command — read it before guessing what to fix.
+5. Run `npx themis test` after each step. Migration is incremental on purpose; do not try to convert the whole suite in one pass.
+
+## 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 just to load `.css`, `.png`, `.jpg`, `.svg`, or font/media imports. Themis handles these 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; treat them as Themis-managed.
+- Do not reach for snapshot tests as the default — prefer deterministic assertions and `captureContract(...)` for contract-style checks.
+
+## Reference
+
+- API reference: [`node_modules/@vitronai/themis/docs/api.md`](node_modules/@vitronai/themis/docs/api.md)
+- Adoption guide: [`node_modules/@vitronai/themis/docs/agents-adoption.md`](node_modules/@vitronai/themis/docs/agents-adoption.md)
+- Machine-readable manifest: [`node_modules/@vitronai/themis/themis.ai.json`](node_modules/@vitronai/themis/themis.ai.json)

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

@@ -0,0 +1,14 @@
+---
+description: Fix failing Themis tests using the agent reporter's repair hints
+---
+
+Read the most recent Themis run output and fix the failures.
+
+1. Run `npx themis test --reporter agent` and capture the JSON output.
+2. Group the failures by `failures[].cluster`. Fixes within a cluster usually share a root cause — address the cluster, not each failure independently.
+3. For each cluster, read `failures[].repairHints` first. They are structured suggestions you can act on directly.
+4. Apply the smallest fix that addresses the root cause. Do not refactor surrounding code.
+5. Re-run with `npx themis test --rerun-failed` to confirm the cluster is fixed.
+6. Repeat for the next cluster. Only run the full suite once `--rerun-failed` is green.
+
+If the user passed specific test names or files, scope the work to those: $ARGUMENTS