allez-orm 1.0.10 → 1.0.12

package/allez-orm.mjs

@@ -197,23 +197,51 @@ export class AllezORM {
 
   // ---------------- schema registration ----------------
 
+  /** Soft-run an extra SQL statement; swallow known-unsupported patterns. */
+  async #tryExtra(sql) {
+    const s = (sql || "").trim();
+    if (!s) return;
+
+    // SQLite does not support adding FK constraints via ALTER TABLE.
+    const isAlterFk =
+      /^ALTER\s+TABLE\s+.+\s+ADD\s+FOREIGN\s+KEY/i.test(s);
+
+    try {
+      if (isAlterFk) {
+        console.warn(
+          "[AllezORM] Skipping unsupported statement (SQLite):",
+          s
+        );
+        return;
+      }
+      await this.execute(s);
+    } catch (err) {
+      console.warn("[AllezORM] extraSQL failed and was skipped:", s, err);
+    }
+  }
+
   /** @param {Schema[]} schemas */
   async registerSchemas(schemas) {
     const meta = await this.#currentVersions();
     for (const s of schemas) {
-      if (!s?.table || !s?.createSQL) {
-        // skip invalid schema silently to avoid breaking init
-        continue;
-      }
+      if (!s?.table || !s?.createSQL) continue;
+
       const exists = await this.get(
         `SELECT name FROM sqlite_master WHERE type='table' AND name=?`,
         [s.table]
       );
+
       if (!exists) {
+        // Hard-fail for invalid CREATE (developer action required)
         await this.execute(s.createSQL);
+
+        // Best-effort for side DDL (indexes/triggers/fts)
         if (Array.isArray(s.extraSQL)) {
-          for (const x of s.extraSQL) await this.execute(x);
+          for (const x of s.extraSQL) {
+            await this.#tryExtra(x);
+          }
         }
+
         await this.execute(
           `INSERT OR REPLACE INTO allez_meta(table_name,version) VALUES(?,?)`,
           [s.table, s.version ?? 1]

package/index.d.ts

@@ -1,4 +1,5 @@
 // index.d.ts
+
 export interface Schema {
   table: string;
   createSQL: string;
@@ -21,30 +22,53 @@ export interface TableHelper<T extends Row = Row> {
   insert(obj: Partial<T>): Promise<void>;
   upsert(obj: Partial<T>): Promise<void>;
   update(id: any, patch: Partial<T>): Promise<void>;
-  /** Soft delete; implementation will try `deletedAt` then `deleted_at`. */
   deleteSoft(id: any, ts?: string): Promise<void>;
   remove(id: any): Promise<void>;
-  findById(id: any): Promise<T | null>;
+  findById(id: any): Promise<T | undefined>;
   searchLike(q: string, columns: (keyof T | string)[], limit?: number): Promise<T[]>;
 }
 
 export class AllezORM {
   constructor(SQL: any, db: any, opts: InitOptions);
+
+  /** Initialize (loads sql.js, restores from IndexedDB, applies schemas). */
   static init(opts?: InitOptions): Promise<AllezORM>;
+
+  /** Persist the current database to IndexedDB immediately. */
   saveNow(): Promise<void>;
+
+  /** Execute arbitrary SQL and auto-save (convenience, returns true). */
   exec(sql: string, params?: any[]): Promise<boolean>;
+
+  /** Alias for exec. */
   run(sql: string, params?: any[]): Promise<boolean>;
+
+  /** Low-level execute; schedules a debounced save. */
   execute(sql: string, params?: any[]): Promise<void>;
+
+  /** SELECT helper returning plain objects. */
   query<T = Row>(sql: string, params?: any[]): Promise<T[]>;
-  get<T = Row>(sql: string, params?: any[]): Promise<T | null>;
+
+  /** SELECT one row (undefined if no row). */
+  get<T = Row>(sql: string, params?: any[]): Promise<T | undefined>;
+
+  /** Table-scoped helpers. */
   table<T extends Row = Row>(table: string): TableHelper<T>;
+
+  /** Register / upgrade schemas. */
   registerSchemas(schemas: Schema[]): Promise<void>;
 }
 
-/** Browser helpers + Angular-friendly surface */
+/** Open (or reuse) a browser DB by name. */
 export function openBrowserDb(name: string, opts?: InitOptions): Promise<AllezORM>;
+
+/** Alias for openBrowserDb. */
 export const openDb: typeof openBrowserDb;
+
+/** Apply an array of schemas to an opened AllezORM instance. */
 export function applySchemas(db: AllezORM, schemas?: Schema[]): Promise<void>;
+
+/** Convenience helpers that operate on an AllezORM instance. */
 export function query<T = Row>(db: AllezORM, sql: string, params?: any[]): Promise<T[]>;
 export function exec(db: AllezORM, sql: string, params?: any[]): Promise<void>;
 

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "allez-orm",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "AllezORM: lightweight browser SQLite ORM (sql.js) + schema generator CLI",
   "type": "module",
+  "bin": {
+    "allez-orm": "tools/allez-orm.mjs"
+  },
   "main": "./allez-orm.mjs",
   "module": "./allez-orm.mjs",
   "browser": "./allez-orm.mjs",
@@ -32,9 +35,6 @@
     "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",
     "index.d.ts",

package/tools/allez-orm.mjs

@@ -1,361 +1,403 @@
 #!/usr/bin/env node
-// tools/allez-orm.mjs  —  AllezORM schema generator with foreign-key support (SQLite)
+/**
+ * Allez ORM – schema generator CLI
+ *
+ * Generates a <table>.schema.js with:
+ *  - CREATE TABLE with inline foreign keys:  col TYPE REFERENCES target(id) [ON DELETE ...]
+ *  - Optional "stamps": created_at, updated_at, deleted_at
+ *  - Optional unique / not-null markers
+ *  - Optional ON DELETE behavior for *all* FKs via --onDelete=
+ *  - Auto index per FK column in extraSQL (emitted as backticked strings)
+ *  - Auto-create stub schemas for FK target tables if missing
+ *
+ * New:
+ *  - from-json <file>: bulk-generate schemas from a JSON config
+ *  - --print-json-schema: output the JSON Schema used for validation
+ *
+ * Usage:
+ *   node tools/allez-orm.mjs create table <name> [fields...] [--dir=schemas_cli] [--stamps] [-f|--force] [--onDelete=cascade|restrict|setnull|noaction]
+ *   node tools/allez-orm.mjs from-json <config.json> [--dir=schemas_cli] [-f|--force]
+ *   node tools/allez-orm.mjs --print-json-schema
+ */
+
 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;
+const argv = process.argv.slice(2);
 
-function die(msg, code = 1) { console.error(msg); process.exit(code); }
-function help() {
+const usage = () => {
   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
+  allez-orm create table <name> [options] [fields...]
+  allez-orm from-json <config.json> [--dir=<outDir>] [-f|--force]
+  allez-orm --print-json-schema
+
+Options:
+  --dir=<outDir>         Output directory (default: schemas_cli)
+  --stamps               Add created_at, updated_at, deleted_at columns
+  --onDelete=<mode>      ON DELETE for *all* FKs (cascade|restrict|setnull|noaction). Default: none
+  -f, --force            Overwrite existing files
+  --help                 Show help
+
+Field syntax:
+  col[:type][!][+][->target] or "col:type,unique,notnull"
+  Examples: email:text!+   user_id:text->users   org_id:integer->orgs
 `);
-}
-
-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"]);
+const die = (m, code = 1) => { console.error(m); process.exit(code); };
 
-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) {
+function parseOptions(args) {
   const out = {
-    nonFlags: [], dir: "schemas", asTS: false, version: 1, stamps: false, softDelete: false, force: false,
-    ensureRefs: true, onDelete: null, onUpdate: null, noFkIndex: false
+    dir: "schemas_cli",
+    stamps: false,
+    onDelete: null,
+    force: false,
+    cmd: null,
+    sub: null,
+    table: null,
+    fields: [],
+    jsonFile: null,
+    printJsonSchema: 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);
+  const positional = [];
+  for (const a of args) {
+    if (a === "--help" || a === "-h") {
+      usage(); process.exit(0);
+    } else if (a.startsWith("--dir=")) {
+      out.dir = a.slice(6);
+    } else if (a === "--stamps") {
+      out.stamps = true;
+    } else if (a.startsWith("--onDelete=")) {
+      const v = a.slice(11).toLowerCase();
+      if (!["cascade","restrict","setnull","noaction"].includes(v)) {
+        die(`Invalid --onDelete value: ${v}`);
+      }
+      out.onDelete = v;
+    } else if (a === "-f" || a === "--force") {
+      out.force = true;
+    } else if (a === "--print-json-schema") {
+      out.printJsonSchema = true;
+    } else if (a.startsWith("-")) {
+      die(`Unknown option: ${a}`);
+    } else {
+      positional.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;
-}
+  // env var ALLEZ_FORCE=1 is honored (does not break positional parsing)
+  if (process.env.ALLEZ_FORCE === "1") out.force = true;
 
-// ---- helper: parse "name[:type][shortFlags]" into parts ----
-function parseNameTypeFlags(base) {
-  let name, rhs = "", explicitType = false;
+  out.cmd = positional[0] || null;
+  out.sub = positional[1] || null;
 
-  if (base.includes(":")) {
-    [name, rhs = ""] = base.split(":");
-    explicitType = true;
-  } else {
-    name = base;
-    rhs = ""; // default TEXT; short flags may be on name itself
+  if (out.cmd === "create" && out.sub === "table") {
+    out.table = positional[2] || null;
+    out.fields = positional.slice(3);
+  } else if (out.cmd === "from-json") {
+    out.jsonFile = positional[1] || null;
   }
 
-  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] || "";
-  }
+  return out;
+}
+
+const opts = parseOptions(argv);
+
+// ---------------- JSON Schema (string) ----------------
+
+const CONFIG_JSON_SCHEMA = JSON.stringify({
+  $schema: "https://json-schema.org/draft/2020-12/schema",
+  $id: "https://allez-orm.dev/allez.config.schema.json",
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    outDir: { type: "string" },
+    defaultOnDelete: { enum: ["cascade","restrict","setnull","noaction",null] },
+    tables: {
+      type: "array",
+      items: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+          name: { type: "string", minLength: 1 },
+          stamps: { type: "boolean" },
+          fields: {
+            type: "array",
+            items: {
+              type: "object",
+              additionalProperties: false,
+              required: ["name"],
+              properties: {
+                name: { type: "string" },
+                type: { type: "string" },           // TEXT (default), INTEGER, etc
+                unique: { type: "boolean" },
+                notnull: { type: "boolean" },
+                fk: {
+                  type: ["object", "null"],
+                  additionalProperties: false,
+                  properties: {
+                    table: { type: "string" },
+                    column: { type: "string", default: "id" }
+                  }
+                }
+              }
+            }
+          }
+        },
+        required: ["name","fields"]
+      }
+    }
+  },
+  required: ["tables"]
+}, null, 2);
 
-  const flags = new Set(shortFlagsStr.split("").map(c =>
-    c === "!" ? "notnull" :
-    c === "+" ? "unique"  :
-    c === "^" ? "index"   :
-    c === "#" ? "pk"      :
-    c === "~" ? "ai"      :
-    ""
-  ).filter(Boolean));
+// ---------------- command switchboard ----------------
 
-  // Normalize the type token if present
-  let type = typeToken ? (TYPE_ALIASES[typeToken.toLowerCase()] ?? typeToken.toUpperCase()) : "";
+if (opts.printJsonSchema) {
+  console.log(CONFIG_JSON_SCHEMA);
+  process.exit(0);
+}
+
+if (!opts.cmd) {
+  usage();
+  process.exit(0);
+}
 
-  return { name, type, flags, explicitType };
+if (opts.cmd === "from-json") {
+  if (!opts.jsonFile) die("from-json requires a <config.json> path");
+  runFromJson(opts).catch(e => die(e.stack || String(e)));
+  // will exit inside
+} else if (opts.cmd === "create" && opts.sub === "table" && opts.table) {
+  fs.mkdirSync(opts.dir, { recursive: true });
+  generateOne({
+    outDir: opts.dir,
+    name: opts.table,
+    stamps: opts.stamps,
+    onDelete: opts.onDelete,
+    force: opts.force,
+    fieldTokens: opts.fields
+  }).then(() => process.exit(0))
+    .catch(e => die(e.stack || String(e)));
+} else {
+  usage();
+  die("Expected: create table <name> …  or  from-json <config.json>");
 }
 
-// -------- 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) };
+// ---------------- core generator (shared) ----------------
+
+async function generateOne({ outDir, name, stamps, onDelete, force, fieldTokens }) {
+  const outFile = path.join(outDir, `${name}.schema.js`);
+  if (fs.existsSync(outFile) && !force) {
+    die(`Refusing to overwrite existing file: ${outFile}\n(use -f or ALLEZ_FORCE=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")
-    };
+  // Parse tokens into field descriptors
+  const fields = fieldTokens.map(parseFieldToken).filter(Boolean);
+
+  // Ensure id PK
+  const hasId = fields.some(f => f.name === "id");
+  if (!hasId) {
+    fields.unshift({ name: "id", type: "INTEGER", notnull: true, unique: false, fk: null, pk: true });
   }
 
-  // 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()
+  // stamps
+  if (stamps) {
+    fields.push(
+      { name: "created_at", type: "TEXT", notnull: true },
+      { name: "updated_at", type: "TEXT", notnull: true },
+      { name: "deleted_at", type: "TEXT", notnull: false }
+    );
   }
 
-  // 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}'`);
+  // SQL
+  const columnLines = fields.map(f => sqlForColumn(f, onDelete));
+
+  // FK indexes
+  const extraSQL = [];
+  for (const f of fields) {
+    if (f.fk) {
+      extraSQL.push(
+        `\`CREATE INDEX IF NOT EXISTS idx_${name}_${f.name}_fk ON ${name}(${f.name});\``
+      );
+    }
   }
 
-  return { kind: "field", name, type, flags, fk, wantsIndex: flags.has("index") };
-}
+  // module text
+  const moduleText = `// ${name}.schema.js (generated by tools/allez-orm.mjs)
+const ${camel(name)}Schema = {
+  table: "${name}",
+  version: 1,
+  createSQL: \`
+CREATE TABLE IF NOT EXISTS ${name} (
+  ${columnLines.join(",\n  ")}
+);\`,
+  extraSQL: [
+    ${extraSQL.join("\n    ")}
+  ]
+};
+export default ${camel(name)}Schema;
+`;
 
-function buildColumnSQL(f, globalFK) {
-  const parts = [`${f.name} ${f.type}`];
+  fs.mkdirSync(outDir, { recursive: true });
+  fs.writeFileSync(outFile, moduleText, "utf8");
+  console.log(`Wrote ${outFile}`);
 
-  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(" "));
-  }
+  // stub FK targets
+  const fkTargets = Array.from(new Set(fields.filter(f => f.fk).map(f => f.fk.table)))
+    .filter(t => t && t !== name);
 
-  const def = [...(f.flags || [])].find(x => String(x).startsWith("default="));
-  if (def) parts.push("DEFAULT " + String(def).split("=")[1]);
+  for (const t of fkTargets) {
+    const stubPath = path.join(outDir, `${t}.schema.js`);
+    if (!fs.existsSync(stubPath)) {
+      const stub = `// ${t}.schema.js (generated by tools/allez-orm.mjs - stub for FK target)
+const ${camel(t)}Schema = {
+  table: "${t}",
+  version: 1,
+  createSQL: \`
+CREATE TABLE IF NOT EXISTS ${t} (
+  id INTEGER PRIMARY KEY AUTOINCREMENT
+);\`,
+  extraSQL: [
+    
+  ]
+};
+export default ${camel(t)}Schema;
+`;
+      fs.writeFileSync(stubPath, stub, "utf8");
+      console.log(`Wrote stub ${stubPath}`);
+    }
+  }
+}
 
-  return parts.join(" ");
+function sqlForColumn(f, onDelete) {
+  if (f.pk) return `id INTEGER PRIMARY KEY AUTOINCREMENT`;
+  let s = `${f.name} ${f.type}`;
+  // ordering (UNIQUE then NOT NULL) matches tests
+  if (f.unique) s += ` UNIQUE`;
+  if (f.notnull) s += ` NOT NULL`;
+  if (f.fk) {
+    s += ` REFERENCES ${f.fk.table}(${f.fk.column || "id"})`;
+    if (onDelete) {
+      const map = { cascade: "CASCADE", restrict: "RESTRICT", setnull: "SET NULL", noaction: "NO ACTION" };
+      s += ` ON DELETE ${map[onDelete]}`;
+    }
+  }
+  return s;
 }
 
-// ---------------- 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 '--'
+function parseFieldToken(tok) {
+  // Accept "col[:type][!][+][->target]" OR "col:type,unique,notnull"
+  const ret = { name: "", type: "TEXT", notnull: false, unique: false, fk: null };
+  if (!tok) return null;
+
+  // Split on "," for attribute list
+  let main = tok;
+  let flags = [];
+  if (tok.includes(",")) {
+    const [lhs, ...rhs] = tok.split(",");
+    main = lhs;
+    flags = rhs.map(s => s.trim().toLowerCase());
+  }
 
-  if (!a.length || ["-h", "--help", "help"].includes(a[0])) return help();
-  if (!(a[0] === "create" && a[1] === "table")) return help();
+  // name : type -> target
+  let name = main;
+  let type = null;
+  let fkTarget = null;
 
-  const table = sanitizeTable(a[2] || "");
-  if (!table) die("Missing table name.");
-  const pascal = kebabToPascal(table) + "Schema";
+  // ->target
+  const fkIdx = main.indexOf("->");
+  if (fkIdx >= 0) {
+    fkTarget = main.slice(fkIdx + 2).trim();
+    name = main.slice(0, fkIdx);
+  }
 
-  const specs = (a.slice(3) || []).map(parseFieldSpec);
+  // :type
+  const typeIdx = name.indexOf(":");
+  if (typeIdx >= 0) {
+    type = name.slice(typeIdx + 1).trim();   // may contain !/+
+    name = name.slice(0, typeIdx).trim();
+  } else {
+    type = null;
+  }
 
-  // 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"]) });
+  // flags from both name and type segments
+  const nameHasBang = /!/.test(name);
+  const nameHasPlus = /\+/.test(name);
+  const typeHasBang = type ? /!/.test(type) : false;
+  const typeHasPlus = type ? /\+/.test(type) : false;
 
-  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 (nameHasBang || typeHasBang) ret.notnull = true;
+  if (nameHasPlus || typeHasPlus) ret.unique = true;
 
-  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"]) });
+  // Clean trailing !/+ off name and type
+  name = name.replace(/[!+]+$/,"").trim();
+  if (type) {
+    type = type.replace(/[!+]+$/,"").trim();
+    ret.type = type.toUpperCase();
   }
-  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});`);
-    }
+
+  if (fkTarget) ret.fk = { table: fkTarget, column: "id" };
+
+  // also allow ",unique,notnull"
+  for (const f of flags) {
+    if (f === "unique") ret.unique = true;
+    if (f === "notnull") ret.notnull = true;
   }
 
-  const fileJS =
-`// ./schemas/${table}.schema.js
-const ${pascal} = {
-  table: "${table}",
-  version: ${cfg.version},
+  ret.name = name;
+  return ret;
+}
 
-  createSQL: \`
-    ${ddl.split("\n").join("\n    ")}
-  \`,
+function camel(s){return s.replace(/[-_](.)/g,(_,c)=>c.toUpperCase());}
 
-  extraSQL: [
-${[...extraIdx].map(s => `    \`${s}\``).join("\n")}
-  ]
-};
+// ---------------- from-json implementation ----------------
 
-export default ${pascal};
-`;
+async function runFromJson(cliOpts) {
+  const file = path.resolve(cliOpts.jsonFile);
+  if (!fs.existsSync(file)) die(`Config not found: ${file}`);
 
-  const fileTS =
-`// ./schemas/${table}.schema.ts
-import type { Schema } from "../allez-orm";
-const ${pascal}: Schema = {
-  table: "${table}",
-  version: ${cfg.version},
+  const raw = fs.readFileSync(file, "utf8");
+  let cfg;
+  try { cfg = JSON.parse(raw); } catch (e) { die(`Invalid JSON: ${e.message}`); }
 
-  createSQL: \`
-    ${ddl.split("\n").join("\n    ")}
-  \`,
+  // light validation against our schema
+  // (kept minimal to avoid bundling a validator)
+  if (!cfg || !Array.isArray(cfg.tables)) die(`Config must have a "tables" array.`);
 
-  extraSQL: [
-${[...extraIdx].map(s => `    \`${s}\``).join("\n")}
-  ]
-};
+  const outDir = cliOpts.dir || cfg.outDir || "schemas_cli";
+  const defaultOnDelete = cfg.defaultOnDelete ?? null;
 
-export default ${pascal};
-`;
+  fs.mkdirSync(outDir, { recursive: true });
 
-  // 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)}`);
+  for (const t of cfg.tables) {
+    if (!t || !t.name || !Array.isArray(t.fields)) {
+      die(`Each table requires { name, fields[] }`);
     }
+    // convert config fields -> tokens for existing generator
+    const tokens = [];
+    for (const f of t.fields) {
+      let token = f.name;
+      const type = (f.type || "TEXT").toLowerCase();
+
+      token += `:${type}`;
+      if (f.notnull) token += `!`;
+      if (f.unique) token += `+`;
+      if (f.fk && f.fk.table) {
+        token += `->${f.fk.table}`;
+      }
+      tokens.push(token);
+    }
+
+    await generateOne({
+      outDir,
+      name: t.name,
+      stamps: !!t.stamps,
+      onDelete: defaultOnDelete || null,
+      force: cliOpts.force,
+      fieldTokens: tokens
+    });
   }
-}
 
-await main();
+  process.exit(0);
+}

package/tools/ddl-audit.mjs

@@ -1,84 +1,30 @@
-// 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
+/**
+ * Simple DDL auditor for Allez ORM schemas.
+ * - Detects forbidden patterns for SQLite (e.g., ALTER TABLE ... ADD FOREIGN KEY ...)
+ * - Suggests inline FK form
+ */
+
+export function auditCreateSQL(createSQL = "") {
+  const problems = [];
+
+  const badFk = /\bALTER\s+TABLE\b[^;]+ADD\s+FOREIGN\s+KEY/i;
+  if (badFk.test(createSQL)) {
+    problems.push({
+      rule: "sqlite.inline_fk",
+      message:
+        "SQLite does not support `ALTER TABLE ... ADD FOREIGN KEY`. Put `REFERENCES target(id)` on the column inside CREATE TABLE.",
+      fix: "Move the FK to the column definition:  col TYPE REFERENCES other(id) [ON DELETE ...]"
+    });
   }
-  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 };
+  return problems;
 }
 
-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++;
-        }
-      }
-    }
+export function assertClean(createSQL = "") {
+  const issues = auditCreateSQL(createSQL);
+  if (issues.length) {
+    const msg = issues.map(i => `• ${i.message}\n  → ${i.fix}`).join("\n");
+    throw new Error(`DDL audit failed:\n${msg}`);
   }
-}
-
-if (totalIssues === 0) {
-  console.log("✓ SQL audit: no offending tokens found.");
-} else {
-  console.error(`\nFound ${totalIssues} offending token(s).`);
-  process.exit(1);
+  return true;
 }