@kazzle/app 0.1.693

package/templates/ai-app/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "{{APP_SLUG}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "components/*"
+  ],
+  "scripts": {
+    "dev": "bun run --cwd components/ui dev",
+    "start": "bun run --cwd components/server start",
+    "check": "bun run --filter='./components/*' check"
+  },
+  "dependencies": {
+    "@kazzle/app": "{{KAZZLE_APP_VERSION}}"
+  }
+}

package/templates/empty-app/KAZZLE.md

@@ -0,0 +1,10 @@
+# Kazzle template context
+
+This app was created from the `empty` template. It intentionally starts with no components so the app structure can be designed from the user's requirements.
+
+Safe next steps:
+- Add components to `kazzle.config.ts` only after choosing the app type.
+- Add files that match those components.
+- Add `package.json` scripts, including `check`, before calling the app done.
+
+If the user wants a common app shape, prefer a purpose-built template such as `ui`, `process`, `ui-db`, or `realtime` instead of rebuilding that structure manually here.

package/templates/empty-app/kazzle.config.ts

@@ -0,0 +1,8 @@
+import { defineConfig } from '@kazzle/app';
+
+export default defineConfig({
+  /** Path to the app icon relative to the repo root. Uploaded to CDN on publish. */
+  icon: 'icon.svg',
+  /** App components — each entry defines a deployable unit. */
+  components: [],
+});

package/templates/empty-app/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "{{APP_SLUG}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "components/*"
+  ],
+  "scripts": {
+    "check": "echo 'No components yet'"
+  },
+  "dependencies": {
+    "@kazzle/app": "{{KAZZLE_APP_VERSION}}"
+  }
+}

package/templates/manifest.json

@@ -0,0 +1,10 @@
+{
+  "entries": [
+    { "id": "empty", "label": "Empty", "description": "Minimal Kazzle app scaffold with config and skills only.", "tags": ["starter"] },
+    { "id": "ui", "label": "UI", "description": "React + Vite UI component with the Kazzle preview Vite helper.", "tags": ["ui", "frontend"] },
+    { "id": "process", "label": "Process", "description": "Background/triggered process component plus AI tool skill.", "tags": ["process", "tools"] },
+    { "id": "ui-db", "label": "UI + Postgres", "description": "React UI plus Hono API backed by a plain Postgres database.", "tags": ["ui", "database"] },
+    { "id": "realtime", "label": "Realtime", "description": "Offline-first UI with PowerSync sync over a Postgres backend.", "tags": ["ui", "database", "sync"] },
+    { "id": "ai", "label": "AI", "description": "React UI plus Hono server exposing Kazzle AI (chat, image, speech, extract).", "tags": ["ui", "ai"] }
+  ]
+}

package/templates/process-app/KAZZLE.md

@@ -0,0 +1,10 @@
+# Kazzle template context
+
+This app was created from the `process` template. It is a server-side process app, not a browser UI.
+
+Template-owned setup:
+- `kazzle.config.ts` declares one process component.
+- `components/process/index.ts` is the process entrypoint.
+- `components/process/package.json` already contains start, dev, typecheck, and check scripts.
+
+Keep runtime-only logic in the process entrypoint. Do not add frontend files, browser preview requirements, or database wiring unless the user's requirements need them.

package/templates/process-app/components/process/index.ts

@@ -0,0 +1,155 @@
+/**
+ * {{APP_NAME}} — process component entry point (persistent mode).
+ *
+ * This is a long-running HTTP server. The Kazzle platform routes triggers
+ * (schedule and webhook) into this server at the paths declared in
+ * `kazzle.config.ts` → `triggers[]`. Each request carries:
+ *
+ *   - `Authorization: Bearer ${KAZZLE_TRIGGER_SECRET}` — validate this
+ *     before doing any work. Calls without the header are external traffic
+ *     and should be handled with your own auth (or rejected).
+ *   - `x-kazzle-trigger-name` — the trigger's `name` from the manifest.
+ *   - `x-kazzle-trigger-run-id` — opaque ID for log correlation.
+ *   - `x-kazzle-triggered-by` — 'cron' | 'webhook' | 'manual'.
+ *
+ * `PORT` and `HOST` are injected by `kazzle run`. Missing values throw so
+ * the platform sees a fast, readable failure instead of binding to the
+ * wrong port.
+ *
+ * If you want one-off ephemeral runs per trigger instead (Vercel cron
+ * style), set `processMode: 'triggered'` in kazzle.config.ts and read
+ * `TRIGGER_NAME` + `WEBHOOK_PAYLOAD` from process.env on startup; the
+ * platform will spawn this file fresh per trigger and the body below
+ * (`Bun.serve`) is never reached.
+ */
+
+import { SaveBookmarkInput } from '../../skills/tools/tools';
+
+// ─── Triggered mode (one-off ephemeral run) ─────────────────────────────
+//
+// If TRIGGERED_BY is set, the platform launched us for a single trigger
+// (cron or webhook) and expects the process to do its job and exit. This
+// mirrors the `processMode: 'triggered'` lifecycle described above.
+if (process.env.TRIGGERED_BY) {
+  const trigger = process.env.TRIGGERED_BY;
+  const runId = process.env.RUN_ID ?? 'unknown';
+  const triggerName = process.env.TRIGGER_NAME ?? '';
+  const payload = process.env.WEBHOOK_PAYLOAD ?? '';
+  console.log(`[{{APP_NAME}}] Triggered by: ${trigger} (runId=${runId}, trigger=${triggerName})`);
+  if (payload) console.log(`[{{APP_NAME}}] Payload: ${payload}`);
+  console.log(`[{{APP_NAME}}] Job complete`);
+  process.exit(0);
+}
+
+// ─────────────────────────────────────────────────────────────────────────
+//  DO NOT CHANGE THE NEXT 4 LINES.  DO NOT ADD FALLBACKS.  DO NOT HARDCODE.
+//  PORT and HOST are injected by `kazzle run`. Missing values must throw so
+//  the platform sees a fast, readable failure instead of binding to the
+//  wrong port.
+// ─────────────────────────────────────────────────────────────────────────
+if (!process.env.PORT || !process.env.HOST) {
+  throw new Error('PORT and HOST must be set by "kazzle run" — never hardcode them.');
+}
+const PORT = Number(process.env.PORT);
+const HOST = process.env.HOST;
+
+// KAZZLE_TRIGGER_SECRET is injected into the env when the migration that
+// adds `drive_items.trigger_secret` lands. Until then the platform skips
+// the Authorization header; treat a missing secret here as "auth not yet
+// available" and accept platform-tagged requests by header presence only.
+const TRIGGER_SECRET = process.env.KAZZLE_TRIGGER_SECRET ?? '';
+
+function isPlatformTrigger(req: Request): boolean {
+  if (!req.headers.get('x-kazzle-trigger-name')) return false;
+  if (!TRIGGER_SECRET) return true;
+  const auth = req.headers.get('authorization') ?? '';
+  return auth === `Bearer ${TRIGGER_SECRET}`;
+}
+
+const server = Bun.serve({
+  hostname: HOST,
+  port: PORT,
+  async fetch(req) {
+    const url = new URL(req.url);
+
+    // /health is the liveness probe. Keep it dependency-free so a flaky
+    // database or downstream API doesn't take the whole process down.
+    if (url.pathname === '/health') {
+      return Response.json({
+        status: 'ok',
+        pid: process.pid,
+        uptime: process.uptime(),
+      });
+    }
+
+    // ── Platform-routed triggers ─────────────────────────────────────────
+    //
+    // Each trigger declared in kazzle.config.ts → triggers[] arrives here
+    // at its declared `path`. The block below shows the canonical handler
+    // shape — extend it as you add triggers.
+
+    // Example: handle a daily cron declared as
+    //   { name: 'hourly-sync', kind: 'schedule', schedule: '0 * * * *', path: '/cron/hourly-sync' }
+    if (req.method === 'POST' && url.pathname === '/cron/hourly-sync') {
+      if (!isPlatformTrigger(req)) return new Response('Unauthorized', { status: 401 });
+      // Do the cron work here.
+      console.log(`[{{APP_NAME}}] hourly sync fired (runId=${req.headers.get('x-kazzle-trigger-run-id')})`);
+      return Response.json({ ok: true });
+    }
+
+    // Example: handle a webhook declared as
+    //   { name: 'incoming', kind: 'webhook', path: '/webhook/incoming' }
+    if (req.method === 'POST' && url.pathname === '/webhook/incoming') {
+      if (!isPlatformTrigger(req)) return new Response('Unauthorized', { status: 401 });
+      const body = await req.json().catch(() => ({})) as Record<string, unknown>;
+      console.log(`[{{APP_NAME}}] webhook fired:`, JSON.stringify(body).slice(0, 256));
+      return Response.json({ ok: true, received: true });
+    }
+
+    // ── AI tool handlers (the "kitchen") ─────────────────────────────────
+    //
+    // Each tool declared in skills/tools/tools.ts is backed by a route here.
+    // When the AI calls `save_bookmark`, Kazzle POSTs { input } to this path
+    // with the app identity as `Authorization: Bearer <token>`. Return either
+    // plain text or JSON { content } — that becomes the tool result the AI sees.
+    //
+    // To add a tool: add it to tools.ts (name + Zod input + path), then add
+    // its matching `POST <path>` route below.
+    if (req.method === 'POST' && url.pathname === '/tools/save-bookmark') {
+      const { input } = (await req.json().catch(() => ({}))) as { input?: unknown };
+      const parsed = SaveBookmarkInput.safeParse(input);
+      if (!parsed.success) {
+        return Response.json({ content: parsed.error.issues.map(issue => issue.message).join('; ') }, { status: 400 });
+      }
+      const toolInput = parsed.data;
+      // Do the real work here (write to your DB, call an API, etc.).
+      //
+      // Per-install runtime secrets (e.g. a connected user's OAuth token) are
+      // saved/read by calling Kazzle back with the SAME identity header this
+      // tool call arrived with — Kazzle scopes them to this install. Use a
+      // fixed name; never key by user yourself:
+      //
+      //   const auth = req.headers.get('authorization')!;
+      //   const api = process.env.KAZZLE_API_URL;
+      //   await fetch(`${api}/apps/secrets/gmail_token`, {
+      //     method: 'PUT', headers: { authorization: auth, 'content-type': 'application/json' },
+      //     body: JSON.stringify({ value: accessToken }),
+      //   });
+      //   const res = await fetch(`${api}/apps/secrets/gmail_token`, { headers: { authorization: auth } });
+      //   const token = res.ok ? (await res.json()).value : null; // 404 → not connected yet
+      console.log(`[{{APP_NAME}}] save_bookmark:`, toolInput.title ?? '(untitled)', toolInput.url);
+      return Response.json({ content: `Saved bookmark: ${toolInput.title ?? toolInput.url}` });
+    }
+
+    // ── Your own HTTP endpoints ──────────────────────────────────────────
+
+    if (req.method === 'POST' && url.pathname === '/process') {
+      const body = await req.json() as Record<string, unknown>;
+      return Response.json({ received: true, echo: body });
+    }
+
+    return new Response('Hello from {{APP_NAME}}!');
+  },
+});
+
+console.log(`[{{APP_NAME}}] Server listening on port ${server.port}`);

package/templates/process-app/components/process/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "{{APP_SLUG}}",
+  "version": "1.0.0",
+  "type": "module",
+  "scripts": {
+    "start": "bun run index.ts",
+    "dev": "kazzle run -- bun --watch index.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions",
+    "check": "bun run typecheck"
+  },
+  "dependencies": {
+    "@kazzle/app": "{{KAZZLE_APP_VERSION}}",
+    "hono": "^4.12.16",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.6",
+    "typescript": "^5.8.3"
+  }
+}

package/templates/process-app/components/process/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["bun"]
+  },
+  "include": ["index.ts"]
+}

package/templates/process-app/kazzle.config.ts

@@ -0,0 +1,32 @@
+import { defineConfig } from '@kazzle/app';
+
+export default defineConfig({
+  /** Path to the app icon relative to the repo root. Uploaded to CDN on publish. */
+  icon: 'icon.svg',
+  /** App components — each entry defines a deployable unit. */
+  components: [
+    {
+      name: '{{APP_NAME}}',
+      type: 'process',
+      path: './components/process/index.ts',
+      runtime: { dev: 'bun run dev', run: 'bun run start' },
+      // Persistent processes are long-running servers. The platform posts
+      // triggers into the running server at each trigger's `path` with
+      // `Authorization: Bearer ${KAZZLE_TRIGGER_SECRET}`. Customer code
+      // validates the header before doing work.
+      processMode: 'persistent',
+      triggers: [
+        // Example cron — uncomment and adjust. 5-field, minute resolution.
+        // { name: 'hourly-sync', kind: 'schedule', schedule: '0 * * * *', path: '/cron/hourly-sync' },
+        // Example webhook — POSTs to /webhooks/{spaceId}/{appId}/{{APP_NAME}}/incoming
+        // { name: 'incoming', kind: 'webhook', path: '/webhook/incoming' },
+      ],
+    },
+  ],
+  // Skills = what the AI knows + can do with this app. Each skill is a folder
+  // (SKILL.md + optional tools.ts). The tools in tools.ts are backed by
+  // `POST /tools/<name>` routes in the process component above (the "kitchen").
+  skills: [
+    { name: '{{APP_NAME}}', path: './skills/tools/SKILL.md' },
+  ],
+});

package/templates/process-app/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "{{APP_SLUG}}",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "workspaces": [
+    "components/*"
+  ],
+  "scripts": {
+    "dev": "bun run --cwd components/process dev",
+    "start": "bun run --cwd components/process start",
+    "check": "bun run --filter='./components/*' check"
+  },
+  "dependencies": {
+    "@kazzle/app": "{{KAZZLE_APP_VERSION}}",
+    "zod": "^4.3.6"
+  }
+}

package/templates/process-app/skills/tools/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: {{APP_NAME}}
+description: What {{APP_NAME}} can do and the tools it exposes.
+alwaysActive: true
+---
+
+# {{APP_NAME}}
+
+This skill is the **menu** for {{APP_NAME}}. It tells the AI what this app can do
+and lists the tools it can call. The **kitchen** — the code that actually runs
+each tool — lives in the process component (`components/process/index.ts`) as one
+`POST /tools/<name>` route per tool.
+
+## How a tool call works
+
+1. The AI calls a tool listed in `tools.ts`, e.g. `save_bookmark(url, title)`.
+2. Kazzle POSTs `{ "input": { ... } }` to that tool's handler route
+   (`POST /tools/save-bookmark`) on this app's process component, with the app
+   identity as `Authorization: Bearer <token>`.
+3. The handler does the work and returns the result — either plain text or JSON
+   `{ "content": "..." }`. The AI sees that as the tool result.
+
+## Tools
+
+- **`save_bookmark(url, title)`** — save a bookmark and return a confirmation.
+
+## Adding a tool (do both, always)
+
+1. Add the tool to `tools.ts` with `type: "app"`, its provider-safe `name`,
+   friendly `displayName`, AI-facing `description`, Zod `input` schema, the
+   `component` that serves it (a component name from `kazzle.config.ts`), and the
+   `path` of its handler route.
+2. Add the matching `POST <path>` route to that component (`components/process/index.ts`).
+
+A tool listed here with no matching route does nothing; a route with no menu entry
+is never called. Never hardcode a URL or use `{{ }}` placeholders — Kazzle joins
+the component's live URL and `path` at call time.

package/templates/process-app/skills/tools/tools.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import type { KazzleTool } from '@kazzle/app/tools';
+
+export const SaveBookmarkInput = z.object({
+  url: z.string().url().describe('URL to save.'),
+  title: z.string().optional().describe('Optional human-readable title for the bookmark.'),
+}).strict();
+
+export const tools = [
+  {
+    type: 'app',
+    name: 'save_bookmark',
+    displayName: 'Save bookmark',
+    description: 'Save a bookmark URL and return a confirmation.',
+    component: '{{APP_NAME}}',
+    path: '/tools/save-bookmark',
+    input: SaveBookmarkInput,
+  },
+] as const satisfies readonly KazzleTool[];

package/templates/realtime-app/KAZZLE.md

@@ -0,0 +1,11 @@
+# Kazzle template context
+
+This app was created from the `realtime` template. It already includes React UI, a server process, and realtime database wiring.
+
+Template-owned setup:
+- `kazzle.config.ts` declares the UI and server components. Realtime env vars are injected by `app.create`.
+- `components/server/index.ts` owns the server process and sync-aware API behavior.
+- `components/ui/src/` owns the realtime UI and client logic.
+- `components/ui/package.json` and `components/server/package.json` already contain install, build, and check scripts.
+
+Do not rerun `db.connect`, rewrite manifest env refs, or replace realtime setup after `app.create` reports template setup complete. Change template-owned files only when requirements actually change app behavior.