puls-dev 0.2.8 → 0.2.9

package/dist/providers/proxmox/template.js

@@ -0,0 +1,349 @@
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { spawn } from "node:child_process";
+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 TemplateBuilder extends BaseBuilder {
+    out = {
+        vmid: new Output(),
+    };
+    resolvedVmid = null;
+    resolvedNode = null;
+    _baseImage;
+    _cores = 2;
+    _memory = 2048;
+    _provision = [];
+    _storage;
+    _sshKeys;
+    constructor(name) {
+        super(name);
+        this.discoveryPromise = this.discoverTemplate(name);
+    }
+    async discoverTemplate(name) {
+        try {
+            const pm = getPMClient();
+            const resources = await pm.get("/cluster/resources?type=vm");
+            const match = (resources ?? []).find((r) => r.name === name && r.template === 1) ?? 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"))
+                return null;
+            throw e;
+        }
+    }
+    baseImage(os) {
+        this._baseImage = os;
+        return this;
+    }
+    cores(n) {
+        this._cores = n;
+        return this;
+    }
+    memory(mb) {
+        this._memory = mb;
+        return this;
+    }
+    storage(pool) {
+        this._storage = pool;
+        return this;
+    }
+    sshKey(keys) {
+        this._sshKeys = Array.isArray(keys) ? [...keys] : keys;
+        return this;
+    }
+    provision(...playbookPaths) {
+        this._provision.push(...playbookPaths.flat());
+        return this;
+    }
+    async deploy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        const pm = getPMClient();
+        if (existing) {
+            this.resolvedVmid = existing.vmid;
+            this.resolvedNode = existing.node;
+            this.out.vmid.resolve(existing.vmid);
+            // Check if playbook hashes differ
+            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 hasChanges = declaredPlaybooksWithHashes.some((p) => {
+                const appliedHash = appliedHashes[p.baseName];
+                return !appliedHash || appliedHash !== p.hash;
+            });
+            if (!hasChanges) {
+                console.log(`\n🖥️  Finalizing Proxmox Template "${this.name}"...`);
+                console.log(`   ✅ Template "${this.name}" already exists and matches defined state.`);
+                return { name: this.name, vmid: this.resolvedVmid, node: this.resolvedNode };
+            }
+            console.log(`\n🖥️  Finalizing Proxmox Template "${this.name}"...`);
+            console.log(`   🔄 Template playbook hashes changed. Purging old template...`);
+            if (dryRun) {
+                console.log(`   📝 [PLAN] Would purge template "${this.name}" (vmid=${existing.vmid}) and rebuild.`);
+                return { name: this.name, vmid: "PENDING" };
+            }
+            else {
+                await pm.delete(`/nodes/${existing.node}/qemu/${existing.vmid}?purge=1&destroy-unreferenced-disks=1`);
+            }
+        }
+        console.log(`\n🖥️  Finalizing Proxmox Template "${this.name}"...`);
+        if (dryRun) {
+            console.log(`   📝 [PLAN] Bake Proxmox Template "${this.name}"`);
+            if (this._baseImage)
+                console.log(`      └─ Base Image: ${this._baseImage}`);
+            console.log(`      └─ Cores: ${this._cores}  Memory: ${this._memory} MB`);
+            if (this._provision.length > 0) {
+                console.log(`      └─ Provision: ${this._provision.join(", ")}`);
+            }
+            this.out.vmid.resolve(-1);
+            return { name: this.name, vmid: "PENDING" };
+        }
+        // Pick target node (cluster-aware)
+        let node;
+        try {
+            const nodesList = await pm.get("/nodes");
+            const configuredNodes = Config.get().providers.proxmox?.nodes;
+            const onlineNodes = (nodesList ?? []).filter((n) => {
+                if (n.status !== "online")
+                    return false;
+                if (configuredNodes && configuredNodes.length > 0) {
+                    return configuredNodes.includes(n.node);
+                }
+                return true;
+            });
+            if (onlineNodes.length > 0) {
+                onlineNodes.sort((a, b) => {
+                    const freeA = (a.maxmem ?? 0) - (a.mem ?? 0);
+                    const freeB = (b.maxmem ?? 0) - (b.mem ?? 0);
+                    return freeB - freeA;
+                });
+                node = onlineNodes[0].node;
+                console.log(`   🧠 Cluster-aware node selection: picked "${node}" with the most free RAM (${Math.round((((onlineNodes[0].maxmem ?? 0) - (onlineNodes[0].mem ?? 0)) / 1024 / 1024 / 1024) * 10) / 10} GB free)`);
+            }
+        }
+        catch (err) {
+            // Fallback
+        }
+        if (!node) {
+            const configuredNodes = Config.get().providers.proxmox?.nodes;
+            node = configuredNodes?.[0];
+        }
+        if (!node) {
+            const nodes = await pm.get("/nodes");
+            node = (nodes ?? [])[0]?.node;
+        }
+        if (!node)
+            throw new Error("No Proxmox nodes available");
+        const newVmid = await pm.get("/cluster/nextid");
+        const storage = this._storage ?? "rbd_pool";
+        // Lookup base image template
+        const resources = await pm.get("/cluster/resources?type=vm");
+        const isVmid = this._baseImage && /^\d+$/.test(this._baseImage);
+        const baseTemplate = this._baseImage
+            ? (resources ?? []).find((r) => r.template === 1 &&
+                (isVmid
+                    ? String(r.vmid) === this._baseImage
+                    : r.name?.includes(this._baseImage)))
+            : null;
+        if (this._baseImage && !baseTemplate) {
+            throw new Error(`No Proxmox base template found matching "${this._baseImage}".`);
+        }
+        if (baseTemplate) {
+            console.log(`   📋 Cloning base template "${baseTemplate.name}" (vmid=${baseTemplate.vmid}) → "${this.name}" (vmid=${newVmid})`);
+            const taskId = await pm.post(`/nodes/${node}/qemu/${baseTemplate.vmid}/clone`, {
+                newid: newVmid,
+                name: this.name,
+                full: 1,
+                storage,
+                format: "raw",
+            });
+            await this.waitForTask(node, taskId, pm);
+        }
+        else {
+            console.log(`   🆕 Creating blank VM "${this.name}" (vmid=${newVmid})`);
+            await pm.post(`/nodes/${node}/qemu`, {
+                vmid: newVmid,
+                name: this.name,
+                cores: this._cores,
+                memory: this._memory,
+                net0: "virtio,bridge=vmbr1",
+                ostype: "l26",
+            });
+        }
+        this.resolvedVmid = newVmid;
+        this.resolvedNode = node;
+        // Apply config
+        const configPatch = {
+            onboot: 0,
+            cores: this._cores,
+            memory: this._memory,
+            net0: "virtio,bridge=vmbr1",
+            ipconfig0: "ip=dhcp",
+            nameserver: (Config.get().providers.proxmox?.dnsServers ?? ["1.1.1.1", "8.8.8.8"]).join(" "),
+            searchdomain: Config.get().providers.proxmox?.dnsDomain ?? "",
+            ciuser: "root",
+        };
+        const pubKeys = this.resolvePublicKeys();
+        if (pubKeys.length) {
+            configPatch.sshkeys = encodeURIComponent(pubKeys.join("\n"));
+        }
+        await pm.post(`/nodes/${node}/qemu/${newVmid}/config`, configPatch);
+        // Start VM for provisioning
+        await pm.post(`/nodes/${node}/qemu/${newVmid}/status/start`);
+        console.log(`🚀 Started VM "${this.name}" (vmid=${newVmid}) for template provisioning...`);
+        // Wait for IP
+        let resolvedIp = null;
+        await this.waitFor(`VM "${this.name}" to boot and get an IP`, async () => {
+            try {
+                const ifaces = await pm.get(`/nodes/${node}/qemu/${newVmid}/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"]) {
+                    resolvedIp = addr["ip-address"];
+                    return true;
+                }
+                return false;
+            }
+            catch {
+                return false;
+            }
+        }, { intervalMs: 10_000, timeoutMs: 300_000 });
+        if (!resolvedIp) {
+            throw new Error(`Failed to resolve IP for VM "${this.name}" during provisioning`);
+        }
+        // Run Playbooks
+        if (this._provision.length > 0) {
+            await this.waitFor(`SSH on ${resolvedIp} to be ready`, () => this.checkPort(resolvedIp, 22), { intervalMs: 10_000, timeoutMs: 300_000 });
+            await this.waitFor(`cloud-init to finish on ${resolvedIp}`, () => this.checkCloudInit(resolvedIp), { intervalMs: 15_000, timeoutMs: 300_000 });
+            const appliedHashes = {};
+            for (const script of this._provision) {
+                await this.runProvisioner(resolvedIp, script);
+                const baseName = script.split("/").pop() ?? script;
+                appliedHashes[baseName] = getFileHash(script);
+            }
+            // Write playbook metadata into VM notes description
+            const updatedNotes = mergeProvisionMetadata("", appliedHashes);
+            await pm.post(`/nodes/${this.resolvedNode}/qemu/${this.resolvedVmid}/config`, {
+                description: updatedNotes,
+            });
+        }
+        // Stop the VM
+        console.log(`   🛑 Stopping VM "${this.name}" (vmid=${newVmid})...`);
+        await pm.post(`/nodes/${node}/qemu/${newVmid}/status/stop`);
+        await this.waitFor(`VM "${this.name}" to stop`, async () => {
+            const s = await pm.get(`/nodes/${node}/qemu/${newVmid}/status/current`);
+            return s?.status === "stopped";
+        }, { intervalMs: 5_000, timeoutMs: 120_000 });
+        // Convert to Template
+        console.log(`   💾 Converting VM "${this.name}" (vmid=${newVmid}) to template...`);
+        await pm.post(`/nodes/${node}/qemu/${newVmid}/template`);
+        console.log(`   ✅ Template "${this.name}" (vmid=${newVmid}) baked successfully.`);
+        this.out.vmid.resolve(newVmid);
+        return { name: this.name, vmid: newVmid, node };
+    }
+    async destroy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        console.log(`\n🗑️  Destroying Proxmox Template "${this.name}"...`);
+        if (!existing) {
+            console.log(`   ─  Template "${this.name}" not found`);
+            return { destroyed: false };
+        }
+        if (dryRun) {
+            console.log(`   📝 [PLAN] Delete Template "${this.name}" (vmid=${existing.vmid})`);
+            return { destroyed: this.name };
+        }
+        const pm = getPMClient();
+        await pm.delete(`/nodes/${existing.node}/qemu/${existing.vmid}?purge=1&destroy-unreferenced-disks=1`);
+        console.log(`   🗑️  Removed Template "${this.name}" (vmid=${existing.vmid})`);
+        return { destroyed: this.name };
+    }
+    async waitForTask(node, upid, pm) {
+        const encoded = encodeURIComponent(upid);
+        await this.waitFor(`clone task to complete`, async () => {
+            const status = await pm.get(`/nodes/${node}/tasks/${encoded}/status`);
+            if (status?.status !== "stopped")
+                return false;
+            if (status.exitstatus && status.exitstatus !== "OK") {
+                throw new Error(`Clone task failed: ${status.exitstatus}`);
+            }
+            return true;
+        }, { intervalMs: 5_000, timeoutMs: 300_000 });
+    }
+    resolvePublicKeys() {
+        const input = this._sshKeys;
+        if (!input) {
+            try {
+                return [readFileSync(`${homedir()}/.ssh/id_ed25519.pub`, "utf-8").trim()];
+            }
+            catch {
+                return [];
+            }
+        }
+        if (Array.isArray(input))
+            return input.map((k) => k.trim()).filter(Boolean);
+        if (input.startsWith("ssh-") ||
+            input.startsWith("ecdsa-") ||
+            input.startsWith("sk-")) {
+            return [input.trim()];
+        }
+        try {
+            return [readFileSync(input.replace(/^~/, homedir()), "utf-8").trim()];
+        }
+        catch {
+            return [];
+        }
+    }
+    checkCloudInit(ip) {
+        const keyPath = this.sshKeyPath();
+        return new Promise((resolve) => {
+            const proc = spawn("ssh", [
+                "-i",
+                keyPath,
+                "-o",
+                "StrictHostKeyChecking=no",
+                "-o",
+                "ConnectTimeout=10",
+                "-o",
+                "BatchMode=yes",
+                `root@${ip}`,
+                "cloud-init status",
+            ], { stdio: ["ignore", "pipe", "ignore"] });
+            let out = "";
+            proc.stdout.on("data", (d) => (out += d.toString()));
+            proc.on("close", () => resolve(out.includes("done") || out.includes("error")));
+            proc.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) ? null : this._sshKeys;
+        return (keyInput &&
+            !keyInput.startsWith("ssh-") &&
+            !keyInput.startsWith("ecdsa-") &&
+            !keyInput.startsWith("sk-")
+            ? keyInput.replace(/\.pub$/, "")
+            : `${homedir()}/.ssh/id_ed25519`).replace(/^~/, homedir());
+    }
+}

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

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

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

@@ -0,0 +1,179 @@
+import { test, describe, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+import { ProxmoxApiClient } from "./api.js";
+import { TemplateBuilder } from "./template.js";
+import { VMBuilder } from "./vm.js";
+import { Config } from "../../core/config.js";
+import { getFileHash, mergeProvisionMetadata } from "./hash.js";
+import { Stack } from "../../core/stack.js";
+describe("Proxmox TemplateBuilder Unit Tests", () => {
+    let originalGet;
+    let originalPost;
+    let originalDelete;
+    let clientCalls = [];
+    let mockGetResponses = {};
+    let mockPostResponses = {};
+    beforeEach(() => {
+        Config.set({
+            dryRun: false,
+            providers: {
+                proxmox: {
+                    url: "https://pve.example.com:8006",
+                    user: "root@pam",
+                    tokenName: "puls",
+                    tokenSecret: "secret-key",
+                    verifySsl: false,
+                    dnsDomain: "nolimit.int",
+                },
+            },
+        });
+        clientCalls = [];
+        mockGetResponses = {};
+        mockPostResponses = {};
+        originalGet = ProxmoxApiClient.prototype.get;
+        originalPost = ProxmoxApiClient.prototype.post;
+        originalDelete = ProxmoxApiClient.prototype.delete;
+        ProxmoxApiClient.prototype.get = async function (path) {
+            clientCalls.push({ method: "GET", path });
+            if (mockGetResponses[path] !== undefined) {
+                const handler = mockGetResponses[path];
+                if (typeof handler === "function")
+                    return handler();
+                return handler;
+            }
+            return [];
+        };
+        ProxmoxApiClient.prototype.post = async function (path, body) {
+            clientCalls.push({ method: "POST", path, body });
+            if (mockPostResponses[path] !== undefined) {
+                const handler = mockPostResponses[path];
+                if (typeof handler === "function")
+                    return handler(body);
+                return handler;
+            }
+            if (path.includes("/clone")) {
+                return "UPID:pve1:00000000:00000000:00000000:qemuclone:101:root@pam:";
+            }
+            return {};
+        };
+        ProxmoxApiClient.prototype.delete = async function (path) {
+            clientCalls.push({ method: "DELETE", path });
+        };
+    });
+    afterEach(() => {
+        ProxmoxApiClient.prototype.get = originalGet;
+        ProxmoxApiClient.prototype.post = originalPost;
+        ProxmoxApiClient.prototype.delete = originalDelete;
+    });
+    test("gracefully handles discovery when Template does not exist", async () => {
+        mockGetResponses["/cluster/resources?type=vm"] = [];
+        const builder = new TemplateBuilder("my-template");
+        const discoveryResult = await builder.discoveryPromise;
+        assert.strictEqual(discoveryResult, null);
+    });
+    test("discovers existing Template and skips deployment if hashes match (Idempotence)", async () => {
+        const nginxHash = getFileHash("playbooks/nginx.yaml");
+        const notes = mergeProvisionMetadata("Pre-baked template notes", {
+            "nginx.yaml": nginxHash,
+        });
+        mockGetResponses["/cluster/resources?type=vm"] = [
+            { name: "my-template", vmid: 500, node: "pve1", template: 1 },
+        ];
+        mockGetResponses["/nodes/pve1/qemu/500/config"] = {
+            description: notes,
+        };
+        const builder = new TemplateBuilder("my-template")
+            .provision("playbooks/nginx.yaml");
+        const result = await builder.deploy();
+        assert.strictEqual(result.vmid, 500);
+        assert.strictEqual(result.node, "pve1");
+        // No POST/DELETE calls should be made since it already matches
+        const writes = clientCalls.filter(c => c.method === "POST" || c.method === "DELETE");
+        assert.strictEqual(writes.length, 0);
+    });
+    test("purges and rebuilds template if playbooks differ", async () => {
+        mockGetResponses["/cluster/resources?type=vm"] = [
+            { name: "my-template", vmid: 500, node: "pve1", template: 1 },
+        ];
+        // Template config notes are empty/out of date
+        mockGetResponses["/nodes/pve1/qemu/500/config"] = {
+            description: "",
+        };
+        mockGetResponses["/nodes"] = [
+            { node: "pve1", status: "online", maxmem: 32 * 1024 * 1024 * 1024, mem: 12 * 1024 * 1024 * 1024 }
+        ];
+        mockGetResponses["/cluster/nextid"] = 600;
+        mockGetResponses["/nodes/pve1/qemu/600/agent/network-get-interfaces"] = [
+            {
+                name: "eth0",
+                "ip-addresses": [
+                    { "ip-address-type": "ipv4", "ip-address": "10.8.10.199" }
+                ]
+            }
+        ];
+        const builder = new TemplateBuilder("my-template")
+            .provision("playbooks/nginx.yaml");
+        const provisionCalls = [];
+        builder.waitFor = async (label, condition) => {
+            return await condition();
+        };
+        builder.checkPort = async () => true;
+        builder.checkCloudInit = async () => true;
+        builder.runProvisioner = async (ip, script) => {
+            provisionCalls.push(script);
+        };
+        const result = await builder.deploy();
+        assert.strictEqual(result.vmid, 600);
+        // Verify it purged the old template
+        const deleteCall = clientCalls.find(c => c.method === "DELETE" && c.path === "/nodes/pve1/qemu/500?purge=1&destroy-unreferenced-disks=1");
+        assert.ok(deleteCall);
+        // Verify it created a blank VM and provisioned it
+        const createCall = clientCalls.find(c => c.method === "POST" && c.path === "/nodes/pve1/qemu");
+        assert.ok(createCall);
+        // Verify playbooks ran
+        assert.strictEqual(provisionCalls.length, 1);
+        assert.strictEqual(provisionCalls[0], "playbooks/nginx.yaml");
+        // Verify it stopped the VM and converted it to a template
+        const stopCall = clientCalls.find(c => c.method === "POST" && c.path === "/nodes/pve1/qemu/600/status/stop");
+        assert.ok(stopCall);
+        const templateCall = clientCalls.find(c => c.method === "POST" && c.path === "/nodes/pve1/qemu/600/template");
+        assert.ok(templateCall);
+    });
+    test("VM clones from Template successfully", async () => {
+        const nginxHash = getFileHash("playbooks/nginx.yaml");
+        const notes = mergeProvisionMetadata("Pre-baked template notes", {
+            "nginx.yaml": nginxHash,
+        });
+        mockGetResponses["/cluster/resources?type=vm"] = [
+            // Template exists
+            { name: "my-game-template", vmid: 500, node: "pve1", template: 1 },
+        ];
+        mockGetResponses["/nodes/pve1/qemu/500/config"] = {
+            description: notes,
+        };
+        mockGetResponses["/cluster/nextid"] = 205;
+        mockGetResponses["/nodes"] = [
+            { node: "pve1", status: "online", maxmem: 32 * 1024 * 1024 * 1024, mem: 12 * 1024 * 1024 * 1024 }
+        ];
+        class ProxmoxStack extends Stack {
+            template = new TemplateBuilder("my-game-template")
+                .provision("playbooks/nginx.yaml");
+            server = new VMBuilder("my-prod-game-01")
+                .fromTemplate(this.template)
+                .cores(4);
+        }
+        const stack = new ProxmoxStack();
+        stack.server.waitFor = async () => true;
+        stack.server.checkPort = async () => true;
+        stack.server.checkCloudInit = async () => true;
+        const result = await stack.deploy();
+        // Verify VM cloned successfully
+        assert.strictEqual(result.template.vmid, 500);
+        assert.strictEqual(result.server.vmid, 205);
+        // Verify clone POST used the template's VMID
+        const cloneCall = clientCalls.find(c => c.method === "POST" && c.path === "/nodes/pve1/qemu/500/clone");
+        assert.ok(cloneCall);
+        assert.strictEqual(cloneCall.body.newid, 205);
+        assert.strictEqual(cloneCall.body.name, "my-prod-game-01");
+    });
+});

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

@@ -1,6 +1,7 @@
 import { BaseBuilder } from "../../core/resource.js";
 import { Output } from "../../core/output.js";
 import type { OSImage } from "../../types/proxmox.js";
+import { TemplateBuilder } from "./template.js";
 export declare class VMBuilder extends BaseBuilder {
     readonly out: {
         ip: Output<string>;
@@ -10,6 +11,7 @@ export declare class VMBuilder extends BaseBuilder {
     resolvedNode: string | null;
     resolvedIp: string | null;
     private _image?;
+    private _templateSource?;
     private _cores;
     private _memory;
     private _provision;
@@ -24,6 +26,7 @@ export declare class VMBuilder extends BaseBuilder {
     constructor(name: string);
     private discoverVm;
     image(os: OSImage): this;
+    fromTemplate(template: TemplateBuilder): this;
     cores(n: number): this;
     memory(mb: number): this;
     provision(...playbookPaths: (string | string[])[]): this;

package/dist/providers/proxmox/vm.js

@@ -7,6 +7,7 @@ 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";
+import { resourceContextStorage } from "../../core/context.js";
 export class VMBuilder extends BaseBuilder {
     out = {
         ip: new Output(),
@@ -16,6 +17,7 @@ export class VMBuilder extends BaseBuilder {
     resolvedNode = null;
     resolvedIp = null;
     _image;
+    _templateSource;
     _cores = 2;
     _memory = 2048;
     _provision = [];
@@ -41,7 +43,8 @@ export class VMBuilder extends BaseBuilder {
                     const config = await pm.get(`/nodes/${match.node}/qemu/${match.vmid}/config`);
                     match.description = config.description ?? "";
                 }
-                catch {
+                catch (err) {
+                    console.warn(`   ⚠️  Could not fetch VM config for ${match.vmid}: ${err.message}`);
                     match.description = "";
                 }
             }
@@ -57,6 +60,11 @@ export class VMBuilder extends BaseBuilder {
         this._image = os;
         return this;
     }
+    fromTemplate(template) {
+        this._templateSource = template;
+        this.dependsOn(template);
+        return this;
+    }
     cores(n) {
         this._cores = n;
         return this;
@@ -178,6 +186,8 @@ export class VMBuilder extends BaseBuilder {
             console.log(`   📝 [PLAN] Create VM "${this.name}"`);
             if (this._image)
                 console.log(`      └─ Image: ${this._image}`);
+            if (this._templateSource)
+                console.log(`      └─ Template: ${this._templateSource.name}`);
             console.log(`      └─ Cores: ${this._cores}  Memory: ${this._memory} MB  Machine: ${this._machine}`);
             if (this._vlan)
                 console.log(`      └─ VLAN: ${this._vlan}`);
@@ -191,19 +201,27 @@ export class VMBuilder extends BaseBuilder {
             return { name: this.name, vmid: "PENDING" };
         }
         // Find the template - match by VMID (numeric string) or name substring
+        let sourceVmid;
+        if (this._templateSource) {
+            const v = await this._templateSource.out.vmid.get();
+            sourceVmid = String(v);
+        }
+        else if (this._image) {
+            sourceVmid = String(this._image);
+        }
         const resources = await pm.get("/cluster/resources?type=vm");
-        const isVmid = this._image && /^\d+$/.test(this._image);
-        const template = this._image
+        const isVmid = sourceVmid && /^\d+$/.test(sourceVmid);
+        const template = sourceVmid
             ? (resources ?? []).find((r) => r.template === 1 &&
                 (isVmid
-                    ? String(r.vmid) === this._image
-                    : r.name?.includes(this._image)))
+                    ? String(r.vmid) === sourceVmid
+                    : r.name?.includes(sourceVmid)))
             : null;
-        if (this._image && !template) {
-            throw new Error(`No Proxmox template found matching "${this._image}". ` +
+        if (sourceVmid && !template) {
+            throw new Error(`No Proxmox template found matching "${sourceVmid}". ` +
                 (isVmid
-                    ? `Check that VMID ${this._image} exists and is marked as a template.`
-                    : `Create a template whose name contains "${this._image}".`));
+                    ? `Check that VMID ${sourceVmid} exists and is marked as a template.`
+                    : `Create a template whose name contains "${sourceVmid}".`));
         }
         // Resolve target node: explicit → cluster-aware (online & max free RAM) → configured nodes list → template's node → API discovery
         let node = this._node;
@@ -358,6 +376,19 @@ export class VMBuilder extends BaseBuilder {
         if (this._replace) {
             await this.destroyVmByName(this._replace, pm);
         }
+        const context = resourceContextStorage.getStore();
+        if (context && context.hosts) {
+            const activeIp = this.resolvedIp ?? "0.0.0.0";
+            if (!context.hosts.some(h => h.name === this.name)) {
+                context.hosts.push({
+                    name: this.name,
+                    ip: activeIp,
+                    user: "root",
+                    sshKey: this.sshKeyPath(),
+                    provider: "proxmox"
+                });
+            }
+        }
         return { name: this.name, vmid: this.resolvedVmid, ip: this.resolvedIp };
     }
     async resolveExistingIp(node, vmid, pm) {