@north-light/api 0.3.580 → 0.3.587

package/dist/commands/pkg/browse/catalog.js

@@ -0,0 +1,461 @@
+// Catalog reads for `crtr pkg browse`. Everything here is read-only; mutations
+// live in actions.ts.
+import { statSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { SUBTREE_NAMES, coreCommandPaths, extensibleCoreBranches } from '../../../build-root.js';
+import { discoverPluginCommandCandidates, validateEffectiveCommandPlugins, validatePluginCommands } from '../../../core/command-plugins/discovery.js';
+import { qualifiedTopLevelCommandName } from '../../../core/command-manifests/registry.js';
+import { listDirs, pathExists, walkFiles } from '../../../core/fs-utils.js';
+import { currentSha, gitSync } from '../../../core/git.js';
+import { packageFiles } from '../../../core/graph/package-files.js';
+import { readMarketplaceManifest, readPluginManifest } from '../../../core/manifest.js';
+import { readConfig } from '../../../core/config.js';
+import { documentFields } from '../../../migrations/004-canvas-documents/fields.js';
+import { pluginMemoryDir, projectScopeRoot } from '../../../core/scope.js';
+import { runtimeRoot } from '../../../core/layout.js';
+import { isGitUrl } from '../shared.js';
+import { INSTALLED_SOURCE_ID, marketplaceSourceId, } from './model.js';
+function parseSemver(version) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
+    return match === null
+        ? null
+        : { core: [Number(match[1]), Number(match[2]), Number(match[3])], prerelease: match[4]?.split(".") ?? [] };
+}
+function compareSemver(left, right) {
+    for (let index = 0; index < left.core.length; index += 1) {
+        const difference = left.core[index] - right.core[index];
+        if (difference !== 0)
+            return difference;
+    }
+    if (left.prerelease.length === 0 || right.prerelease.length === 0) {
+        return left.prerelease.length === right.prerelease.length ? 0 : left.prerelease.length === 0 ? 1 : -1;
+    }
+    for (let index = 0; index < Math.max(left.prerelease.length, right.prerelease.length); index += 1) {
+        const leftPart = left.prerelease[index];
+        const rightPart = right.prerelease[index];
+        if (leftPart === undefined || rightPart === undefined)
+            return leftPart === undefined ? -1 : 1;
+        const leftNumber = /^\d+$/.test(leftPart);
+        const rightNumber = /^\d+$/.test(rightPart);
+        if (leftNumber && rightNumber) {
+            const difference = Number(leftPart) - Number(rightPart);
+            if (difference !== 0)
+                return difference;
+        }
+        else if (leftNumber !== rightNumber) {
+            return leftNumber ? -1 : 1;
+        }
+        else if (leftPart !== rightPart) {
+            return leftPart < rightPart ? -1 : 1;
+        }
+    }
+    return 0;
+}
+function offeredVersionIsNewer(installed, offered) {
+    if (installed === undefined || offered === undefined)
+        return false;
+    const current = parseSemver(installed);
+    const available = parseSemver(offered);
+    return current !== null && available !== null && compareSemver(available, current) > 0;
+}
+function isMarketplaceRelativeSource(source) {
+    return source.startsWith("./") || source.startsWith("../") || (!isAbsolute(source) && !isGitUrl(source));
+}
+function pluginInstallState(plugin, offeredVersion) {
+    return {
+        kind: "installed",
+        scope: plugin.scope,
+        enabled: plugin.enabled,
+        version: plugin.version,
+        path: plugin.root,
+        updateAvailable: offeredVersionIsNewer(plugin.version, offeredVersion),
+    };
+}
+function installedEntry(plugin, offeredVersion) {
+    return {
+        key: `${INSTALLED_SOURCE_ID}:${plugin.scope}:${plugin.name}`,
+        name: plugin.name,
+        ref: plugin.name,
+        sourceId: INSTALLED_SOURCE_ID,
+        ...(plugin.sourceMarketplace !== undefined ? { marketplace: plugin.sourceMarketplace } : {}),
+        // The version the marketplace OFFERS, per PluginEntry.version. The version
+        // actually installed lives in `install.version`, and the dossier renders
+        // the pair as "installed → offered" — filling both from the installed side
+        // renders every update as "1.0.0 → 1.0.0".
+        ...(offeredVersion === undefined ? {} : { version: offeredVersion }),
+        description: plugin.manifest.description,
+        keywords: [],
+        owner: plugin.manifest.owner,
+        source: plugin.manifest.source,
+        install: pluginInstallState(plugin, offeredVersion),
+        root: plugin.root,
+    };
+}
+/** `source_marketplace` records a marketplace name, not its registration
+ * scope. Installation scope is independent, so this join deliberately keys
+ * provenance by marketplace name alone. */
+function marketplacePluginKey(marketplace, name) {
+    return `${marketplace}:${name}`;
+}
+function marketplaceDetail(marketplace, installed) {
+    const revision = currentSha(marketplace.root) ?? undefined;
+    const date = gitSync(["show", "-s", "--format=%cI", "HEAD"], marketplace.root);
+    const revisionDate = date.status === 0 ? date.stdout.trim() || undefined : undefined;
+    const offered = marketplace.manifest.plugins;
+    return {
+        name: marketplace.name,
+        scope: marketplace.scope,
+        url: marketplace.url,
+        ref: marketplace.ref,
+        path: marketplace.root,
+        owner: marketplace.manifest.owner,
+        version: marketplace.manifest.version,
+        pluginCount: offered.length,
+        installedCount: offered.filter((entry) => installed.has(marketplacePluginKey(marketplace.name, entry.name))).length,
+        updatableCount: offered.filter((entry) => {
+            const plugin = installed.get(marketplacePluginKey(marketplace.name, entry.name));
+            return plugin !== undefined && offeredVersionIsNewer(plugin.version, entry.version);
+        }).length,
+        revision,
+        revisionDate,
+    };
+}
+function marketplaceEntry(marketplace, entry, installed) {
+    const installedPlugin = installed.get(marketplacePluginKey(marketplace.name, entry.name));
+    const vendoredRoot = isMarketplaceRelativeSource(entry.source) ? join(marketplace.root, entry.source) : undefined;
+    return {
+        key: `${marketplaceSourceId(marketplace.name, marketplace.scope)}:${entry.name}`,
+        name: entry.name,
+        ref: `${marketplace.name}/${entry.name}`,
+        sourceId: marketplaceSourceId(marketplace.name, marketplace.scope),
+        marketplace: marketplace.name,
+        version: entry.version,
+        description: entry.description,
+        keywords: entry.keywords ?? [],
+        owner: marketplace.manifest.owner,
+        source: entry.source,
+        install: installedPlugin === undefined ? { kind: "absent" } : pluginInstallState(installedPlugin, entry.version),
+        ...(installedPlugin !== undefined ? { root: installedPlugin.root } : vendoredRoot !== undefined && pathExists(vendoredRoot) ? { root: vendoredRoot } : {}),
+    };
+}
+function readableConfig(scope, warnings) {
+    try {
+        return readConfig(scope);
+    }
+    catch (error) {
+        warnings.push(`Could not read ${scope} config: ${errorMessage(error)}`);
+        return null;
+    }
+}
+function readInstalledPlugins(warnings) {
+    const roots = [
+        ...(projectScopeRoot() === null ? [] : [{ scope: "project", root: projectScopeRoot() }]),
+        { scope: "user", root: runtimeRoot() },
+    ];
+    const plugins = [];
+    for (const { scope, root } of roots) {
+        const config = readableConfig(scope, warnings);
+        for (const name of listDirs(join(root, "plugins"))) {
+            const pluginRoot = join(root, "plugins", name);
+            try {
+                const manifest = readPluginManifest(pluginRoot);
+                if (manifest === null) {
+                    warnings.push(`Plugin "${name}" has no readable manifest: ${pluginRoot}`);
+                    continue;
+                }
+                const entry = config?.plugins[name];
+                plugins.push({
+                    name,
+                    scope,
+                    root: pluginRoot,
+                    manifest,
+                    enabled: typeof entry?.enabled === "boolean" ? entry.enabled : true,
+                    sourceMarketplace: typeof entry?.source_marketplace === "string" ? entry.source_marketplace : undefined,
+                    version: typeof entry?.version === "string" ? entry.version : manifest.version,
+                });
+            }
+            catch (error) {
+                warnings.push(`Could not read plugin "${name}": ${errorMessage(error)}`);
+            }
+        }
+    }
+    return plugins;
+}
+function marketplaceEntries(raw, marketplaceName, warnings) {
+    if (!Array.isArray(raw)) {
+        warnings.push(`Marketplace "${marketplaceName}" has an invalid plugins list.`);
+        return [];
+    }
+    const entries = [];
+    for (const [index, entry] of raw.entries()) {
+        if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+            warnings.push(`Marketplace "${marketplaceName}" has an invalid plugin entry at index ${index}.`);
+            continue;
+        }
+        const value = entry;
+        if (typeof value["name"] !== "string" || value["name"] === "" || typeof value["source"] !== "string" || value["source"] === "") {
+            warnings.push(`Marketplace "${marketplaceName}" has a plugin entry without a name and source at index ${index}.`);
+            continue;
+        }
+        entries.push({
+            name: value["name"],
+            source: value["source"],
+            ...(typeof value["version"] === "string" ? { version: value["version"] } : {}),
+            ...(typeof value["description"] === "string" ? { description: value["description"] } : {}),
+            ...(Array.isArray(value["keywords"]) && value["keywords"].every((keyword) => typeof keyword === "string") ? { keywords: value["keywords"] } : {}),
+        });
+    }
+    return entries;
+}
+function readableMarketplaceManifest(raw, directoryName, warnings) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        warnings.push(`Marketplace "${directoryName}" has an invalid manifest.`);
+        return null;
+    }
+    const value = raw;
+    if (typeof value["name"] !== "string" || value["name"] === "") {
+        warnings.push(`Marketplace "${directoryName}" has a manifest without a name.`);
+        return null;
+    }
+    const owner = value["owner"];
+    const ownerRef = typeof owner === "object" && owner !== null && !Array.isArray(owner)
+        ? { ...(typeof owner["name"] === "string" ? { name: owner["name"] } : {}), ...(typeof owner["email"] === "string" ? { email: owner["email"] } : {}) }
+        : undefined;
+    return {
+        name: value["name"],
+        plugins: marketplaceEntries(value["plugins"], value["name"], warnings),
+        ...(typeof value["version"] === "string" ? { version: value["version"] } : {}),
+        ...(ownerRef !== undefined ? { owner: ownerRef } : {}),
+    };
+}
+function readMarketplaces(warnings) {
+    const roots = [
+        ...(projectScopeRoot() === null ? [] : [{ scope: "project", root: projectScopeRoot() }]),
+        { scope: "user", root: runtimeRoot() },
+    ];
+    const marketplaces = [];
+    for (const { scope, root } of roots) {
+        const config = readableConfig(scope, warnings);
+        for (const name of listDirs(join(root, "marketplaces"))) {
+            const marketplaceRoot = join(root, "marketplaces", name);
+            try {
+                const rawManifest = readMarketplaceManifest(marketplaceRoot);
+                if (rawManifest === null) {
+                    warnings.push(`Marketplace "${name}" has no readable manifest: ${marketplaceRoot}`);
+                    continue;
+                }
+                const manifest = readableMarketplaceManifest(rawManifest, name, warnings);
+                if (manifest === null)
+                    continue;
+                const entry = config?.marketplaces[name];
+                marketplaces.push({
+                    name,
+                    scope,
+                    root: marketplaceRoot,
+                    manifest,
+                    url: entry?.url ?? "",
+                    ref: entry?.ref ?? "main",
+                });
+            }
+            catch (error) {
+                warnings.push(`Could not read marketplace "${name}": ${errorMessage(error)}`);
+            }
+        }
+    }
+    return marketplaces;
+}
+/** Every rail source with its rows: the installed library first, then each
+ *  registered marketplace. Called on open and after any action that could
+ *  change install state. Must never throw for a broken marketplace — record it
+ *  in `warnings` and keep the rest of the catalog. */
+export function loadCatalog() {
+    const warnings = [];
+    const installed = readInstalledPlugins(warnings);
+    const marketplaces = readMarketplaces(warnings);
+    const installedByMarketplace = new Map(installed
+        .filter((plugin) => plugin.sourceMarketplace !== undefined)
+        .map((plugin) => [marketplacePluginKey(plugin.sourceMarketplace, plugin.name), plugin]));
+    const offeredVersions = new Map(marketplaces.flatMap((marketplace) => marketplace.manifest.plugins.map((entry) => [
+        marketplacePluginKey(marketplace.name, entry.name),
+        entry.version,
+    ])));
+    const sources = [{
+            id: INSTALLED_SOURCE_ID,
+            kind: "installed",
+            label: "Installed",
+            entries: installed
+                .map((plugin) => installedEntry(plugin, plugin.sourceMarketplace === undefined ? undefined : offeredVersions.get(marketplacePluginKey(plugin.sourceMarketplace, plugin.name))))
+                .sort((a, b) => a.name.localeCompare(b.name)),
+        }];
+    for (const marketplace of marketplaces.sort((a, b) => a.name.localeCompare(b.name))) {
+        try {
+            sources.push({
+                id: marketplaceSourceId(marketplace.name, marketplace.scope),
+                kind: "marketplace",
+                label: marketplace.name,
+                marketplace: marketplaceDetail(marketplace, installedByMarketplace),
+                entries: marketplace.manifest.plugins
+                    .map((entry) => marketplaceEntry(marketplace, entry, installedByMarketplace))
+                    .sort((a, b) => a.name.localeCompare(b.name)),
+            });
+        }
+        catch (error) {
+            warnings.push(`Could not load marketplace "${marketplace.name}": ${errorMessage(error)}`);
+        }
+    }
+    return {
+        sources,
+        installScopes: ["user", ...(projectScopeRoot() === null ? [] : ["project"])],
+        warnings,
+    };
+}
+function commandNode(node, parent = []) {
+    const path = [...parent, node.name];
+    if (node.kind === "branch") {
+        return {
+            path,
+            kind: "branch",
+            description: node.description,
+            whenToUse: node.whenToUse,
+            summary: node.summary,
+            ...(node.tier !== undefined ? { tier: node.tier } : {}),
+            ...(node.passthrough !== undefined ? { passthrough: node.passthrough } : {}),
+            ...(node.rootEntry !== undefined ? { rootEntry: node.rootEntry } : {}),
+            children: node.children.map((child) => commandNode(child, path)),
+            params: [],
+            output: [],
+            effects: [],
+        };
+    }
+    return {
+        path,
+        kind: "leaf",
+        description: node.description,
+        whenToUse: node.whenToUse,
+        summary: node.summary,
+        ...(node.tier !== undefined ? { tier: node.tier } : {}),
+        children: [],
+        params: node.params,
+        output: node.output,
+        effects: [...node.effects],
+        ...("rest" in node ? { rest: { method: node.rest.method, path: node.rest.path, streaming: node.rest.streaming === true } } : {}),
+    };
+}
+function docDetails(plugin) {
+    return packageFiles(pluginMemoryDir(plugin)).files.map((file) => {
+        const f = documentFields(file.frontmatter, file.body, { missingPrivacy: "public" });
+        let sizeBytes;
+        try {
+            sizeBytes = statSync(file.path).size;
+        }
+        catch {
+            // The package read already isolated this document; its size is
+            // supplementary and must not make the dossier unreadable.
+        }
+        return {
+            name: `${plugin.name}/${file.name}`,
+            kind: f.kind === "preference" ? "preference" : "knowledge",
+            ...(f.summary !== null ? { shortForm: f.summary } : {}),
+            ...(f.preview !== "" ? { routingLine: f.preview } : {}),
+            path: file.path,
+            ...(sizeBytes !== undefined ? { sizeBytes } : {}),
+            rules: f.rules,
+            unlisted: f.unlisted,
+            ...(f.whyItExists !== null ? { rationale: f.whyItExists } : {}),
+            body: file.body,
+        };
+    });
+}
+function directorySize(root) {
+    try {
+        return walkFiles(root).reduce((bytes, path) => bytes + statSync(path).size, 0);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** What the focused plugin adds to this machine. Resolved from `entry.root`;
+ *  null when the plugin has no directory on disk yet. */
+export async function loadCapability(entry) {
+    if (entry.root === undefined || !pathExists(entry.root))
+        return null;
+    try {
+        const manifest = readPluginManifest(entry.root);
+        if (manifest === null)
+            return null;
+        const scope = entry.install.kind === "installed" ? entry.install.scope : "user";
+        const plugin = { name: entry.name, scope, root: entry.root, manifest, enabled: entry.install.kind !== "installed" || entry.install.enabled };
+        const reserved = new Set(SUBTREE_NAMES);
+        const [corePaths, extensibleBranches] = await Promise.all([coreCommandPaths(), extensibleCoreBranches()]);
+        let validation = validatePluginCommands(plugin, reserved, corePaths, extensibleBranches);
+        const registryIssues = [];
+        // Effective validation resolves collisions for the command that is mounted
+        // today. An uninstalled or disabled plugin is not in that registry, so its
+        // dossier must validate the declared tree and preview the future result.
+        if (entry.install.kind === "installed" && entry.install.enabled) {
+            try {
+                const effective = validateEffectiveCommandPlugins(reserved, undefined, undefined, corePaths, extensibleBranches);
+                validation = effective.find((candidate) => candidate.plugin.root === entry.root) ?? validation;
+            }
+            catch (error) {
+                registryIssues.push({
+                    message: `Could not resolve the effective command registry: ${errorMessage(error)}`,
+                    next: "Repair the unreadable installed plugin manifest, then reopen the dossier.",
+                });
+            }
+        }
+        if (entry.install.kind !== "installed" || !entry.install.enabled) {
+            // Who already claims each bare top-level name. Ask unresolved candidates,
+            // not the effective registry: resolution has already rewritten collided
+            // names. A disabled installed plugin is excluded from candidates, so the
+            // preview also describes exactly what enabling it changes.
+            const claimants = new Map();
+            for (const candidate of discoverPluginCommandCandidates()) {
+                if (candidate.plugin.root === entry.root)
+                    continue;
+                for (const contribution of candidate.contributions) {
+                    const plugins = claimants.get(contribution.node.name) ?? [];
+                    plugins.push(candidate.plugin);
+                    claimants.set(contribution.node.name, plugins);
+                }
+            }
+            const verb = entry.install.kind === "installed" ? "enabling" : "installing";
+            validation.contributions = validation.contributions.map((contribution) => {
+                const claimantsForName = claimants.get(contribution.node.name);
+                if (claimantsForName === undefined || claimantsForName.length === 0)
+                    return contribution;
+                const qualified = qualifiedTopLevelCommandName({ name: entry.name, sourceMarketplace: entry.marketplace }, contribution.node.name);
+                const otherMounts = claimantsForName.map((claimant) => `moves ${claimant.name}'s to "${qualifiedTopLevelCommandName(claimant, contribution.node.name)}"`);
+                validation.issues.push({
+                    code: "command_collision",
+                    plugin: plugin.name,
+                    path: contribution.node.name,
+                    message: `top-level command "${contribution.node.name}" is already claimed by ${claimantsForName.map((claimant) => claimant.name).join(", ")} — ${verb} mounts this one as "${qualified}" and ${otherMounts.join(" and ")}`,
+                    received: [...claimantsForName.map((claimant) => claimant.name), plugin.name].join(", "),
+                    expected: "an origin-qualified top-level command for each claimant",
+                    next: `After ${verb}, invoke "${qualified}".`,
+                });
+                return { ...contribution, node: { ...contribution.node, name: qualified } };
+            });
+        }
+        const transport = manifest.transport;
+        return {
+            root: entry.root,
+            transport: transport?.kind === 'machine' ? 'http' : transport?.kind ?? null,
+            ...(transport?.kind === "exec" && transport.executable !== undefined ? { transportTarget: transport.executable } : {}),
+            ...(transport?.kind === "http" ? { transportTarget: transport.endpoint } : {}),
+            commands: validation.contributions.map((contribution) => commandNode(contribution.node)),
+            commandIssues: [...validation.issues.map(({ message, next }) => ({ message, ...(next !== undefined ? { next } : {}) })), ...registryIssues],
+            docs: docDetails(plugin),
+            sizeBytes: directorySize(entry.root),
+        };
+    }
+    catch {
+        // Marketplace content is third-party input. Its failure makes this one
+        // dossier unavailable, never the whole browser process.
+        return null;
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/commands/pkg/browse/command-view.d.ts

@@ -0,0 +1,3 @@
+import type { CommandNode, PluginCapability } from './model.js';
+/** Every line of one command's contract view, wrapped to `width`. */
+export declare function renderCommandView(node: CommandNode, capability: PluginCapability, width: number): string[];

package/dist/commands/pkg/browse/command-view.js

@@ -0,0 +1,217 @@
+// The plugin browser's command-contract view: one node of a plugin's command
+// tree rendered as the whole contract an agent would read from `-h`.
+//
+// Pure rendering. It returns styled lines already wrapped to `width`; the
+// dossier owns scrolling and never truncates what comes back.
+import { visibleWidth, wrapTextWithAnsi } from '@earendil-works/pi-tui';
+import { theme, wrapText } from '../../../core/tui/panel.js';
+import { commandLabel } from './model.js';
+/** Every line of one command's contract view, wrapped to `width`. */
+export function renderCommandView(node, capability, width) {
+    const out = [];
+    out.push(...wrapped(commandLabel(node), width).map((line) => theme.fg("accent", theme.bold(line))));
+    out.push(...wrapped(`${node.kind.toUpperCase()} COMMAND · ${(node.tier ?? "normal").toUpperCase()} TIER`, width).map((line) => theme.fg("dim", line)));
+    out.push("");
+    out.push(...paragraph(node.description, width));
+    section(out, "WHEN TO USE", width);
+    out.push(...paragraph(node.whenToUse, width));
+    section(out, "SUMMARY", width);
+    out.push(...paragraph(node.summary, width));
+    if (node.kind === "leaf")
+        renderLeaf(out, node, capability, width);
+    else
+        renderBranch(out, node, width);
+    return out;
+}
+function renderLeaf(out, node, capability, width) {
+    section(out, "PARAMS", width);
+    if (node.params.length === 0)
+        out.push(...paragraph("No input parameters.", width));
+    else
+        for (const param of node.params)
+            out.push(...renderParam(param, width));
+    section(out, "OUTPUT", width);
+    if (node.output.length === 0)
+        out.push(...paragraph("No output fields declared.", width));
+    else
+        for (const field of node.output)
+            out.push(...renderField(field, width));
+    section(out, "EFFECTS", width);
+    if (node.effects.length === 0)
+        out.push(...paragraph("No effects declared.", width));
+    else
+        for (const effect of node.effects)
+            out.push(...hanging("  • ", effect, width));
+    section(out, "INVOKED VIA", width);
+    if (capability.transport === null) {
+        out.push(...wrapped("This plugin declares no command transport.", width).map((line) => theme.fg("warning", line)));
+        return;
+    }
+    const target = capability.transportTarget ?? "No target declared.";
+    out.push(...hanging(`  ${capability.transport}  `, target, width));
+    if (capability.transport === "http" && node.rest !== undefined) {
+        out.push(...hanging("  REST  ", `${node.rest.method} ${node.rest.path} · ${node.rest.streaming ? "streaming response" : "single response"}`, width));
+    }
+}
+function renderBranch(out, node, width) {
+    if (node.rootEntry !== undefined) {
+        section(out, "ROOT ENTRY", width);
+        out.push(...hanging("  Concept  ", node.rootEntry.concept, width));
+        out.push(...hanging("  Description  ", node.rootEntry.description, width));
+        out.push(...hanging("  When to use  ", node.rootEntry.whenToUse, width));
+    }
+    if (node.passthrough !== undefined) {
+        section(out, "PASSES THROUGH", width);
+        out.push(...hanging("  Binary  ", node.passthrough.bin, width));
+        out.push(...hanging("  Install  ", node.passthrough.installHint, width));
+    }
+    section(out, "CHILDREN", width);
+    if (node.children.length === 0) {
+        out.push(...paragraph(node.passthrough === undefined ? "No subcommands." : "No subcommands — every argument is forwarded to the binary.", width));
+        return;
+    }
+    for (const child of node.children)
+        out.push(...hanging(`  ${commandLabel(child)}  `, child.description, width));
+}
+function renderParam(param, width) {
+    const label = paramLabel(param);
+    const lines = hanging(`  ${label}  `, paramMeta(param), width);
+    // Each extra fact starts at one fixed column rather than under its own
+    // label: aligning to the label width makes a param list as ragged as its
+    // longest name, and `--target-pattern` would push its constraint 21 columns in.
+    const detailPrefix = DETAIL_INDENT;
+    if (param.kind === "positional") {
+        if (param.repeatable === true)
+            lines.push(...hanging(detailPrefix, "Repeatable; supply multiple values in argv order.", width));
+        if (param.encoding !== undefined)
+            lines.push(...hanging(detailPrefix, encodingDetail(param.encoding), width));
+        if (param.defaultFromEnv !== undefined)
+            lines.push(...hanging(detailPrefix, envDefaultDetail(param.defaultFromEnv), width));
+    }
+    else if (param.kind === "flag") {
+        if (param.choices !== undefined)
+            lines.push(...hanging(detailPrefix, `Choices: ${param.choices.join(", ")}.`, width));
+        if (param.default !== undefined)
+            lines.push(...hanging(detailPrefix, `Default: ${formatValue(param.default)}.`, width));
+        if (param.repeatable === true)
+            lines.push(...hanging(detailPrefix, "Repeatable; supply the flag multiple times to accumulate values.", width));
+        if (param.encoding !== undefined)
+            lines.push(...hanging(detailPrefix, encodingDetail(param.encoding), width));
+        if (param.defaultFromEnv !== undefined)
+            lines.push(...hanging(detailPrefix, envDefaultDetail(param.defaultFromEnv), width));
+        if (param.hidden === true)
+            lines.push(...hanging(detailPrefix, "Hidden from the command's ordinary -h output.", width, "warning"));
+    }
+    else if (param.kind === "context-file") {
+        lines.push(...hanging(detailPrefix, `Mapped input: ${param.name}.`, width));
+        if (param.shape !== undefined)
+            lines.push(...hanging(detailPrefix, `Expected JSON: ${param.shape}`, width));
+    }
+    lines.push(...hanging(detailPrefix, `Constraint: ${param.constraint}`, width));
+    return lines;
+}
+function renderField(field, width, indent = "  ") {
+    const detail = `${indent}  `;
+    const lines = [
+        ...hanging(`${indent}${field.name}  `, `${field.type} · ${field.required ? "required" : "optional"}`, width),
+        ...hanging(detail, `Constraint: ${field.constraint}`, width),
+    ];
+    lines.push(...renderShapeBody(field, width, detail));
+    return lines;
+}
+/** An output shape's nested structure: enum values, object members, and an
+ *  array's element shape, each one level deeper, so the view shows the same
+ *  result shape `-h` renders. */
+function renderShapeBody(shape, width, indent) {
+    const lines = [];
+    if (shape.values !== undefined)
+        lines.push(...hanging(indent, `Values: ${shape.values.join(", ")}.`, width));
+    for (const child of shape.children ?? [])
+        lines.push(...renderField(child, width, indent));
+    if (shape.extra !== undefined) {
+        const extra = shape.extra;
+        const constraint = extra.constraint.length > 0 ? ` · ${extra.constraint}` : "";
+        lines.push(...hanging(indent, `Other members: ${extra.type}${constraint}`, width));
+        lines.push(...renderShapeBody(extra, width, `${indent}  `));
+    }
+    if (shape.items !== undefined) {
+        const item = shape.items;
+        const constraint = item.constraint.length > 0 ? ` · ${item.constraint}` : "";
+        lines.push(...hanging(indent, `Each element: ${item.type}${constraint}`, width));
+        lines.push(...renderShapeBody(item, width, `${indent}  `));
+    }
+    return lines;
+}
+/** Where a param's or field's supporting facts start, whatever its name. */
+const DETAIL_INDENT = "    ";
+function paramLabel(param) {
+    switch (param.kind) {
+        case "positional":
+            return `${param.name}${param.repeatable === true ? "…" : ""}`;
+        case "flag":
+            return `--${param.name}`;
+        case "stdin":
+            return param.name;
+        case "context-file":
+            return "--context-file PATH";
+    }
+}
+function paramMeta(param) {
+    const requirement = param.required ? "required" : "optional";
+    switch (param.kind) {
+        case "positional":
+            return `positional · ${param.type ?? "string"} · ${requirement}`;
+        case "flag":
+            return `flag · ${param.type} · ${requirement}`;
+        case "stdin":
+            return `stdin · raw text · ${requirement}`;
+        case "context-file":
+            return `context file · JSON file · ${requirement}`;
+    }
+}
+function encodingDetail(encoding) {
+    return encoding === "base64"
+        ? "Encoding: reads the local file's raw bytes and sends base64; the path itself is never sent."
+        : "Encoding: reads the local file as UTF-8 text and sends its content; the path itself is never sent.";
+}
+function formatValue(value) {
+    return typeof value === "string" ? JSON.stringify(value) : String(value);
+}
+function envDefaultDetail(envVar) {
+    return `When $${envVar} is set and non-empty, it supplies the value and counts as supplied.`;
+}
+/** A section heading always has one blank line above it, never a trailing one. */
+function section(out, heading, width) {
+    out.push("");
+    out.push(...wrapped(heading, width).map((line) => theme.fg("dim", line)));
+}
+/** Prose sits two columns in, like the labelled rows beneath every other
+ *  heading here and in the doc view — a flush-left paragraph between indented
+ *  blocks reads as a different document. */
+function paragraph(text, width) {
+    const indent = "  ";
+    return wrapped(text, Math.max(1, width - indent.length)).map((line) => `${indent}${theme.fg("dim", line)}`);
+}
+/** Wrap text after a styled label; every continuation starts under its text. */
+function hanging(prefix, text, width, role = "dim") {
+    const prefixWidth = visibleWidth(prefix);
+    if (prefixWidth >= width) {
+        return [
+            ...wrapped(prefix.trimEnd(), width).map((line) => theme.fg("accent", line)),
+            ...wrapped(text, Math.max(1, width - 2)).map((line) => `  ${theme.fg(role, line)}`),
+        ];
+    }
+    const contentWidth = Math.max(1, width - prefixWidth);
+    const continuation = " ".repeat(prefixWidth);
+    return wrapped(text, contentWidth).map((line, index) => index === 0
+        ? `${theme.fg("accent", prefix)}${theme.fg(role, line)}`
+        : `${continuation}${theme.fg(role, line)}`);
+}
+/** Keep normal prose on the shared word wrapper, but never lose an over-wide token. */
+function wrapped(text, width) {
+    const clean = text.trim();
+    const safeWidth = Math.max(1, width);
+    return clean.split(/\s+/).some((word) => visibleWidth(word) > safeWidth)
+        ? wrapTextWithAnsi(clean, safeWidth)
+        : wrapText(clean, safeWidth);
+}