worclaude 2.5.0 → 2.6.0

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

@@ -9,6 +9,7 @@ import {
   listFilesRecursive,
   removeDirectory,
 } from '../utils/file.js';
+import { WORKFLOW_REF_DIR } from './file-categorizer.js';
 
 /**
  * Classify .claude/ files into safe-to-delete, modified, missing, and user-owned.
@@ -55,8 +56,9 @@ export async function classifyClaudeFiles(projectRoot, meta) {
     const relKey = path.relative(claudeDir, fp).split(path.sep).join('/');
     if (allTrackedKeys.has(relKey)) continue;
 
-    // .workflow-ref.md files are upgrade artifacts — safe to delete
-    if (relKey.endsWith('.workflow-ref.md')) {
+    // Upgrade artifacts — safe to delete: anything under workflow-ref/ (new
+    // location) or the legacy `.workflow-ref.md` sibling suffix.
+    if (relKey.startsWith(`${WORKFLOW_REF_DIR}/`) || relKey.endsWith('.workflow-ref.md')) {
       safeToDelete.push(relKey);
     } else {
       userOwned.push(relKey);
@@ -115,7 +117,7 @@ export async function removeTrackedFiles(projectRoot, fileKeys) {
   }
 
   // Clean up empty subdirectories
-  for (const subdir of ['agents', 'commands', 'skills']) {
+  for (const subdir of ['agents', 'commands', 'skills', WORKFLOW_REF_DIR]) {
     const dirPath = path.join(claudeDir, subdir);
     if (await dirExists(dirPath)) {
       const remaining = await listFilesRecursive(dirPath);
@@ -189,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;
+}

package/src/index.js

@@ -10,6 +10,8 @@ import { restoreCommand } from './commands/restore.js';
 import { diffCommand } from './commands/diff.js';
 import { deleteCommand } from './commands/delete.js';
 import { doctorCommand } from './commands/doctor.js';
+import { scanCommand } from './commands/scan.js';
+import { setupStateCommand } from './commands/setup-state.js';
 
 const program = new Command();
 
@@ -62,4 +64,41 @@ program
   .option('--json', 'Output results as JSON')
   .action((options) => doctorCommand(options));
 
+program
+  .command('scan')
+  .description('Scan project for detectable facts (writes .claude/cache/detection-report.json)')
+  .option('--path <dir>', 'Project root to scan', process.cwd())
+  .option('--json', 'Print the detection report as JSON to stdout')
+  .option('--quiet', 'Suppress human-readable summary (still writes the report file)')
+  .action((options) => scanCommand(options));
+
+const setupState = program
+  .command('setup-state')
+  .description('Inspect or mutate the /setup state file (.claude/cache/setup-state.json)');
+
+setupState
+  .command('show')
+  .description('Print the state file as JSON, or "no state" if absent')
+  .option('--path <dir>', 'Project root', process.cwd())
+  .action((options) => setupStateCommand('show', options));
+
+setupState
+  .command('save')
+  .description('Read a JSON state from stdin, validate, and persist')
+  .option('--stdin', 'Read JSON from stdin (required)')
+  .option('--path <dir>', 'Project root', process.cwd())
+  .action((options) => setupStateCommand('save', options));
+
+setupState
+  .command('reset')
+  .description('Delete the state file (idempotent)')
+  .option('--path <dir>', 'Project root', process.cwd())
+  .action((options) => setupStateCommand('reset', options));
+
+setupState
+  .command('resume-info')
+  .description('Print state/age/staleness summary, or "no state" if absent')
+  .option('--path <dir>', 'Project root', process.cwd())
+  .action((options) => setupStateCommand('resume-info', options));
+
 program.parse();