feat: codegen cli

.agents/skills/btst-ai-context/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: btst-ai-context
+description: Patterns for registering page-level AI context in BTST plugin pages so the AI chat widget understands the current page and can act on it. Use when adding useRegisterPageAIContext to a plugin page, implementing clientTools for AI-driven form filling or editor updates, registering server-side tool schemas in BUILT_IN_PAGE_TOOL_SCHEMAS, or wiring PageAIContextProvider in layouts.
+---
+
+# BTST AI Chat Page Context
+
+Plugin pages can register AI context so the chat widget understands the current page and can act on it (fill forms, update editors, summarize content).
+
+## useRegisterPageAIContext
+
+Call inside `.internal.tsx` page components.
+
+### Read-only (content pages)
+
+```tsx
+import { useRegisterPageAIContext } from "@btst/stack/plugins/ai-chat/client/context"
+
+// Pass null while data is loading — context is not registered until non-null
+useRegisterPageAIContext(item ? {
+  routeName: "my-plugin-detail",
+  pageDescription: `Viewing: "${item.title}"\n\n${item.content?.slice(0, 16000)}`,
+  suggestions: ["Summarize this", "What are the key points?"],
+} : null)
+```
+
+### With client-side tools (form/editor pages)
+
+```tsx
+import { useRef } from "react"
+import { useRegisterPageAIContext } from "@btst/stack/plugins/ai-chat/client/context"
+import type { UseFormReturn } from "react-hook-form"
+
+const formRef = useRef<UseFormReturn<any> | null>(null)
+
+useRegisterPageAIContext({
+  routeName: "my-plugin-edit",
+  pageDescription: "User is editing an item. Help them fill out the form.",
+  suggestions: ["Fill in the form for me", "Suggest a title"],
+  clientTools: {
+    fillMyForm: async ({ title, description }) => {
+      if (!formRef.current) return { success: false, message: "Form not ready" }
+      formRef.current.setValue("title", title, { shouldValidate: true })
+      formRef.current.setValue("description", description, { shouldValidate: true })
+      return { success: true }
+    },
+  },
+})
+```
+
+`clientTools` execute client-side only. Return `{ success: boolean, message?: string }`.
+
+## Server-side tool schemas (first-party tools)
+
+For first-party tools, add the server-side schema to `BUILT_IN_PAGE_TOOL_SCHEMAS` in `src/plugins/ai-chat/api/page-tools.ts`. No `execute` — that's handled client-side:
+
+```typescript
+// src/plugins/ai-chat/api/page-tools.ts
+export const BUILT_IN_PAGE_TOOL_SCHEMAS = {
+  fillBlogForm: { /* existing */ },
+  updatePageLayers: { /* existing */ },
+  fillMyForm: {
+    description: "Fill the my-plugin edit form with the provided values",
+    parameters: z.object({
+      title: z.string().describe("Item title"),
+      description: z.string().optional().describe("Item description"),
+    }),
+  },
+}
+```
+
+## PageAIContextProvider placement
+
+`PageAIContextProvider` must wrap the **root layout**, above all `StackProvider` instances:
+
+```tsx
+import { PageAIContextProvider } from "@btst/stack/plugins/ai-chat/client/context"
+
+export default function RootLayout({ children }) {
+  return <PageAIContextProvider>{children}</PageAIContextProvider>
+}
+```
+
+In the monorepo example apps this is already wired — don't add it again there. In a consumer app, add it once to the root layout when integrating the ai-chat plugin.
+
+## Reference examples in the codebase
+
+| File | Pattern |
+|---|---|
+| `src/plugins/blog/client/components/pages/new-post-page.internal.tsx` | `fillBlogForm` (clientTools) |
+| `src/plugins/blog/client/components/pages/post-page.internal.tsx` | Read-only context |
+| `src/plugins/ui-builder/client/components/pages/page-builder-page.internal.tsx` | `updatePageLayers` (clientTools) |

.agents/skills/btst-backend-plugin-dev/REFERENCE.md

@@ -0,0 +1,205 @@
+# btst-backend-plugin-dev — Reference
+
+## defineBackendPlugin shape (api/plugin.ts)
+
+```typescript
+import type { DBAdapter as Adapter } from "@btst/db"
+import { defineBackendPlugin, createEndpoint } from "@btst/stack/plugins/api"
+import { z } from "zod"
+import { dbSchema } from "./db-schema"
+import { listItems, getItemById } from "./getters"
+import { createItem, updateItem, deleteItem } from "./mutations"
+
+const ItemQuerySchema = z.object({ limit: z.coerce.number().optional() })
+const CreateItemSchema = z.object({ name: z.string() })
+
+export const myBackendPlugin = defineBackendPlugin({
+  name: "my-plugin",
+  dbPlugin: dbSchema,
+
+  // api factory — bound to shared adapter, no HTTP context
+  api: (adapter: Adapter) => ({
+    listItems: () => listItems(adapter),
+    getItemById: (id: string) => getItemById(adapter, id),
+    createItem: (data: CreateItemInput) => createItem(adapter, data),
+  }),
+
+  // routes factory — HTTP endpoints built with createEndpoint
+  routes: (adapter: Adapter) => {
+    const listItemsEndpoint = createEndpoint(
+      "/items",
+      { method: "GET", query: ItemQuerySchema },
+      async (ctx) => {
+        return await listItems(adapter)
+      },
+    )
+
+    const createItemEndpoint = createEndpoint(
+      "/items",
+      { method: "POST", body: CreateItemSchema },
+      async (ctx) => {
+        return await createItem(adapter, ctx.body)
+      },
+    )
+
+    const getItemEndpoint = createEndpoint(
+      "/items/:id",
+      { method: "GET" },
+      async (ctx) => {
+        const item = await getItemById(adapter, ctx.params.id)
+        if (!item) throw ctx.error(404, { message: "Item not found" })
+        return item
+      },
+    )
+
+    return { listItems: listItemsEndpoint, createItem: createItemEndpoint, getItem: getItemEndpoint } as const
+  },
+})
+
+// Router type for client consumption
+export type MyApiRouter = ReturnType<ReturnType<typeof myBackendPlugin>["routes"]>
+```
+
+### ctx object inside createEndpoint handlers
+
+| Property | Description |
+|---|---|
+| `ctx.query` | Validated query params (when `query:` schema provided) |
+| `ctx.body` | Validated request body (when `body:` schema provided) |
+| `ctx.params` | URL path params (e.g. `:id` → `ctx.params.id`) |
+| `ctx.headers` | Request `Headers` object |
+| `ctx.request` | Raw `Request` object |
+| `ctx.error(status, { message })` | Create an HTTP error — always `throw` the result |
+
+---
+
+## getters.ts
+
+Pure DB functions — no HTTP context, no lifecycle hooks, always accept `adapter` as first arg:
+
+```typescript
+import type { DBAdapter as Adapter } from "@btst/db"
+import type { Item } from "./types"
+
+// Authorization hooks are NOT called — callers are responsible for access control
+export async function listItems(adapter: Adapter): Promise<Item[]> {
+  return adapter.findMany({ model: "item" })
+}
+
+export async function getItemById(adapter: Adapter, id: string): Promise<Item | null> {
+  return adapter.findOne({ model: "item", where: { id } }) ?? null
+}
+```
+
+---
+
+## mutations.ts
+
+Write operations — no auth hooks, no HTTP context. JSDoc disclaimer required:
+
+```typescript
+import type { DBAdapter as Adapter } from "@btst/db"
+import type { CreateItemInput, Item } from "./types"
+
+/**
+ * Create a new item directly in the database.
+ * Authorization hooks are NOT called — caller is responsible for access control.
+ */
+export async function createItem(adapter: Adapter, data: CreateItemInput): Promise<Item> {
+  return adapter.create({
+    model: "item",
+    data: { id: crypto.randomUUID(), ...data, createdAt: new Date() },
+  })
+}
+
+/**
+ * Update an existing item.
+ * Authorization hooks are NOT called — caller is responsible for access control.
+ */
+export async function updateItem(
+  adapter: Adapter,
+  id: string,
+  data: Partial<CreateItemInput>,
+): Promise<Item | null> {
+  return adapter.update({ model: "item", where: { id }, data }) ?? null
+}
+
+/**
+ * Delete an item.
+ * Authorization hooks are NOT called — caller is responsible for access control.
+ */
+export async function deleteItem(adapter: Adapter, id: string): Promise<void> {
+  await adapter.delete({ model: "item", where: { id } })
+}
+```
+
+---
+
+## api/index.ts
+
+Re-export getters and mutations for direct server-side import (SSG, scripts, AI tools):
+
+```typescript
+// Getters — read-only, no auth hooks
+export { listItems, getItemById } from "./getters"
+
+// Mutations — write ops, no auth hooks
+export { createItem, updateItem, deleteItem } from "./mutations"
+
+// Types for consumers
+export type { MyApiRouter } from "./plugin"
+export { MY_PLUGIN_QUERY_KEYS } from "./query-key-defs"
+export { serializeItem } from "./serializers"
+```
+
+---
+
+## Lifecycle hook implementation in routes
+
+```typescript
+routes: (adapter: Adapter) => {
+  const createItemEndpoint = createEndpoint(
+    "/items",
+    { method: "POST", body: CreateItemSchema },
+    async (ctx) => {
+      const context = { body: ctx.body, headers: ctx.headers }
+
+      // before hook — throw to deny
+      await ctx.hooks?.onBeforeItemCreated?.(ctx.body, context)
+
+      const item = await createItem(adapter, ctx.body)
+
+      // after hook — fire and forget or await
+      await ctx.hooks?.onAfterItemCreated?.(item, context)
+
+      return item
+    },
+  )
+
+  return { createItem: createItemEndpoint } as const
+},
+```
+
+Hook naming always follows: `onBefore{Entity}{Action}`, `onAfter{Entity}{Action}`, `on{Entity}{Action}Error`.
+
+---
+
+## Plugin stack() wiring (in stack.ts)
+
+```typescript
+import { stack } from "@btst/stack"
+import { myBackendPlugin } from "./src/plugins/my-plugin/api/plugin"
+
+export const myStack = stack({
+  basePath: "/api/data",
+  plugins: {
+    myPlugin: myBackendPlugin,
+  },
+  adapter: (db) => createDrizzleAdapter(schema, db, {}),
+})
+
+export const { handler, dbSchema } = myStack
+
+// Direct server-side access (bypasses auth hooks):
+const items = await myStack.api.myPlugin.listItems()
+```

.agents/skills/btst-backend-plugin-dev/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: btst-backend-plugin-dev
+description: Patterns for writing BTST backend plugins inside the monorepo, including defineBackendPlugin structure, getters.ts/mutations.ts separation, the api factory, lifecycle hook naming conventions, and accessing the adapter in AI tool execute functions. Use when creating or modifying a backend plugin, adding DB getters or mutations, wiring the api factory, or implementing lifecycle hooks in src/plugins/{name}/api/.
+---
+
+# BTST Backend Plugin Development
+
+## File structure
+
+```
+src/plugins/{name}/
+  api/
+    plugin.ts        ← defineBackendPlugin entry
+    getters.ts       ← read-only DB functions (no HTTP context)
+    mutations.ts     ← write DB functions (no auth hooks)
+    index.ts         ← re-exports getters + mutations + types
+  query-keys.ts      ← React Query key factory
+```
+
+## Rules
+
+- **`getters.ts`** — pure async DB functions only. No HTTP context, no lifecycle hooks. Always takes `adapter` as first arg.
+- **`mutations.ts`** — write operations (create/update/delete). No auth hooks, no HTTP context. Add JSDoc: "Authorization hooks are NOT called."
+- **`api/index.ts`** — re-export everything from getters + mutations for direct server-side import.
+- The `api` factory and `routes` factory share the same adapter instance — bind getters inside the factory, don't pass adapter at call site.
+- If the plugin has a one-time init step (e.g. `syncContentTypes`), call it inside each getter/mutation wrapper — not only inside `routes`.
+- **Never** use `myStack.api.*` as a substitute for authenticated HTTP endpoints — auth hooks are not called.
+
+## Key patterns
+
+- Import `defineBackendPlugin` and `createEndpoint` from `"@btst/stack/plugins/api"` (not `@btst/stack/plugins`).
+- Import the adapter type as `import type { DBAdapter as Adapter } from "@btst/db"`.
+- Routes are defined with `createEndpoint(path, { method, query?, body? }, handler)` — not string-keyed `"GET /path"` objects.
+- Route handlers return data directly (`return item`) — no `ctx.json()`.
+- Throw errors with `throw ctx.error(statusCode, { message })`.
+- The `routes` factory returns a named object: `return { listItems, createItem } as const`.
+- Export the router type as `ReturnType<ReturnType<typeof myBackendPlugin>["routes"]>`.
+
+## Lifecycle hook naming
+
+Pattern: `onBefore{Entity}{Action}`, `onAfter{Entity}{Action}`, `on{Entity}{Action}Error`
+
+```typescript
+// Examples from existing plugins:
+onBeforeListPosts, onPostsRead, onListPostsError
+onBeforeCreatePost, onPostCreated, onCreatePostError
+onBeforeUpdatePost, onPostUpdated, onUpdatePostError
+onBeforeDeletePost, onPostDeleted, onDeletePostError
+onBeforePost, onAfterPost          // comments plugin (create comment)
+onBeforeEdit, onAfterEdit          // comments plugin (edit comment)
+onBeforeDelete, onAfterDelete      // comments plugin (delete comment)
+onBeforeStatusChange, onAfterApprove
+```
+
+## Adapter in AI tool execute functions
+
+`myStack` is a module-level const. The `execute` closure runs lazily (only on HTTP request), so `myStack` is always initialised by then:
+
+```typescript
+export const myStack = stack({ ... })
+
+const myTool = tool({
+  execute: async (params) => {
+    await createKanbanTask(myStack.adapter, { title: params.title, columnId: "col-id" })
+    return { success: true }
+  }
+})
+```
+
+## Gotchas
+
+- **Wrong import path** — always import from `"@btst/stack/plugins/api"`, not `"@btst/stack/plugins"`.
+- **Wrong adapter type** — use `import type { DBAdapter as Adapter } from "@btst/db"` in getters/mutations/plugin files.
+- **`"GET /path"` string keys** — routes use `createEndpoint()`, not string-keyed method/path objects.
+- **`ctx.json()`** — does not exist; return data directly from route handlers.
+- **`stack().api` bypasses auth hooks** — never use for authenticated data access; enforce auth at the call site.
+- **Plugin init not called via `api`** — if `routes` factory runs a setup (e.g. `syncContentTypes`), also await it inside each `api` getter wrapper.
+- **Write ops in `getters.ts`** — write functions belong in `mutations.ts`, not `getters.ts`.
+
+## Full code patterns
+
+See [REFERENCE.md](REFERENCE.md) for complete `defineBackendPlugin`, getters, mutations, and `api/index.ts` code shapes.