puls-dev 0.2.6 → 0.2.8

package/README.md

@@ -2,7 +2,7 @@
 
 **Intent-driven infrastructure-as-code. Describe what you want - Puls figures out create, update, or skip.**
 
-[Live Documentation](https://pulsdev.io/) | Discord: **pulsdev.io** ([Join](https://discord.gg/9PcwyjADZj))
+[Live Documentation](https://pulsdev.io/) | Matrix|Gitter: **pulsdev.io** ([Join](https://matrix.to/#/#pulsdevio:gitter.im))
 
 > [!IMPORTANT]
 > **Active Pre-1.0 Development**

package/dist/core/config.d.ts

@@ -4,6 +4,8 @@ export interface GlobalConfig {
         do?: {
             token: string;
             defaultRegion?: string;
+            spacesAccessKey?: string;
+            spacesSecretKey?: string;
         };
         aws?: {
             region: string;

package/dist/core/decorators.d.ts

@@ -2,6 +2,7 @@ import "reflect-metadata";
 type ProviderOpts = {
     token?: string;
     region?: string;
+    regions?: string[];
     dryRun?: boolean;
     firebase?: string;
     proxmox?: {
@@ -17,6 +18,7 @@ type ProviderOpts = {
     };
 };
 export declare function Protected(target: any, propertyKey: string): void;
+export declare function ForceConfigCheck(target: any, propertyKey: string): void;
 export declare function Destroy(target: any, propertyKey: string): void;
 export declare function Destroy(target: Function): void;
 export declare function Destroy(opts: ProviderOpts): (constructor: any) => void;

package/dist/core/decorators.js

@@ -33,6 +33,9 @@ function applyConfig(opts) {
 export function Protected(target, propertyKey) {
     Reflect.defineMetadata("protected", true, target, propertyKey);
 }
+export function ForceConfigCheck(target, propertyKey) {
+    Reflect.defineMetadata("forceConfigCheck", true, target, propertyKey);
+}
 export function Destroy(optsOrTarget, propertyKey) {
     if (propertyKey !== undefined) {
         Reflect.defineMetadata("destroy", true, optsOrTarget, propertyKey);
@@ -48,27 +51,56 @@ export function Destroy(optsOrTarget, propertyKey) {
         return;
     }
     return function (constructor) {
-        applyConfig(optsOrTarget);
-        const instance = new constructor();
-        Stack._register(constructor, instance);
-        Promise.resolve().then(async () => {
-            if (typeof instance.destroy === "function")
-                await instance.destroy();
-        });
+        const regions = optsOrTarget.regions ?? [];
+        if (regions.length > 0) {
+            Promise.resolve().then(async () => {
+                for (const r of regions) {
+                    console.log(`\n🌍 [MULTI-REGION] Tearing down stack in region: ${r}`);
+                    applyConfig({ ...optsOrTarget, region: r });
+                    const instance = new constructor();
+                    Stack._register(constructor, instance, r);
+                    if (typeof instance.destroy === "function")
+                        await instance.destroy();
+                }
+            });
+        }
+        else {
+            applyConfig(optsOrTarget);
+            const instance = new constructor();
+            Stack._register(constructor, instance);
+            Promise.resolve().then(async () => {
+                if (typeof instance.destroy === "function")
+                    await instance.destroy();
+            });
+        }
     };
 }
 // THE "MAGIC": Auto-executing Stack Decorator
 export function Deploy(opts = {}) {
     return function (constructor) {
-        applyConfig(opts);
-        // Instantiate synchronously so resource discovery kicks off immediately and
-        // other stacks can call Stack.from(ThisClass) to reference its Output fields.
-        const instance = new constructor();
-        Stack._register(constructor, instance);
-        Promise.resolve().then(async () => {
-            if (typeof instance.deploy === "function")
-                await instance.deploy();
-        });
+        const regions = opts.regions ?? [];
+        if (regions.length > 0) {
+            Promise.resolve().then(async () => {
+                for (const r of regions) {
+                    console.log(`\n🌍 [MULTI-REGION] Deploying stack to region: ${r}`);
+                    applyConfig({ ...opts, region: r });
+                    const instance = new constructor();
+                    Stack._register(constructor, instance, r);
+                    if (typeof instance.deploy === "function") {
+                        await instance.deploy();
+                    }
+                }
+            });
+        }
+        else {
+            applyConfig(opts);
+            const instance = new constructor();
+            Stack._register(constructor, instance);
+            Promise.resolve().then(async () => {
+                if (typeof instance.deploy === "function")
+                    await instance.deploy();
+            });
+        }
     };
 }
 export function Check(opts = {}) {

package/dist/core/hooks.d.ts

@@ -0,0 +1,21 @@
+export declare const SLACK: {
+    /**
+     * Generates a callback that posts a structured lifecycle notification to a Slack webhook.
+     * In dry-run mode, it outputs a descriptive log to the terminal instead of executing HTTP writes.
+     *
+     * @param webhookUrl The Slack Incoming Webhook URL
+     */
+    notify: (webhookUrl: string) => (result: any) => Promise<void>;
+};
+export declare const DISCORD: {
+    /**
+     * Generates a callback that posts a rich embed lifecycle notification to a Discord webhook.
+     * In dry-run mode, it outputs a descriptive log to the terminal instead of executing HTTP writes.
+     *
+     * @param webhookUrl The Discord Incoming Webhook URL
+     * @example
+     * GCP.CloudRun("api")
+     *   .afterDeploy(DISCORD.notify("https://discord.com/api/webhooks/..."))
+     */
+    notify: (webhookUrl: string) => (result: any) => Promise<void>;
+};

package/dist/core/hooks.js

@@ -0,0 +1,116 @@
+import { Config } from "./config.js";
+export const SLACK = {
+    /**
+     * Generates a callback that posts a structured lifecycle notification to a Slack webhook.
+     * In dry-run mode, it outputs a descriptive log to the terminal instead of executing HTTP writes.
+     *
+     * @param webhookUrl The Slack Incoming Webhook URL
+     */
+    notify: (webhookUrl) => {
+        return async (result) => {
+            const name = result?.name ?? "unknown-resource";
+            const isDryRun = Config.isGlobalDryRun();
+            // Check if it's a destroy result or deploy result
+            const isDestroy = result && ("destroyed" in result || result.destroyed === true);
+            const action = isDestroy ? "destroyed" : "deployed/updated";
+            const statusEmoji = isDestroy ? "🗑️" : "🚀";
+            // Filter and print simple key-value attributes
+            const details = Object.entries(result ?? {})
+                .filter(([k, v]) => k !== "name" &&
+                k !== "destroyed" &&
+                (typeof v === "string" || typeof v === "number" || typeof v === "boolean"))
+                .map(([k, v]) => `• *${k}*: \`${v}\``)
+                .join("\n");
+            const text = `${statusEmoji} *Puls Notification*: Resource *${name}* was successfully *${action}*!\n${details ? `*Details*:\n${details}` : ""}`;
+            if (isDryRun) {
+                console.log(`\n📢 [DRY RUN] Would post Slack notification to webhook: ${webhookUrl}`);
+                console.log(`   Message: ${text.replace(/\n/g, "\n   ")}`);
+                return;
+            }
+            try {
+                const res = await fetch(webhookUrl, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify({ text }),
+                });
+                if (!res.ok) {
+                    console.warn(`[WARN] Slack webhook returned status ${res.status}`);
+                }
+            }
+            catch (err) {
+                console.error(`[ERROR] Failed to send Slack notification: ${err.message}`);
+            }
+        };
+    },
+};
+export const DISCORD = {
+    /**
+     * Generates a callback that posts a rich embed lifecycle notification to a Discord webhook.
+     * In dry-run mode, it outputs a descriptive log to the terminal instead of executing HTTP writes.
+     *
+     * @param webhookUrl The Discord Incoming Webhook URL
+     * @example
+     * GCP.CloudRun("api")
+     *   .afterDeploy(DISCORD.notify("https://discord.com/api/webhooks/..."))
+     */
+    notify: (webhookUrl) => {
+        return async (result) => {
+            const name = result?.name ?? "unknown-resource";
+            const isDryRun = Config.isGlobalDryRun();
+            // Check if it's a destroy result or deploy result
+            const isDestroy = result && ("destroyed" in result || result.destroyed === true);
+            const action = isDestroy ? "destroyed" : "deployed/updated";
+            const statusEmoji = isDestroy ? "🗑️" : "🚀";
+            // Green (0x2ecc71) for deploy, Red (0xe74c3c) for destroy
+            const color = isDestroy ? 15158332 : 3066993;
+            const fields = Object.entries(result ?? {})
+                .filter(([k, v]) => k !== "name" &&
+                k !== "destroyed" &&
+                (typeof v === "string" || typeof v === "number" || typeof v === "boolean"))
+                .map(([k, v]) => ({
+                name: k,
+                value: `\`${v}\``,
+                inline: true,
+            }));
+            const payload = {
+                embeds: [
+                    {
+                        title: `${statusEmoji} Puls Notification`,
+                        description: `Resource **${name}** was successfully **${action}**!`,
+                        color,
+                        fields,
+                        footer: {
+                            text: "Puls Dev Suite",
+                        },
+                        timestamp: new Date().toISOString(),
+                    },
+                ],
+            };
+            if (isDryRun) {
+                console.log(`\n📢 [DRY RUN] Would post Discord notification to webhook: ${webhookUrl}`);
+                console.log(`   Embed Title: ${statusEmoji} Puls Notification`);
+                console.log(`   Embed Description: Resource **${name}** was successfully **${action}**!`);
+                if (fields.length > 0) {
+                    console.log("   Fields:");
+                    for (const f of fields) {
+                        console.log(`     • ${f.name}: ${f.value}`);
+                    }
+                }
+                return;
+            }
+            try {
+                const res = await fetch(webhookUrl, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json" },
+                    body: JSON.stringify(payload),
+                });
+                if (!res.ok) {
+                    console.warn(`[WARN] Discord webhook returned status ${res.status}`);
+                }
+            }
+            catch (err) {
+                console.error(`[ERROR] Failed to send Discord notification: ${err.message}`);
+            }
+        };
+    },
+};

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

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

package/dist/core/hooks.test.js

@@ -0,0 +1,194 @@
+import { test, describe, beforeEach } from "node:test";
+import assert from "node:assert";
+import { Stack } from "./stack.js";
+import { BaseBuilder } from "./resource.js";
+import { Config } from "./config.js";
+import { SLACK, DISCORD } from "./hooks.js";
+// A minimal dummy resource builder for testing hooks
+class TestResource extends BaseBuilder {
+    resultValue;
+    constructor(name, resultValue = { name: "test-res", ip: "1.2.3.4" }) {
+        super(name);
+        this.resultValue = resultValue;
+    }
+    async deploy() {
+        return this.resultValue;
+    }
+    async destroy() {
+        return { name: this.name, destroyed: true };
+    }
+}
+describe("Lifecycle Hooks & Notifier Tests", () => {
+    let executionLogs = [];
+    beforeEach(() => {
+        Config.set({
+            dryRun: false,
+            providers: {},
+        });
+        executionLogs = [];
+    });
+    test("runs Stack-level and Resource-level deploy hooks in the correct order", async () => {
+        class MyStack extends Stack {
+            async beforeDeploy() {
+                executionLogs.push("stack-before-deploy");
+            }
+            async afterDeploy(outputs) {
+                executionLogs.push(`stack-after-deploy:${outputs.res.ip}`);
+            }
+            res = new TestResource("my-res", { name: "my-res", ip: "9.9.9.9" })
+                .beforeDeploy(() => {
+                executionLogs.push("res-before-deploy");
+            })
+                .afterDeploy((result) => {
+                executionLogs.push(`res-after-deploy:${result.ip}`);
+            });
+        }
+        const stack = new MyStack();
+        const outputs = await stack.deploy();
+        // Verify ordering
+        assert.deepStrictEqual(executionLogs, [
+            "stack-before-deploy",
+            "res-before-deploy",
+            "res-after-deploy:9.9.9.9",
+            "stack-after-deploy:9.9.9.9",
+        ]);
+        assert.deepStrictEqual(outputs.res, { name: "my-res", ip: "9.9.9.9" });
+    });
+    test("runs Stack-level and Resource-level destroy hooks in the correct order", async () => {
+        class MyStack extends Stack {
+            async beforeDestroy() {
+                executionLogs.push("stack-before-destroy");
+            }
+            async afterDestroy(outputs) {
+                executionLogs.push(`stack-after-destroy:${outputs.res.destroyed}`);
+            }
+            res = new TestResource("my-res")
+                .beforeDestroy(() => {
+                executionLogs.push("res-before-destroy");
+            })
+                .afterDestroy((result) => {
+                executionLogs.push(`res-after-destroy:${result.destroyed}`);
+            });
+        }
+        const stack = new MyStack();
+        const outputs = await stack.destroy();
+        // Verify ordering (destroy properties are iterated in reverse order, which doesn't affect single resource)
+        assert.deepStrictEqual(executionLogs, [
+            "stack-before-destroy",
+            "res-before-destroy",
+            "res-after-destroy:true",
+            "stack-after-destroy:true",
+        ]);
+        assert.deepStrictEqual(outputs.res, { name: "my-res", destroyed: true });
+    });
+    test("SLACK.notify helper sends fetch call on real deploys", async () => {
+        const originalFetch = globalThis.fetch;
+        let fetchPayload = null;
+        let fetchUrl = "";
+        globalThis.fetch = (async (url, init) => {
+            fetchUrl = url;
+            fetchPayload = JSON.parse(init?.body);
+            return {
+                ok: true,
+                status: 200,
+            };
+        });
+        try {
+            const webhook = "https://hooks.slack.com/services/T00/B00/X00";
+            const notifyHook = SLACK.notify(webhook);
+            const deployResult = { name: "web-app", url: "https://web.run.app", ip: "1.2.3.4" };
+            await notifyHook(deployResult);
+            assert.strictEqual(fetchUrl, webhook);
+            assert.ok(fetchPayload);
+            assert.ok(fetchPayload.text.includes("🚀"));
+            assert.ok(fetchPayload.text.includes("web-app"));
+            assert.ok(fetchPayload.text.includes("https://web.run.app"));
+            assert.ok(fetchPayload.text.includes("1.2.3.4"));
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+        }
+    });
+    test("SLACK.notify helper formats text and logs to console on dry-runs", async () => {
+        Config.set({
+            dryRun: true,
+            providers: {},
+        });
+        const originalLog = console.log;
+        let logOutput = "";
+        console.log = (...args) => {
+            logOutput += args.join(" ") + "\n";
+        };
+        try {
+            const notifyHook = SLACK.notify("https://hooks.slack.com/services/T00");
+            const destroyResult = { name: "old-db", destroyed: true };
+            await notifyHook(destroyResult);
+            assert.ok(logOutput.includes("📢 [DRY RUN]"));
+            assert.ok(logOutput.includes("Would post Slack notification"));
+            assert.ok(logOutput.includes("🗑️"));
+            assert.ok(logOutput.includes("old-db"));
+            assert.ok(logOutput.includes("destroyed"));
+        }
+        finally {
+            console.log = originalLog;
+        }
+    });
+    test("DISCORD.notify helper sends fetch call with rich embed on real deploys", async () => {
+        const originalFetch = globalThis.fetch;
+        let fetchPayload = null;
+        let fetchUrl = "";
+        globalThis.fetch = (async (url, init) => {
+            fetchUrl = url;
+            fetchPayload = JSON.parse(init?.body);
+            return {
+                ok: true,
+                status: 200,
+            };
+        });
+        try {
+            const webhook = "https://discord.com/api/webhooks/123/abc";
+            const notifyHook = DISCORD.notify(webhook);
+            const deployResult = { name: "api-srv", url: "https://api.run.app", active: true };
+            await notifyHook(deployResult);
+            assert.strictEqual(fetchUrl, webhook);
+            assert.ok(fetchPayload);
+            assert.ok(fetchPayload.embeds);
+            assert.strictEqual(fetchPayload.embeds.length, 1);
+            const embed = fetchPayload.embeds[0];
+            assert.strictEqual(embed.title, "🚀 Puls Notification");
+            assert.ok(embed.description.includes("api-srv"));
+            assert.ok(embed.description.includes("deployed/updated"));
+            assert.strictEqual(embed.color, 3066993); // Green
+            assert.strictEqual(embed.fields.length, 2);
+            assert.deepStrictEqual(embed.fields[0], { name: "url", value: "`https://api.run.app`", inline: true });
+            assert.deepStrictEqual(embed.fields[1], { name: "active", value: "`true`", inline: true });
+        }
+        finally {
+            globalThis.fetch = originalFetch;
+        }
+    });
+    test("DISCORD.notify helper formats embeds and logs to console on dry-runs", async () => {
+        Config.set({
+            dryRun: true,
+            providers: {},
+        });
+        const originalLog = console.log;
+        let logOutput = "";
+        console.log = (...args) => {
+            logOutput += args.join(" ") + "\n";
+        };
+        try {
+            const notifyHook = DISCORD.notify("https://discord.com/api/webhooks/123");
+            const destroyResult = { name: "old-cache", destroyed: true };
+            await notifyHook(destroyResult);
+            assert.ok(logOutput.includes("📢 [DRY RUN]"));
+            assert.ok(logOutput.includes("Would post Discord notification"));
+            assert.ok(logOutput.includes("🗑️"));
+            assert.ok(logOutput.includes("old-cache"));
+            assert.ok(logOutput.includes("destroyed"));
+        }
+        finally {
+            console.log = originalLog;
+        }
+    });
+});

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

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

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/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[];