@lumenflow/cli 1.0.0

package/dist/wu-deps.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * WU Dependency Visualization (WU-1247)
+ *
+ * Shows dependency graph for a WU in ASCII or Mermaid format.
+ *
+ * Usage:
+ *   pnpm wu:deps WU-1247                    # ASCII format
+ *   pnpm wu:deps WU-1247 --format mermaid   # Mermaid diagram
+ *   pnpm wu:deps WU-1247 --depth 5          # Deeper traversal
+ *   pnpm wu:deps WU-1247 --direction up     # Only upstream deps
+ */
+import { createWUParser, WU_OPTIONS } from '@lumenflow/core/dist/arg-parser.js';
+import { die } from '@lumenflow/core/dist/error-handler.js';
+import { buildDependencyGraph, renderASCII, renderMermaid, validateGraph, } from '@lumenflow/core/dist/dependency-graph.js';
+import { OUTPUT_FORMATS } from '@lumenflow/initiatives/dist/initiative-constants.js';
+import { PATTERNS } from '@lumenflow/core/dist/wu-constants.js';
+async function main() {
+    const args = createWUParser({
+        name: 'wu-deps',
+        description: 'Visualize WU dependency graph',
+        options: [WU_OPTIONS.id, WU_OPTIONS.format, WU_OPTIONS.depth, WU_OPTIONS.direction],
+        required: [],
+        allowPositionalId: true,
+    });
+    const wuId = args.id;
+    if (!wuId) {
+        die('WU ID is required.\n\nUsage: pnpm wu:deps WU-1247');
+    }
+    if (!PATTERNS.WU_ID.test(wuId)) {
+        die(`Invalid WU ID format: "${wuId}"\n\nExpected format: WU-<number> (e.g., WU-1247)`);
+    }
+    console.log(`[wu:deps] Building dependency graph...`);
+    const graph = buildDependencyGraph();
+    if (!graph.has(wuId)) {
+        die(`WU not found in graph: ${wuId}\n\nEnsure the WU exists in docs/04-operations/tasks/wu/`);
+    }
+    const format = args.format || OUTPUT_FORMATS.ASCII;
+    const depth = args.depth ? parseInt(args.depth, 10) : 3;
+    const direction = args.direction || 'both';
+    // Validate direction
+    if (!['up', 'down', 'both'].includes(direction)) {
+        die(`Invalid direction: "${direction}"\n\nValid options: up, down, both`);
+    }
+    let output;
+    switch (format) {
+        case OUTPUT_FORMATS.MERMAID:
+            output = renderMermaid(graph, { rootId: wuId, direction: 'TD', depth });
+            break;
+        case OUTPUT_FORMATS.JSON:
+            output = renderGraphJSON(graph, wuId, depth, direction);
+            break;
+        case OUTPUT_FORMATS.ASCII:
+        default:
+            output = renderASCII(graph, wuId, { direction, depth });
+            break;
+    }
+    console.log('');
+    console.log(output);
+    // Validate and warn about issues
+    const validation = validateGraph(graph);
+    if (validation.hasCycle) {
+        console.log('\n⚠️  Warning: Circular dependencies detected in graph!');
+        console.log('Run with --validate for full validation report.');
+    }
+}
+function renderGraphJSON(graph, rootId, depth, direction) {
+    const node = graph.get(rootId);
+    if (!node)
+        return JSON.stringify({ error: 'WU not found' }, null, 2);
+    const visited = new Set();
+    const collectDeps = (id, currentDepth, isUpstream) => {
+        if (currentDepth > depth || visited.has(id))
+            return null;
+        visited.add(id);
+        const n = graph.get(id);
+        if (!n)
+            return { id, status: 'unknown', deps: [] };
+        const deps = isUpstream ? n.blockedBy : n.blocks;
+        return {
+            id,
+            title: n.title,
+            status: n.status,
+            deps: deps
+                .filter((d) => graph.has(d))
+                .map((d) => collectDeps(d, currentDepth + 1, isUpstream))
+                .filter(Boolean),
+        };
+    };
+    const output = {
+        root: {
+            id: node.id,
+            title: node.title,
+            status: node.status,
+        },
+    };
+    visited.clear();
+    if (direction === 'up' || direction === 'both') {
+        visited.add(rootId);
+        output.upstream = node.blockedBy
+            .filter((d) => graph.has(d))
+            .map((d) => collectDeps(d, 1, true))
+            .filter(Boolean);
+    }
+    visited.clear();
+    if (direction === 'down' || direction === 'both') {
+        visited.add(rootId);
+        output.downstream = node.blocks
+            .filter((d) => graph.has(d))
+            .map((d) => collectDeps(d, 1, false))
+            .filter(Boolean);
+    }
+    return JSON.stringify(output, null, 2);
+}
+// Guard main() for testability (WU-1366)
+import { fileURLToPath } from 'node:url';
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    main();
+}

package/dist/wu-deps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-deps.js","sourceRoot":"","sources":["../src/wu-deps.ts"],"names":[],"mappings":"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"}

package/dist/wu-done.d.ts

@@ -0,0 +1,153 @@
+#!/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 `.beacon/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 .beacon/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-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 .beacon/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;
+};
+export declare function emitTelemetry(event: any): void;
+/**
+ * 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-done.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wu-done.d.ts","sourceRoot":"","sources":["../src/wu-done.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAmLH;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,KAAA,EAAE,OAAO,KAAK,QAerD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,0BAA0B,CAAC,EAAE,KAAA,EAAE,OAAO,KAAK,QAgB1D;AAgID;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,+BAA+B,CAAC,EAAE,KAAA,EAAE,OAAO,SAAgB,iBA0BhF;AASD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,KAAA,UAQtC;AAED;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,KAAA,oBA0BjD;AAKD,OAAO,EAAE,kBAAkB,IAAI,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAElG;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,EAAE,KAAA,EAAE,WAAW,KAAA;;;EA+B3D;AAiVD,wBAAgB,aAAa,CAAC,KAAK,KAAA,QAMlC;AA67CD;;;;;;;;GAQG;AACH,wBAAsB,6BAA6B,CAAC,SAAS,KAAA,EAAE,OAAO,KAAA,iBA4BrE;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,EAAE,KAAA,EAAE,cAAc,KAAA,EAAE,YAAY,KAAA,QASnE;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,EAAE,KAAA,EAAE,eAAe,KAAA,QAK1D"}