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

package/dist/server/compileCache.d.ts

@@ -0,0 +1 @@
+export declare function compileCacheDirectory(env: NodeJS.ProcessEnv): string | undefined;

package/dist/server/compileCache.js

@@ -0,0 +1,30 @@
+/**
+ * Where the built server keeps V8's compile cache (`module.enableCompileCache`).
+ *
+ * Under the user's cache directory rather than Node's default of the OS temp
+ * directory: the temp directory is emptied on reboot on some systems and is
+ * shared on others, and the cache is only worth having if the next start finds
+ * it. `NODE_COMPILE_CACHE` names another place, and
+ * `NODE_DISABLE_COMPILE_CACHE` turns it off, as they do for Node itself.
+ * Entries are keyed by file content and V8 version, so two installed versions
+ * never read each other's.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { product } from './product.js';
+export function compileCacheDirectory(env) {
+    if (env.NODE_DISABLE_COMPILE_CACHE)
+        return undefined;
+    if (env.NODE_COMPILE_CACHE)
+        return env.NODE_COMPILE_CACHE;
+    if (env.XDG_CACHE_HOME)
+        return join(env.XDG_CACHE_HOME, product(), 'compile');
+    let home;
+    try {
+        home = homedir();
+    }
+    catch {
+        return undefined;
+    }
+    return home ? join(home, '.cache', product(), 'compile') : undefined;
+}

package/dist/server/config/locations.d.ts

@@ -0,0 +1 @@
+export declare function configLocations(explicit?: string, env?: NodeJS.ProcessEnv): string[];

package/dist/server/config/locations.js

@@ -0,0 +1,15 @@
+/**
+ * Where a config file may live, in order.
+ *
+ * Project-local first, because a repo that ships a `mistri.json` (`tablewalk.json` for the browser) should win
+ * for anyone working in it; the user's own file is the fallback.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { configFileName, product } from '../product.js';
+export function configLocations(explicit, env = process.env) {
+    if (explicit)
+        return [explicit];
+    const xdg = env.XDG_CONFIG_HOME || join(homedir(), '.config');
+    return [join(process.cwd(), configFileName()), join(process.cwd(), `.${configFileName()}`), join(xdg, product(), 'connections.json')];
+}

package/dist/server/configPaths.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A SQLite target as a config file wrote it, said from that file's folder: `./shop.db`, `sqlite:shop.db` and
+ * `file:./shop.db` beside the config open that file wherever tablewalk was started — a check run from an App's folder
+ * (`--config ../tablewalk.json`) opened a new, empty `./shop.db` there instead. An absolute path, a server URL and a
+ * target with no folder to read it from are left as written.
+ */
+export declare function sqliteTargetFrom(url: string, base: string | undefined): string;

package/dist/server/configPaths.js

@@ -0,0 +1,34 @@
+/**
+ * The one rule for a path a config file writes: it is the file's folder's. One typed on the command line (--db,
+ * --app, --config) is the working directory's, and so is a value from the environment. Kept apart from
+ * connections.ts so the testing entry, which copies a config's databases, reads it without the registry.
+ */
+import { isAbsolute, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * A SQLite target as a config file wrote it, said from that file's folder: `./shop.db`, `sqlite:shop.db` and
+ * `file:./shop.db` beside the config open that file wherever tablewalk was started — a check run from an App's folder
+ * (`--config ../tablewalk.json`) opened a new, empty `./shop.db` there instead. An absolute path, a server URL and a
+ * target with no folder to read it from are left as written.
+ */
+export function sqliteTargetFrom(url, base) {
+    if (!base || !url || url === ':memory:' || url.includes('$'))
+        return url;
+    if (/^file:/i.test(url)) {
+        let file;
+        try {
+            file = /^file:\/\//i.test(url) ? fileURLToPath(url) : decodeURIComponent(url.slice('file:'.length).split('?')[0]);
+        }
+        catch {
+            return url;
+        }
+        return isAbsolute(file) ? file : resolve(base, file);
+    }
+    if (/^sqlite:/i.test(url)) {
+        const file = url.replace(/^sqlite:(\/\/)?/i, '');
+        return !file || file === ':memory:' || isAbsolute(file) ? url : `sqlite:${resolve(base, file)}`;
+    }
+    if (url.includes('://'))
+        return url;
+    return isAbsolute(url) ? url : resolve(base, url);
+}

package/dist/server/configSections.d.ts

@@ -0,0 +1,64 @@
+/**
+ * The sections of tablewalk.json beside `connections`.
+ *
+ * The engine reads `connections`, `hidden`, `pool` and the cache (connections.ts, cacheService.ts). Every other
+ * entry a config file lists beside the databases — an email service, an identity provider, a webhook, a search
+ * engine — and every other top-level key — `analytics` — belongs to the App framework. Its parsers are a table
+ * (serviceConnections.ts) that a main hands to `loadConfig`: the sections a binary owns are the ones it passes, and
+ * an entry of a kind it does not pass is refused there. The file stays one file; the engine neither knows those
+ * sections' shapes nor imports their parsers.
+ *
+ * A kind's config type is added to `ServiceKinds` by declaration merging from the module that registers it, so
+ * `ServiceConfig` is the union of the kinds the program has, and a reader of `Registry.serviceConfigs()` sees all of
+ * them without the engine naming one.
+ */
+/** Kind → the shape of its entry once checked. A registering module adds its own kinds with `declare module`. */
+export interface ServiceKinds {
+}
+export type ServiceKind = keyof ServiceKinds & string;
+export type ServiceConfig = ServiceKinds[keyof ServiceKinds];
+/** How one kind of service entry is read, checked and written back. */
+interface ServiceKindSpec {
+    /** Found by its issuer or by this server itself, so its entry may leave out "url". */
+    urlless?: boolean;
+    /** What a deployment has one of, in a sentence ("email service"): a second entry of the kind is refused. */
+    singleton?: string;
+    /** The entry, checked. Throws naming the field: a config someone wrote is refused rather than half-read. */
+    parse(entry: Record<string, unknown>, path: string): ServiceConfig;
+    /** The entry as written, for saving: the references stay references. */
+    entry(service: never): Record<string, unknown>;
+}
+/** The sections of a config file a binary owns: its service kinds, the checks across them, its top-level keys. */
+export interface ConfigSections {
+    kinds: Readonly<Record<string, ServiceKindSpec>>;
+    /** A check across every service the file names, run once they are all read (a scim directory names its providers). */
+    checks: ReadonlyArray<(services: readonly ServiceConfig[], path: string) => void>;
+    /** Top-level keys of the file other than `connections`; each parser gets the value and the file's path. */
+    top: Readonly<Record<string, (value: unknown, path: string) => unknown>>;
+    /**
+     * What becomes of an entry of a kind these sections do not name. Absent, it is refused. `'keep'` is the
+     * database browser's (cli/browserCommands.ts): the one file is shared with the App framework, whose services
+     * the browser neither reads nor serves, so their entries are kept as written, unread, and a save writes them
+     * back where they were.
+     */
+    others?: 'keep';
+}
+/** Sections side by side; the kinds and keys of a later part win, its checks follow. */
+export declare function mergeSections(...parts: ConfigSections[]): ConfigSections;
+/** Whether `sections` keep this entry unread: a kind they do not name, which another reader of the file does. */
+export declare const keptUnread: (sections: ConfigSections, kind: unknown) => boolean;
+export declare const isServiceKind: (sections: ConfigSections, kind: unknown) => kind is ServiceKind;
+/** Whether an entry of this kind is found by something other than a url. */
+export declare const isUrlless: (sections: ConfigSections, kind: unknown) => boolean;
+/** How a refusal names an entry: the file and the connection. */
+export declare const serviceWhere: (entry: Record<string, unknown>, path: string) => string;
+export declare function serviceConnectionOf(sections: ConfigSections, entry: Record<string, unknown>, path: string): ServiceConfig;
+export declare function serviceEntry(sections: ConfigSections, service: ServiceConfig): Record<string, unknown>;
+/** At most one of a singleton kind, then each check. */
+export declare function checkServices(sections: ConfigSections, services: readonly ServiceConfig[], path: string): void;
+/** The top-level keys the file has, parsed. */
+export declare function parseConfigSections(sections: ConfigSections, parsed: unknown, path: string): Record<string, unknown>;
+export declare const SHARED_SERVICE_KEYS: string[];
+/** Refuse a key the kind does not take, and a flag that is not a boolean. */
+export declare function checkServiceKeys(entry: Record<string, unknown>, kind: string, keys: readonly string[], where: string): void;
+export {};

package/dist/server/configSections.js

@@ -0,0 +1,72 @@
+/**
+ * The sections of tablewalk.json beside `connections`.
+ *
+ * The engine reads `connections`, `hidden`, `pool` and the cache (connections.ts, cacheService.ts). Every other
+ * entry a config file lists beside the databases — an email service, an identity provider, a webhook, a search
+ * engine — and every other top-level key — `analytics` — belongs to the App framework. Its parsers are a table
+ * (serviceConnections.ts) that a main hands to `loadConfig`: the sections a binary owns are the ones it passes, and
+ * an entry of a kind it does not pass is refused there. The file stays one file; the engine neither knows those
+ * sections' shapes nor imports their parsers.
+ *
+ * A kind's config type is added to `ServiceKinds` by declaration merging from the module that registers it, so
+ * `ServiceConfig` is the union of the kinds the program has, and a reader of `Registry.serviceConfigs()` sees all of
+ * them without the engine naming one.
+ */
+/** Sections side by side; the kinds and keys of a later part win, its checks follow. */
+export function mergeSections(...parts) {
+    return {
+        kinds: Object.assign({}, ...parts.map((p) => p.kinds)),
+        checks: parts.flatMap((p) => p.checks),
+        top: Object.assign({}, ...parts.map((p) => p.top)),
+    };
+}
+/** Whether `sections` keep this entry unread: a kind they do not name, which another reader of the file does. */
+export const keptUnread = (sections, kind) => sections.others === 'keep' && typeof kind === 'string' && kind !== 'http' && !Object.hasOwn(sections.kinds, kind);
+export const isServiceKind = (sections, kind) => typeof kind === 'string' && Object.hasOwn(sections.kinds, kind);
+/** Whether an entry of this kind is found by something other than a url. */
+export const isUrlless = (sections, kind) => typeof kind === 'string' && sections.kinds[kind]?.urlless === true;
+/** How a refusal names an entry: the file and the connection. */
+export const serviceWhere = (entry, path) => `${path}: connection "${String(entry.name)}"`;
+export function serviceConnectionOf(sections, entry, path) {
+    return sections.kinds[entry.kind].parse(entry, path);
+}
+export function serviceEntry(sections, service) {
+    return sections.kinds[service.kind].entry(service);
+}
+/** At most one of a singleton kind, then each check. */
+export function checkServices(sections, services, path) {
+    for (const [kind, spec] of Object.entries(sections.kinds)) {
+        if (!spec.singleton)
+            continue;
+        const named = services.filter((service) => service.kind === kind);
+        if (named.length > 1) {
+            throw new Error(`${path} names ${named.length} ${kind} connections (${named.map((c) => `"${c.name}"`).join(', ')}); a deployment has one ${spec.singleton}.`);
+        }
+    }
+    for (const check of sections.checks)
+        check(services, path);
+}
+/** The top-level keys the file has, parsed. */
+export function parseConfigSections(sections, parsed, path) {
+    const out = {};
+    for (const [key, parse] of Object.entries(sections.top)) {
+        const value = parsed[key];
+        if (value !== undefined)
+            out[key] = parse(value, path);
+    }
+    return out;
+}
+/* ---- what a plain url-and-auth service (a cache, a search engine) shares ---- */
+export const SHARED_SERVICE_KEYS = ['name', 'kind', 'url', 'auth', 'insecure', 'allowLinkLocal'];
+/** Refuse a key the kind does not take, and a flag that is not a boolean. */
+export function checkServiceKeys(entry, kind, keys, where) {
+    const stray = Object.keys(entry).find((key) => !keys.includes(key));
+    if (stray) {
+        throw new Error(`${where} is a ${kind} connection, which takes no "${stray}". It takes: ${keys.join(', ')}.`);
+    }
+    for (const flag of ['insecure', 'allowLinkLocal']) {
+        if (entry[flag] !== undefined && typeof entry[flag] !== 'boolean') {
+            throw new Error(`${where} has "${flag}": ${JSON.stringify(entry[flag])}. It must be true or false, without quotes.`);
+        }
+    }
+}

package/dist/server/connectionRedaction.d.ts

@@ -0,0 +1,30 @@
+/**
+ * A displayable form of a target with no credential in it.
+ *
+ * `URL` parses out the password for us; the fallback matters because a
+ * malformed URL must not fall through to printing the original string.
+ */
+export declare function redact(url: string): string;
+/**
+ * Take the credentials out of anything on its way to the browser.
+ *
+ * `redact` produces the public form of a URL we chose to show. This is for
+ * the other direction: text we did not write, going somewhere we did not
+ * intend. A driver's failure message quotes what it was handed, and what it
+ * was handed is the *resolved* connection string — the one with the password
+ * expanded out of the keychain and into it. That message was stored on the
+ * entry and served by every `GET /api/connections` from then on.
+ *
+ * Two passes, because there are two shapes of leak:
+ *
+ *   1. The whole DSN, echoed. Any `scheme://…` in the text is replaced with
+ *      its redacted form, so the message keeps saying which host it could not
+ *      reach — which is the useful half — without the credentials.
+ *   2. The password alone, quoted without its URL. Rarer, and caught by
+ *      sweeping for the literal value.
+ *
+ * A password shorter than four characters is swept too. It mangles a message
+ * that happens to contain those letters, and that is the right trade: a
+ * garbled sentence is a nuisance, and a password on screen is not.
+ */
+export declare function scrubSecrets(text: string, ...urls: Array<string | undefined>): string;

package/dist/server/connectionRedaction.js

@@ -0,0 +1,77 @@
+/**
+ * A displayable form of a target with no credential in it.
+ *
+ * `URL` parses out the password for us; the fallback matters because a
+ * malformed URL must not fall through to printing the original string.
+ */
+export function redact(url) {
+    if (!/^[a-z][\w+.-]*:\/\//i.test(url)) {
+        // A bare file path. Show the file name, not the whole tree.
+        return url.split('/').pop() || url;
+    }
+    try {
+        const parsed = new URL(url);
+        const user = parsed.username ? `${parsed.username}@` : '';
+        const port = parsed.port ? `:${parsed.port}` : '';
+        return `${user}${parsed.hostname}${port}${parsed.pathname}`;
+    }
+    catch {
+        return '(connection)';
+    }
+}
+/**
+ * Take the credentials out of anything on its way to the browser.
+ *
+ * `redact` produces the public form of a URL we chose to show. This is for
+ * the other direction: text we did not write, going somewhere we did not
+ * intend. A driver's failure message quotes what it was handed, and what it
+ * was handed is the *resolved* connection string — the one with the password
+ * expanded out of the keychain and into it. That message was stored on the
+ * entry and served by every `GET /api/connections` from then on.
+ *
+ * Two passes, because there are two shapes of leak:
+ *
+ *   1. The whole DSN, echoed. Any `scheme://…` in the text is replaced with
+ *      its redacted form, so the message keeps saying which host it could not
+ *      reach — which is the useful half — without the credentials.
+ *   2. The password alone, quoted without its URL. Rarer, and caught by
+ *      sweeping for the literal value.
+ *
+ * A password shorter than four characters is swept too. It mangles a message
+ * that happens to contain those letters, and that is the right trade: a
+ * garbled sentence is a nuisance, and a password on screen is not.
+ */
+export function scrubSecrets(text, ...urls) {
+    let out = text.replace(/\b[a-z][\w+.-]*:\/\/[^\s'"`,)\]]+/gi, (match) => redact(match));
+    for (const url of urls) {
+        if (!url)
+            continue;
+        for (const secret of passwordsIn(url)) {
+            if (!secret)
+                continue;
+            out = out.split(secret).join('\u2022\u2022\u2022\u2022');
+        }
+    }
+    return out;
+}
+/**
+ * The password in a URL, in both the spellings it can appear in.
+ *
+ * `new URL` gives it percent-decoded, and a driver may quote either that or
+ * the raw form it was handed. Both are swept.
+ */
+function passwordsIn(url) {
+    const found = new Set();
+    try {
+        const parsed = new URL(url);
+        if (parsed.password) {
+            found.add(parsed.password);
+            found.add(decodeURIComponent(parsed.password));
+        }
+    }
+    catch {
+        /* Not a URL — a file path, or a string with a `${VAR}` still in it. There
+           is no password to find, and failing to parse is not an error here. */
+    }
+    return [...found];
+}