@fractary/faber-cli 1.4.4 → 1.5.0

package/dist/lib/yaml-config.js

@@ -0,0 +1,343 @@
+/**
+ * Unified YAML Configuration Loader for FABER CLI
+ *
+ * Loads and parses `.fractary/config.yaml` with environment variable substitution.
+ * Provides access to shared configuration for FABER and fractary-core plugins.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import Ajv from 'ajv';
+/**
+ * JSON Schema for validating UnifiedConfig structure
+ * Validates basic structure while allowing flexibility for plugin-specific sections
+ */
+const unifiedConfigSchema = {
+    type: 'object',
+    properties: {
+        version: { type: 'string' },
+        anthropic: {
+            type: 'object',
+            properties: {
+                api_key: { type: 'string' },
+                model: { type: 'string' },
+                max_tokens: { type: 'integer', minimum: 1 },
+            },
+            additionalProperties: false,
+        },
+        github: {
+            type: 'object',
+            properties: {
+                token: { type: 'string' },
+                organization: { type: 'string' },
+                project: { type: 'string' },
+                repo: { type: 'string' },
+                app: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        installation_id: { type: 'string' },
+                        private_key_path: { type: 'string' },
+                        private_key_env_var: { type: 'string' },
+                        created_via: { type: 'string', enum: ['manifest-flow', 'manual'] },
+                        created_at: { type: 'string' },
+                    },
+                    required: ['id', 'installation_id'],
+                    additionalProperties: false,
+                },
+            },
+            additionalProperties: false,
+        },
+        faber: {
+            type: 'object',
+            properties: {
+                worktree: {
+                    type: 'object',
+                    properties: {
+                        location: { type: 'string' },
+                        inherit_from_claude: { type: 'boolean' },
+                    },
+                    additionalProperties: false,
+                },
+                workflow: {
+                    type: 'object',
+                    properties: {
+                        default: { type: 'string' },
+                        config_path: { type: 'string' },
+                    },
+                    additionalProperties: false,
+                },
+                backlog_management: {
+                    type: 'object',
+                    properties: {
+                        default_limit: { type: 'integer', minimum: 1 },
+                        default_order_by: { type: 'string', enum: ['priority', 'created', 'updated', 'none'] },
+                        priority_config: {
+                            type: 'object',
+                            properties: {
+                                label_prefix: { type: 'string' },
+                            },
+                            additionalProperties: false,
+                        },
+                    },
+                    additionalProperties: false,
+                },
+            },
+            additionalProperties: false,
+        },
+        // Allow pass-through for other plugins
+        work: { type: 'object' },
+        repo: { type: 'object' },
+        logs: { type: 'object' },
+        file: { type: 'object' },
+        spec: { type: 'object' },
+        docs: { type: 'object' },
+    },
+    additionalProperties: true, // Allow unknown top-level keys for future extensibility
+};
+// Initialize Ajv validator
+const ajv = new Ajv({ allErrors: true, strict: false });
+const validateConfig = ajv.compile(unifiedConfigSchema);
+/**
+ * Load and parse `.fractary/config.yaml` with environment variable substitution
+ *
+ * @param options Configuration loading options
+ * @returns Parsed configuration object or null if not found
+ * @throws Error if config is invalid or throwIfMissing is true and file doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const config = loadYamlConfig();
+ * if (config?.github) {
+ *   console.log('GitHub config:', config.github);
+ * }
+ * ```
+ */
+export function loadYamlConfig(options = {}) {
+    const { projectRoot, warnMissingEnvVars = true, throwIfMissing = false, } = options;
+    const root = projectRoot || findProjectRoot();
+    const configPath = path.join(root, '.fractary', 'config.yaml');
+    if (!fs.existsSync(configPath)) {
+        if (throwIfMissing) {
+            throw new Error(`Configuration file not found at: ${configPath}\n` +
+                `Run 'fractary-core:init' or 'fractary-faber migrate' to create it.`);
+        }
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(configPath, 'utf-8');
+        const substituted = substituteEnvVars(content, warnMissingEnvVars);
+        const parsed = yaml.load(substituted);
+        // Validate basic structure
+        if (!parsed || typeof parsed !== 'object') {
+            throw new Error('Invalid configuration: must be a YAML object');
+        }
+        // Validate against JSON schema
+        const isValid = validateConfig(parsed);
+        if (!isValid && validateConfig.errors) {
+            const errorMessages = validateConfig.errors
+                .map(err => `  - ${err.instancePath || 'root'}: ${err.message}`)
+                .join('\n');
+            throw new Error(`Configuration validation failed:\n${errorMessages}`);
+        }
+        const config = parsed;
+        if (!config.version) {
+            console.warn(`Warning: Configuration missing version field in ${configPath}`);
+        }
+        return config;
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Failed to load config from ${configPath}: ${error.message}`);
+        }
+        throw error;
+    }
+}
+/**
+ * Write unified configuration to `.fractary/config.yaml`
+ *
+ * @param config Configuration object to write
+ * @param projectRoot Project root directory (auto-detected if not provided)
+ *
+ * @example
+ * ```typescript
+ * writeYamlConfig({
+ *   version: '2.0',
+ *   github: {
+ *     organization: 'myorg',
+ *     project: 'myrepo'
+ *   }
+ * });
+ * ```
+ */
+export function writeYamlConfig(config, projectRoot) {
+    const root = projectRoot || findProjectRoot();
+    const fractaryDir = path.join(root, '.fractary');
+    const configPath = path.join(fractaryDir, 'config.yaml');
+    // Ensure directory exists (atomic operation - no race condition)
+    // mkdirSync with recursive: true is safe even if directory already exists
+    fs.mkdirSync(fractaryDir, { recursive: true });
+    // Convert to YAML with proper formatting
+    const yamlContent = yaml.dump(config, {
+        indent: 2,
+        lineWidth: 100,
+        noRefs: true,
+        sortKeys: false,
+    });
+    fs.writeFileSync(configPath, yamlContent, 'utf-8');
+}
+/**
+ * Substitute ${ENV_VAR} placeholders with actual environment variables
+ *
+ * Supports:
+ * - ${VAR_NAME} - Replace with env var value
+ * - ${VAR_NAME:-default} - Replace with env var value or default if not set
+ *
+ * Security: Default values are limited to 1000 characters to prevent abuse.
+ * Variable names must match pattern: [A-Z_][A-Z0-9_]*
+ *
+ * @param content Content with environment variable placeholders
+ * @param warnMissing Whether to warn about missing environment variables
+ * @returns Content with substituted values
+ *
+ * @example
+ * ```typescript
+ * const content = 'token: ${GITHUB_TOKEN}';
+ * const result = substituteEnvVars(content);
+ * // result: 'token: ghp_xxxxx'
+ * ```
+ */
+export function substituteEnvVars(content, warnMissing = true) {
+    // Input validation
+    if (typeof content !== 'string') {
+        throw new TypeError('Content must be a string');
+    }
+    // Maximum length for default values to prevent abuse
+    const MAX_DEFAULT_LENGTH = 1000;
+    return content.replace(/\$\{([A-Z_][A-Z0-9_]*)(:-([^}]+))?\}/g, (match, varName, _, defaultValue) => {
+        // Validate variable name format
+        if (!/^[A-Z_][A-Z0-9_]*$/.test(varName)) {
+            console.warn(`Warning: Invalid environment variable name: ${varName}`);
+            return match;
+        }
+        const value = process.env[varName];
+        if (value !== undefined) {
+            return value;
+        }
+        if (defaultValue !== undefined) {
+            // Validate default value length
+            if (defaultValue.length > MAX_DEFAULT_LENGTH) {
+                console.warn(`Warning: Default value for ${varName} exceeds maximum length (${MAX_DEFAULT_LENGTH} chars). ` +
+                    `Truncating to prevent abuse.`);
+                return defaultValue.substring(0, MAX_DEFAULT_LENGTH);
+            }
+            return defaultValue;
+        }
+        if (warnMissing) {
+            console.warn(`Warning: Environment variable ${varName} not set. ` +
+                `Using placeholder value.`);
+        }
+        // Keep original placeholder if no value found
+        return match;
+    });
+}
+/**
+ * Find project root by looking for .fractary directory or .git
+ *
+ * Walks up the directory tree from startDir until it finds:
+ * - A directory containing `.fractary/`
+ * - A directory containing `.git/`
+ * - The filesystem root
+ *
+ * Security: Normalizes paths and prevents traversal outside filesystem boundaries.
+ * Maximum of 100 directory levels to prevent infinite loops.
+ *
+ * @param startDir Directory to start searching from (default: current working directory)
+ * @returns Project root directory (normalized absolute path)
+ */
+export function findProjectRoot(startDir = process.cwd()) {
+    // Input validation and normalization
+    if (typeof startDir !== 'string') {
+        throw new TypeError('startDir must be a string');
+    }
+    // Normalize and resolve to absolute path to prevent path traversal
+    let currentDir = path.resolve(path.normalize(startDir));
+    // Get filesystem root for comparison
+    const fsRoot = path.parse(currentDir).root;
+    // Safety limit: maximum 100 directory levels to prevent infinite loops
+    const MAX_LEVELS = 100;
+    let levels = 0;
+    while (currentDir !== fsRoot && levels < MAX_LEVELS) {
+        try {
+            // Check for .fractary directory
+            if (fs.existsSync(path.join(currentDir, '.fractary'))) {
+                return currentDir;
+            }
+            // Check for .git directory
+            if (fs.existsSync(path.join(currentDir, '.git'))) {
+                return currentDir;
+            }
+            // Move up one directory
+            const parentDir = path.dirname(currentDir);
+            // Safety check: ensure we're actually moving up
+            if (parentDir === currentDir) {
+                // Reached filesystem root
+                break;
+            }
+            currentDir = parentDir;
+            levels++;
+        }
+        catch (error) {
+            // Handle permission errors or invalid paths gracefully
+            console.warn(`Warning: Error accessing directory ${currentDir}: ${error}`);
+            break;
+        }
+    }
+    if (levels >= MAX_LEVELS) {
+        console.warn(`Warning: Exceeded maximum directory depth (${MAX_LEVELS} levels) while searching for project root`);
+    }
+    // If no marker found, return the normalized starting directory
+    return path.resolve(path.normalize(startDir));
+}
+/**
+ * Check if a valid configuration file exists
+ *
+ * @param projectRoot Project root directory (auto-detected if not provided)
+ * @returns true if config exists at .fractary/config.yaml
+ */
+export function configExists(projectRoot) {
+    const root = projectRoot || findProjectRoot();
+    const configPath = path.join(root, '.fractary', 'config.yaml');
+    return fs.existsSync(configPath);
+}
+/**
+ * Get the configuration file path
+ *
+ * @param projectRoot Project root directory (auto-detected if not provided)
+ * @returns Full path to configuration file
+ */
+export function getConfigPath(projectRoot) {
+    const root = projectRoot || findProjectRoot();
+    return path.join(root, '.fractary', 'config.yaml');
+}
+/**
+ * Check if old settings.json exists (for migration)
+ *
+ * @param projectRoot Project root directory (auto-detected if not provided)
+ * @returns true if old settings.json exists
+ */
+export function oldSettingsExists(projectRoot) {
+    const root = projectRoot || findProjectRoot();
+    const settingsPath = path.join(root, '.fractary', 'settings.json');
+    return fs.existsSync(settingsPath);
+}
+/**
+ * Get the old settings.json file path
+ *
+ * @param projectRoot Project root directory (auto-detected if not provided)
+ * @returns Full path to old settings.json file
+ */
+export function getOldSettingsPath(projectRoot) {
+    const root = projectRoot || findProjectRoot();
+    return path.join(root, '.fractary', 'settings.json');
+}

package/dist/types/config.d.ts

@@ -2,9 +2,15 @@
  * FABER CLI Configuration Types
  *
  * Type definitions for configuration objects
+ * Version 2.0: Unified configuration with shared authentication
+ */
+/**
+ * Anthropic API configuration (shared across all tools)
  */
 export interface AnthropicConfig {
     api_key?: string;
+    model?: string;
+    max_tokens?: number;
 }
 /**
  * GitHub App authentication configuration
@@ -17,6 +23,9 @@ export interface GitHubAppConfig {
     created_via?: 'manifest-flow' | 'manual';
     created_at?: string;
 }
+/**
+ * GitHub authentication configuration (shared across all tools)
+ */
 export interface GitHubConfig {
     token?: string;
     organization?: string;
@@ -39,7 +48,45 @@ export interface BacklogManagementConfig {
         label_prefix?: string;
     };
 }
+/**
+ * FABER-specific configuration (v2.0: only FABER-specific settings)
+ * Note: anthropic and github are now at the top level of UnifiedConfig
+ */
 export interface FaberConfig {
+    worktree?: WorktreeConfig;
+    workflow?: WorkflowConfig;
+    backlog_management?: BacklogManagementConfig;
+}
+/**
+ * Loaded FABER configuration including shared authentication
+ * This is what ConfigManager.load() returns - combines FABER-specific
+ * settings with shared anthropic/github configuration
+ */
+export type LoadedFaberConfig = FaberConfig & {
+    anthropic?: AnthropicConfig;
+    github?: GitHubConfig;
+};
+/**
+ * Unified configuration structure (v2.0)
+ * Single source of truth shared across FABER and fractary-core plugins
+ */
+export interface UnifiedConfig {
+    version: string;
+    anthropic?: AnthropicConfig;
+    github?: GitHubConfig;
+    faber?: FaberConfig;
+    work?: any;
+    repo?: any;
+    logs?: any;
+    file?: any;
+    spec?: any;
+    docs?: any;
+}
+/**
+ * Legacy configuration structure (v1.x - deprecated)
+ * Kept for backward compatibility during migration
+ */
+export interface LegacyFaberConfig {
     anthropic?: AnthropicConfig;
     github?: GitHubConfig;
     worktree?: WorktreeConfig;
@@ -51,4 +98,15 @@ export interface ClaudeConfig {
         directory?: string;
     };
 }
+/**
+ * Options for loading YAML configuration
+ */
+export interface ConfigLoadOptions {
+    /** Project root directory (auto-detected if not provided) */
+    projectRoot?: string;
+    /** Warn about missing environment variables (default: true) */
+    warnMissingEnvVars?: boolean;
+    /** Throw error if config file doesn't exist (default: false) */
+    throwIfMissing?: boolean;
+}
 //# sourceMappingURL=config.d.ts.map

package/dist/types/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,eAAe,GAAG,QAAQ,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,eAAe,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAC/D,eAAe,CAAC,EAAE;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;CAC9C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE;QACT,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,WAAW,CAAC,EAAE,eAAe,GAAG,QAAQ,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,eAAe,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gBAAgB,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAC/D,eAAe,CAAC,EAAE;QAChB,YAAY,CAAC,EAAE,MAAM,CAAC;KACvB,CAAC;CACH;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;CAC9C;AAED;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG;IAC5C,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,IAAI,CAAC,EAAE,GAAG,CAAC;CACZ;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,kBAAkB,CAAC,EAAE,uBAAuB,CAAC;CAC9C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE;QACT,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,+DAA+D;IAC/D,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,gEAAgE;IAChE,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B"}

package/dist/types/config.js

@@ -2,5 +2,6 @@
  * FABER CLI Configuration Types
  *
  * Type definitions for configuration objects
+ * Version 2.0: Unified configuration with shared authentication
  */
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fractary/faber-cli",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "description": "FABER CLI - Command-line interface for FABER development toolkit",
   "main": "dist/index.js",
   "bin": {
@@ -37,14 +37,16 @@
   },
   "dependencies": {
     "@fractary/core": "^0.2.0",
-    "@fractary/faber": "^2.1.1",
+    "@fractary/faber": "^2.1.2",
     "ajv": "^8.12.0",
     "chalk": "^5.0.0",
     "commander": "^12.0.0",
+    "js-yaml": "^4.1.0",
     "jsonwebtoken": "^9.0.0"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/jsonwebtoken": "^9.0.0",
     "@types/node": "^20.19.26",
     "@typescript-eslint/eslint-plugin": "^6.19.0",