@milesroxas/design-hub 0.0.0-stage → 0.1.0

package/dist/server/env.js

@@ -0,0 +1,57 @@
+/// <reference types="node" />
+// The project's .env as key: value pairs, for the scripts and the dev server.
+// Vite reads the same file on its own (vite.config.ts). No dotenv:
+// the file is a flat list and a dependency for it would be the kind of
+// gravity this repo avoids.
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+const ENV_FILE = '.env';
+export function readEnv(dir) {
+    const file = join(dir, ENV_FILE);
+    if (!existsSync(file))
+        return {};
+    const env = {};
+    for (const raw of readFileSync(file, 'utf8').split('\n')) {
+        const line = raw.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const at = line.indexOf('=');
+        if (at <= 0)
+            continue;
+        env[line.slice(0, at).trim()] = line
+            .slice(at + 1)
+            .trim()
+            .replace(/^(["'])(.*)\1$/, '$2');
+    }
+    return env;
+}
+// Rewrites one key in place and keeps every other line, comments included,
+// so a second run changes nothing.
+export function writeEnv(dir, updates) {
+    const file = join(dir, ENV_FILE);
+    const lines = existsSync(file) ? readFileSync(file, 'utf8').split('\n') : [];
+    const pending = { ...updates };
+    const next = lines.map((line) => {
+        const key = line.match(/^\s*([A-Z0-9_]+)\s*=/)?.[1];
+        if (!key || !(key in pending))
+            return line;
+        const value = pending[key];
+        delete pending[key];
+        return `${key}=${value}`;
+    });
+    while (next.length && next.at(-1)?.trim() === '')
+        next.pop();
+    for (const [key, value] of Object.entries(pending))
+        next.push(`${key}=${value}`);
+    const text = next.join('\n').replace(/\n*$/, '\n');
+    writeFileSync(file, text, { mode: 0o600 });
+}
+/**
+ * The dev server's port. Inside a Conductor workspace, Conductor's own port
+ * wins, because its Open button always points there; everywhere else it is
+ * the PORT that `pnpm bootstrap` wrote to .env.
+ */
+export function devPort(fileEnv, processEnv = process.env) {
+    const port = Number(processEnv.CONDUCTOR_PORT || fileEnv.PORT);
+    return Number.isInteger(port) && port > 0 ? port : undefined;
+}

package/dist/server/fake-upstash.d.ts

@@ -0,0 +1 @@
+export declare function fakeUpstash(): typeof fetch;

package/dist/server/fake-upstash.js

@@ -0,0 +1,37 @@
+/// <reference types="node" />
+// A fetch that answers like Upstash's REST API from memory, for tests that
+// exercise the deployed code path (proxy.ts, api/review.ts) without an account.
+import { memoryKV } from '../core/review/store.js';
+export function fakeUpstash() {
+    const kv = memoryKV();
+    async function run(cmd, [key, a, b]) {
+        switch (cmd) {
+            case 'HGET':
+                return kv.hget(key, a);
+            case 'HSET':
+                await kv.hset(key, a, b);
+                return 1;
+            case 'HDEL':
+                await kv.hdel(key, a);
+                return 1;
+            case 'HGETALL':
+                return Object.entries(await kv.hgetall(key)).flat();
+            case 'SADD':
+                await kv.sadd(key, a);
+                return 1;
+            case 'SMEMBERS':
+                return kv.smembers(key);
+            default:
+                throw new Error(`unknown command ${cmd}`);
+        }
+    }
+    return (async (_url, init) => {
+        const [cmd, ...args] = JSON.parse(String(init?.body));
+        try {
+            return new Response(JSON.stringify({ result: await run(cmd, args) }));
+        }
+        catch (error) {
+            return new Response(JSON.stringify({ error: String(error) }), { status: 400 });
+        }
+    });
+}

package/dist/server/file-kv.d.ts

@@ -0,0 +1,2 @@
+import { type KV } from '../core/review/store.ts';
+export declare function fileKV(file: string): KV;

package/dist/server/file-kv.js

@@ -0,0 +1,24 @@
+/// <reference types="node" />
+// The review store on this machine: the in-memory store, saved to
+// .design-hub/review.json after every write. The dev server and the CLI's
+// --local use it, so the review UI works with no account and no network.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { memoryKV } from '../core/review/store.js';
+export function fileKV(file) {
+    let initial = { hashes: {}, sets: {} };
+    if (existsSync(file)) {
+        try {
+            initial = JSON.parse(readFileSync(file, 'utf8'));
+        }
+        catch {
+            throw new Error(`${file} is not valid JSON. Fix or delete it; it holds the local review data.`);
+        }
+    }
+    return memoryKV(initial, (snapshot) => {
+        mkdirSync(dirname(file), { recursive: true });
+        const tmp = `${file}.${process.pid}.tmp`;
+        writeFileSync(tmp, `${JSON.stringify(snapshot, null, 2)}\n`);
+        renameSync(tmp, file);
+    });
+}

package/dist/server/local.d.ts

@@ -0,0 +1,4 @@
+import type { Person } from '../core/review/model.ts';
+export declare const LOCAL_STORE: string;
+/** Whoever runs this machine's dev server or CLI: an editor, because they hold the store itself. */
+export declare const localEditor: (id?: string, team?: string) => Person;

package/dist/server/local.js

@@ -0,0 +1,25 @@
+/// <reference types="node" />
+// The review store and identity on this machine, shared by the dev server
+// and the CLI: .design-hub/review.json, and a local editor named from git.
+import { execFileSync } from 'node:child_process';
+import { join } from 'node:path';
+import { STATE_DIR } from './paths.js';
+export const LOCAL_STORE = join(STATE_DIR, 'review.json');
+function gitName() {
+    try {
+        return execFileSync('git', ['config', 'user.name'], { encoding: 'utf8' }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+/** Whoever runs this machine's dev server or CLI: an editor, because they hold the store itself. */
+export const localEditor = (id = 'local', team = 'Local') => ({
+    id,
+    name: gitName() || 'You',
+    team,
+    role: 'editor',
+    createdAt: new Date(0).toISOString(),
+    revokedAt: null,
+    epoch: 0,
+});

package/dist/server/paths.d.ts

@@ -0,0 +1,22 @@
+/** The project folder for a path inside it, or null when no ancestor installed design-hub. */
+export declare function findProject(from: string): string | null;
+/** The project: $DESIGN_HUB_ROOT, else the nearest project above the working directory, else the working directory. */
+export declare function projectRoot(env?: Record<string, string | undefined>, cwd?: string): string;
+export declare const ROOT: string;
+/** One folder per prototype. */
+export declare const PROTOTYPES: string;
+/** The project's materials: tokens, the shell's chrome, its icons. */
+export declare const KIT: string;
+export declare const DOCS: string;
+export declare const SKILLS: string;
+/** Local state, gitignored but for checks.json: the Jev log and its labels, the dev review store. */
+export declare const STATE_DIR: string;
+export declare const CHECKS_FILE: string;
+/** The nearest ancestor of `from` whose package.json names this package, so source and dist agree. */
+export declare function packageRoot(from: string): string;
+/** This package on disk, wherever it is installed: the shell, the kit, the templates, the skills. */
+export declare const PACKAGE: string;
+export declare const SHELL: string;
+export declare const PACKAGE_KIT: string;
+export declare const TEMPLATES: string;
+export declare const PACKAGE_SKILLS: string;

package/dist/server/paths.js

@@ -0,0 +1,81 @@
+/// <reference types="node" />
+// Where things are, computed once. The project is the folder that installed
+// design-hub: the nearest ancestor of the working directory whose package.json
+// depends on it, or $DESIGN_HUB_ROOT. The scripts, the hooks and the dev
+// server resolve every path from here, never from the current directory, so a
+// hook run from the repo root and a script run from a subfolder behave the same.
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const DEP = '@milesroxas/design-hub';
+function dependsOnHub(dir) {
+    const file = join(dir, 'package.json');
+    if (!existsSync(file))
+        return false;
+    try {
+        const pkg = JSON.parse(readFileSync(file, 'utf8'));
+        return Boolean(pkg.dependencies?.[DEP] ?? pkg.devDependencies?.[DEP]);
+    }
+    catch {
+        return false;
+    }
+}
+/** The project folder for a path inside it, or null when no ancestor installed design-hub. */
+export function findProject(from) {
+    let dir = resolve(from);
+    for (;;) {
+        if (dependsOnHub(dir))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** The project: $DESIGN_HUB_ROOT, else the nearest project above the working directory, else the working directory. */
+export function projectRoot(env = process.env, cwd = process.cwd()) {
+    const root = env.DESIGN_HUB_ROOT ? resolve(env.DESIGN_HUB_ROOT) : (findProject(cwd) ?? resolve(cwd));
+    // Real, so a file path a hook hands over compares with it whatever symlink it came through.
+    try {
+        return realpathSync(root);
+    }
+    catch {
+        return root;
+    }
+}
+export const ROOT = projectRoot();
+/** One folder per prototype. */
+export const PROTOTYPES = join(ROOT, 'prototypes');
+/** The project's materials: tokens, the shell's chrome, its icons. */
+export const KIT = join(ROOT, 'kit');
+export const DOCS = join(ROOT, 'docs');
+export const SKILLS = join(ROOT, '.claude', 'skills');
+/** Local state, gitignored but for checks.json: the Jev log and its labels, the dev review store. */
+export const STATE_DIR = join(ROOT, '.design-hub');
+export const CHECKS_FILE = join(STATE_DIR, 'checks.json');
+/** The nearest ancestor of `from` whose package.json names this package, so source and dist agree. */
+export function packageRoot(from) {
+    let dir = dirname(from);
+    for (;;) {
+        const file = join(dir, 'package.json');
+        if (existsSync(file)) {
+            try {
+                if (JSON.parse(readFileSync(file, 'utf8')).name === DEP)
+                    return dir;
+            }
+            catch {
+                // Not ours; keep climbing.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            throw new Error(`design-hub's package.json is not above ${from}.`);
+        dir = parent;
+    }
+}
+/** This package on disk, wherever it is installed: the shell, the kit, the templates, the skills. */
+export const PACKAGE = packageRoot(fileURLToPath(import.meta.url));
+export const SHELL = join(PACKAGE, 'shell');
+export const PACKAGE_KIT = join(PACKAGE, 'kit');
+export const TEMPLATES = join(PACKAGE, 'templates');
+export const PACKAGE_SKILLS = join(PACKAGE, 'skills');

package/dist/server/session.d.ts

@@ -0,0 +1,22 @@
+export declare const GATE_COOKIE = "__Host-hub_gate";
+export declare const PERSON_COOKIE = "__Host-hub_person";
+export type Gate = {
+    password: string;
+    secret: string;
+};
+/** The gate's settings, or null when either is missing (the gate then fails closed). */
+export declare function readGate(env: Record<string, string | undefined>): Gate | null;
+export declare function passwordMatches(gate: Gate, submitted: string): Promise<boolean>;
+export declare function issueGateToken(gate: Gate): Promise<string>;
+export declare function gateTokenIsValid(gate: Gate, token: string | undefined): Promise<boolean>;
+export type PersonClaim = {
+    id: string;
+    epoch: number;
+};
+export declare function issuePersonToken(gate: Gate, claim: PersonClaim): Promise<string>;
+/** The person a token names when its signature and expiry hold; the caller still checks the store. */
+export declare function readPersonToken(gate: Gate, token: string | undefined): Promise<PersonClaim | null>;
+export declare function readCookie(request: Request, name: string): string | undefined;
+export declare const sessionCookie: (name: string, value: string) => string;
+export declare const clearedCookie: (name: string) => string;
+export declare function sameOrigin(request: Request): boolean;

package/dist/server/session.js

@@ -0,0 +1,110 @@
+// Signed cookies for the deployed prototypes, on Web Crypto only, so the
+// gate (proxy.ts), the review function (api/review.ts) and their tests share
+// one implementation. Two sessions:
+//
+//   gate     the shared password was typed: view everything, comment on nothing.
+//            The signature covers the password, so rotating it signs everyone out.
+//   person   an invite link was opened: view everything, and comment as that
+//            person. The signature covers the person's epoch, which a reissue
+//            or revoke bumps, so either ends every session they hold.
+//
+// Both are HMAC-SHA256 with GATE_SECRET and last 30 days.
+import { base64url, sha256 } from '../core/bytes.js';
+export const GATE_COOKIE = '__Host-hub_gate';
+export const PERSON_COOKIE = '__Host-hub_person';
+const SESSION_SECONDS = 60 * 60 * 24 * 30;
+/** The gate's settings, or null when either is missing (the gate then fails closed). */
+export function readGate(env) {
+    const password = env.GATE_PASSWORD ?? '';
+    const secret = env.GATE_SECRET ?? '';
+    return password.length > 0 && secret.length >= 32 ? { password, secret } : null;
+}
+const encoder = new TextEncoder();
+async function hmac(secret, message) {
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return base64url(new Uint8Array(await crypto.subtle.sign('HMAC', key, encoder.encode(message))));
+}
+// Runs over every byte whatever the input, so a mismatch costs the same time
+// wherever it falls. Callers pass equal-length digests, so length is not a leak.
+function timingSafeEqual(a, b) {
+    let diff = a.length ^ b.length;
+    for (let i = 0; i < a.length; i++)
+        diff |= a[i] ^ (b[i % b.length] ?? 0);
+    return diff === 0;
+}
+const sameText = (a, b) => timingSafeEqual(encoder.encode(a), encoder.encode(b));
+const nowSeconds = () => Math.floor(Date.now() / 1000);
+const live = (expires) => Number.isInteger(expires) && expires > nowSeconds();
+export async function passwordMatches(gate, submitted) {
+    const [a, b] = await Promise.all([sha256(submitted), sha256(gate.password)]);
+    return timingSafeEqual(a, b);
+}
+// A gate session token: <expires>.<sig>
+async function gateSignature(gate, expires) {
+    return hmac(gate.secret, `v1.${expires}.${base64url(await sha256(gate.password))}`);
+}
+export async function issueGateToken(gate) {
+    const expires = nowSeconds() + SESSION_SECONDS;
+    return `${expires}.${await gateSignature(gate, expires)}`;
+}
+export async function gateTokenIsValid(gate, token) {
+    const [expires, sig, extra] = (token ?? '').split('.');
+    if (!sig || extra !== undefined || !live(Number(expires)))
+        return false;
+    return sameText(sig, await gateSignature(gate, Number(expires)));
+}
+const personMessage = (id, epoch, expires) => `p1.${id}.${epoch}.${expires}`;
+export async function issuePersonToken(gate, claim) {
+    const expires = nowSeconds() + SESSION_SECONDS;
+    return `${claim.id}.${claim.epoch}.${expires}.${await hmac(gate.secret, personMessage(claim.id, claim.epoch, expires))}`;
+}
+/** The person a token names when its signature and expiry hold; the caller still checks the store. */
+export async function readPersonToken(gate, token) {
+    const [id, epochText, expiresText, sig, extra] = (token ?? '').split('.');
+    const epoch = Number(epochText);
+    const expires = Number(expiresText);
+    if (!id ||
+        !sig ||
+        extra !== undefined ||
+        !/^[a-z0-9]+$/.test(id) ||
+        !Number.isInteger(epoch) ||
+        !live(expires))
+        return null;
+    return sameText(sig, await hmac(gate.secret, personMessage(id, epoch, expires))) ? { id, epoch } : null;
+}
+export function readCookie(request, name) {
+    const header = request.headers.get('cookie');
+    if (!header)
+        return undefined;
+    for (const part of header.split(';')) {
+        const eq = part.indexOf('=');
+        if (eq > 0 && part.slice(0, eq).trim() === name)
+            return part.slice(eq + 1).trim();
+    }
+    return undefined;
+}
+export const sessionCookie = (name, value) => `${name}=${value}; Path=/; Max-Age=${SESSION_SECONDS}; HttpOnly; Secure; SameSite=Lax`;
+export const clearedCookie = (name) => `${name}=; Path=/; Max-Age=0; HttpOnly; Secure; SameSite=Lax`;
+// Same-origin check for a state-changing request. Sec-Fetch-Site is the
+// browser's own verdict; Origin backs it up for browsers without it. Host
+// comes from the forwarded header, since request.url carries the deployment
+// host behind a custom domain. A browser sends "Origin: null" on a navigation
+// from a no-referrer document, so null is accepted only with a same-origin verdict.
+export function sameOrigin(request) {
+    const site = request.headers.get('sec-fetch-site');
+    if (site && site !== 'same-origin')
+        return false;
+    const origin = request.headers.get('origin');
+    if (!origin)
+        return true;
+    if (origin === 'null')
+        return site === 'same-origin';
+    const host = request.headers.get('x-forwarded-host') ?? request.headers.get('host') ?? new URL(request.url).host;
+    try {
+        const o = new URL(origin);
+        return (o.protocol === 'https:' || o.hostname === 'localhost') && o.host === host;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/server/upstash.d.ts

@@ -0,0 +1,7 @@
+import type { KV } from '../core/review/store.ts';
+export type StoreConfig = {
+    url: string;
+    token: string;
+};
+export declare function storeConfig(env: Record<string, string | undefined>): StoreConfig | null;
+export declare function upstashKV({ url, token }: StoreConfig, fetcher?: typeof fetch): KV;

package/dist/server/upstash.js

@@ -0,0 +1,41 @@
+export function storeConfig(env) {
+    const url = env.KV_REST_API_URL ?? env.UPSTASH_REDIS_REST_URL;
+    const token = env.KV_REST_API_TOKEN ?? env.UPSTASH_REDIS_REST_TOKEN;
+    return url && token ? { url: url.replace(/\/$/, ''), token } : null;
+}
+const TIMEOUT_MS = 5000;
+export function upstashKV({ url, token }, fetcher = fetch) {
+    async function command(...args) {
+        const response = await fetcher(url, {
+            method: 'POST',
+            headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+            body: JSON.stringify(args),
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+        const json = (await response.json().catch(() => ({})));
+        // A reply without `result` is a failure too, never an empty answer the service would trust.
+        if (!response.ok || json.error !== undefined || !('result' in json))
+            throw new Error(`Upstash ${args[0]} failed (${response.status}): ${json.error ?? 'no result in the reply'}`);
+        return json.result;
+    }
+    return {
+        hget: (key, field) => command('HGET', key, field),
+        hset: async (key, field, value) => {
+            await command('HSET', key, field, value);
+        },
+        hdel: async (key, field) => {
+            await command('HDEL', key, field);
+        },
+        hgetall: async (key) => {
+            const flat = (await command('HGETALL', key)) ?? [];
+            const out = {};
+            for (let i = 0; i + 1 < flat.length; i += 2)
+                out[flat[i]] = flat[i + 1];
+            return out;
+        },
+        sadd: async (key, member) => {
+            await command('SADD', key, member);
+        },
+        smembers: async (key) => (await command('SMEMBERS', key)) ?? [],
+    };
+}

package/dist/vercel/index.d.ts

@@ -0,0 +1,5 @@
+export { createProxy, GATE_FONT, gatePreview } from './proxy.ts';
+/** The /api/review function. `checks` is the project's checks.json, so triage runs on the project's thresholds. */
+export declare function reviewFunction(checks?: unknown): {
+    fetch: (request: Request) => Promise<Response>;
+};

package/dist/vercel/index.js

@@ -0,0 +1,12 @@
+// What a project's two Vercel entry files import. Each is one line:
+//
+//   api/review.ts   export default reviewFunction(checks)   with its .design-hub/checks.json
+//   proxy.ts        export default createProxy({ siteName: 'Prototypes' })
+import { loadChecks } from '../core/checks.js';
+import { deployedHandler } from '../server/api.js';
+export { createProxy, GATE_FONT, gatePreview } from './proxy.js';
+/** The /api/review function. `checks` is the project's checks.json, so triage runs on the project's thresholds. */
+export function reviewFunction(checks = null) {
+    const loaded = loadChecks(checks).checks;
+    return { fetch: (request) => deployedHandler(request, loaded) };
+}

package/dist/vercel/proxy.d.ts

@@ -0,0 +1,11 @@
+export declare const GATE_FONT = "/_gate/geist.woff2";
+export declare function gatePreview(failed: boolean, siteName?: string): Promise<{
+    html: string;
+    csp: string;
+}>;
+export type ProxyOptions = {
+    /** The gate page's title: the project's name as reviewers know it. */
+    siteName?: string;
+};
+/** The middleware a project's proxy.ts default-exports. */
+export declare function createProxy({ siteName }?: ProxyOptions): (request: Request) => Promise<Response>;