frappebun 0.0.0

package/src/api/route.ts

@@ -0,0 +1,301 @@
+/**
+ * `route()` — marks an export as an HTTP endpoint with access-control metadata.
+ *
+ * ─── Two URL conventions ────────────────────────────────────────────────────
+ *
+ * 1. CONVENTION  — no `path:` → URL derived from file path + export name
+ *
+ *      // api/reports.ts
+ *      export const getOutstanding = route(async ({ customer }) => { ... })
+ *      // → GET /api/myapp/reports/get-outstanding?customer=CUST-001
+ *
+ * 2. EXPLICIT    — `path:` is the full URL relative to /api/{appname}/
+ *
+ *      // any file
+ *      export const getProduct = route({
+ *        path:   "/products/:id",
+ *        method: "GET",
+ *        async handler({ id }: { id: string }) { ... },
+ *      })
+ *      // → GET /api/myapp/products/:id
+ *
+ *      export const getProductAction = route({
+ *        path:   "/products/:id/details/:action",
+ *        method: "GET",
+ *        async handler({ id, action }: { id: string; action: string }) { ... },
+ *      })
+ *      // → GET /api/myapp/products/:id/details/:action
+ *
+ * When `path:` is set the file's location has no effect on the URL.
+ * Path params (`:name` segments) are merged with query-string / body params;
+ * path params win on collision.
+ *
+ * ─── Return types ────────────────────────────────────────────────────────────
+ *
+ *   - Plain value  → wrapped in `{ data: <value> }` with status 200
+ *   - `Response`   → passed through as-is (full control over status / headers)
+ */
+
+import { contextStore } from "../context"
+import type { FrappeContext } from "../context"
+import { response as _response } from "../response"
+
+export type AuthMode = "required" | "public" | "guest-only"
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH"
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type RouteHandler = (params: any) => Promise<unknown> | unknown
+
+export interface RouteConfig {
+  handler: RouteHandler
+  /**
+   * App-relative URL pattern, starting with `/`.
+   * Params are declared as `:name` segments and received in the handler.
+   *
+   * Examples:
+   *   "/products/:id"                       → /api/{app}/products/:id
+   *   "/products/:id/details/:action"       → /api/{app}/products/:id/details/:action
+   *   "/orders/:orderId/items/:itemId"      → /api/{app}/orders/:orderId/items/:itemId
+   *
+   * When omitted the URL is derived from the file path + export name convention.
+   */
+  path?: string
+  auth?: AuthMode
+  method?: HttpMethod
+  roles?: string[]
+  rateLimit?: { limit: number; window: number }
+}
+
+export interface RouteDefinition {
+  __isRoute: true
+  config: RouteConfig
+}
+
+// ─── route() factory ──────────────────────────────────────
+
+/**
+ * Infer HTTP method from an export name:
+ *   get / list / fetch / search / check / is / has  →  GET
+ *   everything else                                  →  POST
+ */
+export function inferMethod(exportName: string): HttpMethod {
+  if (!exportName) return "POST"
+  return /^(get|list|fetch|search|check|is|has)/i.test(exportName) ? "GET" : "POST"
+}
+
+/** Convert camelCase to kebab-case: `getOutstanding` → `get-outstanding` */
+export function camelToKebab(s: string): string {
+  return s.replace(/([A-Z])/g, (_, c: string) => `-${c.toLowerCase()}`)
+}
+
+/**
+ * Compute the full server URL path for a route definition.
+ *
+ * Strategy 1 — explicit `path:`:
+ *   `appPrefix` + `def.config.path`
+ *   e.g. "/api/myapp" + "/products/:id"  →  "/api/myapp/products/:id"
+ *
+ * Strategy 2 — convention (no `path:`):
+ *   `appPrefix` / `fileSegment` / kebab(`exportName`)
+ *   e.g. "/api/myapp" / "reports" / "get-outstanding"  →  "/api/myapp/reports/get-outstanding"
+ *
+ * @param appPrefix   App namespace, e.g. `"/api/myapp"`
+ * @param def         The RouteDefinition
+ * @param exportName  JS export name — used for method inference and convention URL
+ * @param fileSegment File URL segment, e.g. `"reports"` for `api/reports.ts`
+ */
+export function resolveRoutePath(
+  appPrefix: string,
+  def: RouteDefinition,
+  exportName: string,
+  fileSegment?: string,
+): string {
+  if (def.config.path) return `${appPrefix}${def.config.path}`
+  const parts = [appPrefix, fileSegment, camelToKebab(exportName)].filter(Boolean)
+  return parts.join("/")
+}
+
+/**
+ * Mark a function as an HTTP endpoint.
+ *
+ *   route(fn)       — simple form, sensible defaults
+ *   route({ ... })  — full form, all options explicit
+ */
+export function route(fnOrConfig: RouteHandler | RouteConfig): RouteDefinition {
+  const config: RouteConfig =
+    typeof fnOrConfig === "function" ? { handler: fnOrConfig } : fnOrConfig
+
+  return { __isRoute: true, config: { auth: "required", ...config } }
+}
+
+export function isRouteDefinition(v: unknown): v is RouteDefinition {
+  return typeof v === "object" && v !== null && (v as RouteDefinition).__isRoute === true
+}
+
+// ─── Route registry ───────────────────────────────────────
+
+interface RegistryEntry {
+  def: RouteDefinition
+  method: HttpMethod
+  segments: string[]
+}
+
+/**
+ * Registry of all discovered user-defined routes.
+ * Framework routes (auth, resource) are dispatched directly by the server.
+ */
+class RouteRegistry {
+  private fixed: RegistryEntry[] = [] // framework routes — survive clear()
+  private dynamic: RegistryEntry[] = [] // user / test routes — cleared by clear()
+
+  /**
+   * Register a framework (system) route.
+   * These are never removed by clear() and have priority over user routes.
+   */
+  registerSystem(fullPath: string, def: RouteDefinition, exportName = ""): void {
+    this.fixed.push(this._entry(fullPath, def, exportName))
+  }
+
+  /**
+   * Register a user-defined route.
+   * Use resolveRoutePath() to compute fullPath from a RouteDefinition.
+   */
+  register(fullPath: string, def: RouteDefinition, exportName = ""): void {
+    this.dynamic.push(this._entry(fullPath, def, exportName))
+  }
+
+  /**
+   * Match an incoming request against registered patterns.
+   * Fixed (framework) routes are checked first.
+   */
+  match(
+    pathname: string,
+    httpMethod: string,
+  ): { def: RouteDefinition; params: Record<string, string> } | null {
+    const incoming = pathname.split("/").filter(Boolean)
+    const method = httpMethod.toUpperCase() as HttpMethod
+
+    for (const entry of [...this.fixed, ...this.dynamic]) {
+      if (entry.method !== method) continue
+      if (entry.segments.length !== incoming.length) continue
+
+      const params: Record<string, string> = {}
+      let ok = true
+
+      for (let i = 0; i < entry.segments.length; i++) {
+        const seg = entry.segments[i]!
+        if (seg.startsWith(":")) {
+          params[seg.slice(1)] = decodeURIComponent(incoming[i]!)
+        } else if (seg !== incoming[i]) {
+          ok = false
+          break
+        }
+      }
+
+      if (ok) return { def: entry.def, params }
+    }
+
+    return null
+  }
+
+  /** Clear user-defined routes only. Framework routes are preserved. */
+  clear(): void {
+    this.dynamic = []
+  }
+
+  /** Return all registered user routes as a flat list for introspection. */
+  list(): Array<{ method: HttpMethod; path: string; auth: AuthMode }> {
+    return this.dynamic.map((e) => ({
+      method: e.method,
+      path: "/" + e.segments.join("/"),
+      auth: e.def.config.auth ?? "required",
+    }))
+  }
+
+  private _entry(fullPath: string, def: RouteDefinition, exportName: string): RegistryEntry {
+    return {
+      def,
+      method: def.config.method ?? inferMethod(exportName),
+      segments: fullPath.split("/").filter(Boolean),
+    }
+  }
+}
+
+/** Singleton route registry — app route files register into this at startup. */
+export const routeRegistry = new RouteRegistry()
+
+// ─── invokeRoute ──────────────────────────────────────────
+
+/**
+ * Execute a RouteDefinition:
+ *   1. Enforce auth / role checks
+ *   2. Merge params (path > query-string > body)
+ *   3. Call handler
+ *   4. Plain return values → `{ data: ... }`; Response objects → pass through
+ *
+ * @param def        The RouteDefinition to invoke
+ * @param pathParams Path parameters extracted from the URL (highest priority)
+ */
+export async function invokeRoute(
+  def: RouteDefinition,
+  pathParams: Record<string, unknown> = {},
+): Promise<Response> {
+  const ctx = contextStore.getStore()
+  const authMode = def.config.auth ?? "required"
+
+  // ── Auth ────────────────────────────────────────────
+  if (authMode === "required" && (!ctx || ctx.user === "Guest")) {
+    return _response.unauthorized()
+  }
+  if (authMode === "guest-only" && ctx?.user !== "Guest") {
+    return _response.error("Already logged in", 400)
+  }
+
+  // ── Roles ────────────────────────────────────────────
+  if (def.config.roles?.length && ctx) {
+    if (!def.config.roles.some((r) => ctx.perms.hasRole(r))) {
+      return _response.forbidden()
+    }
+  }
+
+  // ── Params: query-string + body + path params ────────
+  const params = await mergeParams(pathParams, ctx)
+
+  // ── Execute ──────────────────────────────────────────
+  const result = await def.config.handler(params)
+
+  if (result instanceof Response) return result
+  return _response.ok(result)
+}
+
+// ─── Internal helpers ─────────────────────────────────────
+
+async function mergeParams(
+  pathParams: Record<string, unknown>,
+  ctx: FrappeContext | undefined,
+): Promise<Record<string, unknown>> {
+  const req = ctx?.request
+  if (!req) return { ...pathParams }
+
+  const params: Record<string, unknown> = {}
+
+  // 1. Query-string (lowest priority)
+  for (const [k, v] of new URL(req.url).searchParams) params[k] = v
+
+  // 2. JSON body for write methods
+  const method = req.method.toUpperCase()
+  if (method === "POST" || method === "PUT" || method === "PATCH") {
+    if ((req.headers.get("content-type") ?? "").includes("application/json")) {
+      try {
+        Object.assign(params, (await req.clone().json()) as Record<string, unknown>)
+      } catch {
+        /* non-JSON body */
+      }
+    }
+  }
+
+  // 3. Path params (highest priority)
+  Object.assign(params, pathParams)
+
+  return params
+}

package/src/app/index.ts

@@ -0,0 +1,6 @@
+/**
+ * App module — project/app discovery and loading.
+ */
+
+export { loadApp, readAppMetadata, appNameFromPackage, findProjectRoot, appLabel } from "./loader"
+export type { LoadedApp, AppMetadata } from "./loader"

package/src/app/loader.ts

@@ -0,0 +1,218 @@
+/**
+ * App loader — discover the app module from package.json and scan
+ * its conventional directories (doctype/, api/, pages/, extensions/, ...).
+ *
+ * One app per project. The project root contains a `package.json` with a
+ * `"name"` field — that name becomes the app module directory name.
+ * Scoped names (`@scope/name`) use only the name part.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs"
+import { join, basename } from "node:path"
+
+import { isRouteDefinition, resolveRoutePath, routeRegistry } from "../api/route"
+import type { RouteDefinition } from "../api/route"
+import { discoverDocTypes } from "../doctype/discovery"
+
+// ─── Types ────────────────────────────────────────────────
+
+export interface AppMetadata {
+  name: string
+  version: string
+  title: string
+  description?: string
+}
+
+export interface LoadedApp {
+  /** Project root — directory containing package.json. */
+  readonly root: string
+
+  /** App module name — derived from package.json "name". */
+  readonly name: string
+
+  /** Absolute path to the app module directory — `<root>/<name>/`. */
+  readonly moduleDir: string
+
+  /** Metadata from package.json. */
+  readonly metadata: AppMetadata
+
+  /** Counts of what was loaded — for dev-server logging. */
+  readonly loaded: {
+    doctypes: number
+    apiRoutes: number
+    pages: number
+  }
+}
+
+// ─── package.json parsing ─────────────────────────────────
+
+interface PackageJson {
+  name?: string
+  version?: string
+  frappe?: { title?: string; description?: string }
+}
+
+/** Resolve the app module directory name from a package name. */
+export function appNameFromPackage(pkgName: string): string {
+  // "@scope/hrms" → "hrms", "myapp" → "myapp"
+  return pkgName.startsWith("@") ? (pkgName.split("/")[1] ?? pkgName) : pkgName
+}
+
+/** Read and parse the project's package.json. */
+export function readAppMetadata(root: string): AppMetadata {
+  const pkgPath = join(root, "package.json")
+  if (!existsSync(pkgPath)) {
+    throw new Error(`No package.json found at ${root}`)
+  }
+
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8")) as PackageJson
+
+  if (!pkg.name) {
+    throw new Error(`package.json at ${root} has no "name" field`)
+  }
+
+  return {
+    name: appNameFromPackage(pkg.name),
+    version: pkg.version ?? "0.0.0",
+    title: pkg.frappe?.title ?? pkg.name,
+    description: pkg.frappe?.description,
+  }
+}
+
+// ─── Loading ──────────────────────────────────────────────
+
+/**
+ * Load the app at `root` — read its metadata, then scan all conventional
+ * directories inside the app module for DocTypes, API routes, and pages.
+ *
+ * Missing directories are silently skipped.
+ */
+export async function loadApp(root: string): Promise<LoadedApp> {
+  const metadata = readAppMetadata(root)
+  const moduleDir = join(root, metadata.name)
+
+  if (!existsSync(moduleDir)) {
+    throw new Error(
+      `App module directory "${metadata.name}/" not found at ${root}. ` +
+        `Expected ${moduleDir}/ — it must match package.json "name".`,
+    )
+  }
+
+  const doctypes = await loadDocTypes(moduleDir)
+  const apiRoutes = await loadApiRoutes(moduleDir, metadata.name)
+  const pages = countPages(moduleDir)
+
+  return { root, name: metadata.name, moduleDir, metadata, loaded: { doctypes, apiRoutes, pages } }
+}
+
+// ─── DocTypes ─────────────────────────────────────────────
+
+async function loadDocTypes(moduleDir: string): Promise<number> {
+  const dir = join(moduleDir, "doctype")
+  if (!existsSync(dir)) return 0
+  await discoverDocTypes(dir)
+  return readdirSync(dir).filter((e) => statSync(join(dir, e)).isDirectory()).length
+}
+
+// ─── API routes ───────────────────────────────────────────
+
+/**
+ * Discover API route files under `<moduleDir>/api/` and register them.
+ *
+ * File path → URL segment:
+ *   api/reports.ts           → /api/<app>/reports/<kebab-export>
+ *   api/webhooks/stripe.ts   → /api/<app>/webhooks/stripe/<kebab-export>
+ */
+async function loadApiRoutes(moduleDir: string, appName: string): Promise<number> {
+  const apiDir = join(moduleDir, "api")
+  if (!existsSync(apiDir)) return 0
+
+  const appPrefix = `/api/${appName}`
+  let count = 0
+
+  for (const file of walkTsFiles(apiDir)) {
+    const fileSegment = toRouteSegment(file.relPath)
+    const mod = (await import(file.absPath)) as Record<string, unknown>
+
+    for (const [exportName, value] of Object.entries(mod)) {
+      if (!isRouteDefinition(value)) continue
+
+      // `export default route(...)` owns the file-level URL — no export-name
+      // segment appended. e.g. api/hello.ts → POST /api/myapp/hello
+      const isDefault = exportName === "default"
+      const fullPath = isDefault
+        ? `${appPrefix}/${fileSegment}`
+        : resolveRoutePath(appPrefix, value as RouteDefinition, exportName, fileSegment)
+
+      routeRegistry.register(fullPath, value as RouteDefinition, isDefault ? "" : exportName)
+      count++
+    }
+  }
+
+  return count
+}
+
+// ─── Pages (counted only — SSR loads them separately) ────
+
+function countPages(moduleDir: string): number {
+  const pagesDir = join(moduleDir, "pages")
+  if (!existsSync(pagesDir)) return 0
+  let count = 0
+  for (const _ of walkVueFiles(pagesDir)) count++
+  return count
+}
+
+// ─── Filesystem helpers ───────────────────────────────────
+
+interface WalkedFile {
+  absPath: string
+  relPath: string // relative to walk root, no leading slash
+}
+
+function* walkTsFiles(root: string, prefix = ""): Generator<WalkedFile> {
+  for (const entry of readdirSync(root)) {
+    const abs = join(root, entry)
+    const rel = prefix ? `${prefix}/${entry}` : entry
+    if (statSync(abs).isDirectory()) {
+      yield* walkTsFiles(abs, rel)
+    } else if (entry.endsWith(".ts") && !entry.endsWith(".d.ts") && !entry.endsWith(".test.ts")) {
+      yield { absPath: abs, relPath: rel }
+    }
+  }
+}
+
+function* walkVueFiles(root: string, prefix = ""): Generator<WalkedFile> {
+  for (const entry of readdirSync(root)) {
+    const abs = join(root, entry)
+    const rel = prefix ? `${prefix}/${entry}` : entry
+    if (statSync(abs).isDirectory()) {
+      yield* walkVueFiles(abs, rel)
+    } else if (entry.endsWith(".vue")) {
+      yield { absPath: abs, relPath: rel }
+    }
+  }
+}
+
+/** Convert an api/ relative file path to its URL segment. */
+function toRouteSegment(relPath: string): string {
+  // "webhooks/stripe.ts" → "webhooks/stripe"
+  // "reports.ts"         → "reports"
+  return relPath.replace(/\.ts$/, "")
+}
+
+/** Convenience: infer project root as the nearest ancestor containing package.json. */
+export function findProjectRoot(start: string = process.cwd()): string {
+  let dir = start
+  while (dir !== "/" && dir !== "") {
+    if (existsSync(join(dir, "package.json"))) return dir
+    const parent = join(dir, "..")
+    if (parent === dir) break
+    dir = parent
+  }
+  throw new Error(`Could not find a package.json starting from ${start}`)
+}
+
+/** Friendly basename — used for logging. */
+export function appLabel(app: LoadedApp): string {
+  return basename(app.root)
+}