@lumenflow/cli 2.3.2 → 2.5.0

package/dist/wu-done.d.ts

@@ -1,225 +0,0 @@
-#!/usr/bin/env node
-/**
- * WU Done Helper
- *
- * Canonical sequence (Worktree mode - DEFAULT):
- * 1) Run gates in lane worktree (validates the change, not just main)
- * 2) Pre-flight validation: run ALL pre-commit hooks before merge (prevents partial completion)
- * 3) cd into worktree
- * 4) Auto-update WU YAML/backlog/status to Done in worktree (unless --no-auto)
- * 5) Create `.lumenflow/stamps/WU-{id}.done` in worktree
- * 6) Validate staged files against whitelist
- * 7) Commit metadata changes in worktree (on lane branch)
- * 8) cd back to main
- * 9) Merge lane branch to main with --ff-only (metadata + code merged atomically)
- * 10) Push to `main`
- * 11) Remove the associated worktree (unless --no-remove)
- * 12) Optionally delete the lane branch (with --delete-branch)
- * 13) Emit telemetry to .lumenflow/flow.log
- *
- * Canonical sequence (Branch-Only mode - LEGACY):
- * 1) Run gates on lane branch (in main checkout)
- * 2) Pre-flight validation
- * 3) Merge lane branch to main
- * 4) Update metadata on main
- * 5) Commit and push
- * 6) Delete lane branch
- *
- * Usage:
- *   pnpm wu:done --id WU-334 [--worktree worktrees/intelligence-wu-334] [--no-auto] [--no-remove] [--no-merge] [--delete-branch]
- *
- * WU-2542: This script imports utilities from @lumenflow/core package.
- * Full migration to thin shim pending @lumenflow/core CLI export implementation.
- */
-/**
- * WU-1999: Print exposure validation warnings.
- *
- * Validates exposure field and UI pairing for user-facing WUs.
- * Non-blocking - logs warnings but doesn't prevent completion.
- *
- * Checks:
- * - exposure field is present (warn if missing)
- * - If exposure=api, warns if no ui_pairing_wus specified
- * - If exposure=api, checks acceptance criteria for UI verification mention
- * - If exposure=ui, recommends user_journey field if not present
- *
- * @param {object} wu - WU YAML document
- * @param {object} options - Validation options
- * @param {boolean} [options.skipExposureCheck=false] - Skip all exposure validation
- * @returns {void}
- */
-interface ExposureOptions {
-    skipExposureCheck?: boolean;
-}
-export declare function printExposureWarnings(wu: Record<string, unknown>, options?: ExposureOptions): void;
-/**
- * WU-2022: Validate feature accessibility for UI-exposed WUs.
- *
- * BLOCKING validation - prevents wu:done if exposure=ui but feature is not accessible.
- * This prevents "orphaned code" where UI features exist but users cannot navigate to them.
- *
- * Accessibility is verified by ANY of:
- * 1. navigation_path field is specified (explicit route)
- * 2. code_paths includes a page.tsx file (Next.js page)
- * 3. tests.manual includes navigation/accessibility verification
- *
- * @param {object} wu - WU YAML document
- * @param {object} options - Validation options
- * @param {boolean} [options.skipAccessibilityCheck=false] - Skip accessibility validation
- * @returns {void} Calls die() if validation fails
- */
-interface AccessibilityOptions {
-    skipAccessibilityCheck?: boolean;
-}
-export declare function validateAccessibilityOrDie(wu: Record<string, unknown>, options?: AccessibilityOptions): void;
-/**
- * WU-1012: Validate --docs-only flag usage.
- *
- * The --docs-only flag can only be used when the WU is documentation-focused:
- * 1. exposure field is 'documentation'
- * 2. OR all code_paths are documentation paths (docs/, ai/, .claude/, *.md)
- * 3. OR type is 'documentation'
- *
- * @param {object} wu - WU YAML document
- * @param {object} args - Parsed CLI arguments
- * @param {boolean} args.docsOnly - Whether --docs-only flag was passed
- * @returns {{ valid: boolean, errors: string[] }} Validation result
- */
-interface DocsOnlyArgs {
-    docsOnly?: boolean;
-}
-export declare function validateDocsOnlyFlag(wu: Record<string, unknown>, args: DocsOnlyArgs): {
-    valid: boolean;
-    errors: string[];
-};
-/**
- * WU-1012: Build gates command with --docs-only flag support.
- *
- * Returns the appropriate gates command based on:
- * - Explicit --docs-only flag from CLI
- * - Auto-detected isDocsOnly from code_paths analysis
- *
- * @param {object} options - Build options
- * @param {boolean} options.docsOnly - Explicit --docs-only flag from CLI
- * @param {boolean} options.isDocsOnly - Auto-detected docs-only from code_paths
- * @returns {string} Gates command string
- */
-interface BuildGatesOptions {
-    docsOnly?: boolean;
-    isDocsOnly?: boolean;
-}
-export declare function buildGatesCommand(options: BuildGatesOptions): string;
-/**
- * WU-1946: Update spawn registry on WU completion.
- * Non-blocking wrapper - failures logged as warnings.
- *
- * When a WU is completed via wu:done, this function updates the spawn registry
- * to mark the spawned entry as completed (if one exists). This allows orchestrators
- * to track sub-agent spawn completion status.
- *
- * Gracefully skips if:
- * - No spawn entry found for this WU (legacy WU created before registry)
- * - Registry file doesn't exist
- * - Any error during update
- *
- * @param {string} id - WU ID being completed
- * @param {string} baseDir - Base directory containing .lumenflow/state/
- * @returns {Promise<void>}
- */
-export declare function updateSpawnRegistryOnCompletion(id: any, baseDir?: string): Promise<void>;
-/**
- * WU-1234: Normalize username for ownership comparison
- * Extracts username from email address for comparison.
- * This allows tom@hellm.ai to match 'tom' assigned_to field.
- *
- * @param {string|null|undefined} value - Email address or username
- * @returns {string} Normalized username (lowercase)
- */
-export declare function normalizeUsername(value: any): string;
-/**
- * WU-1234: Detect if branch is already merged to main
- * Checks if branch tip is an ancestor of main HEAD (i.e., already merged).
- * This prevents merge loops when code was merged via emergency fix or manual merge.
- *
- * @param {string} branch - Lane branch name
- * @returns {Promise<boolean>} True if branch is already merged to main
- */
-export declare function isBranchAlreadyMerged(branch: any): Promise<boolean>;
-export { shouldSkipWebTests as isDocsOnlyByPaths } from '@lumenflow/core/dist/path-classifiers.js';
-/**
- * WU-1234: Pre-flight check for backlog state consistency
- * Fails fast if the WU appears in both Done and In Progress sections.
- *
- * @param {string} id - WU ID to check
- * @param {string} backlogPath - Path to backlog.md
- * @returns {{ valid: boolean, error: string|null }}
- */
-export declare function checkBacklogConsistencyForWU(id: any, backlogPath: any): {
-    valid: boolean;
-    error: string;
-};
-/**
- * WU-1084: Check for uncommitted changes on main after merge completes.
- *
- * This catches cases where pnpm format (or other tooling) touched files
- * outside the WU's code_paths during worktree work. These changes survive
- * the merge and would be silently left behind when the worktree is removed.
- *
- * @param gitStatus - Output from git status (porcelain format)
- * @param wuId - The WU ID for error messaging
- * @returns Object with isDirty flag and optional error message
- */
-export declare function checkPostMergeDirtyState(gitStatus: string, wuId: string): {
-    isDirty: boolean;
-    error?: string;
-};
-export declare function emitTelemetry(event: any): void;
-/**
- * Print State HUD for visibility
- * Extracted from main() to reduce complexity (WU-1215 Phase 2 Extraction #4)
- * @param {object} params - Parameters
- * @param {string} params.id - WU ID
- * @param {object} params.docMain - Main WU YAML document
- * @param {boolean} params.isBranchOnly - Whether in branch-only mode
- * @param {boolean} params.isDocsOnly - Whether this is a docs-only WU
- * @param {string|null} params.derivedWorktree - Derived worktree path
- * @param {string} params.STAMPS_DIR - Stamps directory path
- */
-export declare function computeBranchOnlyFallback({ isBranchOnly, branchOnlyRequested, worktreeExists, derivedWorktree, }: {
-    isBranchOnly: boolean;
-    branchOnlyRequested: boolean | undefined;
-    worktreeExists: boolean;
-    derivedWorktree: string | null;
-}): {
-    allowFallback: boolean;
-    effectiveBranchOnly: boolean;
-};
-/**
- * WU-1983: Print migration deployment nudge when WU includes supabase changes.
- * Notifies agent to deploy new migrations to production via MCP tools.
- * Conditional output - only prints when migrations are in scope and new migrations exist.
- *
- * @param {string[]} codePaths - WU code_paths array
- * @param {string} baseDir - Base directory for migration discovery
- * @returns {Promise<void>}
- */
-export declare function printMigrationDeploymentNudge(codePaths: any, baseDir: any): Promise<void>;
-/**
- * WU-1763: Print discovery summary nudge when discoveries exist for this WU.
- * Conditional output - only prints when discoveryCount > 0.
- * Non-blocking, single-line output to avoid flooding the console.
- *
- * @param {string} id - WU ID being completed
- * @param {number} discoveryCount - Number of open discoveries for this WU
- * @param {string[]} discoveryIds - List of discovery IDs (limited to 5 in output)
- */
-export declare function printDiscoveryNudge(id: any, discoveryCount: any, discoveryIds: any): void;
-/**
- * WU-1763: Print documentation validation nudge when docs changed.
- * Conditional output - only prints when changedDocPaths.length > 0.
- * Non-blocking, single-line output to avoid flooding the console.
- *
- * @param {string} id - WU ID being completed
- * @param {string[]} changedDocPaths - List of documentation paths that changed
- */
-export declare function printDocValidationNudge(id: any, changedDocPaths: any): void;

package/dist/wu-edit.d.ts

@@ -1,63 +0,0 @@
-#!/usr/bin/env node
-/**
- * WU Edit Helper
- *
- * Race-safe WU spec editing using micro-worktree isolation (WU-1274).
- *
- * Enables editing WU YAML files without claiming the WU, perfect for:
- * - Filling in placeholder content after wu:create
- * - Updating description/acceptance criteria
- * - Adding code_paths, notes, or other spec fields
- *
- * Uses the same micro-worktree pattern as wu:create (WU-1262):
- * 1) Validate inputs (WU exists, status is ready)
- * 2) Ensure main is clean and up-to-date with origin
- * 3) Create temp branch WITHOUT switching (main checkout stays on main)
- * 4) Create micro-worktree in /tmp pointing to temp branch
- * 5) Apply edits in micro-worktree
- * 6) Commit, ff-only merge, push
- * 7) Cleanup temp branch and micro-worktree
- *
- * Usage:
- *   pnpm wu:edit --id WU-123 --spec-file /path/to/spec.yaml
- *   pnpm wu:edit --id WU-123 --description "New description text"
- *   pnpm wu:edit --id WU-123 --acceptance "Criterion 1" --acceptance "Criterion 2"
- *
- * Part of WU-1274: Add wu:edit command for spec-only changes
- * @see {@link tools/lib/micro-worktree.mjs} - Shared micro-worktree logic
- */
-/**
- * WU-1039: Validate which edits are allowed on done WUs
- *
- * Done WUs only allow metadata reassignment: initiative, phase, and exposure.
- * All other edits are blocked to preserve WU immutability after completion.
- *
- * @param opts - Parsed CLI options
- * @returns { valid: boolean, disallowedEdits: string[] }
- */
-export declare function validateDoneWUEdits(opts: Record<string, unknown>): {
-    valid: boolean;
-    disallowedEdits: string[];
-};
-/**
- * WU-1039: Validate exposure value against schema
- *
- * Uses WU_EXPOSURE_VALUES from core constants (Library-First, no magic strings).
- *
- * @param exposure - Exposure value to validate
- * @returns { valid: boolean, error?: string }
- */
-export declare function validateExposureValue(exposure: string): {
-    valid: boolean;
-    error?: string;
-};
-/**
- * WU-1039: Apply exposure edit to WU object
- *
- * Returns a new WU object with updated exposure (immutable pattern).
- *
- * @param wu - Original WU object
- * @param exposure - New exposure value
- * @returns Updated WU object (does not mutate original)
- */
-export declare function applyExposureEdit(wu: Record<string, unknown>, exposure: string): Record<string, unknown>;

package/dist/wu-infer-lane.d.ts

@@ -1,17 +0,0 @@
-#!/usr/bin/env node
-/**
- * WU Lane Inference CLI (WU-908)
- *
- * Suggests sub-lane for a WU based on code paths and description.
- * Wrapper around lib/lane-inference.mjs for standalone CLI usage.
- *
- * Usage:
- *   # Infer from existing WU
- *   node tools/wu-infer-lane.mjs --id WU-123
- *
- *   # Infer from manual inputs
- *   node tools/wu-infer-lane.mjs --paths "tools/**" "docs/**" --desc "Tooling improvements"
- *
- * Returns suggested lane and confidence score (0-100).
- */
-export {};

package/dist/wu-preflight.d.ts

@@ -1,47 +0,0 @@
-#!/usr/bin/env node
-/**
- * WU Preflight Validation
- *
- * WU-1803: Fast validation of code_paths and test paths before gates run.
- * Completes in under 5 seconds vs 2+ minutes for full gates.
- *
- * This catches YAML mismatches early, preventing wasted time running full
- * gates only to fail on code_paths validation at the end of wu:done.
- *
- * Usage:
- *   pnpm wu:preflight --id WU-1803          # Validate from main checkout
- *   pnpm wu:preflight --id WU-1803 --worktree worktrees/operations-gates-wu-1803
- *
- * Validates:
- *   - code_paths files exist
- *   - test file paths exist (unit, e2e, integration)
- *   - WU YAML schema is valid
- */
-/**
- * Parse command-line arguments
- * @param {string[]} argv - Process arguments
- * @returns {object} Parsed arguments
- */
-declare function parseArgs(argv: any): {
-    help: boolean;
-    error?: undefined;
-    id?: undefined;
-    worktree?: undefined;
-} | {
-    error: string;
-    help?: undefined;
-    id?: undefined;
-    worktree?: undefined;
-} | {
-    id: any;
-    worktree: any;
-    help: boolean;
-    error?: undefined;
-};
-/**
- * Detect worktree path from WU YAML or calculate from lane
- * @param {string} id - WU ID
- * @returns {string|null} Worktree path or null if not found
- */
-declare function detectWorktreePath(id: any): string;
-export { parseArgs, detectWorktreePath };

package/dist/wu-prune.d.ts

@@ -1,16 +0,0 @@
-#!/usr/bin/env node
-/**
- * WU Prune Utility
- *
- * Maintains worktree hygiene by:
- * - Running git worktree prune to clean stale metadata
- * - Validating worktree ↔ WU ↔ lane mappings
- * - Warning on orphaned worktrees (no matching WU YAML)
- * - Warning on stale worktrees (WU status is done/blocked)
- * - Warning on invalid branch naming conventions
- *
- * Usage:
- *   pnpm wu:prune          # Dry-run mode (shows what would be done)
- *   pnpm wu:prune --execute # Actually run cleanup
- */
-export {};

package/dist/wu-recover.d.ts

@@ -1,37 +0,0 @@
-#!/usr/bin/env node
-/**
- * WU Recovery Command
- *
- * WU-1090: Context-aware state machine for WU lifecycle commands
- *
- * Analyzes WU state inconsistencies and offers recovery actions:
- * - resume: Reconcile state and continue working (preserves work)
- * - reset: Discard worktree and reset WU to ready
- * - nuke: Remove all artifacts completely (requires --force)
- * - cleanup: Remove leftover worktree for done WUs
- *
- * Usage:
- *   pnpm wu:recover --id WU-123             # Analyze issues
- *   pnpm wu:recover --id WU-123 --action resume  # Apply fix
- *   pnpm wu:recover --id WU-123 --action nuke --force  # Destructive
- */
-import { type RecoveryAnalysis } from '@lumenflow/core/dist/recovery/recovery-analyzer.js';
-/**
- * Check if action requires --force flag
- */
-export declare function requiresForceFlag(action: string): boolean;
-/**
- * Validate recovery action
- */
-export declare function validateRecoveryAction(action: string): {
-    valid: boolean;
-    error?: string;
-};
-/**
- * Format recovery analysis output
- */
-export declare function formatRecoveryOutput(analysis: RecoveryAnalysis): string;
-/**
- * Get exit code for recovery command
- */
-export declare function getRecoveryExitCode(analysis: RecoveryAnalysis, actionFailed: boolean): number;

package/dist/wu-release.d.ts

@@ -1,19 +0,0 @@
-#!/usr/bin/env node
-/**
- * WU Release Command (WU-1080)
- *
- * Releases an orphaned WU from in_progress back to ready state.
- * Use when an agent is interrupted mid-WU and the WU needs to be reclaimed.
- *
- * Sequence (micro-worktree pattern):
- * 1) Validate WU is in_progress
- * 2) Create micro-worktree from main
- * 3) Append release event to state store
- * 4) Regenerate backlog.md and status.md
- * 5) Commit in micro-worktree, push directly to origin/main
- * 6) Optionally remove the work worktree
- *
- * Usage:
- *   pnpm wu:release --id WU-1080 --reason "Agent interrupted"
- */
-export {};

package/dist/wu-repair.d.ts

@@ -1,60 +0,0 @@
-#!/usr/bin/env node
-/**
- * WU State Repair Tool (Unified - WU-1826, WU-2240)
- *
- * Layer 2 defense-in-depth: detect and repair WU state inconsistencies.
- *
- * This unified tool consolidates four repair modes:
- * - Consistency mode (default): detect/repair state inconsistencies
- * - Claim mode (--claim): repair missing claim metadata in worktrees
- * - Admin mode (--admin): administrative fixes for done WUs
- * - State mode (--repair-state): repair corrupted wu-events.jsonl (WU-2240)
- *
- * Usage:
- *   # Consistency mode (default)
- *   pnpm wu:repair --id WU-123           # Repair single WU
- *   pnpm wu:repair --id WU-123 --check   # Audit only, no changes
- *   pnpm wu:repair --all                 # Batch repair all WUs
- *   pnpm wu:repair --all --check         # Audit all WUs
- *
- *   # Claim mode
- *   pnpm wu:repair --claim --id WU-123           # Repair claim metadata
- *   pnpm wu:repair --claim --id WU-123 --check   # Check only
- *   pnpm wu:repair --claim --id WU-123 --worktree /path/to/worktree
- *
- *   # Admin mode
- *   pnpm wu:repair --admin --id WU-123 --lane "Operations: Tooling"
- *   pnpm wu:repair --admin --id WU-123 --status cancelled
- *   pnpm wu:repair --admin --id WU-123 --notes "Administrative fix"
- *   pnpm wu:repair --admin --id WU-123 --initiative INIT-001
- *
- *   # State mode (WU-2240)
- *   pnpm wu:repair --repair-state                    # Repair default state file
- *   pnpm wu:repair --repair-state --path /path/to/wu-events.jsonl  # Repair specific file
- *
- * Exit codes:
- *   0: Success (no issues or all repaired)
- *   1: Issues detected (--check mode)
- *   2: Repair failed
- *
- * DEPRECATION NOTICE:
- *   - pnpm wu:repair-claim is deprecated. Use: pnpm wu:repair --claim
- *   - pnpm wu:admin-repair is deprecated. Use: pnpm wu:repair --admin
- *
- * @see {@link tools/lib/wu-repair-core.mjs} - Core repair logic
- * @see {@link tools/lib/wu-consistency-checker.mjs} - Consistency detection/repair
- * @see {@link tools/lib/wu-state-store.mjs} - State file repair (repairStateFile)
- */
-/**
- * Normalise WU ID to uppercase with WU- prefix
- * @param {string} id - Raw WU ID
- * @returns {string} Normalised WU ID
- */
-declare function normaliseWUId(id: any): any;
-/**
- * Validate WU ID format
- * @param {string} id - WU ID to validate
- * @returns {boolean} True if valid
- */
-declare function isValidWUId(id: any): boolean;
-export { normaliseWUId, isValidWUId };

package/dist/wu-spawn-completion.d.ts

@@ -1,10 +0,0 @@
-/**
- * Generate the Completion Workflow section for sub-agents (WU-2682).
- *
- * Explicitly instructs sub-agents to run wu:done autonomously after gates pass.
- * This prevents agents from asking permission instead of completing.
- *
- * @param {string} id - WU ID
- * @returns {string} Completion Workflow section
- */
-export declare function generateCompletionWorkflowSection(id: string): string;