x402-engineer 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "x402-engineer",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Claude Code skill pack for adding x402 micropayments to any API endpoint",
   "license": "MIT",
   "type": "module",

package/skills/x402-init/SKILL.md

@@ -9,7 +9,7 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
 
 # /x402:init
 
-> Bootstrap x402 payment protection in your project. I'll detect your framework, install the right packages, and scaffold all config files.
+> Bootstrap x402 payment protection in your project. Works with existing projects (brownfield) or creates a new project from scratch (greenfield). I'll detect your framework, install the right packages, and scaffold all config files.
 
 ## Important Rules
 
@@ -17,6 +17,64 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob]
 - Server-side `ExactStellarScheme` import path is always `@x402/stellar/exact/server` (NOT `@x402/stellar/exact/client`).
 - All templates are in this skill's `templates/` directory. Read the template file and use its content as the basis for generated code.
 - Adapt import paths if needed based on project structure (e.g., relative paths based on file placement).
+- For Next.js greenfield projects, ALWAYS delegate to create-next-app. Do NOT scaffold Next.js manually.
+- Greenfield templates are in this skill's `templates/greenfield/` directory.
+
+## Step 0 -- Detect Greenfield Project (Conditional)
+
+Before anything else, determine if this is a greenfield (new/empty) project:
+
+1. **Check for package.json:** Use Read to check if `package.json` exists in the current working directory
+2. **If package.json exists:** Check if any supported framework (`next`, `express`, `fastify`, `hono`) appears in `dependencies`. If a framework IS found, this is a brownfield project -- skip to Step 1.
+3. **If no package.json OR no framework in dependencies:** This is a greenfield project. Continue below.
+
+### Greenfield: Verify Empty Directory
+
+Before scaffolding, verify the directory is safe to scaffold into:
+
+1. Use Bash to list directory contents: `ls -A`
+2. **Allowed trivial files:** `.git`, `.gitignore`, `CLAUDE.md`, `.claude/`, `README.md`, `.planning/`
+3. If the directory contains files OTHER than the trivial list above, warn the user:
+   `"Directory is not empty. Found: {non-trivial files}. Greenfield scaffolding expects an empty directory. Continue anyway? (The existing files will be preserved, but conflicts may occur.)"`
+   Wait for user confirmation before proceeding. If the user says no, STOP.
+
+### Greenfield: Select Framework
+
+1. **If `$ARGUMENTS` provides a framework** (e.g., `/x402:init express`), use that framework directly. Valid values: `nextjs`, `next`, `express`, `fastify`, `hono`. Normalize `nextjs`/`next` to Next.js.
+2. **If no argument provided**, ask the user:
+   ```
+   No framework detected. Which framework would you like to use?
+
+   1. Express (default -- simplest for API-only)
+   2. Fastify
+   3. Hono
+   4. Next.js (full-stack with App Router)
+
+   Enter choice (1-4) or framework name:
+   ```
+   If the user just presses enter or says "default", use Express.
+
+### Greenfield: Scaffold Project
+
+**For Next.js:**
+
+1. Output: `"Scaffolding Next.js project with create-next-app..."`
+2. Run via Bash: `npx create-next-app@latest . --typescript --app --yes`
+3. Wait for completion. If it fails (e.g., directory not empty), report the error and STOP.
+4. Output: `"Next.js project created. Continuing with x402 setup..."`
+5. Skip to Step 1 (the brownfield flow handles everything from here).
+
+**For Express / Fastify / Hono:**
+
+1. Output: `"Scaffolding {Framework} project..."`
+2. Read `templates/greenfield/{framework}/package.json.md` -- extract JSON from code block, write to `./package.json`
+3. Read `templates/greenfield/{framework}/tsconfig.json.md` -- extract JSON from code block, write to `./tsconfig.json`
+4. Create `src/` directory via Bash: `mkdir -p src`
+5. Read `templates/greenfield/{framework}/server.ts.md` -- extract TypeScript from code block, write to `./src/server.ts`
+6. Run via Bash: `npm install`
+7. Output: `"Project scaffolded. Created 3 files: package.json, tsconfig.json, src/server.ts"`
+8. Output: `"Continuing with x402 setup..."`
+9. Continue to Step 1 (the existing brownfield flow picks up from here -- it will detect the framework from the newly created package.json).
 
 ## Step 1 -- Check for Existing x402 Setup (Idempotency)
 
@@ -50,7 +108,7 @@ Report which pieces are already present. Skip those. Only create the missing pie
 
 **Edge cases:**
 - If `@nestjs/core` is found in dependencies, warn: `"NestJS detected, using underlying Express/Fastify adapter"` and detect which underlying framework NestJS uses (check for `@nestjs/platform-express` or `@nestjs/platform-fastify`)
-- If no supported framework is detected, output: `"Could not detect framework from package.json. Supported: Next.js, Express, Fastify, Hono."` and STOP
+- If no supported framework is detected AND Step 0 was skipped (package.json exists but has no framework): output `"Could not detect framework from package.json. Supported: Next.js, Express, Fastify, Hono."` and STOP
 
 ## Step 3 -- Detect Project Structure
 
@@ -90,7 +148,6 @@ Run the framework-specific install command via Bash:
 6. Check if `.env.example` already exists at the project root:
    - If it does NOT exist: create `.env.example` with the template content
    - If it DOES exist: check if it already contains `SERVER_STELLAR_ADDRESS`. If not, append the x402 section to the existing file
-7. Output: `"Created .env.example with required variables. Copy to .env.local and fill in your values."`
 
 ## Step 6 -- Scaffold Server/Middleware Files
 
@@ -103,7 +160,94 @@ Run the framework-specific install command via Bash:
 5. Extract the TypeScript code from the template's fenced code block
 6. Write to `{base_dir}/x402/adapter.ts`
 
-## Step 7 -- Summary
+## Step 7 -- Configure Environment (Interactive)
+
+Guide the user through setting up `.env.local` with the required values. Check if `.env.local` already exists and has values before prompting.
+
+### 7a -- Check existing .env.local
+
+1. Use Read to check if `.env.local` exists
+2. If it exists and already contains `SERVER_STELLAR_ADDRESS` with a non-empty value, output:
+   `"Environment already configured in .env.local. Skipping setup."`
+   Skip to Step 8.
+
+### 7b -- SERVER_STELLAR_ADDRESS
+
+Output the following explanation:
+
+```
+To receive payments, you need a Stellar account address.
+This is a public key that starts with "G" (56 characters).
+
+How to get one:
+  1. Go to https://laboratory.stellar.org/#account-creator?network=test
+  2. Click "Generate Keypair"
+  3. Save both keys -- you'll use the Public Key (G...) here
+  4. Click "Fund account on testnet" to get test XLM
+
+If you already have a Stellar address, paste it below.
+```
+
+Ask the user for the value. Accept any input that:
+- Starts with `G` and is 56 characters long
+- OR is empty (user wants to skip for now)
+
+If the user provides an invalid format, warn once: `"Stellar addresses start with G and are 56 characters. This doesn't look right, but I'll use it anyway."` and proceed.
+
+If the user skips (empty), set `SERVER_STELLAR_ADDRESS=` (empty value).
+
+### 7c -- FACILITATOR_API_KEY
+
+Output the following explanation:
+
+```
+The facilitator is a service (by OpenZeppelin) that verifies and settles
+x402 payments on your behalf. You need an API key to use it.
+
+How to get one:
+  1. Go to https://channels.openzeppelin.com/testnet/gen
+  2. Generate a new API key
+  3. Paste it below
+
+This takes ~30 seconds. I'll wait.
+```
+
+Ask the user for the value. Accept any non-empty string, or empty to skip.
+
+If the user skips (empty), set `FACILITATOR_API_KEY=` (empty value).
+
+### 7d -- Write .env.local
+
+Write `.env.local` with the collected values:
+
+```env
+# x402 Payment Configuration
+
+# Stellar public key (G...) that receives USDC payments
+SERVER_STELLAR_ADDRESS={collected_value}
+
+# OpenZeppelin facilitator endpoint
+FACILITATOR_URL=https://channels.openzeppelin.com/x402/testnet
+
+# API key from https://channels.openzeppelin.com/testnet/gen
+FACILITATOR_API_KEY={collected_value}
+```
+
+**Rules:**
+- Always set `FACILITATOR_URL` to the testnet endpoint (no need to ask -- testnet is the right default for init)
+- If `.env.local` already exists with OTHER variables (not x402-related), append the x402 section. Do not overwrite existing content.
+- Add `.env.local` to `.gitignore` if not already present (check first for idempotency)
+
+### 7e -- Report status
+
+If both values were provided:
+`"Environment configured. .env.local is ready."`
+
+If one or both were skipped:
+`"Created .env.local with partial configuration. Fill in the missing values before testing:"`
+Then list which variables are still empty.
+
+## Step 8 -- Summary
 
 Count the files created during this run and output:
 
@@ -112,18 +256,20 @@ Count the files created during this run and output:
 List each file with its relative path from the project root, for example:
 
 ```
-x402 initialized. Created 3 files:
+x402 initialized. Created 4 files:
   - lib/x402/config.ts
   - lib/x402/server.ts
   - .env.example
+  - .env.local
 ```
 
 For Fastify projects, the adapter file is also listed:
 
 ```
-x402 initialized. Created 4 files:
+x402 initialized. Created 5 files:
   - lib/x402/config.ts
   - lib/x402/server.ts
   - lib/x402/adapter.ts
   - .env.example
+  - .env.local
 ```

package/skills/x402-init/templates/greenfield/express/package.json.md

@@ -0,0 +1,24 @@
+# Express Greenfield package.json
+
+Minimal package.json for a new Express + TypeScript project.
+
+```json
+{
+  "name": "x402-server",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js"
+  },
+  "dependencies": {
+    "express": "latest"
+  },
+  "devDependencies": {
+    "@types/express": "latest",
+    "tsx": "latest",
+    "typescript": "latest"
+  }
+}
+```

package/skills/x402-init/templates/greenfield/express/server.ts.md

@@ -0,0 +1,18 @@
+# Express Greenfield Server
+
+Minimal Express server with a single `/api/hello` endpoint.
+
+```typescript
+import express from "express";
+
+const app = express();
+const port = process.env.PORT || 3000;
+
+app.get("/api/hello", (_req, res) => {
+  res.json({ message: "Hello from x402!" });
+});
+
+app.listen(port, () => {
+  console.log(`Server running on http://localhost:${port}`);
+});
+```

package/skills/x402-init/templates/greenfield/express/tsconfig.json.md

@@ -0,0 +1,19 @@
+# Express Greenfield tsconfig.json
+
+Minimal TypeScript configuration for a new Express project.
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}
+```

package/skills/x402-init/templates/greenfield/fastify/package.json.md

@@ -0,0 +1,23 @@
+# Fastify Greenfield package.json
+
+Minimal package.json for a new Fastify + TypeScript project.
+
+```json
+{
+  "name": "x402-server",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js"
+  },
+  "dependencies": {
+    "fastify": "latest"
+  },
+  "devDependencies": {
+    "tsx": "latest",
+    "typescript": "latest"
+  }
+}
+```

package/skills/x402-init/templates/greenfield/fastify/server.ts.md

@@ -0,0 +1,22 @@
+# Fastify Greenfield Server
+
+Minimal Fastify server with a single `/api/hello` endpoint.
+
+```typescript
+import Fastify from "fastify";
+
+const fastify = Fastify();
+const port = Number(process.env.PORT) || 3000;
+
+fastify.get("/api/hello", async () => {
+  return { message: "Hello from x402!" };
+});
+
+fastify.listen({ port, host: "0.0.0.0" }, (err, address) => {
+  if (err) {
+    console.error(err);
+    process.exit(1);
+  }
+  console.log(`Server running on http://localhost:${port}`);
+});
+```

package/skills/x402-init/templates/greenfield/fastify/tsconfig.json.md

@@ -0,0 +1,19 @@
+# Fastify Greenfield tsconfig.json
+
+Minimal TypeScript configuration for a new Fastify project.
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}
+```

package/skills/x402-init/templates/greenfield/hono/package.json.md

@@ -0,0 +1,24 @@
+# Hono Greenfield package.json
+
+Minimal package.json for a new Hono + TypeScript project.
+
+```json
+{
+  "name": "x402-server",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "tsx watch src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js"
+  },
+  "dependencies": {
+    "@hono/node-server": "latest",
+    "hono": "latest"
+  },
+  "devDependencies": {
+    "tsx": "latest",
+    "typescript": "latest"
+  }
+}
+```

package/skills/x402-init/templates/greenfield/hono/server.ts.md

@@ -0,0 +1,19 @@
+# Hono Greenfield Server
+
+Minimal Hono server with a single `/api/hello` endpoint.
+
+```typescript
+import { Hono } from "hono";
+import { serve } from "@hono/node-server";
+
+const app = new Hono();
+const port = Number(process.env.PORT) || 3000;
+
+app.get("/api/hello", (c) => {
+  return c.json({ message: "Hello from x402!" });
+});
+
+serve({ fetch: app.fetch, port }, () => {
+  console.log(`Server running on http://localhost:${port}`);
+});
+```

package/skills/x402-init/templates/greenfield/hono/tsconfig.json.md

@@ -0,0 +1,19 @@
+# Hono Greenfield tsconfig.json
+
+Minimal TypeScript configuration for a new Hono project.
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}
+```