@milesroxas/design-hub 0.0.0-stage → 0.1.0

package/dist/scripts/elyx.js

@@ -0,0 +1,195 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+// The Elyx add-on, one way only: tokens.css stays the single source and
+// design-system/ is generated from it, so the two never disagree. A designer
+// consumes it as a read-only Elyx dependency. Two-way sync is refused on
+// purpose: Elyx rounds colours to 8 bits, keeps one font of a stack, cannot
+// hold shadows, rings, easings or durations, and rewrites files on save, so
+// anything read back would quietly change or delete tokens.
+// Needs the Elyx CLI: npm install --global @elyx-design/cli
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import { KIT, ROOT } from '../server/paths.js';
+import { CliError } from './lib/cli.js';
+import { block, classify, toHex } from './lib/css-tokens.js';
+export const spec = {
+    name: 'elyx',
+    summary: 'Generate the Elyx design-system project from kit/tokens.css, or check it has not drifted.',
+    flags: {
+        check: { type: 'boolean', description: 'Fail when design-system/ differs from a fresh generation.' },
+    },
+    output: '{ ok, out, tokens, skipped, diagnostics } or { ok, drift }',
+};
+const TOKENS = join(KIT, 'tokens.css');
+const OUT = join(ROOT, 'design-system');
+const SOURCE = 'kit/tokens.css';
+function elyx(cwd, args) {
+    const run = spawnSync('elyx', args, { cwd, encoding: 'utf8' });
+    if (run.error)
+        throw new CliError('The Elyx CLI is not installed.', { fix: 'npm install --global @elyx-design/cli' });
+    if (run.status !== 0)
+        throw new CliError(`elyx ${args[0]} failed.`, { stderr: (run.stderr || run.stdout).trim().slice(-800) });
+    return run.stdout;
+}
+const header = (what) => `// GENERATED from ${SOURCE}${what} by \`design-hub elyx\`.\n// Do not edit: change tokens.css and run it again.\n`;
+const members = (rows) => rows.map(([n, v]) => `  ${n}: ${v}`).join(',\n');
+export function plan(css) {
+    const light = block(css, ':root');
+    const dark = block(css, '.dark-mode');
+    const groups = { color: [], radius: [], length: [], font: [] };
+    const skipped = [];
+    for (const [name, value] of light) {
+        const c = classify(name, value);
+        if (c.kind === 'skip')
+            skipped.push(`--${name}: ${c.why}`);
+        else
+            groups[c.kind].push([name, c.value]);
+    }
+    const colors = new Set(groups.color.map(([n]) => n));
+    const darkColors = [];
+    for (const [name, value] of dark) {
+        if (!light.has(name))
+            throw new CliError(`--${name} is set in .dark-mode but not on :root.`, {
+                fix: 'Give it a light value.',
+            });
+        if (!colors.has(name)) {
+            skipped.push(`--${name} (.dark-mode): not a colour token`);
+            continue;
+        }
+        const hex = toHex(value);
+        if (!hex)
+            throw new CliError(`--${name}: the dark value ${value} is not a colour.`);
+        darkColors.push([name, hex]);
+    }
+    const family = groups.font.find(([n]) => n === 'font')?.[1];
+    const files = {
+        // Hex encoding stops Elyx rewriting every colour as rgb() percentages on save.
+        'elyx.json': `${JSON.stringify({
+            color: { encoding: 'hex' },
+            ...(family ? { defaults: { text: { font: { family: JSON.parse(family), style: 'Regular' } } } } : {}),
+            exports: { './tokens/*': './tokens/*' },
+        }, null, 2)}\n`,
+        'tokens/colors.elyx': `import "tokens/colors.dark.elyx" as dark\n\n${header('')}file {}\n\n@variants(dark.darkColors)\nexport colors = tokens {\n${members(groups.color)}\n}\n`,
+        'tokens/colors.dark.elyx': `import "tokens/colors.elyx" as base\n\n${header(' (.dark-mode)')}@context(theme="dark")\nfile {}\n\nexport darkColors = tokens : base.colors {\n${members(darkColors)}\n}\n`,
+    };
+    if (groups.radius.length)
+        files['tokens/radius.elyx'] =
+            `${header('')}file {}\n\nexport radius = tokens {\n${members(groups.radius)}\n}\n`;
+    if (groups.length.length)
+        files['tokens/lengths.elyx'] =
+            `${header('')}file {}\n\nexport lengths = tokens {\n${members(groups.length)}\n}\n`;
+    if (groups.font.length)
+        files['tokens/typography.elyx'] =
+            `${header('')}file {}\n\nexport fonts = tokens {\n${members(groups.font)}\n}\n`;
+    return {
+        files,
+        light,
+        dark,
+        counts: {
+            colors: groups.color.length,
+            dark: darkColors.length,
+            radius: groups.radius.length,
+            lengths: groups.length.length,
+            fonts: groups.font.length,
+        },
+        skipped,
+    };
+}
+const README = `# Design system (generated)
+
+An Elyx token project generated from \`${SOURCE}\` by \`design-hub elyx\`. Never edit it here: change \`tokens.css\` and run \`design-hub elyx\` again. \`design-hub elyx --check\` fails when this folder has drifted.
+
+Use it from a designer's Elyx project as a read-only dependency, so a save in Elyx can never write back:
+
+\`\`\`json
+{ "dependencies": { "hub": "path:../design-system" } }
+\`\`\`
+
+Then \`elyx deps fetch\`, and \`import "@hub/tokens/colors.elyx"\`. Commit \`elyx.lock\`, ignore \`elyx_deps/\`, and fetch again after each regeneration.
+
+Shadows, focus rings, easings and durations have no Elyx token type and are left out; \`tokens.css\` keeps them.
+`;
+/** Writes the project into `out`, normalizes it the way the Elyx app saves, and proves it matches tokens.css. */
+function generate(out) {
+    const { files, light, dark, counts, skipped } = plan(readFileSync(TOKENS, 'utf8'));
+    rmSync(out, { recursive: true, force: true });
+    mkdirSync(join(out, 'tokens'), { recursive: true });
+    for (const [path, text] of Object.entries(files))
+        writeFileSync(join(out, path), text);
+    writeFileSync(join(out, 'README.md'), README);
+    for (const path of Object.keys(files).filter((p) => p.endsWith('.elyx')))
+        elyx(out, ['normalize', '-w', path]);
+    const diagnostics = JSON.parse(elyx(out, ['diagnostics', '.']));
+    if (diagnostics.errors)
+        throw new CliError('Elyx reports errors in the generated project.', { diagnostics });
+    const problems = roundTrip(out, light, dark);
+    if (problems.length)
+        throw new CliError('The Elyx export does not match tokens.css.', { problems });
+    return { counts, skipped, diagnostics };
+}
+const bytes = (hex) => [0, 2, 4, 6].map((i) => (i < hex.length - 1 ? Number.parseInt(hex.slice(1 + i, 3 + i), 16) : 255));
+function exported(value) {
+    const m = value.match(/^rgb\((\d+) (\d+) (\d+)(?: \/ ([\d.]+))?\)$/);
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3]), Math.round(Number(m[4] ?? 1) * 255)] : null;
+}
+/** A token whose bytes differ from tokens.css, or null when they match or cannot be compared. */
+export function mismatch(t, source) {
+    const hex = source ? toHex(source) : null;
+    const got = exported(t.value);
+    if (!hex || !got || bytes(hex).join() === got.join())
+        return null;
+    return `${t.context.theme === 'dark' ? 'dark' : 'light'} ${t.name}: ${source} became ${t.value}`;
+}
+/** Colours in tokens.css that the export dropped; Elyx drops what it cannot hold without an error. */
+function dropped(theme, declared, seen) {
+    return [...declared]
+        .filter(([name, value]) => classify(name, value).kind === 'color' && !seen.has(name))
+        .map(([name]) => `${theme} ${name}: missing`);
+}
+/** Every colour in tokens.css is in the export with the same bytes, in both themes. */
+function roundTrip(out, light, dark) {
+    const tokens = JSON.parse(elyx(out, ['tokens', 'tokens/colors.elyx', '--format', 'json'])).tokens;
+    const darkTokens = tokens.filter((t) => t.context.theme === 'dark');
+    const lightTokens = tokens.filter((t) => t.context.theme !== 'dark');
+    return [
+        ...lightTokens.map((t) => mismatch(t, light.get(t.name))),
+        // A dark token without an override inherits the light value.
+        ...darkTokens.map((t) => mismatch(t, dark.get(t.name) ?? light.get(t.name))),
+        ...dropped('light', light, new Set(lightTokens.map((t) => t.name))),
+        ...dropped('dark', dark, new Set(darkTokens.map((t) => t.name))),
+    ].filter((p) => p !== null);
+}
+const listFiles = (dir, base = dir) => existsSync(dir)
+    ? readdirSync(dir, { withFileTypes: true }).flatMap((d) => d.isDirectory()
+        ? d.name === 'elyx_deps'
+            ? []
+            : listFiles(join(dir, d.name), base)
+        : [relative(base, join(dir, d.name))])
+    : [];
+export function main({ flags }) {
+    if (!flags.check) {
+        const result = generate(OUT);
+        return {
+            out: relative(ROOT, OUT),
+            tokens: result.counts,
+            skipped: result.skipped,
+            diagnostics: result.diagnostics,
+        };
+    }
+    const tmp = mkdtempSync(join(tmpdir(), 'hub-elyx-'));
+    try {
+        generate(tmp);
+        const files = new Set([...listFiles(tmp), ...listFiles(OUT)]);
+        const drift = [...files].filter((f) => {
+            const a = join(tmp, f);
+            const b = join(OUT, f);
+            return !existsSync(a) || !existsSync(b) || readFileSync(a, 'utf8') !== readFileSync(b, 'utf8');
+        });
+        return { ok: drift.length === 0, drift, fix: drift.length ? 'design-hub elyx' : undefined };
+    }
+    finally {
+        rmSync(tmp, { recursive: true, force: true });
+    }
+}

package/dist/scripts/fixtures-pull.d.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+import { type Args } from './lib/cli.ts';
+export declare const spec: {
+    readonly name: 'fixtures-pull';
+    readonly summary: "Write a prototype's real fixtures from a Webflow CMS collection.";
+    readonly positionals: [{
+        readonly name: 'prototype';
+        readonly description: 'The prototype folder, e.g. sample-list';
+        readonly required: true;
+    }];
+    readonly flags: {
+        readonly collection: {
+            readonly type: 'string';
+            readonly required: true;
+            readonly description: 'The Webflow collection id.';
+        };
+        readonly map: {
+            readonly type: 'list';
+            readonly description: 'key=field.path: the fixture key and the fieldData path it comes from (thumbnail.url). Omit to list fields.';
+        };
+        readonly limit: {
+            readonly type: 'number';
+            readonly default: 20;
+            readonly description: 'How many items to keep.';
+        };
+        readonly staged: {
+            readonly type: 'boolean';
+            readonly description: 'Read staged items (drafts included) instead of published ones.';
+        };
+    };
+    readonly output: '{ ok, file, items, contacts } or, without --map, { ok: false, fields }';
+};
+type Item = {
+    id: string;
+    isDraft?: boolean;
+    isArchived?: boolean;
+    fieldData: Record<string, unknown>;
+};
+export type FieldMap = {
+    key: string;
+    path: string[];
+};
+export declare function parseMap(raw: string): FieldMap;
+/** One fixture item: the Webflow id, then each mapped field; a path that is not there is null. */
+export declare function pick(item: Item, maps: FieldMap[]): Record<string, unknown>;
+export declare function main({ positionals: [slug], flags }: Args<typeof spec>): Promise<{
+    ok: boolean;
+    error: string;
+    fields: {
+        field: string;
+        type: string;
+        displayName: string;
+    }[];
+} | {
+    file: string;
+    items: number;
+    contacts: number;
+    next: string;
+}>;
+export {};

package/dist/scripts/fixtures-pull.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+// Writes a prototype's `real` fixtures from a Webflow CMS collection, with
+// only the fields the component renders, so a pull spends nothing on fields
+// nobody reads. Pages through the Data API (100 items a request) for any
+// --limit. Every other key in fixtures.json is kept. Run with no --map to
+// list the collection's fields. Needs WEBFLOW_TOKEN (cms:read) in .env.
+// API: https://developers.webflow.com/data/reference/cms/collection-items
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { contactsInJson } from '../core/contacts.js';
+import { readEnv } from '../server/env.js';
+import { PROTOTYPES, ROOT } from '../server/paths.js';
+import { CliError } from './lib/cli.js';
+export const spec = {
+    name: 'fixtures-pull',
+    summary: "Write a prototype's real fixtures from a Webflow CMS collection.",
+    positionals: [{ name: 'prototype', description: 'The prototype folder, e.g. sample-list', required: true }],
+    flags: {
+        collection: { type: 'string', required: true, description: 'The Webflow collection id.' },
+        map: {
+            type: 'list',
+            description: 'key=field.path: the fixture key and the fieldData path it comes from (thumbnail.url). Omit to list fields.',
+        },
+        limit: { type: 'number', default: 20, description: 'How many items to keep.' },
+        staged: {
+            type: 'boolean',
+            description: 'Read staged items (drafts included) instead of published ones.',
+        },
+    },
+    output: '{ ok, file, items, contacts } or, without --map, { ok: false, fields }',
+};
+const API = 'https://api.webflow.com/v2';
+const PAGE = 100;
+const TIMEOUT_MS = 15_000;
+export function parseMap(raw) {
+    const at = raw.indexOf('=');
+    const key = at > 0 ? raw.slice(0, at).trim() : '';
+    const path = at > 0 ? raw.slice(at + 1).trim() : '';
+    if (!/^[A-Za-z_][\w]*$/.test(key) || !path)
+        throw new CliError(`--map ${raw}: write it as key=field.path.`, { example: '--map cover=thumbnail.url' });
+    return { key, path: path.split('.') };
+}
+/** One fixture item: the Webflow id, then each mapped field; a path that is not there is null. */
+export function pick(item, maps) {
+    const out = { id: item.id };
+    for (const { key, path } of maps) {
+        let value = item.fieldData;
+        for (const part of path)
+            value = value && typeof value === 'object' ? value[part] : undefined;
+        out[key] = value ?? null;
+    }
+    return out;
+}
+async function get(token, path) {
+    const response = await fetch(`${API}${path}`, {
+        headers: { authorization: `Bearer ${token}`, accept: 'application/json' },
+        signal: AbortSignal.timeout(TIMEOUT_MS),
+    });
+    if (!response.ok)
+        throw new CliError(`Webflow answered ${response.status} for ${path}.`, {
+            body: (await response.text()).slice(0, 300),
+            fix: response.status === 401 || response.status === 403
+                ? 'WEBFLOW_TOKEN needs the cms:read scope.'
+                : undefined,
+        });
+    return (await response.json());
+}
+async function listFields(token, collection) {
+    const schema = await get(token, `/collections/${collection}`);
+    return {
+        ok: false,
+        error: `Name the fields the component renders with --map, from ${schema.displayName}'s fields.`,
+        fields: schema.fields.map(({ slug: field, type, displayName }) => ({ field, type, displayName })),
+    };
+}
+/** Pages through the collection until `limit` unarchived items are in, or it runs out. */
+async function pullItems(token, collection, limit, staged) {
+    const items = [];
+    const listing = staged ? 'items' : 'items/live';
+    for (let offset = 0; items.length < limit; offset += PAGE) {
+        const page = await get(token, `/collections/${collection}/${listing}?offset=${offset}&limit=${PAGE}`);
+        items.push(...page.items.filter((i) => !i.isArchived));
+        if (offset + PAGE >= page.pagination.total || !page.items.length)
+            break;
+    }
+    return items.slice(0, limit);
+}
+/** Replaces `real` and keeps every other set, adding an empty `missing` for the hand-written cases. */
+function writeReal(file, real) {
+    const current = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+    writeFileSync(file, `${JSON.stringify({ ...current, real, missing: current.missing ?? [] }, null, 2)}\n`);
+}
+export async function main({ positionals: [slug], flags }) {
+    const token = readEnv(ROOT).WEBFLOW_TOKEN;
+    if (!token)
+        throw new CliError('WEBFLOW_TOKEN is not in .env.', {
+            fix: 'Create a site token with cms:read in Webflow (Site settings, Apps & integrations) and add WEBFLOW_TOKEN=<token> to .env.',
+        });
+    const dir = join(PROTOTYPES, slug);
+    if (!existsSync(join(dir, 'README.md')))
+        throw new CliError(`No prototype called ${slug}.`);
+    const collection = encodeURIComponent(flags.collection);
+    if (!flags.map.length)
+        return listFields(token, collection);
+    const maps = flags.map.map(parseMap);
+    if (!Number.isInteger(flags.limit) || flags.limit < 1)
+        throw new CliError('--limit takes a whole number above 0.');
+    const real = (await pullItems(token, collection, flags.limit, flags.staged)).map((i) => pick(i, maps));
+    const file = join(dir, 'fixtures.json');
+    writeReal(file, real);
+    const contacts = contactsInJson(real).length;
+    return {
+        file: relative(ROOT, file),
+        items: real.length,
+        contacts,
+        next: contacts
+            ? `${contacts} email or phone values came in; design-hub preflight stops on them until each is confirmed or replaced.`
+            : 'Write the missing set by hand (miles-get-hostile).',
+    };
+}

package/dist/scripts/guard.d.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+import type { Args } from './lib/cli.ts';
+import { judge } from './lib/judge.ts';
+export declare const spec: {
+    readonly name: 'guard';
+    readonly summary: 'Run the fidelity guard over whole files, as if each had just been written.';
+    readonly positionals: [{
+        readonly name: 'file';
+        readonly description: 'A file under prototypes/ or kit/';
+        readonly required: true;
+        readonly variadic: true;
+    }];
+    readonly flags: {};
+    readonly output: '{ ok, findings: [{ file, rule, level, note, p?, id? }] }';
+};
+export type Change = {
+    file: string;
+    added: string;
+    removed: string;
+    whole: boolean;
+};
+export type Level = 'warn' | 'block';
+export type Finding = {
+    file: string;
+    rule: string;
+    level: Level;
+    note: string;
+    p?: number;
+    id?: string;
+};
+/** The feature folder a file belongs to, or null for anything outside prototypes/<slug>/. */
+export declare function featureOf(file: string): string | null;
+export declare function codeFindings(change: Change): Finding[];
+export declare function readmeStates(feature: string): string[];
+export declare function jevFindings(change: Change, feature: string, ask?: typeof judge): Promise<Finding[]>;
+export declare function findings(change: Change): Promise<Finding[]>;
+type HookInput = {
+    tool_input?: {
+        file_path?: string;
+        content?: string;
+        old_string?: string;
+        new_string?: string;
+        edits?: {
+            old_string: string;
+            new_string: string;
+        }[];
+    };
+};
+/** The file's real path, through any symlink (/tmp on macOS, a linked checkout), so it compares with ROOT. */
+export declare function realFile(path: string): string;
+export declare function changeFromHook(input: HookInput): Change | null;
+/** The hook's stdout: nothing, a warning as context, or a block Claude must answer. */
+export declare function hookOutput(found: Finding[]): Record<string, unknown> | null;
+export declare function guardHook(): Promise<void>;
+export declare function main({ positionals }: Args<typeof spec>): Promise<{
+    findings: Finding[];
+}>;
+export {};

package/dist/scripts/guard.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+// The fidelity guard. A Claude Code PostToolUse hook (`design-hub hook
+// fidelity-guard`, the hook JSON on stdin) over each file written under
+// prototypes/ or kit/, and `design-hub guard <file>` by hand over a file's
+// whole content.
+//
+// Code checks always run: a write outside a feature folder, a new
+// dependency, an import that crosses prototypes. With TYPESAFE_API_KEY in
+// .env, four Nouls follow on the change (rules.ts), in one request. A
+// finding at or over the project's `fidelity.warnAt` goes back to Claude as
+// context; at or over `blockAt`, or a crossing import, it goes back as a
+// block, which makes Claude answer it before going on. Anything countable
+// stays in code; Jev answers only the semantic part.
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { reaches } from '../core/checks.js';
+import { SET_NAMES } from '../core/fixtures.js';
+import { noulOf } from '../core/jev.js';
+import { parseStates } from '../core/states.js';
+import { checks } from '../server/checks.js';
+import { KIT, PROTOTYPES, ROOT } from '../server/paths.js';
+import { judge } from './lib/judge.js';
+import { NOULS, RULE } from './lib/rules.js';
+export const spec = {
+    name: 'guard',
+    summary: 'Run the fidelity guard over whole files, as if each had just been written.',
+    positionals: [
+        { name: 'file', description: 'A file under prototypes/ or kit/', required: true, variadic: true },
+    ],
+    flags: {},
+    output: '{ ok, findings: [{ file, rule, level, note, p?, id? }] }',
+};
+const MAX_CHANGE_CHARS = 12_000;
+const inside = (file, dir) => file === dir || file.startsWith(dir + sep);
+/** The feature folder a file belongs to, or null for anything outside prototypes/<slug>/. */
+export function featureOf(file) {
+    if (!inside(file, PROTOTYPES))
+        return null;
+    const rel = relative(PROTOTYPES, file);
+    const top = rel.split(sep)[0];
+    if (!top || top.startsWith('_') || top.startsWith('.') || !rel.includes(sep))
+        return null;
+    return top;
+}
+const DEPENDENCY_LINE = /^\s*"[^"]+":\s*"[\^~>=<\d]/gm;
+export function codeFindings(change) {
+    const file = relative(ROOT, change.file);
+    if (basename(change.file) === 'package.json' && dirname(change.file) === ROOT) {
+        const removed = new Set(change.removed.match(DEPENDENCY_LINE) ?? []);
+        const fresh = (change.added.match(DEPENDENCY_LINE) ?? [])
+            .filter((l) => !removed.has(l))
+            .map((l) => l.trim().split('"')[1]);
+        return fresh.length
+            ? [
+                {
+                    file,
+                    rule: RULE.dependency,
+                    level: 'warn',
+                    note: `adds ${fresh.join(', ')}; confirm the user agreed`,
+                },
+            ]
+            : [];
+    }
+    const feature = featureOf(change.file);
+    if (!feature) {
+        if (inside(change.file, KIT))
+            return [
+                {
+                    file,
+                    rule: RULE.fork,
+                    level: 'warn',
+                    note: 'a kit change serves every prototype; copy into the feature folder unless this is a second use',
+                },
+            ];
+        return [];
+    }
+    const out = [];
+    const imports = [...change.added.matchAll(/from\s+['"]([^'"]+)['"]/g)].map((m) => m[1]);
+    const crossing = imports.filter((s) => {
+        if (!s.startsWith('.'))
+            return false;
+        const target = resolve(dirname(change.file), s);
+        return inside(target, PROTOTYPES) && !inside(target, join(PROTOTYPES, feature));
+    });
+    if (crossing.length)
+        out.push({
+            file,
+            rule: RULE.gravity,
+            level: 'block',
+            note: `imports ${crossing.join(', ')}; a prototype imports only @kit/* and its own folder`,
+        });
+    return out;
+}
+const clip = (text) => text.length > MAX_CHANGE_CHARS ? `${text.slice(0, MAX_CHANGE_CHARS)}\n…[clipped]` : text;
+export function readmeStates(feature) {
+    const file = join(PROTOTYPES, feature, 'README.md');
+    return existsSync(file) ? (parseStates(readFileSync(file, 'utf8')) ?? []).map((s) => s.name) : [];
+}
+export async function jevFindings(change, feature, ask = judge) {
+    if (!checks || !/\.(tsx?|jsx?)$/.test(change.file) || /\.test\.tsx?$/.test(change.file))
+        return [];
+    const file = relative(ROOT, change.file);
+    const state = {
+        file,
+        readmeStates: readmeStates(feature),
+        fixtureSets: SET_NAMES,
+        change: change.whole
+            ? { content: clip(change.added) }
+            : { removed: clip(change.removed), added: clip(change.added) },
+    };
+    const rules = Object.keys(NOULS);
+    const judged = await ask({
+        check: 'fidelity',
+        subject: file,
+        state,
+        questions: Object.fromEntries(rules.map((r) => [r, { type: 'noul', instructions: NOULS[r] }])),
+        excerpt: clip(change.added).slice(0, 1500),
+    });
+    if (!judged)
+        return [];
+    const { warnAt, blockAt } = checks.fidelity;
+    return rules.flatMap((r) => {
+        const p = noulOf(judged.answers, r);
+        if (p === null || (!reaches(p, warnAt) && !reaches(p, blockAt)))
+            return [];
+        return [
+            {
+                file,
+                rule: RULE[r],
+                level: reaches(p, blockAt) ? 'block' : 'warn',
+                note: NOULS[r],
+                p,
+                id: judged.ids[r],
+            },
+        ];
+    });
+}
+export async function findings(change) {
+    if (!inside(change.file, ROOT) || /\/(node_modules|dist)\//.test(change.file))
+        return [];
+    const feature = featureOf(change.file);
+    return [...codeFindings(change), ...(feature ? await jevFindings(change, feature) : [])];
+}
+/** The file's real path, through any symlink (/tmp on macOS, a linked checkout), so it compares with ROOT. */
+export function realFile(path) {
+    const abs = resolve(path);
+    try {
+        return realpathSync(abs);
+    }
+    catch {
+        return join(realFile(dirname(abs)), basename(abs));
+    }
+}
+export function changeFromHook(input) {
+    const t = input.tool_input;
+    if (!t?.file_path)
+        return null;
+    const file = realFile(t.file_path);
+    if (t.edits)
+        return {
+            file,
+            added: t.edits.map((e) => e.new_string).join('\n'),
+            removed: t.edits.map((e) => e.old_string).join('\n'),
+            whole: false,
+        };
+    if (t.old_string !== undefined || t.new_string !== undefined)
+        return { file, added: t.new_string ?? '', removed: t.old_string ?? '', whole: false };
+    return { file, added: t.content ?? '', removed: '', whole: true };
+}
+const line = (f) => `${f.file}: ${f.rule}${f.p !== undefined ? ` (p=${f.p.toFixed(2)}, log ${f.id})` : ''}. ${f.note}`;
+/** The hook's stdout: nothing, a warning as context, or a block Claude must answer. */
+export function hookOutput(found) {
+    if (!found.length)
+        return null;
+    const blocking = found.some((f) => f.level === 'block');
+    const text = `Fidelity guard: ${found.map(line).join(' | ')}. Hold the fidelity ceiling in miles-prototype, or say why this one earns it.`;
+    const context = { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } };
+    return blocking ? { decision: 'block', reason: text, ...context } : context;
+}
+export async function guardHook() {
+    let input;
+    try {
+        input = JSON.parse(readFileSync(0, 'utf8'));
+    }
+    catch {
+        return;
+    }
+    const change = changeFromHook(input);
+    const output = change ? hookOutput(await findings(change)) : null;
+    if (output)
+        console.log(JSON.stringify(output));
+}
+export async function main({ positionals }) {
+    const all = [];
+    for (const path of positionals) {
+        const file = realFile(path);
+        all.push(...(await findings({ file, added: readFileSync(file, 'utf8'), removed: '', whole: true })));
+    }
+    return { findings: all };
+}

package/dist/scripts/hook.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/** PostToolUse on a Markdown file: ask for the writing pass before the change is reported done. */
+export declare function mdWriting(input: {
+    tool_input?: {
+        file_path?: string;
+    };
+    tool_response?: {
+        filePath?: string;
+    };
+}): {
+    systemMessage: string;
+    hookSpecificOutput: {
+        hookEventName: string;
+        additionalContext: string;
+    };
+} | null;
+export declare const HOOKS: readonly ['fidelity-guard', 'md-writing', 'skill-hint'];
+export declare function runHook(name: string): Promise<void>;