@aotter/mantle 0.2.0-alpha.5 → 0.2.0-alpha.7

package/dist/infrastructure/artifacts.js

@@ -0,0 +1,71 @@
+import { readFile, readdir, mkdir, rm, writeFile, lstat } from "node:fs/promises";
+import { dirname, join, resolve, relative, sep, isAbsolute } from "node:path";
+import { GENERATED } from "../domain/entry.js";
+/** Only marked generated files (and pre-header operation entries) can be removed. */
+async function ownedFiles(directory, prefix = "") {
+    const entries = await readdir(join(directory, prefix), { withFileTypes: true }).catch(error => {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    });
+    const files = [];
+    for (const entry of entries) {
+        const name = join(prefix, entry.name);
+        if (entry.isDirectory())
+            files.push(...await ownedFiles(directory, name));
+        else if (entry.isFile() && /\.(ts|sql)$/.test(name)) {
+            const source = await readFile(join(directory, name), "utf8");
+            if (source.startsWith(`// ${GENERATED}\n`) || source.startsWith(`-- ${GENERATED}\n`) ||
+                /^(?:views|procedures)[/\\]/.test(name) && /^import \{ (?:view|procedure)_[A-Za-z0-9$]+ as operation \} from "\.\.\/generated\.js";\nexport default operation;/.test(source))
+                files.push(name);
+        }
+    }
+    return files;
+}
+/** Check never writes; normal generation removes obsolete SDK-owned files only. */
+export async function writeArtifacts(directory, files, check = false) {
+    const root = resolve(directory);
+    const rootStat = await lstat(root).catch(error => { if (error.code === "ENOENT")
+        return undefined; throw error; });
+    if (rootStat?.isSymbolicLink())
+        throw new Error(`Generated output cannot follow an application-owned symlink: ${root}`);
+    // Preflight all destinations before writing any: a symlink belongs to the app,
+    // never to generated output (including links to somewhere inside the tree).
+    for (const name of Object.keys(files)) {
+        const child = relative(root, resolve(root, name));
+        if (!child || isAbsolute(child) || child === ".." || child.startsWith(`..${sep}`))
+            throw new Error(`Generated path escapes output directory: ${name}`);
+        let path = root;
+        for (const part of child.split(sep)) {
+            path = join(path, part);
+            const stat = await lstat(path).catch(error => { if (error.code === "ENOENT")
+                return undefined; throw error; });
+            if (stat?.isSymbolicLink())
+                throw new Error(`Generated output cannot follow an application-owned symlink: ${path}`);
+        }
+    }
+    const changed = [];
+    for (const [name, source] of Object.entries(files)) {
+        const path = join(directory, name);
+        const previous = await readFile(path, "utf8").catch(error => {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        });
+        if (previous === source)
+            continue;
+        changed.push(path);
+        if (!check) {
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, source);
+        }
+    }
+    for (const name of await ownedFiles(directory)) {
+        if (Object.hasOwn(files, name.replaceAll("\\", "/")))
+            continue;
+        changed.push(join(directory, name));
+        if (!check)
+            await rm(join(directory, name));
+    }
+    return changed.sort();
+}

package/dist/infrastructure/authSchema.js

@@ -0,0 +1,83 @@
+import { getAuthTables } from "@better-auth/core/db";
+import { getSchema } from "better-auth/db";
+import { ident } from "../kernel/dialect/common.js";
+function columnType(field, dialect) {
+    const pg = dialect === "postgres";
+    // Anything else, including the arrays the factory stores as JSON text, is text (Bun.SQL would encode that text into jsonb as a JSON string).
+    switch (field.type) {
+        case "number": return field.bigint ? "bigint" : "integer";
+        case "boolean": return pg ? "boolean" : "integer";
+        case "date": return pg ? "timestamptz" : "text";
+        case "json": return pg ? "jsonb" : "text";
+        default: return "text";
+    }
+}
+/**
+ * Better Auth's name for a field-level index (`<table>_<column>_idx`; past PostgreSQL's 63-byte identifier limit the middle is
+ * cut and an FNV-1a hash of the full name is spliced in). Its helper lives in `@better-auth/core/db/internal`, which is not public
+ * API, so the same rule is restated here: a database already migrated by Better Auth's CLI keeps matching names, and
+ * `IF NOT EXISTS` skips the index instead of duplicating it.
+ */
+export function fieldIndexName(table, column) {
+    const full = `${table}_${column}_idx`;
+    if (new TextEncoder().encode(full).length <= 63)
+        return full;
+    let hash = 2166136261;
+    for (let i = 0; i < full.length; i++)
+        hash = Math.imul(hash ^ full.charCodeAt(i), 16777619);
+    const suffix = `_${(hash >>> 0).toString(16).padStart(8, "0")}_idx`;
+    return full.slice(0, 63 - suffix.length) + suffix;
+}
+/** Better Auth's own `order`, then referenced tables before the tables that reference them. */
+function orderedTables(options) {
+    const byOrder = Object.entries(getSchema(options)).filter(([, table]) => !table.disableMigrations).sort((a, b) => a[1].order - b[1].order);
+    const ordered = [];
+    const place = (entry, visiting) => {
+        if (ordered.includes(entry) || visiting.has(entry[0]))
+            return;
+        visiting.add(entry[0]);
+        for (const field of Object.values(entry[1].fields)) {
+            const target = byOrder.find(([name]) => name === field.references?.model);
+            if (target)
+                place(target, visiting);
+        }
+        ordered.push(entry);
+    };
+    for (const entry of byOrder)
+        place(entry, new Set());
+    return ordered;
+}
+export function authSchemaSql(options, dialect) {
+    const generateId = options.advanced?.database?.generateId;
+    const idType = generateId === "serial" ? "integer" : generateId === "uuid" && dialect === "postgres" ? "uuid" : "text";
+    const idColumn = generateId === "serial" ? (dialect === "postgres" ? "integer GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY" : "integer PRIMARY KEY") : `${idType} PRIMARY KEY NOT NULL${idType === "uuid" ? " DEFAULT gen_random_uuid()" : ""}`;
+    // `references.field` is a logical field name; the column it points at may be renamed (`fields: { email: "email_address" }`).
+    const tables = getAuthTables(options);
+    const logical = Object.values(tables);
+    const referenced = (ref) => logical.find(t => t.modelName === ref.model)?.fields[ref.field]?.fieldName ?? ref.field;
+    const statements = [];
+    const indexes = [];
+    for (const [name, table] of orderedTables(options)) {
+        const index = (unique, index, columns) => indexes.push(`CREATE ${unique ? "UNIQUE " : ""}INDEX IF NOT EXISTS ${ident(index)} ON ${ident(name)} (${columns.map(ident).join(", ")})`);
+        if (name === tables.user?.modelName)
+            index(false, fieldIndexName(`_mantle_auth_${name}`, "member_page"), [tables.user.fields.createdAt?.fieldName ?? "createdAt", "id"]);
+        const columns = [`${ident("id")} ${idColumn}`];
+        for (const [column, field] of Object.entries(table.fields)) {
+            if (column === "id")
+                continue;
+            const type = field.references?.field === "id" ? idType : columnType(field, dialect);
+            columns.push([
+                ident(column), type,
+                field.required !== false && "NOT NULL",
+                field.unique && "UNIQUE",
+                field.references && `REFERENCES ${ident(field.references.model)}(${ident(referenced(field.references))}) ON DELETE ${(field.references.onDelete ?? "cascade").toUpperCase()}`,
+            ].filter(Boolean).join(" "));
+            if (field.index && !field.unique)
+                index(false, fieldIndexName(name, column), [column]);
+        }
+        statements.push(`CREATE TABLE IF NOT EXISTS ${ident(name)} (${columns.join(", ")})`);
+        for (const declared of table.indexes ?? [])
+            index(declared.unique, declared.name, declared.columns);
+    }
+    return [...statements, ...indexes];
+}

package/dist/infrastructure/bundle.js

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync, realpathSync, rmSync } from "node:fs";
+import { relative, resolve, sep } from "node:path";
+import { build } from "esbuild";
+import { INPUTS_FILE, authTableSql, extraRoles, staleInputs } from "./inputs.js";
+/** Only static imports run at startup; dynamic imports remain separate uploaded modules. */
+export function startupGraph(metafile, entry) {
+    const visited = new Set();
+    const visit = (name) => {
+        if (visited.has(name))
+            return;
+        visited.add(name);
+        const output = metafile.outputs[name];
+        for (const imported of output.imports) {
+            if (!imported.external && imported.kind !== "dynamic-import")
+                visit(imported.path);
+        }
+    };
+    for (const [name, output] of Object.entries(metafile.outputs))
+        if (output.entryPoint && resolve(output.entryPoint) === resolve(entry))
+            visit(name);
+    return [...visited];
+}
+const refused = [
+    [/(?:^|\/)node_modules\/(?:better-auth(?:\/|$)|@better-auth\/)/, "Load it through authLoader(() => import(...)) to keep Better Auth out of startup."],
+    [/(?:^|\/)node_modules\/@modelcontextprotocol\//, "Load MCP through a request-time import(...)."],
+    // the compiler: the package's own generator layers (installed, or workspace dist/source) and its parser, YAML and SQL dependencies
+    [/(?:^|\/)node_modules\/(?:@aotter\/mantle\/dist\/(?:build|infrastructure)\/|yaml\/|pgsql-deparser\/|libpg-query\/)|(?:^|\/)mantle\/(?:dist|src)\/(?:build|infrastructure)\//, "Generator code must not run in a Worker; import runtime entry points such as @aotter/mantle/rest."],
+];
+export function guardStartup(metafile, entry) {
+    for (const name of startupGraph(metafile, entry)) {
+        const output = metafile.outputs[name];
+        for (const input of Object.keys(output.inputs)) {
+            // shortcut: vendored auth outside node_modules is not recognized; use package metadata if vendoring is supported.
+            const hit = refused.find(([pattern]) => pattern.test(input.replaceAll("\\", "/")));
+            if (hit)
+                throw new Error(`Startup module ${name} contains ${input}. ${hit[1]}`);
+        }
+    }
+}
+export async function bundle(entry, outdir) {
+    entry = realpathSync(entry);
+    if (resolve(outdir) === process.cwd())
+        throw new Error("Bundle outdir must not be the working directory: it is cleaned before building.");
+    const fromOutput = relative(resolve(outdir), resolve(entry));
+    if (fromOutput === "" || (!fromOutput.startsWith(`..${sep}`) && fromOutput !== "..")) {
+        throw new Error("Bundle outdir must not contain the source entry: it is cleaned before building.");
+    }
+    rmSync(outdir, { recursive: true, force: true });
+    const result = await build({
+        entryPoints: [entry], outdir, bundle: true, splitting: true, format: "esm", platform: "neutral",
+        conditions: ["workerd", "worker", "browser"], mainFields: ["module", "main"],
+        external: ["cloudflare:*", "node:*"], minify: true, metafile: true, chunkNames: "chunks/[name]-[hash]",
+        plugins: [{ name: "optional-peers", setup(builder) {
+                    builder.onResolve({ filter: /^(?:better-auth|@better-auth\/(?:core|oauth-provider)|@modelcontextprotocol\/server)(?:\/|$)/ }, async (args) => {
+                        if (args.pluginData?.optionalPeer)
+                            return;
+                        const resolved = await builder.resolve(args.path, { importer: args.importer, resolveDir: args.resolveDir, kind: args.kind, pluginData: { optionalPeer: true } });
+                        // Unselected request paths may reference absent peers; installed peers still bundle normally.
+                        return resolved.errors.length ? { path: args.path, external: true } : resolved;
+                    });
+                } }],
+    });
+    if (Object.keys(result.metafile.inputs).some(input => /(?:^|\/)mantle\/(?:src|dist)\/testing\//.test(resolve(input).replaceAll("\\", "/"))))
+        throw new Error("@aotter/mantle/testing is only for tests and cannot be bundled for production.");
+    // A build is what `wrangler dev` and deploys run: generated code must match the manifests it came from.
+    // Any bundled module from a generated directory finds its fingerprint (type-only imports leave generated.ts out).
+    const generatedDirs = new Set(Object.keys(result.metafile.inputs).map(input => resolve(input, "..")).filter(dir => existsSync(resolve(dir, INPUTS_FILE))));
+    for (const dir of generatedDirs) {
+        const input = resolve(dir, "generated.ts"), stale = staleInputs(input);
+        if (stale.length)
+            throw new Error(`Generated output in ${relative(process.cwd(), resolve(input, ".."))} is stale (${stale.join("; ")}). Run your generate script (mantle generate ...) and rebuild.`);
+    }
+    const appSources = Object.keys(result.metafile.inputs).filter(input => !/node_modules|(?:^|\/)generated\/|^\.\.\//.test(input) && /\.[cm]?[jt]s$/.test(input)).map(input => [input, readFileSync(input, "utf8")]);
+    for (const [input, source] of appSources) {
+        const tables = authTableSql(source);
+        if (tables.length)
+            console.warn(`note: ${input} queries Better Auth's ${tables.join(", ")} table with SQL. Read users through userOf(caller) or readIdentity(auth) (@aotter/mantle/auth, @aotter/mantle/auth/identity), which follow each instance's table mapping and ban state.`);
+    }
+    const roles = appSources.flatMap(([, source]) => extraRoles(source));
+    if (roles.length)
+        console.warn(`note: Better Auth roles beyond admin and user: ${[...new Set(roles)].join(", ")}. Mantle grants by the admin layer and app code; keep extra roles only if the app needs them.`);
+    guardStartup(result.metafile, entry);
+    return result.metafile;
+}

package/dist/infrastructure/cli.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { resolve, relative } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import { configureWrangler } from "./wrangler.js";
+import { writeArtifacts } from "./artifacts.js";
+import { INPUTS_FILE, inputsFingerprint } from "./inputs.js";
+/** Option modules are often .ts, which older Node rejects with a bare "Unknown file extension". */
+async function load(path) {
+    try {
+        return await import(pathToFileURL(resolve(path)).href);
+    }
+    catch (error) {
+        if (error.code === "ERR_UNKNOWN_FILE_EXTENSION")
+            throw new Error(`Cannot load ${path}: Node ${process.versions.node} does not run TypeScript. Use Node 22.22 or later, as the package engines say.`);
+        throw error;
+    }
+}
+const targets = ["bun-sqlite", "bun-postgres", "cloudflare-d1", "cloudflare-postgres"];
+const usage = "Usage: mantle generate <target> <output-directory> <manifest>... [--check] [--admin] [--site <module>] [--auth <module>]... (one per Better Auth instance) [--admin-extensions <module>] [--wrangler <path>] [--entry <worker entry>] [--outdir <bundle directory>]\n       mantle bundle <entry> <outdir>\n       mantle describe <target> <manifest>... [--diff <old.json>]";
+try {
+    const { values, positionals } = parseArgs({ allowPositionals: true, options: {
+            diff: { type: "string" }, check: { type: "boolean" }, admin: { type: "boolean" }, site: { type: "string" }, "admin-extensions": { type: "string" }, auth: { type: "string", multiple: true }, wrangler: { type: "string" }, entry: { type: "string", default: "src/worker.ts" }, outdir: { type: "string", default: "dist" },
+        } });
+    const command = positionals[0] === "bundle" || positionals[0] === "generate" || positionals[0] === "describe" ? positionals.shift() : "generate";
+    if (command === "describe") {
+        const target = positionals.shift();
+        if (!target || !targets.includes(target) || !positionals.length)
+            throw new Error(usage);
+        const { compilePlan, sqliteCompiler, postgresCompiler } = await import("../build/compiler.js");
+        const { describeApp, diffApp } = await import("../domain/describe/index.js");
+        const sources = await Promise.all(positionals.map(async (path) => ({ sourceId: path, text: await readFile(path, "utf8") })));
+        const compiled = await compilePlan({ sources }, target.endsWith("postgres") ? postgresCompiler : sqliteCompiler, "operational");
+        if (!compiled.ok)
+            throw new Error(JSON.stringify(compiled.diagnostics, null, 2));
+        const report = await describeApp(compiled.plan);
+        if (values.diff) {
+            const changes = diffApp(JSON.parse(await readFile(values.diff, "utf8")), report);
+            console.log(JSON.stringify(changes, null, 2));
+        }
+        else
+            console.log(JSON.stringify(report, null, 2));
+    }
+    else if (command === "bundle") {
+        const [entry, outdir] = positionals;
+        if (!entry || !outdir || positionals.length !== 2 || values.admin || values.site || values.auth || values["admin-extensions"] || values.wrangler || values.check)
+            throw new Error(usage);
+        await (await import("./bundle.js")).bundle(entry, outdir);
+    }
+    else {
+        const [target, destination, ...paths] = positionals;
+        if (!target || !targets.includes(target) || !destination || !paths.length)
+            throw new Error(usage);
+        const sources = await Promise.all(paths.map(async (path) => ({ sourceId: path, text: await readFile(path, "utf8") })));
+        // Read plain options without constructing Better Auth, which can touch the database.
+        // One --auth per Better Auth instance; their tables are merged into one migration.
+        const auth = await Promise.all((values.auth ?? []).map(async (path) => {
+            const loaded = await load(path);
+            const options = loaded.authOptions?.(new Proxy({}, { get: () => undefined })) ?? loaded.auth?.options;
+            if (!options)
+                throw new Error(`${path} must export \`authOptions(env)\` (or \`auth\`, a betterAuth() instance).`);
+            return options;
+        }));
+        const site = values.site ? (await load(values.site)).siteDefaults : undefined;
+        if (values.site && !site)
+            throw new Error(`${values.site} must export siteDefaults.`);
+        const extensionModule = values["admin-extensions"] ? await load(values["admin-extensions"]) : undefined;
+        // The Admin presentation module: extensions and/or the project's sidebar groups.
+        const adminExtensions = extensionModule?.adminExtensions ?? extensionModule?.default ?? (extensionModule?.navGroups ? [] : undefined);
+        const navGroups = extensionModule?.navGroups;
+        if (values["admin-extensions"] && !Array.isArray(adminExtensions))
+            throw new Error(`${values["admin-extensions"]} must export an adminExtensions array (named or default) or navGroups.`);
+        const { generateFromSources } = await (auth.length ? import("./generateAuth.js") : import("./generate.js"));
+        const result = await generateFromSources({ target: target, sources: { sources }, admin: values.admin, auth, site, adminExtensions, navGroups });
+        if (!result.ok)
+            throw new Error(JSON.stringify(result.diagnostics, null, 2));
+        for (const warning of result.warnings ?? [])
+            console.warn(`warning: ${warning}`);
+        const read = [...paths, ...(values.auth ?? []), ...[values.site, values["admin-extensions"]].filter((path) => !!path)];
+        const changed = await writeArtifacts(destination, { ...result.files, [INPUTS_FILE]: inputsFingerprint(destination, read) }, values.check);
+        if (target.startsWith("cloudflare-")) {
+            const wrangler = values.wrangler ?? ["wrangler.jsonc", "wrangler.json", "wrangler.toml"].find(existsSync) ?? "wrangler.jsonc";
+            if (configureWrangler(wrangler, values.entry, values.outdir, destination, values.check))
+                changed.push(wrangler);
+        }
+        if (values.check && changed.length)
+            throw new Error(`Generated output is stale. Run mantle generate with the same options:\n${changed.join("\n")}`);
+        if (!values.check)
+            console.log(`Commit generated output and Wrangler config edits; keep dist/ untracked. Add to .gitattributes: ${JSON.stringify(relative(process.cwd(), resolve(destination)).replaceAll("\\", "/") + "/**")} linguist-generated=true`);
+        for (const name of result.refProcedures)
+            console.log(`Ref Procedure ${JSON.stringify(name)}: implement Handlers[${JSON.stringify(name)}].`);
+        if (result.refProcedures.length)
+            console.log("Next: run tsc --noEmit; pass the handlers at store(db, caller, { handlers }).");
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/dist/infrastructure/generate.d.ts

@@ -0,0 +1,14 @@
+/** Build-time assembly only. None of these imports enter generated applications. */
+import { d1Dialect, type AdminExtension, type ManifestSourceSet } from "../build/compiler.js";
+import type { GenerateResult, Target } from "../domain/generation.js";
+/** Core's own new-entry-id lowering for a dialect, printed once as an SQL expression: the Store's inserts carry the same one its compiled INSERTs do. */
+export declare const coreNewId: (dialect: Pick<typeof d1Dialect, "print" | "lowering">, schemas: Parameters<NonNullable<typeof d1Dialect.print>>[1]) => string;
+export interface GenerateRequest {
+    readonly target: Target;
+    readonly admin?: boolean;
+    readonly sources: ManifestSourceSet; /** Select the optional generated site/media capability and deployment tables. */
+    readonly site?: import("../build/compiler.js").SiteDefaults;
+    readonly adminExtensions?: readonly AdminExtension[]; /** Project sidebar groups (`navGroups` of the `--admin-extensions` module). */
+    readonly navGroups?: readonly import("../build/compiler.js").AdminNavGroup[];
+}
+export declare function generateFromSources(request: GenerateRequest, schema?: () => readonly string[]): Promise<GenerateResult>;

package/dist/infrastructure/generate.js

@@ -0,0 +1,174 @@
+import { describeApp } from "../domain/describe/index.js";
+/** Build-time assembly only. None of these imports enter generated applications. */
+import { compilePlan, viewOutputs, sqliteCompiler, postgresCompiler, d1Dialect, postgresDialect, lowerPlan, sqliteSchema, postgresSchema } from "../build/compiler.js";
+import { wireReturning, wireScalars } from "../domain/wireScalars.js";
+import { boundaryType, outputType } from "../domain/columns.js";
+import { castCursor, provePaging } from "../domain/paging.js";
+import { dialect as sqliteDialect } from "../kernel/dialect/sqlite.js";
+import { cast, dialect as postgresDialect_ } from "../kernel/dialect/postgres.js";
+import { adminBindingsOf } from "./adminPaging.js";
+import { adminIndexes } from "../domain/adminOrder.js";
+import { publishingSql } from "../usecase/publishing.js";
+import { searchDiagnostics } from "../usecase/search.js";
+import { generate } from "../usecase/generate.js";
+import { generatedFiles } from "../domain/entry.js";
+/** Core's own new-entry-id lowering for a dialect, printed once as an SQL expression: the Store's inserts carry the same one its compiled INSERTs do. */
+export const coreNewId = (dialect, schemas) => dialect.print({ SelectStmt: { targetList: [{ ResTarget: { val: dialect.lowering.newId() } }], limitOption: "LIMIT_OPTION_DEFAULT", op: "SETOP_NONE" } }, schemas).replace(/^SELECT /, "");
+// JSON, date-time and date inputs are driver-ready text. Declaring their parameter as text makes every driver send it verbatim:
+// Bun.SQL would JSON-encode a string bound to jsonb a second time, and postgres.js turns one bound to timestamptz or date into a
+// JavaScript Date, which loses microseconds. Core prints `CAST($n AS <type>)`; the PostgreSQL dialect spells what replaces it (the
+// same cast the Store writes with). Any other use of such a parameter is refused.
+const CORE_CAST = { json: "jsonb", timestamptz: "timestamptz", date: "date" };
+function castInputs(statement, path, refusals) {
+    let sql = statement.sql;
+    for (const [i, b] of statement.binds.entries()) {
+        const type = b.k === "input" ? String(b.type) : "", target = CORE_CAST[type];
+        if (!target)
+            continue;
+        const param = `$${i + 1}`, core = `CAST(${param} AS ${target})`;
+        if (sql.split(core).join("").match(new RegExp(`\\$${i + 1}(?!\\d)`)))
+            refusals.push({ code: "GENERATE_UNSUPPORTED", path, message: `Input ${param} must appear only as ${core}. Wrap each occurrence in ${core}.` });
+        sql = sql.replaceAll(core, cast(param, type));
+    }
+    Object.assign(statement, { sql });
+}
+/** Operational records are added in Admin only through a Procedure placed with `uiSchema.collectionAction`; name the Schemas left without one. */
+function adminCreateWarnings(plan) {
+    const placed = new Set(Object.values(plan.procedures).map(p => p.uiSchema?.["collectionAction"]).filter((name) => typeof name === "string").map(name => name.toLowerCase()));
+    return Object.values(plan.schemas).filter(s => {
+        const required = new Set(s.schema.required ?? []);
+        // Folded children open from their parent; translations from their language tabs.
+        const folded = Object.entries(s.schema.properties ?? {}).some(([name, property]) => required.has(name) && typeof property?.["x-mantle-ref"] === "string");
+        // Field-scoped rows belong to their members, who create them.
+        return !s.publishing && s.schema.readOnly !== true && !s.scope && !s.translates && !folded && !placed.has(s.name.toLowerCase());
+    }).map(s => `Schema '${s.name}' is operational and writable, but no Procedure places a create action on it, so Admin cannot add its records. Add a Procedure with uiSchema.collectionAction: ${s.name} and an admin MCP Trigger, or mark the Schema readOnly.`).concat(Object.values(plan.schemas).flatMap(s => Object.entries(s.schema.properties ?? {})
+        .filter(([name, property]) => property?.readOnly === true && (s.schema.required ?? []).includes(name) && property.default === undefined)
+        .map(([name]) => `Schema '${s.name}' field '${name}' is required and readOnly without a default, so Admin cannot create its records. Give it a default (Admin stores it on create).`)));
+}
+/** Warn about SQL's case folding without changing the authored output names. */
+function outputNameWarnings(plan) {
+    const warnings = [];
+    const inspect = (kind, name, stmts) => {
+        for (const stmt of stmts) {
+            const select = stmt.SelectStmt, write = stmt.InsertStmt ?? stmt.UpdateStmt ?? stmt.DeleteStmt;
+            const targets = kind === "View" ? select?.targetList : write?.returningClause?.exprs;
+            const relations = new Map();
+            const from = (node) => {
+                if (node.JoinExpr) {
+                    from(node.JoinExpr.larg);
+                    from(node.JoinExpr.rarg);
+                    return;
+                }
+                const r = node.RangeVar ?? node;
+                if (r.relname)
+                    relations.set(r.alias?.aliasname ?? r.relname, r.mantle === "table" ? r.relname : undefined);
+            };
+            if (write)
+                from(write.relation);
+            for (const node of select?.fromClause ?? write?.fromClause ?? write?.usingClause ?? [])
+                from(node);
+            for (const { ResTarget: target } of targets ?? []) {
+                const refs = target.val?.ColumnRef?.fields;
+                if (target.name || !refs?.every((ref) => ref.String) || refs.length > 2)
+                    continue;
+                const column = refs.at(-1).String.sval;
+                const candidates = refs.length === 2 ? [relations.get(refs[0].String.sval)] : [...relations.values()].filter(schema => schema && plan.schemas[schema]?.fields[column]);
+                if (candidates.length !== 1 || !candidates[0])
+                    continue;
+                const declared = plan.schemas[candidates[0]]?.names?.[column];
+                if (declared && declared !== column) {
+                    const reference = refs.length === 2 ? `${refs[0].String.sval}.${declared}` : declared;
+                    warnings.push(`${kind} '${name}' field '${declared}' outputs storage name '${column}'; use ${reference} AS "${declared}" to preserve the declared name.`);
+                }
+            }
+        }
+    };
+    for (const [name, view] of Object.entries(plan.views))
+        inspect("View", name, view.stmts);
+    for (const [name, procedure] of Object.entries(plan.procedures))
+        if ("sql" in procedure.handler)
+            inspect("Procedure", name, procedure.handler.sql.stmts);
+    return [...new Set(warnings)];
+}
+export async function generateFromSources(request, schema) {
+    const postgres = request.target.endsWith("postgres");
+    const compiler = postgres ? postgresCompiler : sqliteCompiler;
+    const compiled = await compilePlan(request.sources, compiler, "operational");
+    if (!compiled.ok)
+        return { ok: false, diagnostics: compiled.diagnostics.map(({ code, path, message }) => ({ code, path, message })) };
+    const dialect = postgres ? postgresDialect() : d1Dialect;
+    const wire = postgres ? postgresDialect_ : sqliteDialect;
+    const viewKeys = Object.fromEntries(Object.entries(compiled.plan.views).map(([name, view]) => {
+        const output = viewOutputs(view, compiled.plan.schemas);
+        return [name, output.positions?.length === output.keys?.length ? output.keys : undefined];
+    }));
+    const refusals = [], paging = {};
+    const lower = (boundary) => lowerPlan(compiled.plan, dialect, {
+        pageQuery(ast, name) {
+            // Core visits public/caller before trusted. Prove the real caller equality prefixes;
+            // a trusted all-scope read does not acquire a fictional scope predicate.
+            if (!Object.hasOwn(paging, name))
+                paging[name] = provePaging(compiled.plan, ast);
+            return { SelectStmt: { ...ast.SelectStmt, limitCount: undefined, limitOption: "LIMIT_OPTION_DEFAULT" } };
+        },
+        project(ast, kind, name, page) {
+            if (kind === "procedure")
+                return wireReturning(ast, compiled.plan.schemas, wire);
+            if (page && !page.flat)
+                ast = castCursor(ast, page.sources, paging[name]?.types ?? [], postgres);
+            const keys = page && !page.flat ? [...page.names, ...Array.from({ length: page.nkeys }, (_, i) => `_k${i}`)] : viewKeys[name];
+            if (!keys)
+                return ast;
+            const types = page && !page.flat ? [...page.names.map(key => boundaryType(compiled.plan, name, key)), ...(paging[name]?.types ?? [])] : keys.map(key => page ? boundaryType(compiled.plan, name, key) : outputType(compiled.plan, name, key));
+            let projected = wireScalars(ast, keys, types, wire, boundary && !!page);
+            if (typeof projected !== "string" && page && !page.flat && !boundary)
+                projected = wireScalars(projected, keys, [...page.names.map(() => undefined), ...(paging[name]?.types ?? []).map(type => ["integer", "int8", "int4"].includes(type) ? type : undefined)], wire, true);
+            if (typeof projected !== "string")
+                return projected;
+            refusals.push({ code: "GENERATE_UNSUPPORTED", path: `views/${name}`, message: projected });
+            return ast;
+        },
+    });
+    const { lowered, warnings } = lower(false);
+    const wireLowered = lower(true).lowered;
+    if (postgres) {
+        const seen = new Set();
+        const plans = [lowered, wireLowered];
+        for (const plan of plans)
+            for (const [kind, all] of [["views", plan.views], ["procedures", plan.procedures]])
+                for (const [name, modes] of Object.entries(all)) {
+                    for (const statement of Object.values(modes).flat())
+                        if (!seen.has(statement)) {
+                            seen.add(statement);
+                            castInputs(statement, `${kind}/${name}`, refusals);
+                            if ("paged" in statement)
+                                for (const page of Object.values(statement.paged)) {
+                                    const inputPage = { ...statement, sql: page.sql };
+                                    castInputs(inputPage, `${kind}/${name}`, refusals);
+                                    Object.assign(page, { sql: inputPage.sql });
+                                }
+                        }
+                }
+    }
+    const searchProblems = searchDiagnostics(warnings);
+    refusals.push(...searchProblems);
+    const adminReads = request.admin ? await adminBindingsOf(compiled.plan, dialect, paging, wire, refusals) : undefined;
+    const { adminPages, adminEntries } = adminReads ?? {};
+    const report = await describeApp(compiled.plan);
+    const result = generate({ description: report, target: request.target, admin: request.admin, adminPages, adminEntries, site: request.site, plan: compiled.plan, lowered, wireLowered, viewKeys, newId: coreNewId(dialect, compiled.plan.schemas), adminExtensions: request.adminExtensions, navGroups: request.navGroups, paging });
+    if (refusals.length) {
+        const diagnostics = result.ok ? [] : result.diagnostics.filter(d => !searchProblems.some(p => p.path === d.path) ||
+            !["Every reachable visibility mode must have canonical lowered SQL.", "Both caller and trusted SQL must be lowered."].includes(d.message));
+        return { ok: false, diagnostics: [...refusals, ...diagnostics] };
+    }
+    if (!result.ok)
+        return result;
+    const accessTargets = Object.fromEntries(report.targets.map(({ _meta: m }) => {
+        const policy = ({ opaque, requires }) => ({ opaque, ...(requires.guard ? { guard: requires.guard } : {}) });
+        return [m.id, { targetHash: m.targetHash, ...policy(m), ...(m.variants.length ? { variants: m.variants.map(v => ({ id: v.id, ...policy(v) })) } : {}) }];
+    }));
+    const gatewayFiles = generatedFiles({ "access-targets.ts": `import type { AccessTarget } from "@aotter/mantle/contracts";\nexport const targets: Readonly<Record<string, AccessTarget>> = ${JSON.stringify(accessTargets)};\n` });
+    const ddl = [...(postgres ? postgresSchema : sqliteSchema)(compiled.plan.schemas), ...publishingSql(compiled.plan.schemas, !postgres), ...(request.admin ? adminIndexes(compiled.plan.schemas, !postgres) : []), ...(schema?.() ?? [])];
+    const { "site-schema.sql": siteSql = "", ...files } = result.files;
+    return { ...result, warnings: [...outputNameWarnings(compiled.plan), ...(request.admin ? adminCreateWarnings(compiled.plan) : []), ...(compiled.plan.access?.warnings ?? [])], files: { ...files, ...gatewayFiles, ...generatedFiles({ "schema.sql": ddl.join(";\n\n") + ";\n" + siteSql }) } };
+}

package/dist/infrastructure/generateAuth.d.ts

@@ -0,0 +1,8 @@
+/** Selected Auth generation; the compiler and request DTO remain shared with the bare entry. */
+import type { BetterAuthOptions } from "better-auth/types";
+import { type GenerateRequest } from "./generate.js";
+/** One or more Better Auth instances (each with its own table names); their DDL is merged. */
+export declare function generateFromSources(request: GenerateRequest & {
+    readonly auth?: BetterAuthOptions | readonly BetterAuthOptions[];
+}): Promise<import("../domain/generation.js").GenerateResult>;
+export type { GenerateRequest } from "./generate.js";

package/dist/infrastructure/generateAuth.js

@@ -0,0 +1,17 @@
+import { generateFromSources as generate } from "./generate.js";
+import { authSchemaSql } from "./authSchema.js";
+/** One or more Better Auth instances (each with its own table names); their DDL is merged. */
+export function generateFromSources(request) {
+    const instances = request.auth ? [request.auth].flat() : [];
+    return generate(request, instances.length ? () => authSql(instances, request.target.endsWith("postgres") ? "postgres" : "sqlite") : undefined);
+}
+function authSql(instances, dialect) {
+    const statements = [...new Set(instances.flatMap(options => authSchemaSql(options, dialect)))];
+    // CREATE TABLE IF NOT EXISTS would silently keep the first of two different definitions.
+    // Identical statements are already merged, so a repeated table name means two different definitions.
+    const tables = statements.map(statement => /^CREATE TABLE IF NOT EXISTS ("(?:[^"]|"")+")/.exec(statement)?.[1]).filter(Boolean);
+    const twice = tables.find((table, i) => tables.indexOf(table) !== i);
+    if (twice)
+        throw new Error(`Better Auth instances define table ${twice} differently; give each instance its own table names (user.modelName, session.modelName, ...).`);
+    return statements;
+}

package/dist/infrastructure/inputs.js

@@ -0,0 +1,36 @@
+/** `mantle generate` fingerprints its inputs next to the output; `mantle bundle` refuses output whose inputs changed since. */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, relative, resolve } from "node:path";
+export const INPUTS_FILE = ".mantle-inputs.json";
+/** The installed `@aotter/mantle` version (dist/infrastructure → package root). */
+const MANTLE_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+// Line endings are normalized so a CRLF checkout (core.autocrlf) matches the LF fingerprint.
+const digest = (path) => existsSync(path) ? createHash("sha256").update(readFileSync(path, "utf8").replaceAll("\r\n", "\n")).digest("hex") : null;
+/** The manifests and option modules (`--auth`, `--site`, `--admin-extensions`) one generate run read, by path relative to its output. */
+export function inputsFingerprint(destination, paths) {
+    const inputs = Object.fromEntries(paths.map(path => [relative(resolve(destination), resolve(path)).replaceAll("\\", "/"), digest(path)]));
+    return JSON.stringify({ mantle: MANTLE_VERSION, inputs }, null, 2) + "\n";
+}
+/** Why the generated output that holds `generatedModule` no longer matches its inputs (empty when it does, or when it has no fingerprint). */
+export function staleInputs(generatedModule) {
+    const directory = dirname(generatedModule), file = resolve(directory, INPUTS_FILE);
+    if (!existsSync(file))
+        return [];
+    const recorded = JSON.parse(readFileSync(file, "utf8"));
+    const stale = recorded.mantle === MANTLE_VERSION ? [] : [`generated by Mantle ${recorded.mantle}, building with ${MANTLE_VERSION}`];
+    for (const [path, hash] of Object.entries(recorded.inputs))
+        if (digest(resolve(directory, path)) !== hash)
+            stale.push(`${relative(process.cwd(), resolve(directory, path))} changed`);
+    return stale;
+}
+/** Better Auth roles an app declares beyond `admin` and `user` (`<name>: ac.newRole(...)`), for a one-line design note. */
+export function extraRoles(source) {
+    return [...source.matchAll(/["']?([A-Za-z][\w-]*)["']?\s*:\s*ac\.newRole\(/g)].map(m => m[1]).filter(role => role !== "admin" && role !== "user");
+}
+/** Better Auth tables an app's own code queries with SQL (`FROM "user"`, `JOIN session` ...), for a one-line note. */
+export function authTableSql(source) {
+    // Only lines that read like SQL statements, so prose such as "take into account" is not a finding.
+    const sql = source.split("\n").filter(line => /\b(?:SELECT|INSERT|UPDATE|DELETE)\b/.test(line)).join("\n");
+    return [...new Set([...sql.matchAll(/\b(?:FROM|JOIN|UPDATE|INTO)\s+"?(user|session|account|verification)"?(?=[\s;),`'"]|$)/gi)].map(m => m[1].toLowerCase()))];
+}