@rollupdate/hctl 0.0.0-stage → 3.0.0

package/dist/auction/commands.js

@@ -0,0 +1,440 @@
+import { Option } from "commander";
+import { colorize, error, formatJson, info, success, warning, } from "../shared/formatter.js";
+import { fetchAuctionDataWithCache } from "./cache.js";
+import { filterAuctionServers, sortAuctionServers, } from "./client.js";
+import { computeDiff } from "./diff.js";
+import { formatDiff } from "./diff-formatter.js";
+import { formatAuctionDetails, formatAuctionFetchMetadata, formatAuctionList, formatAuctionStatus, } from "./formatter.js";
+import { getAuctionCache, getLatestSnapshot, getSnapshotServers, openDatabase, pruneSnapshots, saveSnapshot, } from "./store.js";
+function resolveFixedPrice(fixedPrice, auctionOnly) {
+    if (fixedPrice) {
+        return true;
+    }
+    if (auctionOnly) {
+        return false;
+    }
+    return undefined;
+}
+function parseNum(val) {
+    if (val === undefined) {
+        return undefined;
+    }
+    const n = Number(val);
+    return Number.isNaN(n) ? undefined : n;
+}
+function buildFilters(options) {
+    return {
+        minPrice: parseNum(options.minPrice),
+        maxPrice: parseNum(options.maxPrice),
+        maxHourlyPrice: parseNum(options.maxHourlyPrice),
+        minRam: parseNum(options.minRam),
+        maxRam: parseNum(options.maxRam),
+        cpu: options.cpu,
+        datacenter: options.datacenter,
+        minDiskSize: parseNum(options.minDiskSize),
+        maxDiskSize: parseNum(options.maxDiskSize),
+        minDiskCount: parseNum(options.minDiskCount),
+        maxDiskCount: parseNum(options.maxDiskCount),
+        diskType: options.diskType,
+        minBandwidth: parseNum(options.minBandwidth),
+        ecc: options.ecc ? true : undefined,
+        gpu: options.gpu ? true : undefined,
+        inic: options.inic ? true : undefined,
+        highio: options.highio ? true : undefined,
+        specials: options.specials,
+        fixedPrice: resolveFixedPrice(options.fixedPrice, options.auctionOnly),
+        maxSetupPrice: options.noSetupFee ? 0 : parseNum(options.maxSetupPrice),
+        minCpuCount: parseNum(options.minCpuCount),
+        maxCpuCount: parseNum(options.maxCpuCount),
+        text: options.search,
+    };
+}
+function buildFetchOptions(options) {
+    return options.direct ? { source: "direct" } : {};
+}
+/** Status messages stay off stdout in JSON mode so it remains parseable. */
+function statusLog(options) {
+    return options.json ? console.error : console.log;
+}
+function maybeWarnAboutLocalCache(metadata, options) {
+    if (options.json && metadata.source === "local-cache") {
+        console.error(warning(formatAuctionFetchMetadata(metadata)));
+    }
+}
+function toCacheStatus(result) {
+    return {
+        ageSeconds: result.metadata.ageSeconds,
+        fetchedAt: result.metadata.fetchedAt,
+        serverCount: result.data.serverCount ?? result.data.server.length,
+        source: result.metadata.source,
+        stale: result.metadata.stale ?? false,
+        updatedAt: result.metadata.updatedAt,
+        url: result.metadata.url,
+    };
+}
+function readLocalAuctionCacheStatus(currency) {
+    let db = null;
+    try {
+        db = openDatabase();
+        const cached = getAuctionCache(db, currency);
+        return cached === null ? null : toCacheStatus(cached);
+    }
+    catch {
+        return null;
+    }
+    finally {
+        db?.close();
+    }
+}
+async function getAuctionStatusSummary(currency, options) {
+    const result = await fetchAuctionDataWithCache(currency, {
+        ...buildFetchOptions(options),
+        allowLocalFallback: true,
+    });
+    const current = toCacheStatus(result);
+    return {
+        ...current,
+        currency,
+        endpointUrl: result.metadata.url,
+        localCache: readLocalAuctionCacheStatus(currency),
+        usingLocalFallback: result.metadata.source === "local-cache",
+    };
+}
+const EMPTY_PAYLOAD_RATIO = 0.5;
+function isSuspiciousEmptyPayload(servers, previous) {
+    if (servers.length === 0) {
+        return true;
+    }
+    if (previous && previous.serverCount > 0) {
+        return servers.length < previous.serverCount * EMPTY_PAYLOAD_RATIO;
+    }
+    return false;
+}
+function fetchAndDiff(db, servers, currency, options) {
+    const previous = getLatestSnapshot(db, currency);
+    if (!previous) {
+        if (isSuspiciousEmptyPayload(servers, null)) {
+            console.error(warning("Skipping initial snapshot: upstream returned no servers"));
+            return null;
+        }
+        const snapshot = saveSnapshot(db, servers, currency);
+        statusLog(options)(success(`Initial snapshot saved (${snapshot.serverCount} servers, snapshot #${snapshot.id})`));
+        return null;
+    }
+    if (isSuspiciousEmptyPayload(servers, previous)) {
+        console.error(warning(`Skipping snapshot: upstream returned ${servers.length} server(s) (was ${previous.serverCount}). Refusing to overwrite baseline with suspicious payload.`));
+        return null;
+    }
+    const previousServers = getSnapshotServers(db, previous.id);
+    const diff = computeDiff(previousServers, servers);
+    const hasChanges = diff.added.length > 0 ||
+        diff.removed.length > 0 ||
+        diff.priceChanged.length > 0;
+    if (!hasChanges) {
+        return { previous, current: previous, diff };
+    }
+    const current = saveSnapshot(db, servers, currency);
+    pruneSnapshots(db, currency);
+    return { previous, current, diff };
+}
+async function pollOnce(db, currency, options) {
+    const { data: { server: servers }, metadata, } = await fetchAuctionDataWithCache(currency, {
+        allowLocalFallback: false,
+        source: options.source,
+    });
+    const result = fetchAndDiff(db, servers, currency, options);
+    if (!result) {
+        return;
+    }
+    const { diff, previous: prev, current: curr } = result;
+    const hasChanges = diff.added.length > 0 ||
+        diff.removed.length > 0 ||
+        diff.priceChanged.length > 0;
+    if (options.quiet && !hasChanges) {
+        return;
+    }
+    if (options.json) {
+        console.log(formatJson({ timestamp: curr.takenAt, ...diff }));
+    }
+    else {
+        const ts = colorize(`[${new Date().toLocaleTimeString()}]`, "dim");
+        console.log(`${ts} ${formatAuctionFetchMetadata(metadata)}\n${formatDiff(diff, prev, curr)}`);
+    }
+}
+function auctionAction(fn) {
+    return async () => {
+        try {
+            await fn();
+        }
+        catch (err) {
+            console.error(error(err instanceof Error ? err.message : "Failed to fetch auction data"));
+            process.exit(1);
+        }
+    };
+}
+export function registerAuctionCommands(parent) {
+    const auction = parent
+        .command("auction")
+        .description("Server auction monitoring (public, no auth required).\n" +
+        "Fetches the current public auction inventory from the hosted auction cache by default and filters/sorts client-side.\n" +
+        "Typical ranges: 30-450 EUR/mo, 32-1024 GB RAM, NVMe/SATA/HDD, datacenters in FSN/HEL/NBG.");
+    // The root command also declares --json and consumes the flag wherever it
+    // appears, so copy it onto the subcommand that is about to run.
+    auction.hook("preAction", (_auction, actionCommand) => {
+        if (actionCommand.optsWithGlobals().json) {
+            actionCommand.setOptionValue("json", true);
+        }
+    });
+    auction
+        .command("list")
+        .alias("ls")
+        .description("List and filter auction servers.\n" +
+        "All filters are optional and combinable. String filters (cpu, datacenter, specials, search) are case-insensitive substrings.\n" +
+        "Examples:\n" +
+        "  hctl auction list --cpu epyc --ecc --disk-type nvme --datacenter HEL --sort price\n" +
+        "  hctl auction list --gpu --max-price 150 --json\n" +
+        "  hctl auction list --auction-only --sort next_reduce --limit 20")
+        .option("--min-price <n>", "Minimum monthly price")
+        .option("--max-price <n>", "Maximum monthly price")
+        .option("--max-hourly-price <n>", "Maximum hourly price")
+        .option("--min-ram <gb>", "Minimum RAM in GB")
+        .option("--max-ram <gb>", "Maximum RAM in GB")
+        .option("--cpu <text>", 'CPU model substring (e.g. "Ryzen", "i7-6700")')
+        .option("--min-cpu-count <n>", "Minimum CPU/socket count")
+        .option("--max-cpu-count <n>", "Maximum CPU/socket count")
+        .option("--datacenter <text>", 'Datacenter substring (e.g. "FSN", "HEL1-DC2")')
+        .option("--min-disk-size <gb>", "Minimum total disk capacity in GB")
+        .option("--max-disk-size <gb>", "Maximum total disk capacity in GB")
+        .option("--min-disk-count <n>", "Minimum number of drives")
+        .option("--max-disk-count <n>", "Maximum number of drives")
+        .addOption(new Option("--disk-type <type>", "Filter by disk type present").choices([
+        "nvme",
+        "sata",
+        "hdd",
+    ]))
+        .option("--min-bandwidth <mbit>", "Minimum bandwidth in Mbit/s")
+        .option("--ecc", "Only ECC RAM servers")
+        .option("--gpu", "Only GPU servers")
+        .option("--inic", "Only servers with Intel NIC")
+        .option("--highio", "Only high I/O servers")
+        .option("--specials <text>", "Filter by special feature (substring match)")
+        .option("--fixed-price", "Only fixed-price servers")
+        .option("--auction-only", "Only auction (non-fixed) servers")
+        .option("--no-setup-fee", "Only servers with no setup fee")
+        .option("--max-setup-price <n>", "Maximum setup price")
+        .option("--search <text>", "Free-text search across description")
+        .addOption(new Option("--currency <currency>", "Price currency")
+        .choices(["EUR", "USD"])
+        .default("EUR"))
+        .option("--direct", "Fetch directly from Hetzner instead of the hosted auction cache")
+        .addOption(new Option("--sort <field>", "Sort by field")
+        .choices([
+        "price",
+        "hourly",
+        "setup",
+        "ram",
+        "disk",
+        "disk_count",
+        "cpu",
+        "cpu_count",
+        "datacenter",
+        "bandwidth",
+        "next_reduce",
+    ])
+        .default("price"))
+        .option("--desc", "Sort in descending order")
+        .option("--limit <n>", "Limit output rows")
+        .option("--json", "Output raw JSON")
+        .action((options) => auctionAction(async () => {
+        const { data: { server: servers }, metadata, } = await fetchAuctionDataWithCache(options.currency, {
+            ...buildFetchOptions(options),
+            allowLocalFallback: true,
+        });
+        const filters = buildFilters(options);
+        let filtered = filterAuctionServers(servers, filters);
+        filtered = sortAuctionServers(filtered, options.sort || "price", !!options.desc);
+        const limit = parseNum(options.limit);
+        if (limit !== undefined && limit > 0) {
+            filtered = filtered.slice(0, limit);
+        }
+        if (options.json) {
+            maybeWarnAboutLocalCache(metadata, options);
+            console.log(formatJson(filtered));
+        }
+        else {
+            console.log(`${formatAuctionFetchMetadata(metadata)}\n${formatAuctionList(filtered)}`);
+        }
+    })());
+    auction
+        .command("show <id>")
+        .description("Show detailed info for an auction server.\n" +
+        "Displays CPU, RAM, disk breakdown by type, datacenter, pricing (monthly + hourly),\n" +
+        "specials (GPU, iNIC, ECC), IP pricing, and full description.\n" +
+        "Example: hctl auction show 2919866")
+        .addOption(new Option("--currency <currency>", "Price currency")
+        .choices(["EUR", "USD"])
+        .default("EUR"))
+        .option("--direct", "Fetch directly from Hetzner instead of the hosted auction cache")
+        .option("--json", "Output raw JSON")
+        .action((id, options) => auctionAction(async () => {
+        const serverId = Number.parseInt(id, 10);
+        if (Number.isNaN(serverId)) {
+            console.error(error("Invalid server ID"));
+            process.exit(1);
+        }
+        const { data: { server: servers }, metadata, } = await fetchAuctionDataWithCache(options.currency, {
+            ...buildFetchOptions(options),
+            allowLocalFallback: true,
+        });
+        const server = servers.find((s) => s.id === serverId);
+        if (!server) {
+            console.error(error(`Auction server ${id} not found`));
+            process.exit(1);
+        }
+        if (options.json) {
+            maybeWarnAboutLocalCache(metadata, options);
+            console.log(formatJson(server));
+        }
+        else {
+            console.log(`${formatAuctionFetchMetadata(metadata)}\n${formatAuctionDetails(server)}`);
+        }
+    })());
+    auction
+        .command("status")
+        .description("Show auction data freshness and cache status.\n" +
+        "Reports hosted cache source, update timestamp, age, stale flag, server count,\n" +
+        "and local offline cache state. Use --json for machine-readable output.")
+        .addOption(new Option("--currency <currency>", "Price currency")
+        .choices(["EUR", "USD"])
+        .default("EUR"))
+        .option("--direct", "Check Hetzner direct instead of the hosted auction cache")
+        .option("--json", "Output status as JSON")
+        .action((options) => auctionAction(async () => {
+        const status = await getAuctionStatusSummary(options.currency, options);
+        if (options.json) {
+            console.log(formatJson(status));
+        }
+        else {
+            console.log(formatAuctionStatus(status));
+        }
+    })());
+    auction
+        .command("diff")
+        .description("Show changes since last snapshot.\n" +
+        "Fetches current auction data, compares against the most recent stored snapshot,\n" +
+        "and shows added, removed, and price-changed servers.\n" +
+        "Example: hctl auction diff")
+        .addOption(new Option("--currency <currency>", "Price currency")
+        .choices(["EUR", "USD"])
+        .default("EUR"))
+        .option("--direct", "Fetch directly from Hetzner instead of the hosted auction cache")
+        .option("--json", "Output diff as JSON")
+        .action((options) => auctionAction(async () => {
+        const currency = options.currency;
+        const db = openDatabase();
+        try {
+            const { data: { server: servers }, metadata, } = await fetchAuctionDataWithCache(currency, {
+                ...buildFetchOptions(options),
+                allowLocalFallback: false,
+            });
+            if (!options.json) {
+                console.log(formatAuctionFetchMetadata(metadata));
+            }
+            const result = fetchAndDiff(db, servers, currency, options);
+            if (!result) {
+                return;
+            }
+            if (options.json) {
+                console.log(formatJson(result.diff));
+            }
+            else {
+                console.log(formatDiff(result.diff, result.previous, result.current));
+            }
+        }
+        finally {
+            db.close();
+        }
+    })());
+    auction
+        .command("watch")
+        .description("Continuously monitor auction changes.\n" +
+        "Polls the auction API at a configurable interval and prints changes as they occur.\n" +
+        "Press Ctrl+C to stop.\n" +
+        "Example: hctl auction watch --interval 10")
+        .option("--interval <minutes>", "Polling interval in minutes", "5")
+        .addOption(new Option("--currency <currency>", "Price currency")
+        .choices(["EUR", "USD"])
+        .default("EUR"))
+        .option("--direct", "Fetch directly from Hetzner instead of the hosted auction cache")
+        .option("--json", "Output diffs as JSON")
+        .option("--quiet", "Only show output when changes are detected")
+        .action((options) => auctionAction(async () => {
+        const currency = options.currency;
+        const intervalMin = parseWatchInterval(options.interval);
+        const intervalMs = intervalMin * 60 * 1000;
+        const db = openDatabase();
+        const fetchOptions = buildFetchOptions(options);
+        let shuttingDown = false;
+        let timer = null;
+        let drainTimer = null;
+        const requestShutdown = () => {
+            if (shuttingDown) {
+                return;
+            }
+            shuttingDown = true;
+            if (timer) {
+                clearTimeout(timer);
+                timer = null;
+            }
+            drainTimer = setTimeout(() => {
+                console.error(warning(`Drain timeout (${SHUTDOWN_DRAIN_MS / 1000}s) reached; forcing exit.`));
+                db.close();
+                process.exit(0);
+            }, SHUTDOWN_DRAIN_MS);
+            drainTimer.unref?.();
+        };
+        process.once("SIGINT", requestShutdown);
+        process.once("SIGTERM", requestShutdown);
+        statusLog(options)(info(`Watching auction (${currency}, every ${intervalMin}min). Press Ctrl+C to stop.`));
+        const poll = () => pollOnce(db, currency, {
+            ...options,
+            source: fetchOptions.source,
+        }).catch((err) => {
+            console.error(error(err instanceof Error ? err.message : "Poll failed"));
+        });
+        try {
+            while (!shuttingDown) {
+                await poll();
+                if (shuttingDown) {
+                    break;
+                }
+                await new Promise((resolve) => {
+                    timer = setTimeout(() => {
+                        timer = null;
+                        resolve();
+                    }, intervalMs);
+                });
+            }
+        }
+        finally {
+            if (drainTimer) {
+                clearTimeout(drainTimer);
+            }
+            process.removeListener("SIGINT", requestShutdown);
+            process.removeListener("SIGTERM", requestShutdown);
+            db.close();
+        }
+    })());
+}
+const SHUTDOWN_DRAIN_MS = 30_000;
+const MAX_WATCH_INTERVAL_MIN = 24 * 60;
+function parseWatchInterval(raw) {
+    if (raw === undefined) {
+        return 5;
+    }
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n < 1 || n > MAX_WATCH_INTERVAL_MIN) {
+        throw new Error(`Invalid --interval "${raw}": expected a number between 1 and ${MAX_WATCH_INTERVAL_MIN} (minutes).`);
+    }
+    return n;
+}

package/dist/auction/diff-formatter.d.ts

@@ -0,0 +1,3 @@
+import type { DiffResult } from "./diff.js";
+import type { StoredSnapshot } from "./store.js";
+export declare function formatDiff(diff: DiffResult, previous: StoredSnapshot, current: StoredSnapshot): string;

package/dist/auction/diff-formatter.js

@@ -0,0 +1,61 @@
+import { colorize, createTable, info } from "../shared/formatter.js";
+function serverRow(s) {
+    return [
+        s.id.toString(),
+        s.cpu,
+        `${s.ram_size} GB${s.is_ecc ? " ECC" : ""}`,
+        s.datacenter,
+        `€${s.price.toFixed(2)}`,
+    ];
+}
+function formatPriceChange(change) {
+    const s = change.server;
+    const delta = s.price - change.previousPrice;
+    const sign = delta > 0 ? "+" : "";
+    const deltaStr = `${sign}${delta.toFixed(2)}`;
+    const colored = delta < 0 ? colorize(deltaStr, "green") : colorize(deltaStr, "red");
+    return [
+        s.id.toString(),
+        s.cpu,
+        `${s.ram_size} GB${s.is_ecc ? " ECC" : ""}`,
+        s.datacenter,
+        `€${change.previousPrice.toFixed(2)} → €${s.price.toFixed(2)} (${colored})`,
+    ];
+}
+export function formatDiff(diff, previous, current) {
+    const totalChanges = diff.added.length + diff.removed.length + diff.priceChanged.length;
+    if (totalChanges === 0) {
+        return info(`No changes detected (${current.serverCount} servers, snapshot #${current.id})`);
+    }
+    const lines = [];
+    lines.push(colorize(`Auction diff: snapshot #${previous.id} → #${current.id}`, "bold"));
+    lines.push(colorize(`  ${previous.serverCount} → ${current.serverCount} servers | ${diff.added.length} added, ${diff.removed.length} removed, ${diff.priceChanged.length} price changes`, "dim"));
+    lines.push("");
+    if (diff.added.length > 0) {
+        lines.push(colorize(`+ ${diff.added.length} new server(s)`, "green"));
+        const table = createTable(["ID", "CPU", "RAM", "DC", "Price"]);
+        for (const s of diff.added) {
+            table.push(serverRow(s));
+        }
+        lines.push(table.toString());
+        lines.push("");
+    }
+    if (diff.removed.length > 0) {
+        lines.push(colorize(`- ${diff.removed.length} removed server(s)`, "red"));
+        const table = createTable(["ID", "CPU", "RAM", "DC", "Price"]);
+        for (const s of diff.removed) {
+            table.push(serverRow(s));
+        }
+        lines.push(table.toString());
+        lines.push("");
+    }
+    if (diff.priceChanged.length > 0) {
+        lines.push(colorize(`~ ${diff.priceChanged.length} price change(s)`, "yellow"));
+        const table = createTable(["ID", "CPU", "RAM", "DC", "Price Change"]);
+        for (const change of diff.priceChanged) {
+            table.push(formatPriceChange(change));
+        }
+        lines.push(table.toString());
+    }
+    return lines.join("\n");
+}

package/dist/auction/diff.d.ts

@@ -0,0 +1,11 @@
+import type { AuctionServer } from "./types.js";
+export interface DiffResult {
+    added: AuctionServer[];
+    priceChanged: PriceChange[];
+    removed: AuctionServer[];
+}
+export interface PriceChange {
+    previousPrice: number;
+    server: AuctionServer;
+}
+export declare function computeDiff(previous: AuctionServer[], current: AuctionServer[]): DiffResult;

package/dist/auction/diff.js

@@ -0,0 +1,28 @@
+export function computeDiff(previous, current) {
+    const prevMap = new Map();
+    for (const s of previous) {
+        prevMap.set(s.id, s);
+    }
+    const currMap = new Map();
+    for (const s of current) {
+        currMap.set(s.id, s);
+    }
+    const added = [];
+    const priceChanged = [];
+    for (const server of current) {
+        const prev = prevMap.get(server.id);
+        if (!prev) {
+            added.push(server);
+        }
+        else if (prev.price !== server.price) {
+            priceChanged.push({ server, previousPrice: prev.price });
+        }
+    }
+    const removed = [];
+    for (const server of previous) {
+        if (!currMap.has(server.id)) {
+            removed.push(server);
+        }
+    }
+    return { added, removed, priceChanged };
+}

package/dist/auction/formatter.d.ts

@@ -0,0 +1,21 @@
+import type { AuctionFetchMetadata } from "./client.js";
+import type { AuctionServer } from "./types.js";
+export interface AuctionCacheStatus {
+    ageSeconds?: number;
+    fetchedAt: string;
+    serverCount: number;
+    source: string;
+    stale: boolean;
+    updatedAt?: string;
+    url: string;
+}
+export interface AuctionStatusSummary extends AuctionCacheStatus {
+    currency: "EUR" | "USD";
+    endpointUrl: string;
+    localCache: AuctionCacheStatus | null;
+    usingLocalFallback: boolean;
+}
+export declare function formatAuctionFetchMetadata(metadata: AuctionFetchMetadata): string;
+export declare function formatAuctionStatus(status: AuctionStatusSummary): string;
+export declare function formatAuctionList(servers: AuctionServer[]): string;
+export declare function formatAuctionDetails(server: AuctionServer): string;