@rollupdate/hctl 0.0.0-stage → 3.1.0

package/dist/shared/config.js

@@ -0,0 +1,289 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { confirm, input, password as passwordPrompt } from "@inquirer/prompts";
+import { config } from "dotenv";
+// `quiet: true` suppresses dotenv 17's "[dotenv@…] injecting env" banner.
+// See src/cli.ts for the full rationale (it breaks JSON-output consumers).
+config({ quiet: true });
+const CONFIG_DIR = join(homedir(), ".hctl");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+const LEGACY_CONFIG_DIR = join(homedir(), ".hetzner-cli");
+const LEGACY_CONFIG_FILE = join(LEGACY_CONFIG_DIR, "config.json");
+const KEYCHAIN_SERVICE = "hctl";
+const LEGACY_KEYCHAIN_SERVICE = "hetzner-cli";
+const KEYCHAIN_ACCOUNT = "robot-api";
+// Lazy-loaded keytar module (optional dependency with native bindings)
+let keytarModule = null;
+let keytarLoadAttempted = false;
+/**
+ * Try to load keytar module (may fail if native deps unavailable)
+ */
+async function getKeytar() {
+    if (keytarLoadAttempted) {
+        return keytarModule;
+    }
+    keytarLoadAttempted = true;
+    try {
+        keytarModule = await import("keytar");
+        return keytarModule;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if system keychain is available
+ */
+export async function hasKeychainSupport() {
+    const keytar = await getKeytar();
+    if (!keytar) {
+        return false;
+    }
+    try {
+        // Try a read operation to verify keychain access
+        await keytar.getPassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get credentials from system keychain
+ */
+export async function getKeychainCredentials() {
+    const keytar = await getKeytar();
+    if (!keytar) {
+        return null;
+    }
+    try {
+        const stored = (await keytar.getPassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT)) ??
+            (await keytar.getPassword(LEGACY_KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT));
+        if (!stored) {
+            return null;
+        }
+        const parsed = JSON.parse(stored);
+        if (parsed.user && parsed.password) {
+            return { user: parsed.user, password: parsed.password };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save credentials to system keychain
+ * @returns true if saved successfully, false otherwise
+ */
+export async function saveToKeychain(user, password) {
+    const keytar = await getKeytar();
+    if (!keytar) {
+        return false;
+    }
+    try {
+        await keytar.setPassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT, JSON.stringify({ user, password }));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Clear credentials from system keychain
+ */
+export async function clearKeychain() {
+    const keytar = await getKeytar();
+    if (!keytar) {
+        return;
+    }
+    try {
+        await keytar.deletePassword(KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+        await keytar.deletePassword(LEGACY_KEYCHAIN_SERVICE, KEYCHAIN_ACCOUNT);
+    }
+    catch {
+        // Ignore errors when clearing
+    }
+}
+/**
+ * Ensure config directory exists
+ */
+function ensureConfigDir() {
+    if (!existsSync(CONFIG_DIR)) {
+        mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    }
+}
+/**
+ * Load configuration from file
+ */
+export function loadConfig() {
+    const file = existsSync(CONFIG_FILE) ? CONFIG_FILE : LEGACY_CONFIG_FILE;
+    if (!existsSync(file)) {
+        return {};
+    }
+    try {
+        const data = readFileSync(file, "utf-8");
+        return JSON.parse(data);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Save configuration to file
+ */
+export function saveConfig(cfg) {
+    ensureConfigDir();
+    writeFileSync(CONFIG_FILE, JSON.stringify(cfg, null, 2), { mode: 0o600 });
+}
+/**
+ * Clear saved configuration from file
+ */
+export function clearConfigFile() {
+    if (existsSync(CONFIG_FILE)) {
+        writeFileSync(CONFIG_FILE, "{}", { mode: 0o600 });
+    }
+}
+/**
+ * Clear saved configuration from all storage locations
+ */
+export async function clearConfig() {
+    await clearKeychain();
+    clearConfigFile();
+}
+/**
+ * Get credentials from environment variables only (sync)
+ */
+export function getCredentialsFromEnv() {
+    const envUser = process.env.HETZNER_ROBOT_USER;
+    const envPassword = process.env.HETZNER_ROBOT_PASSWORD;
+    if (envUser && envPassword) {
+        return { user: envUser, password: envPassword };
+    }
+    return null;
+}
+/**
+ * Get credentials from config file only (sync)
+ */
+export function getCredentialsFromFile() {
+    const cfg = loadConfig();
+    if (cfg.user && cfg.password) {
+        return { user: cfg.user, password: cfg.password };
+    }
+    return null;
+}
+/**
+ * Get credentials from environment variables, keychain, or config file
+ * Priority: env vars → keychain → config file
+ */
+export async function getCredentials() {
+    // First try environment variables
+    const envCreds = getCredentialsFromEnv();
+    if (envCreds) {
+        return { ...envCreds, source: "environment" };
+    }
+    // Then try keychain
+    const keychainCreds = await getKeychainCredentials();
+    if (keychainCreds) {
+        return { ...keychainCreds, source: "keychain" };
+    }
+    // Finally try config file
+    const fileCreds = getCredentialsFromFile();
+    if (fileCreds) {
+        return { ...fileCreds, source: "file" };
+    }
+    return null;
+}
+/**
+ * Check if credentials are configured (sync check - env and file only)
+ */
+export function hasCredentialsSync() {
+    return getCredentialsFromEnv() !== null || getCredentialsFromFile() !== null;
+}
+/**
+ * Check if credentials are configured (async - includes keychain)
+ */
+export async function hasCredentials() {
+    return (await getCredentials()) !== null;
+}
+/**
+ * Interactive login prompt
+ */
+export async function promptLogin() {
+    console.log("");
+    console.log("Hetzner Robot API Authentication");
+    console.log("─".repeat(40));
+    console.log("");
+    console.log("To create Robot web service credentials:");
+    console.log("  1. Open https://robot.hetzner.com");
+    console.log("  2. Top-right menu: Settings > Web service settings");
+    console.log('  3. Click "create access data"');
+    console.log("  4. Choose a username and password");
+    console.log("");
+    console.log("Note: Robot web service credentials are created in the Robot UI, not in the Cloud Console.");
+    console.log("They are separate from your main Hetzner account login.");
+    console.log("");
+    // Check if we should offer migration from file to keychain
+    const keychainAvailable = await hasKeychainSupport();
+    const existingFileCreds = getCredentialsFromFile();
+    if (keychainAvailable && existingFileCreds) {
+        const migrate = await confirm({
+            message: "Migrate existing credentials to secure keychain storage?",
+            default: true,
+        });
+        if (migrate) {
+            const saved = await saveToKeychain(existingFileCreds.user, existingFileCreds.password);
+            if (saved) {
+                clearConfigFile();
+                console.log("");
+                console.log("Credentials migrated to keychain.");
+                return existingFileCreds;
+            }
+        }
+    }
+    const user = await input({
+        message: "Web service username:",
+        validate: (v) => v.length > 0 || "Username is required",
+    });
+    const password = await passwordPrompt({
+        message: "Web service password:",
+        validate: (v) => v.length > 0 || "Password is required",
+    });
+    // Determine storage location based on keychain availability
+    const storageMessage = keychainAvailable
+        ? "Save credentials to secure keychain?"
+        : "Save credentials to ~/.hctl/config.json?";
+    const save = await confirm({
+        message: storageMessage,
+        default: true,
+    });
+    if (save) {
+        let savedToKeychain = false;
+        if (keychainAvailable) {
+            savedToKeychain = await saveToKeychain(user, password);
+        }
+        if (savedToKeychain) {
+            console.log("");
+            console.log("Credentials saved to keychain.");
+        }
+        else {
+            // Fall back to file storage
+            saveConfig({ user, password });
+            console.log("");
+            console.warn("Warning: System keychain unavailable. Credentials stored in plaintext at ~/.hctl/config.json");
+            console.log("Credentials saved to config file.");
+        }
+    }
+    return { user, password };
+}
+/**
+ * Get credentials, prompting if necessary
+ */
+export async function requireCredentials() {
+    const creds = await getCredentials();
+    if (creds) {
+        return { user: creds.user, password: creds.password };
+    }
+    return promptLogin();
+}

package/dist/shared/formatter.d.ts

@@ -0,0 +1,29 @@
+import Table from "cli-table3";
+export declare const colors: {
+    reset: string;
+    bold: string;
+    dim: string;
+    red: string;
+    green: string;
+    yellow: string;
+    blue: string;
+    magenta: string;
+    cyan: string;
+    white: string;
+    gray: string;
+    bgRed: string;
+    bgGreen: string;
+    bgYellow: string;
+};
+export declare function colorize(text: string, color: keyof typeof colors): string;
+export declare function success(message: string): string;
+export declare function error(message: string): string;
+export declare function warning(message: string): string;
+export declare function info(message: string): string;
+export declare function heading(text: string): string;
+export declare function formatStatus(status: string): string;
+export declare function formatBytes(bytes: number): string;
+export declare function formatDate(dateStr: string): string;
+export declare function formatDateTime(dateStr: string): string;
+export declare function createTable(head: string[], colWidths?: number[]): Table.Table;
+export declare function formatJson(data: unknown): string;

package/dist/shared/formatter.js

@@ -0,0 +1,121 @@
+import Table from "cli-table3";
+export const colors = {
+    reset: "\x1b[0m",
+    bold: "\x1b[1m",
+    dim: "\x1b[2m",
+    red: "\x1b[31m",
+    green: "\x1b[32m",
+    yellow: "\x1b[33m",
+    blue: "\x1b[34m",
+    magenta: "\x1b[35m",
+    cyan: "\x1b[36m",
+    white: "\x1b[37m",
+    gray: "\x1b[90m",
+    bgRed: "\x1b[41m",
+    bgGreen: "\x1b[42m",
+    bgYellow: "\x1b[43m",
+};
+export function colorize(text, color) {
+    return `${colors[color]}${text}${colors.reset}`;
+}
+export function success(message) {
+    return `${colors.green}✓${colors.reset} ${message}`;
+}
+export function error(message) {
+    return `${colors.red}✗${colors.reset} ${message}`;
+}
+export function warning(message) {
+    return `${colors.yellow}⚠${colors.reset} ${message}`;
+}
+export function info(message) {
+    return `${colors.blue}ℹ${colors.reset} ${message}`;
+}
+export function heading(text) {
+    return `\n${colors.bold}${colors.cyan}${text}${colors.reset}\n${"─".repeat(text.length)}`;
+}
+export function formatStatus(status) {
+    switch (status.toLowerCase()) {
+        case "ready":
+        case "active":
+        case "enabled":
+        case "success":
+            return colorize(status, "green");
+        case "installing":
+        case "in process":
+        case "running":
+            return colorize(status, "yellow");
+        case "maintenance":
+        case "disabled":
+        case "failed":
+        case "cancelled":
+            return colorize(status, "red");
+        default:
+            return status;
+    }
+}
+export function formatBytes(bytes) {
+    if (bytes === 0) {
+        return "0 B";
+    }
+    const k = 1024;
+    const sizes = ["B", "KB", "MB", "GB", "TB", "PB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${Number.parseFloat((bytes / k ** i).toFixed(2))} ${sizes[i]}`;
+}
+export function formatDate(dateStr) {
+    if (!dateStr) {
+        return "-";
+    }
+    const date = new Date(dateStr);
+    return date.toLocaleDateString("en-US", {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+    });
+}
+export function formatDateTime(dateStr) {
+    if (!dateStr) {
+        return "-";
+    }
+    const date = new Date(dateStr);
+    return date.toLocaleString("en-US", {
+        year: "numeric",
+        month: "short",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+    });
+}
+export function createTable(head, colWidths) {
+    const options = {
+        head: head.map((h) => colorize(h, "cyan")),
+        chars: {
+            top: "─",
+            "top-mid": "┬",
+            "top-left": "┌",
+            "top-right": "┐",
+            bottom: "─",
+            "bottom-mid": "┴",
+            "bottom-left": "└",
+            "bottom-right": "┘",
+            left: "│",
+            "left-mid": "├",
+            mid: "─",
+            "mid-mid": "┼",
+            right: "│",
+            "right-mid": "┤",
+            middle: "│",
+        },
+        style: {
+            "padding-left": 1,
+            "padding-right": 1,
+        },
+    };
+    if (colWidths) {
+        options.colWidths = colWidths;
+    }
+    return new Table(options);
+}
+export function formatJson(data) {
+    return JSON.stringify(data, null, 2);
+}

package/dist/shared/helpers.d.ts

@@ -0,0 +1,39 @@
+import type { OptionValues } from "commander";
+import { HetznerRobotClient } from "../robot/client.js";
+export interface ActionOptions {
+    json?: boolean;
+    password?: string;
+    user?: string;
+    yes?: boolean;
+}
+/**
+ * Handle errors from action wrappers consistently.
+ * Exits with code 0 for user-initiated prompt exits, code 1 for all other errors.
+ */
+export declare function handleActionError(err: unknown): never;
+/**
+ * Split the arguments Commander passes to an action handler, which are
+ * `(...positionals, localOptions, command)`.
+ *
+ * Flags such as --json are declared on ancestor commands, so they are missing
+ * from `localOptions`. The returned `handlerArgs` carry the merged options in
+ * that slot instead.
+ */
+export declare function resolveActionArgs(args: unknown[]): {
+    handlerArgs: unknown[];
+    options: OptionValues;
+};
+export declare function asyncAction<T extends unknown[]>(fn: (client: HetznerRobotClient, ...args: T) => Promise<void>): (...args: [...T, ...unknown[]]) => Promise<void>;
+/**
+ * Output data as JSON or formatted table based on options.
+ */
+export declare function output<T>(data: T, formatter: (data: T) => string, options: {
+    json?: boolean;
+}): void;
+/**
+ * Confirm destructive action unless --yes flag is set.
+ * Returns true if confirmed, false if aborted.
+ */
+export declare function confirmAction(message: string, options: {
+    yes?: boolean;
+}, defaultValue?: boolean): Promise<boolean>;

package/dist/shared/helpers.js

@@ -0,0 +1,86 @@
+import { readFileSync } from "node:fs";
+import { confirm } from "@inquirer/prompts";
+import { HetznerRobotClient } from "../robot/client.js";
+import { requireCredentials } from "./config.js";
+import { error as fmtError, formatJson } from "./formatter.js";
+/**
+ * Handle errors from action wrappers consistently.
+ * Exits with code 0 for user-initiated prompt exits, code 1 for all other errors.
+ */
+export function handleActionError(err) {
+    if (err instanceof Error) {
+        if (err.message.includes("ExitPromptError") ||
+            err.name === "ExitPromptError") {
+            process.exit(0);
+        }
+        console.error(fmtError(err.message));
+    }
+    else {
+        console.error(fmtError("An unknown error occurred"));
+    }
+    process.exit(1);
+}
+/**
+ * Split the arguments Commander passes to an action handler, which are
+ * `(...positionals, localOptions, command)`.
+ *
+ * Flags such as --json are declared on ancestor commands, so they are missing
+ * from `localOptions`. The returned `handlerArgs` carry the merged options in
+ * that slot instead.
+ */
+export function resolveActionArgs(args) {
+    const command = args.at(-1);
+    const options = command.optsWithGlobals();
+    return { handlerArgs: [...args.slice(0, -2), options], options };
+}
+export function asyncAction(fn) {
+    return async (...args) => {
+        const { handlerArgs, options: merged } = resolveActionArgs(args);
+        const options = merged;
+        try {
+            const { user } = options;
+            let password = options.password;
+            if (password === "-") {
+                try {
+                    password = readFileSync(0, "utf-8").trim();
+                }
+                catch {
+                    throw new Error("Failed to read password from stdin");
+                }
+            }
+            let apiClient;
+            if (user && password) {
+                apiClient = new HetznerRobotClient(user, password);
+            }
+            else {
+                const creds = await requireCredentials();
+                apiClient = new HetznerRobotClient(creds.user, creds.password);
+            }
+            await fn(apiClient, ...handlerArgs);
+        }
+        catch (error) {
+            handleActionError(error);
+        }
+    };
+}
+/**
+ * Output data as JSON or formatted table based on options.
+ */
+export function output(data, formatter, options) {
+    console.log(options.json ? formatJson(data) : formatter(data));
+}
+/**
+ * Confirm destructive action unless --yes flag is set.
+ * Returns true if confirmed, false if aborted.
+ */
+export async function confirmAction(message, options, defaultValue = false) {
+    if (options.yes) {
+        return true;
+    }
+    const confirmed = await confirm({ message, default: defaultValue });
+    if (!confirmed) {
+        console.log("Aborted.");
+        return false;
+    }
+    return true;
+}

package/dist/shared/init.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function registerInitCommand(parent: Command): void;

package/dist/shared/init.js

@@ -0,0 +1,107 @@
+import { confirm, input, password as passwordPrompt } from "@inquirer/prompts";
+import { createContext, listContexts } from "../cloud/context.js";
+import { HETZNER_CLOUD_CONSOLE_URL, printCloudTokenInstructions, } from "../cloud/token-instructions.js";
+import { hasCredentials, promptLogin } from "./config.js";
+import { heading, info, success } from "./formatter.js";
+const ROBOT_URL = "https://robot.hetzner.com";
+function printIntro() {
+    console.log("");
+    console.log(heading("hctl setup wizard"));
+    console.log("");
+    console.log("This wizard configures credentials for the two authenticated APIs:");
+    console.log("");
+    console.log(`  Robot API   ${ROBOT_URL}`);
+    console.log("    └─ dedicated server management; uses Robot web service credentials");
+    console.log(`  Cloud API   ${HETZNER_CLOUD_CONSOLE_URL}`);
+    console.log("    └─ cloud infrastructure; uses project-scoped Cloud API tokens");
+    console.log("");
+    console.log(info("Robot and Cloud credentials are created in different Hetzner UIs."));
+    console.log(info("Auction commands need no auth and are skipped by this wizard."));
+}
+async function setupRobot() {
+    if (await hasCredentials()) {
+        console.log("");
+        console.log(success("Robot API: credentials already configured — skipping. Run `hctl auth login` to replace."));
+        return false;
+    }
+    console.log("");
+    const proceed = await confirm({
+        message: "Set up Robot API credentials now?",
+        default: true,
+    });
+    if (!proceed) {
+        return false;
+    }
+    await promptLogin();
+    return true;
+}
+async function setupCloud() {
+    const existing = listContexts().map((c) => c.name);
+    if (existing.length > 0) {
+        console.log("");
+        console.log(success(`Cloud API: ${existing.length} context(s) already configured — skipping. Run \`hctl cloud context create <name>\` to add another.`));
+        return false;
+    }
+    console.log("");
+    const proceed = await confirm({
+        message: "Set up Cloud API token now?",
+        default: true,
+    });
+    if (!proceed) {
+        return false;
+    }
+    printCloudTokenInstructions();
+    const name = await input({
+        message: "Context name (e.g. 'production', 'personal'):",
+        default: "default",
+        validate: (v) => {
+            if (v.length === 0) {
+                return "Context name is required";
+            }
+            if (existing.includes(v)) {
+                return `Context '${v}' already exists. Pick a different name.`;
+            }
+            return true;
+        },
+    });
+    const token = await passwordPrompt({
+        message: `Paste your Cloud API token for '${name}':`,
+        validate: (v) => v.length > 0 || "Token is required",
+    });
+    await createContext(name, token);
+    console.log("");
+    console.log(success(`Context '${name}' created and activated.`));
+    return true;
+}
+function printNextSteps() {
+    console.log("");
+    console.log(heading("Next steps"));
+    console.log("");
+    console.log("  hctl auth status                # verify Robot auth");
+    console.log("  hctl auth test                  # test Robot API call");
+    console.log("  hctl cloud context active       # show active Cloud context");
+    console.log("  hctl cloud server list          # test Cloud API call");
+    console.log("");
+}
+export function registerInitCommand(parent) {
+    parent
+        .command("init")
+        .alias("setup")
+        .description("Walk through API credential setup for Robot and Cloud APIs")
+        .action(async () => {
+        try {
+            printIntro();
+            await setupRobot();
+            await setupCloud();
+            console.log("");
+            console.log(success("Setup complete."));
+            printNextSteps();
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "ExitPromptError") {
+                process.exit(0);
+            }
+            throw err;
+        }
+    });
+}

package/dist/shared/reference.d.ts

@@ -0,0 +1,5 @@
+export type ReferenceSection = "robot" | "cloud" | "auction";
+export interface GenerateReferenceOptions {
+    version?: string;
+}
+export declare function generateReference(section?: ReferenceSection, options?: GenerateReferenceOptions): string;