frappebun 0.0.0

package/src/cli/commands/init.ts

@@ -0,0 +1,98 @@
+/**
+ * `frappe init <name>` — scaffold a complete, runnable project.
+ *
+ * Creates:
+ *   myapp/
+ *     package.json
+ *     tsconfig.json
+ *     .gitignore
+ *     myapp/              ← app module
+ *       pages/index.vue
+ *       doctype/
+ *       api/
+ *     sites/<name>.localhost/site_config.json
+ *     sites/common_site_config.json
+ *
+ * Does NOT run `bun install`, `git init`, or `frappe migrate` — that is
+ * the caller's responsibility and keeps this command trivially testable.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+import type { CliArgs } from "../args"
+import { log } from "../log"
+import {
+  commonSiteConfigTpl,
+  frappeEnvTpl,
+  gitignoreTpl,
+  packageJsonTpl,
+  siteConfigTpl,
+  tsconfigTpl,
+  vscodeLaunchTpl,
+  welcomePageTpl,
+} from "../scaffold/templates"
+
+export interface InitOptions {
+  /** Absolute project root to create. */
+  root: string
+  /** App name — used as both package name and app module directory name. */
+  name: string
+  /** Default site name seeded in common_site_config.json. */
+  site?: string
+}
+
+/** Scaffold a new project at `root`. Safe to call from tests. */
+export function scaffoldProject(opts: InitOptions): string[] {
+  const { root, name } = opts
+  const site = opts.site ?? `${name}.localhost`
+
+  if (existsSync(root)) throw new Error(`Directory already exists: ${root}`)
+
+  const written: string[] = []
+  const write = (relPath: string, content: string) => {
+    const abs = join(root, relPath)
+    mkdirSync(join(abs, ".."), { recursive: true })
+    writeFileSync(abs, content)
+    written.push(relPath)
+  }
+
+  // Root config
+  write("package.json", packageJsonTpl(name))
+  write("tsconfig.json", tsconfigTpl())
+  write(".gitignore", gitignoreTpl())
+  write(".vscode/launch.json", vscodeLaunchTpl())
+  write("frappe-env.d.ts", frappeEnvTpl())
+
+  // App module scaffolding
+  write(`${name}/pages/index.vue`, welcomePageTpl())
+  mkdirSync(join(root, name, "doctype"), { recursive: true })
+  mkdirSync(join(root, name, "api"), { recursive: true })
+
+  // Sites
+  write(`sites/${site}/site_config.json`, siteConfigTpl())
+  write("sites/common_site_config.json", commonSiteConfigTpl(site))
+
+  return written
+}
+
+export async function run(args: CliArgs): Promise<void> {
+  const name = args.positional[0]
+  if (!name) {
+    log.error("Usage: frappe init <name>")
+    process.exit(1)
+  }
+
+  const root = join(process.cwd(), name)
+  log.step(`Creating ${name}...`)
+
+  const written = scaffoldProject({ root, name })
+  for (const file of written) log.success(`${name}/${file}`)
+
+  log.blank()
+  log.info(`Done! Next steps:`)
+  log.info(`    cd ${name}`)
+  log.info(`    bun install`)
+  log.info(`    frappe dev`)
+  log.blank()
+}

package/src/cli/commands/migrate.ts

@@ -0,0 +1,110 @@
+/**
+ * `frappe migrate` — load the app, sync schema, run migrations.
+ *
+ *   Phase 1: before-sync migrations
+ *   Phase 2: schema sync
+ *   Phase 3: after-sync migrations
+ */
+
+import { existsSync, readdirSync, statSync } from "node:fs"
+import { join } from "node:path"
+
+import { loadApp, findProjectRoot } from "../../app/loader"
+import { registerCoreDocTypes } from "../../core/doctypes"
+import { FrappeDatabase } from "../../database/database"
+import { installGlobals } from "../../globals"
+import { runMigrations } from "../../migrations/runner"
+import { loadSiteConfig } from "../../site"
+import { flagString, type CliArgs } from "../args"
+import { log } from "../log"
+
+export interface MigrateOptions {
+  root: string
+  sitesDir: string
+  /** Migrate only this site. If omitted, migrate all sites. */
+  site?: string
+  /** Suppress per-migration log lines — `frappe dev` uses this for its own output. */
+  quiet?: boolean
+}
+
+export interface SiteMigrationResult {
+  site: string
+  /** Number of migrations that ran. */
+  ran: number
+  failed: boolean
+  error?: string
+}
+
+// ─── Core ─────────────────────────────────────────────────
+
+export function discoverSites(sitesDir: string): string[] {
+  if (!existsSync(sitesDir)) return []
+  return readdirSync(sitesDir).filter((e) => {
+    if (e.startsWith(".") || e === "common_site_config.json") return false
+    return (
+      statSync(join(sitesDir, e)).isDirectory() && existsSync(join(sitesDir, e, "site_config.json"))
+    )
+  })
+}
+
+export async function migrate(opts: MigrateOptions): Promise<SiteMigrationResult[]> {
+  installGlobals()
+  await registerCoreDocTypes()
+
+  const app = await loadApp(opts.root)
+  const sites = opts.site ? [opts.site] : discoverSites(opts.sitesDir)
+  const results: SiteMigrationResult[] = []
+
+  for (const site of sites) {
+    const dbPath = join(opts.sitesDir, site, "site.db")
+    loadSiteConfig(site, opts.sitesDir) // validates site exists
+
+    const db = new FrappeDatabase(dbPath)
+    try {
+      if (!opts.quiet) {
+        log.info(``)
+        log.info(`  Migrating ${site}...`)
+      }
+
+      const result = await runMigrations(db, app.moduleDir, app.name)
+      const ran = result.before.length + result.after.length
+
+      if (!opts.quiet) {
+        for (const r of result.before) log.success(`[before] ${r.id}`)
+        for (const r of result.after) log.success(`[after]  ${r.id}`)
+        log.info(`  ${ran} migration(s) executed`)
+      }
+
+      results.push({ site, ran, failed: false })
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error)
+      if (!opts.quiet) log.error(`  ${site}: ${msg}`)
+      results.push({ site, ran: 0, failed: true, error: msg })
+    } finally {
+      db.close()
+    }
+  }
+
+  return results
+}
+
+// ─── CLI entry ────────────────────────────────────────────
+
+export async function run(args: CliArgs): Promise<void> {
+  const root = findProjectRoot()
+  const sitesDir = join(root, "sites")
+  const site = flagString(args, "site")
+
+  const results = await migrate({ root, sitesDir, site })
+
+  log.info(``)
+  for (const r of results) {
+    if (r.failed) {
+      log.error(`  ${r.site} — ${r.error}`)
+    } else {
+      const label = r.ran > 0 ? `${r.ran} migration(s) applied` : "schema up to date"
+      log.success(`  ${r.site} — ${label}`)
+    }
+  }
+  log.blank()
+}

package/src/cli/commands/new-site.ts

@@ -0,0 +1,61 @@
+/**
+ * `frappe new-site <name>` — create a site directory, write its config,
+ * initialise an empty SQLite DB, and migrate core DocTypes into it.
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { registerCoreDocTypes } from "../../core/doctypes"
+import { FrappeDatabase } from "../../database/database"
+import { flagString, type CliArgs } from "../args"
+import { log } from "../log"
+
+export interface NewSiteOptions {
+  /** Absolute path to the sites/ directory. */
+  sitesDir: string
+  /** Site name (used as both directory name and hostname). */
+  name: string
+  /** Database type — Phase 2 only supports sqlite. */
+  dbType?: "sqlite"
+}
+
+/**
+ * Create a new site directory with config + migrated database.
+ * Returns the site's DB instance (caller closes it).
+ */
+export async function createSite(opts: NewSiteOptions): Promise<FrappeDatabase> {
+  const siteDir = join(opts.sitesDir, opts.name)
+  if (existsSync(siteDir)) throw new Error(`Site already exists: ${opts.name}`)
+
+  mkdirSync(siteDir, { recursive: true })
+  writeFileSync(
+    join(siteDir, "site_config.json"),
+    `${JSON.stringify({ db_type: opts.dbType ?? "sqlite" }, null, 2)}\n`,
+  )
+
+  await registerCoreDocTypes()
+
+  const db = new FrappeDatabase(join(siteDir, "site.db"))
+  db.migrate()
+  return db
+}
+
+export async function run(args: CliArgs): Promise<void> {
+  const name = args.positional[0]
+  if (!name) {
+    log.error("Usage: frappe new-site <name>")
+    process.exit(1)
+  }
+
+  const sitesDir = flagString(args, "sites", join(process.cwd(), "sites"))!
+  log.step(`Creating site ${name}...`)
+
+  const db = await createSite({ sitesDir, name })
+  db.close()
+
+  log.success(`sites/${name}/site_config.json`)
+  log.success("Database initialised")
+  log.success("Core tables migrated")
+  log.blank()
+}

package/src/cli/commands/routes.ts

@@ -0,0 +1,56 @@
+/**
+ * `frappe routes` — print all registered API routes and page handlers.
+ *
+ * Loads the app (registering DocTypes and routes) then prints a formatted
+ * table to stdout. Useful for debugging "why is my endpoint 404?".
+ */
+
+import { routeRegistry } from "../../api/route"
+import { findProjectRoot, loadApp } from "../../app/loader"
+import { registerCoreDocTypes } from "../../core/doctypes"
+import { installGlobals } from "../../globals"
+import { loadPages } from "../../ssr/page-loader"
+import type { CliArgs } from "../args"
+import { log } from "../log"
+
+export async function run(_args: CliArgs): Promise<void> {
+  installGlobals()
+  await registerCoreDocTypes()
+
+  const root = findProjectRoot()
+  const app = await loadApp(root)
+  const pages = await loadPages(app.moduleDir)
+
+  // ── API routes ────────────────────────────────────────
+  const routes = routeRegistry.list()
+  log.info("")
+  log.info(`  API routes (${routes.length})`)
+  log.info(`  ${"─".repeat(60)}`)
+
+  if (routes.length === 0) {
+    log.info("  (none)")
+  } else {
+    const methodWidth = 6
+    for (const r of routes) {
+      const method = r.method.padEnd(methodWidth)
+      const auth = r.auth === "public" ? "  public" : r.auth === "guest-only" ? "  guest" : ""
+      log.info(`  ${method} ${r.path}${auth}`)
+    }
+  }
+
+  // ── Pages ─────────────────────────────────────────────
+  log.info("")
+  log.info(`  Pages (${pages.length})`)
+  log.info(`  ${"─".repeat(60)}`)
+
+  if (pages.length === 0) {
+    log.info("  (none)")
+  } else {
+    for (const p of pages) {
+      const ctx = p.getContext ? "  + getContext" : ""
+      log.info(`  GET    ${p.routePath}${ctx}`)
+    }
+  }
+
+  log.info("")
+}

package/src/cli/commands/use.ts

@@ -0,0 +1,30 @@
+/**
+ * `frappe use <site>` — set the default site in common_site_config.json.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+
+import { findProjectRoot } from "../../app/loader"
+import type { CliArgs } from "../args"
+import { log } from "../log"
+
+export function setDefaultSite(sitesDir: string, site: string): void {
+  const configPath = join(sitesDir, "common_site_config.json")
+  const existing = existsSync(configPath)
+    ? (JSON.parse(readFileSync(configPath, "utf-8")) as Record<string, unknown>)
+    : {}
+  existing["default_site"] = site
+  writeFileSync(configPath, `${JSON.stringify(existing, null, 2)}\n`)
+}
+
+export async function run(args: CliArgs): Promise<void> {
+  const site = args.positional[0]
+  if (!site) {
+    log.error("Usage: frappe use <site>")
+    process.exit(1)
+  }
+  const sitesDir = join(findProjectRoot(), "sites")
+  setDefaultSite(sitesDir, site)
+  log.success(`default_site = ${site}`)
+}

package/src/cli/index.ts

@@ -0,0 +1,73 @@
+/**
+ * CLI entry point. Parses argv, dispatches to a lazy-loaded command module.
+ *
+ * Commands are dynamically imported so `frappe --help` stays instant and
+ * one broken command can never take down the rest of the CLI.
+ */
+
+import { parseArgs } from "./args"
+import { log } from "./log"
+
+type CommandModule = { run: (args: ReturnType<typeof parseArgs>) => Promise<void> }
+
+const commands: Record<string, () => Promise<CommandModule>> = {
+  "init": () => import("./commands/init"),
+  "dev": () => import("./commands/dev"),
+  "migrate": () => import("./commands/migrate"),
+  "routes": () => import("./commands/routes"),
+  "new-site": () => import("./commands/new-site"),
+  "drop-site": () => import("./commands/drop-site"),
+  "use": () => import("./commands/use"),
+  "add-doctype": () => import("./commands/add-doctype"),
+  "add-api": () => import("./commands/add-api"),
+  "add-page": () => import("./commands/add-page"),
+  "add-user": () => import("./commands/add-user"),
+}
+
+export async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
+  const [command, ...rest] = argv
+  const loader = command ? commands[command] : undefined
+
+  if (!command || command === "--help" || command === "-h") {
+    printHelp()
+    process.exit(command ? 0 : 0)
+  }
+
+  if (!loader) {
+    log.error(`Unknown command: ${command}`)
+    printHelp()
+    process.exit(1)
+  }
+
+  const mod = await loader()
+  await mod.run(parseArgs(rest))
+}
+
+function printHelp(): void {
+  log.info("")
+  log.info("  frappe — Frappe Framework CLI")
+  log.info("")
+  log.info("  Usage: frappe <command> [options]")
+  log.info("")
+  log.info("  Commands:")
+  log.info("    init <name>          Scaffold a new Frappe project")
+  log.info("    dev                  Start the development server")
+  log.info("    routes               List all API routes and pages")
+  log.info("    migrate              Sync schemas & run migrations")
+  log.info("    new-site <name>      Create a new site")
+  log.info("    drop-site <name>     Delete a site")
+  log.info("    use <site>           Set the default site")
+  log.info("    add-doctype <Name>   Scaffold a new DocType")
+  log.info("    add-api <name>       Scaffold a new API route file")
+  log.info("    add-page <path>      Scaffold a new SSR page")
+  log.info("    add-user <email>     Create a user on the default site")
+  log.info("")
+}
+
+// When executed directly (e.g. via a shim `#!/usr/bin/env bun`).
+if (import.meta.main) {
+  main().catch((err: unknown) => {
+    log.error(err instanceof Error ? err.message : String(err))
+    process.exit(1)
+  })
+}

package/src/cli/log.ts

@@ -0,0 +1,13 @@
+/**
+ * Minimal logger for CLI output — plain text, no color deps.
+ * Functions are tiny and self-contained so tests can spy on them.
+ */
+
+export const log = {
+  info: (msg: string) => console.log(msg),
+  success: (msg: string) => console.log(`  ✓ ${msg}`),
+  warn: (msg: string) => console.warn(`  ! ${msg}`),
+  error: (msg: string) => console.error(`  ✗ ${msg}`),
+  step: (msg: string) => console.log(`\n  ${msg}\n`),
+  blank: () => console.log(""),
+}

package/src/cli/scaffold/templates.ts

@@ -0,0 +1,189 @@
+/**
+ * Inline scaffold templates for `frappe init` and `frappe add-*` commands.
+ *
+ * Kept as functions so we can interpolate the app name cleanly without
+ * pulling in a template library.
+ */
+
+export function packageJsonTpl(name: string): string {
+  return `${JSON.stringify(
+    {
+      name,
+      version: "0.0.1",
+      private: true,
+      frappe: { title: titleCase(name) },
+      scripts: {
+        dev: "frappe dev",
+        test: "frappe test",
+        build: "frappe build",
+        typecheck: "tsc --noEmit",
+      },
+      dependencies: { frappebun: "^0.0.1", vue: "^3.5.0" },
+      devDependencies: { "@types/bun": "latest", "typescript": "^5.0.0" },
+    },
+    null,
+    2,
+  )}\n`
+}
+
+export function vscodeLaunchTpl(): string {
+  return `{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "bun",
+      "request": "launch",
+      "name": "frappe dev",
+      "program": "\${workspaceFolder}/node_modules/frappebun/src/cli/bin.ts",
+      "args": ["dev"],
+      "cwd": "\${workspaceFolder}",
+      "stopOnEntry": false,
+      "watchMode": false
+    }
+  ]
+}\n`
+}
+
+export function frappeEnvTpl(): string {
+  return `/// <reference path="./node_modules/frappebun/src/frappe.d.ts" />\n`
+}
+
+export function tsconfigTpl(): string {
+  return `{
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM"],
+    "target": "ESNext",
+    "module": "Preserve",
+    "moduleDetection": "force",
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedIndexedAccess": true,
+    // picks up @types/* packages AND frappebun's ambient globals
+    "typeRoots": ["./node_modules/@types", "./node_modules"]
+  }
+}\n`
+}
+
+export function gitignoreTpl(): string {
+  return [
+    "node_modules/",
+    "sites/*/site.db",
+    "sites/*/site.db-*",
+    "*.sqlite",
+    "*.sqlite-shm",
+    "*.sqlite-wal",
+    ".frappe-cache/",
+    "",
+  ].join("\n")
+}
+
+export function siteConfigTpl(): string {
+  return `${JSON.stringify({ db_type: "sqlite" }, null, 2)}\n`
+}
+
+export function commonSiteConfigTpl(defaultSite: string): string {
+  return `${JSON.stringify({ default_site: defaultSite }, null, 2)}\n`
+}
+
+export function welcomePageTpl(): string {
+  return `<script context>
+  export default async function getContext() {
+    const userCount = await frappe.db.count("User")
+    return {
+      siteName: frappe.site,
+      userCount,
+    }
+  }
+</script>
+
+<script setup lang="ts">
+  const { siteName, userCount } = useContext<{
+    siteName: string
+    userCount: number
+  }>()
+</script>
+
+<template>
+  <main style="font-family: system-ui; max-width: 40rem; margin: 4rem auto; padding: 0 1rem">
+    <h1>Welcome to {{ siteName }}</h1>
+    <p>Your Frappe app is running — {{ userCount }} user(s) registered.</p>
+    <p>
+      Next steps: run
+      <code>frappe add-doctype "My First DocType"</code>
+    </p>
+  </main>
+</template>
+`
+}
+
+export function doctypeSchemaTpl(name: string): string {
+  return `export default doctype(${JSON.stringify(name)}, {
+  naming: "autoincrement",
+  fields: {
+    title: field.data(),
+  },
+})
+`
+}
+
+export function doctypeControllerTpl(name: string): string {
+  return `export default controller(${JSON.stringify(name)}, {
+  // validate(doc) { },
+  // beforeInsert(doc) { },
+  // afterInsert(doc) { },
+  // beforeSave(doc) { },
+  // afterSave(doc) { },
+  // onTrash(doc) { },
+})
+`
+}
+
+export function apiRouteTpl(): string {
+  return `export const ping = route(async () => {
+  return { message: "pong" }
+})
+`
+}
+
+export function pageTpl(): string {
+  return `<script context>
+  export default async function getContext() {
+    return { now: new Date().toISOString() }
+  }
+</script>
+
+<script setup lang="ts">
+  const { now } = useContext<{ now: string }>()
+</script>
+
+<template>
+  <main>
+    <h1>New page</h1>
+    <p>Rendered at {{ now }}</p>
+  </main>
+</template>
+`
+}
+
+// ─── Helpers ──────────────────────────────────────────────
+
+function titleCase(s: string): string {
+  return s
+    .split(/[-_\s]+/)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ")
+}
+
+/** Lowercase, underscore-separated slug used for DocType directory names. */
+export function slugify(s: string): string {
+  return s
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "")
+}