@kuratchi/js 0.0.9 → 0.0.11

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.**
@@ -211,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';
@@ -470,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:
@@ -481,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.

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.
  */