@milesroxas/design-hub 0.0.0-stage → 0.1.0

package/dist/scripts/cli.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+// The design-hub command line: one binary, one subcommand per file in this
+// folder. Every subcommand keeps the contract in lib/cli.ts: flags only, no
+// prompts, one JSON object on stdout, `--help` for its schema. `dev`,
+// `preview` and `open` are the exceptions: they run a server and print
+// Vite's log. `hook <name>` is for Claude Code's settings.json and prints
+// hook JSON or nothing.
+import * as bootstrap from './bootstrap.js';
+import * as calibrate from './calibrate.js';
+import * as check from './check.js';
+import * as commands from './commands.js';
+import * as comments from './comments.js';
+import * as dev from './dev.js';
+import * as elyx from './elyx.js';
+import * as fixturesPull from './fixtures-pull.js';
+import * as guard from './guard.js';
+import { HOOKS, runHook } from './hook.js';
+import { runCommand } from './lib/cli.js';
+import * as create from './new.js';
+import * as people from './people.js';
+import * as preflight from './preflight.js';
+import * as releaseCheck from './release-check.js';
+import * as skillHint from './skill-hint.js';
+import * as skills from './skills.js';
+import * as visualMatch from './visual-match.js';
+// `guide` is `new --guide`; `open` is `dev` with the browser.
+const COMMANDS = {
+    bootstrap,
+    new: create,
+    guide: {
+        spec: create.spec,
+        main: (args) => create.main({ ...args, flags: { ...args.flags, guide: true } }),
+    },
+    dev,
+    open: { spec: dev.openSpec, main: dev.openMain },
+    build: { spec: dev.buildSpec, main: dev.build },
+    preview: { spec: dev.previewSpec, main: dev.previewBuilt },
+    check,
+    guard,
+    preflight,
+    people,
+    comments,
+    calibrate,
+    'fixtures-pull': fixturesPull,
+    'visual-match': visualMatch,
+    elyx,
+    skills,
+    'skill-hint': skillHint,
+    'release-check': releaseCheck,
+    commands,
+};
+function usage() {
+    console.log(JSON.stringify({
+        ok: false,
+        error: 'Name a command.',
+        commands: [...Object.keys(COMMANDS), 'hook'],
+        fix: 'design-hub commands lists every schema; design-hub <command> --help prints one.',
+    }, null, 2));
+}
+export async function cli([name, ...rest]) {
+    if (name === 'hook')
+        return HOOKS.includes(rest[0]) ? runHook(rest[0]) : usage();
+    const command = name ? COMMANDS[name] : undefined;
+    if (!command) {
+        usage();
+        if (name && name !== '--help' && name !== '-h')
+            process.exitCode = 1;
+        return;
+    }
+    return runCommand(command.spec, command.main, rest);
+}
+await cli(process.argv.slice(2));

package/dist/scripts/commands.d.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { type CommandSpec } from './lib/cli.ts';
+export declare const spec: {
+    readonly name: 'commands';
+    readonly summary: "List every command's schema: its flags, arguments and output.";
+    readonly flags: {};
+    readonly output: '{ ok, commands: [schema] }';
+};
+export declare const COMMANDS: CommandSpec[];
+export declare const main: () => {
+    commands: {
+        command: string;
+        summary: string;
+        positionals: {
+            name: string;
+            description: string;
+            required?: boolean;
+            variadic?: boolean;
+        }[];
+        flags: {
+            [k: string]: import("./lib/cli.ts").Flag;
+        };
+        output: string;
+    }[];
+};

package/dist/scripts/commands.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+// `design-hub commands`: every command's schema in one JSON list, so an agent
+// finds what it can run, and with which flags, without reading any source.
+// Each schema is the command's own `spec`, the same one its --help prints.
+import * as bootstrap from './bootstrap.js';
+import * as calibrate from './calibrate.js';
+import * as check from './check.js';
+import * as comments from './comments.js';
+import * as dev from './dev.js';
+import * as elyx from './elyx.js';
+import * as fixturesPull from './fixtures-pull.js';
+import * as guard from './guard.js';
+import { schema } from './lib/cli.js';
+import * as create from './new.js';
+import * as people from './people.js';
+import * as preflight from './preflight.js';
+import * as releaseCheck from './release-check.js';
+import * as skillHint from './skill-hint.js';
+import * as skills from './skills.js';
+import * as visualMatch from './visual-match.js';
+export const spec = {
+    name: 'commands',
+    summary: "List every command's schema: its flags, arguments and output.",
+    flags: {},
+    output: '{ ok, commands: [schema] }',
+};
+export const COMMANDS = [
+    bootstrap.spec,
+    dev.spec,
+    dev.buildSpec,
+    dev.previewSpec,
+    dev.openSpec,
+    create.spec,
+    check.spec,
+    guard.spec,
+    preflight.spec,
+    people.spec,
+    comments.spec,
+    calibrate.spec,
+    fixturesPull.spec,
+    visualMatch.spec,
+    elyx.spec,
+    skills.spec,
+    skillHint.spec,
+    releaseCheck.spec,
+    spec,
+];
+export const main = () => ({ commands: COMMANDS.map(schema) });

package/dist/scripts/comments.d.ts

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+import { type Comment } from '../core/review/model.ts';
+import type { Review } from '../core/review/service.ts';
+import { type Args } from './lib/cli.ts';
+import { type CliReview } from './lib/review.ts';
+export declare const spec: {
+    readonly name: 'comments';
+    readonly summary: 'Read review comments into the repo, resolve them, or sort the unsorted ones.';
+    readonly positionals: [{
+        readonly name: 'action';
+        readonly description: 'summary (default): open and resolved counts per prototype. pull: docs/sprints/<feature>/comments.md, by state then kind. resolve or reopen <id>. triage: sort what Jev left unsorted, against the README states on disk.';
+    }, {
+        readonly name: 'id';
+        readonly description: 'The comment, for resolve and reopen';
+    }];
+    readonly flags: {
+        readonly all: {
+            readonly type: 'boolean';
+            readonly description: 'For pull: include resolved threads.';
+        };
+        readonly local: {
+            readonly type: 'boolean';
+            readonly description: 'Use the local dev store even when the deployed one is configured.';
+        };
+    };
+    readonly output: '{ ok, store, ... } per action';
+};
+/** One feature's comments as Markdown: by README state in table order, then kind; replies under their thread. */
+export declare function renderComments(feature: string, comments: Comment[], stateOrder: string[]): string;
+type Context = {
+    review: Review;
+    store: CliReview['store'];
+    all: Comment[];
+    roots: Comment[];
+};
+export declare function summary({ store, roots }: Pick<Context, 'store' | 'roots'>): {
+    store: "deployed" | "local";
+    prototypes: Record<string, {
+        open: number;
+        resolved: number;
+    }>;
+};
+export declare function main({ positionals: [action, id], flags }: Args<typeof spec>): Promise<{
+    store: "deployed" | "local";
+    prototypes: Record<string, {
+        open: number;
+        resolved: number;
+    }>;
+} | {
+    store: "deployed" | "local";
+    threads: number;
+    written: string[];
+} | {
+    store: "deployed" | "local";
+    comment: {
+        id: string;
+        status: "open" | "resolved";
+    };
+} | {
+    store: "deployed" | "local";
+    sorted: string[];
+}>;
+export {};

package/dist/scripts/comments.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+// Review comments from the deployed prototypes, brought into the repo where
+// Claude works from them. `pull` writes a generated file per feature; the
+// panel or `resolve` is where a comment is closed, never the file.
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { featureTitle } from '../core/feature.js';
+import { KINDS } from '../core/review/model.js';
+import { jevTriager } from '../core/review/triage.js';
+import { checks } from '../server/checks.js';
+import { readEnv } from '../server/env.js';
+import { DOCS, ROOT } from '../server/paths.js';
+import { prototypes } from './lib/catalog.js';
+import { CliError } from './lib/cli.js';
+import { cliActor, cliReview } from './lib/review.js';
+export const spec = {
+    name: 'comments',
+    summary: 'Read review comments into the repo, resolve them, or sort the unsorted ones.',
+    positionals: [
+        {
+            name: 'action',
+            description: 'summary (default): open and resolved counts per prototype. pull: docs/sprints/<feature>/comments.md, by state then kind. resolve or reopen <id>. triage: sort what Jev left unsorted, against the README states on disk.',
+        },
+        { name: 'id', description: 'The comment, for resolve and reopen' },
+    ],
+    flags: {
+        all: { type: 'boolean', description: 'For pull: include resolved threads.' },
+        local: {
+            type: 'boolean',
+            description: 'Use the local dev store even when the deployed one is configured.',
+        },
+    },
+    output: '{ ok, store, ... } per action',
+};
+const NO_STATE = 'No state';
+const KIND_TITLE = { bug: 'Bugs', taste: 'Taste', copy: 'Copy' };
+const stateOf = (c) => c.triage?.state ?? NO_STATE;
+const isRoot = (c) => c.thread === c.id;
+// A body without closing punctuation gets a full stop, so the location after it reads apart from it.
+const sentence = (text) => (/[.!?…]$/.test(text) ? text : `${text}.`);
+const line = (c) => `${c.author.name} (${c.author.team}): ${sentence(c.body.replace(/\s*\n\s*/g, ' '))}`;
+function threadLines(root, comments) {
+    const where = root.anchor
+        ? ` On \`${root.anchor.url}\`${root.anchor.target ? `, element \`${root.anchor.target}\`` : ''}.`
+        : '';
+    const resolved = root.status === 'resolved' ? ' Resolved.' : '';
+    const replies = comments.filter((c) => c.thread === root.id && !isRoot(c));
+    return [`- ${line(root)}${where}${resolved} id \`${root.id}\``, ...replies.map((r) => `  - ${line(r)}`)];
+}
+function stateSection(state, roots, comments) {
+    const out = ['', `## ${state}`];
+    for (const kind of [...KINDS, null]) {
+        const group = roots.filter((c) => stateOf(c) === state && (c.triage?.kind ?? null) === kind);
+        if (group.length)
+            out.push('', `### ${kind ? KIND_TITLE[kind] : 'Unsorted'}`, '', ...group.flatMap((c) => threadLines(c, comments)));
+    }
+    return out;
+}
+/** One feature's comments as Markdown: by README state in table order, then kind; replies under their thread. */
+export function renderComments(feature, comments, stateOrder) {
+    const roots = comments.filter(isRoot);
+    const states = [...new Set([...stateOrder, ...roots.map(stateOf)])].filter((s) => roots.some((c) => stateOf(c) === s));
+    const out = [
+        `# Comments: ${featureTitle(feature)}`,
+        '',
+        'Generated by `pnpm comments pull`; a second pull replaces it. Resolve a comment in the review panel or with `pnpm comments resolve <id>`, never here.',
+        ...states.flatMap((state) => stateSection(state, roots, comments)),
+    ];
+    return `${out.join('\n')}\n`;
+}
+export function summary({ store, roots }) {
+    const by = {};
+    for (const c of roots) {
+        const key = c.anchor?.prototype ?? 'unknown';
+        by[key] ??= { open: 0, resolved: 0 };
+        by[key][c.status]++;
+    }
+    return { store, prototypes: by };
+}
+function pull({ store, all, roots }, includeResolved) {
+    const keep = new Map(roots.filter((c) => includeResolved || c.status === 'open').map((c) => [c.id, c]));
+    const byFeature = new Map();
+    for (const c of all) {
+        const root = keep.get(c.thread);
+        if (!root)
+            continue;
+        const feature = root.anchor?.feature || root.anchor?.prototype || 'unsorted';
+        byFeature.set(feature, [...(byFeature.get(feature) ?? []), c]);
+    }
+    const disk = prototypes();
+    const written = [...byFeature].map(([feature, comments]) => {
+        const order = disk
+            .filter((p) => p.feature === feature)
+            .flatMap((p) => (p.states ?? []).map((s) => s.name));
+        const dir = join(DOCS, 'sprints', feature);
+        mkdirSync(dir, { recursive: true });
+        writeFileSync(join(dir, 'comments.md'), renderComments(feature, comments, order));
+        return relative(ROOT, join(dir, 'comments.md'));
+    });
+    return { store, threads: keep.size, written };
+}
+async function setStatus({ review, store }, id, resolved) {
+    const action = resolved ? 'resolve' : 'reopen';
+    if (!id)
+        throw new CliError(`Name the comment: pnpm comments ${action} <id>.`, {
+            fix: 'pnpm comments pull lists ids.',
+        });
+    const found = await review.locate(id);
+    if (!found)
+        throw new CliError('No comment has that id.', { id });
+    const comment = await review.resolve(cliActor(), { prototype: found.prototype, id, resolved });
+    return { store, comment: { id: comment.id, status: comment.status } };
+}
+async function triage({ review, store, roots }) {
+    const triager = jevTriager(readEnv(ROOT).TYPESAFE_API_KEY ?? '', checks);
+    if (!triager)
+        throw new CliError('TypeSafe is off.', {
+            fix: 'pnpm bootstrap --typesafe-key <key>, or sort them in the panel.',
+        });
+    const statesOf = new Map(prototypes().map((p) => [p.slug, (p.states ?? []).map((s) => s.name)]));
+    const sorted = [];
+    for (const c of roots) {
+        if (c.triage || !c.anchor)
+            continue;
+        const states = statesOf.get(c.anchor.prototype) ?? [];
+        const t = await triager({ body: c.body, prototype: c.anchor.prototype, url: c.anchor.url, states });
+        if (!t)
+            continue;
+        await review.retriage(cliActor(), { prototype: c.anchor.prototype, id: c.id, triage: t, states });
+        sorted.push(c.id);
+    }
+    return { store, sorted };
+}
+export async function main({ positionals: [action = 'summary', id], flags }) {
+    const { review, store } = cliReview(flags.local);
+    const all = await review.allComments();
+    const ctx = { review, store, all, roots: all.filter(isRoot) };
+    switch (action) {
+        case 'summary':
+            return summary(ctx);
+        case 'pull':
+            return pull(ctx, flags.all);
+        case 'resolve':
+        case 'reopen':
+            return setStatus(ctx, id, action === 'resolve');
+        case 'triage':
+            return triage(ctx);
+        default:
+            throw new CliError(`Unknown action ${action}.`, { fix: 'summary, pull, resolve, reopen or triage' });
+    }
+}

package/dist/scripts/dev.d.ts

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+import type { Args } from './lib/cli.ts';
+export declare const spec: {
+    readonly name: 'dev';
+    readonly summary: 'Serve the hub, every prototype and the review panel on the port in .env.';
+    readonly flags: {
+        readonly open: {
+            readonly type: 'boolean';
+            readonly description: 'Open the browser once the server is up.';
+        };
+    };
+    readonly output: "Vite's own log; the command runs until stopped.";
+};
+export declare const buildSpec: {
+    readonly name: 'build';
+    readonly summary: 'Build the deployable site into dist/.';
+    readonly flags: {};
+    readonly output: '{ ok, outDir }';
+};
+export declare const previewSpec: {
+    readonly name: 'preview';
+    readonly summary: 'Serve dist/ as built, on the port in .env.';
+    readonly flags: {};
+    readonly output: "Vite's own log; the command runs until stopped.";
+};
+export declare const openSpec: {
+    readonly name: 'open';
+    readonly summary: 'Start the hub and open it in the browser; what the project launcher double-click runs.';
+    readonly flags: {};
+    readonly output: "Vite's own log; the command runs until stopped.";
+};
+/** Builds dist/; `ok: false` carries the error, so preflight can report it. */
+export declare function build(): Promise<{
+    ok: boolean;
+    outDir: string;
+    error?: string;
+}>;
+export declare function previewBuilt(): Promise<{
+    stopped: boolean;
+}>;
+export declare function main({ flags }: Args<typeof spec>): Promise<{
+    stopped: boolean;
+}>;
+export declare function openMain(): Promise<{
+    stopped: boolean;
+}>;

package/dist/scripts/dev.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+// `design-hub dev`, `build`, `preview` and `open`: Vite on the hub's config
+// (vite/plugin.ts), with the project as the content. `dev` streams Vite's own
+// output rather than one JSON object, because a server never finishes.
+import { spawn } from 'node:child_process';
+import { createServer, build as viteBuild, preview as vitePreview } from 'vite';
+import { devPort, readEnv } from '../server/env.js';
+import { ROOT } from '../server/paths.js';
+import { hubConfig } from '../vite/plugin.js';
+export const spec = {
+    name: 'dev',
+    summary: 'Serve the hub, every prototype and the review panel on the port in .env.',
+    flags: { open: { type: 'boolean', description: 'Open the browser once the server is up.' } },
+    output: "Vite's own log; the command runs until stopped.",
+};
+export const buildSpec = {
+    name: 'build',
+    summary: 'Build the deployable site into dist/.',
+    flags: {},
+    output: '{ ok, outDir }',
+};
+export const previewSpec = {
+    name: 'preview',
+    summary: 'Serve dist/ as built, on the port in .env.',
+    flags: {},
+    output: "Vite's own log; the command runs until stopped.",
+};
+export const openSpec = {
+    name: 'open',
+    summary: 'Start the hub and open it in the browser; what the project launcher double-click runs.',
+    flags: {},
+    output: "Vite's own log; the command runs until stopped.",
+};
+function openBrowser(url) {
+    const [cmd, args] = process.platform === 'darwin'
+        ? ['open', [url]]
+        : process.platform === 'win32'
+            ? ['cmd', ['/c', 'start', '', url]]
+            : ['xdg-open', [url]];
+    spawn(cmd, args, { stdio: 'ignore', detached: true })
+        .on('error', () => { })
+        .unref();
+}
+async function serve(open) {
+    const server = await createServer(hubConfig({ root: ROOT }, 'serve'));
+    await server.listen();
+    server.printUrls();
+    if (open)
+        openBrowser(`http://localhost:${devPort(readEnv(ROOT))}/`);
+    await new Promise((resolve) => {
+        server.httpServer?.on('close', resolve);
+        for (const signal of ['SIGINT', 'SIGTERM'])
+            process.once(signal, () => {
+                void server.close().then(resolve);
+            });
+    });
+}
+/** Builds dist/; `ok: false` carries the error, so preflight can report it. */
+export async function build() {
+    const config = hubConfig({ root: ROOT }, 'build');
+    const outDir = config.build?.outDir ?? 'dist';
+    try {
+        await viteBuild({ ...config, logLevel: 'warn' });
+        return { ok: true, outDir };
+    }
+    catch (error) {
+        return { ok: false, outDir, error: error instanceof Error ? error.message : String(error) };
+    }
+}
+export async function previewBuilt() {
+    const server = await vitePreview(hubConfig({ root: ROOT }, 'build'));
+    server.printUrls();
+    await new Promise(() => { });
+    return { stopped: true };
+}
+export async function main({ flags }) {
+    await serve(flags.open);
+    return { stopped: true };
+}
+export async function openMain() {
+    await serve(true);
+    return { stopped: true };
+}

package/dist/scripts/elyx.d.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+import { type Args } from './lib/cli.ts';
+export declare const spec: {
+    readonly name: 'elyx';
+    readonly summary: 'Generate the Elyx design-system project from kit/tokens.css, or check it has not drifted.';
+    readonly flags: {
+        readonly check: {
+            readonly type: 'boolean';
+            readonly description: 'Fail when design-system/ differs from a fresh generation.';
+        };
+    };
+    readonly output: '{ ok, out, tokens, skipped, diagnostics } or { ok, drift }';
+};
+export declare function plan(css: string): {
+    files: Record<string, string>;
+    light: Map<string, string>;
+    dark: Map<string, string>;
+    counts: {
+        colors: number;
+        dark: number;
+        radius: number;
+        lengths: number;
+        fonts: number;
+    };
+    skipped: string[];
+};
+type ExportedToken = {
+    name: string;
+    value: string;
+    context: {
+        theme?: string;
+    };
+};
+/** A token whose bytes differ from tokens.css, or null when they match or cannot be compared. */
+export declare function mismatch(t: ExportedToken, source: string | undefined): string | null;
+export declare function main({ flags }: Args<typeof spec>): {
+    out: string;
+    tokens: {
+        colors: number;
+        dark: number;
+        radius: number;
+        lengths: number;
+        fonts: number;
+    };
+    skipped: string[];
+    diagnostics: {
+        errors?: number;
+    };
+    ok?: undefined;
+    drift?: undefined;
+    fix?: undefined;
+} | {
+    out?: undefined;
+    tokens?: undefined;
+    skipped?: undefined;
+    diagnostics?: undefined;
+    ok: boolean;
+    drift: string[];
+    fix: string | undefined;
+};
+export {};