fresco 0.0.1

data/lib/fresco/runtime/sqlite.c

@@ -0,0 +1,220 @@
+/*
+ * Fresco SQLite shim. Wraps libsqlite3 behind a stable str/int FFI
+ * surface so Spinel-AOT'd apps can talk to a database without going
+ * through CRuby's `sqlite3` gem (which ships native code via the MRI
+ * ABI — not loadable by Spinel).
+ *
+ * Pattern mirrors lib/http.c: spinel-friendly types only (:int, :str),
+ * static buffers for return strings, slot tables for opaque handles
+ * so the Ruby side never sees a raw pointer.
+ *
+ * Lifted from tep's lib/tep/tep_sqlite.c. Two intentional divergences
+ * from the original:
+ *
+ *   1. Multi-cursor. Tep keeps a single global `sqlite3_stmt *`, which
+ *      means one in-flight query per process — fine for hand-written
+ *      route handlers, too tight once the codegen tier (M3+) starts
+ *      stacking finders. We track up to FRESCO_SQLITE_MAX_STMTS
+ *      cursors in a slot table and return an int cursor id from
+ *      fresco_sqlite_prepare; subsequent bind/step/col/finalize/reset
+ *      calls take the cursor id as their first argument.
+ *
+ *   2. Naming. `fresco_sqlite_*` rather than `tep_sqlite_*`.
+ *
+ * Errors
+ * ------
+ * Most functions return 0 on success and -1 on error. We don't
+ * surface sqlite3_errmsg through the FFI in v1 — the :str return
+ * lifetime would have to be threaded through another rotating buffer
+ * and callers haven't asked for it yet.
+ */
+
+#include <stdlib.h>
+#include <string.h>
+#include <sqlite3.h>
+
+#define FRESCO_SQLITE_MAX_HANDLES   16
+#define FRESCO_SQLITE_MAX_STMTS     64
+#define FRESCO_SQLITE_COL_BUFSIZE   65536
+#define FRESCO_SQLITE_COL_BUF_SLOTS 16
+
+static sqlite3      *fresco_sqlite_handles[FRESCO_SQLITE_MAX_HANDLES] = {0};
+static sqlite3_stmt *fresco_sqlite_stmts[FRESCO_SQLITE_MAX_STMTS]     = {0};
+
+/* Rotating return buffers for col_str. Spinel's `:str` return type
+ * wants a pointer that stays valid until "the caller is done with
+ * it", but in practice callers stash multiple col_str results into
+ * variables / hashes / array entries before the buffer would
+ * otherwise rotate. A single static buf would alias all those
+ * entries to whatever the most recent call wrote.
+ *
+ * We rotate across SLOTS buffers; each call lands in the next
+ * slot. With 16 slots a typical handler doing
+ *
+ *     a = first_str(...); b = first_str(...); c = first_str(...)
+ *
+ * sees three independent strings. Callers that hold > SLOTS live
+ * col_str references concurrently must copy each result before the
+ * next call. */
+static char fresco_sqlite_col_buf[FRESCO_SQLITE_COL_BUF_SLOTS][FRESCO_SQLITE_COL_BUFSIZE];
+static int  fresco_sqlite_col_slot = 0;
+
+/* Open a database. Returns a 1-indexed handle on success (0 reserved
+ * for "uninitialised"); -1 if the slot table is full or sqlite3_open
+ * rejects the path. `:memory:` works as a path for anonymous in-mem
+ * databases. Closing frees the slot for re-use. */
+int fresco_sqlite_open(const char *path) {
+    int i;
+    for (i = 0; i < FRESCO_SQLITE_MAX_HANDLES; i++) {
+        if (fresco_sqlite_handles[i] == NULL) {
+            sqlite3 *db = NULL;
+            if (sqlite3_open(path, &db) != SQLITE_OK) {
+                if (db) sqlite3_close(db);
+                return -1;
+            }
+            fresco_sqlite_handles[i] = db;
+            return i + 1;
+        }
+    }
+    return -1;
+}
+
+int fresco_sqlite_close(int h) {
+    int i;
+    if (h < 1 || h > FRESCO_SQLITE_MAX_HANDLES) return -1;
+    sqlite3 *db = fresco_sqlite_handles[h - 1];
+    if (db == NULL) return -1;
+    /* Finalize any cursor still attached to this handle to avoid
+     * sqlite3_close returning SQLITE_BUSY. */
+    for (i = 0; i < FRESCO_SQLITE_MAX_STMTS; i++) {
+        if (fresco_sqlite_stmts[i] != NULL &&
+            sqlite3_db_handle(fresco_sqlite_stmts[i]) == db) {
+            sqlite3_finalize(fresco_sqlite_stmts[i]);
+            fresco_sqlite_stmts[i] = NULL;
+        }
+    }
+    sqlite3_close(db);
+    fresco_sqlite_handles[h - 1] = NULL;
+    return 0;
+}
+
+/* No-bind statement runner. Use for DDL, BEGIN/COMMIT, and queries
+ * whose values are constants. For anything user-supplied always go
+ * through prepare + bind + step + finalize. */
+int fresco_sqlite_exec(int h, const char *sql) {
+    if (h < 1 || h > FRESCO_SQLITE_MAX_HANDLES) return -1;
+    sqlite3 *db = fresco_sqlite_handles[h - 1];
+    if (db == NULL) return -1;
+    char *err = NULL;
+    int rc = sqlite3_exec(db, sql, NULL, NULL, &err);
+    if (err) sqlite3_free(err);
+    return rc == SQLITE_OK ? 0 : -1;
+}
+
+/* Prepare a parameterised statement on handle `h`. Returns a 1-indexed
+ * cursor id on success, -1 on failure or if the slot table is full.
+ * The cursor id is the first argument to subsequent bind/step/col/
+ * finalize/reset calls — callers can hold several cursors at once. */
+int fresco_sqlite_prepare(int h, const char *sql) {
+    int i;
+    if (h < 1 || h > FRESCO_SQLITE_MAX_HANDLES) return -1;
+    sqlite3 *db = fresco_sqlite_handles[h - 1];
+    if (db == NULL) return -1;
+    for (i = 0; i < FRESCO_SQLITE_MAX_STMTS; i++) {
+        if (fresco_sqlite_stmts[i] == NULL) {
+            sqlite3_stmt *stmt = NULL;
+            if (sqlite3_prepare_v2(db, sql, -1, &stmt, NULL) != SQLITE_OK) {
+                return -1;
+            }
+            fresco_sqlite_stmts[i] = stmt;
+            return i + 1;
+        }
+    }
+    return -1;
+}
+
+int fresco_sqlite_bind_str(int cid, int idx, const char *value) {
+    if (cid < 1 || cid > FRESCO_SQLITE_MAX_STMTS) return -1;
+    sqlite3_stmt *stmt = fresco_sqlite_stmts[cid - 1];
+    if (stmt == NULL) return -1;
+    /* SQLITE_TRANSIENT — sqlite copies the string before returning,
+     * so the caller's pointer doesn't need to outlive the bind. */
+    return sqlite3_bind_text(stmt, idx, value, -1, SQLITE_TRANSIENT)
+                == SQLITE_OK ? 0 : -1;
+}
+
+int fresco_sqlite_bind_int(int cid, int idx, int value) {
+    if (cid < 1 || cid > FRESCO_SQLITE_MAX_STMTS) return -1;
+    sqlite3_stmt *stmt = fresco_sqlite_stmts[cid - 1];
+    if (stmt == NULL) return -1;
+    return sqlite3_bind_int(stmt, idx, value) == SQLITE_OK ? 0 : -1;
+}
+
+/* 1 -> row available, 0 -> done (no more rows), -1 -> error or invalid
+ * cursor. Iteration pattern: `while step(cid) == 1; ...; end`. */
+int fresco_sqlite_step(int cid) {
+    if (cid < 1 || cid > FRESCO_SQLITE_MAX_STMTS) return -1;
+    sqlite3_stmt *stmt = fresco_sqlite_stmts[cid - 1];
+    if (stmt == NULL) return -1;
+    int rc = sqlite3_step(stmt);
+    if (rc == SQLITE_ROW) return 1;
+    if (rc == SQLITE_DONE) return 0;
+    return -1;
+}
+
+const char *fresco_sqlite_col_str(int cid, int idx) {
+    if (cid < 1 || cid > FRESCO_SQLITE_MAX_STMTS) return "";
+    sqlite3_stmt *stmt = fresco_sqlite_stmts[cid - 1];
+    if (stmt == NULL) return "";
+    const unsigned char *t = sqlite3_column_text(stmt, idx);
+    if (!t) return "";
+    size_t n = strlen((const char *)t);
+    if (n >= FRESCO_SQLITE_COL_BUFSIZE) n = FRESCO_SQLITE_COL_BUFSIZE - 1;
+    char *buf = fresco_sqlite_col_buf[fresco_sqlite_col_slot];
+    fresco_sqlite_col_slot = (fresco_sqlite_col_slot + 1) % FRESCO_SQLITE_COL_BUF_SLOTS;
+    memcpy(buf, t, n);
+    buf[n] = '\0';
+    return buf;
+}
+
+int fresco_sqlite_col_int(int cid, int idx) {
+    if (cid < 1 || cid > FRESCO_SQLITE_MAX_STMTS) return 0;
+    sqlite3_stmt *stmt = fresco_sqlite_stmts[cid - 1];
+    if (stmt == NULL) return 0;
+    return sqlite3_column_int(stmt, idx);
+}
+
+int fresco_sqlite_col_count(int cid) {
+    if (cid < 1 || cid > FRESCO_SQLITE_MAX_STMTS) return 0;
+    sqlite3_stmt *stmt = fresco_sqlite_stmts[cid - 1];
+    if (stmt == NULL) return 0;
+    return sqlite3_column_count(stmt);
+}
+
+int fresco_sqlite_finalize(int cid) {
+    if (cid < 1 || cid > FRESCO_SQLITE_MAX_STMTS) return 0;
+    sqlite3_stmt *stmt = fresco_sqlite_stmts[cid - 1];
+    if (stmt == NULL) return 0;
+    sqlite3_finalize(stmt);
+    fresco_sqlite_stmts[cid - 1] = NULL;
+    return 0;
+}
+
+/* Reset a statement so it can be re-stepped (e.g. inside a loop
+ * where bound params change between iterations). Bindings survive
+ * the reset; sqlite3_clear_bindings is intentionally NOT called so
+ * callers can re-step with the same values cheaply. Use a fresh
+ * prepare if you need cleared bindings. */
+int fresco_sqlite_reset(int cid) {
+    if (cid < 1 || cid > FRESCO_SQLITE_MAX_STMTS) return -1;
+    sqlite3_stmt *stmt = fresco_sqlite_stmts[cid - 1];
+    if (stmt == NULL) return -1;
+    return sqlite3_reset(stmt) == SQLITE_OK ? 0 : -1;
+}
+
+int fresco_sqlite_last_insert_rowid(int h) {
+    if (h < 1 || h > FRESCO_SQLITE_MAX_HANDLES) return -1;
+    sqlite3 *db = fresco_sqlite_handles[h - 1];
+    if (db == NULL) return -1;
+    return (int)sqlite3_last_insert_rowid(db);
+}

data/lib/fresco/runtime/welcome.rb

@@ -0,0 +1,152 @@
+# Fresco: default welcome action. Auto-generated into
+# generated/welcome.rb by `fresco build` when config/routes.rb doesn't
+# define a `root to: ...` route. Source of truth is
+# lib/fresco/runtime/welcome.rb in the fresco gem — `fresco build`
+# copies this file verbatim (same handling as runtime.rb / boot.rb).
+#
+# Inherits Fresco::Action directly (not App::Action) so the welcome
+# page doesn't depend on the user defining a :application layout. The
+# body is built inline via Response.html, bypassing #render and
+# dispatch_layout entirely — no view template, no layout, no coupling
+# with user code.
+#
+# Style matches public/404.html / public/500.html: IBM Plex Mono,
+# 40rem column, CSS-variable light/dark theming with the same toggle
+# button. Pre-paint script runs from localStorage so the page doesn't
+# flash light before JS executes. Stop seeing this page by adding
+# `root to: SomeAction` to config/routes.rb.
+
+module Fresco
+  class Welcome < Fresco::Action
+    def call(req = Request.new("", "", ""))
+      Response.html(200, welcome_body)
+    end
+
+    # Manual string concat (matches build_headers / Json.encode_string
+    # in runtime.rb) keeps each intermediate narrowly typed String for
+    # Spinel — heredocs and `<<~`-style literals don't appear elsewhere
+    # in the Spinel-compiled surface, so we stick to the established
+    # `out += ...` pattern.
+    def welcome_body
+      out = "<!doctype html>"
+      out += "<html>"
+      out += "<head>"
+      out += "<meta charset=\"utf-8\">"
+      out += "<title>Welcome to Fresco</title>"
+      out += "<link rel=\"preconnect\" href=\"https://fonts.googleapis.com\">"
+      out += "<link rel=\"preconnect\" href=\"https://fonts.gstatic.com\" crossorigin>"
+      out += "<link href=\"https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500;700&display=swap\" rel=\"stylesheet\">"
+      out += "<script>"
+      out += "(function () {"
+      out += "  var t = localStorage.getItem(\"theme\");"
+      out += "  if (!t) {"
+      out += "    t = (window.matchMedia && window.matchMedia(\"(prefers-color-scheme: dark)\").matches) ? \"dark\" : \"light\";"
+      out += "    localStorage.setItem(\"theme\", t);"
+      out += "  }"
+      out += "  document.documentElement.setAttribute(\"data-theme\", t);"
+      out += "})();"
+      out += "</script>"
+      out += "<style>"
+      out += ":root { --bg: #f5f5f4; --fg: #1c1917; --muted: #78716c; --border: #e7e5e4; --code-bg: #e7e5e4; --accent: #0066cc; --status: #78716c; }"
+      out += ":root[data-theme=\"dark\"] { --bg: #1c1917; --fg: #e7e5e4; --muted: #a8a29e; --border: #292524; --code-bg: #292524; --accent: #6ab0ff; --status: #a8a29e; }"
+      out += "body { font-family: 'IBM Plex Mono', ui-monospace, SFMono-Regular, Menlo, monospace; max-width: 40rem; margin: 4rem auto; padding: 0 1.5rem; background: var(--bg); color: var(--fg); transition: background 0.15s, color 0.15s; }"
+      out += "h1 { font-weight: 700; font-size: 2.2rem; margin: 0 0 0.5rem; line-height: 1.2; }"
+      out += ".status { color: var(--status); font-size: 0.9rem; letter-spacing: 0.05em; text-transform: uppercase; }"
+      out += ".lede { color: var(--muted); margin: 0 0 1.75rem; }"
+      out += "p { line-height: 1.5; }"
+      out += "code { background: var(--code-bg); padding: 0.1rem 0.3rem; border-radius: 3px; }"
+      out += "a { color: var(--accent); }"
+      out += "a:hover { text-decoration: underline; }"
+      out += "hr { border: none; border-top: 1px solid var(--border); margin: 2rem 0; }"
+      out += "footer { color: var(--muted); font-size: 0.85rem; }"
+      out += "#theme-toggle { position: fixed; top: 1rem; right: 1rem; background: transparent; border: 1px solid var(--border); color: var(--fg); border-radius: 6px; padding: 0.4rem; cursor: pointer; display: inline-flex; align-items: center; justify-content: center; }"
+      out += "#theme-toggle:hover { background: var(--code-bg); }"
+      out += "#theme-toggle svg { width: 18px; height: 18px; display: none; }"
+      out += ":root[data-theme=\"light\"] #theme-toggle .icon-moon { display: inline-block; }"
+      out += ":root[data-theme=\"dark\"]  #theme-toggle .icon-sun  { display: inline-block; }"
+      # Trans pride coloring on the "Fresco" wordmark — 6 letters laid
+      # out as a mirror of the 5-stripe flag (blue / pink / white /
+      # pink / blue). The two middle letters take --fg as a stand-in
+      # for "white" so they stay readable on both stone backgrounds
+      # (renders as dark stone in light mode, near-white in dark mode).
+      # Light mode uses deeper blue/pink variants so they don't wash
+      # out against #f5f5f4; dark mode uses the canonical pastels which
+      # pop on #1c1917.
+      out += ".pride { font-weight: 700; letter-spacing: 0.04em; margin-left: 0.1em; }"
+      out += ".pride span { display: inline-block; }"
+      out += ".pride .p1 { color: #2dbfe0; }"
+      out += ".pride .p2 { color: #ed7b95; }"
+      out += ".pride .p3 { color: var(--fg); }"
+      out += ".pride .p4 { color: var(--fg); }"
+      out += ".pride .p5 { color: #ed7b95; }"
+      out += ".pride .p6 { color: #2dbfe0; }"
+      out += ":root[data-theme=\"dark\"] .pride .p1 { color: #5bcefa; }"
+      out += ":root[data-theme=\"dark\"] .pride .p2 { color: #f5a9b8; }"
+      out += ":root[data-theme=\"dark\"] .pride .p5 { color: #f5a9b8; }"
+      out += ":root[data-theme=\"dark\"] .pride .p6 { color: #5bcefa; }"
+      # Two CTA cards (Docs / GitHub). Whole card is the clickable <a>;
+      # the icon, title, and "→" sit stacked inside. Flex layout, equal
+      # width, collapses to a single column on narrow viewports so the
+      # cards don't squeeze on mobile.
+      out += ".cards { display: flex; gap: 0.875rem; margin: 0 0 1.75rem; }"
+      out += ".cta { flex: 1; display: flex; flex-direction: column; gap: 0.5rem; padding: 1.25rem; border: 2px solid var(--border); border-radius: 8px; background: transparent; color: var(--fg); text-decoration: none; transition: transform 0.15s, border-color 0.15s; }"
+      # Trans pride hover border: two-layer background trick. The inner
+      # solid layer is clipped to padding-box and covers the card body;
+      # the gradient layer fills border-box and only shows through where
+      # the (now-transparent) border sits. The gradient encodes the
+      # 5-stripe flag (blue / pink / white / pink / blue) doubled
+      # end-to-end so panning 200% bg-size from 0 to -100% loops
+      # seamlessly — the second half is identical to the first.
+      out += ".cta:hover { border-color: transparent; transform: translateY(-1px); background-image: linear-gradient(var(--code-bg), var(--code-bg)), linear-gradient(90deg, #5bcefa, #f5a9b8, #ffffff, #f5a9b8, #5bcefa, #f5a9b8, #ffffff, #f5a9b8, #5bcefa); background-size: auto, 200% 100%; background-position: 0 0, 0 0; background-origin: border-box; background-clip: padding-box, border-box; animation: prideShift 4s linear infinite; }"
+      out += "@keyframes prideShift { to { background-position: 0 0, -100% 0; } }"
+      out += ".cta svg { width: 28px; height: 28px; stroke: var(--accent); }"
+      out += ".cta-title { font-weight: 700; font-size: 1.05rem; }"
+      out += ".cta-sub { color: var(--muted); font-size: 0.88rem; }"
+      out += ".cta:hover .cta-sub { color: var(--accent); }"
+      out += "@media (max-width: 30rem) { .cards { flex-direction: column; } }"
+      # Respect the OS reduce-motion preference — keep the rainbow
+      # border, just stop panning it for folks who opted out.
+      out += "@media (prefers-reduced-motion: reduce) { .cta:hover { animation: none; } }"
+      out += "</style>"
+      out += "</head>"
+      out += "<body>"
+      out += "<button id=\"theme-toggle\" aria-label=\"Toggle color theme\" title=\"Toggle color theme\">"
+      out += "<svg class=\"icon-sun\" xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><circle cx=\"12\" cy=\"12\" r=\"4\"/><path d=\"M12 2v2\"/><path d=\"M12 20v2\"/><path d=\"m4.93 4.93 1.41 1.41\"/><path d=\"m17.66 17.66 1.41 1.41\"/><path d=\"M2 12h2\"/><path d=\"M20 12h2\"/><path d=\"m6.34 17.66-1.41 1.41\"/><path d=\"m19.07 4.93-1.41 1.41\"/></svg>"
+      out += "<svg class=\"icon-moon\" xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z\"/></svg>"
+      out += "</button>"
+      out += "<div class=\"status\">200 &middot; Welcome</div>"
+      out += "<h1>You're on <span class=\"pride\"><span class=\"p1\">F</span><span class=\"p2\">r</span><span class=\"p3\">e</span><span class=\"p4\">s</span><span class=\"p5\">c</span><span class=\"p6\">o</span></span>.</h1>"
+      out += "<p class=\"lede\">Spinel-compiled Ruby. Single binary. No runtime.</p>"
+      # Lucide icons (MIT) inlined as SVG. book-open → Docs;
+      # github → repo. Update href="#" with real URLs when ready.
+      out += "<div class=\"cards\">"
+      out += "<a class=\"cta\" href=\"https://github.com/afomera/fresco\">"
+      out += "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M12 7v14\"/><path d=\"M3 18a1 1 0 0 1-1-1V4a1 1 0 0 1 1-1h5a4 4 0 0 1 4 4 4 4 0 0 1 4-4h5a1 1 0 0 1 1 1v13a1 1 0 0 1-1 1h-6a3 3 0 0 0-3 3 3 3 0 0 0-3-3z\"/></svg>"
+      out += "<div class=\"cta-title\">Documentation</div>"
+      out += "<div class=\"cta-sub\">Get started &rarr;</div>"
+      out += "</a>"
+      out += "<a class=\"cta\" href=\"https://github.com/afomera/fresco\">"
+      out += "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\"><path d=\"M15 22v-4a4.8 4.8 0 0 0-1-3.5c3 0 6-2 6-5.5.08-1.25-.27-2.48-1-3.5.28-1.15.28-2.35 0-3.5 0 0-1 0-3 1.5-2.64-.5-5.36-.5-8 0C6 2 5 2 5 2c-.3 1.15-.3 2.35 0 3.5A5.403 5.403 0 0 0 4 9c0 3.5 3 5.5 6 5.5-.39.49-.68 1.05-.85 1.65-.17.6-.22 1.23-.15 1.85v4\"/><path d=\"M9 18c-4.51 2-5-2-7-2\"/></svg>"
+      out += "<div class=\"cta-title\">GitHub</div>"
+      out += "<div class=\"cta-sub\">View source &rarr;</div>"
+      out += "</a>"
+      out += "</div>"
+      out += "<p>Next step: add <code>root to: SomeAction</code> to <code>config/routes.rb</code>, then rebuild and reload.</p>"
+      out += "<hr>"
+      out += "<footer>Powered by Spinel + Fresco. Served from the fresco gem's <code>welcome</code> action.</footer>"
+      out += "<script>"
+      out += "(function () {"
+      out += "  document.getElementById(\"theme-toggle\").addEventListener(\"click\", function () {"
+      out += "    var cur = document.documentElement.getAttribute(\"data-theme\");"
+      out += "    var nxt = cur === \"dark\" ? \"light\" : \"dark\";"
+      out += "    document.documentElement.setAttribute(\"data-theme\", nxt);"
+      out += "    localStorage.setItem(\"theme\", nxt);"
+      out += "  });"
+      out += "})();"
+      out += "</script>"
+      out += "</body>"
+      out += "</html>"
+      out
+    end
+  end
+end

data/lib/fresco/schema_builder.rb

@@ -0,0 +1,71 @@
+# Build-time schema DSL. Captured by db/schema.rb's `Fresco.schema do
+# ... end` block; `fresco build` reads `Fresco.schema_tables` back out
+# to drive the model codegen and (M5+) the embedded migration runner.
+# Runtime never loads db/schema.rb — generated model files are
+# self-contained.
+#
+# Shape captured per table:
+#   { name: :users,
+#     columns: [
+#       { name: :id, type: :int, primary_key: true },
+#       { name: :email, type: :str, null: false, index: :unique },
+#       ...
+#     ] }
+#
+# Columns are an ordered Array of Hashes so iteration order matches
+# the SELECT clause order, which matches the column index the model
+# initializer expects.
+module Fresco
+  @schema_tables = []
+
+  def self.schema_tables
+    @schema_tables
+  end
+
+  def self.schema(&blk)
+    builder = Fresco::SchemaBuilder.new
+    builder.instance_eval(&blk)
+    @schema_tables = builder.tables
+  end
+end
+
+class Fresco::SchemaBuilder
+  attr_reader :tables
+
+  def initialize
+    @tables = []
+  end
+
+  def table(name, &blk)
+    tb = Fresco::TableBuilder.new(name)
+    tb.instance_eval(&blk) if blk
+    @tables << { name: name, columns: tb.columns, foreign_keys: tb.foreign_keys }
+  end
+end
+
+class Fresco::TableBuilder
+  attr_reader :columns, :foreign_keys
+
+  def initialize(name)
+    @name         = name
+    @columns      = []
+    @foreign_keys = []
+  end
+
+  # `type:` is one of :int, :str, :bool. `opts` is open — common
+  # keys: primary_key (Bool), null (Bool), index (:unique or any
+  # truthy), default (literal or Proc — M5+).
+  def column(name, type, **opts)
+    @columns << { name: name, type: type }.merge(opts)
+  end
+
+  # Foreign-key metadata for the generated migration runner (M5+) and
+  # for M6+ join-helper codegen (`post.user`, `user.posts`). M4 only
+  # captures the entry — no SQL is emitted from it yet, and no methods
+  # on the model class reflect it. Convention: the column itself is
+  # declared with `column :user_id, :int` separately; this entry
+  # records the FK relationship only.
+  def foreign_key(column_name, references:)
+    @foreign_keys << { column: column_name, references: references }
+  end
+end

data/lib/fresco/templates/dispatch.rb.erb

@@ -0,0 +1,32 @@
+# Fresco: dispatcher. Auto-generated by bin/build; do not edit.
+#
+# Per-route filter chain is inlined here rather than going through
+# Fresco::Action#handle. Spinel-shape constraint:
+# `<klass>.new.handle(req)` lowers to the generic
+# sp_Fresco_Action_handle, whose internal call(req) is a static
+# dispatch to the base 500 fallback — the subclass's #call never
+# runs. By keeping every method call on `_action` here at the
+# concrete subclass type (sp_<Klass>_*), Spinel statically dispatches
+# each one. Filter hooks (before_action / after_action / halt!) are
+# inherited from Fresco::Action; subclasses override only the ones
+# they need.
+
+def dispatch_request(method, path, req)
+<% routes.each_with_index do |r, i| -%>
+<% if i > 0 -%>
+
+<% end -%>
+<% if r[:captures].empty? -%>
+  if method == <%= r[:verb].inspect %> && path == <%= r[:pattern].inspect %>
+<% else -%>
+  if method == <%= r[:verb].inspect %> && path =~ /<%= r[:regex_src] %>/
+<% r[:captures].each_with_index do |c, j| -%>
+    req.params.set_sym(:<%= c %>, $<%= j + 1 %> || "")
+<% end -%>
+<% end -%>
+    return <%= r[:klass] %>.new.handle(req)
+  end
+<% end -%>
+
+  error_response(404, "Not Found")
+end

data/lib/fresco/templates/layout_dispatch.rb.erb

@@ -0,0 +1,16 @@
+# Fresco: layout dispatcher. Auto-generated by bin/build; do not edit.
+#
+# Maps the layout symbol declared on an action (via `layout :foo`) to
+# the matching `render_layouts_<name>(flash: flash, content: body)` call.
+# Symbol dispatch via static if/elsif so Spinel can lower each branch
+# concretely — no send/public_send. Unknown / :none returns the body
+# unchanged (flash is dropped since there's no layout to consume it).
+
+def dispatch_layout(name, body, flash)
+<% layout_names.each do |layout_name| -%>
+  if name == :<%= layout_name %>
+    return render_layouts_<%= layout_name %>(flash: flash, content: body)
+  end
+<% end -%>
+  body
+end

data/lib/fresco/templates/manifest.rb.erb

@@ -0,0 +1,5 @@
+# Fresco: <%= kind %> manifest. Auto-generated by bin/build; do not edit.
+
+<% paths.each do |p| -%>
+require_relative "<%= p %>"
+<% end -%>

data/lib/fresco/templates/migrations.rb.erb

@@ -0,0 +1,152 @@
+# Fresco migrations runner. Auto-generated by bin/build from
+# db/migrations/*.rb. Do not edit.
+#
+# Each migration's up + down SQL is embedded as a flat method
+# returning Array<String>. Spinel can pin those arrays at codegen
+# time; the runner just iterates and execs them.
+#
+# Schema-version tracking lives in the `schema_migrations` table
+# (one row per applied migration, keyed by name). migrate! runs
+# pending up migrations in declaration order; rollback! reverses
+# the most recently applied one. Both commands print one line per
+# migration to stdout so the operator can see progress when running
+# `./app db:migrate` over an SSH session.
+
+module Fresco
+  module DbMigrations
+    # Applied-migrations sentinel table. Built lazily on the first
+    # migrate! / rollback! call so a fresh DB doesn't require manual
+    # setup. Idempotent — `CREATE TABLE IF NOT EXISTS` is portable
+    # enough across SQLite and Postgres.
+    def self.ensure_schema_table!
+      Fresco::Db.exec("CREATE TABLE IF NOT EXISTS schema_migrations (name TEXT PRIMARY KEY)")
+    end
+
+    # Has `name` been applied already? Used to skip migrations that
+    # already ran. We read via a COUNT(*) rather than a SELECT-then-
+    # step pattern to keep the cursor lifecycle short.
+    def self.applied?(name = "")
+      cid = Fresco::Db.prepare("<%= applied_sql %>")
+      return false if cid < 0
+      Fresco::Db.bind_str(cid, 1, name)
+      n = 0
+      if Fresco::Db.step(cid) == 1
+        n = Fresco::Db.col_int(cid, 0)
+      end
+      Fresco::Db.finalize(cid)
+      n > 0
+    end
+
+    def self.mark_applied!(name = "")
+      cid = Fresco::Db.prepare("<%= insert_applied_sql %>")
+      return if cid < 0
+      Fresco::Db.bind_str(cid, 1, name)
+      Fresco::Db.step(cid)
+      Fresco::Db.finalize(cid)
+    end
+
+    def self.unmark!(name = "")
+      cid = Fresco::Db.prepare("<%= delete_applied_sql %>")
+      return if cid < 0
+      Fresco::Db.bind_str(cid, 1, name)
+      Fresco::Db.step(cid)
+      Fresco::Db.finalize(cid)
+    end
+
+    # Declaration order. Migrations are filename-sorted at build
+    # time so "0001..." comes before "0002...". Earlier entries
+    # also need to run first because later migrations may reference
+    # tables earlier ones created.
+    def self.names
+      [<%= migrations.map { |m| m[:name].inspect }.join(", ") %>]
+    end
+
+<% migrations.each do |m| -%>
+    def self.up_<%= m[:method_suffix] %>
+      [<%= m[:up_sql].map { |s| s.inspect }.join(", ") %>]
+    end
+
+    def self.down_<%= m[:method_suffix] %>
+      [<%= m[:down_sql].map { |s| s.inspect }.join(", ") %>]
+    end
+
+<% end -%>
+
+    # Dispatch on the migration name. Each branch is a typed,
+    # monomorphic Array<String> body — no dynamic method-name lookup
+    # (Spinel can't `send(:up_<name>)` portably).
+    def self.run_up(name = "")
+<% migrations.each_with_index do |m, i| -%>
+      <%= i == 0 ? "if" : "elsif" %> name == "<%= m[:name] %>"
+        sqls = up_<%= m[:method_suffix] %>
+        j = 0
+        while j < sqls.length
+          Fresco::Db.exec(sqls[j])
+          j += 1
+        end
+<% end -%>
+<% if migrations.any? -%>
+      end
+<% end -%>
+    end
+
+    def self.run_down(name = "")
+<% migrations.each_with_index do |m, i| -%>
+      <%= i == 0 ? "if" : "elsif" %> name == "<%= m[:name] %>"
+        sqls = down_<%= m[:method_suffix] %>
+        j = 0
+        while j < sqls.length
+          Fresco::Db.exec(sqls[j])
+          j += 1
+        end
+<% end -%>
+<% if migrations.any? -%>
+      end
+<% end -%>
+    end
+
+    # Apply every pending migration in declaration order. Idempotent
+    # — already-applied names are skipped. Caller prints a header;
+    # this method prints one line per migration it actually ran.
+    def self.migrate!
+      ensure_schema_table!
+<% if migrations.any? -%>
+      ns = names
+      i  = 0
+      while i < ns.length
+        n = ns[i]
+        unless applied?(n)
+          run_up(n)
+          mark_applied!(n)
+          puts "[migrate] up   " + n
+        end
+        i += 1
+      end
+<% end -%>
+    end
+
+    # Roll back the most recently applied migration (the one at the
+    # end of the declaration list whose name appears in
+    # schema_migrations). Down-runs in declaration-reverse so the
+    # call from `./app db:rollback` undoes one step at a time —
+    # rerun the command to peel further back.
+    def self.rollback!
+      ensure_schema_table!
+<% if migrations.any? -%>
+      ns = names
+      i  = ns.length - 1
+      while i >= 0
+        n = ns[i]
+        if applied?(n)
+          run_down(n)
+          unmark!(n)
+          puts "[migrate] down " + n
+          return
+        end
+        i -= 1
+      end
+<% end -%>
+      puts "[migrate] no migrations to roll back"
+    end
+  end
+end