@quiltdata/benchling-webhook 0.6.3-20251104T182406Z → 0.7.1-20251106T100426Z

package/dist/lib/xdg-config.d.ts

@@ -1,28 +1,57 @@
 /**
- * XDG Configuration Management
+ * XDG Configuration Management (v0.7.0 - BREAKING CHANGE)
  *
- * Provides XDG-compliant configuration file management for the Benchling Webhook system.
- * Implements a three-file configuration model:
- * - User configuration: User-provided default settings
- * - Derived configuration: CLI-inferred configuration
- * - Deployment configuration: Deployment-specific artifacts
+ * Complete rewrite with NO backward compatibility with v0.6.x.
  *
- * Supports multiple named profiles (e.g., "default", "dev", "prod") for flexible configuration management.
+ * This module provides XDG-compliant configuration management for the Benchling Webhook system
+ * with a simplified, profile-first architecture:
+ *
+ * - Single unified configuration file per profile (`config.json`)
+ * - Per-profile deployment tracking (`deployments.json`)
+ * - Profile inheritance support with deep merging
+ * - Comprehensive validation and helpful error messages
+ *
+ * Directory Structure:
+ * ```
+ * ~/.config/benchling-webhook/
+ * ├── default/
+ * │   ├── config.json         # Profile configuration
+ * │   └── deployments.json    # Deployment history
+ * └── dev/
+ *     ├── config.json
+ *     └── deployments.json
+ * ```
  *
  * @module xdg-config
+ * @version 0.7.0
  */
-import { ConfigType, ProfileName, XDGConfigPaths, ConfigSet, ConfigProfile } from "./types/config";
-/**
- * Base configuration structure (for backward compatibility)
- */
-export interface BaseConfig {
-    [key: string]: unknown;
-}
-export type { ConfigType, XDGConfigPaths, ConfigSet };
+import { ProfileConfig, DeploymentHistory, DeploymentRecord, ValidationResult } from "./types/config";
 /**
- * XDG Configuration Manager
+ * XDG Configuration Manager (v0.7.0)
+ *
+ * Manages profile-based configuration with deployment tracking.
+ * NO backward compatibility with v0.6.x configuration files.
  *
- * Manages XDG-compliant configuration files for the Benchling Webhook system.
+ * @example
+ * ```typescript
+ * const xdg = new XDGConfig();
+ *
+ * // Read profile configuration
+ * const config = xdg.readProfile("default");
+ *
+ * // Write profile configuration
+ * xdg.writeProfile("default", config);
+ *
+ * // Record deployment
+ * xdg.recordDeployment("default", {
+ *   stage: "prod",
+ *   timestamp: new Date().toISOString(),
+ *   imageTag: "0.7.0",
+ *   endpoint: "https://...",
+ *   stackName: "BenchlingWebhookStack",
+ *   region: "us-east-1"
+ * });
+ * ```
  */
 export declare class XDGConfig {
     private readonly baseDir;
@@ -35,153 +64,242 @@ export declare class XDGConfig {
     /**
      * Gets the default XDG base directory
      *
-     * @returns The default base directory path
+     * Respects XDG_CONFIG_HOME environment variable per XDG Base Directory spec.
+     *
+     * @returns The default base directory path (~/.config/benchling-webhook or $XDG_CONFIG_HOME/benchling-webhook)
      */
     private getDefaultBaseDir;
     /**
-     * Expands home directory in a path
+     * Ensures the base configuration directory exists
      *
-     * @param path - Path potentially containing ~ for home directory
-     * @returns Expanded absolute path
+     * @throws {Error} If directory creation fails
      */
-    private static expandHomeDir;
+    private ensureBaseDirectoryExists;
     /**
-     * Gets the configuration file paths
+     * Reads configuration for a profile
      *
-     * @returns Object containing paths to all configuration files
-     */
-    static getPaths(): XDGConfigPaths;
-    /**
-     * Gets the configuration file paths for this instance
+     * @param profile - Profile name (e.g., "default", "dev", "prod")
+     * @returns Parsed configuration object
+     * @throws {Error} If profile not found or configuration is invalid
      *
-     * @returns Object containing paths to all configuration files
+     * @example
+     * ```typescript
+     * const config = xdg.readProfile("default");
+     * console.log(config.benchling.tenant);
+     * ```
      */
-    getPaths(): XDGConfigPaths;
+    readProfile(profile: string): ProfileConfig;
     /**
-     * Ensures all required configuration directories exist
+     * Writes configuration for a profile
      *
-     * Creates the base configuration directory and subdirectories if they don't exist.
+     * Creates the profile directory if it doesn't exist.
+     * Performs atomic write with automatic backup.
      *
-     * @throws {Error} If directory creation fails
-     */
-    ensureDirectories(): void;
-    /**
-     * Gets the file path for a specific configuration type
+     * @param profile - Profile name
+     * @param config - Configuration object to write
+     * @throws {Error} If validation fails or write operation fails
      *
-     * @param configType - Type of configuration to read
-     * @returns Absolute path to the configuration file
+     * @example
+     * ```typescript
+     * xdg.writeProfile("default", {
+     *   quilt: { ... },
+     *   benchling: { ... },
+     *   packages: { ... },
+     *   deployment: { ... },
+     *   _metadata: {
+     *     version: "0.7.0",
+     *     createdAt: new Date().toISOString(),
+     *     updatedAt: new Date().toISOString(),
+     *     source: "wizard"
+     *   }
+     * });
+     * ```
      */
-    private getConfigPath;
+    writeProfile(profile: string, config: ProfileConfig): void;
     /**
-     * Reads and parses a configuration file with schema validation
+     * Deletes a profile and all its files
      *
-     * @param configType - Type of configuration to read ("user", "derived", or "deploy")
-     * @returns Parsed configuration object
-     * @throws {Error} If file not found, invalid JSON, or schema validation fails
+     * 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
+     * xdg.deleteProfile("dev");
+     * ```
      */
-    readConfig(configType: ConfigType): BaseConfig;
+    deleteProfile(profile: string): void;
     /**
-     * Gets the backup file path for a configuration type
+     * Lists all available profiles
      *
-     * @param configType - Type of configuration
-     * @returns Backup file path
+     * @returns Array of profile names
+     *
+     * @example
+     * ```typescript
+     * const profiles = xdg.listProfiles();
+     * console.log(profiles); // ["default", "dev", "prod"]
+     * ```
      */
-    getBackupPath(configType: ConfigType): string;
+    listProfiles(): string[];
     /**
-     * Validates configuration against schema
+     * Checks if a profile exists
      *
-     * @param config - Configuration object to validate
-     * @throws {Error} If validation fails
+     * @param profile - Profile name to check
+     * @returns True if profile exists and has valid config.json, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (xdg.profileExists("dev")) {
+     *   const config = xdg.readProfile("dev");
+     * }
+     * ```
      */
-    private validateConfigSchema;
+    profileExists(profile: string): boolean;
     /**
-     * Writes a configuration file atomically with backup
+     * Gets deployment history for a profile
      *
-     * Uses a temporary file and rename operation for atomic writes.
-     * Creates a backup of the existing file before overwriting.
+     * Returns empty history if deployments.json doesn't exist.
      *
-     * @param configType - Type of configuration to write ("user", "derived", or "deploy")
-     * @param config - Configuration object to write
-     * @throws {Error} If validation fails or write operation fails
+     * @param profile - Profile name
+     * @returns Deployment history with active deployments and full history
+     *
+     * @example
+     * ```typescript
+     * const deployments = xdg.getDeployments("default");
+     * console.log(deployments.active["prod"]); // Active prod deployment
+     * console.log(deployments.history[0]); // Most recent deployment
+     * ```
      */
-    writeConfig(configType: ConfigType, config: BaseConfig): void;
+    getDeployments(profile: string): DeploymentHistory;
     /**
-     * Merges multiple configuration sources with priority order
+     * Records a new deployment for a profile
+     *
+     * Adds deployment to history and updates active deployment for the stage.
+     * Creates deployments.json if it doesn't exist.
      *
-     * Merges configurations in priority order (user → derived → deploy),
-     * where later configurations override earlier ones.
-     * Uses deep merge to handle nested objects.
+     * @param profile - Profile name
+     * @param deployment - Deployment record to add
      *
-     * @param configs - Configuration set to merge
-     * @returns Merged configuration object
+     * @example
+     * ```typescript
+     * xdg.recordDeployment("default", {
+     *   stage: "prod",
+     *   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"
+     * });
+     * ```
      */
-    mergeConfigs(configs: ConfigSet): BaseConfig;
+    recordDeployment(profile: string, deployment: DeploymentRecord): void;
     /**
-     * Gets the profile directory path
+     * Gets the active deployment for a specific stage
      *
-     * @param profileName - Profile name (defaults to "default")
-     * @returns Profile directory path
+     * @param profile - Profile name
+     * @param stage - Stage name (e.g., "dev", "prod")
+     * @returns Active deployment record for the stage, or null if none exists
+     *
+     * @example
+     * ```typescript
+     * const prodDeployment = xdg.getActiveDeployment("default", "prod");
+     * if (prodDeployment) {
+     *   console.log("Prod endpoint:", prodDeployment.endpoint);
+     * }
+     * ```
      */
-    getProfileDir(profileName?: ProfileName): string;
+    getActiveDeployment(profile: string, stage: string): DeploymentRecord | null;
     /**
-     * Gets configuration file paths for a specific profile
+     * 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 profileName - Profile name (defaults to "default")
-     * @returns Configuration file paths for the profile
+     * @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 = xdg.readProfileWithInheritance("dev");
+     * // Returns default config deep-merged with dev overrides
+     * ```
      */
-    getProfilePaths(profileName?: ProfileName): XDGConfigPaths;
+    readProfileWithInheritance(profile: string, baseProfile?: string): ProfileConfig;
     /**
-     * Ensures profile directories exist
+     * Internal recursive implementation of profile inheritance
      *
-     * @param profileName - Profile name (defaults to "default")
+     * @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
      */
-    ensureProfileDirectories(profileName?: ProfileName): void;
+    private readProfileWithInheritanceInternal;
     /**
-     * Lists all available profiles
+     * Deep merges two profile configurations
      *
-     * @returns Array of profile names
+     * 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
      */
-    listProfiles(): ProfileName[];
+    private deepMergeConfigs;
     /**
-     * Checks if a profile exists
+     * Validates a profile configuration against the schema
      *
-     * @param profileName - Profile name to check
-     * @returns True if profile exists, false otherwise
+     * @param config - Configuration object to validate
+     * @returns Validation result with errors and warnings
+     *
+     * @example
+     * ```typescript
+     * const validation = xdg.validateProfile(config);
+     * if (!validation.isValid) {
+     *   console.error("Validation errors:", validation.errors);
+     * }
+     * ```
      */
-    profileExists(profileName: ProfileName): boolean;
+    validateProfile(config: ProfileConfig): ValidationResult;
     /**
-     * Reads configuration for a specific profile
+     * Gets the directory path for a profile
      *
-     * @param configType - Type of configuration to read
-     * @param profileName - Profile name (defaults to "default")
-     * @returns Parsed configuration object
-     * @throws {Error} If file not found or validation fails
+     * @param profile - Profile name
+     * @returns Absolute path to profile directory
      */
-    readProfileConfig(configType: ConfigType, profileName?: ProfileName): BaseConfig;
+    private getProfileDir;
     /**
-     * Writes configuration for a specific profile
+     * Gets the config.json path for a profile
      *
-     * @param configType - Type of configuration to write
-     * @param config - Configuration object to write
-     * @param profileName - Profile name (defaults to "default")
-     * @throws {Error} If validation fails or write operation fails
+     * @param profile - Profile name
+     * @returns Absolute path to config.json
      */
-    writeProfileConfig(configType: ConfigType, config: BaseConfig, profileName?: ProfileName): void;
+    private getProfileConfigPath;
     /**
-     * Loads a complete profile with all configuration files
+     * Gets the deployments.json path for a profile
      *
-     * @param profileName - Profile name (defaults to "default")
-     * @returns Complete profile configuration
+     * @param profile - Profile name
+     * @returns Absolute path to deployments.json
      */
-    loadProfile(profileName?: ProfileName): ConfigProfile;
+    private getProfileDeploymentsPath;
     /**
-     * Deletes a profile and all its configuration files
+     * Builds a helpful error message when a profile is not found
      *
-     * WARNING: This is a destructive operation!
+     * Detects legacy v0.6.x configuration files and provides upgrade guidance.
      *
-     * @param profileName - Profile name to delete
-     * @throws {Error} If attempting to delete the default profile or if deletion fails
+     * @param profile - Profile name that was not found
+     * @returns Formatted error message
      */
-    deleteProfile(profileName: ProfileName): void;
+    private buildProfileNotFoundError;
 }
 //# sourceMappingURL=xdg-config.d.ts.map

package/dist/lib/xdg-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xdg-config.d.ts","sourceRoot":"","sources":["../../lib/xdg-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,OAAO,EAIH,UAAU,EACV,WAAW,EACX,cAAc,EACd,SAAS,EACT,aAAa,EAChB,MAAM,gBAAgB,CAAC;AAExB;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAGD,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,SAAS,EAAE,CAAC;AAyDtD;;;;GAIG;AACH,qBAAa,SAAS;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;;OAIG;gBACS,OAAO,CAAC,EAAE,MAAM;IAI5B;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAKzB;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAK5B;;;;OAIG;WACW,QAAQ,IAAI,cAAc;IAWxC;;;;OAIG;IACI,QAAQ,IAAI,cAAc;IAQjC;;;;;;OAMG;IACI,iBAAiB,IAAI,IAAI;IAmBhC;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAcrB;;;;;;OAMG;IACI,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU;IAqCrD;;;;;OAKG;IACI,aAAa,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM;IAKpD;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAW5B;;;;;;;;;OASG;IACI,WAAW,CAAC,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,UAAU,GAAG,IAAI;IA8CpE;;;;;;;;;OASG;IACI,YAAY,CAAC,OAAO,EAAE,SAAS,GAAG,UAAU;IAyBnD;;;;;OAKG;IACI,aAAa,CAAC,WAAW,GAAE,WAAuB,GAAG,MAAM;IAOlE;;;;;OAKG;IACI,eAAe,CAAC,WAAW,GAAE,WAAuB,GAAG,cAAc;IAU5E;;;;OAIG;IACI,wBAAwB,CAAC,WAAW,GAAE,WAAuB,GAAG,IAAI;IAqB3E;;;;OAIG;IACI,YAAY,IAAI,WAAW,EAAE;IAepC;;;;;OAKG;IACI,aAAa,CAAC,WAAW,EAAE,WAAW,GAAG,OAAO;IAKvD;;;;;;;OAOG;IACI,iBAAiB,CAAC,UAAU,EAAE,UAAU,EAAE,WAAW,GAAE,WAAuB,GAAG,UAAU;IA4ClG;;;;;;;OAOG;IACI,kBAAkB,CACrB,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,UAAU,EAClB,WAAW,GAAE,WAAuB,GACrC,IAAI;IAuDP;;;;;OAKG;IACI,WAAW,CAAC,WAAW,GAAE,WAAuB,GAAG,aAAa;IAqCvE;;;;;;;OAOG;IACI,aAAa,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI;CAevD"}
+{"version":3,"file":"xdg-config.d.ts","sourceRoot":"","sources":["../../lib/xdg-config.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAQH,OAAO,EACH,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAGnB,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,SAAS;IAClB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IAEjC;;;;OAIG;gBACS,OAAO,CAAC,EAAE,MAAM;IAK5B;;;;;;OAMG;IACH,OAAO,CAAC,iBAAiB;IASzB;;;;OAIG;IACH,OAAO,CAAC,yBAAyB;IAUjC;;;;;;;;;;;;OAYG;IACI,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa;IA8BlD;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACI,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI;IAqDjE;;;;;;;;;;;;;OAaG;IACI,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAiB3C;;;;;;;;;;OAUG;IACI,YAAY,IAAI,MAAM,EAAE;IAgB/B;;;;;;;;;;;;OAYG;IACI,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAS9C;;;;;;;;;;;;;;OAcG;IACI,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB;IAsCzD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACI,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,GAAG,IAAI;IAiE5E;;;;;;;;;;;;;;OAcG;IACI,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,gBAAgB,GAAG,IAAI;IAanF;;;;;;;;;;;;;;;;;;;OAmBG;IACI,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,aAAa;IAKvF;;;;;;;;OAQG;IACH,OAAO,CAAC,kCAAkC;IAoC1C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,gBAAgB;IAQxB;;;;;;;;;;;;;OAaG;IACI,eAAe,CAAC,MAAM,EAAE,aAAa,GAAG,gBAAgB;IA8B/D;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAIrB;;;;;OAKG;IACH,OAAO,CAAC,oBAAoB;IAI5B;;;;;OAKG;IACH,OAAO,CAAC,yBAAyB;IAQjC;;;;;;;OAOG;IACH,OAAO,CAAC,yBAAyB;CAsCpC"}