puls-dev 0.2.8 → 0.3.0

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.js

@@ -1,6 +1,8 @@
 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();
@@ -31,18 +33,34 @@ function resolveSshKeyPath(sshKeys) {
 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 proc = spawn("ansible-playbook", [
-            playbook,
-            "-i",
-            `${ip},`,
-            "-u",
-            user,
-            "--private-key",
-            keyPath,
-            "--ssh-extra-args",
-            "-o StrictHostKeyChecking=no -o ConnectTimeout=30",
-        ], { stdio: "inherit" });
+        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`);

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;
@@ -34,3 +41,4 @@ export declare abstract class BaseBuilder {
     destroy(): Promise<any>;
     abstract deploy(): Promise<any>;
 }
+export declare function createBuilderArray<T extends BaseBuilder>(builders: T[]): T[] & T;

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;
@@ -119,3 +129,38 @@ export class BaseBuilder {
         return { destroyed: this.name };
     }
 }
+export function createBuilderArray(builders) {
+    return new Proxy(builders, {
+        get(target, prop, receiver) {
+            if (prop in target) {
+                const val = Reflect.get(target, prop, receiver);
+                if (typeof val === "function") {
+                    return val.bind(target);
+                }
+                return val;
+            }
+            if (builders.length > 0) {
+                const first = builders[0];
+                const val = Reflect.get(first, prop);
+                if (typeof val === "function") {
+                    return function (...args) {
+                        builders.forEach((b, idx) => {
+                            const method = Reflect.get(b, prop);
+                            if (typeof method === "function") {
+                                const mappedArgs = args.map((arg) => {
+                                    if (Array.isArray(arg) && arg.length === builders.length) {
+                                        return arg[idx];
+                                    }
+                                    return arg;
+                                });
+                                method.apply(b, mappedArgs);
+                            }
+                        });
+                        return receiver;
+                    };
+                }
+            }
+            return undefined;
+        },
+    });
+}

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;
     }