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

package/dist/infrastructure/cli.js

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, resolve, relative } from "node:path";
+import { pathToFileURL } from "node:url";
+import { parseArgs } from "node:util";
+import { configureWrangler } from "./wrangler.js";
+import { writeArtifacts } from "./artifacts.js";
+import { INPUTS_FILE, inputsFingerprint } from "./inputs.js";
+async function load(path) {
+    try {
+        return await import(pathToFileURL(resolve(path)).href);
+    }
+    catch (error) {
+        if (error.code === "ERR_UNKNOWN_FILE_EXTENSION")
+            throw new Error(`Cannot load ${path}: Node ${process.versions.node} does not run TypeScript. Use Node 22.22 or later, as the package engines say.`);
+        throw error;
+    }
+}
+const targets = ["bun-sqlite", "bun-postgres", "cloudflare-d1", "cloudflare-postgres"];
+const usage = "Usage: mantle help [topic]   (start here: the installed docs, one topic at a time)\n       mantle init [directory] [--dry-run]\n       mantle generate <target> <output-directory> <manifest>... [--check] [--admin] [--site <module>] [--auth <module>]... (one per Better Auth instance) [--wrangler <path>] [--entry <worker entry>] [--outdir <bundle directory>] [--assets <static assets directory>]\n       mantle bundle <entry> <outdir> [--assets <static assets directory>]\n       mantle describe <target> <manifest>... [--diff <old.json>]";
+try {
+    const { values, positionals } = parseArgs({ allowPositionals: true, options: {
+            diff: { type: "string" }, check: { type: "boolean" }, admin: { type: "boolean" }, site: { type: "string" }, auth: { type: "string", multiple: true }, wrangler: { type: "string" }, entry: { type: "string", default: "src/worker.ts" }, outdir: { type: "string", default: "dist" }, assets: { type: "string" }, "dry-run": { type: "boolean" }, help: { type: "boolean", short: "h" },
+        } });
+    const named = ["bundle", "generate", "describe", "help", "init"].includes(positionals[0]) ? positionals.shift() : undefined;
+    const command = values.help ? "usage" : named ?? (process.argv.length > 2 ? "generate" : "help");
+    if (command === "usage")
+        console.log(`${usage}\n\nStart with mantle help: the installed docs, one topic at a time.`);
+    else if (command === "help") {
+        const { help, topicList } = await import("./help.js");
+        if (positionals.length > 1)
+            throw new Error(usage);
+        console.log(positionals[0] === "topics" ? topicList() : help(positionals[0]));
+    }
+    else if (command === "init") {
+        if (positionals.length > 1)
+            throw new Error(usage);
+        console.log((await import("./init.js")).init(positionals[0] ?? ".", values["dry-run"]));
+    }
+    else if (command === "describe") {
+        const target = positionals.shift();
+        if (!target || !targets.includes(target) || !positionals.length)
+            throw new Error(usage);
+        const { compilePlan, sqliteCompiler, postgresCompiler } = await import("../build/compiler.js");
+        const { describeApp, diffApp } = await import("../domain/describe/index.js");
+        const sources = await Promise.all(positionals.map(async (path) => ({ sourceId: path, text: await readFile(path, "utf8") })));
+        const compiled = await compilePlan({ sources }, target.endsWith("postgres") ? postgresCompiler : sqliteCompiler, "operational");
+        if (!compiled.ok)
+            throw new Error(JSON.stringify(compiled.diagnostics, null, 2));
+        const report = await describeApp(compiled.plan);
+        if (values.diff) {
+            const changes = diffApp(JSON.parse(await readFile(values.diff, "utf8")), report);
+            console.log(JSON.stringify(changes, null, 2));
+        }
+        else
+            console.log(JSON.stringify(report, null, 2));
+    }
+    else if (command === "bundle") {
+        const [entry, outdir] = positionals;
+        if (!entry || !outdir || positionals.length !== 2 || values.admin || values.site || values.auth || values.wrangler || values.check)
+            throw new Error(usage);
+        await (await import("./bundle.js")).bundleApp(entry, outdir, values.assets);
+    }
+    else {
+        const [target, destination, ...paths] = positionals;
+        if (!target || !targets.includes(target) || !destination || !paths.length)
+            throw new Error(usage);
+        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") })));
+        const auth = await Promise.all((values.auth ?? []).map(async (path) => {
+            const loaded = await load(path);
+            const options = loaded.authOptions?.(new Proxy({}, { get: () => undefined })) ?? loaded.auth?.options;
+            if (!options)
+                throw new Error(`${path} must export \`authOptions(env)\` (or \`auth\`, a betterAuth() instance).`);
+            return options;
+        }));
+        const site = values.site ? (await load(values.site)).siteDefaults : undefined;
+        if (values.site && !site)
+            throw new Error(`${values.site} must export siteDefaults.`);
+        const { generateFromSources } = await (auth.length ? import("./generateAuth.js") : import("./generate.js"));
+        const result = await generateFromSources({ target: target, sources: { sources }, admin: values.admin, auth, site });
+        if (!result.ok)
+            throw new Error(JSON.stringify(result.diagnostics, null, 2));
+        for (const warning of result.warnings ?? [])
+            console.warn(`warning: ${warning}`);
+        const read = [...paths, ...(values.auth ?? []), ...(values.site ? [values.site] : [])];
+        const changed = await writeArtifacts(destination, { ...result.files, [INPUTS_FILE]: inputsFingerprint(destination, read, target) }, values.check);
+        for (const warning of await (await import("./mounts.js")).unmountedWarnings(values.entry, destination, result.files))
+            console.warn(`warning: ${warning}`);
+        if (target.startsWith("cloudflare-")) {
+            const wrangler = values.wrangler ?? ["wrangler.jsonc", "wrangler.json", "wrangler.toml"].find(existsSync) ?? "wrangler.jsonc";
+            const assets = values.admin ? values.assets ?? join(values.outdir, "client") : undefined;
+            const publicFetchRequired = auth.some(options => options.plugins?.some((plugin) => plugin.id === "oauth-provider" || plugin.id === "cimd"));
+            if (configureWrangler(wrangler, values.entry, values.outdir, destination, values.check, assets, publicFetchRequired))
+                changed.push(wrangler);
+        }
+        if (values.check && changed.length)
+            throw new Error(`Generated output is stale. Run mantle generate with the same options:\n${changed.join("\n")}`);
+        if (!values.check)
+            console.log(`Commit generated output and Wrangler config edits; keep dist/ untracked. Add to .gitattributes: ${JSON.stringify(relative(process.cwd(), resolve(destination)).replaceAll("\\", "/") + "/**")} linguist-generated=true`);
+        if (!values.check && result.refProcedures.length)
+            console.log(`Ref Procedures need these Handlers keys (tsc --noEmit checks them; pass them at store(db, caller, { handlers })): ${result.refProcedures.map(name => JSON.stringify(name)).join(", ")}`);
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/dist/infrastructure/generate.d.ts

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

package/dist/infrastructure/generate.js

@@ -0,0 +1,175 @@
+import { describeApp } from "../domain/describe/index.js";
+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";
+export const coreNewId = (dialect, schemas) => dialect.print({ SelectStmt: { targetList: [{ ResTarget: { val: dialect.lowering.newId() } }], limitOption: "LIMIT_OPTION_DEFAULT", op: "SETOP_NONE" } }, schemas).replace(/^SELECT /, "");
+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 });
+}
+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 ?? []);
+        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.${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'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 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) {
+            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] };
+    }
+    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,66 @@
+import { generateFromSources as generate } from "./generate.js";
+import { admin, anonymous, jwt, phoneNumber, siwe, twoFactor } from "better-auth/plugins";
+import { authSchemaSql } from "./authSchema.js";
+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);
+        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)))];
+    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;
+}
+const sharedSchema = {
+    jwt: () => jwt().schema, admin: () => admin().schema, anonymous: () => anonymous().schema,
+    "phone-number": () => phoneNumber({}).schema, siwe: () => siwe({}).schema, "two-factor": () => twoFactor().schema,
+};
+const checkedPlugins = new Set([...Object.keys(sharedSchema), "device-authorization", "oauth-provider"]);
+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;
+}
+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,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

@@ -0,0 +1,32 @@
+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";
+const MANTLE_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+const digest = (path) => existsSync(path) ? createHash("sha256").update(readFileSync(path, "utf8").replaceAll("\r\n", "\n")).digest("hex") : null;
+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";
+}
+export function generatedTarget(generatedModule) {
+    const file = resolve(dirname(generatedModule), INPUTS_FILE);
+    return existsSync(file) ? JSON.parse(readFileSync(file, "utf8")).target : undefined;
+}
+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;
+}
+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");
+}
+export function authTableSql(source) {
+    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.`);
+}