gorsee 0.2.1 → 0.2.2

package/src/cli/cmd-generate.ts

@@ -4,6 +4,7 @@
 import { join } from "node:path"
 import { mkdir, writeFile } from "node:fs/promises"
 import { createMigration } from "../db/migrate.ts"
+import { createProjectContext, type RuntimeOptions } from "../runtime/project.ts"
 
 function capitalize(s: string): string {
   return s.charAt(0).toUpperCase() + s.slice(1)
@@ -18,7 +19,7 @@ function singularize(s: string): string {
 
 function listRoute(entity: string, singular: string): string {
   const cap = capitalize(singular)
-  return `import { Head, Link } from "gorsee"
+  return `import { Head, Link } from "gorsee/client"
 import { SafeSQL } from "gorsee/types"
 import type { Context } from "gorsee/server"
 
@@ -49,7 +50,7 @@ export default function ${capitalize(entity)}ListPage(props: { data: { ${entity}
 
 function detailRoute(entity: string, singular: string): string {
   const cap = capitalize(singular)
-  return `import { Head, Link } from "gorsee"
+  return `import { Head, Link } from "gorsee/client"
 import type { Context } from "gorsee/server"
 
 export async function loader(ctx: Context) {
@@ -73,7 +74,7 @@ export default function ${cap}DetailPage(props: { data: { ${singular}: { id: num
 
 function newRoute(entity: string, singular: string): string {
   const cap = capitalize(singular)
-  return `import { Head, Link } from "gorsee"
+  return `import { Head, Link } from "gorsee/client"
 import { defineAction, parseFormData } from "gorsee/server"
 
 export const action = defineAction(async (ctx) => {
@@ -109,7 +110,9 @@ CREATE TABLE IF NOT EXISTS ${entity} (
 `
 }
 
-export async function runGenerate(args: string[]) {
+export interface GenerateCommandOptions extends RuntimeOptions {}
+
+export async function generateCrudScaffold(args: string[], options: GenerateCommandOptions = {}) {
   const entity = args[0]
   if (!entity) {
     console.error("Usage: gorsee generate <entity-name>")
@@ -117,9 +120,9 @@ export async function runGenerate(args: string[]) {
     process.exit(1)
   }
 
-  const cwd = process.cwd()
+  const { cwd, paths } = createProjectContext(options)
   const singular = singularize(entity)
-  const routeDir = join(cwd, "routes", entity)
+  const routeDir = join(paths.routesDir, entity)
 
   console.log(`\n  Generating CRUD for: ${entity}\n`)
 
@@ -130,7 +133,7 @@ export async function runGenerate(args: string[]) {
   await writeFile(join(routeDir, "new.tsx"), newRoute(entity, singular))
 
   // Create migration
-  const migrationDir = join(cwd, "migrations")
+  const migrationDir = paths.migrationsDir
   await mkdir(migrationDir, { recursive: true })
   const migrationFile = await createMigration(migrationDir, `create_${entity}`)
   const migrationPath = join(migrationDir, migrationFile)
@@ -145,3 +148,8 @@ export async function runGenerate(args: string[]) {
   console.log("  Next: run `gorsee migrate` to apply the migration")
   console.log()
 }
+
+/** @deprecated Use generateCrudScaffold() for programmatic access. */
+export async function runGenerate(args: string[], options: GenerateCommandOptions = {}) {
+  return generateCrudScaffold(args, options)
+}

package/src/cli/cmd-migrate.ts

@@ -1,12 +1,15 @@
 // gorsee migrate -- run database migrations
 // gorsee migrate create <name> -- create new migration file
 
-import { join } from "node:path"
 import { runMigrations, createMigration } from "../db/migrate.ts"
+import { createProjectContext, type RuntimeOptions } from "../runtime/project.ts"
 
-export async function runMigrate(args: string[]) {
-  const cwd = process.cwd()
-  const migrationsDir = join(cwd, "migrations")
+export interface MigrateCommandOptions extends RuntimeOptions {
+  dbPath?: string
+}
+
+export async function runProjectMigrations(args: string[], options: MigrateCommandOptions = {}) {
+  const { env, paths } = createProjectContext(options)
   const subcommand = args[0]
 
   if (subcommand === "create") {
@@ -15,16 +18,16 @@ export async function runMigrate(args: string[]) {
       console.error("Usage: gorsee migrate create <migration-name>")
       process.exit(1)
     }
-    const filename = await createMigration(migrationsDir, name)
+    const filename = await createMigration(paths.migrationsDir, name)
     console.log(`\n  Created: migrations/${filename}\n`)
     return
   }
 
   // Default: run pending migrations
-  const dbPath = process.env.DATABASE_URL ?? join(cwd, "data.sqlite")
+  const dbPath = options.dbPath ?? env.DATABASE_URL ?? paths.dataFile
   console.log("\n  Running migrations...\n")
 
-  const result = await runMigrations(dbPath, migrationsDir)
+  const result = await runMigrations(dbPath, paths.migrationsDir)
 
   if (result.applied.length > 0) {
     console.log("  Applied:")
@@ -43,3 +46,8 @@ export async function runMigrate(args: string[]) {
 
   console.log(`\n  Done: ${result.applied.length} migration(s) applied\n`)
 }
+
+/** @deprecated Use runProjectMigrations() for programmatic access. */
+export async function runMigrate(args: string[], options: MigrateCommandOptions = {}) {
+  return runProjectMigrations(args, options)
+}

package/src/cli/cmd-routes.ts

@@ -1,11 +1,13 @@
 // gorsee routes -- list all routes
 
-import { join } from "node:path"
 import { createRouter } from "../router/scanner.ts"
+import { createProjectContext, type RuntimeOptions } from "../runtime/project.ts"
 
-export async function runRoutes(_args: string[]) {
-  const routesDir = join(process.cwd(), "routes")
-  const routes = await createRouter(routesDir)
+export interface RoutesCommandOptions extends RuntimeOptions {}
+
+export async function listRoutes(options: RoutesCommandOptions = {}) {
+  const { cwd, paths } = createProjectContext(options)
+  const routes = await createRouter(paths.routesDir)
 
   if (routes.length === 0) {
     console.log("\n  No routes found in routes/\n")
@@ -21,9 +23,14 @@ export async function runRoutes(_args: string[]) {
     console.log(
       "  " +
       route.path.padEnd(25) +
-      route.filePath.replace(process.cwd() + "/", "").padEnd(40) +
+      route.filePath.replace(cwd + "/", "").padEnd(40) +
       params
     )
   }
   console.log()
 }
+
+/** @deprecated Use listRoutes() for programmatic access. */
+export async function runRoutes(_args: string[], options: RoutesCommandOptions = {}) {
+  return listRoutes(options)
+}

package/src/cli/cmd-start.ts

@@ -2,14 +2,18 @@
 
 import { join } from "node:path"
 import { stat } from "node:fs/promises"
+import { createProjectContext, type RuntimeOptions } from "../runtime/project.ts"
 
-export async function runStart(_args: string[]) {
-  const cwd = process.cwd()
-  const distDir = join(cwd, "dist")
+export interface StartCommandOptions extends RuntimeOptions {
+  port?: number
+}
+
+export async function startBuiltProject(options: StartCommandOptions = {}) {
+  const { paths } = createProjectContext(options)
 
   // Verify build exists
   try {
-    await stat(join(distDir, "manifest.json"))
+    await stat(join(paths.distDir, "manifest.json"))
   } catch {
     console.error("\n  Error: No production build found.")
     console.error("  Run `gorsee build` first.\n")
@@ -17,5 +21,10 @@ export async function runStart(_args: string[]) {
   }
 
   const { startProductionServer } = await import("../prod.ts")
-  await startProductionServer()
+  await startProductionServer({ cwd: paths.cwd, port: options.port })
+}
+
+/** @deprecated Use startBuiltProject() for programmatic access. */
+export async function runStart(_args: string[], options: StartCommandOptions = {}) {
+  return startBuiltProject(options)
 }

package/src/cli/cmd-test.ts

@@ -2,6 +2,7 @@
 
 import { readdir, stat } from "node:fs/promises"
 import { join } from "node:path"
+import { createProjectContext, type RuntimeOptions } from "../runtime/project.ts"
 
 interface TestFlags {
   watch: boolean
@@ -78,8 +79,10 @@ export function buildTestArgs(flags: TestFlags, files: string[]): string[] {
   return bunArgs
 }
 
-export async function runTest(args: string[]) {
-  const cwd = process.cwd()
+export interface TestCommandOptions extends RuntimeOptions {}
+
+export async function runTests(args: string[], options: TestCommandOptions = {}) {
+  const { cwd, env } = createProjectContext(options)
   const flags = parseFlags(args)
   const pattern = getTestPattern(flags)
 
@@ -100,7 +103,7 @@ export async function runTest(args: string[]) {
     stdout: "inherit",
     stderr: "inherit",
     env: {
-      ...process.env,
+      ...env,
       NODE_ENV: "test",
       GORSEE_TEST: "1",
     },
@@ -117,5 +120,10 @@ export async function runTest(args: string[]) {
   }
 }
 
+/** @deprecated Use runTests() for programmatic access. */
+export async function runTest(args: string[], options: TestCommandOptions = {}) {
+  return runTests(args, options)
+}
+
 // Re-export for testing
 export { parseFlags, findTestFiles, getTestPattern }

package/src/cli/cmd-typegen.ts

@@ -4,6 +4,7 @@
 import { join } from "node:path"
 import { mkdir, writeFile } from "node:fs/promises"
 import { createRouter, type Route } from "../router/index.ts"
+import { createProjectContext, type RuntimeOptions } from "../runtime/project.ts"
 
 const OUTPUT_DIR = ".gorsee"
 const TYPES_FILE = "routes.d.ts"
@@ -54,9 +55,13 @@ function generateDeclaration(routes: Route[]): string {
   return lines.join("\n")
 }
 
-export async function runTypegen(args: string[]): Promise<void> {
-  const cwd = process.cwd()
-  const routesDir = args[0] ?? join(cwd, "routes")
+export interface TypegenCommandOptions extends RuntimeOptions {
+  routesDir?: string
+}
+
+export async function generateRouteTypes(args: string[], options: TypegenCommandOptions = {}): Promise<void> {
+  const { cwd, paths } = createProjectContext(options)
+  const routesDir = options.routesDir ?? args[0] ?? paths.routesDir
 
   console.log(`Scanning routes in: ${routesDir}`)
 
@@ -81,3 +86,8 @@ export async function runTypegen(args: string[]): Promise<void> {
     console.log(`    ${route.path}${params}`)
   }
 }
+
+/** @deprecated Use generateRouteTypes() for programmatic access. */
+export async function runTypegen(args: string[], options: TypegenCommandOptions = {}): Promise<void> {
+  return generateRouteTypes(args, options)
+}

package/src/cli/cmd-upgrade.ts

@@ -2,6 +2,7 @@
 
 import { readFile } from "node:fs/promises"
 import { join } from "node:path"
+import { createProjectContext, type RuntimeOptions } from "../runtime/project.ts"
 
 interface UpgradeFlags {
   check: boolean
@@ -75,8 +76,10 @@ async function checkMigrationHints(cwd: string): Promise<string[]> {
   return hints
 }
 
-export async function runUpgrade(args: string[]) {
-  const cwd = process.cwd()
+export interface UpgradeCommandOptions extends RuntimeOptions {}
+
+export async function upgradeFramework(args: string[], options: UpgradeCommandOptions = {}) {
+  const { cwd } = createProjectContext(options)
   const flags = parseUpgradeFlags(args)
 
   const current = await getCurrentVersion(cwd)
@@ -133,3 +136,8 @@ export async function runUpgrade(args: string[]) {
 
   console.log(`\n  Upgraded successfully to v${latest}\n`)
 }
+
+/** @deprecated Use upgradeFramework() for programmatic access. */
+export async function runUpgrade(args: string[], options: UpgradeCommandOptions = {}) {
+  return upgradeFramework(args, options)
+}

package/src/cli/context.ts

@@ -0,0 +1,12 @@
+/** @deprecated Import shared project context from "../runtime/project" in new code. */
+export {
+  createProjectContext as createCommandContext,
+  resolveProjectPaths,
+} from "../runtime/project.ts"
+
+/** @deprecated Import shared runtime types from "../runtime/project" in new code. */
+export type {
+  RuntimeOptions as CommandRuntimeOptions,
+  ProjectContext as CommandContext,
+  ProjectPaths,
+} from "../runtime/project.ts"

package/src/cli/framework-md.ts

@@ -35,29 +35,56 @@ app.config.ts    Configuration
 ## Imports
 
 \`\`\`typescript
-// Reactivity
-import { createSignal, createComputed, createEffect, createResource, createStore } from "gorsee/reactive"
+// Browser-safe route code
+import { createSignal, createComputed, createEffect, createResource, createStore } from "gorsee/client"
 
-// Types (compile-time safety)
-import { SafeSQL } from "gorsee/types"           // SQL injection = compile error
-import { SafeHTML, sanitize } from "gorsee/types" // XSS = compile error
-import { SafeURL, validateURL } from "gorsee/types"
-import { validate, type UserInput } from "gorsee/types"
+// Server-only code
+import { server, middleware, type Context, createDB, createAuth, cors, log } from "gorsee/server"
+\`\`\`
 
-// Database
-import { createDB } from "gorsee/db"
+## Import Boundaries
 
-// Server functions
-import { server } from "gorsee/server"
-import { middleware, type Context } from "gorsee/server"
+- \`gorsee/client\` for route components, islands, navigation, forms, and reactive primitives
+- \`gorsee/server\` for middleware, loaders, RPC, auth, db, security, env, and logging
+- Root \`gorsee\` is compatibility-only and should not be used in new code
+- \`gorsee/compat\` is available as an explicit legacy migration entrypoint
+
+## Adapter Recipes
 
-// Logging
-import { log } from "gorsee/log"
+\`\`\`typescript
+import { createClient } from "redis"
+import {
+  createAuth,
+  createRedisSessionStore,
+  createRedisCacheStore,
+  createNodeRedisLikeClient,
+  routeCache,
+} from "gorsee/server"
+
+const redis = createClient({ url: process.env.REDIS_URL })
+await redis.connect()
+const redisClient = createNodeRedisLikeClient(redis)
+
+const auth = createAuth({
+  secret: process.env.SESSION_SECRET!,
+  store: createRedisSessionStore(redisClient, { prefix: "app:sessions" }),
+})
 
-// Escape hatches (DANGER)
-import { unsafeSQL, unsafeHTML } from "gorsee/unsafe"
+export const cache = routeCache({
+  maxAge: 60,
+  staleWhileRevalidate: 300,
+  store: createRedisCacheStore(redisClient, {
+    prefix: "app:cache",
+    maxEntryAgeMs: 360_000,
+  }),
+})
 \`\`\`
 
+- SQLite adapters are the default persistent single-node path
+- Redis adapters are the default multi-instance path
+- \`createNodeRedisLikeClient()\` and \`createIORedisLikeClient()\` normalize real Redis SDK clients to the framework adapter contract
+- RPC handlers remain process-local by design; do not try to distribute closures through Redis
+
 ## Patterns
 
 ### Page Route

package/src/client.ts

@@ -0,0 +1,26 @@
+// Explicit browser-safe public entrypoint.
+// Use this in route components and client-facing modules.
+
+export {
+  createSignal,
+  createComputed,
+  createEffect,
+  createResource,
+  createStore,
+  createLive,
+  invalidateResource,
+  invalidateAll,
+  createMutation,
+} from "./reactive/index.ts"
+
+export { Suspense } from "./runtime/suspense.ts"
+export { Link } from "./runtime/link.ts"
+export { Head } from "./runtime/head.ts"
+export { navigate, onNavigate, beforeNavigate, getCurrentPath } from "./runtime/router.ts"
+export { useFormAction } from "./runtime/form.ts"
+export { Image } from "./runtime/image.ts"
+export { ErrorBoundary } from "./runtime/error-boundary.ts"
+export { island } from "./runtime/island.ts"
+export { createEventSource } from "./server/sse.ts"
+export { typedLink, typedNavigate } from "./runtime/typed-routes.ts"
+export { defineForm, validateForm, fieldAttrs } from "./runtime/validated-form.ts"

package/src/dev/partial-handler.ts

@@ -2,8 +2,12 @@
 // Returns JSON with rendered HTML + metadata instead of full page
 
 import { createContext } from "../server/middleware.ts"
-import { renderToString, ssrJsx } from "../runtime/server.ts"
-import { resetServerHead, getServerHead } from "../runtime/head.ts"
+import {
+  buildPartialResponsePayload,
+  createClientScriptPath,
+  renderPageDocument,
+  resolvePageRoute,
+} from "../server/page-render.ts"
 import type { MatchResult } from "../router/matcher.ts"
 import type { BuildResult } from "../build/client.ts"
 
@@ -13,15 +17,6 @@ interface PartialRenderOptions {
   clientBuild: BuildResult
 }
 
-interface PartialResponse {
-  html: string
-  data?: unknown
-  params?: Record<string, string>
-  title?: string
-  css?: string[]
-  script?: string
-}
-
 export async function handlePartialNavigation(opts: PartialRenderOptions): Promise<Response> {
   const { match, request, clientBuild } = opts
   const mod = await import(match.route.filePath)
@@ -32,76 +27,24 @@ export async function handlePartialNavigation(opts: PartialRenderOptions): Promi
     return new Response("Not a page route", { status: 400 })
   }
 
-  const component = mod.default as Function | undefined
-  if (typeof component !== "function") {
+  const resolved = await resolvePageRoute(mod, match, ctx)
+  if (!resolved) {
     return new Response(JSON.stringify({ error: "Route has no default export" }), {
       status: 500,
       headers: { "Content-Type": "application/json" },
     })
   }
 
-  // Parallel loading: import layout modules + run page loader simultaneously
-  const layoutPaths = match.route.layoutPaths ?? []
-  const layoutImportPromises = layoutPaths.map((lp) => import(lp))
-  const pageLoaderPromise = typeof mod.loader === "function" ? mod.loader(ctx) : undefined
-
-  const [layoutMods, loaderData] = await Promise.all([
-    Promise.all(layoutImportPromises),
-    pageLoaderPromise,
-  ])
-
-  // Run layout loaders in parallel
-  const layoutLoaderPromises = layoutMods.map((lm) =>
-    typeof lm.loader === "function" ? lm.loader(ctx) : undefined,
+  const { pageComponent, loaderData, cssFiles } = resolved
+  const rendered = renderPageDocument(pageComponent, ctx, match.params, loaderData)
+  const clientScript = createClientScriptPath(clientBuild.entryMap.get(match.route.path))
+  const result = buildPartialResponsePayload(
+    rendered,
+    loaderData,
+    match.params,
+    cssFiles,
+    clientScript,
   )
-  const layoutLoaderResults = await Promise.all(layoutLoaderPromises)
-
-  // CSS
-  const cssFiles: string[] = []
-  if (typeof mod.css === "string") cssFiles.push(mod.css)
-  if (Array.isArray(mod.css)) cssFiles.push(...(mod.css as string[]))
-
-  // Nested layout wrapping: outermost first, innermost wraps page
-  let pageComponent: Function = component
-  for (let i = layoutMods.length - 1; i >= 0; i--) {
-    const Layout = layoutMods[i]!.default
-    if (typeof Layout === "function") {
-      const inner = pageComponent
-      const layoutData = layoutLoaderResults[i]
-      pageComponent = (props: Record<string, unknown>) =>
-        Layout({ ...props, data: layoutData, children: inner(props) })
-    }
-  }
-
-  // Render
-  resetServerHead()
-  const pageProps = { params: match.params, ctx, data: loaderData }
-  const vnode = ssrJsx(pageComponent as any, pageProps)
-  const html = renderToString(vnode)
-
-  // Extract title from Head component
-  const headElements = getServerHead()
-  let title: string | undefined
-  for (const el of headElements) {
-    const titleMatch = el.match(/<title>(.+?)<\/title>/)
-    if (titleMatch) {
-      title = titleMatch[1]
-      break
-    }
-  }
-
-  // Client JS path
-  const clientJsFile = clientBuild.entryMap.get(match.route.path)
-  const clientScript = clientJsFile ? `/_gorsee/${clientJsFile}` : undefined
-
-  const result: PartialResponse = {
-    html,
-    data: loaderData,
-    params: Object.keys(match.params).length > 0 ? match.params : undefined,
-    title,
-    css: cssFiles.length > 0 ? cssFiles : undefined,
-    script: clientScript,
-  }
 
   return new Response(JSON.stringify(result), {
     headers: { "Content-Type": "application/json" },