@quiltdata/benchling-webhook 0.7.4-20251107T053446Z → 0.7.4-20251113T165616Z

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

@@ -0,0 +1,306 @@
+/**
+ * XDG Base Abstract Class (v0.7.0)
+ *
+ * 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<string, ProfileConfig>();
+ *   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["prod"]); // Active prod 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 for the stage.
+     * Creates deployment history if it doesn't exist.
+     *
+     * @param profile - Profile name
+     * @param deployment - Deployment record to add
+     *
+     * @example
+     * ```typescript
+     * storage.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"
+     * });
+     * ```
+     */
+    recordDeployment(profile: string, deployment: DeploymentRecord): void;
+    /**
+     * 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
+     *
+     * @example
+     * ```typescript
+     * const prodDeployment = storage.getActiveDeployment("default", "prod");
+     * if (prodDeployment) {
+     *   console.log("Prod endpoint:", prodDeployment.endpoint);
+     * }
+     * ```
+     */
+    getActiveDeployment(profile: string, stage: string): DeploymentRecord | null;
+    /**
+     * 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

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

@@ -0,0 +1 @@
+{"version":3,"file":"xdg-base.d.ts","sourceRoot":"","sources":["../../lib/xdg-base.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAKH,OAAO,EACH,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAGnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,8BAAsB,OAAQ,YAAW,cAAc;IAKnD;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa;IAEjE;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI;IAEhF;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAE1D;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,IAAI,MAAM,EAAE;IAE9C;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAE7D;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI;IAEhF;;;;;;OAMG;IACH,SAAS,CAAC,QAAQ,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI;IAMzF;;;;;;;;;;;;OAYG;IACI,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa;IAqBlD;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACI,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI;IAcjE;;;;;;;;;;;;;OAaG;IACI,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAgB3C;;;;;;;;;;OAUG;IACI,YAAY,IAAI,MAAM,EAAE;IAI/B;;;;;;;;;;;;OAYG;IACI,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAQ9C;;;;;;;;;;;;;;OAcG;IACI,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB;IA8BzD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACI,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,gBAAgB,GAAG,IAAI;IA2B5E;;;;;;;;;;;;;;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;;;;;;;;OAQG;IACH,SAAS,CAAC,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;CAY/D"}