puls-dev 0.2.8 → 0.2.9

package/dist/core/resource.d.ts

@@ -4,11 +4,18 @@ 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;

package/dist/core/resource.js

@@ -5,6 +5,12 @@ export class BaseBuilder {
     localDryRun = null;
     discoveryPromise;
     sidecars = [];
+    /** @internal */
+    _deployPromise;
+    /** @internal */
+    _destroyPromise;
+    /** @internal */
+    _dependencies = [];
     _beforeDeployHooks = [];
     _afterDeployHooks = [];
     _beforeDestroyHooks = [];
@@ -12,6 +18,10 @@ export class BaseBuilder {
     constructor(name) {
         this.name = name;
     }
+    dependsOn(resource) {
+        this._dependencies.push(resource);
+        return this;
+    }
     protect() {
         this.isProtected = true;
         return this;

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

@@ -1,4 +1,5 @@
 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.
@@ -11,7 +12,7 @@ export declare class Secret extends Output<string> {
      * 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 | any): Promise<string>;
+    static resolve(val: string | Output<string> | Secret): Promise<string>;
     /**
      * Fetches a secret from a local environment variable.
      */

package/dist/core/secret.js

@@ -1,5 +1,6 @@
 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.
@@ -15,11 +16,16 @@ export class Secret extends Output {
         try {
             if (Config.isGlobalDryRun()) {
                 // Resolve immediately to a secure placeholder during dry-run testing
-                this.resolve(`[SECRET:${this.secretName}]`);
+                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);
@@ -31,7 +37,11 @@ export class Secret extends Output {
      */
     static async resolve(val) {
         if (val instanceof Output) {
-            return await val.get();
+            const resolved = await val.get();
+            if (val instanceof Secret && resolved && resolved.length >= 3) {
+                resolvedSecrets.add(resolved);
+            }
+            return resolved;
         }
         return val;
     }

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 }) => [
@@ -87,75 +100,295 @@ export class Stack {
         return instance;
     }
     async deploy() {
-        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 = {};
-        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();
-                const forceConfigCheck = Reflect.getMetadata("forceConfigCheck", this, prop);
-                if (forceConfigCheck && typeof resource.forceConfigCheck === "function") {
-                    resource.forceConfigCheck();
+        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();
+                        }
+                    }
                 }
-                let res;
-                if (isDestroyed) {
-                    await resource._runBeforeDestroy();
-                    res = await resource.destroy();
-                    await resource._runAfterDestroy(res);
+                // 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 {
-                    await resource._runBeforeDeploy();
-                    res = await resource.deploy();
-                    await resource._runAfterDeploy(res);
+                    // 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;
+                        }
+                    }
                 }
-                outputs[prop] = res;
+                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);
-        // Stack-level afterDeploy hook
-        if (typeof this.afterDeploy === "function") {
-            console.log(`   ⚡ Running Stack-level afterDeploy hook...`);
-            await this.afterDeploy(outputs);
-        }
-        return outputs;
+            finally {
+                console.log = originalLog;
+            }
+        });
     }
     async destroy() {
-        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 = {};
-        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);
+                }
+                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;
+                        }
+                    }
                 }
-                await resource._runBeforeDestroy();
-                const res = await resource.destroy();
-                await resource._runAfterDestroy(res);
-                outputs[prop] = res;
+                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);
-        // Stack-level afterDestroy hook
-        if (typeof this.afterDestroy === "function") {
-            console.log(`   ⚡ Running Stack-level afterDestroy hook...`);
-            await this.afterDestroy(outputs);
-        }
-        return outputs;
+            finally {
+                console.log = originalLog;
+            }
+        });
     }
 }

package/dist/index.d.ts

@@ -3,5 +3,6 @@ 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

@@ -3,5 +3,6 @@ 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";