Hatchable

Mint a short-lived (30 min) preview URL showing the project exactly as an anonymous visitor would see it. On personal (private) projects it bypasses ONLY the platform sign-in wall — the app's own [auth] login and declared route access still apply, and even a signed-in owner opening it is treated as a stranger. Use it to verify the real deployed URL (browser tools, screenshots, curl-style checks) or to hand the user a quick look on another device. `deploy` already returns one; call this to re-mint after expiry without redeploying. This does NOT make the project public and never will: permanent public visibility is a console Settings action only the user can take. Do not present a preview link as the app's public URL.

create_preview_link

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.

create_project

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.

delete_file

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

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.

dry_run_deploy

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. JSONB writes: use `$N::jsonb` in the SQL and pass either a JSON string or the raw object/array in `params` — structured params are JSON-encoded automatically. 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 }

execute_sql

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.

fork_project

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

get_schema

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_deployment

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

get_project