puls-dev 0.2.0 → 0.2.1

package/dist/providers/aws/index.d.ts

@@ -7,6 +7,9 @@ import { FargateBuilder } from "./fargate.js";
 import { RDSBuilder } from "./rds.js";
 import { SQSBuilder } from "./sqs.js";
 import { SecretsBuilder } from "./secrets.js";
+import { IAMRoleBuilder, IAMPolicyBuilder } from "./iam.js";
+import { SNSTopicBuilder } from "./sns.js";
+import { CloudWatchAlarmBuilder } from "./cloudwatch.js";
 export declare const AWS: {
     init: (opts: {
         region: string;
@@ -20,5 +23,9 @@ export declare const AWS: {
     RDS: (name: string) => RDSBuilder;
     SQS: (name: string) => SQSBuilder;
     Secret: (secretId: string) => SecretsBuilder;
+    IAMRole: (name: string) => IAMRoleBuilder;
+    IAMPolicy: (name: string) => IAMPolicyBuilder;
+    SNS: (name: string) => SNSTopicBuilder;
+    Alarm: (name: string) => CloudWatchAlarmBuilder;
 };
 export * from "../../types/aws.js";

package/dist/providers/aws/index.js

@@ -8,6 +8,9 @@ import { FargateBuilder } from "./fargate.js";
 import { RDSBuilder } from "./rds.js";
 import { SQSBuilder } from "./sqs.js";
 import { SecretsBuilder } from "./secrets.js";
+import { IAMRoleBuilder, IAMPolicyBuilder } from "./iam.js";
+import { SNSTopicBuilder } from "./sns.js";
+import { CloudWatchAlarmBuilder } from "./cloudwatch.js";
 export const AWS = {
     init: (opts) => {
         Config.set({
@@ -26,5 +29,9 @@ export const AWS = {
     RDS: (name) => new RDSBuilder(name),
     SQS: (name) => new SQSBuilder(name),
     Secret: (secretId) => new SecretsBuilder(secretId),
+    IAMRole: (name) => new IAMRoleBuilder(name),
+    IAMPolicy: (name) => new IAMPolicyBuilder(name),
+    SNS: (name) => new SNSTopicBuilder(name),
+    Alarm: (name) => new CloudWatchAlarmBuilder(name),
 };
 export * from "../../types/aws.js";

package/dist/providers/aws/lambda.d.ts

@@ -1,5 +1,6 @@
 import { BaseBuilder } from "../../core/resource.js";
 import { SecretsBuilder } from "./secrets.js";
+import { IAMRoleBuilder } from "./iam.js";
 export declare class LambdaBuilder extends BaseBuilder {
     private _runtime;
     private _handler;
@@ -8,6 +9,7 @@ export declare class LambdaBuilder extends BaseBuilder {
     private _codePath?;
     private _env;
     private _roleArn?;
+    private _roleBuilder?;
     resolvedArn: string | null;
     constructor(name: string);
     private discoverFunction;
@@ -16,7 +18,7 @@ export declare class LambdaBuilder extends BaseBuilder {
     handler(h: string): this;
     memory(mb: number): this;
     timeout(seconds: number): this;
-    role(arn: string): this;
+    role(arnOrBuilder: string | IAMRoleBuilder): this;
     env(vars: Record<string, string | SecretsBuilder>): this;
     private ensureRole;
     private buildZip;

package/dist/providers/aws/lambda.js

@@ -25,6 +25,7 @@ export class LambdaBuilder extends BaseBuilder {
     _codePath;
     _env = {};
     _roleArn;
+    _roleBuilder;
     resolvedArn = null;
     constructor(name) {
         super(name);
@@ -64,8 +65,13 @@ export class LambdaBuilder extends BaseBuilder {
         this._timeout = seconds;
         return this;
     }
-    role(arn) {
-        this._roleArn = arn;
+    role(arnOrBuilder) {
+        if (typeof arnOrBuilder === "string") {
+            this._roleArn = arnOrBuilder;
+        }
+        else {
+            this._roleBuilder = arnOrBuilder;
+        }
         return this;
     }
     env(vars) {
@@ -73,6 +79,9 @@ export class LambdaBuilder extends BaseBuilder {
         return this;
     }
     async ensureRole() {
+        if (this._roleBuilder) {
+            return await this._roleBuilder.out.arn.get();
+        }
         if (this._roleArn)
             return this._roleArn;
         const roleName = `puls-lambda-${this.name}-role`;

package/dist/providers/aws/rds.d.ts

@@ -14,6 +14,7 @@ export declare class RDSBuilder extends BaseBuilder {
     resolvedPort: number | null;
     resolvedArn: string | null;
     constructor(name: string);
+    get dbInstanceIdentifier(): string;
     engine(e: {
         engine: string;
         version: string;

package/dist/providers/aws/rds.js

@@ -26,6 +26,9 @@ export class RDSBuilder extends BaseBuilder {
         super(name);
         this.discoveryPromise = this.discoverInstance(name);
     }
+    get dbInstanceIdentifier() {
+        return this.name;
+    }
     engine(e) {
         this._engine = e.engine;
         this._engineVersion = e.version;
@@ -74,7 +77,7 @@ export class RDSBuilder extends BaseBuilder {
             return instance;
         }
         catch (e) {
-            if (e.name === "DBInstanceNotFound")
+            if (e.name === "DBInstanceNotFound" || e.name === "DBInstanceNotFoundFault")
                 return null;
             if (e.name === "CredentialsProviderError")
                 return null;

package/dist/providers/aws/sns.d.ts

@@ -0,0 +1,22 @@
+import { BaseBuilder } from "../../core/resource.js";
+import { Output } from "../../core/output.js";
+export declare class SNSTopicBuilder extends BaseBuilder {
+    readonly out: {
+        arn: Output<string>;
+    };
+    private _displayName?;
+    private _subscriptions;
+    resolvedArn: string | null;
+    resolvedDisplayName: string | null;
+    constructor(name: string);
+    displayName(name: string): this;
+    subscribe(protocol: "email" | "sms" | "lambda" | "sqs" | "https", endpoint: string): this;
+    private discoverTopic;
+    deploy(): Promise<{
+        name: string;
+        arn: string | null;
+    }>;
+    destroy(): Promise<{
+        destroyed: string;
+    }>;
+}

package/dist/providers/aws/sns.js

@@ -0,0 +1,146 @@
+import { CreateTopicCommand, DeleteTopicCommand, GetTopicAttributesCommand, ListTopicsCommand, SetTopicAttributesCommand, SubscribeCommand, UnsubscribeCommand, ListSubscriptionsByTopicCommand, } from "@aws-sdk/client-sns";
+import { BaseBuilder } from "../../core/resource.js";
+import { Output } from "../../core/output.js";
+import { getSNSClient } from "./api.js";
+export class SNSTopicBuilder extends BaseBuilder {
+    out = {
+        arn: new Output(),
+    };
+    _displayName;
+    _subscriptions = [];
+    resolvedArn = null;
+    resolvedDisplayName = null;
+    constructor(name) {
+        super(name);
+        this.discoveryPromise = this.discoverTopic(name);
+    }
+    displayName(name) {
+        this._displayName = name;
+        return this;
+    }
+    subscribe(protocol, endpoint) {
+        this._subscriptions.push({ protocol, endpoint });
+        return this;
+    }
+    async discoverTopic(name) {
+        const sns = getSNSClient();
+        try {
+            let nextToken;
+            do {
+                const result = await sns.send(new ListTopicsCommand({ NextToken: nextToken }));
+                const match = (result.Topics ?? []).find((t) => t.TopicArn?.split(":").pop() === name);
+                if (match) {
+                    this.resolvedArn = match.TopicArn ?? null;
+                    if (this.resolvedArn) {
+                        this.out.arn.resolve(this.resolvedArn);
+                        try {
+                            const attrsResult = await sns.send(new GetTopicAttributesCommand({ TopicArn: this.resolvedArn }));
+                            this.resolvedDisplayName = attrsResult.Attributes?.DisplayName ?? null;
+                        }
+                        catch (err) {
+                            // Ignore attribute fetch errors (e.g. permission or not found)
+                        }
+                    }
+                    return match;
+                }
+                nextToken = result.NextToken;
+            } while (nextToken);
+            return null;
+        }
+        catch (e) {
+            if (e.name === "CredentialsProviderError")
+                return null;
+            throw e;
+        }
+    }
+    async deploy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        const sns = getSNSClient();
+        console.log(`\n📢 Finalizing SNS Topic "${this.name}"...`);
+        if (dryRun) {
+            console.log(`   📝 [PLAN] ${existing ? "Update" : "Create"} SNS topic "${this.name}"`);
+            if (this._displayName) {
+                console.log(`      └─ Display Name: ${this._displayName}`);
+            }
+            for (const sub of this._subscriptions) {
+                console.log(`      └─ Subscribe: ${sub.protocol} to ${sub.endpoint}`);
+            }
+            this.resolvedArn = existing?.TopicArn ?? `arn:aws:sns:us-east-1:000000000000:DRYRUN-${this.name}`;
+            this.out.arn.resolve(this.resolvedArn);
+            return { name: this.name, arn: this.resolvedArn };
+        }
+        const topicAttrs = {};
+        if (this._displayName) {
+            topicAttrs.DisplayName = this._displayName;
+        }
+        if (!existing) {
+            const result = await sns.send(new CreateTopicCommand({
+                Name: this.name,
+                Attributes: topicAttrs,
+            }));
+            this.resolvedArn = result.TopicArn;
+            this.out.arn.resolve(this.resolvedArn);
+            console.log(`🚀 Created SNS Topic "${this.name}" (arn=${this.resolvedArn})`);
+        }
+        else {
+            this.resolvedArn = existing.TopicArn;
+            this.out.arn.resolve(this.resolvedArn);
+            if (this._displayName && this._displayName !== this.resolvedDisplayName) {
+                await sns.send(new SetTopicAttributesCommand({
+                    TopicArn: this.resolvedArn,
+                    AttributeName: "DisplayName",
+                    AttributeValue: this._displayName,
+                }));
+                console.log(`   ✅ Updated SNS topic display name to "${this._displayName}"`);
+            }
+            else {
+                console.log(`   ✅ SNS topic "${this.name}" already exists`);
+            }
+        }
+        // Sync subscriptions
+        const activeSubsResult = await sns.send(new ListSubscriptionsByTopicCommand({ TopicArn: this.resolvedArn }));
+        const activeSubs = activeSubsResult.Subscriptions ?? [];
+        // 1. Unsubscribe stale subscriptions
+        for (const sub of activeSubs) {
+            if (!sub.SubscriptionArn || sub.SubscriptionArn === "PendingConfirmation")
+                continue;
+            const isStillWanted = this._subscriptions.some((s) => s.protocol === sub.Protocol && s.endpoint === sub.Endpoint);
+            if (!isStillWanted) {
+                await sns.send(new UnsubscribeCommand({ SubscriptionArn: sub.SubscriptionArn }));
+                console.log(`   🧹 Unsubscribed stale subscription: ${sub.Protocol} to ${sub.Endpoint}`);
+            }
+        }
+        // 2. Subscribe new subscriptions
+        for (const target of this._subscriptions) {
+            const alreadyExists = activeSubs.some((sub) => sub.Protocol === target.protocol && sub.Endpoint === target.endpoint);
+            if (!alreadyExists) {
+                await sns.send(new SubscribeCommand({
+                    TopicArn: this.resolvedArn,
+                    Protocol: target.protocol,
+                    Endpoint: target.endpoint,
+                }));
+                console.log(`   ➕ Subscribed: ${target.protocol} to ${target.endpoint}`);
+            }
+        }
+        await this.deploySidecars();
+        return { name: this.name, arn: this.resolvedArn };
+    }
+    async destroy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        console.log(`\n🗑️  Destroying SNS Topic "${this.name}"...`);
+        if (!existing) {
+            console.log(`   ✅ Topic "${this.name}" does not exist - nothing to do`);
+            return { destroyed: this.name };
+        }
+        if (dryRun) {
+            console.log(`   📝 [PLAN] Delete SNS Topic "${this.name}"`);
+            return { destroyed: this.name };
+        }
+        const sns = getSNSClient();
+        await sns.send(new DeleteTopicCommand({ TopicArn: this.resolvedArn }));
+        console.log(`   ✅ Deleted SNS Topic "${this.name}"`);
+        return { destroyed: this.name };
+    }
+}

package/dist/providers/aws/sns.test.d.ts

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

package/dist/providers/aws/sns.test.js

@@ -0,0 +1,162 @@
+import { test, describe, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+import { SNSClient } from "@aws-sdk/client-sns";
+import { SNSTopicBuilder } from "./sns.js";
+import { Config } from "../../core/config.js";
+describe("SNSTopicBuilder Unit Tests", () => {
+    let originalSnsSend;
+    let snsCalls = [];
+    let mockSnsResponses = {};
+    beforeEach(() => {
+        Config.set({
+            dryRun: false,
+            providers: {
+                aws: { region: "us-east-1" },
+            },
+        });
+        snsCalls = [];
+        mockSnsResponses = {};
+        originalSnsSend = SNSClient.prototype.send;
+        SNSClient.prototype.send = async function (command) {
+            const commandName = command.constructor.name;
+            const input = command.input;
+            snsCalls.push({ commandName, input });
+            if (mockSnsResponses[commandName]) {
+                const handler = mockSnsResponses[commandName];
+                if (typeof handler === "function")
+                    return handler(input);
+                if (handler instanceof Error)
+                    throw handler;
+                return handler;
+            }
+            return {};
+        };
+    });
+    afterEach(() => {
+        SNSClient.prototype.send = originalSnsSend;
+    });
+    test("gracefully handles discovery when topic does not exist", async () => {
+        mockSnsResponses["ListTopicsCommand"] = { Topics: [] };
+        const builder = new SNSTopicBuilder("my-topic");
+        const discoveryResult = await builder.discoveryPromise;
+        assert.strictEqual(discoveryResult, null);
+        assert.ok(snsCalls.some((c) => c.commandName === "ListTopicsCommand"));
+    });
+    test("discovers existing topic by matching name", async () => {
+        mockSnsResponses["ListTopicsCommand"] = {
+            Topics: [{ TopicArn: "arn:aws:sns:us-east-1:123456789012:my-topic" }],
+        };
+        mockSnsResponses["GetTopicAttributesCommand"] = {
+            Attributes: { DisplayName: "My Friendly Topic" },
+        };
+        const builder = new SNSTopicBuilder("my-topic");
+        const discoveryResult = await builder.discoveryPromise;
+        assert.ok(discoveryResult);
+        assert.strictEqual(builder.resolvedArn, "arn:aws:sns:us-east-1:123456789012:my-topic");
+        assert.strictEqual(builder.resolvedDisplayName, "My Friendly Topic");
+        const resolvedArn = await builder.out.arn.get();
+        assert.strictEqual(resolvedArn, "arn:aws:sns:us-east-1:123456789012:my-topic");
+    });
+    test("creates a new topic with display name and subscriptions", async () => {
+        mockSnsResponses["ListTopicsCommand"] = { Topics: [] };
+        mockSnsResponses["CreateTopicCommand"] = {
+            TopicArn: "arn:aws:sns:us-east-1:123456789012:my-topic",
+        };
+        mockSnsResponses["ListSubscriptionsByTopicCommand"] = { Subscriptions: [] };
+        const builder = new SNSTopicBuilder("my-topic")
+            .displayName("Cool Alert")
+            .subscribe("email", "ops@company.com")
+            .subscribe("sms", "+15555555555");
+        const deployResult = await builder.deploy();
+        assert.strictEqual(deployResult.arn, "arn:aws:sns:us-east-1:123456789012:my-topic");
+        assert.strictEqual(builder.resolvedArn, "arn:aws:sns:us-east-1:123456789012:my-topic");
+        const createCall = snsCalls.find((c) => c.commandName === "CreateTopicCommand");
+        assert.ok(createCall);
+        assert.deepStrictEqual(createCall.input, {
+            Name: "my-topic",
+            Attributes: { DisplayName: "Cool Alert" },
+        });
+        const subscribeCalls = snsCalls.filter((c) => c.commandName === "SubscribeCommand");
+        assert.strictEqual(subscribeCalls.length, 2);
+        assert.deepStrictEqual(subscribeCalls[0].input, {
+            TopicArn: "arn:aws:sns:us-east-1:123456789012:my-topic",
+            Protocol: "email",
+            Endpoint: "ops@company.com",
+        });
+        assert.deepStrictEqual(subscribeCalls[1].input, {
+            TopicArn: "arn:aws:sns:us-east-1:123456789012:my-topic",
+            Protocol: "sms",
+            Endpoint: "+15555555555",
+        });
+    });
+    test("syncs subscriptions correctly - unsubscribes stale and skips active", async () => {
+        mockSnsResponses["ListTopicsCommand"] = {
+            Topics: [{ TopicArn: "arn:aws:sns:us-east-1:123456789012:my-topic" }],
+        };
+        mockSnsResponses["GetTopicAttributesCommand"] = {
+            Attributes: { DisplayName: "Cool Alert" },
+        };
+        mockSnsResponses["ListSubscriptionsByTopicCommand"] = {
+            Subscriptions: [
+                {
+                    SubscriptionArn: "arn:aws:sns:us-east-1:123456789012:my-topic:sub1",
+                    Protocol: "email",
+                    Endpoint: "keep-me@company.com",
+                    TopicArn: "arn:aws:sns:us-east-1:123456789012:my-topic",
+                },
+                {
+                    SubscriptionArn: "arn:aws:sns:us-east-1:123456789012:my-topic:sub2",
+                    Protocol: "email",
+                    Endpoint: "delete-me@company.com",
+                    TopicArn: "arn:aws:sns:us-east-1:123456789012:my-topic",
+                },
+            ],
+        };
+        const builder = new SNSTopicBuilder("my-topic")
+            .displayName("Cool Alert")
+            .subscribe("email", "keep-me@company.com")
+            .subscribe("sms", "+19999999999");
+        await builder.deploy();
+        // Verify unsubscribe was called for stale one
+        const unsubscribeCall = snsCalls.find((c) => c.commandName === "UnsubscribeCommand");
+        assert.ok(unsubscribeCall);
+        assert.strictEqual(unsubscribeCall.input.SubscriptionArn, "arn:aws:sns:us-east-1:123456789012:my-topic:sub2");
+        // Verify subscribe was called for the new sms one, but NOT for keep-me@company.com
+        const subscribeCalls = snsCalls.filter((c) => c.commandName === "SubscribeCommand");
+        assert.strictEqual(subscribeCalls.length, 1);
+        assert.deepStrictEqual(subscribeCalls[0].input, {
+            TopicArn: "arn:aws:sns:us-east-1:123456789012:my-topic",
+            Protocol: "sms",
+            Endpoint: "+19999999999",
+        });
+    });
+    test("destroys an existing topic successfully", async () => {
+        mockSnsResponses["ListTopicsCommand"] = {
+            Topics: [{ TopicArn: "arn:aws:sns:us-east-1:123456789012:my-topic" }],
+        };
+        const builder = new SNSTopicBuilder("my-topic");
+        await builder.discoveryPromise;
+        const destroyResult = await builder.destroy();
+        assert.deepStrictEqual(destroyResult, { destroyed: "my-topic" });
+        const deleteCall = snsCalls.find((c) => c.commandName === "DeleteTopicCommand");
+        assert.ok(deleteCall);
+        assert.strictEqual(deleteCall.input.TopicArn, "arn:aws:sns:us-east-1:123456789012:my-topic");
+    });
+    test("runs in dry run mode safely", async () => {
+        Config.set({
+            dryRun: true,
+            providers: {
+                aws: { region: "us-east-1" },
+            },
+        });
+        mockSnsResponses["ListTopicsCommand"] = { Topics: [] };
+        const builder = new SNSTopicBuilder("my-topic")
+            .displayName("Cool Alert")
+            .subscribe("email", "ops@company.com");
+        const deployResult = await builder.deploy();
+        assert.ok(deployResult.arn.includes("DRYRUN"));
+        // No create topic or subscribe commands should be called in real mode
+        assert.ok(!snsCalls.some((c) => c.commandName === "CreateTopicCommand"));
+        assert.ok(!snsCalls.some((c) => c.commandName === "SubscribeCommand"));
+    });
+});

package/dist/providers/proxmox/vm.d.ts

@@ -19,6 +19,7 @@ export declare class VMBuilder extends BaseBuilder {
     private _vlan?;
     private _ip?;
     private _sshKeys?;
+    private _machine;
     constructor(name: string);
     private discoverVm;
     image(os: OSImage): this;
@@ -31,6 +32,7 @@ export declare class VMBuilder extends BaseBuilder {
     vlan(tag: number): this;
     ip(address: string): this;
     sshKey(keys: string | readonly string[]): this;
+    machine(type: "q35" | "i440fx"): this;
     deploy(): Promise<{
         name: string;
         vmid: number | null;

package/dist/providers/proxmox/vm.js

@@ -24,6 +24,7 @@ export class VMBuilder extends BaseBuilder {
     _vlan;
     _ip;
     _sshKeys;
+    _machine = "q35";
     constructor(name) {
         super(name);
         this.discoveryPromise = this.discoverVm(name);
@@ -80,6 +81,10 @@ export class VMBuilder extends BaseBuilder {
         this._sshKeys = Array.isArray(keys) ? [...keys] : keys;
         return this;
     }
+    machine(type) {
+        this._machine = type;
+        return this;
+    }
     async deploy() {
         const dryRun = this.isDryRunActive();
         const existing = await this.discoveryPromise;
@@ -102,7 +107,7 @@ export class VMBuilder extends BaseBuilder {
             console.log(`   📝 [PLAN] Create VM "${this.name}"`);
             if (this._image)
                 console.log(`      └─ Image: ${this._image}`);
-            console.log(`      └─ Cores: ${this._cores}  Memory: ${this._memory} MB`);
+            console.log(`      └─ Cores: ${this._cores}  Memory: ${this._memory} MB  Machine: ${this._machine}`);
             if (this._vlan)
                 console.log(`      └─ VLAN: ${this._vlan}`);
             if (this._provision) {
@@ -132,8 +137,35 @@ export class VMBuilder extends BaseBuilder {
                     ? `Check that VMID ${this._image} exists and is marked as a template.`
                     : `Create a template whose name contains "${this._image}".`));
         }
-        // Resolve target node: explicit → configured nodes list → template's node → API discovery
+        // Resolve target node: explicit → cluster-aware (online & max free RAM) → configured nodes list → template's node → API discovery
         let node = this._node;
+        if (!node) {
+            try {
+                const nodesList = await pm.get("/nodes");
+                const configuredNodes = Config.get().providers.proxmox?.nodes;
+                const onlineNodes = (nodesList ?? []).filter((n) => {
+                    if (n.status !== "online")
+                        return false;
+                    if (configuredNodes && configuredNodes.length > 0) {
+                        return configuredNodes.includes(n.node);
+                    }
+                    return true;
+                });
+                if (onlineNodes.length > 0) {
+                    // Sort descending by free memory (maxmem - mem)
+                    onlineNodes.sort((a, b) => {
+                        const freeA = (a.maxmem ?? 0) - (a.mem ?? 0);
+                        const freeB = (b.maxmem ?? 0) - (b.mem ?? 0);
+                        return freeB - freeA;
+                    });
+                    node = onlineNodes[0].node;
+                    console.log(`   🧠 Cluster-aware node selection: picked "${node}" with the most free RAM (${Math.round((((onlineNodes[0].maxmem ?? 0) - (onlineNodes[0].mem ?? 0)) / 1024 / 1024 / 1024) * 10) / 10} GB free)`);
+                }
+            }
+            catch (err) {
+                // Fallback silently to configured nodes list or discovery
+            }
+        }
         if (!node) {
             const configuredNodes = Config.get().providers.proxmox?.nodes;
             node = configuredNodes?.[0] ?? template?.node;
@@ -191,7 +223,7 @@ export class VMBuilder extends BaseBuilder {
         const net0 = `virtio,bridge=vmbr1${this._vlan ? `,tag=${this._vlan}` : ""}`;
         const configPatch = {
             onboot: 1,
-            machine: "q35",
+            machine: this._machine,
             cores: this._cores,
             memory: this._memory,
             net0,

package/dist/providers/proxmox/vm.test.d.ts

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