flingit 0.0.1

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

@@ -0,0 +1,204 @@
+# Fling Examples
+
+Common patterns for building personal tools with Fling.
+
+## Simple API with Authentication
+
+Protected endpoints with API key auth.
+
+```typescript
+import { app, db, secrets } from "fling";
+
+const API_KEY = secrets.get("API_KEY");
+
+// Auth middleware
+function requireAuth(c: any, next: () => Promise<void>) {
+  const auth = c.req.header("Authorization");
+  if (auth !== `Bearer ${API_KEY}`) {
+    return c.json({ error: "Unauthorized" }, 401);
+  }
+  return next();
+}
+
+// Public endpoint
+app.get("/health", (c) => c.json({ status: "ok" }));
+
+// Protected endpoints
+app.post("/api/items", requireAuth, async (c) => {
+  const { name, value } = await c.req.json();
+
+  const result = await db.prepare(
+    "INSERT INTO items (name, value) VALUES (?, ?)"
+  ).bind(name, value).run();
+
+  console.log("Created item", name, result.meta.last_row_id);
+
+  return c.json({
+    id: result.meta.last_row_id,
+    name,
+    value
+  }, 201);
+});
+
+app.get("/api/items", requireAuth, async (c) => {
+  const { results } = await db.prepare("SELECT * FROM items").all();
+  return c.json(results);
+});
+
+app.get("/api/items/:id", requireAuth, async (c) => {
+  const id = c.req.param("id");
+  const item = await db.prepare(
+    "SELECT * FROM items WHERE id = ?"
+  ).bind(id).first();
+
+  if (!item) {
+    return c.json({ error: "Not found" }, 404);
+  }
+
+  return c.json(item);
+});
+```
+
+## Webhook Receiver
+
+Process incoming webhooks and store data.
+
+```typescript
+import { app, db, secrets } from "fling";
+
+async function initDb() {
+  await db.prepare(`
+    CREATE TABLE IF NOT EXISTS events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      source TEXT NOT NULL,
+      type TEXT,
+      payload TEXT NOT NULL,
+      received_at TEXT DEFAULT (datetime('now'))
+    )
+  `).run();
+}
+
+// Verify GitHub webhook signature using Web Crypto API
+async function verifyGitHubSignature(body: string, signature: string, secret: string): Promise<boolean> {
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, encoder.encode(body));
+  const expected = "sha256=" + Array.from(new Uint8Array(sig))
+    .map(b => b.toString(16).padStart(2, "0")).join("");
+  return signature === expected;
+}
+
+// GitHub webhook
+app.post("/webhooks/github", async (c) => {
+  const signature = c.req.header("X-Hub-Signature-256");
+  const event = c.req.header("X-GitHub-Event");
+  const body = await c.req.text();
+
+  // Optional: Verify signature (uncomment to enable)
+  // const secret = secrets.get("GITHUB_WEBHOOK_SECRET");
+  // if (signature && !await verifyGitHubSignature(body, signature, secret)) {
+  //   return c.text("Invalid signature", 401);
+  // }
+
+  await db.prepare(
+    "INSERT INTO events (source, type, payload) VALUES (?, ?, ?)"
+  ).bind("github", event, body).run();
+
+  console.log("GitHub webhook received", event);
+
+  return c.json({ ok: true });
+});
+
+// Generic webhook
+app.post("/webhooks/:source", async (c) => {
+  const source = c.req.param("source");
+  const body = await c.req.text();
+
+  await db.prepare(
+    "INSERT INTO events (source, payload) VALUES (?, ?)"
+  ).bind(source, body).run();
+
+  console.log("Webhook received", source);
+
+  return c.json({ ok: true });
+});
+
+// View recent events
+app.get("/events", async (c) => {
+  const { results } = await db.prepare(
+    "SELECT * FROM events ORDER BY received_at DESC LIMIT 100"
+  ).all();
+  return c.json(results);
+});
+```
+
+## Data Sync API
+
+Pull data from an external API and store it.
+
+```typescript
+import { app, db, secrets, migrate } from "fling";
+
+const API_TOKEN = secrets.get("DATA_API_TOKEN");
+
+migrate("001_create_sync_data", async () => {
+  await db.prepare(`
+    CREATE TABLE IF NOT EXISTS sync_data (
+      id TEXT PRIMARY KEY,
+      data TEXT NOT NULL,
+      synced_at TEXT DEFAULT (datetime('now'))
+    )
+  `).run();
+});
+
+// Sync data from external API
+async function syncData() {
+  console.log("Starting data sync");
+
+  const response = await fetch("https://api.example.com/data", {
+    headers: { "Authorization": `Bearer ${API_TOKEN}` }
+  });
+
+  if (!response.ok) {
+    throw new Error(`Sync failed: ${response.status}`);
+  }
+
+  const items = await response.json();
+  let synced = 0;
+
+  for (const item of items) {
+    await db.prepare(
+      "INSERT OR REPLACE INTO sync_data (id, data, synced_at) VALUES (?, ?, datetime('now'))"
+    ).bind(item.id, JSON.stringify(item)).run();
+    synced++;
+  }
+
+  console.log("Sync completed", synced);
+  return synced;
+}
+
+// View synced data
+app.get("/api/data", async (c) => {
+  const { results } = await db.prepare(
+    "SELECT * FROM sync_data ORDER BY synced_at DESC"
+  ).all();
+
+  return c.json(results.map((r: any) => ({
+    id: r.id,
+    data: JSON.parse(r.data),
+    synced_at: r.synced_at
+  })));
+});
+
+// Trigger sync via API
+app.post("/api/sync", async (c) => {
+  const count = await syncData();
+  return c.json({ message: "Sync completed", count });
+});
+```

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

@@ -0,0 +1,73 @@
+# Feedback Skill
+
+This skill helps you collect and submit user feedback about Fling to the team.
+
+## When to Offer Feedback
+
+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
+
+## Critical Rule: Always Ask First
+
+**NEVER send feedback without explicit user approval.** Always:
+
+1. Ask if they'd like to send feedback
+2. Show them exactly what will be sent
+3. Wait for their confirmation before running the command
+
+Example flow:
+```
+User: "This is so frustrating, the logs command never shows what I need!"
+
+You: "I understand that's frustrating. Would you like me to send this feedback
+to the Fling team? Here's what I'd send:
+
+  'The logs command output doesn't include enough context. When debugging
+  deployment issues, users need to see request IDs and timestamps together.'
+
+Should I submit this?"
+```
+
+## Command Usage
+
+```bash
+# Simple feedback (single line)
+npm exec fling feedback "Your feedback message here"
+
+# Interactive mode (for longer, multi-line feedback)
+npm exec fling feedback -i
+```
+
+The user must be logged in (`npm exec fling login`) for feedback to work.
+
+## Writing Good Feedback
+
+Help users write **actionable** feedback:
+
+**Good feedback includes:**
+- What they were trying to do
+- What happened vs. what they expected
+- Specific details (commands, error messages)
+
+**Less useful feedback:**
+- Vague complaints ("this is broken")
+- No context about the situation
+- Just emotional venting without specifics
+
+## Example Good Feedback
+
+```
+"When running 'fling push' after adding a new secret, the deployment succeeds
+but the secret isn't available until a second deploy. Expected the secret to
+be available immediately. Workaround: run 'fling push' twice."
+```
+
+## Feedback Requirements
+
+- Minimum 10 characters (to encourage meaningful feedback)
+- Maximum 5000 characters
+- User must be logged in to the platform

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

@@ -0,0 +1,159 @@
+# Fling Skill
+
+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.
+
+## Core Concepts
+
+Fling provides four primitives that work identically in local development and production:
+
+1. **HTTP** - Expose endpoints via Hono
+2. **Database** - SQLite locally, D1 in production
+3. **Secrets** - Secure credential management
+4. **Migrations** - Version your database schema
+
+## Project Structure
+
+```
+src/
+  worker/
+    index.ts         # Backend API entry point
+  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)
+  data/
+    local.db         # SQLite database (gitignored)
+```
+
+## Quick Reference
+
+```typescript
+// Backend (src/worker/index.ts)
+import { app, db, secrets } from "fling";
+
+// HTTP routes - use /api prefix for Vite proxy
+app.get("/api/hello", (c) => c.json({ message: "Hello!" }));
+app.post("/api/webhook", async (c) => {
+  const body = await c.req.json();
+  return c.json({ ok: true });
+});
+
+// Database (D1-compatible API)
+const row = await db.prepare("SELECT * FROM items WHERE id = ?").bind(id).first();
+const all = await db.prepare("SELECT * FROM items").all();
+await db.prepare("INSERT INTO items (name) VALUES (?)").bind(name).run();
+await db.prepare("CREATE TABLE IF NOT EXISTS items (id INTEGER PRIMARY KEY, name TEXT)").run();
+
+// Secrets (throws if not set)
+const token = secrets.get("API_TOKEN");
+```
+
+```typescript
+// Frontend (src/react-app/App.tsx)
+import { useState, useEffect } from "react";
+
+function App() {
+  const [data, setData] = useState(null);
+
+  useEffect(() => {
+    fetch("/api/hello")
+      .then(res => res.json())
+      .then(setData);
+  }, []);
+
+  return <div>{data?.message}</div>;
+}
+```
+
+## CLI Commands
+
+Always use `npm exec` to run the project's installed Fling (not global):
+
+```bash
+npm exec fling dev              # Start local 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 1"  # Query local SQLite
+npm exec fling secret set KEY=value
+npm exec fling secret list
+npm exec fling secret remove KEY
+npm exec fling logs             # View local logs
+npm exec fling push             # Build and deploy to Cloudflare Workers
+npm exec fling project slug     # Show current project slug and URL
+npm exec fling project slug:set <new-slug>  # Change project slug (affects URL)
+```
+
+### Local vs Production (`--prod`)
+
+Commands default to local environment. Use `--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
+
+# Production (requires login)
+npm exec fling -- --prod secret list       # Deployed secrets
+npm exec fling -- --prod logs              # Deployed logs
+npm exec fling -- --prod db sql "SELECT 1" # Deployed D1
+```
+
+## 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
+
+## Deployment
+
+When the user's request is complete and working locally, deploy it:
+**Run `npm exec fling push` directly** - you have bash access, don't ask the user to run commands.
+
+### What `fling push` does:
+
+1. **Builds frontend** - Runs `vite build`, outputs to `dist/client/`
+2. **Uploads static assets** - HTML, JS, CSS, images from `dist/client/`
+3. **Bundles backend** - Compiles `src/worker/index.ts` with esbuild
+4. **Deploys to Cloudflare** - Both frontend and backend go live
+
+### Static Asset Limits
+
+- **25MB** per file maximum
+- **100MB** total assets maximum
+- Supported: HTML, CSS, JS, images, fonts, video, audio, WebAssembly
+- MIME types are detected automatically from file extensions
+
+### Routing
+
+- `/api/*` routes are handled by your backend code
+- All other paths serve static assets from `dist/client/`
+- If no asset matches, `index.html` is served (SPA fallback)
+
+## Important Constraints
+
+1. **Backend code runs in Cloudflare Workers** - This is NOT a Node.js environment. You cannot use Node.js-specific APIs (`fs`, `path`, `child_process`, etc.) or npm packages that depend on them. Only use packages that explicitly support Cloudflare Workers or are pure JavaScript/TypeScript with no Node.js dependencies.
+
+2. **Memory limit (~128MB)** - Workers have limited memory. Cannot process large datasets in memory. Use streaming, pagination, or chunked processing for large data.
+
+3. **Feature scope** - Fling supports frontend, backend, and database. Not yet supported: cron jobs, file/blob storage, websockets. If users need these, encourage feedback via `npm exec fling feedback`.
+
+4. **Database operations cannot be at module top-level** - They must be inside route handlers or functions called by them.
+
+5. **Secrets throw on missing** - No default values. Use `fling secret set` to configure.
+
+6. **Use /api prefix for backend routes** - Required for Vite proxy during development.
+
+7. **Run commands yourself** - You have bash access. Don't ask the user to run `fling push`, `fling dev`, `npm start`, etc. Execute them directly.
+
+**If the user's request might hit platform limitations, warn them early and suggest alternatives.**
+
+See API.md for detailed API reference and EXAMPLES.md for common patterns.

package/templates/default/src/react-app/App.css

@@ -0,0 +1,34 @@
+.app {
+  max-width: 600px;
+  margin: 0 auto;
+  padding: 2rem;
+  text-align: center;
+}
+
+h1 {
+  font-size: 2.5rem;
+  margin-bottom: 1rem;
+  color: #333;
+}
+
+.api-message {
+  font-size: 1.25rem;
+  color: #0066cc;
+  background: #f0f8ff;
+  padding: 1rem;
+  border-radius: 8px;
+  margin: 1.5rem 0;
+}
+
+.hint {
+  color: #666;
+  font-size: 0.9rem;
+  line-height: 1.6;
+}
+
+.hint code {
+  background: #f4f4f4;
+  padding: 0.2rem 0.4rem;
+  border-radius: 4px;
+  font-family: monospace;
+}

package/templates/default/src/react-app/App.tsx

@@ -0,0 +1,27 @@
+import { useState, useEffect } from "react";
+import "./App.css";
+
+function App() {
+  const [message, setMessage] = useState<string>("Loading...");
+
+  useEffect(() => {
+    fetch("/api/hello")
+      .then((res) => res.json())
+      .then((data: { message: string }) => setMessage(data.message))
+      .catch(() => setMessage("Failed to connect to API"));
+  }, []);
+
+  return (
+    <div className="app">
+      <h1>Fling App</h1>
+      <p className="api-message">{message}</p>
+      <p className="hint">
+        Edit <code>src/react-app/App.tsx</code> for the frontend
+        <br />
+        Edit <code>src/worker/index.ts</code> for the API
+      </p>
+    </div>
+  );
+}
+
+export default App;

package/templates/default/src/react-app/index.css

@@ -0,0 +1,15 @@
+@import "tailwindcss";
+
+:root {
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+    Oxygen, Ubuntu, Cantarell, "Fira Sans", "Droid Sans", "Helvetica Neue",
+    sans-serif;
+  color: #213547;
+}
+
+body {
+  min-height: 100vh;
+  display: flex;
+  place-items: center;
+  justify-content: center;
+}

package/templates/default/src/react-app/main.tsx

@@ -0,0 +1,10 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import "./index.css";
+import App from "./App.tsx";
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+);

package/templates/default/src/react-app/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/default/src/worker/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Fling Backend Worker
+ *
+ * This is your backend API entry point. Define HTTP routes and database
+ * migrations here.
+ */
+
+import { app, migrate, db } from "fling";
+
+// Database migrations - run automatically on startup
+// IMPORTANT: Migrations MUST be idempotent (safe to run multiple times).
+// Due to distributed execution, a migration might run more than once.
+// Use "CREATE TABLE IF NOT EXISTS", "CREATE INDEX IF NOT EXISTS", etc.
+migrate("001_create_example", async () => {
+  await db.prepare(`
+    CREATE TABLE IF NOT EXISTS example (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      name TEXT NOT NULL,
+      created_at TEXT DEFAULT (datetime('now'))
+    )
+  `).run();
+});
+
+// API endpoint - the React frontend calls this
+app.get("/api/hello", (c) => {
+  return c.json({ message: "Hello from Fling API!" });
+});

package/templates/default/tsconfig.app.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["src/react-app"]
+}

package/templates/default/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.worker.json" }
+  ]
+}

package/templates/default/tsconfig.worker.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "target": "ES2024",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/worker"]
+}

package/templates/default/vite.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from "vite";
+import tailwindcss from "@tailwindcss/vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  base: process.env["VITE_BASE"] || "/",
+  plugins: [tailwindcss(), react()],
+  build: {
+    outDir: "dist/client",
+    emptyOutDir: true,
+  },
+  server: {
+    port: 5173,
+    proxy: {
+      "/api": {
+        target: "http://localhost:3210",
+        changeOrigin: true,
+      },
+    },
+  },
+});