puls-dev 0.2.8 → 0.3.0

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

@@ -0,0 +1,227 @@
+import { test, describe, beforeEach, afterEach, mock } from "node:test";
+import assert from "node:assert";
+import fs from "node:fs";
+import { GoogleAuth } from "google-auth-library";
+import { GCPTemplateBuilder } from "./template.js";
+import { GCPVMBuilder } from "./vm.js";
+import { Config } from "../../core/config.js";
+import { getFileHash } from "../proxmox/hash.js";
+import { Stack } from "../../core/stack.js";
+describe("GCPTemplateBuilder Unit Tests", () => {
+    let originalFetch;
+    let fetchCalls = [];
+    let mockResponses = {};
+    beforeEach(() => {
+        Config.set({
+            dryRun: false,
+            providers: {
+                gcp: {
+                    projectId: "my-gcp-project",
+                    serviceAccountPath: "/fake/sa.json",
+                    region: "us-central1",
+                },
+            },
+        });
+        originalFetch = globalThis.fetch;
+        fetchCalls = [];
+        mockResponses = {};
+        globalThis.fetch = async (input, init) => {
+            const url = String(input);
+            const method = init?.method ?? "GET";
+            let body;
+            if (init?.body) {
+                if (typeof init.body === "string") {
+                    try {
+                        body = JSON.parse(init.body);
+                    }
+                    catch {
+                        body = init.body;
+                    }
+                }
+                else {
+                    body = "[Binary/Buffer Body]";
+                }
+            }
+            const headers = init?.headers;
+            fetchCalls.push({ url, method, body, headers });
+            const matchKey = Object.keys(mockResponses)
+                .filter((key) => {
+                const [mMethod, mPath] = key.split(" ");
+                return method === mMethod && url.includes(mPath);
+            })
+                .sort((a, b) => b.split(" ")[1].length - a.split(" ")[1].length)[0];
+            if (matchKey) {
+                const resp = mockResponses[matchKey];
+                return {
+                    ok: resp.status >= 200 && resp.status < 300,
+                    status: resp.status,
+                    json: async () => resp.body,
+                    text: async () => JSON.stringify(resp.body),
+                };
+            }
+            return {
+                ok: false,
+                status: 404,
+                json: async () => ({ error: { message: `Endpoint not mocked: ${method} ${url}` } }),
+                text: async () => `Endpoint not mocked: ${method} ${url}`,
+            };
+        };
+        mock.method(GoogleAuth.prototype, "getClient", async () => {
+            return {
+                getAccessToken: async () => ({ token: "fake-gcp-token" }),
+            };
+        });
+        mock.method(fs, "readFileSync", () => {
+            return "ssh-rsa AAAA_FAKE_GCP_PUBLIC_KEY test@gcp.com";
+        });
+    });
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+        mock.restoreAll();
+    });
+    test("gracefully handles discovery when Template does not exist", async () => {
+        mockResponses["GET /global/images/my-golden-image"] = {
+            status: 404,
+            body: { error: { message: "Not Found" } },
+        };
+        const builder = new GCPTemplateBuilder("my-golden-image");
+        const existing = await builder.discoveryPromise;
+        assert.strictEqual(existing, null);
+    });
+    test("discovers existing Template and skips deployment if hashes match (Idempotence)", async () => {
+        const nginxHash = getFileHash("playbooks/nginx.yaml");
+        mockResponses["GET /global/images/my-docker-base"] = {
+            status: 200,
+            body: {
+                name: "my-docker-base",
+                status: "READY",
+                description: `nginx-yaml=${nginxHash}`,
+            },
+        };
+        const builder = new GCPTemplateBuilder("my-docker-base")
+            .provision("playbooks/nginx.yaml");
+        const result = await builder.deploy();
+        assert.strictEqual(result.imageId, "projects/my-gcp-project/global/images/my-docker-base");
+        // No POST/DELETE calls since it already matches
+        const writes = fetchCalls.filter(c => c.method === "POST" || c.method === "DELETE");
+        assert.strictEqual(writes.length, 0);
+    });
+    test("purges and rebuilds template if playbooks differ", async () => {
+        // 1. Initial image discovery finds outdated hash
+        mockResponses["GET /global/images/my-docker-base"] = {
+            status: 200,
+            body: {
+                name: "my-docker-base",
+                status: "READY",
+                description: "nginx-yaml=outdated-hash",
+            },
+        };
+        // 2. Temp instance discovery transition: first 404, then RUNNING, then stopped (TERMINATED), then 404 after delete
+        let tempQueryCount = 0;
+        mockResponses["GET /instances/puls-bake-temp-my-docker-base"] = {
+            status: 200,
+            get body() {
+                tempQueryCount++;
+                if (tempQueryCount === 1) {
+                    return {
+                        name: "puls-bake-temp-my-docker-base",
+                        status: "RUNNING",
+                        networkInterfaces: [
+                            {
+                                accessConfigs: [{ natIP: "35.200.12.34" }],
+                            },
+                        ],
+                    };
+                }
+                return {
+                    name: "puls-bake-temp-my-docker-base",
+                    status: "TERMINATED",
+                };
+            },
+        };
+        // 3. Mock image ready after bake
+        mockResponses["GET /global/images/my-docker-base"] = {
+            status: 200,
+            body: {
+                name: "my-docker-base",
+                status: "READY",
+            },
+        };
+        // 4. Operations and deletes
+        mockResponses["DELETE /global/images/my-docker-base"] = { status: 200, body: {} };
+        mockResponses["POST /instances"] = { status: 200, body: {} };
+        mockResponses["POST /instances/puls-bake-temp-my-docker-base/stop"] = { status: 200, body: {} };
+        mockResponses["POST /global/images"] = { status: 200, body: {} };
+        mockResponses["DELETE /instances/puls-bake-temp-my-docker-base"] = { status: 200, body: {} };
+        const builder = new GCPTemplateBuilder("my-docker-base")
+            .provision("playbooks/nginx.yaml");
+        builder.waitFor = async (label, condition) => {
+            return await condition();
+        };
+        builder.checkPort = async () => true;
+        const provisionSpy = mock.method(builder, "runProvisioner", async () => { });
+        const result = await builder.deploy();
+        assert.strictEqual(result.imageId, "projects/my-gcp-project/global/images/my-docker-base");
+        // Verify delete old image called
+        assert.ok(fetchCalls.some(c => c.method === "DELETE" && c.url.includes("/global/images/my-docker-base")));
+        // Verify temp instance POST, stop POST, image bake POST, and temp instance DELETE
+        assert.ok(fetchCalls.some(c => c.method === "POST" && c.url.includes("/instances")));
+        assert.ok(fetchCalls.some(c => c.method === "POST" && c.url.includes("/stop")));
+        assert.ok(fetchCalls.some(c => c.method === "POST" && c.url.includes("/global/images")));
+        assert.ok(fetchCalls.some(c => c.method === "DELETE" && c.url.includes("/instances/puls-bake-temp-my-docker-base")));
+        // Verify provision playbook ran
+        assert.strictEqual(provisionSpy.mock.callCount(), 1);
+        assert.strictEqual(provisionSpy.mock.calls[0].arguments[0], "35.200.12.34");
+        assert.strictEqual(provisionSpy.mock.calls[0].arguments[1], "playbooks/nginx.yaml");
+    });
+    test("GCPVMBuilder clones from GCP custom image template successfully", async () => {
+        const nginxHash = getFileHash("playbooks/nginx.yaml");
+        mockResponses["GET /global/images/my-golden-gcp-image"] = {
+            status: 200,
+            body: {
+                name: "my-golden-gcp-image",
+                status: "READY",
+                description: `nginx-yaml=${nginxHash}`,
+            },
+        };
+        let vmQueryCount = 0;
+        mockResponses["GET /instances/prod-server-01"] = {
+            status: 200,
+            get body() {
+                vmQueryCount++;
+                if (vmQueryCount === 1)
+                    return null; // VM absent initially
+                return {
+                    name: "prod-server-01",
+                    status: "RUNNING",
+                    networkInterfaces: [
+                        {
+                            accessConfigs: [{ natIP: "35.240.10.88" }],
+                        },
+                    ],
+                };
+            },
+        };
+        mockResponses["POST /instances"] = { status: 200, body: {} };
+        class GCPStack extends Stack {
+            gcpTemplate = new GCPTemplateBuilder("my-golden-gcp-image")
+                .provision("playbooks/nginx.yaml");
+            server = new GCPVMBuilder("prod-server-01")
+                .fromTemplate(this.gcpTemplate)
+                .machineType("e2-standard-4");
+        }
+        const stack = new GCPStack();
+        stack.server.waitFor = async (label, condition) => {
+            return await condition();
+        };
+        stack.server.checkPort = async () => true;
+        const result = await stack.deploy();
+        assert.strictEqual(result.gcpTemplate.imageId, "projects/my-gcp-project/global/images/my-golden-gcp-image");
+        assert.strictEqual(result.server.ip, "35.240.10.88");
+        // Verify instance creation POST has the dynamically resolved custom image path
+        const createCall = fetchCalls.find(c => c.method === "POST" && c.url.includes("/instances") && c.body?.disks);
+        assert.ok(createCall);
+        assert.strictEqual(createCall.body.disks[0].initializeParams.sourceImage, "projects/my-gcp-project/global/images/my-golden-gcp-image");
+        assert.strictEqual(createCall.body.machineType, "zones/us-central1-a/machineTypes/e2-standard-4");
+    });
+});

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

@@ -1,5 +1,6 @@
 import { BaseBuilder } from "../../core/resource.js";
 import { Output } from "../../core/output.js";
+import { GCPTemplateBuilder } from "./template.js";
 export declare class GCPVMBuilder extends BaseBuilder {
     readonly out: {
         ip: Output<string>;
@@ -7,6 +8,7 @@ export declare class GCPVMBuilder extends BaseBuilder {
     };
     private _machineType;
     private _image;
+    private _templateSource?;
     private _zone;
     private _network;
     private _sshKeys;
@@ -17,6 +19,7 @@ export declare class GCPVMBuilder extends BaseBuilder {
     constructor(name: string);
     machineType(type: string): this;
     image(img: string): this;
+    fromTemplate(template: GCPTemplateBuilder): this;
     zone(z: string): this;
     network(netPath: string): this;
     sshKey(keys: string | string[]): this;

package/dist/providers/gcp/vm.js

@@ -5,6 +5,7 @@ import { Output } from "../../core/output.js";
 import { gcpFetch, getProjectId } from "./api.js";
 import { checkPort, runProvisioner } from "../../core/provisioner.js";
 import { getFileHash } from "../proxmox/hash.js";
+import { resourceContextStorage } from "../../core/context.js";
 export class GCPVMBuilder extends BaseBuilder {
     out = {
         ip: new Output(),
@@ -12,6 +13,7 @@ export class GCPVMBuilder extends BaseBuilder {
     };
     _machineType = "e2-micro";
     _image = "projects/ubuntu-os-cloud/global/images/family/ubuntu-2204-lts";
+    _templateSource;
     _zone = "us-central1-a";
     _network = "global/networks/default";
     _sshKeys = [];
@@ -31,6 +33,11 @@ export class GCPVMBuilder extends BaseBuilder {
         this._image = img;
         return this;
     }
+    fromTemplate(template) {
+        this._templateSource = template;
+        this.dependsOn(template);
+        return this;
+    }
     zone(z) {
         this._zone = z;
         this.discoveryPromise = this.discoverVM();
@@ -58,6 +65,9 @@ export class GCPVMBuilder extends BaseBuilder {
     async runProvisioner(ip, script) {
         const keysArray = Array.isArray(this._sshKeys) ? this._sshKeys : [this._sshKeys];
         const keyPath = keysArray.find(k => !k.startsWith('ssh-') && !k.startsWith('ecdsa-') && !k.startsWith('sk-'));
+        if (!keyPath) {
+            throw new Error(`[GCP VM:${this.name}] No SSH private key path found. Pass a file path via .sshKey() to run provisioning.`);
+        }
         return runProvisioner(ip, "root", keyPath, script);
     }
     async discoverVM() {
@@ -115,9 +125,23 @@ export class GCPVMBuilder extends BaseBuilder {
         if (dryRun) {
             console.log(`\n🔍 [DRY RUN] GCP VM "${this.name}"...`);
             if (!existing) {
-                console.log(`   📝 Plan: Create GCP VM Instance "${this.name}" (${this._machineType} in zone ${this._zone})`);
+                const sourceLabel = this._templateSource ? `Template: ${this._templateSource.name}` : `Image: ${this._image}`;
+                console.log(`   📝 Plan: Create GCP VM Instance`);
+                const details = [
+                    `Name:         ${this.name}`,
+                    `Machine Type: ${this._machineType}`,
+                    `Zone:         ${this._zone}`,
+                    `Source:       ${sourceLabel}`,
+                ];
+                if (this._network) {
+                    details.push(`Network:      ${this._network}`);
+                }
                 if (this._provision.length > 0) {
-                    console.log(`      └─ Provision: ${this._provision.join(", ")}`);
+                    details.push(`Provision:    ${this._provision.join(", ")}`);
+                }
+                for (let i = 0; i < details.length; i++) {
+                    const prefix = i === details.length - 1 ? "      └─ " : "      ├─ ";
+                    console.log(`${prefix}${details[i]}`);
                 }
                 this.out.id.resolve("PENDING");
                 this.out.ip.resolve("0.0.0.0");
@@ -163,6 +187,10 @@ export class GCPVMBuilder extends BaseBuilder {
                 initialHashes[p.slug] = p.hash;
             }
             const initialMetadataVal = mergeGcpMetadataForProvision(initialHashes);
+            let activeImage = this._image;
+            if (this._templateSource) {
+                activeImage = await this._templateSource.out.imageId.get();
+            }
             const body = {
                 name: this.name,
                 machineType: `zones/${zone}/machineTypes/${this._machineType}`,
@@ -171,7 +199,7 @@ export class GCPVMBuilder extends BaseBuilder {
                         boot: true,
                         autoDelete: true,
                         initializeParams: {
-                            sourceImage: this._image,
+                            sourceImage: activeImage,
                         },
                     },
                 ],
@@ -261,6 +289,21 @@ export class GCPVMBuilder extends BaseBuilder {
                 console.log(`✅ GCP VM "${this.name}" is up to date.`);
             }
         }
+        const context = resourceContextStorage.getStore();
+        if (context && context.hosts) {
+            const activeIp = this.resolvedIp ?? "0.0.0.0";
+            const keysArray = Array.isArray(this._sshKeys) ? this._sshKeys : [this._sshKeys];
+            const keyPath = keysArray.find(k => !k.startsWith('ssh-') && !k.startsWith('ecdsa-') && !k.startsWith('sk-'));
+            if (!context.hosts.some(h => h.name === this.name)) {
+                context.hosts.push({
+                    name: this.name,
+                    ip: activeIp,
+                    user: "root",
+                    sshKey: keyPath,
+                    provider: "gcp"
+                });
+            }
+        }
         return {
             name: this.name,
             id: this.resolvedInstanceId,

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

@@ -3,6 +3,7 @@ export declare class ProxmoxApiClient {
     private authToken;
     private dispatcher?;
     constructor(url: string, user: string, tokenName: string, tokenSecret: string, verifySsl?: boolean);
+    private createProxmoxOfflineMock;
     private request;
     get<T>(path: string): Promise<T>;
     post<T>(path: string, body?: unknown): Promise<T>;

package/dist/providers/proxmox/api.js

@@ -1,5 +1,7 @@
 import { Agent } from "undici";
 import { Config } from "../../core/config.js";
+import { withRetry } from "../../core/retry.js";
+import { resourceContextStorage } from "../../core/context.js";
 export class ProxmoxApiClient {
     baseUrl;
     authToken;
@@ -12,22 +14,72 @@ export class ProxmoxApiClient {
             this.dispatcher = new Agent({ connect: { rejectUnauthorized: false } });
         }
     }
+    createProxmoxOfflineMock(method, path, body) {
+        if (path.includes("/nodes") && !path.includes("/qemu")) {
+            return [{ node: "mock-node", status: "online" }];
+        }
+        if (path.includes("/cluster/resources")) {
+            return [
+                { type: "node", node: "mock-node", status: "online" },
+                { type: "storage", node: "mock-node", storage: "rbd_pool", shared: 1 }
+            ];
+        }
+        if (path.includes("/qemu")) {
+            if (path.includes("/status/current")) {
+                return { status: "running", qmpstatus: "running" };
+            }
+            if (path.includes("/config")) {
+                return { ipconfig0: "ip=10.8.10.50/24,gw=10.8.10.1" };
+            }
+            return { vmid: 100, upid: "UPID:mock-node:00001234:00005678:60000000:qmcreate:100:mock-user@pve:" };
+        }
+        return new Proxy({}, {
+            get(target, prop) {
+                if (prop === "then")
+                    return undefined;
+                if (prop === "node")
+                    return "mock-node";
+                if (prop === "vmid")
+                    return 100;
+                if (prop === "status")
+                    return "running";
+                if (prop.endsWith("s"))
+                    return [];
+                return `mock-pm-${prop.toLowerCase()}`;
+            }
+        });
+    }
     async request(method, path, body) {
-        const headers = {
-            Authorization: `PVEAPIToken=${this.authToken}`,
-        };
-        if (body !== undefined)
-            headers['Content-Type'] = 'application/json';
-        const opts = { method, headers };
-        if (body !== undefined)
-            opts.body = JSON.stringify(body);
-        if (this.dispatcher)
-            opts.dispatcher = this.dispatcher;
-        const res = await fetch(`${this.baseUrl}${path}`, opts);
-        if (!res.ok)
-            throw new Error(`Proxmox ${method} ${path}: ${res.status} ${await res.text()}`);
-        const json = (await res.json());
-        return json.data ?? null;
+        const context = resourceContextStorage.getStore();
+        const abortSignal = context?.abortSignal;
+        if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+            return Promise.resolve(this.createProxmoxOfflineMock(method, path, body));
+        }
+        return withRetry(async () => {
+            const headers = {
+                Authorization: `PVEAPIToken=${this.authToken}`,
+            };
+            if (body !== undefined)
+                headers['Content-Type'] = 'application/json';
+            const opts = { method, headers };
+            if (body !== undefined)
+                opts.body = JSON.stringify(body);
+            if (this.dispatcher)
+                opts.dispatcher = this.dispatcher;
+            if (abortSignal)
+                opts.signal = abortSignal;
+            const res = await fetch(`${this.baseUrl}${path}`, opts);
+            if (!res.ok)
+                throw new Error(`Proxmox ${method} ${path}: ${res.status} ${await res.text()}`);
+            const json = (await res.json());
+            return json.data ?? null;
+        }, {
+            retryable: (err) => {
+                const match = err.message.match(/: (\d+)/);
+                const status = match ? parseInt(match[1], 10) : null;
+                return status === 429 || (status && status >= 500) || err.message.includes("ETIMEDOUT");
+            }
+        });
     }
     async get(path) {
         return this.request("GET", path);
@@ -44,7 +96,11 @@ export class ProxmoxApiClient {
 }
 export function getPMClient() {
     const cfg = Config.get().providers.proxmox;
-    if (!cfg?.url || !cfg?.user || !cfg?.tokenName || !cfg?.tokenSecret)
+    if (!cfg?.url || !cfg?.user || !cfg?.tokenName || !cfg?.tokenSecret) {
+        if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+            return new ProxmoxApiClient("https://10.8.4.39:8006", "mock-user@pve", "mock-token-name", "mock-token-secret", false);
+        }
         throw new Error("Proxmox not configured. Set proxmox: { url, user, tokenName, tokenSecret } in @Deploy");
+    }
     return new ProxmoxApiClient(cfg.url, cfg.user, cfg.tokenName, cfg.tokenSecret, cfg.verifySsl ?? true);
 }

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

@@ -1,4 +1,5 @@
 import { VMBuilder } from "./vm.js";
+import { TemplateBuilder } from "./template.js";
 export declare const Proxmox: {
     init: (opts: {
         url: string;
@@ -11,6 +12,7 @@ export declare const Proxmox: {
         dnsServers?: string[];
         verifySsl?: boolean;
     }) => void;
-    VM: (name: string) => VMBuilder;
+    VM: <T extends string | string[]>(name: T) => T extends string[] ? VMBuilder[] & VMBuilder : VMBuilder;
+    Template: <T extends string | string[]>(name: T) => T extends string[] ? TemplateBuilder[] & TemplateBuilder : TemplateBuilder;
 };
 export * from "../../types/proxmox.js";

package/dist/providers/proxmox/index.js

@@ -1,11 +1,24 @@
 import { Config } from "../../core/config.js";
 import { VMBuilder } from "./vm.js";
+import { TemplateBuilder } from "./template.js";
+import { createBuilderArray } from "../../core/resource.js";
 export const Proxmox = {
     init: (opts) => {
         Config.set({
             providers: { ...Config.get().providers, proxmox: opts },
         });
     },
-    VM: (name) => new VMBuilder(name),
+    VM: (name) => {
+        if (Array.isArray(name)) {
+            return createBuilderArray(name.map((n) => new VMBuilder(n)));
+        }
+        return new VMBuilder(name);
+    },
+    Template: (name) => {
+        if (Array.isArray(name)) {
+            return createBuilderArray(name.map((n) => new TemplateBuilder(n)));
+        }
+        return new TemplateBuilder(name);
+    },
 };
 export * from "../../types/proxmox.js";

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

@@ -0,0 +1,44 @@
+import { BaseBuilder } from "../../core/resource.js";
+import { Output } from "../../core/output.js";
+import type { OSImage } from "../../types/proxmox.js";
+export declare class TemplateBuilder extends BaseBuilder {
+    readonly out: {
+        vmid: Output<number>;
+    };
+    resolvedVmid: number | null;
+    resolvedNode: string | null;
+    private _baseImage?;
+    private _cores;
+    private _memory;
+    private _provision;
+    private _storage?;
+    private _sshKeys?;
+    constructor(name: string);
+    private discoverTemplate;
+    baseImage(os: OSImage): this;
+    cores(n: number): this;
+    memory(mb: number): this;
+    storage(pool: string): this;
+    sshKey(keys: string | readonly string[]): this;
+    provision(...playbookPaths: (string | string[])[]): this;
+    deploy(): Promise<{
+        name: string;
+        vmid: number | null;
+        node: string | null;
+    } | {
+        name: string;
+        vmid: string;
+        node?: undefined;
+    }>;
+    destroy(): Promise<{
+        destroyed: boolean;
+    } | {
+        destroyed: string;
+    }>;
+    private waitForTask;
+    private resolvePublicKeys;
+    private checkCloudInit;
+    protected checkPort(ip: string, port: number): Promise<boolean>;
+    protected runProvisioner(ip: string, script: string): Promise<void>;
+    private sshKeyPath;
+}