flingit 0.0.1

package/templates/default/CLAUDE.md

@@ -0,0 +1,197 @@
+# Fling Project
+
+This is a Fling project - a personal software platform for building and deploying personal tools with a React frontend and Hono API backend.
+
+## IMPORTANT: Do NOT ask about deployment, hosting, or technology choices!
+
+Fling handles all of this automatically. When the user asks you to build something:
+1. Write backend code in `src/worker/index.ts` using the Fling API
+2. Write frontend code in `src/react-app/` using React
+3. Run `npm start` to test it locally (you have bash access - run commands yourself!)
+4. When it works, run `npm exec fling push` to deploy
+
+**IMPORTANT: Run CLI commands yourself.** You have bash access. Do NOT ask the user to run commands like `fling push`, `fling dev`, or `npm start`. Execute them directly and report the results.
+
+## Project Structure
+
+```
+src/
+  worker/
+    index.ts         # Backend API entry point (routes, migrations)
+  react-app/
+    main.tsx         # React entry point
+    App.tsx          # Main React component
+    App.css          # Component styles
+    index.css        # Global styles
+public/              # Static assets (served by Vite)
+index.html           # Vite entry HTML
+vite.config.ts       # Vite configuration
+.fling/secrets       # Local secrets (gitignored)
+.fling/data/         # SQLite database (gitignored)
+```
+
+## Development
+
+Run `npm start` (or `fling dev`) to start development:
+- **Frontend**: http://localhost:5173 (Vite with React HMR)
+- **API**: http://localhost:3210 (Hono backend)
+- Vite proxies `/api/*` requests to the API server
+
+## Fling API (Backend)
+
+All primitives are imported from `"fling"` in the backend:
+
+```typescript
+import { app, db, migrate, secrets } from "fling";
+```
+
+### HTTP Routes (Hono)
+
+```typescript
+// API routes should use /api prefix for Vite proxy
+app.get("/api/hello", (c) => c.json({ message: "Hello!" }));
+app.post("/api/data", async (c) => {
+  const body = await c.req.json();
+  return c.json({ received: body });
+});
+```
+
+### Migrations
+
+**IMPORTANT: Migrations MUST be idempotent** (safe to run multiple times).
+
+```typescript
+migrate("001_create_users", async () => {
+  await db.prepare(`
+    CREATE TABLE IF NOT EXISTS users (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL,
+      created_at TEXT DEFAULT (datetime('now'))
+    )
+  `).run();
+});
+```
+
+### Database (SQLite, D1-compatible)
+
+```typescript
+// Query
+const item = await db.prepare("SELECT * FROM items WHERE id = ?").bind(id).first();
+const all = await db.prepare("SELECT * FROM items").all();
+
+// Insert/Update/Delete
+await db.prepare("INSERT INTO items (name) VALUES (?)").bind(name).run();
+```
+
+### Secrets
+
+```typescript
+const apiKey = secrets.get("API_KEY");  // Throws if not set
+```
+
+## React Frontend
+
+The frontend is a standard React + Vite setup. Call the backend API:
+
+```typescript
+// In React components
+useEffect(() => {
+  fetch("/api/hello")
+    .then(res => res.json())
+    .then(data => setMessage(data.message));
+}, []);
+```
+
+## CLI Commands
+
+Always use `npm exec` to run the project's Fling:
+
+```bash
+npm exec fling dev              # Start local dev server (API + Vite)
+npm exec fling dev -- --port 8080  # Custom API port
+npm exec fling db sql "SELECT * FROM users"  # Query local SQLite
+npm exec fling db reset         # Wipe local database
+npm exec fling db sql "SELECT * FROM users"  # Query local SQLite
+npm exec fling secret set K=V   # Set local secret
+npm exec fling secret list      # List local secrets
+npm exec fling logs             # View local logs
+npm exec fling push             # Build and deploy to production
+```
+
+### Local vs Production (`--prod`)
+
+Most CLI commands operate on the **local** environment by default. Add `--prod` for production (logs and db only):
+
+```bash
+# Local (default)
+npm exec fling secret list              # Local secrets
+npm exec fling logs                     # Local logs
+npm exec fling db sql "SELECT 1"        # Local SQLite
+
+# Production (requires login)
+npm exec fling -- --prod logs              # Deployed logs
+npm exec fling -- --prod db sql "SELECT 1" # Deployed D1
+```
+
+**Secrets:** Always stored locally in `.fling/secrets`. Use `fling push` to deploy secrets to production along with your code.
+
+## Deployment
+
+`fling push` handles everything automatically:
+
+1. Builds React frontend with Vite → `dist/client/`
+2. Uploads static assets (HTML, JS, CSS, images, fonts)
+3. Bundles backend code with esbuild
+4. Deploys to Cloudflare Workers
+
+**Limits:** 25MB per file, 100MB total assets.
+
+**Routing in production:**
+- `/api/*` → Backend worker code
+- Everything else → Static assets from `dist/client/`
+- SPA fallback: Unknown paths serve `index.html`
+
+## Platform Limitations
+
+Be aware of these constraints when building:
+
+### Feature Scope
+- **Supported:** Frontend (React), backend (Hono API), database (SQLite/D1)
+- **Not yet supported:** Cron jobs, file/blob storage, websockets
+- If the user needs unsupported features, encourage them to send feedback via `npm exec fling feedback`
+
+### Backend Memory (128MB limit)
+- The backend runs in a Cloudflare Worker with ~128MB memory
+- Cannot process large datasets in memory all at once
+- For large data: use streaming, pagination, or chunked processing
+- Example: process files line-by-line instead of loading entirely into memory
+
+### Cloudflare Workers Runtime
+- Workers do NOT have the full Node.js API
+- Some npm packages won't work (those requiring `fs`, `path`, `child_process`, native modules)
+- Must use Workers-compatible packages (check package docs for "Cloudflare Workers" or "edge runtime" support)
+- Web standard APIs work fine (fetch, crypto.subtle, TextEncoder, etc.)
+
+**If the user's request might hit these limitations, warn them early and suggest alternatives.**
+
+## Key Points
+
+- **Don't ask about hosting** - Fling handles deployment
+- **Don't ask about databases** - Use `db` from fling
+- **Don't suggest external services** - Fling provides what you need
+- **Use /api prefix** - For Vite proxy to work in development
+- **Run commands yourself** - You have bash access, don't ask the user to run CLI commands
+
+## After First Deployment
+
+After your first `fling push`, consider asking the user if they want a custom URL.
+Their project was auto-assigned a slug like `proj-abc123`.
+
+To change it: `npm exec fling project slug:set my-custom-slug`
+
+Slugs must be:
+- More than 4 characters
+- Lowercase alphanumeric with optional hyphens
+- Globally unique across all Fling projects
+
+See `.claude/skills/fling/` for detailed API documentation.

package/templates/default/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Fling App</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/react-app/main.tsx"></script>
+  </body>
+</html>

package/templates/default/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "fling-project",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "fling dev",
+    "start": "fling dev",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "flingit": "^0.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "vite": "^6.0.5",
+    "@vitejs/plugin-react": "^4.3.4",
+    "@tailwindcss/vite": "^4",
+    "tailwindcss": "^4",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "typescript": "~5.6.2"
+  }
+}

package/templates/default/public/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFBD4F"></stop><stop offset="100%" stop-color="#FF980E"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

package/templates/default/skills/fling/API.md

@@ -0,0 +1,335 @@
+# Fling API Reference
+
+## HTTP (Hono)
+
+Fling uses [Hono](https://hono.dev) for HTTP routing. The `app` export is a configured Hono instance.
+
+### Basic Routes
+
+```typescript
+import { app } from "fling";
+
+// GET request
+app.get("/path", (c) => {
+  return c.text("Plain text response");
+});
+
+// POST request with JSON body
+app.post("/api/items", async (c) => {
+  const body = await c.req.json();
+  return c.json({ id: 1, ...body });
+});
+
+// URL parameters
+app.get("/items/:id", (c) => {
+  const id = c.req.param("id");
+  return c.json({ id });
+});
+
+// Query parameters
+app.get("/search", (c) => {
+  const q = c.req.query("q");
+  return c.json({ query: q });
+});
+```
+
+### Response Types
+
+```typescript
+// Plain text
+return c.text("Hello");
+
+// JSON
+return c.json({ key: "value" });
+
+// HTML
+return c.html("<h1>Hello</h1>");
+
+// Custom content type
+return c.text(xmlContent, 200, { "Content-Type": "application/rss+xml" });
+
+// Binary data
+return c.body(buffer, 200, { "Content-Type": "image/png" });
+
+// Status codes
+return c.text("Not found", 404);
+return c.json({ error: "Bad request" }, 400);
+```
+
+### Headers and Cookies
+
+```typescript
+// Read headers
+const auth = c.req.header("Authorization");
+
+// Set headers
+return c.text("OK", 200, { "X-Custom": "value" });
+
+// Cookies
+const session = c.req.cookie("session");
+c.cookie("session", "value", { httpOnly: true });
+```
+
+## Migrations
+
+Database migrations run automatically on app startup. Each migration executes exactly once and is tracked in the `_migrations` table.
+
+### Basic Usage
+
+```typescript
+import { migrate, db } from "fling";
+
+// Migrations run in alphabetical order by name
+migrate("001_create_users", async () => {
+  await db.prepare(`
+    CREATE TABLE users (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL,
+      email TEXT UNIQUE,
+      created_at TEXT DEFAULT (datetime('now'))
+    )
+  `).run();
+});
+
+migrate("002_create_posts", async () => {
+  await db.prepare(`
+    CREATE TABLE posts (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      user_id INTEGER NOT NULL REFERENCES users(id),
+      title TEXT NOT NULL,
+      content TEXT,
+      created_at TEXT DEFAULT (datetime('now'))
+    )
+  `).run();
+});
+
+migrate("003_add_user_avatar", async () => {
+  await db.prepare(`ALTER TABLE users ADD COLUMN avatar_url TEXT`).run();
+});
+```
+
+### Naming Convention
+
+Use numeric prefixes to ensure correct execution order:
+- `001_create_users`
+- `002_create_posts`
+- `003_add_user_avatar`
+- `010_add_comments` (leaves room for insertions)
+
+Migrations run in **alphabetical order**, so numeric prefixes guarantee the intended sequence.
+
+### Startup Sequence
+
+When your app starts:
+
+1. **Import phase**: Routes and migrations are registered (not executed)
+2. **Migration phase**: All pending migrations run in order
+3. **Server phase**: HTTP server begins accepting requests
+
+**Critical**: The HTTP server does NOT start until all migrations complete successfully. If any migration fails, the entire startup aborts.
+
+### Failure Behavior
+
+If a migration fails:
+- A detailed error is logged with the migration name and stack trace
+- The failed migration is NOT recorded (allowing retry on restart)
+- The server does NOT start
+- Previously successful migrations in the same run ARE recorded
+
+```
+============================================================
+MIGRATION FAILED: 003_add_user_avatar
+============================================================
+Type: SqliteError
+Message: duplicate column name: avatar_url
+Code: SQLITE_ERROR
+
+Stack trace:
+SqliteError: duplicate column name: avatar_url
+    at Database.prepare (...)
+    at Object.handler (file:///path/to/src/app.ts:25:9)
+    at runMigrations (...)
+============================================================
+```
+
+The error output includes:
+- **Type**: The error class (e.g., `SqliteError`)
+- **Message**: Human-readable description
+- **Code**: SQLite error code (e.g., `SQLITE_ERROR`, `SQLITE_CONSTRAINT_UNIQUE`)
+- **Stack trace**: Points to the exact line that failed
+
+### Idempotent Migrations
+
+Each migration runs exactly once. Use `IF NOT EXISTS` and `IF EXISTS` for safety:
+
+```typescript
+migrate("001_create_users", async () => {
+  // Safe to run multiple times if migration tracking fails
+  await db.prepare(`
+    CREATE TABLE IF NOT EXISTS users (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL
+    )
+  `).run();
+});
+```
+
+### Data Migrations
+
+Migrations can also modify data:
+
+```typescript
+migrate("004_normalize_emails", async () => {
+  await db.prepare(`
+    UPDATE users SET email = LOWER(email) WHERE email IS NOT NULL
+  `).run();
+});
+```
+
+### Important Notes
+
+- Migrations MUST be declared at module top-level (not inside functions)
+- Each migration must have a unique name
+- Always use `await db.prepare(...).run()` for DDL statements (not `db.exec()` - it doesn't work in production D1)
+- Tables starting with `_` are reserved for the system (`_migrations`, `_fling_logs`)
+- Do NOT perform database operations at module top-level outside of migrations
+- The `_migrations` table is created automatically on first migration
+
+### Migration vs Top-Level Code
+
+**Wrong** - DB access at module load time:
+```typescript
+// DON'T DO THIS - runs during import, before migrations
+const users = await db.prepare("SELECT * FROM users").all();
+```
+
+**Correct** - DB access in migrations and handlers:
+```typescript
+// Migrations run at startup in correct order
+migrate("001_create_users", async () => {
+  await db.prepare(`CREATE TABLE users ...`).run();
+});
+
+// Route handlers run after migrations complete
+app.get("/users", async (c) => {
+  const { results } = await db.prepare("SELECT * FROM users").all();
+  return c.json(results);
+});
+```
+
+## Database
+
+SQLite locally, Cloudflare D1 in production. API matches D1.
+
+### Queries
+
+```typescript
+import { db } from "fling";
+
+// Single row
+const user = await db.prepare("SELECT * FROM users WHERE id = ?")
+  .bind(userId)
+  .first();
+// Returns: { id: 1, name: "Alice" } or null
+
+// All rows
+const users = await db.prepare("SELECT * FROM users ORDER BY name")
+  .all();
+// Returns: { results: [{ id: 1, name: "Alice" }, ...] }
+
+// With multiple parameters
+const items = await db.prepare("SELECT * FROM items WHERE status = ? AND category = ?")
+  .bind("active", "tools")
+  .all();
+```
+
+### Mutations
+
+```typescript
+// Insert
+const result = await db.prepare("INSERT INTO users (name, email) VALUES (?, ?)")
+  .bind("Alice", "alice@example.com")
+  .run();
+// Returns: { success: true, meta: { changes: 1, last_row_id: 5 } }
+
+// Update
+await db.prepare("UPDATE users SET name = ? WHERE id = ?")
+  .bind("Bob", 1)
+  .run();
+
+// Delete
+await db.prepare("DELETE FROM users WHERE id = ?")
+  .bind(1)
+  .run();
+```
+
+### Schema (DDL)
+
+Schema changes should be done in migrations (see Migrations section above):
+
+```typescript
+migrate("001_create_users", async () => {
+  await db.prepare(`
+    CREATE TABLE IF NOT EXISTS users (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL,
+      email TEXT UNIQUE,
+      created_at TEXT DEFAULT (datetime('now'))
+    )
+  `).run();
+
+  await db.prepare(`
+    CREATE INDEX IF NOT EXISTS idx_users_email ON users(email)
+  `).run();
+});
+```
+
+**Important**: Always use `db.prepare(...).run()` for DDL statements. The `db.exec()` method does not work in production D1 databases.
+
+### Important Notes
+
+- Schema changes should be done in migrations (see Migrations section)
+- Database queries should be in route handlers, not at module top-level
+- Use parameterized queries (?) to prevent SQL injection
+- `first()` returns null if no row found (undefined in local SQLite)
+- `all()` always returns `{ results: [...] }`
+- Tables starting with `_` are reserved for the system
+
+## Secrets
+
+Secure credential management. Throws if secret not set.
+
+```typescript
+import { secrets } from "fling";
+
+// Get a secret (throws if not set)
+const apiKey = secrets.get("API_KEY");
+
+// Check if secret exists
+if (secrets.has("OPTIONAL_KEY")) {
+  const key = secrets.get("OPTIONAL_KEY");
+}
+```
+
+### Managing Secrets
+
+```bash
+# Set/manage secrets locally
+fling secret set GITHUB_TOKEN=ghp_xxxx   # Set a secret
+fling secret list                         # List secret names
+fling secret remove GITHUB_TOKEN          # Remove a secret
+
+# Secrets are deployed automatically with:
+fling push
+```
+
+Secrets are always stored locally in `.fling/secrets`. When you run `fling push`, secrets are automatically synced to production along with your code.
+
+### Naming Convention
+
+Secret names must be uppercase with underscores:
+- `API_KEY` ✓
+- `GITHUB_TOKEN` ✓
+- `apiKey` ✗
+- `github-token` ✗
+