@rollupdate/hctl 0.0.0-stage → 3.0.0

package/dist/cloud/helpers.d.ts

@@ -0,0 +1,27 @@
+import { HetznerCloudClient } from "./client.js";
+export interface CloudActionOptions {
+    json?: boolean;
+    token?: string;
+    yes?: boolean;
+}
+/**
+ * Parse a comma-separated "key=value,key2=value2" string into a labels object.
+ */
+export declare function parseLabels(val: string): Record<string, string>;
+/**
+ * Read and parse a JSON file, returning the parsed content.
+ */
+export declare function readJsonFile<T = unknown>(path: string): T;
+/**
+ * Resolve a numeric ID string or a resource name to a numeric ID.
+ * If the input is purely digits, returns it directly without any API call.
+ * Otherwise, calls the resolver to look up the name and expects exactly one match.
+ */
+export declare function resolveIdOrName(idOrName: string, resourceType: string, resolver: (name: string) => Promise<{
+    id: number;
+    name: string | null;
+}[]>): Promise<number>;
+/**
+ * Wrap a cloud API action with token resolution and error handling.
+ */
+export declare function cloudAction<T extends unknown[]>(fn: (client: HetznerCloudClient, ...args: T) => Promise<void>): (...args: [...T, ...unknown[]]) => Promise<void>;

package/dist/cloud/helpers.js

@@ -0,0 +1,67 @@
+import { readFileSync } from "node:fs";
+import { handleActionError, resolveActionArgs } from "../shared/helpers.js";
+import { HetznerCloudClient } from "./client.js";
+import { resolveToken } from "./context.js";
+const DIGITS_ONLY_REGEX = /^\d+$/;
+/**
+ * Parse a comma-separated "key=value,key2=value2" string into a labels object.
+ */
+export function parseLabels(val) {
+    const labels = {};
+    for (const pair of val.split(",")) {
+        const trimmed = pair.trim();
+        if (!trimmed) {
+            continue;
+        }
+        const eqIdx = trimmed.indexOf("=");
+        if (eqIdx === -1) {
+            labels[trimmed] = "";
+        }
+        else {
+            labels[trimmed.slice(0, eqIdx)] = trimmed.slice(eqIdx + 1);
+        }
+    }
+    return labels;
+}
+/**
+ * Read and parse a JSON file, returning the parsed content.
+ */
+export function readJsonFile(path) {
+    const content = readFileSync(path, "utf-8");
+    return JSON.parse(content);
+}
+/**
+ * Resolve a numeric ID string or a resource name to a numeric ID.
+ * If the input is purely digits, returns it directly without any API call.
+ * Otherwise, calls the resolver to look up the name and expects exactly one match.
+ */
+export async function resolveIdOrName(idOrName, resourceType, resolver) {
+    if (DIGITS_ONLY_REGEX.test(idOrName)) {
+        return Number.parseInt(idOrName, 10);
+    }
+    const matches = await resolver(idOrName);
+    if (matches.length === 0) {
+        throw new Error(`${resourceType} '${idOrName}' not found`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`Multiple ${resourceType}s match '${idOrName}' (IDs: ${matches.map((m) => m.id).join(", ")}). Use numeric ID instead.`);
+    }
+    return matches[0].id;
+}
+/**
+ * Wrap a cloud API action with token resolution and error handling.
+ */
+export function cloudAction(fn) {
+    return async (...args) => {
+        const { handlerArgs, options: merged } = resolveActionArgs(args);
+        const options = merged;
+        try {
+            const token = await resolveToken(options.token);
+            const client = new HetznerCloudClient(token);
+            await fn(client, ...handlerArgs);
+        }
+        catch (error) {
+            handleActionError(error);
+        }
+    };
+}

package/dist/cloud/inventory.d.ts

@@ -0,0 +1,100 @@
+import type { HetznerCloudClient } from "./client.js";
+import type { Certificate, CloudFirewall, CloudPricing, CloudServer, CloudSshKey, FloatingIp, Image, LoadBalancer, Network, PlacementGroup, PrimaryIp, Volume } from "./types.js";
+export interface InventoryServerEntry {
+    backup: boolean;
+    created: string;
+    id: number;
+    ipv4: string | null;
+    ipv6: string | null;
+    location: string;
+    monthly: number | null;
+    name: string;
+    primaryDiskGb: number;
+    status: string;
+    type: string | null;
+    volumeGb: number;
+    volumes: number;
+    warnings: string[];
+}
+export interface InventoryVolumeEntry {
+    attachedTo: number | null;
+    id: number;
+    location: string;
+    monthly: number | null;
+    name: string;
+    sizeGb: number;
+    status: string;
+    warnings: string[];
+}
+export interface InventoryIpEntry {
+    assignedTo: string | null;
+    id: number;
+    ip: string;
+    kind: "primary" | "floating";
+    location: string;
+    monthly: number | null;
+    type: "ipv4" | "ipv6";
+    warnings: string[];
+}
+export interface InventoryLoadBalancerEntry {
+    id: number;
+    location: string;
+    monthly: number | null;
+    name: string;
+    publicIpv4: string | null;
+    targets: number;
+    type: string | null;
+    warnings: string[];
+}
+export interface InventoryImageEntry {
+    boundTo: number | null;
+    id: number;
+    monthly: number | null;
+    name: string | null;
+    sizeGb: number;
+    type: string;
+    warnings: string[];
+}
+export interface InventoryReport {
+    counts: {
+        networks: number;
+        firewalls: number;
+        certificates: number;
+        sshKeys: number;
+        placementGroups: number;
+    };
+    currency: string;
+    generatedAt: string;
+    images: InventoryImageEntry[];
+    ips: InventoryIpEntry[];
+    loadBalancers: InventoryLoadBalancerEntry[];
+    note: string;
+    servers: InventoryServerEntry[];
+    totals: {
+        monthly: number | null;
+        servers: number | null;
+        volumes: number | null;
+        ips: number | null;
+        loadBalancers: number | null;
+        images: number | null;
+    };
+    vatRate: string;
+    volumes: InventoryVolumeEntry[];
+    warnings: string[];
+}
+export declare function buildInventory(client: HetznerCloudClient): Promise<InventoryReport>;
+interface RawInventory {
+    certificates: Certificate[];
+    firewalls: CloudFirewall[];
+    floatingIps: FloatingIp[];
+    images: Image[];
+    loadBalancers: LoadBalancer[];
+    networks: Network[];
+    placementGroups: PlacementGroup[];
+    primaryIps: PrimaryIp[];
+    servers: CloudServer[];
+    sshKeys: CloudSshKey[];
+    volumes: Volume[];
+}
+export declare function assembleReport(pricing: CloudPricing, raw: RawInventory): InventoryReport;
+export {};

package/dist/cloud/inventory.js

@@ -0,0 +1,229 @@
+import { backupMonthly, floatingIpMonthly, imageMonthly, loadBalancerTypeMonthly, primaryIpMonthly, roundCost, serverTypeMonthly, volumeMonthly, } from "./pricing.js";
+/**
+ * Fleet inventory with list-price cost estimates.
+ *
+ * Hetzner has no billing API (verified 2026-10-09: /billing, /invoices,
+ * /costs all 404 on the Cloud API; Robot invoices live only in the web
+ * console), so costs here are estimates: current list prices (GET /pricing)
+ * times live inventory. Dedicated (Robot) servers are out of scope for
+ * costing — their price is contract-specific and not exposed via any API.
+ */
+function primaryIpAssignee(ip) {
+    if (ip.assignee_type === "server") {
+        return `server ${ip.assignee_id}`;
+    }
+    if (ip.assignee_type === "load_balancer") {
+        return `load balancer ${ip.assignee_id}`;
+    }
+    return null;
+}
+function sumNullable(values) {
+    let total = 0;
+    let seen = false;
+    for (const v of values) {
+        if (v !== null) {
+            total += v;
+            seen = true;
+        }
+    }
+    return seen ? roundCost(total) : null;
+}
+export async function buildInventory(client) {
+    const pricing = await client.getPricing();
+    const [servers, volumes, floatingIps, primaryIps, loadBalancers, images, networks, firewalls, certificates, sshKeys, placementGroups,] = await Promise.all([
+        client.listServers(),
+        client.listVolumes(),
+        client.listFloatingIps(),
+        client.listPrimaryIps(),
+        client.listLoadBalancers(),
+        client.listImages({}),
+        client.listNetworks(),
+        client.listFirewalls(),
+        client.listCertificates(),
+        client.listSshKeys(),
+        client.listPlacementGroups(),
+    ]);
+    return assembleReport(pricing, {
+        servers,
+        volumes,
+        floatingIps,
+        primaryIps,
+        loadBalancers,
+        images,
+        networks,
+        firewalls,
+        certificates,
+        sshKeys,
+        placementGroups,
+    });
+}
+export function assembleReport(pricing, raw) {
+    const volumeByServer = new Map();
+    for (const v of raw.volumes) {
+        if (v.server !== null) {
+            const entry = volumeByServer.get(v.server) ?? { count: 0, gb: 0 };
+            entry.count += 1;
+            entry.gb += v.size;
+            volumeByServer.set(v.server, entry);
+        }
+    }
+    const servers = raw.servers.map((s) => {
+        const typeName = s.server_type?.name;
+        const base = serverTypeMonthly(pricing, typeName, s.location?.name);
+        const withBackup = base !== null && s.backup_window
+            ? base + backupMonthly(pricing, base)
+            : base;
+        const warnings = [];
+        if (s.status === "off") {
+            warnings.push("stopped server still billed (delete to stop cost)");
+        }
+        if (base === null) {
+            warnings.push(`server type ${typeName ?? "?"} not found in pricing`);
+        }
+        if (s.server_type?.deprecated) {
+            warnings.push("deprecated server type");
+        }
+        return {
+            id: s.id,
+            name: s.name,
+            type: typeName ?? null,
+            location: s.location?.name ?? "?",
+            status: s.status,
+            created: s.created,
+            ipv4: s.public_net?.ipv4?.ip ?? null,
+            ipv6: s.public_net?.ipv6?.ip ?? null,
+            primaryDiskGb: s.primary_disk_size,
+            volumes: volumeByServer.get(s.id)?.count ?? 0,
+            volumeGb: volumeByServer.get(s.id)?.gb ?? 0,
+            backup: s.backup_window !== null,
+            monthly: roundCost(withBackup),
+            warnings,
+        };
+    });
+    const volumes = raw.volumes.map((v) => {
+        const warnings = [];
+        if (v.server === null) {
+            warnings.push("unattached volume still billed");
+        }
+        return {
+            id: v.id,
+            name: v.name,
+            sizeGb: v.size,
+            location: v.location?.name ?? "?",
+            status: v.status,
+            attachedTo: v.server,
+            monthly: roundCost(volumeMonthly(pricing, v.size)),
+            warnings,
+        };
+    });
+    const ips = [
+        ...raw.primaryIps.map((p) => {
+            const warnings = [];
+            if (p.assignee_type === "unassigned") {
+                warnings.push("unassigned primary IP still billed");
+            }
+            return {
+                id: p.id,
+                kind: "primary",
+                type: p.type,
+                ip: p.ip,
+                location: p.location?.name ?? "?",
+                assignedTo: primaryIpAssignee(p),
+                monthly: roundCost(primaryIpMonthly(pricing, p.type, p.location?.name)),
+                warnings,
+            };
+        }),
+        ...raw.floatingIps.map((f) => {
+            const warnings = [];
+            if (f.server === null) {
+                warnings.push("unassigned floating IP still billed");
+            }
+            return {
+                id: f.id,
+                kind: "floating",
+                type: f.type,
+                ip: f.ip,
+                location: f.home_location?.name ?? "?",
+                assignedTo: f.server === null ? null : `server ${f.server}`,
+                monthly: roundCost(floatingIpMonthly(pricing, f.type, f.home_location?.name)),
+                warnings,
+            };
+        }),
+    ];
+    const loadBalancers = raw.loadBalancers.map((lb) => ({
+        id: lb.id,
+        name: lb.name,
+        type: lb.load_balancer_type?.name ?? null,
+        location: lb.location?.name ?? "?",
+        publicIpv4: lb.public_net?.enabled
+            ? (lb.public_net.ipv4?.ip ?? null)
+            : null,
+        targets: lb.targets?.length ?? 0,
+        monthly: roundCost(loadBalancerTypeMonthly(pricing, lb.load_balancer_type?.name, lb.location?.name)),
+        warnings: [],
+    }));
+    const billedImages = raw.images.filter((i) => i.type === "snapshot" || i.type === "backup");
+    const imagesReport = billedImages.map((i) => ({
+        id: i.id,
+        name: i.name,
+        type: i.type,
+        sizeGb: Math.ceil(i.image_size ?? i.disk_size ?? 0),
+        boundTo: i.bound_to,
+        monthly: roundCost(imageMonthly(pricing, Math.ceil(i.image_size ?? i.disk_size ?? 0))),
+        warnings: [],
+    }));
+    const warnings = [];
+    for (const s of servers) {
+        for (const w of s.warnings) {
+            warnings.push(`server ${s.name}: ${w}`);
+        }
+    }
+    for (const v of volumes) {
+        for (const w of v.warnings) {
+            warnings.push(`volume ${v.name}: ${w}`);
+        }
+    }
+    for (const ip of ips) {
+        for (const w of ip.warnings) {
+            warnings.push(`${ip.kind} ip ${ip.ip}: ${w}`);
+        }
+    }
+    const serverCosts = servers.map((s) => s.monthly);
+    const volumeCosts = volumes.map((v) => v.monthly);
+    const ipCosts = ips.map((i) => i.monthly);
+    const lbCosts = loadBalancers.map((l) => l.monthly);
+    const imageCosts = imagesReport.map((i) => i.monthly);
+    return {
+        generatedAt: new Date().toISOString(),
+        currency: pricing.currency,
+        vatRate: pricing.vat_rate,
+        note: "Costs are list-price estimates (GET /pricing gross monthly x inventory); Hetzner has no billing API. Dedicated (Robot) servers are contract-priced and not included.",
+        servers,
+        volumes,
+        ips,
+        loadBalancers,
+        images: imagesReport,
+        counts: {
+            networks: raw.networks.length,
+            firewalls: raw.firewalls.length,
+            certificates: raw.certificates.length,
+            sshKeys: raw.sshKeys.length,
+            placementGroups: raw.placementGroups.length,
+        },
+        totals: {
+            monthly: sumNullable([
+                ...serverCosts,
+                ...volumeCosts,
+                ...ipCosts,
+                ...lbCosts,
+                ...imageCosts,
+            ]),
+            servers: sumNullable(serverCosts),
+            volumes: sumNullable(volumeCosts),
+            ips: sumNullable(ipCosts),
+            loadBalancers: sumNullable(lbCosts),
+            images: sumNullable(imageCosts),
+        },
+        warnings,
+    };
+}

package/dist/cloud/pricing.d.ts

@@ -0,0 +1,27 @@
+import type { CloudPricing, IpPrice, PriceAmount, PricingServerTypePrice } from "./types.js";
+/**
+ * Pure helpers over the GET /pricing payload.
+ *
+ * Hetzner exposes list prices, not per-account billing: there is no
+ * billing/invoice API on either the Cloud or the Robot API, so "cost" here
+ * always means an estimate from list prices (gross, monthly) times live
+ * inventory. See `hctl cloud inventory`.
+ */
+export declare function toNumber(amount: PriceAmount | undefined): number | null;
+export declare function serverTypeMonthly(pricing: CloudPricing, serverTypeName: string | undefined, location: string | undefined): number | null;
+export declare function loadBalancerTypeMonthly(pricing: CloudPricing, lbTypeName: string | undefined, location: string | undefined): number | null;
+export declare function primaryIpMonthly(pricing: CloudPricing, ipType: "ipv4" | "ipv6", location: string | undefined): number | null;
+export declare function floatingIpMonthly(pricing: CloudPricing, ipType: "ipv4" | "ipv6", location: string | undefined): number | null;
+export declare function volumeMonthly(pricing: CloudPricing, sizeGb: number): number | null;
+export declare function imageMonthly(pricing: CloudPricing, sizeGb: number): number | null;
+/**
+ * Server backups cost a percentage on top of the base server price.
+ */
+export declare function backupMonthly(pricing: CloudPricing, baseMonthly: number): number;
+/**
+ * Overage cost for traffic beyond the included allowance. Returns null when
+ * the pricing entry lacks a per-TB traffic price.
+ */
+export declare function trafficOverageMonthly(price: PricingServerTypePrice | IpPrice | undefined, outgoingBytes: number | null, includedBytes: number): number | null;
+/** Round for display: list prices carry 4+ decimal places. */
+export declare function roundCost(value: number | null): number | null;

package/dist/cloud/pricing.js

@@ -0,0 +1,103 @@
+/**
+ * Pure helpers over the GET /pricing payload.
+ *
+ * Hetzner exposes list prices, not per-account billing: there is no
+ * billing/invoice API on either the Cloud or the Robot API, so "cost" here
+ * always means an estimate from list prices (gross, monthly) times live
+ * inventory. See `hctl cloud inventory`.
+ */
+export function toNumber(amount) {
+    if (!amount) {
+        return null;
+    }
+    const value = Number.parseFloat(amount.gross);
+    return Number.isFinite(value) ? value : null;
+}
+/**
+ * Pick the price entry for a location, falling back to the cheapest
+ * available location when the resource's location is not priced (new
+ * region, stale pricing payload).
+ */
+function pickLocationPrice(prices, location) {
+    if (prices.length === 0) {
+        return undefined;
+    }
+    const exact = location
+        ? prices.find((p) => p.location === location)
+        : undefined;
+    if (exact) {
+        return exact;
+    }
+    return prices.reduce((cheapest, p) => (toNumber(p.price_monthly) ?? Number.POSITIVE_INFINITY) <
+        (toNumber(cheapest.price_monthly) ?? Number.POSITIVE_INFINITY)
+        ? p
+        : cheapest);
+}
+function namedTypeMonthly(table, name, location) {
+    const entry = table.find((t) => t.name === name);
+    if (!entry) {
+        return null;
+    }
+    return toNumber(pickLocationPrice(entry.prices, location)?.price_monthly);
+}
+export function serverTypeMonthly(pricing, serverTypeName, location) {
+    return namedTypeMonthly(pricing.server_types, serverTypeName, location);
+}
+export function loadBalancerTypeMonthly(pricing, lbTypeName, location) {
+    return namedTypeMonthly(pricing.load_balancer_types, lbTypeName, location);
+}
+function ipMonthly(table, ipType, location) {
+    const entry = table.find((t) => t.type === ipType);
+    if (!entry) {
+        return null;
+    }
+    const price = pickLocationPrice(entry.prices, location);
+    return toNumber(price?.price_monthly);
+}
+export function primaryIpMonthly(pricing, ipType, location) {
+    return ipMonthly(pricing.primary_ips, ipType, location);
+}
+export function floatingIpMonthly(pricing, ipType, location) {
+    return ipMonthly(pricing.floating_ips, ipType, location);
+}
+export function volumeMonthly(pricing, sizeGb) {
+    const perGb = toNumber(pricing.volume.price_per_gb_month);
+    return perGb === null ? null : perGb * sizeGb;
+}
+export function imageMonthly(pricing, sizeGb) {
+    const perGb = toNumber(pricing.image.price_per_gb_month);
+    return perGb === null ? null : perGb * sizeGb;
+}
+/**
+ * Server backups cost a percentage on top of the base server price.
+ */
+export function backupMonthly(pricing, baseMonthly) {
+    const percentage = Number.parseFloat(pricing.server_backup.percentage);
+    if (!Number.isFinite(percentage)) {
+        return 0;
+    }
+    return (baseMonthly * percentage) / 100;
+}
+/**
+ * Overage cost for traffic beyond the included allowance. Returns null when
+ * the pricing entry lacks a per-TB traffic price.
+ */
+export function trafficOverageMonthly(price, outgoingBytes, includedBytes) {
+    if (outgoingBytes === null) {
+        return null;
+    }
+    const overBytes = Math.max(0, outgoingBytes - includedBytes);
+    if (overBytes === 0) {
+        return 0;
+    }
+    const perTb = toNumber(price?.price_per_tb_traffic);
+    if (perTb === null) {
+        return null;
+    }
+    const TB = 1024 ** 4;
+    return (overBytes / TB) * perTb;
+}
+/** Round for display: list prices carry 4+ decimal places. */
+export function roundCost(value) {
+    return value === null ? null : Math.round(value * 100) / 100;
+}

package/dist/cloud/token-instructions.d.ts

@@ -0,0 +1,2 @@
+export declare const HETZNER_CLOUD_CONSOLE_URL = "https://console.hetzner.cloud";
+export declare function printCloudTokenInstructions(): void;

package/dist/cloud/token-instructions.js

@@ -0,0 +1,21 @@
+import { heading } from "../shared/formatter.js";
+export const HETZNER_CLOUD_CONSOLE_URL = "https://console.hetzner.cloud";
+export function printCloudTokenInstructions() {
+    console.log("");
+    console.log(heading("Hetzner Cloud API Token"));
+    console.log("");
+    console.log("To create a Cloud API token:");
+    console.log(`  1. Open ${HETZNER_CLOUD_CONSOLE_URL}`);
+    console.log("  2. Select your project (or create one)");
+    console.log("  3. Left menu: Security");
+    console.log("  4. Top menu: API Tokens");
+    console.log('  5. Click "Generate API Token"');
+    console.log('  6. Name the token, for example "hctl"');
+    console.log('  7. Choose "Read & Write" for full hctl management, or "Read" for list/describe only');
+    console.log("  8. Copy the token now; Hetzner only shows it once.");
+    console.log("");
+    console.log("Note: Tokens are scoped per project (one token per project).");
+    console.log("This is separate from Robot web service credentials at https://robot.hetzner.com.");
+    console.log("hctl verifies Cloud tokens with api.hetzner.cloud before saving them; use --no-verify only when offline.");
+    console.log("");
+}