puls-dev 0.2.7 → 0.2.9

package/dist/core/secret.test.js

@@ -0,0 +1,166 @@
+import { test, describe, beforeEach, mock } from "node:test";
+import assert from "node:assert";
+import fs from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { Secret } from "./secret.js";
+import { Config } from "./config.js";
+import { Output } from "./output.js";
+// Import clients to mock their prototype methods
+import { SecretsManagerClient } from "@aws-sdk/client-secrets-manager";
+import { SSMClient } from "@aws-sdk/client-ssm";
+import { GoogleAuth } from "google-auth-library";
+describe("Secrets at Deploy Time Unit Tests", () => {
+    beforeEach(() => {
+        // Reset global config before each test
+        Config.set({
+            dryRun: false,
+            providers: {},
+        });
+    });
+    test("Secret.env resolves existing environment variables", async () => {
+        process.env.TEST_MY_SECRET = "super-secret-value";
+        try {
+            const secret = Secret.env("TEST_MY_SECRET");
+            const val = await secret.get();
+            assert.strictEqual(val, "super-secret-value");
+        }
+        finally {
+            delete process.env.TEST_MY_SECRET;
+        }
+    });
+    test("Secret.env uses fallback when environment variable is missing", async () => {
+        const secret = Secret.env("TEST_MISSING_SECRET", "fallback-value");
+        const val = await secret.get();
+        assert.strictEqual(val, "fallback-value");
+    });
+    test("Secret.env throws error when missing and no fallback is set", async () => {
+        const secret = Secret.env("TEST_MISSING_SECRET_NO_FALLBACK");
+        await assert.rejects(async () => {
+            await secret.get();
+        }, /Environment secret "TEST_MISSING_SECRET_NO_FALLBACK" is not set and has no fallback./);
+    });
+    test("Secret.resolve correctly resolves strings, Outputs, and Secrets", async () => {
+        // 1. Resolve plain string
+        const r1 = await Secret.resolve("plain-string");
+        assert.strictEqual(r1, "plain-string");
+        // 2. Resolve general Output
+        const out = new Output();
+        out.resolve("resolved-output");
+        const r2 = await Secret.resolve(out);
+        assert.strictEqual(r2, "resolved-output");
+        // 3. Resolve Secret
+        process.env.TEST_RESOLVE = "secret-val";
+        try {
+            const sec = Secret.env("TEST_RESOLVE");
+            const r3 = await Secret.resolve(sec);
+            assert.strictEqual(r3, "secret-val");
+        }
+        finally {
+            delete process.env.TEST_RESOLVE;
+        }
+    });
+    test("Secret resolves immediately to placeholder [SECRET:name] in dry-run mode", async () => {
+        Config.set({ dryRun: true });
+        // No actual env vars, cloud requests, or file systems will be hit
+        const s1 = Secret.env("SOME_ENV");
+        const s2 = Secret.aws("some/aws/secret");
+        const s3 = Secret.ssm("/some/ssm/param");
+        const s4 = Secret.gcp("some-gcp-secret");
+        assert.strictEqual(await s1.get(), "[SECRET:SOME_ENV]");
+        assert.strictEqual(await s2.get(), "[SECRET:some/aws/secret]");
+        assert.strictEqual(await s3.get(), "[SECRET:/some/ssm/param]");
+        assert.strictEqual(await s4.get(), "[SECRET:some-gcp-secret]");
+    });
+    test("Secret.aws resolves value using mocked AWS Secrets Manager", async () => {
+        const originalSend = SecretsManagerClient.prototype.send;
+        mock.method(SecretsManagerClient.prototype, "send", async (command) => {
+            return { SecretString: "my-aws-vault-password" };
+        });
+        try {
+            const secret = Secret.aws("prod/db/pass", { region: "eu-west-1" });
+            const val = await secret.get();
+            assert.strictEqual(val, "my-aws-vault-password");
+        }
+        finally {
+            SecretsManagerClient.prototype.send = originalSend;
+        }
+    });
+    test("Secret.ssm resolves value using mocked AWS SSM Parameter Store", async () => {
+        const originalSend = SSMClient.prototype.send;
+        mock.method(SSMClient.prototype, "send", async (command) => {
+            return {
+                Parameter: {
+                    Value: "my-ssm-token-value",
+                },
+            };
+        });
+        try {
+            const secret = Secret.ssm("/prod/api/token");
+            const val = await secret.get();
+            assert.strictEqual(val, "my-ssm-token-value");
+        }
+        finally {
+            SSMClient.prototype.send = originalSend;
+        }
+    });
+    test("Secret.gcp resolves value using mocked GCP Secret Manager fetcher", async () => {
+        // 1. Create a dummy service account file
+        const dummySaPath = join(tmpdir(), `puls-gcp-sa-test-${Date.now()}.json`);
+        const dummySa = {
+            project_id: "test-gcp-project",
+            client_email: "test@developer.gserviceaccount.com",
+        };
+        fs.writeFileSync(dummySaPath, JSON.stringify(dummySa));
+        // Configure config to use the dummy file
+        Config.set({
+            providers: {
+                gcp: {
+                    projectId: "test-gcp-project",
+                    serviceAccountPath: dummySaPath,
+                },
+            },
+        });
+        // 2. Mock GoogleAuth class prototype
+        const originalGetClient = GoogleAuth.prototype.getClient;
+        mock.method(GoogleAuth.prototype, "getClient", async () => {
+            return {
+                getAccessToken: async () => ({ token: "mocked-gcp-access-token" }),
+            };
+        });
+        // 3. Mock globalThis.fetch to intercept Secret Manager API request
+        const originalFetch = globalThis.fetch;
+        let requestedUrl = "";
+        let authHeader = "";
+        globalThis.fetch = (async (url, init) => {
+            requestedUrl = url;
+            authHeader = init?.headers?.["Authorization"] ?? "";
+            return {
+                ok: true,
+                status: 200,
+                text: async () => JSON.stringify({
+                    name: "projects/test-gcp-project/secrets/my-secret/versions/latest",
+                    payload: {
+                        data: Buffer.from("my-gcp-payload-value").toString("base64"),
+                    },
+                }),
+            };
+        });
+        try {
+            const secret = Secret.gcp("my-secret");
+            const val = await secret.get();
+            assert.strictEqual(val, "my-gcp-payload-value");
+            assert.strictEqual(requestedUrl, "https://secretmanager.googleapis.com/v1/projects/test-gcp-project/secrets/my-secret/versions/latest:access");
+            assert.strictEqual(authHeader, "Bearer mocked-gcp-access-token");
+        }
+        finally {
+            // Cleanup
+            globalThis.fetch = originalFetch;
+            GoogleAuth.prototype.getClient = originalGetClient;
+            try {
+                fs.unlinkSync(dummySaPath);
+            }
+            catch { }
+        }
+    });
+});

package/dist/core/stack.d.ts

@@ -1,20 +1,21 @@
 import "reflect-metadata";
 export declare abstract class Stack {
     /** @internal - called by @Deploy to register the instance for cross-stack references. */
-    static _register(cls: Function, instance: Stack): void;
+    static _register(cls: Function, instance: Stack, region?: string): void;
     /**
      * Returns the already-constructed instance of another Stack so you can reference
      * its resource Output fields before deployment completes.
      *
      * The target stack must be decorated with @Deploy and imported before this call.
+     * An optional region parameter can be supplied for multi-region configurations.
      *
      * @example
      * class DNSStack extends Stack {
-     *   private infra = Stack.from(InfraStack);
+     *   private infra = Stack.from(InfraStack, REGION.US_EAST_1);
      *   dns = DO.Domain("example.com").pointer("app", this.infra.app.ip);
      * }
      */
-    static from<T extends Stack>(cls: new (...args: any[]) => T): T;
+    static from<T extends Stack>(cls: new (...args: any[]) => T, region?: string): T;
     deploy(): Promise<Record<string, any>>;
     destroy(): Promise<Record<string, any>>;
 }

package/dist/core/stack.js

@@ -1,24 +1,37 @@
 import "reflect-metadata";
 import { BaseBuilder } from "./resource.js";
+import { Config } from "./config.js";
+import { resourceContextStorage } from "./context.js";
+import { resolvedSecrets } from "./secret.js";
 const _registry = new Map();
-function formatEntry(val) {
+function formatEntry(val, parentKey) {
+    const isSensitiveKey = (k) => /password|secret|token|key/i.test(k);
+    if (parentKey && isSensitiveKey(parentKey)) {
+        return { primary: "********" };
+    }
     if (!val || typeof val !== "object")
         return { primary: String(val) };
+    const redactedVal = { ...val };
+    for (const k of Object.keys(redactedVal)) {
+        if (isSensitiveKey(k)) {
+            redactedVal[k] = "********";
+        }
+    }
     // Known shapes
-    if ("destroyed" in val)
-        return { primary: val.destroyed ? "🗑️  destroyed" : "─  not found" };
-    if (val.zone)
-        return { primary: val.zone };
-    if (val.name && val.id)
-        return { primary: `${val.name}  [${val.id}]` };
-    if (val.name)
-        return { primary: val.name };
-    if (val.arn)
-        return { primary: val.arn };
+    if ("destroyed" in redactedVal)
+        return { primary: redactedVal.destroyed ? "🗑️  destroyed" : "─  not found" };
+    if (redactedVal.zone)
+        return { primary: redactedVal.zone };
+    if (redactedVal.name && redactedVal.id)
+        return { primary: `${redactedVal.name}  [${redactedVal.id}]` };
+    if (redactedVal.name)
+        return { primary: redactedVal.name };
+    if (redactedVal.arn)
+        return { primary: redactedVal.arn };
     // Generic: pull all scalar values
-    const pairs = Object.entries(val).filter(([, v]) => typeof v === "string" || typeof v === "number");
+    const pairs = Object.entries(redactedVal).filter(([, v]) => typeof v === "string" || typeof v === "number");
     if (pairs.length === 0)
-        return { primary: JSON.stringify(val) };
+        return { primary: JSON.stringify(redactedVal) };
     // Try compact inline (values only, dot-separated)
     const inline = pairs.map(([, v]) => v).join("  ·  ");
     if (inline.length <= 52)
@@ -35,7 +48,7 @@ function printOutputs(stackName, outputs) {
     const keyWidth = Math.max(...Object.keys(outputs).map((k) => k.length));
     const rows = Object.entries(outputs).map(([key, val]) => ({
         key,
-        ...formatEntry(val),
+        ...formatEntry(val, key),
     }));
     // textWidth = width of row text content (without the 2-space padding on each side)
     const textWidth = Math.max(...rows.flatMap(({ key, primary, sub }) => [
@@ -60,7 +73,10 @@ function printOutputs(stackName, outputs) {
 }
 export class Stack {
     /** @internal - called by @Deploy to register the instance for cross-stack references. */
-    static _register(cls, instance) {
+    static _register(cls, instance, region) {
+        if (region) {
+            _registry.set(`${cls.name}:${region}`, instance);
+        }
         _registry.set(cls, instance);
     }
     /**
@@ -68,53 +84,311 @@ export class Stack {
      * its resource Output fields before deployment completes.
      *
      * The target stack must be decorated with @Deploy and imported before this call.
+     * An optional region parameter can be supplied for multi-region configurations.
      *
      * @example
      * class DNSStack extends Stack {
-     *   private infra = Stack.from(InfraStack);
+     *   private infra = Stack.from(InfraStack, REGION.US_EAST_1);
      *   dns = DO.Domain("example.com").pointer("app", this.infra.app.ip);
      * }
      */
-    static from(cls) {
-        const instance = _registry.get(cls);
+    static from(cls, region) {
+        const key = region ? `${cls.name}:${region}` : cls;
+        const instance = _registry.get(key);
         if (!instance)
-            throw new Error(`Stack "${cls.name}" is not registered. Make sure it is decorated with @Deploy and its module is imported before referencing it.`);
+            throw new Error(`Stack "${cls.name}" ${region ? `for region "${region}" ` : ""}is not registered. Make sure it is decorated with @Deploy and its module is imported before referencing it.`);
         return instance;
     }
     async deploy() {
-        console.log(`\n🏗️  Deploying Stack: ${this.constructor.name}`);
-        const props = Object.getOwnPropertyNames(this);
-        const outputs = {};
-        for (const prop of props) {
-            const resource = this[prop];
-            if (resource instanceof BaseBuilder) {
-                const isProtected = Reflect.getMetadata("protected", this, prop);
-                const isDestroyed = Reflect.getMetadata("destroy", this, prop);
-                if (isProtected)
-                    resource.protect();
-                outputs[prop] = isDestroyed
-                    ? await resource.destroy()
-                    : await resource.deploy();
+        const controller = new AbortController();
+        const hosts = [];
+        const context = {
+            abortSignal: controller.signal,
+            hosts,
+            stackName: this.constructor.name
+        };
+        return resourceContextStorage.run(context, async () => {
+            const originalLog = console.log;
+            console.log = (...args) => {
+                const redact = (message) => {
+                    if (typeof message !== "string")
+                        return message;
+                    let result = message;
+                    for (const secret of resolvedSecrets) {
+                        if (secret && secret.length >= 3) {
+                            const escaped = secret.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&');
+                            const regex = new RegExp(escaped, 'g');
+                            result = result.replace(regex, '********');
+                        }
+                    }
+                    return result;
+                };
+                const redactedArgs = args.map(arg => {
+                    if (typeof arg === "string") {
+                        return redact(arg);
+                    }
+                    try {
+                        const str = String(arg);
+                        let hasSecret = false;
+                        for (const secret of resolvedSecrets) {
+                            if (secret && secret.length >= 3 && str.includes(secret)) {
+                                hasSecret = true;
+                                break;
+                            }
+                        }
+                        if (hasSecret) {
+                            return redact(str);
+                        }
+                    }
+                    catch { }
+                    return arg;
+                });
+                originalLog(...redactedArgs);
+            };
+            try {
+                console.log(`\n🏗️  Deploying Stack: ${this.constructor.name}`);
+                // Stack-level beforeDeploy hook
+                if (typeof this.beforeDeploy === "function") {
+                    console.log(`   ⚡ Running Stack-level beforeDeploy hook...`);
+                    await this.beforeDeploy();
+                }
+                const props = Object.getOwnPropertyNames(this);
+                const outputs = {};
+                const isParallel = Config.isParallelActive();
+                // 1. Gather all resources
+                const resources = [];
+                for (const prop of props) {
+                    const val = this[prop];
+                    if (val instanceof BaseBuilder) {
+                        resources.push({ prop, resource: val });
+                        // Apply metadata properties eagerly
+                        const isProtected = Reflect.getMetadata("protected", this, prop);
+                        if (isProtected)
+                            val.protect();
+                        const forceConfigCheck = Reflect.getMetadata("forceConfigCheck", this, prop);
+                        if (forceConfigCheck && typeof val.forceConfigCheck === "function") {
+                            val.forceConfigCheck();
+                        }
+                    }
+                }
+                // 2. Schedule execution
+                if (isParallel) {
+                    const startPromise = Promise.resolve();
+                    const promises = resources.map(({ prop, resource }) => {
+                        resource._deployPromise = (async () => {
+                            try {
+                                await startPromise;
+                                if (controller.signal.aborted) {
+                                    throw new Error("Deployment aborted due to previous failure");
+                                }
+                                // Wait for explicit dependencies
+                                for (const dep of resource._dependencies) {
+                                    if (dep._deployPromise) {
+                                        await dep._deployPromise;
+                                    }
+                                }
+                                if (controller.signal.aborted) {
+                                    throw new Error("Deployment aborted due to previous failure");
+                                }
+                                // Execute hooks and deploy
+                                const isDestroyed = Reflect.getMetadata("destroy", this, prop);
+                                let res;
+                                if (isDestroyed) {
+                                    await resource._runBeforeDestroy();
+                                    res = await resource.destroy();
+                                    await resource._runAfterDestroy(res);
+                                }
+                                else {
+                                    await resource._runBeforeDeploy();
+                                    res = await resource.deploy();
+                                    await resource._runAfterDeploy(res);
+                                }
+                                outputs[prop] = res;
+                                return res;
+                            }
+                            catch (err) {
+                                controller.abort();
+                                throw err;
+                            }
+                        })();
+                        return resource._deployPromise;
+                    });
+                    await Promise.all(promises);
+                }
+                else {
+                    // Sequential mode
+                    for (const { prop, resource } of resources) {
+                        if (controller.signal.aborted) {
+                            throw new Error("Deployment aborted due to previous failure");
+                        }
+                        try {
+                            const isDestroyed = Reflect.getMetadata("destroy", this, prop);
+                            let res;
+                            if (isDestroyed) {
+                                await resource._runBeforeDestroy();
+                                res = await resource.destroy();
+                                await resource._runAfterDestroy(res);
+                            }
+                            else {
+                                await resource._runBeforeDeploy();
+                                res = await resource.deploy();
+                                await resource._runAfterDeploy(res);
+                            }
+                            outputs[prop] = res;
+                        }
+                        catch (err) {
+                            controller.abort();
+                            throw err;
+                        }
+                    }
+                }
+                printOutputs(this.constructor.name, outputs);
+                // Stack-level afterDeploy hook
+                if (typeof this.afterDeploy === "function") {
+                    console.log(`   ⚡ Running Stack-level afterDeploy hook...`);
+                    await this.afterDeploy(outputs);
+                }
+                return outputs;
             }
-        }
-        printOutputs(this.constructor.name, outputs);
-        return outputs;
+            finally {
+                console.log = originalLog;
+            }
+        });
     }
     async destroy() {
-        console.log(`\n💥 Tearing down Stack: ${this.constructor.name}`);
-        const props = Object.getOwnPropertyNames(this).reverse();
-        const outputs = {};
-        for (const prop of props) {
-            const resource = this[prop];
-            if (resource instanceof BaseBuilder) {
-                if (Reflect.getMetadata("protected", this, prop)) {
-                    console.log(`   🔒 Skipping protected resource "${prop}"`);
-                    continue;
+        const controller = new AbortController();
+        const hosts = [];
+        const context = {
+            abortSignal: controller.signal,
+            hosts,
+            stackName: this.constructor.name
+        };
+        return resourceContextStorage.run(context, async () => {
+            const originalLog = console.log;
+            console.log = (...args) => {
+                const redact = (message) => {
+                    if (typeof message !== "string")
+                        return message;
+                    let result = message;
+                    for (const secret of resolvedSecrets) {
+                        if (secret && secret.length >= 3) {
+                            const escaped = secret.replace(/[-\/\\^$*+?.()|[\]{}]/g, '\\$&');
+                            const regex = new RegExp(escaped, 'g');
+                            result = result.replace(regex, '********');
+                        }
+                    }
+                    return result;
+                };
+                const redactedArgs = args.map(arg => {
+                    if (typeof arg === "string") {
+                        return redact(arg);
+                    }
+                    try {
+                        const str = String(arg);
+                        let hasSecret = false;
+                        for (const secret of resolvedSecrets) {
+                            if (secret && secret.length >= 3 && str.includes(secret)) {
+                                hasSecret = true;
+                                break;
+                            }
+                        }
+                        if (hasSecret) {
+                            return redact(str);
+                        }
+                    }
+                    catch { }
+                    return arg;
+                });
+                originalLog(...redactedArgs);
+            };
+            try {
+                console.log(`\n💥 Tearing down Stack: ${this.constructor.name}`);
+                // Stack-level beforeDestroy hook
+                if (typeof this.beforeDestroy === "function") {
+                    console.log(`   ⚡ Running Stack-level beforeDestroy hook...`);
+                    await this.beforeDestroy();
+                }
+                const props = Object.getOwnPropertyNames(this).reverse();
+                const outputs = {};
+                const isParallel = Config.isParallelActive();
+                // 1. Gather all resources
+                const resources = [];
+                for (const prop of props) {
+                    const val = this[prop];
+                    if (val instanceof BaseBuilder) {
+                        if (Reflect.getMetadata("protected", this, prop)) {
+                            console.log(`   🔒 Skipping protected resource "${prop}"`);
+                            continue;
+                        }
+                        resources.push({ prop, resource: val });
+                    }
+                }
+                // 2. Schedule execution
+                if (isParallel) {
+                    const startPromise = Promise.resolve();
+                    // In parallel destroy, await all dependents (reverse dependencies) first
+                    const promises = resources.map(({ prop, resource }) => {
+                        resource._destroyPromise = (async () => {
+                            try {
+                                await startPromise;
+                                if (controller.signal.aborted) {
+                                    throw new Error("Teardown aborted due to previous failure");
+                                }
+                                // Wait for all resources that explicitly declare this one as a dependency
+                                const dependents = resources.filter(r => r.resource._dependencies.includes(resource));
+                                for (const dep of dependents) {
+                                    if (dep.resource._destroyPromise) {
+                                        await dep.resource._destroyPromise;
+                                    }
+                                }
+                                if (controller.signal.aborted) {
+                                    throw new Error("Teardown aborted due to previous failure");
+                                }
+                                // Execute teardown
+                                await resource._runBeforeDestroy();
+                                const res = await resource.destroy();
+                                await resource._runAfterDestroy(res);
+                                outputs[prop] = res;
+                                return res;
+                            }
+                            catch (err) {
+                                controller.abort();
+                                throw err;
+                            }
+                        })();
+                        return resource._destroyPromise;
+                    });
+                    await Promise.all(promises);
                 }
-                outputs[prop] = await resource.destroy();
+                else {
+                    // Sequential mode
+                    for (const { prop, resource } of resources) {
+                        if (controller.signal.aborted) {
+                            throw new Error("Teardown aborted due to previous failure");
+                        }
+                        try {
+                            await resource._runBeforeDestroy();
+                            const res = await resource.destroy();
+                            await resource._runAfterDestroy(res);
+                            outputs[prop] = res;
+                        }
+                        catch (err) {
+                            controller.abort();
+                            throw err;
+                        }
+                    }
+                }
+                printOutputs(this.constructor.name, outputs);
+                // Stack-level afterDestroy hook
+                if (typeof this.afterDestroy === "function") {
+                    console.log(`   ⚡ Running Stack-level afterDestroy hook...`);
+                    await this.afterDestroy(outputs);
+                }
+                return outputs;
             }
-        }
-        printOutputs(this.constructor.name, outputs);
-        return outputs;
+            finally {
+                console.log = originalLog;
+            }
+        });
     }
 }

package/dist/index.d.ts

@@ -2,4 +2,7 @@ export * from "./core/stack.js";
 export * from "./core/decorators.js";
 export * from "./core/checker.js";
 export * from "./core/resource.js";
+export { Secret } from "./core/secret.js";
+export { Output } from "./core/output.js";
 export * as INVENTORY_TYPES from "./types/inventory.js";
+export { SLACK, DISCORD } from "./core/hooks.js";

package/dist/index.js

@@ -2,4 +2,7 @@ export * from "./core/stack.js";
 export * from "./core/decorators.js";
 export * from "./core/checker.js";
 export * from "./core/resource.js";
+export { Secret } from "./core/secret.js";
+export { Output } from "./core/output.js";
 export * as INVENTORY_TYPES from "./types/inventory.js";
+export { SLACK, DISCORD } from "./core/hooks.js";