@trypattern/sdk 0.0.0-stage → 0.1.1

package/dist/flows/accessFlows.js

@@ -0,0 +1,167 @@
+import { createMemoryRouter } from 'react-router';
+import { expect, inject, test } from 'vitest';
+import { memoryApi } from "../api.js";
+import { Cache } from "../cache.js";
+import { Gate } from "../gate.js";
+import { routeObjects } from "../routes.js";
+import { ownerIdOf, seededRows } from "../table.js";
+import { publicStoreName } from "../tables.js";
+const STRANGER = 'stranger@access.test';
+function seesAll(level) {
+    return level === 'anyone' || level === 'signedIn';
+}
+function strangerOutcome(table, operation) {
+    const level = table.access[operation];
+    if (level === 'admin' || level === 'server')
+        return 'forbidden';
+    if (!seesAll(table.access.read))
+        return 'missing';
+    return level === 'owner' ? 'forbidden' : 'saved';
+}
+function creatorOf(table, admin) {
+    const level = table.access.create;
+    if (level === 'anyone' || level === 'signedIn')
+        return STRANGER;
+    return level === 'admin' ? admin : undefined;
+}
+function fieldsOf(table, row) {
+    return Object.fromEntries(Object.keys(table.columns).map((key) => [key, row[key]]));
+}
+function idsOf(rows) {
+    return rows.map((row) => row.id);
+}
+export function accessFlows({ App }) {
+    if (inject('patternVisualFlows') !== undefined) {
+        test.skip('Access flows run headless, in app test', () => undefined);
+        return;
+    }
+    const { tables, routes, services, memory } = App.definition;
+    const seed = (inject('patternSeed') ?? {});
+    const admins = inject('patternAdmins') ?? [];
+    const title = inject('patternTitle') ?? '';
+    const [admin] = admins;
+    async function started(signedInAs) {
+        const gate = new Gate();
+        const app = new App(createMemoryRouter(routeObjects(routes), { initialEntries: ['/'] }), {
+            api: memoryApi(tables, seed, {
+                gate,
+                signedInAs,
+                admins,
+                title,
+                world: structuredClone(inject('patternWorld') ?? {}),
+                ...(services === undefined ? {} : { services }),
+                ...(memory === undefined ? {} : { memory })
+            }),
+            cache: Cache.memory(),
+            gate
+        });
+        await app.whenIdle();
+        return app;
+    }
+    function storeOf(app, name) {
+        const stores = Reflect.get(app, 'stores');
+        return Reflect.get(Object(stores), name);
+    }
+    async function visibleIds(app, name) {
+        await app.whenIdle();
+        const snapshot = Reflect.get(Object(app.getSnapshot()), 'stores');
+        const state = Reflect.get(Object(snapshot), name);
+        const items = Reflect.get(Object(state), 'items');
+        return {
+            status: Reflect.get(Object(state), 'status'),
+            ids: Array.isArray(items)
+                ? items.map((item) => Reflect.get(Object(item), 'id'))
+                : []
+        };
+    }
+    if (Object.keys(tables).length === 0) {
+        test('Access: schema.ts has no tables yet, so there are no rules to check', () => {
+            expect(Object.keys(tables)).toEqual([]);
+        });
+    }
+    for (const table of Object.values(tables)) {
+        const name = table.name;
+        const rows = seededRows(seed, name);
+        const read = table.access.read;
+        const owners = [
+            ...new Set(rows.flatMap((row) => (row.ownerId ? [row.ownerId] : [])))
+        ];
+        const ownerEmails = new Map((Reflect.get(seed, name) ?? [])
+            .flatMap((row) => typeof row['owner'] === 'string' ? [row['owner'].toLowerCase()] : [])
+            .map((email) => [ownerIdOf(email), email]));
+        if (read !== 'server') {
+            test(`Access: ${name}, signed out, ${read === 'anyone' ? 'every row is visible' : 'nothing loads'}`, async () => {
+                const seen = await visibleIds(await started(null), name);
+                expect(seen).toEqual(read === 'anyone'
+                    ? { status: 'ready', ids: idsOf(rows) }
+                    : { status: 'idle', ids: [] });
+            });
+            test(`Access: ${name}, a signed-in stranger ${seesAll(read) ? 'sees every row' : "sees none of other people's rows"}`, async () => {
+                const seen = await visibleIds(await started(STRANGER), name);
+                expect(seen.ids).toEqual(seesAll(read) ? idsOf(rows) : []);
+            });
+            if (read === 'owner') {
+                for (const ownerId of owners) {
+                    const email = ownerEmails.get(ownerId) ?? ownerId;
+                    test(`Access: ${name}, ${email} sees only their own rows`, async () => {
+                        const seen = await visibleIds(await started(email), name);
+                        expect(seen.ids).toEqual(idsOf(rows.filter((row) => row.ownerId === ownerId)));
+                    });
+                }
+            }
+            if (admin !== undefined) {
+                test(`Access: ${name}, admin ${admin} sees every row`, async () => {
+                    const seen = await visibleIds(await started(admin), name);
+                    expect(seen.ids).toEqual(idsOf(rows));
+                });
+            }
+            const [first] = rows;
+            if (first !== undefined) {
+                for (const operation of ['update', 'delete']) {
+                    const expected = strangerOutcome(table, operation);
+                    const verb = operation === 'update' ? 'change' : 'delete';
+                    test(`Access: ${name}, a signed-in stranger ${expected === 'saved' ? 'can' : 'cannot'} ${verb} someone else's row`, async () => {
+                        const app = await started(STRANGER);
+                        const store = storeOf(app, name);
+                        const before = await visibleIds(app, name);
+                        const outcome = operation === 'update'
+                            ? await store.update(first)
+                            : await store.remove(first.id);
+                        expect(outcome).toBe(expected);
+                        if (expected !== 'saved') {
+                            expect(await visibleIds(app, name)).toEqual(before);
+                        }
+                    });
+                }
+            }
+        }
+        if (table.public.length > 0) {
+            const view = publicStoreName(name);
+            test(`Access: ${name}, signed out, ${view} shows only ${table.public.join(', ')}`, async () => {
+                const app = await started(null);
+                const snapshot = Reflect.get(Object(app.getSnapshot()), 'stores');
+                const state = Reflect.get(Object(snapshot), view);
+                expect(state).toEqual({
+                    status: 'ready',
+                    items: rows.map((row) => Object.fromEntries(['id', ...table.public].map((key) => [key, row[key] ?? null])))
+                });
+            });
+        }
+        const [duplicated] = rows;
+        const creator = creatorOf(table, admin);
+        if (table.unique.length > 0 &&
+            duplicated !== undefined &&
+            creator !== undefined &&
+            read !== 'server') {
+            for (const columns of table.unique) {
+                test(`Access: ${name}, a second row with the same ${columns.join(', ')} is refused`, async () => {
+                    const app = await started(creator);
+                    const before = await visibleIds(app, name);
+                    const outcome = await storeOf(app, name).create(fieldsOf(table, duplicated));
+                    expect(outcome).toBe('conflict');
+                    expect(await visibleIds(app, name)).toEqual(before);
+                });
+            }
+        }
+    }
+}

package/dist/flows/browser.d.ts

@@ -0,0 +1,34 @@
+import type { Browser, BrowserServer, Page } from 'playwright-core';
+export declare const viewports: {
+    readonly desktop: {
+        readonly width: 1440;
+        readonly height: 900;
+        readonly deviceScaleFactor: 1;
+    };
+    readonly compact: {
+        readonly width: 390;
+        readonly height: 844;
+        readonly deviceScaleFactor: 2;
+    };
+};
+export type ViewportName = keyof typeof viewports;
+export declare const viewportNames: readonly ViewportName[];
+export declare function launchChrome(): Promise<Browser>;
+export declare function launchChromeServer(): Promise<BrowserServer>;
+export declare function connectChrome(wsEndpoint: string): Promise<Browser>;
+export type AppPage = {
+    page: Page;
+    problems: string[];
+    send: (command: unknown) => Promise<unknown>;
+    dispatch: (command: unknown) => Promise<void>;
+    snapshot: () => Promise<unknown>;
+    hold: (call: string) => Promise<void>;
+    release: (call: string) => Promise<void>;
+    tick: () => Promise<void>;
+    world: (patch: object) => Promise<void>;
+    reload: (path: string) => Promise<void>;
+    screenshot: (file: string) => Promise<void>;
+    captureAt: (viewport: ViewportName) => Promise<string>;
+    close: () => Promise<void>;
+};
+export declare function openApp(browser: Browser, baseUrl: string, path: string, viewport: ViewportName, signedInAs: string | null, seed?: object, admins?: readonly string[], world?: unknown): Promise<AppPage>;

package/dist/flows/browser.js

@@ -0,0 +1,167 @@
+import { chromium } from 'playwright-core';
+export const viewports = {
+    desktop: { width: 1440, height: 900, deviceScaleFactor: 1 },
+    compact: { width: 390, height: 844, deviceScaleFactor: 2 }
+};
+export const viewportNames = ['desktop', 'compact'];
+const QUIET_NETWORK_MS = 250;
+const SETTLE_TIMEOUT_MS = 10_000;
+const HOOK_TIMEOUT_MS = 10_000;
+function chromeProblem(error) {
+    const reason = (error instanceof Error ? error.message : String(error))
+        .split('\n')
+        .find((line) => line.trim() !== '');
+    return new Error(`Could not launch Google Chrome (${reason ?? 'unknown error'}). Screenshots drive your installed Google Chrome; no browser is bundled. Install it from https://www.google.com/chrome/ (or update it), then rerun.`);
+}
+export async function launchChrome() {
+    try {
+        return await chromium.launch({ channel: 'chrome' });
+    }
+    catch (error) {
+        throw chromeProblem(error);
+    }
+}
+export async function launchChromeServer() {
+    try {
+        return await chromium.launchServer({ channel: 'chrome' });
+    }
+    catch (error) {
+        throw chromeProblem(error);
+    }
+}
+export function connectChrome(wsEndpoint) {
+    return chromium.connect(wsEndpoint);
+}
+function sleep(ms) {
+    return new Promise((done) => setTimeout(done, ms));
+}
+function watchNetwork(page) {
+    let inFlight = 0;
+    let lastActivity = Date.now();
+    const started = () => {
+        inFlight += 1;
+        lastActivity = Date.now();
+    };
+    const ended = () => {
+        inFlight = Math.max(0, inFlight - 1);
+        lastActivity = Date.now();
+    };
+    page.on('request', started);
+    page.on('requestfinished', ended);
+    page.on('requestfailed', ended);
+    return async () => {
+        const deadline = Date.now() + SETTLE_TIMEOUT_MS;
+        while (Date.now() < deadline) {
+            if (inFlight === 0 && Date.now() - lastActivity >= QUIET_NETWORK_MS) {
+                return;
+            }
+            await sleep(25);
+        }
+    };
+}
+function recordProblems(page, problems) {
+    const record = (problem) => {
+        if (!problems.includes(problem))
+            problems.push(problem);
+    };
+    page.on('console', (message) => {
+        if (message.type() === 'error') {
+            record(`console error: ${message.text()}`);
+        }
+    });
+    page.on('pageerror', (error) => {
+        record(`uncaught page error: ${error.message}`);
+    });
+    page.on('requestfailed', (request) => {
+        record(`request failed: ${request.method()} ${request.url()} (${request.failure()?.errorText ?? 'unknown'})`);
+    });
+    page.on('response', (response) => {
+        if (response.status() >= 400) {
+            record(`request failed: ${response.request().method()} ${response.url()} (HTTP ${response.status()})`);
+        }
+    });
+}
+export async function openApp(browser, baseUrl, path, viewport, signedInAs, seed, admins = [], world = {}) {
+    const { width, height, deviceScaleFactor } = viewports[viewport];
+    const context = await browser.newContext({
+        viewport: { width, height },
+        deviceScaleFactor,
+        reducedMotion: 'reduce',
+        colorScheme: 'light'
+    });
+    if (signedInAs !== null) {
+        const signIn = await context.request.post(new URL('/api/auth/dev-sign-in', baseUrl).href, { data: { email: signedInAs } });
+        if (!signIn.ok()) {
+            throw new Error(`Dev sign-in as ${signedInAs} failed (HTTP ${signIn.status()}): ${await signIn.text()}`);
+        }
+    }
+    if (seed !== undefined) {
+        await context.addInitScript((value) => {
+            Object.assign(globalThis, {
+                patternSeed: value.seed,
+                patternAdmins: value.admins,
+                patternWorld: value.world
+            });
+        }, { seed, admins, world });
+    }
+    const page = await context.newPage();
+    const problems = [];
+    recordProblems(page, problems);
+    const networkIdle = watchNetwork(page);
+    const settle = async () => {
+        await networkIdle();
+        await page.evaluate(async () => {
+            const globals = globalThis;
+            await globals.pattern.snapshot();
+            await globals.document.fonts.ready;
+            await new Promise((done) => globals.requestAnimationFrame(() => globals.requestAnimationFrame(done)));
+        });
+    };
+    const load = async (target) => {
+        await page.goto(new URL(target, baseUrl).href);
+        await page.waitForFunction(() => 'pattern' in globalThis, undefined, {
+            timeout: HOOK_TIMEOUT_MS
+        });
+        await settle();
+    };
+    const snapshot = () => page.evaluate(() => globalThis.pattern.snapshot());
+    const dispatch = async (command) => {
+        const reply = await page.evaluate((sent) => globalThis.pattern.send(sent), command);
+        if ('error' in reply)
+            throw new Error(reply.error);
+    };
+    await load(path);
+    let devTools;
+    return {
+        page,
+        problems,
+        send: async (command) => {
+            await dispatch(command);
+            return snapshot();
+        },
+        dispatch,
+        snapshot,
+        hold: (call) => page.evaluate((held) => globalThis.pattern.hold(held), call),
+        release: (call) => page.evaluate((released) => globalThis.pattern.release(released), call),
+        tick: () => page.evaluate(() => globalThis.pattern.tick()),
+        world: (patch) => page.evaluate((changed) => globalThis.pattern.world(changed), patch),
+        reload: load,
+        screenshot: async (file) => {
+            await settle();
+            await page.screenshot({ path: file, animations: 'disabled' });
+        },
+        captureAt: async (next) => {
+            devTools ??= await context.newCDPSession(page);
+            await devTools.send('Emulation.setDeviceMetricsOverride', {
+                ...viewports[next],
+                mobile: false
+            });
+            await settle();
+            const { data } = await devTools.send('Page.captureScreenshot', {
+                format: 'png'
+            });
+            return data;
+        },
+        close: () => context.close()
+    };
+}

package/dist/flows/contactSheet.d.ts

@@ -0,0 +1 @@
+export declare function writeContactSheet(wsEndpoint: string, directory: string, file: string): Promise<void>;

package/dist/flows/contactSheet.js

@@ -0,0 +1,63 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { connectChrome, viewportNames, viewports } from "./browser.js";
+const COLUMNS = 2;
+const IMAGE_HEIGHT_PX = 400;
+function sheetHtml(directory, names) {
+    const sizes = viewportNames
+        .map((v) => `${v} ${viewports[v].width}×${viewports[v].height}`)
+        .join(' · ');
+    const figures = names.map((name) => {
+        const shots = viewportNames.flatMap((viewport) => {
+            const path = join(directory, `${name}-${viewport}.png`);
+            if (!existsSync(path))
+                return [];
+            const png = readFileSync(path);
+            return `<div class="shot"><img src="data:image/png;base64,${png.toString('base64')}"><span>${viewport}</span></div>`;
+        });
+        return `<figure><figcaption>${name}</figcaption><div class="shots">${shots.join('')}</div></figure>`;
+    });
+    return `<!doctype html>
+<html><head><style>
+* { box-sizing: border-box; margin: 0; }
+body { background: #e8e8ec; font: 500 22px/1.3 -apple-system, system-ui, sans-serif; color: #202020; }
+main { display: inline-grid; grid-template-columns: repeat(${COLUMNS}, auto); gap: 40px 48px; padding: 40px; }
+header { grid-column: 1 / -1; display: flex; gap: 24px; align-items: baseline; }
+header h1 { font-size: 30px; font-weight: 650; }
+header p { color: #646464; }
+figure { display: flex; flex-direction: column; gap: 12px; }
+figcaption { font-size: 26px; font-weight: 650; }
+.shots { display: flex; gap: 16px; align-items: flex-start; }
+.shot { display: flex; flex-direction: column; gap: 6px; color: #646464; font-size: 18px; }
+img { height: ${IMAGE_HEIGHT_PX}px; border-radius: 6px; box-shadow: 0 0 0 1px rgb(0 0 0 / 0.12), 0 4px 16px rgb(0 0 0 / 0.08); }
+</style></head><body><main>
+<header><h1>Flow screenshots</h1><p>${names.length} captures · ${sizes}</p></header>
+${figures.join('\n')}
+</main></body></html>`;
+}
+export async function writeContactSheet(wsEndpoint, directory, file) {
+    const suffix = new RegExp(`-(${viewportNames.join('|')})\\.png$`);
+    const names = [
+        ...new Set(readdirSync(directory)
+            .filter((entry) => suffix.test(entry))
+            .map((entry) => entry.replace(suffix, '')))
+    ].sort();
+    if (names.length === 0)
+        return;
+    const browser = await connectChrome(wsEndpoint);
+    try {
+        const page = await browser.newPage({ deviceScaleFactor: 1 });
+        await page.setContent(sheetHtml(directory, names));
+        const box = await page.locator('main').boundingBox();
+        if (box !== null) {
+            await page.setViewportSize({
+                width: Math.ceil(box.width),
+                height: Math.ceil(box.height)
+            });
+        }
+        await page.screenshot({ path: file, fullPage: true });
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/flows/flowBrowser.d.ts

@@ -0,0 +1,25 @@
+import type { ViewportName } from './browser.ts';
+export type VisualFlowSettings = {
+    url: string;
+    wsEndpoint: string;
+    directory: string;
+    viewports: readonly ViewportName[];
+};
+declare module 'vitest' {
+    interface ProvidedContext {
+        patternVisualFlows?: VisualFlowSettings;
+    }
+}
+export declare function closeFlowBrowser(): Promise<void>;
+export declare function openFlowPage(settings: VisualFlowSettings, viewport: ViewportName, startAt: string, signedInAs: string | null, seed: object, admins: readonly string[], world: unknown): Promise<{
+    send: (command: unknown) => Promise<void>;
+    snapshot: () => Promise<unknown>;
+    hold: (call: string) => Promise<void>;
+    release: (call: string) => Promise<void>;
+    tick: () => Promise<void>;
+    world: (patch: object) => Promise<void>;
+    reload: (path: string) => Promise<void>;
+    screenshot: (name: string) => Promise<void>;
+    problems: string[];
+    close: () => Promise<void>;
+}>;

package/dist/flows/flowBrowser.js

@@ -0,0 +1,23 @@
+import { connectChrome, openApp } from "./browser.js";
+let browser;
+export async function closeFlowBrowser() {
+    const connected = browser;
+    browser = undefined;
+    await (await connected)?.close();
+}
+export async function openFlowPage(settings, viewport, startAt, signedInAs, seed, admins, world) {
+    browser ??= connectChrome(settings.wsEndpoint);
+    const app = await openApp(await browser, settings.url, startAt, viewport, signedInAs, seed, admins, world);
+    return {
+        send: app.dispatch,
+        snapshot: app.snapshot,
+        hold: app.hold,
+        release: app.release,
+        tick: app.tick,
+        world: app.world,
+        reload: app.reload,
+        screenshot: (name) => app.screenshot(`${settings.directory}/${name}-${viewport}.png`),
+        problems: app.problems,
+        close: app.close
+    };
+}

package/dist/flows/flowSetup.d.ts

@@ -0,0 +1,3 @@
+import type { TestProject } from 'vitest/node';
+export declare function setup(project: TestProject): Promise<void>;
+export declare function teardown(): Promise<void>;

package/dist/flows/flowSetup.js

@@ -0,0 +1,35 @@
+import { mkdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { launchChromeServer, viewportNames } from "./browser.js";
+import { writeContactSheet } from "./contactSheet.js";
+const ROOT = process.cwd();
+const SCREENSHOTS_DIRECTORY = join(ROOT, '.dev', 'screenshots');
+const FLOW_SCREENSHOTS_DIRECTORY = join(SCREENSHOTS_DIRECTORY, 'flows');
+const CONTACT_SHEET = join(SCREENSHOTS_DIRECTORY, 'contact-sheet.png');
+let server;
+export async function setup(project) {
+    const url = process.env['PATTERN_VISUAL_URL'];
+    if (url === undefined) {
+        throw new Error('Visual flows need the dev server: run `app test --visual`');
+    }
+    rmSync(FLOW_SCREENSHOTS_DIRECTORY, { recursive: true, force: true });
+    rmSync(CONTACT_SHEET, { force: true });
+    mkdirSync(FLOW_SCREENSHOTS_DIRECTORY, { recursive: true });
+    server = await launchChromeServer();
+    project.provide('patternVisualFlows', {
+        url,
+        wsEndpoint: server.wsEndpoint(),
+        directory: FLOW_SCREENSHOTS_DIRECTORY,
+        viewports: viewportNames
+    });
+}
+export async function teardown() {
+    if (server === undefined)
+        return;
+    try {
+        await writeContactSheet(server.wsEndpoint(), FLOW_SCREENSHOTS_DIRECTORY, CONTACT_SHEET);
+    }
+    finally {
+        await server.close();
+    }
+}

package/dist/flows/flows.d.ts

@@ -0,0 +1,47 @@
+import { expect } from 'vitest';
+import type { ApiCall } from '../api.ts';
+import type { AppClass, RunningApp } from '../app.ts';
+import type { Seed, Tables } from '../table.ts';
+export { expect };
+export { accessFlows } from './accessFlows.ts';
+declare module 'vitest' {
+    interface ProvidedContext {
+        patternSeed?: Seed<Tables>;
+        patternAdmins?: readonly string[];
+        patternTitle?: string;
+        patternWorld?: unknown;
+    }
+}
+type Expected<Value> = Value extends readonly (infer Item)[] ? readonly Expected<Item>[] : Value extends object ? {
+    [Key in keyof Value]?: Expected<Value[Key]>;
+} : Value;
+export type FlowStep<Command, Snapshot, Call extends string> = {
+    send: Command;
+} | {
+    expect: Expected<Snapshot> & object;
+} | {
+    screenshot: string;
+} | {
+    hold: Call;
+} | {
+    release: Call;
+} | {
+    restart: true;
+} | {
+    tick: true;
+} | {
+    world: object;
+};
+export type FlowOptions<Call extends string> = {
+    startAt?: string;
+    failing?: readonly Call[];
+    signedInAs?: string | null;
+};
+export type FlowBinding<Group extends Tables, Command, Snapshot extends {
+    readonly path: string;
+}> = {
+    App: AppClass<Group, RunningApp<Command, Snapshot>>;
+};
+export declare function defineFlow<Group extends Tables, Command, Snapshot extends {
+    readonly path: string;
+}>({ App }: FlowBinding<Group, Command, Snapshot>): (name: string, steps: readonly FlowStep<Command, Snapshot, ApiCall<Group>>[], { startAt, failing, signedInAs }?: FlowOptions<ApiCall<Group>>) => void;