@lumenflow/core 3.1.3 → 3.2.1

package/dist/agent-patterns-registry.js

@@ -0,0 +1,320 @@
+// Copyright (c) 2026 Hellmai Ltd
+// SPDX-License-Identifier: AGPL-3.0-only
+/**
+ * Agent Patterns Registry
+ *
+ * Central registry for AI agent branch patterns (claude/*, codex/*, copilot/*, cursor/*, etc.)
+ * that bypass worktree requirements. Static JSON served from lumenflow.dev,
+ * cached locally for 7 days with fallback to defaults.
+ *
+ * WU-1089: Added merge/override/airgapped modes via resolveAgentPatterns()
+ *
+ * @module agent-patterns-registry
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { LUMENFLOW_PATHS } from './wu-constants.js';
+import { MS_PER_DAY } from './constants/duration-constants.js';
+/** Default agent branch patterns (narrow: just agent/*) */
+export const DEFAULT_AGENT_PATTERNS = ['agent/*'];
+/** Remote registry URL */
+export const REGISTRY_URL = 'https://lumenflow.dev/registry/agent-patterns.json';
+/** Cache TTL: 7 days in milliseconds (WU-2044: uses canonical MS_PER_DAY) */
+export const CACHE_TTL_MS = 7 * MS_PER_DAY;
+/** Cache file name */
+const CACHE_FILE_NAME = 'agent-patterns-cache.json';
+/** Default fetch timeout in milliseconds */
+const DEFAULT_TIMEOUT_MS = 5000;
+/** In-memory cache for patterns */
+let memoryCache = null;
+/** In-memory cache timestamp */
+let memoryCacheTime = 0;
+/**
+ * Get the default cache directory
+ *
+ * @returns Path to cache directory (~/.lumenflow/cache or LUMENFLOW_HOME/cache)
+ */
+export function getCacheDir() {
+    const lumenflowHome = process.env.LUMENFLOW_HOME;
+    if (lumenflowHome) {
+        return path.join(lumenflowHome, LUMENFLOW_PATHS.HOME_CACHE);
+    }
+    // WU-1430: Compose home cache path from centralized constants
+    return path.join(os.homedir(), LUMENFLOW_PATHS.BASE, LUMENFLOW_PATHS.HOME_CACHE);
+}
+/**
+ * Validate registry response
+ *
+ * @param data - Data to validate
+ * @returns True if valid registry response
+ */
+function isValidRegistryResponse(data) {
+    if (!data || typeof data !== 'object')
+        return false;
+    const obj = data;
+    if (!Array.isArray(obj.patterns))
+        return false;
+    if (!obj.patterns.every((p) => typeof p === 'string'))
+        return false;
+    return true;
+}
+/**
+ * Read cache from disk
+ *
+ * @param cacheDir - Cache directory
+ * @returns Cache data or null if not found/invalid
+ */
+function readCache(cacheDir) {
+    try {
+        const cacheFile = path.join(cacheDir, CACHE_FILE_NAME);
+        if (!fs.existsSync(cacheFile))
+            return null;
+        const content = fs.readFileSync(cacheFile, 'utf8');
+        const data = JSON.parse(content);
+        // Validate cache structure
+        if (!Array.isArray(data.patterns))
+            return null;
+        if (typeof data.fetchedAt !== 'number')
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Write cache to disk
+ *
+ * @param cacheDir - Cache directory
+ * @param data - Data to cache
+ */
+function writeCache(cacheDir, data) {
+    try {
+        // Ensure cache directory exists
+        if (!fs.existsSync(cacheDir)) {
+            fs.mkdirSync(cacheDir, { recursive: true });
+        }
+        const cacheFile = path.join(cacheDir, CACHE_FILE_NAME);
+        fs.writeFileSync(cacheFile, JSON.stringify(data, null, 2));
+    }
+    catch {
+        // Fail silently - cache is optional
+    }
+}
+/**
+ * Fetch patterns from remote registry with timeout
+ *
+ * @param timeoutMs - Timeout in milliseconds
+ * @returns Registry response or null on failure
+ */
+async function fetchFromRegistry(timeoutMs) {
+    try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        const response = await fetch(REGISTRY_URL, {
+            signal: controller.signal,
+            headers: {
+                Accept: 'application/json',
+                'User-Agent': 'lumenflow-core',
+            },
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            return null;
+        }
+        const data = await response.json();
+        if (!isValidRegistryResponse(data)) {
+            return null;
+        }
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Get agent branch patterns from registry with caching
+ *
+ * Fetches patterns from remote registry, caches locally for 7 days,
+ * and falls back to defaults on failure.
+ *
+ * @param options - Options
+ * @returns Array of agent branch patterns (glob format)
+ *
+ * @example
+ * ```typescript
+ * const patterns = await getAgentPatterns();
+ * // ['claude/*', 'codex/*', 'copilot/*', 'cursor/*', 'agent/*']
+ * ```
+ */
+export async function getAgentPatterns(options = {}) {
+    const { cacheDir = getCacheDir(), timeoutMs = DEFAULT_TIMEOUT_MS } = options;
+    // Check memory cache first (fast path)
+    const now = Date.now();
+    if (memoryCache && now - memoryCacheTime < CACHE_TTL_MS) {
+        return memoryCache;
+    }
+    // Check disk cache
+    const diskCache = readCache(cacheDir);
+    if (diskCache && now - diskCache.fetchedAt < CACHE_TTL_MS) {
+        // Fresh disk cache - use it and update memory cache
+        memoryCache = diskCache.patterns;
+        memoryCacheTime = diskCache.fetchedAt;
+        return diskCache.patterns;
+    }
+    // Cache is stale or missing - try to fetch
+    const registryData = await fetchFromRegistry(timeoutMs);
+    if (registryData) {
+        // Update caches
+        const cacheData = {
+            version: registryData.version,
+            patterns: registryData.patterns,
+            fetchedAt: now,
+        };
+        writeCache(cacheDir, cacheData);
+        memoryCache = registryData.patterns;
+        memoryCacheTime = now;
+        return registryData.patterns;
+    }
+    // Fetch failed - try stale cache as fallback
+    if (diskCache) {
+        memoryCache = diskCache.patterns;
+        memoryCacheTime = diskCache.fetchedAt; // Keep stale time
+        return diskCache.patterns;
+    }
+    // No cache, no network - use defaults
+    return DEFAULT_AGENT_PATTERNS;
+}
+/**
+ * Resolve agent branch patterns based on config with merge/override/airgapped support
+ *
+ * Behavior matrix (WU-1089):
+ *
+ * | disableRegistry | override patterns | config patterns | Result                 | Source        |
+ * |-----------------|-------------------|-----------------|------------------------|---------------|
+ * | false           | undefined         | undefined/[]    | registry               | 'registry'    |
+ * | false           | undefined         | ['custom/*']    | config + registry      | 'merged'      |
+ * | false           | ['only/*']        | UnsafeAny             | override only          | 'override'    |
+ * | true            | undefined         | undefined/[]    | defaults               | 'defaults'    |
+ * | true            | undefined         | ['custom/*']    | config only            | 'config'      |
+ * | true            | ['only/*']        | UnsafeAny             | override only          | 'override'    |
+ *
+ * When registry fetch fails:
+ * - Falls back to config patterns if provided, source = 'config'
+ * - Falls back to defaults if no config, source = 'defaults'
+ *
+ * @param options - Resolution options
+ * @returns Result with patterns, source, and registryFetched flag
+ *
+ * @example Default (fetch from registry)
+ * ```typescript
+ * const result = await resolveAgentPatterns({});
+ * // result.patterns = ['claude/*', 'codex/*', ...] (from registry)
+ * // result.source = 'registry'
+ * // result.registryFetched = true
+ * ```
+ *
+ * @example Merge mode (config + registry)
+ * ```typescript
+ * const result = await resolveAgentPatterns({
+ *   configPatterns: ['my-agent/*'],
+ * });
+ * // result.patterns = ['my-agent/*', 'claude/*', 'codex/*', ...]
+ * // result.source = 'merged'
+ * // result.registryFetched = true
+ * ```
+ *
+ * @example Override mode (explicit replacement)
+ * ```typescript
+ * const result = await resolveAgentPatterns({
+ *   overridePatterns: ['only-this/*'],
+ * });
+ * // result.patterns = ['only-this/*']
+ * // result.source = 'override'
+ * // result.registryFetched = false
+ * ```
+ *
+ * @example Airgapped mode (no network)
+ * ```typescript
+ * const result = await resolveAgentPatterns({
+ *   disableAgentPatternRegistry: true,
+ *   configPatterns: ['my-agent/*'],
+ * });
+ * // result.patterns = ['my-agent/*']
+ * // result.source = 'config'
+ * // result.registryFetched = false
+ * ```
+ */
+export async function resolveAgentPatterns(options = {}) {
+    const { registryFetcher = getAgentPatterns, configPatterns, overridePatterns, disableAgentPatternRegistry = false, cacheDir, timeoutMs, } = options;
+    // Scenario 3/6: Override mode - overridePatterns replaces everything
+    if (overridePatterns && overridePatterns.length > 0) {
+        return {
+            patterns: overridePatterns,
+            source: 'override',
+            registryFetched: false,
+        };
+    }
+    // Scenario 4/5: Airgapped mode - disableAgentPatternRegistry skips network
+    if (disableAgentPatternRegistry) {
+        const hasConfigPatterns = configPatterns && configPatterns.length > 0;
+        return {
+            patterns: hasConfigPatterns ? configPatterns : DEFAULT_AGENT_PATTERNS,
+            source: hasConfigPatterns ? 'config' : 'defaults',
+            registryFetched: false,
+        };
+    }
+    // Scenario 1/2: Normal mode - fetch from registry, optionally merge with config
+    const hasConfigPatterns = configPatterns && configPatterns.length > 0;
+    // Try to fetch from registry
+    let registryPatterns = [];
+    let fetchedSuccessfully;
+    try {
+        registryPatterns = await registryFetcher({ cacheDir, timeoutMs });
+        fetchedSuccessfully = registryPatterns.length > 0;
+    }
+    catch {
+        // Fetch failed - will use fallback below
+        fetchedSuccessfully = false;
+    }
+    // If registry fetch succeeded
+    if (fetchedSuccessfully) {
+        if (hasConfigPatterns) {
+            // Scenario 2: Merge mode - config first, then registry (deduplicated)
+            const merged = [...configPatterns];
+            for (const pattern of registryPatterns) {
+                if (!merged.includes(pattern)) {
+                    merged.push(pattern);
+                }
+            }
+            return {
+                patterns: merged,
+                source: 'merged',
+                registryFetched: true,
+            };
+        }
+        // Scenario 1: Registry only
+        return {
+            patterns: registryPatterns,
+            source: 'registry',
+            registryFetched: true,
+        };
+    }
+    // Registry fetch failed - fallback to config or defaults
+    return {
+        patterns: hasConfigPatterns ? configPatterns : DEFAULT_AGENT_PATTERNS,
+        source: hasConfigPatterns ? 'config' : 'defaults',
+        registryFetched: false,
+    };
+}
+/**
+ * Clear the in-memory cache
+ *
+ * Used primarily for testing.
+ */
+export function clearCache() {
+    memoryCache = null;
+    memoryCacheTime = 0;
+}
+//# sourceMappingURL=agent-patterns-registry.js.map

package/dist/agent-patterns-registry.js.map

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

package/dist/arg-parser.d.ts

@@ -0,0 +1,94 @@
+import { type OptionValues } from 'commander';
+/**
+ * Predefined option configurations for WU management scripts.
+ * Each option has: name, flags, description, and optional default.
+ *
+ * Commander auto-converts kebab-case flags to camelCase in opts().
+ * Example: --branch-only becomes opts().branchOnly
+ *
+ * NOTE: Commander treats --no-* flags specially (negated booleans).
+ * --no-foo creates opts.foo = false (default true).
+ * We post-process to convert these to noFoo = true for backward compat.
+ */
+/**
+ * WU option definition structure
+ */
+interface WUOption {
+    name: string;
+    flags: string;
+    description: string;
+    default?: string | boolean | string[];
+    isNegated?: boolean;
+    isRepeatable?: boolean;
+    /** Type hint for option parsing (e.g., 'boolean' for flags, 'string' for values) */
+    type?: 'boolean' | 'string';
+    /** Whether this option is required (used for validation hints) */
+    required?: boolean;
+}
+export declare const WU_OPTIONS: Record<string, WUOption>;
+/**
+ * WU-1062: Additional options for wu:create command
+ *
+ * These options control how wu:create handles external plan storage.
+ */
+export declare const WU_CREATE_OPTIONS: Record<string, WUOption>;
+/**
+ * WU-1755: Additional options for initiative:create command.
+ * These supplement WU_OPTIONS with initiative-specific repeatable fields.
+ */
+export declare const INITIATIVE_CREATE_OPTIONS: Record<string, WUOption>;
+/**
+ * Negated options that commander handles specially.
+ * --no-foo creates opts.foo = false. We convert to noFoo = true.
+ *
+ * WU-1329: Export for testing purposes.
+ */
+export declare const NEGATED_OPTIONS: string[];
+/**
+ * Create a commander-based CLI parser for a WU script.
+ *
+ * @param {object} config - Parser configuration
+ * @param {string} config.name - Script name (e.g., 'wu-claim')
+ * @param {string} config.description - Script description for help text
+ * @param {Array<object>} config.options - Array of option objects from WU_OPTIONS
+ * @param {Array<string>} [config.required=[]] - Array of option names that are required
+ * @param {boolean} [config.allowPositionalId=false] - Allow first positional arg as WU ID
+ * @param {string} [config.version='1.0.0'] - Script version
+ * @returns {object} Parsed options object (camelCase keys)
+ *
+ * @example
+ * const opts = createWUParser({
+ *   name: 'wu-claim',
+ *   description: 'Claim a work unit for a lane',
+ *   options: [WU_OPTIONS.id, WU_OPTIONS.lane, WU_OPTIONS.branchOnly],
+ *   required: ['id', 'lane'],
+ * });
+ * console.log(opts.id); // 'WU-123'
+ * console.log(opts.branchOnly); // true
+ */
+export declare function createWUParser(config: {
+    name: string;
+    description: string;
+    options?: WUOption[];
+    required?: string[];
+    allowPositionalId?: boolean;
+    version?: string;
+}): OptionValues;
+/**
+ * Backward-compatible unified argument parser for WU management scripts.
+ * Uses commander internally but maintains the same return format.
+ *
+ * @deprecated Use createWUParser() for new scripts to get better help text.
+ *
+ * @param {string[]} argv - Process arguments (typically process.argv)
+ * @returns {object} Parsed arguments object (camelCase keys)
+ * @throws {Error} If unknown flag or missing required value
+ *
+ * @example
+ * const args = parseWUArgs(process.argv);
+ * console.log(args.id); // 'WU-123'
+ * console.log(args.branchOnly); // true
+ */
+export declare function parseWUArgs(argv: string[]): OptionValues;
+export {};
+//# sourceMappingURL=arg-parser.d.ts.map

package/dist/arg-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"arg-parser.d.ts","sourceRoot":"","sources":["../src/arg-parser.ts"],"names":[],"mappings":"AAGA,OAAO,EAAW,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAuBvD;;;;;;;;;;GAUG;AACH;;GAEG;AACH,UAAU,QAAQ;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC;IACtC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oFAAoF;IACpF,IAAI,CAAC,EAAE,SAAS,GAAG,QAAQ,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,eAAO,MAAM,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAid/C,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAUtD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CAkB9D,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,eAAe,UAA8D,CAAC;AAiD3F;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,QAAQ,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,GAAG,YAAY,CAiFf;AAuDD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,YAAY,CA0ExD"}