@positronic/template-new-project 0.0.77 → 0.0.78

package/index.js

@@ -53,10 +53,10 @@ module.exports = {
   ],
   setup: async ctx => {
     const devRootPath = process.env.POSITRONIC_LOCAL_PATH;
-    let coreVersion = '^0.0.77';
-    let cloudflareVersion = '^0.0.77';
-    let clientVercelVersion = '^0.0.77';
-    let genUIComponentsVersion = '^0.0.77';
+    let coreVersion = '^0.0.78';
+    let cloudflareVersion = '^0.0.78';
+    let clientVercelVersion = '^0.0.78';
+    let genUIComponentsVersion = '^0.0.78';
 
     // Map backend selection to package names
     const backendPackageMap = {
@@ -153,6 +153,7 @@ module.exports = {
     if (!ctx.answers.claudemd) {
       ctx.files = ctx.files.filter(file => file.path !== 'CLAUDE.md');
     }
+
   },
   complete: async ctx => {
     // Display getting started message

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@positronic/template-new-project",
-  "version": "0.0.77",
+  "version": "0.0.78",
   "publishConfig": {
     "access": "public"
   },

package/template/.positronic/build-brains.mjs

@@ -0,0 +1,93 @@
+/**
+ * Pre-compiles brain files from src/brains/ to .positronic/brains/.
+ *
+ * For .tsx files, an esbuild plugin preserves JSX text whitespace by wrapping
+ * JSXText nodes in expression containers before the JSX transform runs.
+ * For .ts files, esbuild simply transpiles TypeScript to JavaScript.
+ *
+ * The compiled output lives in .positronic/brains/ and resolves its relative
+ * imports (../brain.js, ../services/...) through symlinks that mirror src/.
+ */
+import * as esbuild from 'esbuild';
+import ts from 'typescript';
+import { readdirSync, promises as fs } from 'fs';
+import { join } from 'path';
+
+// Esbuild plugin that preserves whitespace in JSX text nodes.
+// Uses TypeScript's parser to find JSXText nodes and wrap them in
+// expression containers ({`text`}) before esbuild's JSX transform runs.
+function jsxTextPlugin() {
+  return {
+    name: 'jsx-text-preserver',
+    setup(build) {
+      build.onLoad({ filter: /\.tsx$/ }, async (args) => {
+        const source = await fs.readFile(args.path, 'utf8');
+        const sourceFile = ts.createSourceFile(
+          args.path, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX
+        );
+
+        const replacements = [];
+        function visit(node) {
+          if (node.kind === ts.SyntaxKind.JsxText) {
+            const rawText = node.getText(sourceFile);
+            const escaped = rawText
+              .replace(/\\/g, '\\\\')
+              .replace(/`/g, '\\`')
+              .replace(/\$/g, '\\$');
+            replacements.push({
+              start: node.getStart(sourceFile),
+              end: node.getEnd(),
+              text: `{\`<%= '${escaped}' %>\`}`,
+            });
+          }
+          ts.forEachChild(node, visit);
+        }
+        visit(sourceFile);
+
+        if (replacements.length === 0) return { contents: source, loader: 'tsx' };
+
+        let result = source;
+        for (const r of replacements.reverse()) {
+          result = result.slice(0, r.start) + r.text + result.slice(r.end);
+        }
+        return { contents: result, loader: 'tsx' };
+      });
+    },
+  };
+}
+
+// Find all .ts and .tsx files recursively
+function findBrainFiles(dir) {
+  const results = [];
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+  for (const entry of entries) {
+    if (entry.name.startsWith('_')) continue;
+    const fullPath = join(dir, entry.name);
+    if (entry.isFile() && (entry.name.endsWith('.ts') || entry.name.endsWith('.tsx'))) {
+      results.push(fullPath);
+    } else if (entry.isDirectory()) {
+      results.push(...findBrainFiles(fullPath));
+    }
+  }
+  return results;
+}
+
+const brainFiles = findBrainFiles('../src/brains');
+
+if (brainFiles.length > 0) {
+  await esbuild.build({
+    entryPoints: brainFiles,
+    outdir: 'brains',
+    format: 'esm',
+    jsx: 'automatic',
+    jsxImportSource: '@positronic/core',
+    plugins: [jsxTextPlugin()],
+    bundle: false,
+    allowOverwrite: true,
+  });
+}

package/template/.positronic/bundle.ts

@@ -7,7 +7,7 @@
  * When you add custom components to components/index.ts, they will automatically
  * be included in the bundle.
  */
-import { components } from '../components/index.js';
+import { components } from './components/index.js';
 
 // Extract the React component from each UIComponent and expose to window
 const PositronicComponents: Record<string, React.ComponentType<any>> = {};

package/template/.positronic/src/index.ts

@@ -10,21 +10,26 @@ import {
   AuthDO,
   PositronicManifest,
 } from "@positronic/cloudflare";
+import { collectPluginWebhooks } from "@positronic/core";
 // Import the generated manifests - NOTE the .js extension for runtime compatibility
 // @ts-expect-error - _manifest.js is generated during template processing
 import { manifest as brainManifest } from "./_manifest.js";
 // @ts-expect-error - _webhookManifest.js is generated during template processing
 import { webhookManifest } from "./_webhookManifest.js";
 import { runner } from "./runner.js";
+import { brain as brainFactory } from "../brain.js";
 
 // Configure the manifest to use the statically generated list
 const manifest = new PositronicManifest({
   manifest: brainManifest,
 });
 
+// Merge file-based webhooks with plugin-declared webhooks
+const pluginWebhooks = collectPluginWebhooks(brainFactory.plugins);
+
 setManifest(manifest);
 setBrainRunner(runner);
-setWebhookManifest(webhookManifest);
+setWebhookManifest({ ...webhookManifest, ...pluginWebhooks });
 
 // Define Env type based on wrangler.jsonc bindings
 interface Env {

package/template/.positronic/wrangler.jsonc

@@ -6,6 +6,10 @@
   "compatibility_flags": ["nodejs_compat", "nodejs_compat_populate_process_env"],
   "workers_dev": true,
   "preview_urls": true,
+  "build": {
+    "command": "node build-brains.mjs",
+    "watch_dir": "../src/brains"
+  },
   "limits": {
     "cpu_ms": 300000
   },

package/template/CLAUDE.md

@@ -8,13 +8,16 @@ This is a Positronic project - an AI-powered framework for building and running
 
 ## Project Structure
 
-- **`/brains`** - AI workflow definitions using the Brain DSL
-- **`/webhooks`** - Webhook definitions for external integrations (auto-discovered)
+- **`/src`** - Application source code
+  - **`/src/brain.ts`** - Project brain wrapper (custom `brain` function)
+  - **`/src/brains`** - AI workflow definitions using the Brain DSL
+  - **`/src/runner.ts`** - The main entry point for running brains locally
+  - **`/src/utils`** - Shared utilities (e.g., `bottleneck` for rate limiting)
+  - **`/src/plugins`** - Plugin definitions for external integrations (see `/docs/plugin-guide.md`)
+  - **`/src/components`** - Reusable UI/prompt components
 - **`/resources`** - Files and documents that brains can access via the resource system
 - **`/tests`** - Test files for brains (kept separate to avoid deployment issues)
-- **`/utils`** - Shared utilities (e.g., `bottleneck` for rate limiting)
 - **`/docs`** - Documentation including brain testing guide
-- **`/runner.ts`** - The main entry point for running brains locally
 - **`/positronic.config.json`** - Project configuration
 
 ## Key Commands
@@ -40,6 +43,7 @@ The Brain DSL provides a fluent API for defining AI workflows:
 
 ```typescript
 // Import from the project brain wrapper (see positronic-guide.md)
+// From a file in src/brains/, brain.ts is at src/brain.ts
 import { brain } from '../brain.js';
 
 const myBrain = brain('my-brain')
@@ -60,88 +64,183 @@ const myBrain = brain('my-brain')
 export default myBrain;
 ```
 
+### JSX Templates
+
+Templates in `.prompt()`, `.page()`, and `.map()` steps can be written as JSX for better readability. Rename the brain file to `.tsx` and return JSX from the template function. See `/docs/brain-dsl-guide.md` for details.
+
 ## Resource System
 
 Resources are files that brains can access during execution. They're stored in the `/resources` directory and are automatically typed based on the manifest.
 
 ## Webhooks
 
-Webhooks allow brains to pause execution and wait for external events (like form submissions, API callbacks, or user approvals). Webhooks are auto-discovered from the `/webhooks` directory.
+Webhooks allow brains to pause execution and wait for external events (like Slack replies or GitHub events). Webhooks live inside plugins, not in a separate directory.
+
+### Page Forms vs Service Webhooks
+
+**Page forms** (user submits a form on a page generated by your brain) are handled automatically by `.page()` with `formSchema`. No webhook code needed — see "Custom HTML Pages" below and `/docs/brain-dsl-guide.md`.
 
-### Creating a Webhook
+**Service webhooks** (external services like Slack or GitHub calling back into your app) are declared on plugins. The plugin defines the webhook handler and exposes it for brains to use in `.wait()` steps or as tools in prompt loops.
 
-Create a file in the `/webhooks` directory with a default export:
+### Using Plugin Webhooks in Brains
+
+Plugins that declare webhooks make them available on the step context:
 
 ```typescript
-// webhooks/approval.ts
-import { createWebhook } from '@positronic/core';
+export default brain('feedback-loop')
+  .step('Post draft', async ({ state, slack }) => {
+    const result = await slack.sendMessage(channel, state.draft);
+    return { ...state, threadTs: result.ts };
+  })
+  .wait('Wait for feedback', ({ state, slack }) => slack.webhooks.slack(state.threadTs))
+  .handle('Apply feedback', ({ state, response }) => ({
+    ...state,
+    feedback: response.message.text,
+  }));
+```
+
+The optional `timeout` parameter accepts durations like `'30m'`, `'1h'`, `'24h'`, `'7d'`, or a number in milliseconds. If the timeout elapses without a webhook response, the brain is cancelled. Without a timeout, the brain waits indefinitely.
+
+### Declaring Webhooks in Plugins
+
+Webhooks are declared on the plugin definition using `createWebhook()` and returned from `create()` so brains can access them:
+
+```typescript
+import { definePlugin, createWebhook } from '@positronic/core';
 import { z } from 'zod';
 
-const approvalWebhook = createWebhook(
-  'approval',  // webhook name (should match filename)
-  z.object({   // response schema - what the webhook returns to the brain
-    approved: z.boolean(),
-    reviewerNote: z.string().optional(),
-  }),
+const myWebhook = createWebhook(
+  'my-service',
+  z.object({ message: z.string() }),
   async (request: Request) => {
-    // Parse the incoming request and return identifier + response
     const body = await request.json();
     return {
       type: 'webhook',
-      identifier: body.requestId,  // matches the identifier used in waitFor
-      response: {
-        approved: body.approved,
-        reviewerNote: body.note,
-      },
+      identifier: body.threadId,
+      response: { message: body.text },
     };
   }
 );
 
-export default approvalWebhook;
+export const myService = definePlugin({
+  name: 'myService',
+  webhooks: { myWebhook },
+  create: () => ({
+    webhooks: { myWebhook },
+    // ... other methods and tools
+  }),
+});
 ```
 
-### Using Webhooks in Brains
+Plugin webhooks are automatically registered in the webhook manifest at startup.
+
+### Webhook Handler Return Types
+
+The handler return type determines behavior:
+- `{ type: 'webhook', identifier, response }` — resumes a waiting brain
+- `{ type: 'trigger', response }` — starts a new brain run (requires `triggers` config)
+- `{ type: 'ignore' }` — acknowledges receipt, takes no action
+- `{ type: 'verification', challenge }` — handles webhook verification challenges
+
+### Custom HTML Pages
+
+For pages with forms, use `.page()` with the `html` property instead of `prompt`. The framework handles CSRF tokens, webhook registration, suspension, and form data merging automatically:
+
+```tsx
+import { Form } from '@positronic/core';
+
+.page('Review items', ({ state }) => ({
+  html: (
+    <Form>
+      {state.items.map(item => (
+        <label>
+          <input type="checkbox" name="selectedIds" value={item.id} />
+          {item.name}
+        </label>
+      ))}
+      <button type="submit">Confirm</button>
+    </Form>
+  ),
+  formSchema: z.object({ selectedIds: z.array(z.string()) }),
+  onCreated: async (page) => {
+    await ntfy.send('Review ready', page.url);
+  },
+}))
+.step('Process', ({ state }) => {
+  // state.selectedIds comes from the form submission
+  return { ...state, confirmed: true };
+})
+```
 
-Import the webhook and use `.wait()` to pause execution:
+**Key details:**
+
+- `Form` is imported from `@positronic/core` — it's a Symbol-based built-in component (like `Fragment`, `File`, `Resource`). The framework injects the form action URL into it during rendering.
+- The `html` property accepts JSX directly, a string, or a function component.
+- The page title comes from the step title. The framework wraps the html body in a full HTML document automatically.
+
+### Extracting Page JSX into Separate Files
+
+For complex pages, extract the JSX into a separate `.tsx` file. Don't annotate the return type — let TypeScript infer it from the JSX:
+
+```tsx
+// brains/my-brain/pages/review-page.tsx
+import { Form } from '@positronic/core';
+export function ReviewPage({ items }: { items: { id: string; name: string }[] }) {
+  return (
+    <Form>
+      {items.map(item => (
+        <label>
+          <input type="checkbox" name="selectedIds" value={item.id} />
+          {item.name}
+        </label>
+      ))}
+      <button type="submit">Confirm</button>
+    </Form>
+  );
+}
+```
 
-```typescript
-import { brain } from '../brain.js';
-import approvalWebhook from '../webhooks/approval.js';
+Then use it in the brain:
 
-export default brain('approval-workflow')
-  .step('Request approval', ({ state }) => ({
-    ...state, status: 'pending',
-  }))
-  .wait('Wait for approval', ({ state }) => approvalWebhook(state.requestId), { timeout: '24h' })
-  .step('Process approval', ({ state, response }) => ({
-    ...state,
-    status: response.approved ? 'approved' : 'rejected',
-    reviewerNote: response.reviewerNote,
-  }));
+```tsx
+import { ReviewPage } from './pages/review-page.js';
+
+.page('Review items', ({ state }) => ({
+  html: <ReviewPage items={state.items} />,
+  formSchema: z.object({ selectedIds: z.array(z.string()) }),
+}))
 ```
 
-The optional `timeout` parameter accepts durations like `'30m'`, `'1h'`, `'24h'`, `'7d'`, or a number in milliseconds. If the timeout elapses without a webhook response, the brain is cancelled. Without a timeout, the brain waits indefinitely.
+This works because the positronic JSX runtime handles function components — it calls them with their props and renders the result. The `.tsx` file must use `jsxImportSource: "@positronic/core"` (inherited from the project tsconfig).
+
+**Important:** Do NOT annotate the return type on page components. JSX produces `TemplateNode` (which is `JSX.Element`). Writing `: TemplateChild` or `: ReactNode` will cause type errors — these are different types. Let TypeScript infer the return type.
 
-### CSRF Tokens for Pages with Forms
+**HTML elements work in page JSX.** You can use `<div>`, `<input>`, `<label>`, `<table>`, `<style>`, etc. — any standard HTML element. This is specific to the `html` property on `.page()`. Prompt JSX (in `.prompt()`, `.map()`) only supports `<>` (Fragment), `<File>`, `<Resource>`, and function components — HTML elements will throw an error there.
 
-If your brain generates a custom HTML page with a form that submits to a webhook, you must include a CSRF token. Without a token, the server will reject the submission.
+See `/docs/brain-dsl-guide.md` for full examples.
 
-1. Generate a token with `generateFormToken()` from `@positronic/core`
-2. Add `<input type="hidden" name="__positronic_token" value="<%= '${token}' %>">` to the form
-3. Pass the token when creating the webhook registration: `myWebhook(identifier, token)`
+### No JavaScript in Custom Pages
 
-The `.ui()` step handles this automatically. See `/docs/brain-dsl-guide.md` for full examples.
+Custom HTML pages are static — inline `<script>` tags are blocked by a Content Security Policy (`script-src 'none'`). This prevents XSS when user data is interpolated into page content.
 
-### How Auto-Discovery Works
+**Form submission doesn't need JS.** Native HTML forms work. Unchecked checkboxes don't submit — only checked ones do. The framework's `parseFormData` handles duplicate field names as arrays automatically.
+
+**For interactive UI (tabs, toggles, show/hide), use `<details>`/`<summary>` instead of JavaScript:**
+
+```tsx
+{categories.map(cat => (
+  <details open={cat === firstCategory}>
+    <summary>{cat.label} ({cat.count})</summary>
+    <ThreadList emails={cat.emails} />
+  </details>
+))}
+```
 
-- Place webhook files in `/webhooks` directory
-- Each file must have a default export using `createWebhook()`
-- The dev server generates `_webhookManifest.ts` automatically
-- Webhook name comes from the filename (e.g., `approval.ts` → `'approval'`)
+This gives collapsible sections that work without JS. Style with CSS for a polished look.
 
 ## Development Workflow
 
-1. Define your brain in `/brains`
+1. Define your brain in `/src/brains`
 2. Add any required resources to `/resources`
 3. Run `px brain run <brain-name>` to test locally
 4. Deploy using backend-specific commands