@lumenflow/core 1.0.0

package/dist/orphan-detector.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Orphan Worktree Detector (WU-1476)
+ *
+ * Detects orphan directories in worktrees/ that are not tracked by git worktree.
+ * Orphan directories can occur when wu:done fails mid-workflow due to:
+ * - Backlog sync issues
+ * - Formatting errors
+ * - Typecheck failures
+ * - Recovery mode interruptions
+ *
+ * Multi-layer defense strategy:
+ * - Layer 1: Explicit cleanup in git-adapter.worktreeRemove()
+ * - Layer 2: Orphan detection in wu:prune (this module)
+ * - Layer 3: Pre-flight check in wu:claim
+ * - Layer 4: Manual utility wu:cleanup-orphans
+ *
+ * @see {@link tools/wu-prune.mjs} - Primary consumer
+ * @see {@link tools/wu-claim.mjs} - Pre-flight orphan check
+ * @see {@link tools/lib/git-adapter.mjs} - worktreeRemove with cleanup
+ */
+/**
+ * Result of orphan detection
+ * @typedef {object} OrphanDetectionResult
+ * @property {string[]} orphans - List of orphan directory paths (absolute)
+ * @property {string[]} tracked - List of tracked worktree paths (absolute)
+ * @property {string[]} errors - List of error messages encountered during detection
+ */
+/**
+ * Parsed worktree entry from git worktree list --porcelain
+ */
+interface WorktreeEntry {
+    /** Absolute path to worktree */
+    path: string;
+    /** HEAD commit SHA */
+    head?: string;
+    /** Branch name (without refs/heads/ prefix) */
+    branch?: string;
+}
+/**
+ * Parse git worktree list --porcelain output into structured entries
+ *
+ * @param {string} porcelainOutput - Output from git worktree list --porcelain
+ * @returns {WorktreeEntry[]} Parsed worktree entries
+ */
+export declare function parseWorktreeList(porcelainOutput: string): WorktreeEntry[];
+/**
+ * Get set of tracked worktree paths from git
+ *
+ * @param {string} [projectRoot] - Project root directory (defaults to cwd)
+ * @returns {Promise<Set<string>>} Set of absolute paths tracked by git worktree
+ */
+export declare function getTrackedWorktreePaths(projectRoot: any): Promise<Set<string>>;
+/**
+ * Get list of directories in worktrees/ folder
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {string[]} List of absolute paths to directories in worktrees/
+ */
+export declare function getWorktreeDirectories(projectRoot: any): string[];
+/**
+ * Detect orphan worktree directories
+ *
+ * Compares directories in worktrees/ against git worktree list to find
+ * directories that exist on disk but are not tracked by git.
+ *
+ * @param {string} [projectRoot] - Project root directory (defaults to cwd)
+ * @returns {Promise<OrphanDetectionResult>} Detection result with orphans and tracked paths
+ */
+export declare function detectOrphanWorktrees(projectRoot: any): Promise<{
+    orphans: string[];
+    tracked: any[];
+    errors: any[];
+}>;
+/**
+ * Check if a specific worktree path is an orphan
+ *
+ * Used by wu:claim for pre-flight checks before creating a worktree.
+ *
+ * @param {string} worktreePath - Absolute path to check
+ * @param {string} [projectRoot] - Project root directory (defaults to cwd)
+ * @returns {Promise<boolean>} True if the path exists but is not tracked by git
+ */
+export declare function isOrphanWorktree(worktreePath: any, projectRoot: any): Promise<boolean>;
+/**
+ * Options for removing orphan directories
+ */
+export interface RemoveOrphanDirectoryOptions {
+    /** If true, don't actually remove */
+    dryRun?: boolean;
+}
+/**
+ * Remove an orphan directory
+ *
+ * Safely removes an orphan worktree directory from disk.
+ * Only removes directories that are confirmed orphans.
+ *
+ * @param {string} orphanPath - Absolute path to orphan directory
+ * @param {RemoveOrphanDirectoryOptions} [options] - Options
+ * @returns {Promise<{removed: boolean, path: string, error?: string}>} Result
+ */
+export declare function removeOrphanDirectory(orphanPath: any, options?: RemoveOrphanDirectoryOptions): Promise<{
+    removed: boolean;
+    path: any;
+    error: string;
+    dryRun?: undefined;
+} | {
+    removed: boolean;
+    path: any;
+    dryRun: boolean;
+    error?: undefined;
+} | {
+    removed: boolean;
+    path: any;
+    error?: undefined;
+    dryRun?: undefined;
+}>;
+/**
+ * Clean up all orphan directories
+ *
+ * Detects and removes all orphan worktree directories.
+ *
+ * @param {string} [projectRoot] - Project root directory (defaults to cwd)
+ * @param {RemoveOrphanDirectoryOptions} [options] - Options
+ * @returns {Promise<{detected: number, removed: number, errors: string[]}>} Summary
+ */
+export declare function cleanupOrphanDirectories(projectRoot: any, options?: RemoveOrphanDirectoryOptions): Promise<{
+    detected: number;
+    removed: number;
+    errors: any[];
+}>;
+export {};

package/dist/orphan-detector.js

@@ -0,0 +1,226 @@
+/**
+ * Orphan Worktree Detector (WU-1476)
+ *
+ * Detects orphan directories in worktrees/ that are not tracked by git worktree.
+ * Orphan directories can occur when wu:done fails mid-workflow due to:
+ * - Backlog sync issues
+ * - Formatting errors
+ * - Typecheck failures
+ * - Recovery mode interruptions
+ *
+ * Multi-layer defense strategy:
+ * - Layer 1: Explicit cleanup in git-adapter.worktreeRemove()
+ * - Layer 2: Orphan detection in wu:prune (this module)
+ * - Layer 3: Pre-flight check in wu:claim
+ * - Layer 4: Manual utility wu:cleanup-orphans
+ *
+ * @see {@link tools/wu-prune.mjs} - Primary consumer
+ * @see {@link tools/wu-claim.mjs} - Pre-flight orphan check
+ * @see {@link tools/lib/git-adapter.mjs} - worktreeRemove with cleanup
+ */
+import { readdirSync, statSync, existsSync, rmSync } from 'node:fs';
+import path from 'node:path';
+import { getGitForCwd, createGitForPath } from './git-adapter.js';
+import { STRING_LITERALS, DEFAULTS } from './wu-constants.js';
+/**
+ * Parse git worktree list --porcelain output into structured entries
+ *
+ * @param {string} porcelainOutput - Output from git worktree list --porcelain
+ * @returns {WorktreeEntry[]} Parsed worktree entries
+ */
+export function parseWorktreeList(porcelainOutput) {
+    if (!porcelainOutput || porcelainOutput.trim() === '') {
+        return [];
+    }
+    const worktrees = [];
+    const lines = porcelainOutput.split(STRING_LITERALS.NEWLINE);
+    let current = {};
+    for (const line of lines) {
+        if (line.startsWith('worktree ')) {
+            if (current.path) {
+                worktrees.push(current);
+            }
+            current = { path: line.substring(9).trim() };
+        }
+        else if (line.startsWith('HEAD ')) {
+            current.head = line.substring(5).trim();
+        }
+        else if (line.startsWith('branch ')) {
+            const fullRef = line.substring(7).trim();
+            // Extract branch name from refs/heads/...
+            current.branch = fullRef.replace(/^refs\/heads\//, '');
+        }
+        else if (line === '') {
+            if (current.path) {
+                worktrees.push(current);
+            }
+            current = {};
+        }
+    }
+    // Handle final entry without trailing newline
+    if (current.path) {
+        worktrees.push(current);
+    }
+    return worktrees;
+}
+/**
+ * Get set of tracked worktree paths from git
+ *
+ * @param {string} [projectRoot] - Project root directory (defaults to cwd)
+ * @returns {Promise<Set<string>>} Set of absolute paths tracked by git worktree
+ */
+export async function getTrackedWorktreePaths(projectRoot) {
+    const git = projectRoot ? createGitForPath(projectRoot) : getGitForCwd();
+    const output = await git.worktreeList();
+    const entries = parseWorktreeList(output);
+    return new Set(entries.map((e) => e.path));
+}
+/**
+ * Get list of directories in worktrees/ folder
+ *
+ * @param {string} projectRoot - Absolute path to project root
+ * @returns {string[]} List of absolute paths to directories in worktrees/
+ */
+export function getWorktreeDirectories(projectRoot) {
+    const worktreesDir = path.join(projectRoot, DEFAULTS.WORKTREES_DIR);
+    if (!existsSync(worktreesDir)) {
+        return [];
+    }
+    try {
+        const entries = readdirSync(worktreesDir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => path.join(worktreesDir, entry.name));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Detect orphan worktree directories
+ *
+ * Compares directories in worktrees/ against git worktree list to find
+ * directories that exist on disk but are not tracked by git.
+ *
+ * @param {string} [projectRoot] - Project root directory (defaults to cwd)
+ * @returns {Promise<OrphanDetectionResult>} Detection result with orphans and tracked paths
+ */
+export async function detectOrphanWorktrees(projectRoot) {
+    const errors = [];
+    const root = projectRoot || process.cwd();
+    // Get paths tracked by git worktree
+    let trackedPaths;
+    try {
+        trackedPaths = await getTrackedWorktreePaths(root);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        errors.push(`Failed to get git worktree list: ${message}`);
+        return { orphans: [], tracked: [], errors };
+    }
+    // Get directories on disk
+    const diskDirectories = getWorktreeDirectories(root);
+    // Find orphans: directories that exist but aren't tracked
+    const orphans = diskDirectories.filter((dir) => !trackedPaths.has(dir));
+    return {
+        orphans,
+        tracked: [...trackedPaths],
+        errors,
+    };
+}
+/**
+ * Check if a specific worktree path is an orphan
+ *
+ * Used by wu:claim for pre-flight checks before creating a worktree.
+ *
+ * @param {string} worktreePath - Absolute path to check
+ * @param {string} [projectRoot] - Project root directory (defaults to cwd)
+ * @returns {Promise<boolean>} True if the path exists but is not tracked by git
+ */
+export async function isOrphanWorktree(worktreePath, projectRoot) {
+    // If directory doesn't exist, it's not an orphan
+    if (!existsSync(worktreePath)) {
+        return false;
+    }
+    // Check if path is in the tracked set
+    const trackedPaths = await getTrackedWorktreePaths(projectRoot);
+    return !trackedPaths.has(worktreePath);
+}
+/**
+ * Remove an orphan directory
+ *
+ * Safely removes an orphan worktree directory from disk.
+ * Only removes directories that are confirmed orphans.
+ *
+ * @param {string} orphanPath - Absolute path to orphan directory
+ * @param {RemoveOrphanDirectoryOptions} [options] - Options
+ * @returns {Promise<{removed: boolean, path: string, error?: string}>} Result
+ */
+export async function removeOrphanDirectory(orphanPath, options = {}) {
+    const { dryRun = false } = options;
+    // Verify it exists
+    if (!existsSync(orphanPath)) {
+        return { removed: false, path: orphanPath, error: 'Directory does not exist' };
+    }
+    // Verify it's a directory
+    try {
+        const stat = statSync(orphanPath);
+        if (!stat.isDirectory()) {
+            return { removed: false, path: orphanPath, error: 'Path is not a directory' };
+        }
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { removed: false, path: orphanPath, error: `Failed to stat: ${message}` };
+    }
+    // Verify it's in worktrees/ directory (safety check)
+    const basename = path.basename(path.dirname(orphanPath));
+    if (basename !== DEFAULTS.WORKTREES_DIR) {
+        return {
+            removed: false,
+            path: orphanPath,
+            error: `Safety check failed: not in ${DEFAULTS.WORKTREES_DIR}/ directory`,
+        };
+    }
+    if (dryRun) {
+        return { removed: false, path: orphanPath, dryRun: true };
+    }
+    // Remove the directory
+    try {
+        rmSync(orphanPath, { recursive: true, force: true });
+        return { removed: true, path: orphanPath };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { removed: false, path: orphanPath, error: `Failed to remove: ${message}` };
+    }
+}
+/**
+ * Clean up all orphan directories
+ *
+ * Detects and removes all orphan worktree directories.
+ *
+ * @param {string} [projectRoot] - Project root directory (defaults to cwd)
+ * @param {RemoveOrphanDirectoryOptions} [options] - Options
+ * @returns {Promise<{detected: number, removed: number, errors: string[]}>} Summary
+ */
+export async function cleanupOrphanDirectories(projectRoot, options = {}) {
+    const { dryRun = false } = options;
+    const result = await detectOrphanWorktrees(projectRoot);
+    const errors = [...result.errors];
+    let removed = 0;
+    for (const orphanPath of result.orphans) {
+        const removeResult = await removeOrphanDirectory(orphanPath, { dryRun });
+        if (removeResult.removed) {
+            removed++;
+        }
+        else if (removeResult.error) {
+            errors.push(`${orphanPath}: ${removeResult.error}`);
+        }
+    }
+    return {
+        detected: result.orphans.length,
+        removed,
+        errors,
+    };
+}

package/dist/path-classifiers.d.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * Path Classification Utilities for WU Tooling
+ *
+ * WU-1255: Classifies file paths to determine test scoping.
+ * Uses string methods (no regex) for path prefix matching.
+ *
+ * Paths that skip web app tests:
+ * - Documentation: docs/, ai/, .claude/, README*, CLAUDE*.md
+ * - Tooling: tools/, scripts/
+ *
+ * @see {@link tools/lib/wu-done-validators.mjs} - Consumer for detectDocsOnlyByPaths
+ */
+/**
+ * Prefixes for paths that should skip web app tests.
+ * These are paths for docs, tooling, and configuration that don't affect app functionality.
+ *
+ * @constant {string[]}
+ */
+export declare const SKIP_TESTS_PREFIXES: readonly string[];
+/**
+ * Root file patterns that should skip web app tests.
+ * These are files in the root directory that are documentation.
+ *
+ * @constant {string[]}
+ */
+export declare const SKIP_TESTS_ROOT_FILES: readonly string[];
+/**
+ * Check if a single file path should skip web app tests.
+ *
+ * Uses string methods for matching:
+ * - `startsWith` for directory prefixes (docs/, tools/, etc.)
+ * - `toLowerCase` for case-insensitive root file matching
+ *
+ * @param {string|null|undefined} filePath - File path to check
+ * @returns {boolean} True if path should skip web app tests
+ *
+ * @example
+ * isSkipWebTestsPath('docs/README.md') // true
+ * isSkipWebTestsPath('tools/wu-done.js') // true
+ * isSkipWebTestsPath('apps/web/src/page.tsx') // false
+ */
+export declare function isSkipWebTestsPath(filePath: any): boolean;
+/**
+ * Check if ALL code paths should skip web app tests.
+ *
+ * Returns true only if EVERY path in the array is a skip-tests path.
+ * This is the aggregate check for WU YAML code_paths array.
+ *
+ * @param {string[]|null|undefined} codePaths - Array of file paths from WU YAML
+ * @returns {boolean} True if all paths should skip web app tests
+ *
+ * @example
+ * shouldSkipWebTests(['docs/README.md', 'tools/wu-done.js']) // true
+ * shouldSkipWebTests(['docs/README.md', 'apps/web/src/page.tsx']) // false
+ */
+export declare function shouldSkipWebTests(codePaths: any): boolean;

package/dist/path-classifiers.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * Path Classification Utilities for WU Tooling
+ *
+ * WU-1255: Classifies file paths to determine test scoping.
+ * Uses string methods (no regex) for path prefix matching.
+ *
+ * Paths that skip web app tests:
+ * - Documentation: docs/, ai/, .claude/, README*, CLAUDE*.md
+ * - Tooling: tools/, scripts/
+ *
+ * @see {@link tools/lib/wu-done-validators.mjs} - Consumer for detectDocsOnlyByPaths
+ */
+/**
+ * Prefixes for paths that should skip web app tests.
+ * These are paths for docs, tooling, and configuration that don't affect app functionality.
+ *
+ * @constant {string[]}
+ */
+export const SKIP_TESTS_PREFIXES = Object.freeze([
+    'docs/',
+    'ai/',
+    '.claude/',
+    'tools/', // WU-1255: Tooling WUs
+    'scripts/', // WU-1255: Scripts WUs
+]);
+/**
+ * Root file patterns that should skip web app tests.
+ * These are files in the root directory that are documentation.
+ *
+ * @constant {string[]}
+ */
+export const SKIP_TESTS_ROOT_FILES = Object.freeze([
+    'readme', // Case-insensitive match
+    'claude', // CLAUDE.md, CLAUDE-core.md, etc.
+]);
+/**
+ * Check if a single file path should skip web app tests.
+ *
+ * Uses string methods for matching:
+ * - `startsWith` for directory prefixes (docs/, tools/, etc.)
+ * - `toLowerCase` for case-insensitive root file matching
+ *
+ * @param {string|null|undefined} filePath - File path to check
+ * @returns {boolean} True if path should skip web app tests
+ *
+ * @example
+ * isSkipWebTestsPath('docs/README.md') // true
+ * isSkipWebTestsPath('tools/wu-done.js') // true
+ * isSkipWebTestsPath('apps/web/src/page.tsx') // false
+ */
+export function isSkipWebTestsPath(filePath) {
+    if (!filePath || typeof filePath !== 'string') {
+        return false;
+    }
+    const path = filePath.trim();
+    if (path.length === 0) {
+        return false;
+    }
+    // Check directory prefixes (docs/, ai/, .claude/, tools/, scripts/)
+    for (const prefix of SKIP_TESTS_PREFIXES) {
+        if (path.startsWith(prefix)) {
+            return true;
+        }
+    }
+    // Check root file patterns (README*, CLAUDE*.md)
+    const lowerPath = path.toLowerCase();
+    for (const pattern of SKIP_TESTS_ROOT_FILES) {
+        if (lowerPath.startsWith(pattern)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check if ALL code paths should skip web app tests.
+ *
+ * Returns true only if EVERY path in the array is a skip-tests path.
+ * This is the aggregate check for WU YAML code_paths array.
+ *
+ * @param {string[]|null|undefined} codePaths - Array of file paths from WU YAML
+ * @returns {boolean} True if all paths should skip web app tests
+ *
+ * @example
+ * shouldSkipWebTests(['docs/README.md', 'tools/wu-done.js']) // true
+ * shouldSkipWebTests(['docs/README.md', 'apps/web/src/page.tsx']) // false
+ */
+export function shouldSkipWebTests(codePaths) {
+    if (!codePaths || !Array.isArray(codePaths) || codePaths.length === 0) {
+        return false;
+    }
+    return codePaths.every((path) => isSkipWebTestsPath(path));
+}

package/dist/piped-command-detector.d.ts

@@ -0,0 +1,34 @@
+/**
+ * WU-2278: Piped Command Detection
+ *
+ * Detects when pnpm dependency commands are being executed with piped input,
+ * which can bypass interactive prompts and cause security issues.
+ *
+ * Note: No external library exists for this specific shell command analysis.
+ *
+ * @module piped-command-detector
+ */
+/**
+ * Check if a command is a piped pnpm dependency command
+ *
+ * Detects patterns like:
+ * - echo "y" | pnpm add foo
+ * - yes | pnpm install
+ * - pnpm add foo < /dev/null
+ * - pnpm install <<< "y"
+ *
+ * Does NOT flag:
+ * - pnpm test | grep foo (pnpm not receiving input)
+ * - pnpm add foo (no pipe)
+ *
+ * @param {string} command - Shell command to analyze
+ * @returns {boolean} True if command is a piped pnpm dependency command
+ */
+export declare function isPipedPnpmCommand(command: any): boolean;
+/**
+ * Check if a command contains any dependency-mutating pnpm subcommand
+ *
+ * @param {string} command - Shell command to analyze
+ * @returns {boolean} True if command contains pnpm dependency mutation
+ */
+export declare function containsPnpmDependencyCommand(command: any): boolean;

package/dist/piped-command-detector.js

@@ -0,0 +1,64 @@
+/**
+ * WU-2278: Piped Command Detection
+ *
+ * Detects when pnpm dependency commands are being executed with piped input,
+ * which can bypass interactive prompts and cause security issues.
+ *
+ * Note: No external library exists for this specific shell command analysis.
+ *
+ * @module piped-command-detector
+ */
+/**
+ * List of pnpm commands that mutate dependencies
+ * @constant {string[]}
+ */
+const DEPENDENCY_COMMANDS = ['add', 'install', 'i', 'remove', 'rm', 'uninstall', 'update', 'up'];
+/**
+ * Check if a command is a piped pnpm dependency command
+ *
+ * Detects patterns like:
+ * - echo "y" | pnpm add foo
+ * - yes | pnpm install
+ * - pnpm add foo < /dev/null
+ * - pnpm install <<< "y"
+ *
+ * Does NOT flag:
+ * - pnpm test | grep foo (pnpm not receiving input)
+ * - pnpm add foo (no pipe)
+ *
+ * @param {string} command - Shell command to analyze
+ * @returns {boolean} True if command is a piped pnpm dependency command
+ */
+export function isPipedPnpmCommand(command) {
+    if (!command || typeof command !== 'string') {
+        return false;
+    }
+    // Pattern 1: Something piped TO pnpm (before pnpm in command)
+    // e.g., "echo y | pnpm add", "yes | pnpm install"
+    const pipeToPattern = /\|\s*pnpm\s+(add|install|i|remove|rm|uninstall|update|up)\b/i;
+    if (pipeToPattern.test(command)) {
+        return true;
+    }
+    // Pattern 2: Input redirection (< or <<<)
+    // e.g., "pnpm add foo < /dev/null", "pnpm install <<< y"
+    const redirectPattern = /pnpm\s+(add|install|i|remove|rm|uninstall|update|up)\b[^|]*<(?!<)/i;
+    const heredocPattern = /pnpm\s+(add|install|i|remove|rm|uninstall|update|up)\b[^|]*<<</i;
+    if (redirectPattern.test(command) || heredocPattern.test(command)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if a command contains any dependency-mutating pnpm subcommand
+ *
+ * @param {string} command - Shell command to analyze
+ * @returns {boolean} True if command contains pnpm dependency mutation
+ */
+export function containsPnpmDependencyCommand(command) {
+    if (!command || typeof command !== 'string') {
+        return false;
+    }
+    // eslint-disable-next-line security/detect-non-literal-regexp -- Pattern built from const array, not user input
+    const pattern = new RegExp(`pnpm\\s+(${DEPENDENCY_COMMANDS.join('|')})\\b`, 'i');
+    return pattern.test(command);
+}