@lumenflow/core 1.0.0

package/dist/lumenflow-config-schema.d.ts

@@ -0,0 +1,272 @@
+/**
+ * LumenFlow Configuration Schema
+ *
+ * Zod schemas for LumenFlow configuration.
+ * All paths and settings are configurable via .lumenflow.config.yaml
+ *
+ * @module lumenflow-config-schema
+ */
+import { z } from 'zod';
+/**
+ * Directory paths configuration
+ */
+export declare const DirectoriesSchema: z.ZodObject<{
+    appsWeb: z.ZodDefault<z.ZodString>;
+    worktrees: z.ZodDefault<z.ZodString>;
+    ai: z.ZodDefault<z.ZodString>;
+    claude: z.ZodDefault<z.ZodString>;
+    docs: z.ZodDefault<z.ZodString>;
+    packages: z.ZodDefault<z.ZodString>;
+    tools: z.ZodDefault<z.ZodString>;
+    memoryBank: z.ZodDefault<z.ZodString>;
+    wuDir: z.ZodDefault<z.ZodString>;
+    initiativesDir: z.ZodDefault<z.ZodString>;
+    backlogPath: z.ZodDefault<z.ZodString>;
+    statusPath: z.ZodDefault<z.ZodString>;
+    skillsDir: z.ZodDefault<z.ZodString>;
+    agentsDir: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Beacon paths configuration (.beacon directory structure)
+ */
+export declare const BeaconPathsSchema: z.ZodObject<{
+    base: z.ZodDefault<z.ZodString>;
+    stateDir: z.ZodDefault<z.ZodString>;
+    stampsDir: z.ZodDefault<z.ZodString>;
+    mergeLock: z.ZodDefault<z.ZodString>;
+    telemetry: z.ZodDefault<z.ZodString>;
+    flowLog: z.ZodDefault<z.ZodString>;
+    sessions: z.ZodDefault<z.ZodString>;
+    incidents: z.ZodDefault<z.ZodString>;
+    commandsLog: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Git configuration
+ */
+export declare const GitConfigSchema: z.ZodObject<{
+    mainBranch: z.ZodDefault<z.ZodString>;
+    defaultRemote: z.ZodDefault<z.ZodString>;
+    laneBranchPrefix: z.ZodDefault<z.ZodString>;
+    tempBranchPrefix: z.ZodDefault<z.ZodString>;
+    realGitPath: z.ZodDefault<z.ZodString>;
+    maxBranchDrift: z.ZodDefault<z.ZodNumber>;
+    branchDriftWarning: z.ZodDefault<z.ZodNumber>;
+    branchDriftInfo: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * WU (Work Unit) configuration
+ */
+export declare const WuConfigSchema: z.ZodObject<{
+    idPattern: z.ZodDefault<z.ZodString>;
+    minDescriptionLength: z.ZodDefault<z.ZodNumber>;
+    maxCommitSubject: z.ZodDefault<z.ZodNumber>;
+    defaultPriority: z.ZodDefault<z.ZodString>;
+    defaultStatus: z.ZodDefault<z.ZodString>;
+    defaultType: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Gates configuration
+ */
+export declare const GatesConfigSchema: z.ZodObject<{
+    maxEslintWarnings: z.ZodDefault<z.ZodNumber>;
+    enableCoverage: z.ZodDefault<z.ZodBoolean>;
+    minCoverage: z.ZodDefault<z.ZodNumber>;
+    enableSafetyCriticalTests: z.ZodDefault<z.ZodBoolean>;
+    enableInvariants: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * Memory layer configuration
+ */
+export declare const MemoryConfigSchema: z.ZodObject<{
+    directory: z.ZodDefault<z.ZodString>;
+    sessionTtl: z.ZodDefault<z.ZodNumber>;
+    checkpointTtl: z.ZodDefault<z.ZodNumber>;
+    enableAutoCleanup: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * UI configuration
+ */
+export declare const UiConfigSchema: z.ZodObject<{
+    errorBoxWidth: z.ZodDefault<z.ZodNumber>;
+    statusPreviewLines: z.ZodDefault<z.ZodNumber>;
+    readinessBoxWidth: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * YAML serialization configuration
+ */
+export declare const YamlConfigSchema: z.ZodObject<{
+    lineWidth: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Complete LumenFlow configuration schema
+ */
+export declare const LumenFlowConfigSchema: z.ZodObject<{
+    version: z.ZodDefault<z.ZodString>;
+    directories: z.ZodDefault<z.ZodObject<{
+        appsWeb: z.ZodDefault<z.ZodString>;
+        worktrees: z.ZodDefault<z.ZodString>;
+        ai: z.ZodDefault<z.ZodString>;
+        claude: z.ZodDefault<z.ZodString>;
+        docs: z.ZodDefault<z.ZodString>;
+        packages: z.ZodDefault<z.ZodString>;
+        tools: z.ZodDefault<z.ZodString>;
+        memoryBank: z.ZodDefault<z.ZodString>;
+        wuDir: z.ZodDefault<z.ZodString>;
+        initiativesDir: z.ZodDefault<z.ZodString>;
+        backlogPath: z.ZodDefault<z.ZodString>;
+        statusPath: z.ZodDefault<z.ZodString>;
+        skillsDir: z.ZodDefault<z.ZodString>;
+        agentsDir: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    beacon: z.ZodDefault<z.ZodObject<{
+        base: z.ZodDefault<z.ZodString>;
+        stateDir: z.ZodDefault<z.ZodString>;
+        stampsDir: z.ZodDefault<z.ZodString>;
+        mergeLock: z.ZodDefault<z.ZodString>;
+        telemetry: z.ZodDefault<z.ZodString>;
+        flowLog: z.ZodDefault<z.ZodString>;
+        sessions: z.ZodDefault<z.ZodString>;
+        incidents: z.ZodDefault<z.ZodString>;
+        commandsLog: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    git: z.ZodDefault<z.ZodObject<{
+        mainBranch: z.ZodDefault<z.ZodString>;
+        defaultRemote: z.ZodDefault<z.ZodString>;
+        laneBranchPrefix: z.ZodDefault<z.ZodString>;
+        tempBranchPrefix: z.ZodDefault<z.ZodString>;
+        realGitPath: z.ZodDefault<z.ZodString>;
+        maxBranchDrift: z.ZodDefault<z.ZodNumber>;
+        branchDriftWarning: z.ZodDefault<z.ZodNumber>;
+        branchDriftInfo: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    wu: z.ZodDefault<z.ZodObject<{
+        idPattern: z.ZodDefault<z.ZodString>;
+        minDescriptionLength: z.ZodDefault<z.ZodNumber>;
+        maxCommitSubject: z.ZodDefault<z.ZodNumber>;
+        defaultPriority: z.ZodDefault<z.ZodString>;
+        defaultStatus: z.ZodDefault<z.ZodString>;
+        defaultType: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>>;
+    gates: z.ZodDefault<z.ZodObject<{
+        maxEslintWarnings: z.ZodDefault<z.ZodNumber>;
+        enableCoverage: z.ZodDefault<z.ZodBoolean>;
+        minCoverage: z.ZodDefault<z.ZodNumber>;
+        enableSafetyCriticalTests: z.ZodDefault<z.ZodBoolean>;
+        enableInvariants: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    memory: z.ZodDefault<z.ZodObject<{
+        directory: z.ZodDefault<z.ZodString>;
+        sessionTtl: z.ZodDefault<z.ZodNumber>;
+        checkpointTtl: z.ZodDefault<z.ZodNumber>;
+        enableAutoCleanup: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    ui: z.ZodDefault<z.ZodObject<{
+        errorBoxWidth: z.ZodDefault<z.ZodNumber>;
+        statusPreviewLines: z.ZodDefault<z.ZodNumber>;
+        readinessBoxWidth: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+    yaml: z.ZodDefault<z.ZodObject<{
+        lineWidth: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * TypeScript types inferred from schemas
+ */
+export type Directories = z.infer<typeof DirectoriesSchema>;
+export type BeaconPaths = z.infer<typeof BeaconPathsSchema>;
+export type GitConfig = z.infer<typeof GitConfigSchema>;
+export type WuConfig = z.infer<typeof WuConfigSchema>;
+export type GatesConfig = z.infer<typeof GatesConfigSchema>;
+export type MemoryConfig = z.infer<typeof MemoryConfigSchema>;
+export type UiConfig = z.infer<typeof UiConfigSchema>;
+export type YamlConfig = z.infer<typeof YamlConfigSchema>;
+export type LumenFlowConfig = z.infer<typeof LumenFlowConfigSchema>;
+/**
+ * Validate configuration data
+ *
+ * @param data - Configuration data to validate
+ * @returns Validation result with parsed config or errors
+ */
+export declare function validateConfig(data: unknown): z.ZodSafeParseResult<{
+    version: string;
+    directories: {
+        appsWeb: string;
+        worktrees: string;
+        ai: string;
+        claude: string;
+        docs: string;
+        packages: string;
+        tools: string;
+        memoryBank: string;
+        wuDir: string;
+        initiativesDir: string;
+        backlogPath: string;
+        statusPath: string;
+        skillsDir: string;
+        agentsDir: string;
+    };
+    beacon: {
+        base: string;
+        stateDir: string;
+        stampsDir: string;
+        mergeLock: string;
+        telemetry: string;
+        flowLog: string;
+        sessions: string;
+        incidents: string;
+        commandsLog: string;
+    };
+    git: {
+        mainBranch: string;
+        defaultRemote: string;
+        laneBranchPrefix: string;
+        tempBranchPrefix: string;
+        realGitPath: string;
+        maxBranchDrift: number;
+        branchDriftWarning: number;
+        branchDriftInfo: number;
+    };
+    wu: {
+        idPattern: string;
+        minDescriptionLength: number;
+        maxCommitSubject: number;
+        defaultPriority: string;
+        defaultStatus: string;
+        defaultType: string;
+    };
+    gates: {
+        maxEslintWarnings: number;
+        enableCoverage: boolean;
+        minCoverage: number;
+        enableSafetyCriticalTests: boolean;
+        enableInvariants: boolean;
+    };
+    memory: {
+        directory: string;
+        sessionTtl: number;
+        checkpointTtl: number;
+        enableAutoCleanup: boolean;
+    };
+    ui: {
+        errorBoxWidth: number;
+        statusPreviewLines: number;
+        readinessBoxWidth: number;
+    };
+    yaml: {
+        lineWidth: number;
+    };
+}>;
+/**
+ * Parse configuration with defaults
+ *
+ * @param data - Partial configuration data
+ * @returns Complete configuration with defaults applied
+ * @throws ZodError if validation fails
+ */
+export declare function parseConfig(data?: unknown): LumenFlowConfig;
+/**
+ * Get default configuration
+ *
+ * @returns Default LumenFlow configuration
+ */
+export declare function getDefaultConfig(): LumenFlowConfig;

package/dist/lumenflow-config-schema.js

@@ -0,0 +1,207 @@
+/**
+ * LumenFlow Configuration Schema
+ *
+ * Zod schemas for LumenFlow configuration.
+ * All paths and settings are configurable via .lumenflow.config.yaml
+ *
+ * @module lumenflow-config-schema
+ */
+import { z } from 'zod';
+/**
+ * Directory paths configuration
+ */
+export const DirectoriesSchema = z.object({
+    /** Working directory for web app (default: 'apps/web/') */
+    appsWeb: z.string().default('apps/web/'),
+    /** Worktrees directory (default: 'worktrees/') */
+    worktrees: z.string().default('worktrees/'),
+    /** AI assets directory (default: 'ai/') */
+    ai: z.string().default('ai/'),
+    /** Claude configuration directory (default: '.claude/') */
+    claude: z.string().default('.claude/'),
+    /** Documentation root (default: 'docs/') */
+    docs: z.string().default('docs/'),
+    /** Packages directory (default: 'packages/') */
+    packages: z.string().default('packages/'),
+    /** Tools directory (default: 'tools/') */
+    tools: z.string().default('tools/'),
+    /** Memory bank directory (default: 'memory-bank/') */
+    memoryBank: z.string().default('memory-bank/'),
+    /** WU YAML files directory (default: 'docs/04-operations/tasks/wu') */
+    wuDir: z.string().default('docs/04-operations/tasks/wu'),
+    /** Initiatives directory (default: 'docs/04-operations/tasks/initiatives') */
+    initiativesDir: z.string().default('docs/04-operations/tasks/initiatives'),
+    /** Backlog file path (default: 'docs/04-operations/tasks/backlog.md') */
+    backlogPath: z.string().default('docs/04-operations/tasks/backlog.md'),
+    /** Status file path (default: 'docs/04-operations/tasks/status.md') */
+    statusPath: z.string().default('docs/04-operations/tasks/status.md'),
+    /** Skills directory (default: '.claude/skills') */
+    skillsDir: z.string().default('.claude/skills'),
+    /** Agents directory (default: '.claude/agents') */
+    agentsDir: z.string().default('.claude/agents'),
+});
+/**
+ * Beacon paths configuration (.beacon directory structure)
+ */
+export const BeaconPathsSchema = z.object({
+    /** Base beacon directory (default: '.beacon') */
+    base: z.string().default('.beacon'),
+    /** State directory (default: '.beacon/state') */
+    stateDir: z.string().default('.beacon/state'),
+    /** Stamps directory (default: '.beacon/stamps') */
+    stampsDir: z.string().default('.beacon/stamps'),
+    /** Merge lock file (default: '.beacon/merge.lock') */
+    mergeLock: z.string().default('.beacon/merge.lock'),
+    /** Telemetry directory (default: '.beacon/telemetry') */
+    telemetry: z.string().default('.beacon/telemetry'),
+    /** Flow log file (default: '.beacon/flow.log') */
+    flowLog: z.string().default('.beacon/flow.log'),
+    /** Sessions directory (default: '.beacon/sessions') */
+    sessions: z.string().default('.beacon/sessions'),
+    /** Incidents directory (default: '.beacon/incidents') */
+    incidents: z.string().default('.beacon/incidents'),
+    /** Commands log file (default: '.beacon/commands.log') */
+    commandsLog: z.string().default('.beacon/commands.log'),
+});
+/**
+ * Git configuration
+ */
+export const GitConfigSchema = z.object({
+    /** Main branch name (default: 'main') */
+    mainBranch: z.string().default('main'),
+    /** Default remote name (default: 'origin') */
+    defaultRemote: z.string().default('origin'),
+    /** Lane branch prefix (default: 'lane/') */
+    laneBranchPrefix: z.string().default('lane/'),
+    /** Temporary branch prefix (default: 'tmp/') */
+    tempBranchPrefix: z.string().default('tmp/'),
+    /** Real git executable path (default: '/usr/bin/git') */
+    realGitPath: z.string().default('/usr/bin/git'),
+    /** Maximum commits behind main before requiring rebase */
+    maxBranchDrift: z.number().int().positive().default(20),
+    /** Warning threshold for branch drift */
+    branchDriftWarning: z.number().int().positive().default(15),
+    /** Info threshold for branch drift */
+    branchDriftInfo: z.number().int().positive().default(10),
+});
+/**
+ * WU (Work Unit) configuration
+ */
+export const WuConfigSchema = z.object({
+    /** WU ID pattern (regex string, default: '^WU-\\d+$') */
+    idPattern: z.string().default('^WU-\\d+$'),
+    /** Minimum description length (default: 50) */
+    minDescriptionLength: z.number().int().nonnegative().default(50),
+    /** Maximum commit subject length (default: 100) */
+    maxCommitSubject: z.number().int().positive().default(100),
+    /** Default priority (default: 'P2') */
+    defaultPriority: z.string().default('P2'),
+    /** Default status (default: 'ready') */
+    defaultStatus: z.string().default('ready'),
+    /** Default type (default: 'feature') */
+    defaultType: z.string().default('feature'),
+});
+/**
+ * Gates configuration
+ */
+export const GatesConfigSchema = z.object({
+    /** Maximum ESLint warnings allowed (default: 100) */
+    maxEslintWarnings: z.number().int().nonnegative().default(100),
+    /** Enable coverage gate (default: true) */
+    enableCoverage: z.boolean().default(true),
+    /** Minimum coverage percentage (default: 90) */
+    minCoverage: z.number().min(0).max(100).default(90),
+    /** Enable safety-critical tests (default: true) */
+    enableSafetyCriticalTests: z.boolean().default(true),
+    /** Enable invariants check (default: true) */
+    enableInvariants: z.boolean().default(true),
+});
+/**
+ * Memory layer configuration
+ */
+export const MemoryConfigSchema = z.object({
+    /** Memory directory (default: 'memory-bank/') */
+    directory: z.string().default('memory-bank/'),
+    /** Session TTL in milliseconds (default: 7 days) */
+    sessionTtl: z
+        .number()
+        .int()
+        .positive()
+        .default(7 * 24 * 60 * 60 * 1000),
+    /** Checkpoint TTL in milliseconds (default: 30 days) */
+    checkpointTtl: z
+        .number()
+        .int()
+        .positive()
+        .default(30 * 24 * 60 * 60 * 1000),
+    /** Enable auto-cleanup (default: true) */
+    enableAutoCleanup: z.boolean().default(true),
+});
+/**
+ * UI configuration
+ */
+export const UiConfigSchema = z.object({
+    /** Error box width (default: 70) */
+    errorBoxWidth: z.number().int().positive().default(70),
+    /** Status preview lines (default: 5) */
+    statusPreviewLines: z.number().int().positive().default(5),
+    /** Readiness box width (default: 50) */
+    readinessBoxWidth: z.number().int().positive().default(50),
+});
+/**
+ * YAML serialization configuration
+ */
+export const YamlConfigSchema = z.object({
+    /** Line width for YAML output (default: 100, -1 for no wrap) */
+    lineWidth: z.number().int().default(100),
+});
+/**
+ * Complete LumenFlow configuration schema
+ */
+export const LumenFlowConfigSchema = z.object({
+    /** Schema version for future migrations */
+    version: z.string().default('1.0.0'),
+    /** Directory paths */
+    directories: DirectoriesSchema.default(() => DirectoriesSchema.parse({})),
+    /** Beacon paths */
+    beacon: BeaconPathsSchema.default(() => BeaconPathsSchema.parse({})),
+    /** Git configuration */
+    git: GitConfigSchema.default(() => GitConfigSchema.parse({})),
+    /** WU configuration */
+    wu: WuConfigSchema.default(() => WuConfigSchema.parse({})),
+    /** Gates configuration */
+    gates: GatesConfigSchema.default(() => GatesConfigSchema.parse({})),
+    /** Memory layer configuration */
+    memory: MemoryConfigSchema.default(() => MemoryConfigSchema.parse({})),
+    /** UI configuration */
+    ui: UiConfigSchema.default(() => UiConfigSchema.parse({})),
+    /** YAML configuration */
+    yaml: YamlConfigSchema.default(() => YamlConfigSchema.parse({})),
+});
+/**
+ * Validate configuration data
+ *
+ * @param data - Configuration data to validate
+ * @returns Validation result with parsed config or errors
+ */
+export function validateConfig(data) {
+    return LumenFlowConfigSchema.safeParse(data);
+}
+/**
+ * Parse configuration with defaults
+ *
+ * @param data - Partial configuration data
+ * @returns Complete configuration with defaults applied
+ * @throws ZodError if validation fails
+ */
+export function parseConfig(data = {}) {
+    return LumenFlowConfigSchema.parse(data);
+}
+/**
+ * Get default configuration
+ *
+ * @returns Default LumenFlow configuration
+ */
+export function getDefaultConfig() {
+    return LumenFlowConfigSchema.parse({});
+}

package/dist/lumenflow-config.d.ts

@@ -0,0 +1,95 @@
+/**
+ * LumenFlow Configuration Loader
+ *
+ * Loads and manages LumenFlow configuration from .lumenflow.config.yaml
+ * Falls back to sensible defaults if no config file exists.
+ *
+ * @module lumenflow-config
+ */
+import { type LumenFlowConfig } from './lumenflow-config-schema.js';
+/**
+ * Find project root by looking for .lumenflow.config.yaml or .git
+ *
+ * @param startDir - Directory to start searching from
+ * @returns Project root path or current working directory
+ */
+export declare function findProjectRoot(startDir?: string): string;
+/**
+ * Get LumenFlow configuration
+ *
+ * Loads config from .lumenflow.config.yaml if present, otherwise uses defaults.
+ * Configuration is cached for performance.
+ *
+ * @param options - Options for loading config
+ * @param options.projectRoot - Override project root detection
+ * @param options.reload - Force reload from disk (bypass cache)
+ * @returns LumenFlow configuration
+ */
+export declare function getConfig(options?: {
+    projectRoot?: string;
+    reload?: boolean;
+}): LumenFlowConfig;
+/**
+ * Get the project root directory
+ *
+ * @returns Cached project root or finds it
+ */
+export declare function getProjectRoot(): string;
+/**
+ * Clear cached configuration
+ *
+ * Useful for testing or when config file changes
+ */
+export declare function clearConfigCache(): void;
+/**
+ * Resolve a path relative to project root
+ *
+ * @param relativePath - Relative path from config
+ * @param projectRoot - Optional project root override
+ * @returns Absolute path
+ */
+export declare function resolvePath(relativePath: string, projectRoot?: string): string;
+/**
+ * Get resolved paths for common directories
+ *
+ * Convenience function that resolves all directory paths to absolute paths
+ *
+ * @param options - Options
+ * @param options.projectRoot - Override project root
+ * @returns Object with absolute paths
+ */
+export declare function getResolvedPaths(options?: {
+    projectRoot?: string;
+}): {
+    wuDir: string;
+    initiativesDir: string;
+    backlogPath: string;
+    statusPath: string;
+    worktrees: string;
+    stampsDir: string;
+    stateDir: string;
+    skillsDir: string;
+    agentsDir: string;
+    memoryBank: string;
+};
+/**
+ * Validate a config file
+ *
+ * @param configPath - Path to config file
+ * @returns Validation result
+ */
+export declare function validateConfigFile(configPath: string): {
+    valid: boolean;
+    errors: string[];
+    config?: LumenFlowConfig;
+};
+/**
+ * Create a sample config file
+ *
+ * @param outputPath - Path to write config file
+ * @param options - Options for sample config
+ */
+export declare function createSampleConfig(outputPath: string, options?: {
+    includeComments?: boolean;
+}): void;
+export type { LumenFlowConfig, Directories, BeaconPaths, GitConfig, WuConfig, GatesConfig, MemoryConfig, UiConfig, YamlConfig, } from './lumenflow-config-schema.js';