@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

package/dist/infrastructure/adminPaging.js

@@ -0,0 +1,72 @@
+import { adminEntries } from "./adminEntries.js";
+import { wireScalars } from "../domain/wireScalars.js";
+import { boundaryType } from "../domain/columns.js";
+import { viewOutputs, compileProgram } from "../build/compiler.js";
+import { pagedOf } from "../build/compiler.js";
+import { castCursor } from "../domain/paging.js";
+/** Proved per View: an unproved View is already refused at `views/<name>`; any other failure is refused at `views/<name>/admin`. */
+export function adminPaging(plan, dialect, proofs, project, refuse) {
+    const all = Object.create(null);
+    for (const [name, v] of Object.entries(plan.views).filter(([, v]) => v.surface !== "internal")) {
+        const proof = proofs[name];
+        if (!proof || !proof.types.length && !proof.single)
+            continue;
+        try {
+            const list = (v.uiSchema?.list ?? {});
+            const modes = v.surface === "public" ? ["public", "public"] : ["caller", "trusted"];
+            const pages = modes.map(mode => {
+                const [c] = compileProgram(v.stmts, { dialect, schemas: plan.schemas, inputs: v.inputs, kind: "view", mode, restrict: v.restrict });
+                if (!c)
+                    throw Error(`No compiled Admin View: ${name}`);
+                const keys = c.ast.SelectStmt.sortClause?.length ?? 0;
+                if (keys !== proof.types.length)
+                    throw Error(`Incomplete Admin cursor proof: ${name}`);
+                const first = pagedOf({ schemas: plan.schemas, dialect }, c, undefined, !keys && (list.filterFields?.length || list.searchFields?.length) ? { eq: [{ column: (list.filterFields ?? list.searchFields)[0], value: "" }] } : undefined), next = keys ? pagedOf({ schemas: plan.schemas, dialect }, c, Array(keys).fill(0), undefined) : undefined;
+                if (!keys && !first.flat)
+                    first.ast.SelectStmt.whereClause = undefined;
+                const reserved = JSON.stringify([c.ast, v.source, list, Object.values(plan.schemas).map(s => s.fields)]);
+                let marker = 32767;
+                while (reserved.includes(String(marker)))
+                    marker++;
+                const print = (ast) => dialect.print(ast, plan.schemas);
+                const read = (p) => { const typed = castCursor(p.ast, p.sources, proof.types, !!dialect.nativeOrder); return { prefix: print(project({ SelectStmt: { ...typed.SelectStmt, whereClause: undefined, sortClause: undefined, limitCount: undefined, limitOption: "LIMIT_OPTION_DEFAULT" } }, p.flat ? viewOutputs(v, plan.schemas).keys ?? [] : p.names, keys, name)) + (typed.SelectStmt.whereClause ? ` WHERE (${expression(typed.SelectStmt.whereClause)})` : ""), extra: p.sources.filter(x => "cursor" in x).map(x => x.cursor) }; };
+                const suffixAst = { SelectStmt: { targetList: [{ ResTarget: { val: { A_Const: { ival: { ival: 1 } } } } }], sortClause: keys ? first.ast.SelectStmt.sortClause : undefined, limitCount: { ParamRef: { number: marker } }, limitOption: "LIMIT_OPTION_COUNT", op: "SETOP_NONE" } };
+                const tail = print(suffixAst).replace(/^SELECT 1/, "");
+                const expression = (ast) => print({ SelectStmt: { targetList: [{ ResTarget: { val: ast } }], limitOption: "LIMIT_OPTION_DEFAULT", op: "SETOP_NONE" } }).replace(/^SELECT /, "");
+                const fragment = (match, type) => {
+                    const p = pagedOf({ schemas: plan.schemas, dialect }, c, undefined, match);
+                    const ast = structuredClone(p.ast.SelectStmt.whereClause);
+                    const renumber = (node) => { if (node.ParamRef) {
+                        node.ParamRef.number = marker;
+                        if (dialect.nativeOrder && (type === "date" || type === "timestamptz")) {
+                            delete node.ParamRef;
+                            node.Raw = { parts: ["CAST(CAST(", { ParamRef: { number: marker } }, ` AS text) AS ${type})`] };
+                            return;
+                        }
+                    } for (const child of Object.values(node))
+                        if (child && typeof child === "object")
+                            Array.isArray(child) ? child.forEach(renumber) : renumber(child); };
+                    renumber(ast);
+                    return expression(ast);
+                };
+                return { marker: dialect.nativeOrder ? `$${marker}` : `?${marker}`, binds: c.binds, keys, first: read(first), ...(next ? { next: read(next) } : {}), tail, eq: Object.fromEntries((list.filterFields ?? []).map(field => { const col = v.columns?.[field] ?? v.columns?.[field.toLowerCase()], type = col && plan.schemas[col.schema]?.fields[col.field]; return [field, fragment({ eq: [{ column: field, value: "" }] }, type)]; })), ...(list.searchFields?.length ? { search: fragment({ search: { columns: list.searchFields, text: "x" } }) } : {}) };
+            });
+            all[name] = { caller: pages[0], trusted: pages[1] };
+        }
+        catch (error) {
+            refuse(`views/${name}/admin`, error instanceof Error ? error.message : String(error));
+        }
+    }
+    return all;
+}
+/** Only selected build-time Admin work; the ordinary generator remains unchanged. */
+export async function adminBindingsOf(plan, dialect, paging, wire, refusals) {
+    const adminPages = adminPaging(plan, dialect, paging, (ast, names, nkeys, name) => {
+        const keys = [...names, ...Array.from({ length: nkeys }, (_, i) => `_k${i}`)];
+        const projected = wireScalars(ast, keys, [...names.map(key => boundaryType(plan, name, key)), ...(paging[name]?.types ?? [])], wire, true);
+        if (typeof projected === "string")
+            throw Error(projected);
+        return projected;
+    }, (path, message) => refusals.push({ code: "GENERATE_UNSUPPORTED", path, message }));
+    return { ok: true, adminPages, adminEntries: await adminEntries(plan, dialect, wire, refusals) };
+}

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,188 @@
+import { existsSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { build } from "esbuild";
+import { INPUTS_FILE, authTableSql, extraRoles, generatedTarget, 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."],
+    // Admin's UI is built into <assets>/admin by the app's admin.tsx; the Worker serves it, never runs it.
+    [/(?:^|\/)node_modules\/@aotter\/mantle-admin\/dist\/admin-app\/|(?:^|\/)mantle-admin\/(?:dist\/admin-app|admin\/src)\//, "Admin's UI (@aotter/mantle-admin/app, /hooks) runs in the browser: import it only from src/admin.tsx, which `mantle bundle` builds into the assets directory."],
+];
+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]}`);
+        }
+    }
+}
+/** The physical spelling of a path, including a nonexistent tail below its nearest existing ancestor. */
+const physical = (input) => {
+    let found = resolve(input);
+    const tail = [];
+    while (!existsSync(found)) {
+        const parent = dirname(found);
+        if (parent === found)
+            return found;
+        tail.unshift(basename(found));
+        found = parent;
+    }
+    return resolve(realpathSync(found), ...tail);
+};
+/** Whether `inner` is `outer` or inside it. */
+const within = (outer, inner) => {
+    const path = relative(physical(outer), physical(inner));
+    return path === "" || (path !== ".." && !path.startsWith(`..${sep}`) && !isAbsolute(path));
+};
+/** A directory a build empties must not be the working directory or hold the source entry. */
+function assertCleanable(label, dir, entry) {
+    if (physical(dir) === physical(process.cwd()))
+        throw new Error(`${label} must not be the working directory: it is cleaned before building.`);
+    if (within(dir, entry))
+        throw new Error(`${label} must not contain the source entry: it is cleaned before building.`);
+}
+/** The app's own modules only (packages external): enough to find its generated output and what it imports. */
+export const ownModules = async (entry) => (await build({ entryPoints: [entry], bundle: true, write: false, metafile: true, packages: "external", format: "esm", platform: "neutral", logLevel: "silent", absWorkingDir: process.cwd() })).metafile;
+/**
+ * `mantle bundle <entry> <outdir> [--assets <dir>]`: the Worker into `<outdir>/worker`, and Admin into `<assets>/admin`
+ * (default `<outdir>/client`) when the Worker serves it (`@aotter/mantle-admin/server`; `/mcp` and the other subpaths alone do not).
+ * A server whose generated output records a `bun-*` target runs as TypeScript, so only its Admin is built.
+ */
+export async function bundleApp(entry, outdir, assets = join(outdir, "client")) {
+    const source = realpathSync(entry);
+    // what is cleaned lies under these two, so neither may be the working directory or hold the source
+    assertCleanable("Bundle outdir", outdir, source);
+    assertCleanable("The assets directory", assets, source);
+    const own = await ownModules(entry);
+    if (generatedDirs(own).some(dir => generatedTarget(join(dir, "generated.ts"))?.startsWith("bun-"))) {
+        // Packages are external here, so only the app's own imports of the Admin server are seen; one reached through another package is not.
+        if (Object.values(own.inputs).some(input => input.imports.some(imported => /^@aotter\/mantle-admin\/server(?:\/|$)/.test(imported.path))))
+            await bundleAdmin(source, outdir, join(assets, "admin"));
+        else
+            console.warn("note: no Admin built: the entry's own modules do not import @aotter/mantle-admin/server (an import through another package is not seen).");
+        return;
+    }
+    const worker = join(outdir, "worker");
+    // Wrangler uploads every module under the Worker directory and every file under the assets directory.
+    if (within(worker, assets) || within(assets, worker))
+        throw new Error(`The assets directory ${assets} must not overlap the Worker directory ${worker}.`);
+    const metafile = await bundle(entry, worker);
+    if (Object.keys(metafile.inputs).some(input => /(?:^|\/)mantle-admin\/(?:dist|src)\/server\/index\.[jt]s$/.test(input.replaceAll("\\", "/")))) {
+        await bundleAdmin(source, outdir, join(assets, "admin"));
+    }
+}
+/**
+ * Admin from `<dirname(entry)>/admin.tsx`, or the built-in entry; an optional `admin.mcp.tsx` selects the host-safe graph.
+ * Uses `@aotter/mantle-admin/build` as the app installed
+ * it. The built-in entry is skipped when the installed Admin and its direct dependencies are unchanged since the last
+ * build; an application entry always builds, because what it imports is only known by building it.
+ */
+async function bundleAdmin(entry, outdir, out) {
+    const source = join(dirname(entry), "admin.tsx"), custom = existsSync(source);
+    const mcpSource = join(dirname(entry), "admin.mcp.tsx"), customMcp = existsSync(mcpSource);
+    assertCleanable("The Admin output directory", out, entry);
+    const require = createRequire(entry);
+    let builder;
+    try {
+        builder = require.resolve("@aotter/mantle-admin/build");
+    }
+    catch {
+        throw new Error(`The Worker serves Admin, but @aotter/mantle-admin/build does not resolve from ${relative(process.cwd(), entry)}. Install @aotter/mantle-admin at the version of @aotter/mantle-admin/server.`);
+    }
+    const stamp = join(outdir, ".admin-inputs");
+    // the installed path too: a patched or linked Admin keeps its version but not its path
+    const manifest = realpathSync(lookup(require, "@aotter/mantle-admin") ?? require.resolve("@aotter/mantle-admin/package.json"));
+    const key = custom || customMcp ? undefined : JSON.stringify({ out: resolve(out), path: dirname(manifest), packages: installed(manifest) });
+    if (key && existsSync(join(out, "index.html")) && existsSync(join(out, "mcp-app.html")) && existsSync(stamp) && readFileSync(stamp, "utf8") === key) {
+        console.log(`Admin inputs unchanged; kept ${relative(process.cwd(), out)}.`);
+        return;
+    }
+    rmSync(stamp, { force: true });
+    const { buildAdmin } = await import(pathToFileURL(builder).href);
+    await buildAdmin({ entry: custom ? source : undefined, ...(customMcp ? { mcpEntry: mcpSource } : {}), outDir: out });
+    if (key)
+        writeFileSync(stamp, key);
+}
+/** The package.json a bare import of `name` finds, read from disk (`exports` may hide it, and require caches realpaths). */
+const lookup = (require, name) => require.resolve.paths(name)?.map(dir => join(dir, name, "package.json")).find(file => existsSync(file));
+/** The package's version and the installed version of each of its dependencies and peers (React comes from the application). */
+function installed(manifest) {
+    const { name, version, dependencies = {}, peerDependencies = {} } = JSON.parse(readFileSync(manifest, "utf8"));
+    const require = createRequire(manifest);
+    const versions = { [name]: version };
+    for (const dependency of Object.keys({ ...peerDependencies, ...dependencies }).sort()) {
+        const found = lookup(require, dependency);
+        versions[dependency] = found ? JSON.parse(readFileSync(found, "utf8")).version : null;
+    }
+    return versions;
+}
+/** The generated directories among a build's inputs, refusing stale ones. */
+function generatedDirs(metafile) {
+    const dirs = [...new Set(Object.keys(metafile.inputs).map(input => resolve(input, "..")).filter(dir => existsSync(resolve(dir, INPUTS_FILE))))];
+    for (const dir of dirs) {
+        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.`);
+    }
+    return dirs;
+}
+export async function bundle(entry, outdir) {
+    entry = realpathSync(entry);
+    assertCleanable("Bundle outdir", outdir, entry);
+    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).
+    generatedDirs(result.metafile);
+    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,118 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, 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 help [topic]   (start here: the installed docs, one topic at a time)\n       mantle init [directory] [--dry-run]\n       mantle generate <target> <output-directory> <manifest>... [--check] [--admin] [--site <module>] [--auth <module>]... (one per Better Auth instance) [--wrangler <path>] [--entry <worker entry>] [--outdir <bundle directory>] [--assets <static assets directory>]\n       mantle bundle <entry> <outdir> [--assets <static assets directory>]\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" }, auth: { type: "string", multiple: true }, wrangler: { type: "string" }, entry: { type: "string", default: "src/worker.ts" }, outdir: { type: "string", default: "dist" }, assets: { type: "string" }, "dry-run": { type: "boolean" }, help: { type: "boolean", short: "h" },
+        } });
+    const named = ["bundle", "generate", "describe", "help", "init"].includes(positionals[0]) ? positionals.shift() : undefined;
+    // `-h` prints usage and never runs a command; bare `mantle` starts at help, but options with no positionals stay a usage error.
+    const command = values.help ? "usage" : named ?? (process.argv.length > 2 ? "generate" : "help");
+    if (command === "usage")
+        console.log(`${usage}\n\nStart with mantle help: the installed docs, one topic at a time.`);
+    else if (command === "help") {
+        const { help, topicList } = await import("./help.js");
+        if (positionals.length > 1)
+            throw new Error(usage);
+        console.log(positionals[0] === "topics" ? topicList() : help(positionals[0]));
+    }
+    else if (command === "init") {
+        if (positionals.length > 1)
+            throw new Error(usage);
+        console.log((await import("./init.js")).init(positionals[0] ?? ".", values["dry-run"]));
+    }
+    else 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.wrangler || values.check)
+            throw new Error(usage);
+        await (await import("./bundle.js")).bundleApp(entry, outdir, values.assets);
+    }
+    else {
+        const [target, destination, ...paths] = positionals;
+        if (!target || !targets.includes(target) || !destination || !paths.length)
+            throw new Error(usage);
+        // A shell leaves an unmatched glob as is; say what is missing instead of ENOENT.
+        for (const path of paths)
+            if (/[*?]/.test(path) && !existsSync(path))
+                throw new Error(`No manifest matches ${path}. Add one (mantle help four-atoms, mantle help manifest), then run generate again.`);
+        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 { generateFromSources } = await (auth.length ? import("./generateAuth.js") : import("./generate.js"));
+        const result = await generateFromSources({ target: target, sources: { sources }, admin: values.admin, auth, site });
+        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.site] : [])];
+        const changed = await writeArtifacts(destination, { ...result.files, [INPUTS_FILE]: inputsFingerprint(destination, read, target) }, values.check);
+        // After writing: the entry's imports of generated modules only resolve once they exist.
+        for (const warning of await (await import("./mounts.js")).unmountedWarnings(values.entry, destination, result.files))
+            console.warn(`warning: ${warning}`);
+        if (target.startsWith("cloudflare-")) {
+            const wrangler = values.wrangler ?? ["wrangler.jsonc", "wrangler.json", "wrangler.toml"].find(existsSync) ?? "wrangler.jsonc";
+            const assets = values.admin ? values.assets ?? join(values.outdir, "client") : undefined;
+            const publicFetchRequired = auth.some(options => options.plugins?.some((plugin) => plugin.id === "oauth-provider" || plugin.id === "cimd"));
+            if (configureWrangler(wrangler, values.entry, values.outdir, destination, values.check, assets, publicFetchRequired))
+                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`);
+        // A contract, not a to-do: the CLI does not read the app's handlers; tsc checks them against Handlers.
+        if (!values.check && result.refProcedures.length)
+            console.log(`Ref Procedures need these Handlers keys (tsc --noEmit checks them; pass them at store(db, caller, { handlers })): ${result.refProcedures.map(name => JSON.stringify(name)).join(", ")}`);
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/dist/infrastructure/generate.d.ts

@@ -0,0 +1,12 @@
+/** Build-time assembly only. None of these imports enter generated applications. */
+import { d1Dialect, 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;
+}
+export declare function generateFromSources(request: GenerateRequest, schema?: () => readonly string[]): Promise<GenerateResult>;