spark-ssr 0.1.0

package/README.md

@@ -0,0 +1,117 @@
+# spark-ssr
+
+**Zero config. No build. SSR the Spark way.**
+
+The framework reads the HTML template and infers everything:
+
+```html
+<!-- index.html -->
+<h1>Tasks</h1>
+
+<template await="todos">
+  <input bind:value="draft" placeholder="New task">
+  <button onclick={add}>Add</button>
+  <template each="todo in todos">
+    <li>
+      <input type="checkbox" bind:checked="todo.done" onchange={patch}>
+      {todo.title}
+      <button onclick={remove}>✕</button>
+    </li>
+  </template>
+</template>
+
+<spark-ssr table="todos" />
+```
+
+```bash
+bun spark-ssr
+```
+
+That's it.
+
+| The template says                               | The framework knows                          |
+| ----------------------------------------------- | -------------------------------------------- |
+| `<template each="todo in todos">`               | You need data called `todos`                 |
+| `table="todos"`                                 | It's backed by the `todos` table             |
+| `onclick={add}` (outside the loop)              | `POST /api/todos` — insert                   |
+| `bind:checked="todo.done"` + `onchange={patch}` | `PATCH /api/todos/:id` — update `done`       |
+| `onclick={remove}` (inside the loop)            | `DELETE /api/todos/:id` — remove the row     |
+| `bind:value="draft"`                            | Local state variable `draft`                 |
+| `user_id` column in the table                   | Auth — `WHERE user_id = :session.id`         |
+
+No `<script>`. No SQL. No ORM. No server file. No build step.
+
+## Config (spark.json)
+
+```json
+{
+  "db": "postgres://localhost:5432/myapp",
+  "auth": { "table": "users", "identity": "email", "secret": "ENV.SESSION_SECRET" },
+  "cors": true
+}
+```
+
+`sqlite://./dev.db` works too (Bun ships both drivers). `ENV.*` values resolve
+from the environment at startup. `cors: true` allows all origins on `/api/*`;
+an array allows specific ones.
+
+## Routing
+
+The filesystem is the router. `pages/index.html` → `/`,
+`pages/blog/[slug].html` → `/blog/:slug` (`:slug` binds into queries).
+Without a `pages/` folder, `*.html` at the project root serve the same way.
+
+## Explicit queries
+
+```html
+<!-- pages/search.html -->
+<h1>Results for "{q}"</h1>
+<template each="result in results">
+  <p>{result.title}</p>
+</template>
+
+<spark-ssr>
+  GET /api/search → SELECT * FROM posts WHERE title LIKE '%' || :q || '%' LIMIT 20
+</spark-ssr>
+```
+
+`:` params inject automatically: path params (`:slug`), query string (`:q`),
+JSON body (`:body.title`), session (`:session.id`), headers
+(`:header.x-forwarded-for`), uploads (`:file.url`).
+
+## Custom endpoints — api/
+
+`api/stats.html` auto-serves as `GET /api/stats`:
+
+```html
+<spark-ssr>
+  GET → SELECT COUNT(*) AS videos FROM videos
+</spark-ssr>
+```
+
+Or drop to a `<script>` (runs server-side; `req`, `res`, `db`, `fetch` in
+scope; the return value becomes the JSON response).
+
+## Everything else
+
+- **Components** — `<div import="/components/card" title="{post.title}">`
+  inlines at render time; components are pure UI.
+- **Auth** — built-in email/password sessions (`POST /api/users?auth` logs in,
+  passwords hash on insert), or a plugin (`auth.plugin` in spark.json).
+- **Middleware** — `middleware.html` runs on every request (`req`, `res`,
+  `rateLimit`, `state` in scope; return `{ status, body }` to short-circuit).
+- **Uploads** — multipart bodies stream to `uploads/`; `:file.url` binds the
+  stored URL into your INSERT.
+- **Error pages** — `404.html` / `500.html` at the project root.
+- **Static assets** — `public/` plus co-located page assets, served as-is.
+- **Hydration** — interactive pages ship fully-rendered HTML plus a generated
+  client component; `mount()` takes over with the same spark-html runtime.
+
+## Deploy
+
+```bash
+bun spark-ssr build   # dist/ with a compiled single binary
+bun spark-ssr start   # run in production
+```
+
+MIT

package/bin/cli.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env bun
+/**
+ * spark-ssr CLI
+ *
+ *   bun spark-ssr                serve the current directory (default)
+ *   bun spark-ssr --port 3000    pick a port
+ *   bun spark-ssr build          assemble dist/ (+ compiled binary)
+ *   bun spark-ssr start          serve dist/ if built, else the project
+ *
+ * Options:
+ *   --port <n>      Port (default 3000, or PORT env).
+ *   --root <dir>    Project root (default cwd).
+ *   --no-compile    build: skip the single-binary compile, copy only.
+ *   -h, --help      Show this help.
+ */
+import { join, resolve } from 'node:path';
+import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync, readdirSync, statSync } from 'node:fs';
+import { serve } from '../src/index.js';
+
+function parseArgs(argv) {
+  const opts = { cmd: 'serve', compile: true };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') opts.help = true;
+    else if (a === '--port') opts.port = Number(argv[++i]);
+    else if (a === '--root') opts.root = argv[++i];
+    else if (a === '--no-compile') opts.compile = false;
+    else if (a === 'build' || a === 'start' || a === 'serve') opts.cmd = a;
+    else if (a.startsWith('--')) { console.error(`Unknown option: ${a}`); process.exit(2); }
+  }
+  return opts;
+}
+
+const HELP = `spark-ssr — zero-config SSR for spark-html on Bun
+
+Usage:
+  bun spark-ssr [serve] [--port <n>] [--root <dir>]
+  bun spark-ssr build [--no-compile]
+  bun spark-ssr start
+`;
+
+// The project files a deployment needs — pages, components, api, public,
+// error pages, middleware, config. node_modules/dist/uploads stay behind.
+const SHIP_DIRS = ['pages', 'components', 'api', 'public'];
+const SHIP_FILES = ['404.html', '500.html', 'middleware.html', 'spark.json', 'package.json'];
+
+async function build(root, compile) {
+  const dist = join(root, 'dist');
+  rmSync(dist, { recursive: true, force: true });
+  mkdirSync(dist, { recursive: true });
+  for (const d of SHIP_DIRS) {
+    if (existsSync(join(root, d))) cpSync(join(root, d), join(dist, d), { recursive: true });
+  }
+  for (const f of SHIP_FILES) {
+    if (existsSync(join(root, f))) cpSync(join(root, f), join(dist, f));
+  }
+  // Zero-config single-file projects keep their root pages/assets.
+  if (!existsSync(join(root, 'pages'))) {
+    for (const f of readdirSync(root)) {
+      if (f === 'dist' || f === 'node_modules' || f.startsWith('.')) continue;
+      const full = join(root, f);
+      if (statSync(full).isFile() && /\.(html|css|js|json|png|jpg|svg|ico|webp)$/.test(f)
+        && !SHIP_FILES.includes(f)) {
+        cpSync(full, join(dist, f));
+      }
+    }
+  }
+  writeFileSync(join(dist, '__server.js'),
+    "import { serve } from 'spark-ssr';\n" +
+    'serve({ root: process.cwd(), port: Number(process.env.PORT) || 3000 });\n');
+  console.log(`✓ assembled dist/`);
+  if (compile) {
+    const r = Bun.spawnSync(
+      ['bun', 'build', '--compile', join(dist, '__server.js'), '--outfile', join(dist, 'app')],
+      { cwd: root, stdout: 'inherit', stderr: 'inherit' },
+    );
+    if (r.exitCode !== 0) process.exit(r.exitCode);
+    console.log('✓ compiled dist/app — run it from dist/ (reads pages/ next to it)');
+  }
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (opts.help) { process.stdout.write(HELP); process.exit(0); }
+
+const root = resolve(opts.root || process.cwd());
+const port = opts.port ?? (Number(process.env.PORT) || 3000);
+
+if (opts.cmd === 'build') {
+  await build(root, opts.compile);
+} else if (opts.cmd === 'start') {
+  const dist = join(root, 'dist');
+  await serve({ root: existsSync(join(dist, '__server.js')) ? dist : root, port });
+} else {
+  await serve({ root, port });
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "spark-ssr",
+  "version": "0.1.0",
+  "description": "Zero-config SSR for spark-html on Bun. The HTML template infers everything: filesystem routing, <spark-ssr> declarative queries, auto CRUD APIs, sessions, uploads, middleware. No build step.",
+  "homepage": "https://wilkinnovo.github.io/spark-html",
+  "type": "module",
+  "main": "./src/index.js",
+  "bin": {
+    "spark-ssr": "./bin/cli.js"
+  },
+  "exports": {
+    ".": {
+      "default": "./src/index.js"
+    }
+  },
+  "files": [
+    "src",
+    "bin"
+  ],
+  "engines": {
+    "bun": ">=1.2.0"
+  },
+  "scripts": {
+    "test": "bun test/ssr.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wilkinnovo/spark-html.git",
+    "directory": "packages/spark-ssr"
+  },
+  "dependencies": {
+    "linkedom": "^0.18.12",
+    "spark-html": "^0.27.0"
+  },
+  "keywords": [
+    "spark-html",
+    "ssr",
+    "bun",
+    "no-build",
+    "sql",
+    "html",
+    "server"
+  ],
+  "license": "MIT"
+}

package/src/config.js

@@ -0,0 +1,40 @@
+/**
+ * spark.json — the whole config. Values prefixed "ENV." resolve from
+ * process.env at load time, so secrets never live in the file.
+ *
+ *   { "db": "sqlite://./dev.db",
+ *     "auth": { "table": "users", "identity": "email", "secret": "ENV.SESSION_SECRET" },
+ *     "cors": true }
+ */
+import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+
+function resolveEnv(v) {
+  if (typeof v === 'string' && v.startsWith('ENV.')) {
+    const key = v.slice(4);
+    const val = process.env[key];
+    if (val === undefined) {
+      throw new Error(`spark.json references ${v} but ${key} is not set in the environment`);
+    }
+    return val;
+  }
+  if (Array.isArray(v)) return v.map(resolveEnv);
+  if (v && typeof v === 'object') {
+    const out = {};
+    for (const [k, val] of Object.entries(v)) out[k] = resolveEnv(val);
+    return out;
+  }
+  return v;
+}
+
+export function loadConfig(root) {
+  const file = join(root, 'spark.json');
+  const raw = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+  const cfg = resolveEnv(raw);
+  return {
+    db: cfg.db || null,
+    auth: cfg.auth || null,
+    cors: cfg.cors ?? false,
+    uploads: cfg.uploads || 'uploads',
+  };
+}

package/src/db.js

@@ -0,0 +1,72 @@
+/**
+ * One tiny adapter per driver, no ORM. SQL arrives with `?` placeholders and
+ * an ordered values array (the `:param` → `?` rewrite is quote-aware and
+ * happens in parse.js). Bun ships both drivers — nothing to install.
+ *
+ *   sqlite://./dev.db   sqlite::memory:        → bun:sqlite
+ *   postgres://…        postgresql://…         → Bun.SQL
+ */
+
+// Statements that produce rows (SELECT/WITH, or anything RETURNING) go
+// through .all(); the rest through .run() so we still get change counts.
+const yieldsRows = (sql) => /^\s*(select|with)\b/i.test(sql) || /\breturning\b/i.test(sql);
+
+// sqlite binds primitives only — flatten anything else.
+const bindable = (v) =>
+  v === undefined ? null
+  : v === null || typeof v === 'number' || typeof v === 'string' || typeof v === 'bigint' ? v
+  : typeof v === 'boolean' ? (v ? 1 : 0)
+  : JSON.stringify(v);
+
+export async function connect(url) {
+  if (!url) return null;
+
+  if (url.startsWith('sqlite:')) {
+    const { Database } = await import('bun:sqlite');
+    let path = url.slice('sqlite:'.length).replace(/^\/\//, '');
+    if (path === '' || path === ':memory:') path = ':memory:';
+    const db = new Database(path, { create: true });
+    return {
+      kind: 'sqlite',
+      async query(sql, values = []) {
+        const vals = values.map(bindable);
+        if (yieldsRows(sql)) return db.query(sql).all(...vals);
+        const r = db.run(sql, vals);
+        return Object.assign([], { changes: r.changes, lastInsertRowid: r.lastInsertRowid });
+      },
+      async columns(table) {
+        if (!/^\w+$/.test(table)) return [];
+        try {
+          return db.query(`PRAGMA table_info(${table})`).all()
+            .map((c) => ({ name: c.name, type: String(c.type || '').toUpperCase() }));
+        } catch { return []; }
+      },
+      close() { db.close(); },
+      raw: db,
+    };
+  }
+
+  if (/^postgres(ql)?:/.test(url)) {
+    const sql = new Bun.SQL(url);
+    const positional = (q) => { let i = 0; return q.replace(/\?/g, () => `$${++i}`); };
+    return {
+      kind: 'postgres',
+      async query(q, values = []) {
+        return await sql.unsafe(positional(q), values.map(bindable));
+      },
+      async columns(table) {
+        try {
+          const rows = await sql.unsafe(
+            'SELECT column_name AS name, data_type AS type FROM information_schema.columns WHERE table_name = $1',
+            [table],
+          );
+          return rows.map((r) => ({ name: r.name, type: String(r.type || '').toUpperCase() }));
+        } catch { return []; }
+      },
+      close() { return sql.close(); },
+      raw: sql,
+    };
+  }
+
+  throw new Error(`spark-ssr: unsupported db url "${url}" (sqlite:// or postgres:// expected)`);
+}

package/src/hydrate.js

@@ -0,0 +1,161 @@
+/**
+ * Hydration, the Spark way: the browser receives fully-rendered HTML wrapped
+ * in a host `<div import="/__spark/page/<key>" data-spark-ssr>`. A client
+ * `mount()` re-resolves that import against this module's generated component:
+ * the authored page, minus the <spark-ssr> block, plus a synthesized <script>
+ * holding local state, the initial data (imported from /__spark/data/<key>.js
+ * so no code-shaped strings ever land in a component script), and the CRUD
+ * handlers the template implies:
+ *
+ *   bare handler OUTSIDE a loop                          → insert (POST)
+ *   bare handler INSIDE a loop, next to a member bind    → update (PATCH)
+ *   bare handler INSIDE a loop, no member bind           → delete (DELETE)
+ *
+ * Handlers inside loops are rewritten to pass their row: onclick={remove}
+ * becomes onclick={remove(todo)} — the runtime runs it as an inline statement.
+ */
+import { parseHTML } from 'linkedom';
+
+// Structural roles from the analysis (names are the author's own).
+export function handlerRoles(analysis) {
+  const insert = analysis.handlers.find((h) => !h.inEach) || null;
+  const update = analysis.handlers.find((h) => h.inEach && h.withMemberBind) || null;
+  const del = analysis.handlers.find((h) => h.inEach && !h.withMemberBind) || null;
+  return { insert, update, del };
+}
+
+// The column a lone top-level bind maps to when its name isn't a column:
+// the first text-ish, non-bookkeeping column.
+export function primaryColumn(cols) {
+  const skip = new Set(['id', 'user_id', 'created', 'created_at', 'updated', 'updated_at']);
+  const texty = cols.filter((c) => !skip.has(c.name) && /CHAR|TEXT|CLOB|^$/.test(c.type || ''));
+  return (texty[0] || cols.find((c) => !skip.has(c.name)) || {}).name || null;
+}
+
+/**
+ * Transform the authored page into the client component served at
+ * /__spark/page/<key>.html.
+ *  - <template await="x"> unwraps to its resolved-branch content (state
+ *    starts from the init module; no promise to wait on client-side).
+ *  - loop handlers get their row argument.
+ *  - the synthesized <script> is appended.
+ */
+export function clientComponent({ html, analysis, plan, table, cols, key }) {
+  const { document } = parseHTML('<!doctype html><html><body>' + html + '</body></html>');
+
+  // Nested templates may keep their children in .childNodes rather than
+  // .content depending on how linkedom parsed them — read both.
+  const kids = (node) => [
+    ...(node.content ? node.content.childNodes : []),
+    ...node.childNodes,
+  ];
+
+  (function transform(node, loopVar) {
+    if (node.nodeType !== 1) return;
+    const tag = (node.tagName || '').toLowerCase();
+    if (tag === 'template') {
+      const each = node.getAttribute('each');
+      const aw = node.getAttribute('await');
+      if (aw) {
+        // Prefer an explicit then-branch, else the direct children.
+        const content = kids(node);
+        const thenTpl = content.find((c) => c.nodeType === 1
+          && (c.tagName || '').toLowerCase() === 'template' && c.hasAttribute('then'));
+        const keep = thenTpl ? kids(thenTpl) : content.filter((c) =>
+          !(c.nodeType === 1 && (c.tagName || '').toLowerCase() === 'template'
+            && (c.hasAttribute('then') || c.hasAttribute('catch'))));
+        for (const k of keep) node.parentNode.insertBefore(k, node);
+        node.remove();
+        for (const k of keep) transform(k, loopVar);
+        return;
+      }
+      let inner = loopVar;
+      if (each) {
+        const em = each.match(/^\s*([\w$]+)/);
+        if (em) inner = em[1];
+      }
+      for (const c of kids(node)) transform(c, inner);
+      return;
+    }
+    if (loopVar && node.attributes) {
+      for (const attr of [...node.attributes]) {
+        const v = String(attr.value || '').trim();
+        if (/^on\w+$/.test(attr.name) && /^\{[a-zA-Z_$][\w$]*\}$/.test(v)) {
+          const name = v.slice(1, -1);
+          if (analysis.handlers.some((h) => h.name === name && h.inEach)) {
+            attr.value = '{' + name + '(' + loopVar + ')}';
+          }
+        }
+      }
+    }
+    for (const c of [...node.childNodes]) transform(c, loopVar);
+  })(document.body, null);
+
+  return document.body.innerHTML + '\n<script>\n' + clientScript({ analysis, plan, table, cols, key }) + '</script>\n';
+}
+
+// The synthesized component script. Plain functions, no template literals,
+// no code-shaped strings (the runtime's script rewriter is not string-aware).
+export function clientScript({ analysis, plan, table, cols, key }) {
+  const L = [];
+  L.push(`import __init from '/__spark/data/${key}.js';`);
+  for (const p of plan) {
+    L.push(`let ${p.var} = __init.${p.var};`);
+  }
+  for (const b of analysis.topBinds) {
+    L.push(`let ${b.v} = ${b.kind === 'checked' ? 'false' : "''"};`);
+  }
+
+  if (!table) return L.join('\n') + '\n';
+  const api = '/api/' + table;
+  const listVar = plan.find((p) => p.source && p.source.kind === 'table' && p.source.table === table)?.var;
+  const { insert, update, del } = handlerRoles(analysis);
+  const H = { 'content-type': 'application/json' };
+
+  if (listVar) {
+    L.push('async function __refresh() {');
+    L.push(`  const r = await fetch('${api}');`);
+    L.push(`  ${listVar} = await r.json();`);
+    L.push('}');
+  }
+  if (insert) {
+    L.push(`async function ${insert.name}() {`);
+    L.push('  const body = {};');
+    const colNames = cols.map((c) => c.name);
+    const fallback = primaryColumn(cols);
+    for (const b of analysis.topBinds) {
+      const col = colNames.includes(b.v) ? b.v : fallback;
+      if (col) L.push(`  body.${col} = ${b.v};`);
+    }
+    L.push(`  await fetch('${api}', { method: 'POST', headers: ${JSON.stringify(H)}, body: JSON.stringify(body) });`);
+    for (const b of analysis.topBinds) L.push(`  ${b.v} = ${b.kind === 'checked' ? 'false' : "''"};`);
+    if (listVar) L.push('  await __refresh();');
+    L.push('}');
+  }
+  if (update) {
+    L.push(`async function ${update.name}(row) {`);
+    L.push('  const body = {};');
+    for (const f of [...new Set(analysis.rowBinds.map((b) => b.field))]) {
+      L.push(`  body.${f} = row.${f};`);
+    }
+    L.push(`  await fetch('${api}/' + row.id, { method: 'PATCH', headers: ${JSON.stringify(H)}, body: JSON.stringify(body) });`);
+    L.push('}');
+  }
+  if (del) {
+    L.push(`async function ${del.name}(row) {`);
+    L.push(`  await fetch('${api}/' + row.id, { method: 'DELETE' });`);
+    if (listVar) L.push('  await __refresh();');
+    L.push('}');
+  }
+  return L.join('\n') + '\n';
+}
+
+// The per-request init module served at /__spark/data/<key>.js — plain data
+// in bundled JS (never inlined into a component <script>), no-store cached.
+export function initModule(data) {
+  const json = JSON.stringify(data)
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029')
+    .replace(/<\//g, '<\\/');
+  return 'export default ' + json + ';\n';
+}

package/src/index.js

@@ -0,0 +1,14 @@
+/**
+ * spark-ssr — zero-config SSR for spark-html on Bun.
+ *
+ * The HTML template infers everything: <template each="todo in todos"> means
+ * you need `todos`; <spark-ssr table="todos"> backs it with a table and the
+ * REST endpoints the handlers imply; a user_id column means auth scoping.
+ * Filesystem routing, sessions, uploads, middleware — no build step.
+ */
+export { serve } from './server.js';
+export { loadConfig } from './config.js';
+export { connect } from './db.js';
+export { extractBlocks, rewriteParams, analyze, dataPlan, singleShaped } from './parse.js';
+export { renderFragment, evalExpr } from './render.js';
+export { clientComponent, clientScript, initModule, handlerRoles, primaryColumn } from './hydrate.js';