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

package/dist/server/auth/credentials.js

@@ -0,0 +1,260 @@
+/**
+ * Where connection secrets live, and — more importantly — where they do not.
+ *
+ * The rule this file exists to enforce: **tablewalk does not invent its own
+ * secret storage.** Rolling encryption for a local dev tool means inventing a
+ * key-management scheme, and a key sitting next to the ciphertext it protects
+ * is obfuscation with extra steps. Every option below either delegates to
+ * something that already solves the problem (the OS keychain, the
+ * environment) or is explicit about being plaintext-on-disk with the same
+ * permission discipline ssh and psql use.
+ *
+ * Four ways to supply a password, in the order they are tried:
+ *
+ *   1. `${VAR}` in the URL, expanded from the environment. Nothing is stored.
+ *   2. The OS keychain, addressed by connection name. The secret never
+ *      touches a tablewalk file.
+ *   3. A credentials file at 0600, refused if the mode is wider.
+ *   4. Inline in the URL — supported because it is what people paste, and
+ *      warned about because it ends up in shell history and config files.
+ *
+ * Whatever the source, the resolved URL stays in the server process. The
+ * browser is only ever sent a redacted form; `redact` in connections.ts is
+ * the single point that produces it and there are tests asserting no password
+ * survives the trip.
+ */
+import { readFile, writeFile, chmod, mkdir, rename, rm } from 'node:fs/promises';
+import { statSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { dirname, join } from 'node:path';
+import { execFile, spawn } from 'node:child_process';
+import { promisify } from 'node:util';
+import { product } from '../product.js';
+const run = promisify(execFile);
+/** Where the credentials file lives when one is used at all. */
+export function credentialsPath() {
+    const xdg = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+    return join(xdg, product(), 'credentials.json');
+}
+/** The keychain service name: the product's, one namespace per product, addressed by connection name. */
+const keychainService = () => product();
+/* ---------- 1. environment expansion ---------- */
+/**
+ * Expand `${VAR}` and `$VAR` in a connection string.
+ *
+ * This is the recommended option, and the only one where the secret is never
+ * written anywhere tablewalk controls:
+ *
+ *   { "name": "prod", "url": "postgres://app:${PROD_DB_PASSWORD}@db/app" }
+ *
+ * An unset variable is an error rather than an empty expansion. Silently
+ * producing `postgres://app:@db/app` would send an empty password and fail
+ * with an authentication error that says nothing about the real cause.
+ */
+export function expandEnv(url, env = process.env) {
+    return url.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_, braced, bare) => environmentValue(braced ?? bare, env));
+}
+/**
+ * Expand only the `${NAME}` form. An authentication store URL is read this
+ * way, and it is the only form its documentation names: there a bare `$` is
+ * literal, so a password containing `$abc` is not mistaken for a reference
+ * to an unset variable (and refused) or, worse, to a set one.
+ */
+export function expandEnvReferences(url, env = process.env) {
+    return url.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => environmentValue(name, env));
+}
+function environmentValue(name, env) {
+    const value = env[name];
+    if (value === undefined) {
+        throw new Error(`Connection references $${name}, which is not set. Export it, or remove it from the connection.`);
+    }
+    return value;
+}
+/** True when a URL carries a literal password rather than a reference. */
+export function hasInlinePassword(url) {
+    try {
+        return Boolean(new URL(url).password);
+    }
+    catch {
+        return false;
+    }
+}
+/* ---------- 2. the OS keychain ---------- */
+/**
+ * Read a password from the platform keychain.
+ *
+ * macOS only for now, through the `security` binary that ships with the OS —
+ * no dependency, no native module, and the secret is protected by the same
+ * thing protecting everything else on the machine. Linux and Windows return
+ * undefined and fall through to the file, which is honest: claiming keychain
+ * support and quietly storing plaintext would be worse than not offering it.
+ */
+/* `MISTRI_NO_KEYCHAIN=1` pretends there is none: the test suite sets it
+   so `npm test` never writes to the developer's real keychain (and never
+   hangs on a locked one), and it is a way out for a macOS box whose
+   keychain is not the place a team keeps its passwords. */
+const keychainOff = () => process.env.MISTRI_NO_KEYCHAIN === '1';
+async function keychainGet(account) {
+    if (platform() !== 'darwin' || keychainOff())
+        return undefined;
+    try {
+        const { stdout } = await run('security', ['find-generic-password', '-s', keychainService(), '-a', account, '-w']);
+        return stdout.trim() || undefined;
+    }
+    catch {
+        // Not found, or the user declined the prompt: fall through to the file.
+        return undefined;
+    }
+}
+export async function keychainSet(account, secret) {
+    if (platform() !== 'darwin' || keychainOff())
+        return false;
+    try {
+        /* The secret goes in on stdin, to `security -i`, as hex: `-w <secret>` on the command line is visible to every
+           local user in `ps` for as long as the command runs, and `-w` with no value reads a tty, not a pipe. `-U`
+           updates in place rather than erroring when the item already exists. */
+        if (/[\0\r\n]/.test(account))
+            return false;
+        const quoted = (text) => `"${text.replace(/[\\"]/g, '\\$&')}"`;
+        const command = `add-generic-password -U -s ${quoted(keychainService())} -a ${quoted(account)} -X ${Buffer.from(secret, 'utf8').toString('hex')}\n`;
+        return await new Promise((done) => {
+            const child = spawn('security', ['-i'], { stdio: ['pipe', 'ignore', 'ignore'] });
+            child.once('error', () => done(false));
+            child.once('close', (code) => done(code === 0));
+            child.stdin.on('error', () => { });
+            child.stdin.end(command);
+        });
+    }
+    catch {
+        return false;
+    }
+}
+export async function keychainDelete(account) {
+    if (platform() !== 'darwin')
+        return;
+    try {
+        await run('security', ['delete-generic-password', '-s', keychainService(), '-a', account]);
+    }
+    catch {
+        /* Already gone. */
+    }
+}
+export const keychainAvailable = () => platform() === 'darwin';
+/**
+ * Read the credentials file, refusing it if anyone but the owner can read it.
+ *
+ * The permission check is the whole point. It is what `ssh` does to private
+ * keys and what `psql` does to `.pgpass`, and it catches the realistic
+ * mistake: a file created correctly, then committed, copied or synced with
+ * permissions that no longer match the intent. Refusing loudly is better than
+ * reading it and leaving the user believing it was safe.
+ */
+export async function readCredentials(path = credentialsPath()) {
+    let mode;
+    try {
+        mode = statSync(path).mode & 0o777;
+    }
+    catch (err) {
+        // No file is the normal case, not an error. Any other failure is: it must not read as "nothing saved".
+        if (err.code === 'ENOENT')
+            return {};
+        throw new Error(`${path} could not be read: ${err.message}`);
+    }
+    if (mode & 0o077) {
+        throw new Error(`${path} is readable by others (mode ${mode.toString(8)}). ` + `Run: chmod 600 ${path}`);
+    }
+    try {
+        const parsed = JSON.parse(await readFile(path, 'utf8'));
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed))
+            return parsed;
+        throw new Error('expected an object of name → password');
+    }
+    catch (err) {
+        throw new Error(`${path} could not be read: ${err.message}`);
+    }
+}
+export async function writeCredential(name, secret, path = credentialsPath()) {
+    /* A file that cannot be read (too wide a mode, a stray comma) refuses the write: rewriting it from nothing would
+       delete every other saved password, and the chmod after would hide the one sign that something was wrong. */
+    const existing = await readCredentials(path);
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    /* Written with the restrictive mode from the start rather than chmod-ed
+       afterwards — between a default-mode write and the chmod there is a window
+       where the secret is world-readable. Through a temporary file and a rename, so a crash cannot leave the
+       whole file half-written. */
+    const staged = `${path}.${process.pid}.tmp`;
+    try {
+        await writeFile(staged, `${JSON.stringify({ ...existing, [name]: secret }, null, 2)}\n`, { mode: 0o600 });
+        await chmod(staged, 0o600);
+        await rename(staged, path);
+    }
+    catch (err) {
+        await rm(staged, { force: true });
+        throw err;
+    }
+}
+/**
+ * Turn a stored connection into a usable URL.
+ *
+ * Order matters and is deliberate: the environment wins because it is the
+ * most explicit, then the keychain because it is the best-protected, then the
+ * file. An inline password is used as-is but reported, so the UI can say what
+ * it is doing rather than leaving the user to guess.
+ */
+export async function resolveConnection(name, storedUrl, options = {}) {
+    /* `secrets: false` resolves nothing: no environment expansion, no keychain,
+       no credentials file — the URL is used exactly as written, inline password
+       or none. It is the form for a URL that arrived over the network rather
+       than from this machine's config or command line. Every lookup here binds
+       a secret to a *name* or a *reference* the caller chose, so a caller who
+       is not the operator could name a connection "prod" and have the prod
+       password attached to a host of their choosing, or write `${AWS_SECRET}`
+       into a URL pointing at themselves. The server decides who the operator
+       is; this function only has to offer the switch. */
+    if (options.secrets === false) {
+        return { url: storedUrl, source: hasInlinePassword(storedUrl) ? 'inline' : 'none' };
+    }
+    // 1. Environment references, which may supply the whole URL or just part.
+    const expanded = expandEnv(storedUrl, options.environment);
+    const usedEnv = expanded !== storedUrl;
+    /* Anything with a host has a credential to resolve; a bare file path does
+       not. This tested for Postgres specifically, so any other networked
+       connection skipped the keychain and the credentials file entirely and
+       never warned about a password written into its URL. Asking whether the target *has a host* is the question that
+       was always meant, and it does not need editing again for the next
+       adapter. */
+    if (!/^[a-z][\w+.-]*:\/\//i.test(expanded)) {
+        // SQLite is a file path; there is no credential to resolve.
+        return { url: expanded, source: usedEnv ? 'environment' : 'none' };
+    }
+    if (hasInlinePassword(expanded)) {
+        return {
+            url: expanded,
+            source: usedEnv ? 'environment' : 'inline',
+            warning: usedEnv
+                ? undefined
+                : 'This connection has its password written into the URL. Prefer ${ENV_VAR}, or store it in the keychain.',
+        };
+    }
+    // 2 and 3: a URL with a user but no password can have one supplied.
+    let parsed;
+    try {
+        parsed = new URL(expanded);
+    }
+    catch {
+        return { url: expanded, source: 'none' };
+    }
+    const fromKeychain = await keychainGet(name);
+    if (fromKeychain) {
+        parsed.password = encodeURIComponent(fromKeychain);
+        return { url: parsed.toString(), source: 'keychain' };
+    }
+    const file = await readCredentials(options.credentialsFile);
+    if (file[name]) {
+        parsed.password = encodeURIComponent(file[name]);
+        return { url: parsed.toString(), source: 'file' };
+    }
+    // No password anywhere. Postgres may still accept it — peer auth, trust,
+    // or a ~/.pgpass the driver reads itself — so this is not an error.
+    return { url: expanded, source: 'none' };
+}

package/dist/server/cacheService.d.ts

@@ -0,0 +1,50 @@
+/**
+ * The cache a config file can name beside its databases:
+ *
+ *   { "name": "cache", "kind": "cache", "url": "valkeys://cache.internal:6379/0",
+ *     "auth": { "password": "${VALKEY_PASSWORD}" } }
+ *
+ * A cache (Valkey, or anything speaking its protocol) keeps what may vanish: cached API answers and rate-limit
+ * windows, shared by every instance. Not a source of truth, optional, and a deployment has one. Checked when the
+ * file is read, opened when first used. The credential is a `${VAR}` reference expanded only when it opens, as an
+ * HTTP connection's is, never logged, and written back on save exactly as it was read.
+ *
+ * The other services (search, webhooks, email, identity) are the App framework's: serviceConnections.ts.
+ */
+import { type EgressPolicy } from '../adapters/http/egress.js';
+import { ValkeyCacheStore } from '../adapters/cache/cacheStore.js';
+import { type ConfigSections } from './configSections.js';
+interface CacheServiceConfig {
+    kind: 'cache';
+    name: string;
+    /** `valkey://host:6379/0`, `valkeys://` (TLS); `redis://` and `rediss://` too. `${VAR}` references intact. */
+    url: string;
+    auth?: {
+        username?: string;
+        password: string;
+    };
+    insecure?: boolean;
+    allowLinkLocal?: boolean;
+}
+declare module './configSections.js' {
+    interface ServiceKinds {
+        cache: CacheServiceConfig;
+    }
+}
+/** What the engine reads of a config file beside `connections`: the cache. */
+export declare const CACHE_SECTIONS: ConfigSections;
+/** Where a cache connection dials: host, port, TLS and database, with no credential in the URL. */
+export declare function cacheAddress(text: string, insecure: boolean, where: string): {
+    host: string;
+    port: number;
+    tls: boolean;
+    db: number;
+};
+/** The shared network policy a service's flags ask for. */
+export declare const egressPolicyOf: (service: {
+    insecure?: boolean;
+    allowLinkLocal?: boolean;
+}) => EgressPolicy;
+/** Open the cache: a Valkey client behind the shared network policy. Nothing dials until the first command. */
+export declare function openCache(service: CacheServiceConfig, onUnavailable: (message: string) => void): ValkeyCacheStore;
+export {};

package/dist/server/cacheService.js

@@ -0,0 +1,110 @@
+/**
+ * The cache a config file can name beside its databases:
+ *
+ *   { "name": "cache", "kind": "cache", "url": "valkeys://cache.internal:6379/0",
+ *     "auth": { "password": "${VALKEY_PASSWORD}" } }
+ *
+ * A cache (Valkey, or anything speaking its protocol) keeps what may vanish: cached API answers and rate-limit
+ * windows, shared by every instance. Not a source of truth, optional, and a deployment has one. Checked when the
+ * file is read, opened when first used. The credential is a `${VAR}` reference expanded only when it opens, as an
+ * HTTP connection's is, never logged, and written back on save exactly as it was read.
+ *
+ * The other services (search, webhooks, email, identity) are the App framework's: serviceConnections.ts.
+ */
+import { DEFAULT_POLICY } from '../adapters/http/egress.js';
+import { RespClient } from '../adapters/cache/resp.js';
+import { ValkeyCacheStore } from '../adapters/cache/cacheStore.js';
+import { expandEnvReferences } from './auth/credentials.js';
+import { SHARED_SERVICE_KEYS, checkServiceKeys, serviceWhere } from './configSections.js';
+import { product } from './product.js';
+const CACHE_PROTOCOLS = new Set(['valkey:', 'valkeys:', 'redis:', 'rediss:']);
+const TLS_PROTOCOLS = new Set(['valkeys:', 'rediss:']);
+function cacheConnectionOf(entry, path) {
+    const where = serviceWhere(entry, path);
+    checkServiceKeys(entry, 'cache', SHARED_SERVICE_KEYS, where);
+    const url = String(entry.url);
+    // A URL that is still a reference is checked when it opens, once the environment has said what it is.
+    if (!url.includes('${'))
+        cacheAddress(url, entry.insecure === true, where);
+    return {
+        kind: 'cache',
+        name: String(entry.name),
+        url,
+        ...(entry.insecure === true ? { insecure: true } : {}),
+        ...(entry.allowLinkLocal === true ? { allowLinkLocal: true } : {}),
+        ...(entry.auth !== undefined ? { auth: cacheAuth(entry.auth, where) } : {}),
+    };
+}
+/** What the engine reads of a config file beside `connections`: the cache. */
+export const CACHE_SECTIONS = {
+    kinds: {
+        cache: {
+            singleton: 'cache',
+            parse: cacheConnectionOf,
+            entry: ({ kind, name, url, auth, insecure, allowLinkLocal }) => ({
+                name,
+                kind,
+                url,
+                ...(auth ? { auth } : {}),
+                ...(insecure === true ? { insecure: true } : {}),
+                ...(allowLinkLocal === true ? { allowLinkLocal: true } : {}),
+            }),
+        },
+    },
+    checks: [],
+    top: {},
+};
+function cacheAuth(value, where) {
+    const auth = value;
+    const keys = auth && typeof auth === 'object' && !Array.isArray(auth) ? Object.keys(auth).sort().join(',') : '';
+    if ((keys === 'password' || keys === 'password,username') &&
+        typeof auth.password === 'string' &&
+        auth.password &&
+        (auth.username === undefined || (typeof auth.username === 'string' && auth.username))) {
+        return { ...(typeof auth.username === 'string' ? { username: auth.username } : {}), password: auth.password };
+    }
+    throw new Error(`${where} has an "auth" ${product()} cannot read. Write { "password": "\${VALKEY_PASSWORD}" }, with a "username" for an ACL user.`);
+}
+/** Where a cache connection dials: host, port, TLS and database, with no credential in the URL. */
+export function cacheAddress(text, insecure, where) {
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        throw new Error(`${where} has a "url" that is not a URL.`);
+    }
+    if (!CACHE_PROTOCOLS.has(url.protocol)) {
+        throw new Error(`${where} has a ${url.protocol}// "url". A cache is valkeys:// (TLS) or valkey://; redis:// and rediss:// work too.`);
+    }
+    const tls = TLS_PROTOCOLS.has(url.protocol);
+    if (!tls && !insecure) {
+        throw new Error(`${where} has a plain ${url.protocol}// "url". Use valkeys:// (TLS), or set "insecure": true for a cache on a trusted network.`);
+    }
+    if (url.username || url.password)
+        throw new Error(`${where} has a credential in its "url"; it belongs in "auth".`);
+    if (url.search || url.hash)
+        throw new Error(`${where} has a query or fragment in its "url".`);
+    const db = url.pathname.replace(/^\//, '');
+    if (db && !/^\d{1,2}$/.test(db))
+        throw new Error(`${where} names database "${db}" in its "url"; a cache database is a number (0–15).`);
+    return { host: url.hostname.replace(/^\[|\]$/g, ''), port: url.port ? Number(url.port) : 6379, tls, db: db ? Number(db) : 0 };
+}
+/** The shared network policy a service's flags ask for. */
+export const egressPolicyOf = (service) => ({
+    ...DEFAULT_POLICY,
+    insecure: service.insecure === true,
+    allowLinkLocal: service.allowLinkLocal === true,
+});
+/** Open the cache: a Valkey client behind the shared network policy. Nothing dials until the first command. */
+export function openCache(service, onUnavailable) {
+    const where = `connection "${service.name}"`;
+    const address = cacheAddress(expandEnvReferences(service.url), service.insecure === true, where);
+    const client = new RespClient({
+        ...address,
+        ...(service.auth?.username ? { username: expandEnvReferences(service.auth.username) } : {}),
+        ...(service.auth ? { password: expandEnvReferences(service.auth.password) } : {}),
+        policy: egressPolicyOf(service),
+    });
+    return new ValkeyCacheStore(client, (message) => onUnavailable(`cache "${service.name}": ${message}`));
+}

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

@@ -0,0 +1,176 @@
+/**
+ * The command line, read: every flag `tablewalk` takes, into one Options
+ * value, with the environment variables that stand in for flags in a
+ * container. `USAGE` in cli/usage.ts says the same list in words, and
+ * test/prose.test.ts holds the two and the README to each other.
+ */
+import { type ProxyRange } from '../http/trust.js';
+import type { PoolerMode } from '../../adapters/poolMetrics.js';
+/**
+ * The variable `mistri check` and a build set on the child that validates (build.ts `checkApp`): the real
+ * validation, run as CI runs it, and not a spelling of the command line.
+ */
+export declare const CHECK_VALIDATION = "MISTRI_CHECK_VALIDATION";
+export interface Options {
+    target: string;
+    /** The target is DATABASE_URL's, not a flag's: a config's connections win over it (readStartupConfig). */
+    targetFromEnvironment?: boolean;
+    port: number;
+    host: string;
+    schemas: string[];
+    open: boolean;
+    config?: string;
+    noConfig: boolean;
+    /** `--no-live`: no change rows written, no `/api/live` (live/liveBinding.ts). */
+    noLive?: boolean;
+    /** `--db-latency <ms>`: each database round trip waits this long first, in development (adapters/dbLatency.ts). */
+    dbLatency?: string;
+    /** Extra names the `Host` header may carry. See `doorRefusal`. */
+    allowedHosts: string[];
+    /** Speak MCP over stdio instead of serving HTTP. For coding agents. */
+    mcp: boolean;
+    /** Serve the dev observer at /_mistri/observe: loopback only, memory only (observe/observer.ts). */
+    dev?: boolean;
+    outputSchema: boolean;
+    tools: string;
+    /** Print the schema in this format and exit: md, mermaid, or json. */
+    export?: string;
+    /** Required for local OpenAPI export; no implicit integer wire policy. */
+    apiIntegers?: string;
+    apiReads?: boolean;
+    apiRequestsPerMinute?: string;
+    /** Speak one App's API as MCP tools on stdio; the token comes from the environment. */
+    appMcp?: boolean;
+    /** Report on the shape and exit: text or json. */
+    lint?: string;
+    /** Write a drafted TypeScript App project for the active connection into this directory, then exit. */
+    scaffoldApp?: string;
+    /** With --scaffold-app: the App's name, instead of one read off the database file's. */
+    name?: string;
+    /** Draft an HTTP connection's description from this OpenAPI JSON spec, print it, and exit. */
+    fromOpenapi?: string;
+    /** Serve the API this OpenAPI spec (a file or URL) describes, as a connection. */
+    openapi?: string;
+    /** With --openapi: the API's base URL, over the spec's servers. */
+    apiUrl?: string;
+    /** With --openapi: the variable holding a bearer token. */
+    apiTokenEnv?: string;
+    /** Validate the loaded app(s) against their connections, report, and exit: the validation step of `mistri check`,
+        run as its child (CHECK_VALIDATION), never a flag of a person's. */
+    checkApp?: boolean;
+    /** With `mistri check`: write each App's authority.lock from what it grants now. */
+    writeAuthority?: boolean;
+    /** With `mistri check`: move these commands' contracts to their next version in authority.lock (commandContracts.ts). */
+    bump?: string[];
+    /** With --app: index the searched resources (all, or the one named), then exit. '' means all. */
+    reindex?: string;
+    /** With `lint`, the severity at which the exit code turns non-zero. */
+    failOn?: string;
+    /** Build a throwaway demo database and open it — an instant try with no
+        database of your own. */
+    demo: boolean;
+    /** Whether a port was named explicitly; if not, a busy default rolls on. */
+    portGiven: boolean;
+    /** Print the usage and stop. */
+    help: boolean;
+    /** Print the version and stop. */
+    version: boolean;
+    /** A flag we do not know, kept so the error can name it. */
+    unknown?: string;
+    /** Compare the active connection with this one and exit. */
+    diff?: string;
+    /**
+     * The header a reverse proxy sets with the signed-in user's identity
+     * (`X-Forwarded-User`, `Cf-Access-Authenticated-User-Email`). Set, every
+     * request from beyond loopback must carry it and come from an
+     * `--auth-proxy-from` address, and every write is journaled with it. Not authentication — the proxy did that — but the
+     * line that lets the proxy's decision reach this process.
+     */
+    authProxyHeader?: string;
+    /** A retired spelling was given (a flag or variable renamed before 1.0): startup refuses it with this sentence. */
+    retired?: string;
+    /**
+     * `--trust-proxy` values as given, then (after startup validates them) the
+     * ranges: proxies whose X-Forwarded-For the public form rate limit may believe.
+     * Loopback is trusted without them. Nothing to do with sign-in: identity is `authProxyFrom`.
+     */
+    trustProxy: string[];
+    /**
+     * `--auth-proxy-from` values as given, then (after startup validates them) `authProxies`: the peers, beside
+     * loopback, whose `--auth-proxy-header` value is believed. Its own list so that a wide `--trust-proxy` never
+     * makes every peer in it able to name the signed-in person.
+     */
+    authProxyFrom: string[];
+    authProxies?: ProxyRange[];
+    /** `--trust-proxy-hops` as given; startup validates it (parseClientAddressPolicy). */
+    trustProxyHops?: string;
+    /** `--trust-proxy-cloudflare`: read CF-Connecting-IP. */
+    trustProxyCloudflare: boolean;
+    /** `--insecure-http-sign-in`: serve sign-in at an http address beyond this machine, which is otherwise refused. */
+    insecureHttpSignIn?: boolean;
+    trustedProxies?: ProxyRange[];
+    /** Serve an app: a directory whose app.ts (or app.mjs / app.json) curates the UI. */
+    apps?: string[];
+    /** With one --app: its manifest file, when it is not the directory's own app.ts; the directory stays the App's root. */
+    appEntry?: string;
+    /** `--mount <app>=<path>` as written, by App id: `/` is the main App at the root (shared/mount.ts). Checked in main. */
+    mounts?: Record<string, string>;
+    /** `--base-path` (or MISTRI_BASE_PATH) as written: the path a reverse proxy serves this server under. Checked in main. */
+    basePath?: string;
+    commands?: string;
+    /** A server-only defineJobs module: durable jobs that run the App's commands. */
+    jobs?: string;
+    policy?: string;
+    /** `--read-pool` as written: PostgreSQL readers per database for every pool that names none. Checked in main. */
+    readPool?: string;
+    /** `--write-pool` as written: writers per database for an App's PostgreSQL source. Checked in main. */
+    writePool?: string;
+    /** `--lock-timeout` as written: seconds a writer waits for a lock. Checked in main. */
+    lockTimeout?: string;
+    /** `--pooler` as written: what sits between this process and PostgreSQL. Checked in main. */
+    pooler?: string;
+    /** `--drain-delay` as written: seconds /readyz fails before the listener closes on SIGTERM. Checked by shutdownTimings. */
+    drainDelay?: string;
+    /** `--shutdown-grace` as written: seconds a response still unfinished after the drain may keep the process. Checked by shutdownTimings. */
+    shutdownGrace?: string;
+    /**
+     * Not a flag: set by `createHandler` (embed/handler.ts), whose server
+     * runs inside somebody else's process. A startup refusal throws instead of
+     * exiting it, and links are minted for the host's own origin. `origins` are
+     * its `embed.origins`, carried on the listener's `Bound` (http/trust.ts).
+     */
+    embedded?: {
+        publicURL: string;
+        origins?: readonly string[];
+    };
+}
+export declare function parseArgs(argv: string[]): Options;
+/** Cloud Run gives a stopping instance 10 seconds in all, so the default drains nothing and cuts a stuck response at 10. */
+export declare const DEFAULT_SHUTDOWN_TIMINGS: {
+    readonly drainMs: 0;
+    readonly graceMs: 10000;
+};
+/**
+ * What `--drain-delay` and `--shutdown-grace` (or MISTRI_DRAIN_DELAY and
+ * MISTRI_SHUTDOWN_GRACE) name, in milliseconds, or the sentence saying why
+ * they cannot be used. The delay is the beat a balancer that probes /readyz
+ * needs between the first 503 and the listener closing; the grace bounds a
+ * response that never finishes once the rest has drained. They come one after
+ * the other, so a platform's stop timeout must hold both plus the drain.
+ */
+export declare function shutdownTimings(opts: Pick<Options, 'drainDelay' | 'shutdownGrace'>): {
+    drainMs: number;
+    graceMs: number;
+} | string;
+/**
+ * The process-wide pool defaults `--read-pool`, `--write-pool`, `--pooler`
+ * and `--lock-timeout` (or their variables) name, or the sentence saying why
+ * they cannot be used. Refused rather than clamped: a pod sized for 16
+ * readers that quietly got 4 is a capacity plan nobody can see failing.
+ */
+export declare function postgresPoolFlags(opts: Pick<Options, 'readPool' | 'writePool' | 'pooler' | 'lockTimeout'>): {
+    readers?: number;
+    writers?: number;
+    pooler?: PoolerMode;
+    lockTimeoutMs?: number;
+} | string;