create-surf-app 0.1.26-alpha.0 → 1.0.0-alpha.10

package/dist/chunk-FDATV75D.js

@@ -0,0 +1,87 @@
+// src/index.ts
+import fs from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
+var VALID_TEMPLATES = ["vite", "nextjs"];
+async function createSurfApp({
+  projectName = ".",
+  template: templateArg,
+  logger = console.log
+} = {}) {
+  const root = path.resolve(projectName);
+  const name = path.basename(root);
+  const template = validateTemplate(templateArg);
+  const templateDir = resolveTemplateDir(template);
+  logger(`
+  Creating Surf app (${template}) in ${root}
+`);
+  fs.mkdirSync(root, { recursive: true });
+  copyDir(templateDir, root, root, logger);
+  if (template === "nextjs") {
+    finalizePackageName(root, name);
+    logger(`
+Done! Next steps:
+
+  cd ${name}
+  npm install
+  npm run dev
+
+  Open http://localhost:3000
+`);
+  } else {
+    logger(`
+Done! Next steps:
+
+  cd ${name}
+  npm install
+  npm run dev
+
+  Open the local URL printed by Vite
+`);
+  }
+  return root;
+}
+function validateTemplate(template) {
+  if (!template) return "vite";
+  if (!VALID_TEMPLATES.includes(template)) {
+    throw new Error(`Unknown template: ${template}. Valid templates: ${VALID_TEMPLATES.join(", ")}`);
+  }
+  return template;
+}
+function resolveTemplateDir(template = "vite") {
+  const dirName = template === "vite" ? "default" : template;
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path.join(here, "templates", dirName),
+    path.join(here, "..", "templates", dirName)
+  ];
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) return candidate;
+  }
+  throw new Error(`Could not find ${template} template near ${here}`);
+}
+function copyDir(src, dest, root, logger) {
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyDir(srcPath, destPath, root, logger);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(destPath), { recursive: true });
+    fs.writeFileSync(destPath, fs.readFileSync(srcPath));
+    logger(`  ${path.relative(root, destPath)}`);
+  }
+}
+function finalizePackageName(root, projectName) {
+  const pkgPath = path.join(root, "package.json");
+  if (!fs.existsSync(pkgPath)) return;
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+  pkg.name = projectName.trim().toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "surf-app";
+  fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
+}
+
+export {
+  createSurfApp
+};

package/dist/cli.js

@@ -1,13 +1,10 @@
 #!/usr/bin/env node
 import {
   createSurfApp
-} from "./chunk-E32T2IIS.js";
+} from "./chunk-FDATV75D.js";
 
 // src/cli.ts
 var VALUE_FLAGS = /* @__PURE__ */ new Set([
-  "--frontend-port",
-  "--backend-port",
-  "--preview-base",
   "--template"
 ]);
 function getFlag(args, name) {
@@ -35,9 +32,6 @@ function parseCliArgs(args) {
   }
   return {
     projectName: positionalArgs[0] || ".",
-    frontendPort: getFlag(args, "--frontend-port"),
-    backendPort: getFlag(args, "--backend-port"),
-    previewBase: getFlag(args, "--preview-base"),
     template: getFlag(args, "--template")
   };
 }

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   createSurfApp
-} from "./chunk-E32T2IIS.js";
+} from "./chunk-FDATV75D.js";
 export {
   createSurfApp
 };

package/dist/templates/default/CLAUDE.md

@@ -88,3 +88,23 @@ The agent can also call `POST /api/__sync-schema` explicitly after editing.
 - Do not bypass your backend routes from the frontend
 - Frontend packages are pre-installed - check `package.json` before installing
 - Default to a dark theme unless the user explicitly asks for a different visual direction.
+
+## Design
+
+### Avoid AI-default patterns
+- No colored icon boxes next to metrics (the blue-bg-with-icon KPI pattern)
+- No gradient avatar circles with initials
+- No "Built with React · Tailwind" footers
+- No AI copywriting: "Elevate", "Seamless", "Unleash", "Delve", "Next-Gen"
+- No "Oops!" error messages — be direct ("Failed to load. Try again.")
+- No round placeholder numbers ($100.00) — use realistic data ($847.29)
+- Sentence case on headings, not Title Case On Every Word
+- Icons should aid scanning, not decorate — omit when the label is clear
+
+### ECharts
+- Flat style: show primary axis line, dashed split lines, transparent chart bg
+- Custom tooltip formatter with dash indicators (12×2.5px bars, not default circle dots)
+- Legend: type "plain", icon "roundRect", itemWidth 12, itemHeight 3
+- Prefer timeframe tabs (7D/30D/90D/1Y/All) over dataZoom for time series
+- Default to theme visualizer palette; override when semantics demand it (red/green for gain/loss, sequential scales for heatmaps)
+- Dark mode: parameterize tooltip bg, axis colors, split line colors via resolvedTheme

package/dist/templates/default/backend/.env.example

@@ -0,0 +1,2 @@
+BACKEND_PORT=3001
+SURF_API_KEY=

package/dist/templates/default/backend/package.json

@@ -2,11 +2,10 @@
   "name": "backend",
   "private": true,
   "scripts": {
-    "start": "node server.js",
-    "dev": "node --watch server.js"
+    "dev": "node scripts/check-env.js node --watch server.js"
   },
   "dependencies": {
-    "@surf-ai/sdk": "0.1.4-beta",
+    "@surf-ai/sdk": "1.0.0-alpha.10",
     "express": "4.22.1"
   }
 }

package/dist/templates/default/backend/scripts/check-env.js

@@ -0,0 +1,40 @@
+/**
+ * Validates required env vars before running a command.
+ * Loads .env if it exists (optional convenience), then checks vars.
+ *
+ * Dev/start: BACKEND_PORT, SURF_API_KEY
+ */
+const fs = require('node:fs')
+const path = require('node:path')
+const { execSync } = require('node:child_process')
+
+// Load .env if it exists (convenience — env vars can come from anywhere)
+const envPath = path.join(process.cwd(), '.env')
+if (fs.existsSync(envPath)) {
+  for (const line of fs.readFileSync(envPath, 'utf8').split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eq = trimmed.indexOf('=')
+    if (eq < 0) continue
+    const key = trimmed.slice(0, eq)
+    const val = trimmed.slice(eq + 1)
+    if (!process.env[key]) process.env[key] = val
+  }
+}
+
+const args = process.argv.slice(2)
+
+const required = ['BACKEND_PORT', 'SURF_API_KEY']
+const missing = required.filter(k => !process.env[k])
+
+if (missing.length > 0) {
+  console.error(`\n❌ Missing required env vars: ${missing.join(', ')}`)
+  console.error(`   Set them in your environment or copy .env.example to .env\n`)
+  process.exit(1)
+}
+
+try {
+  execSync(args.join(' '), { stdio: 'inherit', env: process.env })
+} catch (e) {
+  process.exit(e.status || 1)
+}

package/dist/templates/default/backend/server.js

@@ -1,2 +1,2 @@
 const { createServer } = require('@surf-ai/sdk/server')
-createServer({ proxy: false }).start()
+createServer().start()

package/dist/templates/default/frontend/.env.example

@@ -0,0 +1,3 @@
+PORT=5173
+BACKEND_PORT=3001
+BASE_PATH=

package/dist/templates/default/frontend/package.json

@@ -4,8 +4,8 @@
   "version": "0.0.0",
   "type": "module",
   "scripts": {
-    "dev": "vite",
-    "build": "npm run build:client && npm run build:server",
+    "dev": "node scripts/check-env.cjs vite",
+    "build": "node scripts/check-env.cjs npm run build:client && npm run build:server",
     "build:client": "vite build --outDir dist/client",
     "build:server": "vite build --ssr src/entry-server.tsx --outDir dist/server",
     "lint": "eslint .",

package/dist/templates/default/frontend/scripts/check-env.cjs

@@ -0,0 +1,51 @@
+/**
+ * Validates required env vars before running a command.
+ * Loads .env manually, checks vars, then execs the actual command.
+ *
+ * Build: BASE_PATH (defined, can be empty), BACKEND_PORT
+ * Dev: PORT, BACKEND_PORT, BASE_PATH
+ */
+const fs = require('node:fs')
+const path = require('node:path')
+const { execSync } = require('node:child_process')
+
+// Load .env manually (Vite doesn't load non-VITE_ vars into process.env)
+const envPath = path.join(process.cwd(), '.env')
+if (fs.existsSync(envPath)) {
+  for (const line of fs.readFileSync(envPath, 'utf8').split('\n')) {
+    const trimmed = line.trim()
+    if (!trimmed || trimmed.startsWith('#')) continue
+    const eq = trimmed.indexOf('=')
+    if (eq < 0) continue
+    const key = trimmed.slice(0, eq)
+    const val = trimmed.slice(eq + 1)
+    if (!process.env[key]) process.env[key] = val
+  }
+}
+
+const args = process.argv.slice(2)
+const isBuild = args.some(a => a.includes('build'))
+
+// Vars that must be non-empty
+const requiredNonEmpty = isBuild
+  ? ['BACKEND_PORT']
+  : ['PORT', 'BACKEND_PORT']
+
+// Vars that must be defined (empty is ok — BASE_PATH="" means root)
+const requiredDefined = ['BASE_PATH']
+
+const missingNonEmpty = requiredNonEmpty.filter(k => !process.env[k])
+const missingDefined = requiredDefined.filter(k => process.env[k] === undefined)
+const missing = [...missingNonEmpty, ...missingDefined]
+
+if (missing.length > 0) {
+  console.error(`\n❌ Missing required env vars: ${missing.join(', ')}`)
+  console.error(`   Set them in your environment or copy .env.example to .env\n`)
+  process.exit(1)
+}
+
+try {
+  execSync(args.join(' '), { stdio: 'inherit', env: process.env })
+} catch (e) {
+  process.exit(e.status || 1)
+}

package/dist/templates/default/frontend/src/vite-env.d.ts

@@ -1,10 +1 @@
 /// <reference types="vite/client" />
-
-interface ImportMetaEnv {
-  readonly VITE_PORT: string
-  readonly VITE_BACKEND_PORT: string
-}
-
-interface ImportMeta {
-  readonly env: ImportMetaEnv
-}

package/dist/templates/default/frontend/vite.config.ts

@@ -1,24 +1,12 @@
 import path from 'path'
-import { defineConfig, loadEnv } from 'vite'
+import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
 
-function readRequiredPort(
-  env: Record<string, string>,
-  name: 'VITE_BACKEND_PORT' | 'VITE_PORT',
-) {
-  const value = env[name]
-  const port = Number.parseInt(value || '', 10)
-  if (!Number.isInteger(port)) {
-    throw new Error(`Missing required ${name} in frontend/.env`)
-  }
-  return port
-}
-
-export default defineConfig(({ mode }) => {
-  const env = loadEnv(mode, process.cwd())
-  const backendPort = readRequiredPort(env, 'VITE_BACKEND_PORT')
-  const base = env.VITE_BASE || './'
+export default defineConfig(() => {
+  const frontendPort = Number.parseInt(process.env.PORT || '', 10)
+  const backendPort = Number.parseInt(process.env.BACKEND_PORT || '', 10)
+  const base = process.env.BASE_PATH || './'
   const hasAbsBase = base.startsWith('/')
   const apiBasePrefix = hasAbsBase ? base.replace(/\/$/, '') : ''
 
@@ -33,12 +21,11 @@ export default defineConfig(({ mode }) => {
   return {
     plugins: [react(), tailwindcss()],
     server: {
-      port: readRequiredPort(env, 'VITE_PORT'),
       host: '0.0.0.0',
+      port: frontendPort || undefined,
       proxy: {
         [`${apiBasePrefix}/api`]: backendProxy,
       },
-      // Keep the HMR socket under the preview base path.
       hmr: {
         path: 'ws/vite-hmr',
       },
@@ -50,8 +37,6 @@ export default defineConfig(({ mode }) => {
       dedupe: ['react', 'react-dom'],
       preserveSymlinks: true,
     },
-    // Pre-bundle the deps touched during the initial boot path so cold starts
-    // do not race Vite's lazy dependency optimizer.
     optimizeDeps: {
       include: [
         'react',

package/dist/templates/default/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "surf-app",
+  "private": true,
+  "workspaces": ["backend", "frontend"],
+  "scripts": {
+    "dev": "concurrently \"npm run dev --workspace backend\" \"npm run dev --workspace frontend\""
+  },
+  "devDependencies": {
+    "concurrently": "^9.0.0"
+  }
+}

package/dist/templates/nextjs/.env.example

@@ -0,0 +1,3 @@
+PORT=3000
+BASE_PATH=
+SURF_API_KEY=

package/dist/templates/nextjs/CLAUDE.md

@@ -1 +1,93 @@
-@AGENTS.md
+# Project
+
+Built with [Surf SDK](https://github.com/cyberconnecthq/urania/tree/main/packages/sdk) and Next.js App Router.
+
+## Imports from @surf-ai/sdk
+
+Use `@surf-ai/sdk/server` in API route handlers to talk to Surf data APIs.
+Do not import `@surf-ai/sdk/server` in client components.
+Use `fetch('/api/...')` in client components to call your own API routes.
+
+**API Route Handler (`@surf-ai/sdk/server`):**
+
+```ts
+import { dataApi } from "@surf-ai/sdk/server";
+const data = await dataApi.market.price({ symbol: "BTC" });
+const holders = await dataApi.token.holders({
+  address: "0x...",
+  chain: "ethereum",
+});
+// Escape hatch for new endpoints:
+const raw = await dataApi.get("newcategory/endpoint", { foo: "bar" });
+```
+
+## Structure
+
+```
+app/page.tsx              - build your UI here
+app/api/*/route.ts        - add API route handlers
+components/               - add components (use "use client" directive)
+db/schema.ts              - define database tables
+```
+
+## Built-in Endpoints
+
+These are provided automatically - do NOT create routes for them:
+
+| Endpoint             | Method | Purpose                                        |
+| -------------------- | ------ | ---------------------------------------------- |
+| `/api/health`        | GET    | Health check - `{ status: 'ok' }`              |
+| `/api/__sync-schema` | POST   | Sync `db/schema.ts` tables to database         |
+| `/api/cron`          | GET    | List cron jobs                                 |
+| `/api/cron`          | POST   | Create a new cron task                         |
+
+## Creating API Routes
+
+Create Route Handler files in `app/api/`:
+
+```ts
+// app/api/prices/route.ts
+import { dataApi } from '@surf-ai/sdk/server'
+
+export async function GET(request: Request) {
+  const { searchParams } = new URL(request.url)
+  const symbol = searchParams.get('symbol') || 'BTC'
+  const data = await dataApi.market.price({ symbol })
+  return Response.json(data)
+}
+```
+
+## Database
+
+Define tables in `db/schema.ts` using Drizzle ORM:
+
+```ts
+import { pgTable, serial, text, timestamp } from "drizzle-orm/pg-core";
+export const users = pgTable("users", {
+  id: serial("id").primaryKey(),
+  name: text("name").notNull(),
+  created_at: timestamp("created_at").defaultNow(),
+});
+```
+
+Tables are auto-synced on server start and when `db/schema.ts` changes in dev mode.
+
+## Do NOT modify
+
+- `instrumentation.ts` - server boot (schema sync, cron)
+- `next.config.ts` - build/deploy config
+- `db/index.ts` - database connection
+- `lib/boot.ts` - infrastructure (schema sync, cron init)
+- `app/layout.tsx` - root layout and providers
+- `app/providers.tsx` - client-side providers (QueryClient, theme)
+- `eslint.config.mjs` - lint rules
+- `globals.css` - only imports, do not add styles here (use Tailwind classes)
+
+## Rules
+
+- Add `"use client"` at the top of all components you create
+- Use `fetch('/api/...')` in client components to call API routes
+- Use `@surf-ai/sdk/server` `dataApi` in route handlers when you need Surf data
+- Do not bypass your API routes from client components
+- Packages are pre-installed - check `package.json` before installing
+- Default to a dark theme unless the user explicitly asks for a different visual direction

package/dist/templates/nextjs/app/api/__sync-schema/route.ts

@@ -0,0 +1,18 @@
+import path from 'node:path'
+import { syncSchema } from '@surf-ai/sdk/db'
+
+export async function POST() {
+  try {
+    await syncSchema({
+      schemaPath: path.join(process.cwd(), 'db', 'schema.ts'),
+      retries: 2,
+      retryDelay: 1500,
+    })
+    return Response.json({ ok: true })
+  } catch (err) {
+    return Response.json(
+      { ok: false, error: String(err) },
+      { status: 500 }
+    )
+  }
+}

package/dist/templates/nextjs/app/api/cron/route.ts

@@ -0,0 +1,31 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { randomUUID } from 'node:crypto'
+
+const CRON_PATH = path.join(process.cwd(), 'cron.json')
+
+function readCronConfig() {
+  if (!fs.existsSync(CRON_PATH)) return []
+  return JSON.parse(fs.readFileSync(CRON_PATH, 'utf-8'))
+}
+
+function writeCronConfig(config: unknown[]) {
+  fs.writeFileSync(CRON_PATH, JSON.stringify(config, null, 2))
+}
+
+export async function GET() {
+  return Response.json(readCronConfig())
+}
+
+export async function POST(request: Request) {
+  const body = await request.json()
+  const config = readCronConfig()
+  const task = {
+    id: randomUUID(),
+    ...body,
+    enabled: body.enabled ?? true,
+  }
+  config.push(task)
+  writeCronConfig(config)
+  return Response.json(task, { status: 201 })
+}

package/dist/templates/nextjs/app/api/health/route.ts

@@ -1,3 +1,3 @@
 export async function GET() {
-  return Response.json({ status: "ok" });
+  return Response.json({ status: 'ok' })
 }

package/dist/templates/nextjs/app/api/market/price/route.ts

@@ -1,25 +1,9 @@
-import { dataApi } from "@surf-ai/sdk/server";
-import { NextResponse } from "next/server";
-
-const TIME_RANGES = ["1d", "7d", "14d", "30d", "90d", "180d", "365d", "max"] as const;
+import { dataApi } from '@surf-ai/sdk/server'
 
 export async function GET(request: Request) {
-  const { searchParams } = new URL(request.url);
-  const symbol = searchParams.get("symbol") || "BTC";
-  const rawTimeRange = searchParams.get("time_range");
-  const timeRange = TIME_RANGES.includes((rawTimeRange || "") as (typeof TIME_RANGES)[number])
-    ? (rawTimeRange as (typeof TIME_RANGES)[number])
-    : "1d";
-
-  try {
-    const data = await dataApi.market.price({
-      symbol,
-      time_range: timeRange,
-    });
+  const { searchParams } = new URL(request.url)
+  const symbol = searchParams.get('symbol') || 'BTC'
 
-    return NextResponse.json(data);
-  } catch (error) {
-    const message = error instanceof Error ? error.message : "Unknown error";
-    return NextResponse.json({ error: message }, { status: 500 });
-  }
+  const data = await dataApi.market.price({ symbol })
+  return Response.json(data)
 }

package/dist/templates/nextjs/app/globals.css

@@ -1,26 +1,2 @@
 @import "tailwindcss";
-
-:root {
-  --background: #ffffff;
-  --foreground: #171717;
-}
-
-@theme inline {
-  --color-background: var(--background);
-  --color-foreground: var(--foreground);
-  --font-sans: var(--font-geist-sans);
-  --font-mono: var(--font-geist-mono);
-}
-
-@media (prefers-color-scheme: dark) {
-  :root {
-    --background: #0a0a0a;
-    --foreground: #ededed;
-  }
-}
-
-body {
-  background: var(--background);
-  color: var(--foreground);
-  font-family: Arial, Helvetica, sans-serif;
-}
+@import "tw-animate-css";

package/dist/templates/nextjs/app/layout.tsx

@@ -1,33 +1,24 @@
-import type { Metadata } from "next";
-import { Geist, Geist_Mono } from "next/font/google";
-import "./globals.css";
-
-const geistSans = Geist({
-  variable: "--font-geist-sans",
-  subsets: ["latin"],
-});
-
-const geistMono = Geist_Mono({
-  variable: "--font-geist-mono",
-  subsets: ["latin"],
-});
+import type { Metadata } from "next"
+import { ThemeProvider } from "next-themes"
+import { Providers } from "./providers"
+import "./globals.css"
 
 export const metadata: Metadata = {
-  title: "Create Next App",
-  description: "Generated by create next app",
-};
+  title: "Surf App",
+}
 
 export default function RootLayout({
   children,
-}: Readonly<{
-  children: React.ReactNode;
-}>) {
+}: {
+  children: React.ReactNode
+}) {
   return (
-    <html
-      lang="en"
-      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
-    >
-      <body className="min-h-full flex flex-col">{children}</body>
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <ThemeProvider attribute="class" defaultTheme="dark" enableSystem={false}>
+          <Providers>{children}</Providers>
+        </ThemeProvider>
+      </body>
     </html>
-  );
+  )
 }