clawnify 0.20.4 → 0.21.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -109,8 +109,16 @@ clawnify flows edit <name> # Edit the draft in $EDITOR (or --file)
|
|
|
109
109
|
clawnify flows publish <name> # Publish the draft as the next numbered version
|
|
110
110
|
clawnify ai-files install # Install rules + skills + MCP into your agent(s)
|
|
111
111
|
clawnify ai-files uninstall # Remove them
|
|
112
|
+
clawnify workspace # The org's workspace repo, what maps where, how to edit locally
|
|
113
|
+
clawnify workspace clone [dir] # Clone the org's Clawnify git repo (see below)
|
|
112
114
|
```
|
|
113
115
|
|
|
116
|
+
## Workspace repo
|
|
117
|
+
|
|
118
|
+
An org's apps and website live in one git repo: Clawnify git, or GitHub if the org connected it. `clawnify workspace` says which, and what each folder holds.
|
|
119
|
+
|
|
120
|
+
`clawnify workspace clone` clones Clawnify git and sets git, in that clone only, to sign in with your Clawnify login, so `git pull` and `git push` need no token. Any member can clone; owners and admins push, and a push rebuilds only the folders it changed. CI and other tools without a login use an access token (Settings, Access tokens) as the password: `read` to clone, `write` to push.
|
|
121
|
+
|
|
114
122
|
## Websites
|
|
115
123
|
|
|
116
124
|
`clawnify init --type website` scaffolds a minimal Astro project:
|
|
@@ -605,9 +605,19 @@ async function pollUntilReady(resourceId, options = {}) {
|
|
|
605
605
|
let lastMessage = "";
|
|
606
606
|
let statusless = 0;
|
|
607
607
|
const STATUSLESS_LIMIT = 3;
|
|
608
|
+
let lostContact = null;
|
|
608
609
|
while (Date.now() - start < timeout) {
|
|
609
|
-
|
|
610
|
-
|
|
610
|
+
let data;
|
|
611
|
+
try {
|
|
612
|
+
const res = options.anonToken ? await api.request("GET", `${basePath}/${resourceId}`, { token: options.anonToken }) : await api.get(`${basePath}/${resourceId}`, { orgId: options.orgId });
|
|
613
|
+
if (res.status >= 500) throw new Error(`HTTP ${res.status}`);
|
|
614
|
+
data = await res.json();
|
|
615
|
+
lostContact = null;
|
|
616
|
+
} catch (err) {
|
|
617
|
+
lostContact = err?.message ?? String(err);
|
|
618
|
+
await new Promise((r) => setTimeout(r, interval));
|
|
619
|
+
continue;
|
|
620
|
+
}
|
|
611
621
|
if (!data.status) {
|
|
612
622
|
if (++statusless >= STATUSLESS_LIMIT) {
|
|
613
623
|
if (isTTY) process.stdout.write("\r\x1B[K");
|
|
@@ -639,11 +649,16 @@ async function pollUntilReady(resourceId, options = {}) {
|
|
|
639
649
|
await new Promise((r) => setTimeout(r, interval));
|
|
640
650
|
}
|
|
641
651
|
if (isTTY) process.stdout.write("\r\x1B[K");
|
|
652
|
+
if (lostContact) {
|
|
653
|
+
throw new Error(
|
|
654
|
+
`Lost contact with Clawnify while watching the deploy (${lostContact}), so its outcome is unknown. The build keeps running on our side; ` + (kind === "app" && !options.anonToken ? `check it with \`clawnify logs ${resourceId}\`.` : `check it in the dashboard.`)
|
|
655
|
+
);
|
|
656
|
+
}
|
|
642
657
|
throw new Error("Timed out waiting for deployment");
|
|
643
658
|
}
|
|
644
659
|
|
|
645
660
|
// src/version.ts
|
|
646
|
-
var VERSION = "0.
|
|
661
|
+
var VERSION = "0.21.0";
|
|
647
662
|
|
|
648
663
|
export {
|
|
649
664
|
OAUTH_CLIENT_ID,
|
|
@@ -652,6 +667,7 @@ export {
|
|
|
652
667
|
loadAuth,
|
|
653
668
|
saveAuth,
|
|
654
669
|
getValidToken,
|
|
670
|
+
refreshOnUnauthorized,
|
|
655
671
|
getEmailFromToken,
|
|
656
672
|
generatePkce,
|
|
657
673
|
readManifest,
|
|
@@ -17,10 +17,11 @@ import {
|
|
|
17
17
|
readManifest,
|
|
18
18
|
readProject,
|
|
19
19
|
readWorkspaceConfig,
|
|
20
|
+
refreshOnUnauthorized,
|
|
20
21
|
resolveOrgContext,
|
|
21
22
|
saveAuth,
|
|
22
23
|
saveProject
|
|
23
|
-
} from "./chunk-
|
|
24
|
+
} from "./chunk-IHZGT7C6.js";
|
|
24
25
|
|
|
25
26
|
// src/cli.ts
|
|
26
27
|
import { Command, Option } from "commander";
|
|
@@ -680,10 +681,11 @@ async function websiteToReplace(orgId, linkedWebsiteId) {
|
|
|
680
681
|
}
|
|
681
682
|
const { website } = await res.json();
|
|
682
683
|
if (!website || website.id === linkedWebsiteId) return null;
|
|
683
|
-
const
|
|
684
|
-
if (
|
|
685
|
-
const data = await
|
|
686
|
-
|
|
684
|
+
const ws = await api.get("/v1/workspace", opts);
|
|
685
|
+
if (ws.ok) {
|
|
686
|
+
const data = await ws.json();
|
|
687
|
+
const synced = [...data.git?.folders ?? [], ...data.github?.links ?? []];
|
|
688
|
+
if (synced.some((l) => l.target.type === "website" && l.target.slug === website.slug)) return null;
|
|
687
689
|
}
|
|
688
690
|
return { slug: website.slug };
|
|
689
691
|
}
|
|
@@ -696,8 +698,8 @@ async function refuseWebsiteReplace(orgId, linkedWebsiteId, options) {
|
|
|
696
698
|
Deploying replaces that site's pages, theme and code with this folder. The live site
|
|
697
699
|
stays up until someone publishes.
|
|
698
700
|
|
|
699
|
-
To edit the existing site: use the website editor in the dashboard, or
|
|
700
|
-
|
|
701
|
+
To edit the existing site: use the website editor in the dashboard, or work in a
|
|
702
|
+
clone of the org's workspace repo (\`clawnify workspace\` shows it).
|
|
701
703
|
To replace it on purpose: run this again with --replace.
|
|
702
704
|
`
|
|
703
705
|
);
|
|
@@ -1791,12 +1793,12 @@ function agentByName(name) {
|
|
|
1791
1793
|
var ALL_AGENTS = DETECTORS.map((d) => d.agent);
|
|
1792
1794
|
|
|
1793
1795
|
// src/lib/skills/content.gen.ts
|
|
1794
|
-
var CLI_VERSION = "0.
|
|
1796
|
+
var CLI_VERSION = "0.21.0";
|
|
1795
1797
|
var BUNDLED_SKILLS = [
|
|
1796
1798
|
{
|
|
1797
1799
|
name: "build-a-clawnify-app",
|
|
1798
1800
|
description: "Author a Clawnify app end-to-end \u2014 the canonical Hono + React + Vite + @hono/zod-openapi + @clawnify/db (Drizzle) stack, schema.ts as the single schema source of truth (DDL generated via pnpm db:generate), OpenAPIHono routes (createRoute) that auto-generate an OpenAPI spec, and platform-injected identity via user()/orgId()/caller(). Use when building or modifying an app that deploys to the Clawnify platform.",
|
|
1799
|
-
content: '# Build a Clawnify app\n\nCanonical skill: how to author a Clawnify app end-to-end. Same content\nfor humans reading the docs and for AI coding agents injecting this as\ninstructions during an app build.\n\nIf you\'re an agent: this document is enough context to produce a\nworking app from scratch. Follow it literally. The patterns here\nare exactly what `clawnify init` scaffolds and what the platform\nexpects.\n\n## TL;DR\n\n- **One stack.** Hono + React + Vite + `@hono/zod-openapi` +\n `@clawnify/db` (Drizzle) + `@clawnify/app` (entry, routing,\n identity) + Tailwind v4. Nothing else.\n- **Schema lives in `schema.ts` alone** \u2014 the Drizzle DSL your queries\n compile against. The DDL is generated from it (`pnpm db:generate` \u2192\n `.clawnify/drizzle/*.sql`); never hand-write a `schema.sql` in a\n scaffolded app.\n- **Queries through `getDB`** \u2014 `import { getDB, eq } from\n "@clawnify/db"`. JSON columns auto-serialize.\n- **API routes are `OpenAPIHono` + `createRoute`** \u2014 Zod-validated\n request/response.\n- **`createApp()`** (from `@clawnify/app`) builds the entry \u2014 it returns an\n `OpenAPIHono` with API discovery already mounted (`/api/openapi.json` +\n `/llms.txt`, generated from your live routes). That descriptor *is* the\n tool surface agents discover. Never hand-write those routes.\n- **One import.** `@clawnify/app` re-exports `createRoute`, `z` and\n `OpenAPIHono`, and adds `user` / `orgId` / `caller`. Import from it, not\n from `@clawnify/routes` directly.\n- **`clawnify.json`** declares framework, env, and public routes.\n There is no `api.tools[]` \u2014 the agent discovers and calls your\n endpoints via `/llms.txt` (and the OpenAPI spec).\n- **Identity is injected by the platform** \u2014 read it with `user(c)` /\n `orgId(c)` / `caller(c)` from `@clawnify/app`. Your app never\n authenticates anyone.\n\n## Stack rationale\n\nOne template, one set of decisions. Don\'t deviate unless the user has\nexplicitly asked. `clawnify init` (type `app`) scaffolds either a\n`blank` template (one GET route + a page) or a `crud` template (a\ntable with list/create/update/delete + a form). Both share the exact\nsame stack below.\n\n## File layout\n\n```\nmy-app/\n clawnify.json \u2190 Manifest (validated against /schema/v1/clawnify.json)\n package.json\n tsconfig.json\n vite.config.ts \u2190 @vitejs/plugin-react + @tailwindcss/vite; proxies /api \u2192 :8787\n index.html\n .gitignore\n .clawnify/ \u2190 Managed by the CLI (gitignored) \u2014 never edit\n wrangler.toml \u2190 Generated wrangler config\n drizzle.config.ts \u2190 Generated drizzle config (from clawnify.json + schema.ts)\n drizzle/ \u2190 Generated migration SQL (applied by dev + deploy)\n applied-migrations.json \u2190 Local-apply tracker\n src/\n server/\n index.ts \u2190 OpenAPIHono entry \u2014 mounts routes, serves /api/openapi.json\n routes.ts \u2190 OpenAPIHono + createRoute definitions \u2014 the API surface\n schema.ts \u2190 Drizzle table definitions \u2014 the single source of truth\n worker-env.d.ts \u2190 Cloudflare Workers types reference\n uploads.ts \u2190 R2 helpers (only when storage is enabled)\n client/\n main.tsx \u2190 React mount point\n app.tsx \u2190 Root component (plain fetch against /api/*)\n index.css \u2190 @import "tailwindcss"\n```\n\n## Schema \u2014 `schema.ts` is the single source of truth\n\n`schema.ts` (Drizzle DSL) defines the tables. Do **not** hand-write a\n`schema.sql` in a scaffolded app, and there is no toolchain config to\nmaintain: the drizzle config is a managed artifact the CLI materializes\ninto `.clawnify/` (from `clawnify.json` + the schema path), and the DDL\nis generated from `schema.ts` into `.clawnify/drizzle/*.sql` \u2014 which is\nwhat `clawnify dev` applies locally and the deploy applies to your D1.\n\nThe scaffold\'s starter table (blank template):\n\n```ts\n// src/server/schema.ts\nimport { sqliteTable, text, integer } from "@clawnify/db";\n\nexport const items = sqliteTable("items", {\n id: integer("id").primaryKey({ autoIncrement: true }),\n name: text("name").notNull(),\n createdAt: text("created_at").notNull().$default(() => new Date().toISOString()),\n});\n```\n\nReal apps are multi-tenant. Every user-facing table carries an\n`org_id`, every query filters by it. JSON columns and indexes use the\nDrizzle DSL re-exported from `@clawnify/db`:\n\n```ts\nimport { sqliteTable, text, integer, index } from "@clawnify/db";\n\nexport const notes = sqliteTable(\n "notes",\n {\n id: integer("id").primaryKey({ autoIncrement: true }),\n orgId: text("org_id").notNull(), // ALWAYS filter by this in queries\n title: text("title").notNull(),\n body: text("body").notNull().default(""),\n tags: text("tags", { mode: "json" }).$type<string[]>().notNull().default([]),\n createdAt: text("created_at").notNull().$default(() => new Date().toISOString()),\n },\n (t) => ({\n byOrg: index("notes_by_org").on(t.orgId, t.createdAt),\n }),\n);\n```\n\nRules:\n- JSON columns: `text(col, { mode: "json" }).$type<T>()` \u2014 Drizzle\n serializes on write and parses on read.\n- Multi-tenancy: every user-facing table has `org_id`. Every query\n filters by it. No exceptions.\n- Identifiers: snake_case in SQL, camelCase in TS (Drizzle bridges).\n\n## Generating the DDL \u2014 automatic, or `clawnify db generate`\n\n`clawnify dev` and `clawnify deploy` (local-directory deploys) generate\nthe migration SQL themselves \u2014 editing `schema.ts` and running dev or\ndeploy is the whole workflow. To refresh the SQL explicitly without\neither, run `npx clawnify@latest db generate` (the scaffold\'s\n`pnpm db:generate` is an alias for it). Always invoke the CLI as\n`npx clawnify@latest` \u2014 never a global or pinned install. Deploy refuses a database-enabled app with no DDL,\nso a broken generate fails loudly, not silently.\n\nOne artifact to leave alone: after a successful signed-in deploy the CLI\nsyncs a read-only `schema.sql` snapshot of the DEPLOYED schema into the\napp root. It is generated output for reference/diffing \u2014 never edit it,\nand never treat it as the source of truth (`schema.ts` is).\n\nRules:\n- Deploys are **additive**: new tables and columns are added\n automatically. Destructive changes (dropping or retyping a column) are\n not applied automatically \u2014 do those deliberately, and never drop a\n table with user data unless explicitly asked.\n- Never edit the generated `.clawnify/drizzle/*.sql` by hand \u2014 change\n `schema.ts` and regenerate.\n- A hand-written `schema.sql` at the app root is accepted **only** for\n apps that don\'t use Drizzle at all (e.g. some template repos). A\n scaffolded app never needs one.\n\n## `src/server/index.ts` \u2014 the entry\n\n```ts\nimport { createApp } from "@clawnify/app";\nimport api from "./routes";\n\n// db:false \u2014 this app reads the database per request via getDB(c.env),\n// which needs no init middleware.\nconst app = createApp({ title: "My app", version: "1.0.0", db: false });\n\napp.route("/", api);\n\nexport default app;\n```\n\nThe entry is thin: `createApp()` then mount your routes. `createApp`\nreturns an `OpenAPIHono` with **API discovery already mounted** \u2014 it\nserves both `/api/openapi.json` (generated from your `createRoute`\ndefinitions, with schemas) **and** `/llms.txt` (the same, agent-readable).\nAny `/api/*` route written as a plain `app.get` with no `createRoute` is\nstill listed from the live route table, so the endpoint inventory is\nalways complete. **Never hand-write a `/openapi.json` or `/llms.txt`\nhandler** \u2014 and don\'t call `mountDiscovery` yourself; `createApp` did it.\n\nWhen storage (file uploads) is enabled, the entry also wires the R2\nbucket in a middleware before mounting routes:\n\n```ts\nimport { createApp, type AppEnv } from "@clawnify/app";\nimport { initUploads } from "./uploads";\nimport api from "./routes";\n\ntype Env = AppEnv & { Bindings: { UPLOADS: R2Bucket } };\n\nconst app = createApp<Env>({ title: "My app", version: "1.0.0", db: false });\n\napp.use("*", async (c, next) => {\n initUploads(c.env.UPLOADS);\n await next();\n});\n\napp.route("/", api);\n\nexport default app;\n```\n\n## `src/server/routes.ts` \u2014 routes with `createRoute`\n\nEach endpoint is a `createRoute({ method, path, summary, request, responses })`\ndefinition paired with a handler via `api.openapi(route, handler)`.\nRequest bodies and params are Zod-validated (`c.req.valid("json")`,\n`c.req.valid("param")`); response shapes are declared with\n`.openapi("Name")` Zod schemas so they land in the generated spec.\n\nBlank template \u2014 one read route:\n\n```ts\nimport { OpenAPIHono, createRoute, z, PageQuery, pageParams, pagedResponse, type AppEnv } from "@clawnify/app";\nimport { getDB, desc, like } from "@clawnify/db";\nimport * as schema from "./schema";\n\nconst api = new OpenAPIHono<AppEnv>();\n\nconst ItemSchema = z.object({\n id: z.number(),\n name: z.string(),\n createdAt: z.string(),\n}).openapi("Item");\n\napi.openapi(\n createRoute({\n method: "get",\n path: "/api/items",\n summary: "List items",\n // Every list endpoint pages: an agent reads this API through one tool,\n // and an unbounded list would land in its context whole.\n request: { query: PageQuery },\n responses: { 200: pagedResponse("items", ItemSchema) },\n }),\n async (c) => {\n const { page, limit, offset, search } = pageParams(c.req.valid("query"));\n const db = getDB(c.env, { schema });\n const where = search ? like(schema.items.name, "%" + search + "%") : undefined;\n const total = await db.$count(schema.items, where);\n const items = await db\n .select()\n .from(schema.items)\n .where(where)\n .orderBy(desc(schema.items.createdAt))\n .limit(limit)\n .offset(offset);\n return c.json({ items, total, page, limit }, 200);\n },\n);\n\nexport default api;\n```\n\nCRUD template \u2014 the full list/create/update/delete surface:\n\n```ts\nimport { OpenAPIHono, createRoute, z, PageQuery, pageParams, pagedResponse, type AppEnv } from "@clawnify/app";\nimport { getDB, eq, desc, like } from "@clawnify/db";\nimport * as schema from "./schema";\n\nconst api = new OpenAPIHono<AppEnv>();\n\nconst ItemSchema = z.object({\n id: z.number(),\n title: z.string(),\n status: z.string(),\n createdAt: z.string(),\n}).openapi("Item");\n\nconst CreateItemSchema = z.object({ title: z.string().min(1) }).openapi("CreateItem");\nconst UpdateItemSchema = z.object({\n title: z.string().min(1).optional(),\n status: z.string().optional(),\n}).openapi("UpdateItem");\nconst IdParamSchema = z.object({ id: z.string() });\nconst OkSchema = z.object({ ok: z.boolean() }).openapi("Ok");\n\napi.openapi(\n createRoute({\n method: "get",\n path: "/api/items",\n summary: "List items",\n // Every list endpoint pages: an agent reads this API through one tool,\n // and an unbounded list would land in its context whole.\n request: { query: PageQuery },\n responses: { 200: pagedResponse("items", ItemSchema) },\n }),\n async (c) => {\n const { page, limit, offset, search } = pageParams(c.req.valid("query"));\n const db = getDB(c.env, { schema });\n const where = search ? like(schema.items.title, "%" + search + "%") : undefined;\n const total = await db.$count(schema.items, where);\n const items = await db\n .select()\n .from(schema.items)\n .where(where)\n .orderBy(desc(schema.items.createdAt))\n .limit(limit)\n .offset(offset);\n return c.json({ items, total, page, limit }, 200);\n },\n);\n\napi.openapi(\n createRoute({\n method: "post",\n path: "/api/items",\n summary: "Create item",\n request: { body: { content: { "application/json": { schema: CreateItemSchema } } } },\n responses: {\n 201: {\n description: "Created item",\n content: { "application/json": { schema: ItemSchema } },\n },\n },\n }),\n async (c) => {\n const { title } = c.req.valid("json");\n const db = getDB(c.env, { schema });\n const [row] = await db\n .insert(schema.items)\n .values({ title: title.trim() })\n .returning();\n return c.json(row, 201);\n },\n);\n\napi.openapi(\n createRoute({\n method: "patch",\n path: "/api/items/:id",\n summary: "Update item",\n request: {\n params: IdParamSchema,\n body: { content: { "application/json": { schema: UpdateItemSchema } } },\n },\n responses: {\n 200: { description: "Updated", content: { "application/json": { schema: OkSchema } } },\n 400: { description: "Nothing to update", content: { "application/json": { schema: OkSchema } } },\n },\n }),\n async (c) => {\n const { id } = c.req.valid("param");\n const body = c.req.valid("json");\n const patch: Partial<typeof schema.items.$inferInsert> = {};\n if (body.title !== undefined) patch.title = body.title;\n if (body.status !== undefined) patch.status = body.status;\n if (Object.keys(patch).length === 0) return c.json({ ok: false }, 400);\n const db = getDB(c.env, { schema });\n await db.update(schema.items).set(patch).where(eq(schema.items.id, Number(id)));\n return c.json({ ok: true });\n },\n);\n\napi.openapi(\n createRoute({\n method: "delete",\n path: "/api/items/:id",\n summary: "Delete item",\n request: { params: IdParamSchema },\n responses: {\n 200: { description: "Deleted", content: { "application/json": { schema: OkSchema } } },\n },\n }),\n async (c) => {\n const { id } = c.req.valid("param");\n const db = getDB(c.env, { schema });\n await db.delete(schema.items).where(eq(schema.items.id, Number(id)));\n return c.json({ ok: true });\n },\n);\n\nexport default api;\n```\n\nPatterns to follow:\n- **Give every route a clear `summary`/`description`.** The generated\n OpenAPI spec is what the agent reads to decide which endpoint to\n call \u2014 a vague summary makes your endpoint invisible in practice.\n- **Validate input with Zod** via `request.body` / `request.params`\n and read it with `c.req.valid("json")` / `c.req.valid("param")`.\n Never parse `c.req.raw` by hand.\n- **Declare response shapes** with `.openapi("Name")` schemas \u2014 they\n become the documented return type in the spec.\n- **Filter by the org** on every user-facing query (see "who is\n calling" below). No exceptions.\n\n## `src/server` \u2014 who is calling\n\nThe platform authenticates every caller at its perimeter and injects a\nverified identity onto the request (it strips any client-supplied\nversion first, so it can\'t be spoofed). Your app never authenticates\nanyone: no `Authorization`, no cookies, no JWT, no login screen.\n\nRead it with the helpers from `@clawnify/app` \u2014 don\'t parse headers\nyourself:\n\n```ts\nimport { user, orgId, caller } from "@clawnify/app";\n\napp.get("/api/notes", async (c) => {\n const org = orgId(c);\n if (!org) return c.json({ error: "unauthorized" }, 401);\n\n const db = getDB(c.env, { schema });\n return c.json(\n await db.select().from(schema.notes).where(eq(schema.notes.orgId, org)),\n );\n});\n```\n\n| Helper | Returns |\n|--------|---------|\n| `orgId(c)` | Organization UUID \u2014 the tenant key. Filter every user-facing query by it. |\n| `user(c)` | `{ id, email, name, avatarUrl, firstName, lastName }` \u2014 or **`null`** when the caller isn\'t a person. |\n| `caller(c)` | `user`, `api`, `agent`, `agent-browser`, `public`, `bypass`, `system`, or `app`. |\n\nTwo rules that catch people out:\n\n- **`user(c)` is null for five of the eight caller kinds**\n (`agent-browser`, `public`, `bypass`, `system`, `app`). Always handle\n the null case \u2014 don\'t assume a person is present just because a\n request arrived. For per-user rows, store `user(c).id` in a `user_id`\n column and filter on it, exactly as you filter on `org_id`.\n- **`firstName` / `lastName` are a heuristic** split of a single stored\n full name (first word / the rest). Fine for a greeting; never persist\n them or treat them as someone\'s legal name \u2014 store `name`.\n\nDon\'t build app-level users, roles, or permissions. Authorization\nalready happened at the perimeter.\n\n## `src/client` \u2014 React + plain fetch\n\nThe client mounts React and talks to the API with plain `fetch`\nagainst the `/api/*` routes. No data-layer library is scaffolded.\n\n```tsx\n// src/client/main.tsx\nimport { StrictMode } from "react";\nimport { createRoot } from "react-dom/client";\nimport { App } from "./app";\nimport "./index.css";\n\ncreateRoot(document.getElementById("app")!).render(\n <StrictMode>\n <App />\n </StrictMode>\n);\n```\n\n```tsx\n// src/client/app.tsx (CRUD template shape)\nimport { useState, useEffect } from "react";\n\ninterface Item {\n id: number;\n title: string;\n status: string;\n createdAt: string;\n}\n\nexport function App() {\n const [items, setItems] = useState<Item[]>([]);\n const [title, setTitle] = useState("");\n\n async function load() {\n const res = await fetch("/api/items");\n setItems(((await res.json()) as { items: Item[] }).items);\n }\n\n useEffect(() => { load(); }, []);\n\n async function addItem(e: React.FormEvent) {\n e.preventDefault();\n if (!title.trim()) return;\n await fetch("/api/items", {\n method: "POST",\n headers: { "Content-Type": "application/json" },\n body: JSON.stringify({ title }),\n });\n setTitle("");\n load();\n }\n\n // ...toggleStatus / deleteItem call PATCH/DELETE the same way.\n\n return (\n <div className="max-w-xl mx-auto mt-10 px-4">\n {/* form + list */}\n </div>\n );\n}\n```\n\nIn local dev, Vite proxies `/api` to the Worker on `:8787` (see\n`vite.config.ts`), so the same relative fetch paths work in dev and\nin production. The API is the one contract: the UI calls it over\n`fetch`, and the agent calls it over the OpenAPI spec.\n\n## Design\n\nIf the project contains a `DESIGN.md`, it is the single source of\ntruth for visuals \u2014 follow its tokens, don\'t restyle around it. The\nscaffold ships Tailwind v4 (via `@tailwindcss/vite`, imported with\n`@import "tailwindcss";` in `index.css`) and nothing else \u2014 no\ncomponent library. The rules every Clawnify app follows:\n\n- **Neutral chrome.** White canvas and surfaces, one text ramp\n (foreground \u2192 muted \u2192 faint), hairline borders. Color is for\n meaning, not decoration.\n- **One primary CTA per screen.** Blue is reserved for links and\n focus rings; never a second accent.\n- **Status colors are muted pairs** \u2014 never pure-saturated fills.\n- **Style with Tailwind utilities.** Don\'t install another component\n library or write a bespoke CSS system unless the user asks.\n- **Sizes in rem**, so browser zoom and font settings are respected.\n\n## `clawnify.json` \u2014 the manifest\n\n```json\n{\n "$schema": "https://app.clawnify.com/schema/v1/clawnify.json",\n "version": 1,\n "name": "Notes",\n "description": "Take and organize notes. Searchable by tag.",\n "app": {\n "framework": "react+hono",\n "database": true,\n "storage": false\n },\n "env": {\n "optional": ["OPENROUTER_API_KEY"]\n },\n "api": {\n "public_routes": [\n { "path": "/api/feed", "methods": ["GET"] }\n ]\n }\n}\n```\n\n`clawnify init` writes the minimal form:\n`{ app: { framework: "react+hono", database: true, storage } }`. Add\nthe rest as needed.\n\nIf the app talks to third-party services the user has connected\n(ads platforms, CRMs, messaging), declare them:\n\n```json\n{ "app": { "credentials": ["metaads", "googleads"] } }\n```\n\nGet the ids and names from `clawnify connections list` \u2014 see the\nnaming rule below.\n\n`env` supports `required` (deploy warns if missing), `optional`\n(injected when available), and `oneOf` (at least one per group).\n\nRules:\n- **There is no `api.tools[]`.** The manifest\'s `api` object only\n accepts `public_routes` and `automation_bypass`. Your API surface\n is discovered from the generated OpenAPI spec, not a hand-authored\n tools list (see the next section).\n- **Public routes are the exception**, not the default. Every route\n is behind the Clawnify perimeter (auth-required) unless you\n explicitly add a matching path to `api.public_routes`. Use only for\n webhooks, RSS, embedded feeds.\n- **`framework: "react+hono"`** for new apps. Never `preact+hono` or\n `vite-preact` \u2014 those are legacy.\n- **`database: true`** if the app uses a DB. `schema.ts` defines the\n tables; run `pnpm db:generate` after changing it.\n\n## How the agent reaches your API (no `api.tools[]`)\n\nThe old tRPC stack emitted an `api.tools[]` array from procedure meta.\nThat mechanism is gone. Today the flow is:\n\n1. Your `createRoute` definitions auto-generate a live OpenAPI 3.0 spec\n plus a lean `/llms.txt` index, both served for you \u2014 never hand-write\n or route them yourself. **These are the agent\'s discovery channel:**\n it reads `GET /llms.txt` (index of every endpoint) or\n `GET /api/openapi.json` (full request/response schemas) on the live\n app. Because both are generated from the live route table, they\n cannot drift from the code.\n2. The agent then drives your endpoints on the live app. A Clawnify\n agent uses `clawnify_call_app_api`; Claude, ChatGPT and other MCP\n clients use `clawnify_app_api_read` (GET), `clawnify_app_api_write`\n (POST, PUT, PATCH) and `clawnify_app_api_delete`. No per-app MCP\n registration and no manifest tools array. Use source reading to\n *modify* code, not to discover endpoints.\n\nSo you make an endpoint "agent-callable" by defining it with\n`createRoute()` + `app.openapi()` and giving it a clear\n`summary`/`description` with Zod-typed request/response. The clearer\nthose are, the more reliably the agent uses it.\n\n### `agent.md` \u2014 lead with the procedure, not the endpoint list\n\n`agent.md` is extracted into `agent_instructions` on every build. Since\ndiscovery is already covered by the generated surfaces above, **`agent.md`\nis not an API reference** \u2014 re-listing every payload there just creates a\nsecond source of truth that goes stale the first time a route changes.\nIt is the one place for what generation can\'t produce: **judgment**.\n\nWrite it in this order:\n\n1. **Division of labour, first and short.** What the agent should do\n itself vs. what it must delegate to the app \u2014 and say the wrong move\n out loud (*"never look up contact details yourself; post the records\n and let the app resolve them"*). This one block prevents more misuse\n than the rest of the file combined.\n2. **The procedure** \u2014 numbered steps for the app\'s main job, written so\n the agent can follow them on a request it has never seen.\n3. **Pages**, flagging the screenshot-friendly ones.\n4. **API anchors, not API docs** \u2014 method, path, and *when to reach for\n it*, plus the one or two request shapes the agent writes most often.\n For anything else, let it read `/llms.txt`.\n5. **How to read failures**, and any **cost discipline** \u2014 which calls\n spend the user\'s money and which are free.\n\n**Don\'t ship a per-app skill.** A skill\'s frontmatter stays resident in\nagent context, so one skill per app grows the agent\'s context floor as\nthe app count grows; `agent_instructions` and `/llms.txt` are pulled on\ndemand instead. Skills are for **cross-app** procedures \u2014 if one earns\nreuse across more than one app, promote that single procedure\n(parameterized) to the shared skills library rather than copying it into\nevery app.\n\n## Connections & secrets \u2014 `@clawnify/connections`\n\n**The naming rule \u2014 never invent an identifier.** Before declaring\n`credentials` or env names, run `clawnify connections list`: it shows\nthe org\'s canonical integration ids (`googleads`, never `google_ads`),\nthe fixed provider-key names (`OPENROUTER_API_KEY`, never\n`OPENROUTER_KEY`), and custom env vars already defined \u2014 each with\nconnected/set state. Reuse those exact identifiers; a misspelled one\ndoesn\'t fail the build, it silently resolves to nothing at runtime. If\nyou need a custom secret that isn\'t listed, pick a clear name and tell\nthe user to set it in the dashboard.\n\nIf the app needs a third-party service or a provider API key, use\nthe `@clawnify/connections` SDK. Never read credential bindings\ndirectly, never paste API keys, never hardcode a token or endpoint.\n\n```ts\nimport { connect, secret, describe, searchActions } from "@clawnify/connections";\n\n// A connected integration:\nconst meta = connect("metaads", env);\nconst accounts = await meta.adAccounts("name,currency");\n\n// A provider key the user supplied (null if absent):\nconst key = secret("OPENROUTER_API_KEY", env);\n\n// What\'s wired vs missing \u2014 drive your setup/empty state from this:\nconst status = await describe(env, undefined, REQUIRES);\n```\n\nHow to call a connected service \u2014 the mistake that silently breaks\nintegration apps, so get it right:\n\n- **Prefer the typed client\'s semantic methods** where they exist\n (`meta.adAccounts(...)`, `googleads.query(gaql)`).\n- **For anything else, discover and run an action:**\n ```ts\n const [best] = await searchActions("list google ads campaigns", env);\n const data = await connect(best.service, env).run(best.slug, body);\n ```\n- Some integrations also expose a raw REST client\n (`connect("bird", env).get("/path")`) \u2014 but if `.get()`/`.post()`\n throws for a service, that service only supports semantic methods\n and `run()`. When unsure, use `run()`.\n- **Need exact paths/arguments for a raw-REST provider?** Some carry\n a `spec_url` (the provider\'s published OpenAPI spec) \u2014\n `clawnify connections list --json` shows it. Download and query it \u2014\n `curl -s <spec_url> -o spec.json && jq \'.paths | keys\' spec.json` \u2014\n never read a whole spec into context (they run to 10+ MB).\n- **Never fall back to raw `fetch`** against a provider API, and\n never invent endpoints or guess tokens.\n\n**The one exception \u2014 a service we don\'t support at all.** If a\nprovider isn\'t in the connections registry (nothing to `connect()`\nto, and `clawnify connections list` doesn\'t show it), the sanctioned\npath *is* a raw call with a user-supplied key: declare the key(s) it\nneeds in `clawnify.json` `env` (`required`/`optional`/`oneOf`), tell\nthe user to set them in the dashboard, read them with\n`secret("THAT_KEY", env)`, and `fetch` the provider\'s documented\nendpoints directly. This is the escape hatch for the long tail of\nintegrations we don\'t model yet \u2014 it does **not** apply to a service\nwe *do* support (use `connect()` / `run()` for those, always). Keep\nthe endpoint and token server-side, never in the client bundle.\n\nBuild a `describe()`-driven setup state instead of assuming\nconnections exist \u2014 show the user what\'s missing and where to\nconnect it.\n\n## Scheduling & deferred work \u2014 the managed queue\n\nA deployed app **cannot bind Cloudflare Queues, Durable Objects, or cron\ntriggers** (the platform builds every app with a fixed binding set: `DB` +\n`ASSETS` + `UPLOADS`). To run work later \u2014 a scheduled publish, a reminder, a\nretry, a "do this in 10 minutes" \u2014 use the **Clawnify managed queue service**\nover HTTP. It owns the clock, retries, and at-least-once delivery, then calls an\nendpoint on *your own app* back at the scheduled time.\n\nUse the published `@clawnify/queue` package \u2014 `enqueueJob`, `cancelJob`,\n`verifyDelivery` \u2014 same shape as `@clawnify/db` / `@clawnify/connections`.\nAuth is the build-injected `env.CLAWNIFY_TOKEN`; with no token (local dev)\nit degrades to a no-op.\n\n**Enqueue** a deferred call to your own endpoint:\n\n```ts\n// POST https://services.clawnify.com/queue/enqueue (Bearer CLAWNIFY_TOKEN)\nconst res = await fetch("https://services.clawnify.com/queue/enqueue", {\n method: "POST",\n headers: { Authorization: `Bearer ${env.CLAWNIFY_TOKEN}`, "Content-Type": "application/json" },\n body: JSON.stringify({\n target_url: `${origin}/api/internal/publish`, // an endpoint on THIS app\n payload: { post_id: id }, // echoed back to you on fire\n run_at: new Date(whenMs).toISOString(),\n idempotency_key: `post:${id}:${whenMs}`, // same key dedupes; new time = new job\n }),\n});\nconst { job_id } = await res.json(); // store it to cancel/reschedule\n```\n\nPersist `job_id` on the row (e.g. `posts.queue_job_id`). **Cancel / reschedule**:\n`DELETE https://services.clawnify.com/queue/jobs/{job_id}` (Bearer token);\nreschedule = cancel + a fresh enqueue.\n\n**The callback endpoint is a public, signature-verified route.** The queue calls\n`target_url` from outside the perimeter, so the endpoint must be declared in\n`clawnify.json` `public_routes` **and** verify the delivery signature itself \u2014\nthe signature *is* its auth (never trust an unsigned call):\n\n```jsonc\n// clawnify.json\n"api": { "public_routes": [ { "path": "/api/internal/publish", "methods": ["POST"] } ] }\n```\n\nDeliveries are signed with the platform\'s **ECDSA P-256 (ES256)** key,\nStripe-style over `${timestamp}.${rawBody}`, verified against\n`https://services.clawnify.com/.well-known/jwks.json` (public key \u2014 nothing\nbreaks on token rotation). Read the raw body, check the signature + a timestamp\ntolerance (~5 min) before doing anything:\n\n```ts\napp.post("/api/internal/publish", async (c) => {\n const raw = await c.req.text();\n const ok = await verifyDelivery(raw, {\n signature: c.req.header("x-clawnify-signature"),\n timestamp: c.req.header("x-clawnify-timestamp"),\n keyId: c.req.header("x-clawnify-key-id"),\n });\n if (!ok) return c.json({ error: "bad signature" }, 401);\n const { post_id } = JSON.parse(raw);\n // \u2026do the deferred work (short: it\'s one normal Worker invocation)\u2026\n return c.json({ ok: true });\n});\n```\n\nEach fire is a normal Worker request \u2014 size the work to one invocation (publish a\npost, send a digest). For long compute *now* (not deferred), hold the request\nopen and return when done; don\'t fire-and-forget past the response.\n\n## Migrations\n\nThe workflow is:\n\n1. Edit `src/server/schema.ts` for the new shape (types + queries).\n2. Run `pnpm db:generate` \u2014 emits the migration SQL under\n `.clawnify/drizzle/`.\n3. Run `npx clawnify@latest dev` locally, then `npx clawnify@latest deploy`.\n\nOn deploy your schema changes are applied to the app\'s database \u2014 new\ntables and columns are added automatically.\n\nDestructive changes (drop column, rename) are not applied automatically;\ndo them deliberately, and only when the user explicitly asks. Renames\nare risky on production data \u2014 prefer "add new column, backfill, switch\nqueries, drop old column" over a single-step rename.\n\n## What the agent must NOT do\n\n- Author a `/openapi.json` or `/llms.txt` handler by hand. `createApp()`\n mounts both, generated from your `createRoute` definitions.\n- Hand-write a `schema.sql`, edit anything under `.clawnify/`, or add a\n root `drizzle.config.ts`. Schema changes happen in `schema.ts`; the\n CLI generates and applies the SQL.\n- Invent an `api.tools[]` array in the manifest. It isn\'t a valid\n field \u2014 the OpenAPI spec is the tool surface.\n- Use `JSON.stringify` on query params. JSON columns auto-serialize\n via Drizzle. The raw SQL API has `json()` as a helper.\n- Skip the `org_id` filter on a user-facing query. Multi-tenant\n leak is the worst-class bug we can ship.\n- Return a whole table from a list endpoint, or a bare array. Every list\n pages: `PageQuery`, `pageParams` and `pagedResponse` from `@clawnify/app`.\n- Read auth from `Authorization` / cookies / `Bearer` tokens, or\n hand-parse `X-Clawnify-*` headers. Use `user(c)` / `orgId(c)` /\n `caller(c)` from `@clawnify/app`.\n- Call third-party APIs with raw `fetch` or hardcoded tokens. Go\n through `@clawnify/connections` (`connect` / `secret` / `run`).\n- Install `drizzle-orm` as a separate top-level dependency.\n `@clawnify/db@^0.4.1` pulls it in transitively; only add it if you\n need to pin a specific version (rare).\n\n## What the agent SHOULD do\n\n- Import everything from `@clawnify/db` where possible\n (`getDB`, `eq`, `and`, `desc`, `sql`, `sqliteTable`, `text`,\n `integer`, `index`, etc. are all re-exported there). Drop to\n `drizzle-orm` directly only for things not re-exported.\n- Give every route a clear `summary`/`description` and Zod-typed\n request/response so the agent can discover and call it via the\n OpenAPI spec.\n- Page every list endpoint with the helpers `@clawnify/app` exports:\n `request: { query: PageQuery.extend({ /* filters */ }) }`,\n `const { page, limit, offset, search } = pageParams(c.req.valid("query"))`\n (25 per page by default, capped at 100, bad input falls back), and\n `responses: { 200: pagedResponse("items", ItemSchema) }` for\n `{ items, total, page, limit }`. Count with `db.$count(table, where)`.\n- Keep a long text field an agent edits again and again (HTML, a\n document body, a template) as one top-level string of the record,\n with GET and a *partial* update (`PATCH`, or a PUT that keeps the\n fields it is not sent) on the same path, returning the updated\n record. Agents then read it in parts and change it with literal\n `old_text` \u2192 `new_text` edits instead of sending all of it back; the\n platform provides that, so don\'t build a find/replace endpoint.\n- Type a helper that takes the database client as `DB<typeof schema>`\n (from `@clawnify/db`), and a separate routes file\'s env as `AppEnv`\n (from `@clawnify/app`). Never name the backend (`D1Database`,\n `DrizzleD1Database`) or cast `getDB`\'s result: the same app code is\n served by more than one database backend.\n- Test locally with `npx clawnify@latest dev` before deploying; deploys go live at\n `https://<slug>.apps.clawnify.com` (the dashboard\'s preview pane shows\n the draft tier).\n- When unsure about a Drizzle pattern, check the `@clawnify/db`\n README for the current API + version notes.\n\n## Schema-as-data exception\n\nApps that let END users define data shapes at runtime (CMS, no-code\ntable editor) can\'t model their schema in `schema.ts` \u2014 the table\ndefinitions live in rows. Those apps fall back to the raw SQL API\nfrom `@clawnify/db` (`query`, `get`, `run`, `json`). Open-cms is\nthe canonical example.\n\nIf you\'re building this kind of app, you still use Drizzle\'s\n`schema.ts` for the **registry** tables (content types, field\ndefinitions). Only the dynamically-spawned per-collection tables\nneed raw SQL. See open-cms\'s `src/server/schema-sync.ts` for the\nruntime DDL pattern.\n\n## When you\'re stuck: compare with a working app\n\nEvery `Open*` repo under [github.com/clawnify](https://github.com/clawnify)\nis a complete, open-source app running on this platform. When your\napp hits an error you can\'t resolve from this document, find one that\ndoes the same thing and compare how it does it.\n\n- **Pick the repo by what it uses.** Each repo\'s `clawnify.json`\n declares it: `app.credentials` lists its integrations (`metaads`,\n `googleads`, ...), `app.database` and `app.storage` say whether it\n uses D1 and R2. The README says what the app does.\n- **Read it without signing in.** List the repos at\n `https://api.github.com/orgs/clawnify/repos?per_page=100`, and fetch\n any file at `https://raw.githubusercontent.com/clawnify/<repo>/HEAD/<path>`\n (`HEAD` resolves the default branch, which is not always `main`).\n- **Copy the solution, not the layout.** This document wins on\n conventions. Many templates predate parts of it: most hand-write\n `src/server/schema.sql` instead of `schema.ts`, some use Preact, and\n older ones don\'t page their lists with the `@clawnify/app` helpers.\n- **If the error comes from a `@clawnify/*` package**, read what you\n installed: `node_modules/@clawnify/<pkg>/README.md` and\n `dist/index.d.ts`, which match your version exactly.\n'
|
|
1801
|
+
content: '# Build a Clawnify app\n\nCanonical skill: how to author a Clawnify app end-to-end. Same content\nfor humans reading the docs and for AI coding agents injecting this as\ninstructions during an app build.\n\nIf you\'re an agent: this document is enough context to produce a\nworking app from scratch. Follow it literally. The patterns here\nare exactly what `clawnify init` scaffolds and what the platform\nexpects.\n\n## TL;DR\n\n- **One stack.** Hono + React + Vite + `@hono/zod-openapi` +\n `@clawnify/db` (Drizzle) + `@clawnify/app` (entry, routing,\n identity) + Tailwind v4. Nothing else.\n- **Schema lives in `schema.ts` alone** \u2014 the Drizzle DSL your queries\n compile against. The DDL is generated from it (`pnpm db:generate` \u2192\n `.clawnify/drizzle/*.sql`); never hand-write a `schema.sql` in a\n scaffolded app.\n- **Queries through `getDB`** \u2014 `import { getDB, eq } from\n "@clawnify/db"`. JSON columns auto-serialize.\n- **API routes are `OpenAPIHono` + `createRoute`** \u2014 Zod-validated\n request/response.\n- **`createApp()`** (from `@clawnify/app`) builds the entry \u2014 it returns an\n `OpenAPIHono` with API discovery already mounted (`/api/openapi.json` +\n `/llms.txt`, generated from your live routes). That descriptor *is* the\n tool surface agents discover. Never hand-write those routes.\n- **One import.** `@clawnify/app` re-exports `createRoute`, `z` and\n `OpenAPIHono`, and adds `user` / `orgId` / `caller`. Import from it, not\n from `@clawnify/routes` directly.\n- **`clawnify.json`** declares framework, env, and public routes.\n There is no `api.tools[]` \u2014 the agent discovers and calls your\n endpoints via `/llms.txt` (and the OpenAPI spec).\n- **Identity is injected by the platform** \u2014 read it with `user(c)` /\n `orgId(c)` / `caller(c)` from `@clawnify/app`. Your app never\n authenticates anyone.\n\n## Stack rationale\n\nOne template, one set of decisions. Don\'t deviate unless the user has\nexplicitly asked. `clawnify init` (type `app`) scaffolds either a\n`blank` template (one GET route + a page) or a `crud` template (a\ntable with list/create/update/delete + a form). Both share the exact\nsame stack below.\n\n## File layout\n\n```\nmy-app/\n clawnify.json \u2190 Manifest (validated against /schema/v1/clawnify.json)\n package.json\n tsconfig.json\n vite.config.ts \u2190 @vitejs/plugin-react + @tailwindcss/vite; proxies /api \u2192 :8787\n index.html\n .gitignore\n .clawnify/ \u2190 Managed by the CLI (gitignored) \u2014 never edit\n wrangler.toml \u2190 Generated wrangler config\n drizzle.config.ts \u2190 Generated drizzle config (from clawnify.json + schema.ts)\n drizzle/ \u2190 Generated migration SQL (applied by dev + deploy)\n applied-migrations.json \u2190 Local-apply tracker\n src/\n server/\n index.ts \u2190 OpenAPIHono entry \u2014 mounts routes, serves /api/openapi.json\n routes.ts \u2190 OpenAPIHono + createRoute definitions \u2014 the API surface\n schema.ts \u2190 Drizzle table definitions \u2014 the single source of truth\n worker-env.d.ts \u2190 Cloudflare Workers types reference\n uploads.ts \u2190 R2 helpers (only when storage is enabled)\n client/\n main.tsx \u2190 React mount point\n app.tsx \u2190 Root component (plain fetch against /api/*)\n index.css \u2190 @import "tailwindcss"\n```\n\n## Schema \u2014 `schema.ts` is the single source of truth\n\n`schema.ts` (Drizzle DSL) defines the tables. Do **not** hand-write a\n`schema.sql` in a scaffolded app, and there is no toolchain config to\nmaintain: the drizzle config is a managed artifact the CLI materializes\ninto `.clawnify/` (from `clawnify.json` + the schema path), and the DDL\nis generated from `schema.ts` into `.clawnify/drizzle/*.sql` \u2014 which is\nwhat `clawnify dev` applies locally and the deploy applies to your D1.\n\nThe scaffold\'s starter table (blank template):\n\n```ts\n// src/server/schema.ts\nimport { sqliteTable, text, integer } from "@clawnify/db";\n\nexport const items = sqliteTable("items", {\n id: integer("id").primaryKey({ autoIncrement: true }),\n name: text("name").notNull(),\n createdAt: text("created_at").notNull().$default(() => new Date().toISOString()),\n});\n```\n\nReal apps are multi-tenant. Every user-facing table carries an\n`org_id`, every query filters by it. JSON columns and indexes use the\nDrizzle DSL re-exported from `@clawnify/db`:\n\n```ts\nimport { sqliteTable, text, integer, index } from "@clawnify/db";\n\nexport const notes = sqliteTable(\n "notes",\n {\n id: integer("id").primaryKey({ autoIncrement: true }),\n orgId: text("org_id").notNull(), // ALWAYS filter by this in queries\n title: text("title").notNull(),\n body: text("body").notNull().default(""),\n tags: text("tags", { mode: "json" }).$type<string[]>().notNull().default([]),\n createdAt: text("created_at").notNull().$default(() => new Date().toISOString()),\n },\n (t) => ({\n byOrg: index("notes_by_org").on(t.orgId, t.createdAt),\n }),\n);\n```\n\nRules:\n- JSON columns: `text(col, { mode: "json" }).$type<T>()` \u2014 Drizzle\n serializes on write and parses on read.\n- Multi-tenancy: every user-facing table has `org_id`. Every query\n filters by it. No exceptions.\n- Identifiers: snake_case in SQL, camelCase in TS (Drizzle bridges).\n\n## Generating the DDL \u2014 automatic, or `clawnify db generate`\n\n`clawnify dev` and `clawnify deploy` (local-directory deploys) generate\nthe migration SQL themselves \u2014 editing `schema.ts` and running dev or\ndeploy is the whole workflow. To refresh the SQL explicitly without\neither, run `npx clawnify@latest db generate` (the scaffold\'s\n`pnpm db:generate` is an alias for it). Always invoke the CLI as\n`npx clawnify@latest` \u2014 never a global or pinned install. Deploy refuses a database-enabled app with no DDL,\nso a broken generate fails loudly, not silently.\n\nOne artifact to leave alone: after a successful signed-in deploy the CLI\nsyncs a read-only `schema.sql` snapshot of the DEPLOYED schema into the\napp root. It is generated output for reference/diffing \u2014 never edit it,\nand never treat it as the source of truth (`schema.ts` is).\n\nRules:\n- Deploys are **additive**: new tables and columns are added\n automatically. Destructive changes (dropping or retyping a column) are\n not applied automatically \u2014 do those deliberately, and never drop a\n table with user data unless explicitly asked.\n- Never edit the generated `.clawnify/drizzle/*.sql` by hand \u2014 change\n `schema.ts` and regenerate.\n- A hand-written `schema.sql` at the app root is accepted **only** for\n apps that don\'t use Drizzle at all (e.g. some template repos). A\n scaffolded app never needs one.\n\n## `src/server/index.ts` \u2014 the entry\n\n```ts\nimport { createApp } from "@clawnify/app";\nimport api from "./routes";\n\n// db:false \u2014 this app reads the database per request via getDB(c.env),\n// which needs no init middleware.\nconst app = createApp({ title: "My app", version: "1.0.0", db: false });\n\napp.route("/", api);\n\nexport default app;\n```\n\nThe entry is thin: `createApp()` then mount your routes. `createApp`\nreturns an `OpenAPIHono` with **API discovery already mounted** \u2014 it\nserves both `/api/openapi.json` (generated from your `createRoute`\ndefinitions, with schemas) **and** `/llms.txt` (the same, agent-readable).\nAny `/api/*` route written as a plain `app.get` with no `createRoute` is\nstill listed from the live route table, so the endpoint inventory is\nalways complete. **Never hand-write a `/openapi.json` or `/llms.txt`\nhandler** \u2014 and don\'t call `mountDiscovery` yourself; `createApp` did it.\n\nWhen storage (file uploads) is enabled, the entry also wires the R2\nbucket in a middleware before mounting routes:\n\n```ts\nimport { createApp, type AppEnv } from "@clawnify/app";\nimport { initUploads } from "./uploads";\nimport api from "./routes";\n\ntype Env = AppEnv & { Bindings: { UPLOADS: R2Bucket } };\n\nconst app = createApp<Env>({ title: "My app", version: "1.0.0", db: false });\n\napp.use("*", async (c, next) => {\n initUploads(c.env.UPLOADS);\n await next();\n});\n\napp.route("/", api);\n\nexport default app;\n```\n\n## `src/server/routes.ts` \u2014 routes with `createRoute`\n\nEach endpoint is a `createRoute({ method, path, summary, request, responses })`\ndefinition paired with a handler via `api.openapi(route, handler)`.\nRequest bodies and params are Zod-validated (`c.req.valid("json")`,\n`c.req.valid("param")`); response shapes are declared with\n`.openapi("Name")` Zod schemas so they land in the generated spec.\n\nBlank template \u2014 one read route:\n\n```ts\nimport { OpenAPIHono, createRoute, z, PageQuery, pageParams, pagedResponse, type AppEnv } from "@clawnify/app";\nimport { getDB, desc, like } from "@clawnify/db";\nimport * as schema from "./schema";\n\nconst api = new OpenAPIHono<AppEnv>();\n\nconst ItemSchema = z.object({\n id: z.number(),\n name: z.string(),\n createdAt: z.string(),\n}).openapi("Item");\n\napi.openapi(\n createRoute({\n method: "get",\n path: "/api/items",\n summary: "List items",\n // Every list endpoint pages: an agent reads this API through one tool,\n // and an unbounded list would land in its context whole.\n request: { query: PageQuery },\n responses: { 200: pagedResponse("items", ItemSchema) },\n }),\n async (c) => {\n const { page, limit, offset, search } = pageParams(c.req.valid("query"));\n const db = getDB(c.env, { schema });\n const where = search ? like(schema.items.name, "%" + search + "%") : undefined;\n const total = await db.$count(schema.items, where);\n const items = await db\n .select()\n .from(schema.items)\n .where(where)\n .orderBy(desc(schema.items.createdAt))\n .limit(limit)\n .offset(offset);\n return c.json({ items, total, page, limit }, 200);\n },\n);\n\nexport default api;\n```\n\nCRUD template \u2014 the full list/create/update/delete surface:\n\n```ts\nimport { OpenAPIHono, createRoute, z, PageQuery, pageParams, pagedResponse, type AppEnv } from "@clawnify/app";\nimport { getDB, eq, desc, like } from "@clawnify/db";\nimport * as schema from "./schema";\n\nconst api = new OpenAPIHono<AppEnv>();\n\nconst ItemSchema = z.object({\n id: z.number(),\n title: z.string(),\n status: z.string(),\n createdAt: z.string(),\n}).openapi("Item");\n\nconst CreateItemSchema = z.object({ title: z.string().min(1) }).openapi("CreateItem");\nconst UpdateItemSchema = z.object({\n title: z.string().min(1).optional(),\n status: z.string().optional(),\n}).openapi("UpdateItem");\nconst IdParamSchema = z.object({ id: z.string() });\nconst OkSchema = z.object({ ok: z.boolean() }).openapi("Ok");\n\napi.openapi(\n createRoute({\n method: "get",\n path: "/api/items",\n summary: "List items",\n // Every list endpoint pages: an agent reads this API through one tool,\n // and an unbounded list would land in its context whole.\n request: { query: PageQuery },\n responses: { 200: pagedResponse("items", ItemSchema) },\n }),\n async (c) => {\n const { page, limit, offset, search } = pageParams(c.req.valid("query"));\n const db = getDB(c.env, { schema });\n const where = search ? like(schema.items.title, "%" + search + "%") : undefined;\n const total = await db.$count(schema.items, where);\n const items = await db\n .select()\n .from(schema.items)\n .where(where)\n .orderBy(desc(schema.items.createdAt))\n .limit(limit)\n .offset(offset);\n return c.json({ items, total, page, limit }, 200);\n },\n);\n\napi.openapi(\n createRoute({\n method: "post",\n path: "/api/items",\n summary: "Create item",\n request: { body: { content: { "application/json": { schema: CreateItemSchema } } } },\n responses: {\n 201: {\n description: "Created item",\n content: { "application/json": { schema: ItemSchema } },\n },\n },\n }),\n async (c) => {\n const { title } = c.req.valid("json");\n const db = getDB(c.env, { schema });\n const [row] = await db\n .insert(schema.items)\n .values({ title: title.trim() })\n .returning();\n return c.json(row, 201);\n },\n);\n\napi.openapi(\n createRoute({\n method: "patch",\n path: "/api/items/:id",\n summary: "Update item",\n request: {\n params: IdParamSchema,\n body: { content: { "application/json": { schema: UpdateItemSchema } } },\n },\n responses: {\n 200: { description: "Updated", content: { "application/json": { schema: OkSchema } } },\n 400: { description: "Nothing to update", content: { "application/json": { schema: OkSchema } } },\n },\n }),\n async (c) => {\n const { id } = c.req.valid("param");\n const body = c.req.valid("json");\n const patch: Partial<typeof schema.items.$inferInsert> = {};\n if (body.title !== undefined) patch.title = body.title;\n if (body.status !== undefined) patch.status = body.status;\n if (Object.keys(patch).length === 0) return c.json({ ok: false }, 400);\n const db = getDB(c.env, { schema });\n await db.update(schema.items).set(patch).where(eq(schema.items.id, Number(id)));\n return c.json({ ok: true });\n },\n);\n\napi.openapi(\n createRoute({\n method: "delete",\n path: "/api/items/:id",\n summary: "Delete item",\n request: { params: IdParamSchema },\n responses: {\n 200: { description: "Deleted", content: { "application/json": { schema: OkSchema } } },\n },\n }),\n async (c) => {\n const { id } = c.req.valid("param");\n const db = getDB(c.env, { schema });\n await db.delete(schema.items).where(eq(schema.items.id, Number(id)));\n return c.json({ ok: true });\n },\n);\n\nexport default api;\n```\n\nPatterns to follow:\n- **Give every route a clear `summary`/`description`.** The generated\n OpenAPI spec is what the agent reads to decide which endpoint to\n call \u2014 a vague summary makes your endpoint invisible in practice.\n- **Validate input with Zod** via `request.body` / `request.params`\n and read it with `c.req.valid("json")` / `c.req.valid("param")`.\n Never parse `c.req.raw` by hand.\n- **Declare response shapes** with `.openapi("Name")` schemas \u2014 they\n become the documented return type in the spec.\n- **Filter by the org** on every user-facing query (see "who is\n calling" below). No exceptions.\n\n## `src/server` \u2014 who is calling\n\nThe platform authenticates every caller at its perimeter and injects a\nverified identity onto the request (it strips any client-supplied\nversion first, so it can\'t be spoofed). Your app never authenticates\nanyone: no `Authorization`, no cookies, no JWT, no login screen.\n\nRead it with the helpers from `@clawnify/app` \u2014 don\'t parse headers\nyourself:\n\n```ts\nimport { user, orgId, caller } from "@clawnify/app";\n\napp.get("/api/notes", async (c) => {\n const org = orgId(c);\n if (!org) return c.json({ error: "unauthorized" }, 401);\n\n const db = getDB(c.env, { schema });\n return c.json(\n await db.select().from(schema.notes).where(eq(schema.notes.orgId, org)),\n );\n});\n```\n\n| Helper | Returns |\n|--------|---------|\n| `orgId(c)` | Organization UUID \u2014 the tenant key. Filter every user-facing query by it. |\n| `user(c)` | `{ id, email, name, avatarUrl, firstName, lastName }` \u2014 or **`null`** when the caller isn\'t a person. |\n| `caller(c)` | `user`, `api`, `agent`, `agent-browser`, `public`, `bypass`, `system`, or `app`. |\n\nTwo rules that catch people out:\n\n- **`user(c)` is null for five of the eight caller kinds**\n (`agent-browser`, `public`, `bypass`, `system`, `app`). Always handle\n the null case \u2014 don\'t assume a person is present just because a\n request arrived. For per-user rows, store `user(c).id` in a `user_id`\n column and filter on it, exactly as you filter on `org_id`.\n- **`firstName` / `lastName` are a heuristic** split of a single stored\n full name (first word / the rest). Fine for a greeting; never persist\n them or treat them as someone\'s legal name \u2014 store `name`.\n\nDon\'t build app-level users, roles, or permissions. Authorization\nalready happened at the perimeter.\n\n## `src/client` \u2014 React + plain fetch\n\nThe client mounts React and talks to the API with plain `fetch`\nagainst the `/api/*` routes. No data-layer library is scaffolded.\n\n```tsx\n// src/client/main.tsx\nimport { StrictMode } from "react";\nimport { createRoot } from "react-dom/client";\nimport { App } from "./app";\nimport "./index.css";\n\ncreateRoot(document.getElementById("app")!).render(\n <StrictMode>\n <App />\n </StrictMode>\n);\n```\n\n```tsx\n// src/client/app.tsx (CRUD template shape)\nimport { useState, useEffect } from "react";\n\ninterface Item {\n id: number;\n title: string;\n status: string;\n createdAt: string;\n}\n\nexport function App() {\n const [items, setItems] = useState<Item[]>([]);\n const [title, setTitle] = useState("");\n\n async function load() {\n const res = await fetch("/api/items");\n setItems(((await res.json()) as { items: Item[] }).items);\n }\n\n useEffect(() => { load(); }, []);\n\n async function addItem(e: React.FormEvent) {\n e.preventDefault();\n if (!title.trim()) return;\n await fetch("/api/items", {\n method: "POST",\n headers: { "Content-Type": "application/json" },\n body: JSON.stringify({ title }),\n });\n setTitle("");\n load();\n }\n\n // ...toggleStatus / deleteItem call PATCH/DELETE the same way.\n\n return (\n <div className="max-w-xl mx-auto mt-10 px-4">\n {/* form + list */}\n </div>\n );\n}\n```\n\nIn local dev, Vite proxies `/api` to the Worker on `:8787` (see\n`vite.config.ts`), so the same relative fetch paths work in dev and\nin production. The API is the one contract: the UI calls it over\n`fetch`, and the agent calls it over the OpenAPI spec.\n\n## Design\n\nIf the project contains a `DESIGN.md`, it is the single source of\ntruth for visuals \u2014 follow its tokens, don\'t restyle around it. The\nscaffold ships Tailwind v4 (via `@tailwindcss/vite`, imported with\n`@import "tailwindcss";` in `index.css`) and nothing else \u2014 no\ncomponent library. The rules every Clawnify app follows:\n\n- **Neutral chrome.** White canvas and surfaces, one text ramp\n (foreground \u2192 muted \u2192 faint), hairline borders. Color is for\n meaning, not decoration.\n- **One primary CTA per screen.** Blue is reserved for links and\n focus rings; never a second accent.\n- **Status colors are muted pairs** \u2014 never pure-saturated fills.\n- **Style with Tailwind utilities.** Don\'t install another component\n library or write a bespoke CSS system unless the user asks.\n- **Sizes in rem**, so browser zoom and font settings are respected.\n\n## `clawnify.json` \u2014 the manifest\n\n```json\n{\n "$schema": "https://app.clawnify.com/schema/v1/clawnify.json",\n "version": 1,\n "name": "Notes",\n "description": "Take and organize notes. Searchable by tag.",\n "app": {\n "framework": "react+hono",\n "database": true,\n "storage": false\n },\n "env": {\n "optional": ["OPENROUTER_API_KEY"]\n },\n "api": {\n "public_routes": [\n { "path": "/api/feed", "methods": ["GET"] }\n ]\n }\n}\n```\n\n`clawnify init` writes the minimal form:\n`{ app: { framework: "react+hono", database: true, storage } }`. Add\nthe rest as needed.\n\nIf the app talks to third-party services the user has connected\n(ads platforms, CRMs, messaging), declare them:\n\n```json\n{ "app": { "credentials": ["metaads", "googleads"] } }\n```\n\nGet the ids and names from `clawnify connections list` \u2014 see the\nnaming rule below.\n\n`env` supports `required` (deploy warns if missing), `optional`\n(injected when available), and `oneOf` (at least one per group).\n\nRules:\n- **There is no `api.tools[]`.** The manifest\'s `api` object only\n accepts `public_routes` and `automation_bypass`. Your API surface\n is discovered from the generated OpenAPI spec, not a hand-authored\n tools list (see the next section).\n- **Public routes are the exception**, not the default. Every route\n is behind the Clawnify perimeter (auth-required) unless you\n explicitly add a matching path to `api.public_routes`. Use only for\n webhooks, RSS, embedded feeds.\n- **`framework: "react+hono"`** for new apps. Never `preact+hono` or\n `vite-preact` \u2014 those are legacy.\n- **`database: true`** if the app uses a DB. `schema.ts` defines the\n tables; run `pnpm db:generate` after changing it.\n\n## How the agent reaches your API (no `api.tools[]`)\n\nThe old tRPC stack emitted an `api.tools[]` array from procedure meta.\nThat mechanism is gone. Today the flow is:\n\n1. Your `createRoute` definitions auto-generate a live OpenAPI 3.0 spec\n plus a lean `/llms.txt` index, both served for you \u2014 never hand-write\n or route them yourself. **These are the agent\'s discovery channel:**\n it reads `GET /llms.txt` (index of every endpoint) or\n `GET /api/openapi.json` (full request/response schemas) on the live\n app. Because both are generated from the live route table, they\n cannot drift from the code.\n2. The agent then drives your endpoints on the live app. A Clawnify\n agent uses `clawnify_call_app_api`; Claude, ChatGPT and other MCP\n clients use `clawnify_app_api_read` (GET), `clawnify_app_api_write`\n (POST, PUT, PATCH) and `clawnify_app_api_delete`. No per-app MCP\n registration and no manifest tools array. Use source reading to\n *modify* code, not to discover endpoints.\n\nSo you make an endpoint "agent-callable" by defining it with\n`createRoute()` + `app.openapi()` and giving it a clear\n`summary`/`description` with Zod-typed request/response. The clearer\nthose are, the more reliably the agent uses it.\n\n### `agent.md` \u2014 lead with the procedure, not the endpoint list\n\n`agent.md` is extracted into `agent_instructions` on every build. Since\ndiscovery is already covered by the generated surfaces above, **`agent.md`\nis not an API reference** \u2014 re-listing every payload there just creates a\nsecond source of truth that goes stale the first time a route changes.\nIt is the one place for what generation can\'t produce: **judgment**.\n\nWrite it in this order:\n\n1. **Division of labour, first and short.** What the agent should do\n itself vs. what it must delegate to the app \u2014 and say the wrong move\n out loud (*"never look up contact details yourself; post the records\n and let the app resolve them"*). This one block prevents more misuse\n than the rest of the file combined.\n2. **The procedure** \u2014 numbered steps for the app\'s main job, written so\n the agent can follow them on a request it has never seen.\n3. **Pages**, flagging the screenshot-friendly ones.\n4. **API anchors, not API docs** \u2014 method, path, and *when to reach for\n it*, plus the one or two request shapes the agent writes most often.\n For anything else, let it read `/llms.txt`.\n5. **How to read failures**, and any **cost discipline** \u2014 which calls\n spend the user\'s money and which are free.\n\n**Don\'t ship a per-app skill.** A skill\'s frontmatter stays resident in\nagent context, so one skill per app grows the agent\'s context floor as\nthe app count grows; `agent_instructions` and `/llms.txt` are pulled on\ndemand instead. Skills are for **cross-app** procedures \u2014 if one earns\nreuse across more than one app, promote that single procedure\n(parameterized) to the shared skills library rather than copying it into\nevery app.\n\n## Connections & secrets \u2014 `@clawnify/connections`\n\n**The naming rule \u2014 never invent an identifier.** Before declaring\n`credentials` or env names, run `clawnify connections list`: it shows\nthe org\'s canonical integration ids (`googleads`, never `google_ads`),\nthe fixed provider-key names (`OPENROUTER_API_KEY`, never\n`OPENROUTER_KEY`), and custom env vars already defined \u2014 each with\nconnected/set state. Reuse those exact identifiers; a misspelled one\ndoesn\'t fail the build, it silently resolves to nothing at runtime. If\nyou need a custom secret that isn\'t listed, pick a clear name and tell\nthe user to set it in the dashboard.\n\nIf the app needs a third-party service or a provider API key, use\nthe `@clawnify/connections` SDK. Never read credential bindings\ndirectly, never paste API keys, never hardcode a token or endpoint.\n\n```ts\nimport { connect, secret, describe, searchActions } from "@clawnify/connections";\n\n// A connected integration:\nconst meta = connect("metaads", env);\nconst accounts = await meta.adAccounts("name,currency");\n\n// A provider key the user supplied (null if absent):\nconst key = secret("OPENROUTER_API_KEY", env);\n\n// What\'s wired vs missing \u2014 drive your setup/empty state from this:\nconst status = await describe(env, undefined, REQUIRES);\n```\n\nHow to call a connected service \u2014 the mistake that silently breaks\nintegration apps, so get it right:\n\n- **Prefer the typed client\'s semantic methods** where they exist\n (`meta.adAccounts(...)`, `googleads.query(gaql)`).\n- **For anything else, discover and run an action:**\n ```ts\n const [best] = await searchActions("list google ads campaigns", env);\n const data = await connect(best.service, env).run(best.slug, body);\n ```\n- Some integrations also expose a raw REST client\n (`connect("bird", env).get("/path")`) \u2014 but if `.get()`/`.post()`\n throws for a service, that service only supports semantic methods\n and `run()`. When unsure, use `run()`.\n- **Need exact paths/arguments for a raw-REST provider?** Some carry\n a `spec_url` (the provider\'s published OpenAPI spec) \u2014\n `clawnify connections list --json` shows it. Download and query it \u2014\n `curl -s <spec_url> -o spec.json && jq \'.paths | keys\' spec.json` \u2014\n never read a whole spec into context (they run to 10+ MB).\n- **Never fall back to raw `fetch`** against a provider API, and\n never invent endpoints or guess tokens.\n\n**The one exception \u2014 a service we don\'t support at all.** If a\nprovider isn\'t in the connections registry (nothing to `connect()`\nto, and `clawnify connections list` doesn\'t show it), the sanctioned\npath *is* a raw call with a user-supplied key: declare the key(s) it\nneeds in `clawnify.json` `env` (`required`/`optional`/`oneOf`), tell\nthe user to set them in the dashboard, read them with\n`secret("THAT_KEY", env)`, and `fetch` the provider\'s documented\nendpoints directly. This is the escape hatch for the long tail of\nintegrations we don\'t model yet \u2014 it does **not** apply to a service\nwe *do* support (use `connect()` / `run()` for those, always). Keep\nthe endpoint and token server-side, never in the client bundle.\n\nBuild a `describe()`-driven setup state instead of assuming\nconnections exist \u2014 show the user what\'s missing and where to\nconnect it.\n\n## Scheduling & deferred work \u2014 the managed queue\n\nA deployed app **cannot bind Cloudflare Queues, Durable Objects, or cron\ntriggers** (the platform builds every app with a fixed binding set: `DB` +\n`ASSETS` + `UPLOADS`). To run work later \u2014 a scheduled publish, a reminder, a\nretry, a "do this in 10 minutes" \u2014 use the **Clawnify managed queue service**\nover HTTP. It owns the clock, retries, and at-least-once delivery, then calls an\nendpoint on *your own app* back at the scheduled time.\n\nUse the published `@clawnify/queue` package \u2014 `enqueueJob`, `cancelJob`,\n`verifyDelivery` \u2014 same shape as `@clawnify/db` / `@clawnify/connections`.\nAuth is the build-injected `env.CLAWNIFY_TOKEN`; with no token (local dev)\nit degrades to a no-op.\n\n**Enqueue** a deferred call to your own endpoint:\n\n```ts\n// POST https://services.clawnify.com/queue/enqueue (Bearer CLAWNIFY_TOKEN)\nconst res = await fetch("https://services.clawnify.com/queue/enqueue", {\n method: "POST",\n headers: { Authorization: `Bearer ${env.CLAWNIFY_TOKEN}`, "Content-Type": "application/json" },\n body: JSON.stringify({\n target_url: `${origin}/api/internal/publish`, // an endpoint on THIS app\n payload: { post_id: id }, // echoed back to you on fire\n run_at: new Date(whenMs).toISOString(),\n idempotency_key: `post:${id}:${whenMs}`, // same key dedupes; new time = new job\n }),\n});\nconst { job_id } = await res.json(); // store it to cancel/reschedule\n```\n\nPersist `job_id` on the row (e.g. `posts.queue_job_id`). **Cancel / reschedule**:\n`DELETE https://services.clawnify.com/queue/jobs/{job_id}` (Bearer token);\nreschedule = cancel + a fresh enqueue.\n\n**The callback endpoint is a public, signature-verified route.** The queue calls\n`target_url` from outside the perimeter, so the endpoint must be declared in\n`clawnify.json` `public_routes` **and** verify the delivery signature itself \u2014\nthe signature *is* its auth (never trust an unsigned call):\n\n```jsonc\n// clawnify.json\n"api": { "public_routes": [ { "path": "/api/internal/publish", "methods": ["POST"] } ] }\n```\n\nDeliveries are signed with the platform\'s **ECDSA P-256 (ES256)** key,\nStripe-style over `${timestamp}.${rawBody}`, verified against\n`https://services.clawnify.com/.well-known/jwks.json` (public key \u2014 nothing\nbreaks on token rotation). Read the raw body, check the signature + a timestamp\ntolerance (~5 min) before doing anything:\n\n```ts\napp.post("/api/internal/publish", async (c) => {\n const raw = await c.req.text();\n const ok = await verifyDelivery(raw, {\n signature: c.req.header("x-queue-signature"),\n timestamp: c.req.header("x-queue-timestamp"),\n keyId: c.req.header("x-queue-key-id"),\n });\n if (!ok) return c.json({ error: "bad signature" }, 401);\n const { post_id } = JSON.parse(raw);\n // \u2026do the deferred work (short: it\'s one normal Worker invocation)\u2026\n return c.json({ ok: true });\n});\n```\n\nEach fire is a normal Worker request \u2014 size the work to one invocation (publish a\npost, send a digest). For long compute *now* (not deferred), hold the request\nopen and return when done; don\'t fire-and-forget past the response.\n\n**When the queue says no.** A refused enqueue answers `{ "error", "detail" }`\n(`enqueueJob` throws `ClawnifyQueueError` with `code`, `status` and `message`).\nPast the plan\'s monthly included jobs each job costs credits, so only an empty\nbalance (`402 insufficient_credits`) or no active plan (`403 quota_exceeded`)\nrefuses one; show its `detail` to the owner as it is, since it says where to fix\nit. A job that books the next one (a daily sync) must never swallow that\nrefusal: keep it, show it as a banner on the app\'s main page, and return it from\nthe app\'s status endpoint. Every service error code:\nhttps://docs.clawnify.com/concepts/service-errors\n\n## Migrations\n\nThe workflow is:\n\n1. Edit `src/server/schema.ts` for the new shape (types + queries).\n2. Run `pnpm db:generate` \u2014 emits the migration SQL under\n `.clawnify/drizzle/`.\n3. Run `npx clawnify@latest dev` locally, then `npx clawnify@latest deploy`.\n\nOn deploy your schema changes are applied to the app\'s database \u2014 new\ntables and columns are added automatically.\n\nDestructive changes (drop column, rename) are not applied automatically;\ndo them deliberately, and only when the user explicitly asks. Renames\nare risky on production data \u2014 prefer "add new column, backfill, switch\nqueries, drop old column" over a single-step rename.\n\n## What the agent must NOT do\n\n- Author a `/openapi.json` or `/llms.txt` handler by hand. `createApp()`\n mounts both, generated from your `createRoute` definitions.\n- Hand-write a `schema.sql`, edit anything under `.clawnify/`, or add a\n root `drizzle.config.ts`. Schema changes happen in `schema.ts`; the\n CLI generates and applies the SQL.\n- Invent an `api.tools[]` array in the manifest. It isn\'t a valid\n field \u2014 the OpenAPI spec is the tool surface.\n- Use `JSON.stringify` on query params. JSON columns auto-serialize\n via Drizzle. The raw SQL API has `json()` as a helper.\n- Skip the `org_id` filter on a user-facing query. Multi-tenant\n leak is the worst-class bug we can ship.\n- Return a whole table from a list endpoint, or a bare array. Every list\n pages: `PageQuery`, `pageParams` and `pagedResponse` from `@clawnify/app`.\n- Read auth from `Authorization` / cookies / `Bearer` tokens, or\n hand-parse `X-Clawnify-*` headers. Use `user(c)` / `orgId(c)` /\n `caller(c)` from `@clawnify/app`.\n- Call third-party APIs with raw `fetch` or hardcoded tokens. Go\n through `@clawnify/connections` (`connect` / `secret` / `run`).\n- Install `drizzle-orm` as a separate top-level dependency.\n `@clawnify/db@^0.4.1` pulls it in transitively; only add it if you\n need to pin a specific version (rare).\n\n## What the agent SHOULD do\n\n- Import everything from `@clawnify/db` where possible\n (`getDB`, `eq`, `and`, `desc`, `sql`, `sqliteTable`, `text`,\n `integer`, `index`, etc. are all re-exported there). Drop to\n `drizzle-orm` directly only for things not re-exported.\n- Give every route a clear `summary`/`description` and Zod-typed\n request/response so the agent can discover and call it via the\n OpenAPI spec.\n- Page every list endpoint with the helpers `@clawnify/app` exports:\n `request: { query: PageQuery.extend({ /* filters */ }) }`,\n `const { page, limit, offset, search } = pageParams(c.req.valid("query"))`\n (25 per page by default, capped at 100, bad input falls back), and\n `responses: { 200: pagedResponse("items", ItemSchema) }` for\n `{ items, total, page, limit }`. Count with `db.$count(table, where)`.\n- Keep a long text field an agent edits again and again (HTML, a\n document body, a template) as one top-level string of the record,\n with GET and a *partial* update (`PATCH`, or a PUT that keeps the\n fields it is not sent) on the same path, returning the updated\n record. Agents then read it in parts and change it with literal\n `old_text` \u2192 `new_text` edits instead of sending all of it back; the\n platform provides that, so don\'t build a find/replace endpoint.\n- Type a helper that takes the database client as `DB<typeof schema>`\n (from `@clawnify/db`), and a separate routes file\'s env as `AppEnv`\n (from `@clawnify/app`). Never name the backend (`D1Database`,\n `DrizzleD1Database`) or cast `getDB`\'s result: the same app code is\n served by more than one database backend.\n- Test locally with `npx clawnify@latest dev` before deploying; deploys go live at\n `https://<slug>.apps.clawnify.com` (the dashboard\'s preview pane shows\n the draft tier).\n- When unsure about a Drizzle pattern, check the `@clawnify/db`\n README for the current API + version notes.\n\n## Schema-as-data exception\n\nApps that let END users define data shapes at runtime (CMS, no-code\ntable editor) can\'t model their schema in `schema.ts` \u2014 the table\ndefinitions live in rows. Those apps fall back to the raw SQL API\nfrom `@clawnify/db` (`query`, `get`, `run`, `json`). Open-cms is\nthe canonical example.\n\nIf you\'re building this kind of app, you still use Drizzle\'s\n`schema.ts` for the **registry** tables (content types, field\ndefinitions). Only the dynamically-spawned per-collection tables\nneed raw SQL. See open-cms\'s `src/server/schema-sync.ts` for the\nruntime DDL pattern.\n\n## When you\'re stuck: compare with a working app\n\nEvery `Open*` repo under [github.com/clawnify](https://github.com/clawnify)\nis a complete, open-source app running on this platform. When your\napp hits an error you can\'t resolve from this document, find one that\ndoes the same thing and compare how it does it.\n\n- **Pick the repo by what it uses.** Each repo\'s `clawnify.json`\n declares it: `app.credentials` lists its integrations (`metaads`,\n `googleads`, ...), `app.database` and `app.storage` say whether it\n uses D1 and R2. The README says what the app does.\n- **Read it without signing in.** List the repos at\n `https://api.github.com/orgs/clawnify/repos?per_page=100`, and fetch\n any file at `https://raw.githubusercontent.com/clawnify/<repo>/HEAD/<path>`\n (`HEAD` resolves the default branch, which is not always `main`).\n- **Copy the solution, not the layout.** This document wins on\n conventions. Many templates predate parts of it: most hand-write\n `src/server/schema.sql` instead of `schema.ts`, some use Preact, and\n older ones don\'t page their lists with the `@clawnify/app` helpers.\n- **If the error comes from a `@clawnify/*` package**, read what you\n installed: `node_modules/@clawnify/<pkg>/README.md` and\n `dist/index.d.ts`, which match your version exactly.\n'
|
|
1800
1802
|
},
|
|
1801
1803
|
{
|
|
1802
1804
|
name: "build-a-clawnify-website",
|
|
@@ -3629,6 +3631,41 @@ async function connectionsConnectCommand(id, opts) {
|
|
|
3629
3631
|
// src/commands/workspace.ts
|
|
3630
3632
|
import fs7 from "fs";
|
|
3631
3633
|
import path10 from "path";
|
|
3634
|
+
import { spawnSync } from "child_process";
|
|
3635
|
+
|
|
3636
|
+
// src/commands/git-credential.ts
|
|
3637
|
+
var GIT_HOST = "api.clawnify.com";
|
|
3638
|
+
var GIT_HELPER = "!npx --yes clawnify@latest git-credential";
|
|
3639
|
+
async function readRequest() {
|
|
3640
|
+
let text = "";
|
|
3641
|
+
for await (const chunk of process.stdin) text += chunk;
|
|
3642
|
+
const fields = {};
|
|
3643
|
+
for (const line of text.split("\n")) {
|
|
3644
|
+
const at = line.indexOf("=");
|
|
3645
|
+
if (at > 0) fields[line.slice(0, at)] = line.slice(at + 1);
|
|
3646
|
+
}
|
|
3647
|
+
return fields;
|
|
3648
|
+
}
|
|
3649
|
+
async function gitCredentialCommand(operation) {
|
|
3650
|
+
const request = await readRequest();
|
|
3651
|
+
if (request.protocol !== "https" || request.host !== GIT_HOST) return;
|
|
3652
|
+
if (operation === "erase") {
|
|
3653
|
+
if (request.password) await refreshOnUnauthorized(request.password);
|
|
3654
|
+
return;
|
|
3655
|
+
}
|
|
3656
|
+
if (operation !== "get") return;
|
|
3657
|
+
const token = await getValidToken();
|
|
3658
|
+
if (!token) {
|
|
3659
|
+
console.error("Not signed in to Clawnify. Run: npx clawnify@latest login");
|
|
3660
|
+
process.stdout.write("quit=1\n");
|
|
3661
|
+
return;
|
|
3662
|
+
}
|
|
3663
|
+
process.stdout.write(`username=clawnify
|
|
3664
|
+
password=${token}
|
|
3665
|
+
`);
|
|
3666
|
+
}
|
|
3667
|
+
|
|
3668
|
+
// src/commands/workspace.ts
|
|
3632
3669
|
function slugify3(name) {
|
|
3633
3670
|
return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 30);
|
|
3634
3671
|
}
|
|
@@ -3748,13 +3785,18 @@ back under the same subdirs. See \`docs/internal/adr-company-monorepo.md\` \xA7
|
|
|
3748
3785
|
console.log(` clawnify deploy apps/<name>`);
|
|
3749
3786
|
console.log();
|
|
3750
3787
|
}
|
|
3788
|
+
function targetLabel(target) {
|
|
3789
|
+
return target.type === "app" ? `app: ${target.name} (${target.slug})` : target.type === "website" ? `website: ${target.slug}` : `agent: ${target.name}`;
|
|
3790
|
+
}
|
|
3751
3791
|
var WORKSPACE_GUIDE = `How editing works:
|
|
3752
|
-
- The org has ONE workspace repo
|
|
3753
|
-
|
|
3754
|
-
|
|
3755
|
-
|
|
3756
|
-
|
|
3757
|
-
|
|
3792
|
+
- The org has ONE workspace repo: Clawnify git (clone it with
|
|
3793
|
+
\`clawnify workspace clone\`), or GitHub if the org connected it. The
|
|
3794
|
+
website lives under website/ (Astro), apps under apps/<slug>/, and on
|
|
3795
|
+
GitHub agent configs under agents/<name>/. Each folder two-way syncs
|
|
3796
|
+
with Clawnify.
|
|
3797
|
+
- Pushing to main auto-rebuilds ONLY the folders that changed.
|
|
3798
|
+
Clawnify also pushes its own edits back into the repo, so pull
|
|
3799
|
+
before you start.
|
|
3758
3800
|
- Website: cd website && pnpm install && pnpm dev (Node 22+; preview on
|
|
3759
3801
|
localhost:4321). Do NOT use \`clawnify dev\` for the website \u2014 it is
|
|
3760
3802
|
for apps only. Reuse the existing components/blocks under src/.
|
|
@@ -3788,17 +3830,43 @@ ${WORKSPACE_GUIDE}`);
|
|
|
3788
3830
|
process.exit(1);
|
|
3789
3831
|
}
|
|
3790
3832
|
const orgId = await resolveOrgContext();
|
|
3791
|
-
const res = await api.get("/v1/
|
|
3833
|
+
const res = await api.get("/v1/workspace", orgId ? { orgId } : void 0);
|
|
3792
3834
|
if (!res.ok) {
|
|
3793
3835
|
console.error(`Failed to load workspace state (${res.status}).`);
|
|
3794
3836
|
process.exit(1);
|
|
3795
3837
|
}
|
|
3796
|
-
const
|
|
3838
|
+
const state = await res.json();
|
|
3839
|
+
const data = { org_id: state.org_id, installations: state.github.installations, links: state.github.links };
|
|
3797
3840
|
if (opts?.json) {
|
|
3798
|
-
console.log(JSON.stringify({ logged_in: true, ...data, guide: WORKSPACE_GUIDE }));
|
|
3841
|
+
console.log(JSON.stringify({ logged_in: true, ...data, git: state.git, guide: WORKSPACE_GUIDE }));
|
|
3799
3842
|
return;
|
|
3800
3843
|
}
|
|
3801
3844
|
console.log(`Org: ${data.org_id}`);
|
|
3845
|
+
if (state.git) {
|
|
3846
|
+
const git = state.git;
|
|
3847
|
+
console.log(`
|
|
3848
|
+
Workspace repo: Clawnify git`);
|
|
3849
|
+
console.log(` Clone: npx clawnify@latest workspace clone`);
|
|
3850
|
+
console.log(` Remote: ${git.url} (git signs in with your Clawnify login)`);
|
|
3851
|
+
for (const f of git.folders) console.log(` ${(f.subdir || "(root)").padEnd(28)} ${targetLabel(f.target)}`);
|
|
3852
|
+
console.log(
|
|
3853
|
+
git.can_push ? " You can push. A push rebuilds only the folders it changed." : " You can clone and pull. Pushing needs an owner or admin of the org."
|
|
3854
|
+
);
|
|
3855
|
+
console.log(` Cloned some other way? Inside the clone, run:
|
|
3856
|
+
git config --replace-all credential.https://${GIT_HOST}.helper ''
|
|
3857
|
+
git config --add credential.https://${GIT_HOST}.helper '${GIT_HELPER}'`);
|
|
3858
|
+
for (const key of new Set(data.links.map((l) => `${l.repo}#${l.branch}`))) {
|
|
3859
|
+
const [repo, branch] = key.split("#");
|
|
3860
|
+
console.log(`
|
|
3861
|
+
GitHub (separate): ${repo} (branch ${branch})`);
|
|
3862
|
+
for (const l of data.links.filter((x) => `${x.repo}#${x.branch}` === key)) {
|
|
3863
|
+
console.log(` ${(l.subdir || "(root)").padEnd(28)} ${targetLabel(l.target)}`);
|
|
3864
|
+
}
|
|
3865
|
+
}
|
|
3866
|
+
console.log(`
|
|
3867
|
+
${WORKSPACE_GUIDE}`);
|
|
3868
|
+
return;
|
|
3869
|
+
}
|
|
3802
3870
|
if (data.links.length === 0) {
|
|
3803
3871
|
console.log(`
|
|
3804
3872
|
No GitHub repo is linked yet. Local editing works through the org's
|
|
@@ -3824,14 +3892,53 @@ ${WORKSPACE_GUIDE}`);
|
|
|
3824
3892
|
console.log(`
|
|
3825
3893
|
Repo: ${repo} (branch ${branch})`);
|
|
3826
3894
|
console.log(` Clone: git clone https://github.com/${repo}.git`);
|
|
3827
|
-
for (const l of list) {
|
|
3828
|
-
const label = l.target.type === "app" ? `app: ${l.target.name} (${l.target.slug})` : l.target.type === "website" ? `website: ${l.target.slug}` : `agent: ${l.target.name}`;
|
|
3829
|
-
console.log(` ${(l.subdir || "(root)").padEnd(28)} ${label}`);
|
|
3830
|
-
}
|
|
3895
|
+
for (const l of list) console.log(` ${(l.subdir || "(root)").padEnd(28)} ${targetLabel(l.target)}`);
|
|
3831
3896
|
}
|
|
3832
3897
|
console.log(`
|
|
3833
3898
|
${WORKSPACE_GUIDE}`);
|
|
3834
3899
|
}
|
|
3900
|
+
async function workspaceCloneCommand(dir, opts) {
|
|
3901
|
+
if (!await getValidToken()) {
|
|
3902
|
+
console.error(`Not logged in.
|
|
3903
|
+
|
|
3904
|
+
\`clawnify login\` opens a browser for OAuth, which a coding agent cannot
|
|
3905
|
+
complete headlessly. Ask the user to run:
|
|
3906
|
+
|
|
3907
|
+
npx clawnify@latest login
|
|
3908
|
+
|
|
3909
|
+
then re-run \`clawnify workspace clone\`.`);
|
|
3910
|
+
process.exit(1);
|
|
3911
|
+
}
|
|
3912
|
+
const org = await resolveOrg(opts);
|
|
3913
|
+
const res = await api.get("/v1/workspace", { orgId: org.id });
|
|
3914
|
+
if (!res.ok) {
|
|
3915
|
+
console.error(`Failed to load workspace state (${res.status}).`);
|
|
3916
|
+
process.exit(1);
|
|
3917
|
+
}
|
|
3918
|
+
const state = await res.json();
|
|
3919
|
+
if (!state.git) {
|
|
3920
|
+
const github = state.github.links[0];
|
|
3921
|
+
console.error(
|
|
3922
|
+
github ? `${org.name} keeps its workspace repo on GitHub. Clone it with:
|
|
3923
|
+
|
|
3924
|
+
git clone https://github.com/${github.repo}.git` : `${org.name} has no Clawnify git repo yet. Run \`clawnify workspace\` to see how its workspace is set up.`
|
|
3925
|
+
);
|
|
3926
|
+
process.exit(1);
|
|
3927
|
+
}
|
|
3928
|
+
const target = dir ?? slugify3(org.slug);
|
|
3929
|
+
const key = `credential.https://${GIT_HOST}.helper`;
|
|
3930
|
+
const clone = spawnSync("git", ["clone", "-c", `${key}=`, "-c", `${key}=${GIT_HELPER}`, state.git.url, target], { stdio: "inherit" });
|
|
3931
|
+
if (clone.error) {
|
|
3932
|
+
console.error(`Could not run git: ${clone.error.message}`);
|
|
3933
|
+
process.exit(1);
|
|
3934
|
+
}
|
|
3935
|
+
if (clone.status !== 0) process.exit(clone.status ?? 1);
|
|
3936
|
+
console.log(`
|
|
3937
|
+
Cloned ${org.name} into ${target}/. git pull and git push sign in with your
|
|
3938
|
+
Clawnify login.${state.git.can_push ? "" : " You can pull; pushing needs an owner or admin."}
|
|
3939
|
+
|
|
3940
|
+
Run \`clawnify workspace\` in it for what maps where and how editing works.`);
|
|
3941
|
+
}
|
|
3835
3942
|
var INSTALL_URL = "https://github.com/apps/clawnify/installations/new";
|
|
3836
3943
|
var INSTALL_POLL_MS = 5e3;
|
|
3837
3944
|
var INSTALL_TIMEOUT_MS = 5 * 6e4;
|
|
@@ -4232,7 +4339,7 @@ Valid: ${ALL_AGENTS.join(", ")}`
|
|
|
4232
4339
|
}
|
|
4233
4340
|
|
|
4234
4341
|
// src/commands/flows.ts
|
|
4235
|
-
import { spawnSync } from "child_process";
|
|
4342
|
+
import { spawnSync as spawnSync2 } from "child_process";
|
|
4236
4343
|
import fs9 from "fs";
|
|
4237
4344
|
import os from "os";
|
|
4238
4345
|
import path11 from "path";
|
|
@@ -4354,7 +4461,7 @@ async function flowsEditCommand(name, opts) {
|
|
|
4354
4461
|
tmpFile = path11.join(tmpDir, flowFileName(name));
|
|
4355
4462
|
fs9.writeFileSync(tmpFile, JSON.stringify(current, null, 2) + "\n");
|
|
4356
4463
|
const editor = process.env.VISUAL || process.env.EDITOR || "vi";
|
|
4357
|
-
const result =
|
|
4464
|
+
const result = spawnSync2(`${editor} "${tmpFile}"`, { shell: true, stdio: "inherit" });
|
|
4358
4465
|
if (result.status !== 0) {
|
|
4359
4466
|
console.error(`Editor exited without saving \u2014 draft unchanged (kept at ${tmpFile}).`);
|
|
4360
4467
|
process.exit(1);
|
|
@@ -4413,7 +4520,7 @@ async function runCli() {
|
|
|
4413
4520
|
const program = new Command();
|
|
4414
4521
|
program.name("clawnify").description("Deploy apps to Clawnify").version(VERSION).addHelpText(
|
|
4415
4522
|
"after",
|
|
4416
|
-
"\nCoding agent? Start with `clawnify workspace
|
|
4523
|
+
"\nCoding agent? Start with `clawnify workspace`: it prints the org's workspace\nrepo (Clawnify git or GitHub), what maps where, and how local editing works.\n"
|
|
4417
4524
|
);
|
|
4418
4525
|
program.hook("preAction", (_program, actionCommand) => {
|
|
4419
4526
|
const opts = actionCommand.opts();
|
|
@@ -4439,9 +4546,11 @@ async function runCli() {
|
|
|
4439
4546
|
const connections = program.command("connections").description("Org integrations & the naming catalog");
|
|
4440
4547
|
connections.command("list").description("List canonical integration ids, provider keys, and custom env for the active org").option("--json", "Print the full catalog payload (includes docs + spec_url per integration)").action(connectionsListCommand);
|
|
4441
4548
|
connections.command("connect <id>").description("Explain how to connect an integration (OAuth in the dashboard \u2014 the CLI/agent can't do it for you)").option("--json", "Print the steps as JSON").action(connectionsConnectCommand);
|
|
4442
|
-
const workspace = program.command("workspace").description("Show the org's workspace:
|
|
4549
|
+
const workspace = program.command("workspace").description("Show the org's workspace: its repo (Clawnify git or GitHub), targets, and how to edit locally").option("--json", "Machine-readable output").action(workspaceStatusCommand);
|
|
4550
|
+
workspace.command("clone [dir]").description("Clone the org's Clawnify git repo; git signs in with your Clawnify login").option("--org <slug-or-id>", "Org to clone (defaults to the folder's or only org)").action(workspaceCloneCommand);
|
|
4443
4551
|
workspace.command("init [dir]").description("Scaffold a workspace monorepo bound to an org").option("--org <slug-or-id>", "Org to bind the workspace to (defaults to active org)").option("--name <name>", "Workspace display name (defaults to the org name)").action(workspaceInitCommand);
|
|
4444
4552
|
workspace.command("connect").description("Enable GitHub sync: create/join the org's workspace repo and link the website").option("--account <login-or-id>", "GitHub account to use when several are connected").action(workspaceConnectCommand);
|
|
4553
|
+
program.command("git-credential <operation>", { hidden: true }).description("Git credential helper for Clawnify git (get, store, erase)").action(gitCredentialCommand);
|
|
4445
4554
|
program.command("ls").description("List deployed apps").action(lsCommand);
|
|
4446
4555
|
program.command("logs <app-id>").description("Show build logs for an app").action(logsCommand);
|
|
4447
4556
|
const servers = program.command("servers", { hidden: true }).description("Deprecated \u2014 use `clawnify agents list`");
|
package/dist/index.js
CHANGED
|
@@ -2,9 +2,9 @@
|
|
|
2
2
|
|
|
3
3
|
// src/index.ts
|
|
4
4
|
if (process.argv.includes("--mcp")) {
|
|
5
|
-
const { startMcpServer } = await import("./mcp-
|
|
5
|
+
const { startMcpServer } = await import("./mcp-PHXR4VAC.js");
|
|
6
6
|
await startMcpServer();
|
|
7
7
|
} else {
|
|
8
|
-
const { runCli } = await import("./cli-
|
|
8
|
+
const { runCli } = await import("./cli-WASGAE6S.js");
|
|
9
9
|
await runCli();
|
|
10
10
|
}
|