@fredlackey/cli-proxmox 0.0.1

package/src/utils/config.js

@@ -0,0 +1,132 @@
+/**
+ * Single-file config loader.
+ *
+ * Config lives at exactly `~/.config/cli-proxmox/config.json` and nowhere
+ * else. No environment variables, no project-local dotfiles, no ~/.{tool}rc.
+ *
+ * Value resolution precedence for any required input:
+ *   1. command-line flag (passed in opts)
+ *   2. this config file
+ *   3. error
+ *
+ * See `~/Source/Personal/FredLackeySandbox/CLAUDE.md` Rule 2 for the policy.
+ *
+ * Config schema (camelCase):
+ *   - baseUrl     (required, e.g. https://pve.example.com:8006)
+ *   - tokenId     (required, e.g. root@pam!terraform-token)
+ *   - tokenSecret (required, UUID-format secret)
+ *   - defaultNode (optional, PVE node name)
+ *   - verifySsl   (optional, boolean, default false for self-signed certs)
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const CLI_NAME = 'cli-proxmox';
+const CONFIG_DIR = path.join(os.homedir(), '.config', CLI_NAME);
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+export function getConfigPath() {
+  return CONFIG_FILE;
+}
+
+export function getConfigDir() {
+  return CONFIG_DIR;
+}
+
+/**
+ * Load the config file. Returns null if it does not exist or cannot be
+ * parsed. Callers should treat null as "nothing saved yet" and fall through
+ * to command-line flags.
+ */
+export function loadConfig() {
+  try {
+    const raw = fs.readFileSync(CONFIG_FILE, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write the config file atomically. Creates the parent directory if needed.
+ * File mode is 0600 (owner read/write only) since it contains a token secret.
+ */
+export function saveConfig(config) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  const tmp = CONFIG_FILE + '.tmp';
+  fs.writeFileSync(tmp, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+  fs.renameSync(tmp, CONFIG_FILE);
+}
+
+/**
+ * Resolve a required value from command-line flags first, then from the
+ * saved config file. Throws a structured error if missing from both.
+ */
+export function resolveValue(key, opts, config, flagName) {
+  if (opts && opts[key] !== undefined && opts[key] !== null && opts[key] !== '') {
+    return opts[key];
+  }
+  if (config && config[key] !== undefined && config[key] !== null && config[key] !== '') {
+    return config[key];
+  }
+  const err = new Error(
+    `Missing required value: ${flagName || key}. Pass it as a flag or run "proxmox configure".`
+  );
+  err.code = 'missing_required_value';
+  err.detail = { key, flag: flagName };
+  throw err;
+}
+
+/**
+ * Optional value: flag first, config file second, default third. Never
+ * throws.
+ */
+export function resolveOptional(key, opts, config, defaultValue) {
+  if (opts && opts[key] !== undefined && opts[key] !== null && opts[key] !== '') {
+    return opts[key];
+  }
+  if (config && config[key] !== undefined && config[key] !== null && config[key] !== '') {
+    return config[key];
+  }
+  return defaultValue;
+}
+
+/**
+ * Convenience: resolve all five Proxmox credentials/settings in one call.
+ * Used by every command that hits the Proxmox API.
+ *
+ * Returns:
+ *   baseUrl     — required
+ *   tokenId     — required
+ *   tokenSecret — required
+ *   defaultNode — optional (may be undefined)
+ *   verifySsl   — boolean, defaults to false
+ */
+export function resolveCredentials(opts) {
+  const config = loadConfig();
+  return {
+    baseUrl: resolveValue('baseUrl', opts, config, '--base-url'),
+    tokenId: resolveValue('tokenId', opts, config, '--token-id'),
+    tokenSecret: resolveValue('tokenSecret', opts, config, '--token-secret'),
+    defaultNode: resolveOptional('defaultNode', opts, config, undefined),
+    verifySsl: Boolean(resolveOptional('verifySsl', opts, config, false)),
+  };
+}
+
+/**
+ * Resolve a node name from an explicit --node flag, falling back to
+ * the configured defaultNode. Throws a structured error if neither
+ * source supplies a value.
+ */
+export function resolveNode(opts, creds) {
+  if (opts && opts.node) return opts.node;
+  if (creds && creds.defaultNode) return creds.defaultNode;
+  const err = new Error(
+    'No node specified. Pass --node <name> or set a defaultNode in ~/.config/cli-proxmox/config.json.'
+  );
+  err.code = 'missing_required_value';
+  err.detail = { key: 'node', flag: '--node' };
+  throw err;
+}

package/src/utils/errors.js

@@ -0,0 +1,43 @@
+/**
+ * Fatal error emission.
+ *
+ * Called from the top-level parseAsync catch in index.js. A thrown error
+ * from any command action ends up here. In JSON mode we emit a structured
+ * JSON object on stderr so an agent can parse the failure. In interactive
+ * mode we emit a colored message.
+ *
+ * Either way, the process exits 1.
+ *
+ * Errors may carry extra metadata via `err.code` and `err.detail`.
+ * Errors from axios additionally carry `err.response.status` and
+ * `err.response.data` which get unwrapped into `httpStatus` / `httpBody`.
+ */
+
+import chalk from 'chalk';
+import { getRuntime } from './runtime.js';
+
+export function fatalError(err) {
+  const runtime = getRuntime();
+
+  if (runtime.json) {
+    const payload = {
+      error: err?.message || String(err),
+    };
+    if (err?.code) payload.code = err.code;
+    if (err?.detail !== undefined) payload.detail = err.detail;
+    if (err?.response?.status) payload.httpStatus = err.response.status;
+    if (err?.response?.data !== undefined) payload.httpBody = err.response.data;
+    process.stderr.write(JSON.stringify(payload) + '\n');
+  } else {
+    const msg = err?.message || String(err);
+    process.stderr.write(chalk.red('Error: ') + msg + '\n');
+    if (err?.response?.data !== undefined) {
+      const body = typeof err.response.data === 'string'
+        ? err.response.data
+        : JSON.stringify(err.response.data, null, 2);
+      process.stderr.write(chalk.dim(body) + '\n');
+    }
+  }
+
+  process.exit(1);
+}

package/src/utils/output.js

@@ -0,0 +1,140 @@
+/**
+ * Unified output helper.
+ *
+ * `createOutput(runtime)` returns an object with the same API regardless of
+ * mode. In interactive mode, each call prints immediately with chalk
+ * formatting. In JSON mode, calls accumulate into a `_data` object and
+ * `flush()` emits the full object as JSON to stdout.
+ *
+ * Every command should:
+ *   const runtime = getRuntime();
+ *   const out = createOutput(runtime);
+ *   // ... out.heading() / out.info() / out.set() ...
+ *   out.flush();   // must be the last thing the command does
+ *
+ * Output routing:
+ *   - stdout: the result stream. In JSON mode, only the single flush() call
+ *     writes to stdout — everything else either accumulates (info, success,
+ *     set, etc.) or is a no-op (banner, dim, blank).
+ *   - stderr: warnings, failures, and any other diagnostic-flavored output
+ *     when running in interactive mode. In JSON mode, warnings and soft
+ *     failures accumulate into the result payload; truly fatal errors go
+ *     through fatalError() in utils/errors.js, which writes structured JSON
+ *     to stderr.
+ */
+
+import chalk from 'chalk';
+
+const DIVIDER = '\u2500';
+const ANSI_RE = /\u001b\[[0-9;]*m/g;
+
+function stripAnsi(value) {
+  return typeof value === 'string' ? value.replace(ANSI_RE, '') : value;
+}
+
+export function createOutput(runtime) {
+  const _data = {};
+  let _section = null;
+
+  function ensureSection() {
+    if (!_section) _section = '_log';
+    if (!_data[_section] || !Array.isArray(_data[_section])) {
+      _data[_section] = [];
+    }
+  }
+
+  function pushEntry(level, message, detail) {
+    if (!runtime.json) return;
+    ensureSection();
+    const entry = { level, message: stripAnsi(message) };
+    if (detail !== undefined) entry.detail = detail;
+    _data[_section].push(entry);
+  }
+
+  return {
+    /** Cosmetic banner. No-op in JSON mode. */
+    banner(title) {
+      if (!runtime.interactive) return;
+      const line = DIVIDER.repeat(Math.max(4, title.length + 4));
+      console.log('');
+      console.log(chalk.cyan(line));
+      console.log(chalk.cyan(`  ${chalk.bold(title)}`));
+      console.log(chalk.cyan(line));
+      console.log('');
+    },
+
+    /**
+     * Start a new logical section. In JSON mode the section name becomes a
+     * key under which subsequent info/success/warn/fail entries accumulate.
+     */
+    heading(text) {
+      const key = text.toLowerCase().replace(/[^a-z0-9]+/g, '_').replace(/^_|_$/g, '');
+      _section = key || '_log';
+      if (runtime.json) {
+        if (!_data[_section]) _data[_section] = [];
+        return;
+      }
+      console.log('');
+      console.log(chalk.bold.white(`  ${text}`));
+      console.log(chalk.dim(`  ${DIVIDER.repeat(text.length)}`));
+    },
+
+    info(message, detail) {
+      pushEntry('info', message, detail);
+      if (!runtime.interactive) return;
+      console.log(chalk.white(`  ${message}`));
+    },
+
+    success(message, detail) {
+      pushEntry('ok', message, detail);
+      if (!runtime.interactive) return;
+      console.log(chalk.green(`  \u2713 ${message}`));
+    },
+
+    /** Diagnostic-flavored. Goes to stderr in interactive mode. */
+    warn(message, detail) {
+      pushEntry('warn', message, detail);
+      if (!runtime.interactive) return;
+      process.stderr.write(chalk.yellow(`  ! ${message}`) + '\n');
+    },
+
+    /** Non-fatal failure. For fatal errors, throw and let errors.js handle it. */
+    fail(message, detail) {
+      pushEntry('error', message, detail);
+      if (!runtime.interactive) return;
+      process.stderr.write(chalk.red(`  \u2716 ${message}`) + '\n');
+    },
+
+    /** Secondary/faded message. No-op in JSON mode. */
+    dim(message) {
+      if (!runtime.interactive) return;
+      console.log(chalk.dim(`  ${message}`));
+    },
+
+    /** Spacer. No-op in JSON mode. */
+    blank() {
+      if (!runtime.interactive) return;
+      console.log('');
+    },
+
+    /**
+     * Set an arbitrary top-level key in the JSON payload. No-op in
+     * interactive mode — pair with info()/success() calls that the human
+     * will see.
+     */
+    set(key, value) {
+      if (runtime.json) {
+        _data[key] = value;
+      }
+    },
+
+    /**
+     * Emit the accumulated JSON payload to stdout. Must be called at the end
+     * of every command. No-op in interactive mode.
+     */
+    flush() {
+      if (!runtime.json) return;
+      process.stdout.write(JSON.stringify(_data, null, 2) + '\n');
+    },
+  };
+}

package/src/utils/proxmox-client.js

@@ -0,0 +1,127 @@
+/**
+ * Proxmox VE API HTTP client.
+ *
+ * Constructed fresh per command from resolved credentials. Zero module-level
+ * state and zero environment variable access. Each command flow is:
+ *
+ *   const creds = resolveCredentials(opts);
+ *   const client = createProxmoxClient(creds);
+ *   const data = await client.get(`nodes/${node}/qemu`);
+ *
+ * Proxmox quirks handled here:
+ *
+ *   - Authentication uses the `PVEAPIToken={tokenId}={tokenSecret}` header
+ *     format, not Bearer. See `pvesh`/`pveum` docs and the Proxmox REST API
+ *     reference.
+ *
+ *   - TLS is frequently self-signed on PVE installations, so by default we
+ *     pass an https.Agent with `rejectUnauthorized: false`. Callers who have
+ *     a properly signed cert can opt back into verification by setting
+ *     `verifySsl: true` in config (or passing --verify-ssl).
+ *
+ *   - The JSON API root is `/api2/json`. The base URL stored in config is
+ *     the Proxmox host root (e.g. `https://pve.example.com:8006`) so we append
+ *     the API path here.
+ *
+ *   - Proxmox wraps responses in a `{ data: ... }` envelope. The client
+ *     unwraps it automatically and returns the inner value so callers don't
+ *     have to remember.
+ *
+ *   - POST/PUT bodies must be application/x-www-form-urlencoded, not JSON.
+ *     axios handles this when we pass a URLSearchParams instance.
+ */
+
+import axios from 'axios';
+import https from 'node:https';
+
+/**
+ * Create a Proxmox VE client bound to a specific host and token.
+ *
+ * @param {{
+ *   baseUrl: string,
+ *   tokenId: string,
+ *   tokenSecret: string,
+ *   verifySsl?: boolean,
+ *   defaultNode?: string,
+ * }} creds
+ */
+export function createProxmoxClient(creds) {
+  const root = creds.baseUrl.replace(/\/+$/, '');
+  const httpsAgent = new https.Agent({
+    rejectUnauthorized: Boolean(creds.verifySsl),
+  });
+
+  const http = axios.create({
+    baseURL: `${root}/api2/json/`,
+    headers: {
+      Authorization: `PVEAPIToken=${creds.tokenId}=${creds.tokenSecret}`,
+    },
+    httpsAgent,
+    // never fall through to a raw http.Agent; even http:// requests go via
+    // axios defaults but Proxmox is effectively https-only in practice.
+    timeout: 60000,
+  });
+
+  function toFormBody(body) {
+    if (!body || typeof body !== 'object') return undefined;
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(body)) {
+      if (v === undefined || v === null) continue;
+      params.append(k, typeof v === 'boolean' ? (v ? '1' : '0') : String(v));
+    }
+    return params;
+  }
+
+  /** Strip the `{ data: ... }` envelope. */
+  function unwrap(res) {
+    if (res && res.data && Object.prototype.hasOwnProperty.call(res.data, 'data')) {
+      return res.data.data;
+    }
+    return res?.data;
+  }
+
+  return {
+    defaultNode: creds.defaultNode,
+
+    async get(pathname, params) {
+      const res = await http.get(pathname, params ? { params } : undefined);
+      return unwrap(res);
+    },
+
+    async post(pathname, body) {
+      const res = await http.post(pathname, toFormBody(body));
+      return unwrap(res);
+    },
+
+    async put(pathname, body) {
+      const res = await http.put(pathname, toFormBody(body));
+      return unwrap(res);
+    },
+
+    async delete(pathname) {
+      const res = await http.delete(pathname);
+      return unwrap(res);
+    },
+  };
+}
+
+/**
+ * Install the credential option flags on a commander subcommand. Use this
+ * on any command that hits the Proxmox API so the flags stay consistent.
+ */
+export function withCredentialOptions(cmd) {
+  return cmd
+    .option('--base-url <url>', 'Proxmox host root URL (e.g. https://pve.example.com:8006)')
+    .option('--token-id <id>', 'Proxmox API token ID (e.g. root@pam!terraform-token)')
+    .option('--token-secret <secret>', 'Proxmox API token secret (UUID)')
+    .option('--verify-ssl', 'Verify the Proxmox TLS certificate (default: false for self-signed)');
+}
+
+/**
+ * Install the `--node <name>` option on a commander subcommand. Commands
+ * that target a specific PVE node should apply this and then call
+ * `resolveNode()` from config.js to pick the effective value.
+ */
+export function withNodeOption(cmd) {
+  return cmd.option('--node <name>', 'Proxmox node name (falls back to configured defaultNode)');
+}

package/src/utils/readline.js

@@ -0,0 +1,67 @@
+/**
+ * Minimal interactive prompt helpers.
+ *
+ * All of these gracefully return the provided default when stdin is not a
+ * TTY, so an agent invoking the CLI non-interactively will never hang on a
+ * prompt. Prompts themselves are written to stderr so they do not pollute
+ * the stdout result stream.
+ */
+
+import readline from 'node:readline';
+
+let _rl = null;
+
+function getRl() {
+  if (_rl) return _rl;
+  _rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr,
+    terminal: true,
+  });
+  return _rl;
+}
+
+export function closeRl() {
+  if (_rl) {
+    _rl.close();
+    _rl = null;
+  }
+}
+
+/**
+ * Ask a free-form question. Returns the user's answer, or the default if
+ * stdin is not a TTY, or the default if the user just hits enter.
+ */
+export function ask(question, defaultValue = '') {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) {
+      resolve(defaultValue);
+      return;
+    }
+    const suffix = defaultValue ? ` [${defaultValue}]` : '';
+    getRl().question(`${question}${suffix}: `, (answer) => {
+      resolve(answer.trim() || defaultValue);
+    });
+  });
+}
+
+/**
+ * Ask a yes/no question. Returns boolean.
+ */
+export function confirm(question, defaultValue = false) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) {
+      resolve(defaultValue);
+      return;
+    }
+    const suffix = defaultValue ? ' [Y/n]' : ' [y/N]';
+    getRl().question(`${question}${suffix}: `, (answer) => {
+      const trimmed = answer.trim().toLowerCase();
+      if (!trimmed) {
+        resolve(defaultValue);
+        return;
+      }
+      resolve(trimmed === 'y' || trimmed === 'yes');
+    });
+  });
+}

package/src/utils/runtime.js

@@ -0,0 +1,39 @@
+/**
+ * Runtime mode detection.
+ *
+ * Two modes: `interactive` (human at a terminal, pretty output) and `json`
+ * (machine consumer, structured output). Selection rules, first match wins:
+ *
+ *   1. setForceJson(true)         → json mode
+ *   2. setForceInteractive(true)  → interactive mode
+ *   3. stdout.isTTY && stdin.isTTY → interactive mode
+ *   4. otherwise                  → json mode
+ *
+ * Checked fresh on every getRuntime() call. Never cached, because a single
+ * process may emit output in both modes (for example an interactive prompt
+ * during `configure` followed by a flush-to-stdout of the JSON result).
+ */
+
+let _forceJson = false;
+let _forceInteractive = false;
+
+export function setForceJson(value) {
+  _forceJson = Boolean(value);
+}
+
+export function setForceInteractive(value) {
+  _forceInteractive = Boolean(value);
+}
+
+export function getRuntime() {
+  if (_forceJson) {
+    return { interactive: false, json: true };
+  }
+  if (_forceInteractive) {
+    return { interactive: true, json: false };
+  }
+  const stdoutTTY = process.stdout.isTTY === true;
+  const stdinTTY = process.stdin.isTTY === true;
+  const interactive = stdoutTTY && stdinTTY;
+  return { interactive, json: !interactive };
+}