@aotter/mantle 0.2.0-alpha.9 → 0.2.0

package/dist/infrastructure/adminPaging.js

@@ -4,69 +4,67 @@ 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";
-export function adminPaging(plan, dialect, proofs, project) {
+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.reason)
-            throw Error(proof?.reason ?? `Unproved Admin paging: ${name}`);
-        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] };
+        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) {
-    let adminPages;
-    try {
-        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;
-        });
-    }
-    catch (error) {
-        refusals.push({ code: "GENERATE_UNSUPPORTED", path: "admin/views", message: error instanceof Error ? error.message : String(error) });
-    }
+    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

@@ -1,7 +1,6 @@
 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")
@@ -22,15 +21,12 @@ async function ownedFiles(directory, prefix = "") {
     }
     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}`))

package/dist/infrastructure/authSchema.js

@@ -3,7 +3,6 @@ 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";
@@ -12,12 +11,6 @@ function columnType(field, dialect) {
         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)
@@ -28,7 +21,6 @@ export function fieldIndexName(table, column) {
     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 = [];
@@ -51,7 +43,6 @@ 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;

package/dist/infrastructure/bundle.js

@@ -4,7 +4,6 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
 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) => {
@@ -25,23 +24,19 @@ export function startupGraph(metafile, entry) {
 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 = [];
@@ -54,32 +49,23 @@ const physical = (input) => {
     }
     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.`);
 }
-/**
- * `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 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;
 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);
-    // The app's own modules only: enough to find its generated output and whether it imports the Admin server.
-    const { metafile: own } = await build({ entryPoints: [entry], bundle: true, write: false, metafile: true, packages: "external", format: "esm", platform: "neutral", logLevel: "silent" });
+    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
@@ -87,7 +73,6 @@ export async function bundleApp(entry, outdir, assets = join(outdir, "client"))
         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);
@@ -95,12 +80,6 @@ export async function bundleApp(entry, outdir, assets = join(outdir, "client"))
         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);
@@ -114,7 +93,6 @@ async function bundleAdmin(entry, outdir, out) {
         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) {
@@ -127,9 +105,7 @@ async function bundleAdmin(entry, 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);
@@ -140,7 +116,6 @@ function installed(manifest) {
     }
     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) {
@@ -163,15 +138,12 @@ export async function bundle(entry, outdir) {
                         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) {

package/dist/infrastructure/cli.js

@@ -7,7 +7,6 @@ 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);
@@ -19,13 +18,27 @@ async function load(path) {
     }
 }
 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) [--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>]";
+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" },
+            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 command = positionals[0] === "bundle" || positionals[0] === "generate" || positionals[0] === "describe" ? positionals.shift() : "generate";
-    if (command === "describe") {
+    const named = ["bundle", "generate", "describe", "help", "init"].includes(positionals[0]) ? positionals.shift() : undefined;
+    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);
@@ -53,9 +66,10 @@ try {
         const [target, destination, ...paths] = positionals;
         if (!target || !targets.includes(target) || !destination || !paths.length)
             throw new Error(usage);
+        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;
@@ -74,6 +88,8 @@ try {
             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);
+        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;
@@ -85,10 +101,8 @@ try {
             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 }).");
+        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) {

package/dist/infrastructure/generate.js

@@ -1,5 +1,4 @@
 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";
@@ -12,12 +11,7 @@ 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;
@@ -32,20 +26,18 @@ function castInputs(statement, path, refusals) {
     }
     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.
+        const folded = Object.entries(s.schema.properties ?? {}).some(([name, property]) => required.has(name) && property?.["x-mantle-ref"] != null);
         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 ?? {})
+    }).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.${s.userScopes?.length ? ` That Procedure takes ${s.userScopes.map(u => `'${u.column}'`).join(', ')} as an optional input for callers holding { all: true } (field scope in the Schema reference).` : ''}`).concat(Object.values(plan.schemas)
+        .filter(s => s.schema.readOnly !== true && !placed.has(s.name.toLowerCase()))
+        .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).`)));
+        .map(([name]) => `Schema '${s.name}' field '${name}' is required and readOnly without a default, so Admin's generic create cannot fill it. Give it a default (Admin stores it on create), or create the records through a Procedure with uiSchema.collectionAction: ${s.name}.`)));
 }
-/** Warn about SQL's case folding without changing the authored output names. */
 function outputNameWarnings(plan) {
     const warnings = [];
     const inspect = (kind, name, stmts) => {
@@ -113,8 +105,6 @@ export async function generateFromSources(request, schema) {
     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 ast;
@@ -170,7 +160,10 @@ export async function generateFromSources(request, schema) {
         return { ok: false, diagnostics: [...refusals, ...diagnostics] };
     }
     if (!result.ok)
-        return result;
+        return { ...result, diagnostics: result.diagnostics.map(d => {
+                const why = d.message === "Both caller and trusted SQL must be lowered." ? warnings.find(w => w.includes(`${d.path} (caller)`) || w.includes(`${d.path} (admin)`)) : undefined;
+                return why ? { ...d, message: `${d.message} ${why.slice(why.indexOf("): ") + 3)}` } : d;
+            }) };
     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) })) } : {}) }];

package/dist/infrastructure/generateAuth.js

@@ -1,7 +1,6 @@
 import { generateFromSources as generate } from "./generate.js";
 import { admin, anonymous, jwt, phoneNumber, siwe, twoFactor } from "better-auth/plugins";
 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);
@@ -9,29 +8,23 @@ export function generateFromSources(request) {
 function authSql(instances, dialect) {
     for (const options of instances) {
         const ids = (options.plugins ?? []).map(plugin => plugin.id);
-        // Offline OAuth grants outlive sessions; without the revocation plugin a password reset or ban would not end them. mcp() spreads oauthProvider, id included.
-        if (ids.includes("oauth-provider") && !ids.includes("mantle-oauth-grant-revocation") /* oauthGrantRevocation().id */)
+        if (ids.includes("oauth-provider") && !ids.includes("mantle-oauth-grant-revocation") )
             throw new Error("Better Auth has an OAuth provider (oauthProvider or mcp) without oauthGrantRevocation(): add it from @aotter/mantle/auth/oauth to the plugins, so a password reset, an admin ban or session revocation ends that user's OAuth grants.");
     }
     if (instances.length > 1)
         refuseSharedPluginMappings(instances);
     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;
 }
-// Plugins whose factory hands back one module-level schema object (mergeSchema writes `schema` options into it); no options leaves it untouched.
 const sharedSchema = {
     jwt: () => jwt().schema, admin: () => admin().schema, anonymous: () => anonymous().schema,
     "phone-number": () => phoneNumber({}).schema, siwe: () => siwe({}).schema, "two-factor": () => twoFactor().schema,
 };
-// Plugins that share field objects (device-authorization) or copy per call (oauth-provider, listed on request) are only checked for equal resolved names.
 const checkedPlugins = new Set([...Object.keys(sharedSchema), "device-authorization", "oauth-provider"]);
-/** Names a plugin's tables and fields resolve to, keyed `table` / `table.field`; only mappings that differ from the key are listed. */
 function mapped(schema) {
     const names = new Map();
     for (const [table, model] of Object.entries(schema)) {
@@ -45,7 +38,6 @@ function mapped(schema) {
     }
     return names;
 }
-/** Better Auth plugin factories share their schema object, so differing plugin field/model mappings across instances in one Worker override each other. */
 function refuseSharedPluginMappings(instances) {
     const byPlugin = new Map();
     instances.forEach((options, index) => (options.plugins ?? []).forEach(plugin => {

package/dist/infrastructure/help.js

@@ -0,0 +1,55 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, dirname, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+export const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "../..");
+export function docsRoot() {
+    const root = [resolve(packageRoot, "docs"), resolve(packageRoot, "../../docs")].find(path => existsSync(resolve(path, "handbook/navigation.json")));
+    if (!root)
+        throw new Error(`Mantle docs are missing from ${packageRoot}; reinstall @aotter/mantle.`);
+    return root;
+}
+export function topics(root = docsRoot()) {
+    const nav = JSON.parse(readFileSync(resolve(root, "handbook/navigation.json"), "utf8"));
+    const pages = nav.groups.flatMap(group => group.items.map(item => ({ name: item.link.slice(1), title: item.text, file: resolve(root, `handbook${item.link}.md`), group: group.text })));
+    const listed = new Set(pages.map(page => page.file));
+    const unlisted = readdirSync(resolve(root, "handbook"), { recursive: true }).filter(path => path.endsWith(".md")).sort()
+        .map(path => resolve(root, "handbook", path)).filter(file => !listed.has(file))
+        .map(file => ({ name: relative(resolve(root, "handbook"), file).replaceAll("\\", "/").slice(0, -3), title: readFileSync(file, "utf8").match(/^# (.+)$/m)?.[1] ?? basename(file), file, group: "More pages" }));
+    const skills = (existsSync(resolve(root, "skills")) ? readdirSync(resolve(root, "skills")) : []).filter(name => existsSync(resolve(root, "skills", name, "SKILL.md")))
+        .map(name => ({ name: `skills/${name}`, title: `Package skill: ${name}`, file: resolve(root, "skills", name, "SKILL.md"), group: "Package skills" }));
+    const examples = resolve(root, "examples");
+    const shipped = readdirSync(examples, { withFileTypes: true }).filter(entry => entry.isDirectory() && existsSync(resolve(examples, entry.name, "README.md")));
+    return [...pages, ...unlisted, ...skills, { name: "examples", title: "Examples and how to combine them", file: resolve(examples, "README.md"), group: "Examples" },
+        ...shipped.map(entry => ({ name: `examples/${entry.name}`, title: `Example: ${entry.name}`, file: resolve(examples, entry.name, "README.md"), group: "Examples" }))];
+}
+function find(all, name) {
+    const exact = all.find(topic => topic.name === name);
+    if (exact)
+        return exact;
+    const tail = all.filter(topic => basename(topic.name) === name);
+    return tail.length === 1 ? tail[0] : undefined;
+}
+export function help(name, root = docsRoot()) {
+    const all = topics(root);
+    const topic = find(all, name ?? "start/agents");
+    if (!topic) {
+        const near = all.filter(t => name && t.name.includes(name)).map(t => `  mantle help ${t.name}`);
+        throw new Error(`No help topic ${JSON.stringify(name)}.${near.length ? `\nDid you mean:\n${near.join("\n")}` : ""}\nRun mantle help topics for the list.`);
+    }
+    const text = readFileSync(topic.file, "utf8").replace(/^---\n[\s\S]*?\n---\n/, "").trim();
+    const linked = [...new Set([...text.matchAll(/\]\(([^)#\s]+\.md)(?:#[^)]*)?\)/g)].map(match => resolve(dirname(topic.file), match[1])))]
+        .flatMap(file => all.filter(t => t.file === file && t !== topic));
+    const index = all.indexOf(topic), next = all[index + 1]?.group === topic.group ? all[index + 1] : undefined;
+    const lines = [text, "", `Source: ${relative(process.cwd(), topic.file) || topic.file}`];
+    if (next)
+        lines.push(`Next: mantle help ${next.name}  (${next.title})`);
+    if (linked.length)
+        lines.push("Linked:", ...linked.map(t => `  mantle help ${t.name}  (${t.title})`));
+    if (!name)
+        lines.push("", topicList(all));
+    return lines.join("\n");
+}
+export function topicList(all = topics()) {
+    const groups = [...new Set(all.map(topic => topic.group))];
+    return ["Topics:", ...groups.flatMap(group => [`  ${group}`, ...all.filter(t => t.group === group).map(t => `    ${t.name.padEnd(34)} ${t.title}`)])].join("\n");
+}