@north-light/crouter 0.3.154

package/dist/core/configured-clis/manifest.js

@@ -0,0 +1,284 @@
+// Configured CLI manifest validation and forest materialization.
+//
+// Implements §4 of the configured-CLI spec: strict atomic validation of a remote
+// manifest JSON, order-independent self-contained forest materialization,
+// REST mapping validation, and the canonical coalesced-body-source rule (exactly
+// one stdin + one non-stdin flag/positional sharing a body `as`).
+//
+// This is pure validation: no fetch, no registration lookup, no file I/O beyond
+// the raw manifest bytes passed in.
+import { validateConfiguredCliNode } from '../command-manifests/schema.js';
+// ---------------------------------------------------------------------------
+// Validation helpers
+// ---------------------------------------------------------------------------
+const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+const REST_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function typeName(v) {
+    if (v === null)
+        return 'null';
+    if (Array.isArray(v))
+        return 'array';
+    return typeof v;
+}
+// ---------------------------------------------------------------------------
+// Top-level manifest validation
+// ---------------------------------------------------------------------------
+/**
+ * Validates a configured CLI manifest exactly per §4, performing strict atomic
+ * validation and order-independent forest materialization. Returns either a
+ * valid manifest with roots ready to mount, or a complete issues list with
+ * zero contributions.
+ */
+export function validateConfiguredCliManifest(raw, options) {
+    const issues = [];
+    const issue = (code, message, received, expected, next, path) => {
+        issues.push({ code, message, received, expected, next, ...(path ? { path } : {}) });
+    };
+    // Top-level structure check
+    if (!isObject(raw)) {
+        issue('command_manifest_invalid', 'manifest must be an object', typeName(raw), '{ schemaVersion, baseUrl?, timeouts?, mounts }', 'Provide a valid JSON manifest object.');
+        return { issues };
+    }
+    // Check for unknown top-level keys
+    const topKeys = Object.keys(raw);
+    const allowedTopKeys = new Set(['schemaVersion', 'baseUrl', 'timeouts', 'mounts']);
+    const unknownKeys = topKeys.filter((k) => !allowedTopKeys.has(k));
+    if (unknownKeys.length > 0) {
+        issue('command_manifest_invalid', `unknown top-level keys`, unknownKeys.join(', '), 'only: schemaVersion, baseUrl, timeouts, mounts', 'Remove the unknown keys.');
+        return { issues };
+    }
+    // Validate schemaVersion
+    if (raw['schemaVersion'] !== 1) {
+        issue('command_schema_version', `schemaVersion must be exactly 1`, String(raw['schemaVersion']), '1', 'Update the manifest schema version to 1.', 'schemaVersion');
+        return { issues };
+    }
+    // Validate optional baseUrl
+    let baseUrl;
+    if (raw['baseUrl'] !== undefined) {
+        if (typeof raw['baseUrl'] !== 'string') {
+            issue('command_manifest_invalid', 'baseUrl must be a string', typeName(raw['baseUrl']), 'an absolute HTTP(S) URL or omitted', 'Provide a valid baseUrl or remove it.', 'baseUrl');
+            return { issues };
+        }
+        try {
+            const url = new URL(raw['baseUrl']);
+            if (!['http:', 'https:'].includes(url.protocol)) {
+                issue('command_manifest_invalid', 'baseUrl must be http: or https:', url.protocol, 'http: or https:', 'Use an HTTP(S) URL.', 'baseUrl');
+                return { issues };
+            }
+            baseUrl = raw['baseUrl'];
+        }
+        catch {
+            issue('command_manifest_invalid', 'baseUrl must be a valid absolute URL', raw['baseUrl'], 'a valid URL', 'Fix the baseUrl.', 'baseUrl');
+            return { issues };
+        }
+    }
+    // Validate optional timeouts
+    let timeouts;
+    if (raw['timeouts'] !== undefined) {
+        const t = validateTimeouts(raw['timeouts'], issue);
+        if (t === null)
+            return { issues };
+        timeouts = t;
+    }
+    // Validate mounts (required, non-empty)
+    const mounts = raw['mounts'];
+    if (!Array.isArray(mounts)) {
+        issue('command_manifest_invalid', 'mounts must be an array', typeName(mounts), 'a non-empty array of { parent, node } contributions', 'Provide at least one mount.', 'mounts');
+        return { issues };
+    }
+    if (mounts.length === 0) {
+        issue('command_manifest_invalid', 'mounts must be a non-empty array', 'empty array', 'at least one contribution', 'Add at least one mount.', 'mounts');
+        return { issues };
+    }
+    // Validate and collect all mounts
+    const validatedMounts = [];
+    for (let i = 0; i < mounts.length; i++) {
+        const m = validateMount(mounts[i], i, issue);
+        if (m === null)
+            return { issues };
+        validatedMounts.push(m);
+    }
+    // Materialize the forest: merge inline children with mounted nodes
+    const roots = materializeForest(validatedMounts, options.reservedCoreNames, issue);
+    if (roots === null)
+        return { issues };
+    // If we got here with no issues, return the validated manifest
+    if (issues.length === 0) {
+        return {
+            manifest: {
+                schemaVersion: 1,
+                ...(baseUrl !== undefined ? { baseUrl } : {}),
+                ...(timeouts !== undefined ? { timeouts } : {}),
+                roots,
+            },
+            issues: [],
+        };
+    }
+    // Any issue found -> zero contributions
+    return { issues };
+}
+// ---------------------------------------------------------------------------
+// Timeouts validation
+// ---------------------------------------------------------------------------
+function validateTimeouts(raw, issue) {
+    if (!isObject(raw)) {
+        issue('command_manifest_invalid', 'timeouts must be an object', typeName(raw), '{ connectMs?, requestMs?, streamIdleMs? }', 'Fix timeouts.', 'timeouts');
+        return null;
+    }
+    const allowedKeys = new Set(['connectMs', 'requestMs', 'streamIdleMs']);
+    const unknownKeys = Object.keys(raw).filter((k) => !allowedKeys.has(k));
+    if (unknownKeys.length > 0) {
+        issue('command_manifest_invalid', 'unknown timeouts keys', unknownKeys.join(', '), 'only: connectMs, requestMs, streamIdleMs', 'Remove the unknown keys.', 'timeouts');
+        return null;
+    }
+    const out = {};
+    for (const k of ['connectMs', 'requestMs', 'streamIdleMs']) {
+        if (raw[k] !== undefined) {
+            if (typeof raw[k] !== 'number' || !Number.isInteger(raw[k]) || raw[k] <= 0) {
+                issue('command_manifest_invalid', `${k} must be a positive integer`, String(raw[k]), 'a positive integer', `Fix ${k}.`, `timeouts.${k}`);
+                return null;
+            }
+            out[k] = raw[k];
+        }
+    }
+    return out;
+}
+function validateMount(raw, index, issue) {
+    const path = `mounts[${index}]`;
+    if (!isObject(raw)) {
+        issue('command_manifest_invalid', 'mount must be an object', typeName(raw), '{ parent, node }', 'Fix the mount.', path);
+        return null;
+    }
+    const allowedKeys = new Set(['parent', 'node']);
+    const unknownKeys = Object.keys(raw).filter((k) => !allowedKeys.has(k));
+    if (unknownKeys.length > 0) {
+        issue('command_manifest_invalid', 'unknown mount keys', unknownKeys.join(', '), 'only: parent, node', 'Remove the unknown keys.', path);
+        return null;
+    }
+    // Validate parent
+    const parentRaw = raw['parent'];
+    if (!Array.isArray(parentRaw)) {
+        issue('command_manifest_invalid', 'mount parent must be an array', typeName(parentRaw), 'an array of kebab tokens, or [] for a top-level mount', 'Fix parent.', `${path}.parent`);
+        return null;
+    }
+    for (let i = 0; i < parentRaw.length; i++) {
+        const t = parentRaw[i];
+        if (typeof t !== 'string' || !KEBAB.test(t)) {
+            issue('command_manifest_invalid', `parent token must be a kebab token`, String(t), 'a kebab-case identifier', 'Fix the parent path.', `${path}.parent[${i}]`);
+            return null;
+        }
+    }
+    const parent = parentRaw;
+    // Validate node
+    const nodeRaw = raw['node'];
+    const topLevel = parent.length === 0;
+    const node = validateConfiguredCliNode(nodeRaw, `${path}.node`, topLevel, issue);
+    if (node === null)
+        return null;
+    // Top-level mount must be a branch with rootEntry
+    if (topLevel && node.kind !== 'branch') {
+        issue('command_node_invalid', 'top-level mount node must be a branch', node.kind, 'a branch with a rootEntry', 'Wrap the command in a top-level branch.', `${path}.node.kind`);
+        return null;
+    }
+    // Ensure the node is properly typed (should only be ConfiguredCliDeclLeaf at this point)
+    const typedNode = node;
+    return { parent, node: typedNode };
+}
+// ---------------------------------------------------------------------------
+// Forest materialization (order-independent)
+// ---------------------------------------------------------------------------
+/**
+ * Materializes a flat list of mounts into a forest of top-level branches,
+ * resolving parent paths order-independently. Validates self-containment
+ * (no external parents), no duplicates, and no childless branches.
+ */
+function materializeForest(mounts, reservedCoreNames, issue) {
+    // Separate top-level (parent: []) from nested (parent non-empty)
+    const topLevel = mounts.filter((m) => m.parent.length === 0);
+    const nested = mounts.filter((m) => m.parent.length > 0);
+    // Check for core-name collisions in top-level nodes
+    for (const m of topLevel) {
+        if (reservedCoreNames.has(m.node.name)) {
+            issue('command_parent_invalid', `node name conflicts with a crtr core command`, m.node.name, `a name not in core (not one of: ${[...reservedCoreNames].join(', ')})`, 'Rename the node or remove this mount.', `${m.node.name}`);
+            return null;
+        }
+    }
+    // Build the forest: all top-level nodes with inline children, then attach nested mounts
+    const roots = topLevel.map((m) => ({
+        kind: 'branch',
+        name: m.node.name,
+        description: m.node.description,
+        whenToUse: m.node.whenToUse,
+        ...(m.node.tier !== undefined ? { tier: m.node.tier } : {}),
+        ...(m.node.rootEntry !== undefined ? { rootEntry: m.node.rootEntry } : {}),
+        summary: m.node.summary,
+        ...(m.node.model !== undefined ? { model: m.node.model } : {}),
+        children: [...m.node.children],
+    }));
+    // Attach nested mounts
+    for (const mount of nested) {
+        const resolved = resolveAndAttachMount(roots, mount, issue);
+        if (!resolved)
+            return null;
+    }
+    // Collect all paths as we materialize (for verification)
+    const pathIndex = new Set();
+    const indexPaths = (node, path) => {
+        const fullPath = path.join('.');
+        if (pathIndex.has(fullPath)) {
+            issue('command_node_invalid', `duplicate node path`, fullPath, 'unique paths within the manifest', 'Remove the duplicate node.', fullPath);
+            return false;
+        }
+        pathIndex.add(fullPath);
+        if (node.kind === 'branch') {
+            return node.children.every((child) => indexPaths(child, [...path, child.name]));
+        }
+        return true;
+    };
+    for (const root of roots) {
+        const child = root;
+        if (!indexPaths(child, [root.name]))
+            return null;
+    }
+    return roots;
+}
+/**
+ * Resolves a nested mount's parent path within the built roots and attaches
+ * the node. Validates that the parent exists and is a branch.
+ */
+function resolveAndAttachMount(roots, mount, issue) {
+    const [first, ...rest] = mount.parent;
+    const root = roots.find((r) => r.name === first);
+    if (!root) {
+        issue('command_parent_invalid', `parent path starts with unknown branch`, first, 'a branch this manifest contributes', 'Fix the parent path or add the parent branch.', mount.parent.join('.'));
+        return false;
+    }
+    let current = root;
+    for (const token of rest) {
+        const child = current.children.find((c) => c.name === token);
+        if (!child) {
+            issue('command_parent_invalid', `parent path contains unknown branch`, token, 'a branch this manifest contributes', 'Fix the parent path or add the intermediate branch.', mount.parent.join('.'));
+            return false;
+        }
+        if (child.kind === 'leaf') {
+            issue('command_parent_invalid', `parent path resolves to a leaf`, token, 'a branch', 'Change the parent to point to a branch.', mount.parent.join('.'));
+            return false;
+        }
+        current = child;
+    }
+    // Attach the node
+    if (current.children.some((c) => c.name === mount.node.name)) {
+        issue('command_node_invalid', `duplicate child name`, mount.node.name, 'unique child names within a branch', 'Rename the node or remove the duplicate.', `${mount.parent.join('.')}.${mount.node.name}`);
+        return false;
+    }
+    current.children.push(mount.node);
+    return true;
+}
+// ---------------------------------------------------------------------------
+// Configured CLI node validator (implements §4.3 + §4.4)
+// ---------------------------------------------------------------------------
+// Re-export and use the schema validator
+export { validateConfiguredCliNode } from '../command-manifests/schema.js';

package/dist/core/configured-clis/registration.d.ts

@@ -0,0 +1,40 @@
+import type { Scope } from '../../types.js';
+/** A registered configured CLI: name, endpoint, optional auth env var, scope and root. */
+export interface ConfiguredCliRegistration {
+    name: string;
+    endpoint: string;
+    authEnvVar?: string;
+    scope: 'project' | 'user';
+    root: string;
+}
+/** Validation result for registration inputs. */
+export interface RegistrationValidation {
+    isValid: boolean;
+    errors: string[];
+}
+/** Validate a registration name. */
+export declare function validateRegistrationName(name: unknown): RegistrationValidation;
+/** Validate an environment variable name. */
+export declare function validateEnvVarName(name: unknown): RegistrationValidation;
+/** Validate an endpoint URL. */
+export declare function validateEndpoint(endpoint: unknown): RegistrationValidation;
+/** Normalize endpoint URL to a canonical form (remove trailing slash if present). */
+export declare function normalizeEndpoint(endpoint: string): string;
+/** List every EFFECTIVE configured CLI visible across scopes (project nearest-first,
+ *  then user). Dedupes by name: the first-seen registration for a name wins (nearer
+ *  project root, then user) and any same-name registration in a farther scope is
+ *  omitted entirely — there is no shadowed-copy representation and no `effective`
+ *  field on `ConfiguredCliRegistration`. */
+export declare function listConfiguredCliRegistrations(): ConfiguredCliRegistration[];
+/** Get deduplicated effective registrations (one per unique name, project wins over user). */
+export declare function effectiveConfiguredClis(): ConfiguredCliRegistration[];
+/** Resolve a configured CLI registration by name. If scope is omitted, returns the
+ *  effective winner (project > user). If scope is explicit, returns the registration
+ *  in that scope or null if not found. */
+export declare function resolveConfiguredCli(name: string, scope?: Scope | 'project' | 'user'): ConfiguredCliRegistration | null;
+/** Get the cache directory for a configured CLI registration. */
+export declare function configuredCliCacheDir(registration: ConfiguredCliRegistration): string;
+/** Get the manifest file path for a configured CLI. */
+export declare function configuredCliManifestPath(registration: ConfiguredCliRegistration): string;
+/** Get the cache metadata file path for a configured CLI. */
+export declare function configuredCliCacheMetaPath(registration: ConfiguredCliRegistration): string;

package/dist/core/configured-clis/registration.js

@@ -0,0 +1,201 @@
+import { join } from 'node:path';
+import { configuredClisDir, configuredClisDirForRoot, projectScopeRoots, userScopeRoot } from '../scope.js';
+import { readConfig, readConfigAtRoot } from '../config.js';
+/** Kebab-case identifier: lowercase letter start, alphanumeric + hyphen chars,
+ *  no trailing hyphens. Examples: `demo`, `my-cli`, `azure-devops`. */
+function isValidRegistrationName(name) {
+    return /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(name);
+}
+/** Environment variable name: must start with letter or underscore, followed by
+ *  alphanumeric or underscore chars. Examples: `NL_CORE_TOKEN`, `_INTERNAL`. */
+function isValidEnvVarName(name) {
+    return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name);
+}
+/** Loopback hostnames permitted for plain-http endpoints (local dev only).
+ *  Includes `host.docker.internal`, Docker's own DNS alias a container uses to
+ *  reach its host — the container-network equivalent of loopback for the same
+ *  local-dev trust boundary (e.g. a Dockerized guest registering its host
+ *  Core as a configured CLI). */
+function isLoopbackHostname(hostname) {
+    // URL normalizes IPv6 hosts to bracketed form, e.g. `[::1]`.
+    return (hostname === 'localhost' ||
+        hostname === '127.0.0.1' ||
+        hostname === '[::1]' ||
+        hostname === '::1' ||
+        hostname === 'host.docker.internal');
+}
+/** Validate that endpoint is an absolute HTTPS URL (or HTTP on a loopback host)
+ *  with no credentials/fragment. */
+function isValidEndpoint(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        // https required; plain http permitted only for loopback hosts (local dev)
+        if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLoopbackHostname(url.hostname)))
+            return false;
+        if (url.username || url.password || url.hash)
+            return false;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Validate a registration name. */
+export function validateRegistrationName(name) {
+    const errors = [];
+    if (typeof name !== 'string') {
+        errors.push('name must be a string');
+    }
+    else if (!isValidRegistrationName(name)) {
+        errors.push('name must be kebab-case (lowercase letter start, alphanumeric + hyphens)');
+    }
+    return { isValid: errors.length === 0, errors };
+}
+/** Validate an environment variable name. */
+export function validateEnvVarName(name) {
+    const errors = [];
+    if (typeof name !== 'string') {
+        errors.push('env var name must be a string');
+    }
+    else if (!isValidEnvVarName(name)) {
+        errors.push('env var name must start with letter/underscore, followed by alphanumeric/underscore');
+    }
+    return { isValid: errors.length === 0, errors };
+}
+/** Validate an endpoint URL. */
+export function validateEndpoint(endpoint) {
+    const errors = [];
+    if (typeof endpoint !== 'string') {
+        errors.push('endpoint must be a string');
+    }
+    else if (!isValidEndpoint(endpoint)) {
+        errors.push('endpoint must be an absolute https:// URL (http:// permitted for loopback hosts only; no credentials or fragment)');
+    }
+    return { isValid: errors.length === 0, errors };
+}
+/** Normalize endpoint URL to a canonical form (remove trailing slash if present). */
+export function normalizeEndpoint(endpoint) {
+    try {
+        const url = new URL(endpoint);
+        // Reconstruct without trailing slash on path
+        let pathname = url.pathname;
+        if (pathname.length > 1 && pathname.endsWith('/')) {
+            pathname = pathname.slice(0, -1);
+        }
+        return `${url.protocol}//${url.host}${pathname}${url.search}`;
+    }
+    catch {
+        return endpoint;
+    }
+}
+/** List every EFFECTIVE configured CLI visible across scopes (project nearest-first,
+ *  then user). Dedupes by name: the first-seen registration for a name wins (nearer
+ *  project root, then user) and any same-name registration in a farther scope is
+ *  omitted entirely — there is no shadowed-copy representation and no `effective`
+ *  field on `ConfiguredCliRegistration`. */
+export function listConfiguredCliRegistrations() {
+    const out = [];
+    const seen = new Set();
+    // Project scopes, nearest-first (projectScopeRoots is already nearest-first).
+    // Read EACH root's own config directly and address its own cache dir, so a
+    // nested/profile-widened stack keeps nearest-project precedence (first-seen
+    // wins) instead of collapsing every root onto the nearest config. `root` is
+    // the `configured-clis/` cache parent (matching resolveConfiguredCli and
+    // configuredCliCacheDir), never the bare scope-root.
+    for (const scopeRootDir of projectScopeRoots()) {
+        const config = readConfigAtRoot(scopeRootDir);
+        const root = configuredClisDirForRoot(scopeRootDir);
+        for (const [name, entry] of Object.entries(config.configuredClis)) {
+            if (seen.has(name))
+                continue;
+            out.push({
+                name,
+                endpoint: entry.endpoint,
+                authEnvVar: entry.authEnvVar,
+                scope: 'project',
+                root,
+            });
+            seen.add(name);
+        }
+    }
+    // Then user scope (lowest precedence, so add unseen ones).
+    const userConfig = readConfig('user');
+    const userRoot = configuredClisDirForRoot(userScopeRoot());
+    for (const [name, entry] of Object.entries(userConfig.configuredClis)) {
+        if (seen.has(name))
+            continue;
+        out.push({
+            name,
+            endpoint: entry.endpoint,
+            authEnvVar: entry.authEnvVar,
+            scope: 'user',
+            root: userRoot,
+        });
+        seen.add(name);
+    }
+    return out;
+}
+/** Get deduplicated effective registrations (one per unique name, project wins over user). */
+export function effectiveConfiguredClis() {
+    return listConfiguredCliRegistrations();
+}
+/** Resolve a configured CLI registration by name. If scope is omitted, returns the
+ *  effective winner (project > user). If scope is explicit, returns the registration
+ *  in that scope or null if not found. */
+export function resolveConfiguredCli(name, scope) {
+    const all = listConfiguredCliRegistrations();
+    if (scope === undefined) {
+        // Return effective winner (first in list after precedence ordering)
+        return all.find((r) => r.name === name) ?? null;
+    }
+    if (scope !== 'project' && scope !== 'user') {
+        return null; // builtin scope is not applicable
+    }
+    if (scope === 'project') {
+        // Walk every visible project root (nearest-first), matching the same
+        // precedence `listConfiguredCliRegistrations` uses — an explicit
+        // `--scope project` must find a registration in a farther project root,
+        // not only the nearest one.
+        for (const scopeRootDir of projectScopeRoots()) {
+            const config = readConfigAtRoot(scopeRootDir);
+            const entry = config.configuredClis[name];
+            if (!entry)
+                continue;
+            return {
+                name,
+                endpoint: entry.endpoint,
+                authEnvVar: entry.authEnvVar,
+                scope: 'project',
+                root: configuredClisDirForRoot(scopeRootDir),
+            };
+        }
+        return null;
+    }
+    // user scope: single root.
+    const config = readConfig('user');
+    const entry = config.configuredClis[name];
+    if (!entry)
+        return null;
+    const root = configuredClisDir('user');
+    if (!root)
+        return null;
+    return {
+        name,
+        endpoint: entry.endpoint,
+        authEnvVar: entry.authEnvVar,
+        scope: 'user',
+        root,
+    };
+}
+/** Get the cache directory for a configured CLI registration. */
+export function configuredCliCacheDir(registration) {
+    return join(registration.root, registration.name);
+}
+/** Get the manifest file path for a configured CLI. */
+export function configuredCliManifestPath(registration) {
+    return join(configuredCliCacheDir(registration), 'manifest.json');
+}
+/** Get the cache metadata file path for a configured CLI. */
+export function configuredCliCacheMetaPath(registration) {
+    return join(configuredCliCacheDir(registration), 'meta.json');
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,27 @@
+import { type ExitCodeValue } from '../types.js';
+export declare class CrtrError extends Error {
+    code: string;
+    exitCode: ExitCodeValue;
+    details?: Record<string, unknown>;
+    constructor(code: string, message: string, exitCode?: ExitCodeValue, details?: Record<string, unknown>);
+}
+export declare function notFound(message: string, details?: Record<string, unknown>): CrtrError;
+export declare function usage(message: string, details?: Record<string, unknown>): CrtrError;
+export declare function ambiguous(message: string, details?: Record<string, unknown>): CrtrError;
+export declare function network(message: string, details?: Record<string, unknown>): CrtrError;
+export declare function general(message: string, details?: Record<string, unknown>): CrtrError;
+/** A node's broker ENGINE failed to launch or bind its view socket — an
+ *  operational failure surfaced from deep in the spawn/revive path (e.g. the
+ *  front-door root create). It is NOT a bad request and NOT an internal crtr
+ *  bug: it carries a curated cause the caller needs, so it must never collapse
+ *  into a bare `internal` 500 with the message stripped.
+ *
+ *  The `details` deliberately carry the FULL `{error, message, next}` payload so
+ *  a server-thrown instance round-trips through crtrd verbatim: `toErrorBody`
+ *  surfaces it as a <500 body with structured details, and the client's
+ *  `apiErrorToCliError` (tier 2) reconstructs the exact code, message, and
+ *  actionable `next` instead of degrading to a generic `invalid_request`. */
+export declare function brokerLaunchFailed(message: string, next: string): CrtrError;
+/** Thrown by stub handlers for leaves not yet wired in P3+.
+ *  code='not_implemented', exitCode=GENERAL, next names the node. */
+export declare function notImplemented(node: string): CrtrError;

package/dist/core/errors.js

@@ -0,0 +1,48 @@
+import { ExitCode } from '../types.js';
+export class CrtrError extends Error {
+    code;
+    exitCode;
+    details;
+    constructor(code, message, exitCode = ExitCode.GENERAL, details) {
+        super(message);
+        this.name = 'CrtrError';
+        this.code = code;
+        this.exitCode = exitCode;
+        this.details = details;
+    }
+}
+export function notFound(message, details) {
+    return new CrtrError('not_found', message, ExitCode.NOT_FOUND, details);
+}
+export function usage(message, details) {
+    return new CrtrError('usage', message, ExitCode.USAGE, details);
+}
+export function ambiguous(message, details) {
+    return new CrtrError('ambiguous', message, ExitCode.AMBIGUOUS, details);
+}
+export function network(message, details) {
+    return new CrtrError('network', message, ExitCode.NETWORK, details);
+}
+export function general(message, details) {
+    return new CrtrError('error', message, ExitCode.GENERAL, details);
+}
+/** A node's broker ENGINE failed to launch or bind its view socket — an
+ *  operational failure surfaced from deep in the spawn/revive path (e.g. the
+ *  front-door root create). It is NOT a bad request and NOT an internal crtr
+ *  bug: it carries a curated cause the caller needs, so it must never collapse
+ *  into a bare `internal` 500 with the message stripped.
+ *
+ *  The `details` deliberately carry the FULL `{error, message, next}` payload so
+ *  a server-thrown instance round-trips through crtrd verbatim: `toErrorBody`
+ *  surfaces it as a <500 body with structured details, and the client's
+ *  `apiErrorToCliError` (tier 2) reconstructs the exact code, message, and
+ *  actionable `next` instead of degrading to a generic `invalid_request`. */
+export function brokerLaunchFailed(message, next) {
+    const code = 'broker_launch_failed';
+    return new CrtrError(code, message, ExitCode.GENERAL, { error: code, message, next });
+}
+/** Thrown by stub handlers for leaves not yet wired in P3+.
+ *  code='not_implemented', exitCode=GENERAL, next names the node. */
+export function notImplemented(node) {
+    return new CrtrError('not_implemented', `${node} is not yet implemented.`, ExitCode.GENERAL, { next: 'This leaf is not yet wired.' });
+}

package/dist/core/events/emit.d.ts

@@ -0,0 +1,4 @@
+import type { BuildEnvelopeInput } from './types.js';
+export type EmitEventInput = Omit<BuildEnvelopeInput, 'component' | 'stream_id'>;
+/** The only canonical write path. The bound source owns the destination component/path/stream; node_id identifies the event target, with a broker source enforcing its bound node. */
+export declare function emitEvent(input: EmitEventInput): boolean;

package/dist/core/events/emit.js

@@ -0,0 +1,17 @@
+import { appendRotatingRecord } from '../log.js';
+import { buildEnvelope } from './envelope.js';
+import { serializeEventRecord } from './serialize.js';
+import { eventSource } from './source.js';
+/** The only canonical write path. The bound source owns the destination component/path/stream; node_id identifies the event target, with a broker source enforcing its bound node. */
+export function emitEvent(input) {
+    const source = eventSource();
+    if (source === undefined)
+        return false;
+    if (source.component === 'broker' && source.node_id !== undefined && input.node_id !== undefined && input.node_id !== source.node_id) {
+        throw new TypeError(`broker event target node_id must match bound node_id; received ${input.node_id}`);
+    }
+    if (input.level === 'debug' && process.env['CRTR_LOG'] !== 'debug')
+        return false;
+    const envelope = buildEnvelope({ ...input, component: source.component, ...(source.node_id === undefined ? {} : { node_id: source.node_id }), ...(source.stream_id === undefined ? {} : { stream_id: source.stream_id }) });
+    return appendRotatingRecord(source.path, serializeEventRecord(envelope));
+}

package/dist/core/events/envelope.d.ts

@@ -0,0 +1,2 @@
+import type { BuildEnvelopeInput, EventEnvelope } from './types.js';
+export declare function buildEnvelope(input: BuildEnvelopeInput): EventEnvelope;