puls-dev 0.2.7 → 0.2.9

package/dist/core/multiregion.test.js

@@ -0,0 +1,87 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { test, describe, beforeEach } from "node:test";
+import assert from "node:assert";
+import { Stack } from "./stack.js";
+import { Deploy, Destroy } from "./decorators.js";
+import { BaseBuilder } from "./resource.js";
+import { Config } from "./config.js";
+import { Output } from "./output.js";
+class RegionResource extends BaseBuilder {
+    out = {
+        region: new Output(),
+    };
+    async deploy() {
+        const activeRegion = Config.get().providers.aws?.region ?? "unknown";
+        this.out.region.resolve(activeRegion);
+        return { name: this.name, region: activeRegion };
+    }
+    async destroy() {
+        const activeRegion = Config.get().providers.aws?.region ?? "unknown";
+        return { name: this.name, destroyed: true, region: activeRegion };
+    }
+}
+describe("Multi-Region Deployments Unit Tests", () => {
+    let executionLogs = [];
+    beforeEach(() => {
+        Config.set({
+            dryRun: false,
+            providers: {},
+        });
+        executionLogs = [];
+    });
+    test("runs sequential deployments across multiple regions and stores instances in registry", async () => {
+        let MultiStack = class MultiStack extends Stack {
+            res = new RegionResource("my-region-res").afterDeploy((result) => {
+                executionLogs.push(`deploy:${result.region}`);
+            });
+        };
+        MultiStack = __decorate([
+            Deploy({
+                regions: ["us-east-1", "eu-central-1", "ap-northeast-1"],
+                dryRun: false,
+            })
+        ], MultiStack);
+        // Wait for the asynchronous macro/microtask queue to resolve Deploy runs
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        // Verify sequential region changes occurred in correct order
+        assert.deepStrictEqual(executionLogs, [
+            "deploy:us-east-1",
+            "deploy:eu-central-1",
+            "deploy:ap-northeast-1",
+        ]);
+        // Retrieve specific region stack outputs via Stack.from(cls, region)
+        const usStack = Stack.from(MultiStack, "us-east-1");
+        const euStack = Stack.from(MultiStack, "eu-central-1");
+        const apStack = Stack.from(MultiStack, "ap-northeast-1");
+        assert.ok(usStack);
+        assert.ok(euStack);
+        assert.ok(apStack);
+        assert.strictEqual(await usStack.res.out.region.get(), "us-east-1");
+        assert.strictEqual(await euStack.res.out.region.get(), "eu-central-1");
+        assert.strictEqual(await apStack.res.out.region.get(), "ap-northeast-1");
+    });
+    test("runs sequential teardowns across multiple regions on @Destroy", async () => {
+        let CleanStack = class CleanStack extends Stack {
+            res = new RegionResource("my-teardown-res").afterDestroy((result) => {
+                executionLogs.push(`destroy:${result.region}`);
+            });
+        };
+        CleanStack = __decorate([
+            Destroy({
+                regions: ["us-east-1", "eu-central-1"],
+                dryRun: false,
+            })
+        ], CleanStack);
+        // Wait for microtask queue to run Destroy
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        assert.deepStrictEqual(executionLogs, [
+            "destroy:us-east-1",
+            "destroy:eu-central-1",
+        ]);
+    });
+});

package/dist/core/output.d.ts

@@ -1,8 +1,10 @@
 export declare class Output<T> {
     private _promise;
     private _resolve;
+    private _reject;
     constructor();
     resolve(value: T): void;
+    reject(reason: any): void;
     get(): Promise<T>;
     apply<U>(fn: (val: T) => U): Output<U>;
 }

package/dist/core/output.js

@@ -1,19 +1,26 @@
 export class Output {
     _promise;
     _resolve;
+    _reject;
     constructor() {
-        this._promise = new Promise(resolve => (this._resolve = resolve));
+        this._promise = new Promise((resolve, reject) => {
+            this._resolve = resolve;
+            this._reject = reject;
+        });
     }
     resolve(value) {
         this._resolve(value);
     }
+    reject(reason) {
+        this._reject(reason);
+    }
     get() {
         return this._promise;
     }
     // Transform this output into a new Output<U> without awaiting it yourself.
     apply(fn) {
         const out = new Output();
-        this._promise.then(v => out.resolve(fn(v)));
+        this._promise.then(v => out.resolve(fn(v)), err => out.reject(err));
         return out;
     }
 }

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

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

package/dist/core/parallel.test.js

@@ -0,0 +1,215 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { test, describe, beforeEach } from "node:test";
+import assert from "node:assert";
+import { Stack } from "./stack.js";
+import { Deploy } from "./decorators.js";
+import { BaseBuilder } from "./resource.js";
+import { Config } from "./config.js";
+import { Output } from "./output.js";
+// Helper delay
+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}`);
+        this.out.val.resolve(this.name);
+        return { name: this.name };
+    }
+    async destroy() {
+        this.executionLogs.push(`destroy:${this.name}`);
+        await delay(this.delayMs);
+        return { name: this.name, destroyed: true };
+    }
+}
+class FailResource extends BaseBuilder {
+    async deploy() {
+        throw new Error("Failed to deploy!");
+    }
+}
+describe("Parallel Resource Deployment Unit Tests", () => {
+    let logs = [];
+    beforeEach(() => {
+        Config.set({
+            dryRun: false,
+            parallel: false,
+            providers: {},
+        });
+        logs = [];
+    });
+    test("runs sequential deployments by default (verifies base case)", async () => {
+        class SeqStack extends Stack {
+            r1 = new DelayResource("r1", 30, logs);
+            r2 = new DelayResource("r2", 30, logs);
+        }
+        const start = Date.now();
+        const stack = new SeqStack();
+        await stack.deploy();
+        const duration = Date.now() - start;
+        // In sequential, execution is r1 start -> r1 end -> r2 start -> r2 end
+        assert.deepStrictEqual(logs, [
+            "start:r1",
+            "end:r1",
+            "start:r2",
+            "end:r2"
+        ]);
+        assert.ok(duration >= 60, `Sequential should take at least 60ms, took ${duration}ms`);
+    });
+    test("runs parallel deployments concurrently when opted in", async () => {
+        // Enable parallel globally for the stack run
+        Config.set({
+            dryRun: false,
+            parallel: true,
+            providers: {},
+        });
+        class ParStack extends Stack {
+            r1 = new DelayResource("r1", 40, logs);
+            r2 = new DelayResource("r2", 40, logs);
+        }
+        const start = Date.now();
+        const stack = new ParStack();
+        await stack.deploy();
+        const duration = Date.now() - start;
+        // In parallel, both start before either finishes:
+        // start:r1 and start:r2 will both be printed first.
+        assert.strictEqual(logs[0].startsWith("start:"), true);
+        assert.strictEqual(logs[1].startsWith("start:"), true);
+        assert.ok(logs.includes("end:r1"));
+        assert.ok(logs.includes("end:r2"));
+        // Total duration should be closer to 40ms than 80ms
+        assert.ok(duration < 75, `Parallel should take less than 75ms (sum), took ${duration}ms`);
+    });
+    test("respects explicit dependsOn() ordering in parallel mode", async () => {
+        Config.set({
+            dryRun: false,
+            parallel: true,
+            providers: {},
+        });
+        class DependencyStack extends Stack {
+            // r1 depends on r2
+            r1 = new DelayResource("r1", 20, logs);
+            r2 = new DelayResource("r2", 20, logs);
+            constructor() {
+                super();
+                this.r1.dependsOn(this.r2);
+            }
+        }
+        const stack = new DependencyStack();
+        await stack.deploy();
+        // Since r1 depends on r2, r2 must fully complete before r1 starts
+        const r2StartIndex = logs.indexOf("start:r2");
+        const r2EndIndex = logs.indexOf("end:r2");
+        const r1StartIndex = logs.indexOf("start:r1");
+        assert.ok(r2StartIndex < r2EndIndex);
+        assert.ok(r2EndIndex < r1StartIndex);
+    });
+    test("respects implicit Output waiting in parallel mode", async () => {
+        Config.set({
+            dryRun: false,
+            parallel: true,
+            providers: {},
+        });
+        class OutputAwaitingResource extends BaseBuilder {
+            dependentVal;
+            executionLogs;
+            constructor(name, dependentVal, executionLogs) {
+                super(name);
+                this.dependentVal = dependentVal;
+                this.executionLogs = executionLogs;
+            }
+            async deploy() {
+                this.executionLogs.push(`start:${this.name}`);
+                // Blocks on the Output of the other resource!
+                const val = await this.dependentVal.get();
+                this.executionLogs.push(`end:${this.name}:${val}`);
+                return { name: this.name };
+            }
+        }
+        class OutputStack extends Stack {
+            r1 = new DelayResource("r1", 30, logs);
+            // r2 depends implicitly on r1's output
+            r2 = new OutputAwaitingResource("r2", this.r1.out.val, logs);
+        }
+        const stack = new OutputStack();
+        await stack.deploy();
+        // r2 starts in parallel, but it cannot end until r1 finishes and resolves the output
+        const r2StartIndex = logs.indexOf("start:r2");
+        const r1EndIndex = logs.indexOf("end:r1");
+        const r2EndIndex = logs.findIndex(line => line.startsWith("end:r2"));
+        assert.ok(r2StartIndex >= 0);
+        assert.ok(r1EndIndex >= 0);
+        assert.ok(r1EndIndex < r2EndIndex, `r1 end (${r1EndIndex}) must be before r2 end (${r2EndIndex})`);
+        assert.ok(logs.includes("end:r2:r1"));
+    });
+    test("runs parallel teardowns in reverse topological order on @Destroy", async () => {
+        Config.set({
+            dryRun: false,
+            parallel: true,
+            providers: {},
+        });
+        class TeardownStack extends Stack {
+            r1 = new DelayResource("r1", 20, logs);
+            r2 = new DelayResource("r2", 20, logs);
+            constructor() {
+                super();
+                // r2 depends on r1 during deploy (so r1 deploys first).
+                // Teardown should destroy r2 first, then r1!
+                this.r2.dependsOn(this.r1);
+            }
+        }
+        const stack = new TeardownStack();
+        await stack.destroy();
+        const r2DestroyIndex = logs.indexOf("destroy:r2");
+        const r1DestroyIndex = logs.indexOf("destroy:r1");
+        // r2 depends on r1, so r2 must be fully destroyed BEFORE r1 begins destruction
+        assert.ok(r2DestroyIndex < r1DestroyIndex, `r2 destroy (${r2DestroyIndex}) must be before r1 destroy (${r1DestroyIndex})`);
+    });
+    test("halts execution of dependent resources if a dependency fails", async () => {
+        Config.set({
+            dryRun: false,
+            parallel: true,
+            providers: {},
+        });
+        class FailStack extends Stack {
+            r1 = new FailResource("r1");
+            r2 = new DelayResource("r2", 30, logs);
+            constructor() {
+                super();
+                this.r2.dependsOn(this.r1);
+            }
+        }
+        const stack = new FailStack();
+        await assert.rejects(async () => {
+            await stack.deploy();
+        }, /Failed to deploy!/);
+        // r2 should never have started because its dependency r1 failed!
+        assert.strictEqual(logs.includes("start:r2"), false);
+    });
+    test("decorator option propagation sets configuration values", async () => {
+        // Clear parallel flag
+        Config.set({ parallel: false });
+        // We define a decorated simple stack
+        let SimpleDecoStack = class SimpleDecoStack extends Stack {
+        };
+        SimpleDecoStack = __decorate([
+            Deploy({ parallel: true })
+        ], SimpleDecoStack);
+        // Verify decorator correctly updated global configuration to true
+        assert.strictEqual(Config.isParallelActive(), true);
+    });
+});

package/dist/core/parser.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Robust, zero-dependency, indentation-aware YAML parser.
+ * Parses sequences of key-value maps and nested string arrays.
+ */
+export declare function parseYaml(content: string): any[];
+/**
+ * Resolves a file path relative to the current working directory,
+ * reads its content, and parses it according to its extension (.json vs .yaml/.yml).
+ */
+export declare function loadRecordsFromFile(filePath: string): any[];

package/dist/core/parser.js

@@ -0,0 +1,140 @@
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Strips comments from a YAML/JSON line while preserving comment hashes inside quotes.
+ */
+function stripComments(line) {
+    const hashIdx = line.indexOf("#");
+    if (hashIdx < 0)
+        return line;
+    let inQuotes = false;
+    let quoteChar = "";
+    for (let i = 0; i < hashIdx; i++) {
+        const char = line[i];
+        if (char === '"' || char === "'") {
+            if (!inQuotes) {
+                inQuotes = true;
+                quoteChar = char;
+            }
+            else if (char === quoteChar) {
+                inQuotes = false;
+            }
+        }
+    }
+    if (inQuotes) {
+        return line;
+    }
+    return line.slice(0, hashIdx);
+}
+/**
+ * Robust, zero-dependency, indentation-aware YAML parser.
+ * Parses sequences of key-value maps and nested string arrays.
+ */
+export function parseYaml(content) {
+    const list = [];
+    const lines = content.split(/\r?\n/);
+    let currentItem = null;
+    let activeKey = null;
+    let rootIndent = 0;
+    for (let line of lines) {
+        line = stripComments(line);
+        if (!line.trim())
+            continue;
+        const leadingSpaces = line.length - line.trimStart().length;
+        const trimmed = line.trim();
+        // Check if it's a bullet item list entry
+        if (trimmed.startsWith("-")) {
+            const rest = trimmed.slice(1).trim();
+            // If it is indented more than the root item and does not match a key-value pattern,
+            // treat it as an array item under the active key.
+            const isRestKeyValue = /^[a-zA-Z0-9_-]+\s*:/.test(rest);
+            if (leadingSpaces > rootIndent && !isRestKeyValue) {
+                if (currentItem && activeKey) {
+                    if (!Array.isArray(currentItem[activeKey])) {
+                        currentItem[activeKey] = [];
+                    }
+                    let val = rest;
+                    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+                        val = val.slice(1, -1);
+                    }
+                    currentItem[activeKey].push(val);
+                }
+                continue;
+            }
+            // Otherwise, it represents a new item at the root list level
+            if (currentItem) {
+                list.push(currentItem);
+            }
+            currentItem = {};
+            rootIndent = leadingSpaces;
+            activeKey = null;
+            if (rest) {
+                const colonIdx = rest.indexOf(":");
+                if (colonIdx > 0 && isRestKeyValue) {
+                    const key = rest.slice(0, colonIdx).trim();
+                    let value = rest.slice(colonIdx + 1).trim();
+                    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+                        value = value.slice(1, -1);
+                    }
+                    // Convert to number if numeric
+                    if (/^\d+$/.test(value)) {
+                        currentItem[key] = parseInt(value, 10);
+                    }
+                    else {
+                        currentItem[key] = value;
+                    }
+                    activeKey = key;
+                }
+            }
+        }
+        else {
+            // Key-value pair or list start
+            const isKeyValue = /^[a-zA-Z0-9_-]+\s*:/.test(trimmed);
+            if (isKeyValue && currentItem) {
+                const colonIdx = trimmed.indexOf(":");
+                const key = trimmed.slice(0, colonIdx).trim();
+                let value = trimmed.slice(colonIdx + 1).trim();
+                if (value === "") {
+                    // Starts a nested list/array
+                    currentItem[key] = [];
+                    activeKey = key;
+                }
+                else {
+                    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+                        value = value.slice(1, -1);
+                    }
+                    if (/^\d+$/.test(value)) {
+                        currentItem[key] = parseInt(value, 10);
+                    }
+                    else {
+                        currentItem[key] = value;
+                    }
+                    activeKey = key;
+                }
+            }
+        }
+    }
+    if (currentItem) {
+        list.push(currentItem);
+    }
+    return list;
+}
+/**
+ * Resolves a file path relative to the current working directory,
+ * reads its content, and parses it according to its extension (.json vs .yaml/.yml).
+ */
+export function loadRecordsFromFile(filePath) {
+    const absolutePath = path.resolve(process.cwd(), filePath);
+    const fileContent = fs.readFileSync(absolutePath, "utf-8");
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === ".json") {
+        const parsed = JSON.parse(fileContent);
+        return Array.isArray(parsed) ? parsed : [parsed];
+    }
+    else if (ext === ".yaml" || ext === ".yml") {
+        return parseYaml(fileContent);
+    }
+    else {
+        throw new Error(`Unsupported configuration file format: ${filePath}. Only JSON and YAML/YML files are supported.`);
+    }
+}

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

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

package/dist/core/parser.test.js

@@ -0,0 +1,117 @@
+import { test, describe } from "node:test";
+import assert from "node:assert";
+import fs from "node:fs";
+import path from "node:path";
+import { parseYaml, loadRecordsFromFile } from "./parser.js";
+describe("YAML & JSON Config Parser", () => {
+    test("parses standard simple key-value YAML blocks correctly", () => {
+        const yaml = `
+- name: www
+  type: CNAME
+  value: lb.google.com
+- name: mail
+  type: A
+  value: 1.2.3.4
+  ttl: 600
+`;
+        const result = parseYaml(yaml);
+        assert.strictEqual(result.length, 2);
+        assert.deepStrictEqual(result[0], {
+            name: "www",
+            type: "CNAME",
+            value: "lb.google.com",
+        });
+        assert.deepStrictEqual(result[1], {
+            name: "mail",
+            type: "A",
+            value: "1.2.3.4",
+            ttl: 600,
+        });
+    });
+    test("ignores comments and blank lines in YAML", () => {
+        const yaml = `
+# This is a comment at the top
+- name: "@"
+  type: TXT  # inline comment
+  value: "v=spf1 include:_spf.google.com ~all"
+
+# Another comment with spaces
+- name: api
+  type: CNAME
+  value: api.service.com
+`;
+        const result = parseYaml(yaml);
+        assert.strictEqual(result.length, 2);
+        assert.strictEqual(result[0].name, "@");
+        assert.strictEqual(result[0].type, "TXT");
+        assert.strictEqual(result[0].value, "v=spf1 include:_spf.google.com ~all");
+        assert.strictEqual(result[1].name, "api");
+    });
+    test("parses nested array list values based on indentation", () => {
+        const yaml = `
+- type: ingress
+  protocol: tcp
+  port: 80
+  sources:
+    - 0.0.0.0/0
+    - ::/0
+- type: egress
+  protocol: tcp
+  port: all
+  destinations:
+    - 10.0.0.0/8
+`;
+        const result = parseYaml(yaml);
+        assert.strictEqual(result.length, 2);
+        assert.deepStrictEqual(result[0], {
+            type: "ingress",
+            protocol: "tcp",
+            port: 80,
+            sources: ["0.0.0.0/0", "::/0"],
+        });
+        assert.deepStrictEqual(result[1], {
+            type: "egress",
+            protocol: "tcp",
+            port: "all",
+            destinations: ["10.0.0.0/8"],
+        });
+    });
+    test("loads from JSON and YAML files successfully", () => {
+        const tempJsonPath = path.resolve(process.cwd(), "temp-test-records.json");
+        const tempYamlPath = path.resolve(process.cwd(), "temp-test-records.yaml");
+        const jsonContent = JSON.stringify([
+            { name: "api", type: "CNAME", value: "lb.com" }
+        ]);
+        const yamlContent = `
+- name: web
+  type: A
+  value: 5.6.7.8
+`;
+        // Write temp files
+        fs.writeFileSync(tempJsonPath, jsonContent, "utf-8");
+        fs.writeFileSync(tempYamlPath, yamlContent, "utf-8");
+        try {
+            const parsedJson = loadRecordsFromFile("temp-test-records.json");
+            assert.strictEqual(parsedJson.length, 1);
+            assert.deepStrictEqual(parsedJson[0], {
+                name: "api",
+                type: "CNAME",
+                value: "lb.com",
+            });
+            const parsedYaml = loadRecordsFromFile("temp-test-records.yaml");
+            assert.strictEqual(parsedYaml.length, 1);
+            assert.deepStrictEqual(parsedYaml[0], {
+                name: "web",
+                type: "A",
+                value: "5.6.7.8",
+            });
+        }
+        finally {
+            // Clean up temp files
+            if (fs.existsSync(tempJsonPath))
+                fs.unlinkSync(tempJsonPath);
+            if (fs.existsSync(tempYamlPath))
+                fs.unlinkSync(tempYamlPath);
+        }
+    });
+});

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

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