kiwivm-cli 0.1.0

package/src/client.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { KiwiVMClient } from "./client.ts";
+import { KiwiVMError } from "./types.ts";
+
+global.fetch = vi.fn();
+
+const client = new KiwiVMClient({
+  veid: "12345",
+  apiKey: "test-key",
+});
+
+describe("KiwiVMClient", () => {
+  afterEach(() => vi.resetAllMocks());
+
+  it("sends POST with form-encoded body and returns success", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ error: 0 }),
+    } as Response);
+
+    const result = await client.call("restart");
+    expect(result.error).toBe(0);
+
+    const call = vi.mocked(fetch).mock.calls[0];
+    expect(call?.[0]).toBe("https://api.64clouds.com/v1/restart");
+    expect((call?.[1] as RequestInit).method).toBe("POST");
+    expect((call?.[1] as RequestInit).headers).toEqual({
+      "Content-Type": "application/x-www-form-urlencoded",
+    });
+
+    const body = (call?.[1] as RequestInit).body as URLSearchParams;
+    expect(body.get("veid")).toBe("12345");
+    expect(body.get("api_key")).toBe("test-key");
+  });
+
+  it("passes additional params to request body", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce({
+      ok: true,
+      json: () => Promise.resolve({ error: 0 }),
+    } as Response);
+
+    await client.call("snapshot/create", { description: "test" });
+
+    const body = (vi.mocked(fetch).mock.calls[0]?.[1] as RequestInit)
+      .body as URLSearchParams;
+    expect(body.get("description")).toBe("test");
+  });
+
+  it("throws KiwiVMError on API error", async () => {
+    vi.mocked(fetch).mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve({ error: 1, message: "Invalid VEID" }),
+    } as Response);
+
+    await expect(client.call("restart")).rejects.toThrow(KiwiVMError);
+    await expect(client.call("restart")).rejects.toThrow("Invalid VEID");
+  });
+
+  it("throws on HTTP error", async () => {
+    vi.mocked(fetch).mockResolvedValueOnce({
+      ok: false,
+      status: 500,
+      statusText: "Internal Server Error",
+    } as Response);
+
+    await expect(client.call("restart")).rejects.toThrow("HTTP 500");
+  });
+});

package/src/client.ts

@@ -0,0 +1,55 @@
+import type { KiwiVMResponse } from "./types.ts";
+import { KiwiVMError } from "./types.ts";
+
+const API_BASE = "https://api.64clouds.com/v1";
+
+export interface ClientOptions {
+  veid: string;
+  apiKey: string;
+}
+
+export class KiwiVMClient {
+  private veid: string;
+  private apiKey: string;
+
+  constructor(options: ClientOptions) {
+    this.veid = options.veid;
+    this.apiKey = options.apiKey;
+  }
+
+  async call<T extends KiwiVMResponse = KiwiVMResponse>(
+    endpoint: string,
+    params: Record<string, string | number | boolean | undefined> = {},
+  ): Promise<T> {
+    const body = new URLSearchParams();
+    body.set("veid", this.veid);
+    body.set("api_key", this.apiKey);
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined) {
+        body.set(key, String(value));
+      }
+    }
+
+    const response = await fetch(`${API_BASE}/${endpoint}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body,
+    });
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+
+    const data = (await response.json()) as T & KiwiVMResponse;
+
+    if (data.error !== 0) {
+      throw new KiwiVMError(
+        data.message ?? `API error: ${data.error}`,
+        data.error,
+        data,
+      );
+    }
+
+    return data as T;
+  }
+}

package/src/commands/admin.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, it, vi } from "vitest";
+import type { KiwiVMClient } from "../client.ts";
+import { run } from "./admin.ts";
+
+function mockClient() {
+  const call = vi.fn();
+  return { client: { call } as unknown as KiwiVMClient, call };
+}
+
+describe("admin command", () => {
+  describe("suspensions", () => {
+    it("calls getSuspensionDetails", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({
+        error: 0,
+        suspensions: [{ reason: "abuse", createdAt: "2025-01-01" }],
+      });
+
+      const result = await run("suspensions", {}, client);
+
+      expect(client.call).toHaveBeenCalledExactlyOnceWith(
+        "getSuspensionDetails",
+      );
+      expect(result).toMatchObject({
+        suspensions: [{ reason: "abuse" }],
+      });
+    });
+  });
+
+  describe("unsuspend", () => {
+    it("calls unsuspend with record-id flag", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0 });
+
+      await run("unsuspend", { recordId: "42" }, client);
+
+      expect(client.call).toHaveBeenCalledExactlyOnceWith("unsuspend", {
+        recordId: "42",
+      });
+    });
+  });
+
+  describe("resolve", () => {
+    it("calls resolvePolicyViolation with record-id flag", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0 });
+
+      await run("resolve", { recordId: "42" }, client);
+
+      expect(client.call).toHaveBeenCalledExactlyOnceWith(
+        "resolvePolicyViolation",
+        { recordId: "42" },
+      );
+    });
+  });
+
+  it("propagates errors from the client", async () => {
+    const { client, call } = mockClient();
+    call.mockRejectedValueOnce(new Error("Record not found"));
+
+    await expect(run("unsuspend", { recordId: "999" }, client)).rejects.toThrow(
+      "Record not found",
+    );
+  });
+});

package/src/commands/admin.ts

@@ -0,0 +1,25 @@
+import type { KiwiVMClient } from "../client.ts";
+
+export async function run(
+  action: string,
+  flags: Record<string, string>,
+  client: KiwiVMClient,
+): Promise<unknown> {
+  switch (action) {
+    case "suspensions":
+      return client.call("getSuspensionDetails");
+    case "unsuspend":
+      return client.call("unsuspend", { recordId: flags["recordId"] });
+    case "resolve":
+      if (flags["recordId"] !== undefined) {
+        return client.call("resolvePolicyViolation", {
+          recordId: flags["recordId"],
+        });
+      }
+      return client.call("getPolicyViolations");
+    default:
+      throw new Error(
+        `Unknown admin action: ${action}. Valid: suspensions, unsuspend, resolve`,
+      );
+  }
+}

package/src/commands/backup.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it, vi } from "vitest";
+import type { KiwiVMClient } from "../client.ts";
+import { run } from "./backup.ts";
+
+function mockClient() {
+  const call = vi.fn();
+  return { client: { call } as unknown as KiwiVMClient, call };
+}
+
+describe("backup command", () => {
+  describe("list", () => {
+    it("calls backup/list", async () => {
+      const { client, call } = mockClient();
+      const backups = {
+        error: 0,
+        backups: [
+          {
+            backupToken: "tok1",
+            size: 1024,
+            os: "Ubuntu",
+            md5: "abc",
+            timestamp: 1700000000,
+          },
+        ],
+      };
+      call.mockResolvedValueOnce(backups);
+
+      const result = await run("list", {}, client);
+
+      expect(client.call).toHaveBeenCalledExactlyOnceWith("backup/list");
+      expect(result).toEqual(backups);
+    });
+
+    it("does not pass any extra params", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0, backups: [] });
+
+      await run("list", {}, client);
+
+      expect(client.call).toHaveBeenCalledExactlyOnceWith("backup/list");
+    });
+  });
+
+  describe("copy", () => {
+    it("calls backup/copyToSnapshot with backupToken", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0 });
+
+      await run("copy", { backupToken: "tok1" }, client);
+
+      expect(client.call).toHaveBeenCalledExactlyOnceWith(
+        "backup/copyToSnapshot",
+        { backupToken: "tok1" },
+      );
+    });
+  });
+
+  it("propagates errors from the client", async () => {
+    const { client, call } = mockClient();
+    call.mockRejectedValueOnce(new Error("Backup not found"));
+
+    await expect(run("copy", { backupToken: "bad" }, client)).rejects.toThrow(
+      "Backup not found",
+    );
+  });
+});

package/src/commands/backup.ts

@@ -0,0 +1,23 @@
+import type { KiwiVMClient } from "../client.ts";
+import type { Backup, KiwiVMResponse } from "../types.ts";
+
+interface BackupListResponse extends KiwiVMResponse {
+  backups: Backup[];
+}
+
+export async function run(
+  action: string,
+  flags: Record<string, string>,
+  client: KiwiVMClient,
+): Promise<unknown> {
+  switch (action) {
+    case "list":
+      return client.call<BackupListResponse>("backup/list");
+    case "copy":
+      return client.call("backup/copyToSnapshot", {
+        backupToken: flags["backupToken"],
+      });
+    default:
+      throw new Error(`Unknown backup action: ${action}. Valid: list, copy`);
+  }
+}

package/src/commands/help.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest";
+import { run } from "./help.ts";
+
+describe("help command", () => {
+  it("returns a string containing usage information", async () => {
+    const result = await run();
+
+    expect(typeof result).toBe("string");
+  });
+
+  it("mentions the CLI name", async () => {
+    const result = await run();
+
+    expect(result).toContain("kiwivm-cli");
+  });
+
+  it("lists available command categories", async () => {
+    const result = await run();
+
+    // Spot-check a few categories
+    expect(result).toContain("power");
+    expect(result).toContain("info");
+    expect(result).toContain("snapshot");
+    expect(result).toContain("backup");
+    expect(result).toContain("system");
+    expect(result).toContain("network");
+    expect(result).toContain("monitoring");
+    expect(result).toContain("admin");
+  });
+
+  it("mentions global flags --veid and --api-key", async () => {
+    const result = await run();
+
+    expect(result).toContain("--veid");
+    expect(result).toContain("--api-key");
+  });
+
+  it("mentions environment variables", async () => {
+    const result = await run();
+
+    expect(result).toContain("KIWIVM_VEID");
+    expect(result).toContain("KIWIVM_API_KEY");
+  });
+
+  it("returns a multi-line help text", async () => {
+    const result = await run();
+
+    expect(result).toContain("\n");
+  });
+});

package/src/commands/help.ts

@@ -0,0 +1,36 @@
+const HELP = `Usage: kiwivm-cli <category> <action> [--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)
+
+Output: JSON to stdout. Errors to stderr with exit code 1.
+`;
+
+export async function run(): Promise<string> {
+  return HELP;
+}

package/src/commands/info.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, it, vi } from "vitest";
+import type { KiwiVMClient } from "../client.ts";
+import { run } 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);
+
+    expect(client.call).toHaveBeenCalledExactlyOnceWith("getServiceInfo");
+    expect(result).toMatchObject({ hostname: "my-vps" });
+  });
+
+  it("calls getServiceInfo when action is omitted", async () => {
+    const { client, call } = mockClient();
+    call.mockResolvedValueOnce({ error: 0 });
+
+    await run("", {}, client);
+
+    expect(client.call).toHaveBeenCalledExactlyOnceWith("getServiceInfo");
+  });
+
+  it("calls getLiveServiceInfo for live action", async () => {
+    const { client, call } = mockClient();
+    call.mockResolvedValueOnce({
+      error: 0,
+      ve_status: "Running",
+    });
+
+    const result = await run("live", {}, client);
+
+    expect(client.call).toHaveBeenCalledExactlyOnceWith("getLiveServiceInfo");
+    expect(result).toMatchObject({ ve_status: "Running" });
+  });
+
+  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);
+
+    const result = await run("", {}, client);
+
+    expect(result).toEqual(apiResponse);
+  });
+
+  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");
+  });
+});

package/src/commands/info.ts

@@ -0,0 +1,20 @@
+import type { KiwiVMClient } from "../client.ts";
+import type { LiveServiceInfo, ServiceInfo } from "../types.ts";
+
+export async function run(
+  action: 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`,
+      );
+  }
+}

package/src/commands/monitoring.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it, vi } from "vitest";
+import type { KiwiVMClient } from "../client.ts";
+import { run } from "./monitoring.ts";
+
+function mockClient() {
+  const call = vi.fn();
+  return { client: { call } as unknown as KiwiVMClient, call };
+}
+
+describe("monitoring command", () => {
+  describe("usage", () => {
+    it("calls getRawUsageStats", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({
+        error: 0,
+        data: [{ month: "2025-01", usage: 100 }],
+      });
+
+      const result = await run("usage", {}, client);
+
+      expect(client.call).toHaveBeenCalledExactlyOnceWith("getRawUsageStats");
+      expect(result).toMatchObject({
+        data: [{ month: "2025-01", usage: 100 }],
+      });
+    });
+  });
+
+  describe("audit", () => {
+    it("calls getAuditLog", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({
+        error: 0,
+        logs: [{ timestamp: 1700000000, action: "restart" }],
+      });
+
+      const result = await run("audit", {}, client);
+
+      expect(client.call).toHaveBeenCalledExactlyOnceWith("getAuditLog");
+      expect(result).toMatchObject({
+        logs: [{ timestamp: 1700000000, action: "restart" }],
+      });
+    });
+  });
+
+  describe("rate-limit", () => {
+    it("calls getRateLimitStatus", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({
+        error: 0,
+        remaining: 950,
+        limit: 1000,
+      });
+
+      const result = await run("rate-limit", {}, client);
+
+      expect(client.call).toHaveBeenCalledExactlyOnceWith("getRateLimitStatus");
+      expect(result).toMatchObject({ remaining: 950, limit: 1000 });
+    });
+  });
+
+  it("returns the complete API response", async () => {
+    const { client, call } = mockClient();
+    const apiResponse = {
+      error: 0,
+      remaining: 500,
+      limit: 1000,
+      reset: 1700000000,
+    };
+    call.mockResolvedValueOnce(apiResponse);
+
+    const result = await run("rate-limit", {}, client);
+
+    expect(result).toEqual(apiResponse);
+  });
+
+  it("propagates errors from the client", async () => {
+    const { client, call } = mockClient();
+    call.mockRejectedValueOnce(new Error("Rate limited"));
+
+    await expect(run("audit", {}, client)).rejects.toThrow("Rate limited");
+  });
+});

package/src/commands/monitoring.ts

@@ -0,0 +1,20 @@
+import type { KiwiVMClient } from "../client.ts";
+
+export async function run(
+  action: string,
+  _flags: Record<string, string>,
+  client: KiwiVMClient,
+): Promise<unknown> {
+  switch (action) {
+    case "usage":
+      return client.call("getRawUsageStats");
+    case "audit":
+      return client.call("getAuditLog");
+    case "rate-limit":
+      return client.call("getRateLimitStatus");
+    default:
+      throw new Error(
+        `Unknown monitoring action: ${action}. Valid: usage, audit, rate-limit`,
+      );
+  }
+}

package/src/commands/network.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it, vi } from "vitest";
+import type { KiwiVMClient } from "../client.ts";
+import { run } from "./network.ts";
+
+function mockClient() {
+  const call = vi.fn();
+  return { client: { call } as unknown as KiwiVMClient, call };
+}
+
+describe("network command", () => {
+  describe("ipv6-add", () => {
+    it("calls ipv6/add with no extra params", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0 });
+
+      const result = await run("ipv6-add", {}, client);
+
+      expect(client.call).toHaveBeenCalledExactlyOnceWith("ipv6/add");
+      expect(result).toEqual({ error: 0 });
+    });
+  });
+
+  describe("ipv6-delete", () => {
+    it("calls ipv6/delete with ip flag", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0 });
+
+      await run("ipv6-delete", { ip: "2001:db8::1" }, client);
+
+      expect(client.call).toHaveBeenCalledExactlyOnceWith("ipv6/delete", {
+        ip: "2001:db8::1",
+      });
+    });
+  });
+
+  describe("private-list", () => {
+    it("calls privateIp/getAvailableIps", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({
+        error: 0,
+        availableIps: ["10.0.0.1"],
+      });
+
+      const result = await run("private-list", {}, client);
+
+      expect(client.call).toHaveBeenCalledExactlyOnceWith(
+        "privateIp/getAvailableIps",
+      );
+      expect(result).toMatchObject({ availableIps: ["10.0.0.1"] });
+    });
+  });
+
+  describe("private-assign", () => {
+    it("calls privateIp/assign with ip flag", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0 });
+
+      await run("private-assign", { ip: "10.0.0.1" }, client);
+
+      expect(client.call).toHaveBeenCalledExactlyOnceWith("privateIp/assign", {
+        ip: "10.0.0.1",
+      });
+    });
+  });
+
+  describe("private-delete", () => {
+    it("calls privateIp/delete with ip flag", async () => {
+      const { client, call } = mockClient();
+      call.mockResolvedValueOnce({ error: 0 });
+
+      await run("private-delete", { ip: "10.0.0.1" }, client);
+
+      expect(client.call).toHaveBeenCalledExactlyOnceWith("privateIp/delete", {
+        ip: "10.0.0.1",
+      });
+    });
+  });
+
+  it("propagates errors from the client", async () => {
+    const { client, call } = mockClient();
+    call.mockRejectedValueOnce(new Error("Invalid IP"));
+
+    await expect(run("ipv6-add", {}, client)).rejects.toThrow("Invalid IP");
+  });
+});