puls-dev 0.2.7 → 0.2.9

package/dist/core/checker.js

@@ -123,6 +123,53 @@ function renderAws(inv) {
         ]);
     }
 }
+function renderGcp(inv) {
+    if (inv.vms.length > 0) {
+        printSection(`GCP Compute VMs  ·  ${inv.vms.length}`, inv.vms, [
+            { header: "Name", width: 24, render: (v) => v.name },
+            { header: "Zone", width: 15, render: (v) => v.zone },
+            { header: "Machine Type", width: 14, render: (v) => v.machineType },
+            { header: "Status", width: 8, render: (v) => v.status },
+            { header: "IP", width: 15, render: (v) => v.ip },
+        ]);
+    }
+    if (inv.rdsInstances.length > 0) {
+        printSection(`GCP Cloud SQL  ·  ${inv.rdsInstances.length}`, inv.rdsInstances, [
+            { header: "Name", width: 24, render: (i) => i.name },
+            { header: "Engine", width: 18, render: (i) => i.engine },
+            { header: "Tier", width: 12, render: (i) => i.tier },
+            { header: "Status", width: 10, render: (i) => i.status },
+        ]);
+    }
+    if (inv.distributions.length > 0) {
+        printSection(`GCP Cloud Run  ·  ${inv.distributions.length}`, inv.distributions, [
+            { header: "Service", width: 24, render: (s) => s.name },
+            { header: "Region", width: 12, render: (s) => s.region },
+            { header: "URL", width: 42, render: (s) => s.url },
+        ]);
+    }
+    if (inv.hostedZones.length > 0) {
+        printSection(`GCP Cloud DNS  ·  ${inv.hostedZones.length}`, inv.hostedZones, [
+            { header: "Zone", width: 24, render: (z) => z.name },
+            { header: "DNS Name", width: 32, render: (z) => z.dnsName },
+        ]);
+    }
+}
+function renderFirebase(inv) {
+    if (inv.hostingSites.length > 0) {
+        printSection(`Firebase Hosting  ·  ${inv.hostingSites.length}`, inv.hostingSites, [
+            { header: "Site ID", width: 32, render: (s) => s.site },
+        ]);
+    }
+    if (inv.functions.length > 0) {
+        printSection(`Firebase Functions  ·  ${inv.functions.length}`, inv.functions, [
+            { header: "Function", width: 24, render: (f) => f.name },
+            { header: "Region", width: 12, render: (f) => f.region },
+            { header: "Entry Point", width: 18, render: (f) => f.entryPoint },
+            { header: "Runtime", width: 10, render: (f) => f.runtime },
+        ]);
+    }
+}
 // ─── Checker ──────────────────────────────────────────────────────────────────
 export class Checker {
     async check() {
@@ -161,6 +208,26 @@ export class Checker {
                 errors.push({ provider: "aws", message: err.message });
             }));
         }
+        if (cfg.providers.gcp?.serviceAccountPath || process.env.GCP_SA) {
+            tasks.push(import("../providers/gcp/list.js")
+                .then((m) => m.listGcpResources())
+                .then((inv) => {
+                result.gcp = inv;
+            })
+                .catch((err) => {
+                errors.push({ provider: "gcp", message: err.message });
+            }));
+        }
+        if (cfg.providers.firebase?.serviceAccountPath || process.env.FIREBASE_SA) {
+            tasks.push(import("../providers/firebase/list.js")
+                .then((m) => m.listFirebaseResources())
+                .then((inv) => {
+                result.firebase = inv;
+            })
+                .catch((err) => {
+                errors.push({ provider: "firebase", message: err.message });
+            }));
+        }
         await Promise.all(tasks);
         if (result.proxmox)
             renderProxmox(result.proxmox);
@@ -168,6 +235,10 @@ export class Checker {
             renderDo(result.do);
         if (result.aws)
             renderAws(result.aws);
+        if (result.gcp)
+            renderGcp(result.gcp);
+        if (result.firebase)
+            renderFirebase(result.firebase);
         for (const e of errors) {
             console.warn(`\n  [!] ${e.provider}: ${e.message}`);
         }

package/dist/core/config.d.ts

@@ -1,9 +1,13 @@
 export interface GlobalConfig {
     dryRun?: boolean;
+    parallel?: boolean;
+    offline?: boolean;
     providers: {
         do?: {
             token: string;
             defaultRegion?: string;
+            spacesAccessKey?: string;
+            spacesSecretKey?: string;
         };
         aws?: {
             region: string;
@@ -35,6 +39,8 @@ declare class ConfigManager {
     set(newConfig: Partial<GlobalConfig>): void;
     get(): GlobalConfig;
     isGlobalDryRun(): boolean;
+    isParallelActive(): boolean;
+    isOfflineMode(): boolean;
 }
 export declare const Config: ConfigManager;
 export {};

package/dist/core/config.js

@@ -3,7 +3,11 @@ class ConfigManager {
         providers: {},
     };
     set(newConfig) {
-        this.config = { ...this.config, ...newConfig };
+        this.config = {
+            ...this.config,
+            ...newConfig,
+            providers: { ...this.config.providers, ...newConfig.providers },
+        };
     }
     get() {
         return this.config;
@@ -11,5 +15,11 @@ class ConfigManager {
     isGlobalDryRun() {
         return this.config.dryRun ?? false;
     }
+    isParallelActive() {
+        return this.config.parallel ?? false;
+    }
+    isOfflineMode() {
+        return this.config.offline ?? false;
+    }
 }
 export const Config = new ConfigManager();

package/dist/core/context.d.ts

@@ -0,0 +1,14 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export interface HostEntry {
+    name: string;
+    ip: string;
+    user: string;
+    sshKey?: string;
+    provider: string;
+}
+export interface ResourceContext {
+    abortSignal?: AbortSignal;
+    hosts?: HostEntry[];
+    stackName?: string;
+}
+export declare const resourceContextStorage: AsyncLocalStorage<ResourceContext>;

package/dist/core/context.js

@@ -0,0 +1,2 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+export const resourceContextStorage = new AsyncLocalStorage();

package/dist/core/decorators.d.ts

@@ -2,7 +2,10 @@ import "reflect-metadata";
 type ProviderOpts = {
     token?: string;
     region?: string;
+    regions?: string[];
     dryRun?: boolean;
+    parallel?: boolean;
+    offline?: boolean;
     firebase?: string;
     proxmox?: {
         url: string;
@@ -17,6 +20,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

@@ -5,27 +5,21 @@ import { Stack } from "./stack.js";
 function applyConfig(opts) {
     if (opts.dryRun !== undefined)
         Config.set({ dryRun: opts.dryRun });
+    if (opts.parallel !== undefined)
+        Config.set({ parallel: opts.parallel });
+    if (opts.offline !== undefined)
+        Config.set({ offline: opts.offline });
     if (opts.token)
-        Config.set({
-            providers: { ...Config.get().providers, do: { token: opts.token } },
-        });
+        Config.set({ providers: { do: { token: opts.token } } });
     if (opts.region)
-        Config.set({
-            providers: { ...Config.get().providers, aws: { region: opts.region } },
-        });
+        Config.set({ providers: { aws: { region: opts.region } } });
     if (opts.proxmox)
-        Config.set({
-            providers: { ...Config.get().providers, proxmox: opts.proxmox },
-        });
+        Config.set({ providers: { proxmox: opts.proxmox } });
     if (opts.firebase) {
         const sa = JSON.parse(readFileSync(opts.firebase, "utf8"));
         Config.set({
             providers: {
-                ...Config.get().providers,
-                firebase: {
-                    projectId: sa.project_id,
-                    serviceAccountPath: opts.firebase,
-                },
+                firebase: { projectId: sa.project_id, serviceAccountPath: opts.firebase },
             },
         });
     }
@@ -33,6 +27,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 +45,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 {};