flingit 0.0.14 → 0.0.15

package/templates/default/CLAUDE.md

@@ -1,317 +1,5 @@
 # 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.
+This is a Fling project - a personal software platform for building and deploying personal tools with a React frontend, API backend, SQL database, storage, and more.
 
-## 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
-
-### Hot Module Replacement (HMR)
-
-The dev server provides hot reloading for both frontend AND backend - no restart needed:
-- **Frontend (React)**: Changes to `src/react-app/` are instantly reflected via Vite HMR
-- **Backend (Worker)**: Changes to `src/worker/` are automatically reloaded via tsx watch
-
-Just edit and save - changes appear immediately.
-
-## Fling API (Backend)
-
-All primitives are imported from `"flingit"` in the backend:
-
-```typescript
-import { app, db, migrate, secrets, cron, storage } from "flingit";
-```
-
-### 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 });
-});
-```
-
-**Note:** Paths starting with `/__` are reserved for internal platform use. Do not create routes with these prefixes.
-
-### 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
-```
-
-### Cron Jobs
-
-Schedule tasks to run automatically on a schedule using standard cron syntax:
-
-```typescript
-cron("daily-cleanup", "0 3 * * *", async () => {
-  // Runs at 3 AM daily
-  await db.prepare("DELETE FROM old_logs WHERE created_at < ?")
-    .bind(Date.now() - 86400000).run();
-});
-
-cron("hourly-report", "0 * * * *", async () => {
-  // Runs every hour - can return a result that's stored in history
-  const count = await processRecords();
-  return { processed: count };
-});
-```
-
-Cron expressions: `minute hour day-of-month month day-of-week`
-- `"0 9 * * *"` - 9 AM daily
-- `"*/15 * * * *"` - Every 15 minutes
-- `"0 0 * * 1"` - Midnight on Mondays
-
-Manage cron jobs with CLI:
-```bash
-npm exec fling cron list           # List all cron jobs
-npm exec fling cron history <name> # View invocation history
-npm exec fling cron trigger <name> # Manually trigger a job
-```
-
-### Storage (R2)
-
-Store and retrieve files. Uses local filesystem in development, Cloudflare R2 in production.
-
-```typescript
-import { storage } from "flingit";
-
-// Store objects
-await storage.put("images/logo.png", imageBuffer, { contentType: "image/png" });
-await storage.put("data/config.json", JSON.stringify(config));
-
-// Retrieve objects
-const file = await storage.get("images/logo.png");
-if (file) {
-  const buffer = await file.arrayBuffer();
-  const text = await file.text();
-  const json = await file.json<ConfigType>();
-  // Or stream: file.body (ReadableStream)
-}
-
-// Check existence without downloading
-const meta = await storage.head("images/logo.png");
-
-// Delete objects
-await storage.delete("old-file.txt");
-await storage.delete(["file1.txt", "file2.txt"]); // Batch delete
-
-// List objects
-const result = await storage.list({ prefix: "images/", limit: 100 });
-for (const obj of result.objects) {
-  console.log(`${obj.key}: ${obj.size} bytes`);
-}
-```
-
-Manage storage with CLI:
-```bash
-npm exec fling storage list              # List local storage objects
-npm exec fling storage put key file.txt  # Upload file to storage
-npm exec fling storage get key output    # Download object to file
-npm exec fling storage delete key --yes  # Delete object
-npm exec fling storage info              # Show storage stats
-```
-
-## 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 storage list     # List storage objects
-npm exec fling storage put K F  # Upload file F as key K
-npm exec fling storage get K O  # Download key K to file O
-npm exec fling push             # Build and deploy to production
-npm exec fling tunnel 3000      # Expose localhost:3000 via public URL
-```
-
-### Local vs Production (`--prod`)
-
-Most CLI commands operate on the **local** environment by default. Add `--prod` for production:
-
-```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
-npm exec fling storage list             # Local storage
-
-# Production (requires login)
-npm exec fling -- --prod logs              # Deployed logs
-npm exec fling -- --prod db sql "SELECT 1" # Deployed D1
-npm exec fling -- --prod storage list      # R2 storage
-```
-
-**Note:** Production logs have a delay of ~10 seconds or more before they appear.
-
-**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), cron jobs, file storage (R2), Discord integration
-- **Not yet supported:** 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.)
-
-### Backend Assets (Images, Fonts, etc.)
-
-If the backend needs to return or process an asset (image, icon, font), keep it small and store the base64 data in a separate file to keep your main code clean:
-
-```typescript
-// src/worker/assets/favicon.ts - separate file for the asset
-export const FAVICON_BASE64 = "iVBORw0KGgo..."; // base64-encoded PNG
-```
-
-```typescript
-// src/worker/index.ts - import and use the asset
-import { FAVICON_BASE64 } from "./assets/favicon";
-
-app.get("/favicon.ico", (c) => {
-  const buffer = Uint8Array.from(atob(FAVICON_BASE64), c => c.charCodeAt(0));
-  return new Response(buffer, {
-    headers: { "Content-Type": "image/x-icon" }
-  });
-});
-```
-
-This approach:
-- Keeps the main code readable (no long base64 strings inline)
-- Makes assets easy to find and update
-- Base64 keeps assets bundled with the code (required for Workers)
-
-**For large assets:** Serve them from the frontend (`public/` folder) instead.
-
-**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.
-See `.claude/skills/discord/` for Discord chatops integration (slash commands, messages, interactions).
+Read the `fling` skill in detail!

package/templates/default/skills/fling/.hash

@@ -1 +1 @@
-effee60df04f3781c257b08a6cf0c6bb
+221778dddff2fffb4811276555d0f095

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

@@ -333,6 +333,36 @@ Secret names must be uppercase with underscores:
 - `apiKey` ✗
 - `github-token` ✗
 
+## Cron Jobs
+
+Schedule tasks to run automatically on a schedule using standard cron syntax:
+
+```typescript
+cron("daily-cleanup", "0 3 * * *", async () => {
+  // Runs at 3 AM daily
+  await db.prepare("DELETE FROM old_logs WHERE created_at < ?")
+    .bind(Date.now() - 86400000).run();
+});
+
+cron("hourly-report", "0 * * * *", async () => {
+  // Runs every hour - can return a result that's stored in history
+  const count = await processRecords();
+  return { processed: count };
+});
+```
+
+Cron expressions: `minute hour day-of-month month day-of-week`
+- `"0 9 * * *"` - 9 AM daily
+- `"*/15 * * * *"` - Every 15 minutes
+- `"0 0 * * 1"` - Midnight on Mondays
+
+Manage cron jobs with CLI:
+```bash
+npm exec fling cron list           # List all cron jobs
+npm exec fling cron history <name> # View invocation history
+npm exec fling cron trigger <name> # Manually trigger a job
+```
+
 ## Storage (R2)
 
 Object storage for files and binary data. Uses local filesystem in development, Cloudflare R2 in production.
@@ -618,4 +648,3 @@ app.get("/api/compute", async (c) => {
 - **Cloudflare blocks dynamic WASM compilation** - You cannot use `WebAssembly.instantiate(bytes)` with raw bytes fetched at runtime. WASM must be imported statically so Cloudflare can pre-compile it at deploy time.
 - **Initialize once** - WASM initialization is expensive. Cache the instance and reuse it across requests.
 - **Bundle size** - WASM modules count toward the 10MB bundle limit. Large WASM files may require optimization.
-

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

@@ -7,6 +7,25 @@ description: Building and deploying this app easily to the internet
 
 You are working on 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
+
+## When to Send Feedback
+
+Fling can send feedback to its authors.  Read FEEDBACK.md for details.
+
+Proactively offer to send feedback in these situations:
+
+1. **User frustration** - When the user expresses frustration with Fling
+2. **Product limitations** - When Fling can't do something the user needs
+3. **After difficulties** - When you've helped resolve a confusing issue
+4. **Feature requests** - When the user wishes Fling could do something differently
+
 ## Core Concepts
 
 Fling provides seven primitives that work identically in local development and production:
@@ -181,11 +200,33 @@ Run `npm start` (or `fling dev`) to start development:
 - **API**: http://localhost:3210 (Hono backend)
 - Vite proxies `/api/*` requests to the API server
 
+### Hot Module Replacement (HMR)
+
+The dev server provides hot reloading for both frontend AND backend - no restart needed:
+- **Frontend (React)**: Changes to `src/react-app/` are instantly reflected via Vite HMR
+- **Backend (Worker)**: Changes to `src/worker/` are automatically reloaded via tsx watch
+
+Just edit and save - changes appear immediately.
+
 ## Deployment
 
-When the user's request is complete and working locally, deploy it:
+When the user's request is complete and working locally, offer to deploy it.  But if their app has a backend and no secure authorization method, you must make it clear to them that the deployed app will be visible on the internet, and that they should not expose anything that should not be publicly visible!
+
+To deploy:
 **Run `npm exec fling push` directly** - you have bash access, don't ask the user to run 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
+
 ### What `fling push` does:
 
 1. **Builds frontend** - Runs `vite build`, outputs to `dist/client/`
@@ -193,6 +234,8 @@ When the user's request is complete and working locally, deploy it:
 3. **Bundles backend** - Compiles `src/worker/index.ts` with esbuild
 4. **Deploys to Cloudflare** - Both frontend and backend go live
 
+**Secrets:** Always stored locally in `.fling/secrets`. Use `fling push` to deploy secrets to production along with your code.
+
 ### Static Asset Limits
 
 - **25MB** per file maximum
@@ -245,4 +288,52 @@ This gives collaborators:
 
 **If the user's request might hit platform limitations, warn them early and suggest alternatives.**
 
+## Migrations
+
+**IMPORTANT: Migrations MUST be idempotent** (safe to run multiple times).
+
+Use the `migrate` helper for schema changes:
+
+```typescript
+import { migrate, db } from "flingit";
+
+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();
+});
+```
+
+## Backend Assets (Images, Fonts, etc.)
+
+If the backend needs to return or process an asset (image, icon, font), keep it small and store the base64 data in a separate file to keep your main code clean:
+
+```typescript
+// src/worker/assets/favicon.ts - separate file for the asset
+export const FAVICON_BASE64 = "iVBORw0KGgo..."; // base64-encoded PNG
+```
+
+```typescript
+// src/worker/index.ts - import and use the asset
+import { FAVICON_BASE64 } from "./assets/favicon";
+
+app.get("/favicon.ico", (c) => {
+  const buffer = Uint8Array.from(atob(FAVICON_BASE64), c => c.charCodeAt(0));
+  return new Response(buffer, {
+    headers: { "Content-Type": "image/x-icon" }
+  });
+});
+```
+
+This approach:
+- Keeps the main code readable (no long base64 strings inline)
+- Makes assets easy to find and update
+- Base64 keeps assets bundled with the code (required for Workers)
+
+**For large assets:** Serve them from the frontend (`public/` folder) instead.
+
 See API.md for detailed API reference, EXAMPLES.md for common patterns, and FEEDBACK.md for collecting user feedback.