warpmetal 0.1.0

package/README.md

@@ -0,0 +1,75 @@
+# WarpMetal Agent Kit
+
+The official command-line client and portable Agent Skill for WarpMetal.
+
+The CLI uses the public API at `https://api.warpmetal.com`, stores generated
+WarpMetal credentials in a user-private state file, and never reads or stores
+wallet private keys or SSH private-key contents.
+
+## Distribution
+
+- Source and releases: `https://github.com/warpmetal/agent-kit`
+- CLI: the unscoped public npm package `warpmetal`, exposing the `warpmetal`
+  executable
+- Skill: `skills/warpmetal` in the GitHub repository and bundled inside the
+  npm package
+
+Keeping the skill beside the CLI gives Codex, Claude, and other Agent
+Skills-compatible tools one canonical set of safety instructions while the CLI
+remains the stable executable API.
+
+## Install
+
+```sh
+npm install --global warpmetal
+warpmetal --help
+```
+
+Install the bundled skill for supported coding agents:
+
+```sh
+warpmetal agent install --target codex
+warpmetal agent install --target claude
+warpmetal agent install --target all
+```
+
+Use `--scope project` to install into the current repository instead of the
+user-level agent directory.
+
+The bundled `skills/warpmetal` directory follows the portable Agent Skills
+layout. Agents that support that layout but use another installation path can
+consume that directory directly; they do not need a different WarpMetal API
+integration.
+
+## First commands
+
+```sh
+warpmetal health
+warpmetal catalog
+warpmetal order prepare \
+  --plan agent \
+  --hostname codex-workspace \
+  --os '<exact name from warpmetal catalog>' \
+  --ssh-public-key-file ~/.ssh/id_ed25519.pub
+```
+
+Pass `--json` for structured, secret-redacted output. Use
+`WARPMETAL_API_URL` for an alternate API origin and `WARPMETAL_HOME` for an
+alternate state directory.
+
+## Security boundary
+
+- Order and access tokens are never printed; they are written to
+  `${WARPMETAL_HOME:-~/.config/warpmetal}/state.json` with user-only
+  permissions where the platform supports POSIX modes.
+- The CLI passes an SSH private-key path directly to `ssh-keygen`; it never
+  reads the private key.
+- The CLI accepts an externally produced x402 `PAYMENT-SIGNATURE` from a file.
+  Wallet key management and signing remain outside this package.
+- Destructive or state-changing commands require explicit confirmations and
+  generate idempotency keys by default.
+
+## Publishing status
+
+This package is an initial development release. Choose the public-source
+license and replace `UNLICENSED` before publishing it to npm.

package/bin/warpmetal.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import { main } from "../src/cli.js";
+
+const exitCode = await main(process.argv.slice(2));
+process.exitCode = exitCode;

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "warpmetal",
+  "version": "0.1.0",
+  "description": "Agent-safe CLI and skill for purchasing and managing WarpMetal VPS servers",
+  "type": "module",
+  "bin": {
+    "warpmetal": "./bin/warpmetal.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "skills/warpmetal/",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "check": "node --check bin/warpmetal.js && node --check src/api.js && node --check src/args.js && node --check src/cli.js && node --check src/errors.js && node --check src/install-skill.js && node --check src/ssh.js && node --check src/state.js",
+    "test": "node --test",
+    "prepack": "npm run check && npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/warpmetal/agent-kit.git"
+  },
+  "homepage": "https://github.com/warpmetal/agent-kit#readme",
+  "bugs": {
+    "url": "https://github.com/warpmetal/agent-kit/issues"
+  },
+  "license": "UNLICENSED",
+  "keywords": [
+    "warpmetal",
+    "vps",
+    "agent-skills",
+    "codex",
+    "claude",
+    "x402"
+  ]
+}

package/skills/warpmetal/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: warpmetal
+description: Safely purchase and manage WarpMetal VPS servers with the warpmetal CLI. Use when Codex, Claude Code, Cursor, Windsurf, or another shell-capable agent needs to inspect live VPS plans and operating systems, prepare or pay for an x402 order, poll provisioning, prove ownership with an SSH key, inspect a server, or run supported lifecycle operations.
+---
+
+# WarpMetal
+
+Use the `warpmetal` CLI as the executable interface. Do not reconstruct its
+credential, idempotency, exact-body retry, SSH signing, or polling behavior
+with ad hoc HTTP commands.
+
+## Start safely
+
+1. Run `warpmetal --version`.
+2. If it is missing, ask before installing software, then install the official
+   npm package only from `https://www.npmjs.com/package/warpmetal`.
+3. Use `--json` for every agent-driven command.
+4. Read [references/safety.md](references/safety.md) before preparing an order,
+   authorizing payment, using an SSH identity, or changing a server.
+5. Read [references/cli-reference.md](references/cli-reference.md) when choosing
+   a command or interpreting an exit code.
+
+Never read, print, summarize, upload, or commit the WarpMetal state file. Never
+read an SSH private-key file. Pass its path only to a command designed to use
+it. Never request or handle a wallet seed phrase or private key.
+
+## Discover before acting
+
+Run:
+
+```sh
+warpmetal health --json
+warpmetal catalog --json
+```
+
+Stop if `purchasingReady` is false. Select `planId` and the exact OS `name`
+from the live catalog. Do not reuse an OS name or price from documentation or
+a previous session.
+
+## Prepare an order
+
+Confirm the intended plan, exact OS, hostname, and existing SSH public-key file
+with the user. Ask before generating a new SSH key pair.
+
+```sh
+warpmetal order prepare \
+  --plan <planId> \
+  --hostname <hostname> \
+  --os '<exact live OS name>' \
+  --ssh-public-key-file <public-key-path> \
+  --json
+```
+
+The CLI saves the generated recovery credential privately and does not print
+it. Preserve the reported task and server IDs in the conversation, but do not
+open the state file to retrieve the credential.
+
+## Authorize payment
+
+Run `warpmetal checkout challenge --task <taskId> --json` to obtain the live
+x402 terms. Before any wallet creation, funding, or signature, show the user
+the exact amount, asset, network, recipient, and expiration derived from the
+live challenge and obtain explicit approval.
+
+Use a compatible external wallet signer to produce one `PAYMENT-SIGNATURE`
+header value in a file. Do not pass wallet secrets to WarpMetal or the CLI.
+After approval, submit it with:
+
+```sh
+warpmetal checkout submit \
+  --task <taskId> \
+  --payment-signature-file <path> \
+  --wait \
+  --json
+```
+
+If the command reports a rejected signature, inspect the replacement live
+challenge and request new approval where its terms changed. If it reports
+`manual_review`, stop immediately and never create another payment.
+
+## Provision and manage
+
+Poll a prepared or paid order with:
+
+```sh
+warpmetal order status --task <taskId> --wait --json
+```
+
+For routine management, prove possession of the installed SSH key without
+reading it:
+
+```sh
+warpmetal server login --server <serverId> --identity <private-key-path> --json
+warpmetal server get --server <serverId> --json
+```
+
+For power changes, state the intended effect and obtain explicit approval,
+then pass the same action as the confirmation:
+
+```sh
+warpmetal server power \
+  --server <serverId> \
+  --action reboot \
+  --confirm reboot \
+  --wait \
+  --json
+```
+
+Do not fall back to raw API calls for reload, deletion, networking, renewal,
+or another unsupported mutation. Explain that the installed CLI version does
+not yet expose that guarded operation.

package/skills/warpmetal/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "WarpMetal VPS"
+  short_description: "Purchase and manage WarpMetal VPS servers"
+  default_prompt: "Use $warpmetal to choose, purchase, and manage a WarpMetal VPS safely."

package/skills/warpmetal/references/cli-reference.md

@@ -0,0 +1,100 @@
+# WarpMetal CLI reference
+
+## Contents
+
+- Discovery
+- Purchase and provisioning
+- Server management
+- Skill installation and state
+- Exit codes
+
+## Discovery
+
+```sh
+warpmetal health --json
+warpmetal catalog [--plan <planId>] --json
+```
+
+`health` exits with code 3 when the service responds but purchasing is paused.
+The catalog remains useful for read-only discovery.
+
+## Purchase and provisioning
+
+```sh
+warpmetal order prepare \
+  --plan <live planId> \
+  --hostname <dns-label> \
+  --os '<exact live OS name>' \
+  --ssh-public-key-file <path> \
+  [--email <address>] \
+  [--idempotency-key <key>] \
+  --json
+
+warpmetal checkout challenge --task <taskId> --json
+
+warpmetal checkout submit \
+  --task <taskId> \
+  --payment-signature-file <path> \
+  [--wait] [--timeout-seconds <n>] \
+  --json
+
+warpmetal order status \
+  --task <taskId> \
+  [--wait] [--timeout-seconds <n>] \
+  --json
+```
+
+The payment signature file must contain one HTTP header value. The CLI does
+not create or store wallet keys and does not sign x402 challenges.
+
+## Server management
+
+```sh
+warpmetal server login \
+  --server <serverId> \
+  --identity <private-key-path> \
+  --json
+
+warpmetal server get --server <serverId> --json
+
+warpmetal server power \
+  --server <serverId> \
+  --action <boot|reboot|shutdown> \
+  --confirm <same-action> \
+  [--idempotency-key <key>] \
+  [--wait] [--timeout-seconds <n>] \
+  --json
+
+warpmetal operation get \
+  --operation <operationId> \
+  [--server <serverId>] \
+  [--wait] [--timeout-seconds <n>] \
+  --json
+```
+
+Use `--token-file` only for recovery when local state is unavailable. Prefer
+`WARPMETAL_OWNER_TOKEN` or `WARPMETAL_ACCESS_TOKEN` for a single command over a
+shell argument, because command-line arguments can be recorded in history and
+process listings.
+
+## Skill installation and state
+
+```sh
+warpmetal agent install --target <codex|claude|all> [--scope user|project]
+warpmetal state list --json
+```
+
+`state list` returns identifiers and credential-presence booleans only. Never
+open the underlying state file from an agent session.
+
+## Exit codes
+
+- `0`: command completed or reached its requested safe stopping point.
+- `1`: unexpected local or API failure.
+- `2`: invalid command, option, input, or local state.
+- `3`: purchasing unavailable, rate limited, or API temporarily unavailable.
+- `4`: missing or rejected credential or SSH proof.
+- `5`: API conflict, including an idempotency conflict.
+- `6`: manual review; stop and do not retry the consequential action.
+- `7`: payment authorization rejected or required; inspect the live challenge.
+- `8`: operation still pending or wait timeout reached.

package/skills/warpmetal/references/safety.md

@@ -0,0 +1,55 @@
+# WarpMetal safety rules
+
+## Contents
+
+- Authority and freshness
+- Credential boundaries
+- Required confirmations
+- Retry and terminal-state rules
+
+## Authority and freshness
+
+- Treat `https://warpmetal.com/llms.txt`, the live catalog, and the live HTTP
+  402 challenge as authoritative in that order.
+- Stop new purchases when `warpmetal health --json` reports
+  `purchasingReady: false`.
+- Select an exact OS name from the chosen plan's current
+  `operatingSystems[]`. Never guess or hard-code an image version.
+
+## Credential boundaries
+
+- Treat the generated `ownerToken` as an offline recovery credential. Let the
+  CLI store it; never inspect the state file or include it in output.
+- Treat an SSH-derived access token as a short-lived bearer credential. Let
+  the CLI store and refresh it.
+- Never read or transmit an SSH private key. Pass only its filesystem path to
+  `warpmetal server login` or `ssh-keygen`.
+- Never request, read, transmit, or store a wallet seed phrase or private key.
+- Never put a token, payment signature, private key, or state-file content in
+  a prompt, URL, log, screenshot, source file, or shell argument.
+
+## Required confirmations
+
+Obtain explicit user approval immediately before:
+
+- installing the CLI or skill;
+- generating a new SSH key pair;
+- creating or funding a wallet;
+- signing or submitting an x402 payment authorization;
+- booting, rebooting, or shutting down a server; and
+- any destructive reload, deletion, or replacement-key operation.
+
+An order preparation is unpaid but consumes a limited prepared-order slot.
+Confirm the plan, hostname, OS, and public key before preparing it.
+
+## Retry and terminal-state rules
+
+- Reuse the same idempotency key only for the exact same logical request.
+- For `payment_pending`, retry the exact checkout body and the exact same
+  payment signature. Do not create a replacement payment.
+- A signed HTTP 402 rejects that signature. Use the new live challenge for one
+  replacement authorization.
+- Treat `manual_review` as terminal. Do not pay again and do not repeat the
+  mutation.
+- Treat HTTP 202 as accepted or pending, never as proof of success. Poll the
+  returned task or operation until a documented terminal state.

package/src/api.js

@@ -0,0 +1,170 @@
+import { ApiError, CliError } from "./errors.js";
+
+const DEFAULT_API_URL = "https://api.warpmetal.com";
+
+function validateBaseUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new CliError(`Invalid WarpMetal API URL: ${value}`, { exitCode: 2 });
+  }
+  const local = ["localhost", "127.0.0.1", "::1"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(local && url.protocol === "http:")) {
+    throw new CliError("WarpMetal API URLs must use HTTPS (HTTP is allowed for localhost).", {
+      exitCode: 2,
+    });
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new CliError("WarpMetal API URLs cannot contain credentials, query, or fragment data.", {
+      exitCode: 2,
+    });
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
+function parseResponseBody(text) {
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { message: text };
+  }
+}
+
+function headerMap(headers) {
+  return Object.fromEntries(headers.entries());
+}
+
+export class WarpMetalClient {
+  constructor({ baseUrl, fetchImpl = globalThis.fetch, timeoutMs = 30_000 } = {}) {
+    if (typeof fetchImpl !== "function") {
+      throw new CliError("This Node.js runtime does not provide fetch().", { exitCode: 2 });
+    }
+    this.baseUrl = validateBaseUrl(baseUrl || process.env.WARPMETAL_API_URL || DEFAULT_API_URL);
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = timeoutMs;
+  }
+
+  async request(
+    method,
+    path,
+    {
+      body,
+      bodyText,
+      token,
+      idempotencyKey,
+      paymentSignature,
+      acceptStatuses = [],
+    } = {},
+  ) {
+    const url = new URL(path, `${this.baseUrl}/`);
+    const headers = {
+      Accept: "application/json",
+      "User-Agent": "warpmetal-cli/0.1.0",
+    };
+    let requestBody;
+    if (bodyText !== undefined) {
+      requestBody = bodyText;
+      headers["Content-Type"] = "application/json";
+    } else if (body !== undefined) {
+      requestBody = JSON.stringify(body);
+      headers["Content-Type"] = "application/json";
+    }
+    if (token) headers.Authorization = `Bearer ${token}`;
+    if (idempotencyKey) headers["Idempotency-Key"] = idempotencyKey;
+    if (paymentSignature) headers["PAYMENT-SIGNATURE"] = paymentSignature;
+
+    let response;
+    try {
+      response = await this.fetchImpl(url, {
+        method,
+        headers,
+        body: requestBody,
+        signal: AbortSignal.timeout(this.timeoutMs),
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new CliError(`Could not reach ${url.origin}: ${message}`, { exitCode: 3 });
+    }
+
+    const text = await response.text();
+    const data = parseResponseBody(text);
+    const result = {
+      status: response.status,
+      data,
+      headers: headerMap(response.headers),
+      bodyText: text,
+    };
+    if (response.ok || acceptStatuses.includes(response.status)) return result;
+
+    const apiError = data?.error;
+    throw new ApiError(apiError?.message || `Request failed with HTTP ${response.status}.`, {
+      status: response.status,
+      code: apiError?.code,
+      retryAfter: response.headers.get("retry-after") || undefined,
+      body: data,
+    });
+  }
+
+  health() {
+    return this.request("GET", "/api/health");
+  }
+
+  catalog() {
+    return this.request("GET", "/api/catalog");
+  }
+
+  prepareOrder(body, idempotencyKey) {
+    return this.request("POST", "/api/orders", { body, idempotencyKey });
+  }
+
+  getTask(taskId, token) {
+    return this.request("GET", `/api/tasks/${encodeURIComponent(taskId)}`, { token });
+  }
+
+  checkout(path, { bodyText, token, paymentSignature }) {
+    return this.request("POST", path, {
+      bodyText,
+      token,
+      paymentSignature,
+      acceptStatuses: [402, 409],
+    });
+  }
+
+  issueSshChallenge(serverId) {
+    return this.request(
+      "POST",
+      `/api/servers/${encodeURIComponent(serverId)}/auth/challenges`,
+      { body: {} },
+    );
+  }
+
+  exchangeSshChallenge(serverId, challengeId, signature) {
+    return this.request(
+      "POST",
+      `/api/servers/${encodeURIComponent(serverId)}/auth/tokens`,
+      { body: { challengeId, signature } },
+    );
+  }
+
+  getServer(serverId, token) {
+    return this.request("GET", `/api/servers/${encodeURIComponent(serverId)}`, { token });
+  }
+
+  powerServer(serverId, action, token, idempotencyKey) {
+    return this.request("POST", `/api/servers/${encodeURIComponent(serverId)}/power`, {
+      body: { action },
+      token,
+      idempotencyKey,
+    });
+  }
+
+  getOperation(operationId, token) {
+    return this.request("GET", `/api/operations/${encodeURIComponent(operationId)}`, {
+      token,
+    });
+  }
+}
+
+export { DEFAULT_API_URL };

package/src/args.js

@@ -0,0 +1,78 @@
+import { CliError } from "./errors.js";
+
+export function parseArguments(argv) {
+  const positionals = [];
+  const options = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+    if (value === "--") {
+      positionals.push(...argv.slice(index + 1));
+      break;
+    }
+    if (!value.startsWith("--")) {
+      positionals.push(value);
+      continue;
+    }
+
+    if (value.startsWith("--no-")) {
+      options[value.slice(5)] = false;
+      continue;
+    }
+
+    const equals = value.indexOf("=");
+    if (equals !== -1) {
+      options[value.slice(2, equals)] = value.slice(equals + 1);
+      continue;
+    }
+
+    const name = value.slice(2);
+    const next = argv[index + 1];
+    if (next !== undefined && !next.startsWith("--")) {
+      options[name] = next;
+      index += 1;
+    } else {
+      options[name] = true;
+    }
+  }
+
+  return { positionals, options };
+}
+
+export function stringOption(options, name, { required = false } = {}) {
+  const value = options[name];
+  if (value === undefined && !required) return undefined;
+  if (typeof value !== "string" || value.length === 0) {
+    throw new CliError(`--${name} requires a value.`, { exitCode: 2 });
+  }
+  return value;
+}
+
+export function booleanOption(options, name) {
+  const value = options[name];
+  if (value === undefined) return false;
+  if (typeof value !== "boolean") {
+    throw new CliError(`--${name} does not take a value.`, { exitCode: 2 });
+  }
+  return value;
+}
+
+export function integerOption(options, name, fallback) {
+  const value = options[name];
+  if (value === undefined) return fallback;
+  if (typeof value !== "string" || !/^[1-9]\d*$/.test(value)) {
+    throw new CliError(`--${name} must be a positive integer.`, { exitCode: 2 });
+  }
+  const number = Number(value);
+  if (!Number.isSafeInteger(number)) {
+    throw new CliError(`--${name} is too large.`, { exitCode: 2 });
+  }
+  return number;
+}
+
+export function rejectUnknownOptions(options, allowed) {
+  const unknown = Object.keys(options).filter((name) => !allowed.includes(name));
+  if (unknown.length > 0) {
+    throw new CliError(`Unknown option: --${unknown[0]}`, { exitCode: 2 });
+  }
+}