kiwivm-cli 0.1.0

package/src/index.test.ts

@@ -0,0 +1,375 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// All mock variables must be created inside vi.hoisted() so they are
+// initialized before the hoisted vi.mock() factories reference them.
+const {
+  mockPowerRun,
+  mockInfoRun,
+  mockSnapshotRun,
+  mockBackupRun,
+  mockSystemRun,
+  mockNetworkRun,
+  mockMonitoringRun,
+  mockAdminRun,
+  mockClientConstructor,
+} = vi.hoisted(() => ({
+  mockPowerRun: vi.fn(),
+  mockInfoRun: vi.fn(),
+  mockSnapshotRun: vi.fn(),
+  mockBackupRun: vi.fn(),
+  mockSystemRun: vi.fn(),
+  mockNetworkRun: vi.fn(),
+  mockMonitoringRun: vi.fn(),
+  mockAdminRun: vi.fn(),
+  mockClientConstructor: vi.fn(),
+}));
+
+vi.mock("./commands/power.ts", () => ({ run: mockPowerRun }));
+vi.mock("./commands/info.ts", () => ({ run: mockInfoRun }));
+vi.mock("./commands/snapshot.ts", () => ({ run: mockSnapshotRun }));
+vi.mock("./commands/backup.ts", () => ({ run: mockBackupRun }));
+vi.mock("./commands/system.ts", () => ({ run: mockSystemRun }));
+vi.mock("./commands/network.ts", () => ({ run: mockNetworkRun }));
+vi.mock("./commands/monitoring.ts", () => ({ run: mockMonitoringRun }));
+vi.mock("./commands/admin.ts", () => ({ run: mockAdminRun }));
+vi.mock("./client.ts", () => ({
+  KiwiVMClient: mockClientConstructor,
+}));
+
+import { main } from "./index.ts";
+
+function setArgv(...args: string[]) {
+  // argv[0] is node, argv[1] is script path, the rest are user args
+  vi.stubGlobal("process", {
+    ...process,
+    argv: ["/usr/bin/node", "/usr/bin/kiwivm-cli", ...args],
+    exit: vi.fn() as unknown as typeof process.exit,
+  });
+}
+
+describe("CLI dispatcher", () => {
+  afterEach(() => {
+    vi.clearAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  // ---- Dispatch to correct command handler ----
+
+  it("dispatches 'power start' to power.run", async () => {
+    setArgv("power", "start");
+    mockPowerRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockPowerRun).toHaveBeenCalledExactlyOnceWith(
+      "start",
+      {},
+      expect.anything(),
+    );
+  });
+
+  it("dispatches 'info live' to info.run", async () => {
+    setArgv("info", "live");
+    mockInfoRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockInfoRun).toHaveBeenCalledExactlyOnceWith(
+      "live",
+      {},
+      expect.anything(),
+    );
+  });
+
+  it("dispatches 'snapshot list' to snapshot.run", async () => {
+    setArgv("snapshot", "list");
+    mockSnapshotRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockSnapshotRun).toHaveBeenCalledExactlyOnceWith(
+      "list",
+      {},
+      expect.anything(),
+    );
+  });
+
+  it("dispatches 'backup list' to backup.run", async () => {
+    setArgv("backup", "list");
+    mockBackupRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockBackupRun).toHaveBeenCalledExactlyOnceWith(
+      "list",
+      {},
+      expect.anything(),
+    );
+  });
+
+  it("dispatches 'system password' to system.run", async () => {
+    setArgv("system", "password");
+    mockSystemRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockSystemRun).toHaveBeenCalledExactlyOnceWith(
+      "password",
+      {},
+      expect.anything(),
+    );
+  });
+
+  it("dispatches 'network ipv6-add' to network.run", async () => {
+    setArgv("network", "ipv6-add");
+    mockNetworkRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockNetworkRun).toHaveBeenCalledExactlyOnceWith(
+      "ipv6-add",
+      {},
+      expect.anything(),
+    );
+  });
+
+  it("dispatches 'monitoring audit' to monitoring.run", async () => {
+    setArgv("monitoring", "audit");
+    mockMonitoringRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockMonitoringRun).toHaveBeenCalledExactlyOnceWith(
+      "audit",
+      {},
+      expect.anything(),
+    );
+  });
+
+  it("dispatches 'admin suspensions' to admin.run", async () => {
+    setArgv("admin", "suspensions");
+    mockAdminRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockAdminRun).toHaveBeenCalledExactlyOnceWith(
+      "suspensions",
+      {},
+      expect.anything(),
+    );
+  });
+
+  // ---- Flag parsing ----
+
+  it("parses --key=value flags and passes them to the handler", async () => {
+    setArgv("system", "hostname", "--newHostname=my-vps.example.com");
+    mockSystemRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockSystemRun).toHaveBeenCalledExactlyOnceWith(
+      "hostname",
+      { newHostname: "my-vps.example.com" },
+      expect.anything(),
+    );
+  });
+
+  it("parses multiple --key=value flags", async () => {
+    setArgv("snapshot", "sticky", "--snapshot=snap1", "--sticky=1");
+    mockSnapshotRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockSnapshotRun).toHaveBeenCalledExactlyOnceWith(
+      "sticky",
+      { snapshot: "snap1", sticky: "1" },
+      expect.anything(),
+    );
+  });
+
+  it("ignores unknown positional args beyond category and action", async () => {
+    setArgv("power", "start", "extra-arg");
+    mockPowerRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockPowerRun).toHaveBeenCalledExactlyOnceWith(
+      "start",
+      {},
+      expect.anything(),
+    );
+  });
+
+  it("passes an empty flags object when no flags are provided", async () => {
+    setArgv("monitoring", "rate-limit");
+    mockMonitoringRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockMonitoringRun).toHaveBeenCalledExactlyOnceWith(
+      "rate-limit",
+      {},
+      expect.anything(),
+    );
+  });
+
+  // ---- Auth: --veid and --api-key flags ----
+
+  it("creates KiwiVMClient with --veid and --api-key flag values", async () => {
+    setArgv("power", "start", "--veid=12345", "--api-key=secret");
+    mockPowerRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockClientConstructor).toHaveBeenCalledExactlyOnceWith({
+      veid: "12345",
+      apiKey: "secret",
+    });
+  });
+
+  it("strips --veid and --api-key from flags passed to handler", async () => {
+    setArgv(
+      "power",
+      "start",
+      "--veid=12345",
+      "--api-key=secret",
+      "--other=value",
+    );
+    mockPowerRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockPowerRun).toHaveBeenCalledExactlyOnceWith(
+      "start",
+      { other: "value" },
+      expect.anything(),
+    );
+  });
+
+  // ---- Auth: environment variable fallback ----
+
+  it("creates KiwiVMClient from KIWIVM_VEID and KIWIVM_API_KEY env vars", async () => {
+    setArgv("power", "start");
+    vi.stubEnv("KIWIVM_VEID", "env-veid");
+    vi.stubEnv("KIWIVM_API_KEY", "env-key");
+    mockPowerRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockClientConstructor).toHaveBeenCalledExactlyOnceWith({
+      veid: "env-veid",
+      apiKey: "env-key",
+    });
+  });
+
+  it("prefers --veid and --api-key flags over env vars", async () => {
+    setArgv("power", "start", "--veid=flag-veid", "--api-key=flag-key");
+    vi.stubEnv("KIWIVM_VEID", "env-veid");
+    vi.stubEnv("KIWIVM_API_KEY", "env-key");
+    mockPowerRun.mockResolvedValueOnce({ error: 0 });
+
+    await main();
+
+    expect(mockClientConstructor).toHaveBeenCalledExactlyOnceWith({
+      veid: "flag-veid",
+      apiKey: "flag-key",
+    });
+  });
+
+  // ---- Output: JSON to stdout ----
+
+  it("writes JSON result to stdout", async () => {
+    setArgv("power", "start");
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    mockPowerRun.mockResolvedValueOnce({ error: 0, message: "Started" });
+
+    await main();
+
+    expect(consoleSpy).toHaveBeenCalledExactlyOnceWith(
+      JSON.stringify({ error: 0, message: "Started" }),
+    );
+    consoleSpy.mockRestore();
+  });
+
+  it("writes pretty-printed JSON to stdout", async () => {
+    setArgv("power", "start");
+    const consoleSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const result = {
+      error: 0,
+      data: { key: "value", nested: { deep: true } },
+    };
+    mockPowerRun.mockResolvedValueOnce(result);
+
+    await main();
+
+    const logged = consoleSpy.mock.calls[0]?.[0] as string;
+    expect(() => JSON.parse(logged)).not.toThrow();
+    expect(JSON.parse(logged)).toEqual(result);
+    consoleSpy.mockRestore();
+  });
+
+  // ---- Error handling: stderr + exit code 1 ----
+
+  it("writes errors to stderr and exits with code 1", async () => {
+    setArgv("power", "start");
+    const stderrSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    mockPowerRun.mockRejectedValueOnce(new Error("API failure"));
+
+    await main();
+
+    expect(stderrSpy).toHaveBeenCalledWith(
+      expect.stringContaining("API failure"),
+    );
+    expect(process.exit).toHaveBeenCalledWith(1);
+    stderrSpy.mockRestore();
+  });
+
+  it("exits with code 1 on unknown category", async () => {
+    setArgv("unknown", "action");
+    const stderrSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    await main();
+
+    expect(stderrSpy).toHaveBeenCalled();
+    expect(process.exit).toHaveBeenCalledWith(1);
+    stderrSpy.mockRestore();
+  });
+
+  it("exits with code 1 when neither flags nor env vars provide credentials", async () => {
+    setArgv("power", "start");
+    vi.stubEnv("KIWIVM_VEID", undefined);
+    vi.stubEnv("KIWIVM_API_KEY", undefined);
+    const stderrSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    await main();
+
+    expect(stderrSpy).toHaveBeenCalled();
+    expect(process.exit).toHaveBeenCalledWith(1);
+    stderrSpy.mockRestore();
+  });
+
+  // ---- Help command ----
+
+  it("prints help text when category is 'help'", async () => {
+    setArgv("help");
+    const consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await main();
+
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      expect.stringContaining("kiwivm-cli"),
+    );
+    consoleLogSpy.mockRestore();
+  });
+
+  it("prints help and exits successfully for 'help' command", async () => {
+    setArgv("help");
+    const consoleLogSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+    await main();
+
+    // Help should not call process.exit with an error code
+    expect(process.exit).not.toHaveBeenCalledWith(1);
+    consoleLogSpy.mockRestore();
+  });
+});

package/src/index.ts

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+
+import { KiwiVMClient } from "./client.ts";
+import { KiwiVMError } from "./types.ts";
+
+function parseFlags(args: string[]): Record<string, string> {
+  const flags: Record<string, string> = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!arg?.startsWith("--")) continue;
+    const eqIdx = arg.indexOf("=");
+    if (eqIdx !== -1) {
+      const key = arg.slice(2, eqIdx);
+      const value = arg.slice(eqIdx + 1);
+      flags[toCamelCase(key)] = value;
+    } else {
+      const next = args[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        const key = arg.slice(2);
+        flags[toCamelCase(key)] = next;
+        i++;
+      } else {
+        // --flag with no value (treat as boolean/empty string)
+        const key = arg.slice(2);
+        flags[toCamelCase(key)] = "";
+      }
+    }
+  }
+  return flags;
+}
+
+function toCamelCase(key: string): string {
+  // Known mappings: kebab-case flags that need camelCase API param names
+  const known: Record<string, string> = {
+    "backup-token": "backupToken",
+    "new-hostname": "newHostname",
+    "ssh-keys": "sshKeys",
+    "source-veid": "sourceVeid",
+    "source-token": "sourceToken",
+    "record-id": "recordId",
+    "api-key": "apiKey",
+    "rate-limit": "rateLimit",
+  };
+  if (known[key]) return known[key];
+
+  // Default: convert --some-flag to someFlag
+  return key.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
+function getCommandFromArgs(args: string[]): {
+  positional: string[];
+  flags: Record<string, string>;
+} {
+  const positional: string[] = [];
+  let i = 0;
+  while (i < args.length) {
+    const arg = args[i];
+    if (!arg || arg.startsWith("--")) {
+      break;
+    }
+    positional.push(arg);
+    i++;
+  }
+  const flagArgs = args.slice(i);
+  const flags = parseFlags(flagArgs);
+  return { positional, flags };
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const { positional, flags } = getCommandFromArgs(args);
+
+  const category = positional[0] ?? "";
+  const action = positional[1] ?? "";
+
+  // Handle help before auth (no credentials needed)
+  if (category === "" || category === "help") {
+    const { run } = await import("./commands/help.ts");
+    const text = await run();
+    console.log(text as string);
+    return;
+  }
+
+  // Resolve auth: flags first, then env vars
+  const flagVeid = flags["veid"];
+  const flagApiKey = flags["apiKey"];
+  const resolvedVeid = flagVeid || process.env["KIWIVM_VEID"];
+  const resolvedApiKey = flagApiKey || process.env["KIWIVM_API_KEY"];
+
+  if (!resolvedVeid || !resolvedApiKey) {
+    console.error(
+      "Error: VEID and API key are required. Use --veid and --api-key flags, or set KIWIVM_VEID and KIWIVM_API_KEY environment variables.",
+    );
+    process.exit(1);
+  }
+
+  // Strip auth flags before passing to handlers
+  const handlerFlags = { ...flags };
+  delete handlerFlags["veid"];
+  delete handlerFlags["apiKey"];
+
+  const client = new KiwiVMClient({
+    veid: resolvedVeid,
+    apiKey: resolvedApiKey,
+  });
+
+  try {
+    let result: unknown;
+
+    switch (category) {
+      case "power": {
+        const { run } = await import("./commands/power.ts");
+        result = await run(action, handlerFlags, client);
+        break;
+      }
+      case "info": {
+        const { run } = await import("./commands/info.ts");
+        result = await run(action, handlerFlags, client);
+        break;
+      }
+      case "snapshot": {
+        const { run } = await import("./commands/snapshot.ts");
+        result = await run(action, handlerFlags, client);
+        break;
+      }
+      case "backup": {
+        const { run } = await import("./commands/backup.ts");
+        result = await run(action, handlerFlags, client);
+        break;
+      }
+      case "system": {
+        const { run } = await import("./commands/system.ts");
+        result = await run(action, handlerFlags, client);
+        break;
+      }
+      case "network": {
+        const { run } = await import("./commands/network.ts");
+        result = await run(action, handlerFlags, client);
+        break;
+      }
+      case "monitoring": {
+        const { run } = await import("./commands/monitoring.ts");
+        result = await run(action, handlerFlags, client);
+        break;
+      }
+      case "admin": {
+        const { run } = await import("./commands/admin.ts");
+        result = await run(action, handlerFlags, client);
+        break;
+      }
+      default: {
+        console.error(`Unknown category: ${category}`);
+        console.error("Run 'kiwivm-cli help' for usage.");
+        process.exit(1);
+      }
+    }
+
+    console.log(JSON.stringify(result));
+  } catch (error) {
+    const message =
+      error instanceof KiwiVMError ? error.message : String(error);
+    console.error(`Error: ${message}`);
+    process.exit(1);
+  }
+}
+
+export { main };
+
+// Only auto-run when executed directly (not when imported by tests)
+if (!process.env["VITEST"]) {
+  main();
+}

package/src/types.ts

@@ -0,0 +1,94 @@
+export interface KiwiVMResponse {
+  error: number;
+  message?: string;
+}
+
+export class KiwiVMError extends Error {
+  public readonly errorCode: number;
+  public readonly rawResponse: KiwiVMResponse;
+
+  constructor(message: string, errorCode: number, rawResponse: KiwiVMResponse) {
+    super(message);
+    this.name = "KiwiVMError";
+    this.errorCode = errorCode;
+    this.rawResponse = rawResponse;
+  }
+}
+
+export interface ServiceInfo extends KiwiVMResponse {
+  hostname?: string;
+  node_alias?: string;
+  node_location?: string;
+  location_ipv6_ready?: number;
+  plan?: string;
+  plan_monthly_data?: number;
+  plan_disk?: number;
+  plan_ram?: number;
+  plan_swap?: number;
+  os?: string;
+  email?: string;
+  data_counter?: number;
+  data_next_reset?: number;
+  ip_addresses?: string[];
+  private_ip_addresses?: string[];
+  ip_nullroutes?: Record<
+    string,
+    {
+      nullroute_timestamp: number;
+      nullroute_duration_s: number;
+      log: string;
+    }
+  >;
+  iso1?: string;
+  iso2?: string;
+  available_isos?: string[];
+  plan_max_ipv6s?: number;
+  rdns_api_available?: number;
+  plan_private_network_available?: number;
+  location_private_network_available?: number;
+  ptr?: Record<string, string>;
+  suspended?: number;
+  policy_violation?: number;
+  suspension_count?: number;
+  total_abuse_points?: number;
+  max_abuse_points?: number;
+}
+
+export interface LiveServiceInfo extends ServiceInfo {
+  vm_type?: "ovz" | "kvm";
+  vz_status?: Record<string, unknown>;
+  vz_quota?: Record<string, unknown>;
+  ve_status?: "Starting" | "Running" | "Stopped";
+  ve_mac1?: string;
+  ve_used_disk_space_b?: number;
+  ve_disk_quota_gb?: number;
+  is_cpu_throttled?: number;
+  is_disk_throttled?: number;
+  ssh_port?: number;
+  live_hostname?: string;
+  load_average?: string;
+  mem_available_kb?: number;
+  swap_total_kb?: number;
+  swap_available_kb?: number;
+  screendump_png_base64?: string;
+}
+
+export interface Snapshot {
+  fileName: string;
+  os: string;
+  description: string;
+  size: number;
+  md5: string;
+  sticky: number;
+  purgesIn: number;
+  downloadLink: string;
+  downloadLinkSSL: string;
+}
+
+export interface Backup {
+  backupToken: string;
+  size: number;
+  os: string;
+  md5: string;
+  timestamp: number;
+}