puls-dev 0.2.7 → 0.2.8

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

@@ -0,0 +1,279 @@
+import { test, describe, beforeEach, mock } from "node:test";
+import assert from "node:assert";
+import fs from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { EC2VMBuilder, parseAwsTagsForProvision, mergeAwsTagsForProvision } from "./ec2.js";
+import { getFileHash } from "../proxmox/hash.js";
+import { Config } from "../../core/config.js";
+import { EC2Client } from "@aws-sdk/client-ec2";
+describe("EC2VMBuilder Unit Tests", () => {
+    let originalSend;
+    beforeEach(() => {
+        Config.set({
+            dryRun: false,
+            providers: {
+                aws: { region: "us-east-1" },
+            },
+        });
+        originalSend = EC2Client.prototype.send;
+    });
+    test("gracefully handles discovery when VM does not exist", async () => {
+        EC2Client.prototype.send = (async (command) => {
+            if (command.constructor.name === "DescribeInstancesCommand") {
+                return { Reservations: [] };
+            }
+            return {};
+        });
+        try {
+            const vm = new EC2VMBuilder("missing-vm");
+            const existing = await vm.discoveryPromise;
+            assert.strictEqual(existing, null);
+            assert.strictEqual(vm.resolvedInstanceId, undefined);
+        }
+        finally {
+            EC2Client.prototype.send = originalSend;
+        }
+    });
+    test("discovers VM successfully when it exists", async () => {
+        EC2Client.prototype.send = (async (command) => {
+            if (command.constructor.name === "DescribeInstancesCommand") {
+                return {
+                    Reservations: [
+                        {
+                            Instances: [
+                                {
+                                    InstanceId: "i-1234567890abcdef0",
+                                    InstanceType: "t3.micro",
+                                    PublicIpAddress: "54.80.12.34",
+                                    State: { Name: "running" },
+                                    Tags: [{ Key: "Name", Value: "existing-vm" }],
+                                },
+                            ],
+                        },
+                    ],
+                };
+            }
+            return {};
+        });
+        try {
+            const vm = new EC2VMBuilder("existing-vm");
+            const existing = await vm.discoveryPromise;
+            assert.ok(existing);
+            assert.strictEqual(existing.InstanceId, "i-1234567890abcdef0");
+            assert.strictEqual(await vm.out.id.get(), "i-1234567890abcdef0");
+            assert.strictEqual(await vm.out.ip.get(), "54.80.12.34");
+        }
+        finally {
+            EC2Client.prototype.send = originalSend;
+        }
+    });
+    test("runs in dry-run mode safely and logs plan", async () => {
+        Config.set({ dryRun: true });
+        EC2Client.prototype.send = (async (command) => {
+            if (command.constructor.name === "DescribeInstancesCommand") {
+                return { Reservations: [] };
+            }
+            return {};
+        });
+        const originalLog = console.log;
+        let logOutput = "";
+        console.log = (...args) => {
+            logOutput += args.join(" ") + "\n";
+        };
+        try {
+            const vm = new EC2VMBuilder("dryrun-vm")
+                .instanceType("t3.medium")
+                .ami("ami-test123")
+                .provision("playbooks/nginx.yaml");
+            const result = await vm.deploy();
+            assert.strictEqual(result.name, "dryrun-vm");
+            assert.strictEqual(result.id, "PENDING");
+            assert.strictEqual(await vm.out.id.get(), "PENDING");
+            assert.strictEqual(await vm.out.ip.get(), "0.0.0.0");
+            assert.ok(logOutput.includes("🔍 [DRY RUN]"));
+            assert.ok(logOutput.includes("Plan: Create EC2 Instance \"dryrun-vm\""));
+            assert.ok(logOutput.includes("t3.medium from AMI ami-test123"));
+            assert.ok(logOutput.includes("playbooks/nginx.yaml"));
+        }
+        finally {
+            console.log = originalLog;
+            EC2Client.prototype.send = originalSend;
+        }
+    });
+    test("creates a new VM instance and runs playbooks successfully", async () => {
+        // 1. Create a dummy playbook file to check hash
+        const dummyPlaybookDir = join(tmpdir(), `puls-ec2-test-${Date.now()}`);
+        fs.mkdirSync(dummyPlaybookDir);
+        const playbookPath = join(dummyPlaybookDir, "setup.yaml");
+        fs.writeFileSync(playbookPath, "- hosts: all\n  tasks:\n    - name: Hello");
+        // Mock EC2 Client state transitions:
+        // First DescribeInstancesCommand returns empty, then returns running VM.
+        let describeCount = 0;
+        EC2Client.prototype.send = (async (command) => {
+            const name = command.constructor.name;
+            if (name === "DescribeInstancesCommand") {
+                describeCount++;
+                if (describeCount === 1) {
+                    return { Reservations: [] };
+                }
+                return {
+                    Reservations: [
+                        {
+                            Instances: [
+                                {
+                                    InstanceId: "i-999",
+                                    InstanceType: "t3.micro",
+                                    PublicIpAddress: "34.200.10.20",
+                                    State: { Name: "running" },
+                                    Tags: [
+                                        { Key: "Name", Value: "new-ec2-vm" },
+                                        { Key: "puls-provision", Value: `setup-yaml=${getFileHash(playbookPath)}` },
+                                    ],
+                                },
+                            ],
+                        },
+                    ],
+                };
+            }
+            if (name === "RunInstancesCommand") {
+                return {
+                    Instances: [
+                        {
+                            InstanceId: "i-999",
+                            State: { Name: "pending" },
+                        },
+                    ],
+                };
+            }
+            return {};
+        });
+        try {
+            const vm = new EC2VMBuilder("new-ec2-vm")
+                .ami("ami-0c55b159cbfafe1f0")
+                .instanceType("t3.micro")
+                .sshPrivateKey("~/.ssh/id_rsa")
+                .provision(playbookPath);
+            // Mock SSH Port check and playbook run
+            mock.method(vm, "checkPort", async () => true);
+            const runProvisionSpy = mock.method(vm, "runProvisioner", async () => { });
+            const result = await vm.deploy();
+            assert.strictEqual(result.id, "i-999");
+            assert.strictEqual(result.ip, "34.200.10.20");
+            assert.strictEqual(await vm.out.ip.get(), "34.200.10.20");
+            assert.strictEqual(runProvisionSpy.mock.callCount(), 1);
+            assert.strictEqual(runProvisionSpy.mock.calls[0].arguments[0], "34.200.10.20");
+            assert.strictEqual(runProvisionSpy.mock.calls[0].arguments[1], playbookPath);
+        }
+        finally {
+            // Cleanup
+            EC2Client.prototype.send = originalSend;
+            try {
+                fs.unlinkSync(playbookPath);
+                fs.rmdirSync(dummyPlaybookDir);
+            }
+            catch { }
+        }
+    });
+    test("stops, resizes, and starts the VM when instanceType changes", async () => {
+        let state = "running";
+        let type = "t3.micro";
+        EC2Client.prototype.send = (async (command) => {
+            const name = command.constructor.name;
+            if (name === "DescribeInstancesCommand") {
+                return {
+                    Reservations: [
+                        {
+                            Instances: [
+                                {
+                                    InstanceId: "i-123",
+                                    InstanceType: type,
+                                    PublicIpAddress: "34.20.10.5",
+                                    State: { Name: state },
+                                    Tags: [{ Key: "Name", Value: "resize-vm" }],
+                                },
+                            ],
+                        },
+                    ],
+                };
+            }
+            if (name === "StopInstancesCommand") {
+                state = "stopped";
+                return {};
+            }
+            if (name === "ModifyInstanceAttributeCommand") {
+                type = command.input.InstanceType.Value;
+                return {};
+            }
+            if (name === "StartInstancesCommand") {
+                state = "running";
+                return {};
+            }
+            return {};
+        });
+        try {
+            const vm = new EC2VMBuilder("resize-vm").instanceType("t3.medium");
+            const result = await vm.deploy();
+            assert.strictEqual(result.id, "i-123");
+            assert.strictEqual(type, "t3.medium");
+            assert.strictEqual(state, "running");
+        }
+        finally {
+            EC2Client.prototype.send = originalSend;
+        }
+    });
+    test("terminates the VM successfully on destroy", async () => {
+        let terminated = false;
+        EC2Client.prototype.send = (async (command) => {
+            const name = command.constructor.name;
+            if (name === "DescribeInstancesCommand") {
+                return {
+                    Reservations: [
+                        {
+                            Instances: [
+                                {
+                                    InstanceId: "i-555",
+                                    InstanceType: "t3.micro",
+                                    State: { Name: "running" },
+                                    Tags: [{ Key: "Name", Value: "delete-vm" }],
+                                },
+                            ],
+                        },
+                    ],
+                };
+            }
+            if (name === "TerminateInstancesCommand") {
+                terminated = true;
+                return {};
+            }
+            return {};
+        });
+        try {
+            const vm = new EC2VMBuilder("delete-vm");
+            const result = await vm.destroy();
+            assert.strictEqual(result.destroyed, "delete-vm");
+            assert.ok(terminated);
+        }
+        finally {
+            EC2Client.prototype.send = originalSend;
+        }
+    });
+    test("parseAwsTagsForProvision correctly handles missing and formatted provision tags", () => {
+        assert.deepStrictEqual(parseAwsTagsForProvision(undefined), {});
+        assert.deepStrictEqual(parseAwsTagsForProvision([]), {});
+        const tags = [
+            { Key: "Name", Value: "my-vm" },
+            { Key: "puls-provision", Value: "setup-yaml=h123,configure-yaml=h456" },
+        ];
+        const parsed = parseAwsTagsForProvision(tags);
+        assert.deepStrictEqual(parsed, {
+            "setup-yaml": "h123",
+            "configure-yaml": "h456",
+        });
+    });
+    test("mergeAwsTagsForProvision merges record mapping back into string", () => {
+        const hashes = { "nginx-yaml": "hash-abc", "sec-yaml": "hash-xyz" };
+        const merged = mergeAwsTagsForProvision(hashes);
+        assert.strictEqual(merged, "nginx-yaml=hash-abc,sec-yaml=hash-xyz");
+    });
+});

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

@@ -10,6 +10,7 @@ import { SecretsBuilder } from "./secrets.js";
 import { IAMRoleBuilder, IAMPolicyBuilder } from "./iam.js";
 import { SNSTopicBuilder } from "./sns.js";
 import { CloudWatchAlarmBuilder } from "./cloudwatch.js";
+import { EC2VMBuilder } from "./ec2.js";
 export declare const AWS: {
     init: (opts: {
         region: string;
@@ -27,5 +28,6 @@ export declare const AWS: {
     IAMPolicy: (name: string) => IAMPolicyBuilder;
     SNS: (name: string) => SNSTopicBuilder;
     Alarm: (name: string) => CloudWatchAlarmBuilder;
+    EC2: (name: string) => EC2VMBuilder;
 };
 export * from "../../types/aws.js";

package/dist/providers/aws/index.js

@@ -11,6 +11,7 @@ import { SecretsBuilder } from "./secrets.js";
 import { IAMRoleBuilder, IAMPolicyBuilder } from "./iam.js";
 import { SNSTopicBuilder } from "./sns.js";
 import { CloudWatchAlarmBuilder } from "./cloudwatch.js";
+import { EC2VMBuilder } from "./ec2.js";
 export const AWS = {
     init: (opts) => {
         Config.set({
@@ -33,5 +34,6 @@ export const AWS = {
     IAMPolicy: (name) => new IAMPolicyBuilder(name),
     SNS: (name) => new SNSTopicBuilder(name),
     Alarm: (name) => new CloudWatchAlarmBuilder(name),
+    EC2: (name) => new EC2VMBuilder(name),
 };
 export * from "../../types/aws.js";

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

@@ -21,6 +21,7 @@ export declare class Route53Builder extends BaseBuilder {
     cert(): ACMCertificateBuilder | undefined;
     withWildcardSSL(): this;
     register(contact?: RegistrantContact): this;
+    record(filePath: string): this;
     record(name: string, type: "A" | "AAAA" | "CNAME" | "MX" | "TXT" | "NS" | "PTR" | "SRV" | "CAA" | "NAPTR" | "SPF", value: string, ttl?: number): this;
     pointer(name: string, target: BaseBuilder): this;
     deploy(): Promise<{

package/dist/providers/aws/route53.js

@@ -4,6 +4,7 @@ import { BaseBuilder } from "../../core/resource.js";
 import { Output } from "../../core/output.js";
 import { ACMCertificateBuilder } from "./acm.js";
 import { getR53Client, getR53DomainsClient } from "./api.js";
+import { loadRecordsFromFile } from "../../core/parser.js";
 export class Route53Builder extends BaseBuilder {
     out = {
         zone: new Output(),
@@ -59,8 +60,20 @@ export class Route53Builder extends BaseBuilder {
         this._registrantContact = contact;
         return this;
     }
-    record(name, type, value, ttl = 300) {
-        this.records.push({ name, type, value, ttl });
+    record(nameOrPath, type, value, ttl = 300) {
+        if (arguments.length === 1 && typeof nameOrPath === "string" && (nameOrPath.endsWith(".yaml") || nameOrPath.endsWith(".yml") || nameOrPath.endsWith(".json"))) {
+            const loaded = loadRecordsFromFile(nameOrPath);
+            for (const r of loaded) {
+                this.records.push({
+                    name: r.name,
+                    type: r.type,
+                    value: r.value,
+                    ttl: r.ttl ?? 300,
+                });
+            }
+            return this;
+        }
+        this.records.push({ name: nameOrPath, type: type, value: value, ttl });
         return this;
     }
     pointer(name, target) {

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

@@ -1,5 +1,7 @@
 import { test, describe, beforeEach, afterEach } from 'node:test';
 import assert from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
 import { Route53Client } from '@aws-sdk/client-route-53';
 import { Route53DomainsClient } from '@aws-sdk/client-route-53-domains';
 import { Route53Builder } from './route53.js';
@@ -226,4 +228,49 @@ describe('Route53Builder Unit Tests', () => {
         assert.strictEqual(pollCall.length, 2);
         assert.strictEqual(pollCall[0].input.OperationId, 'op-registration-abc');
     });
+    test("loads records from a configuration file (JSON) successfully", async () => {
+        mockR53Responses['ListHostedZonesByNameCommand'] = {
+            HostedZones: [{ Id: '/hostedzone/Z123', Name: 'example.com.' }]
+        };
+        mockR53Responses['ChangeResourceRecordSetsCommand'] = {};
+        // Mock JSON file creation
+        const tempJsonPath = path.resolve(process.cwd(), "temp-route53-records.json");
+        const jsonContent = JSON.stringify([
+            { name: "www", type: "CNAME", value: "lb.com", ttl: 120 },
+            { name: "mail", type: "A", value: "1.1.1.1" }
+        ]);
+        fs.writeFileSync(tempJsonPath, jsonContent, "utf-8");
+        try {
+            const builder = new Route53Builder("example.com")
+                .record("temp-route53-records.json")
+                .record("api", "A", "2.2.2.2"); // Hybrid programmatic record!
+            await builder.deploy();
+            const changeCall = r53Calls.find(c => c.commandName === 'ChangeResourceRecordSetsCommand');
+            assert.ok(changeCall);
+            const changes = changeCall.input.ChangeBatch.Changes;
+            assert.strictEqual(changes.length, 3);
+            assert.deepStrictEqual(changes[0].ResourceRecordSet, {
+                Name: "www",
+                Type: "CNAME",
+                TTL: 120,
+                ResourceRecords: [{ Value: "lb.com" }]
+            });
+            assert.deepStrictEqual(changes[1].ResourceRecordSet, {
+                Name: "mail",
+                Type: "A",
+                TTL: 300, // default
+                ResourceRecords: [{ Value: "1.1.1.1" }]
+            });
+            assert.deepStrictEqual(changes[2].ResourceRecordSet, {
+                Name: "api",
+                Type: "A",
+                TTL: 300,
+                ResourceRecords: [{ Value: "2.2.2.2" }]
+            });
+        }
+        finally {
+            if (fs.existsSync(tempJsonPath))
+                fs.unlinkSync(tempJsonPath);
+        }
+    });
 });

package/dist/providers/do/api.d.ts

@@ -6,6 +6,6 @@ export declare class DoApiClient {
     get<T>(path: string): Promise<T>;
     post<T>(path: string, body: unknown): Promise<T>;
     put<T>(path: string, body: unknown): Promise<T>;
-    delete(path: string): Promise<void>;
+    delete(path: string, body?: unknown): Promise<void>;
 }
 export declare function getDoApi(): DoApiClient;

package/dist/providers/do/api.js

@@ -38,10 +38,11 @@ export class DoApiClient {
             throw new Error(`DO API PUT ${path}: ${res.status} ${await res.text()}`);
         return res.json();
     }
-    async delete(path) {
+    async delete(path, body) {
         const res = await fetch(`${DoApiClient.BASE}${path}`, {
             method: 'DELETE',
             headers: this.authHeaders,
+            ...(body !== undefined && { body: JSON.stringify(body) }),
         });
         if (!res.ok && res.status !== 404) {
             throw new Error(`DO API DELETE ${path}: ${res.status} ${await res.text()}`);

package/dist/providers/do/app.d.ts

@@ -0,0 +1,26 @@
+import { BaseBuilder } from "../../core/resource.js";
+import { Output } from "../../core/output.js";
+export declare class AppPlatformBuilder extends BaseBuilder {
+    readonly out: {
+        id: Output<string>;
+        liveUrl: Output<string>;
+    };
+    private _spec;
+    constructor(appName: string);
+    spec(jsonSpec: any): this;
+    private discoverApp;
+    deploy(): Promise<{
+        name: string;
+        id: any;
+        liveUrl: any;
+    } | {
+        name: string;
+        id: string;
+        liveUrl?: undefined;
+    }>;
+    destroy(): Promise<{
+        destroyed: boolean;
+    } | {
+        destroyed: string;
+    }>;
+}

package/dist/providers/do/app.js

@@ -0,0 +1,124 @@
+import { BaseBuilder } from "../../core/resource.js";
+import { getDoApi } from "./api.js";
+import { Output } from "../../core/output.js";
+export class AppPlatformBuilder extends BaseBuilder {
+    out = {
+        id: new Output(),
+        liveUrl: new Output(),
+    };
+    _spec = {};
+    constructor(appName) {
+        super(appName);
+        this._spec.name = appName;
+        this.discoveryPromise = this.discoverApp(appName);
+    }
+    spec(jsonSpec) {
+        this._spec = { ...this._spec, ...jsonSpec, name: this.name };
+        return this;
+    }
+    async discoverApp(name) {
+        try {
+            const api = getDoApi();
+            const res = await api.get("/apps");
+            const match = (res.apps ?? []).find((a) => a.spec?.name === name);
+            if (match) {
+                this.out.id.resolve(match.id);
+                this.out.liveUrl.resolve(match.live_url);
+            }
+            return match ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    async deploy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        const api = getDoApi();
+        console.log(`\n🚀 Finalizing DigitalOcean App Platform "${this.name}"...`);
+        if (existing) {
+            this.out.id.resolve(existing.id);
+            this.out.liveUrl.resolve(existing.live_url);
+            const hasSpecChange = JSON.stringify(existing.spec) !== JSON.stringify(this._spec);
+            if (hasSpecChange) {
+                if (dryRun) {
+                    console.log(`   📝 [PLAN] Update App Platform "${this.name}" with new specification`);
+                }
+                else {
+                    console.log(`   🔄 Updating App Platform "${this.name}" (id=${existing.id})...`);
+                    const updateRes = await api.put(`/apps/${existing.id}`, {
+                        spec: this._spec,
+                    });
+                    console.log(`   ✅ App Platform "${this.name}" updated successfully.`);
+                    this.out.id.resolve(updateRes.app.id);
+                    this.out.liveUrl.resolve(updateRes.app.live_url);
+                }
+            }
+            else {
+                console.log(`   ✅ App Platform "${this.name}" already exists and configuration is up to date.`);
+            }
+            return {
+                name: this.name,
+                id: existing.id,
+                liveUrl: existing.live_url,
+            };
+        }
+        if (dryRun) {
+            console.log(`   📝 [PLAN] Create DigitalOcean App Platform "${this.name}"`);
+            console.log(`      └─ Region: ${this._spec.region ?? "default"}`);
+            if (this._spec.services) {
+                console.log(`      └─ Services: ${this._spec.services.map((s) => s.name).join(", ")}`);
+            }
+            if (this._spec.static_sites) {
+                console.log(`      └─ Static Sites: ${this._spec.static_sites.map((s) => s.name).join(", ")}`);
+            }
+            this.out.id.resolve("PENDING");
+            this.out.liveUrl.resolve(`https://${this.name}.ondigitalocean.app`);
+            return { name: this.name, id: "PENDING" };
+        }
+        console.log(`🚀 Creating DigitalOcean App Platform "${this.name}"...`);
+        const createRes = await api.post("/apps", {
+            spec: this._spec,
+        });
+        const app = createRes.app;
+        console.log(`🚀 App Platform created with ID: ${app.id}`);
+        let finalApp = app;
+        // Wait for the app deployment to complete and be active
+        await this.waitFor(`App Platform "${this.name}" to finish deploying`, async () => {
+            const check = await api.get(`/apps/${app.id}`);
+            if (check.app) {
+                if (check.app.live_url) {
+                    finalApp = check.app;
+                    this.out.id.resolve(check.app.id);
+                    this.out.liveUrl.resolve(check.app.live_url);
+                    return true;
+                }
+            }
+            return false;
+        }, { intervalMs: 15_000, timeoutMs: 900_000 });
+        console.log(`🚀 App Platform deployment complete → ${finalApp.live_url}`);
+        return {
+            name: this.name,
+            id: finalApp.id,
+            liveUrl: finalApp.live_url,
+        };
+    }
+    async destroy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        const api = getDoApi();
+        console.log(`\n🗑️  Destroying DigitalOcean App Platform "${this.name}"...`);
+        if (!existing) {
+            console.log(`   ─  App Platform "${this.name}" not found`);
+            return { destroyed: false };
+        }
+        if (dryRun) {
+            console.log(`   📝 [PLAN] Delete App Platform "${this.name}" (id=${existing.id})`);
+            return { destroyed: this.name };
+        }
+        console.log(`   🔄 Deleting App Platform "${this.name}" (id=${existing.id})...`);
+        await api.delete(`/apps/${existing.id}`);
+        console.log(`   🗑️  Removed App Platform "${this.name}"`);
+        return { destroyed: this.name };
+    }
+}

package/dist/providers/do/app.test.d.ts

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