Hatchable

Deploy the project. Runs migrations/*.sql (tracked so each runs once), runs seed.sql on first deploy, copies public/ files to the CDN, and registers api/ files as live endpoints. Increments the project version. Always populate `intent` and `summary` so the user sees a readable changelog in the console: - `intent` is what the USER asked for, in their own words. Quote or lightly paraphrase their last instruction. e.g. "Add a split-the-bill section", "Make the buttons rounder". - `summary` is what YOU did, in plain language they can read. 1–3 sentences. e.g. "Added a SplitBill component with a member counter and per-person breakdown. Updated the main page nav to switch between solo and split modes." These become the commit message AND the History row title in the console. A user will likely scroll their History a week from now to remember what they built — write the summary so a future-you-with-no-context understands what shipped. If there is no clear user prompt (autonomous maintenance), leave `intent` blank but still pass a `summary` describing what changed and why. Call this after writing all your files. To verify your functions work after deploying, use `run_function` — it calls the function directly through your authenticated session and works for all project visibilities. The `url` field is the public URL for end users — personal projects require visitors to sign up before they can view the site.

deploy

Create a new Hatchable project. This generates a URL slug, creates a dedicated PostgreSQL database, and returns the project ID and URLs. Call this FIRST, then keep going — creating a project does NOT make anything live. The returned URL is an empty shell that returns 404 until you (1) write your files with `write_files` and (2) call `deploy`. Do not stop, report success, or hand the user the URL until you have deployed. ## Project structure ``` public/ static files, served at their file path api/ backend functions — each file is one endpoint hello.js → /api/hello users/list.js → /api/users/list users/[id].js → /api/users/:id (req.params.id — one segment) docs/[...path].js → /api/docs/*path (req.params.path — string[], catches multi-segment) pages/ server-rendered HTML at clean URLs — each file renders one page index.js → / about.js → /about blog/[id].js → /blog/:id (req.params.id; res.send(html), SSR'd in the isolate) lib/ shared code pool, not routed — import from any file as `lib/<name>.js` migrations/*.sql SQL files, run in filename order on every deploy seed.sql optional — runs on first deploy / fork, once per project hatchable.toml optional overrides (cron, auth, project name) package.json dependencies (no build scripts yet — build locally, commit public/) ``` ### Routing precedence Most-specific wins. For a request to `/api/users/42`: 1. `api/users/42.js` (static) — beats 2. `api/users/[id].js` (single-param, `params.id = "42"`) — beats 3. `api/users/[...rest].js` (catch-all, `params.rest = ["42"]`) Catch-all params arrive as `string[]`, never slash-joined. Use `req.params.path` as an array: `const [first, ...rest] = req.params.path;` ### Page & static resolution (the clean-URL order) A request to a non-`/api/` URL like `/about` resolves in this order: 1. **Exact static file** — `public/about`, `public/about.html`, `public/about/index.html` 2. **`pages/` handler** — `pages/about.js` (server-rendered in the isolate; see skill `pages/server-render-a-page`) 3. **Ancestor `index.html` fallback** — walks up: `public/foo/index.html` → `public/index.html` (the SPA shell) A committed static file always wins over a page handler at the same URL, and a page handler always wins over the SPA shell — so pick `public/` *or* `pages/` for a given route, not both. Step 3 means each folder with an `index.html` acts as its own mini-site: ship an `/admin/*` SPA beside a static marketing `/` and unmatched paths under `/admin/` fall back to `public/admin/index.html`. Use `pages/` when the HTML must be filled in server-side (share/OG/SEO pages, signed-in first paint); use `public/` + Alpine for everything else. ## Handler contract Every file under api/ exports a default async function: ```js // api/notes/list.js import { db } from "hatchable"; export const access = "member"; // require a signed-in collaborator (edge-gated) export default async function (req, res) { // The edge already gated the route; req.member is the signed-in caller. const member = req.member; // { id, handle, ... } const { rows } = await db.query( "SELECT id, title FROM notes WHERE author_id = $1", [member.id] ); res.json(rows); } // Optional: restrict methods export const methods = ["GET"]; // Optional: register this endpoint as a recurring scheduled task. // Minimum interval is hourly. See also: scheduler.at() in the SDK // for imperative / one-shot / per-firing-payload scheduling. // export const schedule = "0 */6 * * *"; ``` ### req (Express-shaped) - method, url, path, headers, cookies, params, query - body — parsed by Content-Type: JSON → object, urlencoded → object, multipart/form-data → object of non-file fields - files — present for multipart uploads: [{ field, filename, contentType, buffer }] ### res (Express-shaped) - res.json(data), res.status(code) (chainable), res.send(text|buffer) - res.redirect(url), res.cookie(name, value, opts), res.setHeader(name, value) ## SDK — import from "hatchable" Everything you need lives under one import. Do not reach for npm packages that duplicate these — the deploy linter rejects `puppeteer-core`, `@anthropic-ai/sdk`, `pg`, `nodemailer`, `bullmq`, `ioredis`, `@aws-sdk/client-s3`, `child_process`, etc. and points you here. ``` // project storage / SQL db.query(sql, params) → { rows, rowCount } db.transaction([{sql, params}, ...]) → { results: [...] } storage.put(key, buffer, contentType) → url storage.get(key) → { buffer, contentType } storage.del(key) // identity + comms // req.member — signed-in caller, set by the edge; null on anonymous public routes // → { id, handle, email?, display_name?, avatar_url?, role? } | null email.send({ to, subject, html }) // scheduling + background work scheduler.at(when, route, opts?) → declared/armed cron scheduler.cancel(taskId) // browser, AI, knowledge — managed services, no npm install browser.html(url) / browser.pdf(url) / browser.screenshot(url) browser.session(async page => { ... }) → puppeteer-shaped ai.generateText({ model: 'sonnet', prompt | messages, system?, tools?, maxSteps?, purpose? }) ai.streamText(opts) → AsyncIterator ai.embed(input) → { embedding } | { embeddings } knowledge.base(name, { dimensions }).add/search/searchByVector/remove/table ``` External HTTP via global `fetch` (routed through Hatchable's egress proxy automatically). Project secrets are declared in `hatchable.toml` under `[[secret]]`; humans paste values via the platform-rendered setup gate. `ai.generateText` reads keys server-side via the gateway — never via raw `process.env`. ### What you cannot do - Spawn binaries (no `child_process`, no shell). - Persist to local filesystem between requests (use `storage` instead). - Open a long-lived TCP/WebSocket server. - Install npm packages with native bindings — Hatchable does not run `npm install` at deploy. The SDK above replaces every common reason to reach for one. ## Deploy-blocking rules (the four that most often fail a deploy — get them right up front) 1. **Every file under `api/`, `pages/`, and `mcp/` MUST `export const access`** — one of `"public"` | `"member"` | `"admin"` | `"scheduler"`. Omitting it HARD-FAILS the deploy. (`public` = anyone; `member` = signed-in end user via the `[auth]` block; `admin` = project owner; `scheduler` = cron-only.) 2. **No npm packages — including for auth.** The isolate has no `npm install`. For end-user accounts use the **passwordless `[auth]` block** (email-code login; see skill `auth/gate-an-endpoint`) — do NOT hand-roll login with `bcrypt`, `argon2`, `bcryptjs`, or `jsonwebtoken` (all rejected at deploy, and you can't vendor native modules). If you genuinely must hash, use **WebCrypto PBKDF2** (`crypto.subtle`), never bcrypt. Never store or compare plaintext passwords. 3. **SQL runs through a guarded gateway** (`seed.sql`, `migrations/*.sql`, `execute_sql`) — these rules avoid "This SQL operation is not allowed": - One statement per call — no `;`-separated multi-statements. - No `$<digit>` inside string literals (`$29` parses as a bind param) — write `29 USD`. - No standalone `GRANT`/`REVOKE` tokens, even inside string data. - Avoid large multi-row `VALUES` — use one `INSERT ... SELECT ... WHERE NOT EXISTS` per row. - Use `gen_random_uuid()` for UUID defaults. 4. **`/api/auth/*` is reserved** by the platform's auth system — don't define routes there or you'll get a route collision at deploy. ### Scheduling Two ways to schedule a function — pick based on whether the "when" is known at deploy time or at runtime. **Declared** (static, lives in source, reconciled on deploy): ```js // api/nightly-report.js export const schedule = "0 9 * * *"; // 5-field cron, minimum hourly export default async function (req, res) { /* ... */ } ``` **Armed** (dynamic, from user code, preserved across deploys): ```js import { scheduler } from "hatchable"; // recurring — first arg is a 5-field cron string await scheduler.at("0 * * * *", "/api/ping"); // one-shot at a specific moment, with per-firing payload await scheduler.at("2026-05-01T07:00:00Z", "/api/book", { payload: { missionId: 42 } }); // idempotent named arm — repeated calls update the same task await scheduler.at("0 9 * * *", "/api/digest", { name: "daily-digest" }); // cancel by id await scheduler.cancel(taskId); ``` Each firing invokes `route` with `req.headers['x-hatchable-trigger'] === 'cron'` and `req.body === payload`. Use one-shot + payload instead of writing your own "pending jobs" table with a polling cron — that's the pattern the primitive replaces. ## Database Postgres. Write schema in migrations/*.sql. Files run in filename order, tracked in __hatchable_migrations so each runs once. Always use RETURNING to get inserted ids in the same round trip: ```sql INSERT INTO users (email) VALUES ($1) RETURNING id ``` Never call lastval() or LAST_INSERT_ID() — each db.query is a fresh connection, so session-local state doesn't carry across calls. ## Available APIs Functions run in V8 isolates. You get: - The full Hatchable SDK (see above). - Plain JS / TypeScript (no transpile step needed for modern syntax). - `fetch` for external HTTP (routed through Hatchable's egress proxy for quota + accounting; pass through transparently to the URL). - Web Crypto and standard ECMAScript builtins. - Pure-JS npm packages — anything that doesn't need native bindings, filesystem persistence, child processes, or raw sockets. Common ones used regularly: csv-parse, xlsx, bcrypt, jsonwebtoken, uuid, date-fns, lodash, marked, sanitize-html, cheerio, xml2js, qrcode, stripe. - Declared secrets via `process.env.KEY` (only for `[[secret]]` entries in hatchable.toml that have `expose = true`; the project owner pastes the value through the setup gate). Most secrets are SDK-mediated and never reach process.env — see the secrets docs. What's NOT available — and the SDK alternative: | You wanted | Use this | |---|---| | `puppeteer-core` / chromium | `import { browser } from "hatchable"` | | `pg` / `mysql2` / SQL drivers | `import { db } from "hatchable"` | | `@anthropic-ai/sdk` / `openai` | `import { ai } from "hatchable"` (BYOK — set ANTHROPIC_API_KEY in project env) | | `nodemailer` / `@sendgrid/mail` | `import { email } from "hatchable"` | | `@aws-sdk/client-s3` | `import { storage } from "hatchable"` | | `ioredis` / `@upstash/redis` | `db` — use a Postgres table for KV-shaped state (Redis clients aren't available) | | `bullmq` / `bull` | `import { tasks } from "hatchable"` | | `sharp` / `jimp` | URL-based storage transforms (planned); `browser.screenshot` for HTML→image | | `fs.writeFileSync('/tmp/...')` | `storage.put(key, bytes)` | | `child_process.spawn` | not available — use `browser` for chromium, file an issue otherwise | The deploy linter rejects deploys that import the deny-listed packages and points you at the right SDK module by name. You'll see the redirect message before the deploy lands. ## Calling the API from public/ At deploy time, Hatchable injects a tiny bootstrap into every HTML file: ```js window.__HATCHABLE__ = { slug: "my-app", api: "/api" }; ``` Use it as the base URL: ```js const API = window.__HATCHABLE__.api; fetch(API + "/users/list").then(r => r.json()).then(render); ``` ## Identity You never build a login form, session, or users table — the platform owns identity. Every route declares `export const access` (`public` | `member` | `admin` | `scheduler`); the edge authenticates the caller and gates the route BEFORE your handler runs. - To require a signed-in person, declare `access: 'member'`. The edge bounces anonymous visitors to login; inside the handler `req.member` is guaranteed present. - Read who's calling from `req.member` → `{ id, handle, email?, display_name?, avatar_url?, role? }` (null on anonymous `'public'` routes; `email` present for any authenticated caller). Use it to scope rows / stamp `created_by`; you don't check it for authorization, the edge already did. - Gate the owner/operator surface with `access: 'admin'` (or the `admin.*` SDK for in-handler profile/redirect). ```js // api/notes/list.js — only signed-in collaborators reach this import { db } from "hatchable"; export const access = "member"; export default async function (req, res) { const member = req.member; const { rows } = await db.query( "SELECT * FROM notes WHERE author_id = $1", [member.id] ); res.json(rows); } ``` See skills `api/access`, `auth/gate-an-endpoint`, `auth/handle-the-anonymous-case`, and `admin/recognize-the-project-admin`. ## Deploy After writing files, call the `deploy` tool. It runs migrations, seeds (first deploy only), copies public/ to the CDN, and registers api/ routes.

Delete a project file. Takes effect after the next deploy. Optional `reason`: surfaces in the History view so the user understands why the file was removed.

Run every deploy-time validator against the project's current files without actually deploying. Returns `errors` (hard gates) and `warnings` (soft lints), plus a `would_deploy` summary of what would ship. Errors catch: package.json build scripts, reserved table names in migrations, auth route collisions, usage cap breaches. Warnings catch known runtime footguns that type-check but silently misbehave — most notably `db.query()` / `ai.generateText()` / `config.get()` calls without `await` (returning a Promise is truthy, so `if (!result)` guards pass and downstream property reads are undefined). Safer than calling deploy blindly and finding out mid-flight.

Run SQL against the project's dedicated PostgreSQL database. Supports: CREATE TABLE, ALTER TABLE, DROP TABLE, INSERT, SELECT, UPDATE, DELETE. Use parameterized queries for safety: pass values in the `params` array with $1, $2, etc. placeholders. Guarded gateway — these avoid "This SQL operation is not allowed": - One statement per call — no `;`-separated multi-statements. - No `$<digit>` inside string literals ($29 parses as a bind param) — write "29 USD", or pass it via `params`. - No standalone GRANT/REVOKE tokens, even inside string data. - Avoid large multi-row VALUES — use one `INSERT ... SELECT ... WHERE NOT EXISTS` per row. - Use `gen_random_uuid()` for UUID defaults. Return format: - SELECT: { rows: [...], count: N } — DECIMAL columns return as strings (e.g. "45.00") - INSERT/UPDATE/DELETE: { changes: N } - DDL: { changes: 0 }

Fork a public project into your account. Copies all code and database schema (no data). The fork starts as a personal project you can modify freely. This is the recommended way to start from an existing app: fork it, then modify the code.

Detail view of one deployment by version number — returns the full file manifest (paths, hashes, sizes) and function list captured when that version shipped. Use it with list_deployments to audit or compare what changed between versions.

Get project details including slug, status, deployed functions, and the database schema (tables, columns, types).

Return the database schema for the project's PostgreSQL database: tables, columns (with types), and indexes.

Regex content search across a project's files. Postgres-backed, scoped to one project, with glob filtering. Three output modes: - files_with_matches (default) — list paths containing a match - content — matching lines with optional context and line numbers - count — per-file match counts + total Default head_limit is 250 to prevent context blowups on broad patterns. Use glob to narrow by path (e.g. 'api/**/*.js', 'public/**/*.html'). Regex uses Postgres syntax (~ / ~*). Invalid or catastrophic patterns error out via a 2s statement timeout — simplify the pattern if that happens.