puls-dev 0.2.7 → 0.2.9

package/dist/core/production.test.js

@@ -0,0 +1,189 @@
+import { test, describe, beforeEach } from "node:test";
+import assert from "node:assert";
+import { Stack } from "./stack.js";
+import { Config } from "./config.js";
+import { Output } from "./output.js";
+import { BaseBuilder } from "./resource.js";
+import { Secret } from "./secret.js";
+import { resourceContextStorage } from "./context.js";
+import { runAnsible } from "./provisioner.js";
+const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+class DelayResource extends BaseBuilder {
+    delayMs;
+    executionLogs;
+    out = { val: new Output() };
+    constructor(name, delayMs, executionLogs) {
+        super(name);
+        this.delayMs = delayMs;
+        this.executionLogs = executionLogs;
+    }
+    async deploy() {
+        this.executionLogs.push(`start:${this.name}`);
+        await delay(this.delayMs);
+        this.executionLogs.push(`end:${this.name}`);
+        return { name: this.name };
+    }
+}
+class FailResource extends BaseBuilder {
+    async deploy() {
+        throw new Error("Failure in deploy!");
+    }
+}
+class AbortResource extends BaseBuilder {
+    signalLogs;
+    constructor(name, signalLogs) {
+        super(name);
+        this.signalLogs = signalLogs;
+    }
+    async deploy() {
+        const signal = resourceContextStorage.getStore()?.abortSignal;
+        if (signal) {
+            if (signal.aborted) {
+                this.signalLogs.push(`aborted-before:${this.name}`);
+            }
+            else {
+                signal.addEventListener("abort", () => {
+                    this.signalLogs.push(`aborted-during:${this.name}`);
+                });
+            }
+        }
+        await delay(50);
+        return { name: this.name };
+    }
+}
+describe("Production Features Unit Tests", () => {
+    beforeEach(() => {
+        Config.set({
+            dryRun: false,
+            parallel: false,
+            offline: false,
+            providers: {}
+        });
+    });
+    test("Secret Redaction in console.log during Stack execution", async () => {
+        // Register secret
+        const mySecret = new Secret("my-api-key", async () => "super-secret-12345");
+        await mySecret.get(); // resolves and registers it
+        const logs = [];
+        const originalLog = console.log;
+        // Create a stack that logs the secret
+        class SecretStack extends Stack {
+            r1 = new DelayResource("r1", 10, []);
+            async beforeDeploy() {
+                console.log("Starting deployment with my-api-key super-secret-12345");
+            }
+        }
+        const stack = new SecretStack();
+        // Intercept console.log temporarily just to capture it
+        console.log = (...args) => {
+            logs.push(args.join(" "));
+            originalLog(...args);
+        };
+        try {
+            await stack.deploy();
+        }
+        finally {
+            console.log = originalLog;
+        }
+        const deploymentLog = logs.join("\n");
+        assert.ok(!deploymentLog.includes("super-secret-12345"), "Should NOT contain raw secret");
+        assert.ok(deploymentLog.includes("my-api-key ********"), "Should contain redacted secret replacement");
+    });
+    test("Secret Redaction in formatEntry table matching patterns", async () => {
+        class CredentialsStack extends Stack {
+            creds_resource = new class extends BaseBuilder {
+                async deploy() {
+                    return {
+                        password: "my-cleartext-password",
+                        api_token: "my-cleartext-token",
+                        safe_field: "public-info"
+                    };
+                }
+            }("creds");
+            db_password = new class extends BaseBuilder {
+                async deploy() {
+                    return "my-cleartext-db-pass";
+                }
+            }("db-pass");
+        }
+        const logs = [];
+        const originalLog = console.log;
+        console.log = (...args) => {
+            logs.push(args.join(" "));
+            originalLog(...args);
+        };
+        try {
+            await new CredentialsStack().deploy();
+        }
+        finally {
+            console.log = originalLog;
+        }
+        const tableOutput = logs.join("\n");
+        assert.ok(!tableOutput.includes("my-cleartext-password"), "Should redact password key values in table");
+        assert.ok(!tableOutput.includes("my-cleartext-token"), "Should redact token key values in table");
+        assert.ok(!tableOutput.includes("my-cleartext-db-pass"), "Should redact sensitive parent key values in table");
+        assert.ok(tableOutput.includes("********"), "Should replace with asterisks");
+        assert.ok(tableOutput.includes("public-info"), "Should preserve non-sensitive fields");
+    });
+    test("Parallel Scheduler Cancellation (Fail-Fast)", async () => {
+        Config.set({ parallel: true });
+        const signalLogs = [];
+        class CancelStack extends Stack {
+            r1 = new AbortResource("r1", signalLogs);
+            r2 = new FailResource("r2");
+        }
+        await assert.rejects(async () => {
+            await new CancelStack().deploy();
+        }, /Failure in deploy!/);
+        // Wait a bit for abort listener
+        await delay(30);
+        assert.ok(signalLogs.includes("aborted-during:r1") || signalLogs.includes("aborted-before:r1"), "Aborted resource should have abort signal triggered");
+    });
+    test("Credential-Free Offline Dry-Run Mode", async () => {
+        Config.set({ offline: true, dryRun: true });
+        class OfflineStack extends Stack {
+            aws_vm = new class extends BaseBuilder {
+                async deploy() {
+                    const { getEC2Client } = await import("../providers/aws/api.js");
+                    const client = getEC2Client();
+                    const res = await client.send({ constructor: { name: "RunInstancesCommand" } });
+                    return res;
+                }
+            }("aws");
+            gcp_vm = new class extends BaseBuilder {
+                async deploy() {
+                    const { gcpFetch } = await import("../providers/gcp/api.js");
+                    const res = await gcpFetch("compute", "/instances");
+                    return res;
+                }
+            }("gcp");
+        }
+        const outputs = await new OfflineStack().deploy();
+        assert.ok(outputs.aws_vm.Instances[0].InstanceId.startsWith("i-mock"), "AWS VM should resolve to mock");
+        assert.ok(outputs.gcp_vm.id.startsWith("mock-gcp-instance"), "GCP VM should resolve to mock");
+    });
+    test("Ansible Provisioner Stack-Wide Dynamic Inventory Generation", async () => {
+        const context = {
+            stackName: "my-test-stack",
+            hosts: [
+                { name: "web1", ip: "1.2.3.4", user: "root", sshKey: "/path/to/key", provider: "do" },
+                { name: "db1", ip: "5.6.7.8", user: "ubuntu", sshKey: "/path/to/other-key", provider: "aws" }
+            ]
+        };
+        await resourceContextStorage.run(context, async () => {
+            try {
+                await runAnsible("1.2.3.4", "root", "/path/to/key", "playbook.yml");
+            }
+            catch (err) {
+                // We expect it might fail if ansible-playbook binary is missing, but it should still attempt write!
+                assert.ok(err.message.includes("ansible-playbook") || err.message.includes("ENOENT"), "Should attempt run");
+            }
+            const fs = await import("node:fs");
+            const exists = fs.existsSync("/tmp/puls-inventory-my-test-stack.ini");
+            assert.ok(exists, "Dynamic inventory file should be generated in /tmp");
+            const contents = fs.readFileSync("/tmp/puls-inventory-my-test-stack.ini", "utf8");
+            assert.ok(contents.includes("web1 ansible_host=1.2.3.4"), "Should contain web1 host entry");
+            assert.ok(contents.includes("db1 ansible_host=5.6.7.8"), "Should contain db1 host entry");
+        });
+    });
+});

package/dist/core/provisioner.d.ts

@@ -0,0 +1,4 @@
+export declare function checkPort(ip: string, port: number): Promise<boolean>;
+export declare function runAnsible(ip: string, user: string, sshKeys: string | string[] | undefined, playbook: string): Promise<void>;
+export declare function runPuppet(ip: string, user: string, sshKeys: string | string[] | undefined, manifest: string): Promise<void>;
+export declare function runProvisioner(ip: string, user: string, sshKeys: string | string[] | undefined, scriptPath: string): Promise<void>;

package/dist/core/provisioner.js

@@ -0,0 +1,123 @@
+import { spawn } from "node:child_process";
+import net from "node:net";
+import { homedir } from "node:os";
+import { writeFileSync } from "node:fs";
+import { resourceContextStorage } from "./context.js";
+export function checkPort(ip, port) {
+    return new Promise((resolve) => {
+        const socket = new net.Socket();
+        socket.setTimeout(2000);
+        socket.on("connect", () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.on("error", () => {
+            resolve(false);
+        });
+        socket.on("timeout", () => {
+            socket.destroy();
+            resolve(false);
+        });
+        socket.connect(port, ip);
+    });
+}
+function resolveSshKeyPath(sshKeys) {
+    const keyInput = Array.isArray(sshKeys) ? null : sshKeys;
+    return (keyInput &&
+        !keyInput.startsWith("ssh-") &&
+        !keyInput.startsWith("ecdsa-") &&
+        !keyInput.startsWith("sk-")
+        ? keyInput.replace(/\.pub$/, "")
+        : `${homedir()}/.ssh/id_ed25519`).replace(/^~/, homedir());
+}
+export function runAnsible(ip, user, sshKeys, playbook) {
+    console.log(`   🔧 Running Ansible: ${playbook} → ${ip}`);
+    const keyPath = resolveSshKeyPath(sshKeys);
+    const context = resourceContextStorage.getStore();
+    const stackName = context?.stackName ?? "default";
+    const hosts = context?.hosts ?? [];
+    return new Promise((resolve, reject) => {
+        const args = [playbook];
+        if (hosts.length > 0) {
+            const inventoryPath = `/tmp/puls-inventory-${stackName}.ini`;
+            let inventoryContent = "[all]\n";
+            for (const h of hosts) {
+                const hKeyPath = resolveSshKeyPath(h.sshKey);
+                inventoryContent += `${h.name} ansible_host=${h.ip} ansible_user=${h.user} ansible_ssh_private_key_file=${hKeyPath}\n`;
+            }
+            try {
+                writeFileSync(inventoryPath, inventoryContent, "utf8");
+            }
+            catch (err) {
+                reject(new Error(`Failed to write Ansible inventory: ${err.message}`));
+                return;
+            }
+            const currentHost = hosts.find(h => h.ip === ip);
+            const hostLimit = currentHost ? currentHost.name : ip;
+            args.push("-i", inventoryPath, "--limit", hostLimit);
+        }
+        else {
+            args.push("-i", `${ip},`, "-u", user, "--private-key", keyPath);
+        }
+        args.push("--ssh-extra-args", "-o StrictHostKeyChecking=no -o ConnectTimeout=30");
+        const proc = spawn("ansible-playbook", args, { stdio: "inherit" });
+        proc.on("close", (code) => {
+            if (code === 0) {
+                console.log(`   ✅ Provisioning complete`);
+                resolve();
+            }
+            else
+                reject(new Error(`ansible-playbook exited with code ${code}`));
+        });
+        proc.on("error", (err) => reject(new Error(`Failed to run ansible-playbook: ${err.message}`)));
+    });
+}
+export function runPuppet(ip, user, sshKeys, manifest) {
+    console.log(`   🔧 Applying Puppet manifest: ${manifest} → ${ip}`);
+    const keyPath = resolveSshKeyPath(sshKeys);
+    // Copy manifest then apply it
+    return new Promise((resolve, reject) => {
+        const scp = spawn("scp", [
+            "-i",
+            keyPath,
+            "-o",
+            "StrictHostKeyChecking=no",
+            manifest,
+            `${user}@${ip}:/tmp/manifest.pp`,
+        ], { stdio: "inherit" });
+        scp.on("close", (code) => {
+            if (code !== 0) {
+                reject(new Error(`scp exited with code ${code}`));
+                return;
+            }
+            const puppet = spawn("ssh", [
+                "-i",
+                keyPath,
+                "-o",
+                "StrictHostKeyChecking=no",
+                `${user}@${ip}`,
+                "puppet apply /tmp/manifest.pp",
+            ], { stdio: "inherit" });
+            puppet.on("close", (c) => {
+                if (c === 0) {
+                    console.log(`   ✅ Provisioning complete`);
+                    resolve();
+                }
+                else
+                    reject(new Error(`puppet apply exited with code ${c}`));
+            });
+            puppet.on("error", (err) => reject(new Error(`Failed to run puppet: ${err.message}`)));
+        });
+        scp.on("error", (err) => reject(new Error(`Failed to run scp: ${err.message}`)));
+    });
+}
+export function runProvisioner(ip, user, sshKeys, scriptPath) {
+    const ext = scriptPath.split(".").pop()?.toLowerCase();
+    if (ext === "sh") {
+        throw new Error(`Shell script provisioning (.sh) is no longer supported. ` +
+            `Please migrate "${scriptPath}" to an Ansible playbook (.yaml/.yml).`);
+    }
+    if (ext === "pp")
+        return runPuppet(ip, user, sshKeys, scriptPath);
+    return runAnsible(ip, user, sshKeys, scriptPath); // .yml / .yaml
+}

package/dist/core/resource.d.ts

@@ -4,9 +4,32 @@ export declare abstract class BaseBuilder {
     protected localDryRun: boolean | null;
     protected discoveryPromise: Promise<any>;
     protected sidecars: BaseBuilder[];
+    /** @internal */
+    _deployPromise: Promise<any>;
+    /** @internal */
+    _destroyPromise?: Promise<any>;
+    /** @internal */
+    _dependencies: BaseBuilder[];
+    private _beforeDeployHooks;
+    private _afterDeployHooks;
+    private _beforeDestroyHooks;
+    private _afterDestroyHooks;
     constructor(name: string);
+    dependsOn(resource: BaseBuilder): this;
     protect(): this;
     dryRun(enabled?: boolean): this;
+    beforeDeploy(callback: () => Promise<void> | void): this;
+    afterDeploy(callback: (result: any) => Promise<void> | void): this;
+    beforeDestroy(callback: () => Promise<void> | void): this;
+    afterDestroy(callback: (result: any) => Promise<void> | void): this;
+    /** @internal */
+    _runBeforeDeploy(): Promise<void>;
+    /** @internal */
+    _runAfterDeploy(result: any): Promise<void>;
+    /** @internal */
+    _runBeforeDestroy(): Promise<void>;
+    /** @internal */
+    _runAfterDestroy(result: any): Promise<void>;
     protected isDryRunActive(): boolean;
     protected checkProtection(hasChanges: boolean): Promise<boolean>;
     protected waitFor(label: string, condition: () => Promise<boolean>, opts?: {

package/dist/core/resource.js

@@ -5,9 +5,23 @@ export class BaseBuilder {
     localDryRun = null;
     discoveryPromise;
     sidecars = [];
+    /** @internal */
+    _deployPromise;
+    /** @internal */
+    _destroyPromise;
+    /** @internal */
+    _dependencies = [];
+    _beforeDeployHooks = [];
+    _afterDeployHooks = [];
+    _beforeDestroyHooks = [];
+    _afterDestroyHooks = [];
     constructor(name) {
         this.name = name;
     }
+    dependsOn(resource) {
+        this._dependencies.push(resource);
+        return this;
+    }
     protect() {
         this.isProtected = true;
         return this;
@@ -16,6 +30,46 @@ export class BaseBuilder {
         this.localDryRun = enabled;
         return this;
     }
+    beforeDeploy(callback) {
+        this._beforeDeployHooks.push(callback);
+        return this;
+    }
+    afterDeploy(callback) {
+        this._afterDeployHooks.push(callback);
+        return this;
+    }
+    beforeDestroy(callback) {
+        this._beforeDestroyHooks.push(callback);
+        return this;
+    }
+    afterDestroy(callback) {
+        this._afterDestroyHooks.push(callback);
+        return this;
+    }
+    /** @internal */
+    async _runBeforeDeploy() {
+        for (const cb of this._beforeDeployHooks) {
+            await cb();
+        }
+    }
+    /** @internal */
+    async _runAfterDeploy(result) {
+        for (const cb of this._afterDeployHooks) {
+            await cb(result);
+        }
+    }
+    /** @internal */
+    async _runBeforeDestroy() {
+        for (const cb of this._beforeDestroyHooks) {
+            await cb();
+        }
+    }
+    /** @internal */
+    async _runAfterDestroy(result) {
+        for (const cb of this._afterDestroyHooks) {
+            await cb(result);
+        }
+    }
     isDryRunActive() {
         return this.localDryRun !== null
             ? this.localDryRun

package/dist/core/retry.d.ts

@@ -0,0 +1,9 @@
+export interface RetryOptions {
+    maxAttempts?: number;
+    initialDelayMs?: number;
+    backoffFactor?: number;
+    jitter?: boolean;
+    retryable?: (error: any) => boolean;
+    delayFn?: (ms: number) => Promise<void>;
+}
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;

package/dist/core/retry.js

@@ -0,0 +1,28 @@
+export async function withRetry(fn, options = {}) {
+    const maxAttempts = options.maxAttempts ?? 5;
+    const initialDelayMs = options.initialDelayMs ?? 1000;
+    const backoffFactor = options.backoffFactor ?? 2;
+    const useJitter = options.jitter ?? true;
+    const retryable = options.retryable ?? (() => true);
+    const delayFn = options.delayFn ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    let attempt = 0;
+    while (true) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            attempt++;
+            if (attempt >= maxAttempts || !retryable(error)) {
+                throw error;
+            }
+            let delay = initialDelayMs * Math.pow(backoffFactor, attempt - 1);
+            if (useJitter) {
+                // Add random jitter offset of +/- 10%
+                const jitterAmount = (Math.random() * 0.2 - 0.1) * delay;
+                delay += jitterAmount;
+            }
+            console.warn(`   ⚠️  Transient error encountered: ${error.message || error}. Retrying in ${Math.round(delay)}ms (attempt ${attempt}/${maxAttempts})...`);
+            await delayFn(delay);
+        }
+    }
+}

package/dist/core/retry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/retry.test.js

@@ -0,0 +1,66 @@
+import { test, describe } from "node:test";
+import assert from "node:assert";
+import { withRetry } from "./retry.js";
+describe("Retry & Backoff Engine Unit Tests", () => {
+    test("resolves immediately if target function succeeds on the first try", async () => {
+        let calls = 0;
+        const res = await withRetry(async () => {
+            calls++;
+            return "success";
+        });
+        assert.strictEqual(res, "success");
+        assert.strictEqual(calls, 1);
+    });
+    test("retries up to max attempts and then throws the final error", async () => {
+        let calls = 0;
+        const delayTimes = [];
+        await assert.rejects(withRetry(async () => {
+            calls++;
+            throw new Error(`fail-${calls}`);
+        }, {
+            maxAttempts: 3,
+            jitter: false,
+            delayFn: async (ms) => {
+                delayTimes.push(ms);
+            },
+        }), /fail-3/);
+        assert.strictEqual(calls, 3);
+        // Exponential backoff verification:
+        // Delay 1: 1000ms * 2^0 = 1000ms
+        // Delay 2: 1000ms * 2^1 = 2000ms
+        assert.deepStrictEqual(delayTimes, [1000, 2000]);
+    });
+    test("immediately stops retrying and throws on non-retryable errors", async () => {
+        let calls = 0;
+        await assert.rejects(withRetry(async () => {
+            calls++;
+            if (calls === 1)
+                throw new Error("transient");
+            throw new Error("fatal");
+        }, {
+            maxAttempts: 5,
+            retryable: (err) => err.message === "transient",
+            delayFn: async () => { },
+        }), /fatal/);
+        assert.strictEqual(calls, 2);
+    });
+    test("includes randomized jitter when options.jitter is enabled", async () => {
+        const delayTimes = [];
+        await assert.rejects(withRetry(async () => {
+            throw new Error("fail");
+        }, {
+            maxAttempts: 3,
+            initialDelayMs: 1000,
+            backoffFactor: 2,
+            jitter: true,
+            delayFn: async (ms) => {
+                delayTimes.push(ms);
+            },
+        }), /fail/);
+        assert.strictEqual(delayTimes.length, 2);
+        // With 10% jitter, first delay (1000) should be between 900 and 1100
+        assert.ok(delayTimes[0] >= 900 && delayTimes[0] <= 1100);
+        // Second delay (2000) should be between 1800 and 2200
+        assert.ok(delayTimes[1] >= 1800 && delayTimes[1] <= 2200);
+    });
+});

package/dist/core/secret.d.ts

@@ -0,0 +1,41 @@
+import { Output } from "./output.js";
+export declare const resolvedSecrets: Set<string>;
+/**
+ * Secret represents a lazy, secure credential that is fetched asynchronously
+ * at deployment time instead of during the eager construction phase.
+ */
+export declare class Secret extends Output<string> {
+    readonly secretName: string;
+    constructor(secretName: string, fetcher: () => Promise<string>);
+    private startFetching;
+    /**
+     * Helper method to seamlessly unpack either a static string, a standard Output, or a Secret.
+     * Call this within resource builder deploy() methods.
+     */
+    static resolve(val: string | Output<string> | Secret): Promise<string>;
+    /**
+     * Fetches a secret from a local environment variable.
+     */
+    static env(envName: string, fallback?: string): Secret;
+    /**
+     * Fetches a secret from AWS Secrets Manager.
+     * Uses dynamic imports so AWS SDK is only loaded if this helper is actually called.
+     */
+    static aws(secretId: string, options?: {
+        region?: string;
+    }): Secret;
+    /**
+     * Fetches a parameter from AWS SSM Parameter Store.
+     * Uses dynamic imports so AWS SDK is only loaded if this helper is actually called.
+     */
+    static ssm(parameterName: string, options?: {
+        region?: string;
+    }): Secret;
+    /**
+     * Fetches a secret from GCP Secret Manager.
+     * Uses dynamic imports so GCP config/fetch tools are only loaded if this helper is actually called.
+     */
+    static gcp(secretId: string, options?: {
+        projectId?: string;
+    }): Secret;
+}

package/dist/core/secret.js

@@ -0,0 +1,105 @@
+import { Output } from "./output.js";
+import { Config } from "./config.js";
+export const resolvedSecrets = new Set();
+/**
+ * Secret represents a lazy, secure credential that is fetched asynchronously
+ * at deployment time instead of during the eager construction phase.
+ */
+export class Secret extends Output {
+    secretName;
+    constructor(secretName, fetcher) {
+        super();
+        this.secretName = secretName;
+        this.startFetching(fetcher);
+    }
+    async startFetching(fetcher) {
+        try {
+            if (Config.isGlobalDryRun()) {
+                // Resolve immediately to a secure placeholder during dry-run testing
+                const placeholder = `[SECRET:${this.secretName}]`;
+                this.resolve(placeholder);
+                resolvedSecrets.add(placeholder);
+                return;
+            }
+            const val = await fetcher();
+            this.resolve(val);
+            if (val && val.length >= 3) {
+                resolvedSecrets.add(val);
+            }
+        }
+        catch (err) {
+            this.reject(err);
+        }
+    }
+    /**
+     * Helper method to seamlessly unpack either a static string, a standard Output, or a Secret.
+     * Call this within resource builder deploy() methods.
+     */
+    static async resolve(val) {
+        if (val instanceof Output) {
+            const resolved = await val.get();
+            if (val instanceof Secret && resolved && resolved.length >= 3) {
+                resolvedSecrets.add(resolved);
+            }
+            return resolved;
+        }
+        return val;
+    }
+    /**
+     * Fetches a secret from a local environment variable.
+     */
+    static env(envName, fallback) {
+        return new Secret(envName, async () => {
+            const val = process.env[envName] ?? fallback;
+            if (val === undefined) {
+                throw new Error(`Environment secret "${envName}" is not set and has no fallback.`);
+            }
+            return val;
+        });
+    }
+    /**
+     * Fetches a secret from AWS Secrets Manager.
+     * Uses dynamic imports so AWS SDK is only loaded if this helper is actually called.
+     */
+    static aws(secretId, options) {
+        return new Secret(secretId, async () => {
+            const { SecretsManagerClient, GetSecretValueCommand } = await import("@aws-sdk/client-secrets-manager");
+            const client = new SecretsManagerClient({ region: options?.region ?? process.env.AWS_REGION ?? "us-east-1" });
+            const result = await client.send(new GetSecretValueCommand({ SecretId: secretId }));
+            if (!result.SecretString) {
+                throw new Error(`AWS Secret "${secretId}" is empty or not a string.`);
+            }
+            return result.SecretString;
+        });
+    }
+    /**
+     * Fetches a parameter from AWS SSM Parameter Store.
+     * Uses dynamic imports so AWS SDK is only loaded if this helper is actually called.
+     */
+    static ssm(parameterName, options) {
+        return new Secret(parameterName, async () => {
+            const { SSMClient, GetParameterCommand } = await import("@aws-sdk/client-ssm");
+            const client = new SSMClient({ region: options?.region ?? process.env.AWS_REGION ?? "us-east-1" });
+            const result = await client.send(new GetParameterCommand({ Name: parameterName, WithDecryption: true }));
+            if (!result.Parameter?.Value) {
+                throw new Error(`AWS SSM Parameter "${parameterName}" is empty.`);
+            }
+            return result.Parameter.Value;
+        });
+    }
+    /**
+     * Fetches a secret from GCP Secret Manager.
+     * Uses dynamic imports so GCP config/fetch tools are only loaded if this helper is actually called.
+     */
+    static gcp(secretId, options) {
+        return new Secret(secretId, async () => {
+            const { gcpFetch, getProjectId } = await import("../providers/gcp/api.js");
+            const project = options?.projectId ?? getProjectId();
+            const payload = await gcpFetch("https://secretmanager.googleapis.com", `/v1/projects/${project}/secrets/${secretId}/versions/latest:access`);
+            if (!payload?.payload?.data) {
+                throw new Error(`GCP Secret "${secretId}" payload is empty.`);
+            }
+            return Buffer.from(payload.payload.data, "base64").toString("utf8");
+        });
+    }
+}

package/dist/core/secret.test.d.ts

@@ -0,0 +1 @@
+export {};