@lumenflow/core 1.3.0 → 1.3.2

package/dist/wu-done-docs-generate.d.ts

@@ -0,0 +1,73 @@
+/**
+ * @file wu-done-docs-generate.ts
+ * @description Documentation regeneration utilities for wu:done
+ *
+ * WU-1061: Integrate docs:generate into wu:done for @lumenflow/* changes
+ *
+ * Detects changes to files that affect generated documentation and triggers
+ * regeneration during wu:done (after gates pass, before metadata commit).
+ */
+/**
+ * Pathspecs for files that affect generated documentation.
+ * When any of these files change, docs:generate should be run.
+ *
+ * Based on .husky/hooks/docs-sync.mjs patterns, expanded to match
+ * all files that can affect CLI/config documentation.
+ */
+export declare const DOC_SOURCE_PATHSPECS: readonly ["tools/generate-cli-docs.ts", "packages/@lumenflow/core/src/arg-parser.ts", "packages/@lumenflow/core/src/lumenflow-config-schema.ts", "packages/@lumenflow/core/src/index.ts", "packages/@lumenflow/cli/package.json", "packages/@lumenflow/cli/src/"];
+/**
+ * Output files generated by docs:generate.
+ * These files are staged before the metadata commit.
+ */
+export declare const DOC_OUTPUT_FILES: readonly ["apps/docs/src/content/docs/reference/cli.mdx", "apps/docs/src/content/docs/reference/config.mdx"];
+/**
+ * Check if any doc-source files changed compared to the base branch.
+ * Uses git diff with pathspecs for efficient detection.
+ *
+ * @param baseBranch - Base branch for comparison (e.g., 'main', 'origin/main')
+ * @returns Promise<boolean> - True if doc-source files changed
+ */
+export declare function hasDocSourceChanges(baseBranch: string): Promise<boolean>;
+/**
+ * Stage doc output files for the metadata commit.
+ *
+ * @returns Promise<void>
+ */
+export declare function stageDocOutputs(): Promise<void>;
+/**
+ * Run turbo docs:generate to regenerate documentation.
+ * Turbo handles build dependencies and caching.
+ *
+ * @param repoRoot - Repository root directory
+ * @returns void
+ */
+export declare function runDocsGenerate(repoRoot: string): void;
+/**
+ * Result of the docs regeneration check.
+ */
+export interface DocsRegenerationResult {
+    /** Whether doc-source files changed */
+    docsChanged: boolean;
+    /** Whether docs were regenerated */
+    regenerated: boolean;
+}
+/**
+ * Options for maybeRegenerateAndStageDocs.
+ */
+export interface MaybeRegenerateDocsOptions {
+    /** Base branch for comparison (e.g., 'main', calculated from defaultBranchFrom) */
+    baseBranch: string;
+    /** Repository root directory for running turbo */
+    repoRoot: string;
+}
+/**
+ * Detect doc-source changes and regenerate docs if needed.
+ * This is the main integration point for wu:done.
+ *
+ * Call this BEFORE stageAndFormatMetadata() to include doc outputs
+ * in the single atomic commit.
+ *
+ * @param options - Detection and regeneration options
+ * @returns Promise<DocsRegenerationResult> - Whether docs changed and were regenerated
+ */
+export declare function maybeRegenerateAndStageDocs(options: MaybeRegenerateDocsOptions): Promise<DocsRegenerationResult>;

package/dist/wu-done-docs-generate.js

@@ -0,0 +1,108 @@
+/**
+ * @file wu-done-docs-generate.ts
+ * @description Documentation regeneration utilities for wu:done
+ *
+ * WU-1061: Integrate docs:generate into wu:done for @lumenflow/* changes
+ *
+ * Detects changes to files that affect generated documentation and triggers
+ * regeneration during wu:done (after gates pass, before metadata commit).
+ */
+import { execSync } from 'node:child_process';
+import { getGitForCwd } from './git-adapter.js';
+import { STDIO } from './wu-constants.js';
+/**
+ * Pathspecs for files that affect generated documentation.
+ * When any of these files change, docs:generate should be run.
+ *
+ * Based on .husky/hooks/docs-sync.mjs patterns, expanded to match
+ * all files that can affect CLI/config documentation.
+ */
+export const DOC_SOURCE_PATHSPECS = [
+    'tools/generate-cli-docs.ts',
+    'packages/@lumenflow/core/src/arg-parser.ts',
+    'packages/@lumenflow/core/src/lumenflow-config-schema.ts',
+    'packages/@lumenflow/core/src/index.ts',
+    'packages/@lumenflow/cli/package.json',
+    'packages/@lumenflow/cli/src/',
+];
+/**
+ * Output files generated by docs:generate.
+ * These files are staged before the metadata commit.
+ */
+export const DOC_OUTPUT_FILES = [
+    'apps/docs/src/content/docs/reference/cli.mdx',
+    'apps/docs/src/content/docs/reference/config.mdx',
+];
+/**
+ * Check if any doc-source files changed compared to the base branch.
+ * Uses git diff with pathspecs for efficient detection.
+ *
+ * @param baseBranch - Base branch for comparison (e.g., 'main', 'origin/main')
+ * @returns Promise<boolean> - True if doc-source files changed
+ */
+export async function hasDocSourceChanges(baseBranch) {
+    try {
+        const gitAdapter = getGitForCwd();
+        const diff = await gitAdapter.raw([
+            'diff',
+            `${baseBranch}...HEAD`,
+            '--name-only',
+            '--',
+            ...DOC_SOURCE_PATHSPECS,
+        ]);
+        return diff.trim().length > 0;
+    }
+    catch {
+        // Fail-safe: don't regenerate on git errors
+        return false;
+    }
+}
+/**
+ * Stage doc output files for the metadata commit.
+ *
+ * @returns Promise<void>
+ */
+export async function stageDocOutputs() {
+    const gitAdapter = getGitForCwd();
+    await gitAdapter.add([...DOC_OUTPUT_FILES]);
+}
+/**
+ * Run turbo docs:generate to regenerate documentation.
+ * Turbo handles build dependencies and caching.
+ *
+ * @param repoRoot - Repository root directory
+ * @returns void
+ */
+export function runDocsGenerate(repoRoot) {
+    execSync('pnpm turbo docs:generate', {
+        cwd: repoRoot,
+        stdio: STDIO.INHERIT,
+        encoding: 'utf-8',
+    });
+}
+/**
+ * Detect doc-source changes and regenerate docs if needed.
+ * This is the main integration point for wu:done.
+ *
+ * Call this BEFORE stageAndFormatMetadata() to include doc outputs
+ * in the single atomic commit.
+ *
+ * @param options - Detection and regeneration options
+ * @returns Promise<DocsRegenerationResult> - Whether docs changed and were regenerated
+ */
+export async function maybeRegenerateAndStageDocs(options) {
+    const { baseBranch, repoRoot } = options;
+    // Check if doc-source files changed
+    const docsChanged = await hasDocSourceChanges(baseBranch);
+    if (!docsChanged) {
+        console.log('[wu:done] No doc-source changes detected, skipping docs:generate');
+        return { docsChanged: false, regenerated: false };
+    }
+    console.log('[wu:done] Doc-source changes detected, running turbo docs:generate...');
+    // Run turbo docs:generate (Turbo handles caching and dependencies)
+    runDocsGenerate(repoRoot);
+    // Stage the doc output files
+    await stageDocOutputs();
+    console.log('[wu:done] Documentation regenerated and staged');
+    return { docsChanged: true, regenerated: true };
+}

package/dist/wu-done-worktree.js

@@ -36,6 +36,8 @@ import { isPRModeEnabled, createPR, printPRCreatedMessage } from './wu-done-pr.j
 import { isBranchAlreadyMerged } from './wu-done-branch-utils.js';
 // WU-1371: Import rebase artifact cleanup functions
 import { detectRebasedArtifacts, cleanupRebasedArtifacts } from './rebase-artifact-cleanup.js';
+// WU-1061: Import docs regeneration utilities
+import { maybeRegenerateAndStageDocs } from './wu-done-docs-generate.js';
 import { WUTransaction, createTransactionSnapshot, restoreFromSnapshot } from './wu-transaction.js';
 // WU-1506: Import backlog invariant repair
 // WU-1574: Removed repairBacklogInvariants - no longer needed with state store architecture
@@ -261,6 +263,16 @@ export async function executeWorktreeCompletion(context) {
         // PHASE 4: GIT OPERATIONS (stage, format, commit)
         // Files are now written - proceed with git operations
         // ======================================================================
+        // ======================================================================
+        // WU-1061: Regenerate docs if doc-source files changed
+        // This runs BEFORE stageAndFormatMetadata to include doc outputs
+        // in the single atomic commit
+        // Uses main as base to detect changes introduced by this WU
+        // ======================================================================
+        await maybeRegenerateAndStageDocs({
+            baseBranch: BRANCHES.MAIN,
+            repoRoot: worktreePath,
+        });
         // Stage and format files
         await stageAndFormatMetadata({
             id,

package/dist/wu-schema.js

@@ -826,10 +826,12 @@ export function validateWUCompleteness(wu) {
         warnings.push(`${wu.id}: Missing 'tests.manual' field. Add manual verification steps for acceptance criteria.`);
     }
     // Check for spec_refs (features should link to plans/specs)
+    // WU-1062: Accepts both repo-relative paths (docs/04-operations/plans/) and
+    // external paths (~/.lumenflow/plans/, $LUMENFLOW_HOME/plans/, lumenflow://plans/)
     if (type === 'feature') {
         const hasSpecRefs = wu.spec_refs && wu.spec_refs.length > 0;
         if (!hasSpecRefs) {
-            warnings.push(`${wu.id}: Missing 'spec_refs' field. Link to plan file in docs/04-operations/plans/ for traceability.`);
+            warnings.push(`${wu.id}: Missing 'spec_refs' field. Link to plan file (docs/04-operations/plans/, lumenflow://plans/, or ~/.lumenflow/plans/) for traceability.`);
         }
     }
     return { warnings };

package/dist/wu-spawn.js

@@ -89,6 +89,9 @@ function formatAcceptance(acceptance) {
 /**
  * Format spec_refs as markdown links
  *
+ * WU-1062: Handles external paths (lumenflow://, ~/.lumenflow/, $LUMENFLOW_HOME/)
+ * by expanding them to absolute paths and adding a note about reading them.
+ *
  * @param {string[]|undefined} specRefs - Spec references array
  * @returns {string} Formatted references or empty string if none
  */
@@ -96,7 +99,17 @@ function formatSpecRefs(specRefs) {
     if (!specRefs || specRefs.length === 0) {
         return '';
     }
-    return specRefs.map((ref) => `- ${ref}`).join('\n');
+    const formattedRefs = specRefs.map((ref) => {
+        // WU-1062: Add note for external paths
+        if (ref.startsWith('lumenflow://') ||
+            ref.startsWith('~/') ||
+            ref.startsWith('$LUMENFLOW_HOME') ||
+            (ref.startsWith('/') && ref.includes('.lumenflow'))) {
+            return `- ${ref} (external - read with filesystem access)`;
+        }
+        return `- ${ref}`;
+    });
+    return formattedRefs.join('\n');
 }
 /**
  * Format risks as markdown list

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lumenflow/core",
-  "version": "1.3.0",
+  "version": "1.3.2",
   "description": "Core WU lifecycle tools for LumenFlow workflow framework",
   "keywords": [
     "lumenflow",
@@ -76,6 +76,7 @@
     "gray-matter": "^4.0.3",
     "micromatch": "^4.0.8",
     "minimatch": "^10.1.1",
+    "ms": "^2.1.3",
     "picocolors": "^1.1.1",
     "pretty-ms": "^9.2.0",
     "ps-list": "^8.1.1",
@@ -90,8 +91,8 @@
     "vitest": "^4.0.17"
   },
   "peerDependencies": {
-    "@lumenflow/memory": "1.3.0",
-    "@lumenflow/initiatives": "1.3.0"
+    "@lumenflow/memory": "1.3.2",
+    "@lumenflow/initiatives": "1.3.2"
   },
   "peerDependenciesMeta": {
     "@lumenflow/memory": {