flingit 0.0.3 → 0.0.5

package/templates/default/CLAUDE.md

@@ -42,7 +42,7 @@ Run `npm start` (or `fling dev`) to start development:
 All primitives are imported from `"flingit"` in the backend:
 
 ```typescript
-import { app, db, migrate, secrets } from "flingit";
+import { app, db, migrate, secrets, cron } from "flingit";
 ```
 
 ### HTTP Routes (Hono)
@@ -56,6 +56,8 @@ app.post("/api/data", async (c) => {
 });
 ```
 
+**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).
@@ -89,6 +91,36 @@ await db.prepare("INSERT INTO items (name) VALUES (?)").bind(name).run();
 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
+```
+
 ## React Frontend
 
 The frontend is a standard React + Vite setup. Call the backend API:
@@ -133,6 +165,8 @@ npm exec fling -- --prod logs              # Deployed logs
 npm exec fling -- --prod db sql "SELECT 1" # Deployed D1
 ```
 
+**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
@@ -156,8 +190,8 @@ npm exec fling -- --prod db sql "SELECT 1" # Deployed D1
 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
+- **Supported:** Frontend (React), backend (Hono API), database (SQLite/D1), cron jobs
+- **Not yet supported:** File/blob storage, websockets
 - If the user needs unsupported features, encourage them to send feedback via `npm exec fling feedback`
 
 ### Backend Memory (128MB limit)

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

@@ -4,12 +4,13 @@ You are working on a Fling project - a personal software platform for building a
 
 ## Core Concepts
 
-Fling provides four primitives that work identically in local development and production:
+Fling provides five 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
+5. **Cron** - Scheduled tasks that run on a schedule
 
 ## Project Structure
 
@@ -52,6 +53,20 @@ await db.prepare("CREATE TABLE IF NOT EXISTS items (id INTEGER PRIMARY KEY, name
 
 // Secrets (throws if not set)
 const token = secrets.get("API_TOKEN");
+
+// Cron jobs - run on a schedule
+import { cron } from "flingit";
+
+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-stats", "0 * * * *", async () => {
+  // Runs every hour
+  const stats = await generateStats();
+  return { processed: stats.count }; // Optional return value stored in history
+});
 ```
 
 ```typescript
@@ -88,6 +103,9 @@ 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)
+npm exec fling cron list        # List registered cron jobs
+npm exec fling cron history <name>  # View invocation history
+npm exec fling cron trigger <name>  # Manually trigger a cron job
 ```
 
 ### Local vs Production (`--prod`)
@@ -106,6 +124,8 @@ npm exec fling -- --prod logs              # Deployed logs
 npm exec fling -- --prod db sql "SELECT 1" # Deployed D1
 ```
 
+**Note:** Production logs have a delay of ~10 seconds or more before they appear.
+
 ## Development
 
 Run `npm start` (or `fling dev`) to start development:
@@ -144,7 +164,7 @@ When the user's request is complete and working locally, deploy it:
 
 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`.
+3. **Feature scope** - Fling supports frontend, backend, database, and cron jobs. Not yet supported: 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.
 
@@ -154,6 +174,8 @@ When the user's request is complete and working locally, deploy it:
 
 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.
 
+8. **Reserved paths (`/__*`)** - Paths starting with `/__` are reserved for internal platform use (e.g., `/__cron` for cron jobs). Do not create routes with these prefixes.
+
 **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.