@kuratchi/js 0.0.14 → 0.0.16

package/README.md

@@ -16,9 +16,9 @@ cd my-app
 bun run dev
 ```
 
-## How it works
-
-`kuratchi build` (or `kuratchi watch`) scans `src/routes/` and generates framework output:
+## How it works
+
+`kuratchi build` (or `kuratchi watch`) scans `src/routes/` and generates framework output:
 
 | File | Purpose |
 |---|---|
@@ -26,11 +26,13 @@ bun run dev
 | `.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.**
-
-```jsonc
-// wrangler.jsonc
-{
+Point wrangler at the entry and you're done. **No `src/index.ts` needed.**
+
+For the framework's internal compiler/runtime orchestration and tracked implementation roadmap, see [ARCHITECTURE.md](./ARCHITECTURE.md).
+
+```jsonc
+// wrangler.jsonc
+{
   "main": ".kuratchi/worker.js"
 }
 ```
@@ -349,14 +351,31 @@ Navigate to a URL on click (respects `http:`/`https:` only):
 
 ### `data-poll` — polling
 
-Refresh a section automatically on an interval (milliseconds):
+Poll and update an element's content at a human-readable interval with automatic exponential backoff:
 
 ```html
-<div data-refresh="/status" data-poll="3000">
+<div data-poll={getStatus(itemId)} data-interval="2s">
   {status}
 </div>
 ```
 
+**How it works:**
+1. Client sends a fragment request with `x-kuratchi-fragment` header
+2. Server re-renders the route but returns **only the fragment's innerHTML** — not the full page
+3. Client swaps the element's content — minimal payload, no full page reload
+
+This fragment-based architecture is the foundation for partial rendering and scales to Astro-style islands.
+
+**Interval formats:**
+- `2s` — 2 seconds
+- `500ms` — 500 milliseconds
+- `1m` — 1 minute
+- Default: `30s` with exponential backoff (30s → 45s → 67s → ... capped at 5 minutes)
+
+**Options:**
+- `data-interval` — polling interval (human-readable, default `30s`)
+- `data-backoff="false"` — disable exponential backoff
+
 ### `data-select-all` / `data-select-item` — checkbox groups
 
 Sync a "select all" checkbox with a group of item checkboxes:
@@ -397,79 +416,87 @@ Durable Object behavior is enabled by filename suffix.
 - 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)
+### Writing a Durable Object
 
-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.
+Extend the native Cloudflare `DurableObject` class. Public methods automatically become RPC-accessible:
 
 ```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;
-}
+// src/server/user.do.ts
+import { DurableObject } from 'cloudflare:workers';
 
-export async function getOrgUsers() {
-  const result = await this.db.users.orderBy({ createdAt: 'asc' }).many();
-  return result.data ?? [];
-}
+export default class UserDO extends DurableObject {
+  async getName() {
+    return await this.ctx.storage.get('name');
+  }
 
-export async function createOrgUser(formData: FormData) {
-  const user = await getCurrentUser();
-  if (!user?.orgId) throw new Error('Not authenticated');
+  async setName(name: string) {
+    this._validate(name);
+    await this.ctx.storage.put('name', name);
+  }
 
-  const email = String(formData.get('email') ?? '').trim().toLowerCase();
-  if (!email) throw new Error('Email is required');
+  // NOT RPC-accessible (underscore prefix)
+  _validate(name: string) {
+    if (!name) throw new Error('Name required');
+  }
 
-  const passwordHash = await hashPassword(await randomPassword(), undefined, this.env.AUTH_SECRET);
-  await this.db.users.insert({ email, role: 'member', passwordHash });
-  redirect('/settings/users');
+  // NOT RPC-accessible (lifecycle method)
+  async alarm() {
+    // Handle alarm
+  }
 }
 ```
 
-Optional lifecycle exports in function mode:
+**RPC rules:**
+- **Public methods** (`getName`, `setName`) → RPC-accessible
+- **Underscore prefix** (`_validate`) → NOT RPC-accessible
+- **Private/protected** (`private foo()`) → NOT RPC-accessible
+- **Lifecycle methods** (`constructor`, `fetch`, `alarm`, `webSocketMessage`, etc.) → NOT RPC-accessible
 
-- `export async function onInit()`
-- `export async function onAlarm(...args)`
-- `export function onMessage(...args)`
+### Using from routes
 
-These lifecycle names are not exposed as RPC methods.
+Import from `$do/<filename>` (without the `.do` suffix):
 
-### Class mode (optional)
+```html
+<script server>
+import { getName, setName } from '$do/user';
 
-Class-based handlers are still supported in `.do.ts` files:
+const name = await getName();
+</script>
 
-```ts
-import { kuratchiDO } from '@kuratchi/js';
+<h1>Hello, {name}</h1>
+```
 
-export default class NotesDO extends kuratchiDO {
-  static binding = 'NOTES_DO';
+The framework handles RPC wiring automatically.
 
-  async getNotes() {
-    return (await this.db.notes.orderBy({ created_at: 'desc' }).many()).data ?? [];
-  }
+### Auto-Discovery
+
+Durable Objects are auto-discovered from `.do.ts` files. **No config needed.**
+
+**Naming convention:**
+- `user.do.ts` → binding `USER_DO`
+- `org-settings.do.ts` → binding `ORG_SETTINGS_DO`
+
+**Override binding name** with `static binding`:
+```ts
+export default class UserDO extends DurableObject {
+  static binding = 'CUSTOM_BINDING';  // Optional override
+  // ...
 }
 ```
 
-Declare it in `kuratchi.config.ts` and in `wrangler.jsonc`. The compiler exports DO classes from `.kuratchi/worker.js` automatically.
+The framework auto-syncs discovered DOs to `wrangler.jsonc`.
 
-```jsonc
-// wrangler.jsonc
-{
-  "durable_objects": {
-    "bindings": [{ "name": "NOTES_DO", "class_name": "NotesDO" }]
+### Optional: stubId for auth integration
+
+If you need automatic stub resolution based on user context, add `stubId` in `kuratchi.config.ts`:
+
+```ts
+// kuratchi.config.ts
+export default defineConfig({
+  durableObjects: {
+    USER_DO: { stubId: 'user.orgId' },  // Only needed for auth integration
   },
-  "migrations": [
-    { "tag": "v1", "new_sqlite_classes": ["NotesDO"] }
-  ]
-}
+});
 ```
 
 ## Agents
@@ -542,6 +569,46 @@ Examples:
 - `bond.workflow.ts` → `BOND_WORKFLOW` binding
 - `new-site.workflow.ts` → `NEW_SITE_WORKFLOW` binding
 
+### Workflow Status Polling
+
+Kuratchi auto-generates status polling RPCs for each discovered workflow. Poll workflow status with zero setup:
+
+```html
+<div data-poll={migrationWorkflowStatus(instanceId)} data-interval="2s">
+  if (workflowStatus.status === 'running') {
+    <div class="spinner">Running...</div>
+  } else if (workflowStatus.status === 'complete') {
+    <div>✓ Complete</div>
+  }
+</div>
+```
+
+The element's innerHTML updates automatically when the workflow status changes — no page reload needed.
+
+**Auto-generated RPC naming** (camelCase):
+- `migration.workflow.ts` → `migrationWorkflowStatus(instanceId)`
+- `james-bond.workflow.ts` → `jamesBondWorkflowStatus(instanceId)`
+- `site.workflow.ts` → `siteWorkflowStatus(instanceId)`
+
+**Multiple workflows on one page:** Each `data-poll` element is independent. You can poll multiple workflow instances without collision:
+
+```html
+for (const job of jobs) {
+  <div data-poll={migrationWorkflowStatus(job.instanceId)} data-interval="2s">
+    {job.name}: polling...
+  </div>
+}
+```
+
+The status RPC returns the Cloudflare `InstanceStatus` object:
+```ts
+{
+  status: 'queued' | 'running' | 'paused' | 'errored' | 'terminated' | 'complete' | 'waiting' | 'unknown';
+  error?: { name: string; message: string; };
+  output?: unknown;
+}
+```
+
 ## Containers
 
 Kuratchi auto-discovers `.container.ts` files in `src/server/`. **No config needed.**
@@ -701,7 +768,9 @@ Kuratchi also exposes a framework build-mode flag:
 
 ## `kuratchi.config.ts`
 
-Optional. Required only when using framework integrations or Durable Objects.
+Optional. Required only when using framework integrations (ORM, auth, UI).
+
+**Durable Objects are auto-discovered** — no config needed unless you need `stubId` for auth integration.
 
 ```ts
 import { defineConfig } from '@kuratchi/js';
@@ -717,16 +786,14 @@ export default defineConfig({
       NOTES_DO: { schema: notesSchema, type: 'do' },
     },
   }),
-  durableObjects: {
-    NOTES_DO: {
-      className: 'NotesDO',
-      files: ['notes.do.ts'],
-    },
-  },
   auth: kuratchiAuthConfig({
     cookieName: 'kuratchi_session',
     sessionEnabled: true,
   }),
+  // Optional: only needed for auth-based stub resolution
+  durableObjects: {
+    NOTES_DO: { stubId: 'user.orgId' },
+  },
 });
 ```
 

package/dist/cli.js

@@ -6,34 +6,41 @@ 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 { createRequire } from 'node:module';
 import { spawn } from 'node:child_process';
 const args = process.argv.slice(2);
 const command = args[0];
 const projectDir = process.cwd();
-switch (command) {
-    case 'build':
-        runBuild();
-        break;
-    case 'watch':
-        runWatch(false);
-        break;
-    case 'dev':
-        runWatch(true);
-        break;
-    case 'create':
-        runCreate();
-        break;
-    default:
-        console.log(`
-KuratchiJS CLI
-
-Usage:
-  kuratchi create [name]  Scaffold a new KuratchiJS project
-  kuratchi build          Compile routes once
-  kuratchi dev            Compile, watch for changes, and start wrangler dev server
-  kuratchi watch          Compile + watch only (no wrangler — for custom setups)
+void main().catch((err) => {
+    console.error(`[kuratchi] ${err?.message ?? err}`);
+    process.exit(1);
+});
+async function main() {
+    switch (command) {
+        case 'build':
+            runBuild();
+            return;
+        case 'watch':
+            await runWatch(false);
+            return;
+        case 'dev':
+            await runWatch(true);
+            return;
+        case 'create':
+            await runCreate();
+            return;
+        default:
+            console.log(`
+KuratchiJS CLI
+
+Usage:
+  kuratchi create [name]  Scaffold a new KuratchiJS project
+  kuratchi build          Compile routes once
+  kuratchi dev            Compile, watch for changes, and start wrangler dev server
+  kuratchi watch          Compile + watch only (no wrangler — for custom setups)
 `);
-        process.exit(1);
+            process.exit(1);
+    }
 }
 async function runCreate() {
     const { create } = await import('./create.js');
@@ -53,7 +60,7 @@ function runBuild(isDev = false) {
         process.exit(1);
     }
 }
-function runWatch(withWrangler = false) {
+async function runWatch(withWrangler = false) {
     runBuild(true);
     const routesDir = path.join(projectDir, 'src', 'routes');
     const serverDir = path.join(projectDir, 'src', 'server');
@@ -80,11 +87,10 @@ function runWatch(withWrangler = false) {
     // `kuratchi dev` also starts the wrangler dev server.
     // `kuratchi watch` is the compiler-only mode for custom setups.
     if (withWrangler) {
-        startWranglerDev().catch((err) => {
-            console.error(`[kuratchi] Failed to start wrangler dev: ${err?.message ?? err}`);
-            process.exit(1);
-        });
+        await startWranglerDev();
+        return;
     }
+    await new Promise(() => { });
 }
 function hasPortFlag(inputArgs) {
     for (let i = 0; i < inputArgs.length; i++) {
@@ -117,25 +123,13 @@ async function findOpenPort(start = 8787, end = 8899) {
 }
 async function startWranglerDev() {
     const passthroughArgs = args.slice(1);
-    const wranglerArgs = ['wrangler', 'dev', ...passthroughArgs];
+    const wranglerArgs = ['dev', ...passthroughArgs];
     if (!hasPortFlag(passthroughArgs)) {
         const port = await findOpenPort();
         wranglerArgs.push('--port', String(port));
         console.log(`[kuratchi] Starting wrangler dev on port ${port}`);
     }
-    // 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 wrangler = spawnWranglerProcess(wranglerArgs);
     const cleanup = () => {
         if (!wrangler.killed)
             wrangler.kill();
@@ -143,10 +137,49 @@ async function startWranglerDev() {
     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);
+    await new Promise((resolve, reject) => {
+        wrangler.on('exit', (code) => {
+            if (code !== 0 && code !== null) {
+                reject(new Error(`wrangler exited with code ${code}`));
+                return;
+            }
+            resolve();
+        });
+        wrangler.on('error', (err) => {
+            reject(err);
+        });
+    }).catch((err) => {
+        console.error(`[kuratchi] Failed to start wrangler dev: ${err?.message ?? err}`);
+        process.exit(1);
+    });
+}
+function resolveWranglerBin() {
+    try {
+        const projectPackageJson = path.join(projectDir, 'package.json');
+        const projectRequire = createRequire(projectPackageJson);
+        return projectRequire.resolve('wrangler/bin/wrangler.js');
+    }
+    catch {
+        return null;
+    }
+}
+function getNodeExecutable() {
+    if (!process.versions.bun)
+        return process.execPath;
+    return 'node';
+}
+function spawnWranglerProcess(wranglerArgs) {
+    const localWranglerBin = resolveWranglerBin();
+    const stdio = ['pipe', 'inherit', 'inherit'];
+    if (localWranglerBin) {
+        return spawn(getNodeExecutable(), [localWranglerBin, ...wranglerArgs], {
+            cwd: projectDir,
+            stdio,
+        });
+    }
+    const fallbackCommand = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+    return spawn(fallbackCommand, ['wrangler', ...wranglerArgs], {
+        cwd: projectDir,
+        stdio,
     });
 }

package/dist/compiler/api-route-pipeline.d.ts

@@ -0,0 +1,8 @@
+export declare function compileApiRoute(opts: {
+    pattern: string;
+    fullPath: string;
+    projectDir: string;
+    transformModule: (entryAbsPath: string) => string;
+    allocateModuleId: () => string;
+    pushImport: (statement: string) => void;
+}): string;

package/dist/compiler/api-route-pipeline.js

@@ -0,0 +1,23 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const ALL_API_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+export function compileApiRoute(opts) {
+    const outFileDir = path.join(opts.projectDir, '.kuratchi');
+    const absRoutePath = opts.transformModule(opts.fullPath);
+    let importPath = path.relative(outFileDir, absRoutePath).replace(/\\/g, '/');
+    if (!importPath.startsWith('.'))
+        importPath = './' + importPath;
+    const moduleId = opts.allocateModuleId();
+    opts.pushImport(`import * as ${moduleId} from '${importPath}';`);
+    const apiSource = fs.readFileSync(opts.fullPath, 'utf-8');
+    const exportedMethods = ALL_API_METHODS.filter((method) => {
+        const fnPattern = new RegExp(`export\\s+(async\\s+)?function\\s+${method}\\b`);
+        const reExportPattern = new RegExp(`export\\s*\\{[^}]*\\b\\w+\\s+as\\s+${method}\\b`);
+        const namedExportPattern = new RegExp(`export\\s*\\{[^}]*\\b${method}\\b`);
+        return fnPattern.test(apiSource) || reExportPattern.test(apiSource) || namedExportPattern.test(apiSource);
+    });
+    const methodEntries = exportedMethods
+        .map((method) => `${method}: ${moduleId}.${method}`)
+        .join(', ');
+    return `{ pattern: '${opts.pattern}', __api: true, ${methodEntries} }`;
+}

package/dist/compiler/asset-pipeline.d.ts

@@ -0,0 +1,7 @@
+export interface CompiledAsset {
+    name: string;
+    content: string;
+    mime: string;
+    etag: string;
+}
+export declare function compileAssets(assetsDir: string): CompiledAsset[];

package/dist/compiler/asset-pipeline.js

@@ -0,0 +1,33 @@
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const MIME_TYPES = {
+    '.css': 'text/css; charset=utf-8',
+    '.js': 'text/javascript; charset=utf-8',
+    '.json': 'application/json; charset=utf-8',
+    '.svg': 'image/svg+xml',
+    '.txt': 'text/plain; charset=utf-8',
+};
+export function compileAssets(assetsDir) {
+    const compiledAssets = [];
+    if (!fs.existsSync(assetsDir))
+        return compiledAssets;
+    const scanAssets = (dir, prefix) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+            if (entry.isDirectory()) {
+                scanAssets(path.join(dir, entry.name), prefix ? `${prefix}/${entry.name}` : entry.name);
+                continue;
+            }
+            const ext = path.extname(entry.name).toLowerCase();
+            const mime = MIME_TYPES[ext];
+            if (!mime)
+                continue;
+            const content = fs.readFileSync(path.join(dir, entry.name), 'utf-8');
+            const etag = '"' + crypto.createHash('md5').update(content).digest('hex').slice(0, 12) + '"';
+            const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+            compiledAssets.push({ name, content, mime, etag });
+        }
+    };
+    scanAssets(assetsDir, '');
+    return compiledAssets;
+}

package/dist/compiler/client-module-pipeline.d.ts

@@ -0,0 +1,25 @@
+import type { CompiledAsset } from './asset-pipeline.js';
+import { type RouteImportEntry } from './import-linking.js';
+export interface ClientEventRegistration {
+    routeId: string;
+    handlerId: string;
+    argsExpr: string | null;
+}
+export interface ClientModuleCompiler {
+    createRegistry(scopeId: string, importEntries: RouteImportEntry[]): ClientRouteRegistry;
+    createRouteRegistry(routeIndex: number, importEntries: RouteImportEntry[]): ClientRouteRegistry;
+    getCompiledAssets(): CompiledAsset[];
+}
+export interface ClientRouteRegistry {
+    hasBindings(): boolean;
+    hasBindingReference(expression: string): boolean;
+    registerEventHandler(eventName: string, expression: string): ClientEventRegistration | null;
+    buildEntryAsset(): {
+        assetName: string;
+        asset: CompiledAsset;
+    } | null;
+}
+export declare function createClientModuleCompiler(opts: {
+    projectDir: string;
+    srcDir: string;
+}): ClientModuleCompiler;