x402-engineer 0.1.0 → 0.1.2

package/package.json

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

package/skills/x402-add-paywall/SKILL.md

@@ -137,21 +137,36 @@ Read [references/patterns.md](references/patterns.md) for the framework-specific
 For each selected unprotected endpoint:
 
 1. **Read the route file** -- always read before editing (never assume file state)
-2. **Add import** -- if `withPayment` or `withX402` is not already imported, add the import:
+2. **Add imports** -- if `withX402` and `resourceServer` are not already imported, add:
    ```typescript
-   import { withPayment } from "{relative_path_to_server}";
+   import { withX402, resourceServer } from "{relative_path_to_server}";
+   import { PRICE, NETWORK, SERVER_ADDRESS } from "{relative_path_to_config}";
    ```
-   Use the path to the x402 server file found in Step 1. Preserve existing imports -- do not duplicate.
+   Use the paths to the x402 server and config files found in Step 1. Preserve existing imports -- do not duplicate.
 3. **Add marker comment** -- add `// x402: payment-protected endpoint` above the handler function
-4. **Wrap the handler** -- wrap the handler's body with `withPayment(req, () => { ... original handler ... })`:
+4. **Wrap the handler** -- use `withX402(handler, routeConfig, resourceServer)` where `routeConfig` is a **single route config object** (NOT the full RoutesConfig map):
    ```typescript
    // x402: payment-protected endpoint
-   export async function GET(req: Request) {
-     return withPayment(req, () => {
+   export const GET = withX402(
+     async (req: Request) => {
        // ... original handler body ...
-     });
-   }
+     },
+     {
+       accepts: [
+         {
+           scheme: "exact",
+           price: PRICE,
+           network: NETWORK,
+           payTo: SERVER_ADDRESS,
+         },
+       ],
+       description: "Description of endpoint",
+       mimeType: "application/json",
+     },
+     resourceServer,
+   );
    ```
+   **IMPORTANT:** `withX402` takes a single `RouteConfig` object as its 2nd argument, NOT the full `RoutesConfig` map. Passing the map will cause `Cannot read properties of undefined (reading 'network')` errors.
 5. **Use Edit tool** to apply changes to the route file
 
 ### Express / Fastify / Hono (middleware)

package/skills/x402-add-paywall/references/patterns.md

@@ -12,16 +12,29 @@ Next.js route handlers must be wrapped individually because there is no global m
 
 **Using @x402/next (official):**
 
+`withX402` takes three arguments: `(handler, routeConfig, resourceServer)` where `routeConfig` is a **single route config object** (NOT the full `RoutesConfig` map).
+
 ```typescript
-import { withX402 } from "../lib/x402/server";
-import { routesConfig, resourceServer } from "../lib/x402/server";
+import { withX402, resourceServer } from "../lib/x402/server";
+import { PRICE, NETWORK, SERVER_ADDRESS } from "../lib/x402/config";
 
 // x402: payment-protected endpoint
 export const GET = withX402(
   async (req: Request) => {
     return Response.json({ data: "protected content" });
   },
-  routesConfig,
+  {
+    accepts: [
+      {
+        scheme: "exact",
+        price: PRICE,
+        network: NETWORK,
+        payTo: SERVER_ADDRESS,
+      },
+    ],
+    description: "Description of endpoint",
+    mimeType: "application/json",
+  },
   resourceServer,
 );
 ```

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
 

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"]
+}
+```