puls-dev 0.2.8 → 0.3.0

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

@@ -0,0 +1,208 @@
+import { test, describe, beforeEach, afterEach, mock } from "node:test";
+import assert from "node:assert";
+import { EC2Client } from "@aws-sdk/client-ec2";
+import { EC2TemplateBuilder } from "./template.js";
+import { EC2VMBuilder } from "./ec2.js";
+import { Config } from "../../core/config.js";
+import { getFileHash } from "../proxmox/hash.js";
+import { Stack } from "../../core/stack.js";
+describe("AWS EC2TemplateBuilder Unit Tests", () => {
+    let originalSend;
+    let clientCalls = [];
+    let mockResponses = {};
+    beforeEach(() => {
+        Config.set({
+            dryRun: false,
+            providers: {
+                aws: { region: "us-east-1" },
+            },
+        });
+        clientCalls = [];
+        mockResponses = {};
+        originalSend = EC2Client.prototype.send;
+        EC2Client.prototype.send = async function (command) {
+            const name = command.constructor.name;
+            clientCalls.push({ method: name, input: command.input });
+            if (mockResponses[name] !== undefined) {
+                const handler = mockResponses[name];
+                if (typeof handler === "function")
+                    return handler(command.input);
+                return handler;
+            }
+            if (name === "DescribeImagesCommand") {
+                return { Images: [] };
+            }
+            if (name === "DescribeInstancesCommand") {
+                return { Reservations: [] };
+            }
+            if (name === "RunInstancesCommand") {
+                return { Instances: [{ InstanceId: "i-temp123" }] };
+            }
+            if (name === "CreateImageCommand") {
+                return { ImageId: "ami-custom456" };
+            }
+            return {};
+        };
+    });
+    afterEach(() => {
+        EC2Client.prototype.send = originalSend;
+    });
+    test("gracefully handles discovery when Template does not exist", async () => {
+        const template = new EC2TemplateBuilder("my-golden-image");
+        const existing = await template.discoveryPromise;
+        assert.strictEqual(existing, null);
+    });
+    test("discovers existing Template and skips deployment if hashes match (Idempotence)", async () => {
+        const nginxHash = getFileHash("playbooks/nginx.yaml");
+        mockResponses["DescribeImagesCommand"] = {
+            Images: [
+                {
+                    ImageId: "ami-golden123",
+                    State: "available",
+                    Tags: [
+                        { Key: "Name", Value: "my-docker-base" },
+                        { Key: "puls-provision", Value: `nginx-yaml=${nginxHash}` },
+                    ],
+                },
+            ],
+        };
+        const template = new EC2TemplateBuilder("my-docker-base")
+            .provision("playbooks/nginx.yaml");
+        const result = await template.deploy();
+        assert.strictEqual(result.amiId, "ami-golden123");
+        // Ensure no RunInstances or CreateImage calls were made
+        const writes = clientCalls.filter(c => c.method === "RunInstancesCommand" || c.method === "CreateImageCommand");
+        assert.strictEqual(writes.length, 0);
+    });
+    test("purges and rebuilds template if playbooks differ", async () => {
+        mockResponses["DescribeImagesCommand"] = (input) => {
+            // If querying the target name "my-docker-base"
+            if (input.Filters?.some((f) => f.Name === "name" && f.Values?.includes("my-docker-base"))) {
+                return {
+                    Images: [
+                        {
+                            ImageId: "ami-old555",
+                            State: "available",
+                            Tags: [
+                                { Key: "Name", Value: "my-docker-base" },
+                                { Key: "puls-provision", Value: "nginx-yaml=outdated" },
+                            ],
+                            BlockDeviceMappings: [
+                                { Ebs: { SnapshotId: "snap-old999" } }
+                            ],
+                        },
+                    ],
+                };
+            }
+            // If querying the baked template status "ami-custom456"
+            if (input.ImageIds?.includes("ami-custom456")) {
+                return {
+                    Images: [{ ImageId: "ami-custom456", State: "available" }]
+                };
+            }
+            return { Images: [] };
+        };
+        let describeInstanceCount = 0;
+        mockResponses["DescribeInstancesCommand"] = () => {
+            describeInstanceCount++;
+            return {
+                Reservations: [
+                    {
+                        Instances: [
+                            {
+                                InstanceId: "i-temp123",
+                                State: { Name: describeInstanceCount > 1 ? "stopped" : "running" },
+                                PublicIpAddress: "34.20.10.99",
+                            }
+                        ]
+                    }
+                ]
+            };
+        };
+        const template = new EC2TemplateBuilder("my-docker-base")
+            .provision("playbooks/nginx.yaml");
+        template.waitFor = async (label, condition) => {
+            return await condition();
+        };
+        template.checkPort = async () => true;
+        const provisionSpy = mock.method(template, "runProvisioner", async () => { });
+        const result = await template.deploy();
+        assert.strictEqual(result.amiId, "ami-custom456");
+        // Verify Deregister and Snapshot delete called
+        const deregisterCall = clientCalls.find(c => c.method === "DeregisterImageCommand");
+        assert.ok(deregisterCall);
+        assert.strictEqual(deregisterCall.input.ImageId, "ami-old555");
+        const deleteSnapCall = clientCalls.find(c => c.method === "DeleteSnapshotCommand");
+        assert.ok(deleteSnapCall);
+        assert.strictEqual(deleteSnapCall.input.SnapshotId, "snap-old999");
+        // Verify temp instance was created, stopped, image created, and terminated
+        assert.ok(clientCalls.some(c => c.method === "RunInstancesCommand"));
+        assert.ok(clientCalls.some(c => c.method === "StopInstancesCommand"));
+        assert.ok(clientCalls.some(c => c.method === "CreateImageCommand"));
+        assert.ok(clientCalls.some(c => c.method === "TerminateInstancesCommand"));
+        // Verify provision script ran on resolved temporary instance IP
+        assert.strictEqual(provisionSpy.mock.callCount(), 1);
+        assert.strictEqual(provisionSpy.mock.calls[0].arguments[0], "34.20.10.99");
+        assert.strictEqual(provisionSpy.mock.calls[0].arguments[1], "playbooks/nginx.yaml");
+    });
+    test("EC2 instance clones from custom baked template successfully", async () => {
+        const nginxHash = getFileHash("playbooks/nginx.yaml");
+        mockResponses["DescribeImagesCommand"] = (input) => {
+            if (input.Filters?.some((f) => f.Name === "name" && f.Values?.includes("my-golden-ami"))) {
+                return {
+                    Images: [
+                        {
+                            ImageId: "ami-custom777",
+                            State: "available",
+                            Tags: [
+                                { Key: "Name", Value: "my-golden-ami" },
+                                { Key: "puls-provision", Value: `nginx-yaml=${nginxHash}` },
+                            ],
+                        },
+                    ],
+                };
+            }
+            return { Images: [] };
+        };
+        let describeCount = 0;
+        mockResponses["DescribeInstancesCommand"] = () => {
+            describeCount++;
+            if (describeCount === 1)
+                return { Reservations: [] }; // VM doesn't exist initially
+            return {
+                Reservations: [
+                    {
+                        Instances: [
+                            {
+                                InstanceId: "i-prod123",
+                                State: { Name: "running" },
+                                PublicIpAddress: "34.200.5.5",
+                            }
+                        ]
+                    }
+                ]
+            };
+        };
+        mockResponses["RunInstancesCommand"] = {
+            Instances: [{ InstanceId: "i-prod123" }],
+        };
+        class AWSStack extends Stack {
+            amiTemplate = new EC2TemplateBuilder("my-golden-ami")
+                .provision("playbooks/nginx.yaml");
+            server = new EC2VMBuilder("prod-server-01")
+                .fromTemplate(this.amiTemplate)
+                .instanceType("t3.small");
+        }
+        const stack = new AWSStack();
+        stack.server.waitFor = async () => true;
+        stack.server.checkPort = async () => true;
+        const result = await stack.deploy();
+        // Verify Stack outputs
+        assert.strictEqual(result.amiTemplate.amiId, "ami-custom777");
+        assert.strictEqual(result.server.id, "i-prod123");
+        // Verify VM cloned from dynamic template AMI
+        const runInstanceCall = clientCalls.find(c => c.method === "RunInstancesCommand" && c.input?.ImageId === "ami-custom777");
+        assert.ok(runInstanceCall);
+        assert.strictEqual(runInstanceCall.input.InstanceType, "t3.small");
+    });
+});

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

@@ -3,6 +3,8 @@ export declare class DoApiClient {
     private static readonly BASE;
     constructor(token: string);
     private get authHeaders();
+    private createDoOfflineMock;
+    private request;
     get<T>(path: string): Promise<T>;
     post<T>(path: string, body: unknown): Promise<T>;
     put<T>(path: string, body: unknown): Promise<T>;

package/dist/providers/do/api.js

@@ -1,4 +1,6 @@
 import { Config } from '../../core/config.js';
+import { withRetry } from '../../core/retry.js';
+import { resourceContextStorage } from '../../core/context.js';
 export class DoApiClient {
     token;
     static BASE = 'https://api.digitalocean.com/v2';
@@ -12,46 +14,142 @@ export class DoApiClient {
             'Accept-Encoding': 'identity'
         };
     }
+    createDoOfflineMock(method, path, body) {
+        if (path.includes("/droplets")) {
+            return {
+                droplet: {
+                    id: 1234567,
+                    name: body?.name ?? "mock-droplet",
+                    networks: {
+                        v4: [
+                            { ip_address: "159.203.12.34", type: "public" },
+                            { ip_address: "10.132.0.3", type: "private" }
+                        ]
+                    }
+                },
+                droplets: [
+                    {
+                        id: 1234567,
+                        name: body?.name ?? "mock-droplet",
+                        networks: {
+                            v4: [
+                                { ip_address: "159.203.12.34", type: "public" },
+                                { ip_address: "10.132.0.3", type: "private" }
+                            ]
+                        }
+                    }
+                ]
+            };
+        }
+        if (path.includes("/domains")) {
+            return { domain: { name: "mock-domain.com", ttl: 1800 } };
+        }
+        if (path.includes("/ssh_keys")) {
+            return { ssh_key: { id: 12345, name: "mock-key", public_key: "ssh-rsa mock" } };
+        }
+        return new Proxy({}, {
+            get(target, prop) {
+                if (prop === "then")
+                    return undefined;
+                if (prop === "id")
+                    return 123456;
+                if (prop === "name")
+                    return "mock-do-name";
+                if (prop === "status")
+                    return "active";
+                if (prop.endsWith("s"))
+                    return [];
+                return `mock-do-${prop.toLowerCase()}`;
+            }
+        });
+    }
+    async request(fn) {
+        return withRetry(fn, {
+            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) {
-        const res = await fetch(`${DoApiClient.BASE}${path}`, { headers: this.authHeaders });
-        if (!res.ok)
-            throw new Error(`DO API GET ${path}: ${res.status} ${await res.text()}`);
-        return res.json();
+        const context = resourceContextStorage.getStore();
+        const abortSignal = context?.abortSignal;
+        if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+            return Promise.resolve(this.createDoOfflineMock('GET', path));
+        }
+        return this.request(async () => {
+            const res = await fetch(`${DoApiClient.BASE}${path}`, {
+                headers: this.authHeaders,
+                ...(abortSignal && { signal: abortSignal })
+            });
+            if (!res.ok)
+                throw new Error(`DO API GET ${path}: ${res.status} ${await res.text()}`);
+            return res.json();
+        });
     }
     async post(path, body) {
-        const res = await fetch(`${DoApiClient.BASE}${path}`, {
-            method: 'POST',
-            headers: this.authHeaders,
-            body: JSON.stringify(body),
+        const context = resourceContextStorage.getStore();
+        const abortSignal = context?.abortSignal;
+        if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+            return Promise.resolve(this.createDoOfflineMock('POST', path, body));
+        }
+        return this.request(async () => {
+            const res = await fetch(`${DoApiClient.BASE}${path}`, {
+                method: 'POST',
+                headers: this.authHeaders,
+                body: JSON.stringify(body),
+                ...(abortSignal && { signal: abortSignal })
+            });
+            if (!res.ok)
+                throw new Error(`DO API POST ${path}: ${res.status} ${await res.text()}`);
+            return res.json();
         });
-        if (!res.ok)
-            throw new Error(`DO API POST ${path}: ${res.status} ${await res.text()}`);
-        return res.json();
     }
     async put(path, body) {
-        const res = await fetch(`${DoApiClient.BASE}${path}`, {
-            method: 'PUT',
-            headers: this.authHeaders,
-            body: JSON.stringify(body),
+        const context = resourceContextStorage.getStore();
+        const abortSignal = context?.abortSignal;
+        if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+            return Promise.resolve(this.createDoOfflineMock('PUT', path, body));
+        }
+        return this.request(async () => {
+            const res = await fetch(`${DoApiClient.BASE}${path}`, {
+                method: 'PUT',
+                headers: this.authHeaders,
+                body: JSON.stringify(body),
+                ...(abortSignal && { signal: abortSignal })
+            });
+            if (!res.ok)
+                throw new Error(`DO API PUT ${path}: ${res.status} ${await res.text()}`);
+            return res.json();
         });
-        if (!res.ok)
-            throw new Error(`DO API PUT ${path}: ${res.status} ${await res.text()}`);
-        return res.json();
     }
     async delete(path, body) {
-        const res = await fetch(`${DoApiClient.BASE}${path}`, {
-            method: 'DELETE',
-            headers: this.authHeaders,
-            ...(body !== undefined && { body: JSON.stringify(body) }),
-        });
-        if (!res.ok && res.status !== 404) {
-            throw new Error(`DO API DELETE ${path}: ${res.status} ${await res.text()}`);
+        const context = resourceContextStorage.getStore();
+        const abortSignal = context?.abortSignal;
+        if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+            return Promise.resolve();
         }
+        return this.request(async () => {
+            const res = await fetch(`${DoApiClient.BASE}${path}`, {
+                method: 'DELETE',
+                headers: this.authHeaders,
+                ...(body !== undefined && { body: JSON.stringify(body) }),
+                ...(abortSignal && { signal: abortSignal })
+            });
+            if (!res.ok && res.status !== 404) {
+                throw new Error(`DO API DELETE ${path}: ${res.status} ${await res.text()}`);
+            }
+        });
     }
 }
 export function getDoApi() {
     const token = Config.get().providers.do?.token;
-    if (!token)
+    if (!token) {
+        if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+            return new DoApiClient("mock-do-token");
+        }
         throw new Error('DO token not configured. Call DO.init({ token: "..." })');
+    }
     return new DoApiClient(token);
 }

package/dist/providers/do/droplet.js

@@ -10,6 +10,7 @@ import { LoadBalancerBuilder } from './load_balancer.js';
 import { getDoApi } from './api.js';
 import { checkPort, runProvisioner } from '../../core/provisioner.js';
 import { getFileHash } from '../proxmox/hash.js';
+import { resourceContextStorage } from '../../core/context.js';
 export class DropletBuilder extends BaseBuilder {
     out = {
         ip: new Output(),
@@ -250,6 +251,19 @@ export class DropletBuilder extends BaseBuilder {
                 console.log(`✅ ${this.name} is up to date.`);
             }
         }
+        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: "do"
+                });
+            }
+        }
         for (const sidecar of this.sidecars)
             await sidecar.deploy();
         return this.config;

package/dist/providers/firebase/api.js

@@ -1,7 +1,10 @@
 import fs from 'node:fs';
 import { GoogleAuth } from 'google-auth-library';
 import { Config } from '../../core/config.js';
+import { withRetry } from '../../core/retry.js';
+import { resourceContextStorage } from '../../core/context.js';
 function resolveFirebaseConfig() {
+    const isOffline = Config.isOfflineMode() || Config.isGlobalDryRun();
     const cfg = Config.get().providers.firebase;
     if (cfg?.serviceAccountPath)
         return cfg;
@@ -11,12 +14,18 @@ function resolveFirebaseConfig() {
         const sa = JSON.parse(fs.readFileSync(saPath, 'utf8'));
         return { projectId: sa.project_id, serviceAccountPath: saPath };
     }
+    if (isOffline) {
+        return { projectId: "mock-firebase-project", serviceAccountPath: "/mock/sa.json" };
+    }
     throw new Error('Firebase not configured. Set FIREBASE_SA=/path/to/sa.json or use @Deploy({ firebase: "..." })');
 }
 export function getProjectId() {
     return resolveFirebaseConfig().projectId;
 }
 export async function getFirebaseToken(scopes) {
+    if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+        return "mock-firebase-token";
+    }
     const { serviceAccountPath } = resolveFirebaseConfig();
     const auth = new GoogleAuth({ keyFile: serviceAccountPath, scopes });
     const client = await auth.getClient();
@@ -25,38 +34,92 @@ export async function getFirebaseToken(scopes) {
 }
 const HOSTING_SCOPE = 'https://www.googleapis.com/auth/firebase.hosting';
 const CLOUD_SCOPE = 'https://www.googleapis.com/auth/cloud-platform';
-export async function hostingFetch(path, opts = {}) {
-    const token = await getFirebaseToken([HOSTING_SCOPE]);
-    const base = 'https://firebasehosting.googleapis.com/v1beta1';
-    const res = await fetch(`${base}${path}`, {
-        ...opts,
-        headers: {
-            'Authorization': `Bearer ${token}`,
-            'Content-Type': 'application/json',
-            ...(opts.headers ?? {}),
-        },
+function createFirebaseOfflineMock(path, opts) {
+    if (path.includes("/versions")) {
+        return { name: `${path}/versions/mock-version-id`, status: "FINALIZED" };
+    }
+    if (path.includes("/releases")) {
+        return { name: `${path}/releases/mock-release-id` };
+    }
+    if (path.includes("/sites/")) {
+        return { name: "mock-site-name", defaultUrl: "https://mock-project.web.app" };
+    }
+    return new Proxy({}, {
+        get(target, prop) {
+            if (prop === "then")
+                return undefined;
+            if (prop === "name")
+                return "mock-firebase-name";
+            if (prop === "status")
+                return "FINALIZED";
+            if (prop === "id")
+                return "mock-firebase-id";
+            if (prop.endsWith("s"))
+                return [];
+            return `mock-fb-${prop.toLowerCase()}`;
+        }
     });
-    if (!res.ok) {
-        const body = await res.text();
-        throw new Error(`Firebase Hosting API ${opts.method ?? 'GET'} ${path} → ${res.status}: ${body}`);
+}
+export async function hostingFetch(path, opts = {}) {
+    const context = resourceContextStorage.getStore();
+    const abortSignal = context?.abortSignal;
+    if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+        return Promise.resolve(createFirebaseOfflineMock(path, opts));
     }
-    const text = await res.text();
-    return text ? JSON.parse(text) : null;
+    const fetchOpts = abortSignal ? { ...opts, signal: abortSignal } : opts;
+    return withRetry(async () => {
+        const token = await getFirebaseToken([HOSTING_SCOPE]);
+        const base = 'https://firebasehosting.googleapis.com/v1beta1';
+        const res = await fetch(`${base}${path}`, {
+            ...fetchOpts,
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Content-Type': 'application/json',
+                ...(fetchOpts.headers ?? {}),
+            },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`Firebase Hosting API ${fetchOpts.method ?? 'GET'} ${path} → ${res.status}: ${body}`);
+        }
+        const text = await res.text();
+        return text ? JSON.parse(text) : 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");
+        }
+    });
 }
 export async function cloudFetch(base, path, opts = {}) {
-    const token = await getFirebaseToken([CLOUD_SCOPE]);
-    const res = await fetch(`${base}${path}`, {
-        ...opts,
-        headers: {
-            'Authorization': `Bearer ${token}`,
-            'Content-Type': 'application/json',
-            ...(opts.headers ?? {}),
-        },
-    });
-    if (!res.ok) {
-        const body = await res.text();
-        throw new Error(`GCP API ${opts.method ?? 'GET'} ${path} → ${res.status}: ${body}`);
+    const context = resourceContextStorage.getStore();
+    const abortSignal = context?.abortSignal;
+    if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+        return Promise.resolve(createFirebaseOfflineMock(path, opts));
     }
-    const text = await res.text();
-    return text ? JSON.parse(text) : null;
+    const fetchOpts = abortSignal ? { ...opts, signal: abortSignal } : opts;
+    return withRetry(async () => {
+        const token = await getFirebaseToken([CLOUD_SCOPE]);
+        const res = await fetch(`${base}${path}`, {
+            ...fetchOpts,
+            headers: {
+                'Authorization': `Bearer ${token}`,
+                'Content-Type': 'application/json',
+                ...(fetchOpts.headers ?? {}),
+            },
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`GCP API ${fetchOpts.method ?? 'GET'} ${path} → ${res.status}: ${body}`);
+        }
+        const text = await res.text();
+        return text ? JSON.parse(text) : 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");
+        }
+    });
 }

package/dist/providers/firebase/list.d.ts

@@ -0,0 +1,2 @@
+import type { FirebaseInventory } from "../../types/inventory.js";
+export declare function listFirebaseResources(): Promise<FirebaseInventory>;

package/dist/providers/firebase/list.js

@@ -0,0 +1,25 @@
+import { getProjectId, hostingFetch, cloudFetch } from "./api.js";
+export async function listFirebaseResources() {
+    const project = getProjectId();
+    const [hostRes, fnRes] = await Promise.all([
+        hostingFetch(`/projects/${project}/sites`).catch(() => ({})),
+        cloudFetch("https://cloudfunctions.googleapis.com/v2", `/projects/${project}/locations/-/functions`).catch(() => ({})),
+    ]);
+    // 1. Map Hosting Sites
+    const hostingSites = (hostRes.sites ?? []).map((s) => ({
+        site: s.name.split("/").pop() ?? "unknown",
+    }));
+    // 2. Map Cloud Functions
+    const functions = (fnRes.functions ?? []).map((f) => {
+        const parts = f.name.split("/");
+        const name = parts.pop() ?? "unknown";
+        const region = parts[parts.indexOf("locations") + 1] ?? "unknown";
+        return {
+            name,
+            region,
+            entryPoint: f.buildConfig?.entryPoint ?? "unknown",
+            runtime: f.buildConfig?.runtime ?? "unknown",
+        };
+    });
+    return { hostingSites, functions };
+}