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

package/dist/lib/xdg-config.js

@@ -1,16 +1,30 @@
 "use strict";
 /**
- * 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
  */
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
@@ -20,67 +34,36 @@ exports.XDGConfig = void 0;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
-const os_2 = require("os");
 const ajv_1 = __importDefault(require("ajv"));
+const ajv_formats_1 = __importDefault(require("ajv-formats"));
 const lodash_merge_1 = __importDefault(require("lodash.merge"));
+const config_1 = require("./types/config");
 /**
- * JSON Schema for configuration validation
- * This is a lenient schema that allows additional properties
- */
-const CONFIG_SCHEMA = {
-    type: "object",
-    properties: {
-        quiltCatalog: { type: "string" },
-        quiltUserBucket: { type: "string" },
-        quiltDatabase: { type: "string" },
-        quiltStackArn: { type: "string" },
-        quiltRegion: { type: "string" },
-        catalogUrl: { type: "string" },
-        benchlingTenant: { type: "string" },
-        benchlingClientId: { type: "string" },
-        benchlingClientSecret: { type: "string" },
-        benchlingAppDefinitionId: { type: "string" },
-        benchlingPkgBucket: { type: "string" },
-        benchlingTestEntry: { type: "string" },
-        benchlingSecret: { type: "string" },
-        benchlingSecrets: { type: "string" },
-        cdkAccount: { type: "string" },
-        cdkRegion: { type: "string" },
-        awsProfile: { type: "string" },
-        queueArn: { type: "string" },
-        pkgPrefix: { type: "string" },
-        pkgKey: { type: "string" },
-        logLevel: { type: "string" },
-        webhookAllowList: { type: "string" },
-        webhookEndpoint: { type: "string" },
-        enableWebhookVerification: { type: "string" },
-        createEcrRepository: { type: "string" },
-        ecrRepositoryName: { type: "string" },
-        imageTag: { type: "string" },
-        webhookUrl: { type: "string" },
-        deploymentTimestamp: { type: "string" },
-        deployedAt: { type: "string" },
-        stackArn: { type: "string" },
-        _metadata: {
-            type: "object",
-            properties: {
-                savedAt: { type: "string" },
-                source: { type: "string" },
-                version: { type: "string" },
-                inferredAt: { type: "string" },
-                inferredFrom: { type: "string" },
-                deployedBy: { type: "string" },
-                stackName: { type: "string" },
-            },
-            additionalProperties: true,
-        },
-    },
-    additionalProperties: true,
-};
-/**
- * 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"
+ * });
+ * ```
  */
 class XDGConfig {
     /**
@@ -90,108 +73,54 @@ class XDGConfig {
      */
     constructor(baseDir) {
         this.baseDir = baseDir || this.getDefaultBaseDir();
+        this.ensureBaseDirectoryExists();
     }
     /**
      * 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)
      */
     getDefaultBaseDir() {
+        const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+        if (xdgConfigHome) {
+            return (0, path_1.resolve)(xdgConfigHome, "benchling-webhook");
+        }
         const home = (0, os_1.homedir)();
         return (0, path_1.resolve)(home, ".config", "benchling-webhook");
     }
     /**
-     * Expands home directory in a path
-     *
-     * @param path - Path potentially containing ~ for home directory
-     * @returns Expanded absolute path
-     */
-    static expandHomeDir(path) {
-        const home = (0, os_1.homedir)();
-        return path.replace(/^~/, home);
-    }
-    /**
-     * Gets the configuration file paths
-     *
-     * @returns Object containing paths to all configuration files
-     */
-    static getPaths() {
-        const home = (0, os_1.homedir)();
-        const baseDir = (0, path_1.resolve)(home, ".config", "benchling-webhook");
-        return {
-            userConfig: (0, path_1.resolve)(baseDir, "default.json"),
-            derivedConfig: (0, path_1.resolve)(baseDir, "config", "default.json"),
-            deployConfig: (0, path_1.resolve)(baseDir, "deploy", "default.json"),
-        };
-    }
-    /**
-     * Gets the configuration file paths for this instance
-     *
-     * @returns Object containing paths to all configuration files
-     */
-    getPaths() {
-        return {
-            userConfig: (0, path_1.resolve)(this.baseDir, "default.json"),
-            derivedConfig: (0, path_1.resolve)(this.baseDir, "config", "default.json"),
-            deployConfig: (0, path_1.resolve)(this.baseDir, "deploy", "default.json"),
-        };
-    }
-    /**
-     * Ensures all required configuration directories exist
-     *
-     * Creates the base configuration directory and subdirectories if they don't exist.
+     * Ensures the base configuration directory exists
      *
      * @throws {Error} If directory creation fails
      */
-    ensureDirectories() {
-        // Create base directory
+    ensureBaseDirectoryExists() {
         if (!(0, fs_1.existsSync)(this.baseDir)) {
             (0, fs_1.mkdirSync)(this.baseDir, { recursive: true });
         }
-        // Create config subdirectory
-        const configDir = (0, path_1.resolve)(this.baseDir, "config");
-        if (!(0, fs_1.existsSync)(configDir)) {
-            (0, fs_1.mkdirSync)(configDir, { recursive: true });
-        }
-        // Create deploy subdirectory
-        const deployDir = (0, path_1.resolve)(this.baseDir, "deploy");
-        if (!(0, fs_1.existsSync)(deployDir)) {
-            (0, fs_1.mkdirSync)(deployDir, { recursive: true });
-        }
-    }
-    /**
-     * Gets the file path for a specific configuration type
-     *
-     * @param configType - Type of configuration to read
-     * @returns Absolute path to the configuration file
-     */
-    getConfigPath(configType) {
-        const paths = this.getPaths();
-        switch (configType) {
-            case "user":
-                return paths.userConfig;
-            case "derived":
-                return paths.derivedConfig;
-            case "deploy":
-                return paths.deployConfig;
-            default:
-                throw new Error(`Unknown configuration type: ${configType}`);
-        }
     }
+    // ====================================================================
+    // Configuration Management
+    // ====================================================================
     /**
-     * Reads and parses a configuration file with schema validation
+     * Reads configuration for a profile
      *
-     * @param configType - Type of configuration to read ("user", "derived", or "deploy")
+     * @param profile - Profile name (e.g., "default", "dev", "prod")
      * @returns Parsed configuration object
-     * @throws {Error} If file not found, invalid JSON, or schema validation fails
+     * @throws {Error} If profile not found or configuration is invalid
+     *
+     * @example
+     * ```typescript
+     * const config = xdg.readProfile("default");
+     * console.log(config.benchling.tenant);
+     * ```
      */
-    readConfig(configType) {
-        const configPath = this.getConfigPath(configType);
-        // Check if file exists
+    readProfile(profile) {
+        const configPath = this.getProfileConfigPath(profile);
         if (!(0, fs_1.existsSync)(configPath)) {
-            throw new Error(`Configuration file not found: ${configPath}`);
+            throw new Error(this.buildProfileNotFoundError(profile));
         }
-        // Read file content
         let fileContent;
         try {
             fileContent = (0, fs_1.readFileSync)(configPath, "utf-8");
@@ -199,7 +128,6 @@ class XDGConfig {
         catch (error) {
             throw new Error(`Failed to read configuration file: ${configPath}. ${error.message}`);
         }
-        // Parse JSON
         let config;
         try {
             config = JSON.parse(fileContent);
@@ -208,61 +136,52 @@ class XDGConfig {
             throw new Error(`Invalid JSON in configuration file: ${configPath}. ${error.message}`);
         }
         // Validate schema
-        const ajv = new ajv_1.default();
-        const validate = ajv.compile(CONFIG_SCHEMA);
-        const valid = validate(config);
-        if (!valid) {
-            const errors = validate.errors?.map((err) => `${err.instancePath} ${err.message}`).join(", ");
-            throw new Error(`Invalid configuration schema in ${configPath}: ${errors}`);
+        const validation = this.validateProfile(config);
+        if (!validation.isValid) {
+            throw new Error(`Invalid configuration in ${configPath}:\n${validation.errors.join("\n")}`);
         }
         return config;
     }
     /**
-     * Gets the backup file path for a configuration type
-     *
-     * @param configType - Type of configuration
-     * @returns Backup file path
-     */
-    getBackupPath(configType) {
-        const configPath = this.getConfigPath(configType);
-        return `${configPath}.backup`;
-    }
-    /**
-     * Validates configuration against schema
+     * Writes configuration for a profile
      *
-     * @param config - Configuration object to validate
-     * @throws {Error} If validation fails
-     */
-    validateConfigSchema(config) {
-        const ajv = new ajv_1.default();
-        const validate = ajv.compile(CONFIG_SCHEMA);
-        const valid = validate(config);
-        if (!valid) {
-            const errors = validate.errors?.map((err) => `${err.instancePath} ${err.message}`).join(", ");
-            throw new Error(`Invalid configuration schema: ${errors}`);
-        }
-    }
-    /**
-     * Writes a configuration file atomically with backup
+     * Creates the profile directory if it doesn't exist.
+     * Performs atomic write with automatic backup.
      *
-     * Uses a temporary file and rename operation for atomic writes.
-     * Creates a backup of the existing file before overwriting.
-     *
-     * @param configType - Type of configuration to write ("user", "derived", or "deploy")
+     * @param profile - Profile name
      * @param config - Configuration object to write
      * @throws {Error} If validation fails or write operation fails
+     *
+     * @example
+     * ```typescript
+     * xdg.writeProfile("default", {
+     *   quilt: { ... },
+     *   benchling: { ... },
+     *   packages: { ... },
+     *   deployment: { ... },
+     *   _metadata: {
+     *     version: "0.7.0",
+     *     createdAt: new Date().toISOString(),
+     *     updatedAt: new Date().toISOString(),
+     *     source: "wizard"
+     *   }
+     * });
+     * ```
      */
-    writeConfig(configType, config) {
+    writeProfile(profile, config) {
         // Validate configuration before writing
-        this.validateConfigSchema(config);
-        const configPath = this.getConfigPath(configType);
-        const backupPath = this.getBackupPath(configType);
-        const configDir = (0, path_1.dirname)(configPath);
-        // Ensure config directory exists first
-        if (!(0, fs_1.existsSync)(configDir)) {
-            (0, fs_1.mkdirSync)(configDir, { recursive: true });
-        }
-        // Create backup only if file already exists
+        const validation = this.validateProfile(config);
+        if (!validation.isValid) {
+            throw new Error(`Invalid configuration:\n${validation.errors.join("\n")}`);
+        }
+        // Ensure profile directory exists
+        const profileDir = this.getProfileDir(profile);
+        if (!(0, fs_1.existsSync)(profileDir)) {
+            (0, fs_1.mkdirSync)(profileDir, { recursive: true });
+        }
+        const configPath = this.getProfileConfigPath(profile);
+        const backupPath = `${configPath}.backup`;
+        // Create backup if file exists
         if ((0, fs_1.existsSync)(configPath)) {
             try {
                 (0, fs_1.copyFileSync)(configPath, backupPath);
@@ -272,7 +191,7 @@ class XDGConfig {
             }
         }
         // Write to temporary file first (atomic write)
-        const tempPath = (0, path_1.resolve)((0, os_2.tmpdir)(), `benchling-webhook-config-${Date.now()}.json`);
+        const tempPath = (0, path_1.join)(profileDir, `.config.json.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`);
         const configJson = JSON.stringify(config, null, 4);
         try {
             (0, fs_1.writeFileSync)(tempPath, configJson, "utf-8");
@@ -282,9 +201,10 @@ class XDGConfig {
             }
             catch {
                 // Fall back to copy+delete for cross-device scenarios (Windows)
-                // Ensure parent directory exists before copy (in case rename failed due to cross-device)
-                if (!(0, fs_1.existsSync)(configDir)) {
-                    (0, fs_1.mkdirSync)(configDir, { recursive: true });
+                // Ensure target directory exists before copying
+                const targetDir = (0, path_1.dirname)(configPath);
+                if (!(0, fs_1.existsSync)(targetDir)) {
+                    (0, fs_1.mkdirSync)(targetDir, { recursive: true });
                 }
                 (0, fs_1.copyFileSync)(tempPath, configPath);
                 (0, fs_1.unlinkSync)(tempPath);
@@ -295,271 +215,418 @@ class XDGConfig {
         }
     }
     /**
-     * Merges multiple configuration sources with priority order
+     * Deletes a profile and all its files
      *
-     * Merges configurations in priority order (user → derived → deploy),
-     * where later configurations override earlier ones.
-     * Uses deep merge to handle nested objects.
+     * WARNING: This is a destructive operation!
+     * Cannot delete the "default" profile.
      *
-     * @param configs - Configuration set to merge
-     * @returns Merged configuration object
-     */
-    mergeConfigs(configs) {
-        // Start with empty config
-        let merged = {};
-        // Merge in priority order: user → derived → deploy
-        // Each subsequent config overrides previous values
-        if (configs.user) {
-            merged = (0, lodash_merge_1.default)({}, merged, configs.user);
-        }
-        if (configs.derived) {
-            merged = (0, lodash_merge_1.default)({}, merged, configs.derived);
-        }
-        if (configs.deploy) {
-            merged = (0, lodash_merge_1.default)({}, merged, configs.deploy);
-        }
-        return merged;
-    }
-    // ====================================================================
-    // Profile Management Methods (Phase 1.1)
-    // ====================================================================
-    /**
-     * Gets the profile directory path
+     * @param profile - Profile name to delete
+     * @throws {Error} If attempting to delete default profile or if deletion fails
      *
-     * @param profileName - Profile name (defaults to "default")
-     * @returns Profile directory path
+     * @example
+     * ```typescript
+     * xdg.deleteProfile("dev");
+     * ```
      */
-    getProfileDir(profileName = "default") {
-        if (profileName === "default") {
-            return this.baseDir;
+    deleteProfile(profile) {
+        if (profile === "default") {
+            throw new Error("Cannot delete the default profile");
         }
-        return (0, path_1.resolve)(this.baseDir, "profiles", profileName);
-    }
-    /**
-     * Gets configuration file paths for a specific profile
-     *
-     * @param profileName - Profile name (defaults to "default")
-     * @returns Configuration file paths for the profile
-     */
-    getProfilePaths(profileName = "default") {
-        const profileDir = this.getProfileDir(profileName);
-        return {
-            userConfig: (0, path_1.resolve)(profileDir, "default.json"),
-            derivedConfig: (0, path_1.resolve)(profileDir, "config", "default.json"),
-            deployConfig: (0, path_1.resolve)(profileDir, "deploy", "default.json"),
-        };
-    }
-    /**
-     * Ensures profile directories exist
-     *
-     * @param profileName - Profile name (defaults to "default")
-     */
-    ensureProfileDirectories(profileName = "default") {
-        const profileDir = this.getProfileDir(profileName);
-        // Create profile directory
+        const profileDir = this.getProfileDir(profile);
         if (!(0, fs_1.existsSync)(profileDir)) {
-            (0, fs_1.mkdirSync)(profileDir, { recursive: true });
+            throw new Error(`Profile does not exist: ${profile}`);
         }
-        // Create config subdirectory
-        const configDir = (0, path_1.resolve)(profileDir, "config");
-        if (!(0, fs_1.existsSync)(configDir)) {
-            (0, fs_1.mkdirSync)(configDir, { recursive: true });
+        try {
+            (0, fs_1.rmSync)(profileDir, { recursive: true, force: true });
         }
-        // Create deploy subdirectory
-        const deployDir = (0, path_1.resolve)(profileDir, "deploy");
-        if (!(0, fs_1.existsSync)(deployDir)) {
-            (0, fs_1.mkdirSync)(deployDir, { recursive: true });
+        catch (error) {
+            throw new Error(`Failed to delete profile: ${error.message}`);
         }
     }
     /**
      * Lists all available profiles
      *
      * @returns Array of profile names
+     *
+     * @example
+     * ```typescript
+     * const profiles = xdg.listProfiles();
+     * console.log(profiles); // ["default", "dev", "prod"]
+     * ```
      */
     listProfiles() {
-        const profiles = ["default"];
-        const profilesDir = (0, path_1.resolve)(this.baseDir, "profiles");
-        if ((0, fs_1.existsSync)(profilesDir)) {
-            const entries = (0, fs_1.readdirSync)(profilesDir, { withFileTypes: true });
-            const profileDirs = entries
-                .filter((entry) => entry.isDirectory())
-                .map((entry) => entry.name);
-            profiles.push(...profileDirs);
-        }
-        return profiles;
+        if (!(0, fs_1.existsSync)(this.baseDir)) {
+            return [];
+        }
+        const entries = (0, fs_1.readdirSync)(this.baseDir, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .filter((name) => {
+            // Only include directories with config.json
+            const configPath = this.getProfileConfigPath(name);
+            return (0, fs_1.existsSync)(configPath);
+        });
     }
     /**
      * Checks if a profile exists
      *
-     * @param profileName - Profile name to check
-     * @returns True if profile exists, false otherwise
+     * @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");
+     * }
+     * ```
      */
-    profileExists(profileName) {
-        const profileDir = this.getProfileDir(profileName);
-        return (0, fs_1.existsSync)(profileDir);
+    profileExists(profile) {
+        const configPath = this.getProfileConfigPath(profile);
+        return (0, fs_1.existsSync)(configPath);
     }
+    // ====================================================================
+    // Deployment Tracking
+    // ====================================================================
     /**
-     * Reads configuration for a specific profile
+     * Gets deployment history 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
+     * Returns empty history if deployments.json doesn't exist.
+     *
+     * @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
+     * ```
      */
-    readProfileConfig(configType, profileName = "default") {
-        const paths = this.getProfilePaths(profileName);
-        let configPath;
-        switch (configType) {
-            case "user":
-                configPath = paths.userConfig;
-                break;
-            case "derived":
-                configPath = paths.derivedConfig;
-                break;
-            case "deploy":
-                configPath = paths.deployConfig;
-                break;
-            default:
-                throw new Error(`Unknown configuration type: ${configType}`);
-        }
-        // Check if file exists
-        if (!(0, fs_1.existsSync)(configPath)) {
-            throw new Error(`Configuration file not found: ${configPath}`);
+    getDeployments(profile) {
+        const deploymentsPath = this.getProfileDeploymentsPath(profile);
+        if (!(0, fs_1.existsSync)(deploymentsPath)) {
+            return {
+                active: {},
+                history: [],
+            };
         }
-        // Read and parse
         let fileContent;
         try {
-            fileContent = (0, fs_1.readFileSync)(configPath, "utf-8");
+            fileContent = (0, fs_1.readFileSync)(deploymentsPath, "utf-8");
         }
         catch (error) {
-            throw new Error(`Failed to read configuration file: ${configPath}. ${error.message}`);
+            throw new Error(`Failed to read deployments file: ${deploymentsPath}. ${error.message}`);
         }
-        let config;
+        let deployments;
         try {
-            config = JSON.parse(fileContent);
+            deployments = JSON.parse(fileContent);
         }
         catch (error) {
-            throw new Error(`Invalid JSON in configuration file: ${configPath}. ${error.message}`);
+            throw new Error(`Invalid JSON in deployments file: ${deploymentsPath}. ${error.message}`);
         }
         // Validate schema
-        this.validateConfigSchema(config);
-        return config;
+        const ajv = new ajv_1.default();
+        (0, ajv_formats_1.default)(ajv);
+        const validate = ajv.compile(config_1.DeploymentHistorySchema);
+        const valid = validate(deployments);
+        if (!valid) {
+            const errors = validate.errors?.map((err) => `${err.instancePath} ${err.message}`).join(", ");
+            throw new Error(`Invalid deployments schema in ${deploymentsPath}: ${errors}`);
+        }
+        return deployments;
     }
     /**
-     * Writes configuration for a specific profile
+     * Records a new deployment 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
+     * Adds deployment to history and updates active deployment for the stage.
+     * Creates deployments.json if it doesn't exist.
+     *
+     * @param profile - Profile name
+     * @param deployment - Deployment record to add
+     *
+     * @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"
+     * });
+     * ```
      */
-    writeProfileConfig(configType, config, profileName = "default") {
-        // Validate configuration before writing
-        this.validateConfigSchema(config);
-        // Ensure profile directories exist
-        this.ensureProfileDirectories(profileName);
-        const paths = this.getProfilePaths(profileName);
-        let configPath;
-        switch (configType) {
-            case "user":
-                configPath = paths.userConfig;
-                break;
-            case "derived":
-                configPath = paths.derivedConfig;
-                break;
-            case "deploy":
-                configPath = paths.deployConfig;
-                break;
-            default:
-                throw new Error(`Unknown configuration type: ${configType}`);
+    recordDeployment(profile, deployment) {
+        // Ensure profile directory exists
+        const profileDir = this.getProfileDir(profile);
+        if (!(0, fs_1.existsSync)(profileDir)) {
+            (0, fs_1.mkdirSync)(profileDir, { recursive: true });
         }
-        const backupPath = `${configPath}.backup`;
+        // Load existing deployments or create new
+        let deployments;
+        try {
+            deployments = this.getDeployments(profile);
+        }
+        catch {
+            deployments = {
+                active: {},
+                history: [],
+            };
+        }
+        // Add to history (newest first)
+        deployments.history.unshift(deployment);
+        // Update active deployment for this stage
+        deployments.active[deployment.stage] = deployment;
+        // Write deployments file
+        const deploymentsPath = this.getProfileDeploymentsPath(profile);
+        const backupPath = `${deploymentsPath}.backup`;
         // Create backup if file exists
-        if ((0, fs_1.existsSync)(configPath)) {
+        if ((0, fs_1.existsSync)(deploymentsPath)) {
             try {
-                (0, fs_1.copyFileSync)(configPath, backupPath);
+                (0, fs_1.copyFileSync)(deploymentsPath, backupPath);
             }
             catch (error) {
                 throw new Error(`Failed to create backup: ${error.message}`);
             }
         }
         // Write to temporary file first (atomic write)
-        const tempPath = (0, path_1.resolve)((0, os_2.tmpdir)(), `benchling-webhook-config-${Date.now()}.json`);
-        const configJson = JSON.stringify(config, null, 4);
+        const tempPath = (0, path_1.join)(profileDir, `.deployments.json.tmp-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`);
+        const deploymentsJson = JSON.stringify(deployments, null, 4);
         try {
-            (0, fs_1.writeFileSync)(tempPath, configJson, "utf-8");
+            (0, fs_1.writeFileSync)(tempPath, deploymentsJson, "utf-8");
             // Atomic rename (with fallback for cross-device on Windows)
             try {
-                (0, fs_1.renameSync)(tempPath, configPath);
+                (0, fs_1.renameSync)(tempPath, deploymentsPath);
             }
             catch {
                 // Fall back to copy+delete for cross-device scenarios (Windows)
-                (0, fs_1.copyFileSync)(tempPath, configPath);
+                // Ensure target directory exists before copying
+                const targetDir = (0, path_1.dirname)(deploymentsPath);
+                if (!(0, fs_1.existsSync)(targetDir)) {
+                    (0, fs_1.mkdirSync)(targetDir, { recursive: true });
+                }
+                (0, fs_1.copyFileSync)(tempPath, deploymentsPath);
                 (0, fs_1.unlinkSync)(tempPath);
             }
         }
         catch (error) {
-            throw new Error(`Failed to write configuration file: ${error.message}`);
+            throw new Error(`Failed to write deployments file: ${error.message}`);
         }
     }
     /**
-     * Loads a complete profile with all configuration files
+     * Gets the active deployment for a specific stage
+     *
+     * @param profile - Profile name
+     * @param stage - Stage name (e.g., "dev", "prod")
+     * @returns Active deployment record for the stage, or null if none exists
      *
-     * @param profileName - Profile name (defaults to "default")
-     * @returns Complete profile configuration
+     * @example
+     * ```typescript
+     * const prodDeployment = xdg.getActiveDeployment("default", "prod");
+     * if (prodDeployment) {
+     *   console.log("Prod endpoint:", prodDeployment.endpoint);
+     * }
+     * ```
      */
-    loadProfile(profileName = "default") {
-        const profile = {
-            name: profileName,
-        };
-        const paths = this.getProfilePaths(profileName);
-        // Load user config if exists
-        if ((0, fs_1.existsSync)(paths.userConfig)) {
-            try {
-                profile.user = this.readProfileConfig("user", profileName);
-            }
-            catch {
-                // User config is optional
-            }
-        }
-        // Load derived config if exists
-        if ((0, fs_1.existsSync)(paths.derivedConfig)) {
-            try {
-                profile.derived = this.readProfileConfig("derived", profileName);
-            }
-            catch {
-                // Derived config is optional
-            }
+    getActiveDeployment(profile, stage) {
+        try {
+            const deployments = this.getDeployments(profile);
+            return deployments.active[stage] || null;
         }
-        // Load deploy config if exists
-        if ((0, fs_1.existsSync)(paths.deployConfig)) {
-            try {
-                profile.deploy = this.readProfileConfig("deploy", profileName);
-            }
-            catch {
-                // Deploy config is optional
-            }
+        catch {
+            return null;
         }
-        return profile;
     }
+    // ====================================================================
+    // Profile Inheritance
+    // ====================================================================
     /**
-     * Deletes a profile and all its configuration files
+     * Reads profile configuration with inheritance support
      *
-     * WARNING: This is a destructive operation!
+     * If the profile has an `_inherits` field, loads the base profile first
+     * and deep merges the current profile on top.
      *
-     * @param profileName - Profile name to delete
-     * @throws {Error} If attempting to delete the default profile or if deletion fails
+     * 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 = xdg.readProfileWithInheritance("dev");
+     * // Returns default config deep-merged with dev overrides
+     * ```
      */
-    deleteProfile(profileName) {
-        if (profileName === "default") {
-            throw new Error("Cannot delete the default profile");
-        }
-        const profileDir = this.getProfileDir(profileName);
-        if (!(0, fs_1.existsSync)(profileDir)) {
-            throw new Error(`Profile does not exist: ${profileName}`);
-        }
-        // For safety, we'll require manual deletion
-        throw new Error(`Profile deletion must be done manually. Profile directory: ${profileDir}`);
+    readProfileWithInheritance(profile, baseProfile) {
+        const visited = new Set();
+        return this.readProfileWithInheritanceInternal(profile, baseProfile, visited);
+    }
+    /**
+     * 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
+     */
+    readProfileWithInheritanceInternal(profile, explicitBase, visited) {
+        // Detect circular inheritance
+        if (visited.has(profile)) {
+            const chain = Array.from(visited).join(" -> ");
+            throw new Error(`Circular inheritance detected: ${chain} -> ${profile}`);
+        }
+        visited.add(profile);
+        // Read current profile
+        const config = this.readProfile(profile);
+        // Determine base profile
+        const baseProfileName = explicitBase || config._inherits;
+        // No inheritance - return as-is
+        if (!baseProfileName) {
+            return config;
+        }
+        // Load base profile with inheritance
+        const baseConfig = this.readProfileWithInheritanceInternal(baseProfileName, undefined, visited);
+        // Deep merge: base config first, then current profile overrides
+        const merged = this.deepMergeConfigs(baseConfig, config);
+        // Remove _inherits from final result (it's already applied)
+        delete merged._inherits;
+        return merged;
+    }
+    /**
+     * 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
+     */
+    deepMergeConfigs(base, current) {
+        return (0, lodash_merge_1.default)({}, base, current);
+    }
+    // ====================================================================
+    // Validation
+    // ====================================================================
+    /**
+     * Validates a profile configuration against the schema
+     *
+     * @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);
+     * }
+     * ```
+     */
+    validateProfile(config) {
+        const ajv = new ajv_1.default({ allErrors: true, strict: false });
+        (0, ajv_formats_1.default)(ajv);
+        const validate = ajv.compile(config_1.ProfileConfigSchema);
+        const valid = validate(config);
+        if (valid) {
+            return {
+                isValid: true,
+                errors: [],
+                warnings: [],
+            };
+        }
+        const errors = validate.errors?.map((err) => {
+            const path = err.instancePath || "(root)";
+            return `${path}: ${err.message}`;
+        }) || [];
+        return {
+            isValid: false,
+            errors,
+            warnings: [],
+        };
+    }
+    // ====================================================================
+    // Path Helpers
+    // ====================================================================
+    /**
+     * Gets the directory path for a profile
+     *
+     * @param profile - Profile name
+     * @returns Absolute path to profile directory
+     */
+    getProfileDir(profile) {
+        return (0, path_1.join)(this.baseDir, profile);
+    }
+    /**
+     * Gets the config.json path for a profile
+     *
+     * @param profile - Profile name
+     * @returns Absolute path to config.json
+     */
+    getProfileConfigPath(profile) {
+        return (0, path_1.join)(this.getProfileDir(profile), "config.json");
+    }
+    /**
+     * Gets the deployments.json path for a profile
+     *
+     * @param profile - Profile name
+     * @returns Absolute path to deployments.json
+     */
+    getProfileDeploymentsPath(profile) {
+        return (0, path_1.join)(this.getProfileDir(profile), "deployments.json");
+    }
+    // ====================================================================
+    // Error Messages
+    // ====================================================================
+    /**
+     * Builds a helpful error message when a profile is not found
+     *
+     * Detects legacy v0.6.x configuration files and provides upgrade guidance.
+     *
+     * @param profile - Profile name that was not found
+     * @returns Formatted error message
+     */
+    buildProfileNotFoundError(profile) {
+        const legacyFiles = [
+            (0, path_1.join)(this.baseDir, "default.json"),
+            (0, path_1.join)(this.baseDir, "deploy.json"),
+            (0, path_1.join)(this.baseDir, "profiles"),
+        ];
+        const hasLegacyFiles = legacyFiles.some((f) => (0, fs_1.existsSync)(f));
+        if (hasLegacyFiles) {
+            return `
+Profile not found: ${profile}
+
+Configuration format changed in v0.7.0.
+Your old configuration files are not compatible.
+
+Please run setup wizard to create new configuration:
+  npx @quiltdata/benchling-webhook@latest setup
+
+Your old configuration files remain at:
+  ~/.config/benchling-webhook/default.json
+  ~/.config/benchling-webhook/deploy.json
+
+You can manually reference these files to re-enter your settings.
+            `.trim();
+        }
+        return `
+Profile not found: ${profile}
+
+No configuration found for profile: ${profile}
+
+Run setup wizard to create configuration:
+  npx @quiltdata/benchling-webhook@latest setup
+
+Available profiles: ${this.listProfiles().join(", ") || "(none)"}
+        `.trim();
     }
 }
 exports.XDGConfig = XDGConfig;