@kuratchi/js 0.0.3 → 0.0.5

package/README.md

@@ -18,12 +18,13 @@ bun run dev
 
 ## How it works
 
-`kuratchi build` (or `kuratchi watch`) scans `src/routes/` and generates two files:
+`kuratchi build` (or `kuratchi watch`) scans `src/routes/` and generates framework output:
 
 | File | Purpose |
 |---|---|
 | `.kuratchi/routes.js` | Compiled routes, actions, RPC handlers, and render functions |
-| `.kuratchi/worker.js` | Stable wrangler entry — re-exports the fetch handler and all Durable Object classes |
+| `.kuratchi/worker.js` | Stable wrangler entry - re-exports the fetch handler and all Durable Object classes |
+| `.kuratchi/do/*.js` | Generated Durable Object RPC proxy modules for `$durable-objects/*` imports |
 
 Point wrangler at the entry and you're done. **No `src/index.ts` needed.**
 
@@ -49,8 +50,6 @@ src/routes/layout.html        → shared layout wrapping all routes
 
 ```html
 <script>
-  // Imports and server-side logic run on every request.
-  // Exported functions become actions or RPC handlers automatically.
   import { getItems, addItem, deleteItem } from '$database/items';
 
   const items = await getItems();
@@ -95,7 +94,8 @@ The `$database/` alias resolves to `src/database/`. You can use any path alias c
 
 ```html
 <p>{title}</p>
-<p>{=html rawHtml}</p>  <!-- unescaped, use carefully -->
+<p>{@html bodyHtml}</p>  <!-- sanitized HTML -->
+<p>{@raw trustedHtml}</p> <!-- unescaped, unsafe -->
 ```
 
 ### Conditionals
@@ -131,6 +131,40 @@ Import `.html` components from your `src/lib/` directory or from packages:
 </Card>
 ```
 
+### Client Reactivity (`$:`)
+
+Inside client/browser `<script>` tags in the template markup, Kuratchi supports Svelte-style reactive labels:
+
+```html
+<script>
+  let users = ['Alice'];
+
+  $: console.log(`Users: ${users.length}`);
+
+  function addUser() {
+    users.push('Bob'); // reactive update, no reassignment required
+  }
+</script>
+```
+
+Block form is also supported:
+
+```html
+<script>
+  let form = { first: '', last: '' };
+
+  $: {
+    const fullName = `${form.first} ${form.last}`.trim();
+    console.log(fullName);
+  }
+</script>
+```
+
+Notes:
+- This reactivity runs in browser scripts rendered in the template markup, not in the top server route `<script>` load/action block.
+- Object/array `let` bindings are proxy-backed automatically when `$:` is used.
+- `$: name = expr` works; when replacing proxy-backed values, the compiler preserves reactivity under the hood.
+
 ## Form actions
 
 Export server functions from a route's `<script>` block and reference them with `action={fn}`. The compiler automatically registers them as dispatchable actions.
@@ -147,12 +181,15 @@ Export server functions from a route's `<script>` block and reference them with
 </form>
 ```
 
-The action function receives the raw `FormData`:
+The action function receives the raw `FormData`. Throw `ActionError` to surface a message back to the form — see [Error handling](#error-handling).
 
 ```ts
 // src/database/items.ts
+import { ActionError } from '@kuratchi/js';
+
 export async function addItem(formData: FormData): Promise<void> {
-  const title = formData.get('title') as string;
+  const title = (formData.get('title') as string)?.trim();
+  if (!title) throw new ActionError('Title is required');
   // write to DB...
 }
 ```
@@ -170,6 +207,85 @@ export async function createItem(formData: FormData): Promise<void> {
 }
 ```
 
+## Error handling
+
+### Action errors
+
+Throw `ActionError` from a form action to surface a user-facing message in the template. The error message is bound directly to the action by name — if you have multiple forms on the same page, each has its own isolated error state.
+
+```ts
+import { ActionError } from '@kuratchi/js';
+
+export async function signIn(formData: FormData) {
+  const email = formData.get('email') as string;
+  const password = formData.get('password') as string;
+
+  if (!email || !password) throw new ActionError('Email and password are required');
+
+  const user = await db.findUser(email);
+  if (!user || !await verify(password, user.passwordHash)) {
+    throw new ActionError('Invalid credentials');
+  }
+}
+```
+
+In the template, the action's state object is available under its function name:
+
+```html
+<script>
+  import { signIn } from '$database/auth';
+</script>
+
+<form action={signIn}>
+  (signIn.error ? `<p class="error">${signIn.error}</p>` : '')
+  <input type="email" name="email" />
+  <input type="password" name="password" />
+  <button type="submit">Sign in</button>
+</form>
+```
+
+The state object shape: `{ error?: string, loading: boolean, success: boolean }`.
+
+- `actionName.error` — set on `ActionError` throw, cleared on next successful action
+- `actionName.loading` — set by the client bridge during form submission (CSS target: `form[data-action-loading]`)
+- `actionName.success` — reserved for future use
+
+Throwing a plain `Error` instead of `ActionError` keeps the message hidden in production and shows a generic "Action failed" message. Use `ActionError` for expected validation failures; let plain errors propagate for unexpected crashes.
+
+### Load errors
+
+Throw `PageError` from a route's load scope to return the correct HTTP error page. Without it, any thrown error becomes a 500.
+
+```ts
+import { PageError } from '@kuratchi/js';
+
+// In src/routes/posts/[id]/page.html <script> block:
+const post = await db.posts.findOne({ id: params.id });
+if (!post) throw new PageError(404);
+if (!post.isPublished && !currentUser?.isAdmin) throw new PageError(403);
+```
+
+`PageError` accepts any HTTP status. The framework renders the matching custom error page (`src/routes/404.html`, `src/routes/500.html`, etc.) if one exists, otherwise falls back to the built-in error page.
+
+```ts
+throw new PageError(404);                          // → 404 page
+throw new PageError(403, 'Admin only');            // → 403 page, message shown in dev
+throw new PageError(401, 'Login required');        // → 401 page
+```
+
+For soft load failures where the page should still render (e.g. a widget that failed to fetch), return the error as data from `load()` and handle it in the template:
+
+```html
+<script>
+  const { data: recommendations, error: recError } = await safeGetRecommendations();
+</script>
+
+(recError ? '<p class="notice">Could not load recommendations.</p>' : '')
+for (const rec of (recommendations ?? [])) {
+  <article>{rec.title}</article>
+}
+```
+
 ## Progressive enhancement
 
 These `data-*` attributes wire up client-side interactivity without writing JavaScript.
@@ -239,53 +355,93 @@ for (const todo of todos) {
 
 ## RPC
 
-Export an `rpc` object from a route to expose server functions callable from client-side JavaScript. RPC names are replaced with opaque IDs at compile time — real function names are never exposed to the client.
+For Durable Objects, RPC is file-driven and automatic.
+
+- Put handler logic in a `.do.ts` file.
+- Exported functions in that file become RPC methods.
+- Import RPC methods from `$durable-objects/<file-name-without-.do>`.
 
 ```html
 <script>
-  import { getCount } from '$database/items';
-
-  export const rpc = {
-    getCount,
-  };
+  import { getOrgUsers, createOrgUser } from '$durable-objects/auth';
+  const users = await getOrgUsers();
 </script>
+
+<form action={createOrgUser} method="POST">
+  <input type="email" name="email" required />
+  <button type="submit">Create</button>
+</form>
 ```
+## Durable Objects
 
-Call from the client using the generated `rpc` helper:
+Durable Object behavior is enabled by filename suffix.
 
-```html
-<script client>
-  const result = await rpc.getCount();
-</script>
+- Any file ending in `.do.ts` is treated as a Durable Object handler file.
+- Any file not ending in `.do.ts` is treated as a normal server module.
+- No required folder name. `src/server/auth.do.ts`, `src/server/foo/bar/sites.do.ts`, etc. all work.
+
+### Function mode (recommended)
+
+Write plain exported functions in a `.do.ts` file. Exported functions become DO RPC methods.
+Use `this.db`, `this.env`, and `this.ctx` inside those functions.
+
+```ts
+// src/server/auth/auth.do.ts
+import { getCurrentUser, hashPassword } from '@kuratchi/auth';
+import { redirect } from '@kuratchi/js';
+
+async function randomPassword(length = 24): Promise<string> {
+  const alphabet = 'ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz23456789';
+  const bytes = new Uint8Array(length);
+  crypto.getRandomValues(bytes);
+  let out = '';
+  for (let i = 0; i < length; i++) out += alphabet[bytes[i] % alphabet.length];
+  return out;
+}
+
+export async function getOrgUsers() {
+  const result = await this.db.users.orderBy({ createdAt: 'asc' }).many();
+  return result.data ?? [];
+}
+
+export async function createOrgUser(formData: FormData) {
+  const user = await getCurrentUser();
+  if (!user?.orgId) throw new Error('Not authenticated');
+
+  const email = String(formData.get('email') ?? '').trim().toLowerCase();
+  if (!email) throw new Error('Email is required');
+
+  const passwordHash = await hashPassword(await randomPassword(), undefined, this.env.AUTH_SECRET);
+  await this.db.users.insert({ email, role: 'member', passwordHash });
+  redirect('/settings/users');
+}
 ```
 
-## Durable Objects
+Optional lifecycle exports in function mode:
 
-Extend `kuratchiDO` to create a Durable Object class backed by SQLite. The `static binding` name must match the binding in `wrangler.jsonc`.
+- `export async function onInit()`
+- `export async function onAlarm(...args)`
+- `export function onMessage(...args)`
+
+These lifecycle names are not exposed as RPC methods.
+
+### Class mode (optional)
+
+Class-based handlers are still supported in `.do.ts` files:
 
 ```ts
-// src/server/notes.do.ts
 import { kuratchiDO } from '@kuratchi/js';
-import type { Note } from '../schemas/notes';
 
 export default class NotesDO extends kuratchiDO {
   static binding = 'NOTES_DO';
 
-  async getNotes(): Promise<Note[]> {
+  async getNotes() {
     return (await this.db.notes.orderBy({ created_at: 'desc' }).many()).data ?? [];
   }
-
-  async addNote(title: string): Promise<void> {
-    await this.db.notes.insert({ title });
-  }
-
-  async deleteNote(id: number): Promise<void> {
-    await this.db.notes.delete({ id });
-  }
 }
 ```
 
-Declare it in `kuratchi.config.ts` and in `wrangler.jsonc`. The compiler exports it from `.kuratchi/worker.js` automatically.
+Declare it in `kuratchi.config.ts` and in `wrangler.jsonc`. The compiler exports DO classes from `.kuratchi/worker.js` automatically.
 
 ```jsonc
 // wrangler.jsonc
@@ -298,22 +454,6 @@ Declare it in `kuratchi.config.ts` and in `wrangler.jsonc`. The compiler exports
   ]
 }
 ```
-
-Call DO methods from your route via a stub module in `src/database/`:
-
-```ts
-// src/database/notes.ts
-import { env } from 'cloudflare:workers';
-
-function getStub() {
-  return (env as any).NOTES_DO.get((env as any).NOTES_DO.idFromName('global'));
-}
-
-export const getNotes = () => getStub().getNotes();
-export const addNote  = (title: string) => getStub().addNote(title);
-export const deleteNote = (id: number) => getStub().deleteNote(id);
-```
-
 ## Runtime APIs
 
 These are available anywhere in server-side route code:
@@ -330,7 +470,26 @@ import {
 } from '@kuratchi/js';
 ```
 
-Environment bindings are accessed directly via the Cloudflare Workers API — no framework wrapper needed:
+## Environment bindings
+
+Cloudflare env is server-only.
+
+- Route top-level `<script>`, route `load()` functions, server actions, API handlers, and other server modules can read env.
+- Templates, components, and client `<script>` blocks cannot read env directly.
+- If a value must reach the browser, compute it in the server route script and reference it in the template, or return it from `load()` explicitly.
+
+```html
+<script>
+  import { env } from 'cloudflare:workers';
+  const turnstileSiteKey = env.TURNSTILE_SITE_KEY || '';
+</script>
+
+if (turnstileSiteKey) {
+  <div class="cf-turnstile" data-sitekey={turnstileSiteKey}></div>
+}
+```
+
+Server modules can still access env directly:
 
 ```ts
 import { env } from 'cloudflare:workers';
@@ -357,7 +516,10 @@ export default defineConfig({
     },
   }),
   durableObjects: {
-    NOTES_DO: { className: 'NotesDO' },
+    NOTES_DO: {
+      className: 'NotesDO',
+      files: ['notes.do.ts'],
+    },
   },
   auth: kuratchiAuthConfig({
     cookieName: 'kuratchi_session',
@@ -375,6 +537,20 @@ npx kuratchi build   # one-shot build
 npx kuratchi watch   # watch mode (for use with wrangler dev)
 ```
 
+## Testing the Framework
+
+Run framework tests from `packages/kuratchi-js`:
+
+```bash
+bun run test
+```
+
+Watch mode:
+
+```bash
+bun run test:watch
+```
+
 ## TypeScript & Worker types
 
 ```bash

package/dist/cli.js

@@ -5,6 +5,7 @@
 import { compile } from './compiler/index.js';
 import * as path from 'node:path';
 import * as fs from 'node:fs';
+import * as net from 'node:net';
 import { spawn } from 'node:child_process';
 const args = process.argv.slice(2);
 const command = args[0];
@@ -79,24 +80,65 @@ function runWatch(withWrangler = false) {
     // `kuratchi dev` also starts the wrangler dev server.
     // `kuratchi watch` is the compiler-only mode for custom setups.
     if (withWrangler) {
-        const wranglerArgs = ['wrangler', 'dev', '--port', '8787'];
-        const wrangler = spawn('npx', wranglerArgs, {
-            cwd: projectDir,
-            stdio: 'inherit',
-            shell: process.platform === 'win32',
+        startWranglerDev().catch((err) => {
+            console.error(`[kuratchi] Failed to start wrangler dev: ${err?.message ?? err}`);
+            process.exit(1);
         });
-        const cleanup = () => {
-            if (!wrangler.killed)
-                wrangler.kill();
-        };
-        process.on('exit', cleanup);
-        process.on('SIGINT', () => { cleanup(); process.exit(0); });
-        process.on('SIGTERM', () => { cleanup(); process.exit(0); });
-        wrangler.on('exit', (code) => {
-            if (code !== 0 && code !== null) {
-                console.error(`[kuratchi] wrangler exited with code ${code}`);
-            }
-            process.exit(code ?? 0);
+    }
+}
+function hasPortFlag(inputArgs) {
+    for (let i = 0; i < inputArgs.length; i++) {
+        const arg = inputArgs[i];
+        if (arg === '--port' || arg === '-p')
+            return true;
+        if (arg.startsWith('--port='))
+            return true;
+        if (arg.startsWith('-p='))
+            return true;
+    }
+    return false;
+}
+function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', () => resolve(false));
+        server.once('listening', () => {
+            server.close(() => resolve(true));
         });
+        server.listen(port, '127.0.0.1');
+    });
+}
+async function findOpenPort(start = 8787, end = 8899) {
+    for (let port = start; port <= end; port++) {
+        if (await isPortAvailable(port))
+            return port;
+    }
+    throw new Error(`No open dev port found in range ${start}-${end}`);
+}
+async function startWranglerDev() {
+    const passthroughArgs = args.slice(1);
+    const wranglerArgs = ['wrangler', 'dev', ...passthroughArgs];
+    if (!hasPortFlag(passthroughArgs)) {
+        const port = await findOpenPort();
+        wranglerArgs.push('--port', String(port));
+        console.log(`[kuratchi] Starting wrangler dev on port ${port}`);
     }
+    const wrangler = spawn('npx', wranglerArgs, {
+        cwd: projectDir,
+        stdio: 'inherit',
+        shell: process.platform === 'win32',
+    });
+    const cleanup = () => {
+        if (!wrangler.killed)
+            wrangler.kill();
+    };
+    process.on('exit', cleanup);
+    process.on('SIGINT', () => { cleanup(); process.exit(0); });
+    process.on('SIGTERM', () => { cleanup(); process.exit(0); });
+    wrangler.on('exit', (code) => {
+        if (code !== 0 && code !== null) {
+            console.error(`[kuratchi] wrangler exited with code ${code}`);
+        }
+        process.exit(code ?? 0);
+    });
 }

package/dist/compiler/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * Compiler — scans a project's routes/ directory, parses .html files,
+ * Compiler â€" scans a project's routes/ directory, parses .html files,
  * and generates a single Worker entry point.
  */
 export { parseFile } from './parser.js';
@@ -27,7 +27,7 @@ export interface CompiledRoute {
 /**
  * Compile a project's src/routes/ into .kuratchi/routes.js
  *
- * The generated module exports { app } — an object with a fetch() method
+ * The generated module exports { app } â€" an object with a fetch() method
  * that handles routing, load functions, form actions, and rendering.
  * Returns the path to .kuratchi/worker.js — the stable wrangler entry point that
  * re-exports everything from routes.js (default fetch handler + named DO class exports).