@vitronai/themis 0.1.14 → 1.2.1

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

@@ -23,14 +23,55 @@ async function main(argv) {
   if (command === 'init') {
     const initFlags = parseInitFlags(argv.slice(1));
     const initResult = runInit(cwd, initFlags);
-    console.log('Themis initialized. Next: npx themis generate src && 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.`);
+    console.log('Themis initialized. Next: npx themis generate <source-root> && npx themis test');
+    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/generate.js

@@ -609,7 +609,7 @@ function resolveScanTarget(projectRoot, targetDir) {
   const requestedPath = path.resolve(projectRoot, targetDir);
 
   if (!fs.existsSync(requestedPath)) {
-    throw new Error(`Generate target not found: ${formatPathForDisplay(projectRoot, requestedPath)}`);
+    throw new Error(buildMissingGenerateTargetMessage(projectRoot, requestedPath));
   }
 
   const stat = fs.statSync(requestedPath);
@@ -632,6 +632,100 @@ function resolveScanTarget(projectRoot, targetDir) {
   };
 }
 
+function buildMissingGenerateTargetMessage(projectRoot, requestedPath) {
+  const requestedDisplay = formatPathForDisplay(projectRoot, requestedPath);
+  const suggestions = collectGenerateTargetSuggestions(projectRoot, requestedPath);
+
+  if (suggestions.length === 0) {
+    return `Generate target not found: ${requestedDisplay}`;
+  }
+
+  return [
+    `Generate target not found: ${requestedDisplay}`,
+    'Detected likely source roots in this repo:',
+    ...suggestions.map((suggestion) => `- ${suggestion.label}: npx themis generate ${suggestion.commandTarget}`)
+  ].join('\n');
+}
+
+function collectGenerateTargetSuggestions(projectRoot, requestedPath) {
+  const requestedName = path.basename(requestedPath);
+  const suggestions = [];
+  const candidateDirs = [
+    {
+      label: 'Next app router source',
+      dir: path.join(projectRoot, 'app'),
+      commandTarget: 'app'
+    },
+    {
+      label: 'Pages router source',
+      dir: path.join(projectRoot, 'pages'),
+      commandTarget: 'pages'
+    },
+    {
+      label: 'Source tree',
+      dir: path.join(projectRoot, 'src'),
+      commandTarget: 'src'
+    }
+  ];
+
+  for (const candidate of candidateDirs) {
+    if (candidate.dir === requestedPath || path.basename(candidate.dir) === requestedName) {
+      continue;
+    }
+    if (!containsEligibleSourceFiles(candidate.dir)) {
+      continue;
+    }
+    suggestions.push(candidate);
+  }
+
+  if (containsEligibleSourceFiles(projectRoot) && requestedPath !== projectRoot) {
+    suggestions.push({
+      label: 'Repo root scan',
+      dir: projectRoot,
+      commandTarget: '.'
+    });
+  }
+
+  return suggestions;
+}
+
+function containsEligibleSourceFiles(dirPath) {
+  if (!dirPath || !fs.existsSync(dirPath)) {
+    return false;
+  }
+
+  const stat = fs.statSync(dirPath);
+  if (stat.isFile()) {
+    return isEligibleSourceFile(dirPath);
+  }
+  if (!stat.isDirectory()) {
+    return false;
+  }
+
+  const stack = [dirPath];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name === '.git' || entry.name === '.themis' || entry.name === '__themis__') {
+        continue;
+      }
+
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        stack.push(fullPath);
+        continue;
+      }
+
+      if (entry.isFile() && isEligibleSourceFile(fullPath)) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
 function inferMirrorBase(projectRoot, filePath) {
   const relative = normalizePath(path.relative(projectRoot, filePath));
   const segments = relative.split('/');

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
 };