puls-dev 0.2.6 → 0.2.8

package/dist/providers/proxmox/vm.js

@@ -1,11 +1,12 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { spawn } from "node:child_process";
-import { createConnection } from "node:net";
 import { BaseBuilder } from "../../core/resource.js";
 import { Config } from "../../core/config.js";
 import { Output } from "../../core/output.js";
 import { getPMClient } from "./api.js";
+import { getFileHash, parseProvisionMetadata, mergeProvisionMetadata } from "./hash.js";
+import { checkPort, runProvisioner } from "../../core/provisioner.js";
 export class VMBuilder extends BaseBuilder {
     out = {
         ip: new Output(),
@@ -17,7 +18,7 @@ export class VMBuilder extends BaseBuilder {
     _image;
     _cores = 2;
     _memory = 2048;
-    _provision;
+    _provision = [];
     _replace;
     _node;
     _storage;
@@ -25,6 +26,7 @@ export class VMBuilder extends BaseBuilder {
     _ip;
     _sshKeys;
     _machine = "q35";
+    _forceConfigCheck = false;
     constructor(name) {
         super(name);
         this.discoveryPromise = this.discoverVm(name);
@@ -33,7 +35,17 @@ export class VMBuilder extends BaseBuilder {
         try {
             const pm = getPMClient();
             const resources = await pm.get("/cluster/resources?type=vm");
-            return ((resources ?? []).find((r) => r.name === name && !r.template) ?? null);
+            const match = (resources ?? []).find((r) => r.name === name && !r.template) ?? null;
+            if (match) {
+                try {
+                    const config = await pm.get(`/nodes/${match.node}/qemu/${match.vmid}/config`);
+                    match.description = config.description ?? "";
+                }
+                catch {
+                    match.description = "";
+                }
+            }
+            return match;
         }
         catch (e) {
             if (e.message?.includes("not configured"))
@@ -53,8 +65,8 @@ export class VMBuilder extends BaseBuilder {
         this._memory = mb;
         return this;
     }
-    provision(playbookPath) {
-        this._provision = playbookPath;
+    provision(...playbookPaths) {
+        this._provision.push(...playbookPaths.flat());
         return this;
     }
     replace(oldVmName) {
@@ -85,24 +97,83 @@ export class VMBuilder extends BaseBuilder {
         this._machine = type;
         return this;
     }
+    forceConfigCheck() {
+        this._forceConfigCheck = true;
+        return this;
+    }
     async deploy() {
         const dryRun = this.isDryRunActive();
         const existing = await this.discoveryPromise;
         const pm = getPMClient();
-        console.log(`\n🖥️  Finalizing Proxmox VM "${this.name}"...`);
         if (existing) {
             this.resolvedVmid = existing.vmid;
             this.resolvedNode = existing.node;
             this.out.vmid.resolve(existing.vmid);
-            if (this._ip)
-                this.out.ip.resolve(this._ip.split("/")[0]);
+            // Resolve the IP of the existing VM
+            this.resolvedIp = await this.resolveExistingIp(existing.node, existing.vmid, pm);
+            if (this.resolvedIp) {
+                this.out.ip.resolve(this.resolvedIp);
+            }
+            const activeIp = this.resolvedIp ?? "0.0.0.0";
+            // 1. Calculate hashes and check if playbooks need to run
+            const appliedHashes = parseProvisionMetadata(existing.description ?? "");
+            const declaredPlaybooksWithHashes = this._provision.map((p) => {
+                const baseName = p.split("/").pop() ?? p;
+                return { path: p, baseName, hash: getFileHash(p) };
+            });
+            const playbooksToRun = this._forceConfigCheck
+                ? declaredPlaybooksWithHashes
+                : declaredPlaybooksWithHashes.filter((p) => {
+                    const appliedHash = appliedHashes[p.baseName];
+                    return !appliedHash || appliedHash !== p.hash;
+                });
+            if (playbooksToRun.length > 0) {
+                console.log(`\n🖥️  Finalizing Proxmox VM "${this.name}"...`);
+                console.log(`   ✅ VM "${this.name}" already exists (vmid=${existing.vmid}, node=${existing.node}, status=${existing.status})`);
+                if (dryRun) {
+                    console.log(`   📝 [PLAN] Run ${playbooksToRun.length} playbook changes on existing VM:`);
+                    for (const p of playbooksToRun) {
+                        console.log(`      └─ Playbook: ${p.path} (hash: ${p.hash})`);
+                    }
+                }
+                else {
+                    console.log(`   🔄 Running ${playbooksToRun.length} playbook changes → ${activeIp}`);
+                    if (activeIp === "0.0.0.0") {
+                        throw new Error(`Failed to resolve IP for existing VM "${this.name}" to run playbooks`);
+                    }
+                    // Wait for SSH
+                    await this.waitFor(`SSH on ${activeIp} to be ready`, () => this.checkPort(activeIp, 22), { intervalMs: 10_000, timeoutMs: 300_000 });
+                    // Execute each playbook
+                    for (const p of playbooksToRun) {
+                        await this.runProvisioner(activeIp, p.path);
+                        appliedHashes[p.baseName] = p.hash;
+                    }
+                    // Update notes on Proxmox VM
+                    const updatedNotes = mergeProvisionMetadata(existing.description ?? "", appliedHashes);
+                    await pm.post(`/nodes/${existing.node}/qemu/${existing.vmid}/config`, {
+                        description: updatedNotes,
+                    });
+                    console.log(`   ✅ Playbooks applied successfully and metadata updated.`);
+                }
+                return {
+                    name: this.name,
+                    vmid: this.resolvedVmid,
+                    node: this.resolvedNode,
+                    ip: activeIp,
+                };
+            }
+            // No playbook changes!
+            console.log(`\n🖥️  Finalizing Proxmox VM "${this.name}"...`);
             console.log(`   ✅ VM "${this.name}" already exists (vmid=${existing.vmid}, node=${existing.node}, status=${existing.status})`);
+            console.log(`   ✅ Configuration and playbooks are up to date.`);
             return {
                 name: this.name,
                 vmid: this.resolvedVmid,
                 node: this.resolvedNode,
+                ip: activeIp,
             };
         }
+        console.log(`\n🖥️  Finalizing Proxmox VM "${this.name}"...`);
         if (dryRun) {
             console.log(`   📝 [PLAN] Create VM "${this.name}"`);
             if (this._image)
@@ -110,11 +181,8 @@ export class VMBuilder extends BaseBuilder {
             console.log(`      └─ Cores: ${this._cores}  Memory: ${this._memory} MB  Machine: ${this._machine}`);
             if (this._vlan)
                 console.log(`      └─ VLAN: ${this._vlan}`);
-            if (this._provision) {
-                const p = Array.isArray(this._provision)
-                    ? this._provision.join(", ")
-                    : this._provision;
-                console.log(`      └─ Provision: ${p}`);
+            if (this._provision.length > 0) {
+                console.log(`      └─ Provision: ${this._provision.join(", ")}`);
             }
             if (this._replace)
                 console.log(`      └─ Replace: "${this._replace}" after creation`);
@@ -272,21 +340,56 @@ export class VMBuilder extends BaseBuilder {
                 this.out.ip.resolve(this.resolvedIp);
             console.log(`   🌐 IP: ${this.resolvedIp}`);
         }
-        if (this._provision) {
+        if (this._provision.length > 0) {
             await this.waitFor(`SSH on ${this.resolvedIp} to be ready`, () => this.checkPort(this.resolvedIp, 22), { intervalMs: 10_000, timeoutMs: 300_000 });
             await this.waitFor(`cloud-init to finish on ${this.resolvedIp}`, () => this.checkCloudInit(this.resolvedIp), { intervalMs: 15_000, timeoutMs: 300_000 });
-            const scripts = Array.isArray(this._provision)
-                ? this._provision
-                : [this._provision];
-            for (const script of scripts) {
+            const appliedHashes = {};
+            for (const script of this._provision) {
                 await this.runProvisioner(this.resolvedIp, script);
+                const baseName = script.split("/").pop() ?? script;
+                appliedHashes[baseName] = getFileHash(script);
             }
+            // Write metadata to new VM description
+            const updatedNotes = mergeProvisionMetadata("", appliedHashes);
+            await pm.post(`/nodes/${this.resolvedNode}/qemu/${this.resolvedVmid}/config`, {
+                description: updatedNotes,
+            });
         }
         if (this._replace) {
             await this.destroyVmByName(this._replace, pm);
         }
         return { name: this.name, vmid: this.resolvedVmid, ip: this.resolvedIp };
     }
+    async resolveExistingIp(node, vmid, pm) {
+        if (this._ip) {
+            return this._ip.split("/")[0];
+        }
+        // Try QEMU guest agent first
+        try {
+            const ifaces = await pm.get(`/nodes/${node}/qemu/${vmid}/agent/network-get-interfaces`);
+            const eth = (ifaces ?? []).find((i) => i.name !== "lo");
+            const addr = eth?.["ip-addresses"]?.find((a) => a["ip-address-type"] === "ipv4");
+            if (addr?.["ip-address"]) {
+                return addr["ip-address"];
+            }
+        }
+        catch {
+            // Agent might not be running or installed yet
+        }
+        // Try DNS lookup next
+        const domain = Config.get().providers.proxmox?.dnsDomain;
+        if (domain) {
+            try {
+                const { resolve4 } = await import("node:dns/promises");
+                const [addr] = await resolve4(`${this.name}.${domain}`);
+                return addr;
+            }
+            catch {
+                // Ignored
+            }
+        }
+        return null;
+    }
     async destroy() {
         const dryRun = this.isDryRunActive();
         const existing = await this.discoveryPromise;
@@ -384,19 +487,11 @@ export class VMBuilder extends BaseBuilder {
             proc.on("error", () => resolve(false));
         });
     }
-    checkPort(ip, port) {
-        return new Promise((resolve) => {
-            const socket = createConnection({ host: ip, port, timeout: 3_000 });
-            socket.on("connect", () => {
-                socket.destroy();
-                resolve(true);
-            });
-            socket.on("timeout", () => {
-                socket.destroy();
-                resolve(false);
-            });
-            socket.on("error", () => resolve(false));
-        });
+    async checkPort(ip, port) {
+        return checkPort(ip, port);
+    }
+    async runProvisioner(ip, script) {
+        return runProvisioner(ip, "root", this._sshKeys, script);
     }
     sshKeyPath() {
         const keyInput = Array.isArray(this._sshKeys)
@@ -409,79 +504,4 @@ export class VMBuilder extends BaseBuilder {
             ? keyInput.replace(/\.pub$/, "")
             : `${homedir()}/.ssh/id_ed25519`).replace(/^~/, homedir());
     }
-    runProvisioner(ip, script) {
-        const ext = script.split(".").pop()?.toLowerCase();
-        if (ext === "sh") {
-            throw new Error(`Shell script provisioning (.sh) is no longer supported. ` +
-                `Please migrate "${script}" to an Ansible playbook (.yaml/.yml).`);
-        }
-        if (ext === "pp")
-            return this.runPuppet(ip, script);
-        return this.runAnsible(ip, script); // .yml / .yaml
-    }
-    runPuppet(ip, manifest) {
-        console.log(`   🔧 Applying Puppet manifest: ${manifest} → ${ip}`);
-        const keyPath = this.sshKeyPath();
-        // Copy manifest then apply it
-        return new Promise((resolve, reject) => {
-            const scp = spawn("scp", [
-                "-i",
-                keyPath,
-                "-o",
-                "StrictHostKeyChecking=no",
-                manifest,
-                `root@${ip}:/tmp/manifest.pp`,
-            ], { stdio: "inherit" });
-            scp.on("close", (code) => {
-                if (code !== 0) {
-                    reject(new Error(`scp exited with code ${code}`));
-                    return;
-                }
-                const puppet = spawn("ssh", [
-                    "-i",
-                    keyPath,
-                    "-o",
-                    "StrictHostKeyChecking=no",
-                    `root@${ip}`,
-                    "puppet apply /tmp/manifest.pp",
-                ], { stdio: "inherit" });
-                puppet.on("close", (c) => {
-                    if (c === 0) {
-                        console.log(`   ✅ Provisioning complete`);
-                        resolve();
-                    }
-                    else
-                        reject(new Error(`puppet apply exited with code ${c}`));
-                });
-                puppet.on("error", (err) => reject(new Error(`Failed to run puppet: ${err.message}`)));
-            });
-            scp.on("error", (err) => reject(new Error(`Failed to run scp: ${err.message}`)));
-        });
-    }
-    runAnsible(ip, playbook) {
-        console.log(`   🔧 Running Ansible: ${playbook} → ${ip}`);
-        const keyPath = this.sshKeyPath();
-        return new Promise((resolve, reject) => {
-            const proc = spawn("ansible-playbook", [
-                playbook,
-                "-i",
-                `${ip},`,
-                "-u",
-                "root",
-                "--private-key",
-                keyPath,
-                "--ssh-extra-args",
-                "-o StrictHostKeyChecking=no -o ConnectTimeout=30",
-            ], { stdio: "inherit" });
-            proc.on("close", (code) => {
-                if (code === 0) {
-                    console.log(`   ✅ Provisioning complete`);
-                    resolve();
-                }
-                else
-                    reject(new Error(`ansible-playbook exited with code ${code}`));
-            });
-            proc.on("error", (err) => reject(new Error(`Failed to run ansible-playbook: ${err.message}`)));
-        });
-    }
 }

package/dist/providers/proxmox/vm.test.js

@@ -1,8 +1,20 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
 import { test, describe, beforeEach, afterEach } from "node:test";
 import assert from "node:assert";
 import { ProxmoxApiClient } from "./api.js";
 import { VMBuilder } from "./vm.js";
 import { Config } from "../../core/config.js";
+import { getFileHash, parseProvisionMetadata, mergeProvisionMetadata } from "./hash.js";
+import { Stack } from "../../core/stack.js";
+import { ForceConfigCheck } from "../../core/decorators.js";
 describe("Proxmox VMBuilder Unit Tests", () => {
     let originalGet;
     let originalPost;
@@ -152,4 +164,216 @@ describe("Proxmox VMBuilder Unit Tests", () => {
         // Let's verify we logged or called the delete path or returned safely.
         assert.ok(destroyResult.destroyed);
     });
+    test("deploys new VM and writes playbook hashes to VM notes", async () => {
+        mockGetResponses["/cluster/resources?type=vm"] = [];
+        mockGetResponses["/cluster/nextid"] = 105;
+        mockGetResponses["/nodes"] = [
+            { node: "pve1", status: "online", maxmem: 32 * 1024 * 1024 * 1024, mem: 12 * 1024 * 1024 * 1024 }
+        ];
+        const builder = new VMBuilder("prov-new-vm")
+            .cores(2)
+            .memory(2048)
+            .ip("10.8.10.90")
+            .provision("playbooks/nginx.yaml", "playbooks/db.yaml");
+        const provisionCalls = [];
+        // Overrides
+        builder.waitFor = async (label, condition) => {
+            return await condition();
+        };
+        builder.checkPort = async () => true;
+        builder.checkCloudInit = async () => true;
+        builder.runProvisioner = async (ip, script) => {
+            provisionCalls.push({ ip, script });
+        };
+        const deployResult = await builder.deploy();
+        assert.strictEqual(deployResult.vmid, 105);
+        // Verify playbooks were executed
+        assert.strictEqual(provisionCalls.length, 2);
+        assert.strictEqual(provisionCalls[0].script, "playbooks/nginx.yaml");
+        assert.strictEqual(provisionCalls[1].script, "playbooks/db.yaml");
+        // Verify VM configuration was updated with playbooks hash
+        const configCall = clientCalls.find((c) => c.method === "POST" && c.path === "/nodes/pve1/qemu/105/config" && c.body?.description);
+        assert.ok(configCall);
+        const expectedDescription = mergeProvisionMetadata("", {
+            "nginx.yaml": getFileHash("playbooks/nginx.yaml"),
+            "db.yaml": getFileHash("playbooks/db.yaml"),
+        });
+        assert.strictEqual(configCall.body.description, expectedDescription);
+    });
+    test("skips playbook execution on existing VM if hashes match (Idempotence)", async () => {
+        const nginxHash = getFileHash("playbooks/nginx.yaml");
+        const dbHash = getFileHash("playbooks/db.yaml");
+        const descriptionNotes = mergeProvisionMetadata("User customized notes here", {
+            "nginx.yaml": nginxHash,
+            "db.yaml": dbHash,
+        });
+        mockGetResponses["/cluster/resources?type=vm"] = [
+            { name: "my-existing-vm", vmid: 200, node: "pve1", template: 0, status: "running" },
+        ];
+        mockGetResponses["/nodes/pve1/qemu/200/config"] = {
+            description: descriptionNotes,
+        };
+        const builder = new VMBuilder("my-existing-vm")
+            .ip("10.8.10.95")
+            .provision("playbooks/nginx.yaml", "playbooks/db.yaml");
+        const provisionCalls = [];
+        // Overrides
+        builder.waitFor = async (label, condition) => {
+            return await condition();
+        };
+        builder.checkPort = async () => true;
+        builder.checkCloudInit = async () => true;
+        builder.runProvisioner = async (ip, script) => {
+            provisionCalls.push({ ip, script });
+        };
+        const deployResult = await builder.deploy();
+        assert.strictEqual(deployResult.vmid, 200);
+        // Verify NO playbooks were executed
+        assert.strictEqual(provisionCalls.length, 0);
+        // Verify VM configuration was NOT posted to update notes
+        const updateConfigCall = clientCalls.find((c) => c.method === "POST" && c.path === "/nodes/pve1/qemu/200/config");
+        assert.ok(!updateConfigCall);
+    });
+    test("executes only new/changed playbooks on existing VM and merges notes metadata (Incremental)", async () => {
+        const nginxHash = getFileHash("playbooks/nginx.yaml");
+        const dbHash = getFileHash("playbooks/db.yaml");
+        const descriptionNotes = mergeProvisionMetadata("User notes preserved", {
+            "nginx.yaml": nginxHash,
+        });
+        mockGetResponses["/cluster/resources?type=vm"] = [
+            { name: "my-existing-vm", vmid: 200, node: "pve1", template: 0, status: "running" },
+        ];
+        mockGetResponses["/nodes/pve1/qemu/200/config"] = {
+            description: descriptionNotes,
+        };
+        const builder = new VMBuilder("my-existing-vm")
+            .ip("10.8.10.95")
+            .provision("playbooks/nginx.yaml", "playbooks/db.yaml");
+        const provisionCalls = [];
+        // Overrides
+        builder.waitFor = async (label, condition) => {
+            return await condition();
+        };
+        builder.checkPort = async () => true;
+        builder.checkCloudInit = async () => true;
+        builder.runProvisioner = async (ip, script) => {
+            provisionCalls.push({ ip, script });
+        };
+        const deployResult = await builder.deploy();
+        assert.strictEqual(deployResult.vmid, 200);
+        // Verify ONLY db.yaml was executed (nginx.yaml was skipped!)
+        assert.strictEqual(provisionCalls.length, 1);
+        assert.strictEqual(provisionCalls[0].script, "playbooks/db.yaml");
+        // Verify VM configuration was updated with BOTH hashes and preserved user notes
+        const updateConfigCall = clientCalls.find((c) => c.method === "POST" && c.path === "/nodes/pve1/qemu/200/config");
+        assert.ok(updateConfigCall);
+        const expectedDescription = mergeProvisionMetadata("User notes preserved", {
+            "nginx.yaml": nginxHash,
+            "db.yaml": dbHash,
+        });
+        assert.strictEqual(updateConfigCall.body.description, expectedDescription);
+        assert.ok(expectedDescription.startsWith("User notes preserved"));
+    });
+    test("forceConfigCheck() builder method forces playbook execution even if hashes match", async () => {
+        const nginxHash = getFileHash("playbooks/nginx.yaml");
+        const descriptionNotes = mergeProvisionMetadata("User notes", {
+            "nginx.yaml": nginxHash,
+        });
+        mockGetResponses["/cluster/resources?type=vm"] = [
+            { name: "force-vm", vmid: 200, node: "pve1", template: 0, status: "running" },
+        ];
+        mockGetResponses["/nodes/pve1/qemu/200/config"] = {
+            description: descriptionNotes,
+        };
+        const builder = new VMBuilder("force-vm")
+            .ip("10.8.10.95")
+            .provision("playbooks/nginx.yaml")
+            .forceConfigCheck();
+        const provisionCalls = [];
+        // Overrides
+        builder.waitFor = async (label, condition) => {
+            return await condition();
+        };
+        builder.checkPort = async () => true;
+        builder.checkCloudInit = async () => true;
+        builder.runProvisioner = async (ip, script) => {
+            provisionCalls.push({ ip, script });
+        };
+        const deployResult = await builder.deploy();
+        assert.strictEqual(deployResult.vmid, 200);
+        // Verify playbook WAS executed because of forceConfigCheck()
+        assert.strictEqual(provisionCalls.length, 1);
+        assert.strictEqual(provisionCalls[0].script, "playbooks/nginx.yaml");
+    });
+    test("ForceConfigCheck decorator forces playbook execution even if hashes match", async () => {
+        const nginxHash = getFileHash("playbooks/nginx.yaml");
+        const descriptionNotes = mergeProvisionMetadata("User notes", {
+            "nginx.yaml": nginxHash,
+        });
+        mockGetResponses["/cluster/resources?type=vm"] = [
+            { name: "force-dec-vm", vmid: 200, node: "pve1", template: 0, status: "running" },
+        ];
+        mockGetResponses["/nodes/pve1/qemu/200/config"] = {
+            description: descriptionNotes,
+        };
+        const provisionCalls = [];
+        class TestStack extends Stack {
+            server = new VMBuilder("force-dec-vm")
+                .ip("10.8.10.95")
+                .provision("playbooks/nginx.yaml");
+        }
+        __decorate([
+            ForceConfigCheck,
+            __metadata("design:type", Object)
+        ], TestStack.prototype, "server", void 0);
+        const stack = new TestStack();
+        stack.server.waitFor = async (label, condition) => {
+            return await condition();
+        };
+        stack.server.checkPort = async () => true;
+        stack.server.checkCloudInit = async () => true;
+        stack.server.runProvisioner = async (ip, script) => {
+            provisionCalls.push({ ip, script });
+        };
+        await stack.deploy();
+        // Verify playbook WAS executed because of @ForceConfigCheck decorator
+        assert.strictEqual(provisionCalls.length, 1);
+        assert.strictEqual(provisionCalls[0].script, "playbooks/nginx.yaml");
+    });
+});
+describe("Proxmox Provision Hash & Metadata Utilities", () => {
+    test("parseProvisionMetadata parses valid, invalid, and empty strings", () => {
+        assert.deepStrictEqual(parseProvisionMetadata(""), {});
+        assert.deepStrictEqual(parseProvisionMetadata("Plain text note without tag"), {});
+        assert.deepStrictEqual(parseProvisionMetadata("User description\n\n[puls-provision: a=123,b=456]"), {
+            a: "123",
+            b: "456",
+        });
+        assert.deepStrictEqual(parseProvisionMetadata("[puls-provision:  nginx.yaml = abc123def456 , db.yaml=789 ]"), {
+            "nginx.yaml": "abc123def456",
+            "db.yaml": "789",
+        });
+    });
+    test("mergeProvisionMetadata merges tags into notes without corrupting user descriptions", () => {
+        const meta = { "nginx.yaml": "abc", "db.yaml": "def" };
+        const expectedBlock = "[puls-provision: nginx.yaml=abc,db.yaml=def]";
+        // Case 1: Empty note
+        assert.strictEqual(mergeProvisionMetadata("", meta), expectedBlock);
+        // Case 2: Existing note without tags
+        assert.strictEqual(mergeProvisionMetadata("My server description", meta), `My server description\n\n${expectedBlock}`);
+        // Case 3: Existing note with existing tags (should replace them)
+        const existing = `Some description\n\n[puls-provision: nginx.yaml=old]\nMore details`;
+        const merged = mergeProvisionMetadata(existing, meta);
+        assert.ok(merged.includes(expectedBlock));
+        assert.ok(merged.includes("Some description"));
+        assert.ok(!merged.includes("nginx.yaml=old"));
+    });
+    test("getFileHash returns stable fallback hash for virtual playbooks", () => {
+        const hash1 = getFileHash("virtual-playbook-path-1.yaml");
+        const hash2 = getFileHash("virtual-playbook-path-1.yaml");
+        const hash3 = getFileHash("virtual-playbook-path-2.yaml");
+        assert.strictEqual(hash1.length, 12);
+        assert.strictEqual(hash1, hash2);
+        assert.notStrictEqual(hash1, hash3);
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "puls-dev",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Intent-driven infrastructure-as-code with eager discovery and no state files.",
   "type": "module",
   "main": "./dist/index.js",
@@ -70,6 +70,7 @@
     "@aws-sdk/client-secrets-manager": "^3.1053.0",
     "@aws-sdk/client-sns": "^3.1053.0",
     "@aws-sdk/client-sqs": "^3.1053.0",
+    "@aws-sdk/client-ssm": "^3.1053.0",
     "@types/node": "^25.6.2",
     "google-auth-library": "^10.6.2",
     "ts-node": "^10.9.2",
@@ -94,6 +95,7 @@
     "@aws-sdk/client-secrets-manager": "^3.1053.0",
     "@aws-sdk/client-sns": "^3.1053.0",
     "@aws-sdk/client-sqs": "^3.1053.0",
+    "@aws-sdk/client-ssm": "^3.1053.0",
     "dotenv": "^17.4.2",
     "google-auth-library": "^10.6.2",
     "reflect-metadata": "^0.2.2",