kiwivm-cli 0.1.0 → 0.2.0

package/src/commands/help.ts

@@ -1,32 +1,67 @@
-const HELP = `Usage: kiwivm-cli <category> <action> [--flags...]
+const HELP = `Usage: kiwivm-cli <command> [<subcommand>] [args...] [--flags...]
 
 Auth: --veid <VEID> --api-key <KEY>  (or KIWIVM_VEID / KIWIVM_API_KEY env vars)
 
-Categories:
-
-  power       start | stop | restart | kill
-  info        (no action) | live
-  snapshot    create | list | delete | restore | sticky | export | import
-  backup      list | copy
-  system      hostname | rdns | password | sshkey | os | reinstall
-  network     ipv6-add | ipv6-delete | private-list | private-assign | private-delete
-  monitoring  usage | audit | rate-limit
-  admin       suspensions | unsuspend | resolve | resolve-violation
-
-Flags:
-
-  --description     Snapshot description (snapshot create)
-  --snapshot        Snapshot file name (snapshot delete/restore/sticky/export)
-  --sticky          0 or 1 (snapshot sticky)
-  --source-veid     Source VEID (snapshot import)
-  --source-token    Source token (snapshot import)
-  --backup-token    Backup token (backup copy)
-  --new-hostname    New hostname (system hostname)
-  --ip              IP address (system rdns, network ipv6-delete/private-assign/private-delete)
-  --ptr             PTR/rDNS record (system rdns)
-  --ssh-keys        SSH keys (system sshkey update)
-  --os              OS template name (system reinstall)
-  --record-id       Record ID (admin unsuspend/resolve-violation)
+Commands:
+
+  start                         Start the VPS
+  stop                          Stop the VPS
+  restart                       Reboot the VPS
+  kill                          Force-stop a stuck VPS
+
+  info                          Get service info (plan, IPs, bandwidth, etc.)
+  status                        Get live status (CPU, RAM, disk, uptime)
+
+  snapshot list                 List all snapshots
+  snapshot create [--desc]      Create a new snapshot
+  snapshot delete <token>       Delete a snapshot
+  snapshot restore <token>      Restore from snapshot
+  snapshot sticky <token>       Toggle sticky (--on | --off)
+  snapshot export <token>       Generate transfer token
+  snapshot import <veid> <token> Import snapshot from another instance
+
+  backup list                   List automatic backups
+  backup copy <token>           Convert backup to restorable snapshot
+
+  os list                       List available OS templates
+  os reinstall <template>       Reinstall OS
+
+  hostname <name>               Set new hostname
+  password                      Reset root password
+
+  ssh-key                       Show SSH keys
+  ssh-key set <keys>            Set SSH keys
+
+  rdns set <ip> <ptr>           Set reverse DNS record
+
+  ipv6 add                      Assign new IPv6 /64 subnet
+  ipv6 delete <subnet>          Release IPv6 subnet
+
+  private-ip list               List available private IPs
+  private-ip assign [<ip>]      Assign private IP (random if omitted)
+  private-ip delete <ip>        Release private IP
+
+  iso mount <name>              Mount ISO for boot (VM must be off)
+  iso unmount                   Unmount ISO, boot from disk
+
+  shell exec <command>          Execute command synchronously
+  shell script <script>         Execute script asynchronously
+
+  migrate locations             List available migration locations
+  migrate start <location>      Start migration to new location
+  clone <ip> <password> [--port] Clone from external server (OVZ only)
+
+  stats usage                   Get detailed usage statistics
+  stats audit                   Get audit log
+  stats rate-limit              Check API rate limit status
+
+  suspensions                   View suspension details
+  unsuspend <record-id>         Clear abuse issue and unsuspend
+  violations                    View policy violations
+  violations resolve <record-id> Resolve policy violation
+
+  notifications                 Get notification preferences
+  notifications set <json>      Update notification preferences
 
 Output: JSON to stdout. Errors to stderr with exit code 1.
 `;

package/src/commands/info.test.ts

@@ -1,67 +1,71 @@
 import { describe, expect, it, vi } from "vitest";
 import type { KiwiVMClient } from "../client.ts";
-import { run } from "./info.ts";
+import { info, status } from "./info.ts";
 
 function mockClient() {
   const call = vi.fn();
   return { client: { call } as unknown as KiwiVMClient, call };
 }
 
-describe("info command", () => {
-  it("calls getServiceInfo for basic info (empty action)", async () => {
-    const { client, call } = mockClient();
-    call.mockResolvedValueOnce({
-      error: 0,
-      hostname: "my-vps",
-    });
-
-    const result = await run("", {}, client);
+describe("info handlers", () => {
+  describe("info", () => {
+    it("calls client.call('getServiceInfo')", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({
+        error: 0,
+        hostname: "my-vps",
+        plan_disk: 50,
+        plan_ram: 1024,
+      });
 
-    expect(client.call).toHaveBeenCalledExactlyOnceWith("getServiceInfo");
-    expect(result).toMatchObject({ hostname: "my-vps" });
-  });
+      const result = await info([], {}, client);
 
-  it("calls getServiceInfo when action is omitted", async () => {
-    const { client, call } = mockClient();
-    call.mockResolvedValueOnce({ error: 0 });
+      expect(call).toHaveBeenCalledExactlyOnceWith("getServiceInfo");
+      expect(result).toMatchObject({ hostname: "my-vps" });
+    });
 
-    await run("", {}, client);
+    it("returns the complete API response", async () => {
+      const { client, call } = mockClient();
+      const apiResponse = {
+        error: 0,
+        hostname: "my-vps",
+        plan_disk: 50,
+        plan_ram: 1024,
+      };
+      call.mockResolvedValueOnce(apiResponse);
 
-    expect(client.call).toHaveBeenCalledExactlyOnceWith("getServiceInfo");
-  });
+      const result = await info([], {}, client);
 
-  it("calls getLiveServiceInfo for live action", async () => {
-    const { client, call } = mockClient();
-    call.mockResolvedValueOnce({
-      error: 0,
-      ve_status: "Running",
+      expect(result).toEqual(apiResponse);
     });
 
-    const result = await run("live", {}, client);
+    it("propagates errors from the client", async () => {
+      const { client, call } = mockClient();
+      call.mockRejectedValueOnce(new Error("Network error"));
 
-    expect(client.call).toHaveBeenCalledExactlyOnceWith("getLiveServiceInfo");
-    expect(result).toMatchObject({ ve_status: "Running" });
+      await expect(info([], {}, client)).rejects.toThrow("Network error");
+    });
   });
 
-  it("returns the complete API response", async () => {
-    const { client, call } = mockClient();
-    const apiResponse = {
-      error: 0,
-      hostname: "my-vps",
-      plan_disk: 50,
-      plan_ram: 1024,
-    };
-    call.mockResolvedValueOnce(apiResponse);
+  describe("status", () => {
+    it("calls client.call('getLiveServiceInfo')", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({
+        error: 0,
+        ve_status: "Running",
+      });
 
-    const result = await run("", {}, client);
+      const result = await status([], {}, client);
 
-    expect(result).toEqual(apiResponse);
-  });
+      expect(call).toHaveBeenCalledExactlyOnceWith("getLiveServiceInfo");
+      expect(result).toMatchObject({ ve_status: "Running" });
+    });
 
-  it("propagates errors from the client", async () => {
-    const { client, call } = mockClient();
-    call.mockRejectedValueOnce(new Error("Network error"));
+    it("propagates errors from the client", async () => {
+      const { client, call } = mockClient();
+      call.mockRejectedValueOnce(new Error("Network error"));
 
-    await expect(run("live", {}, client)).rejects.toThrow("Network error");
+      await expect(status([], {}, client)).rejects.toThrow("Network error");
+    });
   });
 });

package/src/commands/info.ts

@@ -1,20 +1,18 @@
 import type { KiwiVMClient } from "../client.ts";
 import type { LiveServiceInfo, ServiceInfo } from "../types.ts";
 
-export async function run(
-  action: string,
+export async function info(
+  _args: string[],
   _flags: Record<string, string>,
   client: KiwiVMClient,
 ): Promise<unknown> {
-  switch (action) {
-    case "live":
-      return client.call<LiveServiceInfo>("getLiveServiceInfo");
-    case "":
-    case "info":
-      return client.call<ServiceInfo>("getServiceInfo");
-    default:
-      throw new Error(
-        `Unknown info action: ${action}. Valid: (no action), live`,
-      );
-  }
+  return client.call<ServiceInfo>("getServiceInfo");
+}
+
+export async function status(
+  _args: string[],
+  _flags: Record<string, string>,
+  client: KiwiVMClient,
+): Promise<unknown> {
+  return client.call<LiveServiceInfo>("getLiveServiceInfo");
 }

package/src/commands/iso.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it, vi } from "vitest";
+import type { KiwiVMClient } from "../client.ts";
+import { mount, unmount } from "./iso.ts";
+
+function mockClient() {
+  const call = vi.fn();
+  return { client: { call } as unknown as KiwiVMClient, call };
+}
+
+describe("iso handlers", () => {
+  describe("mount", () => {
+    it("calls iso/mount with iso name from args", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0 });
+
+      const result = await mount(["ubuntu.iso"], {}, client);
+
+      expect(call).toHaveBeenCalledExactlyOnceWith("iso/mount", {
+        iso: "ubuntu.iso",
+      });
+      expect(result).toEqual({ error: 0 });
+    });
+
+    it("throws when no ISO name provided", async () => {
+      const { client } = mockClient();
+
+      await expect(mount([], {}, client)).rejects.toThrow(/name/);
+    });
+
+    it("propagates errors from the client", async () => {
+      const { client, call } = mockClient();
+      call.mockRejectedValueOnce(new Error("Mount failed"));
+
+      await expect(mount(["ubuntu.iso"], {}, client)).rejects.toThrow(
+        "Mount failed",
+      );
+    });
+  });
+
+  describe("unmount", () => {
+    it("calls iso/unmount with no params", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0 });
+
+      const result = await unmount([], {}, client);
+
+      expect(call).toHaveBeenCalledExactlyOnceWith("iso/unmount");
+      expect(result).toEqual({ error: 0 });
+    });
+
+    it("propagates errors from the client", async () => {
+      const { client, call } = mockClient();
+      call.mockRejectedValueOnce(new Error("Unmount failed"));
+
+      await expect(unmount([], {}, client)).rejects.toThrow("Unmount failed");
+    });
+  });
+});

package/src/commands/iso.ts

@@ -0,0 +1,21 @@
+import type { KiwiVMClient } from "../client.ts";
+
+export async function mount(
+  args: string[],
+  _flags: Record<string, string>,
+  client: KiwiVMClient,
+): Promise<unknown> {
+  const iso = args[0];
+  if (!iso) {
+    throw new Error("iso mount requires a <name> argument");
+  }
+  return client.call("iso/mount", { iso });
+}
+
+export async function unmount(
+  _args: string[],
+  _flags: Record<string, string>,
+  client: KiwiVMClient,
+): Promise<unknown> {
+  return client.call("iso/unmount");
+}

package/src/commands/migrate.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it, vi } from "vitest";
+import type { KiwiVMClient } from "../client.ts";
+import { clone, locations, migrateStart } from "./migrate.ts";
+
+function mockClient() {
+  const call = vi.fn();
+  return { client: { call } as unknown as KiwiVMClient, call };
+}
+
+describe("migrate handlers", () => {
+  describe("locations", () => {
+    it("calls migrate/getLocations", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({
+        error: 0,
+        locations: ["lasvegas", "newyork", "luxembourg"],
+      });
+
+      const result = await locations([], {}, client);
+
+      expect(call).toHaveBeenCalledExactlyOnceWith("migrate/getLocations");
+      expect(result).toMatchObject({
+        locations: ["lasvegas", "newyork", "luxembourg"],
+      });
+    });
+
+    it("propagates errors from the client", async () => {
+      const { client, call } = mockClient();
+      call.mockRejectedValueOnce(new Error("API failure"));
+
+      await expect(locations([], {}, client)).rejects.toThrow("API failure");
+    });
+  });
+
+  describe("migrateStart", () => {
+    it("calls migrate/start with location from args", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0 });
+
+      await migrateStart(["lasvegas"], {}, client);
+
+      expect(call).toHaveBeenCalledExactlyOnceWith("migrate/start", {
+        location: "lasvegas",
+      });
+    });
+
+    it("throws when no location provided", async () => {
+      const { client } = mockClient();
+
+      await expect(migrateStart([], {}, client)).rejects.toThrow("location");
+    });
+
+    it("propagates errors from the client", async () => {
+      const { client, call } = mockClient();
+      call.mockRejectedValueOnce(new Error("Migration not available"));
+
+      await expect(migrateStart(["lasvegas"], {}, client)).rejects.toThrow(
+        "Migration not available",
+      );
+    });
+  });
+
+  describe("clone", () => {
+    it("calls cloneFromExternalServer with IP, default port, and password", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0 });
+
+      await clone(["1.2.3.4", "mypassword"], {}, client);
+
+      expect(call).toHaveBeenCalledExactlyOnceWith("cloneFromExternalServer", {
+        externalServerIP: "1.2.3.4",
+        externalServerSSHport: "22",
+        externalServerRootPassword: "mypassword",
+      });
+    });
+
+    it("calls cloneFromExternalServer with custom port from flags", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0 });
+
+      await clone(["1.2.3.4", "mypassword"], { port: "2222" }, client);
+
+      expect(call).toHaveBeenCalledExactlyOnceWith("cloneFromExternalServer", {
+        externalServerIP: "1.2.3.4",
+        externalServerSSHport: "2222",
+        externalServerRootPassword: "mypassword",
+      });
+    });
+
+    it("throws when password not provided", async () => {
+      const { client } = mockClient();
+
+      await expect(clone(["1.2.3.4"], {}, client)).rejects.toThrow("password");
+    });
+
+    it("propagates errors from the client", async () => {
+      const { client, call } = mockClient();
+      call.mockRejectedValueOnce(new Error("Clone failed"));
+
+      await expect(
+        clone(["1.2.3.4", "mypassword"], {}, client),
+      ).rejects.toThrow("Clone failed");
+    });
+  });
+});

package/src/commands/migrate.ts

@@ -0,0 +1,38 @@
+import type { KiwiVMClient } from "../client.ts";
+
+export async function locations(
+  _args: string[],
+  _flags: Record<string, string>,
+  client: KiwiVMClient,
+): Promise<unknown> {
+  return client.call("migrate/getLocations");
+}
+
+export async function migrateStart(
+  args: string[],
+  _flags: Record<string, string>,
+  client: KiwiVMClient,
+): Promise<unknown> {
+  const location = args[0];
+  if (!location) {
+    throw new Error("migrate start requires a <location> argument");
+  }
+  return client.call("migrate/start", { location });
+}
+
+export async function clone(
+  args: string[],
+  flags: Record<string, string>,
+  client: KiwiVMClient,
+): Promise<unknown> {
+  const ip = args[0];
+  const password = args[1];
+  if (!ip || !password) {
+    throw new Error("clone requires both <ip> and <password> arguments");
+  }
+  return client.call("cloneFromExternalServer", {
+    externalServerIP: ip,
+    externalServerSSHport: flags["port"] || "22",
+    externalServerRootPassword: password,
+  });
+}

package/src/commands/network.test.ts

@@ -1,85 +1,162 @@
 import { describe, expect, it, vi } from "vitest";
 import type { KiwiVMClient } from "../client.ts";
-import { run } from "./network.ts";
+import {
+  ipv6Add,
+  ipv6Delete,
+  privateIpAssign,
+  privateIpDelete,
+  privateIpList,
+  rdnsSet,
+} from "./network.ts";
 
 function mockClient() {
   const call = vi.fn();
   return { client: { call } as unknown as KiwiVMClient, call };
 }
 
-describe("network command", () => {
-  describe("ipv6-add", () => {
+describe("network handlers", () => {
+  describe("rdnsSet", () => {
+    it("calls setPTR with ip and ptr from args", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0 });
+
+      await rdnsSet(["1.2.3.4", "my.domain.com"], {}, client);
+
+      expect(call).toHaveBeenCalledExactlyOnceWith("setPTR", {
+        ip: "1.2.3.4",
+        ptr: "my.domain.com",
+      });
+    });
+
+    it("propagates errors from the client", async () => {
+      const { client, call } = mockClient();
+      call.mockRejectedValueOnce(new Error("Invalid PTR"));
+
+      await expect(
+        rdnsSet(["1.2.3.4", "my.domain.com"], {}, client),
+      ).rejects.toThrow("Invalid PTR");
+    });
+  });
+
+  describe("ipv6Add", () => {
     it("calls ipv6/add with no extra params", async () => {
       const { client, call } = mockClient();
       call.mockResolvedValueOnce({ error: 0 });
 
-      const result = await run("ipv6-add", {}, client);
+      const result = await ipv6Add([], {}, client);
 
-      expect(client.call).toHaveBeenCalledExactlyOnceWith("ipv6/add");
+      expect(call).toHaveBeenCalledExactlyOnceWith("ipv6/add");
       expect(result).toEqual({ error: 0 });
     });
+
+    it("propagates errors from the client", async () => {
+      const { client, call } = mockClient();
+      call.mockRejectedValueOnce(new Error("IPv6 not available"));
+
+      await expect(ipv6Add([], {}, client)).rejects.toThrow(
+        "IPv6 not available",
+      );
+    });
   });
 
-  describe("ipv6-delete", () => {
-    it("calls ipv6/delete with ip flag", async () => {
+  describe("ipv6Delete", () => {
+    it("calls ipv6/delete with ip from args", async () => {
       const { client, call } = mockClient();
       call.mockResolvedValueOnce({ error: 0 });
 
-      await run("ipv6-delete", { ip: "2001:db8::1" }, client);
+      await ipv6Delete(["2001:db8::1"], {}, client);
 
-      expect(client.call).toHaveBeenCalledExactlyOnceWith("ipv6/delete", {
+      expect(call).toHaveBeenCalledExactlyOnceWith("ipv6/delete", {
         ip: "2001:db8::1",
       });
     });
+
+    it("propagates errors from the client", async () => {
+      const { client, call } = mockClient();
+      call.mockRejectedValueOnce(new Error("Invalid IP"));
+
+      await expect(ipv6Delete(["2001:db8::1"], {}, client)).rejects.toThrow(
+        "Invalid IP",
+      );
+    });
   });
 
-  describe("private-list", () => {
+  describe("privateIpList", () => {
     it("calls privateIp/getAvailableIps", async () => {
       const { client, call } = mockClient();
       call.mockResolvedValueOnce({
         error: 0,
-        availableIps: ["10.0.0.1"],
+        availableIps: ["10.0.0.1", "10.0.0.2"],
       });
 
-      const result = await run("private-list", {}, client);
+      const result = await privateIpList([], {}, client);
+
+      expect(call).toHaveBeenCalledExactlyOnceWith("privateIp/getAvailableIps");
+      expect(result).toMatchObject({ availableIps: ["10.0.0.1", "10.0.0.2"] });
+    });
+
+    it("propagates errors from the client", async () => {
+      const { client, call } = mockClient();
+      call.mockRejectedValueOnce(new Error("Private IP not available"));
 
-      expect(client.call).toHaveBeenCalledExactlyOnceWith(
-        "privateIp/getAvailableIps",
+      await expect(privateIpList([], {}, client)).rejects.toThrow(
+        "Private IP not available",
       );
-      expect(result).toMatchObject({ availableIps: ["10.0.0.1"] });
     });
   });
 
-  describe("private-assign", () => {
-    it("calls privateIp/assign with ip flag", async () => {
+  describe("privateIpAssign", () => {
+    it("calls privateIp/assign with ip from args", async () => {
       const { client, call } = mockClient();
       call.mockResolvedValueOnce({ error: 0 });
 
-      await run("private-assign", { ip: "10.0.0.1" }, client);
+      await privateIpAssign(["10.0.0.5"], {}, client);
 
-      expect(client.call).toHaveBeenCalledExactlyOnceWith("privateIp/assign", {
-        ip: "10.0.0.1",
+      expect(call).toHaveBeenCalledExactlyOnceWith("privateIp/assign", {
+        ip: "10.0.0.5",
       });
     });
-  });
 
-  describe("private-delete", () => {
-    it("calls privateIp/delete with ip flag", async () => {
+    it("calls privateIp/assign with undefined ip when no arg", async () => {
       const { client, call } = mockClient();
       call.mockResolvedValueOnce({ error: 0 });
 
-      await run("private-delete", { ip: "10.0.0.1" }, client);
+      await privateIpAssign([], {}, client);
 
-      expect(client.call).toHaveBeenCalledExactlyOnceWith("privateIp/delete", {
-        ip: "10.0.0.1",
+      expect(call).toHaveBeenCalledExactlyOnceWith("privateIp/assign", {
+        ip: undefined,
       });
     });
+
+    it("propagates errors from the client", async () => {
+      const { client, call } = mockClient();
+      call.mockRejectedValueOnce(new Error("Assignment failed"));
+
+      await expect(privateIpAssign(["10.0.0.5"], {}, client)).rejects.toThrow(
+        "Assignment failed",
+      );
+    });
   });
 
-  it("propagates errors from the client", async () => {
-    const { client, call } = mockClient();
-    call.mockRejectedValueOnce(new Error("Invalid IP"));
+  describe("privateIpDelete", () => {
+    it("calls privateIp/delete with ip from args", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0 });
+
+      await privateIpDelete(["10.0.0.5"], {}, client);
+
+      expect(call).toHaveBeenCalledExactlyOnceWith("privateIp/delete", {
+        ip: "10.0.0.5",
+      });
+    });
+
+    it("propagates errors from the client", async () => {
+      const { client, call } = mockClient();
+      call.mockRejectedValueOnce(new Error("Delete failed"));
 
-    await expect(run("ipv6-add", {}, client)).rejects.toThrow("Invalid IP");
+      await expect(privateIpDelete(["10.0.0.5"], {}, client)).rejects.toThrow(
+        "Delete failed",
+      );
+    });
   });
 });