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

package/dist/infrastructure/generate.js

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

package/dist/infrastructure/generateAuth.d.ts

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

package/dist/infrastructure/generateAuth.js

@@ -0,0 +1,74 @@
+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);
+}
+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 */)
+            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)) {
+        if (model.modelName && model.modelName !== table)
+            names.set(table, model.modelName);
+        for (const [field, type] of Object.entries(model.fields ?? {})) {
+            const name = type.fieldName;
+            if (name && name !== field)
+                names.set(`${table}.${field}`, name);
+        }
+    }
+    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 => {
+        const schema = plugin.schema;
+        if (schema && checkedPlugins.has(plugin.id))
+            byPlugin.set(plugin.id, [...(byPlugin.get(plugin.id) ?? []), { index, schema }]);
+    }));
+    for (const [id, uses] of byPlugin) {
+        const names = uses.map(use => mapped(use.schema));
+        if (uses.length < 2 || !names.some(own => own.size))
+            continue;
+        const fail = (reason, which) => { throw new Error(`Better Auth plugin ${id} is used by instances ${which.join(", ")} (--auth order, from 0) and ${reason}. Plugin factories share their schema object, so differing plugin field/model mappings across instances in one Worker override each other: pass an explicit \`schema\` mapping to the ${id} plugin in every instance, with names that differ between instances, and give each instance its own copy right after constructing it, \`{ ...plugin, schema: structuredClone(plugin.schema) }\`; or keep the ${id} plugin at its defaults and separate the instances by core table names.`); };
+        const shared = sharedSchema[id]?.();
+        const holders = uses.filter(use => use.schema === shared).map(use => use.index);
+        if (holders.length)
+            fail("a non-default mapping exists while an instance holds the plugin's shared schema object (no own copy)", holders);
+        for (const [i, a] of uses.entries())
+            for (const [j, b] of uses.entries()) {
+                if (j <= i)
+                    continue;
+                for (const [key, name] of names[i])
+                    if (names[j].get(key) === name)
+                        fail(`both resolve ${key} to "${name}"; non-default plugin names must differ between instances, because generate cannot tell an identical mapping from an inherited one`, [a.index, b.index]);
+            }
+    }
+}

package/dist/infrastructure/help.js

@@ -0,0 +1,60 @@
+/** `mantle help [topic]`: a projection of the installed docs/handbook/navigation.json; the docs stay the only source. */
+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)), "../..");
+/** Packed: <package>/docs. Workspace: the repository's docs/, which prepack copies in. */
+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 })));
+    // Pages the sidebar leaves out (acceptance, release notes) are still topics.
+    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" }))];
+}
+/** A full topic name, or its last segment when only one topic ends with it. */
+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();
+    // Links to other topics become commands, so an agent can follow them without knowing the docs layout.
+    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,54 @@
+/** `mantle init`: copy the installed app shell once. The app owns every file afterwards; init never overwrites one. */
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { docsRoot, packageRoot } from "./help.js";
+// Local state a docs checkout may hold after someone ran the shell in place; sync-package-docs excludes the same names.
+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);
+    // A packed shell carries `gitignore` (npm drops .gitignore); a workspace checkout has .gitignore itself.
+    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");
+        // Pin the shell's Mantle packages to the installed SDK.
+        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

@@ -0,0 +1,41 @@
+/** `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))
+        return [];
+    const recorded = JSON.parse(readFileSync(file, "utf8"));
+    const stale = recorded.mantle === MANTLE_VERSION ? [] : [`generated by Mantle ${recorded.mantle}, building with ${MANTLE_VERSION}`];
+    for (const [path, hash] of Object.entries(recorded.inputs))
+        if (digest(resolve(directory, path)) !== hash)
+            stale.push(`${relative(process.cwd(), resolve(directory, path))} changed`);
+    return stale;
+}
+/** Better Auth roles an app declares beyond `admin` and `user` (`<name>: ac.newRole(...)`), for a one-line design note. */
+export function extraRoles(source) {
+    return [...source.matchAll(/["']?([A-Za-z][\w-]*)["']?\s*:\s*ac\.newRole\(/g)].map(m => m[1]).filter(role => role !== "admin" && role !== "user");
+}
+/** Better Auth tables an app's own code queries with SQL (`FROM "user"`, `JOIN session` ...), for a one-line note. */
+export function authTableSql(source) {
+    // Only lines that read like SQL statements, so prose such as "take into account" is not a finding.
+    const sql = source.split("\n").filter(line => /\b(?:SELECT|INSERT|UPDATE|DELETE)\b/.test(line)).join("\n");
+    return [...new Set([...sql.matchAll(/\b(?:FROM|JOIN|UPDATE|INTO)\s+"?(user|session|account|verification)"?(?=[\s;),`'"]|$)/gi)].map(m => m[1].toLowerCase()))];
+}

package/dist/infrastructure/mounts.js

@@ -0,0 +1,25 @@
+/** Warn when a surface the manifests select is generated but the app entry never imports it, so it is never served. */
+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" },
+];
+/** Follows relative static and dynamic imports from the entry; packages stay external, so nothing needs to be installed. */
+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) {
+        // This probe has none of mantle bundle's loaders or conditions, so a failure here says nothing about the entry.
+        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.`);
+}

package/dist/infrastructure/wrangler.js

@@ -0,0 +1,109 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+import { applyEdits, modify, parse } from "jsonc-parser";
+const requiredFlags = ["nodejs_compat", "global_fetch_strictly_public"];
+/** Newest date the project's installed workerd supports, as create-cloudflare picks it; a fixed date before Wrangler is installed. */
+function compatibilityDate(dir) {
+    try {
+        let from = join(dir, "package.json");
+        for (const name of ["wrangler", "miniflare", "workerd"])
+            from = createRequire(from).resolve(`${name}/package.json`);
+        const [, y, m, d] = /^\d+\.(\d{4})(\d{2})(\d{2})\./.exec(JSON.parse(readFileSync(from, "utf8")).version) ?? [];
+        if (y)
+            return `${y}-${m}-${d}`;
+    }
+    catch { }
+    return "2026-09-28";
+}
+/** `assets`: with `--admin`, the static assets directory `mantle bundle` builds Admin into (`<assets>/admin`). */
+export function configureWrangler(configPath, entry, outdir, generated, check = false, assets, publicFetchRequired = false) {
+    const configDir = dirname(resolve(configPath));
+    const local = (path) => relative(configDir, resolve(path)).replaceAll("\\", "/") || ".";
+    const output = local(outdir);
+    const quote = (arg) => /^[\w./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`;
+    const worker = `${output}/worker`;
+    const assetsFlag = assets !== undefined && resolve(assets) !== resolve(outdir, "client") ? ` --assets ${quote(assets)}` : "";
+    const keys = {
+        main: `${worker}/${basename(entry).replace(/\.[^.]+$/, "")}.js`, no_bundle: true,
+        find_additional_modules: true, base_dir: worker,
+        rules: [{ type: "ESModule", globs: ["**/*.js"], fallthrough: true }],
+        build: { command: `mantle bundle ${quote(entry)} ${quote(outdir)}${assetsFlag}`, watch_dir: [local(dirname(entry)), local(generated)] },
+    };
+    if (configPath.endsWith(".toml")) {
+        if (check)
+            throw new Error("--check requires a JSON or JSONC Wrangler config; TOML generation only prints manual edits.");
+        console.log(`Leave ${configPath} unchanged. Add these Wrangler TOML keys (include nodejs_compat and global_fetch_strictly_public in every compatibility_flags override):\n` +
+            `main = ${JSON.stringify(keys.main)}\nno_bundle = true\nfind_additional_modules = true\nbase_dir = ${JSON.stringify(worker)}\ncompatibility_flags = ${JSON.stringify(requiredFlags)}\n\n` +
+            (assets === undefined ? "" : `[assets]\ndirectory = ${JSON.stringify(local(assets))}\nbinding = "ASSETS"\nrun_worker_first = true\nhtml_handling = "none"\n\n`) +
+            `[[rules]]\ntype = "ESModule"\nglobs = ["**/*.js"]\nfallthrough = true\n\n[build]\ncommand = ${JSON.stringify(keys.build.command)}\nwatch_dir = ${JSON.stringify(keys.build.watch_dir)}`);
+        return false;
+    }
+    const exists = existsSync(configPath);
+    const original = exists ? readFileSync(configPath, "utf8") : JSON.stringify({ name: "your-worker-name", compatibility_date: compatibilityDate(configDir) }, null, 2) + "\n";
+    let text = original;
+    const errors = [];
+    const config = parse(text, errors, { allowTrailingComma: true });
+    if (errors.length || !config || typeof config !== "object" || Array.isArray(config))
+        throw new Error(`${configPath} must be a valid JSONC object.`);
+    const indent = text.match(/\n([ \t]+)"/)?.[1] ?? "  ";
+    const formattingOptions = { insertSpaces: !indent.includes("\t"), tabSize: indent.length, eol: text.includes("\r\n") ? "\r\n" : "\n" };
+    // Merge, never replace: the user's own module rules and build options survive.
+    const { rules: [rule], build: buildKeys, ...top } = keys;
+    const edit = (path, value) => {
+        if (!isDeepStrictEqual(path.reduce((v, k) => v?.[k], config), value))
+            text = applyEdits(text, modify(text, path, value, { formattingOptions }));
+    };
+    // Public routing is the default; an explicit private origin remains app-owned without OAuth/CIMD.
+    const ensureFlags = (path, flags) => {
+        if (flags !== undefined && (!Array.isArray(flags) || !flags.every(flag => typeof flag === "string")))
+            throw new Error(`${configPath}: ${path.join(".")} must be an array of strings.`);
+        const privateFetch = Array.isArray(flags) && flags.includes("global_fetch_private_origin");
+        if (privateFetch && (publicFetchRequired || flags.includes("global_fetch_strictly_public")))
+            throw new Error(`${configPath}: ${path.join(".")} includes global_fetch_private_origin, which conflicts with public OAuth/CIMD fetch routing. Remove it and use global_fetch_strictly_public.`);
+        const required = privateFetch ? ["nodejs_compat"] : requiredFlags;
+        if (flags === undefined)
+            edit(path, required);
+        else
+            for (const flag of required)
+                if (!flags.includes(flag))
+                    edit([...path, -1], flag);
+    };
+    ensureFlags(["compatibility_flags"], config.compatibility_flags);
+    // Wrangler environment arrays replace the top-level flags rather than inheriting them.
+    for (const [name, environment] of Object.entries(config.env ?? {})) {
+        if (environment?.compatibility_flags !== undefined)
+            ensureFlags(["env", name, "compatibility_flags"], environment.compatibility_flags);
+    }
+    for (const [key, value] of Object.entries(top))
+        edit([key], value);
+    for (const [key, value] of Object.entries(buildKeys))
+        edit(["build", key], value);
+    if (assets !== undefined) {
+        const wireAssets = (path, current) => {
+            edit([...path, "directory"], local(assets));
+            const ownsDefaults = current === undefined || current?.binding === undefined;
+            if (ownsDefaults && current?.binding === undefined)
+                edit([...path, "binding"], "ASSETS");
+            if (ownsDefaults && current?.run_worker_first === undefined)
+                edit([...path, "run_worker_first"], true);
+            // The shell fetches index.html itself; asset canonicalization would redirect it back to /admin/ forever.
+            if (current?.html_handling === undefined && (current?.run_worker_first === true || (ownsDefaults && current?.run_worker_first === undefined)))
+                edit([...path, "html_handling"], "none");
+        };
+        wireAssets(["assets"], config.assets);
+        for (const [name, environment] of Object.entries(config.env ?? {})) {
+            if (environment?.assets !== undefined)
+                wireAssets(["env", name, "assets"], environment.assets);
+        }
+    }
+    if (!(config.rules ?? []).some((r) => isDeepStrictEqual(r, rule)))
+        edit(config.rules === undefined ? ["rules"] : ["rules", -1], config.rules === undefined ? [rule] : rule);
+    const changed = !exists || text !== original;
+    if (changed && !check)
+        writeFileSync(configPath, text);
+    if (!exists && !check)
+        console.log(`Created ${configPath}. Set name and compatibility_date for your Worker, and add your D1/Hyperdrive bindings and other application settings.`);
+    return changed;
+}

package/dist/kernel/authorization.d.ts

@@ -0,0 +1,4 @@
+import { type Authorize, type Target, type Caller } from "./contracts.js";
+/** Rejections deny; synchronous application failures remain internal errors. */
+export declare function authorized(authorize: Authorize, target: Target, caller: Caller): Promise<boolean>;
+export declare function authorizeTarget(authorize: Authorize, target: Target, caller: Caller): Promise<void>;

package/dist/kernel/authorization.js

@@ -0,0 +1,16 @@
+import { ContractError } from "./contracts.js";
+/** Rejections deny; synchronous application failures remain internal errors. */
+export async function authorized(authorize, target, caller) {
+    let result;
+    try {
+        result = authorize(target, caller);
+    }
+    catch (cause) {
+        throw new Error("Authorization failed.", { cause });
+    }
+    return await Promise.resolve(result).catch(() => false) === true;
+}
+export async function authorizeTarget(authorize, target, caller) {
+    if (!await authorized(authorize, target, caller))
+        throw new ContractError("AUTH_DENIED", "Target is not authorized.", target.kind + "/" + target.name);
+}