clawnify 0.21.0 → 0.22.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.
|
@@ -6,6 +6,7 @@ import {
|
|
|
6
6
|
VERSION,
|
|
7
7
|
api,
|
|
8
8
|
createArchive,
|
|
9
|
+
findProjectRoot,
|
|
9
10
|
findWorkspaceRoot,
|
|
10
11
|
generatePkce,
|
|
11
12
|
getEmailFromToken,
|
|
@@ -21,7 +22,7 @@ import {
|
|
|
21
22
|
resolveOrgContext,
|
|
22
23
|
saveAuth,
|
|
23
24
|
saveProject
|
|
24
|
-
} from "./chunk-
|
|
25
|
+
} from "./chunk-ID77VUXK.js";
|
|
25
26
|
|
|
26
27
|
// src/cli.ts
|
|
27
28
|
import { Command, Option } from "commander";
|
|
@@ -233,8 +234,8 @@ async function getOrCreateAnonContext(dir, name, agents) {
|
|
|
233
234
|
saveAnon(dir, ctx);
|
|
234
235
|
return { ctx, created: true };
|
|
235
236
|
}
|
|
236
|
-
async function anonPostForm(
|
|
237
|
-
return api.request("POST",
|
|
237
|
+
async function anonPostForm(path14, formData, ctx) {
|
|
238
|
+
return api.request("POST", path14, { formData, token: ctx.deploy_token });
|
|
238
239
|
}
|
|
239
240
|
function explainAnonUnauthorized(dir) {
|
|
240
241
|
clearAnon(dir);
|
|
@@ -429,11 +430,11 @@ function ask(question) {
|
|
|
429
430
|
});
|
|
430
431
|
});
|
|
431
432
|
}
|
|
432
|
-
async function postFormWithRetry(
|
|
433
|
+
async function postFormWithRetry(path14, formData, orgId, attempts = 3) {
|
|
433
434
|
let lastErr;
|
|
434
435
|
for (let i = 0; i < attempts; i++) {
|
|
435
436
|
try {
|
|
436
|
-
return await api.postForm(
|
|
437
|
+
return await api.postForm(path14, formData, { orgId });
|
|
437
438
|
} catch (err) {
|
|
438
439
|
lastErr = err;
|
|
439
440
|
if (i === attempts - 1) break;
|
|
@@ -464,7 +465,7 @@ async function uploadDeploy(archive, name, framework, orgId) {
|
|
|
464
465
|
return { ok: false, error: err.error || res.statusText };
|
|
465
466
|
}
|
|
466
467
|
function gitSyncBase(dir) {
|
|
467
|
-
const
|
|
468
|
+
const git2 = (...args) => {
|
|
468
469
|
try {
|
|
469
470
|
return execFileSync("git", ["-C", dir, ...args], {
|
|
470
471
|
encoding: "utf8",
|
|
@@ -474,7 +475,7 @@ function gitSyncBase(dir) {
|
|
|
474
475
|
return void 0;
|
|
475
476
|
}
|
|
476
477
|
};
|
|
477
|
-
return
|
|
478
|
+
return git2("merge-base", "HEAD", "@{upstream}") ?? git2("rev-parse", "HEAD");
|
|
478
479
|
}
|
|
479
480
|
function appendSyncFields(formData, dir, force) {
|
|
480
481
|
if (force) {
|
|
@@ -695,8 +696,8 @@ async function refuseWebsiteReplace(orgId, linkedWebsiteId, options) {
|
|
|
695
696
|
if (!existing) return;
|
|
696
697
|
console.error(
|
|
697
698
|
`This organization already has a website (${existing.slug}), and this folder isn't linked to it.
|
|
698
|
-
Deploying replaces that site's pages, theme and code with this folder
|
|
699
|
-
|
|
699
|
+
Deploying replaces that site's pages, theme and code with this folder, and publishes
|
|
700
|
+
it, unless the site has unpublished changes from the chat.
|
|
700
701
|
|
|
701
702
|
To edit the existing site: use the website editor in the dashboard, or work in a
|
|
702
703
|
clone of the org's workspace repo (\`clawnify workspace\` shows it).
|
|
@@ -843,8 +844,8 @@ async function deployWebsite(dir, options) {
|
|
|
843
844
|
} else {
|
|
844
845
|
console.log(
|
|
845
846
|
`
|
|
846
|
-
\u2713 Deployed
|
|
847
|
-
Review
|
|
847
|
+
\u2713 Deployed as a draft. The site has unpublished changes from the chat, so this deploy joined them.
|
|
848
|
+
Review them in the dashboard, then "Publish to live" to ship both.
|
|
848
849
|
`
|
|
849
850
|
);
|
|
850
851
|
}
|
|
@@ -1082,7 +1083,7 @@ async function deployCommand(dir, options = {}) {
|
|
|
1082
1083
|
}
|
|
1083
1084
|
console.log(`
|
|
1084
1085
|
\u2713 Deployed (private link):`);
|
|
1085
|
-
console.log(` https://${data.slug}.
|
|
1086
|
+
console.log(` ${data.url ?? `https://${data.slug}.draft.clawnify.com`}?token=${data.app_token}
|
|
1086
1087
|
`);
|
|
1087
1088
|
printClaimBlock(ctx);
|
|
1088
1089
|
return;
|
|
@@ -1632,7 +1633,7 @@ async function envUnsetCommand(key) {
|
|
|
1632
1633
|
}
|
|
1633
1634
|
|
|
1634
1635
|
// src/commands/api.ts
|
|
1635
|
-
async function apiCommand(
|
|
1636
|
+
async function apiCommand(path14, opts) {
|
|
1636
1637
|
const method = (opts.method || (opts.data !== void 0 ? "POST" : "GET")).toUpperCase();
|
|
1637
1638
|
let body;
|
|
1638
1639
|
if (opts.data !== void 0) {
|
|
@@ -1643,7 +1644,7 @@ async function apiCommand(path12, opts) {
|
|
|
1643
1644
|
process.exit(1);
|
|
1644
1645
|
}
|
|
1645
1646
|
}
|
|
1646
|
-
const p =
|
|
1647
|
+
const p = path14.startsWith("/") ? path14 : `/${path14}`;
|
|
1647
1648
|
const orgId = await resolveOrgContext({ orgFlag: opts.org });
|
|
1648
1649
|
const res = await api.call(method, p, { body, orgId });
|
|
1649
1650
|
const text = await res.text();
|
|
@@ -1694,24 +1695,7 @@ async function rmCommand(appId) {
|
|
|
1694
1695
|
// src/commands/open.ts
|
|
1695
1696
|
import open2 from "open";
|
|
1696
1697
|
async function openCommand(slug) {
|
|
1697
|
-
|
|
1698
|
-
const project = readProject();
|
|
1699
|
-
if (project?.slug === slug && project.app_token) {
|
|
1700
|
-
appToken = project.app_token;
|
|
1701
|
-
}
|
|
1702
|
-
if (!appToken) {
|
|
1703
|
-
const res = await api.get("/v1/apps");
|
|
1704
|
-
if (res.ok) {
|
|
1705
|
-
const apps = await res.json();
|
|
1706
|
-
const app = apps.find((a) => a.slug === slug);
|
|
1707
|
-
appToken = app?.app_token;
|
|
1708
|
-
}
|
|
1709
|
-
}
|
|
1710
|
-
let url = `https://${slug}.apps.clawnify.com`;
|
|
1711
|
-
if (appToken) {
|
|
1712
|
-
url += `?token=${appToken}`;
|
|
1713
|
-
}
|
|
1714
|
-
await open2(url);
|
|
1698
|
+
await open2(`https://app.clawnify.com/apps/${encodeURIComponent(slug)}`);
|
|
1715
1699
|
console.log("Opened in browser");
|
|
1716
1700
|
}
|
|
1717
1701
|
|
|
@@ -1767,9 +1751,9 @@ var DETECTORS = [
|
|
|
1767
1751
|
{ agent: "aider", markers: ["CONVENTIONS.md", ".aider.conf.yml"], target: "CONVENTIONS.md" }
|
|
1768
1752
|
];
|
|
1769
1753
|
function exists(cwd, name) {
|
|
1770
|
-
const
|
|
1754
|
+
const path14 = join(cwd, name);
|
|
1771
1755
|
try {
|
|
1772
|
-
statSync(
|
|
1756
|
+
statSync(path14);
|
|
1773
1757
|
return true;
|
|
1774
1758
|
} catch {
|
|
1775
1759
|
return false;
|
|
@@ -1793,17 +1777,17 @@ function agentByName(name) {
|
|
|
1793
1777
|
var ALL_AGENTS = DETECTORS.map((d) => d.agent);
|
|
1794
1778
|
|
|
1795
1779
|
// src/lib/skills/content.gen.ts
|
|
1796
|
-
var CLI_VERSION = "0.
|
|
1780
|
+
var CLI_VERSION = "0.22.0";
|
|
1797
1781
|
var BUNDLED_SKILLS = [
|
|
1798
1782
|
{
|
|
1799
1783
|
name: "build-a-clawnify-app",
|
|
1800
1784
|
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.",
|
|
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'
|
|
1785
|
+
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| `hasRole(c, min)` | Whether the caller may do a task meant for `min` (`member` < `admin` < `owner`). Use it to gate admin-only tasks. Needs `@clawnify/app` 0.4.5 or later. |\n| `role(c)` | `owner`, `admin` or `member` on Team plans and up; **`null`** below that, where every member is treated the same. For display, not for gating. |\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. For a task meant for admins, use\n`hasRole(c, "admin")`: it checks the role where the plan has role tiers\nand lets every person through where it does not, so one check works on\nevery plan. It fails closed: a caller with no person behind it, or a\nrequest with no identity at all (local `pnpm dev`), passes no check, so a\ngated endpoint answering 403 there is the gate working. Don\'t loosen a\ngate to make a test pass. Never gate on `role(c)` by hand.\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'
|
|
1802
1786
|
},
|
|
1803
1787
|
{
|
|
1804
1788
|
name: "build-a-clawnify-website",
|
|
1805
|
-
description: "Build and ship a Clawnify website
|
|
1806
|
-
content: "# Build a Clawnify website\n\nA Clawnify website is an **Astro** project deployed to Cloudflare Workers. One\nsite per organization. You write pages; the platform owns hosting, forms and\nthe publish flow.\n\n```bash\nnpx clawnify@latest init --type website --name \"My Site\" website\ncd website && pnpm install && pnpm dev # http://localhost:4321\n```\n\nAlways invoke the CLI as `npx clawnify@latest <command>` \u2014 never a\nglobal or pinned install; stale CLIs miss deploy guards and fixes.\n\n```\nwebsite/\n src/pages/ # one .astro file per route (index.astro \u2192 /)\n src/layouts/ # shared shell: nav, footer, <head>\n src/blocks/ # platform blocks you've adopted (see Forms below)\n public/ # images, favicons \u2014 served as-is from /\n```\n\n## Forms: use the built-in system. Do not build your own.\n\n**This is the single most common mistake.** A site needs a contact or waitlist\nform, and the obvious move is to write a `<form>` and POST it somewhere \u2014 your\nown endpoint, a third-party form service, or the platform's submit URL with the\nwebsite id pasted in. All three are wrong, and the last one looks right enough\nto survive review.\n\nClawnify has a form system. It captures submissions, stores them, can email you,\nand can hand each one to an agent or a flow. You get all of it by using the\n**Forms block** rather than writing a form yourself.\n\n### How it works\n\n- The submit target is **computed at render time** from `WEBSITE_ID` \u2014 a\n variable the platform bakes into your site's Worker \u2014 plus the form's id:\n\n ```astro\n const env = (Astro.locals as { runtime?: { env?: Record<string, string> } })?.runtime?.env;\n const websiteId = env?.WEBSITE_ID ?? \"\";\n const action = websiteId ? `https://provision.clawnify.com/forms/submit/${websiteId}/${formId}` : \"\";\n ```\n\n **Never hardcode the website id.** It is baked per Worker so a site can only\n ever submit to itself \u2014 hardcoding throws that away, and the literal goes\n stale the moment the site is recreated. An empty `action` in local `astro dev`\n is expected: there are no Worker vars locally, so the form simply no-ops.\n\n- The submit script POSTs JSON with `Content-Type: text/plain;charset=UTF-8`.\n That is not a typo \u2014 `text/plain` is CORS-safelisted, so the request needs no\n preflight, which matters because the platform can't know your site's origin in\n advance. The route parses the text body as JSON.\n\n- **Keep the Turnstile widget.** The ingest rejects a submission with no token,\n so a form without the widget fails every time with \"Verification required\".\n The sitekey shipped in the block is public and pairs with the platform's\n secret; the widget will not validate on `localhost`, only on a real hostname.\n\n### Getting the block\n\nSites are seeded with the platform's block library at creation. If yours has\n`src/blocks/Forms/Contact.astro`, import it and go. If it doesn't \u2014 an older\nsite, or one scaffolded bare by the CLI \u2014 copy it in from the website template\nand adapt it.\n\n**The design is yours; the plumbing is not.** Restyle the markup, labels and\nclasses freely. Preserve, exactly:\n\n- the computed `action` (never a prop, never a literal),\n- the Turnstile widget,\n- the `data-clawnify-managed-form` attribute,\n- `export const schema`,\n- destructuring only known props \u2014 never splat leftover props onto `<form>`,\n or an injected `action` becomes a way to point your form at someone else.\n\nThere is no submit script to copy. The runtime lives in the framework catch-all\n(`src/pages/[...path].astro`) and binds every `data-clawnify-managed-form` on\nthe page. If the block you inherited still has its own inline `<script>` and a\n`data-clawnify-form` attribute, it is the older shape: it still works, and you\ncan migrate it by deleting the script and renaming the attribute. Do not carry\nboth attributes on one form, and do not add `data-clawnify-form` to a managed\nform: older blocks bind that selector unconditionally, so the form would submit\ntwice.\n\n### After a successful submit\n\nTwo options, and the default is unchanged.\n\n- **Inline message** (default). The `successText` prop, rendered into the\n status line.\n- **Redirect.** Set the `successUrl` prop, or `data-success-url` on any form\n you hand-built. A site-relative path (`/thanks`) or an absolute `https://`\n URL (a booking page is fine). Anything else is ignored and the message is\n shown instead, which is what keeps `javascript:` out of the navigation.\n\nA redirect to a thank-you page is also the only way to count a form conversion\nin the analytics tool, which has no custom events: the dashboard Submissions\npanel counts submissions, but a pageview is what gives you a rate.\n\nNeed a side effect on success, like setting a cookie? Listen for the\n`clawnify:form-success` event on the form. It is cancelable, so\n`preventDefault()` suppresses the redirect if you would rather navigate\nyourself.\n\n### Fields\n\nThe stock block collects **name, email and message**. Two ways to go beyond\nthat, and the right one depends on whether your form is registered:\n\n- **Registered forms** (a tree node named `Forms/Contact`) are schema-locked:\n the ingest 422s any field it doesn't expect. Give extra inputs **no `name`\n attribute** and have the submit script fold them into `message`.\n- **Unregistered forms** \u2014 hand-built pages like this one \u2014 are not locked, so\n extra fields post as themselves and are stored verbatim in the payload. Better\n data, but if the site later moves onto the tree renderer, registration will\n start rejecting them. Leave a comment saying so.\n\n### PDF attachments\n\nThe Contact block can collect one PDF per submission (job applications, RFQs).\nOff by default \u2014 enable it with the block's `attachment` prop (and optionally\n`attachmentLabel`), then **publish**: the file field is registered at publish\ntime, and the ingest rejects files on forms that haven't registered one. Rules\nthe platform enforces server-side (don't fight them client-side): PDF only,\nverified by content not by extension, max 10 MB. The submission's payload\ncarries the filename and a download link that only the site's own organization\ncan open \u2014 the file is never on a public URL. When a file is attached the\nsubmit script posts `multipart/form-data` instead of JSON; both are\npreflight-free, and the block already handles the switch.\n\n### Where submissions go\n\nEvery submission is stored and visible in the dashboard. From there it can\nnotify an email address, or fan out to an agent or a flow \u2014 which is how a\nsignup becomes a CRM record or a WhatsApp message without you writing a backend.\nSet the notification address in the dashboard, not in the site.\n\n## Images and assets\n\nPut them in `public/` and reference them with an absolute path (`/img/hero.jpg`).\nThey're served as static files. Pull in real assets at real resolution rather\nthan linking someone else's CDN from your markup.\n\n## Deploying:
|
|
1789
|
+
description: "Build and ship a Clawnify website (Astro on Cloudflare Workers): the built-in form system (never hand-roll a form), images and assets, and the deploy flow (live, or a draft when the chat has one open). Use when creating or editing a Clawnify website, or when a site needs a contact/waitlist/signup form.",
|
|
1790
|
+
content: "# Build a Clawnify website\n\nA Clawnify website is an **Astro** project deployed to Cloudflare Workers. One\nsite per organization. You write pages; the platform owns hosting, forms and\nthe publish flow.\n\n```bash\nnpx clawnify@latest init --type website --name \"My Site\" website\ncd website && pnpm install && pnpm dev # http://localhost:4321\n```\n\nAlways invoke the CLI as `npx clawnify@latest <command>` \u2014 never a\nglobal or pinned install; stale CLIs miss deploy guards and fixes.\n\n```\nwebsite/\n src/pages/ # one .astro file per route (index.astro \u2192 /)\n src/layouts/ # shared shell: nav, footer, <head>\n src/blocks/ # platform blocks you've adopted (see Forms below)\n public/ # images, favicons \u2014 served as-is from /\n```\n\n## Forms: use the built-in system. Do not build your own.\n\n**This is the single most common mistake.** A site needs a contact or waitlist\nform, and the obvious move is to write a `<form>` and POST it somewhere \u2014 your\nown endpoint, a third-party form service, or the platform's submit URL with the\nwebsite id pasted in. All three are wrong, and the last one looks right enough\nto survive review.\n\nClawnify has a form system. It captures submissions, stores them, can email you,\nand can hand each one to an agent or a flow. You get all of it by using the\n**Forms block** rather than writing a form yourself.\n\n### How it works\n\n- The submit target is **computed at render time** from `WEBSITE_ID` \u2014 a\n variable the platform bakes into your site's Worker \u2014 plus the form's id:\n\n ```astro\n const env = (Astro.locals as { runtime?: { env?: Record<string, string> } })?.runtime?.env;\n const websiteId = env?.WEBSITE_ID ?? \"\";\n const action = websiteId ? `https://provision.clawnify.com/forms/submit/${websiteId}/${formId}` : \"\";\n ```\n\n **Never hardcode the website id.** It is baked per Worker so a site can only\n ever submit to itself \u2014 hardcoding throws that away, and the literal goes\n stale the moment the site is recreated. An empty `action` in local `astro dev`\n is expected: there are no Worker vars locally, so the form simply no-ops.\n\n- The submit script POSTs JSON with `Content-Type: text/plain;charset=UTF-8`.\n That is not a typo \u2014 `text/plain` is CORS-safelisted, so the request needs no\n preflight, which matters because the platform can't know your site's origin in\n advance. The route parses the text body as JSON.\n\n- **Keep the Turnstile widget.** The ingest rejects a submission with no token,\n so a form without the widget fails every time with \"Verification required\".\n The sitekey shipped in the block is public and pairs with the platform's\n secret; the widget will not validate on `localhost`, only on a real hostname.\n\n### Getting the block\n\nSites are seeded with the platform's block library at creation. If yours has\n`src/blocks/Forms/Contact.astro`, import it and go. If it doesn't \u2014 an older\nsite, or one scaffolded bare by the CLI \u2014 copy it in from the website template\nand adapt it.\n\n**The design is yours; the plumbing is not.** Restyle the markup, labels and\nclasses freely. Preserve, exactly:\n\n- the computed `action` (never a prop, never a literal),\n- the Turnstile widget,\n- the `data-clawnify-managed-form` attribute,\n- `export const schema`,\n- destructuring only known props \u2014 never splat leftover props onto `<form>`,\n or an injected `action` becomes a way to point your form at someone else.\n\nThere is no submit script to copy. The runtime lives in the framework catch-all\n(`src/pages/[...path].astro`) and binds every `data-clawnify-managed-form` on\nthe page. If the block you inherited still has its own inline `<script>` and a\n`data-clawnify-form` attribute, it is the older shape: it still works, and you\ncan migrate it by deleting the script and renaming the attribute. Do not carry\nboth attributes on one form, and do not add `data-clawnify-form` to a managed\nform: older blocks bind that selector unconditionally, so the form would submit\ntwice.\n\n### After a successful submit\n\nTwo options, and the default is unchanged.\n\n- **Inline message** (default). The `successText` prop, rendered into the\n status line.\n- **Redirect.** Set the `successUrl` prop, or `data-success-url` on any form\n you hand-built. A site-relative path (`/thanks`) or an absolute `https://`\n URL (a booking page is fine). Anything else is ignored and the message is\n shown instead, which is what keeps `javascript:` out of the navigation.\n\nA redirect to a thank-you page is also the only way to count a form conversion\nin the analytics tool, which has no custom events: the dashboard Submissions\npanel counts submissions, but a pageview is what gives you a rate.\n\nNeed a side effect on success, like setting a cookie? Listen for the\n`clawnify:form-success` event on the form. It is cancelable, so\n`preventDefault()` suppresses the redirect if you would rather navigate\nyourself.\n\n### Fields\n\nThe stock block collects **name, email and message**. Two ways to go beyond\nthat, and the right one depends on whether your form is registered:\n\n- **Registered forms** (a tree node named `Forms/Contact`) are schema-locked:\n the ingest 422s any field it doesn't expect. Give extra inputs **no `name`\n attribute** and have the submit script fold them into `message`.\n- **Unregistered forms** \u2014 hand-built pages like this one \u2014 are not locked, so\n extra fields post as themselves and are stored verbatim in the payload. Better\n data, but if the site later moves onto the tree renderer, registration will\n start rejecting them. Leave a comment saying so.\n\n### PDF attachments\n\nThe Contact block can collect one PDF per submission (job applications, RFQs).\nOff by default \u2014 enable it with the block's `attachment` prop (and optionally\n`attachmentLabel`), then **publish**: the file field is registered at publish\ntime, and the ingest rejects files on forms that haven't registered one. Rules\nthe platform enforces server-side (don't fight them client-side): PDF only,\nverified by content not by extension, max 10 MB. The submission's payload\ncarries the filename and a download link that only the site's own organization\ncan open \u2014 the file is never on a public URL. When a file is attached the\nsubmit script posts `multipart/form-data` instead of JSON; both are\npreflight-free, and the block already handles the switch.\n\n### Where submissions go\n\nEvery submission is stored and visible in the dashboard. From there it can\nnotify an email address, or fan out to an agent or a flow \u2014 which is how a\nsignup becomes a CRM record or a WhatsApp message without you writing a backend.\nSet the notification address in the dashboard, not in the site.\n\n## Images and assets\n\nPut them in `public/` and reference them with an absolute path (`/img/hero.jpg`).\nThey're served as static files. Pull in real assets at real resolution rather\nthan linking someone else's CDN from your markup.\n\n## Deploying: live, unless the chat has a draft open\n\n```bash\nnpx clawnify@latest deploy # \u2192 the LIVE site\n```\n\nA deploy (or a push to the workspace repo) goes live. The exception: when the\nsite has unpublished changes made from the dashboard chat, the deploy joins\nthem on the DRAFT site, visible only to your org, and **Publish to live** in the\ndashboard ships both. The CLI says which happened; pass it on to the user.\n\n## Pinning the org\n\nEvery command resolves which organization it targets, folder-first. In a linked\nfolder you get it for free; otherwise pass `--org`. If you work across several\norganizations, pass `--org` explicitly on anything that writes \u2014 the global\nactive org is shared machine-wide and another session can change it under you.\n"
|
|
1807
1791
|
},
|
|
1808
1792
|
{
|
|
1809
1793
|
name: "use-the-clawnify-cli",
|
|
@@ -1838,10 +1822,10 @@ var VERSION_HEADER_RE = /<!--\s*clawnify-skill:\s*([\w-]+)\s+v([\d.]+)\s*-->/;
|
|
|
1838
1822
|
function versionHeader(name) {
|
|
1839
1823
|
return `<!-- clawnify-skill: ${name} v${CLI_VERSION} -->`;
|
|
1840
1824
|
}
|
|
1841
|
-
function readExistingVersion(
|
|
1842
|
-
if (!existsSync2(
|
|
1825
|
+
function readExistingVersion(path14) {
|
|
1826
|
+
if (!existsSync2(path14)) return null;
|
|
1843
1827
|
try {
|
|
1844
|
-
const head = readFileSync(
|
|
1828
|
+
const head = readFileSync(path14, "utf8").slice(0, 500);
|
|
1845
1829
|
const match = head.match(VERSION_HEADER_RE);
|
|
1846
1830
|
return match ? match[2] : null;
|
|
1847
1831
|
} catch {
|
|
@@ -3578,7 +3562,7 @@ async function connectionsListCommand(opts) {
|
|
|
3578
3562
|
} else {
|
|
3579
3563
|
const envWidth = Math.max(4, ...catalog.customEnv.map((e) => e.name.length));
|
|
3580
3564
|
for (const e of catalog.customEnv) {
|
|
3581
|
-
console.log(` ${e.name.padEnd(envWidth)} \u25CF set
|
|
3565
|
+
console.log(` ${e.name.padEnd(envWidth)} \u25CF set`);
|
|
3582
3566
|
}
|
|
3583
3567
|
}
|
|
3584
3568
|
}
|
|
@@ -3629,9 +3613,9 @@ async function connectionsConnectCommand(id, opts) {
|
|
|
3629
3613
|
}
|
|
3630
3614
|
|
|
3631
3615
|
// src/commands/workspace.ts
|
|
3632
|
-
import
|
|
3633
|
-
import
|
|
3634
|
-
import { spawnSync } from "child_process";
|
|
3616
|
+
import fs9 from "fs";
|
|
3617
|
+
import path12 from "path";
|
|
3618
|
+
import { spawnSync as spawnSync2 } from "child_process";
|
|
3635
3619
|
|
|
3636
3620
|
// src/commands/git-credential.ts
|
|
3637
3621
|
var GIT_HOST = "api.clawnify.com";
|
|
@@ -3665,8 +3649,606 @@ password=${token}
|
|
|
3665
3649
|
`);
|
|
3666
3650
|
}
|
|
3667
3651
|
|
|
3652
|
+
// src/commands/knowledge.ts
|
|
3653
|
+
import fs8 from "fs";
|
|
3654
|
+
import path11 from "path";
|
|
3655
|
+
|
|
3656
|
+
// src/lib/knowledge-guards.ts
|
|
3657
|
+
import fs7 from "fs";
|
|
3658
|
+
import path10 from "path";
|
|
3659
|
+
import { spawnSync } from "child_process";
|
|
3660
|
+
function git(cwd, args) {
|
|
3661
|
+
return spawnSync("git", args, { cwd, encoding: "utf8" });
|
|
3662
|
+
}
|
|
3663
|
+
function existingAncestor(p) {
|
|
3664
|
+
let cur = path10.resolve(p);
|
|
3665
|
+
while (!fs7.existsSync(cur)) {
|
|
3666
|
+
const parent = path10.dirname(cur);
|
|
3667
|
+
if (parent === cur) break;
|
|
3668
|
+
cur = parent;
|
|
3669
|
+
}
|
|
3670
|
+
return cur;
|
|
3671
|
+
}
|
|
3672
|
+
function dotGitAbove(p) {
|
|
3673
|
+
let cur = existingAncestor(p);
|
|
3674
|
+
for (; ; ) {
|
|
3675
|
+
if (fs7.existsSync(path10.join(cur, ".git"))) return cur;
|
|
3676
|
+
const parent = path10.dirname(cur);
|
|
3677
|
+
if (parent === cur) return null;
|
|
3678
|
+
cur = parent;
|
|
3679
|
+
}
|
|
3680
|
+
}
|
|
3681
|
+
function gitToplevel(p) {
|
|
3682
|
+
const res = git(existingAncestor(p), ["rev-parse", "--show-toplevel"]);
|
|
3683
|
+
if (res.error || res.status !== 0) return null;
|
|
3684
|
+
return res.stdout.trim() || null;
|
|
3685
|
+
}
|
|
3686
|
+
function relativeToTop(top, p) {
|
|
3687
|
+
const abs = path10.resolve(p);
|
|
3688
|
+
const anc = existingAncestor(abs);
|
|
3689
|
+
const real = path10.join(fs7.realpathSync(anc), path10.relative(anc, abs));
|
|
3690
|
+
return path10.relative(fs7.realpathSync(top), real).split(path10.sep).join("/");
|
|
3691
|
+
}
|
|
3692
|
+
function checkGitIgnored(target) {
|
|
3693
|
+
const top = gitToplevel(target);
|
|
3694
|
+
if (!top) {
|
|
3695
|
+
const probe = git(existingAncestor(target), ["--version"]);
|
|
3696
|
+
const repo = probe.error ? dotGitAbove(target) : null;
|
|
3697
|
+
return repo ? { ok: false, message: `it is inside the git repository ${repo}, and git is not installed to check that it ignores the folder. Install git, then pull again.` } : { ok: true };
|
|
3698
|
+
}
|
|
3699
|
+
const rel = relativeToTop(top, target);
|
|
3700
|
+
if (rel === "" || rel.startsWith("..")) {
|
|
3701
|
+
return { ok: false, message: `${target} is the root of the git repository ${top}. Pull into a folder git ignores, such as knowledge/.` };
|
|
3702
|
+
}
|
|
3703
|
+
const tracked = git(top, ["ls-files", "--", `${rel}/`]);
|
|
3704
|
+
if (tracked.error || tracked.status !== 0) {
|
|
3705
|
+
return { ok: false, message: `Could not ask git about ${rel}/: ${tracked.error?.message ?? tracked.stderr.trim()}` };
|
|
3706
|
+
}
|
|
3707
|
+
if (tracked.stdout.trim()) {
|
|
3708
|
+
return {
|
|
3709
|
+
ok: false,
|
|
3710
|
+
message: `${rel}/ holds files committed to git. Knowledge is pulled, never committed.
|
|
3711
|
+
Take them out of git first: git rm -r --cached ${rel} && git commit -m "Stop tracking ${rel}"`
|
|
3712
|
+
};
|
|
3713
|
+
}
|
|
3714
|
+
const ignored = git(top, ["check-ignore", "-q", "--", `${rel}/`]);
|
|
3715
|
+
if (ignored.status === 0) return { ok: true };
|
|
3716
|
+
if (ignored.status === 1) {
|
|
3717
|
+
return {
|
|
3718
|
+
ok: false,
|
|
3719
|
+
message: `${rel}/ is inside the git repository ${top} and git does not ignore it, so the pulled
|
|
3720
|
+
documents could be committed. Add it to .gitignore first:
|
|
3721
|
+
|
|
3722
|
+
echo '${rel}/' >> ${path10.join(top, ".gitignore")}`
|
|
3723
|
+
};
|
|
3724
|
+
}
|
|
3725
|
+
return { ok: false, message: `Could not ask git whether ${rel}/ is ignored: ${ignored.error?.message ?? ignored.stderr.trim()}` };
|
|
3726
|
+
}
|
|
3727
|
+
var CLAWNIFY_GIT_URL = new RegExp(
|
|
3728
|
+
`^https://(?:[^@/]+@)?${GIT_HOST.replace(/\./g, "\\.")}/git/([0-9a-f-]{36})(?:\\.git)?/?$`,
|
|
3729
|
+
"i"
|
|
3730
|
+
);
|
|
3731
|
+
function orgFromGitUrl(url) {
|
|
3732
|
+
return CLAWNIFY_GIT_URL.exec(url.trim())?.[1]?.toLowerCase() ?? null;
|
|
3733
|
+
}
|
|
3734
|
+
function folderBindings(target) {
|
|
3735
|
+
const out = [];
|
|
3736
|
+
const ws = findWorkspaceRoot(target);
|
|
3737
|
+
if (ws) out.push({ source: `${path10.join(ws.dir, "clawnify.json")} (workspace.org)`, org: ws.org });
|
|
3738
|
+
const link = findProjectRoot(target);
|
|
3739
|
+
if (link?.org_id) out.push({ source: ".clawnify/project.json (clawnify link)", org: link.org_id });
|
|
3740
|
+
const top = gitToplevel(target);
|
|
3741
|
+
if (top) {
|
|
3742
|
+
const res = git(top, ["config", "--get-regexp", "^remote\\..*\\.url$"]);
|
|
3743
|
+
for (const line of res.status === 0 ? res.stdout.split("\n") : []) {
|
|
3744
|
+
const [key, url] = line.trim().split(/\s+/, 2);
|
|
3745
|
+
const org = url ? orgFromGitUrl(url) : null;
|
|
3746
|
+
if (key && org) out.push({ source: `git ${key.replace(/\.url$/, "")} (${url})`, org });
|
|
3747
|
+
}
|
|
3748
|
+
}
|
|
3749
|
+
return out;
|
|
3750
|
+
}
|
|
3751
|
+
function conflictingBindings(bindings, org) {
|
|
3752
|
+
return bindings.filter((b) => b.org.toLowerCase() !== org.id.toLowerCase() && b.org !== org.slug);
|
|
3753
|
+
}
|
|
3754
|
+
|
|
3755
|
+
// src/lib/knowledge-plan.ts
|
|
3756
|
+
import { createHash } from "crypto";
|
|
3757
|
+
var MANIFEST_FILE = ".clawnify-knowledge.json";
|
|
3758
|
+
var FORMAT = 1;
|
|
3759
|
+
function sha256(data) {
|
|
3760
|
+
return createHash("sha256").update(data).digest("hex");
|
|
3761
|
+
}
|
|
3762
|
+
function itemKey(item) {
|
|
3763
|
+
return `${item.kind}:${item.id}`;
|
|
3764
|
+
}
|
|
3765
|
+
function slugify3(text, max = 80) {
|
|
3766
|
+
return text.normalize("NFKD").replace(/[̀-ͯ]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, max).replace(/-+$/, "") || "untitled";
|
|
3767
|
+
}
|
|
3768
|
+
function slugifyFolder(folder) {
|
|
3769
|
+
if (!folder) return "";
|
|
3770
|
+
return folder.split("/").map((seg) => slugify3(seg)).filter((seg) => seg !== "untitled").join("/");
|
|
3771
|
+
}
|
|
3772
|
+
function splitFilename(name) {
|
|
3773
|
+
const base = name.split(/[\\/]/).pop() ?? name;
|
|
3774
|
+
const m = /^(.+?)\.([A-Za-z0-9]{1,10})$/.exec(base);
|
|
3775
|
+
if (!m) return { stem: slugify3(base), ext: "" };
|
|
3776
|
+
return { stem: slugify3(m[1]), ext: `.${m[2].toLowerCase()}` };
|
|
3777
|
+
}
|
|
3778
|
+
function join5(dir, name) {
|
|
3779
|
+
return dir ? `${dir}/${name}` : name;
|
|
3780
|
+
}
|
|
3781
|
+
function assignPaths(items, previous) {
|
|
3782
|
+
const prevPath = /* @__PURE__ */ new Map();
|
|
3783
|
+
for (const [p, e] of Object.entries(previous)) prevPath.set(itemKey(e), p);
|
|
3784
|
+
const plain = (it) => join5(it.dir, `${it.stem}${it.ext}`);
|
|
3785
|
+
const short = (it) => join5(it.dir, `${it.stem}-${it.id.slice(0, 8)}${it.ext}`);
|
|
3786
|
+
const out = /* @__PURE__ */ new Map();
|
|
3787
|
+
const taken = /* @__PURE__ */ new Set();
|
|
3788
|
+
for (const it of items) {
|
|
3789
|
+
const p = prevPath.get(itemKey(it));
|
|
3790
|
+
if (p && (p === plain(it) || p === short(it)) && !taken.has(p)) {
|
|
3791
|
+
out.set(itemKey(it), p);
|
|
3792
|
+
taken.add(p);
|
|
3793
|
+
}
|
|
3794
|
+
}
|
|
3795
|
+
const rest = items.filter((it) => !out.has(itemKey(it))).sort((a, b) => itemKey(a) < itemKey(b) ? -1 : 1);
|
|
3796
|
+
for (const it of rest) {
|
|
3797
|
+
let p = plain(it);
|
|
3798
|
+
if (taken.has(p)) p = short(it);
|
|
3799
|
+
if (taken.has(p)) p = join5(it.dir, `${it.stem}-${it.id}${it.ext}`);
|
|
3800
|
+
out.set(itemKey(it), p);
|
|
3801
|
+
taken.add(p);
|
|
3802
|
+
}
|
|
3803
|
+
return out;
|
|
3804
|
+
}
|
|
3805
|
+
function planPull(input) {
|
|
3806
|
+
const previous = input.manifest?.entries ?? {};
|
|
3807
|
+
const sameFormat = input.manifest?.format === FORMAT;
|
|
3808
|
+
const paths = assignPaths(input.listed, previous);
|
|
3809
|
+
const listedKeys = new Set(input.listed.map(itemKey));
|
|
3810
|
+
const claimed = new Set(paths.values());
|
|
3811
|
+
const actions = [];
|
|
3812
|
+
for (const item of input.listed) {
|
|
3813
|
+
const path14 = paths.get(itemKey(item));
|
|
3814
|
+
const entry = previous[path14];
|
|
3815
|
+
const local = input.local(path14);
|
|
3816
|
+
if (local === void 0) {
|
|
3817
|
+
actions.push({ type: "write", path: path14, item, guard: "absent" });
|
|
3818
|
+
} else if (local === "unreadable") {
|
|
3819
|
+
actions.push({ type: "keep", path: path14, reason: "unreadable", gone: false });
|
|
3820
|
+
} else if (!entry) {
|
|
3821
|
+
actions.push({ type: "write", path: path14, item, guard: "unowned" });
|
|
3822
|
+
} else {
|
|
3823
|
+
const current = sameFormat && entry.id === item.id && entry.kind === item.kind && entry.edit_revision === item.edit_revision;
|
|
3824
|
+
if (local !== entry.sha256) {
|
|
3825
|
+
actions.push(current ? { type: "keep", path: path14, reason: "edited", gone: false } : { type: "write", path: path14, item, guard: "edited" });
|
|
3826
|
+
} else {
|
|
3827
|
+
actions.push(current ? { type: "skip", path: path14, item } : { type: "write", path: path14, item, guard: "owned" });
|
|
3828
|
+
}
|
|
3829
|
+
}
|
|
3830
|
+
}
|
|
3831
|
+
for (const [path14, entry] of Object.entries(previous)) {
|
|
3832
|
+
if (claimed.has(path14)) continue;
|
|
3833
|
+
const local = input.local(path14);
|
|
3834
|
+
const because = !input.inScope(entry.kind) ? "out_of_scope" : listedKeys.has(itemKey(entry)) ? "moved" : "unlisted";
|
|
3835
|
+
if (local === void 0) actions.push({ type: "forget", path: path14 });
|
|
3836
|
+
else if (local === "unreadable") actions.push({ type: "keep", path: path14, reason: "unreadable", gone: true });
|
|
3837
|
+
else if (local !== entry.sha256) actions.push({ type: "keep", path: path14, reason: "edited", gone: true });
|
|
3838
|
+
else actions.push({ type: "remove", path: path14, entry, because });
|
|
3839
|
+
}
|
|
3840
|
+
return actions;
|
|
3841
|
+
}
|
|
3842
|
+
function renderDoc(doc, body) {
|
|
3843
|
+
const text = body.endsWith("\n") || body === "" ? body : `${body}
|
|
3844
|
+
`;
|
|
3845
|
+
const lines = [
|
|
3846
|
+
"---",
|
|
3847
|
+
"# A local copy pulled by `clawnify knowledge pull`. Edits here are not sent to",
|
|
3848
|
+
"# Clawnify, and the next pull leaves an edited file as it is. Change the",
|
|
3849
|
+
"# document in Clawnify instead.",
|
|
3850
|
+
`id: ${doc.id}`,
|
|
3851
|
+
`title: ${JSON.stringify(doc.title)}`
|
|
3852
|
+
];
|
|
3853
|
+
if (doc.description) lines.push(`description: ${JSON.stringify(doc.description)}`);
|
|
3854
|
+
lines.push(`type: ${JSON.stringify(doc.doc_type)}`);
|
|
3855
|
+
lines.push(`version: ${doc.version}`);
|
|
3856
|
+
lines.push(`edit_revision: ${doc.edit_revision}`);
|
|
3857
|
+
if (doc.folder) lines.push(`folder: ${JSON.stringify(doc.folder)}`);
|
|
3858
|
+
if (doc.tags && doc.tags.length > 0) lines.push(`tags: ${JSON.stringify(doc.tags)}`);
|
|
3859
|
+
if (doc.review_state) lines.push(`review_state: ${JSON.stringify(doc.review_state)}`);
|
|
3860
|
+
if (doc.published_at) lines.push(`published_at: ${JSON.stringify(doc.published_at)}`);
|
|
3861
|
+
lines.push(`body_sha256: ${sha256(text)}`);
|
|
3862
|
+
lines.push("---", "");
|
|
3863
|
+
return `${lines.join("\n")}${text}`;
|
|
3864
|
+
}
|
|
3865
|
+
function docItem(doc) {
|
|
3866
|
+
return {
|
|
3867
|
+
id: doc.id,
|
|
3868
|
+
kind: "doc",
|
|
3869
|
+
edit_revision: doc.edit_revision,
|
|
3870
|
+
dir: slugifyFolder(doc.folder),
|
|
3871
|
+
stem: slugify3(doc.title),
|
|
3872
|
+
ext: ".md"
|
|
3873
|
+
};
|
|
3874
|
+
}
|
|
3875
|
+
function fileItem(doc) {
|
|
3876
|
+
const { stem, ext } = splitFilename(doc.source?.note || doc.title || "file");
|
|
3877
|
+
const folder = slugifyFolder(doc.folder);
|
|
3878
|
+
return {
|
|
3879
|
+
id: doc.id,
|
|
3880
|
+
kind: "file",
|
|
3881
|
+
edit_revision: doc.edit_revision,
|
|
3882
|
+
dir: folder ? `files/${folder}` : "files",
|
|
3883
|
+
stem,
|
|
3884
|
+
ext
|
|
3885
|
+
};
|
|
3886
|
+
}
|
|
3887
|
+
|
|
3888
|
+
// src/commands/knowledge.ts
|
|
3889
|
+
var LEAN_PAGE = 500;
|
|
3890
|
+
var FULL_PAGE = 100;
|
|
3891
|
+
var CONCURRENCY = 6;
|
|
3892
|
+
var SAVE_EVERY_MS = 250;
|
|
3893
|
+
var ORIGINAL_PREFIX = "knowledge/files/";
|
|
3894
|
+
async function readJson(res) {
|
|
3895
|
+
try {
|
|
3896
|
+
return await res.json();
|
|
3897
|
+
} catch {
|
|
3898
|
+
return null;
|
|
3899
|
+
}
|
|
3900
|
+
}
|
|
3901
|
+
async function listCompanyDocs(orgId, lean) {
|
|
3902
|
+
const page = lean ? LEAN_PAGE : FULL_PAGE;
|
|
3903
|
+
const seen = /* @__PURE__ */ new Map();
|
|
3904
|
+
for (let offset = 0; ; offset += page) {
|
|
3905
|
+
const res = await api.get(
|
|
3906
|
+
`/v1/knowledge?status=published${lean ? "&fields=sync" : ""}&limit=${page}&offset=${offset}`,
|
|
3907
|
+
{ orgId }
|
|
3908
|
+
);
|
|
3909
|
+
const body = res.ok ? await readJson(res) : null;
|
|
3910
|
+
if (!body?.documents) return `Could not list documents (HTTP ${res.status}).`;
|
|
3911
|
+
let fresh = 0;
|
|
3912
|
+
for (const d of body.documents) {
|
|
3913
|
+
if (seen.has(d.id)) continue;
|
|
3914
|
+
seen.set(d.id, d);
|
|
3915
|
+
fresh++;
|
|
3916
|
+
}
|
|
3917
|
+
if (body.documents.length < page || fresh === 0) break;
|
|
3918
|
+
}
|
|
3919
|
+
return [...seen.values()].filter((d) => d.status === "published" && d.project_id === null);
|
|
3920
|
+
}
|
|
3921
|
+
async function listProjectSources(orgId, projectId, lean) {
|
|
3922
|
+
const res = await api.get(
|
|
3923
|
+
`/v1/knowledge/projects/${encodeURIComponent(projectId)}/sources${lean ? "?fields=sync" : ""}`,
|
|
3924
|
+
{ orgId }
|
|
3925
|
+
);
|
|
3926
|
+
const body = res.ok ? await readJson(res) : null;
|
|
3927
|
+
if (!body?.sources) return `Could not list the Project's sources (HTTP ${res.status}).`;
|
|
3928
|
+
return body.sources.filter((s) => s.status === "published");
|
|
3929
|
+
}
|
|
3930
|
+
async function listBodies(orgId, scope) {
|
|
3931
|
+
const docs = scope === "company" ? await listCompanyDocs(orgId, false) : await listProjectSources(orgId, scope.slice("project:".length), false);
|
|
3932
|
+
return new Map(typeof docs === "string" ? [] : docs.map((d) => [d.id, d]));
|
|
3933
|
+
}
|
|
3934
|
+
var hasOriginal = (d) => d.source?.kind === "upload" && typeof d.source.ref === "string" && d.source.ref.startsWith(ORIGINAL_PREFIX);
|
|
3935
|
+
async function listItems(orgId, scope, withFiles) {
|
|
3936
|
+
if (scope === "company") {
|
|
3937
|
+
const docs2 = await listCompanyDocs(orgId, true);
|
|
3938
|
+
if (typeof docs2 === "string") return { ok: false, error: docs2 };
|
|
3939
|
+
if (!withFiles) return { ok: true, docs: docs2, files: [], filesProjectId: null };
|
|
3940
|
+
const res = await api.get("/v1/knowledge/company-files?fields=sync", { orgId });
|
|
3941
|
+
const body = res.ok ? await readJson(res) : null;
|
|
3942
|
+
if (!body?.sources) return { ok: false, error: `Could not list Company files (HTTP ${res.status}).` };
|
|
3943
|
+
const files = body.sources.filter((s) => s.status === "published" && hasOriginal(s));
|
|
3944
|
+
return { ok: true, docs: docs2, files, filesProjectId: body.project?.id ?? null };
|
|
3945
|
+
}
|
|
3946
|
+
const projectId = scope.slice("project:".length);
|
|
3947
|
+
const docs = await listProjectSources(orgId, projectId, true);
|
|
3948
|
+
if (typeof docs === "string") return { ok: false, error: docs };
|
|
3949
|
+
return { ok: true, docs, files: withFiles ? docs.filter(hasOriginal) : [], filesProjectId: projectId };
|
|
3950
|
+
}
|
|
3951
|
+
async function fetchContent(orgId, item, withBody) {
|
|
3952
|
+
const enc = new TextEncoder();
|
|
3953
|
+
if (item.kind === "file") {
|
|
3954
|
+
const res2 = await api.get(`/v1/knowledge/company-files/${encodeURIComponent(item.id)}/original`, { orgId });
|
|
3955
|
+
if (!res2.ok) return { error: `HTTP ${res2.status} fetching the original` };
|
|
3956
|
+
return { bytes: new Uint8Array(await res2.arrayBuffer()), edit_revision: item.edit_revision };
|
|
3957
|
+
}
|
|
3958
|
+
if (withBody && withBody.content_uri == null && typeof withBody.content === "string") {
|
|
3959
|
+
return { bytes: enc.encode(renderDoc(withBody, withBody.content)), edit_revision: withBody.edit_revision };
|
|
3960
|
+
}
|
|
3961
|
+
const res = await api.get(`/v1/knowledge/${encodeURIComponent(item.id)}`, { orgId });
|
|
3962
|
+
const body = res.ok ? await readJson(res) : null;
|
|
3963
|
+
if (!body?.document) return { error: `HTTP ${res.status} fetching the document` };
|
|
3964
|
+
return { bytes: enc.encode(renderDoc(body.document, body.document.content ?? "")), edit_revision: body.document.edit_revision };
|
|
3965
|
+
}
|
|
3966
|
+
async function confirmGone(orgId, entry, scope, filesProjectId) {
|
|
3967
|
+
const res = await api.get(`/v1/knowledge/${encodeURIComponent(entry.id)}`, { orgId });
|
|
3968
|
+
if (res.status === 404) return true;
|
|
3969
|
+
const body = res.ok ? await readJson(res) : null;
|
|
3970
|
+
if (!body?.document) return false;
|
|
3971
|
+
const d = body.document;
|
|
3972
|
+
if (d.status !== "published") return true;
|
|
3973
|
+
if (scope === "company" && entry.kind === "doc") return d.project_id !== null;
|
|
3974
|
+
return filesProjectId !== null && d.project_id !== filesProjectId;
|
|
3975
|
+
}
|
|
3976
|
+
function hashLocal(target, rel) {
|
|
3977
|
+
const abs = path11.join(target, ...rel.split("/"));
|
|
3978
|
+
try {
|
|
3979
|
+
if (!fs8.lstatSync(abs).isFile()) return "unreadable";
|
|
3980
|
+
return sha256(fs8.readFileSync(abs));
|
|
3981
|
+
} catch (err) {
|
|
3982
|
+
return err.code === "ENOENT" ? void 0 : "unreadable";
|
|
3983
|
+
}
|
|
3984
|
+
}
|
|
3985
|
+
function writeAtomic(file, data) {
|
|
3986
|
+
fs8.mkdirSync(path11.dirname(file), { recursive: true });
|
|
3987
|
+
const tmp = path11.join(path11.dirname(file), `.${path11.basename(file)}.${process.pid}.tmp`);
|
|
3988
|
+
fs8.writeFileSync(tmp, data);
|
|
3989
|
+
fs8.renameSync(tmp, file);
|
|
3990
|
+
}
|
|
3991
|
+
function pruneEmptyDirs(file, target) {
|
|
3992
|
+
let dir = path11.dirname(file);
|
|
3993
|
+
while (dir.startsWith(target + path11.sep)) {
|
|
3994
|
+
try {
|
|
3995
|
+
fs8.rmdirSync(dir);
|
|
3996
|
+
} catch {
|
|
3997
|
+
return;
|
|
3998
|
+
}
|
|
3999
|
+
dir = path11.dirname(dir);
|
|
4000
|
+
}
|
|
4001
|
+
}
|
|
4002
|
+
async function pool(items, size, run) {
|
|
4003
|
+
let next = 0;
|
|
4004
|
+
const workers = Array.from({ length: Math.min(size, items.length) }, async () => {
|
|
4005
|
+
while (next < items.length) await run(items[next++]);
|
|
4006
|
+
});
|
|
4007
|
+
await Promise.all(workers);
|
|
4008
|
+
}
|
|
4009
|
+
function readManifest2(file) {
|
|
4010
|
+
let text;
|
|
4011
|
+
try {
|
|
4012
|
+
text = fs8.readFileSync(file, "utf8");
|
|
4013
|
+
} catch {
|
|
4014
|
+
return null;
|
|
4015
|
+
}
|
|
4016
|
+
try {
|
|
4017
|
+
const m = JSON.parse(text);
|
|
4018
|
+
if (typeof m.org_id !== "string" || typeof m.scope !== "string" || typeof m.entries !== "object" || !m.entries) {
|
|
4019
|
+
return "corrupt";
|
|
4020
|
+
}
|
|
4021
|
+
return m;
|
|
4022
|
+
} catch {
|
|
4023
|
+
return "corrupt";
|
|
4024
|
+
}
|
|
4025
|
+
}
|
|
4026
|
+
async function resolvePullOrg(flag, bindings) {
|
|
4027
|
+
const orgs = await listMyOrgs();
|
|
4028
|
+
if (orgs.length === 0) return "No organizations on your account. Run `clawnify login` first.";
|
|
4029
|
+
const find = (ref) => orgs.find((o) => o.id.toLowerCase() === ref.toLowerCase() || o.slug === ref);
|
|
4030
|
+
const available = `Available: ${orgs.map((o) => o.slug).join(", ")}`;
|
|
4031
|
+
if (flag) return find(flag) ?? `No org matched "${flag}". ${available}`;
|
|
4032
|
+
const env = process.env.CLAWNIFY_ORG_ID;
|
|
4033
|
+
if (env) return find(env) ?? `CLAWNIFY_ORG_ID="${env}" matches none of your orgs. ${available}`;
|
|
4034
|
+
const bound = bindings[0];
|
|
4035
|
+
if (bound) {
|
|
4036
|
+
return find(bound.org) ?? `This folder belongs to the org "${bound.org}" (${bound.source}), and your login is not a member of it.`;
|
|
4037
|
+
}
|
|
4038
|
+
if (orgs.length === 1) return orgs[0];
|
|
4039
|
+
return `Several orgs, and this folder is bound to none: pick one with --org <slug>. ${available}`;
|
|
4040
|
+
}
|
|
4041
|
+
function shown(abs) {
|
|
4042
|
+
return path11.relative(process.cwd(), abs) || ".";
|
|
4043
|
+
}
|
|
4044
|
+
async function pullKnowledge(dir, opts) {
|
|
4045
|
+
const out = (line) => {
|
|
4046
|
+
if (!opts.quiet) console.log(line);
|
|
4047
|
+
};
|
|
4048
|
+
const fail = (line) => {
|
|
4049
|
+
console.error(line);
|
|
4050
|
+
return 1;
|
|
4051
|
+
};
|
|
4052
|
+
if (!await getValidToken()) {
|
|
4053
|
+
return fail("Not logged in. Run `npx clawnify@latest login`, then `clawnify knowledge pull` again.");
|
|
4054
|
+
}
|
|
4055
|
+
const root = findWorkspaceRoot()?.dir ?? gitToplevel(process.cwd()) ?? process.cwd();
|
|
4056
|
+
const base = dir ? path11.resolve(dir) : path11.join(root, "knowledge");
|
|
4057
|
+
const bindings = folderBindings(base);
|
|
4058
|
+
const baseManifestPath = path11.join(base, MANIFEST_FILE);
|
|
4059
|
+
const baseManifest = readManifest2(baseManifestPath);
|
|
4060
|
+
if (baseManifest === "corrupt") {
|
|
4061
|
+
return fail(`Could not read ${shown(baseManifestPath)}. Nothing changed. Delete ${shown(base)} to pull it fresh.`);
|
|
4062
|
+
}
|
|
4063
|
+
if (baseManifest) bindings.push({ source: shown(baseManifestPath), org: baseManifest.org_id });
|
|
4064
|
+
const org = opts.resolvedOrg ?? await resolvePullOrg(opts.org, bindings);
|
|
4065
|
+
if (typeof org === "string") return fail(org);
|
|
4066
|
+
let scope = "company";
|
|
4067
|
+
let target = base;
|
|
4068
|
+
let what = `${org.name}'s Company Knowledge`;
|
|
4069
|
+
if (opts.project) {
|
|
4070
|
+
const res = await api.get("/v1/knowledge/projects", { orgId: org.id });
|
|
4071
|
+
const body = res.ok ? await readJson(res) : null;
|
|
4072
|
+
if (!body?.projects) return fail(`Could not list ${org.name}'s Projects (HTTP ${res.status}). Nothing changed.`);
|
|
4073
|
+
const project = body.projects.find((p) => p.id === opts.project);
|
|
4074
|
+
if (!project) {
|
|
4075
|
+
const list = body.projects.map((p) => ` ${p.id} ${p.name}`).join("\n");
|
|
4076
|
+
return fail(`${org.name} has no Project ${opts.project}.${list ? ` Its Projects:
|
|
4077
|
+
${list}` : " It has no Projects."}`);
|
|
4078
|
+
}
|
|
4079
|
+
scope = `project:${project.id}`;
|
|
4080
|
+
what = `the ${project.name} Project`;
|
|
4081
|
+
if (!dir) target = path11.join(base, "projects", slugify3(project.name));
|
|
4082
|
+
}
|
|
4083
|
+
const manifestPath = path11.join(target, MANIFEST_FILE);
|
|
4084
|
+
const manifest = target === base ? baseManifest : readManifest2(manifestPath);
|
|
4085
|
+
if (manifest === "corrupt") {
|
|
4086
|
+
return fail(`Could not read ${shown(manifestPath)}. Nothing changed. Delete ${shown(target)} to pull it fresh.`);
|
|
4087
|
+
}
|
|
4088
|
+
if (manifest) {
|
|
4089
|
+
if (target !== base) bindings.push({ source: shown(manifestPath), org: manifest.org_id });
|
|
4090
|
+
if (manifest.scope !== scope) {
|
|
4091
|
+
const held = manifest.scope === "company" ? "Company Knowledge" : `Project ${manifest.scope.slice("project:".length)}`;
|
|
4092
|
+
return fail(`${shown(target)} holds ${held} from an earlier pull. Pull ${what} into another folder.`);
|
|
4093
|
+
}
|
|
4094
|
+
}
|
|
4095
|
+
const conflicts = conflictingBindings(bindings, org);
|
|
4096
|
+
if (conflicts.length > 0) {
|
|
4097
|
+
return fail(
|
|
4098
|
+
`Refusing to pull ${org.name} (${org.slug}) into ${shown(target)}: the folder belongs to another org.
|
|
4099
|
+
` + conflicts.map((b) => ` ${b.source} names ${b.org}`).join("\n")
|
|
4100
|
+
);
|
|
4101
|
+
}
|
|
4102
|
+
const ignored = checkGitIgnored(target);
|
|
4103
|
+
if (!ignored.ok) return fail(`Refusing to pull into ${shown(target)}: ${ignored.message}`);
|
|
4104
|
+
const withFiles = opts.files ?? manifest?.files ?? false;
|
|
4105
|
+
const listing = await listItems(org.id, scope, withFiles);
|
|
4106
|
+
if (!listing.ok) return fail(`${listing.error} Nothing changed.`);
|
|
4107
|
+
const sources = /* @__PURE__ */ new Map();
|
|
4108
|
+
for (const doc of listing.docs) {
|
|
4109
|
+
const item = docItem(doc);
|
|
4110
|
+
sources.set(itemKey(item), { item, doc });
|
|
4111
|
+
}
|
|
4112
|
+
for (const doc of listing.files) {
|
|
4113
|
+
const item = fileItem(doc);
|
|
4114
|
+
sources.set(itemKey(item), { item, doc });
|
|
4115
|
+
}
|
|
4116
|
+
const actions = planPull({
|
|
4117
|
+
listed: [...sources.values()].map((s) => s.item),
|
|
4118
|
+
manifest,
|
|
4119
|
+
local: (rel) => hashLocal(target, rel),
|
|
4120
|
+
inScope: (kind) => kind === "doc" || withFiles
|
|
4121
|
+
});
|
|
4122
|
+
const next = {
|
|
4123
|
+
format: manifest?.format ?? FORMAT,
|
|
4124
|
+
org_id: org.id,
|
|
4125
|
+
scope,
|
|
4126
|
+
files: withFiles,
|
|
4127
|
+
entries: { ...manifest?.entries ?? {} }
|
|
4128
|
+
};
|
|
4129
|
+
let savedAt = 0;
|
|
4130
|
+
const save = (now = false) => {
|
|
4131
|
+
if (!now && Date.now() - savedAt < SAVE_EVERY_MS) return;
|
|
4132
|
+
savedAt = Date.now();
|
|
4133
|
+
writeAtomic(manifestPath, `${JSON.stringify(next, null, 2)}
|
|
4134
|
+
`);
|
|
4135
|
+
};
|
|
4136
|
+
fs8.mkdirSync(target, { recursive: true });
|
|
4137
|
+
save(true);
|
|
4138
|
+
const abs = (rel) => path11.join(target, ...rel.split("/"));
|
|
4139
|
+
const onDisk = /* @__PURE__ */ new Set();
|
|
4140
|
+
let written = 0;
|
|
4141
|
+
let unchanged = 0;
|
|
4142
|
+
let removed = 0;
|
|
4143
|
+
const edited = [];
|
|
4144
|
+
const editedGone = [];
|
|
4145
|
+
const unreadable = [];
|
|
4146
|
+
const notOurs = [];
|
|
4147
|
+
const failed = [];
|
|
4148
|
+
for (const a of actions) {
|
|
4149
|
+
if (a.type === "skip") {
|
|
4150
|
+
onDisk.add(itemKey(a.item));
|
|
4151
|
+
unchanged++;
|
|
4152
|
+
} else if (a.type === "keep") {
|
|
4153
|
+
const list = a.reason === "unreadable" ? unreadable : a.gone ? editedGone : edited;
|
|
4154
|
+
list.push(shown(abs(a.path)));
|
|
4155
|
+
} else if (a.type === "forget") {
|
|
4156
|
+
delete next.entries[a.path];
|
|
4157
|
+
}
|
|
4158
|
+
}
|
|
4159
|
+
const writes = actions.filter((a) => a.type === "write");
|
|
4160
|
+
const docWrites = writes.filter((a) => a.item.kind === "doc").length;
|
|
4161
|
+
const bodies = docWrites > 10 && docWrites * 4 > listing.docs.length ? await listBodies(org.id, scope) : /* @__PURE__ */ new Map();
|
|
4162
|
+
await pool(writes, CONCURRENCY, async (a) => {
|
|
4163
|
+
const file = abs(a.path);
|
|
4164
|
+
const got = await fetchContent(org.id, a.item, bodies.get(a.item.id) ?? sources.get(itemKey(a.item)).doc);
|
|
4165
|
+
if ("error" in got) {
|
|
4166
|
+
failed.push(`${shown(file)}: ${got.error}`);
|
|
4167
|
+
return;
|
|
4168
|
+
}
|
|
4169
|
+
const hash = sha256(got.bytes);
|
|
4170
|
+
const now = hashLocal(target, a.path);
|
|
4171
|
+
const owned = next.entries[a.path];
|
|
4172
|
+
const entry = { id: a.item.id, kind: a.item.kind, edit_revision: got.edit_revision, sha256: hash };
|
|
4173
|
+
if (now === hash) {
|
|
4174
|
+
next.entries[a.path] = entry;
|
|
4175
|
+
unchanged++;
|
|
4176
|
+
} else if (now === void 0 || owned && now === owned.sha256) {
|
|
4177
|
+
try {
|
|
4178
|
+
writeAtomic(file, got.bytes);
|
|
4179
|
+
} catch (err) {
|
|
4180
|
+
failed.push(`${shown(file)}: ${err.message}`);
|
|
4181
|
+
return;
|
|
4182
|
+
}
|
|
4183
|
+
next.entries[a.path] = entry;
|
|
4184
|
+
written++;
|
|
4185
|
+
} else {
|
|
4186
|
+
(owned ? edited : notOurs).push(shown(file));
|
|
4187
|
+
return;
|
|
4188
|
+
}
|
|
4189
|
+
onDisk.add(itemKey(a.item));
|
|
4190
|
+
save();
|
|
4191
|
+
});
|
|
4192
|
+
const removals = actions.filter((a) => a.type === "remove");
|
|
4193
|
+
await pool(removals, CONCURRENCY, async (a) => {
|
|
4194
|
+
if (a.because === "moved" && !onDisk.has(itemKey(a.entry))) return;
|
|
4195
|
+
if (a.because === "unlisted" && !await confirmGone(org.id, a.entry, scope, listing.filesProjectId)) return;
|
|
4196
|
+
const file = abs(a.path);
|
|
4197
|
+
const now = hashLocal(target, a.path);
|
|
4198
|
+
if (now !== void 0 && now !== a.entry.sha256) {
|
|
4199
|
+
editedGone.push(shown(file));
|
|
4200
|
+
return;
|
|
4201
|
+
}
|
|
4202
|
+
try {
|
|
4203
|
+
if (now !== void 0) fs8.unlinkSync(file);
|
|
4204
|
+
} catch (err) {
|
|
4205
|
+
if (err.code !== "ENOENT") {
|
|
4206
|
+
failed.push(`${shown(file)}: ${err.message}`);
|
|
4207
|
+
return;
|
|
4208
|
+
}
|
|
4209
|
+
}
|
|
4210
|
+
delete next.entries[a.path];
|
|
4211
|
+
removed++;
|
|
4212
|
+
save();
|
|
4213
|
+
pruneEmptyDirs(file, target);
|
|
4214
|
+
});
|
|
4215
|
+
if (failed.length === 0) next.format = FORMAT;
|
|
4216
|
+
save(true);
|
|
4217
|
+
const counts = [
|
|
4218
|
+
`${listing.docs.length} document${listing.docs.length === 1 ? "" : "s"}`,
|
|
4219
|
+
...withFiles ? [`${listing.files.length} file${listing.files.length === 1 ? "" : "s"}`] : []
|
|
4220
|
+
].join(", ");
|
|
4221
|
+
out(`Pulled ${what} (${org.slug}) into ${shown(target)}/: ${counts}. ${written} written, ${unchanged} unchanged, ${removed} removed.`);
|
|
4222
|
+
if (listing.docs.length === 0 && listing.files.length === 0) out(` ${org.name} has nothing published here yet.`);
|
|
4223
|
+
const report = (lines, head, tail) => {
|
|
4224
|
+
if (lines.length === 0) return;
|
|
4225
|
+
console.error(`${head}
|
|
4226
|
+
${lines.sort().map((l) => ` ${l}`).join("\n")}${tail ? `
|
|
4227
|
+
${tail}` : ""}`);
|
|
4228
|
+
};
|
|
4229
|
+
report(
|
|
4230
|
+
edited,
|
|
4231
|
+
`Left ${edited.length} file${edited.length === 1 ? "" : "s"} as ${edited.length === 1 ? "it is" : "they are"}: changed since the last pull, so not updated.`,
|
|
4232
|
+
"Edits here are not sent to Clawnify. Change the document in Clawnify, then delete the file to get the current version on the next pull."
|
|
4233
|
+
);
|
|
4234
|
+
report(
|
|
4235
|
+
editedGone,
|
|
4236
|
+
`Left ${editedGone.length} file${editedGone.length === 1 ? "" : "s"} changed since the last pull whose document is no longer published here.`,
|
|
4237
|
+
"Delete them once you no longer need them."
|
|
4238
|
+
);
|
|
4239
|
+
report(unreadable, "Left files the pull could not read:");
|
|
4240
|
+
report(notOurs, "Left files the pull did not write, at paths a document wants:", "Move them away and pull again to get those documents.");
|
|
4241
|
+
report(failed, `Could not fetch ${failed.length}; ${failed.length === 1 ? "it stays" : "they stay"} as before and the next pull tries again:`);
|
|
4242
|
+
if (failed.length > 0) return 1;
|
|
4243
|
+
if (opts.strict && edited.length + editedGone.length + unreadable.length + notOurs.length > 0) return 1;
|
|
4244
|
+
return 0;
|
|
4245
|
+
}
|
|
4246
|
+
async function knowledgePullCommand(dir, opts) {
|
|
4247
|
+
process.exitCode = await pullKnowledge(dir, opts);
|
|
4248
|
+
}
|
|
4249
|
+
|
|
3668
4250
|
// src/commands/workspace.ts
|
|
3669
|
-
function
|
|
4251
|
+
function slugify4(name) {
|
|
3670
4252
|
return name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 30);
|
|
3671
4253
|
}
|
|
3672
4254
|
async function resolveOrg(opts) {
|
|
@@ -3696,15 +4278,15 @@ async function resolveOrg(opts) {
|
|
|
3696
4278
|
process.exit(1);
|
|
3697
4279
|
}
|
|
3698
4280
|
function write2(dir, file, content) {
|
|
3699
|
-
const fullPath =
|
|
3700
|
-
|
|
3701
|
-
|
|
4281
|
+
const fullPath = path12.join(dir, file);
|
|
4282
|
+
fs9.mkdirSync(path12.dirname(fullPath), { recursive: true });
|
|
4283
|
+
fs9.writeFileSync(fullPath, content);
|
|
3702
4284
|
}
|
|
3703
4285
|
async function workspaceInitCommand(dir, opts) {
|
|
3704
4286
|
const org = await resolveOrg(opts);
|
|
3705
4287
|
const name = opts?.name || org.name;
|
|
3706
|
-
const targetDir = dir ?
|
|
3707
|
-
if (
|
|
4288
|
+
const targetDir = dir ? path12.resolve(dir) : path12.resolve(slugify4(org.slug));
|
|
4289
|
+
if (fs9.existsSync(targetDir) && fs9.readdirSync(targetDir).length > 0) {
|
|
3708
4290
|
console.error(`Directory ${targetDir} is not empty.`);
|
|
3709
4291
|
process.exit(1);
|
|
3710
4292
|
}
|
|
@@ -3719,7 +4301,7 @@ async function workspaceInitCommand(dir, opts) {
|
|
|
3719
4301
|
- "website"
|
|
3720
4302
|
`);
|
|
3721
4303
|
write2(targetDir, "package.json", JSON.stringify({
|
|
3722
|
-
name:
|
|
4304
|
+
name: slugify4(org.slug),
|
|
3723
4305
|
private: true,
|
|
3724
4306
|
type: "module"
|
|
3725
4307
|
}, null, 2));
|
|
@@ -3775,7 +4357,7 @@ back under the same subdirs. See \`docs/internal/adr-company-monorepo.md\` \xA7
|
|
|
3775
4357
|
write2(targetDir, "apps/.gitkeep", "");
|
|
3776
4358
|
write2(targetDir, "agents/.gitkeep", "");
|
|
3777
4359
|
write2(targetDir, "website/.gitkeep", "");
|
|
3778
|
-
const rel =
|
|
4360
|
+
const rel = path12.relative(process.cwd(), targetDir) || ".";
|
|
3779
4361
|
console.log();
|
|
3780
4362
|
console.log(` Created workspace for ${org.name} (${org.slug}) in ${rel}/`);
|
|
3781
4363
|
console.log();
|
|
@@ -3801,12 +4383,16 @@ var WORKSPACE_GUIDE = `How editing works:
|
|
|
3801
4383
|
localhost:4321). Do NOT use \`clawnify dev\` for the website \u2014 it is
|
|
3802
4384
|
for apps only. Reuse the existing components/blocks under src/.
|
|
3803
4385
|
- Apps: cd apps/<slug> && clawnify dev.
|
|
3804
|
-
- Website deploys (via push or \`clawnify deploy\` from website/)
|
|
3805
|
-
|
|
3806
|
-
|
|
3807
|
-
|
|
4386
|
+
- Website deploys (via push or \`clawnify deploy\` from website/) go
|
|
4387
|
+
live. If the site has unpublished changes from the chat, the deploy
|
|
4388
|
+
joins them on the DRAFT site (<slug>.draft-site.clawnify.com) instead,
|
|
4389
|
+
and "Publish" in the dashboard ships both. Tell the user which happened.
|
|
3808
4390
|
- NEVER commit .env files or .clawnify/ folders \u2014 they hold secrets.
|
|
3809
4391
|
Never commit or echo tokens found in them.
|
|
4392
|
+
- knowledge/ (git-ignored) holds the org's published Company Knowledge
|
|
4393
|
+
as markdown: read it for specs and facts. \`clawnify knowledge pull\`
|
|
4394
|
+
refreshes it (a clone does on each git pull). Edits there are not sent
|
|
4395
|
+
back: change a document in Clawnify.
|
|
3810
4396
|
- Run \`clawnify ai-files install\` in the repo once: it installs
|
|
3811
4397
|
Clawnify rules, skills, and MCP access for coding agents.
|
|
3812
4398
|
- Per-app deep docs: \`clawnify docs <app-slug>\`.`;
|
|
@@ -3843,14 +4429,14 @@ ${WORKSPACE_GUIDE}`);
|
|
|
3843
4429
|
}
|
|
3844
4430
|
console.log(`Org: ${data.org_id}`);
|
|
3845
4431
|
if (state.git) {
|
|
3846
|
-
const
|
|
4432
|
+
const git2 = state.git;
|
|
3847
4433
|
console.log(`
|
|
3848
4434
|
Workspace repo: Clawnify git`);
|
|
3849
4435
|
console.log(` Clone: npx clawnify@latest workspace clone`);
|
|
3850
|
-
console.log(` Remote: ${
|
|
3851
|
-
for (const f of
|
|
4436
|
+
console.log(` Remote: ${git2.url} (git signs in with your Clawnify login)`);
|
|
4437
|
+
for (const f of git2.folders) console.log(` ${(f.subdir || "(root)").padEnd(28)} ${targetLabel(f.target)}`);
|
|
3852
4438
|
console.log(
|
|
3853
|
-
|
|
4439
|
+
git2.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
4440
|
);
|
|
3855
4441
|
console.log(` Cloned some other way? Inside the clone, run:
|
|
3856
4442
|
git config --replace-all credential.https://${GIT_HOST}.helper ''
|
|
@@ -3925,9 +4511,9 @@ async function workspaceCloneCommand(dir, opts) {
|
|
|
3925
4511
|
);
|
|
3926
4512
|
process.exit(1);
|
|
3927
4513
|
}
|
|
3928
|
-
const target = dir ??
|
|
4514
|
+
const target = dir ?? slugify4(org.slug);
|
|
3929
4515
|
const key = `credential.https://${GIT_HOST}.helper`;
|
|
3930
|
-
const clone =
|
|
4516
|
+
const clone = spawnSync2("git", ["clone", "-c", `${key}=`, "-c", `${key}=${GIT_HELPER}`, state.git.url, target], { stdio: "inherit" });
|
|
3931
4517
|
if (clone.error) {
|
|
3932
4518
|
console.error(`Could not run git: ${clone.error.message}`);
|
|
3933
4519
|
process.exit(1);
|
|
@@ -3936,9 +4522,67 @@ async function workspaceCloneCommand(dir, opts) {
|
|
|
3936
4522
|
console.log(`
|
|
3937
4523
|
Cloned ${org.name} into ${target}/. git pull and git push sign in with your
|
|
3938
4524
|
Clawnify login.${state.git.can_push ? "" : " You can pull; pushing needs an owner or admin."}
|
|
3939
|
-
|
|
4525
|
+
`);
|
|
4526
|
+
const repoDir = path12.resolve(target);
|
|
4527
|
+
console.log(` ${ignoreKnowledge(repoDir)}`);
|
|
4528
|
+
const pulled = await pullKnowledge(path12.join(repoDir, "knowledge"), { resolvedOrg: org });
|
|
4529
|
+
console.log(` ${installKnowledgeHook(repoDir)}`);
|
|
4530
|
+
if (pulled !== 0) {
|
|
4531
|
+
console.log(" The clone is fine; run `clawnify knowledge pull` in it to try the knowledge again.");
|
|
4532
|
+
}
|
|
4533
|
+
console.log(`
|
|
3940
4534
|
Run \`clawnify workspace\` in it for what maps where and how editing works.`);
|
|
3941
4535
|
}
|
|
4536
|
+
var KNOWLEDGE_IGNORE = "knowledge/";
|
|
4537
|
+
var HOOK_MARK = "clawnify knowledge pull";
|
|
4538
|
+
function appendLine(file, comment, line) {
|
|
4539
|
+
const current = fs9.existsSync(file) ? fs9.readFileSync(file, "utf8") : "";
|
|
4540
|
+
const sep = current === "" || current.endsWith("\n") ? "" : "\n";
|
|
4541
|
+
fs9.mkdirSync(path12.dirname(file), { recursive: true });
|
|
4542
|
+
fs9.writeFileSync(file, `${current}${sep}${current ? "\n" : ""}# ${comment}
|
|
4543
|
+
${line}
|
|
4544
|
+
`);
|
|
4545
|
+
}
|
|
4546
|
+
function ignoreKnowledge(repoDir) {
|
|
4547
|
+
const comment = "Company Knowledge, pulled by `clawnify knowledge pull`. Never committed.";
|
|
4548
|
+
const check = spawnSync2("git", ["check-ignore", "-q", "--", KNOWLEDGE_IGNORE], { cwd: repoDir });
|
|
4549
|
+
const where = spawnSync2("git", ["rev-parse", "--git-path", "info/exclude"], { cwd: repoDir, encoding: "utf8" });
|
|
4550
|
+
if (where.status === 0 && where.stdout.trim()) {
|
|
4551
|
+
const exclude = path12.resolve(repoDir, where.stdout.trim());
|
|
4552
|
+
const current = fs9.existsSync(exclude) ? fs9.readFileSync(exclude, "utf8") : "";
|
|
4553
|
+
if (!current.split("\n").includes(KNOWLEDGE_IGNORE)) appendLine(exclude, comment, KNOWLEDGE_IGNORE);
|
|
4554
|
+
}
|
|
4555
|
+
if (check.status === 0) return `${KNOWLEDGE_IGNORE} is already ignored by git.`;
|
|
4556
|
+
appendLine(path12.join(repoDir, ".gitignore"), comment, KNOWLEDGE_IGNORE);
|
|
4557
|
+
return `Added ${KNOWLEDGE_IGNORE} to .gitignore (commit it so every clone ignores it).`;
|
|
4558
|
+
}
|
|
4559
|
+
function installKnowledgeHook(repoDir) {
|
|
4560
|
+
const command = "npx --yes clawnify@latest knowledge pull --quiet";
|
|
4561
|
+
const hooksPath = spawnSync2("git", ["config", "--get", "core.hooksPath"], { cwd: repoDir, encoding: "utf8" });
|
|
4562
|
+
if (hooksPath.status === 0 && hooksPath.stdout.trim()) {
|
|
4563
|
+
return `Did not add a post-merge hook: git keeps hooks in ${hooksPath.stdout.trim()} (core.hooksPath). To refresh knowledge/ on each pull, add to its post-merge hook:
|
|
4564
|
+
${command}`;
|
|
4565
|
+
}
|
|
4566
|
+
const where = spawnSync2("git", ["rev-parse", "--git-path", "hooks/post-merge"], { cwd: repoDir, encoding: "utf8" });
|
|
4567
|
+
if (where.status !== 0) return `Did not add a post-merge hook: ${where.stderr.trim() || "git could not say where hooks go"}.`;
|
|
4568
|
+
const hook = path12.resolve(repoDir, where.stdout.trim());
|
|
4569
|
+
if (fs9.existsSync(hook)) {
|
|
4570
|
+
return fs9.readFileSync(hook, "utf8").includes(HOOK_MARK) ? "The post-merge hook already refreshes knowledge/ on each git pull." : `Left the existing hook ${hook} as it is. To refresh knowledge/ on each pull, add to it:
|
|
4571
|
+
${command}`;
|
|
4572
|
+
}
|
|
4573
|
+
fs9.mkdirSync(path12.dirname(hook), { recursive: true });
|
|
4574
|
+
fs9.writeFileSync(
|
|
4575
|
+
hook,
|
|
4576
|
+
`#!/bin/sh
|
|
4577
|
+
# Added by \`clawnify workspace clone\`: refresh knowledge/, the org's Company
|
|
4578
|
+
# Knowledge, after each git pull (${HOOK_MARK}). Delete this file to stop it.
|
|
4579
|
+
${command}
|
|
4580
|
+
exit 0
|
|
4581
|
+
`,
|
|
4582
|
+
{ mode: 493 }
|
|
4583
|
+
);
|
|
4584
|
+
return "Added a post-merge hook: each git pull refreshes knowledge/ (a pull with --rebase does not run it).";
|
|
4585
|
+
}
|
|
3942
4586
|
var INSTALL_URL = "https://github.com/apps/clawnify/installations/new";
|
|
3943
4587
|
var INSTALL_POLL_MS = 5e3;
|
|
3944
4588
|
var INSTALL_TIMEOUT_MS = 5 * 6e4;
|
|
@@ -4034,13 +4678,13 @@ async function workspaceConnectCommand(opts) {
|
|
|
4034
4678
|
|
|
4035
4679
|
Clone: git clone https://github.com/${data.repo}.git
|
|
4036
4680
|
The website lives under ${data.subdir ?? "website"}/ \u2014 pushes to
|
|
4037
|
-
${data.branch ?? "main"} auto-deploy to the
|
|
4681
|
+
${data.branch ?? "main"} auto-deploy to the live site.
|
|
4038
4682
|
|
|
4039
4683
|
Run \`clawnify workspace\` any time for the full map + editing contract.`);
|
|
4040
4684
|
}
|
|
4041
4685
|
|
|
4042
4686
|
// src/commands/execute.ts
|
|
4043
|
-
import
|
|
4687
|
+
import fs10 from "fs";
|
|
4044
4688
|
|
|
4045
4689
|
// src/lib/mcp-client.ts
|
|
4046
4690
|
var MCP_URL = "https://mcp.clawnify.com/mcp";
|
|
@@ -4090,7 +4734,7 @@ async function executeCommand(file, options) {
|
|
|
4090
4734
|
code = options.code;
|
|
4091
4735
|
} else if (file) {
|
|
4092
4736
|
try {
|
|
4093
|
-
code =
|
|
4737
|
+
code = fs10.readFileSync(file, "utf-8");
|
|
4094
4738
|
} catch (err) {
|
|
4095
4739
|
process.stderr.write(`Failed to read ${file}: ${String(err)}
|
|
4096
4740
|
`);
|
|
@@ -4145,8 +4789,8 @@ async function docsCommand(slug, options) {
|
|
|
4145
4789
|
process.exit(1);
|
|
4146
4790
|
}
|
|
4147
4791
|
const caller = options.caller ?? "external";
|
|
4148
|
-
const
|
|
4149
|
-
const res = await fetch(DOCS_URL +
|
|
4792
|
+
const path14 = slug ? `/docs/${orgId}/${slug}.md?caller=${caller}` : `/docs/${orgId}/index.md`;
|
|
4793
|
+
const res = await fetch(DOCS_URL + path14, {
|
|
4150
4794
|
headers: {
|
|
4151
4795
|
authorization: "Bearer " + token
|
|
4152
4796
|
}
|
|
@@ -4339,18 +4983,18 @@ Valid: ${ALL_AGENTS.join(", ")}`
|
|
|
4339
4983
|
}
|
|
4340
4984
|
|
|
4341
4985
|
// src/commands/flows.ts
|
|
4342
|
-
import { spawnSync as
|
|
4343
|
-
import
|
|
4986
|
+
import { spawnSync as spawnSync3 } from "child_process";
|
|
4987
|
+
import fs11 from "fs";
|
|
4344
4988
|
import os from "os";
|
|
4345
|
-
import
|
|
4989
|
+
import path13 from "path";
|
|
4346
4990
|
function flowFileName(name) {
|
|
4347
4991
|
return name.endsWith(".json") ? name : `${name}.json`;
|
|
4348
4992
|
}
|
|
4349
4993
|
function parseFlowFile(file) {
|
|
4350
|
-
const abs =
|
|
4994
|
+
const abs = path13.resolve(file);
|
|
4351
4995
|
let raw;
|
|
4352
4996
|
try {
|
|
4353
|
-
raw =
|
|
4997
|
+
raw = fs11.readFileSync(abs, "utf8");
|
|
4354
4998
|
} catch {
|
|
4355
4999
|
console.error(`Cannot read ${abs}.`);
|
|
4356
5000
|
process.exit(1);
|
|
@@ -4457,18 +5101,18 @@ async function flowsEditCommand(name, opts) {
|
|
|
4457
5101
|
} else {
|
|
4458
5102
|
const res = await api.get(`/servers/${serverId}/flows?name=${encodeURIComponent(flowFileName(name))}`);
|
|
4459
5103
|
const { flow: current } = await res.json();
|
|
4460
|
-
tmpDir =
|
|
4461
|
-
tmpFile =
|
|
4462
|
-
|
|
5104
|
+
tmpDir = fs11.mkdtempSync(path13.join(os.tmpdir(), "clawnify-flow-"));
|
|
5105
|
+
tmpFile = path13.join(tmpDir, flowFileName(name));
|
|
5106
|
+
fs11.writeFileSync(tmpFile, JSON.stringify(current, null, 2) + "\n");
|
|
4463
5107
|
const editor = process.env.VISUAL || process.env.EDITOR || "vi";
|
|
4464
|
-
const result =
|
|
5108
|
+
const result = spawnSync3(`${editor} "${tmpFile}"`, { shell: true, stdio: "inherit" });
|
|
4465
5109
|
if (result.status !== 0) {
|
|
4466
5110
|
console.error(`Editor exited without saving \u2014 draft unchanged (kept at ${tmpFile}).`);
|
|
4467
5111
|
process.exit(1);
|
|
4468
5112
|
}
|
|
4469
|
-
const edited =
|
|
5113
|
+
const edited = fs11.readFileSync(tmpFile, "utf8");
|
|
4470
5114
|
if (edited === JSON.stringify(current, null, 2) + "\n") {
|
|
4471
|
-
|
|
5115
|
+
fs11.rmSync(tmpDir, { recursive: true, force: true });
|
|
4472
5116
|
console.log("No changes.");
|
|
4473
5117
|
return;
|
|
4474
5118
|
}
|
|
@@ -4485,7 +5129,7 @@ async function flowsEditCommand(name, opts) {
|
|
|
4485
5129
|
flow,
|
|
4486
5130
|
tmpFile ? `Draft unchanged \u2014 your edits are kept at ${tmpFile}; fix and re-save with: clawnify flows edit ${name} --file "${tmpFile}"` : void 0
|
|
4487
5131
|
);
|
|
4488
|
-
if (tmpDir)
|
|
5132
|
+
if (tmpDir) fs11.rmSync(tmpDir, { recursive: true, force: true });
|
|
4489
5133
|
console.log(
|
|
4490
5134
|
existing.published != null ? `Saved draft "${name}". Runs and triggers keep using v${existing.published} \u2014 publish to make this live: clawnify flows publish ${name}` : `Saved draft "${name}". This flow has no published version, so runs and triggers execute the draft as-is \u2014 cut v1 with: clawnify flows publish ${name}`
|
|
4491
5135
|
);
|
|
@@ -4550,6 +5194,8 @@ async function runCli() {
|
|
|
4550
5194
|
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);
|
|
4551
5195
|
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);
|
|
4552
5196
|
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);
|
|
5197
|
+
const knowledge = program.command("knowledge").description("Company Knowledge on disk, for coding agents");
|
|
5198
|
+
knowledge.command("pull [dir]").description("Write the org's published Company Knowledge as markdown into a git-ignored folder (default: knowledge/ at the workspace root)").option("--org <slug-or-id>", "Org to pull (defaults to the folder's org)").option("--project <id>", "Pull a Project's sources instead (default folder: knowledge/projects/<name>/)").option("--files", "Also pull the original Company files (kept on for later pulls)").option("--no-files", "Stop pulling the original files, and remove the ones pulled").option("--strict", "Exit non-zero when a file was left because it changed locally").option("-q, --quiet", "Print only what needs attention (the git hook uses it)").action(knowledgePullCommand);
|
|
4553
5199
|
program.command("git-credential <operation>", { hidden: true }).description("Git credential helper for Clawnify git (get, store, erase)").action(gitCredentialCommand);
|
|
4554
5200
|
program.command("ls").description("List deployed apps").action(lsCommand);
|
|
4555
5201
|
program.command("logs <app-id>").description("Show build logs for an app").action(logsCommand);
|