/**
 * Unified YAML Configuration Loader
 *
 * Loads and parses `.fractary/core/config.yaml` with environment variable substitution.
 * Provides a single source of truth for all plugin configurations.
 */
/**
 * Documentation URLs for each configuration section
 * These are injected as comments when writing config.yaml
 */
export declare const PLUGIN_DOC_URLS: Record<string, string>;
/**
 * URL for the main configuration guide
 */
export declare const CONFIG_GUIDE_URL = "https://github.com/fractary/core/blob/main/docs/guides/configuration.md";
/**
 * Work tracking configuration
 */
export interface WorkConfig {
    active_handler: string;
    handlers: Record<string, any>;
    defaults?: Record<string, any>;
    hooks?: Record<string, any>;
    advanced?: Record<string, any>;
}
/**
 * PR merge default options
 */
export interface PRMergeDefaults {
    /** Default merge strategy: 'squash', 'merge', or 'rebase' */
    strategy?: 'squash' | 'merge' | 'rebase';
    /** Whether to delete the branch after merge by default */
    delete_branch?: boolean;
}
/**
 * PR configuration defaults
 */
export interface PRDefaults {
    template?: string;
    require_work_id?: boolean;
    auto_link_issues?: boolean;
    ci_polling?: {
        enabled?: boolean;
        interval_seconds?: number;
        timeout_seconds?: number;
        initial_delay_seconds?: number;
    };
    /** Default options for PR merge operations */
    merge?: PRMergeDefaults;
}
/**
 * Environment branch configuration
 *
 * Maps an environment to its corresponding branch and protection settings.
 */
export interface EnvironmentBranch {
    /** The git branch name for this environment */
    branch: string;
    /** Whether the branch is protected (requires approval for direct push) */
    protected?: boolean;
    /** Optional CI/CD deploy target name */
    deploy_target?: string;
}
/**
 * Repository defaults configuration
 */
export interface RepoDefaults {
    /** @deprecated Use environments + default_environment instead */
    default_branch?: string;
    /** Map of environment IDs to their branch configuration */
    environments?: Record<string, EnvironmentBranch>;
    /** Which environment is the default context (e.g., "production") */
    default_environment?: string;
    protected_branches?: string[];
    branch_naming?: Record<string, any>;
    commit_format?: string;
    require_signed_commits?: boolean;
    merge_strategy?: string;
    auto_delete_merged_branches?: boolean;
    remote?: Record<string, any>;
    push_sync_strategy?: string;
    pull_sync_strategy?: string;
    pr?: PRDefaults;
}
/**
 * Worktree configuration within the repo section of config.yaml
 */
export interface RepoWorktreeConfig {
    /** Relative path (from project root) where worktrees are created */
    location: string;
    /** Naming conventions for worktree directories */
    naming?: {
        /** Pattern when associated with a work item (e.g., "work-id-{id}") */
        with_work_id?: string;
        /** Strategy when no work ID: "random-words" */
        default?: string;
    };
}
/**
 * Repository management configuration
 */
export interface RepoConfig {
    active_handler: string;
    handlers: Record<string, any>;
    worktree?: RepoWorktreeConfig;
    defaults?: RepoDefaults;
    faber_integration?: Record<string, any>;
    hooks?: Record<string, any>;
    platform_specific?: Record<string, any>;
}
/**
 * Logs management configuration
 */
export interface LogsConfig {
    schema_version: string;
    /**
     * Path to custom log type templates manifest (local project overrides)
     * Falls back to core templates if not specified
     */
    custom_templates_path?: string;
    storage?: PluginStorage;
    retention?: Record<string, any>;
    session_logging?: Record<string, any>;
    auto_backup?: Record<string, any>;
    summarization?: Record<string, any>;
    archive?: Record<string, any>;
    search?: Record<string, any>;
    integration?: Record<string, any>;
    docs_integration?: Record<string, any>;
}
/**
 * Plugin file handler entry
 *
 * Maps a name (e.g. 'default' or a template name) to write and archive
 * file handler references. The referenced handlers are defined in the
 * file.handlers section and own the storage path/type configuration.
 */
export interface PluginFileHandler {
    /** Identifier: 'default' for the fallback, or a template/type name for overrides */
    name: string;
    /** Named file handler for write operations (references a key in file.handlers) */
    write: string;
    /** Named file handler for archive operations (references a key in file.handlers) */
    archive: string;
}
/**
 * Plugin storage configuration
 *
 * Shared storage shape used by logs and docs plugins.
 * Provides a list of file handler mappings where the first entry named
 * 'default' acts as the fallback and additional entries can override
 * handlers for specific templates or types.
 */
export interface PluginStorage {
    file_handlers: PluginFileHandler[];
}
/**
 * File storage source configuration (v2.0)
 */
export interface FileSource {
    type: string;
    bucket?: string;
    prefix?: string;
    region?: string;
    project_id?: string;
    local: {
        base_path: string;
    };
    push?: {
        compress?: boolean;
        keep_local?: boolean;
    };
    auth?: Record<string, any>;
}
/**
 * File storage configuration (supports both v1.0 and v2.0)
 */
export interface FileConfig {
    schema_version: string;
    handlers?: Record<string, FileSource>;
    global_settings?: Record<string, any>;
    active_handler?: string;
}
/**
 * Documentation management configuration
 */
export interface DocsConfig {
    schema_version: string;
    /**
     * Path to custom doc type templates manifest (local project overrides)
     * Falls back to core templates if not specified
     */
    custom_templates_path?: string;
    storage?: PluginStorage;
    hooks?: Record<string, any>;
    doc_types?: Record<string, any>;
    output_paths?: Record<string, any>;
    templates?: Record<string, any>;
    frontmatter?: Record<string, any>;
    validation?: Record<string, any>;
    linking?: Record<string, any>;
}
/**
 * Codex configuration for cross-project context
 */
export interface CodexConfig {
    schema_version: string;
    organization: string;
    project: string;
    dependencies?: Record<string, any>;
}
/**
 * Unified configuration structure for all Fractary Core plugins
 */
export interface CoreYamlConfig {
    version: string;
    work?: WorkConfig;
    repo?: RepoConfig;
    logs?: LogsConfig;
    file?: FileConfig;
    docs?: DocsConfig;
    codex?: CodexConfig;
}
/**
 * Configuration loading options
 */
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;
}
/**
 * Load and parse `.fractary/core/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?.work) {
 *   console.log('Work config:', config.work);
 * }
 * ```
 */
export declare function loadYamlConfig(options?: ConfigLoadOptions): CoreYamlConfig | null;
/**
 * Options for writing YAML configuration
 */
export interface WriteYamlConfigOptions {
    /** Project root directory (auto-detected if not provided) */
    projectRoot?: string;
    /** Include documentation URL comments for each section (default: true) */
    includeDocComments?: boolean;
}
/**
 * Inject documentation URL comments into YAML content
 *
 * Adds a comment with the documentation URL above each plugin section.
 * Also adds a header comment with the main configuration guide URL.
 *
 * @param yamlContent The raw YAML string
 * @param config The configuration object (used to determine which sections exist)
 * @returns YAML string with documentation comments injected
 */
export declare function injectDocumentationComments(yamlContent: string, config: CoreYamlConfig): string;
/**
 * Write unified configuration to `.fractary/config.yaml`
 *
 * @param config Configuration object to write
 * @param options Write options (projectRoot, includeDocComments)
 *
 * @example
 * ```typescript
 * writeYamlConfig({
 *   version: '2.0',
 *   work: {
 *     active_handler: 'github',
 *     handlers: { ... }
 *   }
 * });
 *
 * // Without documentation comments
 * writeYamlConfig(config, { includeDocComments: false });
 * ```
 */
export declare function writeYamlConfig(config: CoreYamlConfig, options?: WriteYamlConfigOptions | string): void;
/**
 * 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 declare function substituteEnvVars(content: string, warnMissing?: boolean): string;
/**
 * 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 declare function findProjectRoot(startDir?: string): string;
/**
 * Check if a valid configuration file exists
 *
 * @param projectRoot Project root directory (auto-detected if not provided)
 * @returns true if config exists at either new or old location
 */
export declare function configExists(projectRoot?: string): boolean;
/**
 * Get the configuration file path
 *
 * @param projectRoot Project root directory (auto-detected if not provided)
 * @returns Full path to configuration file (prefers new location)
 */
export declare function getConfigPath(projectRoot?: string): string;
/**
 * Get the .fractary/core directory path
 *
 * @param projectRoot Project root directory (auto-detected if not provided)
 * @returns Full path to .fractary/core directory
 */
export declare function getCoreDir(projectRoot?: string): string;
/**
 * Validate that environment variables referenced in config exist
 *
 * @param config Configuration object to validate
 * @returns Array of missing environment variable names
 */
export declare function validateEnvVars(config: CoreYamlConfig): string[];
//# sourceMappingURL=yaml-config.d.ts.map