frappebun 0.0.0

package/src/frappe.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Ambient globals for the frappe framework.
+ *
+ * This file is a pure TypeScript script (no top-level imports, no exports).
+ * Top-level `declare` statements in a script file are automatically global —
+ * no `declare global {}` wrapper is needed. Inline `import()` types are used
+ * to reference types from other modules without making this file a module.
+ *
+ * Consumer projects add:
+ *   /// <reference path="./node_modules/frappebun/src/frappe.d.ts" />
+ * in their `frappe-env.d.ts` to activate these globals.
+ */
+
+// ─── Request context ──────────────────────────────────────
+
+/** The frappe context — available in request handlers, controllers, and scripts. */
+declare var frappe: import("./context").FrappeContext & {
+  response: import("./response").FrappeResponse
+}
+
+// ─── DocType definition ───────────────────────────────────
+
+/** Define a DocType schema. */
+declare function doctype(
+  name: string,
+  schema: import("./doctype/types").DocTypeSchema,
+): import("./doctype/types").DocTypeDefinition
+
+/** Define a controller for a DocType. */
+declare function controller(
+  name: string,
+  hooks: import("./doctype/types").ControllerHooks,
+): import("./doctype/types").ControllerDefinition
+
+// ─── Field factory ────────────────────────────────────────
+
+/** Field factory — creates FieldDefinition objects. */
+declare var field: {
+  data(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  int(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  float(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  currency(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  percent(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  check(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  rating(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  text(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  smallText(
+    opts?: import("./doctype/types").FieldOptions,
+  ): import("./doctype/types").FieldDefinition
+  longText(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  textEditor(
+    opts?: import("./doctype/types").FieldOptions,
+  ): import("./doctype/types").FieldDefinition
+  markdownEditor(
+    opts?: import("./doctype/types").FieldOptions,
+  ): import("./doctype/types").FieldDefinition
+  code(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  htmlEditor(
+    opts?: import("./doctype/types").FieldOptions,
+  ): import("./doctype/types").FieldDefinition
+  json(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  date(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  datetime(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  time(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  duration(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  select(
+    options: string[],
+    opts?: import("./doctype/types").FieldOptions,
+  ): import("./doctype/types").FieldDefinition
+  link(
+    doctype: string,
+    opts?: import("./doctype/types").FieldOptions,
+  ): import("./doctype/types").FieldDefinition
+  dynamicLink(
+    linkField: string,
+    opts?: import("./doctype/types").FieldOptions,
+  ): import("./doctype/types").FieldDefinition
+  tableMultiSelect(
+    doctype: string,
+    opts?: import("./doctype/types").FieldOptions,
+  ): import("./doctype/types").FieldDefinition
+  table(
+    doctypeOrFields: string | Record<string, import("./doctype/types").FieldDefinition>,
+    opts?: import("./doctype/types").FieldOptions,
+  ): import("./doctype/types").FieldDefinition
+  attach(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  attachImage(
+    opts?: import("./doctype/types").FieldOptions,
+  ): import("./doctype/types").FieldDefinition
+  image(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  color(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  signature(
+    opts?: import("./doctype/types").FieldOptions,
+  ): import("./doctype/types").FieldDefinition
+  geolocation(
+    opts?: import("./doctype/types").FieldOptions,
+  ): import("./doctype/types").FieldDefinition
+  password(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  readOnly(opts?: import("./doctype/types").FieldOptions): import("./doctype/types").FieldDefinition
+  htmlField(
+    opts?: import("./doctype/types").FieldOptions,
+  ): import("./doctype/types").FieldDefinition
+}
+
+// ─── Layout helpers ───────────────────────────────────────
+
+/** Layout helper — creates a section. */
+// oxlint-disable-next-line typescript/no-explicit-any
+declare function section(...args: any[]): import("./doctype/types").LayoutSection
+
+/** Layout helper — creates a column. */
+declare function column(fields: string[]): import("./doctype/types").LayoutColumn
+
+/** Layout helper — creates a tab. */
+declare function tab(
+  label: string,
+  sections: import("./doctype/types").LayoutSection[],
+): import("./doctype/types").LayoutTab
+
+// ─── API ──────────────────────────────────────────────────
+
+/** Mark a function or config as an HTTP endpoint. */
+declare var route: typeof import("./api/route").route
+
+// ─── SSR composables ──────────────────────────────────────
+
+/** Read the server-provided page context inside a Vue SFC `<script setup>`. */
+declare function useContext<T = Record<string, unknown>>(): T

package/src/globals.ts

@@ -0,0 +1,72 @@
+/**
+ * Ambient `frappe` global — a Proxy that delegates to the current AsyncLocalStorage context.
+ *
+ * Also installs ambient globals: defineDocType, controller, field, section, column, tab
+ */
+
+import { route } from "./api/route"
+import { contextStore, type FrappeContext } from "./context"
+import { q } from "./database/query-builder"
+import { doctype, controller } from "./doctype/define"
+import { field } from "./doctype/field"
+import { section, column, tab } from "./doctype/layout"
+import { useContext } from "./ssr/use-context"
+
+export function createFrappeProxy(): FrappeContext {
+  return new Proxy({} as FrappeContext, {
+    get(_, prop: string) {
+      const ctx = contextStore.getStore()
+      if (!ctx) {
+        throw new Error(
+          `frappe.${prop} is not available outside a request context. ` +
+            `Use frappe.initSite("sitename", async (frappe) => { ... }) for scripts.`,
+        )
+      }
+      const value = ctx[prop as keyof FrappeContext]
+      if (typeof value === "function") {
+        return value.bind(ctx)
+      }
+      return value
+    },
+    // oxlint-disable-next-line typescript/no-explicit-any -- Proxy set trap requires `any`
+    set(_, prop: string, value: any) {
+      const ctx = contextStore.getStore()
+      if (!ctx) {
+        throw new Error(`frappe.${prop} cannot be set outside a request context.`)
+      }
+      // oxlint-disable-next-line typescript/no-explicit-any
+      ;(ctx as any)[prop] = value
+      return true
+    },
+  })
+}
+
+/**
+ * Install all ambient globals on globalThis.
+ */
+export function installGlobals(): FrappeContext {
+  const proxy = createFrappeProxy()
+  const g = globalThis as any // oxlint-disable-line typescript/no-explicit-any -- globalThis extension
+
+  // The main frappe global
+  g.frappe = proxy
+
+  // DocType definition globals
+  g.doctype = doctype
+  g.controller = controller
+  g.field = field
+  g.section = section
+  g.column = column
+  g.tab = tab
+
+  // Query builder helpers
+  g.q = q
+
+  // API route marker
+  g.route = route
+
+  // SSR composables — available inside Vue SFC <script setup> blocks
+  g.useContext = useContext
+
+  return proxy
+}

package/src/index.ts

@@ -0,0 +1,112 @@
+/**
+ * Main entry point — re-exports all runtime modules.
+ */
+
+// Layer 0: Foundation
+export * from "./errors"
+export * from "./context"
+export { response } from "./response"
+export type { FrappeResponse } from "./response"
+export { installGlobals, createFrappeProxy } from "./globals"
+export * from "./site"
+export { createServer, initSiteDb, closeAllDbs } from "./server"
+export type { ServerOptions } from "./server"
+
+// Layer 1: DocType
+export {
+  doctype,
+  controller,
+  field,
+  section,
+  column,
+  tab,
+  registerDocType,
+  registerController,
+  getDocTypeMeta,
+  getController,
+  getAllDocTypes,
+  hasDocType,
+  clearRegistry,
+  toTableName,
+  discoverDocTypes,
+} from "./doctype"
+export type {
+  DocTypeSchema,
+  DocTypeDefinition,
+  FieldDefinition,
+  FieldType,
+  FieldOptions,
+  ControllerHooks,
+  ControllerDefinition,
+  NamingStrategy,
+  PermissionRule,
+  PermissionsBlock,
+  PermissionDenial,
+  PermCheckResult,
+  RestConfig,
+  LayoutSection,
+  LayoutColumn,
+  LayoutTab,
+  LayoutEntry,
+  ListConfig,
+  SearchConfig,
+  WorkflowConfig,
+} from "./doctype"
+
+// Layer 1: Database
+export { FrappeDatabase } from "./database"
+export type { GetAllArgs } from "./database"
+export { QueryBuilder, FnExpr, OnCondition, Paginator, fn, q, createQueryBuilder } from "./database"
+export type { BuilderState, ConnectedWhere, WhereNode, OrderByNode, Connector } from "./database"
+
+// Layer 2: Permissions
+export {
+  hasRolePermission,
+  checkDocPermission,
+  checkCreatePermission,
+  getUserRoles,
+  deny,
+  createPermsNamespace,
+} from "./permissions"
+export type { PermsNamespace } from "./permissions"
+
+// Layer 2: API routes
+export {
+  route,
+  isRouteDefinition,
+  inferMethod,
+  camelToKebab,
+  resolveRoutePath,
+  invokeRoute,
+  routeRegistry,
+} from "./api"
+export type { RouteConfig, RouteDefinition, AuthMode, HttpMethod, RouteHandler } from "./api"
+
+// Layer 1: Document
+export { Document, newDoc, getDoc, getList, deleteDoc, getSingle, generateName } from "./document"
+
+// Layer 1: Auth
+export { login, logout, hashPassword, resolveAuth, verifyCsrf, ensureAdminUser } from "./auth"
+
+// Layer 1: Core DocTypes
+export { registerCoreDocTypes } from "./core/doctypes"
+
+// Layer 2: App loading
+export { loadApp, readAppMetadata, findProjectRoot, appNameFromPackage } from "./app"
+export type { LoadedApp, AppMetadata } from "./app"
+
+// Layer 3: Migrations
+export { runMigrations, discoverMigrations } from "./migrations"
+export type { MigrationPhase, MigrationResult, DiscoveredMigration } from "./migrations"
+
+// Layer 2: SSR
+export {
+  loadPages,
+  relPathToRoute,
+  renderPage,
+  renderComponent,
+  useContext,
+  handlePageRequest,
+  createPageMatcher,
+} from "./ssr"
+export type { LoadedPage, GetContextFn, GetContextArgs, RenderOptions, PageMatcher } from "./ssr"

package/src/migrations/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Migrations — three-phase schema/data migration runner.
+ */
+
+export { runMigrations, discoverMigrations, loadExecutedIds, partitionByPhase } from "./runner"
+export type {
+  MigrationPhase,
+  DiscoveredMigration,
+  MigrationRecord,
+  MigrationResult,
+} from "./runner"

package/src/migrations/runner.ts

@@ -0,0 +1,256 @@
+/**
+ * Migration runner — three-phase execution:
+ *
+ *   1. before-sync migrations   (data patches; old schema still in place)
+ *   2. schema sync              (auto: CREATE TABLE / ADD COLUMN)
+ *   3. after-sync migrations    (data patches that need new schema)
+ *
+ * Migration files live in two conventional locations:
+ *   <moduleDir>/migrations/
+ *   <moduleDir>/doctype/<name>/migrations/
+ *
+ * Ordering is strictly filename-alphabetical within each location. Use
+ * numeric or timestamp prefixes (`001_...`, `20260405_...`).
+ *
+ * State is tracked in the core `Migration` DocType so each migration runs
+ * at most once per site.
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs"
+import { join } from "node:path"
+
+import type { FrappeDatabase } from "../database/database"
+
+// ─── Types ────────────────────────────────────────────────
+
+export type MigrationPhase = "before" | "after"
+
+export interface DiscoveredMigration {
+  /** Unique id: `<app>:<relPath>` — stable across runs. */
+  id: string
+  /** Absolute file path for dynamic import. */
+  absPath: string
+  /** Sort key — the filename. */
+  filename: string
+  /** Source: "app" (cross-cutting) or DocType directory name. */
+  source: string
+}
+
+interface MigrationModule {
+  default: () => Promise<void> | void
+  phase?: MigrationPhase
+}
+
+export interface MigrationRecord {
+  id: string
+  phase: MigrationPhase
+  executedAt: string
+  status: "Success" | "Failed"
+  error?: string
+}
+
+export interface MigrationResult {
+  before: MigrationRecord[]
+  after: MigrationRecord[]
+  schemaChanges: number
+}
+
+// ─── Discovery ────────────────────────────────────────────
+
+/**
+ * Discover all migration files under an app module directory.
+ * Returns them in the order they should be considered for execution
+ * (filename-alphabetical within each source).
+ */
+export function discoverMigrations(moduleDir: string, appName: string): DiscoveredMigration[] {
+  const discovered: DiscoveredMigration[] = []
+
+  // 1. App-level: <moduleDir>/migrations/
+  const appMigrationsDir = join(moduleDir, "migrations")
+  if (existsSync(appMigrationsDir)) {
+    for (const file of listMigrationFiles(appMigrationsDir)) {
+      discovered.push({
+        id: `${appName}:${file}`,
+        absPath: join(appMigrationsDir, file),
+        filename: file,
+        source: "app",
+      })
+    }
+  }
+
+  // 2. DocType-level: <moduleDir>/doctype/<name>/migrations/
+  const doctypeDir = join(moduleDir, "doctype")
+  if (existsSync(doctypeDir)) {
+    const doctypes = readdirSync(doctypeDir)
+      .filter((d) => statSync(join(doctypeDir, d)).isDirectory())
+      .sort()
+    for (const dt of doctypes) {
+      const dtMigrations = join(doctypeDir, dt, "migrations")
+      if (!existsSync(dtMigrations)) continue
+      for (const file of listMigrationFiles(dtMigrations)) {
+        discovered.push({
+          id: `${appName}:${dt}/${file}`,
+          absPath: join(dtMigrations, file),
+          filename: file,
+          source: dt,
+        })
+      }
+    }
+  }
+
+  return discovered
+}
+
+function listMigrationFiles(dir: string): string[] {
+  return readdirSync(dir)
+    .filter((f) => f.endsWith(".ts") && !f.endsWith(".d.ts") && !f.endsWith(".test.ts"))
+    .sort()
+}
+
+// ─── Phase partitioning ───────────────────────────────────
+
+/**
+ * Import each migration module and split them by phase. Pending filter
+ * excludes any migration whose id is already recorded as Success.
+ */
+export async function partitionByPhase(
+  migrations: DiscoveredMigration[],
+  alreadyRun: Set<string>,
+): Promise<{ before: PreparedMigration[]; after: PreparedMigration[] }> {
+  const before: PreparedMigration[] = []
+  const after: PreparedMigration[] = []
+
+  for (const m of migrations) {
+    if (alreadyRun.has(m.id)) continue
+    const mod = (await import(m.absPath)) as MigrationModule
+    const phase: MigrationPhase = mod.phase ?? "after"
+    const prepared: PreparedMigration = { ...m, phase, run: mod.default }
+    if (phase === "before") before.push(prepared)
+    else after.push(prepared)
+  }
+
+  return { before, after }
+}
+
+interface PreparedMigration extends DiscoveredMigration {
+  phase: MigrationPhase
+  run: () => Promise<void> | void
+}
+
+// ─── State ────────────────────────────────────────────────
+
+/**
+ * Core `Migration` DocType tracks which migrations have run. We read the
+ * table directly so migration bookkeeping works even before controllers
+ * are loaded.
+ */
+interface MigrationRow extends Record<string, unknown> {
+  name: string
+  migrationName: string
+  status: string
+}
+
+export async function loadExecutedIds(db: FrappeDatabase): Promise<Set<string>> {
+  const rows = await db.sql<MigrationRow>(
+    `SELECT "name", "migrationName", "status" FROM "Migration" WHERE "status" = 'Success'`,
+  )
+  return new Set(rows.map((r) => r.migrationName))
+}
+
+async function recordMigration(
+  db: FrappeDatabase,
+  prepared: PreparedMigration,
+  status: "Success" | "Failed",
+  errorMessage?: string,
+): Promise<void> {
+  const now = new Date().toISOString()
+  db.insertRow("Migration", {
+    name: prepared.id,
+    migrationName: prepared.id,
+    app: prepared.id.split(":")[0] ?? "",
+    phase: prepared.phase,
+    executedAt: now,
+    status,
+    error: errorMessage ?? null,
+    creation: now,
+    modified: now,
+    owner: "Administrator",
+    modifiedBy: "Administrator",
+    docstatus: 0,
+    idx: 0,
+  })
+}
+
+// ─── Execution ────────────────────────────────────────────
+
+/**
+ * Run a list of migrations sequentially, recording each outcome.
+ * Throws on the first failure — subsequent migrations are not attempted.
+ */
+async function runPhase(
+  db: FrappeDatabase,
+  phase: PreparedMigration[],
+): Promise<MigrationRecord[]> {
+  const records: MigrationRecord[] = []
+
+  for (const m of phase) {
+    try {
+      await m.run()
+      await recordMigration(db, m, "Success")
+      records.push({
+        id: m.id,
+        phase: m.phase,
+        executedAt: new Date().toISOString(),
+        status: "Success",
+      })
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error)
+      await recordMigration(db, m, "Failed", msg)
+      records.push({
+        id: m.id,
+        phase: m.phase,
+        executedAt: new Date().toISOString(),
+        status: "Failed",
+        error: msg,
+      })
+      throw error
+    }
+  }
+
+  return records
+}
+
+/**
+ * Full migrate flow: before → schema-sync → after.
+ *
+ * Assumes the `Migration` DocType has already been registered (it is part
+ * of the core DocType set). The schema sync will ensure its table exists
+ * before we try to record anything into it.
+ */
+export async function runMigrations(
+  db: FrappeDatabase,
+  moduleDir: string,
+  appName: string,
+): Promise<MigrationResult> {
+  // Pre-sync the schema once so the Migration table exists before we
+  // try to query it. This is cheap if schema is already up to date.
+  db.migrate()
+
+  const executed = await loadExecutedIds(db)
+  const discovered = discoverMigrations(moduleDir, appName)
+  const { before, after } = await partitionByPhase(discovered, executed)
+
+  const beforeRecords = await runPhase(db, before)
+
+  // Re-run schema sync after before-migrations — they may have renamed
+  // fields/tables, so the target schema diff needs to be recomputed.
+  db.migrate()
+
+  const afterRecords = await runPhase(db, after)
+
+  return {
+    before: beforeRecords,
+    after: afterRecords,
+    schemaChanges: beforeRecords.length + afterRecords.length,
+  }
+}