ugly-app 0.1.0

package/templates/.husky/pre-commit

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+npx lint-staged

package/templates/CLAUDE.md

@@ -0,0 +1,199 @@
+# Project Structure & Conventions
+
+Generated by `website-core`. See the full framework docs at [npm:website-core](https://www.npmjs.com/package/website-core).
+
+## Stack
+- Server: Express + TypeScript (`server/index.ts`)
+- Client: React + Vite (`client/main.tsx`)
+- Shared: Types + API definitions (`shared/`)
+- CLI: `web` commands from website-core (see package.json scripts)
+
+## Commands
+- `yarn dev` — Start dev server (docker + server + vite + tsc watch + eslint watch)
+- `yarn build` — Build for production
+- `yarn deploy:single` — Deploy to single server
+- `yarn deploy:multi` — Deploy to multiple servers
+- `yarn db:migrate` — Run database migrations
+- `yarn db:init` — (Re)create database indexes
+- `yarn logs` — Show local dev logs
+- `yarn error` — Show local error logs
+- `yarn feedback` — Show user feedback from production
+
+## Adding a new API endpoint
+
+1. Add to `shared/api.ts` using `fn()` or `req()` with Zod schemas:
+   ```typescript
+   import { fn, req, z } from 'website-core/shared';
+
+   export const functions = defineFunctions({
+     myFunction: fn({
+       input: z.object({ name: z.string() }),
+       output: z.object({ greeting: z.string() }),
+     }),
+   });
+   ```
+2. Register handler in `server/index.ts`:
+   ```typescript
+   app.registerFunction('myFunction', async (ctx, input) => {
+     const { name } = input as { name: string };
+     return { greeting: `Hello, ${name}` };
+   });
+   ```
+3. Available in handlers: `ctx.db`, `ctx.storage`, `ctx.rateLimit`, `ctx.userId`, `ctx.user`
+
+## Adding a new database collection
+
+1. Add to `shared/collections.ts`:
+   ```typescript
+   export const collections = defineCollections({
+     myCollection: { cache: false, trackable: true, public: true, parent: null },
+   });
+   ```
+2. Add TypeScript interface to `shared/types.ts` (create if needed)
+3. Add indexes to `shared/dbIndexes.ts` (create if needed)
+4. Run `yarn db:init`
+
+## Changing existing data (DB migrations)
+
+NEVER just change a TypeScript type for existing data — write a migration:
+1. Create `server/migrations/NNN-description.ts`:
+   ```typescript
+   export const name = 'NNN-description';
+   export async function up(db: Db) {
+     await db.collection('myCollection').updateMany({}, { $set: { newField: 'default' } });
+   }
+   ```
+2. Run `yarn db:migrate`
+
+## Static assets
+- Build-time files (favicon, fonts, OG images): `client/public/`
+- User-uploaded files: `ctx.storage.getUploadUrl()` then `ctx.storage.moveToPublic()`
+- Never hardcode `/asset/...` paths — use the buildId from `shared/Build.ts`
+
+## Environment variables
+- Adding a new one: add to `.env` AND `.env.example` with a comment
+- Never read `process.env` in client code (use `import.meta.env.VITE_*`)
+- Never commit `.env`
+
+## Auth
+- Default: ugly.bot OAuth popup — works out of the box, no config needed
+- `ctx.userId`: always a non-null string in authenticated handlers
+- Public handlers: use `defineRequests()` for unauthenticated reads
+
+## Showing Popups / Modals
+
+**Always use `useRouter().openPopup()` — never build custom fixed overlays.**
+
+The `RouterProvider` (in `client/main.tsx`) manages a popup layer with proper z-index, backdrop, and animation. Use it for all popups, modals, and sheets.
+
+```tsx
+import { useRouter } from '@/router'
+
+function MyComponent() {
+  const { openPopup } = useRouter()
+
+  function handleOpen() {
+    openPopup(<MyContent />, { mode: 'transient' })
+    // mode: 'block'      — dark backdrop (40%), clicking it does NOT dismiss
+    // mode: 'transient'  — light backdrop (20%), clicking it dismisses
+    // mode: 'contextMenu'— same as transient, for menus/pickers
+    // slideFrom: 'bottom' | 'top' | 'left' | 'right' | 'none'
+  }
+}
+```
+
+To dismiss programmatically:
+```tsx
+const handle = openPopup(<MyContent />, { mode: 'block' })
+handle.hide()
+```
+
+For simple dialogs, `Modal` from `website-core/client` wraps content with backdrop + Escape key handling:
+```tsx
+import { Modal } from 'website-core/client'
+{open && <Modal title="My Dialog" onClose={() => setOpen(false)}><p>Content</p></Modal>}
+```
+
+**In tests:** mock `../../router` to stub `useRouter`:
+```tsx
+const mockOpenPopup = vi.fn().mockReturnValue({ id: '1', hide: vi.fn() })
+vi.mock('../../router', () => ({ useRouter: () => ({ openPopup: mockOpenPopup }) }))
+```
+
+## Common mistakes to avoid
+- Do NOT use in-memory Maps for per-user state — use Redis or MongoDB (multi-server safe)
+- Do NOT change collection field types without a migration
+- Do NOT make NATS subscriptions without storing and calling the returned `unsub()` function
+- Do NOT skip `ctx.rateLimit.check()` before expensive operations (AI, storage, email)
+- Do NOT add `any` types — the TypeScript config enforces `noExplicitAny`
+
+## Feedback System
+
+The feedback button is always present at `[data-id="feedback-button"]` (bottom-right corner).
+Bots can trigger it by calling `document.querySelector('[data-id="feedback-button"]').click()`.
+Users see their feedback history at `GET /my_feedback` (returns markdown, requires auth cookie).
+The maintain bot resolves feedback via the `resolveFeedback` socket function (requires MAINTAIN_BOT_USER_ID).
+
+## AI Providers
+
+Use `createTextGen(userId, { provider })` or `createImageGen(userId, { provider })`.
+All providers are optional — only configured keys are active.
+
+### Text Generation
+
+| Provider | `provider` value | JSON | Tools | Vision | Best for |
+|---|---|---|---|---|---|
+| Together AI (Llama-4-Scout) | `'together'` | ✅ | ✅ | ✅ | Fast, cheap, 10M context |
+| Anthropic (claude-sonnet-4-6) | `'claude'` | ✅ | ✅ | ✅ | Complex reasoning, code |
+| OpenAI (gpt-4o) | `'openai'` | ✅ | ✅ | ✅ | General purpose |
+| Google (gemini-2.0-flash) | `'google'` | ✅ | ✅ | ✅ | Very long context (1M) |
+| Groq (llama-3.3-70b) | `'groq'` | ✅ | ✅ | ❌ | Ultra-fast, no vision |
+
+Use `provider: 'auto'` (default) to let the system pick based on requirements.
+
+### JSON Generation (type-safe)
+
+```typescript
+import { z } from 'zod'
+const schema = z.object({ title: z.string(), tags: z.array(z.string()) })
+const result = await textGen.generateJson(schema, messages)
+// result typed as { title: string, tags: string[] }
+// Retries up to 3 times on schema validation failure
+```
+
+### Tool Calling
+
+```typescript
+const result = await textGen.generateWithTools(messages, {
+  myTool: {
+    description: 'What the tool does',
+    input: z.object({ param: z.string() }),
+    handler: async ({ param }) => ({ result: 'value' })
+  }
+})
+// Tool loop runs automatically until model produces final text (max 5 rounds)
+```
+
+### Image Generation
+
+| Provider | `provider` value | Best for |
+|---|---|---|
+| Together AI (FLUX schnell) | `'together'` | Free tier, fast |
+| FAL (FLUX pro) | `'fal'` | High quality |
+| Google (Imagen 3) | `'google'` | Photorealistic |
+
+### Adding a Custom Provider
+
+```typescript
+// In server/index.ts, before createApp():
+import { registerTextGenProvider } from 'website-core'
+
+registerTextGenProvider({
+  name: 'mistral',
+  apiKeyEnv: 'MISTRAL_API_KEY',
+  capabilities: { json: true, tools: true, vision: false, maxContextTokens: 32_000 },
+  costPerMillionInputTokens: 0.20,
+  costPerMillionOutputTokens: 0.60,
+  generate: (messages, opts) => { /* your implementation */ },
+})
+```

package/templates/client/App.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import type { AppSocket } from 'website-core/client';
+import { FeedbackButton } from 'website-core/client';
+import type { AppRegistry } from '../shared/api.js';
+import { AuthDemoPage } from './pages/AuthDemoPage.js';
+import { HomePage } from './pages/HomePage.js';
+import { SearchPage } from './pages/SearchPage.js';
+import { UserPage } from './pages/UserPage.js';
+
+interface AppProps {
+  socket: AppSocket<AppRegistry> | null;
+}
+
+function Router(): React.ReactElement {
+  const path = window.location.pathname;
+
+  if (path.startsWith('/auth-demo')) return <AuthDemoPage />;
+  if (path.startsWith('/user/')) {
+    const userId = path.split('/')[2] ?? '';
+    return <UserPage userId={userId} />;
+  }
+  if (path.startsWith('/search')) return <SearchPage />;
+  return <HomePage />;
+}
+
+export default function App({ socket }: AppProps): React.ReactElement {
+  return (
+    <>
+      <Router />
+      <FeedbackButton socket={socket} />
+    </>
+  );
+}

package/templates/client/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>App</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/client/main.tsx"></script>
+  </body>
+</html>

package/templates/client/main.tsx

@@ -0,0 +1,52 @@
+import { createRoot } from 'react-dom/client';
+import { AppProvider, createSocket, LoginPopup } from 'website-core/client';
+import { functions, requests } from '../shared/api.js';
+import App from './App.js';
+import { RouterProvider } from './router.js';
+
+const root = createRoot(document.getElementById('root')!);
+
+const loginPopup = (
+  <LoginPopup
+    uglyBotUrl={import.meta.env.VITE_UGLY_BOT_URL ?? 'https://ugly.bot'}
+    onSuccess={() => {
+      window.location.reload();
+    }}
+  />
+);
+
+// Token is injected server-side from the auth_token cookie — no localStorage needed
+const token = (window as unknown as { __AUTH_TOKEN__?: string }).__AUTH_TOKEN__;
+
+if (!token) {
+  root.render(
+    <RouterProvider
+      fallback={<div>404 — Page not found</div>}
+      loginFallback={loginPopup}
+      isAuthenticated={() => false}
+    >
+      <App socket={null} />
+    </RouterProvider>,
+  );
+} else {
+  const userId = JSON.parse(atob(token.split('.')[1]!)).sub as string;
+  const socket = createSocket({ functions, requests, url: '/rpc' });
+  socket
+    .connect(token)
+    .then((user) => {
+      root.render(
+        <RouterProvider
+          fallback={<div>404 — Page not found</div>}
+          loginFallback={loginPopup}
+          isAuthenticated={() => true}
+        >
+          <AppProvider socket={socket} userId={userId} user={user}>
+            <App socket={socket} />
+          </AppProvider>
+        </RouterProvider>,
+      );
+    })
+    .catch(() => {
+      window.location.reload();
+    });
+}

package/templates/client/pages/AuthDemoPage.tsx

@@ -0,0 +1,85 @@
+import React from 'react';
+import { Button, Card, PageLayout, Text, useApp } from 'website-core/client';
+
+function AuthDemoAuthenticated(): React.ReactElement {
+  const app = useApp();
+
+  async function handleLogout(): Promise<void> {
+    await fetch('/auth/logout', { method: 'POST' });
+    window.location.reload();
+  }
+
+  return (
+    <PageLayout
+      header={
+        <div className="px-6 py-4">
+          <a href="/" className="text-blue-600">
+            ← Home
+          </a>
+        </div>
+      }
+    >
+      <div className="max-w-md mx-auto">
+        <Text size="xl" weight="bold">
+          Auth Demo
+        </Text>
+        <Card className="mt-4">
+          <Text weight="bold">Logged In</Text>
+          <pre className="mt-2 text-sm bg-gray-100 dark:bg-gray-900 p-3 rounded overflow-auto">
+            {JSON.stringify(
+              {
+                userId: app.userId,
+                email: app.user.email,
+                phone: app.user.phone,
+              },
+              null,
+              2,
+            )}
+          </pre>
+          <Button variant="secondary" onClick={handleLogout} className="mt-4">
+            Logout
+          </Button>
+        </Card>
+      </div>
+    </PageLayout>
+  );
+}
+
+function AuthDemoUnauthenticated(): React.ReactElement {
+  function handleLogin(): void {
+    // The RouterProvider's loginFallback will show the login popup for auth-required routes.
+    // For a manual trigger, redirect to initiate the OAuth flow.
+    window.location.href = '/?login=1';
+  }
+
+  return (
+    <PageLayout
+      header={
+        <div className="px-6 py-4">
+          <a href="/" className="text-blue-600">
+            ← Home
+          </a>
+        </div>
+      }
+    >
+      <div className="max-w-md mx-auto">
+        <Text size="xl" weight="bold">
+          Auth Demo
+        </Text>
+        <Card className="mt-4">
+          <Text>You are not logged in.</Text>
+          <Button onClick={handleLogin} className="mt-4">
+            Login with ugly.bot
+          </Button>
+        </Card>
+      </div>
+    </PageLayout>
+  );
+}
+
+export function AuthDemoPage(): React.ReactElement {
+  const isLoggedIn = !!(window as unknown as { __AUTH_TOKEN__?: string })
+    .__AUTH_TOKEN__;
+  if (isLoggedIn) return <AuthDemoAuthenticated />;
+  return <AuthDemoUnauthenticated />;
+}

package/templates/client/pages/HomePage.tsx

@@ -0,0 +1,111 @@
+import React from 'react';
+import { Button, Card, PageLayout, Text, useApp } from 'website-core/client';
+
+function HomePageAuthenticated(): React.ReactElement {
+  const app = useApp();
+
+  async function handleLogout(): Promise<void> {
+    await fetch('/auth/logout', { method: 'POST' });
+    window.location.reload();
+  }
+
+  return (
+    <PageLayout
+      header={
+        <div className="flex items-center justify-between px-6 py-4">
+          <Text size="lg" weight="bold">
+            My App
+          </Text>
+          <Button variant="secondary" onClick={handleLogout}>
+            Logout
+          </Button>
+        </div>
+      }
+    >
+      <HomePageBody userId={app.userId} />
+    </PageLayout>
+  );
+}
+
+function HomePageUnauthenticated(): React.ReactElement {
+  function handleLogin(): void {
+    // Trigger login — navigate to /auth-demo or show login popup via RouterProvider
+    window.location.href = '/auth-demo';
+  }
+
+  return (
+    <PageLayout
+      header={
+        <div className="flex items-center justify-between px-6 py-4">
+          <Text size="lg" weight="bold">
+            My App
+          </Text>
+          <Button variant="primary" onClick={handleLogin}>
+            Login
+          </Button>
+        </div>
+      }
+    >
+      <HomePageBody userId={null} />
+    </PageLayout>
+  );
+}
+
+function HomePageBody({
+  userId,
+}: {
+  userId: string | null;
+}): React.ReactElement {
+  return (
+    <div className="max-w-2xl mx-auto">
+      <Card>
+        <Text size="xl" weight="bold">
+          Welcome
+        </Text>
+        {userId ? (
+          <Text className="mt-2 text-gray-600 dark:text-gray-400">
+            Logged in as: {userId}
+          </Text>
+        ) : (
+          <Text className="mt-2 text-gray-600 dark:text-gray-400">
+            This app was built with website-core.
+          </Text>
+        )}
+      </Card>
+
+      <div className="mt-6 grid gap-4">
+        <a href="/auth-demo" className="block">
+          <Card className="hover:shadow-md transition-shadow cursor-pointer">
+            <Text weight="medium">Auth Demo →</Text>
+            <Text size="sm" className="text-gray-500 mt-1">
+              See login/logout and user info
+            </Text>
+          </Card>
+        </a>
+        <a href="/user/example-user-id" className="block">
+          <Card className="hover:shadow-md transition-shadow cursor-pointer">
+            <Text weight="medium">Path Params Demo →</Text>
+            <Text size="sm" className="text-gray-500 mt-1">
+              URL: /user/:userId
+            </Text>
+          </Card>
+        </a>
+        <a href="/search?q=hello" className="block">
+          <Card className="hover:shadow-md transition-shadow cursor-pointer">
+            <Text weight="medium">Query Params Demo →</Text>
+            <Text size="sm" className="text-gray-500 mt-1">
+              URL: /search?q=...
+            </Text>
+          </Card>
+        </a>
+      </div>
+    </div>
+  );
+}
+
+export function HomePage(): React.ReactElement {
+  const isLoggedIn = !!(window as unknown as { __AUTH_TOKEN__?: string })
+    .__AUTH_TOKEN__;
+  if (isLoggedIn) return <HomePageAuthenticated />;
+  return <HomePageUnauthenticated />;
+}

package/templates/client/pages/SearchPage.tsx

@@ -0,0 +1,48 @@
+import React, { useState } from 'react';
+import { Card, Input, PageLayout, Text } from 'website-core/client';
+
+export function SearchPage(): React.ReactElement {
+  const initialQ = new URLSearchParams(window.location.search).get('q') ?? '';
+  const [query, setQuery] = useState(initialQ);
+
+  function handleQueryChange(v: string): void {
+    setQuery(v);
+    const url = new URL(window.location.href);
+    url.searchParams.set('q', v);
+    window.history.replaceState(null, '', url.toString());
+  }
+
+  return (
+    <PageLayout
+      header={
+        <div className="px-6 py-4">
+          <a href="/" className="text-blue-600">
+            ← Home
+          </a>
+        </div>
+      }
+    >
+      <div className="max-w-md mx-auto">
+        <Text size="xl" weight="bold">
+          Search
+        </Text>
+        <div className="mt-4">
+          <Input
+            label="Search query"
+            value={query}
+            onChange={handleQueryChange}
+            placeholder="Search..."
+          />
+        </div>
+        <Card className="mt-4">
+          <Text size="sm" className="text-gray-500">
+            Query parameter:
+          </Text>
+          <Text weight="bold" className="font-mono mt-1">
+            ?q={query}
+          </Text>
+        </Card>
+      </div>
+    </PageLayout>
+  );
+}

package/templates/client/pages/UserPage.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+import { Card, PageLayout, Text } from 'website-core/client';
+
+export function UserPage({ userId }: { userId: string }): React.ReactElement {
+  return (
+    <PageLayout
+      header={
+        <div className="px-6 py-4">
+          <a href="/" className="text-blue-600">
+            ← Home
+          </a>
+        </div>
+      }
+    >
+      <div className="max-w-md mx-auto">
+        <Text size="xl" weight="bold">
+          User Profile
+        </Text>
+        <Card className="mt-4">
+          <Text size="sm" className="text-gray-500">
+            Path parameter:
+          </Text>
+          <Text weight="bold" className="font-mono mt-1">
+            /user/{userId}
+          </Text>
+          <Text size="sm" className="text-gray-500 mt-3">
+            userId = <code>{userId}</code>
+          </Text>
+        </Card>
+      </div>
+    </PageLayout>
+  );
+}

package/templates/client/router.ts

@@ -0,0 +1,4 @@
+import { createRouter } from 'website-core/client';
+import { pages } from '../shared/pages.js';
+
+export const { RouterProvider, useRouter } = createRouter({ pages });

package/templates/docker-compose.yml

@@ -0,0 +1,50 @@
+services:
+  mongodb:
+    image: mongodb/mongodb-atlas-local:8.0
+    restart: unless-stopped
+    ports:
+      - '${PORT_MONGO:-3003}:27017'
+    volumes:
+      - mongodb_data:/data/db
+
+  minio:
+    image: minio/minio:RELEASE.2024-11-07T00-52-20Z
+    ports:
+      - '${PORT_MINIO:-3006}:9000'
+      - '${PORT_MINIO_CONSOLE:-3007}:9001'
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    volumes:
+      - minio_data:/data
+
+  minio-init:
+    image: minio/mc:RELEASE.2024-11-07T00-37-53Z
+    depends_on: [minio]
+    restart: 'no'
+    entrypoint: >
+      /bin/sh -c "
+      until mc alias set local http://minio:9000 minioadmin minioadmin; do sleep 1; done;
+      mc mb --ignore-existing local/public;
+      mc mb --ignore-existing local/temp;
+      mc anonymous set download local/public;
+      mc anonymous set download local/temp;
+      exit 0;"
+
+  nats:
+    image: nats:2-alpine
+    command: ['-js']
+    ports:
+      - '${PORT_NATS:-3005}:4222'
+    restart: unless-stopped
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - '${PORT_REDIS:-3004}:6379'
+    restart: unless-stopped
+
+volumes:
+  mongodb_data:
+  minio_data:

package/templates/index.html

@@ -0,0 +1,14 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/x-icon" href="/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>App</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/client/main.tsx"></script>
+  </body>
+</html>