run402 1.0.0

package/cli.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * run402 — CLI for Run402
+ * https://run402.com
+ */
+
+const [,, cmd, sub, ...rest] = process.argv;
+
+const HELP = `run402 v1.0.0 — Full-stack backend infra for AI agents
+https://run402.com
+
+Usage:
+  run402 <command> [subcommand] [options]
+
+Commands:
+  wallet    Manage your x402 wallet (create, fund, check status)
+  projects  Manage deployed projects (list, query, inspect, renew, delete)
+  deploy    Deploy a full-stack app or static site (Postgres + hosting)
+  image     Generate AI images via x402 micropayments
+
+Run 'run402 <command> --help' for detailed usage of each command.
+
+Examples:
+  run402 wallet create
+  run402 wallet fund
+  run402 deploy --tier prototype --manifest app.json
+  run402 projects list
+  run402 projects sql <project_id> "SELECT * FROM users LIMIT 5"
+  run402 image generate "a startup mascot, pixel art" --output logo.png
+
+Getting started:
+  1. run402 wallet create    Create a local wallet
+  2. run402 wallet fund      Fund it with test USDC (Base Sepolia faucet)
+  3. run402 deploy ...       Deploy your app — payments handled automatically
+`;
+
+if (!cmd || cmd === '--help' || cmd === '-h') {
+  console.log(HELP);
+  process.exit(cmd ? 0 : 0);
+}
+
+switch (cmd) {
+  case "wallet": {
+    const { run } = await import("./lib/wallet.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "projects": {
+    const { run } = await import("./lib/projects.mjs");
+    await run(sub, rest);
+    break;
+  }
+  case "deploy": {
+    const { run } = await import("./lib/deploy.mjs");
+    await run([sub, ...rest].filter(Boolean));
+    break;
+  }
+  case "image": {
+    const { run } = await import("./lib/image.mjs");
+    await run(sub, rest);
+    break;
+  }
+  default:
+    console.error(`Unknown command: ${cmd}\n`);
+    console.log(HELP);
+    process.exit(1);
+}

package/lib/config.mjs

@@ -0,0 +1,40 @@
+/**
+ * Run402 config loader — reads local project and wallet state.
+ * Kept in a separate module so credential reads stay isolated.
+ */
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+
+export const CONFIG_DIR = join(homedir(), ".config", "run402");
+export const WALLET_FILE = join(CONFIG_DIR, "wallet.json");
+export const PROJECTS_FILE = join(CONFIG_DIR, "projects.json");
+export const API = "https://api.run402.com";
+
+export function readWallet() {
+  if (!existsSync(WALLET_FILE)) return null;
+  return JSON.parse(readFileSync(WALLET_FILE, "utf-8"));
+}
+
+export function saveWallet(data) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(WALLET_FILE, JSON.stringify(data, null, 2), { mode: 0o600 });
+  try { chmodSync(WALLET_FILE, 0o600); } catch {}
+}
+
+export function loadProjects() {
+  if (!existsSync(PROJECTS_FILE)) return [];
+  return JSON.parse(readFileSync(PROJECTS_FILE, "utf-8"));
+}
+
+export function saveProjects(projects) {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(PROJECTS_FILE, JSON.stringify(projects, null, 2), { mode: 0o600 });
+}
+
+export function findProject(id) {
+  const p = loadProjects().find(p => p.project_id === id);
+  if (!p) { console.error(`Project ${id} not found in local registry.`); process.exit(1); }
+  return p;
+}

package/lib/deploy.mjs

@@ -0,0 +1,92 @@
+import { readFileSync, existsSync, mkdirSync, writeFileSync } from "fs";
+import { readWallet, loadProjects, API, WALLET_FILE, PROJECTS_FILE } from "./config.mjs";
+
+const HELP = `run402 deploy — Deploy a full-stack app or static site on Run402
+
+Usage:
+  run402 deploy [options]
+  cat manifest.json | run402 deploy [options]
+
+Options:
+  --tier <tier>        Deployment tier: prototype | hobby | team  (default: prototype)
+  --manifest <file>    Path to manifest JSON file  (default: read from stdin)
+  --help, -h           Show this help message
+
+Tiers:
+  prototype   Smallest, cheapest — great for demos and experiments
+  hobby       Mid-tier — personal projects and side hustles
+  team        Full power — production-ready, shared team access
+
+Manifest format (JSON):
+  {
+    "name": "my-app",
+    "files": {
+      "index.html": "<html>...</html>",
+      "style.css": "body { margin: 0; }"
+    },
+    "env": {
+      "MY_VAR": "value"
+    }
+  }
+
+Examples:
+  run402 deploy --tier prototype --manifest app.json
+  run402 deploy --tier hobby --manifest app.json
+  cat app.json | run402 deploy --tier team
+
+Notes:
+  - Requires a funded wallet (run402 wallet create && run402 wallet fund)
+  - Payments are processed automatically via x402 micropayments (Base Sepolia USDC)
+  - Project credentials (project_id, keys, URL) are saved locally after deploy
+  - Use 'run402 projects list' to see all deployed projects
+`;
+
+async function readStdin() {
+  const chunks = [];
+  for await (const chunk of process.stdin) chunks.push(chunk);
+  return Buffer.concat(chunks).toString("utf-8");
+}
+
+function saveProject(project) {
+  const projects = loadProjects();
+  projects.push({ project_id: project.project_id, anon_key: project.anon_key, service_key: project.service_key, tier: project.tier, lease_expires_at: project.lease_expires_at, site_url: project.site_url || project.subdomain_url, deployed_at: new Date().toISOString() });
+  const dir = PROJECTS_FILE.replace(/\/[^/]+$/, "");
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(PROJECTS_FILE, JSON.stringify(projects, null, 2), { mode: 0o600 });
+}
+
+export async function run(args) {
+  const opts = { tier: "prototype", manifest: null };
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === "--help" || args[i] === "-h") { console.log(HELP); process.exit(0); }
+    if (args[i] === "--tier" && args[i + 1]) opts.tier = args[++i];
+    if (args[i] === "--manifest" && args[i + 1]) opts.manifest = args[++i];
+  }
+
+  if (!existsSync(WALLET_FILE)) {
+    console.error(JSON.stringify({ status: "error", message: "No wallet found. Run: run402 wallet create && run402 wallet fund" }));
+    process.exit(1);
+  }
+  const wallet = readWallet();
+  const manifest = opts.manifest ? JSON.parse(readFileSync(opts.manifest, "utf-8")) : JSON.parse(await readStdin());
+
+  const { privateKeyToAccount } = await import("viem/accounts");
+  const { createPublicClient, http } = await import("viem");
+  const { baseSepolia } = await import("viem/chains");
+  const { x402Client, wrapFetchWithPayment } = await import("@x402/fetch");
+  const { ExactEvmScheme } = await import("@x402/evm/exact/client");
+  const { toClientEvmSigner } = await import("@x402/evm");
+
+  const account = privateKeyToAccount(wallet.privateKey);
+  const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
+  const signer = toClientEvmSigner(account, publicClient);
+  const client = new x402Client();
+  client.register("eip155:84532", new ExactEvmScheme(signer));
+  const fetchPaid = wrapFetchWithPayment(fetch, client);
+
+  const res = await fetchPaid(`${API}/v1/deploy/${opts.tier}`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(manifest) });
+  const result = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...result })); process.exit(1); }
+  saveProject(result);
+  console.log(JSON.stringify(result, null, 2));
+}

package/lib/image.mjs

@@ -0,0 +1,80 @@
+import { writeFileSync, existsSync } from "fs";
+import { readWallet, API, WALLET_FILE } from "./config.mjs";
+
+const HELP = `run402 image — Generate AI images via x402 micropayments
+
+Usage:
+  run402 image generate "<prompt>" [options]
+
+Options:
+  --aspect <ratio>    Image aspect ratio: square | landscape | portrait  (default: square)
+  --output <file>     Save image to file (e.g. output.png)
+                      If omitted, returns base64 JSON to stdout
+  --help, -h          Show this help message
+
+Examples:
+  run402 image generate "a startup mascot, pixel art"
+  run402 image generate "futuristic city at night" --aspect landscape
+  run402 image generate "portrait of a cat CEO" --aspect portrait --output cat.png
+
+Output (without --output):
+  { "status": "ok", "aspect": "square", "content_type": "image/png", "image": "<base64>" }
+
+Notes:
+  - Requires a funded wallet (run402 wallet create && run402 wallet fund)
+  - Payments are processed automatically via x402 micropayments (Base Sepolia USDC)
+  - Use --output to save directly to a file instead of printing base64
+`;
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  if (sub !== "generate") {
+    console.error(`Unknown subcommand: ${sub}\n`);
+    console.log(HELP);
+    process.exit(1);
+  }
+
+  const opts = { prompt: null, aspect: "square", output: null };
+  let i = 0;
+  if (i < args.length && !args[i].startsWith("--")) opts.prompt = args[i++];
+  while (i < args.length) {
+    if (args[i] === "--help" || args[i] === "-h") { console.log(HELP); process.exit(0); }
+    else if (args[i] === "--aspect" && args[i + 1]) { opts.aspect = args[++i]; }
+    else if (args[i] === "--output" && args[i + 1]) { opts.output = args[++i]; }
+    i++;
+  }
+
+  if (!opts.prompt) { console.error(JSON.stringify({ status: "error", message: "Prompt required. Usage: run402 image generate \"your prompt\"" })); process.exit(1); }
+  if (!existsSync(WALLET_FILE)) { console.error(JSON.stringify({ status: "error", message: "No wallet found. Run: run402 wallet create && run402 wallet fund" })); process.exit(1); }
+
+  const wallet = readWallet();
+  const { privateKeyToAccount } = await import("viem/accounts");
+  const { createPublicClient, http } = await import("viem");
+  const { baseSepolia } = await import("viem/chains");
+  const { x402Client, wrapFetchWithPayment } = await import("@x402/fetch");
+  const { ExactEvmScheme } = await import("@x402/evm/exact/client");
+  const { toClientEvmSigner } = await import("@x402/evm");
+
+  const account = privateKeyToAccount(wallet.privateKey);
+  const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
+  const signer = toClientEvmSigner(account, publicClient);
+  const client = new x402Client();
+  client.register("eip155:84532", new ExactEvmScheme(signer));
+  const fetchPaid = wrapFetchWithPayment(fetch, client);
+
+  const res = await fetchPaid(`${API}/v1/generate-image`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ prompt: opts.prompt, aspect: opts.aspect }) });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+
+  if (opts.output) {
+    const buf = Buffer.from(data.image, "base64");
+    writeFileSync(opts.output, buf);
+    console.log(JSON.stringify({ status: "ok", file: opts.output, size: buf.length, aspect: data.aspect }));
+  } else {
+    console.log(JSON.stringify({ status: "ok", aspect: data.aspect, content_type: data.content_type, image: data.image }));
+  }
+}

package/lib/projects.mjs

@@ -0,0 +1,128 @@
+import { findProject, loadProjects, saveProjects, readWallet, API, WALLET_FILE } from "./config.mjs";
+import { existsSync } from "fs";
+
+const HELP = `run402 projects — Manage your deployed Run402 projects
+
+Usage:
+  run402 projects <subcommand> [args...]
+
+Subcommands:
+  list                           List all your projects (IDs, tiers, URLs, expiry)
+  sql   <id> "<query>"           Run a SQL query against a project's Postgres DB
+  rest  <id> <table> [params]    Query a table via the REST API (PostgREST)
+  usage <id>                     Show compute/storage usage for a project
+  schema <id>                    Inspect the database schema
+  renew <id>                     Extend the project lease (pays via x402)
+  delete <id>                    Delete a project and remove it from local state
+
+Examples:
+  run402 projects list
+  run402 projects sql abc123 "SELECT * FROM users LIMIT 5"
+  run402 projects rest abc123 users "limit=10&select=id,name"
+  run402 projects usage abc123
+  run402 projects schema abc123
+  run402 projects renew abc123
+  run402 projects delete abc123
+
+Notes:
+  - <id> is the project_id shown in 'run402 projects list'
+  - 'rest' uses PostgREST query syntax (table name + optional query string)
+  - 'renew' requires a funded wallet — payment is automatic via x402
+`;
+
+async function setupPaidFetch() {
+  if (!existsSync(WALLET_FILE)) {
+    console.error(JSON.stringify({ status: "error", message: "No wallet found. Run: run402 wallet create && run402 wallet fund" }));
+    process.exit(1);
+  }
+  const wallet = readWallet();
+  const { privateKeyToAccount } = await import("viem/accounts");
+  const { createPublicClient, http } = await import("viem");
+  const { baseSepolia } = await import("viem/chains");
+  const { x402Client, wrapFetchWithPayment } = await import("@x402/fetch");
+  const { ExactEvmScheme } = await import("@x402/evm/exact/client");
+  const { toClientEvmSigner } = await import("@x402/evm");
+  const account = privateKeyToAccount(wallet.privateKey);
+  const publicClient = createPublicClient({ chain: baseSepolia, transport: http() });
+  const signer = toClientEvmSigner(account, publicClient);
+  const client = new x402Client();
+  client.register("eip155:84532", new ExactEvmScheme(signer));
+  return wrapFetchWithPayment(fetch, client);
+}
+
+async function list() {
+  const projects = loadProjects();
+  if (projects.length === 0) { console.log(JSON.stringify({ status: "ok", projects: [], message: "No projects yet." })); return; }
+  console.log(JSON.stringify(projects.map(p => ({ project_id: p.project_id, tier: p.tier, site_url: p.site_url, lease_expires_at: p.lease_expires_at, deployed_at: p.deployed_at })), null, 2));
+}
+
+async function sqlCmd(projectId, query) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/sql`, { method: "POST", headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "text/plain" }, body: query });
+  console.log(JSON.stringify(await res.json(), null, 2));
+}
+
+async function rest(projectId, table, queryParams) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/rest/v1/${table}${queryParams ? '?' + queryParams : ''}`, { headers: { "apikey": p.anon_key } });
+  console.log(JSON.stringify(await res.json(), null, 2));
+}
+
+async function usage(projectId) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/usage`, { headers: { "Authorization": `Bearer ${p.service_key}` } });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function schema(projectId) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/admin/v1/projects/${projectId}/schema`, { headers: { "Authorization": `Bearer ${p.service_key}` } });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function renew(projectId) {
+  const fetchPaid = await setupPaidFetch();
+  const res = await fetchPaid(`${API}/v1/projects/${projectId}/renew`, { method: "POST", headers: { "Content-Type": "application/json" } });
+  const data = await res.json();
+  if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
+  const projects = loadProjects();
+  const idx = projects.findIndex(pr => pr.project_id === projectId);
+  if (idx >= 0 && data.lease_expires_at) { projects[idx].lease_expires_at = data.lease_expires_at; saveProjects(projects); }
+  console.log(JSON.stringify(data, null, 2));
+}
+
+async function deleteProject(projectId) {
+  const p = findProject(projectId);
+  const res = await fetch(`${API}/v1/projects/${projectId}`, { method: "DELETE", headers: { "Authorization": `Bearer ${p.service_key}` } });
+  if (res.status === 204 || res.ok) {
+    saveProjects(loadProjects().filter(pr => pr.project_id !== projectId));
+    console.log(JSON.stringify({ status: "ok", message: `Project ${projectId} deleted.` }));
+  } else {
+    const data = await res.json().catch(() => ({}));
+    console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1);
+  }
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') {
+    console.log(HELP);
+    process.exit(0);
+  }
+  switch (sub) {
+    case "list":   await list(); break;
+    case "sql":    await sqlCmd(args[0], args[1]); break;
+    case "rest":   await rest(args[0], args[1], args[2]); break;
+    case "usage":  await usage(args[0]); break;
+    case "schema": await schema(args[0]); break;
+    case "renew":  await renew(args[0]); break;
+    case "delete": await deleteProject(args[0]); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/lib/wallet.mjs

@@ -0,0 +1,89 @@
+import { readWallet, saveWallet, API } from "./config.mjs";
+
+const HELP = `run402 wallet — Manage your x402 wallet
+
+Usage:
+  run402 wallet <subcommand>
+
+Subcommands:
+  status    Show wallet address, network, and funding status
+  create    Generate a new wallet and save it locally
+  fund      Request test USDC from the Run402 faucet (Base Sepolia)
+  export    Print the wallet address (useful for scripting)
+
+Notes:
+  - Wallet is stored locally at ~/.run402/wallet.json
+  - Network: Base Sepolia (testnet) — uses USDC for x402 payments
+  - You need to create and fund a wallet before deploying or generating images
+
+Examples:
+  run402 wallet create
+  run402 wallet status
+  run402 wallet fund
+  run402 wallet export
+`;
+
+async function loadDeps() {
+  const { generatePrivateKey, privateKeyToAccount } = await import("viem/accounts");
+  const { createPublicClient, http } = await import("viem");
+  const { baseSepolia } = await import("viem/chains");
+  return { generatePrivateKey, privateKeyToAccount, createPublicClient, http, baseSepolia };
+}
+
+async function status() {
+  const w = readWallet();
+  if (!w) {
+    console.log(JSON.stringify({ status: "no_wallet", message: "No wallet found. Run: run402 wallet create" }));
+    return;
+  }
+  console.log(JSON.stringify({ status: "ok", address: w.address, network: w.network || "base-sepolia", created: w.created, funded: w.funded || false }));
+}
+
+async function create() {
+  if (readWallet()) {
+    console.log(JSON.stringify({ status: "error", message: "Wallet already exists. Use 'status' to check it." }));
+    process.exit(1);
+  }
+  const { generatePrivateKey, privateKeyToAccount } = await loadDeps();
+  const privateKey = generatePrivateKey();
+  const account = privateKeyToAccount(privateKey);
+  saveWallet({ address: account.address, privateKey, network: "base-sepolia", created: new Date().toISOString(), funded: false });
+  console.log(JSON.stringify({ status: "ok", address: account.address, message: "Wallet created and saved." }));
+}
+
+async function fund() {
+  const w = readWallet();
+  if (!w) { console.log(JSON.stringify({ status: "error", message: "No wallet. Run: run402 wallet create" })); process.exit(1); }
+  const res = await fetch(`${API}/v1/faucet`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ address: w.address }) });
+  const data = await res.json();
+  if (res.ok) {
+    saveWallet({ ...w, funded: true, lastFaucet: new Date().toISOString() });
+    console.log(JSON.stringify({ status: "ok", ...data }));
+  } else {
+    console.log(JSON.stringify({ status: "error", ...data }));
+    process.exit(1);
+  }
+}
+
+async function exportAddr() {
+  const w = readWallet();
+  if (!w) { console.log(JSON.stringify({ status: "error", message: "No wallet." })); process.exit(1); }
+  console.log(w.address);
+}
+
+export async function run(sub, args) {
+  if (!sub || sub === '--help' || sub === '-h') {
+    console.log(HELP);
+    process.exit(0);
+  }
+  switch (sub) {
+    case "status": await status(); break;
+    case "create": await create(); break;
+    case "fund":   await fund(); break;
+    case "export": await exportAddr(); break;
+    default:
+      console.error(`Unknown subcommand: ${sub}\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "run402",
+  "version": "1.0.0",
+  "description": "CLI for Run402 — provision Postgres databases, deploy static sites, generate images, and manage wallets via x402 micropayments.",
+  "type": "module",
+  "bin": {
+    "run402": "cli.mjs"
+  },
+  "files": [
+    "cli.mjs",
+    "lib/"
+  ],
+  "dependencies": {
+    "@x402/evm": "^2.6.0",
+    "@x402/fetch": "^2.6.0",
+    "viem": "^2.47.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "homepage": "https://run402.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kychee-com/run402-mcp.git",
+    "directory": "cli"
+  },
+  "keywords": [
+    "run402",
+    "x402",
+    "postgres",
+    "ai-agent",
+    "openclaw"
+  ]
+}