Extract shared core/ module from MCP/CLI/OpenClaw

Move duplicated logic (config, wallet, wallet-auth, keystore, API client)
into core/src/ so each interface is a thin presentation layer.

- core/src/config.ts: path resolution and env vars
- core/src/wallet.ts: read/write wallet.json with atomic writes
- core/src/wallet-auth.ts: EIP-191 signing via @noble/curves
- core/src/keystore.ts: unified object-based keystore with auto-migration
  from legacy array format and expires_at → lease_expires_at rename
- core/src/client.ts: apiRequest() fetch wrapper

MCP src/ files become thin re-exports from core. CLI config.mjs imports
from core with process.exit wrappers. OpenClaw scripts become one-line
re-exports from CLI modules (-1,771 lines). Shared paid-fetch.mjs
deduplicates x402 payment setup across tier and image commands.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: MajorTal

CLAUDE.md

@@ -8,50 +8,81 @@ run402-mcp is an MCP (Model Context Protocol) server that exposes Run402 develop
 
 - **MCP server** (root `src/`) — the main package, published as `run402-mcp` on npm
 - **CLI** (`cli/`) — standalone CLI published as `run402` on npm, uses `@x402/fetch` for payments
-- **OpenClaw skill** (`openclaw/`) — skill for OpenClaw agents, calls the API via Node.js scripts
+- **OpenClaw skill** (`openclaw/`) — skill for OpenClaw agents, thin shims over CLI modules
+
+All three share core logic via the `core/` module.
 
 ## Build & Test Commands
 
 ```bash
-npm run build          # tsc → dist/
+npm run build:core     # tsc -p core/tsconfig.json → core/dist/
+npm run build          # build:core + tsc → dist/
 npm run start          # node dist/index.js (stdio MCP transport)
 npm run test:skill     # node --test --import tsx SKILL.test.ts (validates SKILL.md frontmatter/body)
 npm run test:sync      # node --test --import tsx sync.test.ts (checks MCP/CLI/OpenClaw stay in sync)
-npm test               # runs all tests (SKILL.test.ts + sync.test.ts + src/**/*.test.ts)
+npm test               # runs all tests (SKILL.test.ts + sync.test.ts + core/src/**/*.test.ts + src/**/*.test.ts)
+npm run test:e2e       # node --test cli-e2e.test.mjs (47 CLI end-to-end tests)
 ```
 
 Unit tests use Node's built-in `node:test` runner with `tsx` for TypeScript:
 
 ```bash
 # Run all unit tests
-node --test --import tsx src/**/*.test.ts
+node --test --import tsx core/src/**/*.test.ts src/**/*.test.ts
 
 # Run a single test file
 node --test --import tsx src/tools/run-sql.test.ts
-node --test --import tsx src/client.test.ts
+node --test --import tsx core/src/keystore.test.ts
 ```
 
-Tests are excluded from the build (`tsconfig.json` excludes `src/**/*.test.ts`).
+Tests are excluded from the build (`tsconfig.json` and `core/tsconfig.json` both exclude `**/*.test.ts`).
 
 ### Sync Test (`sync.test.ts`)
 
 `sync.test.ts` defines the canonical API surface in a `SURFACE` array and checks:
 - MCP tools in `src/index.ts` match the expected set (no missing, no extra)
 - CLI commands in `cli/lib/*.mjs` match the expected set
-- OpenClaw commands in `openclaw/scripts/*.mjs` match the expected set
+- OpenClaw commands in `openclaw/scripts/*.mjs` match the expected set (follows re-exports to CLI)
 - CLI and OpenClaw have identical command sets (parity)
 - If `~/dev/run402/site/llms.txt` exists: MCP Tools table lists all tools, all endpoints documented
 
 When adding a new tool/command, add it to the `SURFACE` array in `sync.test.ts`.
 
 ## Architecture
 
-### Core Modules (`src/`)
+### Shared Core (`core/src/`)
+
+The `core/` module contains shared logic imported by all three interfaces:
+
+- **`config.ts`** — Path resolution and env vars: `getApiBase()`, `getConfigDir()`, `getKeystorePath()`, `getWalletPath()`.
+- **`wallet.ts`** — `readWallet()`, `saveWallet()` with atomic writes (temp-file + rename, mode 0600).
+- **`wallet-auth.ts`** — EIP-191 signing with `@noble/curves`. `getWalletAuthHeaders()` returns headers or null.
+- **`keystore.ts`** — Unified project credential store. Object schema: `{projects: {id: {anon_key, service_key, tier, lease_expires_at}}}`. Auto-migrates legacy array format and `expires_at` → `lease_expires_at`. Functions: `loadKeyStore()`, `saveKeyStore()`, `getProject()`, `saveProject()`, `removeProject()`.
+- **`client.ts`** — `apiRequest()` fetch wrapper. Handles JSON/text responses, 402 payment detection.
+
+Core functions return `null` or throw — they never call `process.exit()`. Each interface wraps with its own error behavior.
+
+### MCP Server (`src/`)
+
+Thin re-export layer over `core/dist/` plus MCP-specific wrappers:
+
+- **`config.ts`**, **`client.ts`**, **`keystore.ts`**, **`wallet.ts`** — re-export from core
+- **`wallet-auth.ts`** — re-exports core's `getWalletAuthHeaders()` + adds `requireWalletAuth()` which returns MCP error shape
+- **`errors.ts`** — MCP-specific error formatting (`formatApiError`, `projectNotFound`)
+- **`index.ts`** — Entry point. Registers all tools via `McpServer`.
+- **`tools/*.ts`** — Each tool exports a Zod schema + async handler
+
+### CLI (`cli/`)
+
+- **`cli/lib/config.mjs`** — Imports from `core/dist/`, adds CLI wrappers (`walletAuthHeaders()` with process.exit, `findProject()` with process.exit). Re-exports core keystore functions.
+- **`cli/lib/paid-fetch.mjs`** — Shared `setupPaidFetch()` using viem + @x402/fetch for paid endpoints.
+- **`cli/lib/*.mjs`** — Each module exports `async run(sub, args)` with CLI output format.
+
+### OpenClaw (`openclaw/`)
 
-- **`index.ts`** — Entry point. Creates the `McpServer`, registers all tools with their Zod schemas and handlers, connects via `StdioServerTransport`.
-- **`client.ts`** — Single `apiRequest()` function wrapping `fetch()` against `RUN402_API_BASE`. Handles JSON/text responses and identifies 402 (payment required) responses with `is402` flag.
-- **`config.ts`** — Reads `RUN402_API_BASE` (default `https://api.run402.com`) and `RUN402_CONFIG_DIR` (default `~/.config/run402`) from env.
-- **`keystore.ts`** — Atomic file-based credential store at `~/.config/run402/projects.json` (mode 0600). Uses temp-file + rename for safe writes.
+- **`openclaw/scripts/config.mjs`** — Re-exports from `cli/lib/config.mjs`
+- **`openclaw/scripts/*.mjs`** — Thin shims: `export { run } from "../../cli/lib/<name>.mjs"`
+- **`openclaw/scripts/init.mjs`** — Calls CLI's `run()` at top level (executable script)
 
 ### Tool Pattern
 

cli-e2e.test.mjs

@@ -447,9 +447,9 @@ describe("CLI e2e happy path", () => {
     await run("provision", ["--tier", "prototype"]);
     captureStop();
     assert.ok(captured().includes("prj_test123"), "should return project_id");
-    // Verify project saved locally
-    const projects = JSON.parse(readFileSync(join(tempDir, "projects.json"), "utf-8"));
-    assert.ok(projects.some(p => p.project_id === "prj_test123"), "project should be saved locally");
+    // Verify project saved locally (unified object-based keystore format)
+    const store = JSON.parse(readFileSync(join(tempDir, "projects.json"), "utf-8"));
+    assert.ok(store.projects && store.projects["prj_test123"], "project should be saved locally");
   });
 
   it("projects list", async () => {

cli/lib/apps.mjs

@@ -1,5 +1,4 @@
-import { findProject, loadProjects, saveProjects, API, PROJECTS_FILE, walletAuthHeaders } from "./config.mjs";
-import { mkdirSync, writeFileSync } from "fs";
+import { findProject, API, walletAuthHeaders, saveProject } from "./config.mjs";
 
 const HELP = `run402 apps — Browse and manage the app marketplace
 
@@ -63,15 +62,12 @@ async function fork(versionId, name, args) {
 
   // Save project credentials locally
   if (data.project_id) {
-    const projects = loadProjects();
-    projects.push({
-      project_id: data.project_id, anon_key: data.anon_key, service_key: data.service_key,
+    saveProject(data.project_id, {
+      anon_key: data.anon_key, service_key: data.service_key,
       tier: data.tier, lease_expires_at: data.lease_expires_at,
-      site_url: data.site_url || data.subdomain_url, deployed_at: new Date().toISOString(),
+      site_url: data.site_url || data.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 });
   }
   console.log(JSON.stringify(data, null, 2));
 }

cli/lib/config.mjs

@@ -1,53 +1,37 @@
 /**
- * Run402 config loader — reads local project and wallet state.
- * Kept in a separate module so credential reads stay isolated.
+ * Run402 config loader — thin wrapper over core/ shared modules.
+ * Adds CLI-specific behavior: process.exit() on errors.
  */
 
-import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync, renameSync } from "fs";
-import { join, dirname } from "path";
-import { homedir } from "os";
-import { randomBytes } from "crypto";
+import { getApiBase, getConfigDir, getKeystorePath, getWalletPath } from "../../core/dist/config.js";
+import { readWallet as coreReadWallet, saveWallet as coreSaveWallet } from "../../core/dist/wallet.js";
+import { getWalletAuthHeaders } from "../../core/dist/wallet-auth.js";
+import { loadKeyStore, getProject, saveProject, removeProject, saveKeyStore } from "../../core/dist/keystore.js";
 
-export const CONFIG_DIR = process.env.RUN402_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 = process.env.RUN402_API_BASE || "https://api.run402.com";
+export const CONFIG_DIR = getConfigDir();
+export const WALLET_FILE = getWalletPath();
+export const PROJECTS_FILE = getKeystorePath();
+export const API = getApiBase();
 
 export function readWallet() {
-  if (!existsSync(WALLET_FILE)) return null;
-  return JSON.parse(readFileSync(WALLET_FILE, "utf-8"));
+  return coreReadWallet();
 }
 
 export function saveWallet(data) {
-  mkdirSync(CONFIG_DIR, { recursive: true });
-  const tmp = join(CONFIG_DIR, `.wallet.${randomBytes(4).toString("hex")}.tmp`);
-  writeFileSync(tmp, JSON.stringify(data, null, 2), { mode: 0o600 });
-  renameSync(tmp, WALLET_FILE);
-  chmodSync(WALLET_FILE, 0o600);
-}
-
-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 });
+  coreSaveWallet(data);
 }
 
 export async function walletAuthHeaders() {
-  const w = readWallet();
-  if (!w) { console.error(JSON.stringify({ status: "error", message: "No wallet found. Run: run402 wallet create" })); process.exit(1); }
-  const { privateKeyToAccount } = await import("viem/accounts");
-  const account = privateKeyToAccount(w.privateKey);
-  const timestamp = Math.floor(Date.now() / 1000).toString();
-  const signature = await account.signMessage({ message: `run402:${timestamp}` });
-  return { "X-Run402-Wallet": account.address, "X-Run402-Signature": signature, "X-Run402-Timestamp": timestamp };
+  const headers = getWalletAuthHeaders();
+  if (!headers) { console.error(JSON.stringify({ status: "error", message: "No wallet found. Run: run402 wallet create" })); process.exit(1); }
+  return headers;
 }
 
 export function findProject(id) {
-  const p = loadProjects().find(p => p.project_id === id);
+  const p = getProject(id);
   if (!p) { console.error(`Project ${id} not found in local registry.`); process.exit(1); }
   return p;
 }
+
+// Re-export core keystore functions for direct use
+export { loadKeyStore, saveProject, removeProject, saveKeyStore };

cli/lib/deploy.mjs

@@ -1,5 +1,5 @@
-import { readFileSync, mkdirSync, writeFileSync } from "fs";
-import { loadProjects, API, PROJECTS_FILE, walletAuthHeaders } from "./config.mjs";
+import { readFileSync } from "fs";
+import { API, walletAuthHeaders, saveProject } from "./config.mjs";
 
 const HELP = `run402 deploy — Deploy a full-stack app or static site on Run402
 
@@ -39,14 +39,6 @@ async function readStdin() {
   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 = { manifest: null };
   for (let i = 0; i < args.length; i++) {
@@ -60,6 +52,13 @@ export async function run(args) {
   const res = await fetch(`${API}/deploy/v1`, { method: "POST", headers: { "Content-Type": "application/json", ...authHeaders }, 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);
+  if (result.project_id) {
+    saveProject(result.project_id, {
+      anon_key: result.anon_key, service_key: result.service_key,
+      tier: result.tier, lease_expires_at: result.lease_expires_at,
+      site_url: result.site_url || result.subdomain_url,
+      deployed_at: new Date().toISOString(),
+    });
+  }
   console.log(JSON.stringify(result, null, 2));
 }

cli/lib/image.mjs

@@ -1,5 +1,6 @@
-import { writeFileSync, existsSync } from "fs";
-import { readWallet, API, WALLET_FILE } from "./config.mjs";
+import { writeFileSync } from "fs";
+import { API, WALLET_FILE } from "./config.mjs";
+import { setupPaidFetch } from "./paid-fetch.mjs";
 
 const HELP = `run402 image — Generate AI images via x402 micropayments
 
@@ -49,22 +50,8 @@ export async function run(sub, args) {
   }
 
   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 fetchPaid = await setupPaidFetch();
 
   const res = await fetchPaid(`${API}/generate-image/v1`, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify({ prompt: opts.prompt, aspect: opts.aspect }) });
   const data = await res.json();

cli/lib/init.mjs

@@ -1,4 +1,4 @@
-import { readWallet, saveWallet, loadProjects, CONFIG_DIR, WALLET_FILE, API } from "./config.mjs";
+import { readWallet, saveWallet, loadKeyStore, CONFIG_DIR, WALLET_FILE, API } from "./config.mjs";
 import { mkdirSync } from "fs";
 
 const USDC_ABI = [{ name: "balanceOf", type: "function", stateMutability: "view", inputs: [{ name: "account", type: "address" }], outputs: [{ name: "", type: "uint256" }] }];
@@ -91,8 +91,8 @@ export async function run() {
   }
 
   // 5. Projects
-  const projects = loadProjects();
-  line("Projects", `${projects.length} active`);
+  const store = loadKeyStore();
+  line("Projects", `${Object.keys(store.projects).length} active`);
 
   // 6. Next step
   console.log();

cli/lib/paid-fetch.mjs

@@ -0,0 +1,27 @@
+/**
+ * Shared x402 payment wrapper for CLI commands that need paid fetch.
+ * Uses viem for wallet signing + @x402/fetch for payment wrapping.
+ */
+
+import { readWallet, WALLET_FILE } from "./config.mjs";
+import { existsSync } from "fs";
+
+export 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);
+}

cli/lib/projects.mjs

@@ -1,5 +1,4 @@
-import { findProject, loadProjects, saveProjects, API, PROJECTS_FILE, walletAuthHeaders } from "./config.mjs";
-import { mkdirSync, writeFileSync } from "fs";
+import { findProject, loadKeyStore, saveProject, removeProject, API, walletAuthHeaders } from "./config.mjs";
 
 const HELP = `run402 projects — Manage your deployed Run402 projects
 
@@ -61,14 +60,11 @@ async function provision(args) {
   if (!res.ok) { console.error(JSON.stringify({ status: "error", http: res.status, ...data })); process.exit(1); }
   // Save project credentials locally
   if (data.project_id) {
-    const projects = loadProjects();
-    projects.push({
-      project_id: data.project_id, anon_key: data.anon_key, service_key: data.service_key,
-      tier: data.tier, lease_expires_at: data.lease_expires_at, deployed_at: new Date().toISOString(),
+    saveProject(data.project_id, {
+      anon_key: data.anon_key, service_key: data.service_key,
+      tier: data.tier, lease_expires_at: data.lease_expires_at,
+      deployed_at: new Date().toISOString(),
     });
-    const dir = PROJECTS_FILE.replace(/\/[^/]+$/, "");
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(PROJECTS_FILE, JSON.stringify(projects, null, 2), { mode: 0o600 });
   }
   console.log(JSON.stringify(data, null, 2));
 }
@@ -87,9 +83,10 @@ async function rls(projectId, template, tablesJson) {
 }
 
 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));
+  const store = loadKeyStore();
+  const entries = Object.entries(store.projects);
+  if (entries.length === 0) { console.log(JSON.stringify({ status: "ok", projects: [], message: "No projects yet." })); return; }
+  console.log(JSON.stringify(entries.map(([id, p]) => ({ project_id: 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) {
@@ -124,7 +121,7 @@ async function deleteProject(projectId) {
   const p = findProject(projectId);
   const res = await fetch(`${API}/projects/v1/${projectId}`, { method: "DELETE", headers: { "Authorization": `Bearer ${p.service_key}` } });
   if (res.status === 204 || res.ok) {
-    saveProjects(loadProjects().filter(pr => pr.project_id !== projectId));
+    removeProject(projectId);
     console.log(JSON.stringify({ status: "ok", message: `Project ${projectId} deleted.` }));
   } else {
     const data = await res.json().catch(() => ({}));