@aotter/mantle 0.2.0-alpha.9 → 0.2.1-alpha.1

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,53 +49,62 @@ 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 async function bundleApp(entry, outdir, assets = join(outdir, "client")) {
+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"), options = {}) {
     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" });
-    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.
+    const own = await ownModules(entry);
+    const worker = join(outdir, "worker");
+    const apart = () => {
+        if (within(worker, assets) || within(assets, worker))
+            throw new Error(`The assets directory ${assets} must not overlap the Worker directory ${worker}.`);
+    };
+    const refuse = (error) => {
+        if (!options.watch || !(error instanceof StaleGeneratedError))
+            throw error;
+        apart();
+        rmSync(worker, { recursive: true, force: true });
+        console.error(`${error.summary} Run your generate script (mantle generate ...). ${worker} is removed, so Wrangler reports its entry missing; a running wrangler dev holds requests and rebuilds when ${error.dir} changes.`);
+    };
+    let dirs;
+    try {
+        dirs = generatedDirs(own);
+    }
+    catch (error) {
+        refuse(error);
+        return;
+    }
+    if (dirs.some(dir => generatedTarget(join(dir, "generated.ts"))?.startsWith("bun-"))) {
         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);
+    apart();
+    let metafile;
+    try {
+        metafile = await bundle(entry, worker);
+    }
+    catch (error) {
+        refuse(error);
+        return;
+    }
     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);
@@ -114,7 +118,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 +130,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,13 +141,22 @@ function installed(manifest) {
     }
     return versions;
 }
-/** The generated directories among a build's inputs, refusing stale ones. */
+export class StaleGeneratedError extends Error {
+    dir;
+    summary;
+    constructor(dir, reasons) {
+        const summary = `Generated output in ${dir} is stale (${reasons.join("; ")}).`;
+        super(`${summary} Run your generate script (mantle generate ...) and rebuild.`);
+        this.dir = dir;
+        this.summary = summary;
+    }
+}
 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);
+        const stale = staleInputs(resolve(dir, "generated.ts"));
         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.`);
+            throw new StaleGeneratedError(relative(process.cwd(), dir), stale);
     }
     return dirs;
 }
@@ -163,15 +173,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);
@@ -47,15 +60,16 @@ try {
         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);
+        await (await import("./bundle.js")).bundleApp(entry, outdir, values.assets, { watch: process.env.WRANGLER_COMMAND === "dev" });
     }
     else {
         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,6 +1,5 @@
 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 { compilePlan, lockCondition, 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";
@@ -12,12 +11,11 @@ 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. */
+const coreLocks = (dialect, schemas) => Object.fromEntries(Object.entries(schemas).flatMap(([name, s]) => s.locks?.length ? [[name, s.locks.map(l => ({
+            name: l.name, on: l.on, message: l.message,
+            sql: dialect.print({ SelectStmt: { targetList: [{ ResTarget: { val: lockCondition(l.when, schemas, dialect.lowering) } }], limitOption: "LIMIT_OPTION_DEFAULT", op: "SETOP_NONE" } }, schemas).replace(/^SELECT /, ""),
+        }))]] : []));
 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 +30,26 @@ 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}.`)));
+}
+function adminSearchWarnings(plan) {
+    return Object.values(plan.schemas).filter(s => !s.translates && !s.search?.length).flatMap(s => {
+        const properties = (s.schema.properties ?? {});
+        const primary = s.uiSchema?.["list"]?.primaryField;
+        const field = [primary, "title"].find((f) => typeof f === "string" && [properties[f]?.type].flat().includes("string") && !["date", "date-time"].includes(String(properties[f]?.format)) && properties[f]?.["x-mantle-ref"] == null);
+        return field ? [`Schema '${s.name}' declares no searchableFields, so Admin's list search matches the entry id only and a search for its '${field}' finds nothing. Add searchableFields: [${field}] to search it.`] : [];
+    });
 }
-/** Warn about SQL's case folding without changing the authored output names. */
 function outputNameWarnings(plan) {
     const warnings = [];
     const inspect = (kind, name, stmts) => {
@@ -113,8 +117,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;
@@ -149,6 +151,8 @@ export async function generateFromSources(request, schema) {
                         if (!seen.has(statement)) {
                             seen.add(statement);
                             castInputs(statement, `${kind}/${name}`, refusals);
+                            if (statement.probe)
+                                castInputs(statement.probe, `${kind}/${name}`, refusals);
                             if ("paged" in statement)
                                 for (const page of Object.values(statement.paged)) {
                                     const inputPage = { ...statement, sql: page.sql };
@@ -163,14 +167,17 @@ export async function generateFromSources(request, schema) {
     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), paging });
+    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), locks: coreLocks(dialect, compiled.plan.schemas), 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;
+        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) })) } : {}) }];
@@ -178,5 +185,5 @@ export async function generateFromSources(request, schema) {
     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: [...missingMcpWarnings(compiled.plan), ...outputNameWarnings(compiled.plan), ...(request.admin ? adminCreateWarnings(compiled.plan) : []), ...(compiled.plan.access?.warnings ?? [])], files: { ...files, ...gatewayFiles, ...generatedFiles({ "schema.sql": ddl.join(";\n\n") + ";\n" + siteSql }) } };
+    return { ...result, warnings: [...missingMcpWarnings(compiled.plan), ...outputNameWarnings(compiled.plan), ...(request.admin ? [...adminCreateWarnings(compiled.plan), ...adminSearchWarnings(compiled.plan)] : []), ...(compiled.plan.access?.warnings ?? [])], files: { ...files, ...gatewayFiles, ...generatedFiles({ "schema.sql": ddl.join(";\n\n") + ";\n" + siteSql }) } };
 }

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");
+}

package/dist/infrastructure/init.js

@@ -0,0 +1,50 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { docsRoot, packageRoot } from "./help.js";
+const LOCAL = new Set(["node_modules", ".wrangler", ".dev.vars", "pnpm-lock.yaml", "generated", "dist"]);
+function files(directory) {
+    return readdirSync(directory, { withFileTypes: true }).flatMap(entry => LOCAL.has(entry.name) ? []
+        : entry.isDirectory() ? files(join(directory, entry.name)).map(file => join(entry.name, file)) : [entry.name]);
+}
+export function init(destination, dryRun = false) {
+    const shell = resolve(docsRoot(), "examples/app-shell");
+    const sdk = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8"));
+    const target = resolve(destination);
+    const all = files(shell).map(file => file === "gitignore" ? ".gitignore" : file);
+    const source = (file) => file === ".gitignore" && !existsSync(join(shell, file)) ? join(shell, "gitignore") : join(shell, file);
+    const existing = all.filter(file => existsSync(join(target, file)));
+    if (existing.length)
+        throw new Error(`mantle init writes the app shell once and never overwrites. These files already exist in ${target}:\n${existing.map(f => `  ${f}`).join("\n")}\nMove them aside or run mantle init in an empty directory; to use generated code inside an existing app, skip init and run mantle help typed-queries.`);
+    const notes = [];
+    for (const file of all) {
+        let text = readFileSync(source(file), "utf8");
+        if (file === "package.json") {
+            const pkg = JSON.parse(text);
+            for (const name of Object.keys(pkg.dependencies))
+                if (name.startsWith("@aotter/mantle"))
+                    pkg.dependencies[name] = sdk.version;
+            text = JSON.stringify(pkg, null, 2) + "\n";
+        }
+        if (!file.endsWith(".md"))
+            text.split("\n").forEach((line, index) => { if (line.includes("AGENT:"))
+                notes.push(`  ${file}:${index + 1}: ${line.slice(line.indexOf("AGENT:") + 6).trim()}`); });
+        if (dryRun)
+            continue;
+        mkdirSync(dirname(join(target, file)), { recursive: true });
+        writeFileSync(join(target, file), text, { flag: "wx" });
+    }
+    if (!dryRun)
+        mkdirSync(join(target, "manifests"), { recursive: true });
+    const where = relative(process.cwd(), target) || ".";
+    return [
+        `${dryRun ? "Would write" : "Wrote"} the Mantle ${sdk.version} app shell to ${where}:`,
+        ...all.map(file => `  ${file}`), "  manifests/",
+        "",
+        "AGENT: the app must fill in these before it is done (each is marked in the file):",
+        "  manifests/*.yaml: the app's Schemas, Views, Procedures and Triggers (mantle help four-atoms)",
+        ...notes,
+        "",
+        `Next: cd ${where} && pnpm install; then follow README.md. mantle help explains each step;`,
+        "mantle help examples shows the patterns to take for each need. Accept with mantle help agent-workflow-acceptance before reporting done.",
+    ].join("\n");
+}

package/dist/infrastructure/inputs.js

@@ -1,23 +1,17 @@
-/** `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 target and the manifests and option modules (`--auth`, `--site`) one generate run read, by path relative to its output. */
 export function inputsFingerprint(destination, paths, target) {
     const inputs = Object.fromEntries(paths.map(path => [relative(resolve(destination), resolve(path)).replaceAll("\\", "/"), digest(path)]));
     return JSON.stringify({ mantle: MANTLE_VERSION, target, inputs }, null, 2) + "\n";
 }
-/** The generate target recorded beside `generatedModule` (undefined without a fingerprint, or one written before targets were recorded). */
 export function generatedTarget(generatedModule) {
     const file = resolve(dirname(generatedModule), INPUTS_FILE);
     return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")).target : undefined;
 }
-/** 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))
@@ -29,13 +23,10 @@ export function staleInputs(generatedModule) {
             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()))];
 }

package/dist/infrastructure/mounts.js

@@ -0,0 +1,22 @@
+import { existsSync } from "node:fs";
+import { relative, resolve } from "node:path";
+import { ownModules } from "./bundle.js";
+const SURFACES = [
+    { module: "rest.ts", selected: files => files["rest.ts"]?.includes("pattern: new RegExp") ?? false, what: "REST routes", topic: "service-entry" },
+    { module: "mcp.ts", selected: files => "mcp.ts" in files, what: "MCP tools", topic: "service-entry" },
+    { module: "admin-bindings.ts", selected: files => "admin-bindings.ts" in files, what: "Admin bindings", topic: "native-admin" },
+];
+export async function unmountedWarnings(entry, destination, files) {
+    const selected = SURFACES.filter(surface => surface.selected(files));
+    if (!selected.length || !existsSync(entry))
+        return [];
+    let inputs;
+    try {
+        inputs = Object.keys((await ownModules(entry)).inputs).map(path => resolve(path));
+    }
+    catch (error) {
+        const first = error.errors?.[0]?.text ?? String(error);
+        return [`skipped checking which generated surfaces ${entry} serves: could not follow its imports (${first}).`];
+    }
+    return selected.filter(surface => !inputs.includes(resolve(destination, surface.module))).map(surface => `${surface.what} are generated in ${relative(process.cwd(), resolve(destination, surface.module))}, but ${entry} never imports it, so no request reaches them. Mount it in the entry (mantle help ${surface.topic}), or pass --entry if the app starts elsewhere.`);
+}