puls-dev 0.2.6 → 0.2.7

package/README.md

@@ -2,7 +2,7 @@
 
 **Intent-driven infrastructure-as-code. Describe what you want - Puls figures out create, update, or skip.**
 
-[Live Documentation](https://pulsdev.io/) | Discord: **pulsdev.io** ([Join](https://discord.gg/9PcwyjADZj))
+[Live Documentation](https://pulsdev.io/) | Matrix|Gitter: **pulsdev.io** ([Join](https://matrix.to/#/#pulsdevio:gitter.im))
 
 > [!IMPORTANT]
 > **Active Pre-1.0 Development**

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

@@ -0,0 +1,3 @@
+export declare function getFileHash(filePath: string): string;
+export declare function parseProvisionMetadata(description: string): Record<string, string>;
+export declare function mergeProvisionMetadata(description: string, metadata: Record<string, string>): string;

package/dist/providers/proxmox/hash.js

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+import crypto from "node:crypto";
+export function getFileHash(filePath) {
+    try {
+        if (!fs.existsSync(filePath)) {
+            // Stable hash fallback for virtual playbooks or missing dry-run files
+            return crypto.createHash("sha256").update(filePath).digest("hex").slice(0, 12);
+        }
+        const content = fs.readFileSync(filePath);
+        return crypto.createHash("sha256").update(content).digest("hex").slice(0, 12);
+    }
+    catch {
+        return "unknown";
+    }
+}
+export function parseProvisionMetadata(description) {
+    if (!description)
+        return {};
+    const match = description.match(/\[puls-provision:\s*([^\]]+)\]/);
+    if (!match)
+        return {};
+    const record = {};
+    const entries = match[1].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 mergeProvisionMetadata(description, metadata) {
+    const metaString = Object.entries(metadata)
+        .map(([name, hash]) => `${name}=${hash}`)
+        .join(",");
+    const block = `[puls-provision: ${metaString}]`;
+    const regex = /\[puls-provision:\s*[^\]]+\]/;
+    if (regex.test(description)) {
+        return description.replace(regex, block);
+    }
+    const trimmed = description.trim();
+    return trimmed ? `${trimmed}\n\n${block}` : block;
+}

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

@@ -12,7 +12,7 @@ export declare class VMBuilder extends BaseBuilder {
     private _image?;
     private _cores;
     private _memory;
-    private _provision?;
+    private _provision;
     private _replace?;
     private _node?;
     private _storage?;
@@ -25,7 +25,7 @@ export declare class VMBuilder extends BaseBuilder {
     image(os: OSImage): this;
     cores(n: number): this;
     memory(mb: number): this;
-    provision(playbookPath: string | string[]): this;
+    provision(...playbookPaths: (string | string[])[]): this;
     replace(oldVmName: string): this;
     node(n: string): this;
     storage(pool: string): this;
@@ -37,7 +37,7 @@ export declare class VMBuilder extends BaseBuilder {
         name: string;
         vmid: number | null;
         node: string | null;
-        ip?: undefined;
+        ip: string;
     } | {
         name: string;
         vmid: string;
@@ -49,6 +49,7 @@ export declare class VMBuilder extends BaseBuilder {
         ip: string | null;
         node?: undefined;
     }>;
+    private resolveExistingIp;
     destroy(): Promise<any>;
     private waitForTask;
     private destroyVmByName;

package/dist/providers/proxmox/vm.js

@@ -6,6 +6,7 @@ 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";
 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;
@@ -33,7 +34,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 +64,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) {
@@ -89,20 +100,73 @@ export class VMBuilder extends BaseBuilder {
         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 = 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 +174,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 +333,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;

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

@@ -3,6 +3,7 @@ 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";
 describe("Proxmox VMBuilder Unit Tests", () => {
     let originalGet;
     let originalPost;
@@ -152,4 +153,150 @@ 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"));
+    });
+});
+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.7",
   "description": "Intent-driven infrastructure-as-code with eager discovery and no state files.",
   "type": "module",
   "main": "./dist/index.js",