@rollupdate/hctl 0.0.0-stage → 3.1.0

package/dist/auction/formatter.js

@@ -0,0 +1,182 @@
+import { colorize, createTable, heading, info } from "../shared/formatter.js";
+function summarizeDisks(server) {
+    const parts = [];
+    const { nvme, sata, hdd } = server.serverDiskData;
+    if (nvme.length > 0) {
+        parts.push(`${nvme.length}x ${formatDiskSize(nvme[0])} NVMe`);
+    }
+    if (sata.length > 0) {
+        parts.push(`${sata.length}x ${formatDiskSize(sata[0])} SATA`);
+    }
+    if (hdd.length > 0) {
+        parts.push(`${hdd.length}x ${formatDiskSize(hdd[0])} HDD`);
+    }
+    return parts.length > 0 ? parts.join(", ") : "-";
+}
+function formatDiskSize(gb) {
+    if (gb >= 1000) {
+        return `${(gb / 1000).toFixed(gb % 1000 === 0 ? 0 : 1)} TB`;
+    }
+    return `${gb} GB`;
+}
+function formatNextReduce(server) {
+    if (server.fixed_price) {
+        return "Fixed";
+    }
+    if (server.next_reduce <= 0) {
+        return "-";
+    }
+    const hours = Math.floor(server.next_reduce / 60);
+    const mins = server.next_reduce % 60;
+    if (hours > 0) {
+        return `${hours}h ${mins}m`;
+    }
+    return `${mins}m`;
+}
+function formatUpdatedAt(timestamp) {
+    const parsed = new Date(timestamp);
+    if (Number.isNaN(parsed.getTime())) {
+        return timestamp;
+    }
+    return parsed.toLocaleString();
+}
+function formatAge(ageSeconds) {
+    if (ageSeconds < 60) {
+        return `${ageSeconds}s ago`;
+    }
+    const minutes = Math.floor(ageSeconds / 60);
+    if (minutes < 60) {
+        return `${minutes}m ago`;
+    }
+    const hours = Math.floor(minutes / 60);
+    const remainingMinutes = minutes % 60;
+    return remainingMinutes === 0
+        ? `${hours}h ago`
+        : `${hours}h ${remainingMinutes}m ago`;
+}
+function formatSource(source) {
+    if (source === "cloudflare-r2") {
+        return "hosted cache";
+    }
+    if (source === "cloudflare-kv") {
+        return "hosted cache fallback";
+    }
+    if (source === "direct") {
+        return "Hetzner direct";
+    }
+    if (source === "local-cache") {
+        return "local cache";
+    }
+    return source;
+}
+export function formatAuctionFetchMetadata(metadata) {
+    const source = formatSource(metadata.source);
+    const updatedAt = metadata.updatedAt === undefined
+        ? `fetched ${formatUpdatedAt(metadata.fetchedAt)}`
+        : `updated ${formatUpdatedAt(metadata.updatedAt)}`;
+    const age = metadata.ageSeconds === undefined
+        ? ""
+        : ` (${formatAge(metadata.ageSeconds)})`;
+    const stale = metadata.stale ? " stale" : "";
+    return colorize(`Auction data: ${updatedAt}${age} via ${source}${stale}`, "gray");
+}
+export function formatAuctionStatus(status) {
+    const table = createTable(["Property", "Value"]);
+    table.push(["Currency", status.currency], ["Endpoint", status.endpointUrl], ["Source", formatSource(status.source)], ["Server Count", status.serverCount.toString()], ["Updated", status.updatedAt ? formatUpdatedAt(status.updatedAt) : "-"], [
+        "Age",
+        status.ageSeconds === undefined ? "-" : formatAge(status.ageSeconds),
+    ], ["Stale", status.stale ? "Yes" : "No"], ["Offline Fallback", status.usingLocalFallback ? "Yes" : "No"]);
+    if (status.localCache !== null) {
+        table.push([
+            "Local Cache Updated",
+            status.localCache.updatedAt
+                ? formatUpdatedAt(status.localCache.updatedAt)
+                : "-",
+        ], [
+            "Local Cache Age",
+            status.localCache.ageSeconds === undefined
+                ? "-"
+                : formatAge(status.localCache.ageSeconds),
+        ], ["Local Cache Servers", status.localCache.serverCount.toString()]);
+    }
+    else {
+        table.push(["Local Cache", "Not seeded"]);
+    }
+    return `${heading("Auction Status")}\n${table.toString()}`;
+}
+export function formatAuctionList(servers) {
+    if (servers.length === 0) {
+        return info("No auction servers found matching your filters.");
+    }
+    const table = createTable([
+        "ID",
+        "CPU",
+        "RAM",
+        "Disks",
+        "DC",
+        "Price",
+        "Setup",
+        "Type",
+        "Reduce",
+        "Specials",
+    ]);
+    for (const s of servers) {
+        const specials = s.specials.length > 0 ? s.specials.join(", ") : "-";
+        table.push([
+            s.id.toString(),
+            s.cpu,
+            `${s.ram_size} GB${s.is_ecc ? " ECC" : ""}`,
+            summarizeDisks(s),
+            s.datacenter,
+            `€${s.price.toFixed(2)}`,
+            s.setup_price > 0 ? `€${s.setup_price.toFixed(2)}` : "Free",
+            s.fixed_price ? "Fixed" : "Auction",
+            formatNextReduce(s),
+            specials,
+        ]);
+    }
+    return `${table.toString()}\n${colorize(`${servers.length} server(s) found`, "gray")}`;
+}
+export function formatAuctionDetails(server) {
+    const lines = [];
+    lines.push(heading(`Auction Server ${server.id}`));
+    lines.push("");
+    const table = createTable(["Property", "Value"]);
+    table.push(["ID", server.id.toString()], ["Name", server.name], ["CPU", server.cpu], ["CPU Count", server.cpu_count.toString()], ["RAM", `${server.ram_size} GB${server.is_ecc ? " (ECC)" : ""}`], ["RAM Details", server.ram.join(", ")], ["Disks", summarizeDisks(server)], ["Disk Details", server.hdd_hr.join(", ") || "-"], ["Total Disk Size", `${server.hdd_size} GB`], ["Disk Count", server.hdd_count.toString()], ["Datacenter", `${server.datacenter_hr} (${server.datacenter})`], ["Traffic", server.traffic], ["Bandwidth", `${server.bandwidth} Mbit/s`], ["Price", `€${server.price.toFixed(2)}/mo`], ["Hourly Price", `€${server.hourly_price.toFixed(4)}/h`], [
+        "Setup Price",
+        server.setup_price > 0 ? `€${server.setup_price.toFixed(2)}` : "Free",
+    ], ["Price Type", server.fixed_price ? "Fixed" : "Auction"], ["Next Reduce", formatNextReduce(server)], [
+        "Specials",
+        server.specials.length > 0 ? server.specials.join(", ") : "None",
+    ], ["High I/O", server.is_highio ? "Yes" : "No"], ["ECC", server.is_ecc ? "Yes" : "No"]);
+    lines.push(table.toString());
+    // Disk breakdown
+    const { nvme, sata, hdd } = server.serverDiskData;
+    if (nvme.length > 0 || sata.length > 0 || hdd.length > 0) {
+        lines.push("");
+        lines.push(colorize("Disk Breakdown:", "bold"));
+        if (nvme.length > 0) {
+            lines.push(`  NVMe: ${nvme.map((d) => formatDiskSize(d)).join(", ")}`);
+        }
+        if (sata.length > 0) {
+            lines.push(`  SATA: ${sata.map((d) => formatDiskSize(d)).join(", ")}`);
+        }
+        if (hdd.length > 0) {
+            lines.push(`  HDD:  ${hdd.map((d) => formatDiskSize(d)).join(", ")}`);
+        }
+    }
+    // IP Pricing
+    lines.push("");
+    lines.push(colorize("Additional IP Pricing:", "bold"));
+    lines.push(`  Monthly: €${server.ip_price.Monthly.toFixed(2)}`);
+    lines.push(`  Hourly:  €${server.ip_price.Hourly.toFixed(4)}`);
+    // Description
+    if (server.description.length > 0) {
+        lines.push("");
+        lines.push(colorize("Description:", "bold"));
+        for (const line of server.description) {
+            lines.push(`  ${line}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/auction/store.d.ts

@@ -0,0 +1,24 @@
+import Database from "better-sqlite3";
+import type { AuctionFetchMetadata } from "./client.js";
+import type { AuctionServer } from "./types.js";
+export interface StoredSnapshot {
+    currency: string;
+    id: number;
+    serverCount: number;
+    takenAt: string;
+}
+export interface CachedAuctionData {
+    data: {
+        server: AuctionServer[];
+        serverCount: number;
+    };
+    metadata: AuctionFetchMetadata;
+}
+export declare function initSchema(db: Database.Database): void;
+export declare function openDatabase(dbPath?: string): Database.Database;
+export declare function saveSnapshot(db: Database.Database, servers: AuctionServer[], currency: string): StoredSnapshot;
+export declare function getLatestSnapshot(db: Database.Database, currency: string): StoredSnapshot | null;
+export declare function getSnapshotServers(db: Database.Database, snapshotId: number): AuctionServer[];
+export declare function saveAuctionCache(db: Database.Database, currency: string, cached: CachedAuctionData): void;
+export declare function getAuctionCache(db: Database.Database, currency: string): CachedAuctionData | null;
+export declare function pruneSnapshots(db: Database.Database, currency: string, keepCount?: number): number;

package/dist/auction/store.js

@@ -0,0 +1,177 @@
+import { existsSync, mkdirSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import Database from "better-sqlite3";
+const CONFIG_DIR = join(homedir(), ".hctl");
+const DB_PATH = join(CONFIG_DIR, "auction.db");
+// Pre-1.0 builds wrote the auction DB under ~/.hetzner-cli. We migrate it once
+// to the new ~/.hctl location so the old directory stops accumulating state.
+const LEGACY_DB_PATH = join(homedir(), ".hetzner-cli", "auction.db");
+function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    }
+}
+export function initSchema(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS snapshots (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      taken_at TEXT NOT NULL DEFAULT (datetime('now')),
+      server_count INTEGER NOT NULL,
+      currency TEXT NOT NULL DEFAULT 'EUR'
+    );
+
+    CREATE TABLE IF NOT EXISTS servers (
+      snapshot_id INTEGER NOT NULL REFERENCES snapshots(id) ON DELETE CASCADE,
+      server_id INTEGER NOT NULL,
+      price REAL NOT NULL,
+      data TEXT NOT NULL,
+      PRIMARY KEY (snapshot_id, server_id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_servers_server_id ON servers(server_id);
+
+    CREATE TABLE IF NOT EXISTS auction_cache (
+      currency TEXT PRIMARY KEY,
+      data TEXT NOT NULL,
+      fetched_at TEXT NOT NULL,
+      source TEXT NOT NULL,
+      stale INTEGER NOT NULL DEFAULT 0,
+      updated_at TEXT,
+      url TEXT NOT NULL
+    );
+  `);
+    db.pragma("foreign_keys = ON");
+}
+export function openDatabase(dbPath) {
+    const path = dbPath ?? resolveDefaultDbPath();
+    ensureDir(dirname(path));
+    const db = new Database(path);
+    db.pragma("journal_mode = WAL");
+    db.pragma("busy_timeout = 5000");
+    initSchema(db);
+    return db;
+}
+function resolveDefaultDbPath() {
+    if (!existsSync(LEGACY_DB_PATH)) {
+        return DB_PATH;
+    }
+    if (existsSync(DB_PATH)) {
+        return DB_PATH;
+    }
+    ensureDir(dirname(DB_PATH));
+    try {
+        renameSync(LEGACY_DB_PATH, DB_PATH);
+    }
+    catch {
+        return LEGACY_DB_PATH;
+    }
+    return DB_PATH;
+}
+export function saveSnapshot(db, servers, currency) {
+    const insertSnapshot = db.prepare("INSERT INTO snapshots (server_count, currency) VALUES (?, ?)");
+    const insertServer = db.prepare("INSERT INTO servers (snapshot_id, server_id, price, data) VALUES (?, ?, ?, ?)");
+    const result = db.transaction(() => {
+        const info = insertSnapshot.run(servers.length, currency);
+        const snapshotId = info.lastInsertRowid;
+        for (const server of servers) {
+            insertServer.run(snapshotId, server.id, server.price, JSON.stringify(server));
+        }
+        return snapshotId;
+    })();
+    const row = db
+        .prepare("SELECT id, taken_at, server_count, currency FROM snapshots WHERE id = ?")
+        .get(result);
+    return {
+        id: row.id,
+        takenAt: row.taken_at,
+        serverCount: row.server_count,
+        currency: row.currency,
+    };
+}
+export function getLatestSnapshot(db, currency) {
+    const row = db
+        .prepare("SELECT id, taken_at, server_count, currency FROM snapshots WHERE currency = ? ORDER BY id DESC LIMIT 1")
+        .get(currency);
+    if (!row) {
+        return null;
+    }
+    return {
+        id: row.id,
+        takenAt: row.taken_at,
+        serverCount: row.server_count,
+        currency: row.currency,
+    };
+}
+export function getSnapshotServers(db, snapshotId) {
+    const rows = db
+        .prepare("SELECT data FROM servers WHERE snapshot_id = ?")
+        .all(snapshotId);
+    return rows.map((row) => parseStoredServer(row.data));
+}
+function parseStoredServer(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new Error(`Stored auction server payload is not valid JSON (schema drift or DB corruption): ${detail}`, { cause: err });
+    }
+}
+export function saveAuctionCache(db, currency, cached) {
+    db.prepare(`INSERT INTO auction_cache
+      (currency, data, fetched_at, source, stale, updated_at, url)
+     VALUES
+      (?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(currency) DO UPDATE SET
+      data = excluded.data,
+      fetched_at = excluded.fetched_at,
+      source = excluded.source,
+      stale = excluded.stale,
+      updated_at = excluded.updated_at,
+      url = excluded.url`).run(currency, JSON.stringify(cached.data), cached.metadata.fetchedAt, cached.metadata.source, cached.metadata.stale ? 1 : 0, cached.metadata.updatedAt ?? null, cached.metadata.url);
+}
+export function getAuctionCache(db, currency) {
+    const row = db
+        .prepare("SELECT data, fetched_at, source, stale, updated_at, url FROM auction_cache WHERE currency = ?")
+        .get(currency);
+    if (row === undefined) {
+        return null;
+    }
+    const updatedAt = row.updated_at ?? row.fetched_at;
+    const updatedTime = Date.parse(updatedAt);
+    const ageSeconds = Number.isNaN(updatedTime)
+        ? undefined
+        : Math.max(0, Math.floor((Date.now() - updatedTime) / 1000));
+    let parsed;
+    try {
+        parsed = JSON.parse(row.data);
+    }
+    catch {
+        return null;
+    }
+    return {
+        data: parsed,
+        metadata: {
+            ageSeconds,
+            fetchedAt: row.fetched_at,
+            source: "local-cache",
+            stale: true,
+            updatedAt,
+            url: row.url,
+        },
+    };
+}
+export function pruneSnapshots(db, currency, keepCount = 50) {
+    const result = db
+        .prepare(`DELETE FROM snapshots
+        WHERE currency = ?
+          AND id NOT IN (
+            SELECT id FROM snapshots
+            WHERE currency = ?
+            ORDER BY id DESC
+            LIMIT ?
+          )`)
+        .run(currency, currency, keepCount);
+    return result.changes;
+}

package/dist/auction/types.d.ts

@@ -0,0 +1,74 @@
+export interface AuctionDiskData {
+    general: number[];
+    hdd: number[];
+    nvme: number[];
+    sata: number[];
+}
+export interface AuctionIpPrice {
+    Amount: number;
+    Hourly: number;
+    Monthly: number;
+}
+export interface AuctionServer {
+    bandwidth: number;
+    cat_id?: number;
+    category?: string;
+    cpu: string;
+    cpu_count: number;
+    datacenter: string;
+    datacenter_hr: string;
+    description: string[];
+    dist: string[];
+    fixed_price: boolean;
+    hdd_arr: string[];
+    hdd_count: number;
+    hdd_hr: string[];
+    hdd_size: number;
+    hourly_price: number;
+    id: number;
+    information: string[] | null;
+    ip_price: AuctionIpPrice;
+    is_ecc: boolean;
+    is_highio: boolean;
+    key: number;
+    name: string;
+    next_reduce: number;
+    next_reduce_hr: boolean;
+    next_reduce_timestamp: number;
+    price: number;
+    ram: string[];
+    ram_size: number;
+    serverDiskData: AuctionDiskData;
+    setup_price: number;
+    specials: string[];
+    traffic: string;
+}
+export interface AuctionFilterOptions {
+    cpu?: string;
+    datacenter?: string;
+    diskType?: "nvme" | "sata" | "hdd";
+    ecc?: boolean;
+    fixedPrice?: boolean;
+    gpu?: boolean;
+    highio?: boolean;
+    inic?: boolean;
+    maxCpuCount?: number;
+    maxDiskCount?: number;
+    maxDiskSize?: number;
+    maxHourlyPrice?: number;
+    maxPrice?: number;
+    maxRam?: number;
+    maxSetupPrice?: number;
+    minBandwidth?: number;
+    minCpuCount?: number;
+    minDiskCount?: number;
+    minDiskSize?: number;
+    minPrice?: number;
+    minRam?: number;
+    specials?: string;
+    text?: string;
+}
+export interface AuctionResponse {
+    server: AuctionServer[];
+    serverCount: number;
+}

package/dist/auction/types.js

@@ -0,0 +1,5 @@
+// ============================================================================
+// Hetzner Auction Types
+// Public API: https://www.hetzner.com/_resources/app/data/app/live_data_sb_EUR.json
+// ============================================================================
+export {};

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command, Option } from "commander";
+import { config } from "dotenv";
+import { registerAuctionCommands } from "./auction/commands.js";
+import { registerCloudCommands } from "./cloud/commands/index.js";
+import { registerRobotCommands } from "./robot/commands/index.js";
+import { registerInitCommand } from "./shared/init.js";
+import { generateReference, } from "./shared/reference.js";
+import { outputSchemas } from "./shared/schemas.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../package.json");
+// `quiet: true` suppresses dotenv 17's "[dotenv@…] injecting env (0) from .env"
+// banner that otherwise lands on stdout for every command. The banner breaks
+// any consumer that pipes `hctl --json …` into jq, since the first line of
+// stdout is no longer parseable JSON.
+config({ quiet: true });
+const program = new Command();
+program
+    .name("hctl")
+    .description("Unified CLI for Hetzner Robot API (dedicated servers), Cloud API, and public server auction.\n\n" +
+    "  Three APIs, one tool:\n" +
+    "    Robot commands   — manage dedicated servers (requires Robot web service credentials)\n" +
+    '    Cloud commands   — manage cloud infrastructure under "hctl cloud ..." (requires Cloud API token)\n' +
+    '    Auction commands — browse server auction under "hctl auction ..." (no auth required)\n\n' +
+    '  Run "hctl reference" for a complete structured reference of all commands and options.\n' +
+    '  Run "hctl <command> --help" for help on a specific command.')
+    .version(version)
+    .option("-u, --user <username>", "Hetzner Robot web service username (or set HETZNER_ROBOT_USER)")
+    .option("-p, --password <password>", 'Hetzner Robot web service password (or set HETZNER_ROBOT_PASSWORD; use "-" to read from stdin)')
+    .option("--json", "Output raw JSON instead of formatted tables")
+    .option("--output-schema", "Print TypeScript type for --json output and exit (no API call)");
+// Top-level setup wizard for first-time users
+registerInitCommand(program);
+// Register all robot commands directly on program (backward compat)
+registerRobotCommands(program);
+// Register cloud commands under 'hctl cloud ...'
+registerCloudCommands(program);
+// Register auction commands (public API, no auth required)
+registerAuctionCommands(program);
+// Built-in reference command (structured docs for LLMs and humans)
+program
+    .command("reference")
+    .alias("ref")
+    .description("Print complete CLI reference (optimized for LLM context)")
+    .addOption(new Option("--section <section>", "Show only a specific section").choices([
+    "robot",
+    "cloud",
+    "auction",
+]))
+    .action((options) => {
+    console.log(generateReference(options.section, { version }));
+});
+program.hook("preAction", (thisCommand, actionCommand) => {
+    if (thisCommand.opts().outputSchema) {
+        const parts = [];
+        let cmd = actionCommand;
+        while (cmd && cmd !== program) {
+            parts.unshift(cmd.name());
+            cmd = cmd.parent;
+        }
+        const path = parts.join(" ");
+        const schema = outputSchemas[path];
+        if (schema) {
+            console.log(schema);
+        }
+        else {
+            console.error(`No output schema for: hctl ${path}`);
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+});
+program.parse();

package/dist/client.d.ts

@@ -0,0 +1,2 @@
+export { type AuctionFetchMetadata, type AuctionFetchOptions, type AuctionFetchResult, type AuctionSource, DEFAULT_AUCTION_CACHE_BASE_URL, fetchAuctionData, fetchAuctionServers, filterAuctionServers, getAuctionDataUrl, sortAuctionServers, } from "./auction/client.js";
+export { HetznerRobotClient } from "./robot/client.js";

package/dist/client.js

@@ -0,0 +1,4 @@
+// Re-export from new location for backward compatibility
+// Auction client (public API, no auth)
+export { DEFAULT_AUCTION_CACHE_BASE_URL, fetchAuctionData, fetchAuctionServers, filterAuctionServers, getAuctionDataUrl, sortAuctionServers, } from "./auction/client.js";
+export { HetznerRobotClient } from "./robot/client.js";

package/dist/cloud/browser-bootstrap.d.ts

@@ -0,0 +1,28 @@
+import { type Options } from "chrome-launcher";
+import type { Page } from "playwright-core";
+export type CloudTokenPermission = "read" | "read-write";
+export interface CloudTokenBootstrapOptions {
+    contextName: string;
+    createProject?: boolean;
+    envFile?: string | boolean;
+    permission: CloudTokenPermission;
+    projectName: string;
+    tokenName?: string;
+    verify?: boolean;
+}
+export declare function normalizePermission(value: string): CloudTokenPermission;
+export declare function upsertEnvValue(content: string, key: string, value: string): string;
+export declare function writeEnvToken(envFile: string, token: string): void;
+export declare function chromeLaunchOptions(startingUrl: string, extraFlags?: string[]): Options;
+export interface ConsoleBrowserSession {
+    attach: () => Promise<Page>;
+    close: () => Promise<void>;
+}
+/**
+ * Open Chrome without any automation attached. The user logs in to an ordinary
+ * browser session; `attach` connects only once they ask hctl to continue.
+ */
+export declare function launchConsoleBrowser(consoleUrl: string, extraFlags?: string[]): Promise<ConsoleBrowserSession>;
+export declare function submitApiTokenForm(page: Page): Promise<void>;
+export declare function automateTokenSetup(page: Page, options: CloudTokenBootstrapOptions, tokenName: string): Promise<void>;
+export declare function runCloudTokenBootstrap(options: CloudTokenBootstrapOptions): Promise<boolean>;