allez-orm 1.0.0

package/allez-orm.mjs

@@ -0,0 +1,278 @@
+// allez-orm.mjs
+// AllezORM — minimal browser ORM on top of sql.js (WASM)
+// - Pure client-side
+// - IndexedDB persistence (debounced auto-save)
+// - Plug-in schemas with optional versioned upgrades
+// - Simple table helpers (insert/upsert/update/deleteSoft/remove/findById/searchLike)
+
+/**
+ * @typedef {Object} Schema
+ * @property {string} table               // table name
+ * @property {string} createSQL           // CREATE TABLE IF NOT EXISTS ...
+ * @property {string[]=} extraSQL         // indexes / triggers / FTS setup
+ * @property {number=} version            // defaults to 1
+ * @property {(db:any,from:number,to:number)=>void|Promise<void>=} onUpgrade
+ */
+
+/**
+ * @typedef {Object} InitOptions
+ * @property {string=} dbName
+ * @property {number=} autoSaveMs
+ * @property {(file:string)=>string=} wasmLocateFile
+ * @property {Schema[]=} schemas
+ * @property {Record<string,{default:Schema}>=} schemaModules // for bundlers (import.meta.glob)
+ */
+
+const DEFAULT_DB_NAME = "allez.db";
+const DEFAULT_AUTOSAVE_MS = 1500;
+
+export class AllezORM {
+    /** @param {any} SQL @param {any} db @param {InitOptions} opts */
+    constructor(SQL, db, opts) {
+        this.SQL = SQL;
+        this.db = db;
+        this.dbName = opts.dbName ?? DEFAULT_DB_NAME;
+        this.autoSaveMs = opts.autoSaveMs ?? DEFAULT_AUTOSAVE_MS;
+        this.saveTimer = null;
+    }
+
+    // run arbitrary SQL (DDL/DML). Returns true on success.
+    // Usage: await orm.exec("ALTER TABLE posts ADD COLUMN ...");
+    async exec(sql, params = []) {
+        if (params && params.length) {
+            const stmt = this.db.prepare(sql);
+            try {
+                stmt.bind(params);
+                while (stmt.step()) { }      // iterate to completion
+            } finally {
+                stmt.free();
+            }
+        } else {
+            this.db.exec(sql);
+        }
+        // persist to IndexedDB if your class exposes it
+        if (typeof this.saveNow === "function") await this.saveNow();
+        return true;
+    }
+
+    // nice alias
+    run(sql, params) { return this.exec(sql, params); }
+
+
+    /** @param {InitOptions=} opts */
+    static async init(opts = {}) {
+        // Resolve sql.js from global <script> or dynamic import
+        let SQL;
+        if (typeof window !== "undefined" && window.initSqlJs) {
+            SQL = await window.initSqlJs({
+                locateFile: opts.wasmLocateFile ?? (f => `https://sql.js.org/dist/${f}`)
+            });
+        } else {
+            const { default: initSqlJs } = await import("sql.js");
+            SQL = await initSqlJs({
+                locateFile: opts.wasmLocateFile ?? (f => `https://sql.js.org/dist/${f}`)
+            });
+        }
+
+        // Restore DB from IndexedDB, or create fresh
+        const saved = await idbGet(opts.dbName ?? DEFAULT_DB_NAME);
+        const db = saved ? new SQL.Database(saved) : new SQL.Database();
+        // after: const db = saved ? new SQL.Database(saved) : new SQL.Database();
+        const orm = new AllezORM(SQL, db, opts);
+        await orm.execute("PRAGMA foreign_keys = ON;");  // <-- add this line
+        await orm.#ensureMeta();
+
+        const schemas = collectSchemas(opts);
+        await orm.registerSchemas(schemas);
+        db.exec("PRAGMA foreign_keys = ON;");
+
+
+        return orm;
+    }
+
+    // ---------------- core SQL helpers ----------------
+
+    async execute(sql, params = []) {
+        const stmt = this.db.prepare(sql);
+        try {
+            stmt.bind(params);
+            while (stmt.step()) { } // drain
+        } finally {
+            stmt.free();
+        }
+        this.#scheduleSave();
+    }
+
+    async query(sql, params = []) {
+        const stmt = this.db.prepare(sql);
+        const out = [];
+        try {
+            stmt.bind(params);
+            while (stmt.step()) out.push(stmt.getAsObject());
+        } finally {
+            stmt.free();
+        }
+        return out;
+    }
+
+    async get(sql, params = []) {
+        const rows = await this.query(sql, params);
+        return rows[0];
+    }
+
+    // ---------------- table helper ----------------
+
+    table(table) {
+        const self = this;
+        return {
+            async insert(obj) {
+                const cols = Object.keys(obj);
+                const qs = cols.map(() => "?").join(",");
+                await self.execute(
+                    `INSERT INTO ${table} (${cols.join(",")}) VALUES (${qs})`,
+                    cols.map(c => obj[c])
+                );
+            },
+            async upsert(obj) {
+                const cols = Object.keys(obj);
+                const qs = cols.map(() => "?").join(",");
+                const updates = cols.map(c => `${c}=excluded.${c}`).join(",");
+                await self.execute(
+                    `INSERT INTO ${table} (${cols.join(",")}) VALUES (${qs})
+           ON CONFLICT(id) DO UPDATE SET ${updates}`,
+                    cols.map(c => obj[c])
+                );
+            },
+            async update(id, patch) {
+                const cols = Object.keys(patch);
+                if (!cols.length) return;
+                const assigns = cols.map(c => `${c}=?`).join(",");
+                await self.execute(
+                    `UPDATE ${table} SET ${assigns} WHERE id=?`,
+                    [...cols.map(c => patch[c]), id]
+                );
+            },
+            async deleteSoft(id, ts = new Date().toISOString()) {
+                await self.execute(`UPDATE ${table} SET deleted_at=? WHERE id=?`, [ts, id]);
+            },
+            async remove(id) {
+                await self.execute(`DELETE FROM ${table} WHERE id=?`, [id]);
+            },
+            async findById(id) {
+                return await self.get(`SELECT * FROM ${table} WHERE id=?`, [id]);
+            },
+            async searchLike(q, columns, limit = 50) {
+                if (!columns?.length) return [];
+                const where = columns.map(c => `${table}.${c} LIKE ?`).join(" OR ");
+                const params = columns.map(() => `%${q}%`);
+                return await self.query(
+                    `SELECT * FROM ${table} WHERE (${where}) LIMIT ?`,
+                    [...params, limit]
+                );
+            }
+        };
+    }
+
+    // ---------------- schema registration ----------------
+
+    /** @param {Schema[]} schemas */
+    async registerSchemas(schemas) {
+        const meta = await this.#currentVersions();
+        for (const s of schemas) {
+            const exists = await this.get(
+                `SELECT name FROM sqlite_master WHERE type='table' AND name=?`,
+                [s.table]
+            );
+            if (!exists) {
+                await this.execute(s.createSQL);
+                if (Array.isArray(s.extraSQL)) {
+                    for (const x of s.extraSQL) await this.execute(x);
+                }
+                await this.execute(
+                    `INSERT OR REPLACE INTO allez_meta(table_name,version) VALUES(?,?)`,
+                    [s.table, s.version ?? 1]
+                );
+            } else {
+                const cur = meta.get(s.table) ?? 1;
+                const next = s.version ?? cur;
+                if (s.onUpgrade && next > cur) {
+                    await s.onUpgrade(this.db, cur, next);
+                    await this.execute(
+                        `UPDATE allez_meta SET version=? WHERE table_name=?`,
+                        [next, s.table]
+                    );
+                }
+            }
+        }
+        this.#scheduleSave();
+    }
+
+    async saveNow() {
+        const data = this.db.export(); // Uint8Array
+        await idbSet(this.dbName, data);
+    }
+
+    // ---------------- internals ----------------
+
+    async #ensureMeta() {
+        await this.execute(`
+      CREATE TABLE IF NOT EXISTS allez_meta (
+        table_name TEXT PRIMARY KEY,
+        version INTEGER NOT NULL
+      );
+    `);
+    }
+
+    async #currentVersions() {
+        const rows = await this.query(
+            `SELECT table_name, version FROM allez_meta`
+        );
+        return new Map(rows.map(r => [r.table_name, r.version]));
+    }
+
+    #scheduleSave() {
+        clearTimeout(this.saveTimer);
+        this.saveTimer = setTimeout(() => { void this.saveNow(); }, this.autoSaveMs);
+    }
+}
+
+// ---------------- helpers: schema collection + IndexedDB ----------------
+
+/** @param {InitOptions} opts */
+function collectSchemas(opts) {
+    const fromModules = opts.schemaModules
+        ? Object.values(opts.schemaModules).map(m => m.default)
+        : [];
+    const fromArray = opts.schemas ?? [];
+    return [...fromModules, ...fromArray];
+}
+
+function openIdb() {
+    return new Promise((resolve, reject) => {
+        const req = indexedDB.open("allez-orm-store", 1);
+        req.onupgradeneeded = () => req.result.createObjectStore("dbs");
+        req.onerror = () => reject(req.error);
+        req.onsuccess = () => resolve(req.result);
+    });
+}
+
+async function idbGet(key) {
+    const db = await openIdb();
+    return new Promise((resolve, reject) => {
+        const tx = db.transaction("dbs", "readonly");
+        const store = tx.objectStore("dbs");
+        const get = store.get(key);
+        get.onsuccess = () => resolve(get.result || null);
+        get.onerror = () => reject(get.error);
+    });
+}
+
+async function idbSet(key, value) {
+    const db = await openIdb();
+    return new Promise((resolve, reject) => {
+        const tx = db.transaction("dbs", "readwrite");
+        tx.objectStore("dbs").put(value, key);
+        tx.oncomplete = () => resolve();
+        tx.onerror = () => reject(tx.error);
+    });
+}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "allez-orm",
+  "version": "1.0.0",
+  "description": "AllezORM: lightweight browser SQLite ORM (sql.js) + schema generator CLI",
+  "type": "module",
+  "main": "./allez-orm.mjs",
+  "module": "./allez-orm.mjs",
+  "browser": "./allez-orm.mjs",
+  "exports": {
+    ".": {
+      "import": "./allez-orm.mjs"
+    },
+    "./cli": "./tools/allez-orm.mjs"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "dev": "node dev-server.mjs",
+    "dev:static": "serve -l 5173",
+    "allez": "node tools/allez-orm.mjs",
+    "test:cli": "node tests/test-cli.mjs",
+    "ddl:audit": "node tools/ddl-audit.mjs",
+    "prepublishOnly": "node tests/test-cli.mjs && node tools/ddl-audit.mjs"
+  },
+  "bin": {
+    "allez-orm": "tools/allez-orm.mjs"
+  },
+  "files": [
+    "allez-orm.mjs",
+    "tools/allez-orm.mjs",
+    "tools/ddl-audit.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "sqlite",
+    "sql.js",
+    "wasm",
+    "browser",
+    "orm",
+    "cli",
+    "schema",
+    "ionic",
+    "angular",
+    "typescript"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/AllezMarketing/allez-orm.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AllezMarketing/allez-orm/issues"
+  },
+  "homepage": "https://github.com/AllezMarketing/allez-orm#readme",
+  "license": "ISC",
+  "author": "Allez Marketing LLC",
+  "devDependencies": {
+    "serve": "^14.2.5"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/tools/allez-orm.mjs

@@ -0,0 +1,361 @@
+#!/usr/bin/env node
+// tools/allez-orm.mjs  —  AllezORM schema generator with foreign-key support (SQLite)
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+
+const CWD = process.cwd();
+
+// ---- robust force detection (works across shells) ----
+const FORCE_FROM_ENV = String(process.env.ALLEZ_FORCE || "").trim() === "1";
+const FORCE_FROM_ARGV = process.argv.includes("--force") || process.argv.includes("-f");
+const FORCE_EFFECTIVE = FORCE_FROM_ENV || FORCE_FROM_ARGV;
+
+function die(msg, code = 1) { console.error(msg); process.exit(code); }
+function help() {
+  console.log(`
+AllezORM schema generator
+
+Usage:
+  allez-orm create table <name> [fieldSpec ...]
+    [--dir=./schemas] [--ts] [--version=1]
+    [--stamps] [--soft-delete] [--force|-f]
+    [--onDelete=cascade|restrict|setnull|setdefault]
+    [--onUpdate=cascade|restrict|setnull|setdefault]
+    [--ensure-refs] [--no-fk-index]
+
+Env overrides:
+  ALLEZ_FORCE=1        # forces overwrite even if your shell drops --force
+
+FieldSpec grammar (compact):
+  name                       -> TEXT
+  name! / name+ / name^ ...  -> short flags directly after name (default type TEXT)
+  name:type                  -> type = INTEGER|TEXT|REAL|BLOB|NUMERIC (aliases allowed)
+  name:type!+^#~             -> ! NOT NULL, + UNIQUE, ^ INDEX, # PRIMARY KEY, ~ AUTOINCREMENT
+  name:type,notnull,unique,index,pk,ai,default=<expr>
+  ^col                       -> standalone index on col
+  fk shorthand:
+    col>table                -> INTEGER REFERENCES table(id)
+    col>table(col)           -> INTEGER REFERENCES table(col)
+    col:fk(table.col)        -> same, leaves type as INTEGER unless you pass another
+  PowerShell-safe FK alias:
+    col->table[(col)]        -> same as '>'
+  Per-field FK options via commas: ,onDelete=cascade ,onUpdate=restrict ,defer ,deferrable
+`);
+}
+
+const TYPE_ALIASES = {
+  int: "INTEGER", integer: "INTEGER", bool: "INTEGER",
+  text: "TEXT", string: "TEXT", datetime: "TEXT", timestamp: "TEXT",
+  real: "REAL", float: "REAL",
+  number: "NUMERIC", numeric: "NUMERIC", blob: "BLOB"
+};
+
+const VALID_ACTIONS = new Set(["cascade", "restrict", "setnull", "setdefault"]);
+
+function kebabToPascal(name) {
+  return name.split(/[_\- ]+/).map(s => s.charAt(0).toUpperCase() + s.slice(1)).join("");
+}
+function sanitizeTable(name) {
+  const ok = name.trim().toLowerCase().replace(/[^\w]/g, "_");
+  if (!ok) die("Invalid table name.");
+  return ok;
+}
+
+function parseArgs(argv) {
+  const out = {
+    nonFlags: [], dir: "schemas", asTS: false, version: 1, stamps: false, softDelete: false, force: false,
+    ensureRefs: true, onDelete: null, onUpdate: null, noFkIndex: false
+  };
+  for (const a of argv) {
+    if (a === "--") continue;                           // ignore npm passthrough token
+    if (a === "--ts") out.asTS = true;
+    else if (a.startsWith("--dir=")) out.dir = a.split("=")[1];
+    else if (a.startsWith("--version=")) out.version = Number(a.split("=")[1] || "1") || 1;
+    else if (a === "--stamps") out.stamps = true;
+    else if (a === "--soft-delete") out.softDelete = true;
+    else if (a === "--force" || a === "-f") out.force = true;
+    else if (a === "--ensure-refs") out.ensureRefs = true;
+    else if (a === "--no-fk-index") out.noFkIndex = true;
+    else if (a.startsWith("--onDelete=")) out.onDelete = a.split("=")[1].toLowerCase();
+    else if (a.startsWith("--onUpdate=")) out.onUpdate = a.split("=")[1].toLowerCase();
+    else out.nonFlags.push(a);
+  }
+  if (FORCE_EFFECTIVE) out.force = true;
+
+  if (out.onDelete && !VALID_ACTIONS.has(out.onDelete)) die("Invalid --onDelete action");
+  if (out.onUpdate && !VALID_ACTIONS.has(out.onUpdate)) die("Invalid --onUpdate action");
+  return out;
+}
+
+// ---- helper: parse "name[:type][shortFlags]" into parts ----
+function parseNameTypeFlags(base) {
+  let name, rhs = "", explicitType = false;
+
+  if (base.includes(":")) {
+    [name, rhs = ""] = base.split(":");
+    explicitType = true;
+  } else {
+    name = base;
+    rhs = ""; // default TEXT; short flags may be on name itself
+  }
+
+  name = String(name || "").trim();
+  if (!name) die(`Bad field spec '${base}'`);
+
+  // If no ":", short flags might be appended to name (e.g., "name!+")
+  // If ":", short flags might be appended to type token (e.g., "text!+")
+  let typeToken = rhs;
+  let shortFlagsStr = "";
+  if (rhs) {
+    const m = rhs.match(/^(.*?)([!+^#~?]+)?$/);
+    typeToken = (m?.[1] || "").trim();
+    shortFlagsStr = m?.[2] || "";
+  } else {
+    const m = name.match(/^(.*?)([!+^#~?]+)?$/);
+    name = (m?.[1] || "").trim();
+    shortFlagsStr = m?.[2] || "";
+  }
+
+  const flags = new Set(shortFlagsStr.split("").map(c =>
+    c === "!" ? "notnull" :
+    c === "+" ? "unique"  :
+    c === "^" ? "index"   :
+    c === "#" ? "pk"      :
+    c === "~" ? "ai"      :
+    ""
+  ).filter(Boolean));
+
+  // Normalize the type token if present
+  let type = typeToken ? (TYPE_ALIASES[typeToken.toLowerCase()] ?? typeToken.toUpperCase()) : "";
+
+  return { name, type, flags, explicitType };
+}
+
+// -------- Field parsing (with FK forms) ------------------------------------
+function parseFieldSpec(specRaw) {
+  // Handle "^col" index-only
+  if (specRaw.startsWith("^")
+      && !specRaw.includes(":")
+      && !specRaw.includes(",")
+      && !specRaw.includes(">")
+      && !specRaw.includes("->")) {
+    return { kind: "indexOnly", name: specRaw.slice(1) };
+  }
+
+  // FK shorthand "left>table(col)" or PowerShell-safe "left->table(col)"
+  if ((specRaw.includes(">") || specRaw.includes("->")) && !specRaw.includes(":fk")) {
+    const [left, rhs] = specRaw.includes("->") ? specRaw.split("->") : specRaw.split(">");
+    const { name, type, flags, explicitType } = parseNameTypeFlags(left);
+    const m = rhs.match(/^([a-zA-Z0-9_]+)(?:\(([a-zA-Z0-9_]+)\))?$/);
+    if (!m) die(`Bad FK ref '${specRaw}'`);
+    const table = sanitizeTable(m[1]);
+    const refCol = m[2] || "id";
+
+    // default FK storage type is INTEGER unless caller annotated a type
+    const resolvedType = explicitType ? (type || "TEXT") : "INTEGER";
+    const finalType = TYPE_ALIASES[(resolvedType || "").toLowerCase()] ?? (resolvedType || "TEXT");
+
+    return {
+      kind: "field",
+      name,
+      type: finalType,
+      flags,
+      fk: { table, col: refCol, opts: [] },
+      wantsIndex: flags.has("index")
+    };
+  }
+
+  // General field (may include ":fk(table.col)" in type OR short flags on name/type)
+  const parts = specRaw.split(",");
+  const base = parts.shift();
+  const ntf = parseNameTypeFlags(base);
+  let { name, type, flags } = ntf;
+
+  let fk = null;
+  const typeLower = (type || "").toLowerCase();
+  if (typeLower.startsWith("fk(") && typeLower.endsWith(")")) {
+    const inside = type.slice(3, -1);
+    const [t, c = "id"] = inside.split(".");
+    fk = { table: sanitizeTable(t), col: c, opts: [] };
+    type = "INTEGER"; // storage type for fk()
+  }
+
+  // default type if still empty
+  if (!type) type = "TEXT";
+
+  // long flags
+  for (const f of parts) {
+    const [k, v] = f.split("=");
+    const key = (k || "").toLowerCase().trim();
+    if (!key) continue;
+    if (["notnull", "nn", "!"].includes(key)) flags.add("notnull");
+    else if (["unique", "u", "+"].includes(key)) flags.add("unique");
+    else if (["index", "idx", "^"].includes(key)) flags.add("index");
+    else if (["pk", "primary", "#"].includes(key)) flags.add("pk");
+    else if (["ai", "autoincrement", "~"].includes(key)) flags.add("ai");
+    else if (["default", "def", "="].includes(key)) flags.add(`default=${v}`);
+    else if (["ondelete", "on_delete"].includes(key)) fk?.opts.push(`ON DELETE ${v.toUpperCase()}`);
+    else if (["onupdate", "on_update"].includes(key)) fk?.opts.push(`ON UPDATE ${v.toUpperCase()}`);
+    else if (["defer", "deferrable"].includes(key)) fk?.opts.push(`DEFERRABLE INITIALLY DEFERRED`);
+    else die(`Unknown flag '${key}' in '${specRaw}'`);
+  }
+
+  return { kind: "field", name, type, flags, fk, wantsIndex: flags.has("index") };
+}
+
+function buildColumnSQL(f, globalFK) {
+  const parts = [`${f.name} ${f.type}`];
+
+  if (f.flags?.has("pk")) parts.push("PRIMARY KEY");
+  if (f.flags?.has("ai")) {
+    if (!(f.flags.has("pk") && f.type === "INTEGER")) die(`AUTOINCREMENT requires INTEGER PRIMARY KEY on '${f.name}'`);
+    parts.push("AUTOINCREMENT");
+  }
+  if (f.flags?.has("unique")) parts.push("UNIQUE");
+  if (f.flags?.has("notnull")) parts.push("NOT NULL");
+
+  // FK inline constraint
+  const fk = f.fk;
+  if (fk) {
+    const segs = [`REFERENCES ${fk.table}(${fk.col})`];
+    const scoped = [];
+    const gDel = globalFK?.onDelete ? `ON DELETE ${globalFK.onDelete.toUpperCase()}` : null;
+    const gUpd = globalFK?.onUpdate ? `ON UPDATE ${globalFK.onUpdate.toUpperCase()}` : null;
+    if (fk.opts?.length) scoped.push(...fk.opts);
+    else { if (gDel) scoped.push(gDel); if (gUpd) scoped.push(gUpd); }
+    parts.push(segs.join(" "));
+    if (scoped.length) parts.push(scoped.join(" "));
+  }
+
+  const def = [...(f.flags || [])].find(x => String(x).startsWith("default="));
+  if (def) parts.push("DEFAULT " + String(def).split("=")[1]);
+
+  return parts.join(" ");
+}
+
+// ---------------- main ----------------
+async function main() {
+  const cfg = parseArgs(process.argv.slice(2));
+  const raw = cfg.nonFlags;
+  const a = raw.length && raw[0] === "--" ? raw.slice(1) : raw;  // belt & suspenders for stray '--'
+
+  if (!a.length || ["-h", "--help", "help"].includes(a[0])) return help();
+  if (!(a[0] === "create" && a[1] === "table")) return help();
+
+  const table = sanitizeTable(a[2] || "");
+  if (!table) die("Missing table name.");
+  const pascal = kebabToPascal(table) + "Schema";
+
+  const specs = (a.slice(3) || []).map(parseFieldSpec);
+
+  // Default PK if none supplied
+  const hasUserPK = specs.some(f => f.kind === "field" && f.flags?.has("pk"));
+  const cols = [];
+  if (!hasUserPK) cols.push({ name: "id", type: "INTEGER", flags: new Set(["pk", "ai"]) });
+
+  const fkRefs = [];  // { table, col }
+  for (const f of specs) {
+    if (f.kind === "indexOnly") continue;
+    cols.push(f);
+    if (f.fk) fkRefs.push({ table: f.fk.table, col: f.fk.col });
+  }
+
+  if (cfg.stamps) {
+    cols.push({ name: "created_at", type: "TEXT", flags: new Set(["notnull"]) });
+    cols.push({ name: "updated_at", type: "TEXT", flags: new Set(["notnull"]) });
+  }
+  if (cfg.softDelete || cfg.stamps) cols.push({ name: "deleted_at", type: "TEXT", flags: new Set() });
+
+  // Compose DDL
+  const ddl =
+`CREATE TABLE IF NOT EXISTS ${table} (
+  ${cols.map(c => buildColumnSQL(c, { onDelete: cfg.onDelete, onUpdate: cfg.onUpdate })).join(",\n  ")}
+);`;
+
+  // Extra indexes: any explicit ^ plus FK columns (unless --no-fk-index)
+  const extraIdx = new Set();
+  for (const f of specs) {
+    if (f.kind === "indexOnly") {
+      extraIdx.add(`CREATE INDEX IF NOT EXISTS idx_${table}_${f.name} ON ${table}(${f.name});`);
+    } else {
+      if (f.wantsIndex) extraIdx.add(`CREATE INDEX IF NOT EXISTS idx_${table}_${f.name} ON ${table}(${f.name});`);
+      if (f.fk && !cfg.noFkIndex) extraIdx.add(`CREATE INDEX IF NOT EXISTS idx_${table}_${f.name}_fk ON ${table}(${f.name});`);
+    }
+  }
+
+  const fileJS =
+`// ./schemas/${table}.schema.js
+const ${pascal} = {
+  table: "${table}",
+  version: ${cfg.version},
+
+  createSQL: \`
+    ${ddl.split("\n").join("\n    ")}
+  \`,
+
+  extraSQL: [
+${[...extraIdx].map(s => `    \`${s}\``).join("\n")}
+  ]
+};
+
+export default ${pascal};
+`;
+
+  const fileTS =
+`// ./schemas/${table}.schema.ts
+import type { Schema } from "../allez-orm";
+const ${pascal}: Schema = {
+  table: "${table}",
+  version: ${cfg.version},
+
+  createSQL: \`
+    ${ddl.split("\n").join("\n    ")}
+  \`,
+
+  extraSQL: [
+${[...extraIdx].map(s => `    \`${s}\``).join("\n")}
+  ]
+};
+
+export default ${pascal};
+`;
+
+  // Ensure out dir
+  const dir = path.resolve(CWD, cfg.dir);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  // Write this schema
+  const outFile = path.join(dir, `${table}.schema.${cfg.asTS ? "ts" : "js"}`);
+  if (fs.existsSync(outFile) && !cfg.force) die(`Refusing to overwrite: ${path.relative(CWD, outFile)} (use --force)`);
+  fs.writeFileSync(outFile, cfg.asTS ? fileTS : fileJS, "utf8");
+  console.log(`✔ Created ${path.relative(CWD, outFile)}`);
+
+  // Ensure referenced schemas exist (minimal ones)
+  if (cfg.ensureRefs && fkRefs.length) {
+    for (const r of fkRefs) {
+      const refPathJS = path.join(dir, `${r.table}.schema.js`);
+      const refPathTS = path.join(dir, `${r.table}.schema.ts`);
+      if (fs.existsSync(refPathJS) || fs.existsSync(refPathTS)) continue;
+      const pas = kebabToPascal(r.table) + "Schema";
+      const stub =
+`// ./schemas/${r.table}.schema.js  (auto-created stub for FK target)
+const ${pas} = {
+  table: "${r.table}",
+  version: 1,
+  createSQL: \`
+    CREATE TABLE IF NOT EXISTS ${r.table} (
+      id INTEGER PRIMARY KEY AUTOINCREMENT
+    );
+  \`,
+  extraSQL: []
+};
+export default ${pas};
+`;
+      fs.writeFileSync(refPathJS, stub, "utf8");
+      console.log(`✔ Created FK target stub ${path.relative(CWD, refPathJS)}`);
+    }
+  }
+}
+
+await main();

package/tools/ddl-audit.mjs

@@ -0,0 +1,84 @@
+// tools/ddl-audit.mjs — audit ONLY SQL template strings in schemas for bad tokens
+import fs from "node:fs";
+import path from "node:path";
+
+const TARGET_DIRS = process.argv.slice(2).length ? process.argv.slice(2) : ["schemas"];
+
+// patterns that should never appear inside SQL we execute
+const BAD = [
+  {
+    name: "dangling-short-flag",
+    rx: / [A-Za-z_][A-Za-z0-9_]*! /g, // e.g., "name! " instead of "name TEXT NOT NULL"
+    hint: 'Use "NOT NULL" — generator should emit it now.',
+  },
+  {
+    name: "type-suffix-in-sql",
+    rx: /:[A-Za-z]+/g,               // e.g., "user_id:text" leaking into SQL
+    hint: "Identifiers must not contain :type suffixes — generator should strip them.",
+  },
+];
+
+function getSqlBlocks(source) {
+  // Grab all backticked segments; our schemas put SQL in template literals.
+  const blocks = [];
+  const re = /`([\s\S]*?)`/g;
+  let m;
+  while ((m = re.exec(source))) {
+    blocks.push({ text: m[1], start: m.index + 1 }); // +1 to point inside the backtick
+  }
+  return blocks;
+}
+
+function indexToLineCol(text, idx) {
+  // line/col are 1-based
+  let line = 1, col = 1;
+  for (let i = 0; i < idx; i++) {
+    if (text[i] === "\n") { line++; col = 1; }
+    else { col++; }
+  }
+  return { line, col };
+}
+
+let totalIssues = 0;
+
+for (const dir of TARGET_DIRS) {
+  if (!fs.existsSync(dir)) continue;
+  const files = fs.readdirSync(dir).filter(f => f.endsWith(".js") || f.endsWith(".ts"));
+  for (const f of files) {
+    const full = path.join(dir, f);
+    const src = fs.readFileSync(full, "utf8");
+    const blocks = getSqlBlocks(src);
+    if (!blocks.length) continue;
+
+    let fileIssues = 0;
+    for (const { text, start } of blocks) {
+      for (const rule of BAD) {
+        rule.rx.lastIndex = 0; // reset global regex
+        let m;
+        while ((m = rule.rx.exec(text))) {
+          const hitIdx = start + m.index; // index in whole file (unused except for future)
+          const { line, col } = indexToLineCol(text, m.index);
+          const ctxStart = Math.max(0, m.index - 40);
+          const ctxEnd = Math.min(text.length, m.index + m[0].length + 40);
+          const snippet = text.slice(ctxStart, ctxEnd).replace(/\n/g, "↵");
+          if (fileIssues === 0) {
+            console.log(`\n✖ ${full}`);
+          }
+          console.log(
+            `  • ${rule.name} at SQL ${line}:${col}  ${rule.hint}\n` +
+            `    …${snippet}…`
+          );
+          fileIssues++;
+          totalIssues++;
+        }
+      }
+    }
+  }
+}
+
+if (totalIssues === 0) {
+  console.log("✓ SQL audit: no offending tokens found.");
+} else {
+  console.error(`\nFound ${totalIssues} offending token(s).`);
+  process.exit(1);
+}