@lumenflow/core 1.3.6 → 1.5.0

package/README.md

@@ -68,6 +68,60 @@ const exists = await worktrees.exists('/path/to/worktree');
 await worktrees.remove('worktrees/operations-wu-123');
 ```
 
+### Agent Branch Patterns
+
+Check if a branch is an agent branch that can bypass worktree requirements. Patterns are fetched from a central registry with 7-day caching, and can be configured via `.lumenflow.config.yaml`.
+
+```typescript
+import { isAgentBranch, isAgentBranchWithDetails, resolveAgentPatterns } from '@lumenflow/core';
+
+// Check if branch can bypass worktree requirements (async, uses registry)
+if (await isAgentBranch('claude/session-12345')) {
+  console.log('Agent branch - bypass allowed');
+}
+
+// Get detailed result for observability
+const result = await isAgentBranchWithDetails('claude/session-123');
+if (result.isMatch) {
+  console.log(`Matched via ${result.patternResult.source}`); // 'registry', 'merged', 'override', 'config', 'defaults'
+  console.log(`Registry fetched: ${result.patternResult.registryFetched}`);
+}
+
+// Resolve patterns with custom options (useful for testing)
+const resolved = await resolveAgentPatterns({
+  configPatterns: ['my-agent/*'], // Merge with registry
+  // overridePatterns: ['only-this/*'], // Replace registry entirely
+  // disableAgentPatternRegistry: true, // Airgapped mode
+});
+console.log(resolved.patterns, resolved.source);
+
+// Synchronous version (uses local config only, no registry fetch)
+import { isAgentBranchSync } from '@lumenflow/core';
+const syncResult = isAgentBranchSync('agent/task-123');
+```
+
+#### Configuration Options
+
+In `.lumenflow.config.yaml`:
+
+```yaml
+git:
+  # Patterns to MERGE with registry (default: [])
+  agentBranchPatterns:
+    - 'my-custom-agent/*'
+    - 'internal-tool/*'
+
+  # Patterns that REPLACE registry entirely (optional)
+  # agentBranchPatternsOverride:
+  #   - 'claude/*'
+  #   - 'codex/*'
+
+  # Disable registry fetch for airgapped environments (default: false)
+  # disableAgentPatternRegistry: true
+```
+
+Protected branches (main, master, lane/\*) are **never** bypassed, regardless of patterns.
+
 ## API Reference
 
 ### GitAdapter

package/dist/agent-patterns-registry.d.ts

@@ -0,0 +1,151 @@
+/**
+ * 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
+ */
+/** Default agent branch patterns (narrow: just agent/*) */
+export declare const DEFAULT_AGENT_PATTERNS: string[];
+/** Remote registry URL */
+export declare const REGISTRY_URL = "https://lumenflow.dev/registry/agent-patterns.json";
+/** Cache TTL: 7 days in milliseconds */
+export declare const CACHE_TTL_MS: number;
+/**
+ * Options for getAgentPatterns
+ */
+export interface GetAgentPatternsOptions {
+    /** Override cache directory (default: ~/.lumenflow/cache) */
+    cacheDir?: string;
+    /** Fetch timeout in milliseconds (default: 5000) */
+    timeoutMs?: number;
+}
+/**
+ * Source of agent patterns for observability
+ */
+export type AgentPatternSource = 'registry' | 'merged' | 'override' | 'config' | 'defaults';
+/**
+ * Result of resolveAgentPatterns with observability fields
+ */
+export interface AgentPatternResult {
+    /** Resolved patterns to use for agent branch matching */
+    patterns: string[];
+    /** Source of the patterns for observability */
+    source: AgentPatternSource;
+    /** Whether the registry was successfully fetched */
+    registryFetched: boolean;
+}
+/**
+ * Type for injectable registry fetcher function
+ */
+export type RegistryFetcher = (options: GetAgentPatternsOptions) => Promise<string[]>;
+/**
+ * Options for resolveAgentPatterns (WU-1089)
+ */
+export interface ResolveAgentPatternsOptions {
+    /** Injectable registry fetcher for testing (uses getAgentPatterns by default) */
+    registryFetcher?: RegistryFetcher;
+    /** Patterns from config.git.agentBranchPatterns (merged with registry by default) */
+    configPatterns?: string[];
+    /** Patterns from config.git.agentBranchPatternsOverride (replaces everything if set) */
+    overridePatterns?: string[];
+    /** config.git.disableAgentPatternRegistry - skips network fetch (airgapped mode) */
+    disableAgentPatternRegistry?: boolean;
+    /** Override cache directory (passed to fetcher) */
+    cacheDir?: string;
+    /** Fetch timeout in milliseconds (passed to fetcher) */
+    timeoutMs?: number;
+}
+/**
+ * Get the default cache directory
+ *
+ * @returns Path to cache directory (~/.lumenflow/cache or LUMENFLOW_HOME/cache)
+ */
+export declare function getCacheDir(): string;
+/**
+ * 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 declare function getAgentPatterns(options?: GetAgentPatternsOptions): Promise<string[]>;
+/**
+ * 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/*']        | any             | override only          | 'override'    |
+ * | true            | undefined         | undefined/[]    | defaults               | 'defaults'    |
+ * | true            | undefined         | ['custom/*']    | config only            | 'config'      |
+ * | true            | ['only/*']        | any             | 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 declare function resolveAgentPatterns(options?: ResolveAgentPatternsOptions): Promise<AgentPatternResult>;
+/**
+ * Clear the in-memory cache
+ *
+ * Used primarily for testing.
+ */
+export declare function clearCache(): void;

package/dist/agent-patterns-registry.js

@@ -0,0 +1,314 @@
+/**
+ * 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';
+/** 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 */
+export const CACHE_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** 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, 'cache');
+    }
+    return path.join(os.homedir(), '.lumenflow', '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/*']        | any             | override only          | 'override'    |
+ * | true            | undefined         | undefined/[]    | defaults               | 'defaults'    |
+ * | true            | undefined         | ['custom/*']    | config only            | 'config'      |
+ * | true            | ['only/*']        | any             | 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 = null;
+    let fetchedSuccessfully = false;
+    try {
+        registryPatterns = await registryFetcher({ cacheDir, timeoutMs });
+        fetchedSuccessfully = registryPatterns !== null && registryPatterns.length > 0;
+    }
+    catch {
+        // Fetch failed - will use fallback below
+        fetchedSuccessfully = false;
+    }
+    // If registry fetch succeeded
+    if (fetchedSuccessfully && registryPatterns) {
+        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;
+}

package/dist/arg-parser.js

@@ -247,6 +247,13 @@ export const WU_OPTIONS = {
         flags: '--color',
         description: 'Enable colored output',
     },
+    // WU-1085: NO_COLOR standard support (https://no-color.org/)
+    noColor: {
+        name: 'noColor',
+        flags: '--no-color',
+        description: 'Disable colored output (respects NO_COLOR env var)',
+        isNegated: true,
+    },
     status: {
         name: 'status',
         flags: '--status <status>',

package/dist/branch-check.d.ts

@@ -4,16 +4,67 @@
  * Provides functions to check if a branch is an agent branch that can
  * bypass worktree requirements, and if headless mode is allowed.
  *
+ * WU-1089: Updated to use resolveAgentPatterns with merge/override/airgapped support.
+ *
  * @module branch-check
  */
+import { type AgentPatternResult } from './agent-patterns-registry.js';
 /**
  * Check if branch is an agent branch that can bypass worktree requirements.
- * Uses the existing config loader (which handles caching/validation).
+ *
+ * WU-1089: Now uses resolveAgentPatterns with proper merge/override/airgapped support:
+ * - Default: Fetches from registry (lumenflow.dev) with 7-day cache
+ * - Config patterns merge with registry patterns (config first)
+ * - Override patterns (agentBranchPatternsOverride) replace everything
+ * - Airgapped mode (disableAgentPatternRegistry) skips network fetch
+ *
+ * @param branch - Branch name to check
+ * @returns Promise<true> if branch matches agent patterns
+ *
+ * @example
+ * ```typescript
+ * if (await isAgentBranch('claude/session-123')) {
+ *   // Allow bypass for agent branch
+ * }
+ * ```
+ */
+export declare function isAgentBranch(branch: string | null | undefined): Promise<boolean>;
+/**
+ * Check if branch is an agent branch with full result details.
+ *
+ * Same as isAgentBranch but returns the full AgentPatternResult
+ * for observability and debugging.
+ *
+ * @param branch - Branch name to check
+ * @returns Promise with match result and pattern resolution details
+ *
+ * @example
+ * ```typescript
+ * const result = await isAgentBranchWithDetails('claude/session-123');
+ * if (result.isMatch) {
+ *   console.log(`Matched via ${result.patternResult.source}`);
+ *   console.log(`Registry fetched: ${result.patternResult.registryFetched}`);
+ * }
+ * ```
+ */
+export declare function isAgentBranchWithDetails(branch: string | null | undefined): Promise<{
+    isMatch: boolean;
+    patternResult: AgentPatternResult;
+}>;
+/**
+ * Synchronous version of isAgentBranch for backwards compatibility.
+ *
+ * Uses only local config patterns or defaults - does NOT fetch from registry.
+ * Prefer async isAgentBranch() when possible.
+ *
+ * WU-1089: Updated to respect override and disable flags, but cannot fetch from registry.
  *
  * @param branch - Branch name to check
  * @returns True if branch matches agent patterns
+ *
+ * @deprecated Use async isAgentBranch() instead for registry support
  */
-export declare function isAgentBranch(branch: string | null | undefined): boolean;
+export declare function isAgentBranchSync(branch: string | null | undefined): boolean;
 /**
  * Check if headless mode is allowed (guarded).
  * Requires LUMENFLOW_HEADLESS=1 AND (LUMENFLOW_ADMIN=1 OR CI truthy OR GITHUB_ACTIONS truthy)