worclaude 2.5.1 → 2.6.0

package/src/core/project-scanner/detectors/spec-docs.js

@@ -0,0 +1,110 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { readFile } from '../../../utils/file.js';
+
+const EXCLUDES = new Set([
+  'node_modules',
+  '.git',
+  '.claude',
+  'dist',
+  'build',
+  '.next',
+  'target',
+  'vendor',
+  '.venv',
+  '__pycache__',
+  '.cache',
+]);
+
+const MAX_FILES = 200;
+const MAX_DEPTH = 3;
+const HEADING_CHAR_CAP = 80;
+const ROOT_PATTERNS = [/^PRD/i, /^SPEC/i, /^REQUIREMENTS/i];
+
+async function rootMatches(projectRoot) {
+  const matches = [];
+  try {
+    const entries = await fs.readdir(projectRoot, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile()) continue;
+      if (ROOT_PATTERNS.some((p) => p.test(entry.name))) {
+        matches.push(entry.name);
+      }
+    }
+  } catch {
+    /* missing or unreadable — non-fatal */
+  }
+  return matches;
+}
+
+async function walkDocs(dir, projectRoot, depth, results) {
+  if (depth > MAX_DEPTH || results.length >= MAX_FILES) return;
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (results.length >= MAX_FILES) return;
+    if (EXCLUDES.has(entry.name)) continue;
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      await walkDocs(fullPath, projectRoot, depth + 1, results);
+    } else if (entry.isFile() && /\.(md|txt)$/i.test(entry.name)) {
+      results.push(path.relative(projectRoot, fullPath).split(path.sep).join('/'));
+    }
+  }
+}
+
+async function firstHeading(projectRoot, relativePath) {
+  try {
+    const raw = await readFile(path.join(projectRoot, relativePath));
+    for (const rawLine of raw.split(/\r?\n/)) {
+      const line = rawLine.trim();
+      if (line === '') continue;
+      const match = line.match(/^#\s+(.+)$/);
+      if (match) return match[1].slice(0, HEADING_CHAR_CAP);
+      return line.slice(0, HEADING_CHAR_CAP);
+    }
+  } catch {
+    /* missing or unreadable — non-fatal */
+  }
+  return null;
+}
+
+export default async function detectSpecDocs(projectRoot) {
+  const docs = [];
+  const rootNames = await rootMatches(projectRoot);
+  for (const name of rootNames) docs.push(name);
+
+  const docsDir = path.join(projectRoot, 'docs');
+  try {
+    const stat = await fs.stat(docsDir);
+    if (stat.isDirectory()) {
+      await walkDocs(docsDir, projectRoot, 1, docs);
+    }
+  } catch {
+    /* missing or unreadable — non-fatal */
+  }
+
+  if (docs.length === 0) return [];
+
+  const unique = Array.from(new Set(docs));
+  const value = await Promise.all(
+    unique.map(async (relative) => ({
+      path: relative,
+      firstHeading: await firstHeading(projectRoot, relative),
+    }))
+  );
+
+  return [
+    {
+      field: 'specDocs',
+      value,
+      confidence: 'high',
+      source: 'project tree',
+      candidates: null,
+    },
+  ];
+}

package/src/core/project-scanner/detectors/testing.js

@@ -0,0 +1,88 @@
+import path from 'node:path';
+import { fileExists } from '../../../utils/file.js';
+import { getAllDeps, readPyprojectToml } from '../manifests.js';
+
+const CONFIG_VARIANTS = {
+  vitest: ['vitest.config.js', 'vitest.config.ts', 'vitest.config.mjs', 'vitest.config.mts'],
+  jest: ['jest.config.js', 'jest.config.ts', 'jest.config.mjs', 'jest.config.cjs'],
+  playwright: ['playwright.config.js', 'playwright.config.ts', 'playwright.config.mjs'],
+  cypress: ['cypress.config.js', 'cypress.config.ts', 'cypress.config.mjs'],
+  mocha: ['.mocharc.js', '.mocharc.json', '.mocharc.yml', '.mocharc.cjs'],
+};
+
+async function findConfig(projectRoot, variants) {
+  for (const name of variants) {
+    if (await fileExists(path.join(projectRoot, name))) return name;
+  }
+  return null;
+}
+
+async function hasPytestConfig(projectRoot) {
+  if (await fileExists(path.join(projectRoot, 'pytest.ini'))) return 'pytest.ini';
+  const pyproject = await readPyprojectToml(projectRoot);
+  if (pyproject && pyproject.tool && pyproject.tool.pytest) {
+    return 'pyproject.toml';
+  }
+  return null;
+}
+
+export default async function detectTesting(projectRoot) {
+  const { js, py } = await getAllDeps(projectRoot);
+  const results = [];
+
+  const jsFrameworkOrder = ['vitest', 'jest', 'mocha'];
+  for (const name of jsFrameworkOrder) {
+    if (js[name] !== undefined) {
+      const configFile = await findConfig(projectRoot, CONFIG_VARIANTS[name] || []);
+      results.push({
+        field: 'testing',
+        value: {
+          framework: name,
+          configFile,
+          browserTesting: false,
+        },
+        confidence: 'high',
+        source: configFile || 'package.json',
+        candidates: null,
+      });
+      break;
+    }
+  }
+
+  if (js['playwright'] !== undefined || js['@playwright/test'] !== undefined) {
+    const configFile = await findConfig(projectRoot, CONFIG_VARIANTS.playwright);
+    results.push({
+      field: 'testing',
+      value: { framework: 'playwright', configFile, browserTesting: true },
+      confidence: 'high',
+      source: configFile || 'package.json',
+      candidates: null,
+    });
+  }
+
+  if (js['cypress'] !== undefined) {
+    const configFile = await findConfig(projectRoot, CONFIG_VARIANTS.cypress);
+    results.push({
+      field: 'testing',
+      value: { framework: 'cypress', configFile, browserTesting: true },
+      confidence: 'high',
+      source: configFile || 'package.json',
+      candidates: null,
+    });
+  }
+
+  const pytestPresent =
+    py['pytest'] !== undefined || Object.keys(py).some((k) => k.startsWith('pytest-'));
+  if (pytestPresent) {
+    const configFile = await hasPytestConfig(projectRoot);
+    results.push({
+      field: 'testing',
+      value: { framework: 'pytest', configFile, browserTesting: false },
+      confidence: 'high',
+      source: configFile || 'pyproject.toml',
+      candidates: null,
+    });
+  }
+
+  return results;
+}

package/src/core/project-scanner/index.js

@@ -0,0 +1,126 @@
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import fs from 'fs-extra';
+import { dirExists } from '../../utils/file.js';
+import { resetManifestCache } from './manifests.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DETECTOR_TIMEOUT_MS = 5000;
+const SCHEMA_VERSION = 1;
+
+async function loadDetectorsFromDisk() {
+  const detectorsDir = path.join(__dirname, 'detectors');
+  const entries = await fs.readdir(detectorsDir, { withFileTypes: true });
+  const detectorFiles = entries.filter(
+    (e) =>
+      e.isFile() && !e.name.startsWith('.') && !e.name.startsWith('_') && e.name.endsWith('.js')
+  );
+  return Promise.all(
+    detectorFiles.map(async (entry) => {
+      const fileUrl = pathToFileURL(path.join(detectorsDir, entry.name)).href;
+      const mod = await import(fileUrl);
+      if (typeof mod.default !== 'function') {
+        throw new Error(`Detector ${entry.name} must export a default function`);
+      }
+      return { name: path.basename(entry.name, '.js'), fn: mod.default };
+    })
+  );
+}
+
+function normalizeOverride(overrideDetectors) {
+  return overrideDetectors.map((entry, index) => {
+    if (typeof entry === 'function') {
+      return { name: entry.name || `override-${index}`, fn: entry };
+    }
+    if (entry && typeof entry.fn === 'function') {
+      return { name: entry.name || `override-${index}`, fn: entry.fn };
+    }
+    throw new Error(`overrideDetectors[${index}] must be a function or { name, fn } object`);
+  });
+}
+
+function withTimeout(promise, ms) {
+  let timeoutId;
+  const timeout = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => reject(new Error('timeout')), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timeoutId));
+}
+
+async function runDetector(detector, projectRoot) {
+  try {
+    const results = await withTimeout(
+      Promise.resolve().then(() => detector.fn(projectRoot)),
+      DETECTOR_TIMEOUT_MS
+    );
+    if (!Array.isArray(results)) {
+      return {
+        results: [],
+        error: {
+          detector: detector.name,
+          kind: 'exception',
+          message: `Detector did not return an array (got ${typeof results})`,
+        },
+      };
+    }
+    const annotated = results.map((r) => ({ ...r, detector: detector.name }));
+    return { results: annotated, error: null };
+  } catch (err) {
+    const kind = err && err.message === 'timeout' ? 'timeout' : 'exception';
+    const message =
+      kind === 'timeout'
+        ? `Detector exceeded ${DETECTOR_TIMEOUT_MS}ms timeout`
+        : String(err && err.message ? err.message : err);
+    return { results: [], error: { detector: detector.name, kind, message } };
+  }
+}
+
+export async function scanProject(projectRoot, options = {}) {
+  if (!projectRoot || typeof projectRoot !== 'string') {
+    throw new Error('scanProject requires a projectRoot string');
+  }
+  const absoluteRoot = path.resolve(projectRoot);
+  if (!(await dirExists(absoluteRoot))) {
+    throw new Error(`projectRoot not found: ${absoluteRoot}`);
+  }
+
+  resetManifestCache();
+
+  const detectors = options.overrideDetectors
+    ? normalizeOverride(options.overrideDetectors)
+    : await loadDetectorsFromDisk();
+
+  const settled = await Promise.all(detectors.map((d) => runDetector(d, absoluteRoot)));
+
+  const results = [];
+  const errors = [];
+  for (const { results: r, error } of settled) {
+    for (const item of r) results.push(item);
+    if (error) errors.push(error);
+  }
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    generatedAt: new Date().toISOString(),
+    projectRoot: absoluteRoot,
+    results,
+    errors,
+  };
+}
+
+export async function writeDetectionReport(report, projectRoot) {
+  if (!report || typeof report !== 'object') {
+    throw new Error('writeDetectionReport requires a report object');
+  }
+  if (report.schemaVersion !== SCHEMA_VERSION) {
+    throw new Error(`Unsupported schemaVersion: ${report.schemaVersion}`);
+  }
+  if (!Array.isArray(report.results) || !Array.isArray(report.errors)) {
+    throw new Error('Report must have results and errors arrays');
+  }
+  const cacheDir = path.join(projectRoot, '.claude', 'cache');
+  await fs.ensureDir(cacheDir);
+  const filePath = path.join(cacheDir, 'detection-report.json');
+  await fs.writeFile(filePath, JSON.stringify(report, null, 2) + '\n', 'utf-8');
+  return filePath;
+}

package/src/core/project-scanner/manifests.js

@@ -0,0 +1,120 @@
+import path from 'node:path';
+import { parse as parseToml } from 'smol-toml';
+import { readFile, fileExists } from '../../utils/file.js';
+
+// Per-scan caches — cleared by resetManifestCache() at the start of each scanProject call.
+// Without this, detectors that independently call readPackageJson / readPyprojectToml would
+// each re-read and re-parse the same files (up to 7× package.json, 5× pyproject.toml per scan).
+const pkgCache = new Map();
+const pyprojectCache = new Map();
+
+export function resetManifestCache() {
+  pkgCache.clear();
+  pyprojectCache.clear();
+}
+
+export async function readPackageJson(projectRoot) {
+  if (pkgCache.has(projectRoot)) return pkgCache.get(projectRoot);
+  const filePath = path.join(projectRoot, 'package.json');
+  let result = null;
+  if (await fileExists(filePath)) {
+    try {
+      const raw = await readFile(filePath);
+      result = JSON.parse(raw.replace(/^/, ''));
+    } catch {
+      result = null;
+    }
+  }
+  pkgCache.set(projectRoot, result);
+  return result;
+}
+
+export async function readPyprojectToml(projectRoot) {
+  if (pyprojectCache.has(projectRoot)) return pyprojectCache.get(projectRoot);
+  const filePath = path.join(projectRoot, 'pyproject.toml');
+  let result = null;
+  if (await fileExists(filePath)) {
+    try {
+      const raw = await readFile(filePath);
+      result = parseToml(raw);
+    } catch {
+      result = null;
+    }
+  }
+  pyprojectCache.set(projectRoot, result);
+  return result;
+}
+
+function normalizeDepMap(input) {
+  if (!input || typeof input !== 'object') return {};
+  if (Array.isArray(input)) {
+    const out = {};
+    for (const entry of input) {
+      if (typeof entry === 'string') {
+        const match = entry.match(/^\s*([A-Za-z0-9_.\-[\]]+)/);
+        if (match) out[match[1]] = entry;
+      }
+    }
+    return out;
+  }
+  return input;
+}
+
+export function flattenPyprojectDeps(pyproject) {
+  if (!pyproject) return {};
+  const deps = {};
+  const assign = (map) => {
+    const normalized = normalizeDepMap(map);
+    for (const [k, v] of Object.entries(normalized)) {
+      // Skip Poetry's interpreter pin — `python = "^3.11"` is the runtime, not a dep.
+      if (k === 'python') continue;
+      if (!(k in deps)) deps[k] = typeof v === 'string' ? v : '';
+    }
+  };
+
+  if (pyproject.project) {
+    if (pyproject.project.dependencies) assign(pyproject.project.dependencies);
+    if (pyproject.project['optional-dependencies']) {
+      for (const group of Object.values(pyproject.project['optional-dependencies'])) {
+        assign(group);
+      }
+    }
+  }
+
+  if (pyproject.tool && pyproject.tool.poetry) {
+    if (pyproject.tool.poetry.dependencies) assign(pyproject.tool.poetry.dependencies);
+    if (pyproject.tool.poetry.group) {
+      for (const group of Object.values(pyproject.tool.poetry.group)) {
+        if (group && group.dependencies) assign(group.dependencies);
+      }
+    }
+  }
+
+  if (pyproject['dependency-groups']) {
+    for (const group of Object.values(pyproject['dependency-groups'])) {
+      assign(group);
+    }
+  }
+
+  return deps;
+}
+
+export async function getAllDeps(projectRoot) {
+  const pkg = await readPackageJson(projectRoot);
+  const pyproject = await readPyprojectToml(projectRoot);
+  const js = {};
+  if (pkg) {
+    for (const k of Object.keys(pkg.dependencies || {})) js[k] = pkg.dependencies[k];
+    for (const k of Object.keys(pkg.devDependencies || {})) js[k] = pkg.devDependencies[k];
+  }
+  const py = flattenPyprojectDeps(pyproject);
+  return { js, py, hasPackageJson: pkg !== null, hasPyproject: pyproject !== null };
+}
+
+export function depMatches(deps, pattern) {
+  if (pattern.endsWith('/*')) {
+    const prefix = pattern.slice(0, -1);
+    return Object.keys(deps).some((name) => name.startsWith(prefix));
+  }
+  return Object.prototype.hasOwnProperty.call(deps, pattern);
+}

package/src/core/remover.js

@@ -191,6 +191,7 @@ export async function cleanGitignore(projectRoot) {
     '.claude/workflow-meta.json',
     '.claude/worktrees/',
     '.claude/.stop-hook-active',
+    '.claude/cache/',
   ]);
 
   const filtered = lines.filter((line) => !REMOVE_LINES.has(line.trim()));

package/src/core/scaffolder.js

@@ -55,6 +55,7 @@ export async function updateGitignore(projectDir) {
     '.claude-backup-*/',
     '.claude/learnings/',
     '.claude/.stop-hook-active',
+    '.claude/cache/',
   ];
   const header = '# Worclaude (generated workflow files)';
 

package/src/core/setup-state.js

@@ -0,0 +1,213 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+
+export const SCHEMA_VERSION = 1;
+
+export const STATE_NAMES = [
+  'INIT',
+  'SCAN',
+  'CONFIRM_HIGH',
+  'CONFIRM_MEDIUM',
+  'INTERVIEW_STORY',
+  'INTERVIEW_ARCH',
+  'INTERVIEW_FEATURES',
+  'INTERVIEW_WORKFLOW',
+  'INTERVIEW_CONVENTIONS',
+  'INTERVIEW_VERIFICATION',
+  'WRITE',
+  'DONE',
+];
+
+export const QUESTION_IDS = [
+  'story.audience',
+  'story.problem',
+  'story.analogs',
+  'arch.classification',
+  'arch.modules',
+  'arch.entities',
+  'arch.external_apis',
+  'arch.stack_rationale',
+  'features.core',
+  'features.nice_to_have',
+  'features.non_goals',
+  'workflow.new_dev_steps',
+  'workflow.env_values',
+  'conventions.patterns',
+  'conventions.errors',
+  'conventions.logging',
+  'conventions.api_format',
+  'conventions.naming',
+  'conventions.rules',
+  'verification.manual',
+  'verification.staging',
+  'verification.required_checks',
+];
+
+// Unchecked-namespace routing: rejected high-confidence fields re-asked in the
+// state matching the field's natural section. Source of truth for
+// interviewAnswers key validation.
+export const UNCHECKED_ROUTING = {
+  readme: 'story',
+  specDocs: 'story',
+  packageManager: 'arch',
+  language: 'arch',
+  frameworks: 'arch',
+  orm: 'arch',
+  monorepo: 'arch',
+  deployment: 'arch',
+  externalApis: 'arch',
+  scripts: 'workflow',
+  envVariables: 'workflow',
+  linting: 'workflow',
+  ci: 'workflow',
+  testing: 'verification',
+};
+
+export function getStateFilePath(projectRoot) {
+  return path.join(projectRoot, '.claude', 'cache', 'setup-state.json');
+}
+
+function isUncheckedKey(key) {
+  const match = /^(story|arch|workflow|verification)\.unchecked\.([A-Za-z][A-Za-z0-9]*)$/.exec(key);
+  if (!match) return false;
+  const [, prefix, field] = match;
+  return UNCHECKED_ROUTING[field] === prefix;
+}
+
+function isKnownQuestionId(key) {
+  return QUESTION_IDS.includes(key);
+}
+
+function isKnownStateName(name) {
+  return STATE_NAMES.includes(name);
+}
+
+function validateState(state) {
+  if (!state || typeof state !== 'object' || Array.isArray(state)) {
+    throw new Error('state must be an object');
+  }
+  if (state.schemaVersion !== SCHEMA_VERSION) {
+    throw new Error(
+      `Unsupported schemaVersion: ${state.schemaVersion} (expected ${SCHEMA_VERSION})`
+    );
+  }
+  if (typeof state.startedAt !== 'string' || !state.startedAt) {
+    throw new Error('state.startedAt must be a non-empty ISO string');
+  }
+  if (typeof state.updatedAt !== 'string' || !state.updatedAt) {
+    throw new Error('state.updatedAt must be a non-empty ISO string');
+  }
+  if (!isKnownStateName(state.currentState)) {
+    throw new Error(`Unknown currentState: ${state.currentState}`);
+  }
+  if (typeof state.detectionReportPath !== 'string') {
+    throw new Error('state.detectionReportPath must be a string');
+  }
+  if (!Array.isArray(state.highConfirmedAccepted)) {
+    throw new Error('state.highConfirmedAccepted must be an array');
+  }
+  if (!Array.isArray(state.highConfirmedRejected)) {
+    throw new Error('state.highConfirmedRejected must be an array');
+  }
+  if (!state.mediumResolved || typeof state.mediumResolved !== 'object') {
+    throw new Error('state.mediumResolved must be an object');
+  }
+  for (const [k, v] of Object.entries(state.mediumResolved)) {
+    if (typeof v !== 'string') {
+      throw new Error(`state.mediumResolved.${k} must be a string`);
+    }
+  }
+  if (!state.interviewAnswers || typeof state.interviewAnswers !== 'object') {
+    throw new Error('state.interviewAnswers must be an object');
+  }
+  for (const [k, v] of Object.entries(state.interviewAnswers)) {
+    if (typeof v !== 'string') {
+      throw new Error(`state.interviewAnswers.${k} must be a string`);
+    }
+    if (!isKnownQuestionId(k) && !isUncheckedKey(k)) {
+      throw new Error(
+        `state.interviewAnswers has unknown key: ${k} (must be in QuestionId enumeration or a routed <state>.unchecked.<field> key)`
+      );
+    }
+  }
+  if (state.writeResults !== undefined) {
+    if (!state.writeResults || typeof state.writeResults !== 'object') {
+      throw new Error('state.writeResults must be an object when present');
+    }
+    for (const [k, v] of Object.entries(state.writeResults)) {
+      if (typeof v !== 'string') {
+        throw new Error(`state.writeResults.${k} must be a string`);
+      }
+    }
+  }
+}
+
+export async function loadSetupState(projectRoot) {
+  const filePath = getStateFilePath(projectRoot);
+  if (!(await fs.pathExists(filePath))) {
+    return null;
+  }
+  const raw = await fs.readFile(filePath, 'utf-8');
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Corrupt setup-state.json: ${err.message}`);
+  }
+  validateState(parsed);
+  return parsed;
+}
+
+export async function saveSetupState(projectRoot, state) {
+  const filePath = getStateFilePath(projectRoot);
+  await fs.ensureDir(path.dirname(filePath));
+
+  const merged = {
+    ...state,
+    startedAt: (await readExistingStartedAt(filePath)) || state.startedAt,
+    updatedAt: new Date().toISOString(),
+  };
+
+  validateState(merged);
+  await fs.writeFile(filePath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
+  return filePath;
+}
+
+// Preserves startedAt across re-saves so the timeline reflects when setup
+// actually began, not when the most recent mutation happened. Returns null
+// for fresh saves. Corrupt JSON is treated as "no preserved value"; other
+// I/O errors propagate so we never silently lose timeline data.
+async function readExistingStartedAt(filePath) {
+  let raw;
+  try {
+    raw = await fs.readFile(filePath, 'utf-8');
+  } catch (err) {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  }
+  try {
+    const existing = JSON.parse(raw);
+    return typeof existing.startedAt === 'string' && existing.startedAt ? existing.startedAt : null;
+  } catch (err) {
+    if (err instanceof SyntaxError) return null;
+    throw err;
+  }
+}
+
+export async function clearSetupState(projectRoot) {
+  const filePath = getStateFilePath(projectRoot);
+  await fs.remove(filePath);
+}
+
+export function isSetupStateStale(state, staleHours = 24) {
+  if (!state || typeof state.updatedAt !== 'string') {
+    throw new Error('isSetupStateStale requires a state with updatedAt');
+  }
+  const updated = Date.parse(state.updatedAt);
+  if (Number.isNaN(updated)) {
+    throw new Error(`Invalid updatedAt: ${state.updatedAt}`);
+  }
+  const ageMs = Date.now() - updated;
+  const staleMs = staleHours * 60 * 60 * 1000;
+  return ageMs >= staleMs;
+}