chore: scaffold PYRE MVP monorepo (structure + docs)

pnpm + TypeScript workspace per design doc §13: - apps/{web,api,worker} skeletons (Next.js 16, Fastify 5, BullMQ) - packages/{core,solana,prometheus,db,config} (core has real types/DTOs; solana/prometheus are stubs) - programs/pyre-core placeholder (future Anchor, v1.0) - docs/: PYRE_MVP_DESIGN (canonical), ARCHITECTURE, SECURITY, TOKEN_CLASSIFICATION - CLAUDE.md, README, .env.example (no private-key var by design) Skeleton + docs only — no Solana/business logic yet. All workspaces typecheck clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-05-31 02:20:55 +00:00
parent e86b57e00f
commit c20094ab56
65 changed files with 13834 additions and 1 deletions
--- a/apps/api/README.md
+++ b/apps/api/README.md
@@ -0,0 +1,38 @@
+# @pyre/api
+
+PYRE backend HTTP API. **Skeleton only** — endpoints exist as TODO stubs/route
+placeholders, NOT real implementations. No Solana transaction or scan/build
+logic is implemented yet (see [`CLAUDE.md`](../../CLAUDE.md), §14).
+
+Stack: Node.js + Fastify + TypeScript, with PostgreSQL (`@pyre/db`), Redis +
+BullMQ for queueing jobs handled by `@pyre/worker`.
+
+## Responsibilities (§13)
+
+Token scan coordination, classification helpers, route evaluation, AI generation
+orchestration, metadata preparation, receipt storage, Spawn record storage,
+public API, admin API.
+
+## Endpoints to implement (§14) — TODO
+
+- [ ] `POST /api/scan` — scan a wallet's token accounts; return summary + accounts.
+- [ ] `POST /api/build/close-empty` — build unsigned close-account tx for empty ATAs.
+- [ ] `POST /api/build/burn` — build unsigned burn tx for selected junk tokens.
+- [ ] `POST /api/receipt` — record/return a cleanup receipt for a confirmed tx.
+- [ ] `POST /api/prometheus/generate` — enqueue a Prometheus Spawn generation job.
+- [ ] Admin endpoints — review/approve/reject generated Spawn packages.
+
+Currently only `GET /health` is wired up.
+
+## Backend security rules (§16)
+
+Rate-limit scan endpoints, validate wallet pubkeys, validate token-account
+ownership, never trust client-submitted classifications (recompute server-side),
+log all transaction-build requests, protect admin endpoints, use env secrets only.
+
+## Scripts
+
+- `dev` — `tsx watch src/index.ts`
+- `build` — `tsc -p tsconfig.json`
+- `typecheck` — `tsc --noEmit`
+- `lint` / `test` — placeholders for now
--- a/apps/api/package.json
+++ b/apps/api/package.json
@@ -0,0 +1,28 @@
+{
+  "name": "@pyre/api",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "PYRE backend HTTP API (Fastify) — scan, classify, build transaction, receipt, generation, admin endpoints.",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"TODO: lint\"",
+    "test": "echo \"TODO: tests\""
+  },
+  "dependencies": {
+    "@pyre/config": "workspace:*",
+    "@pyre/core": "workspace:*",
+    "@pyre/db": "workspace:*",
+    "@pyre/solana": "workspace:*",
+    "bullmq": "^5.34.0",
+    "fastify": "^5.2.0",
+    "ioredis": "^5.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}
--- a/apps/api/src/index.ts
+++ b/apps/api/src/index.ts
@@ -0,0 +1,57 @@
+// PYRE backend API — SKELETON ONLY.
+//
+// Minimal Fastify bootstrap. Only `/health` is wired up. The §14 endpoints
+// below are intentionally NOT implemented — no scan/classify/build logic here.
+//
+// Trust rules (§16): never request private keys, never sign custodially,
+// always build an unsigned tx the client decodes + previews before signing,
+// validate wallet pubkeys, validate token-account ownership, never trust
+// client-submitted classifications (recompute server-side), log all tx-build
+// requests, rate-limit scan endpoints, protect admin endpoints.
+
+import Fastify from "fastify";
+
+const app = Fastify({ logger: true });
+
+app.get("/health", async () => {
+  return { status: "ok", service: "@pyre/api" };
+});
+
+// TODO (§14): implement the following routes as real, validated handlers.
+//   POST /api/scan
+//     in:  { wallet }
+//     out: { scanId, wallet, summary, accounts[] }
+//
+//   POST /api/build/close-empty
+//     in:  { wallet, accountAddresses[] }
+//     out: { transactionBase64, preview: { accountsToClose,
+//            estimatedRentReturnedLamports, rentDestination } }
+//
+//   POST /api/build/burn
+//     in:  { wallet, items[] }
+//     out: { transactionBase64, preview: { tokensToBurn, accountsPotentiallyClosable } }
+//
+//   POST /api/receipt
+//     in:  { wallet, txSignature, scanId }
+//     out: { receiptId, txSignature, rentReturnedLamports, closedAccounts,
+//            burnedTokens, skippedTokens }
+//
+//   POST /api/prometheus/generate   (enqueue BullMQ job for @pyre/worker)
+//     in:  { receiptId, chaos, operatorSeed? }
+//     out: { generationId, spawnName, ticker, lore, imagePrompt, metadata, riskFlags }
+//
+//   Admin endpoints — review/approve/reject Spawn generations (protected).
+
+const port = Number(process.env.PORT ?? 3001);
+const host = process.env.HOST ?? "0.0.0.0";
+
+// TODO: load + validate config via @pyre/config instead of reading process.env here.
+app
+  .listen({ port, host })
+  .then((address) => {
+    app.log.info(`@pyre/api listening on ${address}`);
+  })
+  .catch((err) => {
+    app.log.error(err);
+    process.exit(1);
+  });
--- a/apps/api/tsconfig.json
+++ b/apps/api/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}
--- a/apps/web/README.md
+++ b/apps/web/README.md
@@ -0,0 +1,43 @@
+# @pyre/web
+
+User-facing PYRE web app. **Skeleton only** — no wallet or business logic is
+implemented yet (see [`CLAUDE.md`](../../CLAUDE.md) and §13 of the design doc).
+
+Stack: Next.js (App Router) + TypeScript + Tailwind + Solana Wallet Adapter +
+React Query.
+
+## Responsibilities (§13)
+
+- Landing page
+- Wallet connect (Solana Wallet Adapter)
+- Scanner UI — display token accounts and classification grouping
+- Cleanup preview — accounts to close, tokens to burn, rent returned, fees,
+  warnings, rent destination (decode tx and match against preview before signing)
+- Receipt page — tx signature, accounts closed, tokens burned, rent returned,
+  skipped accounts
+- Prometheus generation preview — Spawn name/ticker/lore/image-prompt review
+- Admin review page — approve/reject generated Spawn packages
+
+## Trust rules (do not weaken)
+
+- PYRE never holds private keys; all signing is client-side in the user's wallet.
+- Always show a preview and match the decoded transaction against it before
+  requesting a signature.
+- Recovered ATA rent returns to the user by default.
+
+## TODO
+
+- [ ] Tailwind + PostCSS config and global styles
+- [ ] WalletAdapter / React Query providers
+- [ ] Scanner page wired to `POST /api/scan`
+- [ ] Cleanup preview + transaction decode/match UI
+- [ ] Sign flow via wallet adapter
+- [ ] Receipt page wired to `POST /api/receipt`
+- [ ] Prometheus generation preview + admin review pages
+
+## Scripts
+
+- `dev` — `next dev`
+- `build` — `next build`
+- `typecheck` — `tsc --noEmit`
+- `lint` / `test` — placeholders for now
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -0,0 +1,34 @@
+{
+  "name": "@pyre/web",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "PYRE web app — Next.js user-facing UI: landing, wallet connect, scanner, cleanup preview, receipt, Prometheus preview, admin review.",
+  "scripts": {
+    "build": "next build",
+    "dev": "next dev",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"TODO: lint\"",
+    "test": "echo \"TODO: tests\""
+  },
+  "dependencies": {
+    "@pyre/core": "workspace:*",
+    "@solana/wallet-adapter-react": "^0.15.39",
+    "@solana/wallet-adapter-react-ui": "^0.9.39",
+    "@solana/wallet-adapter-wallets": "^0.19.38",
+    "@solana/web3.js": "^1.98.4",
+    "@tanstack/react-query": "^5.100.0",
+    "next": "^16.2.6",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.3.0",
+    "@types/node": "^22.10.0",
+    "@types/react": "^19.2.0",
+    "@types/react-dom": "^19.2.0",
+    "postcss": "^8.5.15",
+    "tailwindcss": "^4.3.0",
+    "typescript": "^5.7.2"
+  }
+}
--- a/apps/web/postcss.config.mjs
+++ b/apps/web/postcss.config.mjs
@@ -0,0 +1,8 @@
+/** Tailwind CSS v4 PostCSS setup. */
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;
--- a/apps/web/src/app/globals.css
+++ b/apps/web/src/app/globals.css
@@ -0,0 +1,3 @@
+@import "tailwindcss";
+
+/* PYRE global styles. TODO: theme tokens (ember palette) once UI work begins. */
--- a/apps/web/src/app/layout.tsx
+++ b/apps/web/src/app/layout.tsx
@@ -0,0 +1,17 @@
+import type { ReactNode } from "react";
+import "./globals.css";
+
+export const metadata = {
+  title: "PYRE — Burn the dead. Feed the PYRE. Claim the Spawn.",
+  description:
+    "Solana wallet cleanup: scan token accounts, close empty ATAs, and recover rent to your wallet.",
+};
+
+// Root layout (Next.js App Router). Intentionally minimal — UI is built in later phases.
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
--- a/apps/web/src/app/page.tsx
+++ b/apps/web/src/app/page.tsx
@@ -0,0 +1,20 @@
+// PYRE landing page — SKELETON ONLY.
+//
+// TODO (§13): build out the real landing experience and wire up the app:
+//   - Wallet connect (Solana Wallet Adapter) — NO wallet logic here yet.
+//   - Entry point into the scanner UI (POST /api/scan).
+//   - Links to cleanup preview, receipt, Prometheus preview, and admin review.
+//
+// Trust rules: PYRE never holds private keys; signing is always client-side and
+// must be preceded by a decoded-transaction preview that matches what the user
+// sees. See ../../README.md and the repo CLAUDE.md.
+
+export default function HomePage() {
+  return (
+    <main>
+      <h1>PYRE</h1>
+      <p>Burn the dead. Feed the PYRE. Claim the Spawn.</p>
+      {/* TODO: wallet connect button + scanner entry point */}
+    </main>
+  );
+}
--- a/apps/web/src/globals.d.ts
+++ b/apps/web/src/globals.d.ts
@@ -0,0 +1,3 @@
+// Ambient declaration so `tsc --noEmit` accepts global CSS imports
+// (Next.js handles the actual bundling at build time).
+declare module "*.css";
--- a/apps/web/tsconfig.json
+++ b/apps/web/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "preserve",
+    "noEmit": true,
+    "allowJs": true,
+    "incremental": true,
+    "plugins": [{ "name": "next" }]
+  },
+  "include": ["src", "next-env.d.ts", ".next/types/**/*.ts"],
+  "exclude": ["node_modules", "dist", ".next"]
+}
--- a/apps/worker/README.md
+++ b/apps/worker/README.md
@@ -0,0 +1,36 @@
+# @pyre/worker
+
+PYRE background worker process. **Skeleton only** — no job logic is implemented
+yet (see [`CLAUDE.md`](../../CLAUDE.md), §13).
+
+Stack: Node.js worker + BullMQ + Redis (`ioredis`), with `@pyre/db`,
+`@pyre/config`, `@pyre/core`, and `@pyre/prometheus`. AI services are API-based
+only — do not run local LLMs or image models.
+
+## Responsibilities (§13)
+
+Slow token metadata enrichment, AI generation jobs, image-prompt generation,
+safety checks, ticker/name collision checks, background confirmation tracking,
+receipt enrichment.
+
+## Job types to implement — TODO
+
+- [ ] `metadata-lookup` — async token metadata enrichment for scanned accounts.
+- [ ] `prometheus-generate` — AI Spawn generation (name/ticker/lore/image prompt)
+      via `@pyre/prometheus`.
+- [ ] `safety-check` — moderation + forbidden-term + ticker/name collision checks.
+- [ ] `tx-confirmation-watch` — track on-chain confirmation of submitted txs.
+- [ ] `receipt-enrichment` — enrich stored cleanup receipts post-confirmation.
+
+## AI safety rules (§16)
+
+Filter generated names/tickers/lore; avoid hate, explicit, extremist,
+copyrighted, impersonation, and scam-like outputs; require human approval before
+first launches.
+
+## Scripts
+
+- `dev` — `tsx watch src/index.ts`
+- `build` — `tsc -p tsconfig.json`
+- `typecheck` — `tsc --noEmit`
+- `lint` / `test` — placeholders for now
--- a/apps/worker/package.json
+++ b/apps/worker/package.json
@@ -0,0 +1,27 @@
+{
+  "name": "@pyre/worker",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "PYRE background worker (BullMQ) — async metadata lookup, AI generation, safety checks, tx-confirmation watcher, receipt enrichment.",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx watch src/index.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "echo \"TODO: lint\"",
+    "test": "echo \"TODO: tests\""
+  },
+  "dependencies": {
+    "@pyre/config": "workspace:*",
+    "@pyre/core": "workspace:*",
+    "@pyre/db": "workspace:*",
+    "@pyre/prometheus": "workspace:*",
+    "bullmq": "^5.34.0",
+    "ioredis": "^5.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}
--- a/apps/worker/src/index.ts
+++ b/apps/worker/src/index.ts
@@ -0,0 +1,26 @@
+// PYRE background worker — SKELETON ONLY.
+//
+// Minimal bootstrap stub. No queues or processors are wired up yet, and no real
+// job logic is implemented. AI services are API-based only (§11) — never run
+// local LLMs or image models on the server.
+
+// TODO: construct the Redis connection (ioredis) from @pyre/config and create a
+// BullMQ Worker per queue below, each delegating to a typed processor.
+//
+// Job types to implement (§13):
+//   - metadata-lookup        : async token metadata enrichment for scanned accounts
+//   - prometheus-generate    : AI Spawn generation via @pyre/prometheus
+//   - safety-check           : moderation + forbidden-term + ticker/name collision checks
+//   - tx-confirmation-watch  : background tracking of on-chain tx confirmation
+//   - receipt-enrichment     : enrich stored cleanup receipts post-confirmation
+//
+// AI safety (§16): filter generated names/tickers/lore; block hate, explicit,
+// extremist, copyrighted, impersonation, and scam-like outputs; require human
+// approval before any launch.
+
+function main(): void {
+  // TODO: start BullMQ workers and register graceful shutdown handlers.
+  console.log("@pyre/worker: skeleton bootstrap — no jobs registered yet");
+}
+
+main();
--- a/apps/worker/tsconfig.json
+++ b/apps/worker/tsconfig.json
@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"],
+  "exclude": ["node_modules", "dist"]
+}