@crouter/api 0.3.387 → 0.3.389

package/dist/core/help.js

@@ -0,0 +1,406 @@
+// Descriptor types and renderers for the -h layer of the crtr CLI.
+// Pure functions — no side effects, no commander, no process.exit.
+// Rendering matches reference.md shapes exactly:
+//   root L11-32, branch L43-58, leaf L65-189.
+/** `help` with the async state the render shows read once: the leaf's for
+ *  ordinary help, only `focusedFlag`'s for focused help. A read that throws
+ *  renders no element, the same soft failure `evalDynamic` gives a sync one. */
+export async function withAsyncHelpState(help, state, focusedFlag) {
+    const read = async (load) => {
+        try {
+            const s = await load();
+            return () => s;
+        }
+        catch {
+            return () => null;
+        }
+    };
+    const flagLoad = focusedFlag === undefined ? undefined : state.flags?.[focusedFlag];
+    const flagState = new Map(flagLoad === undefined ? [] : [[focusedFlag, await read(flagLoad)]]);
+    return {
+        ...help,
+        ...(focusedFlag === undefined && state.leaf !== undefined ? { dynamicState: await read(state.leaf) } : {}),
+        params: help.params?.map((p) => {
+            const dynamicState = p.kind === 'flag' ? flagState.get(p.name) : undefined;
+            return p.kind === 'flag' && p.focusedHelp !== undefined && dynamicState !== undefined
+                ? { ...p, focusedHelp: { ...p.focusedHelp, dynamicState } }
+                : p;
+        }),
+    };
+}
+// Internal helpers
+/** Build a self-named runtime-state element: `<tag attr="v">body</tag>`. The
+ *  subtree that owns the state authors it through this, so the tag name and any
+ *  scalar metadata (e.g. a count) travel with the data and render identically
+ *  at every level the block appears. The tag name carries the label, so the
+ *  body never repeats it. Attribute values are controlled (counts, short
+ *  tokens) and not escaped. */
+export function stateBlock(tag, attrs, body) {
+    const a = Object.entries(attrs)
+        .map(([k, v]) => ` ${k}="${v}"`)
+        .join('');
+    return `<${tag}${a}>\n${body}\n</${tag}>`;
+}
+/** Evaluate a dynamicState hook, soft-failing to null on throw or empty. */
+function evalDynamic(fn) {
+    if (fn === undefined)
+        return null;
+    try {
+        const s = fn();
+        return s !== null && s !== '' ? s : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Return the longest string length in an array of names. */
+function maxLen(names) {
+    let max = 0;
+    for (const n of names) {
+        if (n.length > max)
+            max = n.length;
+    }
+    return max;
+}
+/** Pad a string to the given width with trailing spaces. */
+function pad(s, width) {
+    return s + ' '.repeat(Math.max(0, width - s.length));
+}
+// renderRoot
+const IO_CONTRACT = 'I/O contract: flags and positional args on input; stdout is agent-ready markdown/XML you\n' +
+    'act on directly — read it as a continuation of your prompt, don\'t parse it as data.\n' +
+    'Exit 0 on success, non-zero on failure. Schemas appear at leaf -h; a leaf may route an uncommon flag to focused --flag -h guidance.';
+// Behavioral instruction (not a schema) — engrained in the appended system
+// prompt so the model treats unfamiliar capabilities as a cue to discover the
+// contract, never to guess, AND reads a command's contract before invoking it.
+// Lives in the root guide, outside any leaf -h. Scoped to state-changing
+// invocations: cheap read-only inspection doesn't need a forced preflight.
+const CAPABILITY_DISCOVERY = 'Before running a crtr command that changes state — creates, mutates, or ' +
+    "deletes anything — whose exact contract (args, flags, effects) you haven't " +
+    'verified this session, run `-h` on it and read the schema first — a reliable ' +
+    'read beats a guess that wastes a turn or triggers an unintended effect. ' +
+    'When a leaf routes a flag to focused help, read that focused help before using the flag; the compact row is discovery, not its invocation contract. ' +
+    "Same when the user names a capability you don't fully recognize: " +
+    '`-h` it before acting.';
+/** Lines for a command's subcommand affordance at root: any promoted
+ *  (common/important) subcommands, then a remainder line naming how many other
+ *  subcommands exist behind `crtr <name> -h`. Returns [] when the command has
+ *  no listable subcommands at all. */
+function rootSubcommandLines(c) {
+    const promoted = c.subcommands ?? [];
+    const other = c.otherSubcommandCount ?? 0;
+    if (promoted.length === 0 && other === 0)
+        return [];
+    const out = [];
+    if (promoted.length > 0) {
+        const labelW = maxLen(promoted.map((s) => s.path));
+        for (const s of promoted) {
+            // important → padded name + shortform desc; common → bare name.
+            out.push(s.desc !== undefined && s.desc !== ''
+                ? `  ${pad(s.path, labelW)}  ${s.desc}`
+                : `  ${s.path}`);
+        }
+    }
+    if (other > 0) {
+        const word = promoted.length > 0 ? 'other subcommand' : 'subcommand';
+        out.push(`  [+${other} ${word}${other === 1 ? '' : 's'} — \`crtr ${c.name} -h\`]`);
+    }
+    return out;
+}
+export function renderRoot(h) {
+    const lines = [];
+    lines.push(`${h.tagline}`);
+    lines.push('');
+    // Each subtree is one <command name="…"> block. The uniform wrapper states
+    // "this is a command you invoke as `crtr <name>`" — so the model reads them
+    // by one rule, and a nested state element (which is never a <command>) can't
+    // be mistaken for a sibling command. Inside: the concept (what it is), the
+    // selection rubric (when to pick it), then any self-named state element
+    // grouped with the command it belongs to. Once injected into a system prompt,
+    // each block reads as one self-contained concern domain. Header (tagline) and
+    // footer (Globals + I/O contract + capability-discovery rule) are the only
+    // non-command areas. Two levels of nesting: <command> → <state>.
+    for (const c of h.commands) {
+        lines.push(`<command name="${c.name}">`);
+        lines.push(c.concept);
+        lines.push(`use when ${c.useWhen}`);
+        // The command's subcommand surface: promoted (common/important) children
+        // inline, plus a "[+N other subcommands]" pointer to its own -h. Sits
+        // between the selection rubric and any live state block.
+        for (const l of rootSubcommandLines(c))
+            lines.push(l);
+        // dynamicState returns a complete self-named element (e.g.
+        // <kinds count="7">…</kinds>) — emit it as-is, nested in the command.
+        const state = evalDynamic(c.dynamicState);
+        if (state !== null)
+            lines.push(state);
+        lines.push('</command>');
+        lines.push('');
+    }
+    // Globals block (footer) — rendered only when globals exist, so an empty
+    // list never leaves a bare "Globals" header. -h itself is not a global: the
+    // capability-discovery rule below teaches -h usage with its reasoning, so no
+    // per-command CTA or standalone "-h: print help" stub is needed.
+    if (h.globals.length > 0) {
+        lines.push('Globals');
+        const gNameW = maxLen(h.globals.map((g) => g.name));
+        for (const g of h.globals) {
+            lines.push(`  ${pad(g.name, gNameW)}  ${g.desc}`);
+        }
+        lines.push('');
+    }
+    lines.push(IO_CONTRACT);
+    lines.push('');
+    lines.push(CAPABILITY_DISCOVERY);
+    return lines.join('\n');
+}
+// renderBranch
+/** Escape a value for a rendered XML attribute. Output is light XML around
+ *  markdown read as prose by a model, not parsed — so we only guard the
+ *  double-quote that would visually break the attribute, swapping it for a
+ *  single quote rather than emitting noisy entities. */
+function attr(s) {
+    return s.replace(/"/g, "'");
+}
+/** A branch with more visible children than this lists only its promoted
+ *  (`common` / `important`) children in its own -h and counts the rest. A
+ *  plugin that mounts one command per catalog entry (a provider with >1,000
+ *  services) would otherwise print every one on each `-h`. Unlisted children
+ *  still route, and their own `-h` still renders. */
+export const WIDE_BRANCH_LISTING_LIMIT = 40;
+/** Split a branch's non-hidden children into the ones its -h lists and the count
+ *  it leaves out. A branch at or under the limit, or one with no promoted child
+ *  to fall back on, lists everything. */
+export function collapseWideChildren(visible) {
+    if (visible.length <= WIDE_BRANCH_LISTING_LIMIT)
+        return { listed: [...visible], unlisted: 0 };
+    const promoted = visible.filter((c) => c.tier === 'common' || c.tier === 'important');
+    if (promoted.length === 0)
+        return { listed: [...visible], unlisted: 0 };
+    return { listed: promoted, unlisted: visible.length - promoted.length };
+}
+/** The children of a branch that its parent's (root) -h promotes inline: its
+ *  `common` / `important` ones. On a wide branch only leaves are promoted, so a
+ *  promoted service branch shows in the branch's own -h but does not widen the
+ *  root listing every agent reads. */
+export function rootPromotedChildren(visible) {
+    const wide = visible.length > WIDE_BRANCH_LISTING_LIMIT;
+    return visible.filter((c) => (c.tier === 'common' || c.tier === 'important') && (!wide || c.kind === 'leaf'));
+}
+export function renderBranch(h) {
+    const lines = [];
+    // The branch renders as one <command> card: its own description in the
+    // opening attribute, then orientation prose / live state, then one
+    // self-closing <subcommand> per child. Each child's description + whenToUse
+    // are assembled by defineBranch from the child's own self-description, so the
+    // parent never restates what a child is — the child owns its representation.
+    lines.push(`<command name="${h.name}" description="${attr(h.summary)}">`);
+    const branchState = evalDynamic(h.dynamicState);
+    if (branchState !== null)
+        lines.push(branchState);
+    if (h.model !== undefined)
+        lines.push(h.model);
+    const { listed, unlisted } = collapseWideChildren((h.listing ?? []).filter((c) => c.tier !== 'hidden'));
+    for (const c of listed) {
+        const plugin = c.plugin === undefined ? '' : ` plugin="${attr(c.plugin)}"`;
+        const subs = c.subCount !== undefined && c.subCount > 0 ? ` subcommands="${c.subCount}"` : '';
+        // whenToUse plainly states when to reach for this child, rendered verbatim —
+        // expansive with examples for judgment-heavy commands, concise for
+        // single-purpose ones. It does not restate "read my -h"; the
+        // capability-discovery rule in the root footer already teaches that.
+        if (lines.length > 1)
+            lines.push('');
+        lines.push(`<subcommand name="${c.name}" description="${attr(c.description)}" whenToUse="${attr(c.whenToUse)}"${plugin}${subs}/>`);
+    }
+    if (unlisted > 0) {
+        lines.push('');
+        lines.push(`<unlisted-subcommands count="${unlisted}">${unlisted} more subcommands are not listed here. Each one runs by name, and \`crtr ${h.name} <name> -h\` prints its help.</unlisted-subcommands>`);
+    }
+    if (h.extensionIssue !== undefined) {
+        lines.push(`<extension-issue fragment="${attr(h.extensionIssue.fragment)}">This repository's contributed commands were rejected: ${h.extensionIssue.message}. Run \`crtr sys doctor\` for the full report.</extension-issue>`);
+    }
+    lines.push('</command>');
+    return lines.join('\n');
+}
+// renderLeafArgv
+/** Build the display label for a param entry (left column). */
+function paramLabel(p) {
+    if (p.kind === 'positional')
+        return `${p.name.toUpperCase()}${p.repeatable === true ? '...' : ''}`;
+    if (p.kind === 'stdin')
+        return 'stdin';
+    if (p.kind === 'context-file')
+        return '--context-file PATH';
+    // flag
+    const f = p;
+    if (f.type === 'bool')
+        return `--${f.name}`;
+    return `--${f.name} ${f.name.toUpperCase().replace(/-/g, '_')}`;
+}
+/** Build the description line for a param entry (right column). */
+/** The sentence a `path` param with a declared `encoding` contributes: it is the
+ *  whole reason the agent can pass a local path instead of pre-encoding bytes,
+ *  so the leaf's own `-h` must state it. */
+function fileEncodingNote(encoding) {
+    if (encoding === undefined)
+        return '';
+    return encoding === 'base64'
+        ? ' Local file path: the file is read and its raw bytes are base64-encoded into the request; the path itself is never sent.'
+        : ' Local file path: the file is read as UTF-8 text and its content is sent as the value; the path itself is never sent.';
+}
+/** The sentence a param with an ambient env default contributes — the agent must
+ *  know the value can arrive without being typed, and from where. */
+function envDefaultNote(envVar) {
+    return envVar === undefined
+        ? ''
+        : ` Defaults to $${envVar} when that is set and non-empty in the environment, and counts as supplied.`;
+}
+/** The sentence a `file` param contributes: the value names a file, not text. */
+function fileParamNote(type) {
+    return type === 'file' ? ' A file: pass its path.' : '';
+}
+function focusedFlagHelpNote(flag, leafName) {
+    if (flag.focusedHelp === undefined)
+        return '';
+    return ` Before using this flag, run \`crtr ${leafName} --${flag.name} -h\` and read its focused guidance.`;
+}
+function paramDesc(p, leafName) {
+    const req = p.required ? 'required' : 'optional';
+    if (p.kind === 'positional') {
+        const repeatable = p.repeatable === true
+            ? ' Repeatable — pass multiple values to accumulate in argv order.'
+            : '';
+        return `positional, ${req}.${fileParamNote(p.type)}${fileEncodingNote(p.encoding)}${envDefaultNote(p.defaultFromEnv)} ${p.constraint}${repeatable}`;
+    }
+    if (p.kind === 'stdin')
+        return `${req}. ${p.constraint}`;
+    if (p.kind === 'context-file') {
+        const shape = p.shape !== undefined
+            ? ` Shape: ${p.shape}`
+            : '';
+        return `${req}. Path to a JSON file.${shape} ${p.constraint}`.trim();
+    }
+    // flag
+    const f = p;
+    const focusedNote = focusedFlagHelpNote(f, leafName);
+    if (f.type === 'bool')
+        return `${req} boolean. Presence means true. ${f.constraint}${focusedNote}`.trim();
+    const dflt = f.default !== undefined ? ` Default: ${String(f.default)}.` : '';
+    const choices = f.type === 'enum' && f.choices !== undefined
+        ? ` One of: ${f.choices.join(', ')}.`
+        : '';
+    const repeatable = f.repeatable === true
+        ? ' Repeatable — pass multiple times to accumulate.'
+        : '';
+    return `${f.type}, ${req}.${choices}${dflt}${fileParamNote(f.type)}${fileEncodingNote(f.encoding)}${envDefaultNote(f.defaultFromEnv)} ${f.constraint}${repeatable}${focusedNote}`.trim();
+}
+/** One output shape's type phrase: `array of <element>` for an array with a
+ *  declared element shape, the declared type otherwise. */
+function outputTypePhrase(shape) {
+    if (shape.items === undefined)
+        return shape.type;
+    const nullable = /\|\s*null\s*$/i.test(shape.type) ? ', or null' : '';
+    return `array of ${outputTypePhrase(shape.items)}${nullable}`;
+}
+/** The values sentence of an enum shape, or nothing. */
+function outputValuesNote(shape) {
+    return shape.values !== undefined ? ` One of: ${shape.values.join(', ')}.` : '';
+}
+/** Render output fields as rows, then each structural field's shape beneath
+ *  it, one indent deeper: an object's children, an array's element children
+ *  and enum values, so the result's shape reads straight from `-h`. */
+function renderOutputFields(fields, indent, lines) {
+    const nameW = maxLen(fields.map((f) => f.name));
+    for (const f of fields) {
+        const constraint = f.constraint.length > 0 ? ` ${f.constraint}` : '';
+        lines.push(`${indent}${pad(f.name, nameW)}  ${outputTypePhrase(f)}.${outputValuesNote(f)}${constraint}`);
+        renderOutputShapeBody(f, `${indent}  `, lines);
+    }
+}
+/** The nested part of a shape: object children, or an array element's shape. */
+function renderOutputShapeBody(shape, indent, lines) {
+    if (shape.children !== undefined && shape.children.length > 0) {
+        renderOutputFields(shape.children, indent, lines);
+    }
+    let item = shape.items;
+    while (item !== undefined) {
+        const note = outputValuesNote(item);
+        if (item.constraint.length > 0 || note.length > 0) {
+            lines.push(`${indent}each element: ${outputTypePhrase(item)}.${note}${item.constraint.length > 0 ? ` ${item.constraint}` : ''}`);
+        }
+        if (item.children !== undefined && item.children.length > 0) {
+            renderOutputFields(item.children, indent, lines);
+            return;
+        }
+        item = item.items;
+    }
+}
+/** Render one leaf's ordinary contract, or the focused continuation for one
+ *  uncommon flag selected through `--flag -h`. The caller reaches focused help
+ *  from the ordinary row, so that view contains only leaf identity and the new
+ *  parameter detail instead of repeating information already in context. */
+export function renderLeafArgv(h, focusedFlag) {
+    const lines = [`${h.name}: ${h.summary}.`];
+    // Hidden flags are parsed but never advertised in -h (see FlagParam.hidden).
+    const params = (h.params ?? []).filter((p) => !(p.kind === 'flag' && p.hidden === true));
+    const focused = focusedFlag === undefined
+        ? undefined
+        : params.find((p) => p.kind === 'flag' && p.name === focusedFlag && p.focusedHelp !== undefined);
+    if (focused?.focusedHelp !== undefined) {
+        const detail = focused.focusedHelp;
+        lines.push('');
+        lines.push(`<parameter name="${focused.name}">`);
+        lines.push('When to use');
+        lines.push(`  ${detail.whenToUse}`);
+        lines.push('');
+        lines.push('Value');
+        lines.push(`  ${detail.value}`);
+        if ((detail.effects ?? []).length > 0) {
+            lines.push('');
+            lines.push('Effects');
+            for (const effect of detail.effects ?? [])
+                lines.push(`  ${effect}`);
+        }
+        const focusedState = evalDynamic(detail.dynamicState);
+        if (focusedState !== null) {
+            lines.push('');
+            lines.push(focusedState);
+        }
+        lines.push('</parameter>');
+        return lines.join('\n');
+    }
+    if (h.guide !== undefined) {
+        lines.push('');
+        lines.push(h.guide);
+    }
+    lines.push('');
+    if (params.length > 0) {
+        lines.push('Input');
+        const labels = params.map(paramLabel);
+        const colW = maxLen(labels);
+        for (let i = 0; i < params.length; i++) {
+            lines.push(`  ${pad(labels[i], colW)}  ${paramDesc(params[i], h.name)}`);
+        }
+    }
+    else {
+        lines.push(h.inputNote !== undefined ? h.inputNote : 'No input parameters.');
+    }
+    lines.push('');
+    // The result is rendered as instruction-shaped XML+markdown; these fields are
+    // the information it carries, in order, not a literal JSON shape.
+    lines.push('Output (fields carried in the rendered result)');
+    renderOutputFields(h.output, '  ', lines);
+    lines.push('');
+    lines.push('Effects');
+    for (const e of h.effects) {
+        lines.push(`  ${e}`);
+    }
+    // Optional bounded runtime-state block (e.g. the live <kinds> list), appended
+    // after the schema. Soft-fails to omission on null/throw, mirroring renderBranch.
+    const state = evalDynamic(h.dynamicState);
+    if (state !== null) {
+        lines.push('');
+        lines.push(state);
+    }
+    return lines.join('\n');
+}

package/dist/core/human/page-catalog.d.ts

@@ -0,0 +1,57 @@
+import type { PageComponentRegistration, ProductPageComponents } from '../../types.js';
+/** The page component kinds crtr validates and renders itself. */
+export declare const BUILTIN_PAGE_KINDS: readonly ["options", "text", "table", "cards", "chart"];
+export declare const STRUCTURAL_PAGE_KINDS: readonly ["page", "step"];
+export interface PageComponentCatalogEntry {
+    kind: string;
+    tag: string;
+    description: string;
+    useWhen: string;
+    doc?: string;
+    builtin: boolean;
+    structural: boolean;
+}
+/** The JSX component name a registered kind is authored as. Registry names reach page
+ *  code as JS identifiers, so a hyphenated kind is authored in its PascalCase form
+ *  (`worker-card` → `<WorkerCard>`); the registered kind string is what travels on
+ *  the wire. */
+export declare function pageComponentTag(kind: string): string;
+/** The built-in component kind each authored JSX component name maps to. */
+export declare const BUILTIN_KIND_BY_TAG: Readonly<Record<string, string>>;
+/** Every JSX identifier reserved by the built-in page registry, including structure. */
+export declare const BUILTIN_PAGE_COMPONENT_TAGS: ReadonlySet<string>;
+/** The shadcn display set a page may compose with. These carry no response and never
+ *  appear in the page manifest; they are in scope so an authored page can lay its
+ *  content out. */
+export declare const DISPLAY_PAGE_COMPONENT_TAGS: ReadonlySet<string>;
+/** Normalize legacy kind strings and documented product component registrations.
+ *  `label` names the source in every error message — the default is a scope
+ *  `config.json` block; a plugin contribution passes its own plugin-named
+ *  label so a bad registration points at the package that shipped it. */
+export declare function normalizePageComponents(raw: unknown, label?: string): PageComponentRegistration[];
+/** One contributing source of product page components: a scope's own
+ *  `config.json` block, or one installed plugin's manifest contributions. */
+export interface PageComponentLayer {
+    /** How this source is named in a collision error, e.g. `plugin "acme"`. */
+    origin: string;
+    components: readonly PageComponentRegistration[];
+}
+/** Concatenate every contributing layer into one active catalog, rejecting a
+ *  kind — or a derived JSX tag — that two sources both register. There is no
+ *  precedence here on purpose: two sources claiming one component kind is an
+ *  authoring defect, and silently letting either win would ship a page component
+ *  bound to a renderer nobody chose. Each layer's own entries are already
+ *  validated by `normalizePageComponents`; this is the cross-source gate. */
+export declare function mergePageComponentLayers(layers: readonly PageComponentLayer[]): PageComponentRegistration[];
+/** STRICT install-time validation of a plugin-declared `page_components` block
+ *  — the loud counterpart to a read path that must never ship a half-valid
+ *  catalog. Returns one human-readable reason per defect; empty = valid. Used
+ *  by the archive-bundle validator and by source plugin installs. */
+export declare function invalidPageComponentsReasons(raw: unknown): string[];
+/** Names-only projection for page validation and rendering consumers. */
+export declare function pageComponentKinds(components: readonly PageComponentRegistration[]): string[];
+/** Full built-in + product catalog for CLI discovery. */
+export declare function pageComponentCatalog(components: readonly PageComponentRegistration[]): PageComponentCatalogEntry[];
+/** Whether crtr or the product catalog registers a page component kind. */
+export declare function productPageComponent(kind: string, components: ProductPageComponents): PageComponentRegistration | undefined;
+export declare function isRegisteredPageKind(kind: string, productComponents: ProductPageComponents): boolean;

package/dist/core/human/page-catalog.js

@@ -0,0 +1,172 @@
+/** The page component kinds crtr validates and renders itself. */
+export const BUILTIN_PAGE_KINDS = ['options', 'text', 'table', 'cards', 'chart'];
+export const STRUCTURAL_PAGE_KINDS = ['page', 'step'];
+const PAGE_KIND_PATTERN = /^[a-z][a-z0-9-]{0,63}$/;
+const BUILTIN_PAGE_KIND_SET = new Set(BUILTIN_PAGE_KINDS);
+const BUILTIN_COMPONENTS = [
+    { kind: 'page', tag: 'Page', description: 'the page itself: title, subtitle, and every step it contains', useWhen: 'use as the single root element every page returns', builtin: true, structural: true },
+    { kind: 'step', tag: 'Step', description: 'one step inside a Page', useWhen: 'use for each step the user sees and completes in sequence', builtin: true, structural: true },
+    { kind: 'options', tag: 'UserQuestion', description: 'known alternatives with single or multiple selection', useWhen: 'use when the user picks among known alternatives, optionally with freetext', builtin: true, structural: false },
+    { kind: 'text', tag: 'UserText', description: 'writing surface whose answer is the text the user hands back', useWhen: 'use when you need prose from the user — a value they write, or a draft they revise; prose they only read is a plain element', builtin: true, structural: false },
+    { kind: 'table', tag: 'UserTable', description: 'rows and columns with optional selection', useWhen: 'use when structured records are easiest to compare in rows and columns', builtin: true, structural: false },
+    { kind: 'cards', tag: 'UserCards', description: 'visual records with optional selection', useWhen: 'use when the user compares or picks richer items than a compact option list can carry', builtin: true, structural: false },
+    { kind: 'chart', tag: 'Chart', description: 'line, bar, or area data visualization', useWhen: 'use when shape, trend, or magnitude matters more than exact tabular values', builtin: true, structural: false },
+];
+/** The JSX component name a registered kind is authored as. Registry names reach page
+ *  code as JS identifiers, so a hyphenated kind is authored in its PascalCase form
+ *  (`worker-card` → `<WorkerCard>`); the registered kind string is what travels on
+ *  the wire. */
+export function pageComponentTag(kind) {
+    return kind.split('-').map((part) => (part === '' ? '' : `${part[0].toUpperCase()}${part.slice(1)}`)).join('');
+}
+/** The built-in component kind each authored JSX component name maps to. */
+export const BUILTIN_KIND_BY_TAG = Object.fromEntries(BUILTIN_COMPONENTS.filter((entry) => !entry.structural).map((entry) => [entry.tag, entry.kind]));
+/** Every JSX identifier reserved by the built-in page registry, including structure. */
+export const BUILTIN_PAGE_COMPONENT_TAGS = new Set(BUILTIN_COMPONENTS.map((entry) => entry.tag));
+/** The shadcn display set a page may compose with. These carry no response and never
+ *  appear in the page manifest; they are in scope so an authored page can lay its
+ *  content out. */
+export const DISPLAY_PAGE_COMPONENT_TAGS = new Set([
+    'Card', 'CardHeader', 'CardTitle', 'CardDescription', 'CardContent', 'CardFooter', 'CardAction',
+    'Badge', 'Button', 'Separator', 'Progress', 'Alert', 'AlertTitle', 'AlertDescription',
+    'Table', 'TableHeader', 'TableBody', 'TableFooter', 'TableRow', 'TableHead', 'TableCell', 'TableCaption',
+    'Tabs', 'TabsList', 'TabsTrigger', 'TabsContent',
+    'Accordion', 'AccordionItem', 'AccordionTrigger', 'AccordionContent',
+]);
+function describeEntry(entry) {
+    try {
+        const json = JSON.stringify(entry);
+        return json === undefined ? String(entry) : json;
+    }
+    catch {
+        return String(entry);
+    }
+}
+function optionalText(value, field, label, index) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`${label}[${index}].${field} must be a non-empty string; received ${describeEntry(value)}`);
+    }
+    return value.trim();
+}
+/** Normalize legacy kind strings and documented product component registrations.
+ *  `label` names the source in every error message — the default is a scope
+ *  `config.json` block; a plugin contribution passes its own plugin-named
+ *  label so a bad registration points at the package that shipped it. */
+export function normalizePageComponents(raw, label = 'page_components') {
+    if (raw === undefined)
+        return [];
+    if (!Array.isArray(raw))
+        throw new Error(`${label} must be an array; received ${describeEntry(raw)}`);
+    const seenKinds = new Set();
+    const seenTags = new Set();
+    return raw.map((entry, index) => {
+        let registration;
+        if (typeof entry === 'string') {
+            registration = { kind: entry.trim() };
+        }
+        else if (entry !== null && typeof entry === 'object' && !Array.isArray(entry)) {
+            const object = entry;
+            const extra = Object.keys(object).filter((key) => !['kind', 'description', 'useWhen', 'doc', 'display'].includes(key));
+            if (extra.length > 0)
+                throw new Error(`${label}[${index}] has unknown field(s): ${extra.join(', ')}`);
+            if (typeof object['kind'] !== 'string')
+                throw new Error(`${label}[${index}].kind must be a string; offending entry: ${describeEntry(entry)}`);
+            if (object['display'] !== undefined && typeof object['display'] !== 'boolean')
+                throw new Error(`${label}[${index}].display must be a boolean; offending entry: ${describeEntry(entry)}`);
+            registration = {
+                kind: object['kind'].trim(),
+                ...(optionalText(object['description'], 'description', label, index) === undefined ? {} : { description: optionalText(object['description'], 'description', label, index) }),
+                ...(optionalText(object['useWhen'], 'useWhen', label, index) === undefined ? {} : { useWhen: optionalText(object['useWhen'], 'useWhen', label, index) }),
+                ...(optionalText(object['doc'], 'doc', label, index) === undefined ? {} : { doc: optionalText(object['doc'], 'doc', label, index) }),
+                ...(object['display'] === true ? { display: true } : {}),
+            };
+        }
+        else {
+            throw new Error(`${label}[${index}] must be a string or component object; offending entry: ${describeEntry(entry)}`);
+        }
+        const kind = registration.kind;
+        if (!PAGE_KIND_PATTERN.test(kind))
+            throw new Error(`${label}[${index}] has invalid page kind ${describeEntry(kind)}; expected /^[a-z][a-z0-9-]{0,63}$/`);
+        if (BUILTIN_PAGE_KIND_SET.has(kind) || STRUCTURAL_PAGE_KINDS.includes(kind))
+            throw new Error(`${label}[${index}] collides with built-in page kind "${kind}"`);
+        if (seenKinds.has(kind))
+            throw new Error(`${label}[${index}] duplicates page kind "${kind}"`);
+        const tag = pageComponentTag(kind);
+        if (BUILTIN_PAGE_COMPONENT_TAGS.has(tag))
+            throw new Error(`${label}[${index}] kind "${kind}" derives JSX tag "${tag}", which collides with a built-in page component`);
+        if (seenTags.has(tag))
+            throw new Error(`${label}[${index}] kind "${kind}" derives JSX tag "${tag}", which duplicates another product page component`);
+        seenKinds.add(kind);
+        seenTags.add(tag);
+        return registration;
+    });
+}
+/** Concatenate every contributing layer into one active catalog, rejecting a
+ *  kind — or a derived JSX tag — that two sources both register. There is no
+ *  precedence here on purpose: two sources claiming one component kind is an
+ *  authoring defect, and silently letting either win would ship a page component
+ *  bound to a renderer nobody chose. Each layer's own entries are already
+ *  validated by `normalizePageComponents`; this is the cross-source gate. */
+export function mergePageComponentLayers(layers) {
+    const originByKind = new Map();
+    const claimByTag = new Map();
+    const out = [];
+    for (const layer of layers) {
+        for (const component of layer.components) {
+            const kindOrigin = originByKind.get(component.kind);
+            if (kindOrigin !== undefined) {
+                throw new Error(`page component kind "${component.kind}" is registered by both ${kindOrigin} and ${layer.origin}`);
+            }
+            const tag = pageComponentTag(component.kind);
+            const tagClaim = claimByTag.get(tag);
+            if (tagClaim !== undefined) {
+                throw new Error(`page component kind "${component.kind}" (${layer.origin}) derives JSX tag "${tag}", which duplicates kind "${tagClaim.kind}" from ${tagClaim.origin}`);
+            }
+            originByKind.set(component.kind, layer.origin);
+            claimByTag.set(tag, { kind: component.kind, origin: layer.origin });
+            out.push(component);
+        }
+    }
+    return out;
+}
+/** STRICT install-time validation of a plugin-declared `page_components` block
+ *  — the loud counterpart to a read path that must never ship a half-valid
+ *  catalog. Returns one human-readable reason per defect; empty = valid. Used
+ *  by the archive-bundle validator and by source plugin installs. */
+export function invalidPageComponentsReasons(raw) {
+    try {
+        normalizePageComponents(raw);
+        return [];
+    }
+    catch (error) {
+        return [error instanceof Error ? error.message : String(error)];
+    }
+}
+/** Names-only projection for page validation and rendering consumers. */
+export function pageComponentKinds(components) {
+    return components.map((component) => component.kind);
+}
+/** Full built-in + product catalog for CLI discovery. */
+export function pageComponentCatalog(components) {
+    return [
+        ...BUILTIN_COMPONENTS,
+        ...components.map((component) => ({
+            kind: component.kind,
+            tag: pageComponentTag(component.kind),
+            description: component.description ?? 'product-registered page component',
+            useWhen: component.useWhen ?? 'use when the product component matches the structured UI the user needs',
+            ...(component.doc === undefined ? {} : { doc: component.doc }),
+            builtin: false,
+            structural: false,
+        })),
+    ];
+}
+/** Whether crtr or the product catalog registers a page component kind. */
+export function productPageComponent(kind, components) {
+    return components.find((component) => component.kind === kind);
+}
+export function isRegisteredPageKind(kind, productComponents) {
+    return BUILTIN_PAGE_KIND_SET.has(kind) || productPageComponent(kind, productComponents) !== undefined;
+}

package/dist/core/installed-plugins.d.ts

@@ -0,0 +1,2 @@
+import type { InstalledPlugin, Scope } from '../types.js';
+export declare function listInstalledPluginsInRoot(scope: Scope, scopeRootPath: string): InstalledPlugin[];