@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/server/cli/config.js

@@ -0,0 +1,206 @@
+/**
+ * The config file at startup: its connections and services into the
+ * registry, and the sections beside them — views, saved SQL, pages, record
+ * layouts and app directories — read once, as the connections are. A config
+ * that exists but is wrong stops the start; a missing one is fine.
+ */
+import { startupReport } from '../../shared/refusal.js';
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { loadConfig } from '../connections.js';
+import { configLocations } from '../config/locations.js';
+import { parsePagesConfig } from '../../shared/page.js';
+import { parseLayoutsConfig } from '../../shared/recordview.js';
+import { parseViewsConfig } from '../../shared/view.js';
+import { parseQueriesConfig } from '../../shared/sqlsaved.js';
+import { product } from '../product.js';
+/* A name that reads like a credential. What a definition reads of the
+   environment can end up in what every browser is sent — a title, a link, a
+   query — so a password is refused unless the operator says, in so many
+   words, that the definition needs it. */
+const SECRET_LOOKING = /PASS|SECRET|TOKEN|KEY|CREDENTIAL|DATABASE_URL|^PG/i;
+/** One "apps" entry's `env`: names, or `{ "name": …, "secret": true }` for one that reads like a credential. */
+export function parseAppEnv(raw, where) {
+    if (!Array.isArray(raw))
+        throw new Error(`${where} "env" must be a list of environment variable names.`);
+    const seen = new Set();
+    return raw.map((entry) => {
+        const named = typeof entry === 'string' ? { name: entry } : entry && typeof entry === 'object' ? entry : {};
+        const name = typeof named.name === 'string' ? named.name.trim() : '';
+        const extra = Object.keys(named).filter((key) => key !== 'name' && key !== 'secret');
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name) || extra.length || (named.secret !== undefined && named.secret !== true)) {
+            throw new Error(`${where} "env" takes names ("REGION") or { "name": "API_KEY", "secret": true }, not ${JSON.stringify(entry)}.`);
+        }
+        if (seen.has(name))
+            throw new Error(`${where} "env" names ${name} twice.`);
+        seen.add(name);
+        if (SECRET_LOOKING.test(name) && named.secret !== true) {
+            throw new Error(`${where} "env" names ${name}, which reads like a credential. Whatever the App's definition does with it can reach ` +
+                `the browser; if the definition truly needs it, write { "name": "${name}", "secret": true }. See \`mistri docs secrets\`.`);
+        }
+        return named.secret === true ? { name, secret: true } : { name };
+    });
+}
+/**
+ * Whether the config file a start would read names Apps: read raw, before anything is said of it, so the database
+ * browser's main can hand a start that serves Apps to the App framework's without both reading the file aloud. The
+ * file is the one `loadConfig` would read; one it cannot parse is left for that to refuse.
+ */
+export async function configNamesApps(opts) {
+    if (opts.noConfig)
+        return false;
+    for (const path of configLocations(opts.config)) {
+        let text;
+        try {
+            text = await readFile(path, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        try {
+            return JSON.parse(text)?.apps !== undefined;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+/** `sections` may be a promise's maker, so a start that reads no config file (`--no-config`) never loads them. */
+export async function readStartupConfig(opts, registry, given) {
+    const read = { views: [], queries: [], pages: [], layouts: [], apps: [], appEnv: {} };
+    if (opts.noConfig)
+        return read;
+    const sections = typeof given === 'function' ? await given() : given;
+    try {
+        const config = await loadConfig(opts.config, sections);
+        if (config) {
+            // Remembered so "Save" writes back to the file this session was
+            // started from, rather than to whichever path happens to sort first.
+            read.configPath = config.path;
+            read.loadedConfigSignature = JSON.stringify(config);
+            read.loadedConfigText = await readFile(config.path, 'utf8');
+            for (const c of config.connections) {
+                registry.add({
+                    name: c.name,
+                    // Located against the file already (loadConfig); the spelling is kept for a save.
+                    url: c.url,
+                    ...(c.writtenUrl !== undefined ? { writtenUrl: c.writtenUrl } : {}),
+                    schemas: c.schemas,
+                    // Opt in, per connection. Absent means read-only, which is the
+                    // right default for a file someone may have copied from a
+                    // colleague without reading every line of.
+                    writable: c.writable === true,
+                    /* Opt *out*, per connection: the default is a normal connection,
+                       and `"rows": false` is someone deciding this database's rows
+                       must not leave the process. */
+                    rows: c.rows === false ? false : undefined,
+                    // Columns never served over it, checked by loadConfig.
+                    ...(c.hidden ? { hidden: c.hidden } : {}),
+                    // A PostgreSQL reader count, checked by loadConfig.
+                    pool: c.pool,
+                    // Read replicas' URLs, checked by loadConfig.
+                    ...(c.replicas ? { replicas: c.replicas } : {}),
+                    // A direct URL for LISTEN behind a pooler, checked by loadConfig.
+                    ...(c.listen ? { listen: c.listen } : {}),
+                    // An API's base URL, description and auth, checked by loadConfig.
+                    http: c.http,
+                    // Where its migrations are (tablewalk migrate), checked by loadConfig.
+                    ...(c.migrations ? { migrations: c.migrations } : {}),
+                    source: 'config',
+                });
+            }
+            // A cache and a search engine: services, not databases, opened when first used.
+            registry.sections = sections;
+            for (const service of config.services)
+                registry.addService(service);
+            for (const entry of config.kept ?? [])
+                registry.keep(entry);
+            const services = config.services.length ? `, plus ${config.services.map((s) => `${s.kind} "${s.name}"`).join(' and ')}` : '';
+            console.log(`${product()}: ${config.connections.length} connection(s)${services} from ${config.path}`);
+            /* DATABASE_URL is the default database of a start that names none. A
+               config that lists connections names them — usually "${DATABASE_URL}"
+               among them — and adding the variable as well opened the same database
+               a second time under a second name. The config wins; said when the
+               variable is not one of its connections, so nobody wonders which. */
+            if (opts.targetFromEnvironment && config.connections.length) {
+                opts.target = '';
+                opts.targetFromEnvironment = false;
+                if (!config.connections.some((c) => typeof c.url === 'string' && /\$(?:\{DATABASE_URL\}|DATABASE_URL(?!\w))/.test(c.url))) {
+                    read.environmentTargetNote =
+                        `DATABASE_URL is set, and ${config.path} names the connections, so it is not used; ` +
+                            'write "${DATABASE_URL}" as a connection\'s url to use it.';
+                    console.log(`${product()}: ${read.environmentTargetNote}`);
+                }
+            }
+            /* Re-read rather than widening `loadConfig`'s return: connections are
+               the file's reason to exist and views are a second, independent
+               section of it. One extra read of a small file at startup buys the
+               connection loader staying exactly as it was. */
+            read.views = parseViewsConfig(JSON.parse(await readFile(config.path, 'utf8')), config.path);
+            if (read.views.length) {
+                console.log(`${product()}: ${read.views.length} view(s) from ${config.path}`);
+            }
+            read.queries = parseQueriesConfig(JSON.parse(await readFile(config.path, 'utf8')), config.path);
+            if (read.queries.length) {
+                console.log(`${product()}: ${read.queries.length} saved SQL statement(s) from ${config.path}`);
+            }
+            read.pages = parsePagesConfig(JSON.parse(await readFile(config.path, 'utf8')), config.path);
+            if (read.pages.length) {
+                console.log(`${product()}: ${read.pages.length} page(s) from ${config.path}`);
+            }
+            read.layouts = parseLayoutsConfig(JSON.parse(await readFile(config.path, 'utf8')), config.path);
+            if (read.layouts.length) {
+                console.log(`${product()}: ${read.layouts.length} record layout(s) from ${config.path}`);
+            }
+            /* "apps": [dir | { "dir": dir, "env": [name, …] }, …] — directories,
+               resolved against the config file's own location: the file travels,
+               and a path written next to it should keep pointing at the thing
+               next to it. `env` is what that App's definition may read of the
+               environment; nothing else reaches it (apps.ts, importFresh). */
+            const rawApps = JSON.parse(await readFile(config.path, 'utf8')).apps;
+            if (rawApps !== undefined) {
+                const entries = Array.isArray(rawApps) ? rawApps : [undefined];
+                read.apps = entries.map((entry, i) => {
+                    const dir = typeof entry === 'string'
+                        ? entry
+                        : entry && typeof entry === 'object' && !Array.isArray(entry)
+                            ? entry.dir
+                            : undefined;
+                    const extra = entry && typeof entry === 'object' ? Object.keys(entry).filter((key) => key !== 'dir' && key !== 'env') : [];
+                    if (typeof dir !== 'string' || !dir.trim() || extra.length) {
+                        throw new Error(`${config.path}: "apps" must be a list of app directory paths, or { "dir": …, "env": [names] }.`);
+                    }
+                    const resolved = resolve(dirname(config.path), dir.trim());
+                    const env = entry.env;
+                    if (typeof entry === 'object' && env !== undefined)
+                        read.appEnv[resolved] = parseAppEnv(env, `${config.path}: apps[${i}]`);
+                    return resolved;
+                });
+            }
+            /* Where the Apps are served, beside which Apps: a deployment's fact,
+               checked with the flags' own rule once the Apps are loaded (main). */
+            const { mount, basePath } = JSON.parse(await readFile(config.path, 'utf8'));
+            if (mount !== undefined) {
+                if (!mount || typeof mount !== 'object' || Array.isArray(mount) || Object.values(mount).some((at) => typeof at !== 'string')) {
+                    throw new Error(`${config.path}: "mount" must name each App's place by its id, like { "main": "/", "billing": "/billing" }.`);
+                }
+                read.mount = mount;
+            }
+            if (basePath !== undefined) {
+                if (typeof basePath !== 'string')
+                    throw new Error(`${config.path}: "basePath" must be a path, like "/tools".`);
+                read.basePath = basePath;
+            }
+        }
+    }
+    catch (err) {
+        // A config that exists but is wrong is reported, never skipped:
+        // silently ignoring a file someone wrote is worse than refusing.
+        console.error(`Config error: ${startupReport(err)}`);
+        if (opts.embedded)
+            throw err;
+        process.exit(1);
+    }
+    return read;
+}

package/dist/server/cli/startup.d.ts

@@ -0,0 +1,36 @@
+import { type Options } from './args.js';
+/** A main: what a binary runs (bin.ts). Each binary has one, and a start that is the other's is refused by name. */
+export type Main = () => Promise<void>;
+/**
+ * The binary a start is answered by, in its own words: the name every line it says starts with, its usage (`--help
+ * all`) and first screen (`--help`), and the command and flag words a near miss is matched against.
+ */
+export interface Product {
+    readonly bin: 'tablewalk' | 'mistri';
+    readonly usage: string;
+    readonly shortUsage: string;
+    readonly commandWords: readonly string[];
+    readonly flagWords: readonly string[];
+}
+/**
+ * `--help`, `--version`, a retired spelling, an unknown flag, a command one slip away: answered before anything
+ * else, and before any of it can start a server. True when answered.
+ *
+ * None of the first two was handled once. `--help` and `--version` were ignored and then rescued by the "nothing
+ * to open" gate, which printed the usage and exited 1 — the right text, the wrong exit code, and only ever by
+ * accident. Once a server started with no connection, the accident became `tablewalk --help` sitting on port 4111
+ * waiting for a browser.
+ */
+export declare function answeredFirst(opts: Options, product: Product): Promise<boolean>;
+/** The process's settings the flags make: the proxies whose addresses it believes, and its pools. Exits on a bad one. */
+export declare function configureProcess(opts: Options, bin: Product['bin']): void;
+/** The formats of `--export` the database browser prints (databaseOneShot.ts); the rest are an App's. */
+export declare const SCHEMA_EXPORTS: ReadonlySet<string>;
+/**
+ * Which product a start is the business of, on its flags alone: the App framework's when any flag names an App,
+ * serves or checks its API, scaffolds one or watches it; else the database browser's modes (`--mcp`, `--lint`,
+ * `--diff`, the schema in words); else neither yet — a server, which is the App framework's when the config file
+ * names Apps (configNamesApps). Both mains ask, and each refuses the other's start by the other's name: there is no
+ * handing over between the two binaries.
+ */
+export declare function startFor(opts: Options): 'browser' | 'mistri' | undefined;

package/dist/server/cli/startup.js

@@ -0,0 +1,128 @@
+/**
+ * What every start does before its mode, whichever binary runs it: the questions answered without starting
+ * anything (`--help`, `--version`, a typo), and the process's settings the flags make (the proxies it believes,
+ * its pools). Both mains call these (packages/tablewalk/src/server/cli/browserMain.ts,
+ * packages/mistri/src/server/cli/mistriMain.ts), each with its own words (`Product`), and each binary runs its own
+ * main (bin.ts).
+ */
+import { parseClientAddressPolicy, parseTrustedProxies } from '../http/trust.js';
+import { configureServerSettings } from '../../adapters/serverSettings.js';
+import { configurePostgresPools } from '../../adapters/postgresPool.js';
+import { configureLockTimeout, configureWriterPool } from '../../adapters/writeLanes.js';
+import { postgresPoolFlags, shutdownTimings } from './args.js';
+import { didYouMean, packageVersion } from './usage.js';
+import { envName } from '../product.js';
+/**
+ * `--help`, `--version`, a retired spelling, an unknown flag, a command one slip away: answered before anything
+ * else, and before any of it can start a server. True when answered.
+ *
+ * None of the first two was handled once. `--help` and `--version` were ignored and then rescued by the "nothing
+ * to open" gate, which printed the usage and exited 1 — the right text, the wrong exit code, and only ever by
+ * accident. Once a server started with no connection, the accident became `tablewalk --help` sitting on port 4111
+ * waiting for a browser.
+ */
+export async function answeredFirst(opts, product) {
+    const { bin } = product;
+    if (opts.help) {
+        console.log(opts.target === 'all' ? product.usage : product.shortUsage);
+        return true;
+    }
+    if (opts.version) {
+        console.log(await packageVersion());
+        return true;
+    }
+    if (opts.retired) {
+        console.error(`${bin}: ${opts.retired}`);
+        process.exit(1);
+    }
+    /* A typo is named with its near miss, and the help is one command away: the whole usage after it buried the one
+       line that said what was wrong. */
+    if (opts.unknown) {
+        const flag = opts.unknown.split(/[ =]/)[0];
+        console.error(`${bin}: unknown option "${opts.unknown}".${opts.unknown === flag ? await didYouMean(flag, product.flagWords) : ''} ${bin} --help lists the options.`);
+        process.exit(1);
+    }
+    /* A word that is no file and is one slip from a command (`tablewalk chek`) was opened as a SQLite file of that
+       name: a database that does not exist, said as a connection that would not open. */
+    if (opts.target && /^[a-z][a-z-]*$/.test(opts.target) && !product.commandWords.includes(opts.target)) {
+        const { existsSync } = await import('node:fs');
+        const near = existsSync(opts.target) ? '' : await didYouMean(opts.target, product.commandWords);
+        if (near) {
+            console.error(`${bin}: "${opts.target}" is not a command, and no file of that name is here.${near.replace('Did you mean ', `Did you mean ${bin} `)} ${bin} --help lists the commands.`);
+            process.exit(1);
+        }
+    }
+    return false;
+}
+/** The process's settings the flags make: the proxies whose addresses it believes, and its pools. Exits on a bad one. */
+export function configureProcess(opts, bin) {
+    const proxies = parseTrustedProxies(opts.trustProxy);
+    if (proxies.invalid.length) {
+        console.error(`${bin}: --trust-proxy takes an IPv4 or IPv6 address or CIDR range (172.17.0.1, 10.0.0.0/8, fd00::/8); ` +
+            `${proxies.invalid.map((entry) => `"${entry}"`).join(', ')} is not one. It comes from the flag or ${envName('TRUST_PROXY')}.`);
+        process.exit(1);
+    }
+    opts.trustedProxies = proxies.ranges;
+    const identity = parseTrustedProxies(opts.authProxyFrom);
+    if (identity.invalid.length) {
+        console.error(`${bin}: --auth-proxy-from takes an IPv4 or IPv6 address or CIDR range (10.0.0.7, fd00::7); ` +
+            `${identity.invalid.map((entry) => `"${entry}"`).join(', ')} is not one. It comes from the flag or ${envName('AUTH_PROXY_FROM')}.`);
+        process.exit(1);
+    }
+    opts.authProxies = identity.ranges;
+    const client = parseClientAddressPolicy({ hops: opts.trustProxyHops, cloudflare: opts.trustProxyCloudflare });
+    if ('error' in client) {
+        console.error(`${bin}: ${client.error}`);
+        process.exit(1);
+    }
+    // One server per process: its settings are the process's (adapters/serverSettings.ts).
+    configureServerSettings({ clientAddress: client.policy });
+    const timings = shutdownTimings(opts);
+    if (typeof timings === 'string') {
+        console.error(`${bin}: ${timings}`);
+        process.exit(1);
+    }
+    const pools = postgresPoolFlags(opts);
+    if (typeof pools === 'string') {
+        console.error(`${bin}: ${pools}`);
+        process.exit(1);
+    }
+    // Before anything opens a pool: the registry's, a tenant source's, the job host's.
+    configurePostgresPools(pools);
+    configureWriterPool(pools.writers);
+    configureLockTimeout(pools.lockTimeoutMs);
+}
+/** The formats of `--export` the database browser prints (databaseOneShot.ts); the rest are an App's. */
+export const SCHEMA_EXPORTS = new Set(['md', 'markdown', 'mermaid', 'json']);
+/**
+ * Which product a start is the business of, on its flags alone: the App framework's when any flag names an App,
+ * serves or checks its API, scaffolds one or watches it; else the database browser's modes (`--mcp`, `--lint`,
+ * `--diff`, the schema in words); else neither yet — a server, which is the App framework's when the config file
+ * names Apps (configNamesApps). Both mains ask, and each refuses the other's start by the other's name: there is no
+ * handing over between the two binaries.
+ */
+export function startFor(opts) {
+    if (opts.appMcp ||
+        opts.checkApp ||
+        opts.apiReads ||
+        opts.apiIntegers !== undefined ||
+        opts.apiRequestsPerMinute !== undefined ||
+        opts.apps?.length ||
+        opts.appEntry !== undefined ||
+        opts.commands !== undefined ||
+        opts.jobs !== undefined ||
+        opts.policy !== undefined ||
+        opts.writeAuthority ||
+        opts.bump ||
+        opts.reindex !== undefined ||
+        opts.scaffoldApp !== undefined ||
+        opts.dev ||
+        opts.fromOpenapi !== undefined ||
+        (opts.export !== undefined && !SCHEMA_EXPORTS.has(opts.export.toLowerCase())) ||
+        opts.mounts !== undefined ||
+        opts.embedded)
+        return 'mistri';
+    if (opts.mcp || opts.lint || opts.diff || opts.export !== undefined)
+        return 'browser';
+    return undefined;
+}

package/dist/server/cli/startupOptions.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The API modes' own flags, checked before anything is read or loaded.
+ *
+ * Kept apart from the modes themselves (`api-read-startup-options.ts`,
+ * `appMcpMode.ts`) because `main` asks these questions on every start, and
+ * the modes import the auth store, the API owners and the tenant host: a
+ * check that lived beside them made `--help` and `--mcp` load all of that to
+ * learn that no API flag was given. This module imports nothing but types.
+ */
+import type { Options } from './args.js';
+import type { ProxyRange } from '../http/trust.js';
+export declare const APP_MCP_TOKEN_VARIABLE = "MISTRI_API_TOKEN";
+/** `--api-reads` and the flags that only mean something with it or an export. */
+export declare function apiReadStartupOptions(opts: Options): Readonly<{
+    integers: 'decimal-string' | 'number';
+    requestsPerMinute: number;
+    network?: true | undefined;
+}> | undefined;
+/** The startup line for a served App API: where it answers, to whom, and at
+ * what rate — said where the operator is looking, so a network exposure is
+ * never a surprise. */
+export declare function apiServingLine(app: Readonly<{
+    name: string;
+    id: string;
+    api?: Readonly<{
+        version: number;
+    }>;
+}>, api: Readonly<{
+    requestsPerMinute: number;
+    network?: true;
+}>, tenant?: boolean): string;
+/**
+ * What a listener beyond loopback exposes, said once it listens. The Workbench, or an App that signs no one in,
+ * reads the database for whoever reaches the port; an App that signs people in reads for a signed-out visitor only
+ * what its `auth.public` opens, so the warning that "anyone can read the database" was not true of it (OP8).
+ * Behind `--auth-proxy-header` a request from beyond loopback must carry the proxy's identity, so nobody is read for
+ * without one and the warning would be false; without it, the warning names the three ways out, because the Docker
+ * image binds 0.0.0.0 by default and the person who started it never typed a host (SSRF-4).
+ */
+export declare function exposureLines(host: string, apps: ReadonlyArray<Readonly<{
+    name: string;
+    auth?: Readonly<{
+        public?: Readonly<{
+            read: readonly string[];
+        }>;
+    }>;
+}>>, authProxyHeader?: string): string[];
+/**
+ * Who may set `--auth-proxy-header`, said once it listens: loopback and the `--auth-proxy-from` peers, nobody else
+ * (`identityFor`); `--trust-proxy` is a different question (which client) and never answers this one. A server beyond
+ * loopback with no peer listed believes the header only from this machine, so a proxy on another one has every request
+ * refused; that is said at start rather than learned from the first refusal. A range wider than one host is warned
+ * about, not refused: it is sometimes the only address a proxy has, but every peer in it can then name the person.
+ */
+export declare function proxyIdentityLines(host: string, header: string | undefined, from?: readonly ProxyRange[]): string[];
+/** `--app-mcp`'s own flags. */
+export declare function appMcpStartupOptions(opts: Options): Readonly<{
+    integers: 'decimal-string' | 'number';
+}> | undefined;
+/** Taken once and removed from the environment before any App or command code
+ * loads, so neither can find it there and no child process inherits it.
+ * Never echoed: the message names the variable, not its value. */
+export declare function readAppMcpToken(env: NodeJS.ProcessEnv): string;

package/dist/server/cli/startupOptions.js

@@ -0,0 +1,143 @@
+import { product } from '../product.js';
+export const APP_MCP_TOKEN_VARIABLE = 'MISTRI_API_TOKEN';
+/** `--api-reads` and the flags that only mean something with it or an export. */
+export function apiReadStartupOptions(opts) {
+    const exporting = ['openapi', 'asyncapi'].includes(opts.export?.toLowerCase() ?? '');
+    if (!opts.apiReads) {
+        if (opts.apiRequestsPerMinute !== undefined)
+            throw new Error('--api-requests-per-minute requires --api-reads.');
+        if (exporting || opts.appMcp ? !['decimal-string', 'number'].includes(opts.apiIntegers ?? '') : opts.apiIntegers !== undefined) {
+            throw new Error('--api-integers decimal-string or number is required with --export openapi or asyncapi, --api-reads or --app-mcp, and only valid with those modes.');
+        }
+        return undefined;
+    }
+    if (!['decimal-string', 'number'].includes(opts.apiIntegers ?? '') ||
+        !/^[1-9][0-9]*(?![\s\S])/.test(opts.apiRequestsPerMinute ?? '') ||
+        Number(opts.apiRequestsPerMinute) > 1000000)
+        throw new Error('--api-reads requires explicit --api-integers and --api-requests-per-minute (1–1000000).');
+    if (opts.export !== undefined ||
+        opts.fromOpenapi !== undefined ||
+        opts.openapi !== undefined ||
+        opts.mcp ||
+        opts.appMcp ||
+        opts.lint !== undefined ||
+        opts.diff !== undefined ||
+        opts.scaffoldApp !== undefined ||
+        opts.checkApp ||
+        opts.writeAuthority ||
+        opts.reindex !== undefined ||
+        opts.demo) {
+        throw new Error('--api-reads cannot be combined with one-shot, import, MCP or demo modes.');
+    }
+    // A client address read from an arbitrary header could be anyone's: the
+    // per-address budget trusts only X-Forwarded-For from a --trust-proxy peer.
+    if (opts.authProxyHeader)
+        throw new Error('--api-reads cannot be combined with --auth-proxy-header.');
+    /* Listening beyond loopback — another interface, a name other than this
+       machine's, or behind a proxy — is the operator's half of the network
+       opt-in; the App's `api.network: true` is the other, checked once the App
+       is loaded (assertApiReadStartupComposition). */
+    const network = !['127.0.0.1', 'localhost', '::1', '::ffff:127.0.0.1'].includes(opts.host) ||
+        opts.allowedHosts.length > 0 ||
+        opts.trustProxy.length > 0 ||
+        opts.trustProxyHops !== undefined ||
+        opts.trustProxyCloudflare ||
+        (opts.trustedProxies?.length ?? 0) > 0;
+    return Object.freeze({
+        integers: opts.apiIntegers,
+        requestsPerMinute: Number(opts.apiRequestsPerMinute),
+        ...(network ? { network: true } : {}),
+    });
+}
+/** The startup line for a served App API: where it answers, to whom, and at
+ * what rate — said where the operator is looking, so a network exposure is
+ * never a surprise. */
+export function apiServingLine(app, api, tenant = false) {
+    const at = `/api/apps/${app.id}/v${app.api?.version ?? 1}`;
+    return (`${product()}: "${app.name}" API at ${at} (MCP at ${at}/$mcp) ` +
+        (api.network ? 'beyond loopback' : 'on loopback') +
+        `: scoped bearer tokens only${tenant ? ', each bound to one membership' : ''}; ` +
+        `${api.requestsPerMinute} requests a minute per token, counted in this process` +
+        (api.network ? '. Terminate TLS in front of it.' : '.'));
+}
+/**
+ * What a listener beyond loopback exposes, said once it listens. The Workbench, or an App that signs no one in,
+ * reads the database for whoever reaches the port; an App that signs people in reads for a signed-out visitor only
+ * what its `auth.public` opens, so the warning that "anyone can read the database" was not true of it (OP8).
+ * Behind `--auth-proxy-header` a request from beyond loopback must carry the proxy's identity, so nobody is read for
+ * without one and the warning would be false; without it, the warning names the three ways out, because the Docker
+ * image binds 0.0.0.0 by default and the person who started it never typed a host (SSRF-4).
+ */
+export function exposureLines(host, apps, authProxyHeader) {
+    if (/^(localhost|127\.0\.0\.1|::1)$/i.test(host))
+        return [];
+    if (authProxyHeader)
+        return [];
+    const remedy = 'Bind --host 127.0.0.1, put it behind a proxy that signs people in (--auth-proxy-header), or give the App sign-in.';
+    if (!apps.length)
+        return [`Warning: bound to ${host}, beyond loopback, with no sign-in. Anyone who can reach this port can read the database. ${remedy}`];
+    return apps.map((app) => !app.auth
+        ? `Warning: bound to ${host}, beyond loopback, and "${app.name}" signs no one in: anyone who can reach this port reads what it shows. ${remedy}`
+        : app.auth.public?.read.length
+            ? `${product()}: bound beyond loopback; "${app.name}" signs people in, and a signed-out visitor reads only what auth.public opens (${app.auth.public.read.join(', ')}) and its public forms show.`
+            : `${product()}: bound beyond loopback; "${app.name}" signs people in, and a signed-out visitor reads nothing but what its public forms show.`);
+}
+/**
+ * Who may set `--auth-proxy-header`, said once it listens: loopback and the `--auth-proxy-from` peers, nobody else
+ * (`identityFor`); `--trust-proxy` is a different question (which client) and never answers this one. A server beyond
+ * loopback with no peer listed believes the header only from this machine, so a proxy on another one has every request
+ * refused; that is said at start rather than learned from the first refusal. A range wider than one host is warned
+ * about, not refused: it is sometimes the only address a proxy has, but every peer in it can then name the person.
+ */
+export function proxyIdentityLines(host, header, from = []) {
+    if (!header)
+        return [];
+    const source = from.length ? `loopback and ${from.map((range) => range.text).join(', ')}` : 'loopback only';
+    const lines = [`${product()}: trusting ${header} for who is asking, from ${source}; a request from anywhere else is refused`];
+    if (!from.length && !/^(localhost|127\.0\.0\.1|::1)$/i.test(host))
+        lines.push(`Warning: bound to ${host} with --auth-proxy-header and no --auth-proxy-from: a proxy on another machine is refused on every request. Name its address with --auth-proxy-from.`);
+    /* IPv4 is held mapped (parseTrustedProxies), so /32 is 128 and a single host is 128 in both families.
+       This module imports types only, so the test is here rather than a helper in trust.ts. */
+    const wide = from.filter((range) => range.prefix < 128);
+    if (wide.length)
+        lines.push(`Warning: --auth-proxy-from ${wide.map((range) => range.text).join(', ')} is wider than one host: every peer in it can assert who is signed in through ${header}. Name the proxy's own address.`);
+    return lines;
+}
+/** `--app-mcp`'s own flags. */
+export function appMcpStartupOptions(opts) {
+    if (!opts.appMcp)
+        return undefined;
+    if (opts.apiReads ||
+        opts.apiRequestsPerMinute !== undefined ||
+        opts.mcp ||
+        opts.export !== undefined ||
+        opts.fromOpenapi !== undefined ||
+        opts.openapi !== undefined ||
+        opts.lint !== undefined ||
+        opts.diff !== undefined ||
+        opts.scaffoldApp !== undefined ||
+        opts.checkApp ||
+        opts.writeAuthority ||
+        opts.reindex !== undefined ||
+        opts.demo ||
+        opts.jobs !== undefined ||
+        opts.open ||
+        opts.portGiven) {
+        throw new Error('--app-mcp has no listener: it cannot be combined with --api-reads, --mcp, --jobs, --port, --open, or an import, one-shot or demo mode.');
+    }
+    if (!['decimal-string', 'number'].includes(opts.apiIntegers ?? ''))
+        throw new Error('--app-mcp requires explicit --api-integers decimal-string or number.');
+    return Object.freeze({ integers: opts.apiIntegers });
+}
+/** Taken once and removed from the environment before any App or command code
+ * loads, so neither can find it there and no child process inherits it.
+ * Never echoed: the message names the variable, not its value. */
+export function readAppMcpToken(env) {
+    const value = env[APP_MCP_TOKEN_VARIABLE];
+    delete env[APP_MCP_TOKEN_VARIABLE];
+    // Shape only; whether it is a token at all is the owners' decision, per call.
+    if (typeof value !== 'string' || !value || value.length > 4096 || /[\s\p{Cc}]/u.test(value)) {
+        throw new Error(`--app-mcp reads the App API token from ${APP_MCP_TOKEN_VARIABLE}; set it to a token from mistri api-token issue.`);
+    }
+    return value;
+}

package/dist/server/cli/subcommand.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A word of the command line that is a command of its own (`tablewalk migrate`, `mistri tenant`), not a
+ * database to open, and the one way each main runs one.
+ *
+ * Each main has a table of them (cli/browserCommands.ts, cli/mistriCommands.ts). They were some twenty-five
+ * copied blocks in one `main`, and they failed two ways: some caught a throw and said `tablewalk: …` with exit 1,
+ * the rest let it escape as a stack trace. `runSubcommand` is the one way now: a command returns its exit code,
+ * and whatever it throws is said in a line, exit 1.
+ *
+ * A command is read before the flags are, since parseArgs would take its word for a SQLite file, and nothing a
+ * start reads — a config, a connection, a server — is its business. A file of that name is still `./migrate`.
+ */
+interface Subcommand {
+    /**
+     * Whether these arguments (the ones after the word) are this command's. Absent, the word alone is enough; a
+     * word that is a command only with a second word (`theme show`) or a flag (`new --api`) leaves the rest to the
+     * start, which opens a SQLite file of that name.
+     */
+    takes?(argv: readonly string[]): boolean;
+    /** The arguments after the word; the exit code, or nothing for 0. */
+    run(argv: string[]): Promise<number | void> | number | void;
+}
+export type Subcommands = Readonly<Record<string, Subcommand>>;
+/** The command `argv` (the process's arguments after the script) names in `table`, or nothing. */
+export declare function subcommandIn(table: Subcommands, argv: readonly string[]): Subcommand | undefined;
+/** Runs one, as every main does: its exit code on the process, a throw said in a line, under the binary's name, with exit 1. */
+export declare function runSubcommand(command: Subcommand, argv: string[], bin: 'tablewalk' | 'mistri'): Promise<void>;
+export {};

package/dist/server/cli/subcommand.js

@@ -0,0 +1,32 @@
+/**
+ * A word of the command line that is a command of its own (`tablewalk migrate`, `mistri tenant`), not a
+ * database to open, and the one way each main runs one.
+ *
+ * Each main has a table of them (cli/browserCommands.ts, cli/mistriCommands.ts). They were some twenty-five
+ * copied blocks in one `main`, and they failed two ways: some caught a throw and said `tablewalk: …` with exit 1,
+ * the rest let it escape as a stack trace. `runSubcommand` is the one way now: a command returns its exit code,
+ * and whatever it throws is said in a line, exit 1.
+ *
+ * A command is read before the flags are, since parseArgs would take its word for a SQLite file, and nothing a
+ * start reads — a config, a connection, a server — is its business. A file of that name is still `./migrate`.
+ */
+/** The command `argv` (the process's arguments after the script) names in `table`, or nothing. */
+export function subcommandIn(table, argv) {
+    const word = argv[0];
+    if (word === undefined || !Object.hasOwn(table, word))
+        return undefined;
+    const command = table[word];
+    return !command.takes || command.takes(argv.slice(1)) ? command : undefined;
+}
+/** Runs one, as every main does: its exit code on the process, a throw said in a line, under the binary's name, with exit 1. */
+export async function runSubcommand(command, argv, bin) {
+    try {
+        const code = await command.run(argv);
+        if (typeof code === 'number')
+            process.exitCode = code;
+    }
+    catch (error) {
+        console.error(`${bin}: ${error.message}`);
+        process.exitCode = 1;
+    }
+}

package/dist/server/cli/usage.d.ts

@@ -0,0 +1,13 @@
+/**
+ * What both command lines share about their words: the near miss a typo is told, the version, and how a usage text
+ * is read for its command and flag words. Each binary keeps its own `USAGE` (packages/tablewalk/src/server/cli/usage.ts,
+ * packages/mistri/src/server/cli/usage.ts), and test/prose.test.ts holds each one to its own README.
+ */
+/** The command words a usage names (`tablewalk migrate`, `mistri check`, …), for a near miss's suggestion. */
+export declare function commandWordsOf(usage: string, bin: string): string[];
+/** Every flag a usage spells, for an unknown option's suggestion. */
+export declare function flagWordsOf(usage: string): string[];
+/** What was probably meant, said the way a person would type it, or nothing when nothing is near. */
+export declare function didYouMean(said: string, among: readonly string[]): Promise<string>;
+/** What the package says it is, best effort. Every package of the workspace carries the one version. */
+export declare function packageVersion(): Promise<string>;