@puls-dev/hcloud 0.5.3

package/README.md

@@ -0,0 +1,55 @@
+# @puls-dev/hcloud
+
+**Hetzner Cloud (HCloud) Provider for Puls IaC. Declare servers, networks, firewalls, and SSH keys in strongly-typed TypeScript.**
+
+---
+
+## What is @puls-dev/hcloud?
+
+This package is the official Hetzner Cloud provider plug-in for Puls. It manages HCloud resources securely by resolving live states directly through the Hetzner Cloud REST APIs.
+
+## Available Builders
+
+* **\`HCloud.Server\`**: Provision cloud servers (analogous to Droplets) with support for SSH keys, server types, locations, and our signature Ansible playbook provisioning.
+* **\`HCloud.SSHKey\`**: Register SSH public keys on your Hetzner Cloud account.
+* **\`HCloud.Network\`**: Create private networks (VPCs) with custom IP ranges.
+* **\`HCloud.Firewall\`**: Define inbound/outbound firewall rules.
+
+## Installation
+
+\`\`\`bash
+npm install @puls-dev/core @puls-dev/hcloud
+\`\`\`
+
+## Quick Example
+
+\`\`\`typescript
+import { Stack, Deploy } from "@puls-dev/core";
+import { HCloud, SERVER_TYPE, LOCATION, OS_IMAGE } from "@puls-dev/hcloud";
+
+@Deploy()
+class MyStack extends Stack {
+  key = HCloud.SSHKey("my-key")
+    .publicKey("ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL...");
+
+  net = HCloud.Network("private-net")
+    .ipRange("10.0.0.0/16");
+
+  web = HCloud.Server("web-server")
+    .serverType(SERVER_TYPE.CX22)
+    .image(OS_IMAGE.UBUNTU_24_04)
+    .location(LOCATION.NBG1)
+    .sshKeys([this.key])
+    .networks([this.net])
+    .provision(["playbooks/web.yml"]);
+}
+\`\`\`
+
+## Authentication
+
+Declare your Hetzner Cloud API token in your \`.env\` file:
+\`\`\`bash
+HCLOUD_TOKEN=your-hetzner-cloud-api-token
+\`\`\`
+
+Learn more at **[pulsdev.io/providers/hcloud](https://pulsdev.io/providers/hcloud.md)**.

package/dist/api.d.ts

@@ -0,0 +1,14 @@
+export declare class HCloudApiClient {
+    private token;
+    private static readonly BASE;
+    constructor(token: string);
+    private get authHeaders();
+    private createOfflineMock;
+    private request;
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+    put<T>(path: string, body: unknown): Promise<T>;
+    delete(path: string, body?: unknown): Promise<void>;
+    waitForAction(actionId: number): Promise<void>;
+}
+export declare function getHCloudApi(): HCloudApiClient;

package/dist/api.js

@@ -0,0 +1,211 @@
+import { Config } from '@puls-dev/core';
+import { withRetry } from '@puls-dev/core';
+import { resourceContextStorage } from '@puls-dev/core';
+export class HCloudApiClient {
+    token;
+    static BASE = 'https://api.hetzner.cloud/v1';
+    constructor(token) {
+        this.token = token;
+    }
+    get authHeaders() {
+        return {
+            Authorization: `Bearer ${this.token}`,
+            'Content-Type': 'application/json',
+            'Accept-Encoding': 'identity'
+        };
+    }
+    createOfflineMock(method, path, body) {
+        if (path.includes("/servers")) {
+            const name = body?.name ?? "mock-server";
+            return {
+                server: {
+                    id: 123456,
+                    name,
+                    status: "running",
+                    public_net: {
+                        ipv4: { ip: "159.69.1.2" }
+                    },
+                    private_net: [],
+                    server_type: { name: body?.server_type ?? "cx22" },
+                    image: { name: body?.image ?? "ubuntu-24.04" },
+                    datacenter: { location: { name: body?.location ?? "nbg1" } }
+                },
+                servers: [
+                    {
+                        id: 123456,
+                        name,
+                        status: "running",
+                        public_net: {
+                            ipv4: { ip: "159.69.1.2" }
+                        },
+                        private_net: [],
+                        server_type: { name: "cx22" },
+                        image: { name: "ubuntu-24.04" },
+                        datacenter: { location: { name: "nbg1" } }
+                    }
+                ],
+                action: { id: 7890, status: "success" }
+            };
+        }
+        if (path.includes("/ssh_keys")) {
+            return {
+                ssh_key: {
+                    id: 12345,
+                    name: body?.name ?? "mock-key",
+                    public_key: body?.public_key ?? "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIL...",
+                    fingerprint: "00:11:22:33:44:55:66:77:88:99:aa:bb:cc:dd:ee:ff"
+                },
+                ssh_keys: []
+            };
+        }
+        if (path.includes("/networks")) {
+            return {
+                network: {
+                    id: 5678,
+                    name: body?.name ?? "mock-net",
+                    ip_range: body?.ip_range ?? "10.0.0.0/16"
+                },
+                networks: []
+            };
+        }
+        if (path.includes("/firewalls")) {
+            return {
+                firewall: {
+                    id: 9012,
+                    name: body?.name ?? "mock-fw",
+                    rules: body?.rules ?? []
+                },
+                firewalls: []
+            };
+        }
+        if (path.includes("/actions/")) {
+            return { action: { id: 7890, status: "success" } };
+        }
+        return new Proxy({}, {
+            get(target, prop) {
+                if (prop === "then")
+                    return undefined;
+                if (prop === "id")
+                    return 123456;
+                if (prop === "name")
+                    return "mock-hcloud-name";
+                if (prop === "status")
+                    return "success";
+                if (prop.endsWith("s"))
+                    return [];
+                return `mock-hcloud-${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 context = resourceContextStorage.getStore();
+        const abortSignal = context?.abortSignal;
+        if (Config.isOfflineMode() || (Config.isGlobalDryRun() && this.token === "mock-hcloud-token")) {
+            return Promise.resolve(this.createOfflineMock('GET', path));
+        }
+        return this.request(async () => {
+            const res = await fetch(`${HCloudApiClient.BASE}${path}`, {
+                headers: this.authHeaders,
+                ...(abortSignal && { signal: abortSignal })
+            });
+            if (!res.ok)
+                throw new Error(`HCloud API GET ${path}: ${res.status} ${await res.text()}`);
+            return res.json();
+        });
+    }
+    async post(path, body) {
+        const context = resourceContextStorage.getStore();
+        const abortSignal = context?.abortSignal;
+        if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+            return Promise.resolve(this.createOfflineMock('POST', path, body));
+        }
+        return this.request(async () => {
+            const res = await fetch(`${HCloudApiClient.BASE}${path}`, {
+                method: 'POST',
+                headers: this.authHeaders,
+                body: JSON.stringify(body),
+                ...(abortSignal && { signal: abortSignal })
+            });
+            if (!res.ok)
+                throw new Error(`HCloud API POST ${path}: ${res.status} ${await res.text()}`);
+            return res.json();
+        });
+    }
+    async put(path, body) {
+        const context = resourceContextStorage.getStore();
+        const abortSignal = context?.abortSignal;
+        if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+            return Promise.resolve(this.createOfflineMock('PUT', path, body));
+        }
+        return this.request(async () => {
+            const res = await fetch(`${HCloudApiClient.BASE}${path}`, {
+                method: 'PUT',
+                headers: this.authHeaders,
+                body: JSON.stringify(body),
+                ...(abortSignal && { signal: abortSignal })
+            });
+            if (!res.ok)
+                throw new Error(`HCloud API PUT ${path}: ${res.status} ${await res.text()}`);
+            return res.json();
+        });
+    }
+    async delete(path, body) {
+        const context = resourceContextStorage.getStore();
+        const abortSignal = context?.abortSignal;
+        if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+            return Promise.resolve();
+        }
+        return this.request(async () => {
+            const res = await fetch(`${HCloudApiClient.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(`HCloud API DELETE ${path}: ${res.status} ${await res.text()}`);
+            }
+        });
+    }
+    async waitForAction(actionId) {
+        if (Config.isOfflineMode() || Config.isGlobalDryRun()) {
+            return Promise.resolve();
+        }
+        const context = resourceContextStorage.getStore();
+        const abortSignal = context?.abortSignal;
+        while (true) {
+            if (abortSignal?.aborted) {
+                throw new Error("Action wait aborted");
+            }
+            const res = await this.get(`/actions/${actionId}`);
+            if (res.action.status === 'success') {
+                return;
+            }
+            if (res.action.status === 'error') {
+                throw new Error(`HCloud Action ${actionId} failed: ${res.action.error?.message}`);
+            }
+            // Wait 1 second before polling again
+            await new Promise((resolve) => setTimeout(resolve, 1000));
+        }
+    }
+}
+let apiInstance = null;
+export function getHCloudApi() {
+    if (apiInstance)
+        return apiInstance;
+    const token = process.env.HCLOUD_TOKEN || Config.get().providers.hcloud?.token;
+    if (!token && !Config.isOfflineMode()) {
+        throw new Error("Hetzner Cloud token not configured. Set HCLOUD_TOKEN environment variable.");
+    }
+    apiInstance = new HCloudApiClient(token || "mock-hcloud-token");
+    return apiInstance;
+}

package/dist/firewall.d.ts

@@ -0,0 +1,27 @@
+import { BaseBuilder } from '@puls-dev/core';
+export interface HCloudFirewallRule {
+    type: 'ingress' | 'egress';
+    protocol: 'tcp' | 'udp' | 'icmp' | 'esp' | 'gre';
+    port: number | string;
+    sources?: string[];
+    destinations?: string[];
+}
+export declare class FirewallBuilder extends BaseBuilder {
+    private _rules;
+    private serverNames;
+    private firewallId?;
+    private log;
+    constructor(name: string);
+    private discoverFirewall;
+    ingress(protocol: 'tcp' | 'udp' | 'icmp' | 'esp' | 'gre', port: number | string, sources: string[]): this;
+    egress(protocol: 'tcp' | 'udp' | 'icmp' | 'esp' | 'gre', port: number | string, destinations: string[]): this;
+    rules(filePath: string): this;
+    attachTo(serverName: string): this;
+    private resolveServerIds;
+    private buildApiRules;
+    deploy(): Promise<{
+        name: string;
+        rules: HCloudFirewallRule[];
+    }>;
+    destroy(): Promise<void>;
+}

package/dist/firewall.js

@@ -0,0 +1,133 @@
+import { BaseBuilder } from '@puls-dev/core';
+import { getHCloudApi } from './api.js';
+import { loadRecordsFromFile } from '@puls-dev/core';
+export class FirewallBuilder extends BaseBuilder {
+    _rules = [];
+    serverNames = [];
+    firewallId;
+    log(msg) {
+        console.log(`   🛡️ [HCloud.Firewall] ${msg}`);
+    }
+    constructor(name) {
+        super(name);
+        this.discoveryPromise = this.discoverFirewall(name);
+    }
+    async discoverFirewall(name) {
+        const api = getHCloudApi();
+        const data = await api.get('/firewalls');
+        const match = data.firewalls.find(f => f.name === name) ?? null;
+        if (match) {
+            this.firewallId = match.id;
+        }
+        return match;
+    }
+    ingress(protocol, port, sources) {
+        this._rules.push({ type: 'ingress', protocol, port, sources });
+        return this;
+    }
+    egress(protocol, port, destinations) {
+        this._rules.push({ type: 'egress', protocol, port, destinations });
+        return this;
+    }
+    rules(filePath) {
+        const loaded = loadRecordsFromFile(filePath);
+        for (const r of loaded) {
+            this._rules.push({
+                type: r.type,
+                protocol: r.protocol,
+                port: r.port,
+                sources: r.sources,
+                destinations: r.destinations,
+            });
+        }
+        return this;
+    }
+    attachTo(serverName) {
+        this.serverNames.push(serverName);
+        return this;
+    }
+    async resolveServerIds(api) {
+        const ids = [];
+        for (const name of this.serverNames) {
+            const data = await api.get(`/servers?name=${encodeURIComponent(name)}`);
+            const match = data.servers.find(s => s.name === name);
+            if (match)
+                ids.push(match.id);
+        }
+        return ids;
+    }
+    buildApiRules() {
+        return this._rules.map(r => {
+            const direction = r.type === 'ingress' ? 'in' : 'out';
+            const rule = {
+                direction,
+                protocol: r.protocol,
+                port: String(r.port),
+            };
+            if (direction === 'in') {
+                rule.source_ips = r.sources ?? [];
+            }
+            else {
+                rule.destination_ips = r.destinations ?? [];
+            }
+            return rule;
+        });
+    }
+    async deploy() {
+        const dryRun = this.isDryRunActive();
+        const existing = await this.discoveryPromise;
+        const api = getHCloudApi();
+        this.log(`Finalizing firewall...`);
+        if (dryRun) {
+            this._rules.forEach(r => {
+                const dir = r.type === 'ingress' ? 'from' : 'to';
+                const targets = r.type === 'ingress' ? r.sources : r.destinations;
+                this.log(`[PLAN] ${r.type.toUpperCase()}: ${r.protocol.toUpperCase()} ${r.port} ${dir} [${targets?.join(', ')}]`);
+            });
+            return { name: this.name, rules: this._rules };
+        }
+        const serverIds = await this.resolveServerIds(api);
+        const rules = this.buildApiRules();
+        const applyTo = serverIds.map(id => ({
+            type: 'server',
+            server: { id }
+        }));
+        if (existing) {
+            this.firewallId = existing.id;
+            // Update rules
+            await api.post(`/firewalls/${this.firewallId}/actions/set_rules`, { rules });
+            // Apply to resources
+            if (applyTo.length > 0) {
+                await api.post(`/firewalls/${this.firewallId}/actions/apply_to_resources`, { apply_to: applyTo });
+            }
+            this.log(`Updated firewall (id=${this.firewallId})`);
+        }
+        else {
+            const result = await api.post('/firewalls', {
+                name: this.name,
+                rules,
+                apply_to: applyTo
+            });
+            this.firewallId = result.firewall.id;
+            this.log(`Created firewall (id=${this.firewallId})`);
+        }
+        this._rules.forEach(r => {
+            const dir = r.type === 'ingress' ? 'from' : 'to';
+            const targets = r.type === 'ingress' ? r.sources : r.destinations;
+            this.log(`✅ ${r.type.toUpperCase()}: ${r.protocol.toUpperCase()} ${r.port} ${dir} [${targets?.join(', ')}]`);
+        });
+        return { name: this.name, rules: this._rules };
+    }
+    async destroy() {
+        const existing = await this.discoveryPromise;
+        if (existing) {
+            this.log(`Deleting firewall...`);
+            const api = getHCloudApi();
+            await api.delete(`/firewalls/${existing.id}`);
+            this.log(`Deleted firewall.`);
+        }
+        else {
+            this.log(`Firewall does not exist. Skipping deletion.`);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+import "./plugin.js";
+import { ServerBuilder } from "./server.js";
+import { SSHKeyBuilder } from "./ssh_key.js";
+import { NetworkBuilder } from "./network.js";
+import { FirewallBuilder } from "./firewall.js";
+export declare const HCloud: {
+    init: (opts: {
+        token: string;
+        defaultLocation?: string;
+        sshUser?: string;
+    }) => void;
+    Server: (name: string) => ServerBuilder;
+    SSHKey: (name: string) => SSHKeyBuilder;
+    Network: (name: string) => NetworkBuilder;
+    Firewall: (name: string) => FirewallBuilder;
+};
+export * from "./types/hcloud.js";
+export { ServerBuilder } from "./server.js";
+export { SSHKeyBuilder } from "./ssh_key.js";
+export { NetworkBuilder } from "./network.js";
+export { FirewallBuilder } from "./firewall.js";
+export { HCloudApiClient, getHCloudApi } from "./api.js";
+export { listHCloudResources } from "./list.js";

package/dist/index.js

@@ -0,0 +1,27 @@
+import "./plugin.js";
+import { Config } from "@puls-dev/core";
+import { ServerBuilder } from "./server.js";
+import { SSHKeyBuilder } from "./ssh_key.js";
+import { NetworkBuilder } from "./network.js";
+import { FirewallBuilder } from "./firewall.js";
+export const HCloud = {
+    init: (opts) => {
+        Config.set({
+            providers: {
+                ...Config.get().providers,
+                hcloud: opts,
+            },
+        });
+    },
+    Server: (name) => new ServerBuilder(name),
+    SSHKey: (name) => new SSHKeyBuilder(name),
+    Network: (name) => new NetworkBuilder(name),
+    Firewall: (name) => new FirewallBuilder(name),
+};
+export * from "./types/hcloud.js";
+export { ServerBuilder } from "./server.js";
+export { SSHKeyBuilder } from "./ssh_key.js";
+export { NetworkBuilder } from "./network.js";
+export { FirewallBuilder } from "./firewall.js";
+export { HCloudApiClient, getHCloudApi } from "./api.js";
+export { listHCloudResources } from "./list.js";

package/dist/list.d.ts

@@ -0,0 +1,2 @@
+import type { HCloudInventory } from '@puls-dev/core';
+export declare function listHCloudResources(): Promise<HCloudInventory>;

package/dist/list.js

@@ -0,0 +1,45 @@
+import { getHCloudApi } from './api.js';
+const HCLOUD_PRICING = {
+    'cx22': 3.60,
+    'cpx11': 4.80,
+    'cpx21': 7.90,
+    'cpx31': 14.80,
+    'cpx41': 29.60,
+    'cpx51': 64.20,
+    'cax11': 4.00,
+    'cax21': 8.00,
+    'cax31': 16.00,
+    'cax41': 32.00,
+};
+function priceForType(type) {
+    return HCLOUD_PRICING[type] ?? 0;
+}
+export async function listHCloudResources() {
+    const api = getHCloudApi();
+    const [serversData, firewallsData, networksData] = await Promise.all([
+        api.get('/servers'),
+        api.get('/firewalls'),
+        api.get('/networks'),
+    ]);
+    const servers = serversData.servers.map((s) => ({
+        id: s.id,
+        name: s.name,
+        status: s.status,
+        location: s.datacenter?.location?.name ?? '',
+        serverType: s.server_type?.name ?? '',
+        ip: s.public_net?.ipv4?.ip,
+        monthlyCost: priceForType(s.server_type?.name),
+    }));
+    const firewalls = firewallsData.firewalls.map((f) => ({
+        id: f.id,
+        name: f.name,
+        serverCount: (f.applied_to ?? []).filter((r) => r.type === 'server').length,
+    }));
+    const networks = networksData.networks.map((n) => ({
+        id: n.id,
+        name: n.name,
+        ipRange: n.ip_range ?? '',
+    }));
+    const totalMonthlyCost = servers.reduce((sum, s) => sum + s.monthlyCost, 0);
+    return { servers, firewalls, networks, totalMonthlyCost };
+}

package/dist/network.d.ts

@@ -0,0 +1,20 @@
+import { BaseBuilder } from '@puls-dev/core';
+import { Output } from '@puls-dev/core';
+export declare class NetworkBuilder extends BaseBuilder {
+    readonly out: {
+        id: Output<number>;
+    };
+    private _ipRange;
+    private networkId?;
+    private log;
+    constructor(name: string);
+    private discoverNetwork;
+    ipRange(range: string): this;
+    getDiff(existing: any): {
+        field: string;
+        declared: string;
+        live: any;
+    }[];
+    deploy(): Promise<void>;
+    destroy(): Promise<void>;
+}

package/dist/network.js

@@ -0,0 +1,80 @@
+import { BaseBuilder } from '@puls-dev/core';
+import { Output } from '@puls-dev/core';
+import { getHCloudApi } from './api.js';
+export class NetworkBuilder extends BaseBuilder {
+    out = {
+        id: new Output(),
+    };
+    _ipRange = "10.0.0.0/16";
+    networkId;
+    log(msg) {
+        console.log(`   🌐 [HCloud.Network] ${msg}`);
+    }
+    constructor(name) {
+        super(name);
+        this.discoveryPromise = this.discoverNetwork(name);
+    }
+    async discoverNetwork(name) {
+        const api = getHCloudApi();
+        const data = await api.get('/networks');
+        const match = data.networks.find(n => n.name === name) ?? null;
+        if (match) {
+            this.networkId = match.id;
+            this.out.id.resolve(match.id);
+        }
+        return match;
+    }
+    ipRange(range) {
+        this._ipRange = range;
+        return this;
+    }
+    getDiff(existing) {
+        const diffs = [];
+        if (existing && existing.ip_range !== this._ipRange) {
+            diffs.push({ field: "ipRange", declared: this._ipRange, live: existing.ip_range });
+        }
+        return diffs;
+    }
+    async deploy() {
+        const api = getHCloudApi();
+        const existing = await this.discoveryPromise;
+        if (!existing) {
+            this.log(`Creating Network...`);
+            const res = await api.post('/networks', {
+                name: this.name,
+                ip_range: this._ipRange,
+            });
+            this.networkId = res.network.id;
+            this.out.id.resolve(res.network.id);
+            this.log(`Created Network with ID ${this.networkId}`);
+        }
+        else {
+            const diffs = this.getDiff(existing);
+            if (diffs.length > 0) {
+                this.log(`Network IP range has drifted. Re-creating...`);
+                await api.delete(`/networks/${this.networkId}`);
+                const res = await api.post('/networks', {
+                    name: this.name,
+                    ip_range: this._ipRange,
+                });
+                this.networkId = res.network.id;
+                this.out.id.resolve(res.network.id);
+            }
+            else {
+                this.log(`Network already exists and is up to date.`);
+            }
+        }
+    }
+    async destroy() {
+        const existing = await this.discoveryPromise;
+        if (existing) {
+            this.log(`Deleting Network...`);
+            const api = getHCloudApi();
+            await api.delete(`/networks/${this.networkId}`);
+            this.log(`Deleted Network.`);
+        }
+        else {
+            this.log(`Network does not exist. Skipping deletion.`);
+        }
+    }
+}

package/dist/plugin.d.ts

@@ -0,0 +1,9 @@
+import { listHCloudResources } from "./list.js";
+import type { HCloudInventory } from "@puls-dev/core";
+export declare const hcloudPlugin: {
+    name: string;
+    isConfigured: (cfg: any) => boolean;
+    list: typeof listHCloudResources;
+    render: (inv: HCloudInventory) => void;
+    configure: (pOpts: any) => void;
+};