@kuratchi/js 0.0.1

package/dist/runtime/do.js

@@ -0,0 +1,123 @@
+/**
+ * KuratchiJS — Durable Object helpers
+ *
+ * kuratchiDO
+ *   Base class for DO handler modules. Extend it, write your methods,
+ *   declare `static binding = 'BINDING_NAME'` — the compiler does the rest.
+ *
+ *   - Methods are copied onto the generated DO class prototype
+ *   - RPC proxy exports are auto-generated for pages
+ *   - Stub resolvers are registered from config
+ *
+ * The compiler uses __registerDoResolver / __getDoStub internally.
+ * User code never touches these — they're wired up from kuratchi.config.ts.
+ */
+// ── Internal: stub resolver registry ────────────────────────
+const _resolvers = new Map();
+const _classBindings = new WeakMap();
+/** @internal — called by compiler-generated init code */
+export function __registerDoResolver(binding, resolver) {
+    _resolvers.set(binding, resolver);
+}
+/** @internal — called by compiler-generated init code */
+export function __registerDoClassBinding(klass, binding) {
+    if (!klass || !binding)
+        return;
+    _classBindings.set(klass, binding);
+}
+/** @internal — called by compiler-generated RPC proxy modules */
+export async function __getDoStub(binding) {
+    const resolver = _resolvers.get(binding);
+    if (!resolver) {
+        throw new Error(`[KuratchiJS] No DO resolver registered for binding '${binding}'. Check your durableObjects config.`);
+    }
+    return resolver();
+}
+// ── kuratchiDO base class ──────────────────────────────────────
+/**
+ * Base class for Durable Object handler modules.
+ *
+ * ```ts
+ * // sites.ts — extend, write methods, done.
+ * export default class Sites extends kuratchiDO {
+ *   static binding = 'ORG_DB';
+ *
+ *   async getSites(userId: number) {
+ *     return (await this.db.sites.where({ userId }).many()).data ?? [];
+ *   }
+ * }
+ * ```
+ *
+ * `this.db` is the ORM instance — set by the generated DO class at runtime.
+ *
+ * Call `Sites.rpc()` in the same file if you need to call DO methods
+ * from worker-side helper functions:
+ *
+ * ```ts
+ * const remote = Sites.rpc();
+ *
+ * export async function createSite(formData: FormData) {
+ *   await remote.createSiteRecord({ name, slug, userId });
+ * }
+ * ```
+ */
+export class kuratchiDO {
+    /** The DO namespace binding this handler belongs to (e.g. 'ORG_DB'). */
+    static binding;
+    /**
+     * Implicit RPC proxy getter.
+     *
+     * Lets handler modules call `MyDO.remote.someMethod()` without declaring
+     * `const remote = MyDO.rpc();` boilerplate.
+     */
+    static get remote() {
+        return this.rpc();
+    }
+    /**
+     * Create a typed RPC proxy for calling DO methods from worker-side code.
+     * The actual stub resolution is lazy — happens at call time, not import time.
+     */
+    static rpc() {
+        const klass = this;
+        return new Proxy({}, {
+            get(_, method) {
+                return async (...args) => {
+                    const binding = this.binding || _classBindings.get(klass);
+                    if (!binding) {
+                        throw new Error(`[KuratchiJS] Missing DO binding for class '${this?.name || 'UnknownDO'}'. Add static binding or ensure compiler binding registration is active.`);
+                    }
+                    console.log(`[rpc] ${binding}.${method}() — resolving stub...`);
+                    const stub = await __getDoStub(binding);
+                    if (!stub) {
+                        throw new Error(`[KuratchiJS] Not authenticated — cannot call '${method}' on ${binding}`);
+                    }
+                    console.log(`[rpc] ${binding}.${method}() — stub type: ${stub?.constructor?.name ?? typeof stub}`);
+                    console.log(`[rpc] ${binding}.${method}() — calling with ${args.length} arg(s)...`);
+                    try {
+                        // Call method directly on the stub — DO NOT detach with stub[method]
+                        // then .apply(). Workers RPC stubs are Proxy-based; detaching breaks
+                        // the runtime's interception and causes DataCloneError trying to
+                        // serialize the DurableObject as `this`.
+                        const result = await stub[method](...args);
+                        console.log(`[rpc] ${binding}.${method}() — returned, result type: ${typeof result}`);
+                        return result;
+                    }
+                    catch (err) {
+                        console.error(`[rpc] ${binding}.${method}() — THREW: ${err.message}`);
+                        throw err;
+                    }
+                };
+            },
+        });
+    }
+}
+/**
+ * DX helper for worker-side code in DO handler modules.
+ *
+ * Usage:
+ * `const doSites = doRpc(Sites);`
+ * `await doSites.getSiteBySlug(slug);`
+ */
+export function doRpc(klass) {
+    return klass.rpc();
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,8 @@
+export { createApp } from './app.js';
+export { defineConfig } from './config.js';
+export { Router, filePathToPattern } from './router.js';
+export { getEnv, getCtx, getRequest, getLocals, getParams, getParam, redirect, goto, setBreadcrumbs, getBreadcrumbs, breadcrumbsHome, breadcrumbsPrev, breadcrumbsNext, breadcrumbsCurrent, buildDefaultBreadcrumbs, } from './context.js';
+export { kuratchiDO, doRpc } from './do.js';
+export { extractSubdomainSlug, extractSlugFromPrefix, matchContainerViewPath, rewriteProxyLocationHeader, buildContainerRequest, createContainerEnvVars, startContainer, proxyToContainer, handleContainerRouting, forwardJsonPostToContainerDO, matchSiteViewPath, buildSiteContainerRequest, createWpContainerEnvVars, startSiteContainer, proxyToSiteContainer, } from './containers.js';
+export type { AppConfig, Env, AuthConfig, RouteContext, RouteModule, LayoutModule } from './types.js';
+export type { RpcOf } from './do.js';

package/dist/runtime/index.js

@@ -0,0 +1,8 @@
+export { createApp } from './app.js';
+export { defineConfig } from './config.js';
+export { Router, filePathToPattern } from './router.js';
+export { getEnv, getCtx, getRequest, getLocals, getParams, getParam, redirect, goto, setBreadcrumbs, getBreadcrumbs, breadcrumbsHome, breadcrumbsPrev, breadcrumbsNext, breadcrumbsCurrent, buildDefaultBreadcrumbs, } from './context.js';
+export { kuratchiDO, doRpc } from './do.js';
+export { extractSubdomainSlug, extractSlugFromPrefix, matchContainerViewPath, rewriteProxyLocationHeader, buildContainerRequest, createContainerEnvVars, startContainer, proxyToContainer, handleContainerRouting, forwardJsonPostToContainerDO, 
+// Compatibility aliases
+matchSiteViewPath, buildSiteContainerRequest, createWpContainerEnvVars, startSiteContainer, proxyToSiteContainer, } from './containers.js';

package/dist/runtime/router.d.ts

@@ -0,0 +1,29 @@
+/**
+ * URL router — matches incoming requests to route modules.
+ *
+ * Supports:
+ *   /todos          → static
+ *   /blog/:slug     → named param
+ *   /files/*rest    → catch-all
+ */
+export interface MatchResult {
+    params: Record<string, string>;
+    index: number;
+}
+export declare class Router {
+    private routes;
+    /** Register a pattern (e.g. '/blog/:slug') and associate it with an index. */
+    add(pattern: string, index: number): void;
+    /** Match a pathname against registered routes. Returns null if no match. */
+    match(pathname: string): MatchResult | null;
+}
+/**
+ * Convert a file-system path to a route pattern.
+ *
+ * Examples:
+ *   'index'        → '/'
+ *   'about'        → '/about'
+ *   'blog/[slug]'  → '/blog/:slug'
+ *   'files/[...path]' → '/files/*path'
+ */
+export declare function filePathToPattern(filePath: string): string;

package/dist/runtime/router.js

@@ -0,0 +1,73 @@
+/**
+ * URL router — matches incoming requests to route modules.
+ *
+ * Supports:
+ *   /todos          → static
+ *   /blog/:slug     → named param
+ *   /files/*rest    → catch-all
+ */
+export class Router {
+    routes = [];
+    /** Register a pattern (e.g. '/blog/:slug') and associate it with an index. */
+    add(pattern, index) {
+        const paramNames = [];
+        // Convert pattern to regex
+        // :param  → named capture group
+        // *param  → catch-all capture group
+        let regexStr = pattern
+            // Catch-all: /files/*rest → /files/(?<rest>.+)
+            .replace(/\*(\w+)/g, (_match, name) => {
+            paramNames.push(name);
+            return `(?<${name}>.+)`;
+        })
+            // Named params: /blog/:slug → /blog/(?<slug>[^/]+)
+            .replace(/:(\w+)/g, (_match, name) => {
+            paramNames.push(name);
+            return `(?<${name}>[^/]+)`;
+        });
+        // Anchor
+        regexStr = `^${regexStr}$`;
+        this.routes.push({
+            regex: new RegExp(regexStr),
+            paramNames,
+            index,
+        });
+    }
+    /** Match a pathname against registered routes. Returns null if no match. */
+    match(pathname) {
+        // Normalize: strip trailing slash (except root)
+        const normalized = pathname === '/' ? '/' : pathname.replace(/\/$/, '');
+        for (const route of this.routes) {
+            const m = normalized.match(route.regex);
+            if (m) {
+                const params = {};
+                for (const name of route.paramNames) {
+                    params[name] = m.groups?.[name] ?? '';
+                }
+                return { params, index: route.index };
+            }
+        }
+        return null;
+    }
+}
+/**
+ * Convert a file-system path to a route pattern.
+ *
+ * Examples:
+ *   'index'        → '/'
+ *   'about'        → '/about'
+ *   'blog/[slug]'  → '/blog/:slug'
+ *   'files/[...path]' → '/files/*path'
+ */
+export function filePathToPattern(filePath) {
+    if (filePath === 'index')
+        return '/';
+    let pattern = '/' + filePath
+        // [...param] → *param (catch-all)
+        .replace(/\[\.\.\.(\w+)\]/g, '*$1')
+        // [param] → :param
+        .replace(/\[(\w+)\]/g, ':$1');
+    // Remove trailing /index
+    pattern = pattern.replace(/\/index$/, '') || '/';
+    return pattern;
+}

package/dist/runtime/types.d.ts

@@ -0,0 +1,207 @@
+/**
+ * Core framework types
+ */
+/** Cloudflare Worker env — consumers define their own Env type */
+export type Env = Record<string, any>;
+/** Route context — passed to load functions, actions, and server utilities */
+export interface RouteContext<E extends Env = Env> {
+    /** The incoming Request (standard Web API) */
+    request: Request;
+    /** Cloudflare Worker env — D1, KV, R2, DO, AI, etc. */
+    env: E;
+    /** Cloudflare execution context */
+    ctx: ExecutionContext;
+    /** Route parameters (e.g., { slug: 'hello-world' }) */
+    params: Record<string, string>;
+    /** Request-scoped state (set by middleware, read by load/actions) */
+    locals: Record<string, any>;
+    /** Parsed URL */
+    url: URL;
+}
+/** A compiled route module */
+export interface RouteModule {
+    /** Pattern string (e.g., '/todos', '/blog/:slug') */
+    pattern: string;
+    /** Load function — runs on GET, returns data for the template */
+    load?: (ctx: RouteContext) => Promise<Record<string, any>> | Record<string, any>;
+    /** Form actions — keyed by action name */
+    actions?: Record<string, (formData: FormData, env: Env, ctx: RouteContext) => Promise<any>>;
+    /** RPC functions — callable from client via fetch */
+    rpc?: Record<string, (args: any[], env: Env, ctx: RouteContext) => Promise<any>>;
+    /** Render function — returns HTML string from data */
+    render: (data: Record<string, any>) => string;
+    /** Layout name (default: 'default') */
+    layout?: string;
+}
+/** Layout module */
+export interface LayoutModule {
+    /** Render function — wraps page content */
+    render: (data: {
+        content: string;
+        data: Record<string, any>;
+        head?: string;
+    }) => string;
+}
+/** App configuration (internal — used by compiler-generated code) */
+export interface AppConfig<E extends Env = Env> {
+    /** Route modules — generated by compiler or defined manually */
+    routes?: RouteModule[];
+    /** Layout modules — keyed by name */
+    layouts?: Record<string, LayoutModule>;
+    /** Static file directory (relative to project root) */
+    publicDir?: string;
+}
+/** Database schema config — maps a binding name to its schema */
+export interface DatabaseConfig {
+    /** Schema definition (SchemaDsl or DatabaseSchema from @kuratchi/orm) */
+    schema: any;
+    /** Storage type: 'd1' (default) or 'do' (Durable Object SqlStorage) */
+    type?: 'd1' | 'do';
+    /** Skip migrations for this database (e.g., in production). Default: false */
+    skipMigrations?: boolean;
+}
+/**
+ * Framework configuration — the user-facing config file (kuratchi.config.ts)
+ *
+ * @example
+ * ```ts
+ * // kuratchi.config.ts
+ * import { defineConfig } from '@kuratchi/js';
+ * import { todoSchema } from './src/schemas/todo';
+ *
+ * export default defineConfig({
+ *   orm: {
+ *     databases: {
+ *       DB: { schema: todoSchema }
+ *     }
+ *   }
+ * });
+ * ```
+ */
+export interface kuratchiConfig<E extends Env = Env> {
+    /** ORM configuration — schema definitions and auto-migration */
+    orm?: {
+        /** Map of D1 binding names to their database configs */
+        databases: Record<string, DatabaseConfig>;
+    };
+    /** UI configuration — opt into @kuratchi/ui theme and components */
+    ui?: {
+        /** Theme to inject: 'default' uses @kuratchi/ui's built-in theme, or a path to a custom CSS file */
+        theme?: 'default' | string;
+    };
+    /** Auth configuration — @kuratchi/auth plugin setup */
+    auth?: AuthConfig;
+    /**
+     * Durable Object configuration — config-driven DO class generation.
+     *
+     * Map a DO namespace binding to its class name and optional configuration.
+     * Supports string shorthand or an object with stubId option.
+     *
+     * @example
+     * ```ts
+     * durableObjects: {
+     *   // Object form — stubId tells the framework which user field identifies the stub
+     *   ORG_DB: {
+     *     className: 'OrganizationDO',
+     *     stubId: 'user.orgId'
+     *   },
+     *   // String shorthand — className only, no auto-stub resolution
+     *   CACHE_DB: 'CacheDO'
+     * }
+     * ```
+     */
+    durableObjects?: Record<string, string | {
+        className: string;
+        /** The user field path that identifies the DO stub (e.g. 'user.orgId') */
+        stubId?: string;
+    }>;
+}
+/** Auth configuration for kuratchi.config.ts */
+export interface AuthConfig {
+    /** Session cookie name (default: 'kuratchi_session') */
+    cookieName?: string;
+    /** Auth secret env binding name (default: 'AUTH_SECRET') */
+    secretEnvKey?: string;
+    /** Enable session parsing on every request (default: true) */
+    sessionEnabled?: boolean;
+    /** Credentials config — enables signUp/signIn/signOut/getCurrentUser */
+    credentials?: {
+        /** D1 binding name for auth database (default: 'DB') */
+        binding?: string;
+        /** Default role for new users (default: 'user') */
+        defaultRole?: string;
+        /** Session duration in ms (default: 30 days) */
+        sessionDuration?: number;
+        /** Min password length (default: 8) */
+        minPasswordLength?: number;
+        /** Redirect after signup (default: '/auth/login') */
+        signUpRedirect?: string;
+        /** Redirect after signin (default: '/admin') */
+        signInRedirect?: string;
+        /** Redirect after signout (default: '/auth/login') */
+        signOutRedirect?: string;
+    };
+    /** Activity tracking config — enables logActivity/getActivity */
+    activity?: Record<string, {
+        label: string;
+        severity?: 'info' | 'warning' | 'critical';
+        category?: string;
+    }>;
+    /** Role definitions — enables hasRole/hasPermission/assignRole */
+    roles?: Record<string, string[]>;
+    /** OAuth providers config — enables startOAuth/handleOAuthCallback */
+    oauth?: {
+        providers?: Record<string, {
+            clientIdEnv: string;
+            clientSecretEnv: string;
+            scopes?: string[];
+        }>;
+        /** Redirect after OAuth login (default: '/admin') */
+        loginRedirect?: string;
+    };
+    /** Route guards — protect paths, redirect if not authenticated */
+    guards?: {
+        paths?: string[];
+        exclude?: string[];
+        redirectTo?: string;
+    };
+    /** Rate limiting — throttle requests per route */
+    rateLimit?: {
+        defaultWindowMs?: number;
+        defaultMaxRequests?: number;
+        kvBinding?: string;
+        keyPrefix?: string;
+        routes?: {
+            id?: string;
+            path: string;
+            methods?: string[];
+            maxRequests?: number;
+            windowMs?: number;
+            message?: string;
+        }[];
+    };
+    /** Turnstile bot protection — verify Cloudflare Turnstile tokens */
+    turnstile?: {
+        /** Env var name for Turnstile secret key (default: 'TURNSTILE_SECRET') */
+        secretEnv?: string;
+        /** Env var name for Turnstile site key (default: 'TURNSTILE_SITE_KEY') — exposed to client */
+        siteKeyEnv?: string;
+        /** Skip Turnstile verification in dev mode (default: true) */
+        skipInDev?: boolean;
+        /** Routes that require Turnstile verification */
+        routes?: {
+            id?: string;
+            path: string;
+            methods?: string[];
+            tokenField?: string;
+            tokenHeader?: string;
+            message?: string;
+            expectedAction?: string;
+        }[];
+    };
+    /** Organization multi-tenancy — DO-backed per-org databases */
+    organizations?: {
+        /** DO namespace binding name in env (e.g. 'ORG_DB') */
+        binding: string;
+    };
+}

package/dist/runtime/types.js

@@ -0,0 +1,4 @@
+/**
+ * Core framework types
+ */
+export {};

package/package.json

@@ -0,0 +1,50 @@
+{
+    "name":  "@kuratchi/js",
+    "version":  "0.0.1",
+    "description":  "A thin, Cloudflare Workers-native web framework with Svelte-inspired syntax",
+    "type":  "module",
+    "main":  "./dist/index.js",
+    "types":  "./dist/index.d.ts",
+    "bin":  {
+                "kuratchi":  "./dist/cli.js"
+            },
+    "files":  [
+                  "dist",
+                  "README.md"
+              ],
+    "scripts":  {
+                    "build":  "tsc -p tsconfig.build.json",
+                    "check":  "tsc -p tsconfig.build.json --noEmit",
+                    "prepublishOnly":  "npm run build"
+                },
+    "exports":  {
+                    ".":  {
+                              "types":  "./dist/index.d.ts",
+                              "import":  "./dist/index.js"
+                          },
+                    "./runtime/context.js":  {
+                                                 "types":  "./dist/runtime/context.d.ts",
+                                                 "import":  "./dist/runtime/context.js"
+                                             },
+                    "./runtime/do.js":  {
+                                            "types":  "./dist/runtime/do.d.ts",
+                                            "import":  "./dist/runtime/do.js"
+                                        },
+                    "./package.json":  "./package.json"
+                },
+    "engines":  {
+                    "node":  "\u003e=18"
+                },
+    "publishConfig":  {
+                          "access":  "public"
+                      },
+    "devDependencies":  {
+                            "@cloudflare/workers-types":  "^4.20260223.0",
+                            "@types/node":  "^24.4.0",
+                            "typescript":  "^5.8.0"
+                        }
+}
+
+
+
+