@north-light/crouter 0.3.318 → 0.3.320

package/dist/core/command-hooks/transport/exec-lifecycle.js

@@ -1,211 +1 @@
-import { randomBytes } from 'node:crypto';
-import { spawn } from 'node:child_process';
-import { PROCESS_GROUP_KILL_GRACE_MS, posixProcessGroupSpawnOptions, terminateProcessGroup } from '../../../hook-process.js';
-import { isRecord } from '../../../shared/predicates.js';
-import { diag } from '../../io.js';
-import { LIFECYCLE_CATALOG } from '../lifecycle-catalog.js';
-const MAX_STDOUT = 10 * 1024 * 1024;
-/** Runs one lifecycle hook. `node:start` and `node:close` remain best-effort. */
-export async function invokeLifecycleHook(hook, invocation, timeoutMs) {
-    try {
-        const envelope = await executeLifecycleHook(hook, invocation, timeoutMs);
-        if (!envelope.ok)
-            diag(`crtr: ${label(hook)} failed: ${envelope.error.code}: ${envelope.error.message}`);
-    }
-    catch (error) {
-        diag(`crtr: ${label(hook)} failed: ${describeError(error)}`);
-    }
-}
-/** Executes non-blocking lifecycle hooks in discovery order within the event's catalogued budget. */
-export async function invokeLifecycleHooks(hooks, invocation) {
-    if (hooks.length === 0)
-        return;
-    const { hookTimeoutMs, eventBudgetMs } = LIFECYCLE_CATALOG[hooks[0].event];
-    const deadline = Date.now() + eventBudgetMs;
-    for (const hook of hooks) {
-        const remaining = deadline - Date.now();
-        const timeoutMs = Math.min(hookTimeoutMs, remaining - PROCESS_GROUP_KILL_GRACE_MS);
-        if (timeoutMs <= 0) {
-            diag(`crtr: lifecycle hook event ${hook.event} exceeded its ${eventBudgetMs}ms aggregate budget; skipped ${label(hook)}`);
-            return;
-        }
-        await invokeLifecycleHook(hook, invocation, timeoutMs);
-    }
-}
-/** Runs blocking `node:create` hooks. Every protocol or process failure refuses the create. */
-export async function invokeBlockingLifecycleHooks(hooks, invocation) {
-    if (hooks.length === 0)
-        return null;
-    const { hookTimeoutMs, eventBudgetMs } = LIFECYCLE_CATALOG['node:create'];
-    const deadline = Date.now() + eventBudgetMs;
-    for (const hook of hooks) {
-        const remaining = deadline - Date.now();
-        const timeoutMs = Math.min(hookTimeoutMs, remaining - PROCESS_GROUP_KILL_GRACE_MS);
-        if (timeoutMs <= 0) {
-            return refusal(hook, `lifecycle hook event node:create exceeded its ${eventBudgetMs}ms aggregate budget`);
-        }
-        try {
-            const envelope = await executeLifecycleHook(hook, invocation, timeoutMs);
-            if (!envelope.ok)
-                return {
-                    hook,
-                    message: envelope.error.message,
-                    next: envelope.error.next ?? attribution(hook),
-                };
-        }
-        catch (error) {
-            return refusal(hook, describeError(error));
-        }
-    }
-    return null;
-}
-function refusal(hook, cause) {
-    return {
-        hook,
-        message: `${label(hook)} failed: ${cause}`,
-        next: attribution(hook),
-    };
-}
-export function lifecycleHookAttribution(hook) {
-    return attribution(hook);
-}
-async function executeLifecycleHook(hook, invocation, timeoutMs) {
-    const request = hook.event === 'node:create'
-        ? createRequest(hook, invocation)
-        : nodeRequest(hook, invocation);
-    const result = await runLifecycleProcess(hook, JSON.stringify(request), timeoutMs);
-    if (result.signal !== null)
-        throw new Error(`executable was killed by signal ${result.signal}`);
-    const envelope = parseEnvelope(result.stdout);
-    if (envelope.ok && result.status !== 0) {
-        diag(`crtr: ${label(hook)} returned ok:true but exited ${result.status} (honoring the envelope)`);
-    }
-    return envelope;
-}
-function nodeRequest(hook, invocation) {
-    return {
-        protocolVersion: 1,
-        op: hook.op,
-        event: hook.event,
-        phase: hook.phase,
-        operationId: randomBytes(16).toString('hex'),
-        node: invocation.node,
-        runtime: invocation.runtime,
-        context: { cwd: invocation.node.cwd },
-    };
-}
-function createRequest(hook, invocation) {
-    return {
-        protocolVersion: 1,
-        op: hook.op,
-        event: 'node:create',
-        phase: 'before',
-        operationId: randomBytes(16).toString('hex'),
-        create: invocation.create,
-        runtime: invocation.runtime,
-        context: { cwd: invocation.create.cwd },
-    };
-}
-async function runLifecycleProcess(hook, input, timeoutMs) {
-    let child;
-    try {
-        child = spawn(hook.executable, ['--crtr-hook-protocol', '1'], {
-            cwd: hook.plugin.root,
-            env: process.env,
-            stdio: ['pipe', 'pipe', 'inherit'],
-            ...posixProcessGroupSpawnOptions(),
-        });
-    }
-    catch (error) {
-        throw new Error(`executable could not be run (${describeError(error)})`);
-    }
-    return new Promise((resolve, reject) => {
-        let stdoutBytes = 0;
-        const stdout = [];
-        let failure;
-        let closed = false;
-        let cleaned = false;
-        let status = null;
-        let signal = null;
-        let timeout;
-        const finish = () => {
-            if (!closed || (failure !== undefined && !cleaned))
-                return;
-            if (timeout !== undefined)
-                clearTimeout(timeout);
-            if (failure?.kind === 'timeout')
-                return reject(new Error(`executable timed out after ${timeoutMs}ms`));
-            if (failure?.kind === 'output_limit')
-                return reject(new Error('stdout exceeded the 10 MiB cap'));
-            if (failure?.kind === 'spawn')
-                return reject(new Error(`executable could not be run (${describeError(failure.error)})`));
-            if (failure?.kind === 'cleanup')
-                return reject(new Error(`executable cleanup failed (${describeError(failure.error)})`));
-            resolve({ stdout: Buffer.concat(stdout).toString('utf8'), status, signal });
-        };
-        const terminate = (reason) => {
-            if (failure !== undefined)
-                return;
-            failure = reason;
-            if (timeout !== undefined)
-                clearTimeout(timeout);
-            void terminateProcessGroup(child).then(() => { cleaned = true; finish(); }, (error) => { failure = { kind: 'cleanup', error }; cleaned = true; finish(); });
-        };
-        child.stdout.on('data', (chunk) => {
-            stdoutBytes += chunk.byteLength;
-            if (stdoutBytes > MAX_STDOUT)
-                return terminate({ kind: 'output_limit' });
-            stdout.push(chunk);
-        });
-        child.once('error', (error) => {
-            if (child.pid === undefined) {
-                failure = { kind: 'spawn', error };
-                closed = true;
-                cleaned = true;
-                finish();
-                return;
-            }
-            terminate({ kind: 'spawn', error });
-        });
-        child.once('close', (nextStatus, nextSignal) => {
-            status = nextStatus;
-            signal = nextSignal;
-            closed = true;
-            finish();
-        });
-        timeout = setTimeout(() => terminate({ kind: 'timeout' }), timeoutMs);
-        child.stdin.end(input);
-    });
-}
-function parseEnvelope(stdout) {
-    let value;
-    try {
-        value = JSON.parse(stdout.trim());
-    }
-    catch {
-        throw new Error('stdout was not a single JSON envelope');
-    }
-    if (!isRecord(value) || value['protocolVersion'] !== 1)
-        throw new Error('stdout was not a protocolVersion: 1 envelope');
-    if (value['ok'] === true && exactKeys(value, ['protocolVersion', 'ok']))
-        return { protocolVersion: 1, ok: true };
-    if (value['ok'] !== false || !exactKeys(value, ['protocolVersion', 'ok', 'error']))
-        throw new Error('response envelope had missing or extra fields');
-    const error = value['error'];
-    if (!isRecord(error) || !exactKeys(error, ['code', 'message'], ['next']) || typeof error['code'] !== 'string' || error['code'] === '' || typeof error['message'] !== 'string' || error['message'] === '' || (error['next'] !== undefined && typeof error['next'] !== 'string')) {
-        throw new Error('failure envelope had invalid error fields');
-    }
-    return { protocolVersion: 1, ok: false, error: { code: error['code'], message: error['message'], ...(error['next'] === undefined ? {} : { next: error['next'] }) } };
-}
-function exactKeys(value, required, optional = []) {
-    return required.every((key) => Object.hasOwn(value, key)) && Object.keys(value).every((key) => required.includes(key) || optional.includes(key));
-}
-function label(hook) {
-    return `plugin "${hook.plugin.name}" lifecycle hook "${hook.op}" for ${hook.event}`;
-}
-function attribution(hook) {
-    return `Refused by plugin ${hook.plugin.name}, op ${hook.op}.`;
-}
-function describeError(error) {
-    return error instanceof Error ? error.message : String(error);
-}
+var V=Object.defineProperty;var s=(e,t)=>V(e,"name",{value:t,configurable:!0});import{randomBytes as E}from"node:crypto";import{spawn as _}from"node:child_process";import{PROCESS_GROUP_KILL_GRACE_MS as S,posixProcessGroupSpawnOptions as B,terminateProcessGroup as R}from"../../../hook-process.js";import{isRecord as L}from"../../../shared/predicates.js";import{diag as w}from"../../io.js";import{LIFECYCLE_CATALOG as O}from"../lifecycle-catalog.js";const P=10*1024*1024;async function A(e,t,n){try{const r=await T(e,t,n);r.ok||w(`crtr: ${f(e)} failed: ${r.error.code}: ${r.error.message}`)}catch(r){w(`crtr: ${f(e)} failed: ${p(r)}`)}}s(A,"invokeLifecycleHook");async function X(e,t){if(e.length===0)return;const{hookTimeoutMs:n,eventBudgetMs:r}=O[e[0].event],u=Date.now()+r;for(const o of e){const l=u-Date.now(),a=Math.min(n,l-S);if(a<=0){w(`crtr: lifecycle hook event ${o.event} exceeded its ${r}ms aggregate budget; skipped ${f(o)}`);return}await A(o,t,a)}}s(X,"invokeLifecycleHooks");async function Y(e,t){if(e.length===0)return null;const{hookTimeoutMs:n,eventBudgetMs:r}=O["node:create"],u=Date.now()+r;for(const o of e){const l=u-Date.now(),a=Math.min(n,l-S);if(a<=0)return M(o,`lifecycle hook event node:create exceeded its ${r}ms aggregate budget`);try{const i=await T(o,t,a);if(!i.ok)return{hook:o,message:i.error.message,next:i.error.next??b(o)}}catch(i){return M(o,p(i))}}return null}s(Y,"invokeBlockingLifecycleHooks");function M(e,t){return{hook:e,message:`${f(e)} failed: ${t}`,next:b(e)}}s(M,"refusal");function z(e){return b(e)}s(z,"lifecycleHookAttribution");async function T(e,t,n){const r=e.event==="node:create"?D(e,t):C(e,t),u=await G(e,JSON.stringify(r),n);if(u.signal!==null)throw new Error(`executable was killed by signal ${u.signal}`);const o=H(u.stdout);return o.ok&&u.status!==0&&w(`crtr: ${f(e)} returned ok:true but exited ${u.status} (honoring the envelope)`),o}s(T,"executeLifecycleHook");function C(e,t){return{protocolVersion:1,op:e.op,event:e.event,phase:e.phase,operationId:E(16).toString("hex"),node:t.node,runtime:t.runtime,context:{cwd:t.node.cwd}}}s(C,"nodeRequest");function D(e,t){return{protocolVersion:1,op:e.op,event:"node:create",phase:"before",operationId:E(16).toString("hex"),create:t.create,runtime:t.runtime,context:{cwd:t.create.cwd}}}s(D,"createRequest");async function G(e,t,n){let r;try{r=_(e.executable,["--crtr-hook-protocol","1"],{cwd:e.plugin.root,env:process.env,stdio:["pipe","pipe","inherit"],...B()})}catch(u){throw new Error(`executable could not be run (${p(u)})`)}return new Promise((u,o)=>{let l=0;const a=[];let i,x=!1,m=!1,h=null,k=null,d;const g=s(()=>{if(!(!x||i!==void 0&&!m)){if(d!==void 0&&clearTimeout(d),i?.kind==="timeout")return o(new Error(`executable timed out after ${n}ms`));if(i?.kind==="output_limit")return o(new Error("stdout exceeded the 10 MiB cap"));if(i?.kind==="spawn")return o(new Error(`executable could not be run (${p(i.error)})`));if(i?.kind==="cleanup")return o(new Error(`executable cleanup failed (${p(i.error)})`));u({stdout:Buffer.concat(a).toString("utf8"),status:h,signal:k})}},"finish"),y=s(c=>{i===void 0&&(i=c,d!==void 0&&clearTimeout(d),R(r).then(()=>{m=!0,g()},v=>{i={kind:"cleanup",error:v},m=!0,g()}))},"terminate");r.stdout.on("data",c=>{if(l+=c.byteLength,l>P)return y({kind:"output_limit"});a.push(c)}),r.once("error",c=>{if(r.pid===void 0){i={kind:"spawn",error:c},x=!0,m=!0,g();return}y({kind:"spawn",error:c})}),r.once("close",(c,v)=>{h=c,k=v,x=!0,g()}),d=setTimeout(()=>y({kind:"timeout"}),n),r.stdin.end(t)})}s(G,"runLifecycleProcess");function H(e){let t;try{t=JSON.parse(e.trim())}catch{throw new Error("stdout was not a single JSON envelope")}if(!L(t)||t.protocolVersion!==1)throw new Error("stdout was not a protocolVersion: 1 envelope");if(t.ok===!0&&$(t,["protocolVersion","ok"]))return{protocolVersion:1,ok:!0};if(t.ok!==!1||!$(t,["protocolVersion","ok","error"]))throw new Error("response envelope had missing or extra fields");const n=t.error;if(!L(n)||!$(n,["code","message"],["next"])||typeof n.code!="string"||n.code===""||typeof n.message!="string"||n.message===""||n.next!==void 0&&typeof n.next!="string")throw new Error("failure envelope had invalid error fields");return{protocolVersion:1,ok:!1,error:{code:n.code,message:n.message,...n.next===void 0?{}:{next:n.next}}}}s(H,"parseEnvelope");function $(e,t,n=[]){return t.every(r=>Object.hasOwn(e,r))&&Object.keys(e).every(r=>t.includes(r)||n.includes(r))}s($,"exactKeys");function f(e){return`plugin "${e.plugin.name}" lifecycle hook "${e.op}" for ${e.event}`}s(f,"label");function b(e){return`Refused by plugin ${e.plugin.name}, op ${e.op}.`}s(b,"attribution");function p(e){return e instanceof Error?e.message:String(e)}s(p,"describeError");export{Y as invokeBlockingLifecycleHooks,A as invokeLifecycleHook,X as invokeLifecycleHooks,z as lifecycleHookAttribution};

package/dist/core/command-manifests/manifest.js

@@ -1,324 +1 @@
-// Transport-parameterized command manifest validation and forest materialization.
-//
-// Validates command manifests atomically, materializes self-contained forests
-// independent of nested-mount order when the parent is inline, validates REST
-// mappings, and enforces 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 { validateCommandNode } from './schema.js';
-import { isRecord } from '../../shared/predicates.js';
-// Validation helpers
-const KEBAB = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
-const REST_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
-function typeName(v) {
-    if (v === null)
-        return 'null';
-    if (Array.isArray(v))
-        return 'array';
-    return typeof v;
-}
-// Top-level manifest validation
-/**
- * Validates a HTTP-transport plugin 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 validateCommandManifest(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 (!isRecord(raw)) {
-        issue('command_manifest_invalid', 'manifest must be an object', typeName(raw), options.extensionFragment === true ? '{ schemaVersion, transport, mounts }' : options.transport === 'http' ? '{ schemaVersion, baseUrl?, timeouts?, mounts, helpAddenda? }' : '{ schemaVersion, mounts, helpAddenda? }', 'Provide a valid JSON manifest object.');
-        return { issues };
-    }
-    // Check for unknown top-level keys
-    const topKeys = Object.keys(raw);
-    const allowedTopKeys = options.extensionFragment === true
-        ? new Set(['schemaVersion', 'transport', 'mounts'])
-        : options.transport === 'http'
-            ? new Set(['schemaVersion', 'baseUrl', 'timeouts', 'mounts', 'helpAddenda'])
-            : new Set(['schemaVersion', 'mounts', 'helpAddenda']);
-    const unknownKeys = topKeys.filter((k) => !allowedTopKeys.has(k));
-    if (unknownKeys.length > 0) {
-        issue('command_manifest_invalid', `unknown top-level keys`, unknownKeys.join(', '), options.extensionFragment === true ? 'only: schemaVersion, transport, mounts' : options.transport === 'http' ? 'only: schemaVersion, baseUrl, timeouts, mounts, helpAddenda' : 'only: schemaVersion, mounts, helpAddenda', '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 (options.transport === 'http' && 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 (options.transport === 'http' && raw['timeouts'] !== undefined) {
-        const t = validateTimeouts(raw['timeouts'], issue);
-        if (t === null)
-            return { issues };
-        timeouts = t;
-    }
-    // Validate optional helpAddenda (both transports)
-    let helpAddenda;
-    if (raw['helpAddenda'] !== undefined) {
-        const h = validateHelpAddenda(raw['helpAddenda'], options.coreCommandPaths, issue);
-        if (h === null)
-            return { issues };
-        if (Object.keys(h).length > 0)
-            helpAddenda = h;
-    }
-    // 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, options.transport, issue, options.extensionFragment === true ? { topLevelRootEntry: 'forbidden', allowPassthrough: false, allowExtensible: false } : undefined);
-        if (m === null)
-            return { issues };
-        validatedMounts.push(m);
-    }
-    // Materialize plugin-local trees separately from mounts below an explicitly
-    // extensible core branch. Core mounts remain nodes, never fake plugin roots.
-    const coreMounts = validatedMounts.filter((mount) => mount.parent.length > 0 && options.extensibleCoreBranches?.has(mount.parent[0]) === true);
-    for (const mount of coreMounts) {
-        if (mount.parent.length !== 1) {
-            issue('command_parent_invalid', 'core mount parent must name an extensible core branch directly', mount.parent.join('.'), `one extensible core branch (one of: ${[...(options.extensibleCoreBranches ?? [])].join(', ')})`, `Mount below one of the extensible core branches: ${[...(options.extensibleCoreBranches ?? [])].join(', ')}.`, mount.parent.join('.'));
-            return { issues };
-        }
-        if (options.coreCommandPaths?.has(`${mount.parent[0]} ${mount.node.name}`) === true) {
-            issue('command_collision', `contributed command "${mount.node.name}" conflicts with a child the extensible core branch already owns`, mount.node.name, `a name not already owned by the ${mount.parent[0]} core branch`, 'Rename the contributed command or remove this mount.', `${mount.parent.join('.')}.${mount.node.name}`);
-            return { issues };
-        }
-    }
-    const roots = materializeForest(validatedMounts.filter((mount) => !coreMounts.includes(mount)), options.reservedCoreNames, options.extensibleCoreBranches, 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 } : {}),
-                ...(helpAddenda !== undefined ? { helpAddenda } : {}),
-                roots,
-                coreMounts,
-            },
-            issues: [],
-        };
-    }
-    // Any issue found -> zero contributions
-    return { issues };
-}
-// Timeouts validation
-function validateTimeouts(raw, issue) {
-    if (!isRecord(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;
-}
-// Help addenda validation
-/** Validate the optional top-level `helpAddenda` map: core command path →
- *  addendum text rendered as an attributed block beneath that core command's
- *  help. When the caller supplies the core command path set, a key naming no
- *  existing core path is rejected outright — a typo fails at the gate, never
- *  silently at render. */
-function validateHelpAddenda(raw, coreCommandPaths, issue) {
-    if (!isRecord(raw)) {
-        issue('command_manifest_invalid', 'helpAddenda must be an object', typeName(raw), 'a map of core command path → addendum text', 'Fix helpAddenda.', 'helpAddenda');
-        return null;
-    }
-    const out = {};
-    for (const [key, value] of Object.entries(raw)) {
-        if (key.split(' ').some((t) => !KEBAB.test(t))) {
-            issue('command_help_addendum_invalid', 'helpAddenda key must be a space-separated core command path', key, 'kebab tokens separated by single spaces (e.g. "cron" or "cron add")', 'Fix the helpAddenda key.', `helpAddenda.${key}`);
-            return null;
-        }
-        if (typeof value !== 'string' || value.length === 0) {
-            issue('command_manifest_invalid', 'helpAddenda value must be a non-empty string', typeof value === 'string' ? 'empty string' : typeName(value), 'non-empty addendum text', 'Fix the helpAddenda value.', `helpAddenda.${key}`);
-            return null;
-        }
-        if (coreCommandPaths !== undefined && !coreCommandPaths.has(key)) {
-            issue('command_help_addendum_invalid', 'helpAddenda key names no crtr core command path', key, 'an existing core command path (e.g. "cron", "cron add")', 'Fix the key or remove the addendum.', `helpAddenda.${key}`);
-            return null;
-        }
-        out[key] = value;
-    }
-    return out;
-}
-function validateMount(raw, index, transport, issue, nodeOptions) {
-    const path = `mounts[${index}]`;
-    if (!isRecord(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 = validateCommandNode(nodeRaw, [`${path}.node`], topLevel, transport, issue, nodeOptions);
-    if (node === null)
-        return null;
-    return { parent, node };
-}
-// Forest materialization (order-independent)
-/**
- * Materializes a flat list of mounts into a forest of top-level branches,
- * resolving nested mounts whose parent exists in a top-level inline tree regardless of order. Nested mounts that provide another nested mount's parent must appear first. Validates self-containment and no duplicates.
- */
-function materializeForest(mounts, reservedCoreNames, extensibleCoreBranches, 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_collision', `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) => m.node.kind === 'branch'
-        ? { ...m.node, children: [...m.node.children] }
-        : { ...m.node });
-    for (const mount of nested) {
-        if (reservedCoreNames.has(mount.parent[0])) {
-            issue('command_parent_invalid', 'parent path starts with a core branch that is not extensible', mount.parent[0], `an extensible core branch (one of: ${[...(extensibleCoreBranches ?? [])].join(', ')})`, `Mount below one of the extensible core branches: ${[...(extensibleCoreBranches ?? [])].join(', ')}.`, mount.parent.join('.'));
-            return null;
-        }
-    }
-    // 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) {
-        if (!indexPaths(root, [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;
-    }
-    if (root.kind === 'leaf') {
-        issue('command_parent_invalid', 'parent path resolves to a leaf', first, 'a branch', 'Change the parent to point to a 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;
-    }
-    // A passthrough owns every token below its path, so nested mounts would make
-    // the materialized branch invalid even though its inline children are empty.
-    if (current.passthrough !== undefined) {
-        issue('command_parent_invalid', 'parent path resolves to a passthrough branch', mount.parent.join('.'), 'a branch without passthrough', 'Remove the nested mount or remove passthrough from its parent branch.', mount.parent.join('.'));
-        return false;
-    }
-    // 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;
-}
+var j=Object.defineProperty;var h=(e,n)=>j(e,"name",{value:n,configurable:!0});import{validateCommandNode as U}from"./schema.js";import{isRecord as y}from"../../shared/predicates.js";const g=/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/,E=new Set(["GET","POST","PUT","PATCH","DELETE"]);function b(e){return e===null?"null":Array.isArray(e)?"array":typeof e}h(b,"typeName");function L(e,n){const a=[],o=h((t,v,k,x,A,_)=>{a.push({code:t,message:v,received:k,expected:x,next:A,..._?{path:_}:{}})},"issue");if(!y(e))return o("command_manifest_invalid","manifest must be an object",b(e),n.extensionFragment===!0?"{ schemaVersion, transport, mounts }":n.transport==="http"?"{ schemaVersion, baseUrl?, timeouts?, mounts, helpAddenda? }":"{ schemaVersion, mounts, helpAddenda? }","Provide a valid JSON manifest object."),{issues:a};const s=Object.keys(e),r=n.extensionFragment===!0?new Set(["schemaVersion","transport","mounts"]):n.transport==="http"?new Set(["schemaVersion","baseUrl","timeouts","mounts","helpAddenda"]):new Set(["schemaVersion","mounts","helpAddenda"]),l=s.filter(t=>!r.has(t));if(l.length>0)return o("command_manifest_invalid","unknown top-level keys",l.join(", "),n.extensionFragment===!0?"only: schemaVersion, transport, mounts":n.transport==="http"?"only: schemaVersion, baseUrl, timeouts, mounts, helpAddenda":"only: schemaVersion, mounts, helpAddenda","Remove the unknown keys."),{issues:a};if(e.schemaVersion!==1)return o("command_schema_version","schemaVersion must be exactly 1",String(e.schemaVersion),"1","Update the manifest schema version to 1.","schemaVersion"),{issues:a};let d;if(n.transport==="http"&&e.baseUrl!==void 0){if(typeof e.baseUrl!="string")return o("command_manifest_invalid","baseUrl must be a string",b(e.baseUrl),"an absolute HTTP(S) URL or omitted","Provide a valid baseUrl or remove it.","baseUrl"),{issues:a};try{const t=new URL(e.baseUrl);if(!["http:","https:"].includes(t.protocol))return o("command_manifest_invalid","baseUrl must be http: or https:",t.protocol,"http: or https:","Use an HTTP(S) URL.","baseUrl"),{issues:a};d=e.baseUrl}catch{return o("command_manifest_invalid","baseUrl must be a valid absolute URL",e.baseUrl,"a valid URL","Fix the baseUrl.","baseUrl"),{issues:a}}}let m;if(n.transport==="http"&&e.timeouts!==void 0){const t=$(e.timeouts,o);if(t===null)return{issues:a};m=t}let i;if(e.helpAddenda!==void 0){const t=M(e.helpAddenda,n.coreCommandPaths,o);if(t===null)return{issues:a};Object.keys(t).length>0&&(i=t)}const c=e.mounts;if(!Array.isArray(c))return o("command_manifest_invalid","mounts must be an array",b(c),"a non-empty array of { parent, node } contributions","Provide at least one mount.","mounts"),{issues:a};if(c.length===0)return o("command_manifest_invalid","mounts must be a non-empty array","empty array","at least one contribution","Add at least one mount.","mounts"),{issues:a};const u=[];for(let t=0;t<c.length;t++){const v=R(c[t],t,n.transport,o,n.extensionFragment===!0?{topLevelRootEntry:"forbidden",allowPassthrough:!1,allowExtensible:!1}:void 0);if(v===null)return{issues:a};u.push(v)}const f=u.filter(t=>t.parent.length>0&&n.extensibleCoreBranches?.has(t.parent[0])===!0);for(const t of f){if(t.parent.length!==1)return o("command_parent_invalid","core mount parent must name an extensible core branch directly",t.parent.join("."),`one extensible core branch (one of: ${[...n.extensibleCoreBranches??[]].join(", ")})`,`Mount below one of the extensible core branches: ${[...n.extensibleCoreBranches??[]].join(", ")}.`,t.parent.join(".")),{issues:a};if(n.coreCommandPaths?.has(`${t.parent[0]} ${t.node.name}`)===!0)return o("command_collision",`contributed command "${t.node.name}" conflicts with a child the extensible core branch already owns`,t.node.name,`a name not already owned by the ${t.parent[0]} core branch`,"Rename the contributed command or remove this mount.",`${t.parent.join(".")}.${t.node.name}`),{issues:a}}const p=F(u.filter(t=>!f.includes(t)),n.reservedCoreNames,n.extensibleCoreBranches,o);return p===null?{issues:a}:a.length===0?{manifest:{schemaVersion:1,...d!==void 0?{baseUrl:d}:{},...m!==void 0?{timeouts:m}:{},...i!==void 0?{helpAddenda:i}:{},roots:p,coreMounts:f},issues:[]}:{issues:a}}h(L,"validateCommandManifest");function $(e,n){if(!y(e))return n("command_manifest_invalid","timeouts must be an object",b(e),"{ connectMs?, requestMs?, streamIdleMs? }","Fix timeouts.","timeouts"),null;const a=new Set(["connectMs","requestMs","streamIdleMs"]),o=Object.keys(e).filter(r=>!a.has(r));if(o.length>0)return n("command_manifest_invalid","unknown timeouts keys",o.join(", "),"only: connectMs, requestMs, streamIdleMs","Remove the unknown keys.","timeouts"),null;const s={};for(const r of["connectMs","requestMs","streamIdleMs"])if(e[r]!==void 0){if(typeof e[r]!="number"||!Number.isInteger(e[r])||e[r]<=0)return n("command_manifest_invalid",`${r} must be a positive integer`,String(e[r]),"a positive integer",`Fix ${r}.`,`timeouts.${r}`),null;s[r]=e[r]}return s}h($,"validateTimeouts");function M(e,n,a){if(!y(e))return a("command_manifest_invalid","helpAddenda must be an object",b(e),"a map of core command path \u2192 addendum text","Fix helpAddenda.","helpAddenda"),null;const o={};for(const[s,r]of Object.entries(e)){if(s.split(" ").some(l=>!g.test(l)))return a("command_help_addendum_invalid","helpAddenda key must be a space-separated core command path",s,'kebab tokens separated by single spaces (e.g. "cron" or "cron add")',"Fix the helpAddenda key.",`helpAddenda.${s}`),null;if(typeof r!="string"||r.length===0)return a("command_manifest_invalid","helpAddenda value must be a non-empty string",typeof r=="string"?"empty string":b(r),"non-empty addendum text","Fix the helpAddenda value.",`helpAddenda.${s}`),null;if(n!==void 0&&!n.has(s))return a("command_help_addendum_invalid","helpAddenda key names no crtr core command path",s,'an existing core command path (e.g. "cron", "cron add")',"Fix the key or remove the addendum.",`helpAddenda.${s}`),null;o[s]=r}return o}h(M,"validateHelpAddenda");function R(e,n,a,o,s){const r=`mounts[${n}]`;if(!y(e))return o("command_manifest_invalid","mount must be an object",b(e),"{ parent, node }","Fix the mount.",r),null;const l=new Set(["parent","node"]),d=Object.keys(e).filter(p=>!l.has(p));if(d.length>0)return o("command_manifest_invalid","unknown mount keys",d.join(", "),"only: parent, node","Remove the unknown keys.",r),null;const m=e.parent;if(!Array.isArray(m))return o("command_manifest_invalid","mount parent must be an array",b(m),"an array of kebab tokens, or [] for a top-level mount","Fix parent.",`${r}.parent`),null;for(let p=0;p<m.length;p++){const t=m[p];if(typeof t!="string"||!g.test(t))return o("command_manifest_invalid","parent token must be a kebab token",String(t),"a kebab-case identifier","Fix the parent path.",`${r}.parent[${p}]`),null}const i=m,c=e.node,u=i.length===0,f=U(c,[`${r}.node`],u,a,o,s);return f===null?null:{parent:i,node:f}}h(R,"validateMount");function F(e,n,a,o){const s=e.filter(i=>i.parent.length===0),r=e.filter(i=>i.parent.length>0);for(const i of s)if(n.has(i.node.name))return o("command_collision","node name conflicts with a crtr core command",i.node.name,`a name not in core (not one of: ${[...n].join(", ")})`,"Rename the node or remove this mount.",`${i.node.name}`),null;const l=s.map(i=>i.node.kind==="branch"?{...i.node,children:[...i.node.children]}:{...i.node});for(const i of r)if(n.has(i.parent[0]))return o("command_parent_invalid","parent path starts with a core branch that is not extensible",i.parent[0],`an extensible core branch (one of: ${[...a??[]].join(", ")})`,`Mount below one of the extensible core branches: ${[...a??[]].join(", ")}.`,i.parent.join(".")),null;for(const i of r)if(!S(l,i,o))return null;const d=new Set,m=h((i,c)=>{const u=c.join(".");return d.has(u)?(o("command_node_invalid","duplicate node path",u,"unique paths within the manifest","Remove the duplicate node.",u),!1):(d.add(u),i.kind==="branch"?i.children.every(f=>m(f,[...c,f.name])):!0)},"indexPaths");for(const i of l)if(!m(i,[i.name]))return null;return l}h(F,"materializeForest");function S(e,n,a){const[o,...s]=n.parent,r=e.find(d=>d.name===o);if(!r)return a("command_parent_invalid","parent path starts with unknown branch",o,"a branch this manifest contributes","Fix the parent path or add the parent branch.",n.parent.join(".")),!1;if(r.kind==="leaf")return a("command_parent_invalid","parent path resolves to a leaf",o,"a branch","Change the parent to point to a branch.",n.parent.join(".")),!1;let l=r;for(const d of s){const m=l.children.find(i=>i.name===d);if(!m)return a("command_parent_invalid","parent path contains unknown branch",d,"a branch this manifest contributes","Fix the parent path or add the intermediate branch.",n.parent.join(".")),!1;if(m.kind==="leaf")return a("command_parent_invalid","parent path resolves to a leaf",d,"a branch","Change the parent to point to a branch.",n.parent.join(".")),!1;l=m}return l.passthrough!==void 0?(a("command_parent_invalid","parent path resolves to a passthrough branch",n.parent.join("."),"a branch without passthrough","Remove the nested mount or remove passthrough from its parent branch.",n.parent.join(".")),!1):l.children.some(d=>d.name===n.node.name)?(a("command_node_invalid","duplicate child name",n.node.name,"unique child names within a branch","Rename the node or remove the duplicate.",`${n.parent.join(".")}.${n.node.name}`),!1):(l.children.push(n.node),!0)}h(S,"resolveAndAttachMount");export{L as validateCommandManifest};