@milesroxas/design-hub 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,17 @@
+export declare const ENVIRONMENTS: readonly ['production', 'preview'];
+export type Target = (typeof ENVIRONMENTS)[number] | 'development';
+/** What the Upstash for Redis integration injects (Vercel Marketplace). */
+export declare const STORE_ENV: readonly ['KV_REST_API_URL', 'KV_REST_API_TOKEN'];
+export type Run = {
+    status: number;
+    stdout: string;
+    stderr: string;
+};
+export declare function vercel(cwd: string, args: string[], input?: string): Run | null;
+export declare function linkedProject(cwd: string): string | null;
+/** The variable names set for a target, read from `vercel env ls`'s table. */
+export declare function envNames(cwd: string, target: Target): Set<string> | null;
+/** Sets one variable for one target; `force` replaces a value that is already there. */
+export declare function setEnv(cwd: string, name: string, target: Target, value: string, force: boolean): Run | null;
+/** The gate variables missing from production or preview, or null when the CLI cannot say. */
+export declare function gateEnvMissing(cwd: string): string[] | null;

package/dist/scripts/lib/vercel.js

@@ -0,0 +1,53 @@
+/// <reference types="node" />
+// The Vercel CLI calls the scripts make, in one place. Each returns null when
+// the CLI is missing or signed out, so a caller decides whether that is a
+// failure (bootstrap --vercel) or a skipped check (preflight).
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+export const ENVIRONMENTS = ['production', 'preview'];
+const GATE_ENV = ['GATE_PASSWORD', 'GATE_SECRET'];
+/** What the Upstash for Redis integration injects (Vercel Marketplace). */
+export const STORE_ENV = ['KV_REST_API_URL', 'KV_REST_API_TOKEN'];
+export function vercel(cwd, args, input) {
+    const out = spawnSync('vercel', args, { cwd, encoding: 'utf8', input, env: process.env });
+    if (out.error)
+        return null;
+    return { status: out.status ?? 1, stdout: out.stdout ?? '', stderr: out.stderr ?? '' };
+}
+export function linkedProject(cwd) {
+    const file = join(cwd, '.vercel', 'project.json');
+    if (!existsSync(file))
+        return null;
+    try {
+        return JSON.parse(readFileSync(file, 'utf8')).projectName ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The variable names set for a target, read from `vercel env ls`'s table. */
+export function envNames(cwd, target) {
+    const out = vercel(cwd, ['env', 'ls', target]);
+    if (out?.status !== 0)
+        return null;
+    return new Set([...out.stdout.matchAll(/^\s*([A-Z][A-Z0-9_]*)\s/gm)].map((m) => m[1]));
+}
+/** Sets one variable for one target; `force` replaces a value that is already there. */
+export function setEnv(cwd, name, target, value, force) {
+    // The value goes on stdin, never argv, so it stays out of the process list.
+    return vercel(cwd, ['env', 'add', name, target, ...(force ? ['--force'] : []), '--yes'], value);
+}
+/** The gate variables missing from production or preview, or null when the CLI cannot say. */
+export function gateEnvMissing(cwd) {
+    const missing = [];
+    for (const target of ENVIRONMENTS) {
+        const names = envNames(cwd, target);
+        if (!names)
+            return null;
+        for (const name of GATE_ENV)
+            if (!names.has(name))
+                missing.push(`${name}:${target}`);
+    }
+    return missing;
+}

package/dist/scripts/new.d.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { type Args } from './lib/cli.ts';
+export declare const spec: {
+    readonly name: 'new';
+    readonly summary: 'Scaffold a prototype folder, or with --guide a feature walkthrough.';
+    readonly positionals: [{
+        readonly name: 'slug';
+        readonly description: 'kebab-case folder name (with --guide: the feature)';
+        readonly required: true;
+    }];
+    readonly flags: {
+        readonly app: {
+            readonly type: 'boolean';
+            readonly description: 'Inside the product or site shell instead of the Space.';
+        };
+        readonly sprint: {
+            readonly type: 'boolean';
+            readonly description: "The feature's one primary prototype. Needs --feature.";
+        };
+        readonly alternate: {
+            readonly type: 'boolean';
+            readonly description: 'Another take on the primary. Needs --feature and a primary.';
+        };
+        readonly feature: {
+            readonly type: 'string';
+            readonly description: 'The feature slug: the folder under docs/sprints/.';
+        };
+        readonly title: {
+            readonly type: 'string';
+            readonly description: 'Display title. Default: the slug in sentence case.';
+        };
+        readonly guide: {
+            readonly type: 'boolean';
+            readonly description: 'Scaffold docs/sprints/<feature>/guide.md instead.';
+        };
+    };
+    readonly output: '{ ok, created, url, next }';
+};
+type Kind = 'sprint' | 'alternate' | 'exploration';
+/** The kind the flags ask for, refused when the feature's state does not allow it. */
+export declare function kindFor(flags: Pick<Args<typeof spec>['flags'], 'sprint' | 'alternate'>, feature: string, primary?: (f: string) => string | undefined): Kind;
+export declare function main(args: Args<typeof spec>): {
+    created: string;
+    url: string;
+    next: string;
+};
+export {};

package/dist/scripts/new.js

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+// Scaffolds a prototype from the package's templates/ (a Space, or --app inside the
+// shell), or a feature's walkthrough at docs/sprints/<feature>/guide.md.
+// A feature has one primary prototype (--sprint); --alternate is refused
+// until it exists, so the index always has a primary to show first.
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { featureTitle, guideHref, SLUG } from '../core/feature.js';
+import { devPort, readEnv } from '../server/env.js';
+import { DOCS, PROTOTYPES, ROOT, TEMPLATES } from '../server/paths.js';
+import { primaryOf } from './lib/catalog.js';
+import { CliError } from './lib/cli.js';
+export const spec = {
+    name: 'new',
+    summary: 'Scaffold a prototype folder, or with --guide a feature walkthrough.',
+    positionals: [
+        { name: 'slug', description: 'kebab-case folder name (with --guide: the feature)', required: true },
+    ],
+    flags: {
+        app: { type: 'boolean', description: 'Inside the product or site shell instead of the Space.' },
+        sprint: { type: 'boolean', description: "The feature's one primary prototype. Needs --feature." },
+        alternate: {
+            type: 'boolean',
+            description: 'Another take on the primary. Needs --feature and a primary.',
+        },
+        feature: { type: 'string', description: 'The feature slug: the folder under docs/sprints/.' },
+        title: { type: 'string', description: 'Display title. Default: the slug in sentence case.' },
+        guide: { type: 'boolean', description: 'Scaffold docs/sprints/<feature>/guide.md instead.' },
+    },
+    output: '{ ok, created, url, next }',
+};
+const created = () => new Date().toISOString().slice(0, 10);
+const localUrl = (path) => `http://localhost:${devPort(readEnv(ROOT)) ?? '<port>'}${path}`;
+/** Copies a template file or folder and fills its {{placeholders}}. */
+function scaffold(src, dest, vars) {
+    if (existsSync(dest))
+        throw new CliError(`${relative(ROOT, dest)} already exists.`);
+    mkdirSync(dirname(dest), { recursive: true });
+    cpSync(src, dest, { recursive: true });
+    const files = statSync(dest).isDirectory() ? readdirSync(dest).map((f) => join(dest, f)) : [dest];
+    for (const path of files) {
+        let text = readFileSync(path, 'utf8');
+        for (const [key, value] of Object.entries(vars))
+            text = text.replaceAll(`{{${key}}}`, () => value);
+        writeFileSync(path, text);
+    }
+}
+function guide(feature) {
+    if (!SLUG.test(feature))
+        throw new CliError('The feature is a kebab-case slug.', { got: feature });
+    const dest = join(DOCS, 'sprints', feature, 'guide.md');
+    scaffold(join(TEMPLATES, 'guide.md'), dest, {
+        feature,
+        title: featureTitle(feature),
+        created: created(),
+    });
+    return {
+        created: relative(ROOT, dest),
+        url: localUrl(guideHref(feature)),
+        next: `Write it from the States table. Screenshots go in docs/sprints/${feature}/assets/guide/.`,
+    };
+}
+/** The kind the flags ask for, refused when the feature's state does not allow it. */
+export function kindFor(flags, feature, primary = (f) => primaryOf(f)?.slug) {
+    if (flags.sprint && flags.alternate)
+        throw new CliError('Pick one of --sprint and --alternate.');
+    const kind = flags.sprint ? 'sprint' : flags.alternate ? 'alternate' : 'exploration';
+    if (kind === 'exploration')
+        return kind;
+    if (!feature)
+        throw new CliError(`A ${kind} prototype names its feature.`, { fix: 'Add --feature <feature>.' });
+    const existing = primary(feature);
+    if (kind === 'sprint' && existing)
+        throw new CliError(`${feature} already has its primary prototype, ${existing}/.`, {
+            fix: 'Use --alternate for another take on it.',
+        });
+    if (kind === 'alternate' && !existing)
+        throw new CliError(`${feature} has no primary prototype yet.`, {
+            fix: 'Start it with --sprint, then add alternates.',
+        });
+    return kind;
+}
+function prototype(slug, { flags }) {
+    if (!SLUG.test(slug))
+        throw new CliError('The slug is kebab-case.', { got: slug });
+    if (slug === 'guide')
+        throw new CliError('guide/ is the walkthrough route; pick another slug.');
+    const feature = flags.feature ?? '';
+    if (feature && !SLUG.test(feature))
+        throw new CliError('--feature takes a kebab-case slug.', { got: feature });
+    const kind = kindFor(flags, feature);
+    const context = flags.app ? 'app' : 'space';
+    scaffold(join(TEMPLATES, context), join(PROTOTYPES, slug), {
+        title: flags.title ?? featureTitle(slug),
+        slug,
+        created: created(),
+        kind,
+        feature,
+    });
+    return {
+        created: `prototypes/${slug}/`,
+        context,
+        kind,
+        feature,
+        url: localUrl(`/${slug}/`),
+        next: `Write the Problem, Question and States in prototypes/${slug}/README.md before any code.`,
+    };
+}
+export function main(args) {
+    const [slug] = args.positionals;
+    return args.flags.guide ? guide(slug) : prototype(slug, args);
+}

package/dist/scripts/people.d.ts

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+import { type Args } from './lib/cli.ts';
+export declare const spec: {
+    readonly name: 'people';
+    readonly summary: 'List, invite, reissue or revoke the people who comment on the deployed prototypes.';
+    readonly positionals: [{
+        readonly name: 'action';
+        readonly description: 'list (default): everyone who may comment. invite: a new person and their link. reissue <id>: a new link; the old one and every session stop. revoke <id>.';
+    }, {
+        readonly name: 'id';
+        readonly description: 'The person, for reissue and revoke';
+    }];
+    readonly flags: {
+        readonly name: {
+            readonly type: 'string';
+            readonly description: 'For invite: their name as it shows on comments.';
+        };
+        readonly team: {
+            readonly type: 'string';
+            readonly description: "For invite: the studio, or the client's company.";
+        };
+        readonly role: {
+            readonly type: 'string';
+            readonly default: 'reviewer';
+            readonly choices: readonly ["editor", "reviewer"];
+            readonly description: 'reviewer comments; editor also resolves, sorts and invites.';
+        };
+        readonly site: {
+            readonly type: 'string';
+            readonly description: 'The deployed URL, so the invite link prints whole.';
+        };
+        readonly local: {
+            readonly type: 'boolean';
+            readonly description: 'Use the local dev store even when the deployed one is configured.';
+        };
+    };
+    readonly output: '{ ok, store, people } or { ok, store, person, link }';
+};
+export declare function main({ positionals: [action, id], flags }: Args<typeof spec>): Promise<{
+    store: "deployed" | "local";
+    people: Omit<import("../core/review/model.ts").Person, "epoch">[];
+    person?: undefined;
+} | {
+    link: string;
+    next: string;
+    people?: undefined;
+    store: "deployed" | "local";
+    person: Omit<import("../core/review/model.ts").Person, "epoch">;
+} | {
+    next?: undefined;
+    link: string;
+    people?: undefined;
+    store: "deployed" | "local";
+    person: Omit<import("../core/review/model.ts").Person, "epoch">;
+} | {
+    people?: undefined;
+    store: "deployed" | "local";
+    person: Omit<import("../core/review/model.ts").Person, "epoch">;
+}>;

package/dist/scripts/people.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+// The people who comment on the deployed prototypes. The first editor is
+// invited from here; after that, editors invite from the People tab.
+import { ROLES } from '../core/review/model.js';
+import { CliError } from './lib/cli.js';
+import { cliActor, cliReview } from './lib/review.js';
+export const spec = {
+    name: 'people',
+    summary: 'List, invite, reissue or revoke the people who comment on the deployed prototypes.',
+    positionals: [
+        {
+            name: 'action',
+            description: 'list (default): everyone who may comment. invite: a new person and their link. reissue <id>: a new link; the old one and every session stop. revoke <id>.',
+        },
+        { name: 'id', description: 'The person, for reissue and revoke' },
+    ],
+    flags: {
+        name: { type: 'string', description: 'For invite: their name as it shows on comments.' },
+        team: { type: 'string', description: "For invite: the studio, or the client's company." },
+        role: {
+            type: 'string',
+            default: 'reviewer',
+            choices: ROLES,
+            description: 'reviewer comments; editor also resolves, sorts and invites.',
+        },
+        site: { type: 'string', description: 'The deployed URL, so the invite link prints whole.' },
+        local: {
+            type: 'boolean',
+            description: 'Use the local dev store even when the deployed one is configured.',
+        },
+    },
+    output: '{ ok, store, people } or { ok, store, person, link }',
+};
+const linkFor = (token, site) => {
+    const path = `/invite/${token}`;
+    if (!site)
+        return { link: path, next: 'Prefix the link with the deployed URL, or pass --site <url>.' };
+    try {
+        return { link: new URL(path, site).href };
+    }
+    catch {
+        throw new CliError('--site takes a URL.', { got: site });
+    }
+};
+export async function main({ positionals: [action = 'list', id], flags }) {
+    const { review, store } = cliReview(flags.local);
+    const actor = cliActor();
+    const strip = ({ epoch: _e, ...rest }) => rest;
+    switch (action) {
+        case 'list':
+            return { store, people: (await review.listPeople(actor)).map(strip) };
+        case 'invite': {
+            const { person, token } = await review.invite(actor, {
+                name: flags.name,
+                team: flags.team,
+                role: flags.role,
+            });
+            return { store, person: strip(person), ...linkFor(token, flags.site) };
+        }
+        case 'reissue':
+        case 'revoke': {
+            if (!id)
+                throw new CliError(`Name the person: pnpm people ${action} <id>.`, { fix: 'pnpm people lists ids.' });
+            if (action === 'revoke')
+                return { store, person: strip(await review.revoke(actor, id)) };
+            const { person, token } = await review.reissue(actor, id);
+            return { store, person: strip(person), ...linkFor(token, flags.site) };
+        }
+        default:
+            throw new CliError(`Unknown action ${action}.`, { fix: 'list, invite, reissue or revoke' });
+    }
+}

package/dist/scripts/preflight.d.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+import { type OnDisk } from './lib/catalog.ts';
+import type { Args } from './lib/cli.ts';
+import { judge } from './lib/judge.ts';
+export declare const STEPS: readonly ['checks', 'types', 'lint', 'build', 'elyx', 'guides', 'states', 'contacts', 'gate', 'secrets'];
+type StepName = (typeof STEPS)[number];
+export declare const spec: {
+    readonly name: 'preflight';
+    readonly summary: 'Run every check a share link needs. Exit 1 when any step fails.';
+    readonly flags: {
+        readonly skip: {
+            readonly type: 'list';
+            readonly description: `A step to skip: ${string}.`;
+        };
+        readonly 'allow-contact': {
+            readonly type: 'list';
+            readonly description: 'A contact the user confirmed is a business, added to .design-hub/checks.json contacts.allow.';
+        };
+    };
+    readonly output: '{ ok, steps: [{ step, ok, skipped?, detail?, fix? }] }';
+};
+type Step = {
+    step: StepName;
+    ok: boolean;
+    skipped?: string;
+    detail?: unknown;
+    fix?: string;
+};
+export declare function states(all: OnDisk[], ask?: typeof judge): Promise<Step>;
+export declare function contacts(all: OnDisk[], allow: Set<string>, ask?: typeof judge): Promise<Step>;
+export declare function main({ flags }: Args<typeof spec>): Promise<{
+    ok: boolean;
+    steps: Step[];
+}>;
+export {};

package/dist/scripts/preflight.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+// Everything that must be true before a share link goes out, in one run, so
+// no step depends on Claude remembering it. Every step runs, so one failure
+// never hides the next; the JSON says which failed and the fix.
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+import { isLive } from '../core/catalog.js';
+import { DEFAULT_CHECKS, reaches } from '../core/checks.js';
+import { contactsInJson } from '../core/contacts.js';
+import { noulOf } from '../core/jev.js';
+import { checkProblems, checks } from '../server/checks.js';
+import { CHECKS_FILE, DOCS, ROOT } from '../server/paths.js';
+import { lint, typecheck } from './check.js';
+import { build } from './dev.js';
+import * as elyxCommand from './elyx.js';
+import { prototypes } from './lib/catalog.js';
+import { judge } from './lib/judge.js';
+import { NOULS } from './lib/rules.js';
+import { gateEnvMissing } from './lib/vercel.js';
+export const STEPS = [
+    'checks',
+    'types',
+    'lint',
+    'build',
+    'elyx',
+    'guides',
+    'states',
+    'contacts',
+    'gate',
+    'secrets',
+];
+export const spec = {
+    name: 'preflight',
+    summary: 'Run every check a share link needs. Exit 1 when any step fails.',
+    flags: {
+        skip: { type: 'list', description: `A step to skip: ${STEPS.join(', ')}.` },
+        'allow-contact': {
+            type: 'list',
+            description: 'A contact the user confirmed is a business, added to .design-hub/checks.json contacts.allow.',
+        },
+    },
+    output: '{ ok, steps: [{ step, ok, skipped?, detail?, fix? }] }',
+};
+const MAX_CODE_CHARS = 12_000;
+const outcome = (step, run, fix) => run.ok ? { step, ok: true } : { step, ok: false, detail: run.output ?? run.error, fix };
+/** Prototypes a reviewer is sent to: live sprints and their alternates. */
+const reviewed = (all) => all.filter((p) => isLive(p) && p.kind !== 'exploration');
+function guides(all) {
+    const features = [
+        ...new Set(reviewed(all)
+            .map((p) => p.feature)
+            .filter(Boolean)),
+    ];
+    const missing = features.filter((f) => !existsSync(join(DOCS, 'sprints', f, 'guide.md')));
+    return missing.length
+        ? {
+            step: 'guides',
+            ok: false,
+            detail: { missing },
+            fix: 'design-hub guide <feature>, written from the States table.',
+        }
+        : { step: 'guides', ok: true, detail: { features } };
+}
+function code(dir) {
+    return readdirSync(dir)
+        .filter((f) => /\.tsx?$/.test(f) && !f.endsWith('.test.ts'))
+        .map((f) => `// ${f}\n${readFileSync(join(dir, f), 'utf8')}`)
+        .join('\n\n')
+        .slice(0, MAX_CODE_CHARS);
+}
+export async function states(all, ask = judge) {
+    const problems = [];
+    for (const p of reviewed(all)) {
+        if (!p.states?.length) {
+            problems.push({ prototype: p.slug, problem: 'README has no States rows' });
+            continue;
+        }
+        if (!checks)
+            continue;
+        const judged = await ask({
+            check: 'states',
+            subject: p.slug,
+            state: {
+                prototype: p.slug,
+                readmeStates: p.states.map((s) => s.name),
+                change: { content: code(p.dir) },
+            },
+            questions: { state: { type: 'noul', instructions: NOULS.state } },
+        });
+        const prob = judged ? noulOf(judged.answers, 'state') : null;
+        if (prob !== null && reaches(prob, checks.states.blockAt))
+            problems.push({
+                prototype: p.slug,
+                problem: 'renders a state the States table does not list',
+                p: prob,
+                id: judged?.ids.state,
+            });
+    }
+    return problems.length
+        ? {
+            step: 'states',
+            ok: false,
+            detail: problems,
+            fix: 'Add a row per state, with how to reach it, to the README.',
+        }
+        : { step: 'states', ok: true };
+}
+export async function contacts(all, allow, ask = judge) {
+    const flagged = [];
+    for (const p of all) {
+        const file = join(p.dir, 'fixtures.json');
+        if (!existsSync(file))
+            continue;
+        const found = contactsInJson(JSON.parse(readFileSync(file, 'utf8'))).filter((c) => !allow.has(c.value));
+        if (!found.length)
+            continue;
+        const rel = relative(ROOT, file);
+        // With Jev, only a private person's details stop the share; without it, every match does.
+        const judged = checks &&
+            (await ask({
+                check: 'contacts',
+                subject: rel,
+                state: { contacts: found.map(({ kind, value, path }) => ({ kind, value, path })) },
+                questions: Object.fromEntries(found.map((_, i) => [
+                    `private:${i}`,
+                    {
+                        type: 'noul',
+                        instructions: `Is \`contacts[${i}].value\` the personal contact of a private individual, rather than a business, organisation or role address?`,
+                    },
+                ])),
+            }));
+        found.forEach((c, i) => {
+            const prob = judged ? noulOf(judged.answers, `private:${i}`) : null;
+            if (prob === null || !checks || reaches(prob, checks.contacts.privateAt))
+                flagged.push({
+                    ...c,
+                    file: rel,
+                    private: prob ?? undefined,
+                    id: judged ? judged.ids[`private:${i}`] : undefined,
+                });
+        });
+    }
+    return flagged.length
+        ? {
+            step: 'contacts',
+            ok: false,
+            detail: flagged,
+            fix: 'Show each to the user. Replace it, or after they confirm it is a business contact: design-hub preflight --allow-contact <value>.',
+        }
+        : { step: 'contacts', ok: true };
+}
+// Only for a project that took the Elyx add-on; without the CLI on this machine the check cannot run.
+function elyx() {
+    if (!existsSync(join(ROOT, 'design-system', 'elyx.json')))
+        return { step: 'elyx', ok: true, skipped: 'no design-system/' };
+    if (spawnSync('elyx', ['--version']).error)
+        return { step: 'elyx', ok: true, skipped: 'Elyx CLI not installed' };
+    try {
+        const result = elyxCommand.main({ flags: { check: true }, positionals: [] });
+        return result.ok
+            ? { step: 'elyx', ok: true }
+            : {
+                step: 'elyx',
+                ok: false,
+                detail: result.drift,
+                fix: 'design-hub elyx regenerates design-system/ from tokens.css.',
+            };
+    }
+    catch (error) {
+        return {
+            step: 'elyx',
+            ok: false,
+            detail: error instanceof Error ? error.message : String(error),
+            fix: 'design-hub elyx',
+        };
+    }
+}
+function gate() {
+    if (!existsSync(join(ROOT, '.vercel', 'project.json')))
+        return {
+            step: 'gate',
+            ok: true,
+            skipped: 'not linked to Vercel yet',
+            fix: 'design-hub bootstrap --vercel <project>',
+        };
+    const missing = gateEnvMissing(ROOT);
+    if (missing === null)
+        return { step: 'gate', ok: true, skipped: 'vercel CLI unavailable or signed out' };
+    return missing.length
+        ? {
+            step: 'gate',
+            ok: false,
+            detail: { missing },
+            fix: 'design-hub bootstrap --vercel <project> sets them.',
+        }
+        : { step: 'gate', ok: true };
+}
+function secrets() {
+    const ignored = spawnSync('git', ['-C', ROOT, 'check-ignore', '-q', '.env']).status === 0;
+    const tracked = (spawnSync('git', ['-C', ROOT, 'ls-files'], { encoding: 'utf8' }).stdout ?? '')
+        .split('\n')
+        .filter((f) => /(^|\/)\.env(\.|$)/.test(f) && !f.endsWith('.env.example'));
+    if (ignored && !tracked.length)
+        return { step: 'secrets', ok: true };
+    return {
+        step: 'secrets',
+        ok: false,
+        detail: { envIgnored: ignored, tracked },
+        fix: 'Keep .env in .gitignore; git rm --cached any tracked env file.',
+    };
+}
+function allowContacts(values) {
+    const current = (existsSync(CHECKS_FILE) ? JSON.parse(readFileSync(CHECKS_FILE, 'utf8')) : structuredClone(DEFAULT_CHECKS));
+    const allow = new Set([...(current.contacts.allow ?? []), ...values]);
+    if (values.length) {
+        current.contacts.allow = [...allow].sort();
+        mkdirSync(dirname(CHECKS_FILE), { recursive: true });
+        writeFileSync(CHECKS_FILE, `${JSON.stringify(current, null, 2)}\n`);
+    }
+    return allow;
+}
+export async function main({ flags }) {
+    const skip = new Set(flags.skip);
+    const all = prototypes();
+    const allow = allowContacts(flags['allow-contact']);
+    const run = {
+        checks: () => checkProblems.length
+            ? {
+                step: 'checks',
+                ok: false,
+                detail: checkProblems,
+                fix: 'Fix .design-hub/checks.json; every Jev check is off until then.',
+            }
+            : { step: 'checks', ok: true },
+        types: () => outcome('types', typecheck(), 'Fix what tsc names.'),
+        lint: () => outcome('lint', lint(false), 'design-hub check --fix for formatting; the rest by hand.'),
+        build: async () => outcome('build', await build(), 'A missing walkthrough image fails here first.'),
+        elyx,
+        guides: () => guides(all),
+        states: () => states(all),
+        contacts: () => contacts(all, allow),
+        gate,
+        secrets,
+    };
+    const steps = [];
+    for (const name of STEPS)
+        steps.push(skip.has(name) ? { step: name, ok: true, skipped: 'skipped by --skip' } : await run[name]());
+    return { ok: steps.every((s) => s.ok), steps };
+}

package/dist/scripts/release-check.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { type Args } from './lib/cli.ts';
+export declare const spec: {
+    readonly name: 'release-check';
+    readonly summary: 'Fail when any tracked file contains one of the given terms.';
+    readonly flags: {
+        readonly term: {
+            readonly type: 'list';
+            readonly description: 'A term to refuse, case-insensitive. Repeat for more.';
+        };
+    };
+    readonly output: '{ ok, terms, files, hits: { <file>: [terms] } }';
+};
+export declare function main({ flags }: Args<typeof spec>): {
+    ok: boolean;
+    terms: string[];
+    files: number;
+    hits: Record<string, string[]>;
+};