@milesroxas/design-hub 0.0.0-stage → 0.1.1

package/dist/core/review/service.d.ts

@@ -0,0 +1,79 @@
+import { type Comment, type Person, type Triage } from './model.ts';
+import { type KV } from './store.ts';
+export type ErrorCode = 'unauthorized' | 'forbidden' | 'not_found' | 'invalid';
+export declare class ReviewError extends Error {
+    code: ErrorCode;
+    problems: string[];
+    constructor(code: ErrorCode, message: string, problems?: string[]);
+}
+export type TriageInput = {
+    body: string;
+    prototype: string;
+    url: string;
+    states: string[];
+};
+/** Classifies a new comment; null when it cannot (TypeSafe off, slow, unsure). */
+export type Triager = (input: TriageInput) => Promise<Triage | null>;
+export type Deps = {
+    now: () => Date;
+    random: (bytes: number) => Uint8Array;
+    triage: Triager | null;
+};
+export declare function createReview(kv: KV, overrides?: Partial<Deps>): {
+    person: (id: string) => Promise<Person | null>;
+    /** The person a signed session names, if they still may sign in with it. */
+    sessionPerson(id: string, epoch: number): Promise<Person | null>;
+    listPeople(actor: Person | null): Promise<Person[]>;
+    invite(actor: Person | null, input: unknown): Promise<{
+        person: Person;
+        token: string;
+    }>;
+    /** A fresh link for someone; their old link and every session they hold stop working. */
+    reissue(actor: Person | null, id: string): Promise<{
+        person: Person;
+        token: string;
+    }>;
+    revoke(actor: Person | null, id: string): Promise<Person>;
+    /** The person an invite token names, while the invite is current and they are not revoked. */
+    acceptInvite(token: string): Promise<Person | null>;
+    listComments(actor: Person | null, prototype: string): Promise<Comment[]>;
+    /** Every comment on every prototype, for the CLI, which holds the store's own credentials. */
+    allComments(): Promise<Comment[]>;
+    add(actor: Person | null, input: {
+        body?: unknown;
+        anchor?: unknown;
+        states?: unknown;
+    }): Promise<Comment>;
+    reply(actor: Person | null, input: {
+        prototype: string;
+        thread: string;
+        body?: unknown;
+    }): Promise<Comment>;
+    edit(actor: Person | null, input: {
+        prototype: string;
+        id: string;
+        body?: unknown;
+    }): Promise<Comment>;
+    /** Deletes a comment; deleting a thread's root deletes its replies with it. */
+    remove(actor: Person | null, input: {
+        prototype: string;
+        id: string;
+    }): Promise<string[]>;
+    resolve(actor: Person | null, input: {
+        prototype: string;
+        id: string;
+        resolved: boolean;
+    }): Promise<Comment>;
+    retriage(actor: Person | null, input: {
+        prototype: string;
+        id: string;
+        triage?: unknown;
+        states?: unknown;
+    }): Promise<Comment>;
+    /** Where a comment lives, for the CLI, which has an id and no prototype. */
+    locate(id: string): Promise<{
+        prototype: string;
+        comment: Comment;
+    } | null>;
+};
+export type Review = ReturnType<typeof createReview>;

package/dist/core/review/service.js

@@ -0,0 +1,245 @@
+// The review use cases over the storage port. Every adapter (the Vercel
+// function, the Vite dev server, the CLI) builds one of these and calls it;
+// none of them touches the store directly, so the rules in model.ts and
+// policy.ts hold everywhere. Writes are per record (one hash field per
+// person, per comment), so two people commenting at once never collide;
+// two edits of the same comment at once keep the last.
+import { base64url, hex, sha256 } from '../bytes.js';
+import { authorOf, checkAnchor, checkBody, checkPersonInput, checkStates, checkTriage, INVITE_DAYS, isRoot, } from './model.js';
+import { can } from './policy.js';
+import { KEY } from './store.js';
+export class ReviewError extends Error {
+    code;
+    problems;
+    constructor(code, message, problems = []) {
+        super(message);
+        this.code = code;
+        this.problems = problems;
+    }
+}
+const DAY_MS = 86_400_000;
+const defaults = {
+    now: () => new Date(),
+    random: (n) => crypto.getRandomValues(new Uint8Array(n)),
+    triage: null,
+};
+export function createReview(kv, overrides = {}) {
+    const deps = { ...defaults, ...overrides };
+    const now = () => deps.now().toISOString();
+    // Sortable by time, unique without coordination.
+    const newId = () => `${deps.now().getTime().toString(36).padStart(9, '0')}${hex(deps.random(5))}`;
+    const parse = (json) => (json === null ? null : JSON.parse(json));
+    function allow(actor, action, subject) {
+        if (!actor)
+            throw new ReviewError('unauthorized', 'Sign in with an invite link to do that.');
+        if (!can(actor, action, subject))
+            throw new ReviewError('forbidden', 'You cannot do that.');
+    }
+    function valid(checked) {
+        if (!checked.ok)
+            throw new ReviewError('invalid', 'Some fields are not valid.', checked.problems);
+        return checked.value;
+    }
+    // Every field checked before any throws, so one save names every problem.
+    function validAll(a, b) {
+        const problems = [...(a.ok ? [] : a.problems), ...(b.ok ? [] : b.problems)];
+        if (!a.ok || !b.ok)
+            throw new ReviewError('invalid', 'Some fields are not valid.', problems);
+        return [a.value, b.value];
+    }
+    const person = async (id) => parse(await kv.hget(KEY.people, id));
+    const savePerson = (p) => kv.hset(KEY.people, p.id, JSON.stringify(p));
+    async function issueInvite(p) {
+        // The link carries the token; the store keeps only its hash, so a leaked store signs nobody in.
+        const token = base64url(deps.random(32));
+        const invite = {
+            person: p.id,
+            expiresAt: new Date(deps.now().getTime() + INVITE_DAYS * DAY_MS).toISOString(),
+        };
+        await kv.hset(KEY.invites, hex(await sha256(token)), JSON.stringify(invite));
+        return token;
+    }
+    async function dropInvites(personId) {
+        const all = await kv.hgetall(KEY.invites);
+        for (const [hash, json] of Object.entries(all))
+            if (JSON.parse(json).person === personId)
+                await kv.hdel(KEY.invites, hash);
+    }
+    async function needPerson(id) {
+        const p = await person(id);
+        if (!p)
+            throw new ReviewError('not_found', 'No such person.');
+        return p;
+    }
+    const commentsOf = async (prototype) => Object.values(await kv.hgetall(KEY.comments(prototype)))
+        .map((json) => JSON.parse(json))
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt) || a.id.localeCompare(b.id));
+    const saveComment = (prototype, c) => kv.hset(KEY.comments(prototype), c.id, JSON.stringify(c));
+    async function needComment(prototype, id) {
+        const c = parse(await kv.hget(KEY.comments(prototype), id));
+        if (!c)
+            throw new ReviewError('not_found', 'No such comment.');
+        return c;
+    }
+    async function needRoot(prototype, id) {
+        const c = await needComment(prototype, id);
+        if (!isRoot(c))
+            throw new ReviewError('invalid', 'That is a reply; act on its thread.');
+        return c;
+    }
+    return {
+        person,
+        /** The person a signed session names, if they still may sign in with it. */
+        async sessionPerson(id, epoch) {
+            const p = await person(id);
+            return p && !p.revokedAt && p.epoch === epoch ? p : null;
+        },
+        async listPeople(actor) {
+            allow(actor, 'people');
+            const all = Object.values(await kv.hgetall(KEY.people)).map((j) => JSON.parse(j));
+            return all.sort((a, b) => a.team.localeCompare(b.team) || a.name.localeCompare(b.name));
+        },
+        async invite(actor, input) {
+            allow(actor, 'people');
+            const p = {
+                id: newId(),
+                ...valid(checkPersonInput(input)),
+                createdAt: now(),
+                revokedAt: null,
+                epoch: 0,
+            };
+            await savePerson(p);
+            return { person: p, token: await issueInvite(p) };
+        },
+        /** A fresh link for someone; their old link and every session they hold stop working. */
+        async reissue(actor, id) {
+            allow(actor, 'people');
+            const p = await needPerson(id);
+            if (p.revokedAt)
+                throw new ReviewError('invalid', 'That person is revoked; invite them again.');
+            const next = { ...p, epoch: p.epoch + 1 };
+            await dropInvites(id);
+            await savePerson(next);
+            return { person: next, token: await issueInvite(next) };
+        },
+        async revoke(actor, id) {
+            allow(actor, 'people');
+            if (actor.id === id)
+                throw new ReviewError('invalid', 'You cannot revoke yourself.');
+            const p = await needPerson(id);
+            const next = { ...p, revokedAt: p.revokedAt ?? now(), epoch: p.epoch + 1 };
+            await dropInvites(id);
+            await savePerson(next);
+            return next;
+        },
+        /** The person an invite token names, while the invite is current and they are not revoked. */
+        async acceptInvite(token) {
+            if (!/^[\w-]{20,100}$/.test(token))
+                return null;
+            const invite = parse(await kv.hget(KEY.invites, hex(await sha256(token))));
+            if (!invite || invite.expiresAt <= now())
+                return null;
+            const p = await person(invite.person);
+            return p && !p.revokedAt ? p : null;
+        },
+        async listComments(actor, prototype) {
+            allow(actor, 'read');
+            return commentsOf(prototype);
+        },
+        /** Every comment on every prototype, for the CLI, which holds the store's own credentials. */
+        async allComments() {
+            const prototypes = await kv.smembers(KEY.prototypes);
+            return (await Promise.all(prototypes.map(commentsOf))).flat();
+        },
+        async add(actor, input) {
+            allow(actor, 'comment');
+            const [body, anchor] = validAll(checkBody(input.body), checkAnchor(input.anchor));
+            const id = newId();
+            const triage = deps.triage
+                ? await deps
+                    .triage({ body, prototype: anchor.prototype, url: anchor.url, states: checkStates(input.states) })
+                    // Triage is a convenience; a triager that throws never costs the comment.
+                    .catch(() => null)
+                : null;
+            const c = {
+                id,
+                thread: id,
+                author: authorOf(actor),
+                body,
+                createdAt: now(),
+                editedAt: null,
+                anchor,
+                status: 'open',
+                resolvedBy: null,
+                triage,
+            };
+            await kv.sadd(KEY.prototypes, anchor.prototype);
+            await saveComment(anchor.prototype, c);
+            return c;
+        },
+        async reply(actor, input) {
+            allow(actor, 'comment');
+            const root = await needRoot(input.prototype, input.thread);
+            const id = newId();
+            const c = {
+                id,
+                thread: root.id,
+                author: authorOf(actor),
+                body: valid(checkBody(input.body)),
+                createdAt: now(),
+                editedAt: null,
+                anchor: null,
+                status: 'open',
+                resolvedBy: null,
+                triage: null,
+            };
+            await saveComment(input.prototype, c);
+            return c;
+        },
+        async edit(actor, input) {
+            const c = await needComment(input.prototype, input.id);
+            allow(actor, 'edit', c);
+            const next = { ...c, body: valid(checkBody(input.body)), editedAt: now() };
+            await saveComment(input.prototype, next);
+            return next;
+        },
+        /** Deletes a comment; deleting a thread's root deletes its replies with it. */
+        async remove(actor, input) {
+            const c = await needComment(input.prototype, input.id);
+            allow(actor, 'delete', c);
+            const gone = isRoot(c)
+                ? (await commentsOf(input.prototype)).filter((x) => x.thread === c.id).map((x) => x.id)
+                : [c.id];
+            for (const id of gone)
+                await kv.hdel(KEY.comments(input.prototype), id);
+            return gone;
+        },
+        async resolve(actor, input) {
+            const c = await needRoot(input.prototype, input.id);
+            allow(actor, 'resolve', c);
+            const next = input.resolved
+                ? { ...c, status: 'resolved', resolvedBy: authorOf(actor) }
+                : { ...c, status: 'open', resolvedBy: null };
+            await saveComment(input.prototype, next);
+            return next;
+        },
+        async retriage(actor, input) {
+            allow(actor, 'triage');
+            const c = await needRoot(input.prototype, input.id);
+            const states = checkStates(input.states);
+            const { kind, state } = valid(checkTriage(input.triage, states.length ? states : null));
+            const next = { ...c, triage: { kind, state, by: 'person', confidence: null } };
+            await saveComment(input.prototype, next);
+            return next;
+        },
+        /** Where a comment lives, for the CLI, which has an id and no prototype. */
+        async locate(id) {
+            for (const prototype of await kv.smembers(KEY.prototypes)) {
+                const c = parse(await kv.hget(KEY.comments(prototype), id));
+                if (c)
+                    return { prototype, comment: c };
+            }
+            return null;
+        },
+    };
+}

package/dist/core/review/store.d.ts

@@ -0,0 +1,20 @@
+export interface KV {
+    hget(key: string, field: string): Promise<string | null>;
+    hset(key: string, field: string, value: string): Promise<void>;
+    hdel(key: string, field: string): Promise<void>;
+    hgetall(key: string): Promise<Record<string, string>>;
+    sadd(key: string, member: string): Promise<void>;
+    smembers(key: string): Promise<string[]>;
+}
+/** Every key the hub writes starts here, so a shared Redis never mixes it with another app's data. */
+export declare const KEY: {
+    readonly people: 'hub:people';
+    readonly invites: 'hub:invites';
+    readonly prototypes: 'hub:prototypes';
+    readonly comments: (prototype: string) => string;
+};
+export type Snapshot = {
+    hashes: Record<string, Record<string, string>>;
+    sets: Record<string, string[]>;
+};
+export declare function memoryKV(initial?: Snapshot, onChange?: (s: Snapshot) => void): KV;

package/dist/core/review/store.js

@@ -0,0 +1,37 @@
+// The one storage port the review service needs: a few Redis-shaped hash
+// and set operations. Production is Upstash Redis over REST
+// (server/upstash.ts); dev and tests use the in-memory store below, which
+// the dev server persists to a file (server/file-kv.ts).
+/** Every key the hub writes starts here, so a shared Redis never mixes it with another app's data. */
+export const KEY = {
+    people: 'hub:people',
+    invites: 'hub:invites',
+    prototypes: 'hub:prototypes',
+    comments: (prototype) => `hub:comments:${prototype}`,
+};
+export function memoryKV(initial = { hashes: {}, sets: {} }, onChange) {
+    const hashes = new Map(Object.entries(initial.hashes).map(([k, v]) => [k, new Map(Object.entries(v))]));
+    const sets = new Map(Object.entries(initial.sets).map(([k, v]) => [k, new Set(v)]));
+    const changed = () => onChange?.({
+        hashes: Object.fromEntries([...hashes].map(([k, v]) => [k, Object.fromEntries(v)])),
+        sets: Object.fromEntries([...sets].map(([k, v]) => [k, [...v]])),
+    });
+    const hash = (key) => hashes.get(key) ?? hashes.set(key, new Map()).get(key);
+    return {
+        hget: async (key, field) => hashes.get(key)?.get(field) ?? null,
+        hset: async (key, field, value) => {
+            hash(key).set(field, value);
+            changed();
+        },
+        hdel: async (key, field) => {
+            hashes.get(key)?.delete(field);
+            changed();
+        },
+        hgetall: async (key) => Object.fromEntries(hashes.get(key) ?? []),
+        sadd: async (key, member) => {
+            (sets.get(key) ?? sets.set(key, new Set()).get(key)).add(member);
+            changed();
+        },
+        smembers: async (key) => [...(sets.get(key) ?? [])],
+    };
+}

package/dist/core/review/triage.d.ts

@@ -0,0 +1,6 @@
+import type { Checks } from '../checks.ts';
+import { askJev } from '../jev.ts';
+import type { Triager } from './service.ts';
+type Ask = typeof askJev;
+export declare function jevTriager(apiKey: string, checks: Checks | null, ask?: Ask): Triager | null;
+export {};

package/dist/core/review/triage.js

@@ -0,0 +1,45 @@
+import { askJev, choiceOf } from '../jev.js';
+const KIND_CRITERIA = {
+    bug: 'Something is broken or wrong: it does not work, shows the wrong thing, or the layout breaks.',
+    taste: 'A design opinion about look, feel, motion, spacing or hierarchy, where nothing is broken.',
+    copy: 'About the words: a typo, a label, wording or content to change.',
+};
+export function jevTriager(apiKey, checks, ask = askJev) {
+    if (!apiKey || !checks)
+        return null;
+    const { model, timeoutMs } = checks.jev;
+    const at = checks.triage.at;
+    return async ({ body, prototype, url, states }) => {
+        const questions = {
+            kind: {
+                type: 'choice',
+                instructions: 'What kind of review note is `comment`?',
+                criteria: KIND_CRITERIA,
+            },
+        };
+        if (states.length)
+            questions.state = {
+                type: 'choice',
+                instructions: 'Which state of the prototype is `comment` about? `url` is where the reviewer was.',
+                criteria: Object.fromEntries(states.map((s) => [s, null])),
+            };
+        const result = await ask(apiKey, { model, state: { comment: body, prototype, url }, questions }, { timeoutMs });
+        if (!result.ok)
+            return null;
+        const pick = (key) => {
+            const c = choiceOf(result.answers, key);
+            return c && at !== null && c.confidence >= at ? c : null;
+        };
+        const kind = pick('kind');
+        const state = pick('state');
+        if (!kind && !state)
+            return null;
+        const triage = {
+            kind: kind?.choice ?? null,
+            state: state?.choice ?? null,
+            by: 'jev',
+            confidence: Math.min(kind?.confidence ?? 1, state?.confidence ?? 1),
+        };
+        return triage;
+    };
+}

package/dist/core/states.d.ts

@@ -0,0 +1,6 @@
+export type State = {
+    name: string;
+    reach: string;
+};
+/** The states listed in a README, or null when it has no States section. */
+export declare function parseStates(readme: string): State[] | null;

package/dist/core/states.js

@@ -0,0 +1,29 @@
+// A prototype README's `## States` table: one row per state the prototype
+// holds, the first cell its name and the second how a reviewer reaches it.
+// The fidelity guard, the pre-flight, comment triage and `miles-port` all
+// read states through this one parser, so they never disagree on the list.
+const HEADING = /^##\s+States\s*$/m;
+const NEXT_HEADING = /^#{1,2}\s/m;
+const SEPARATOR = /^\|\s*:?-{3,}/;
+const cells = (row) => row
+    .trim()
+    .replace(/^\||\|$/g, '')
+    .split('|')
+    .map((c) => c.trim());
+/** The states listed in a README, or null when it has no States section. */
+export function parseStates(readme) {
+    const start = readme.search(HEADING);
+    if (start < 0)
+        return null;
+    const rest = readme.slice(start).replace(HEADING, '');
+    const end = rest.search(NEXT_HEADING);
+    const section = end < 0 ? rest : rest.slice(0, end);
+    const rows = section.split('\n').filter((l) => l.trim().startsWith('|'));
+    // The first row is the header, whatever it says; the separator follows it.
+    return rows
+        .slice(1)
+        .filter((r) => !SEPARATOR.test(r.trim()))
+        .map(cells)
+        .map(([name = '', reach = '']) => ({ name, reach }))
+        .filter((s) => s.name !== '');
+}

package/dist/scripts/bootstrap.d.ts

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { type Args } from './lib/cli.ts';
+export declare const spec: {
+    readonly name: 'bootstrap';
+    readonly summary: 'Set the project up on this machine, and optionally on Vercel. Safe to run again.';
+    readonly flags: {
+        readonly port: {
+            readonly type: 'number';
+            readonly description: 'Use this port. Refused when another process holds it or another project claims it.';
+        };
+        readonly 'no-install': {
+            readonly type: 'boolean';
+            readonly description: 'Skip pnpm install.';
+        };
+        readonly 'typesafe-key': {
+            readonly type: 'string';
+            readonly description: "Turn TypeSafe's Jev checks on with this API key.";
+        };
+        readonly conductor: {
+            readonly type: 'boolean';
+            readonly description: 'Write .conductor/settings.toml for Conductor workspaces.';
+        };
+        readonly branch: {
+            readonly type: 'string';
+            readonly default: 'main';
+            readonly description: 'The branch Conductor workspaces land on.';
+        };
+        readonly vercel: {
+            readonly type: 'string';
+            readonly description: 'Link this Vercel project and set the password gate env on it.';
+        };
+        readonly 'gate-password': {
+            readonly type: 'string';
+            readonly description: 'The share password (8+ characters). Given again, it rotates.';
+        };
+        readonly review: {
+            readonly type: 'boolean';
+            readonly description: 'Provision the review store (Upstash Redis) on the Vercel project.';
+        };
+    };
+    readonly output: '{ ok, node, port, install, typesafe, conductor?, vercel?, share?, review?, warnings }';
+};
+/** The gate's values: the password given, kept, or made, and the secret kept or made. */
+export declare function gateValues(given: string | undefined, env: Record<string, string>): {
+    password: string;
+    secret: string;
+    rotated: boolean;
+};
+export declare function main({ flags }: Args<typeof spec>): {
+    warnings: string[];
+};