@mistriwork/engine 0.0.0 → 1.0.0-rc.10

package/dist/server/cli/usage.js

@@ -0,0 +1,31 @@
+/**
+ * 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 function commandWordsOf(usage, bin) {
+    return [...new Set([...usage.matchAll(new RegExp(`^ {2}${bin} ([a-z][a-z-]*)(?=\\s|$)`, 'gm'))].map((match) => match[1]))];
+}
+/** Every flag a usage spells, for an unknown option's suggestion. */
+export function flagWordsOf(usage) {
+    return [...new Set([...usage.matchAll(/(?<![\w-])--?[a-zA-Z][\w-]*/g)].map((match) => match[0]))];
+}
+/** What was probably meant, said the way a person would type it, or nothing when nothing is near. */
+export async function didYouMean(said, among) {
+    const { distance, nearest } = await import('../../shared/suggest.js');
+    const near = nearest(said, among);
+    return near !== undefined && distance(said.toLowerCase(), near.toLowerCase()) <= Math.max(1, Math.floor(said.length / 3))
+        ? ` Did you mean ${near}?`
+        : '';
+}
+/** What the package says it is, best effort. Every package of the workspace carries the one version. */
+export async function packageVersion() {
+    try {
+        const { runtimeVersion } = await import('../packageVersion.js');
+        return runtimeVersion();
+    }
+    catch {
+        return '0.0.0';
+    }
+}

package/dist/server/clientHttp.d.ts

@@ -0,0 +1,184 @@
+/**
+ * The shared client files. Callers own host checks and API dispatch.
+ *
+ * From source, Vite's middleware answers (devclient.ts). From the build,
+ * dist/client is served the way `vite build` left it (vite.config.ts): the
+ * scripts and stylesheets under assets/ are named for their content, so a
+ * browser may keep them for a year and never ask again; index.html and
+ * anything else unhashed is revalidated on every load, by ETag, so an
+ * unchanged page costs a 304. Every text file has a `.br` and a `.gz` beside
+ * it, and the request's Accept-Encoding picks one; the one thing compressed
+ * here, per request, is a public page with its own head (publicHead.ts).
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type ClientFiles } from './devclient.js';
+import { type PageGrounds } from './clientSurface.js';
+/**
+ * The page's Content-Security-Policy: what the shell — the one page every
+ * App, sign-in and the Workbench are drawn in — may load and talk to.
+ *
+ * The reason is egress. Every endpoint the page can reach is authorized on
+ * the server, so a script in the page can do nothing the reader could not;
+ * what the server cannot stop is a script sending what the reader sees
+ * somewhere else. So scripts come from this origin and from the inline
+ * startup scripts in index.html, pinned by their hashes, and the page talks
+ * to this origin alone (`connect-src 'self'`, which also admits the dev
+ * server's hot-reload socket on the same port). Images may come from any
+ * https address, because an App may name a picture by URL in a column (a
+ * card's image); nothing else leaves the origin. Styles keep
+ * `'unsafe-inline'`: React's style props, the layout preview's copied
+ * sheets and the dev server's injected stylesheets are all inline, and a
+ * stylesheet cannot send anything the image and connect rules do not let
+ * out. The hashes are read from the page being sent — Vite adds its own
+ * inline script in development — so a changed startup script cannot drift
+ * from its policy.
+ */
+export declare function shellPolicy(html: string, { fromSource, socket }?: {
+    fromSource?: boolean;
+    socket?: string;
+}): string;
+/**
+ * Where the served Apps' custom components may reach beyond the page's own
+ * origin (`ui.csp`, recorded in each App's authority.lock).
+ * One shell draws every App a server serves, and a reader moves between them
+ * without it reloading, so the policy opens the union — nothing any of them
+ * did not declare. Once any App serves components, the page's pictures stop
+ * coming from any https address: an image request is a way out too, so its
+ * origins are the declared ones.
+ */
+interface ShellEgress {
+    connect: readonly string[];
+    images: readonly string[];
+    narrowImages: boolean;
+    /** A human check's provider (`auth.challenge` with a widget): its script, the frame it draws and what it asks. */
+    widgets?: readonly string[];
+}
+/** The egress of the Apps a server serves, from their `ui`, whether each serves components, and the origin of the
+    human check widget its public forms draw (the App framework's commands/challenges.ts), if any. */
+export declare function shellEgress(apps: ReadonlyArray<{
+    ui: {
+        csp?: {
+            connect?: readonly string[];
+            images?: readonly string[];
+        };
+    };
+    components: boolean;
+    widget?: string;
+}>): ShellEgress | undefined;
+/** The shell's policy with the served Apps' egress in its connect and image sources (shellPolicy writes both directives exactly so). */
+export declare function withEgress(policy: string, egress: ShellEgress | undefined): string;
+/**
+ * What one page's shell says of itself beyond the static file: a public
+ * page's title and canonical address (http/publicHead.ts), the served Apps'
+ * egress, and where the Apps are mounted (shared/mount.ts) — the base path
+ * its own files are under and the mounts the client reads its addresses by —
+ * with the inside address the page is for, which names its surface, and
+ * where the dev observer is when one runs (server/observe/): the page reports
+ * its errors and layout shifts there and shows its badge.
+ */
+interface ShellTitle {
+    title?: string;
+    canonical?: string;
+    egress?: ShellEgress;
+    /** Origins besides this one that may frame the page (`withFrameAncestors`). */
+    frameAncestors?: readonly string[];
+    /** Nobody may frame the page, this origin included: an OAuth consent page (http/handler.ts). */
+    unframed?: boolean;
+    mount?: {
+        base: string;
+        json: string;
+    };
+    path?: string;
+    /** The database browser's page (browserHandler.ts): its own surface, and the meta that starts its main (clientSurface.ts). */
+    workbench?: true;
+    observe?: string;
+    /** Already resolved under the request's read owner, before streaming begins. */
+    branding?: HeadBranding;
+    /** The look sheets the App at this address wears (clientSurface.ts lookSheetsFor), preloaded beside the entry. */
+    looks?: readonly string[];
+    /** The density that look starts at (clientSurface.ts lookDensityFor), said in the page so boot zooms to it once. */
+    density?: string;
+    /**
+     * The App at this address is an installable PWA (mistri http/pwaRoutes.ts):
+     * its manifest and the script that registers its worker, both from this
+     * origin, so the page's `script-src 'self'` admits them with no inline
+     * script and no hash to keep. Absent, the page says nothing of the kind.
+     */
+    pwa?: {
+        manifest: string;
+        register: string;
+    };
+    /** The scheme that look says (clientSurface.ts lookSchemeFor), said in the page so it is dark from its first paint. */
+    scheme?: 'dark' | 'dark-only';
+    /** The page's colours in each mode (clientSurface.ts lookGroundsFor), written as `color-scheme` and `theme-color`. */
+    grounds?: PageGrounds;
+    /** The look sheets whose face that look is set in (clientSurface.ts lookFacesFor), preloaded beside them. */
+    faces?: readonly string[];
+    /** The App theme's own faces: their `@font-face` rules and the heading face's preload (clientSurface.ts appFaceHead). */
+    appFaces?: string;
+    /** A tenant host's page: its shell page preloads the tenant's flows too (clientSurface.ts tenantPreloads). */
+    tenant?: true;
+    /** The reader's locale where the server knows it (an App's), so a non-English reader's chrome words are preloaded (clientSurface.ts localePreloads). */
+    locale?: string;
+    /** The page's first answers (http/firstPaint.ts), asked only when a page — not a file — is what is sent. */
+    data?: () => Promise<ShellData | undefined>;
+    /** What a link preview reads (http/publicHead.ts): the page's absolute address, its words and its picture. */
+    social?: SocialHead;
+    /** The content pane drawn on the server (publicRender.ts), from the page's carried answers where it needs them. */
+    pane?: (answers: ShellData['answers']) => Promise<DrawnPane | undefined>;
+}
+/**
+ * A record's look a page is sent in (the App framework's http/recordBranding.ts
+ * BrandingPresentation): the theme, which is validated again here before a
+ * token is written, whether the look is one person's (the page is then never
+ * stored by a shared cache), and the whole presentation, which the page
+ * carries as JSON.
+ */
+interface HeadBranding {
+    readonly value: {
+        readonly theme: unknown;
+    };
+    readonly private: boolean;
+}
+/** A content pane drawn on the server (the App framework's publicRender.ts): its kind, said to the client, and its markup. */
+interface DrawnPane {
+    kind: string;
+    html: string;
+}
+/** A page's data block (firstPaint.ts), written where the page's body ends, and the answers it carries by request. */
+interface ShellData {
+    block: string;
+    answers?: Readonly<Record<string, {
+        body: unknown;
+    }>>;
+}
+/** A public page as a link preview and a search result say it: Open Graph and Twitter's card. */
+export interface SocialHead {
+    /** The canonical address, absolute. */
+    url: string;
+    title: string;
+    site: string;
+    description?: string;
+    /** The preview picture, absolute. */
+    image?: string;
+    imageAlt?: string;
+    type: 'website' | 'article';
+}
+/**
+ * The shell with a page's own head written in. Under a base path the page's
+ * own files are said under it (a component's host modules are said under it
+ * where the component is served, componentRoutes.ts). An inline script the
+ * head adds changes the page, so a caller whose page changed takes its policy
+ * from the page it sends (shellPolicy), never the static file's.
+ */
+export declare function withHead(html: string, head: ShellTitle | undefined): string;
+/**
+ * What the browser draws around the page: the form controls and scroll bars in the scheme the theme wears
+ * (`color-scheme`; a dark-only theme says dark alone), and the address bar and overscroll in its ground, one
+ * `theme-color` for each mode the reader's machine can be in. Plain HTML in the head: nothing for a script to wait on.
+ */
+export declare function groundsMeta(grounds: PageGrounds): string;
+export declare function serveClient(files: ClientFiles, req: IncomingMessage, res: ServerResponse, shell?: ShellTitle): Promise<void>;
+/** Serves a built client directory: the one the package ships, or a test's. */
+export declare function builtClient(dir: string): (req: IncomingMessage, res: ServerResponse, head: boolean, shell?: ShellTitle) => Promise<void>;
+export {};