@crouton-kit/crouter 0.3.8 → 0.3.12

package/dist/core/io.js

@@ -1,9 +1,23 @@
-// The agent-facing I/O contract. Flags and positional args on input; one JSON
-// object on stdout (JSONL for streams); structured errors; stderr is
-// diagnostics only and never carries the result. The stdout value is the next
-// caller's stdin. See cli-design SKILL.md / reference.md.
+// The agent-facing I/O contract. Flags and positional args on input; stdout is
+// agent-ready markdown/XML the caller acts on directly (the result rendered FOR
+// the model, not data it parses); structured errors; stderr is diagnostics only
+// and never carries the result. The raw JSON object is available behind the
+// `--json` global for tooling. See cli-design SKILL.md / reference.md.
 import { CrtrError } from './errors.js';
 import { ExitCode } from '../types.js';
+import { renderError } from './render.js';
+// ---------------------------------------------------------------------------
+// output mode — prose (default) vs raw JSON (--json global, for tooling)
+// ---------------------------------------------------------------------------
+let jsonOutput = false;
+/** Set by the dispatcher when `--json` is present anywhere in argv. */
+export function setJsonOutput(v) {
+    jsonOutput = v;
+}
+/** True when the caller asked for raw JSON instead of rendered prose. */
+export function isJsonOutput() {
+    return jsonOutput;
+}
 /** A command-level failure: surfaces as the JSON response on stdout. */
 export class InputError extends CrtrError {
     payload;
@@ -29,7 +43,8 @@ export async function readStdinRaw() {
 // ---------------------------------------------------------------------------
 // stdout — the result, nothing else
 // ---------------------------------------------------------------------------
-/** Single-shot response: one JSON object. The whole response is one value. */
+/** Raw-JSON mirror of a single-shot response (the `--json` escape hatch). The
+ *  default path renders the result as prose instead — see render.ts. */
 export function emit(obj) {
     process.stdout.write(JSON.stringify(obj, null, 2) + '\n');
 }
@@ -37,6 +52,37 @@ export function emit(obj) {
 export function emitLine(obj) {
     process.stdout.write(JSON.stringify(obj) + '\n');
 }
+/**
+ * Write to stdout and resolve true ONLY once the bytes are confirmed flushed to
+ * a connected reader. Resolves false if the consumer is gone (EPIPE) or the
+ * write fails. This is the reliable "the caller actually received it" signal:
+ * use it to gate side effects that must only happen on genuine delivery (e.g.
+ * acking a collected result). A killed process never resolves at all — also
+ * safe, since the gated side effect then never runs.
+ */
+export function writeStdout(s) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const onErr = (e) => {
+            if (e.code === 'EPIPE')
+                finish(false);
+        };
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            process.stdout.off('error', onErr);
+            resolve(ok);
+        };
+        process.stdout.on('error', onErr);
+        try {
+            process.stdout.write(s, (err) => finish(err === null || err === undefined));
+        }
+        catch {
+            finish(false);
+        }
+    });
+}
 // ---------------------------------------------------------------------------
 // stderr — diagnostics the agent MAY capture, never the result
 // ---------------------------------------------------------------------------
@@ -67,7 +113,11 @@ function payloadOf(e) {
  *  raw traces never reach the agent. Exits non-zero either way. */
 export function handle(e) {
     if (e instanceof CrtrError) {
-        process.stdout.write(JSON.stringify(payloadOf(e), null, 2) + '\n');
+        const payload = payloadOf(e);
+        const out = jsonOutput
+            ? JSON.stringify(payload, null, 2)
+            : renderError(payload);
+        process.stdout.write(out + '\n');
         process.exit(e.exitCode);
     }
     const err = e;

package/dist/core/personas/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Persona composer public surface.
+ *
+ * Re-exports:
+ *   - loadPersona / loadKernel / availableKinds   (loader — raw file access)
+ *   - resolve                    (high-level composer)
+ *   - ResolvedPersona            (return type of resolve)
+ */
+export { loadPersona, loadKernel, availableKinds } from './loader.js';
+export type { LoadedPersona } from './loader.js';
+export { resolve } from './resolve.js';
+export type { ResolvedPersona } from './resolve.js';

package/dist/core/personas/index.js

@@ -0,0 +1,10 @@
+/**
+ * Persona composer public surface.
+ *
+ * Re-exports:
+ *   - loadPersona / loadKernel / availableKinds   (loader — raw file access)
+ *   - resolve                    (high-level composer)
+ *   - ResolvedPersona            (return type of resolve)
+ */
+export { loadPersona, loadKernel, availableKinds } from './loader.js';
+export { resolve } from './resolve.js';

package/dist/core/personas/loader.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Persona file loader.
+ *
+ * Discovers and parses persona markdown files with YAML frontmatter.
+ * Resolution order (highest → lowest precedence): project > user > builtin.
+ *
+ * Layout on disk:
+ *   <root>/personas/<kind>/base.md
+ *   <root>/personas/<kind>/orchestrator.md
+ *   <root>/personas/orchestration-kernel.md
+ *
+ * The builtin root is src/builtin-personas (or dist/builtin-personas in the
+ * compiled build), resolved relative to this module — mirrors the pattern used
+ * for STOPHOOK_PATH in spawn.ts.
+ */
+export interface LoadedPersona {
+    /** Raw, uncoerced frontmatter key/value record (null when no frontmatter). */
+    frontmatter: Record<string, unknown> | null;
+    /** Body text with any @include directives inlined. */
+    body: string;
+}
+/**
+ * Load and parse a persona file for the given `kind` and `mode`.
+ *
+ * Returns `null` when no file is found in any scope (project/user/builtin).
+ * On success, `@include` directives in the body are resolved and inlined.
+ */
+export declare function loadPersona(kind: string, mode: 'base' | 'orchestrator'): LoadedPersona | null;
+/**
+ * Load the raw text of the orchestration kernel (no frontmatter, body only).
+ * Returns an empty string if the kernel file cannot be found.
+ */
+export declare function loadKernel(): string;
+/**
+ * Load the base runtime prompt — the node operating protocol prepended to
+ * EVERY persona (push/finish/delegate/feed/ask). Returns '' if not found.
+ */
+export declare function loadRuntimeBase(): string;
+/**
+ * Enumerate the kinds with at least one persona file (base.md or
+ * orchestrator.md) across all scope roots (project/user/builtin). Used to
+ * validate a requested `--kind` and to list the valid choices.
+ */
+export declare function availableKinds(): string[];

package/dist/core/personas/loader.js

@@ -0,0 +1,157 @@
+/**
+ * Persona file loader.
+ *
+ * Discovers and parses persona markdown files with YAML frontmatter.
+ * Resolution order (highest → lowest precedence): project > user > builtin.
+ *
+ * Layout on disk:
+ *   <root>/personas/<kind>/base.md
+ *   <root>/personas/<kind>/orchestrator.md
+ *   <root>/personas/orchestration-kernel.md
+ *
+ * The builtin root is src/builtin-personas (or dist/builtin-personas in the
+ * compiled build), resolved relative to this module — mirrors the pattern used
+ * for STOPHOOK_PATH in spawn.ts.
+ */
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseFrontmatterGeneric } from '../frontmatter.js';
+import { userScopeRoot, findProjectScopeRoot } from '../scope.js';
+// ---------------------------------------------------------------------------
+// Builtin root resolution
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the builtin-personas directory from the location of this compiled
+ * or source module. Works from both `dist/core/personas/loader.js` and
+ * `src/core/personas/loader.ts` (tsx dev runs).
+ */
+function builtinPersonasRoot() {
+    const here = dirname(fileURLToPath(import.meta.url)); // dist/core/personas or src/core/personas
+    const coreDir = dirname(here); // dist/core or src/core
+    const pkgDir = dirname(coreDir); // dist/ or src/
+    const distPath = join(pkgDir, 'builtin-personas');
+    const srcPath = join(dirname(pkgDir), 'src', 'builtin-personas');
+    // Prefer the path that exists; fall back to the dist-sibling (which may not
+    // exist yet if the package is being run pre-build, but that is the caller's
+    // problem).
+    if (existsSync(distPath))
+        return distPath;
+    if (existsSync(srcPath))
+        return srcPath;
+    return distPath;
+}
+// ---------------------------------------------------------------------------
+// Scope roots for personas
+// ---------------------------------------------------------------------------
+/** Returns the ordered list of roots to search, highest precedence first. */
+function personaSearchRoots() {
+    const roots = [];
+    const projectRoot = findProjectScopeRoot();
+    if (projectRoot)
+        roots.push(join(projectRoot, 'personas'));
+    roots.push(join(userScopeRoot(), 'personas'));
+    roots.push(builtinPersonasRoot());
+    return roots;
+}
+// ---------------------------------------------------------------------------
+// File resolution helpers
+// ---------------------------------------------------------------------------
+/**
+ * Find the first existing file across the scope roots.
+ * `relativePath` is relative to each root (e.g. 'general/base.md').
+ */
+function resolveFile(relativePath) {
+    for (const root of personaSearchRoots()) {
+        const candidate = join(root, relativePath);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// @include inlining
+// ---------------------------------------------------------------------------
+const INCLUDE_RE = /^@include\s+(\S+)\s*$/m;
+/**
+ * Inline any `@include <filename>` directive found in `body`.
+ * The included file is looked up via the same scope-resolution chain; if it
+ * cannot be found, the directive line is replaced with an empty string rather
+ * than throwing — callers that need the kernel should use `loadKernel()`
+ * directly and can assert it themselves.
+ */
+function inlineIncludes(body) {
+    return body.replace(INCLUDE_RE, (_match, filename) => {
+        const path = resolveFile(filename);
+        if (!path)
+            return '';
+        const src = readFileSync(path, 'utf8');
+        // The kernel file has no frontmatter, but run through the parser just in
+        // case someone added one in a user/project override.
+        const { body: kernelBody } = parseFrontmatterGeneric(src);
+        return kernelBody.trim();
+    });
+}
+/**
+ * Load and parse a persona file for the given `kind` and `mode`.
+ *
+ * Returns `null` when no file is found in any scope (project/user/builtin).
+ * On success, `@include` directives in the body are resolved and inlined.
+ */
+export function loadPersona(kind, mode) {
+    const relativePath = `${kind}/${mode}.md`;
+    const filePath = resolveFile(relativePath);
+    if (!filePath)
+        return null;
+    const src = readFileSync(filePath, 'utf8');
+    const { data, body } = parseFrontmatterGeneric(src);
+    return {
+        frontmatter: data,
+        body: inlineIncludes(body).trim(),
+    };
+}
+/**
+ * Load the raw text of the orchestration kernel (no frontmatter, body only).
+ * Returns an empty string if the kernel file cannot be found.
+ */
+export function loadKernel() {
+    const filePath = resolveFile('orchestration-kernel.md');
+    if (!filePath)
+        return '';
+    const src = readFileSync(filePath, 'utf8');
+    const { body } = parseFrontmatterGeneric(src);
+    return body.trim();
+}
+/**
+ * Load the base runtime prompt — the node operating protocol prepended to
+ * EVERY persona (push/finish/delegate/feed/ask). Returns '' if not found.
+ */
+export function loadRuntimeBase() {
+    const filePath = resolveFile('runtime-base.md');
+    if (!filePath)
+        return '';
+    const src = readFileSync(filePath, 'utf8');
+    const { body } = parseFrontmatterGeneric(src);
+    return body.trim();
+}
+/**
+ * Enumerate the kinds with at least one persona file (base.md or
+ * orchestrator.md) across all scope roots (project/user/builtin). Used to
+ * validate a requested `--kind` and to list the valid choices.
+ */
+export function availableKinds() {
+    const kinds = new Set();
+    for (const root of personaSearchRoots()) {
+        if (!existsSync(root))
+            continue;
+        for (const entry of readdirSync(root, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const dir = join(root, entry.name);
+            if (existsSync(join(dir, 'base.md')) || existsSync(join(dir, 'orchestrator.md'))) {
+                kinds.add(entry.name);
+            }
+        }
+    }
+    return [...kinds].sort();
+}

package/dist/core/personas/resolve.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Persona resolver — composes base + orchestrator personas into a
+ * ResolvedPersona ready for use when spawning a canvas node.
+ *
+ * Composition rules:
+ *   mode==='base'
+ *     → load <kind>/base.md; if missing fall back to general defaults.
+ *
+ *   mode==='orchestrator'
+ *     → prefer <kind>/orchestrator.md (which must embed the kernel via
+ *       @include orchestration-kernel.md — inlined by the loader).
+ *       If no orchestrator.md exists for this kind, compose:
+ *         <kind>/base.md body  +  '\n\n'  +  kernel body
+ *       If even the base is missing, fall back to general defaults + kernel.
+ *
+ * Frontmatter from whichever file is the primary source (orchestrator.md >
+ * base.md) supplies model/lifecycle/skills/extensions/tools.
+ *
+ * Lifecycle defaults:
+ *   base         → 'terminal'
+ *   orchestrator → 'resident'
+ */
+export interface ResolvedPersona {
+    systemPrompt: string;
+    extensions: string[];
+    skills: string[];
+    model?: string;
+    lifecycle: 'terminal' | 'resident';
+    tools?: string[];
+}
+/**
+ * Resolve a fully composed persona for the given `kind` and `mode`.
+ *
+ * Never throws for missing files — missing personas produce sensible defaults.
+ */
+export declare function resolve(kind: string, mode: 'base' | 'orchestrator'): ResolvedPersona;

package/dist/core/personas/resolve.js

@@ -0,0 +1,110 @@
+/**
+ * Persona resolver — composes base + orchestrator personas into a
+ * ResolvedPersona ready for use when spawning a canvas node.
+ *
+ * Composition rules:
+ *   mode==='base'
+ *     → load <kind>/base.md; if missing fall back to general defaults.
+ *
+ *   mode==='orchestrator'
+ *     → prefer <kind>/orchestrator.md (which must embed the kernel via
+ *       @include orchestration-kernel.md — inlined by the loader).
+ *       If no orchestrator.md exists for this kind, compose:
+ *         <kind>/base.md body  +  '\n\n'  +  kernel body
+ *       If even the base is missing, fall back to general defaults + kernel.
+ *
+ * Frontmatter from whichever file is the primary source (orchestrator.md >
+ * base.md) supplies model/lifecycle/skills/extensions/tools.
+ *
+ * Lifecycle defaults:
+ *   base         → 'terminal'
+ *   orchestrator → 'resident'
+ */
+import { loadPersona, loadKernel, loadRuntimeBase } from './loader.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function toStringArray(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((x) => typeof x === 'string');
+}
+function toOptionalString(v) {
+    return typeof v === 'string' ? v : undefined;
+}
+function toLifecycle(v, defaultValue) {
+    if (v === 'terminal' || v === 'resident')
+        return v;
+    return defaultValue;
+}
+/** The bare-minimum system prompt used when no persona file is found at all. */
+function fallbackBasePrompt(kind) {
+    return `You are a ${kind} agent. Complete the task you have been given.`;
+}
+/** Prepend the base runtime protocol (push/finish/delegate/feed/ask) to a
+ *  persona's prompt — every node, every kind, every mode gets it first. */
+function withBase(personaPrompt) {
+    const base = loadRuntimeBase();
+    return base ? `${base}\n\n---\n\n${personaPrompt}` : personaPrompt;
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a fully composed persona for the given `kind` and `mode`.
+ *
+ * Never throws for missing files — missing personas produce sensible defaults.
+ */
+export function resolve(kind, mode) {
+    if (mode === 'base') {
+        const persona = loadPersona(kind, 'base');
+        if (!persona) {
+            // No persona file for this kind — use minimal defaults.
+            return {
+                systemPrompt: withBase(fallbackBasePrompt(kind)),
+                extensions: [],
+                skills: [],
+                lifecycle: 'terminal',
+            };
+        }
+        const fm = persona.frontmatter ?? {};
+        return {
+            systemPrompt: withBase(persona.body || fallbackBasePrompt(kind)),
+            extensions: toStringArray(fm['extensions']),
+            skills: toStringArray(fm['skills']),
+            model: toOptionalString(fm['model']),
+            lifecycle: toLifecycle(fm['lifecycle'], 'terminal'),
+            tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
+        };
+    }
+    // mode === 'orchestrator'
+    const orchestratorPersona = loadPersona(kind, 'orchestrator');
+    if (orchestratorPersona) {
+        // Orchestrator file exists; @include was already inlined by the loader.
+        const fm = orchestratorPersona.frontmatter ?? {};
+        return {
+            systemPrompt: withBase(orchestratorPersona.body || fallbackBasePrompt(kind)),
+            extensions: toStringArray(fm['extensions']),
+            skills: toStringArray(fm['skills']),
+            model: toOptionalString(fm['model']),
+            lifecycle: toLifecycle(fm['lifecycle'], 'resident'),
+            tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
+        };
+    }
+    // No orchestrator.md for this kind — compose base + bare kernel.
+    const kernel = loadKernel();
+    const basePersona = loadPersona(kind, 'base');
+    const baseBody = basePersona?.body || fallbackBasePrompt(kind);
+    const fm = basePersona?.frontmatter ?? {};
+    // Append the kernel to the base body (with separator if kernel is non-empty).
+    const systemPrompt = kernel ? `${baseBody}\n\n${kernel}` : baseBody;
+    return {
+        systemPrompt: withBase(systemPrompt),
+        extensions: toStringArray(fm['extensions']),
+        skills: toStringArray(fm['skills']),
+        model: toOptionalString(fm['model']),
+        // Override lifecycle to 'resident' — this node is being used as an orchestrator.
+        lifecycle: 'resident',
+        tools: fm['tools'] !== undefined ? toStringArray(fm['tools']) : undefined,
+    };
+}

package/dist/core/render.d.ts

@@ -0,0 +1,11 @@
+import type { LeafHelp } from './help.js';
+import type { ErrorPayload } from './io.js';
+/** Schema-driven fallback: turn a result object into agent-ready XML+markdown.
+ *  Field order follows the leaf's declared output schema; any extra keys append
+ *  after. Scalars become attributes or a bullet list, prose and collections
+ *  become their own fenced blocks. */
+export declare function renderResult(result: Record<string, unknown>, help: LeafHelp): string;
+/** Render a structured failure as an instruction-shaped block: what broke, what
+ *  was received, and the recovery road sign — the same recovery info the JSON
+ *  payload carries, shaped for the model to act on. */
+export declare function renderError(p: ErrorPayload): string;

package/dist/core/render.js

@@ -0,0 +1,126 @@
+// Default stdout rendering: the result a leaf returns is written FOR the model
+// to act on, not as data to parse. Output is a continuation of the agent's
+// prompt — light XML fences around markdown, prose where prose belongs. The
+// raw JSON object is still available behind the `--json` global for tooling.
+//
+// A leaf may hand `defineLeaf` a bespoke `render(result)` for instruction-shaped
+// output (see `node new`, `push`, `feed read`). Everything else falls through to
+// the schema-driven generic renderer here, so every command obeys the paradigm
+// without a hand-written renderer.
+// Field names whose value is prose the agent reads, not a scalar it keys on —
+// these always render as their own fenced block, never as a tag attribute.
+const PROSE_FIELDS = new Set([
+    'follow_up', 'digest', 'message', 'next', 'result', 'content', 'body', 'guide',
+    'summary', 'note', 'reason', 'detail', 'details', 'hint', 'instruction',
+    'instructions', 'prompt', 'roadmap', 'report', 'answer', 'response', 'text',
+]);
+/** Minimal attribute-value sanitization: values here are controlled (ids,
+ *  statuses, counts), so collapse quotes rather than entity-escape. */
+function attrEsc(s) {
+    return String(s).replace(/"/g, "'").replace(/\n/g, ' ');
+}
+function scalarStr(v) {
+    if (v === null || v === undefined)
+        return '';
+    if (Array.isArray(v))
+        return v.map(scalarStr).join(', ');
+    if (typeof v === 'object')
+        return JSON.stringify(v);
+    return String(v);
+}
+/** A string field is prose when it is named as such, spans lines, or is long
+ *  enough that it reads as a sentence rather than an identifier. */
+function isProse(name, v) {
+    if (typeof v !== 'string')
+        return false;
+    if (PROSE_FIELDS.has(name))
+        return true;
+    return v.includes('\n') || v.length > 80;
+}
+/** Short, space-free scalars ride as attributes on the open tag (ids, statuses,
+ *  counts); everything else that isn't prose lists as a markdown bullet. */
+function isAttr(v) {
+    if (typeof v === 'number' || typeof v === 'boolean')
+        return true;
+    return typeof v === 'string' && v.length <= 40 && !v.includes(' ') && !v.includes('\n');
+}
+/** Root element name = the command path with spaces hyphenated. */
+function rootTag(help) {
+    return help.name.trim().split(/\s+/).join('-').replace(/[^a-zA-Z0-9_-]/g, '') || 'result';
+}
+function renderArray(name, arr) {
+    if (arr.length === 0)
+        return `<${name} count="0"></${name}>`;
+    const allObjects = arr.every((x) => x !== null && typeof x === 'object' && !Array.isArray(x));
+    if (allObjects) {
+        const rows = arr;
+        const cols = [];
+        for (const r of rows)
+            for (const k of Object.keys(r))
+                if (!cols.includes(k))
+                    cols.push(k);
+        const head = `| ${cols.join(' | ')} |`;
+        const sep = `| ${cols.map(() => '---').join(' | ')} |`;
+        const body = rows.map((r) => `| ${cols.map((c) => scalarStr(r[c])).join(' | ')} |`).join('\n');
+        return `<${name} count="${arr.length}">\n${head}\n${sep}\n${body}\n</${name}>`;
+    }
+    const items = arr.map((x) => `- ${scalarStr(x)}`).join('\n');
+    return `<${name} count="${arr.length}">\n${items}\n</${name}>`;
+}
+/** Schema-driven fallback: turn a result object into agent-ready XML+markdown.
+ *  Field order follows the leaf's declared output schema; any extra keys append
+ *  after. Scalars become attributes or a bullet list, prose and collections
+ *  become their own fenced blocks. */
+export function renderResult(result, help) {
+    const order = help.output.map((f) => f.name);
+    for (const k of Object.keys(result))
+        if (!order.includes(k))
+            order.push(k);
+    const attrs = [];
+    const bullets = [];
+    const blocks = [];
+    for (const name of order) {
+        const v = result[name];
+        if (v === undefined || v === null)
+            continue;
+        if (Array.isArray(v)) {
+            blocks.push(renderArray(name, v));
+            continue;
+        }
+        if (typeof v === 'object') {
+            blocks.push(`<${name}>\n${JSON.stringify(v, null, 2)}\n</${name}>`);
+            continue;
+        }
+        if (isProse(name, v)) {
+            blocks.push(`<${name}>\n${v}\n</${name}>`);
+            continue;
+        }
+        if (isAttr(v)) {
+            attrs.push(`${name}="${attrEsc(v)}"`);
+            continue;
+        }
+        bullets.push(`- ${name}: ${scalarStr(v)}`);
+    }
+    const tag = rootTag(help);
+    const open = attrs.length > 0 ? `<${tag} ${attrs.join(' ')}>` : `<${tag}>`;
+    const parts = [];
+    if (bullets.length > 0)
+        parts.push(bullets.join('\n'));
+    if (blocks.length > 0)
+        parts.push(blocks.join('\n\n'));
+    const inner = parts.join('\n\n');
+    return inner !== '' ? `${open}\n${inner}\n</${tag}>` : `${open}</${tag}>`;
+}
+/** Render a structured failure as an instruction-shaped block: what broke, what
+ *  was received, and the recovery road sign — the same recovery info the JSON
+ *  payload carries, shaped for the model to act on. */
+export function renderError(p) {
+    const lines = [p.message];
+    if (p.received !== undefined && p.received !== null && p.received !== '') {
+        lines.push(`received: ${scalarStr(p.received)}`);
+    }
+    if (p.field !== undefined)
+        lines.push(`field: ${p.field}`);
+    lines.push(`Next: ${p.next}`);
+    return `<error code="${attrEsc(p.error)}">\n${lines.join('\n')}\n</error>`;
+}

package/dist/core/resolver.d.ts

@@ -28,5 +28,15 @@ export declare function parseSkillQualifier(raw: string): ParsedSkillQualifier;
 export declare function listInstalledMarketplaces(scope: Scope): InstalledMarketplace[];
 export declare function listAllMarketplaces(): InstalledMarketplace[];
 export declare function findMarketplaceByName(name: string, scope?: Scope): InstalledMarketplace | null;
+export interface CategoryResolution {
+    id: string;
+    plugin: string | undefined;
+    scope: Scope | undefined;
+    dir: string;
+    indexPath: string | undefined;
+    skills: Skill[];
+}
+export declare function resolveCategory(name: string, opts?: SkillResolutionOpts): CategoryResolution | null;
+export declare function buildCategoryIndex(cat: CategoryResolution): string;
 export declare function scopeRootsLabel(): string;
 export {};