create-fff-app 0.1.0

package/template/migrate.ts

@@ -0,0 +1,166 @@
+#!/usr/bin/env bun
+/**
+ * D1 migration runner for fff-stack.
+ *
+ * Usage:
+ *   bun run migrate            — apply pending migrations (local D1)
+ *   bun run migrate --remote   — apply pending migrations (production D1)
+ *   bun run migrate --status   — show migration status without applying
+ *
+ * Migration files must be named  NNNN_description.sql  (e.g. 0001_init.sql)
+ * and placed in the  migrations/  directory next to this script.
+ *
+ * Applied migrations are tracked in a  _migrations  table inside D1 itself,
+ * so the system is self-contained and requires no external state.
+ */
+
+import { readdirSync, existsSync } from "fs";
+import path from "path";
+
+const DB_NAME = "fff-stack-db";
+const MIGRATIONS_DIR = path.join(import.meta.dir, "migrations");
+const MIGRATION_PATTERN = /^\d{4}_[\w-]+\.sql$/;
+
+// ── Wrangler helpers ──────────────────────────────────────────────────────────
+
+async function wrangler(args: string[]): Promise<string> {
+  const proc = Bun.spawn(["bunx", "wrangler", ...args], {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (code !== 0) {
+    throw new Error(`wrangler exited ${code}:\n${stderr.trim()}`);
+  }
+  return stdout.trim();
+}
+
+function d1args(extra: string[], local: boolean): string[] {
+  const args = ["d1", "execute", DB_NAME, ...extra];
+  if (local) args.push("--local");
+  return args;
+}
+
+async function execSql(sql: string, local: boolean): Promise<void> {
+  await wrangler(d1args(["--command", sql], local));
+}
+
+async function execFile(filePath: string, local: boolean): Promise<void> {
+  await wrangler(d1args(["--file", filePath], local));
+}
+
+async function querySql(
+  sql: string,
+  local: boolean
+): Promise<Record<string, unknown>[]> {
+  const text = await wrangler(d1args(["--command", sql, "--json"], local));
+  const parsed = JSON.parse(text) as Array<{ results?: unknown[] }>;
+  return (parsed[0]?.results ?? []) as Record<string, unknown>[];
+}
+
+// ── Migrations table ──────────────────────────────────────────────────────────
+
+async function ensureTable(local: boolean): Promise<void> {
+  await execSql(
+    "CREATE TABLE IF NOT EXISTS _migrations (" +
+      "id INTEGER PRIMARY KEY AUTOINCREMENT, " +
+      "name TEXT NOT NULL UNIQUE, " +
+      "applied_at TEXT NOT NULL DEFAULT (datetime('now')))",
+    local
+  );
+}
+
+async function appliedSet(local: boolean): Promise<Set<string>> {
+  const rows = await querySql(
+    "SELECT name FROM _migrations ORDER BY name",
+    local
+  );
+  return new Set(rows.map((r) => r.name as string));
+}
+
+async function recordApplied(name: string, local: boolean): Promise<void> {
+  // filename is validated by MIGRATION_PATTERN so no injection risk
+  await execSql(`INSERT INTO _migrations (name) VALUES ('${name}')`, local);
+}
+
+// ── Migration files ───────────────────────────────────────────────────────────
+
+function listFiles(): string[] {
+  if (!existsSync(MIGRATIONS_DIR)) return [];
+  return readdirSync(MIGRATIONS_DIR)
+    .filter((f) => MIGRATION_PATTERN.test(f))
+    .sort();
+}
+
+// ── Commands ──────────────────────────────────────────────────────────────────
+
+async function migrate(local: boolean): Promise<void> {
+  console.log(`Migrations (${local ? "local" : "remote"}):`);
+
+  await ensureTable(local);
+
+  const files = listFiles();
+  if (files.length === 0) {
+    console.log("  No migration files found in ./migrations/");
+    return;
+  }
+
+  const applied = await appliedSet(local);
+  let count = 0;
+
+  for (const file of files) {
+    if (applied.has(file)) {
+      console.log(`  [skip]   ${file}`);
+      continue;
+    }
+    process.stdout.write(`  [apply]  ${file} ... `);
+    await execFile(path.join(MIGRATIONS_DIR, file), local);
+    await recordApplied(file, local);
+    console.log("done");
+    count++;
+  }
+
+  console.log(
+    count === 0
+      ? "\nAlready up to date."
+      : `\nApplied ${count} migration(s).`
+  );
+}
+
+async function status(local: boolean): Promise<void> {
+  console.log(`Migration status (${local ? "local" : "remote"}):`);
+
+  const files = listFiles();
+  if (files.length === 0) {
+    console.log("  No migration files found.");
+    return;
+  }
+
+  let applied: Set<string>;
+  try {
+    await ensureTable(local);
+    applied = await appliedSet(local);
+  } catch {
+    console.log("  (cannot reach D1 — is wrangler configured?)");
+    return;
+  }
+
+  for (const file of files) {
+    const tag = applied.has(file) ? "[applied]" : "[pending]";
+    console.log(`  ${tag}  ${file}`);
+  }
+}
+
+// ── Entry point ───────────────────────────────────────────────────────────────
+
+const argv = process.argv.slice(2);
+const local = !argv.includes("--remote");
+
+(argv.includes("--status") ? status(local) : migrate(local)).catch((err) => {
+  console.error((err as Error).message ?? String(err));
+  process.exit(1);
+});

package/template/migrations/0001_init.sql

@@ -0,0 +1,25 @@
+-- Initial schema: users and posts tables
+-- Applied automatically by: bun run migrate
+
+CREATE TABLE IF NOT EXISTS users (
+  id         TEXT PRIMARY KEY,
+  name       TEXT NOT NULL,
+  created_at TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_users_created_at ON users(created_at);
+
+CREATE TABLE IF NOT EXISTS posts (
+  id           TEXT PRIMARY KEY,
+  author_id    TEXT NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  title        TEXT NOT NULL,
+  slug         TEXT NOT NULL UNIQUE,
+  body         TEXT NOT NULL,
+  published_at TEXT,
+  created_at   TEXT NOT NULL DEFAULT (datetime('now')),
+  updated_at   TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_posts_slug       ON posts(slug);
+CREATE INDEX IF NOT EXISTS idx_posts_author_id  ON posts(author_id);
+CREATE INDEX IF NOT EXISTS idx_posts_created_at ON posts(created_at);

package/template/migrations/0002_employees.sql

@@ -0,0 +1,16 @@
+-- Employee directory table
+-- Applied automatically by: bun run migrate
+
+CREATE TABLE IF NOT EXISTS employees (
+  id         TEXT PRIMARY KEY,
+  name       TEXT NOT NULL,
+  email      TEXT NOT NULL UNIQUE,
+  department TEXT NOT NULL,
+  role       TEXT NOT NULL,
+  status     TEXT NOT NULL DEFAULT 'active',
+  joined_at  TEXT NOT NULL DEFAULT (date('now'))
+);
+
+CREATE INDEX IF NOT EXISTS idx_employees_name       ON employees(name);
+CREATE INDEX IF NOT EXISTS idx_employees_department ON employees(department);
+CREATE INDEX IF NOT EXISTS idx_employees_status     ON employees(status);

package/template/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "fff-stack-app",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "demo":  "bun run dev-server.ts",
+    "build": "bun run build:assets && bun run build:templates && bun run build:page-templates && bun run build:client && bun run build:server",
+    "build:assets": "mkdir -p dist/client && cp -r public/. dist/client/",
+    "build:templates": "fjsx --dir src/client --out dist/client/templates",
+    "build:page-templates": "fjsx --dir src/server/Endpoints/Pages --out dist/server/Pages",
+    "dev:templates":      "fjsx-watcher --dir src/client --out dist/client/templates",
+    "dev:page-templates": "fjsx-watcher --dir src/server/Endpoints/Pages --out dist/server/Pages",
+    "build:client": "fable src/client/Client.fsproj --outDir dist/client/fable && bun build dist/client/fable/App.js --outdir dist/client --entry-naming bundle.js",
+    "build:server": "fable src/server/Server.fsproj --outDir dist/server",
+    "dev": "concurrently \"bun run dev:templates\" \"bun run dev:page-templates\" \"bun run dev:client\" \"wrangler dev\"",
+    "dev:client": "fable src/client/Client.fsproj --watch --outDir dist/client/fable",
+    "deploy": "wrangler deploy",
+    "migrate": "bun run migrate.ts",
+    "migrate:remote": "bun run migrate.ts --remote",
+    "migrate:status": "bun run migrate.ts --status"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@fff-stack/fjsx-compiler": "^0.1.0",
+    "concurrently": "^8.0.0",
+    "wrangler": "^3.0.0"
+  }
+}

package/template/public/app.js

@@ -0,0 +1,156 @@
+/**
+ * Demo app — mirrors template/src/client/App.fs for the dev server demo.
+ * In production this is replaced by the Fable-compiled output of App.fs.
+ */
+
+import { Component, Template, registerTemplate } from '/runtime.js';
+
+import * as CounterTemplate  from '/templates/Counter.js';
+import * as UserListTemplate from '/templates/UserList.js';
+
+registerTemplate('Counter',  CounterTemplate);
+registerTemplate('UserList', UserListTemplate);
+
+// ── Component definitions (mirrors Counter.fs / UserList.fs) ─────────────────
+
+class Counter extends Component {
+  constructor(id) { super(id); this.Count = 0; }
+  Increment() { this.Count++; this.Render(); }
+  Decrement() { this.Count--; this.Render(); }
+  Reset()     { this.Count = 0; this.Render(); }
+  Render()    { Template.load('Counter.fjsx', this); }
+}
+
+class UserList extends Component {
+  constructor(id) {
+    super(id);
+    this.Users   = [];
+    this.Loading = false;
+    this.Error   = null;
+  }
+
+  async FetchUsers() {
+    this.Loading = true; this.Error = null; this.Render();
+    try {
+      const res  = await fetch('/api/users');
+      this.Users = await res.json();
+    } catch (e) { this.Error = e.message; }
+    this.Loading = false; this.Render();
+  }
+
+  OnMount() { this.FetchUsers(); }
+  Render()  { Template.load('UserList.fjsx', this); }
+}
+
+// ── Island registry (mirrors App.fs registry) ─────────────────────────────────
+
+const _registry = new Map();
+
+function findIsland(name) { return _registry.get(name) ?? null; }
+
+// ── Island mounting (mirrors App.fs mountIslands) ─────────────────────────────
+
+function mountIslands() {
+  document.querySelectorAll('[data-island]').forEach(el => {
+    const name = el.dataset.island;
+    if (!el.id) el.id = `island-${name.toLowerCase()}`;
+
+    let instance;
+    switch (name) {
+      case 'Counter':  instance = new Counter(el.id);  break;
+      case 'UserList': instance = new UserList(el.id); break;
+      default: console.warn(`[fff-stack] Unknown island: ${name}`); return;
+    }
+
+    instance.Mount();
+    if (!_registry.has(name)) _registry.set(name, instance);
+  });
+}
+
+// ── Add-user form (mirrors App.fs setupUserForm) ──────────────────────────────
+
+function setupUserForm() {
+  const form  = document.getElementById('user-form');
+  const input = document.getElementById('user-name-input');
+  const error = document.getElementById('user-error');
+  if (!form) return;
+
+  form.addEventListener('submit', async (e) => {
+    e.preventDefault();
+    if (error) error.textContent = '';
+    const res = await fetch('/api/users', {
+      method:  'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body:    JSON.stringify({ name: input.value.trim() }),
+    });
+    if (res.ok) {
+      input.value = '';
+      findIsland('UserList')?.FetchUsers();
+    } else {
+      const body = await res.json();
+      if (error) error.textContent = body.error ?? 'Error';
+    }
+  });
+}
+
+// ── Delete handler (mirrors App.fs setupDeleteHandler) ───────────────────────
+
+function setupDeleteHandler() {
+  document.addEventListener('click', async (e) => {
+    const btn = e.target.closest('[data-delete-id]');
+    if (!btn) return;
+    await fetch(`/api/users/${btn.dataset.deleteId}`, { method: 'DELETE' });
+    findIsland('UserList')?.FetchUsers();
+  });
+}
+
+// ── Client-side navigation (mirrors Nav.fs) ───────────────────────────────────
+
+function updateNav(pathname) {
+  document.querySelectorAll('.site-nav a').forEach(a => {
+    if (a.getAttribute('href') === pathname) a.classList.add('active');
+    else a.classList.remove('active');
+  });
+}
+
+async function navigate(url) {
+  try {
+    const res = await fetch(url);
+    if (!res.ok) { location.href = url; return; }
+    const html    = await res.text();
+    const parser  = new DOMParser();
+    const doc     = parser.parseFromString(html, 'text/html');
+    const newMain = doc.querySelector('main');
+    const curMain = document.querySelector('main');
+    if (newMain && curMain) {
+      curMain.innerHTML = newMain.innerHTML;
+      const uri = new URL(url, location.href);
+      history.pushState(null, '', uri.pathname);
+      updateNav(uri.pathname);
+      mountIslands(); // re-mount islands in new content
+    } else {
+      location.href = url;
+    }
+  } catch { location.href = url; }
+}
+
+document.addEventListener('click', (e) => {
+  const a = e.target.closest('a');
+  if (!a) return;
+  const sameOrigin  = a.origin === location.origin;
+  const plainClick  = !(e.metaKey || e.ctrlKey || e.shiftKey || e.altKey);
+  const noTarget    = !a.target || a.target === '_self';
+  const noDownload  = !a.getAttribute('download');
+  if (sameOrigin && plainClick && noTarget && noDownload) {
+    e.preventDefault();
+    navigate(a.href);
+  }
+});
+
+window.addEventListener('popstate', () => navigate(location.href));
+
+// ── Init ──────────────────────────────────────────────────────────────────────
+
+mountIslands();
+setupUserForm();
+setupDeleteHandler();

package/template/public/runtime.js

@@ -0,0 +1,149 @@
+/**
+ * fff-stack client runtime (vanilla JS)
+ *
+ * In production this is generated by Fable from packages/client-runtime/*.fs.
+ * In dev we ship this hand-written equivalent so the demo runs without .NET.
+ */
+
+// ── Template registry ─────────────────────────────────────────────────────────
+
+const _registry = new Map();
+
+export function registerTemplate(name, mod) {
+  _registry.set(name, mod);
+}
+
+// ── Mounted component registry (used by HMR) ─────────────────────────────────
+
+const _mounted = new Set();
+
+// ── Component base class ──────────────────────────────────────────────────────
+
+export class Component {
+  constructor(containerId) {
+    this._containerId = containerId;
+    this._mounted     = false;
+    this._handle      = null;
+    this._lastTemplate = null;
+  }
+
+  get ContainerId() { return this._containerId; }
+  get IsMounted()   { return this._mounted; }
+
+  Mount() {
+    this._mounted = true;
+    _mounted.add(this);
+    this.OnMount();
+    this.Render();
+  }
+
+  Hydrate() {
+    this._mounted = true;
+    this._hydrating = true;
+    _mounted.add(this);
+    this.OnMount();
+    this.Render();
+    this._hydrating = false;
+  }
+
+  Unmount() {
+    this._mounted = false;
+    _mounted.delete(this);
+    this.OnDispose();
+    this._handle = null;
+  }
+
+  // Override in subclass
+  Render() {}
+
+  // Optional lifecycle hooks
+  OnMount()   {}
+  OnUpdate()  {}
+  OnDispose() {}
+
+  // Internal — used by Template.load
+  _setHandle(h) { this._handle = h; }
+  _getHandle()  { return this._handle; }
+}
+
+// ── Template.load / Template.hydrate ─────────────────────────────────────────
+
+export const Template = {
+  /**
+   * Called from Component.Render().
+   * First call: finds the registered compiled template, calls init().
+   * Subsequent calls: calls the stored handle's update().
+   */
+  load(templateName, component) {
+    const name      = templateName.replace('.fjsx', '');
+    const container = document.getElementById(component.ContainerId);
+    if (!container)
+      throw new Error(`fff-stack: container '#${component.ContainerId}' not found in the DOM`);
+
+    // Track which template this component last rendered with (for HMR)
+    component._lastTemplate = name;
+
+    const handle = component._getHandle();
+    if (handle) {
+      handle.update(component);
+      component.OnUpdate();
+      return;
+    }
+
+    const mod = _registry.get(name);
+    if (!mod)
+      throw new Error(`fff-stack: template '${name}' not registered. Import it before mounting.`);
+
+    const newHandle = component._hydrating
+      ? mod.hydrate(component, container)
+      : mod.init(component, container);
+    component._setHandle(newHandle);
+  },
+
+  /**
+   * Hydrate a server-rendered container.
+   * Attaches to existing server-rendered HTML without clearing it.
+   */
+  hydrate(templateName, component) {
+    component._hydrating = true;
+    component._setHandle(null);
+    this.load(templateName, component);
+    component._hydrating = false;
+  },
+};
+
+// ── Hot-reload (dev only) ─────────────────────────────────────────────────────
+
+const sse = new EventSource('/__sse');
+
+sse.addEventListener('reload', async (e) => {
+  const { template } = JSON.parse(e.data);
+
+  try {
+    // Re-import the compiled template with a cache-busting query param.
+    // ES module cache is keyed by URL, so the ?t= makes this a fresh request.
+    const mod = await import(`/templates/${template}.js?t=${Date.now()}`);
+    registerTemplate(template, mod);
+
+    // Re-render every mounted component that uses this template.
+    let count = 0;
+    for (const comp of _mounted) {
+      if (comp._lastTemplate === template) {
+        comp._setHandle(null); // force re-init on next Render()
+        comp.Render();
+        count++;
+      }
+    }
+
+    if (count > 0) {
+      console.log(`[HMR] '${template}' hot-swapped (${count} component${count > 1 ? 's' : ''})`);
+    } else {
+      // No mounted components use this template — full reload as fallback.
+      console.log(`[HMR] '${template}' changed, no mounted components found → reloading`);
+      location.reload();
+    }
+  } catch (err) {
+    console.warn(`[HMR] hot-swap failed for '${template}', falling back to reload:`, err);
+    location.reload();
+  }
+});