@kuratchi/js 0.0.8 → 0.0.10

package/README.md

@@ -23,7 +23,7 @@ bun run dev
 | 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 plus all Durable Object and Agent 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.**
@@ -46,6 +46,18 @@ src/routes/blog/[slug]/page.html → /blog/:slug
 src/routes/layout.html        → shared layout wrapping all routes
 ```
 
+### Execution model
+
+Kuratchi routes are server-first.
+
+- `src/routes` defines server-rendered route modules.
+- Top-level route `<script>` blocks run on the server.
+- Template expressions, `if`, and `for` blocks render on the server.
+- `src/server` is for private server-only modules and reusable backend logic.
+- Reactive `$:` code is the browser-only escape hatch.
+
+Route files are not client files. They are server-rendered routes that can opt into small browser-side reactive behavior when needed.
+
 ### Route file structure
 
 ```html
@@ -64,6 +76,7 @@ src/routes/layout.html        → shared layout wrapping all routes
 ```
 
 The `$database/` alias resolves to `src/database/`. You can use any path alias configured in your tsconfig.
+Private server logic should live in `src/server/` and be imported into routes explicitly.
 
 ### Layout file
 
@@ -161,9 +174,11 @@ Block form is also supported:
 ```
 
 Notes:
-- This reactivity runs in browser scripts rendered in the template markup, not in the top server route `<script>` load/action block.
+- Route files are server-rendered by default. `$:` is the only browser-side execution primitive in a route template.
+- This reactivity runs in browser scripts rendered in the template markup, not in the top server route `<script>` 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.
+- You should not need `if (browser)` style guards in normal Kuratchi route code. If browser checks become necessary outside `$:`, the boundary is likely in the wrong place.
 
 ## Form actions
 
@@ -196,7 +211,7 @@ export async function addItem(formData: FormData): Promise<void> {
 
 ### Redirect after action
 
-Call `redirect()` inside an action to send the user to a different URL after the POST:
+Call `redirect()` inside an action or `load()` to immediately exit and send the user to a different URL. `throw redirect()` also works, but is redundant because `redirect()` already throws:
 
 ```ts
 import { redirect } from '@kuratchi/js';
@@ -360,6 +375,7 @@ 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>`.
+- RPC methods are still server-side code. They are exposed intentionally by the framework runtime, not because route files are client-side.
 
 ```html
 <script>
@@ -454,6 +470,44 @@ Declare it in `kuratchi.config.ts` and in `wrangler.jsonc`. The compiler exports
   ]
 }
 ```
+
+## Agents
+
+Kuratchi treats `src/server/**/*.agent.ts` as a first-class Worker export convention.
+
+- Any `.agent.ts` file under `src/server/` is scanned during build.
+- The file must export a class with either `export class MyAgent` or `export default class MyAgent`.
+- The compiler re-exports that class from `.kuratchi/worker.js`, so Wrangler can bind it directly.
+- `.agent.ts` files are not route modules and are not converted into `$durable-objects/*` RPC proxies.
+
+```ts
+// src/server/ai/session.agent.ts
+import { Agent } from 'agents';
+
+export class SessionAgent extends Agent {
+  async onRequest() {
+    return Response.json({ ok: true });
+  }
+}
+```
+
+```jsonc
+// wrangler.jsonc
+{
+  "durable_objects": {
+    "bindings": [{ "name": "AI_SESSION", "class_name": "SessionAgent" }]
+  },
+  "migrations": [
+    { "tag": "v1", "new_sqlite_classes": ["SessionAgent"] }
+  ]
+}
+```
+
+Failure and edge behavior:
+
+- If a `.agent.ts` file does not export a class, the build fails.
+- Kuratchi only auto-discovers `.agent.ts` files under `src/server/`.
+- You still need Wrangler Durable Object bindings and migrations because Agents run as Durable Objects.
 ## Runtime APIs
 
 These are available anywhere in server-side route code:
@@ -465,11 +519,29 @@ import {
   getLocals,   // mutable locals bag for the current request
   getParams,   // URL params ({ slug: 'foo' })
   getParam,    // getParam('slug')
-  redirect,    // redirect('/path', 302)
+  RedirectError, // redirect signal thrown by redirect()\r\n  redirect,      // redirect('/path', 302)\r\n  goto,          // same as redirect()
   goto,        // same as redirect — alias
 } from '@kuratchi/js';
 ```
 
+### Request helpers
+
+For a batteries-included request layer, import pre-parsed request state from `@kuratchi/js/request`:
+
+```ts
+import { url, pathname, searchParams, slug } from '@kuratchi/js/request';
+
+const page = pathname;
+const tab = searchParams.get('tab');
+const postSlug = slug;
+```
+
+- `url` is the parsed `URL` for the current request.
+- `pathname` is the full path, like `/blog/hello-world`.
+- `searchParams` is `url.searchParams` for the current request.
+- `slug` is `params.slug` when the matched route defines a `slug` param.
+- `headers`, `method`, and `params` are also exported from `@kuratchi/js/request`.
+- Use `getRequest()` when you want the raw native `Request` object.
 ## Environment bindings
 
 Cloudflare env is server-only.
@@ -497,6 +569,24 @@ import { env } from 'cloudflare:workers';
 const result = await env.DB.prepare('SELECT 1').run();
 ```
 
+## Framework environment
+
+Kuratchi also exposes a framework build-mode flag:
+
+```html
+<script>
+  import { dev } from '@kuratchi/js/environment';
+  import { env } from 'cloudflare:workers';
+
+  const turnstileSiteKey = dev ? '' : (env.TURNSTILE_SITE_KEY || '');
+</script>
+```
+
+- `dev` is `true` for Kuratchi development builds
+- `dev` is `false` for production builds
+- `dev` is compile-time framework state, not a generic process env var
+- `@kuratchi/js/environment` is intended for server route code, not client `$:` scripts
+
 ## `kuratchi.config.ts`
 
 Optional. Required only when using framework integrations or Durable Objects.

package/dist/cli.js

@@ -123,11 +123,19 @@ async function startWranglerDev() {
         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',
-    });
+    // Use 'pipe' for stdin so wrangler doesn't detect stdin EOF and exit
+    // prematurely when launched via a script runner (e.g. `bun run dev`).
+    const isWin = process.platform === 'win32';
+    const wrangler = isWin
+        ? spawn('npx ' + wranglerArgs.join(' '), {
+            cwd: projectDir,
+            stdio: ['pipe', 'inherit', 'inherit'],
+            shell: true,
+        })
+        : spawn('npx', wranglerArgs, {
+            cwd: projectDir,
+            stdio: ['pipe', 'inherit', 'inherit'],
+        });
     const cleanup = () => {
         if (!wrangler.killed)
             wrangler.kill();

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,9 +27,9 @@ 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
+ * 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).
  * No src/index.ts is needed in user projects.
  */