ugly-app 0.1.0

package/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git add:*)",
+      "Bash(git check-ignore:*)",
+      "Bash(ls -la /Users/admin/Documents/GitHub/app/server/backend/DB*)",
+      "Bash(npx tsc:*)",
+      "Bash(npx vitest:*)",
+      "Bash(grep -E \"\\\\.ts$\")",
+      "Bash(npm test:*)",
+      "Bash(git push:*)",
+      "Bash(git rm:*)",
+      "Bash(npm run:*)",
+      "Bash(git worktree:*)",
+      "Bash(git remote:*)"
+    ]
+  }
+}

package/.env.example

@@ -0,0 +1,9 @@
+# AI Providers (all optional — Together AI works with TOGETHER_API_KEY alone)
+ANTHROPIC_API_KEY=
+OPENAI_API_KEY=
+GOOGLE_API_KEY=
+GROQ_API_KEY=
+FAL_API_KEY=
+ELEVENLABS_API_KEY=
+DEEPGRAM_API_KEY=
+MAINTAIN_BOT_USER_ID=

package/.yarn-metadata.json

@@ -0,0 +1,113 @@
+{
+  "manifest": {
+    "name": "ugly-app",
+    "version": "0.1.0",
+    "type": "module",
+    "main": "./dist/server/index.js",
+    "exports": {
+      ".": "./dist/server/index.js",
+      "./shared": "./dist/shared/index.js",
+      "./client": "./dist/client/index.js",
+      "./playwright": "./dist/playwright/index.js",
+      "./webrtc": {
+        "default": "./dist/webrtc/index.js"
+      }
+    },
+    "bin": {
+      "web": "dist/cli/index.js"
+    },
+    "scripts": {
+      "build": "tsc",
+      "test": "vitest run",
+      "test:watch": "vitest"
+    },
+    "dependencies": {
+      "@anthropic-ai/sdk": "^0.80.0",
+      "@deepgram/sdk": "^5.0.0",
+      "elevenlabs": "^1.59.0",
+      "@aws-sdk/client-s3": "^3.700.0",
+      "@aws-sdk/s3-request-presigner": "^3.700.0",
+      "@fal-ai/client": "^1.9.4",
+      "@google/generative-ai": "^0.24.1",
+      "bcrypt": "^6.0.0",
+      "commander": "^12.0.0",
+      "concurrently": "^9.0.0",
+      "cookie-parser": "^1.4.7",
+      "express": "^4.21.1",
+      "fs-extra": "^11.0.0",
+      "groq-sdk": "^1.1.1",
+      "ioredis": "^5.10.1",
+      "jose": "^6.0.13",
+      "lru-cache": "^11.0.0",
+      "mongodb": "^6.18.0",
+      "nanoid": "^5.1.5",
+      "nats": "^2.28.2",
+      "openai": "^6.32.0",
+      "together-ai": "^0.13.0",
+      "ws": "^8.18.0",
+      "zod": "^4.3.6",
+      "handlebars": "^4.7.8",
+      "onnxruntime-node": "^1.23.0"
+    },
+    "devDependencies": {
+      "@playwright/test": "^1.58.2",
+      "@testing-library/dom": "^10.4.1",
+      "@testing-library/react": "^16.3.2",
+      "@types/bcrypt": "^5.0.2",
+      "@types/cookie-parser": "^1.4.10",
+      "@types/express": "^5.0.0",
+      "@types/fs-extra": "^11.0.4",
+      "@types/node": "^22.0.0",
+      "@types/react": "^19.2.14",
+      "@types/react-dom": "^19.2.3",
+      "@types/ws": "^8.5.13",
+      "@typescript-eslint/eslint-plugin": "^8.0.0",
+      "@typescript-eslint/parser": "^8.0.0",
+      "@vitejs/plugin-react": "^6.0.1",
+      "eslint": "^8.57.0",
+      "eslint-watch": "^7.0.0",
+      "html2canvas": "^1.4.1",
+      "jsdom": "^29.0.1",
+      "mongodb-memory-server": "^10.0.0",
+      "react": "^19.2.4",
+      "react-dom": "^19.2.4",
+      "typescript": "^5.9.3",
+      "vitest": "^4.0.18"
+    },
+    "peerDependencies": {
+      "@types/react": ">=18.0.0",
+      "html2canvas": ">=1.0.0",
+      "preact": ">=10.0.0",
+      "react": ">=18.0.0",
+      "react-dom": ">=18.0.0"
+    },
+    "peerDependenciesMeta": {
+      "@types/react": {
+        "optional": true
+      },
+      "html2canvas": {
+        "optional": true
+      },
+      "preact": {
+        "optional": true
+      },
+      "mediasoup": {
+        "optional": true
+      }
+    },
+    "_registry": "npm",
+    "_loc": "/Users/admin/Library/Caches/Yarn/v6/npm-ugly-app-0.1.0-d3eac800-7702-4eda-affb-29c511f7037a-1774140424109/node_modules/ugly-app/package.json",
+    "readmeFilename": "README.md",
+    "readme": "# website-core\n\nA full-stack TypeScript framework for building production-ready web applications. Provides an opinionated architecture combining an Express backend, React frontend, and MongoDB database with built-in authentication, real-time communication, storage, AI integration, and audio streaming.\n\n## What's Included\n\n- **Server**: Express with type-safe RPC routing and Zod schema validation\n- **WebSockets**: Bidirectional socket server/client with RPC calls, document tracking, and file uploads\n- **Database**: MongoDB with typed collections, cascade delete, indexes, migrations, and Change Streams\n- **Auth**: JWT + OAuth (ugly.bot by default, extensible via `AuthProvider` interface)\n- **Storage**: AWS S3 / Cloudflare R2 with presigned URLs and file promotion\n- **AI**: 5 text generation providers (Together, Claude, OpenAI, Google, Groq) + 3 image providers (Together, FAL, Google)\n- **Audio**: Text-to-speech and speech-to-text streaming with React hooks (`useTTS`, `useSTT`), optional viseme data for lip sync, and word-level timestamps\n- **Logging**: Multi-channel logging to MongoDB (error, console, perf, feedback) with server error capture, deduplication, and classification\n- **Queues**: NATS JetStream worker queues, Redis pub/sub with in-memory fallback\n- **Rate Limiting**: Per-user/per-operation token-bucket limiting with queue management\n- **Push Notifications**: Real-time delivery via WebSocket + Redis, with FCM support\n- **Feedback**: Built-in user feedback collection with screenshot capture\n- **CLI**: `web` command for dev, build, deploy, migrations, log queries, and auth utilities\n\n## Installation\n\n```bash\nnpm install website-core\n```\n\nPeer dependencies:\n\n```bash\nnpm install react react-dom html2canvas\n```\n\n## Quick Start\n\n### Scaffold a new project\n\n```bash\nnpx web init my-app\n```\n\n### Start development\n\n```bash\nyarn dev\n# Starts Docker services, Express server, Vite, TypeScript watcher, and ESLint concurrently\n```\n\n## Usage\n\n### Server\n\n```typescript\nimport { createApp } from 'website-core';\n\nconst app = await createApp({\n  authProvider,    // optional — defaults to ugly.bot OAuth\n  pages,           // optional — page definitions with SSR support\n  onSocketMessage, // optional — handle custom WebSocket messages\n  workerQueues,    // optional — background job queue configs\n  extendContext,   // optional — add fields to handler context\n});\n```\n\n### Shared types and API definitions\n\n```typescript\nimport { fn, req, defineFunctions, defineRequests } from 'website-core/shared';\nimport { z } from 'website-core/shared';\n\nexport const functions = defineFunctions({\n  greet: fn(\n    z.object({ name: z.string() }),\n    z.object({ message: z.string() })\n  ),\n});\n```\n\n### React client\n\n```typescript\nimport { AppProvider, useApp, createRouter, createSocket } from 'website-core/client';\n```\n\n## Key APIs\n\n### Server — `createApp()`\n\nRegisters handlers with full context (user, db, storage, textGen, imageGen, logger, rateLimit):\n\n```typescript\napp.registerFunction('greet', functions.greet, async ({ input, userId, db, logger }) => {\n  return { message: `Hello, ${input.name}` };\n});\n\napp.registerRequest('stream', requests.stream, async ({ input, res }) => {\n  // streaming HTTP handler\n});\n```\n\nBuilt-in routes: `GET /health`, `POST /auth/verify`, `GET /auth/url`, `POST /logs/client`, `GET /my_feedback`\n\n### Database — `createTypedDB()`\n\n```typescript\nimport { defineCollections, defineDbIndexes } from 'website-core/shared';\n\nconst collections = defineCollections({\n  notes: { schema: noteSchema, cascadeDelete: ['attachments'] },\n});\n\nconst db = createTypedDB(mongoClient, collections);\nawait db.notes.setDoc(id, data);\nawait db.notes.getDocs({ userId });\n```\n\n### WebSocket Client\n\n```typescript\nconst socket = createSocket({ url, registry });\n\nawait socket.call('greet', { name: 'world' });        // RPC call\nconst doc = await socket.getDoc('notes', id);          // fetch document\nsocket.trackDoc('notes', id, (doc) => { /* live */ }); // live updates\nawait socket.uploadFile(file, { bucket: 'temp' });     // file upload\n```\n\n### AI — Text Generation\n\n```typescript\nconst textGen = createTextGen({ provider: 'claude' });\n\nconst text = await textGen.generate({ messages, model });\nconst json = await textGen.generateJson({ messages, schema, model });\nconst result = await textGen.generateWithTools({ messages, tools, model });\n```\n\nSupported providers: `together`, `claude`, `openai`, `google`, `groq`\n\n### AI — Image Generation\n\n```typescript\nconst imageGen = createImageGen({ provider: 'fal' });\nconst url = await imageGen.generate(prompt, { width: 1024, height: 1024 });\n```\n\nSupported providers: `together`, `fal`, `google`\n\n### Audio — TTS/STT React Hooks\n\n```typescript\n// Text-to-speech\nconst { playing, currentWord, play, stop } = useTTS(socket);\nawait play('Hello world');\n\n// With viseme data for lip sync (opt-in — adds latency)\nawait play('Hello world', { requestVisemes: true });\n// viseme events arrive via onViseme callback in useTTS options\n\n// Speech-to-text\nconst { transcript, isFinal, listening, start, stop } = useSTT(socket, {\n  mode: 'realtime', // 'realtime' | 'batch' | 'auto'\n});\n\n// With word-level timestamps (opt-in — uses Groq verbose_json, slower)\nconst { transcript, words } = useSTT(socket, {\n  mode: 'batch',\n  requestWords: true,\n});\n// words: STTWord[] — each has { word, startMs, durationMs }\n```\n\nViseme and word types are exported from `website-core/shared`:\n\n```typescript\nimport type { TTSViseme, TTSVisemeName, STTWord } from 'website-core/shared';\n```\n\n### Rate Limiting\n\n```typescript\nconst rateLimit = createRateLimiter({\n  windowMs: 3600_000, // 1 hour\n  maxUnits: 1.0,\n  queueDepth: 5,\n});\n\nawait rateLimit.check(userId, 'generate', 0.1);\nawait rateLimit.charge(userId, 'generate', actualCost);\n```\n\n### Worker Queues\n\n```typescript\nconst queue = createWorkerQueue({ stream: 'jobs', subject: 'jobs.process' });\n\nawait queue.enqueue({ type: 'email', to: 'user@example.com' });\nqueue.registerHandler('email', async (job) => { /* process */ });\nawait queue.start();\n```\n\n### Storage\n\n```typescript\nconst storage = createStorageClient();\n\nconst key = await storage.put(buffer, { bucket: 'temp', ext: 'png' });\nconst publicKey = await storage.moveToPublic(key);\nconst url = storage.url(publicKey);\n\n// Browser direct upload\nconst { uploadUrl, key } = await socket.call('uploadUrl', { ext: 'jpg' });\n```\n\n### Logging\n\n```typescript\nconst logger = createLogger({ db, userId });\n\nlogger.info('User signed in', { userId });\nlogger.perf('query', durationMs, { collection: 'notes' });\nlogger.feedback('Feature request', { screenshot, context });\nlogger.error('Something failed', error);\n```\n\n### Server Error Capture\n\n`captureServerError` persists unexpected errors to a MongoDB `errorLog` collection with automatic deduplication (repeated errors increment a `count` field instead of inserting duplicates). Expected/recoverable errors can be suppressed from persistence by registering patterns.\n\n```typescript\nimport {\n  captureServerError,\n  registerExpectedErrorPattern,\n  classifyError,\n} from 'website-core';\n\n// Register known-recoverable patterns at startup — matched errors log to\n// console only and are never written to MongoDB\nregisterExpectedErrorPattern('ECONNRESET')\nregisterExpectedErrorPattern('[STT] Session ended before audio was received')\n\n// Capture an error in a catch block\ntry {\n  await riskyOperation()\n} catch (err) {\n  captureServerError('[MyService] Failed to process request', err, { userId })\n}\n\n// Classify a message manually ('expected' | 'unexpected')\nconst classification = classifyError('[STT] Session ended before audio was received')\n```\n\n### Push Notifications\n\n```typescript\nimport { sendPush } from 'website-core';\n\nawait sendPush(userId, { title: 'New message', body: 'You have a reply' });\n```\n\n## CLI Commands\n\n| Command | Description |\n|---|---|\n| `web init <name>` | Scaffold a new project |\n| `web dev` | Start all dev services (Docker, server, Vite, TS, ESLint) |\n| `web build` | Production build |\n| `web db:init` | Create/update MongoDB indexes |\n| `web db:migrate` | Run pending database migrations (`--status` to preview) |\n| `web publish:assets` | Deploy static assets to CDN (`--dry-run` to preview) |\n| `web purge:assets` | Remove old build artifacts (keeps last 3 by default) |\n| `web logs:local` | Query local dev logs |\n| `web logs:server` | Query server logs from MongoDB |\n| `web error:local` | Query local error logs |\n| `web error:server` | Query server error logs from MongoDB |\n| `web perf:local` | Query local performance metrics |\n| `web perf:server` | Query server performance metrics from MongoDB |\n| `web feedback` | Query user feedback submissions |\n| `web auth:create-account` | Create an account directly in the database |\n| `web auth:create-token` | Generate a JWT for a userId |\n| `web test:e2e` | Run Playwright end-to-end tests (`--headed` for browser UI) |\n\n## React Components\n\n```typescript\nimport {\n  Button, Card, Text, Input, Modal, Toast, PageLayout,\n  FeedbackButton,\n} from 'website-core/client';\n```\n\nThe `FeedbackButton` captures a screenshot and submits it with user context automatically.\n\n## Routing (Client)\n\n```typescript\nconst { useRouter, RouterProvider } = createRouter(pages);\n\nfunction App() {\n  const { push, replace, back } = useRouter();\n  return <RouterProvider fallback={<NotFound />} authGuard={<Login />} />;\n}\n```\n\nPage transitions are animated by default using `ViewFlipper`. The transition type (`PUSH`, `POP`, `REPLACE`, `NONE`) is inferred automatically from navigation calls.\n\n### Popups\n\n```typescript\nimport { usePopup } from 'website-core/client';\n\nfunction MyComponent() {\n  const { showPopup } = usePopup();\n\n  function openMenu() {\n    const handle = showPopup(<MyMenu />, {\n      mode: 'contextMenu',   // 'block' | 'transient' | 'contextMenu'\n      slideFrom: 'bottom',   // 'left' | 'right' | 'top' | 'bottom' | 'none'\n      onClose: () => console.log('closed'),\n      animConfig: { duration: 250 },\n    });\n\n    // Dismiss programmatically\n    handle.hide();\n  }\n}\n```\n\n- **`block`** — modal overlay, blocks interaction behind it\n- **`transient`** — tapping the backdrop closes it\n- **`contextMenu`** — same as transient but typically for menus/pickers\n\n### Animation Primitives\n\n```typescript\nimport {\n  createAnimatedValue,\n  useAnimatedValue,\n  Animated,\n  easingFunctions,\n} from 'website-core/client';\nimport type { EasingFunction } from 'website-core/client';\n\n// Imperative animated value (RAF-driven, no React re-renders)\nconst spring = createAnimatedValue(0);\nspring.animateTo(1, { duration: 300, easing: easingFunctions.easeInOut });\n\n// React hook version\nconst opacity = useAnimatedValue(0);\n\n// Apply to DOM via ref — zero re-renders\n<Animated value={spring} style={(v) => ({ opacity: v, transform: `scale(${v})` })}>\n  <div>Content</div>\n</Animated>\n```\n\n## Project Structure\n\nProjects built with `website-core` follow this layout:\n\n```\nmy-app/\n├── src/\n│   ├── server/      # Express handlers, DB collections, migrations\n│   ├── client/      # React pages and components\n│   └── shared/      # API definitions and shared types\n├── static/          # Build-time static assets\n└── docker-compose.dev.yml\n```\n\n## Environment Variables\n\n| Variable | Description |\n|---|---|\n| `MONGO_URL` | MongoDB connection string |\n| `JWT_SECRET` | Secret for signing JWT tokens |\n| `REDIS_URL` | Redis connection (optional, uses in-memory fallback) |\n| `NATS_URL` | NATS server URL |\n| `NATS_CREDS` | NATS credentials file path (Synadia Cloud) |\n| `R2_ACCOUNT_ID` | Cloudflare R2 account ID |\n| `R2_ACCESS_KEY_ID` | R2 access key |\n| `R2_SECRET_ACCESS_KEY` | R2 secret key |\n| `R2_BUCKET` | R2 bucket name |\n| `TOGETHER_API_KEY` | Together AI API key |\n| `ANTHROPIC_API_KEY` | Anthropic Claude API key |\n| `OPENAI_API_KEY` | OpenAI API key |\n| `GOOGLE_API_KEY` | Google Gemini API key |\n| `IS_CLOCK_SERVER` | Set to `true` on the instance that processes worker queues |\n\nClient-side variables must be prefixed with `VITE_`.\n\n## Tech Stack\n\n- **Runtime**: Node.js, TypeScript (ES2022, NodeNext modules)\n- **Server**: Express, ws (WebSockets)\n- **Frontend**: React 18, Vite, Tailwind CSS\n- **Database**: MongoDB\n- **Messaging**: NATS with JetStream\n- **Cache**: Redis (in-memory fallback for dev)\n- **Storage**: AWS S3 / Cloudflare R2\n- **Auth**: JWT (jose), OAuth\n- **AI**: Together AI, Anthropic, OpenAI, Google, Groq, FAL\n- **Audio**: InWorld TTS, Groq Whisper STT\n- **Validation**: Zod\n- **Testing**: Vitest, Playwright, mongodb-memory-server\n\n## Development\n\n```bash\nnpm run build       # Compile TypeScript\nnpm test            # Run unit tests\nnpm run test:watch  # Watch mode\n```\n",
+    "description": "A full-stack TypeScript framework for building production-ready web applications. Provides an opinionated architecture combining an Express backend, React frontend, and MongoDB database with built-in authentication, real-time communication, storage, AI integration, and audio streaming."
+  },
+  "artifacts": [],
+  "remote": {
+    "type": "copy",
+    "registry": "npm",
+    "hash": "1f1f44d3-e29b-4eb4-a53b-7939ba38f3b9-1774221755838",
+    "reference": "/Users/admin/Documents/GitHub/app/.worktrees/ugly-app"
+  },
+  "registry": "npm",
+  "hash": "1f1f44d3-e29b-4eb4-a53b-7939ba38f3b9-1774221755838"
+}