@milesroxas/design-hub 0.0.0-stage → 0.1.0

package/dist/scripts/hook.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+// `design-hub hook <name>`: the Claude Code hooks a project's
+// .claude/settings.json runs. Each reads the hook's JSON on stdin and fails
+// open: any error exits 0 with nothing said, so a broken hook can never be
+// the reason the user is stuck.
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { guardHook } from './guard.js';
+import { skillHintHook } from './skill-hint.js';
+const MD = /\.md$/i;
+/** PostToolUse on a Markdown file: ask for the writing pass before the change is reported done. */
+export function mdWriting(input) {
+    const file = input.tool_input?.file_path ?? input.tool_response?.filePath ?? '';
+    if (!MD.test(file) || file.includes('/node_modules/'))
+        return null;
+    return {
+        systemMessage: `Markdown changed: ${basename(file)}. Run /emil-writing-skills on it before reporting done.`,
+        hookSpecificOutput: {
+            hookEventName: 'PostToolUse',
+            additionalContext: `You changed the Markdown file ${file}. Before you report this work done, invoke the emil-writing-skills skill (Skill tool, skill: emil-writing-skills) and apply its checklist to that file: every line changes what a reader or agent does, no hedge words, rules carry their why, nothing stale against the current code and decisions, dates and paths it cites still exist. Fix what fails, then say in your reply that the pass ran.`,
+        },
+    };
+}
+export const HOOKS = ['fidelity-guard', 'md-writing', 'skill-hint'];
+export async function runHook(name) {
+    try {
+        switch (name) {
+            case 'fidelity-guard':
+                return await guardHook();
+            case 'skill-hint':
+                return await skillHintHook();
+            case 'md-writing': {
+                const output = mdWriting(JSON.parse(readFileSync(0, 'utf8')));
+                if (output)
+                    console.log(JSON.stringify(output));
+                return;
+            }
+            default:
+                return;
+        }
+    }
+    catch {
+        // Fail open.
+    }
+}

package/dist/scripts/lib/bin.d.ts

@@ -0,0 +1,4 @@
+/** The folder of an installed package, searched the way Node searches, so an exports map never hides it. */
+export declare function packageDir(name: string): string;
+export declare const tscBin: () => string;
+export declare const biomeBin: () => string;

package/dist/scripts/lib/bin.js

@@ -0,0 +1,20 @@
+/// <reference types="node" />
+// The executables this package brings a project (tsc, biome), found from
+// where Node resolves the package, so a project installs neither and pnpm's
+// layout never matters. A package's exports map may hide its bin and its
+// package.json, so the folder is found by walking up from its entry point.
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+const require = createRequire(import.meta.url);
+/** The folder of an installed package, searched the way Node searches, so an exports map never hides it. */
+export function packageDir(name) {
+    for (const dir of require.resolve.paths(name) ?? []) {
+        const candidate = join(dir, name);
+        if (existsSync(join(candidate, 'package.json')))
+            return candidate;
+    }
+    throw new Error(`${name} is not installed beside design-hub.`);
+}
+export const tscBin = () => join(packageDir('typescript'), 'bin', 'tsc');
+export const biomeBin = () => join(packageDir('@biomejs/biome'), 'bin', 'biome');

package/dist/scripts/lib/catalog.d.ts

@@ -0,0 +1,7 @@
+import { type Meta } from '../../core/catalog.ts';
+export type OnDisk = Meta & {
+    dir: string;
+};
+export declare function prototypes(root?: string): OnDisk[];
+/** The feature's live primary prototype, if it has one. */
+export declare const primaryOf: (feature: string, all?: OnDisk[]) => OnDisk | undefined;

package/dist/scripts/lib/catalog.js

@@ -0,0 +1,18 @@
+/// <reference types="node" />
+// The prototypes on disk, read the way the browser index reads them (vite/registry.ts).
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { byIndexOrder, isLive, readMeta } from '../../core/catalog.js';
+import { PROTOTYPES } from '../../server/paths.js';
+export function prototypes(root = PROTOTYPES) {
+    return readdirSync(root, { withFileTypes: true })
+        .filter((d) => d.isDirectory() && !d.name.startsWith('_') && !d.name.startsWith('.') && d.name !== 'node_modules')
+        .filter((d) => existsSync(join(root, d.name, 'README.md')))
+        .map((d) => ({
+        ...readMeta(d.name, readFileSync(join(root, d.name, 'README.md'), 'utf8')),
+        dir: join(root, d.name),
+    }))
+        .sort(byIndexOrder);
+}
+/** The feature's live primary prototype, if it has one. */
+export const primaryOf = (feature, all = prototypes()) => all.find((p) => p.kind === 'sprint' && isLive(p) && p.feature === feature);

package/dist/scripts/lib/cli.d.ts

@@ -0,0 +1,75 @@
+export type Flag = {
+    type: 'string';
+    description: string;
+    required?: boolean;
+    default?: string;
+    choices?: readonly string[];
+} | {
+    type: 'number';
+    description: string;
+    required?: boolean;
+    default?: number;
+} | {
+    type: 'boolean';
+    description: string;
+} | {
+    type: 'list';
+    description: string;
+};
+export type CommandSpec = {
+    name: string;
+    summary: string;
+    flags: Record<string, Flag>;
+    positionals?: {
+        name: string;
+        description: string;
+        required?: boolean;
+        variadic?: boolean;
+    }[];
+    output: string;
+};
+type ValueOf<F extends Flag> = F extends {
+    type: 'number';
+} ? number : F extends {
+    type: 'boolean';
+} ? boolean : F extends {
+    type: 'list';
+} ? string[] : string;
+type Defined<F extends Flag> = F extends {
+    type: 'boolean' | 'list';
+} ? true : F extends {
+    required: true;
+} ? true : F extends {
+    default: unknown;
+} ? true : false;
+export type Args<S extends CommandSpec> = {
+    flags: {
+        [K in keyof S['flags']]: Defined<S['flags'][K]> extends true ? ValueOf<S['flags'][K]> : ValueOf<S['flags'][K]> | undefined;
+    };
+    positionals: string[];
+};
+export type Result = Record<string, unknown> & {
+    ok?: boolean;
+};
+/** A failure the caller can act on: the message, and the fix when there is one. */
+export declare class CliError extends Error {
+    detail: Record<string, unknown>;
+    constructor(message: string, detail?: Record<string, unknown>);
+}
+export declare function schema(spec: CommandSpec): {
+    command: string;
+    summary: string;
+    positionals: {
+        name: string;
+        description: string;
+        required?: boolean;
+        variadic?: boolean;
+    }[];
+    flags: {
+        [k: string]: Flag;
+    };
+    output: string;
+};
+/** Parses argv, runs the command, prints its JSON and sets the exit code. */
+export declare function runCommand<S extends CommandSpec>(spec: S, main: (args: Args<S>) => Result | Promise<Result>, argv?: string[]): Promise<void>;
+export {};

package/dist/scripts/lib/cli.js

@@ -0,0 +1,88 @@
+/// <reference types="node" />
+// The contract every design-hub command keeps, because its reader is an
+// agent, not a person: every input is a flag, nothing prompts, stdout is one
+// JSON object, `--help` prints the command's schema as JSON, and a failure is
+// `{ ok: false, error, fix? }` with exit code 1. `design-hub commands` lists every
+// schema, so an agent discovers the commands without reading their source.
+import { parseArgs } from 'node:util';
+/** A failure the caller can act on: the message, and the fix when there is one. */
+export class CliError extends Error {
+    detail;
+    constructor(message, detail = {}) {
+        super(message);
+        this.detail = detail;
+    }
+}
+export function schema(spec) {
+    return {
+        command: `design-hub ${spec.name}`,
+        summary: spec.summary,
+        positionals: spec.positionals ?? [],
+        flags: Object.fromEntries(Object.entries(spec.flags).map(([name, flag]) => [`--${name}`, flag])),
+        output: spec.output,
+    };
+}
+/** One flag's value, typed by its spec; a missing optional flag takes its default. */
+function flagValue(name, f, raw) {
+    if (f.type === 'boolean')
+        return raw === true;
+    if (f.type === 'list')
+        return raw ?? [];
+    if (raw === undefined) {
+        if (f.required)
+            throw new CliError(`--${name} is required.`, { fix: f.description });
+        return f.default;
+    }
+    if (f.type === 'number') {
+        const n = Number(raw);
+        if (!Number.isFinite(n))
+            throw new CliError(`--${name} takes a number.`, { got: raw });
+        return n;
+    }
+    if (f.choices && !f.choices.includes(raw))
+        throw new CliError(`--${name} takes one of: ${f.choices.join(', ')}.`, { got: raw });
+    return raw;
+}
+function parse(spec, argv) {
+    const options = Object.fromEntries(Object.entries(spec.flags).map(([name, f]) => [
+        name,
+        { type: f.type === 'boolean' ? 'boolean' : 'string', multiple: f.type === 'list' },
+    ]));
+    const help = { fix: `Run design-hub ${spec.name} --help for the flags and arguments.` };
+    let parsed;
+    try {
+        parsed = parseArgs({ args: argv, options, allowPositionals: true, strict: true });
+    }
+    catch (error) {
+        throw new CliError(error instanceof Error ? error.message : String(error), help);
+    }
+    const flags = Object.fromEntries(Object.entries(spec.flags).map(([name, f]) => [name, flagValue(name, f, parsed.values[name])]));
+    const required = (spec.positionals ?? []).filter((p) => p.required).length;
+    if (parsed.positionals.length < required)
+        throw new CliError(`Missing ${spec.positionals?.[parsed.positionals.length]?.name}.`, help);
+    // flagValue gave every flag the type its spec declares, which is what Args<S> describes.
+    return { flags, positionals: parsed.positionals };
+}
+const print = (value) => console.log(JSON.stringify(value, null, 2));
+/** Parses argv, runs the command, prints its JSON and sets the exit code. */
+export async function runCommand(spec, main, argv = process.argv.slice(2)) {
+    if (argv.includes('--help') || argv.includes('-h'))
+        return print(schema(spec));
+    try {
+        const { ok = true, ...rest } = await main(parse(spec, argv));
+        print({ ok, ...rest });
+        if (!ok)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        // A domain error (the review service's) carries its problems by path; print them the same way.
+        const problems = error?.problems;
+        const detail = error instanceof CliError
+            ? error.detail
+            : Array.isArray(problems) && problems.length
+                ? { problems }
+                : {};
+        print({ ok: false, error: error instanceof Error ? error.message : String(error), ...detail });
+        process.exitCode = 1;
+    }
+}

package/dist/scripts/lib/css-tokens.d.ts

@@ -0,0 +1,13 @@
+export type TokenKind = 'color' | 'radius' | 'length' | 'font';
+export type Classified = {
+    kind: TokenKind;
+    value: string;
+} | {
+    kind: 'skip';
+    why: string;
+};
+/** The custom properties declared in one selector's block, comments stripped. */
+export declare function block(css: string, selector: string): Map<string, string>;
+/** #rgb, #rrggbbaa, rgb() and rgba() as lowercase #rrggbb or #rrggbbaa; null for anything else. */
+export declare const toHex: (value: string) => string | null;
+export declare function classify(name: string, value: string): Classified;

package/dist/scripts/lib/css-tokens.js

@@ -0,0 +1,67 @@
+// kit/tokens.css read as data: the light values on :root and the dark
+// overrides on .dark-mode, each classified by what an Elyx token can hold.
+// Pure, so the Elyx generator's mapping is tested without the Elyx CLI.
+// The harness is the prototype's own voice, never the product's, so it never enters the design system.
+const EXCLUDED = /^harness-/;
+/** The custom properties declared in one selector's block, comments stripped. */
+export function block(css, selector) {
+    const clean = css.replace(/\/\*[\s\S]*?\*\//g, '');
+    const at = clean.indexOf(`${selector} {`);
+    if (at < 0)
+        throw new Error(`tokens.css has no ${selector} block.`);
+    const body = clean.slice(clean.indexOf('{', at) + 1, clean.indexOf('}', at));
+    const out = new Map();
+    for (const decl of body.split(';')) {
+        const m = decl.match(/^\s*--([A-Za-z_-][\w-]*)\s*:\s*([\s\S]+?)\s*$/);
+        if (m)
+            out.set(m[1], m[2].replace(/\s+/g, ' '));
+    }
+    return out;
+}
+const byte = (n) => Math.round(Math.min(255, Math.max(0, n)))
+    .toString(16)
+    .padStart(2, '0');
+function hexColor(value) {
+    const m = value.match(/^#([0-9a-f]{3,8})$/i);
+    if (!m)
+        return null;
+    const short = m[1].length === 3 || m[1].length === 4;
+    const h = short ? [...m[1].toLowerCase()].map((c) => c + c).join('') : m[1].toLowerCase();
+    if (h.length !== 6 && h.length !== 8)
+        return null;
+    return `#${h.length === 8 && h.endsWith('ff') ? h.slice(0, 6) : h}`;
+}
+const channel = (p) => (p.endsWith('%') ? (Number.parseFloat(p) * 255) / 100 : Number.parseFloat(p));
+const alphaOf = (p) => p === undefined ? 1 : p.endsWith('%') ? Number.parseFloat(p) / 100 : Number.parseFloat(p);
+function rgbColor(value) {
+    const m = value.match(/^rgba?\(\s*([^)]+)\)$/i);
+    const parts = m ? m[1].split(/\s*[,/]\s*|\s+/).filter(Boolean) : [];
+    if (parts.length < 3 || parts.length > 4)
+        return null;
+    const rgb = parts.slice(0, 3).map(channel);
+    const alpha = alphaOf(parts[3]);
+    if (![...rgb, alpha].every(Number.isFinite))
+        return null;
+    return `#${rgb.map(byte).join('')}${alpha >= 1 ? '' : byte(alpha * 255)}`;
+}
+/** #rgb, #rrggbbaa, rgb() and rgba() as lowercase #rrggbb or #rrggbbaa; null for anything else. */
+export const toHex = (value) => hexColor(value) ?? rgbColor(value);
+export function classify(name, value) {
+    if (EXCLUDED.test(name))
+        return { kind: 'skip', why: 'harness material, not the design' };
+    const color = toHex(value);
+    if (color)
+        return { kind: 'color', value: color };
+    const px = value.match(/^(-?\d+(?:\.\d+)?)px$/);
+    if (px)
+        return { kind: name.startsWith('radius-') ? 'radius' : 'length', value: px[1] };
+    if (/^font(-|$)/.test(name)) {
+        // Elyx binds one family; the first in the stack is the design's, the rest are fallbacks.
+        const first = value
+            .split(',')[0]
+            .trim()
+            .replace(/^["']|["']$/g, '');
+        return { kind: 'font', value: JSON.stringify(first) };
+    }
+    return { kind: 'skip', why: 'no Elyx token type (a shadow, ring, easing, duration or keyword)' };
+}

package/dist/scripts/lib/judge.d.ts

@@ -0,0 +1,24 @@
+import { type Answer, type ImageAsset, type Question } from '../../core/jev.ts';
+export declare const JEV_LOG: string;
+export declare const LABELS: string;
+/** The checks that ask Jev; calibration groups judgments by these. */
+type CheckName = 'fidelity' | 'states' | 'contacts' | 'skillHint' | 'triage' | 'visual';
+export type Judged = {
+    answers: Record<string, Answer>;
+    ids: Record<string, string>;
+};
+export declare const typesafeKey: () => string;
+export declare function appendJsonl(file: string, entry: Record<string, unknown>): void;
+type Ask = {
+    check: CheckName;
+    /** What was judged, for the reader of the log: a file, a feature, a prompt. */
+    subject: string;
+    state: unknown;
+    questions: Record<string, Question>;
+    assets?: Record<string, ImageAsset>;
+    /** Kept in the log so a person labelling the judgment can see what was judged. */
+    excerpt?: string;
+};
+/** The answers and one log id per question, or null when Jev is off or failed. */
+export declare function judge({ check, subject, state, questions, assets, excerpt, }: Ask): Promise<Judged | null>;
+export {};

package/dist/scripts/lib/judge.js

@@ -0,0 +1,60 @@
+/// <reference types="node" />
+// Jev from the Node scripts: the key from .env, the model and timeout from
+// checks.json, and every judgment appended to .design-hub/jev.jsonl with an
+// id, so `design-hub calibrate` can label it right or wrong and thresholds come
+// from data. Off without TYPESAFE_API_KEY, silently: the user chose that.
+import { randomBytes } from 'node:crypto';
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { askJev } from '../../core/jev.js';
+import { checks } from '../../server/checks.js';
+import { readEnv } from '../../server/env.js';
+import { ROOT, STATE_DIR } from '../../server/paths.js';
+export const JEV_LOG = join(STATE_DIR, 'jev.jsonl');
+export const LABELS = join(STATE_DIR, 'labels.jsonl');
+// The project's .env only, never the shell: a key in someone's profile must not turn
+// TypeSafe on in a project whose owner did not opt in (design-hub bootstrap --typesafe-key).
+export const typesafeKey = () => readEnv(ROOT).TYPESAFE_API_KEY ?? '';
+export function appendJsonl(file, entry) {
+    try {
+        mkdirSync(dirname(file), { recursive: true });
+        appendFileSync(file, `${JSON.stringify(entry)}\n`);
+    }
+    catch {
+        // A log that cannot be written never stops the check it records.
+    }
+}
+/** The answers and one log id per question, or null when Jev is off or failed. */
+export async function judge({ check, subject, state, questions, assets, excerpt, }) {
+    const key = typesafeKey();
+    if (!key || !checks)
+        return null;
+    const result = await askJev(key, { model: checks.jev.model, state, questions, assets }, {
+        timeoutMs: checks.jev.timeoutMs,
+    });
+    const at = new Date().toISOString();
+    if (!result.ok) {
+        appendJsonl(JEV_LOG, { at, check, subject, error: result.error, ms: result.ms });
+        return null;
+    }
+    const ids = {};
+    for (const [question, answer] of Object.entries(result.answers)) {
+        const id = randomBytes(4).toString('hex');
+        ids[question] = id;
+        const value = answer.type === 'noul'
+            ? { p: answer.noul }
+            : { choice: answer.choice, confidence: answer.confidence, probabilities: answer.probabilities };
+        appendJsonl(JEV_LOG, {
+            id,
+            at,
+            check,
+            question,
+            subject,
+            model: result.model,
+            ms: result.ms,
+            ...value,
+            excerpt,
+        });
+    }
+    return { answers: result.answers, ids };
+}

package/dist/scripts/lib/ports.d.ts

@@ -0,0 +1,35 @@
+/** Project folder (absolute) to its port. Claims for folders that no longer exist are dropped. */
+export declare function readClaims(file?: string): Record<string, number>;
+/** Records the claim; written to a temp file and renamed, so a crash never leaves half a registry. */
+export declare function writeClaim(dir: string, port: number, file?: string): void;
+export type Holder = {
+    pid: number;
+    command: string;
+    cwd: string;
+};
+/** The process listening on the port, with its working directory, or null. */
+export declare function holderOf(port: number): Holder | null;
+export type PortChoice = {
+    ok: true;
+    port: number;
+    warnings: string[];
+} | {
+    ok: false;
+    error: string;
+    detail: Record<string, unknown>;
+};
+type PickInput = {
+    dir: string;
+    wanted?: number;
+    current?: number;
+    claims: Record<string, number>;
+    holder: (port: number) => Holder | null;
+    range?: readonly [number, number];
+};
+/**
+ * The port for `dir`: the one asked for, else the one it already has, else
+ * the first in range nobody holds or claims. Pure apart from `holder`, so the
+ * rules are tested without opening sockets.
+ */
+export declare function pickPort(input: PickInput): PortChoice;
+export {};

package/dist/scripts/lib/ports.js

@@ -0,0 +1,113 @@
+/// <reference types="node" />
+// One dev port per project on this machine. A live `lsof` check alone is not
+// enough: a project whose server is stopped today still owns its port, and a
+// second project handed the same one serves the wrong site the day both run.
+// So every project's claim is written to one registry outside any repo, and a
+// port is free only when nothing holds it and no other project claims it.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+// Off the 3000s that Next, Vite examples and most templates default to, so a
+// project that never ran bootstrap is unlikely to sit on a hub port.
+const PORT_RANGE = [3100, 3999];
+/** `$DESIGN_HUB_PORTS`, else `$XDG_CONFIG_HOME/design-hub/ports.json`, else `~/.config/...`. */
+function registryFile() {
+    if (process.env.DESIGN_HUB_PORTS)
+        return process.env.DESIGN_HUB_PORTS;
+    const config = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+    return join(config, 'design-hub', 'ports.json');
+}
+/** Project folder (absolute) to its port. Claims for folders that no longer exist are dropped. */
+export function readClaims(file = registryFile()) {
+    if (!existsSync(file))
+        return {};
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, 'utf8'));
+    }
+    catch {
+        // Read as empty, the next claim would overwrite every other project's; stop instead.
+        throw new Error(`${file} is not valid JSON. Fix it, or delete it and run pnpm bootstrap in each project again.`);
+    }
+    return Object.fromEntries(Object.entries(raw.claims ?? {}).filter((entry) => Number.isInteger(entry[1]) && existsSync(entry[0])));
+}
+/** Records the claim; written to a temp file and renamed, so a crash never leaves half a registry. */
+export function writeClaim(dir, port, file = registryFile()) {
+    const claims = { ...readClaims(file), [dir]: port };
+    mkdirSync(dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify({ claims }, null, 2)}\n`);
+    renameSync(tmp, file);
+}
+/** The process listening on the port, with its working directory, or null. */
+export function holderOf(port) {
+    const out = spawnSync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-Fpc'], { encoding: 'utf8' });
+    if (out.status !== 0 || !out.stdout)
+        return null;
+    const pid = Number(out.stdout.match(/^p(\d+)/m)?.[1]);
+    const command = out.stdout.match(/^c(.+)/m)?.[1] ?? '';
+    const cwd = spawnSync('lsof', ['-a', '-p', String(pid), '-d', 'cwd', '-Fn'], { encoding: 'utf8' }).stdout.match(/^n(.+)/m)?.[1] ?? '';
+    return { pid, command, cwd };
+}
+function owners({ dir, claims, holder }) {
+    return {
+        claimant: (port) => Object.entries(claims).find(([d, p]) => p === port && d !== dir)?.[0] ?? null,
+        foreign: (port) => {
+            const held = holder(port);
+            return held && held.cwd !== dir ? held : null;
+        },
+    };
+}
+/** A port asked for by name: refused, naming the owner, rather than swapped for another. */
+function checkWanted(wanted, { claimant, foreign }) {
+    if (!Number.isInteger(wanted) || wanted < 1024 || wanted > 65535)
+        return { ok: false, error: '--port takes an integer from 1024 to 65535.', detail: { got: wanted } };
+    const owner = claimant(wanted);
+    if (owner)
+        return {
+            ok: false,
+            error: `Port ${wanted} is claimed by another project.`,
+            detail: { port: wanted, claimedBy: owner, fix: 'Pass another --port.' },
+        };
+    const held = foreign(wanted);
+    if (held)
+        return {
+            ok: false,
+            error: `Port ${wanted} is taken.`,
+            detail: { port: wanted, holder: held, fix: 'Pass another --port, or stop that server.' },
+        };
+    return { ok: true, port: wanted, warnings: [] };
+}
+/** Why the port in .env cannot stay, or null when it can. */
+function currentConflict(current, { claimant, foreign }) {
+    const owner = claimant(current);
+    if (owner)
+        return `Port ${current} from .env is claimed by ${owner}; picked a new one.`;
+    const held = foreign(current);
+    return held
+        ? `Port ${current} from .env is held by pid ${held.pid} (${held.command}) in ${held.cwd}; picked a new one.`
+        : null;
+}
+/**
+ * The port for `dir`: the one asked for, else the one it already has, else
+ * the first in range nobody holds or claims. Pure apart from `holder`, so the
+ * rules are tested without opening sockets.
+ */
+export function pickPort(input) {
+    const own = owners(input);
+    if (input.wanted !== undefined)
+        return checkWanted(input.wanted, own);
+    const warnings = [];
+    if (input.current !== undefined) {
+        const conflict = currentConflict(input.current, own);
+        if (!conflict)
+            return { ok: true, port: input.current, warnings };
+        warnings.push(conflict);
+    }
+    const [from, to] = input.range ?? PORT_RANGE;
+    for (let port = from; port <= to; port++)
+        if (!own.claimant(port) && !own.foreign(port))
+            return { ok: true, port, warnings };
+    return { ok: false, error: `No free port between ${from} and ${to}.`, detail: {} };
+}

package/dist/scripts/lib/review.d.ts

@@ -0,0 +1,7 @@
+import { type Review } from '../../core/review/service.ts';
+export type CliReview = {
+    review: Review;
+    store: 'deployed' | 'local';
+};
+export declare function cliReview(local: boolean): CliReview;
+export declare const cliActor: () => import("../../core/review/model.ts").Person;

package/dist/scripts/lib/review.js

@@ -0,0 +1,22 @@
+/// <reference types="node" />
+// The review service from the command line: the deployed store when its
+// credentials are in .env (`design-hub bootstrap --review` puts them there), else
+// the local one the dev server uses. The CLI acts as an editor, because
+// whoever holds the store's credentials can already do anything to it.
+import { createReview } from '../../core/review/service.js';
+import { jevTriager } from '../../core/review/triage.js';
+import { checks } from '../../server/checks.js';
+import { readEnv } from '../../server/env.js';
+import { fileKV } from '../../server/file-kv.js';
+import { LOCAL_STORE, localEditor } from '../../server/local.js';
+import { ROOT } from '../../server/paths.js';
+import { storeConfig, upstashKV } from '../../server/upstash.js';
+export function cliReview(local) {
+    const env = readEnv(ROOT);
+    const config = local ? null : storeConfig(env);
+    const triage = jevTriager(env.TYPESAFE_API_KEY ?? '', checks);
+    return config
+        ? { review: createReview(upstashKV(config), { triage }), store: 'deployed' }
+        : { review: createReview(fileKV(LOCAL_STORE), { triage }), store: 'local' };
+}
+export const cliActor = () => localEditor('cli', 'CLI');

package/dist/scripts/lib/rules.d.ts

@@ -0,0 +1,12 @@
+export declare const RULE: {
+    readonly gravity: 'Low gravity';
+    readonly fork: "Fork, don't flex";
+    readonly dependency: 'No new dependency without the user';
+    readonly fetching: 'Fixtures, never a backend';
+    readonly abstraction: 'No abstraction for later';
+    readonly handling: 'No handling a fixture cannot reach';
+    readonly state: 'Every state is in the README';
+};
+export type SemanticRule = 'fetching' | 'abstraction' | 'handling' | 'state';
+/** Each question reads `change`, `readmeStates` and `fixtureSets` from the state by path. */
+export declare const NOULS: Record<SemanticRule, string>;

package/dist/scripts/lib/rules.js

@@ -0,0 +1,20 @@
+// The fidelity ceiling's rules, named exactly as the headings in
+// .claude/skills/miles-prototype/SKILL.md, and the Noul each semantic rule
+// asks. The guard asks all four on a write; the pre-flight asks the states
+// one over each sprint prototype before a share link goes out.
+export const RULE = {
+    gravity: 'Low gravity',
+    fork: "Fork, don't flex",
+    dependency: 'No new dependency without the user',
+    fetching: 'Fixtures, never a backend',
+    abstraction: 'No abstraction for later',
+    handling: 'No handling a fixture cannot reach',
+    state: 'Every state is in the README',
+};
+/** Each question reads `change`, `readmeStates` and `fixtureSets` from the state by path. */
+export const NOULS = {
+    fetching: 'Does the code in `change` introduce data fetching, persistence or a backend call: fetch, XMLHttpRequest, WebSocket, IndexedDB, a server module, or localStorage used as a database rather than as a prototype preference?',
+    abstraction: 'Does the code in `change` introduce an abstraction (a custom hook, a React context, a generic or higher-order component, a utility module) that only one place uses?',
+    handling: 'Does the code in `change` add error handling, loading state or input validation for a case that none of the fixture sets in `fixtureSets` would exercise?',
+    state: 'Does the code in `change` render a user-visible UI state that is not listed in `readmeStates`?',
+};