puls-dev 0.2.7 → 0.2.8

package/dist/core/secret.test.js

@@ -0,0 +1,166 @@
+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 { Secret } from "./secret.js";
+import { Config } from "./config.js";
+import { Output } from "./output.js";
+// Import clients to mock their prototype methods
+import { SecretsManagerClient } from "@aws-sdk/client-secrets-manager";
+import { SSMClient } from "@aws-sdk/client-ssm";
+import { GoogleAuth } from "google-auth-library";
+describe("Secrets at Deploy Time Unit Tests", () => {
+    beforeEach(() => {
+        // Reset global config before each test
+        Config.set({
+            dryRun: false,
+            providers: {},
+        });
+    });
+    test("Secret.env resolves existing environment variables", async () => {
+        process.env.TEST_MY_SECRET = "super-secret-value";
+        try {
+            const secret = Secret.env("TEST_MY_SECRET");
+            const val = await secret.get();
+            assert.strictEqual(val, "super-secret-value");
+        }
+        finally {
+            delete process.env.TEST_MY_SECRET;
+        }
+    });
+    test("Secret.env uses fallback when environment variable is missing", async () => {
+        const secret = Secret.env("TEST_MISSING_SECRET", "fallback-value");
+        const val = await secret.get();
+        assert.strictEqual(val, "fallback-value");
+    });
+    test("Secret.env throws error when missing and no fallback is set", async () => {
+        const secret = Secret.env("TEST_MISSING_SECRET_NO_FALLBACK");
+        await assert.rejects(async () => {
+            await secret.get();
+        }, /Environment secret "TEST_MISSING_SECRET_NO_FALLBACK" is not set and has no fallback./);
+    });
+    test("Secret.resolve correctly resolves strings, Outputs, and Secrets", async () => {
+        // 1. Resolve plain string
+        const r1 = await Secret.resolve("plain-string");
+        assert.strictEqual(r1, "plain-string");
+        // 2. Resolve general Output
+        const out = new Output();
+        out.resolve("resolved-output");
+        const r2 = await Secret.resolve(out);
+        assert.strictEqual(r2, "resolved-output");
+        // 3. Resolve Secret
+        process.env.TEST_RESOLVE = "secret-val";
+        try {
+            const sec = Secret.env("TEST_RESOLVE");
+            const r3 = await Secret.resolve(sec);
+            assert.strictEqual(r3, "secret-val");
+        }
+        finally {
+            delete process.env.TEST_RESOLVE;
+        }
+    });
+    test("Secret resolves immediately to placeholder [SECRET:name] in dry-run mode", async () => {
+        Config.set({ dryRun: true });
+        // No actual env vars, cloud requests, or file systems will be hit
+        const s1 = Secret.env("SOME_ENV");
+        const s2 = Secret.aws("some/aws/secret");
+        const s3 = Secret.ssm("/some/ssm/param");
+        const s4 = Secret.gcp("some-gcp-secret");
+        assert.strictEqual(await s1.get(), "[SECRET:SOME_ENV]");
+        assert.strictEqual(await s2.get(), "[SECRET:some/aws/secret]");
+        assert.strictEqual(await s3.get(), "[SECRET:/some/ssm/param]");
+        assert.strictEqual(await s4.get(), "[SECRET:some-gcp-secret]");
+    });
+    test("Secret.aws resolves value using mocked AWS Secrets Manager", async () => {
+        const originalSend = SecretsManagerClient.prototype.send;
+        mock.method(SecretsManagerClient.prototype, "send", async (command) => {
+            return { SecretString: "my-aws-vault-password" };
+        });
+        try {
+            const secret = Secret.aws("prod/db/pass", { region: "eu-west-1" });
+            const val = await secret.get();
+            assert.strictEqual(val, "my-aws-vault-password");
+        }
+        finally {
+            SecretsManagerClient.prototype.send = originalSend;
+        }
+    });
+    test("Secret.ssm resolves value using mocked AWS SSM Parameter Store", async () => {
+        const originalSend = SSMClient.prototype.send;
+        mock.method(SSMClient.prototype, "send", async (command) => {
+            return {
+                Parameter: {
+                    Value: "my-ssm-token-value",
+                },
+            };
+        });
+        try {
+            const secret = Secret.ssm("/prod/api/token");
+            const val = await secret.get();
+            assert.strictEqual(val, "my-ssm-token-value");
+        }
+        finally {
+            SSMClient.prototype.send = originalSend;
+        }
+    });
+    test("Secret.gcp resolves value using mocked GCP Secret Manager fetcher", async () => {
+        // 1. Create a dummy service account file
+        const dummySaPath = join(tmpdir(), `puls-gcp-sa-test-${Date.now()}.json`);
+        const dummySa = {
+            project_id: "test-gcp-project",
+            client_email: "test@developer.gserviceaccount.com",
+        };
+        fs.writeFileSync(dummySaPath, JSON.stringify(dummySa));
+        // Configure config to use the dummy file
+        Config.set({
+            providers: {
+                gcp: {
+                    projectId: "test-gcp-project",
+                    serviceAccountPath: dummySaPath,
+                },
+            },
+        });
+        // 2. Mock GoogleAuth class prototype
+        const originalGetClient = GoogleAuth.prototype.getClient;
+        mock.method(GoogleAuth.prototype, "getClient", async () => {
+            return {
+                getAccessToken: async () => ({ token: "mocked-gcp-access-token" }),
+            };
+        });
+        // 3. Mock globalThis.fetch to intercept Secret Manager API request
+        const originalFetch = globalThis.fetch;
+        let requestedUrl = "";
+        let authHeader = "";
+        globalThis.fetch = (async (url, init) => {
+            requestedUrl = url;
+            authHeader = init?.headers?.["Authorization"] ?? "";
+            return {
+                ok: true,
+                status: 200,
+                text: async () => JSON.stringify({
+                    name: "projects/test-gcp-project/secrets/my-secret/versions/latest",
+                    payload: {
+                        data: Buffer.from("my-gcp-payload-value").toString("base64"),
+                    },
+                }),
+            };
+        });
+        try {
+            const secret = Secret.gcp("my-secret");
+            const val = await secret.get();
+            assert.strictEqual(val, "my-gcp-payload-value");
+            assert.strictEqual(requestedUrl, "https://secretmanager.googleapis.com/v1/projects/test-gcp-project/secrets/my-secret/versions/latest:access");
+            assert.strictEqual(authHeader, "Bearer mocked-gcp-access-token");
+        }
+        finally {
+            // Cleanup
+            globalThis.fetch = originalFetch;
+            GoogleAuth.prototype.getClient = originalGetClient;
+            try {
+                fs.unlinkSync(dummySaPath);
+            }
+            catch { }
+        }
+    });
+});

package/dist/core/stack.d.ts

@@ -1,20 +1,21 @@
 import "reflect-metadata";
 export declare abstract class Stack {
     /** @internal - called by @Deploy to register the instance for cross-stack references. */
-    static _register(cls: Function, instance: Stack): void;
+    static _register(cls: Function, instance: Stack, region?: string): void;
     /**
      * Returns the already-constructed instance of another Stack so you can reference
      * its resource Output fields before deployment completes.
      *
      * The target stack must be decorated with @Deploy and imported before this call.
+     * An optional region parameter can be supplied for multi-region configurations.
      *
      * @example
      * class DNSStack extends Stack {
-     *   private infra = Stack.from(InfraStack);
+     *   private infra = Stack.from(InfraStack, REGION.US_EAST_1);
      *   dns = DO.Domain("example.com").pointer("app", this.infra.app.ip);
      * }
      */
-    static from<T extends Stack>(cls: new (...args: any[]) => T): T;
+    static from<T extends Stack>(cls: new (...args: any[]) => T, region?: string): T;
     deploy(): Promise<Record<string, any>>;
     destroy(): Promise<Record<string, any>>;
 }

package/dist/core/stack.js

@@ -60,7 +60,10 @@ function printOutputs(stackName, outputs) {
 }
 export class Stack {
     /** @internal - called by @Deploy to register the instance for cross-stack references. */
-    static _register(cls, instance) {
+    static _register(cls, instance, region) {
+        if (region) {
+            _registry.set(`${cls.name}:${region}`, instance);
+        }
         _registry.set(cls, instance);
     }
     /**
@@ -68,21 +71,28 @@ export class Stack {
      * its resource Output fields before deployment completes.
      *
      * The target stack must be decorated with @Deploy and imported before this call.
+     * An optional region parameter can be supplied for multi-region configurations.
      *
      * @example
      * class DNSStack extends Stack {
-     *   private infra = Stack.from(InfraStack);
+     *   private infra = Stack.from(InfraStack, REGION.US_EAST_1);
      *   dns = DO.Domain("example.com").pointer("app", this.infra.app.ip);
      * }
      */
-    static from(cls) {
-        const instance = _registry.get(cls);
+    static from(cls, region) {
+        const key = region ? `${cls.name}:${region}` : cls;
+        const instance = _registry.get(key);
         if (!instance)
-            throw new Error(`Stack "${cls.name}" is not registered. Make sure it is decorated with @Deploy and its module is imported before referencing it.`);
+            throw new Error(`Stack "${cls.name}" ${region ? `for region "${region}" ` : ""}is not registered. Make sure it is decorated with @Deploy and its module is imported before referencing it.`);
         return instance;
     }
     async deploy() {
         console.log(`\n🏗️  Deploying Stack: ${this.constructor.name}`);
+        // Stack-level beforeDeploy hook
+        if (typeof this.beforeDeploy === "function") {
+            console.log(`   ⚡ Running Stack-level beforeDeploy hook...`);
+            await this.beforeDeploy();
+        }
         const props = Object.getOwnPropertyNames(this);
         const outputs = {};
         for (const prop of props) {
@@ -92,16 +102,39 @@ export class Stack {
                 const isDestroyed = Reflect.getMetadata("destroy", this, prop);
                 if (isProtected)
                     resource.protect();
-                outputs[prop] = isDestroyed
-                    ? await resource.destroy()
-                    : await resource.deploy();
+                const forceConfigCheck = Reflect.getMetadata("forceConfigCheck", this, prop);
+                if (forceConfigCheck && typeof resource.forceConfigCheck === "function") {
+                    resource.forceConfigCheck();
+                }
+                let res;
+                if (isDestroyed) {
+                    await resource._runBeforeDestroy();
+                    res = await resource.destroy();
+                    await resource._runAfterDestroy(res);
+                }
+                else {
+                    await resource._runBeforeDeploy();
+                    res = await resource.deploy();
+                    await resource._runAfterDeploy(res);
+                }
+                outputs[prop] = res;
             }
         }
         printOutputs(this.constructor.name, outputs);
+        // Stack-level afterDeploy hook
+        if (typeof this.afterDeploy === "function") {
+            console.log(`   ⚡ Running Stack-level afterDeploy hook...`);
+            await this.afterDeploy(outputs);
+        }
         return outputs;
     }
     async destroy() {
         console.log(`\n💥 Tearing down Stack: ${this.constructor.name}`);
+        // Stack-level beforeDestroy hook
+        if (typeof this.beforeDestroy === "function") {
+            console.log(`   ⚡ Running Stack-level beforeDestroy hook...`);
+            await this.beforeDestroy();
+        }
         const props = Object.getOwnPropertyNames(this).reverse();
         const outputs = {};
         for (const prop of props) {
@@ -111,10 +144,18 @@ export class Stack {
                     console.log(`   🔒 Skipping protected resource "${prop}"`);
                     continue;
                 }
-                outputs[prop] = await resource.destroy();
+                await resource._runBeforeDestroy();
+                const res = await resource.destroy();
+                await resource._runAfterDestroy(res);
+                outputs[prop] = res;
             }
         }
         printOutputs(this.constructor.name, outputs);
+        // Stack-level afterDestroy hook
+        if (typeof this.afterDestroy === "function") {
+            console.log(`   ⚡ Running Stack-level afterDestroy hook...`);
+            await this.afterDestroy(outputs);
+        }
         return outputs;
     }
 }

package/dist/index.d.ts

@@ -2,4 +2,6 @@ export * from "./core/stack.js";
 export * from "./core/decorators.js";
 export * from "./core/checker.js";
 export * from "./core/resource.js";
+export { Secret } from "./core/secret.js";
 export * as INVENTORY_TYPES from "./types/inventory.js";
+export { SLACK, DISCORD } from "./core/hooks.js";

package/dist/index.js

@@ -2,4 +2,6 @@ export * from "./core/stack.js";
 export * from "./core/decorators.js";
 export * from "./core/checker.js";
 export * from "./core/resource.js";
+export { Secret } from "./core/secret.js";
 export * as INVENTORY_TYPES from "./types/inventory.js";
+export { SLACK, DISCORD } from "./core/hooks.js";

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

@@ -0,0 +1,48 @@
+import { BaseBuilder } from "../../core/resource.js";
+import { Output } from "../../core/output.js";
+export declare class EC2VMBuilder extends BaseBuilder {
+    readonly out: {
+        ip: Output<string>;
+        id: Output<string>;
+    };
+    private _instanceType;
+    private _ami;
+    private _keyName?;
+    private _subnetId?;
+    private _securityGroupIds?;
+    private _userData?;
+    private _sshPrivateKeyPath?;
+    private _provision;
+    private _forceConfigCheck;
+    private resolvedInstanceId?;
+    private resolvedIp?;
+    constructor(name: string);
+    instanceType(type: string): this;
+    ami(amiId: string): this;
+    keyName(name: string): this;
+    subnetId(id: string): this;
+    securityGroupIds(ids: string[]): this;
+    userData(data: string): this;
+    sshPrivateKey(path: string): this;
+    provision(...playbookPaths: (string | string[])[]): this;
+    forceConfigCheck(): this;
+    protected checkPort(ip: string, port: number): Promise<boolean>;
+    protected runProvisioner(ip: string, script: string): Promise<void>;
+    private discoverVM;
+    deploy(): Promise<{
+        name: string;
+        id: string;
+        ip?: undefined;
+    } | {
+        name: string;
+        id: string | undefined;
+        ip: string | undefined;
+    } | null>;
+    destroy(): Promise<{
+        destroyed: boolean;
+    } | {
+        destroyed: string;
+    }>;
+}
+export declare function parseAwsTagsForProvision(tags?: any[]): Record<string, string>;
+export declare function mergeAwsTagsForProvision(metadata: Record<string, string>): string;

package/dist/providers/aws/ec2.js

@@ -0,0 +1,297 @@
+import { DescribeInstancesCommand, RunInstancesCommand, TerminateInstancesCommand, StopInstancesCommand, StartInstancesCommand, ModifyInstanceAttributeCommand, CreateTagsCommand, } from "@aws-sdk/client-ec2";
+import { BaseBuilder } from "../../core/resource.js";
+import { Output } from "../../core/output.js";
+import { getEC2Client } from "./api.js";
+import { checkPort, runProvisioner } from "../../core/provisioner.js";
+import { getFileHash } from "../proxmox/hash.js";
+export class EC2VMBuilder extends BaseBuilder {
+    out = {
+        ip: new Output(),
+        id: new Output(),
+    };
+    _instanceType = "t3.micro";
+    _ami = "ami-0c55b159cbfafe1f0"; // Default standard Ubuntu 22.04 LTS in us-east-1
+    _keyName;
+    _subnetId;
+    _securityGroupIds;
+    _userData;
+    _sshPrivateKeyPath;
+    _provision = [];
+    _forceConfigCheck = false;
+    resolvedInstanceId;
+    resolvedIp;
+    constructor(name) {
+        super(name);
+        this.discoveryPromise = this.discoverVM();
+    }
+    instanceType(type) {
+        this._instanceType = type;
+        return this;
+    }
+    ami(amiId) {
+        this._ami = amiId;
+        return this;
+    }
+    keyName(name) {
+        this._keyName = name;
+        return this;
+    }
+    subnetId(id) {
+        this._subnetId = id;
+        return this;
+    }
+    securityGroupIds(ids) {
+        this._securityGroupIds = ids;
+        return this;
+    }
+    userData(data) {
+        this._userData = data;
+        return this;
+    }
+    sshPrivateKey(path) {
+        this._sshPrivateKeyPath = path;
+        return this;
+    }
+    provision(...playbookPaths) {
+        this._provision.push(...playbookPaths.flat());
+        return this;
+    }
+    forceConfigCheck() {
+        this._forceConfigCheck = true;
+        return this;
+    }
+    async checkPort(ip, port) {
+        return checkPort(ip, port);
+    }
+    async runProvisioner(ip, script) {
+        if (!this._sshPrivateKeyPath) {
+            throw new Error(`[EC2VMBuilder:${this.name}] sshPrivateKey(path) is required to run playbook provisioning.`);
+        }
+        // Default user is 'ubuntu' for standard Ubuntu images on AWS EC2
+        return runProvisioner(ip, "ubuntu", this._sshPrivateKeyPath, script);
+    }
+    async discoverVM() {
+        try {
+            const client = getEC2Client();
+            const result = await client.send(new DescribeInstancesCommand({
+                Filters: [
+                    { Name: "tag:Name", Values: [this.name] },
+                    {
+                        Name: "instance-state-name",
+                        Values: ["pending", "running", "stopping", "stopped"],
+                    },
+                ],
+            }));
+            const reservation = result.Reservations?.[0];
+            const instance = reservation?.Instances?.[0];
+            if (instance) {
+                this.resolvedInstanceId = instance.InstanceId;
+                this.resolvedIp = instance.PublicIpAddress ?? instance.PrivateIpAddress ?? undefined;
+                if (instance.InstanceId)
+                    this.out.id.resolve(instance.InstanceId);
+                if (this.resolvedIp)
+                    this.out.ip.resolve(this.resolvedIp);
+            }
+            return instance ?? null;
+        }
+        catch (e) {
+            if (e.name === "CredentialsProviderError" ||
+                e.message?.includes("credentials not configured")) {
+                return null;
+            }
+            throw e;
+        }
+    }
+    async deploy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        const client = getEC2Client();
+        const hasChanges = existing ? existing.InstanceType !== this._instanceType : true;
+        if (await this.checkProtection(hasChanges))
+            return null;
+        // Parse applied playbooks metadata from EC2 Tags
+        const appliedHashes = parseAwsTagsForProvision(existing?.Tags);
+        const declaredPlaybooksWithHashes = this._provision.map((p) => {
+            const baseName = p.split("/").pop() ?? p;
+            const slug = baseName.toLowerCase().replace(/[^a-z0-9_-]/g, "-");
+            return { path: p, slug, hash: getFileHash(p) };
+        });
+        const playbooksToRun = this._forceConfigCheck
+            ? declaredPlaybooksWithHashes
+            : declaredPlaybooksWithHashes.filter((p) => {
+                const appliedHash = appliedHashes[p.slug];
+                return !appliedHash || appliedHash !== p.hash;
+            });
+        const playbookRunRequired = playbooksToRun.length > 0;
+        if (dryRun) {
+            console.log(`\n🔍 [DRY RUN] AWS EC2 VM "${this.name}"...`);
+            if (!existing) {
+                console.log(`   📝 Plan: Create EC2 Instance "${this.name}" (${this._instanceType} from AMI ${this._ami})`);
+                if (this._provision.length > 0) {
+                    console.log(`      └─ Provision: ${this._provision.join(", ")}`);
+                }
+                this.out.id.resolve("PENDING");
+                this.out.ip.resolve("0.0.0.0");
+            }
+            else if (hasChanges || playbookRunRequired) {
+                if (hasChanges) {
+                    console.log(`   📝 Plan: Stop, Resize, and Start EC2 VM ${this.name} (${existing.InstanceType} → ${this._instanceType})`);
+                }
+                if (playbookRunRequired) {
+                    console.log(`   📝 [PLAN] Run ${playbooksToRun.length} playbook changes on existing EC2 VM:`);
+                    for (const p of playbooksToRun) {
+                        console.log(`      └─ Playbook: ${p.path} (hash: ${p.hash})`);
+                    }
+                }
+            }
+            else {
+                console.log(`   ✅ AWS EC2 VM "${this.name}" is up to date.`);
+            }
+            return { name: this.name, id: this.resolvedInstanceId ?? "PENDING" };
+        }
+        console.log(`\n⏳ Finalizing AWS EC2 VM "${this.name}"...`);
+        if (!existing) {
+            const initialHashes = {};
+            for (const p of declaredPlaybooksWithHashes) {
+                initialHashes[p.slug] = p.hash;
+            }
+            const initialMetadataVal = mergeAwsTagsForProvision(initialHashes);
+            console.log(`🚀 Creating AWS EC2 VM Instance "${this.name}"...`);
+            const result = await client.send(new RunInstancesCommand({
+                ImageId: this._ami,
+                InstanceType: this._instanceType,
+                MinCount: 1,
+                MaxCount: 1,
+                KeyName: this._keyName,
+                SubnetId: this._subnetId,
+                SecurityGroupIds: this._securityGroupIds,
+                UserData: this._userData ? Buffer.from(this._userData).toString("base64") : undefined,
+                TagSpecifications: [
+                    {
+                        ResourceType: "instance",
+                        Tags: [
+                            { Key: "Name", Value: this.name },
+                            ...(initialMetadataVal ? [{ Key: "puls-provision", Value: initialMetadataVal }] : []),
+                        ],
+                    },
+                ],
+            }));
+            const instanceId = result.Instances?.[0]?.InstanceId;
+            if (!instanceId)
+                throw new Error("Failed to retrieve instance ID from RunInstancesCommand");
+            this.resolvedInstanceId = instanceId;
+            this.out.id.resolve(instanceId);
+            // Poll until instance is running and has an IP address
+            await this.waitFor(`AWS EC2 VM "${this.name}" to start running`, async () => {
+                const current = await this.discoverVM();
+                return current && current.State?.Name === "running" && !!this.resolvedIp;
+            }, { intervalMs: 10_000, timeoutMs: 300_000 });
+            console.log(`🚀 AWS EC2 VM "${this.name}" is now running.`);
+            if (this._provision.length > 0) {
+                const activeIp = this.resolvedIp ?? "0.0.0.0";
+                if (activeIp === "0.0.0.0") {
+                    throw new Error(`Failed to resolve IP for new AWS EC2 VM "${this.name}" to run playbooks`);
+                }
+                await this.waitFor(`SSH on ${activeIp} to be ready`, () => this.checkPort(activeIp, 22), { intervalMs: 10_000, timeoutMs: 300_000 });
+                for (const playbook of this._provision) {
+                    await this.runProvisioner(activeIp, playbook);
+                }
+            }
+        }
+        else {
+            const instanceId = existing.InstanceId;
+            this.resolvedInstanceId = instanceId;
+            if (hasChanges) {
+                console.log(`✨ Resizing AWS EC2 VM ${this.name} (${existing.InstanceType} → ${this._instanceType})...`);
+                console.log(`   🔄 Stopping EC2 VM to perform resize...`);
+                await client.send(new StopInstancesCommand({ InstanceIds: [instanceId] }));
+                await this.waitFor(`VM "${this.name}" to stop`, async () => {
+                    const current = await this.discoverVM();
+                    return current && current.State?.Name === "stopped";
+                }, { intervalMs: 10_000, timeoutMs: 300_000 });
+                // Perform resize
+                await client.send(new ModifyInstanceAttributeCommand({
+                    InstanceId: instanceId,
+                    InstanceType: { Value: this._instanceType },
+                }));
+                // Restart VM
+                console.log(`   🔄 Restarting EC2 VM...`);
+                await client.send(new StartInstancesCommand({ InstanceIds: [instanceId] }));
+                await this.waitFor(`VM "${this.name}" to restart`, async () => {
+                    const current = await this.discoverVM();
+                    return current && current.State?.Name === "running" && !!this.resolvedIp;
+                }, { intervalMs: 10_000, timeoutMs: 300_000 });
+                console.log(`   ✅ AWS EC2 VM resized and restarted successfully.`);
+            }
+            if (playbookRunRequired) {
+                console.log(`   🔄 Running ${playbooksToRun.length} playbook changes on AWS EC2 VM...`);
+                const activeIp = this.resolvedIp ?? "0.0.0.0";
+                if (activeIp === "0.0.0.0") {
+                    throw new Error(`Failed to resolve IP for AWS EC2 VM "${this.name}" to run playbooks`);
+                }
+                await this.waitFor(`SSH on ${activeIp} to be ready`, () => this.checkPort(activeIp, 22), { intervalMs: 10_000, timeoutMs: 300_000 });
+                for (const p of playbooksToRun) {
+                    await this.runProvisioner(activeIp, p.path);
+                    appliedHashes[p.slug] = p.hash;
+                }
+                // Update EC2 Tags with new hashes
+                const newValue = mergeAwsTagsForProvision(appliedHashes);
+                await client.send(new CreateTagsCommand({
+                    Resources: [instanceId],
+                    Tags: [{ Key: "puls-provision", Value: newValue }],
+                }));
+                console.log(`   ✅ Playbooks applied successfully and EC2 Tags updated.`);
+            }
+            if (!hasChanges && !playbookRunRequired) {
+                console.log(`   ✅ AWS EC2 VM "${this.name}" is up to date.`);
+            }
+        }
+        await this.deploySidecars();
+        return {
+            name: this.name,
+            id: this.resolvedInstanceId,
+            ip: this.resolvedIp,
+        };
+    }
+    async destroy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        const client = getEC2Client();
+        console.log(`\n🗑️  Destroying AWS EC2 VM "${this.name}"...`);
+        if (!existing) {
+            console.log(`   ─  AWS EC2 VM "${this.name}" not found`);
+            return { destroyed: false };
+        }
+        if (dryRun) {
+            console.log(`   📝 [PLAN] Delete AWS EC2 VM "${this.name}" (id=${existing.InstanceId})`);
+            return { destroyed: this.name };
+        }
+        console.log(`   🔄 Terminating AWS EC2 VM "${this.name}" (id=${existing.InstanceId})...`);
+        await client.send(new TerminateInstancesCommand({ InstanceIds: [existing.InstanceId] }));
+        console.log(`   🗑️  Removed AWS EC2 VM "${this.name}"`);
+        await this.destroySidecars();
+        return { destroyed: this.name };
+    }
+}
+export function parseAwsTagsForProvision(tags) {
+    const tag = (tags ?? []).find((t) => t.Key === "puls-provision");
+    if (!tag?.Value)
+        return {};
+    const record = {};
+    const entries = tag.Value.split(",");
+    for (const entry of entries) {
+        const parts = entry.trim().split("=");
+        if (parts.length === 2) {
+            const [name, hash] = parts;
+            if (name && hash) {
+                record[name.trim()] = hash.trim();
+            }
+        }
+    }
+    return record;
+}
+export function mergeAwsTagsForProvision(metadata) {
+    return Object.entries(metadata)
+        .map(([name, hash]) => `${name}=${hash}`)
+        .join(",");
+}

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

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