worclaude 2.4.4 → 2.4.6

package/src/core/drift-checks.js

@@ -0,0 +1,63 @@
+import path from 'node:path';
+import fs from 'fs-extra';
+import { fileExists, readFile, writeFile } from '../utils/file.js';
+
+export const MEMORY_GUIDANCE_KEYWORDS = [
+  'memory architecture',
+  'native memory',
+  '.claude/learnings',
+  '[LEARN]',
+  '/learn',
+];
+
+export function hasClaudeMdMemoryGuidance(content) {
+  if (typeof content !== 'string' || content.length === 0) return false;
+  const lower = content.toLowerCase();
+  return MEMORY_GUIDANCE_KEYWORDS.some((kw) => lower.includes(kw.toLowerCase()));
+}
+
+export async function ensureLearningsDir(projectRoot) {
+  const dir = path.join(projectRoot, '.claude', 'learnings');
+  const gitkeep = path.join(dir, '.gitkeep');
+  if (await fs.pathExists(gitkeep)) return false;
+  await fs.ensureDir(dir);
+  await writeFile(gitkeep, '');
+  return true;
+}
+
+export function buildMemoryGuidanceSidecar() {
+  const preamble = [
+    '# CLAUDE.md — Memory Architecture Suggestion',
+    '',
+    'Your CLAUDE.md does not reference the workflow memory architecture. Auto-learnings may',
+    'pollute the main file. Paste the snippet below into CLAUDE.md (near the top, under an',
+    'existing "Conventions" or "Session Protocol" section), then delete this sidecar file.',
+    '',
+    '---',
+    '',
+    '## Memory Architecture',
+    '',
+    '- Auto-memory: `.claude/learnings/` (captured by hooks; reviewed via `/learn`).',
+    '- CLAUDE.md stays lean — it is shared with teammates. Long-form notes belong in',
+    '  `docs/memory/` or the learnings directory.',
+    '- The `[LEARN]` marker in tool output flags moments worth capturing.',
+    '',
+  ];
+  return preamble.join('\n');
+}
+
+export async function writeMemoryGuidanceSidecar(projectRoot) {
+  const dest = path.join(projectRoot, 'CLAUDE.md.workflow-ref.md');
+  await writeFile(dest, buildMemoryGuidanceSidecar());
+  return dest;
+}
+
+export async function readClaudeMd(projectRoot) {
+  const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
+  if (!(await fileExists(claudeMdPath))) return null;
+  try {
+    return await readFile(claudeMdPath);
+  } catch {
+    return null;
+  }
+}

package/src/core/file-categorizer.js

@@ -1,6 +1,7 @@
 import path from 'node:path';
+import fs from 'fs-extra';
 import { hashContent, hashFile } from '../utils/hash.js';
-import { readTemplate } from './scaffolder.js';
+import { readTemplate, getTemplatesDir } from './scaffolder.js';
 import { fileExists, listFilesRecursive } from '../utils/file.js';
 import {
   UNIVERSAL_AGENTS,
@@ -10,6 +11,40 @@ import {
   TEMPLATE_SKILLS,
 } from '../data/agents.js';
 
+const ALWAYS_SCAFFOLDED_TYPES = new Set([
+  'universal-agent',
+  'command',
+  'universal-skill',
+  'hook',
+  'root-file',
+]);
+
+/**
+ * Predicate: is this template entry one that should be restored when missing on disk?
+ * - universal-agent, command, universal-skill, hook, root-file: always scaffolded
+ * - optional-agent: only if the agent name is in meta.optionalAgents
+ * - template-skill: excluded (needs variable substitution; stored hash won't match)
+ */
+export function isAlwaysScaffolded(entry, meta) {
+  if (!entry) return false;
+  if (ALWAYS_SCAFFOLDED_TYPES.has(entry.type)) return true;
+  if (entry.type === 'optional-agent') {
+    const agentName = entry.agentName;
+    return Boolean(agentName && meta?.optionalAgents?.includes(agentName));
+  }
+  return false;
+}
+
+export const ROOT_KEY_PREFIX = 'root/';
+
+export function resolveKeyPath(key, projectRoot) {
+  if (key.startsWith(ROOT_KEY_PREFIX)) {
+    const rel = key.slice(ROOT_KEY_PREFIX.length);
+    return path.join(projectRoot, ...rel.split('/'));
+  }
+  return path.join(projectRoot, '.claude', ...key.split('/'));
+}
+
 /**
  * Build a map of all workflow template files to their hash keys, template paths, and hashes.
  * Hash keys match the format stored in workflow-meta.json (relative to .claude/).
@@ -30,7 +65,12 @@ export async function buildTemplateHashMap() {
     const key = `agents/${name}.md`;
     const templatePath = `agents/optional/${info.category}/${name}.md`;
     const content = await readTemplate(templatePath);
-    map[key] = { templatePath, hash: hashContent(content), type: 'optional-agent' };
+    map[key] = {
+      templatePath,
+      hash: hashContent(content),
+      type: 'optional-agent',
+      agentName: name,
+    };
   }
 
   // Commands: key = commands/{name}.md, templatePath = commands/{name}.md
@@ -58,6 +98,34 @@ export async function buildTemplateHashMap() {
     map[key] = { templatePath, hash: hashContent(content), type: 'template-skill' };
   }
 
+  // Hook scripts: walked from templates/hooks/ so new hooks flow through automatically.
+  // Key = hooks/{name}, templatePath = hooks/{name}
+  const hooksDir = path.join(getTemplatesDir(), 'hooks');
+  if (await fs.pathExists(hooksDir)) {
+    const entries = await fs.readdir(hooksDir);
+    for (const entry of entries) {
+      if (!entry.endsWith('.cjs') && !entry.endsWith('.js')) continue;
+      const key = `hooks/${entry}`;
+      const templatePath = `hooks/${entry}`;
+      const content = await readTemplate(templatePath);
+      map[key] = { templatePath, hash: hashContent(content), type: 'hook' };
+    }
+  }
+
+  // Root-level files: key = root/<path>, templatePath points into templates/
+  // AGENTS.md needs variable substitution at scaffold time; the raw-template hash
+  // is used only to detect drift against a previously-substituted install hash,
+  // and a mismatch routes us down the user-modified path (no false overwrite).
+  {
+    const templatePath = 'core/agents-md.md';
+    const content = await readTemplate(templatePath);
+    map['root/AGENTS.md'] = {
+      templatePath,
+      hash: hashContent(content),
+      type: 'root-file',
+    };
+  }
+
   return map;
 }
 
@@ -74,7 +142,8 @@ export async function categorizeFiles(projectRoot, meta) {
     conflict: [],
     newFiles: [],
     unchanged: [],
-    deleted: [],
+    missingExpected: [],
+    missingUntracked: [],
     userAdded: [],
     modified: [],
     outdated: [],
@@ -83,14 +152,31 @@ export async function categorizeFiles(projectRoot, meta) {
   // Track which keys we've processed
   const processedKeys = new Set();
 
+  // Shared routing for files whose outdated-detection step is skipped (no
+  // template entry, or template has variable placeholders we can't hash
+  // against). Classification reduces to "did the user touch it?"
+  const recordByUserModification = (key, userModified) => {
+    if (userModified) result.modified.push({ key });
+    else result.unchanged.push({ key });
+  };
+
   // 1. Process each file in stored hashes
   for (const [key, storedHash] of Object.entries(storedHashes)) {
     processedKeys.add(key);
-    const filePath = path.join(claudeDir, ...key.split('/'));
+    const filePath = resolveKeyPath(key, projectRoot);
 
     // Check if file still exists on disk
     if (!(await fileExists(filePath))) {
-      result.deleted.push({ key });
+      const templateEntry = templateMap[key];
+      if (isAlwaysScaffolded(templateEntry, meta)) {
+        result.missingExpected.push({
+          key,
+          templatePath: templateEntry.templatePath,
+          type: templateEntry.type,
+        });
+      } else {
+        result.missingUntracked.push({ key });
+      }
       continue;
     }
 
@@ -102,22 +188,17 @@ export async function categorizeFiles(projectRoot, meta) {
     const templateEntry = templateMap[key];
 
     if (!templateEntry) {
-      // File is in stored hashes but not in template map — treat as tracked file
-      if (userModified) {
-        result.modified.push({ key });
-      } else {
-        result.unchanged.push({ key });
-      }
+      // File is in stored hashes but not in template map — treat as tracked file.
+      recordByUserModification(key, userModified);
       continue;
     }
 
-    // Skip template skills from outdated detection (raw vs substituted hash mismatch)
-    if (templateEntry.type === 'template-skill') {
-      if (userModified) {
-        result.modified.push({ key });
-      } else {
-        result.unchanged.push({ key });
-      }
+    // Skip template skills and root-files from outdated detection —
+    // both contain {variable} placeholders, so raw-template hash won't
+    // match the installed (substituted) hash. Restoration paths still
+    // catch them when missing; we just can't auto-update them here.
+    if (templateEntry.type === 'template-skill' || templateEntry.type === 'root-file') {
+      recordByUserModification(key, userModified);
       continue;
     }
 
@@ -125,11 +206,7 @@ export async function categorizeFiles(projectRoot, meta) {
 
     if (!templateChanged) {
       // Template unchanged — only report user modifications
-      if (userModified) {
-        result.modified.push({ key });
-      } else {
-        result.unchanged.push({ key });
-      }
+      recordByUserModification(key, userModified);
     } else {
       // Template was updated in new version
       result.outdated.push({ key, templatePath: templateEntry.templatePath });
@@ -141,22 +218,13 @@ export async function categorizeFiles(projectRoot, meta) {
     }
   }
 
-  // 2. Find new files (in template map but not in stored hashes)
+  // 2. Find new files (in template map but not in stored hashes).
+  // Gate is the same predicate used for missingExpected: always-scaffolded types,
+  // selected optional agents only, template skills excluded (need substitution).
   for (const [key, entry] of Object.entries(templateMap)) {
     if (processedKeys.has(key)) continue;
-
-    // Skip optional agents the user didn't select
-    if (entry.type === 'optional-agent') {
-      const agentName = key.replace('agents/', '').replace('.md', '');
-      if (!meta.optionalAgents?.includes(agentName)) {
-        continue;
-      }
-    }
-
-    // Skip template skills (would need variable substitution)
-    if (entry.type === 'template-skill') continue;
-
-    result.newFiles.push({ key, templatePath: entry.templatePath });
+    if (!isAlwaysScaffolded(entry, meta)) continue;
+    result.newFiles.push({ key, templatePath: entry.templatePath, type: entry.type });
   }
 
   // 3. Find user-added files (on disk but not in stored hashes or template map)

package/src/core/variables.js

@@ -0,0 +1,196 @@
+import path from 'node:path';
+import { readFile, fileExists } from '../utils/file.js';
+import { TECH_STACKS } from '../data/agents.js';
+
+export const LANGUAGE_COMMANDS = {
+  python: {
+    heading: 'Python',
+    commands: [
+      'python -m pytest                # Run tests',
+      'ruff check .                    # Lint',
+      'ruff format .                   # Format',
+    ],
+  },
+  node: {
+    heading: 'Node.js / TypeScript',
+    commands: [
+      'npm test                        # Run tests',
+      'npx eslint .                    # Lint',
+      'npx prettier --write .          # Format',
+    ],
+  },
+  java: {
+    heading: 'Java',
+    commands: [
+      'mvn test                        # Run tests',
+      'mvn checkstyle:check            # Lint',
+      'mvn spotless:apply              # Format',
+    ],
+  },
+  csharp: {
+    heading: 'C# / .NET',
+    commands: [
+      'dotnet test                     # Run tests',
+      'dotnet format --verify-no-changes # Lint',
+      'dotnet format                   # Format',
+    ],
+  },
+  cpp: {
+    heading: 'C / C++',
+    commands: [
+      'cmake --build build && ctest    # Build & test',
+      'clang-tidy src/*.cpp            # Lint',
+      'clang-format -i src/*.[ch]pp    # Format',
+    ],
+  },
+  go: {
+    heading: 'Go',
+    commands: [
+      'go test ./...                   # Run tests',
+      'golangci-lint run               # Lint',
+      'gofmt -w .                      # Format',
+    ],
+  },
+  php: {
+    heading: 'PHP',
+    commands: [
+      'vendor/bin/phpunit              # Run tests',
+      'vendor/bin/phpstan analyse      # Lint',
+      'vendor/bin/php-cs-fixer fix .   # Format',
+    ],
+  },
+  ruby: {
+    heading: 'Ruby',
+    commands: [
+      'bundle exec rspec               # Run tests',
+      'rubocop                         # Lint',
+      'rubocop -A                      # Format',
+    ],
+  },
+  kotlin: {
+    heading: 'Kotlin',
+    commands: [
+      'gradle test                     # Run tests',
+      'detekt                          # Lint',
+      'ktlint -F                       # Format',
+    ],
+  },
+  swift: {
+    heading: 'Swift',
+    commands: [
+      'swift test                      # Run tests',
+      'swiftlint                       # Lint',
+      'swift-format format -r . -i     # Format',
+    ],
+  },
+  rust: {
+    heading: 'Rust',
+    commands: [
+      'cargo test                      # Run tests',
+      'cargo clippy                    # Lint',
+      'cargo fmt                       # Format',
+    ],
+  },
+  dart: {
+    heading: 'Dart / Flutter',
+    commands: [
+      'dart test                       # Run tests',
+      'dart analyze                    # Lint',
+      'dart format .                   # Format',
+    ],
+  },
+  scala: {
+    heading: 'Scala',
+    commands: [
+      'sbt test                        # Run tests',
+      'sbt scalafix                    # Lint',
+      'scalafmt                        # Format',
+    ],
+  },
+  elixir: {
+    heading: 'Elixir',
+    commands: [
+      'mix test                        # Run tests',
+      'mix credo                       # Lint',
+      'mix format                      # Format',
+    ],
+  },
+  zig: {
+    heading: 'Zig',
+    commands: [
+      'zig build test                  # Run tests',
+      'zig build                       # Build (lint via compiler)',
+      'zig fmt .                       # Format',
+    ],
+  },
+};
+
+export function buildCommandsBlock(languages, useDocker) {
+  const lines = ['```bash'];
+  for (const lang of languages) {
+    const entry = LANGUAGE_COMMANDS[lang];
+    if (!entry) continue;
+    if (lines.length > 1) lines.push('');
+    lines.push(`# ${entry.heading}`);
+    lines.push(...entry.commands);
+  }
+  if (useDocker) {
+    if (lines.length > 1) lines.push('');
+    lines.push('# Docker');
+    lines.push('docker compose up -d            # Start services');
+    lines.push('docker compose down             # Stop services');
+  }
+  if (lines.length === 1) {
+    lines.push('# Add your project-specific commands here');
+  }
+  lines.push('```');
+  return lines.join('\n');
+}
+
+function buildTechStackText(languages, useDocker) {
+  const lines = languages
+    .filter((l) => l !== 'other')
+    .map((l) => {
+      const entry = TECH_STACKS.find((s) => s.value === l);
+      return `- ${entry ? entry.name : l}`;
+    });
+  if (languages.includes('other') && lines.length === 0) {
+    lines.push('- Not specified');
+  }
+  if (useDocker) lines.push('- Docker');
+  return lines.join('\n');
+}
+
+async function readPackageJsonFields(projectRoot) {
+  const pkgPath = path.join(projectRoot, 'package.json');
+  if (!(await fileExists(pkgPath))) return {};
+  try {
+    const content = await readFile(pkgPath);
+    const pkg = JSON.parse(content);
+    return { name: pkg.name, description: pkg.description };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Reconstruct template variables from workflow-meta.json for repair flows.
+ * Best-effort: pulls projectName/description from package.json, tech stack
+ * from meta.techStack, commands block from meta.techStack + meta.useDocker.
+ */
+export async function buildAgentsMdVariables(meta, projectRoot) {
+  const languages = meta.techStack || [];
+  const useDocker = meta.useDocker || false;
+  const pkg = await readPackageJsonFields(projectRoot);
+  const projectName = pkg.name || path.basename(projectRoot);
+  const description = pkg.description || 'A project scaffolded with Worclaude';
+  const techStackText = buildTechStackText(languages, useDocker);
+  const commandsText = buildCommandsBlock(languages, useDocker);
+  return {
+    project_name: projectName,
+    description,
+    tech_stack_filled_during_init: techStackText,
+    commands_filled_during_init: commandsText,
+    timestamp: new Date().toISOString(),
+  };
+}

package/src/index.js

@@ -29,7 +29,10 @@ program
 program
   .command('upgrade')
   .description('Update workflow components to the latest version')
-  .action(upgradeCommand);
+  .option('--dry-run', 'Preview changes without writing')
+  .option('--yes', 'Skip confirmation prompts')
+  .option('--repair-only', 'Restore missing files without applying template updates')
+  .action((options) => upgradeCommand(options));
 
 program
   .command('status')