/** * XDG Base Abstract Class * * Abstract base class containing all shared business logic for configuration management. * Concrete implementations (XDGConfig, XDGTest) provide storage primitives. * * This separation allows: * - Shared validation, inheritance, and error handling logic in one place * - Multiple storage backends (filesystem, in-memory) with identical behavior * - Better test coverage by exercising business logic through both implementations * * @module xdg-base * @version 0.7.0 */ import { ProfileConfig, DeploymentHistory, DeploymentRecord, ValidationResult } from "./types/config"; import { IConfigStorage } from "./interfaces/config-storage"; /** * Abstract base class for XDG configuration management * * Implements IConfigStorage interface with all business logic. * Subclasses must implement abstract storage primitives for their specific storage mechanism. * * @abstract * @example * ```typescript * // Filesystem implementation * class XDGConfig extends XDGBase { * protected readProfileRaw(profile: string): ProfileConfig { * const data = readFileSync(this.getProfilePath(profile), "utf-8"); * return JSON.parse(data); * } * // ... other primitives * } * * // In-memory implementation * class XDGTest extends XDGBase { * private profiles = new Map(); * protected readProfileRaw(profile: string): ProfileConfig { * const config = this.profiles.get(profile); * if (!config) throw new Error(`Profile not found: ${profile}`); * return config; * } * // ... other primitives * } * ``` */ export declare abstract class XDGBase implements IConfigStorage { /** * Reads raw profile configuration without validation * * @param profile - Profile name * @returns Raw profile configuration * @throws {Error} If profile cannot be read */ protected abstract readProfileRaw(profile: string): ProfileConfig; /** * Writes raw profile configuration without validation * * @param profile - Profile name * @param config - Configuration to write * @throws {Error} If write fails */ protected abstract writeProfileRaw(profile: string, config: ProfileConfig): void; /** * Deletes profile and all associated data * * @param profile - Profile name * @throws {Error} If deletion fails */ protected abstract deleteProfileRaw(profile: string): void; /** * Lists all profile names * * @returns Array of profile names */ protected abstract listProfilesRaw(): string[]; /** * Checks if profile exists * * @param profile - Profile name * @returns True if profile exists */ protected abstract profileExistsRaw(profile: string): boolean; /** * Reads raw deployment history without validation * * @param profile - Profile name * @returns Deployment history or null if none exists * @throws {Error} If read fails */ protected abstract readDeploymentsRaw(profile: string): DeploymentHistory | null; /** * Writes raw deployment history without validation * * @param profile - Profile name * @param history - Deployment history to write * @throws {Error} If write fails */ protected abstract writeDeploymentsRaw(profile: string, history: DeploymentHistory): void; /** * Reads configuration for a profile with validation * * @param profile - Profile name (e.g., "default", "dev", "prod") * @returns Validated configuration object * @throws {Error} If profile not found or configuration is invalid * * @example * ```typescript * const config = storage.readProfile("default"); * console.log(config.benchling.tenant); * ``` */ readProfile(profile: string): ProfileConfig; /** * Writes configuration for a profile with validation * * Creates the profile if it doesn't exist. * * @param profile - Profile name * @param config - Configuration object to write * @throws {Error} If validation fails or write operation fails * * @example * ```typescript * storage.writeProfile("default", { * quilt: { ... }, * benchling: { ... }, * packages: { ... }, * deployment: { ... }, * _metadata: { * version: "0.7.0", * createdAt: new Date().toISOString(), * updatedAt: new Date().toISOString(), * source: "wizard" * } * }); * ``` */ writeProfile(profile: string, config: ProfileConfig): void; /** * Deletes a profile and all its data * * WARNING: This is a destructive operation! * Cannot delete the "default" profile. * * @param profile - Profile name to delete * @throws {Error} If attempting to delete default profile or if deletion fails * * @example * ```typescript * storage.deleteProfile("dev"); * ``` */ deleteProfile(profile: string): void; /** * Lists all available profiles * * @returns Array of profile names * * @example * ```typescript * const profiles = storage.listProfiles(); * console.log(profiles); // ["default", "dev", "prod"] * ``` */ listProfiles(): string[]; /** * Checks if a profile exists * * @param profile - Profile name to check * @returns True if profile exists and has valid configuration, false otherwise * * @example * ```typescript * if (storage.profileExists("dev")) { * const config = storage.readProfile("dev"); * } * ``` */ profileExists(profile: string): boolean; /** * Gets deployment history for a profile with validation * * Returns empty history if deployments don't exist. * * @param profile - Profile name * @returns Deployment history with active deployments and full history * * @example * ```typescript * const deployments = storage.getDeployments("default"); * console.log(deployments.active); // Active deployment * console.log(deployments.history[0]); // Most recent deployment * ``` */ getDeployments(profile: string): DeploymentHistory; /** * Records a new deployment for a profile * * Adds deployment to history and updates active deployment. * Creates deployment history if it doesn't exist. * * @param profile - Profile name * @param deployment - Deployment record to add * * @example * ```typescript * storage.recordDeployment("default", { * timestamp: new Date().toISOString(), * imageTag: "0.7.0", * endpoint: "https://abc123.execute-api.us-east-1.amazonaws.com/prod", * stackName: "BenchlingWebhookStack", * region: "us-east-1", * deployedBy: "ernest@example.com", * commit: "abc123f" * }); * ``` */ recordDeployment(profile: string, deployment: DeploymentRecord): void; /** * Gets the active deployment for a profile * * @param profile - Profile name * @returns Active deployment record, or null if none exists * * @example * ```typescript * const deployment = storage.getActiveDeployment("default"); * if (deployment) { * console.log("Endpoint:", deployment.endpoint); * } * ``` */ getActiveDeployment(profile: string): DeploymentRecord | null; /** * Clears the active deployment for a profile * * Removes the active deployment entry, but keeps the deployment history intact. * * @param profile - Profile name * * @example * ```typescript * // Clear deployment tracking after destroying the stack * storage.clearDeployment("default"); * ``` */ clearDeployment(profile: string): void; /** * Reads profile configuration with inheritance support * * If the profile has an `_inherits` field, loads the base profile first * and deep merges the current profile on top. * * Detects and prevents circular inheritance chains. * * @param profile - Profile name to read * @param baseProfile - Optional explicit base profile (overrides `_inherits`) * @returns Merged configuration with inheritance applied * @throws {Error} If circular inheritance is detected * * @example * ```typescript * // dev/config.json has "_inherits": "default" * const devConfig = storage.readProfileWithInheritance("dev"); * // Returns default config deep-merged with dev overrides * ``` */ readProfileWithInheritance(profile: string, baseProfile?: string): ProfileConfig; /** * Internal recursive implementation of profile inheritance * * @param profile - Current profile name * @param explicitBase - Explicitly specified base profile * @param visited - Set of visited profiles (for circular detection) * @returns Merged configuration * @throws {Error} If circular inheritance is detected */ private readProfileWithInheritanceInternal; /** * Deep merges two profile configurations * * Nested objects are merged recursively. * Arrays are replaced (not concatenated). * Current config takes precedence over base config. * * @param base - Base configuration * @param current - Current configuration (takes precedence) * @returns Merged configuration */ private deepMergeConfigs; /** * Validates a profile configuration against the schema * * @param config - Configuration object to validate * @returns Validation result with errors and warnings * * @example * ```typescript * const validation = storage.validateProfile(config); * if (!validation.isValid) { * console.error("Validation errors:", validation.errors); * } * ``` */ validateProfile(config: ProfileConfig): ValidationResult; /** * Builds a helpful error message when a profile is not found * * Subclasses can override this to add storage-specific detection * (e.g., legacy file detection for filesystem storage). * * @param profile - Profile name that was not found * @returns Formatted error message */ protected buildProfileNotFoundError(profile: string): string; } //# sourceMappingURL=xdg-base.d.ts.map