@lumenflow/core 1.3.0 → 1.3.2

package/dist/arg-parser.d.ts

@@ -21,6 +21,12 @@ interface WUOption {
     isRepeatable?: boolean;
 }
 export declare const WU_OPTIONS: Record<string, WUOption>;
+/**
+ * WU-1062: Additional options for wu:create command
+ *
+ * These options control how wu:create handles spec storage and branch creation.
+ */
+export declare const WU_CREATE_OPTIONS: Record<string, WUOption>;
 /**
  * Create a commander-based CLI parser for a WU script.
  *

package/dist/arg-parser.js

@@ -396,6 +396,32 @@ export const WU_OPTIONS = {
         description: 'Skip automatic pnpm install in worktree after creation (faster claims when deps already built)',
     },
 };
+/**
+ * WU-1062: Additional options for wu:create command
+ *
+ * These options control how wu:create handles spec storage and branch creation.
+ */
+export const WU_CREATE_OPTIONS = {
+    /**
+     * Create plan template in $LUMENFLOW_HOME/plans/
+     * Used with spec branch mode to store plans externally.
+     */
+    plan: {
+        name: 'plan',
+        flags: '--plan',
+        description: 'Create plan template in $LUMENFLOW_HOME/plans/ (external plan storage for traceability)',
+    },
+    /**
+     * Direct main-write mode (legacy behavior)
+     * Writes WU spec directly to main branch instead of spec branch.
+     * Use for emergency/hotfix scenarios or when spec branch workflow is not desired.
+     */
+    direct: {
+        name: 'direct',
+        flags: '--direct',
+        description: 'Write to main directly (legacy behavior). Default is spec branch mode (spec/wu-XXXX)',
+    },
+};
 /**
  * Negated options that commander handles specially.
  * --no-foo creates opts.foo = false. We convert to noFoo = true.

package/dist/git-adapter.d.ts

@@ -66,6 +66,13 @@ export declare class GitAdapter {
      * await git.getStatus(); // " M file.txt\n?? untracked.txt"
      */
     getStatus(): Promise<string>;
+    /**
+     * Get unpushed commits (compared to upstream)
+     * @returns {Promise<string>} Oneline log output for unpushed commits
+     * @example
+     * await git.getUnpushedCommits(); // "abc123 fix: ...\n"
+     */
+    getUnpushedCommits(): Promise<string>;
     /**
      * Check if a branch exists
      * @param {string} branch - Branch name

package/dist/git-adapter.js

@@ -18,7 +18,7 @@
  */
 import { simpleGit } from 'simple-git';
 import { existsSync, rmSync } from 'node:fs';
-import { GIT_FLAGS } from './wu-constants.js';
+import { GIT_COMMANDS, GIT_FLAGS, GIT_REFS } from './wu-constants.js';
 // WU-2242: Runtime assertion helpers
 /**
  * Assert that a value is a non-empty string
@@ -117,6 +117,20 @@ export class GitAdapter {
         const result = await this.git.raw(['status', GIT_FLAGS.PORCELAIN]);
         return result.trim();
     }
+    /**
+     * Get unpushed commits (compared to upstream)
+     * @returns {Promise<string>} Oneline log output for unpushed commits
+     * @example
+     * await git.getUnpushedCommits(); // "abc123 fix: ...\n"
+     */
+    async getUnpushedCommits() {
+        const result = await this.git.raw([
+            GIT_COMMANDS.LOG,
+            GIT_REFS.UPSTREAM_RANGE,
+            GIT_FLAGS.ONELINE,
+        ]);
+        return result.trim();
+    }
     /**
      * Check if a branch exists
      * @param {string} branch - Branch name

package/dist/index.d.ts

@@ -41,3 +41,5 @@ export * from './stamp-utils.js';
 export * from './lumenflow-config.js';
 export * from './lumenflow-config-schema.js';
 export * from './branch-check.js';
+export * from './lumenflow-home.js';
+export * from './spec-branch-helpers.js';

package/dist/index.js

@@ -61,3 +61,6 @@ export * from './lumenflow-config.js';
 export * from './lumenflow-config-schema.js';
 // Branch check utilities
 export * from './branch-check.js';
+// WU-1062: External plan storage and spec branch helpers
+export * from './lumenflow-home.js';
+export * from './spec-branch-helpers.js';

package/dist/lumenflow-home.d.ts

@@ -0,0 +1,130 @@
+/**
+ * LumenFlow Home Directory Resolution
+ *
+ * WU-1062: External plan storage and no-main-write mode
+ *
+ * Provides helpers for resolving the $LUMENFLOW_HOME directory and related paths.
+ * Plans are stored externally in $LUMENFLOW_HOME/plans/ instead of in the repo.
+ *
+ * Default: ~/.lumenflow/
+ * Override: Set $LUMENFLOW_HOME environment variable
+ *
+ * @module
+ */
+/**
+ * Environment variable name for LumenFlow home directory
+ */
+export declare const LUMENFLOW_HOME_ENV = "LUMENFLOW_HOME";
+/**
+ * Default LumenFlow home directory name
+ */
+export declare const DEFAULT_LUMENFLOW_DIR = ".lumenflow";
+/**
+ * Plans subdirectory name
+ */
+export declare const PLANS_SUBDIR = "plans";
+/**
+ * Custom protocol for external LumenFlow paths
+ */
+export declare const LUMENFLOW_PROTOCOL = "lumenflow://";
+/**
+ * Environment variable prefix for spec_refs
+ */
+export declare const LUMENFLOW_HOME_VAR_PREFIX = "$LUMENFLOW_HOME";
+/**
+ * Get the LumenFlow home directory path
+ *
+ * Resolution order:
+ * 1. $LUMENFLOW_HOME environment variable (with ~ expansion)
+ * 2. ~/.lumenflow/ default
+ *
+ * @returns {string} Absolute path to LumenFlow home directory
+ *
+ * @example
+ * // With LUMENFLOW_HOME=/custom/path
+ * getLumenflowHome() // '/custom/path'
+ *
+ * @example
+ * // With LUMENFLOW_HOME=~/.custom-lumenflow
+ * getLumenflowHome() // '/home/user/.custom-lumenflow'
+ *
+ * @example
+ * // Without LUMENFLOW_HOME set
+ * getLumenflowHome() // '/home/user/.lumenflow'
+ */
+export declare function getLumenflowHome(): string;
+/**
+ * Get the plans directory path
+ *
+ * Plans are stored in $LUMENFLOW_HOME/plans/
+ *
+ * @returns {string} Absolute path to plans directory
+ *
+ * @example
+ * getPlansDir() // '/home/user/.lumenflow/plans'
+ */
+export declare function getPlansDir(): string;
+/**
+ * Check if a path is an external (non-repo) path
+ *
+ * External paths include:
+ * - Paths starting with ~/
+ * - Paths starting with $LUMENFLOW_HOME
+ * - Paths using lumenflow:// protocol
+ * - Absolute paths (starting with /)
+ *
+ * @param {string} path - Path to check
+ * @returns {boolean} True if path is external
+ *
+ * @example
+ * isExternalPath('~/.lumenflow/plans/plan.md') // true
+ * isExternalPath('$LUMENFLOW_HOME/plans/plan.md') // true
+ * isExternalPath('lumenflow://plans/plan.md') // true
+ * isExternalPath('/home/user/.lumenflow/plans/plan.md') // true
+ * isExternalPath('docs/04-operations/plans/plan.md') // false
+ */
+export declare function isExternalPath(path: string): boolean;
+/**
+ * Normalize a spec_ref path by expanding variables and protocols
+ *
+ * Expands:
+ * - lumenflow://path -> $LUMENFLOW_HOME/path
+ * - ~/path -> /home/user/path
+ * - $LUMENFLOW_HOME/path -> actual LUMENFLOW_HOME value
+ *
+ * Repo-relative paths are returned unchanged.
+ *
+ * @param {string} specRef - Spec reference path
+ * @returns {string} Normalized absolute path or unchanged relative path
+ *
+ * @example
+ * normalizeSpecRef('lumenflow://plans/WU-1062-plan.md')
+ * // '/home/user/.lumenflow/plans/WU-1062-plan.md'
+ *
+ * @example
+ * normalizeSpecRef('docs/04-operations/plans/plan.md')
+ * // 'docs/04-operations/plans/plan.md' (unchanged)
+ */
+export declare function normalizeSpecRef(specRef: string): string;
+/**
+ * Get the full path for a plan file given a WU ID
+ *
+ * @param {string} wuId - Work Unit ID (e.g., 'WU-1062')
+ * @returns {string} Full path to the plan file
+ *
+ * @example
+ * getPlanPath('WU-1062')
+ * // '/home/user/.lumenflow/plans/WU-1062-plan.md'
+ */
+export declare function getPlanPath(wuId: string): string;
+/**
+ * Get the lumenflow:// protocol reference for a plan
+ *
+ * @param {string} wuId - Work Unit ID (e.g., 'WU-1062')
+ * @returns {string} Protocol reference (e.g., 'lumenflow://plans/WU-1062-plan.md')
+ *
+ * @example
+ * getPlanProtocolRef('WU-1062')
+ * // 'lumenflow://plans/WU-1062-plan.md'
+ */
+export declare function getPlanProtocolRef(wuId: string): string;

package/dist/lumenflow-home.js

@@ -0,0 +1,208 @@
+/**
+ * LumenFlow Home Directory Resolution
+ *
+ * WU-1062: External plan storage and no-main-write mode
+ *
+ * Provides helpers for resolving the $LUMENFLOW_HOME directory and related paths.
+ * Plans are stored externally in $LUMENFLOW_HOME/plans/ instead of in the repo.
+ *
+ * Default: ~/.lumenflow/
+ * Override: Set $LUMENFLOW_HOME environment variable
+ *
+ * @module
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/**
+ * Environment variable name for LumenFlow home directory
+ */
+export const LUMENFLOW_HOME_ENV = 'LUMENFLOW_HOME';
+/**
+ * Default LumenFlow home directory name
+ */
+export const DEFAULT_LUMENFLOW_DIR = '.lumenflow';
+/**
+ * Plans subdirectory name
+ */
+export const PLANS_SUBDIR = 'plans';
+/**
+ * Custom protocol for external LumenFlow paths
+ */
+export const LUMENFLOW_PROTOCOL = 'lumenflow://';
+/**
+ * Environment variable prefix for spec_refs
+ */
+export const LUMENFLOW_HOME_VAR_PREFIX = '$LUMENFLOW_HOME';
+/**
+ * Expand ~ to user's home directory
+ *
+ * @param {string} path - Path that may contain ~
+ * @returns {string} Expanded path
+ */
+function expandTilde(path) {
+    if (path.startsWith('~/')) {
+        return join(homedir(), path.slice(2));
+    }
+    if (path === '~') {
+        return homedir();
+    }
+    return path;
+}
+/**
+ * Remove trailing slashes from path
+ *
+ * @param {string} path - Path that may have trailing slashes
+ * @returns {string} Path without trailing slashes
+ */
+function removeTrailingSlash(path) {
+    return path.replace(/\/+$/, '');
+}
+/**
+ * Get the LumenFlow home directory path
+ *
+ * Resolution order:
+ * 1. $LUMENFLOW_HOME environment variable (with ~ expansion)
+ * 2. ~/.lumenflow/ default
+ *
+ * @returns {string} Absolute path to LumenFlow home directory
+ *
+ * @example
+ * // With LUMENFLOW_HOME=/custom/path
+ * getLumenflowHome() // '/custom/path'
+ *
+ * @example
+ * // With LUMENFLOW_HOME=~/.custom-lumenflow
+ * getLumenflowHome() // '/home/user/.custom-lumenflow'
+ *
+ * @example
+ * // Without LUMENFLOW_HOME set
+ * getLumenflowHome() // '/home/user/.lumenflow'
+ */
+export function getLumenflowHome() {
+    const envValue = process.env[LUMENFLOW_HOME_ENV];
+    if (envValue) {
+        const expanded = expandTilde(envValue);
+        return removeTrailingSlash(expanded);
+    }
+    return join(homedir(), DEFAULT_LUMENFLOW_DIR);
+}
+/**
+ * Get the plans directory path
+ *
+ * Plans are stored in $LUMENFLOW_HOME/plans/
+ *
+ * @returns {string} Absolute path to plans directory
+ *
+ * @example
+ * getPlansDir() // '/home/user/.lumenflow/plans'
+ */
+export function getPlansDir() {
+    return join(getLumenflowHome(), PLANS_SUBDIR);
+}
+/**
+ * Check if a path is an external (non-repo) path
+ *
+ * External paths include:
+ * - Paths starting with ~/
+ * - Paths starting with $LUMENFLOW_HOME
+ * - Paths using lumenflow:// protocol
+ * - Absolute paths (starting with /)
+ *
+ * @param {string} path - Path to check
+ * @returns {boolean} True if path is external
+ *
+ * @example
+ * isExternalPath('~/.lumenflow/plans/plan.md') // true
+ * isExternalPath('$LUMENFLOW_HOME/plans/plan.md') // true
+ * isExternalPath('lumenflow://plans/plan.md') // true
+ * isExternalPath('/home/user/.lumenflow/plans/plan.md') // true
+ * isExternalPath('docs/04-operations/plans/plan.md') // false
+ */
+export function isExternalPath(path) {
+    // Check for tilde-prefixed paths
+    if (path.startsWith('~/')) {
+        return true;
+    }
+    // Check for environment variable reference
+    if (path.startsWith(LUMENFLOW_HOME_VAR_PREFIX)) {
+        return true;
+    }
+    // Check for lumenflow:// protocol
+    if (path.startsWith(LUMENFLOW_PROTOCOL)) {
+        return true;
+    }
+    // Check for absolute paths (starting with /)
+    if (path.startsWith('/')) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Normalize a spec_ref path by expanding variables and protocols
+ *
+ * Expands:
+ * - lumenflow://path -> $LUMENFLOW_HOME/path
+ * - ~/path -> /home/user/path
+ * - $LUMENFLOW_HOME/path -> actual LUMENFLOW_HOME value
+ *
+ * Repo-relative paths are returned unchanged.
+ *
+ * @param {string} specRef - Spec reference path
+ * @returns {string} Normalized absolute path or unchanged relative path
+ *
+ * @example
+ * normalizeSpecRef('lumenflow://plans/WU-1062-plan.md')
+ * // '/home/user/.lumenflow/plans/WU-1062-plan.md'
+ *
+ * @example
+ * normalizeSpecRef('docs/04-operations/plans/plan.md')
+ * // 'docs/04-operations/plans/plan.md' (unchanged)
+ */
+export function normalizeSpecRef(specRef) {
+    // Handle lumenflow:// protocol
+    if (specRef.startsWith(LUMENFLOW_PROTOCOL)) {
+        const relativePath = specRef.slice(LUMENFLOW_PROTOCOL.length);
+        return join(getLumenflowHome(), relativePath);
+    }
+    // Handle $LUMENFLOW_HOME variable
+    if (specRef.startsWith(LUMENFLOW_HOME_VAR_PREFIX)) {
+        const relativePath = specRef.slice(LUMENFLOW_HOME_VAR_PREFIX.length);
+        // Remove leading slash if present
+        const cleanPath = relativePath.startsWith('/') ? relativePath.slice(1) : relativePath;
+        return join(getLumenflowHome(), cleanPath);
+    }
+    // Handle tilde expansion
+    if (specRef.startsWith('~/')) {
+        return expandTilde(specRef);
+    }
+    // Return relative paths unchanged
+    return specRef;
+}
+/**
+ * Get the full path for a plan file given a WU ID
+ *
+ * @param {string} wuId - Work Unit ID (e.g., 'WU-1062')
+ * @returns {string} Full path to the plan file
+ *
+ * @example
+ * getPlanPath('WU-1062')
+ * // '/home/user/.lumenflow/plans/WU-1062-plan.md'
+ */
+export function getPlanPath(wuId) {
+    const filename = `${wuId}-plan.md`;
+    return join(getPlansDir(), filename);
+}
+/**
+ * Get the lumenflow:// protocol reference for a plan
+ *
+ * @param {string} wuId - Work Unit ID (e.g., 'WU-1062')
+ * @returns {string} Protocol reference (e.g., 'lumenflow://plans/WU-1062-plan.md')
+ *
+ * @example
+ * getPlanProtocolRef('WU-1062')
+ * // 'lumenflow://plans/WU-1062-plan.md'
+ */
+export function getPlanProtocolRef(wuId) {
+    const filename = `${wuId}-plan.md`;
+    return `${LUMENFLOW_PROTOCOL}${PLANS_SUBDIR}/${filename}`;
+}

package/dist/manual-test-validator.js

@@ -20,7 +20,7 @@ import { TEST_TYPES, WU_TYPES } from './wu-constants.js';
  * Code file extensions that require automated tests.
  * @constant {string[]}
  */
-const CODE_EXTENSIONS = Object.freeze(['.js', '.ts', '.tsx', '.js']);
+const CODE_EXTENSIONS = Object.freeze(['.js', '.ts', '.tsx', '.mjs']);
 /**
  * Non-code file extensions (documentation, data, config).
  * @constant {string[]}

package/dist/orphan-detector.d.ts

@@ -18,6 +18,7 @@
  * @see {@link tools/wu-claim.mjs} - Pre-flight orphan check
  * @see {@link tools/lib/git-adapter.mjs} - worktreeRemove with cleanup
  */
+import { existsSync } from 'node:fs';
 /**
  * Result of orphan detection
  * @typedef {object} OrphanDetectionResult
@@ -50,6 +51,21 @@ export declare function parseWorktreeList(porcelainOutput: string): WorktreeEntr
  * @returns {Promise<Set<string>>} Set of absolute paths tracked by git worktree
  */
 export declare function getTrackedWorktreePaths(projectRoot: any): Promise<Set<string>>;
+/**
+ * Identify tracked worktrees that are missing on disk
+ *
+ * @param {string[]} trackedPaths - Absolute paths from git worktree list
+ * @param {(path: string) => boolean} [existsFn] - Optional fs.existsSync override
+ * @returns {string[]} Missing worktree paths
+ */
+export declare function getMissingWorktreesFromTracked(trackedPaths: any, existsFn?: typeof existsSync): any[];
+/**
+ * Detect tracked worktrees that are missing on disk
+ *
+ * @param {string} [projectRoot] - Project root directory (defaults to cwd)
+ * @returns {Promise<string[]>} Missing tracked worktree paths
+ */
+export declare function detectMissingTrackedWorktrees(projectRoot: any): Promise<any[]>;
 /**
  * Get list of directories in worktrees/ folder
  *

package/dist/orphan-detector.js

@@ -75,6 +75,30 @@ export async function getTrackedWorktreePaths(projectRoot) {
     const entries = parseWorktreeList(output);
     return new Set(entries.map((e) => e.path));
 }
+/**
+ * Identify tracked worktrees that are missing on disk
+ *
+ * @param {string[]} trackedPaths - Absolute paths from git worktree list
+ * @param {(path: string) => boolean} [existsFn] - Optional fs.existsSync override
+ * @returns {string[]} Missing worktree paths
+ */
+export function getMissingWorktreesFromTracked(trackedPaths, existsFn = existsSync) {
+    if (!Array.isArray(trackedPaths)) {
+        return [];
+    }
+    return trackedPaths.filter((trackedPath) => !existsFn(trackedPath));
+}
+/**
+ * Detect tracked worktrees that are missing on disk
+ *
+ * @param {string} [projectRoot] - Project root directory (defaults to cwd)
+ * @returns {Promise<string[]>} Missing tracked worktree paths
+ */
+export async function detectMissingTrackedWorktrees(projectRoot) {
+    const root = projectRoot || process.cwd();
+    const tracked = await getTrackedWorktreePaths(root);
+    return getMissingWorktreesFromTracked([...tracked]);
+}
 /**
  * Get list of directories in worktrees/ folder
  *

package/dist/spec-branch-helpers.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Spec Branch Helpers
+ *
+ * WU-1062: External plan storage and no-main-write mode
+ *
+ * Provides helpers for working with spec branches (spec/wu-XXXX).
+ * wu:create writes to spec branches by default; wu:claim merges them to main.
+ *
+ * @module
+ */
+import type { SimpleGit } from 'simple-git';
+/**
+ * Spec branch prefix
+ */
+export declare const SPEC_BRANCH_PREFIX = "spec/";
+/**
+ * WU source location constants
+ */
+export declare const WU_SOURCE: {
+    /** WU exists on main branch only */
+    readonly MAIN: "main";
+    /** WU exists on spec branch only */
+    readonly SPEC_BRANCH: "spec_branch";
+    /** WU exists on both main and spec branch */
+    readonly BOTH: "both";
+    /** WU not found anywhere */
+    readonly NOT_FOUND: "not_found";
+};
+export type WUSourceType = (typeof WU_SOURCE)[keyof typeof WU_SOURCE];
+/**
+ * Get the spec branch name for a WU
+ *
+ * @param {string} wuId - Work Unit ID (e.g., 'WU-1062')
+ * @returns {string} Spec branch name (e.g., 'spec/wu-1062')
+ *
+ * @example
+ * getSpecBranchName('WU-1062') // 'spec/wu-1062'
+ */
+export declare function getSpecBranchName(wuId: string): string;
+/**
+ * Get the origin-qualified spec branch name
+ *
+ * @param {string} wuId - Work Unit ID
+ * @returns {string} Origin-qualified branch name (e.g., 'origin/spec/wu-1062')
+ */
+export declare function getOriginSpecBranch(wuId: string): string;
+/**
+ * Check if a spec branch exists on origin
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @returns {Promise<boolean>} True if spec branch exists
+ *
+ * @example
+ * const exists = await specBranchExists('WU-1062', git);
+ */
+export declare function specBranchExists(wuId: string, git: SimpleGit): Promise<boolean>;
+/**
+ * Check if a WU exists on main branch
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @returns {Promise<boolean>} True if WU YAML exists on main
+ */
+export declare function isWUOnMain(wuId: string, git: SimpleGit): Promise<boolean>;
+/**
+ * Merge spec branch to main branch (fast-forward only)
+ *
+ * This is used by wu:claim when a WU exists only on a spec branch.
+ * The spec branch is merged to main before creating the worktree.
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @throws {Error} If merge fails (e.g., due to conflicts)
+ *
+ * @example
+ * await mergeSpecBranchToMain('WU-1062', git);
+ */
+export declare function mergeSpecBranchToMain(wuId: string, git: SimpleGit): Promise<void>;
+/**
+ * Delete spec branch after merge
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ */
+export declare function deleteSpecBranch(wuId: string, git: SimpleGit): Promise<void>;
+/**
+ * Determine the source of a WU (main, spec branch, both, or not found)
+ *
+ * Used by wu:claim to decide whether to merge spec branch before creating worktree.
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ * @returns {Promise<WUSourceType>} Source location constant
+ *
+ * @example
+ * const source = await getWUSource('WU-1062', git);
+ * if (source === WU_SOURCE.SPEC_BRANCH) {
+ *   await mergeSpecBranchToMain('WU-1062', git);
+ * }
+ */
+export declare function getWUSource(wuId: string, git: SimpleGit): Promise<WUSourceType>;
+/**
+ * Create a spec branch from current HEAD
+ *
+ * Used by wu:create in default mode (no --direct flag).
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ */
+export declare function createSpecBranch(wuId: string, git: SimpleGit): Promise<void>;
+/**
+ * Push spec branch to origin
+ *
+ * @param {string} wuId - Work Unit ID
+ * @param {SimpleGit} git - Git adapter instance
+ */
+export declare function pushSpecBranch(wuId: string, git: SimpleGit): Promise<void>;