@north-light/crouter 0.3.318 → 0.3.320

package/dist/hook-authoring.js

@@ -1,447 +1,5 @@
-import { spawn } from 'node:child_process';
-import { Console } from 'node:console';
-import { posixProcessGroupSpawnOptions, terminateProcessGroup } from './hook-process.js';
-export function hookError(code, message, details = {}) {
-    return { protocolVersion: 1, ok: false, error: { code, message, ...details } };
-}
-export async function runHookExecutable(handlers, options = {}) {
-    const stdin = options.stdin ?? process.stdin;
-    const stdout = options.stdout ?? process.stdout;
-    const stderr = options.stderr ?? process.stderr;
-    let response;
-    try {
-        const raw = await readStream(stdin);
-        let value;
-        try {
-            value = JSON.parse(raw);
-        }
-        catch {
-            response = hookError('invalid_hook_request', 'stdin must contain one JSON hook request');
-            writeResponse(stdout, response);
-            return;
-        }
-        const request = validateRequest(value);
-        if (!request.valid) {
-            response = hookError('invalid_hook_request', request.message);
-            writeResponse(stdout, response);
-            return;
-        }
-        const handler = handlers[request.value.op];
-        if (handler === undefined) {
-            response = hookError('unsupported_hook_op', `no handler is registered for ${request.value.op}`);
-            writeResponse(stdout, response);
-            return;
-        }
-        try {
-            response = await withConsoleStdoutOnStderr(stderr, () => handler(request.value));
-        }
-        catch (error) {
-            stderr.write(`hook handler ${request.value.op} failed: ${describeError(error)}\n`);
-            response = hookError('hook_handler_failed', `handler failed for ${request.value.op}`);
-        }
-        const validated = validateResponse(response, request.value);
-        if (!validated.valid) {
-            stderr.write(`hook handler ${request.value.op} returned an invalid response: ${validated.message}\n`);
-            response = hookError('invalid_hook_response', validated.message);
-        }
-    }
-    catch (error) {
-        stderr.write(`hook executable failed: ${describeError(error)}\n`);
-        response = hookError('hook_executable_failed', 'hook executable could not read its request');
-    }
-    writeResponse(stdout, response);
-}
-export async function runLocalHookProcess(argv, options) {
-    const executable = argv[0];
-    if (executable === undefined || executable === '') {
-        return hookError('local_process_invalid', 'local process argv[0] must not be empty');
-    }
-    if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
-        return hookError('local_process_invalid_options', 'timeoutMs must be greater than zero');
-    }
-    return new Promise((resolve) => {
-        let settled = false;
-        let timedOut = false;
-        let closed = false;
-        let cleanupComplete = false;
-        let timeout;
-        const stdout = [];
-        const settle = (result) => {
-            if (settled)
-                return;
-            settled = true;
-            if (timeout !== undefined)
-                clearTimeout(timeout);
-            resolve(result);
-        };
-        let child;
-        try {
-            child = spawn(executable, argv.slice(1), {
-                cwd: options.cwd,
-                env: options.env,
-                shell: false,
-                stdio: [options.input === undefined ? 'ignore' : 'pipe', 'pipe', 'inherit'],
-                ...posixProcessGroupSpawnOptions(),
-            });
-        }
-        catch (error) {
-            settle(hookError('local_process_spawn_failed', `could not start ${executable}: ${describeError(error)}`));
-            return;
-        }
-        const settleTimeout = () => {
-            if (timedOut && closed && cleanupComplete) {
-                settle(hookError('local_process_timeout', `${executable} did not finish within ${options.timeoutMs}ms`));
-            }
-        };
-        timeout = setTimeout(() => {
-            timedOut = true;
-            void terminateProcessGroup(child).then(() => {
-                cleanupComplete = true;
-                settleTimeout();
-            }, (error) => {
-                cleanupComplete = true;
-                settle(hookError('local_process_cleanup_failed', `could not stop ${executable}: ${describeError(error)}`));
-            });
-        }, options.timeoutMs);
-        child.stdout.on('data', (chunk) => stdout.push(chunk));
-        child.once('error', (error) => {
-            if (child.pid !== undefined)
-                return;
-            settle(hookError('local_process_spawn_failed', `could not start ${executable}: ${describeError(error)}`));
-        });
-        child.once('close', (code, signal) => {
-            closed = true;
-            if (timedOut) {
-                settleTimeout();
-                return;
-            }
-            if (code === 0) {
-                settle({ ok: true, stdout: Buffer.concat(stdout).toString('utf8') });
-                return;
-            }
-            const status = signal === null ? `exit code ${code ?? 'unknown'}` : `signal ${signal}`;
-            settle(hookError('local_process_failed', `${executable} exited with ${status}`));
-        });
-        if (options.input !== undefined && child.stdin !== null) {
-            child.stdin.end(options.input);
-        }
-    });
-}
-export async function forwardHook(endpoint, request, options) {
-    if (!Number.isFinite(options.timeoutMs) || options.timeoutMs <= 0) {
-        return hookError('hook_forward_invalid_options', 'timeoutMs must be greater than zero');
-    }
-    if (!Number.isSafeInteger(options.maxResponseBytes) || options.maxResponseBytes <= 0) {
-        return hookError('hook_forward_invalid_options', 'maxResponseBytes must be a positive integer');
-    }
-    const headers = new Headers(options.headers);
-    if (!headers.has('content-type'))
-        headers.set('content-type', 'application/json');
-    if (options.bearer !== undefined)
-        headers.set('authorization', `Bearer ${options.bearer}`);
-    const controller = new AbortController();
-    let timedOut = false;
-    const timeout = setTimeout(() => {
-        timedOut = true;
-        controller.abort();
-    }, options.timeoutMs);
-    try {
-        const response = await fetch(endpoint, {
-            method: 'POST',
-            headers,
-            body: JSON.stringify(request),
-            signal: controller.signal,
-        });
-        const body = await readResponseBody(response, options.maxResponseBytes);
-        let value;
-        try {
-            value = JSON.parse(body);
-        }
-        catch {
-            return hookError('hook_forward_invalid_response', `hook endpoint returned invalid JSON (HTTP ${response.status})`);
-        }
-        // A valid protocol envelope is authoritative regardless of HTTP status.
-        const validated = validateResponse(value, request);
-        if (!validated.valid)
-            return hookError('hook_forward_invalid_response', `${validated.message} (HTTP ${response.status})`);
-        return validated.value;
-    }
-    catch (error) {
-        if (timedOut)
-            return hookError('hook_forward_timeout', `hook endpoint did not respond within ${options.timeoutMs}ms`);
-        if (error instanceof ResponseTooLargeError) {
-            return hookError('hook_forward_response_too_large', `hook endpoint exceeded ${options.maxResponseBytes} response bytes`);
-        }
-        return hookError('hook_forward_failed', `hook endpoint request failed: ${describeError(error)}`);
-    }
-    finally {
-        clearTimeout(timeout);
-    }
-}
-const STDOUT_CONSOLE_METHODS = ['log', 'info', 'debug', 'dir', 'table', 'group', 'groupCollapsed'];
-async function withConsoleStdoutOnStderr(stderr, run) {
-    const redirected = new Console({ stdout: stderr, stderr, colorMode: false });
-    const original = new Map();
-    for (const method of STDOUT_CONSOLE_METHODS) {
-        original.set(method, console[method]);
-        console[method] = redirected[method].bind(redirected);
-    }
-    try {
-        return await run();
-    }
-    finally {
-        for (const method of STDOUT_CONSOLE_METHODS)
-            console[method] = original.get(method);
-    }
-}
-function writeResponse(stdout, response) {
-    stdout.write(`${JSON.stringify(response)}\n`);
-}
-async function readStream(stream) {
-    const chunks = [];
-    for await (const chunk of stream)
-        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-    return Buffer.concat(chunks).toString('utf8');
-}
-async function readResponseBody(response, maxBytes) {
-    if (response.body === null)
-        return '';
-    const reader = response.body.getReader();
-    const chunks = [];
-    let total = 0;
-    try {
-        for (;;) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            total += value.byteLength;
-            if (total > maxBytes) {
-                await reader.cancel();
-                throw new ResponseTooLargeError();
-            }
-            chunks.push(value);
-        }
-    }
-    finally {
-        reader.releaseLock();
-    }
-    return new TextDecoder().decode(concatBytes(chunks, total));
-}
-function concatBytes(chunks, total) {
-    const result = new Uint8Array(total);
-    let offset = 0;
-    for (const chunk of chunks) {
-        result.set(chunk, offset);
-        offset += chunk.byteLength;
-    }
-    return result;
-}
-function validateRequest(value) {
-    if (!isRecord(value))
-        return invalid('request must be an object');
-    if (value['protocolVersion'] !== 1)
-        return invalid('unsupported hook protocol version');
-    if (typeof value['op'] !== 'string' || value['op'] === '')
-        return invalid('op must be a non-empty string');
-    if (typeof value['operationId'] !== 'string' || !/^[0-9a-f]{32}$/.test(value['operationId'])) {
-        return invalid('operationId must be a 32-character lowercase hexadecimal string');
-    }
-    if (value['event'] === 'node:create') {
-        if (!hasOnlyKeys(value, ['protocolVersion', 'op', 'event', 'phase', 'operationId', 'create', 'runtime', 'context']))
-            return invalid('node:create request contains unknown fields');
-        if (value['phase'] !== 'before')
-            return invalid('node:create phase must be before');
-        if (!isNodeCreate(value['create']))
-            return invalid('node:create request create contains invalid fields');
-        if (!isCreateRuntime(value['runtime']))
-            return invalid('node:create request runtime contains invalid fields');
-        if (!isLifecycleContext(value['context']))
-            return invalid('node:create request context must contain cwd');
-        return valid({
-            protocolVersion: 1,
-            op: value['op'],
-            event: 'node:create',
-            phase: 'before',
-            operationId: value['operationId'],
-            create: value['create'],
-            runtime: value['runtime'],
-            context: value['context'],
-        });
-    }
-    if (value['phase'] === 'on') {
-        if (!hasOnlyKeys(value, ['protocolVersion', 'op', 'event', 'phase', 'operationId', 'node', 'runtime', 'context']))
-            return invalid('lifecycle request contains unknown fields');
-        if (value['event'] !== 'node:start' && value['event'] !== 'node:close')
-            return invalid('unsupported lifecycle event');
-        if (!isLifecycleNode(value['node']))
-            return invalid('lifecycle request node contains invalid fields');
-        if (!isLifecycleRuntime(value['runtime']))
-            return invalid('lifecycle request runtime contains invalid fields');
-        if (!isLifecycleContext(value['context']))
-            return invalid('lifecycle request context must contain cwd');
-        return valid({
-            protocolVersion: 1,
-            op: value['op'],
-            event: value['event'],
-            phase: 'on',
-            operationId: value['operationId'],
-            node: value['node'],
-            runtime: value['runtime'],
-            context: value['context'],
-        });
-    }
-    if (!hasOnlyKeys(value, ['protocolVersion', 'op', 'phase', 'command', 'operationId', 'input', 'context', 'result'])) {
-        return invalid('request contains unknown fields');
-    }
-    if (!isStringArray(value['command']) || value['command'].length === 0)
-        return invalid('command must be a non-empty string array');
-    if (!isRecord(value['input']) || !isJson(value['input']))
-        return invalid('input must be a JSON object');
-    if (!isContext(value['context']))
-        return invalid('context must contain cwd and providedParams');
-    if (value['phase'] === 'after') {
-        if (!Object.hasOwn(value, 'result') || !isJson(value['result']))
-            return invalid('after requests require a JSON result');
-        return valid({
-            protocolVersion: 1,
-            op: value['op'],
-            phase: 'after',
-            command: value['command'],
-            operationId: value['operationId'],
-            input: value['input'],
-            context: value['context'],
-            result: value['result'],
-        });
-    }
-    if (value['phase'] !== 'before' && value['phase'] !== 'replace')
-        return invalid('phase must be before, after, or replace');
-    if (Object.hasOwn(value, 'result'))
-        return invalid('only after requests may contain result');
-    if (value['phase'] === 'before') {
-        return valid({
-            protocolVersion: 1,
-            op: value['op'],
-            phase: 'before',
-            command: value['command'],
-            operationId: value['operationId'],
-            input: value['input'],
-            context: value['context'],
-        });
-    }
-    return valid({
-        protocolVersion: 1,
-        op: value['op'],
-        phase: 'replace',
-        command: value['command'],
-        operationId: value['operationId'],
-        input: value['input'],
-        context: value['context'],
-    });
-}
-function validateResponse(value, request) {
-    if (!isRecord(value))
-        return invalid('response must be an object');
-    if (value['protocolVersion'] !== 1)
-        return invalid('response has an unsupported hook protocol version');
-    if (value['ok'] === true) {
-        if (!hasOnlyKeys(value, ['protocolVersion', 'ok', 'result']))
-            return invalid('successful response contains unknown fields');
-        const hasResult = Object.hasOwn(value, 'result');
-        if (request.phase === 'replace' && !hasResult)
-            return invalid('replace response requires result');
-        if (request.phase !== 'replace' && hasResult)
-            return invalid('only replace responses may contain result');
-        if (hasResult) {
-            const result = value['result'];
-            if (!isJson(result))
-                return invalid('response result must be JSON');
-            return valid({ protocolVersion: 1, ok: true, result });
-        }
-        return valid({ protocolVersion: 1, ok: true });
-    }
-    if (value['ok'] !== false || !hasOnlyKeys(value, ['protocolVersion', 'ok', 'error'])) {
-        return invalid('response must contain protocolVersion, ok, and error or result');
-    }
-    if (!isHookError(value['error']))
-        return invalid('response error must contain code and message strings');
-    return valid({ protocolVersion: 1, ok: false, error: value['error'] });
-}
-function isContext(value) {
-    return isRecord(value)
-        && hasOnlyKeys(value, ['cwd', 'providedParams'])
-        && typeof value['cwd'] === 'string'
-        && isStringArray(value['providedParams']);
-}
-function isLifecycleContext(value) {
-    return isRecord(value) && hasOnlyKeys(value, ['cwd']) && typeof value['cwd'] === 'string';
-}
-function isNodeCreate(value) {
-    return isRecord(value)
-        && hasOnlyKeys(value, ['kind', 'mode', 'cwd', 'profile', 'root', 'parentId', 'requestingNodeId', 'lifecycle', 'replaces'])
-        && typeof value['kind'] === 'string'
-        && typeof value['mode'] === 'string'
-        && typeof value['cwd'] === 'string'
-        && (typeof value['profile'] === 'string' || value['profile'] === null)
-        && typeof value['root'] === 'boolean'
-        && (typeof value['parentId'] === 'string' || value['parentId'] === null)
-        && (typeof value['requestingNodeId'] === 'string' || value['requestingNodeId'] === null)
-        && (value['lifecycle'] === 'resident' || value['lifecycle'] === 'terminal')
-        && (typeof value['replaces'] === 'string' || value['replaces'] === null);
-}
-function isCreateRuntime(value) {
-    return isRecord(value)
-        && hasOnlyKeys(value, ['canvasHome', 'profile'])
-        && typeof value['canvasHome'] === 'string'
-        && (typeof value['profile'] === 'string' || value['profile'] === null);
-}
-function isLifecycleNode(value) {
-    return isRecord(value)
-        && hasOnlyKeys(value, ['id', 'name', 'kind', 'mode', 'lifecycle', 'cwd', 'nodeDir', 'contextDir', 'jobDir', 'reportsDir'])
-        && ['id', 'name', 'kind', 'mode', 'lifecycle', 'cwd', 'nodeDir', 'contextDir', 'jobDir', 'reportsDir'].every((field) => typeof value[field] === 'string');
-}
-function isLifecycleRuntime(value) {
-    return isRecord(value)
-        && hasOnlyKeys(value, ['isBirth', 'canvasHome', 'profile'])
-        && typeof value['isBirth'] === 'boolean'
-        && typeof value['canvasHome'] === 'string'
-        && (typeof value['profile'] === 'string' || value['profile'] === null);
-}
-function isHookError(value) {
-    return isRecord(value)
-        && hasOnlyKeys(value, ['code', 'message', 'field', 'next'])
-        && typeof value['code'] === 'string'
-        && value['code'] !== ''
-        && typeof value['message'] === 'string'
-        && value['message'] !== ''
-        && (value['field'] === undefined || typeof value['field'] === 'string')
-        && (value['next'] === undefined || typeof value['next'] === 'string');
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function isStringArray(value) {
-    return Array.isArray(value) && value.every((item) => typeof item === 'string');
-}
-function isJson(value) {
-    if (value === null || typeof value === 'boolean' || typeof value === 'string')
-        return true;
-    if (typeof value === 'number')
-        return Number.isFinite(value);
-    if (Array.isArray(value))
-        return value.every(isJson);
-    return isRecord(value) && Object.values(value).every(isJson);
-}
-function hasOnlyKeys(value, keys) {
-    return Object.keys(value).every((key) => keys.includes(key));
-}
-function valid(value) {
-    return { valid: true, value };
-}
-function invalid(message) {
-    return { valid: false, message };
-}
-function describeError(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-class ResponseTooLargeError extends Error {
-}
+var B=Object.defineProperty;var o=(e,r)=>B(e,"name",{value:r,configurable:!0});import{spawn as R}from"node:child_process";import{Console as T}from"node:console";import{posixProcessGroupSpawnOptions as M,terminateProcessGroup as j}from"./hook-process.js";function d(e,r,t={}){return{protocolVersion:1,ok:!1,error:{code:e,message:r,...t}}}o(d,"hookError");async function X(e,r={}){const t=r.stdin??process.stdin,s=r.stdout??process.stdout,i=r.stderr??process.stderr;let c;try{const m=await D(t);let p;try{p=JSON.parse(m)}catch{c=d("invalid_hook_request","stdin must contain one JSON hook request"),_(s,c);return}const f=P(p);if(!f.valid){c=d("invalid_hook_request",f.message),_(s,c);return}const g=e[f.value.op];if(g===void 0){c=d("unsupported_hook_op",`no handler is registered for ${f.value.op}`),_(s,c);return}try{c=await H(i,()=>g(f.value))}catch(h){i.write(`hook handler ${f.value.op} failed: ${b(h)}
+`),c=d("hook_handler_failed",`handler failed for ${f.value.op}`)}const a=I(c,f.value);a.valid||(i.write(`hook handler ${f.value.op} returned an invalid response: ${a.message}
+`),c=d("invalid_hook_response",a.message))}catch(m){i.write(`hook executable failed: ${b(m)}
+`),c=d("hook_executable_failed","hook executable could not read its request")}_(s,c)}o(X,"runHookExecutable");async function Y(e,r){const t=e[0];return t===void 0||t===""?d("local_process_invalid","local process argv[0] must not be empty"):!Number.isFinite(r.timeoutMs)||r.timeoutMs<=0?d("local_process_invalid_options","timeoutMs must be greater than zero"):new Promise(s=>{let i=!1,c=!1,m=!1,p=!1,f;const g=[],a=o(u=>{i||(i=!0,f!==void 0&&clearTimeout(f),s(u))},"settle");let h;try{h=R(t,e.slice(1),{cwd:r.cwd,env:r.env,shell:!1,stdio:[r.input===void 0?"ignore":"pipe","pipe","inherit"],...M()})}catch(u){a(d("local_process_spawn_failed",`could not start ${t}: ${b(u)}`));return}const x=o(()=>{c&&m&&p&&a(d("local_process_timeout",`${t} did not finish within ${r.timeoutMs}ms`))},"settleTimeout");f=setTimeout(()=>{c=!0,j(h).then(()=>{p=!0,x()},u=>{p=!0,a(d("local_process_cleanup_failed",`could not stop ${t}: ${b(u)}`))})},r.timeoutMs),h.stdout.on("data",u=>g.push(u)),h.once("error",u=>{h.pid===void 0&&a(d("local_process_spawn_failed",`could not start ${t}: ${b(u)}`))}),h.once("close",(u,$)=>{if(m=!0,c){x();return}if(u===0){a({ok:!0,stdout:Buffer.concat(g).toString("utf8")});return}const V=$===null?`exit code ${u??"unknown"}`:`signal ${$}`;a(d("local_process_failed",`${t} exited with ${V}`))}),r.input!==void 0&&h.stdin!==null&&h.stdin.end(r.input)})}o(Y,"runLocalHookProcess");async function Z(e,r,t){if(!Number.isFinite(t.timeoutMs)||t.timeoutMs<=0)return d("hook_forward_invalid_options","timeoutMs must be greater than zero");if(!Number.isSafeInteger(t.maxResponseBytes)||t.maxResponseBytes<=0)return d("hook_forward_invalid_options","maxResponseBytes must be a positive integer");const s=new Headers(t.headers);s.has("content-type")||s.set("content-type","application/json"),t.bearer!==void 0&&s.set("authorization",`Bearer ${t.bearer}`);const i=new AbortController;let c=!1;const m=setTimeout(()=>{c=!0,i.abort()},t.timeoutMs);try{const p=await fetch(e,{method:"POST",headers:s,body:JSON.stringify(r),signal:i.signal}),f=await C(p,t.maxResponseBytes);let g;try{g=JSON.parse(f)}catch{return d("hook_forward_invalid_response",`hook endpoint returned invalid JSON (HTTP ${p.status})`)}const a=I(g,r);return a.valid?a.value:d("hook_forward_invalid_response",`${a.message} (HTTP ${p.status})`)}catch(p){return c?d("hook_forward_timeout",`hook endpoint did not respond within ${t.timeoutMs}ms`):p instanceof N?d("hook_forward_response_too_large",`hook endpoint exceeded ${t.maxResponseBytes} response bytes`):d("hook_forward_failed",`hook endpoint request failed: ${b(p)}`)}finally{clearTimeout(m)}}o(Z,"forwardHook");const O=["log","info","debug","dir","table","group","groupCollapsed"];async function H(e,r){const t=new T({stdout:e,stderr:e,colorMode:!1}),s=new Map;for(const i of O)s.set(i,console[i]),console[i]=t[i].bind(t);try{return await r()}finally{for(const i of O)console[i]=s.get(i)}}o(H,"withConsoleStdoutOnStderr");function _(e,r){e.write(`${JSON.stringify(r)}
+`)}o(_,"writeResponse");async function D(e){const r=[];for await(const t of e)r.push(Buffer.isBuffer(t)?t:Buffer.from(t));return Buffer.concat(r).toString("utf8")}o(D,"readStream");async function C(e,r){if(e.body===null)return"";const t=e.body.getReader(),s=[];let i=0;try{for(;;){const{done:c,value:m}=await t.read();if(c)break;if(i+=m.byteLength,i>r)throw await t.cancel(),new N;s.push(m)}}finally{t.releaseLock()}return new TextDecoder().decode(J(s,i))}o(C,"readResponseBody");function J(e,r){const t=new Uint8Array(r);let s=0;for(const i of e)t.set(i,s),s+=i.byteLength;return t}o(J,"concatBytes");function P(e){return y(e)?e.protocolVersion!==1?n("unsupported hook protocol version"):typeof e.op!="string"||e.op===""?n("op must be a non-empty string"):typeof e.operationId!="string"||!/^[0-9a-f]{32}$/.test(e.operationId)?n("operationId must be a 32-character lowercase hexadecimal string"):e.event==="node:create"?l(e,["protocolVersion","op","event","phase","operationId","create","runtime","context"])?e.phase!=="before"?n("node:create phase must be before"):E(e.create)?L(e.runtime)?q(e.context)?w({protocolVersion:1,op:e.op,event:"node:create",phase:"before",operationId:e.operationId,create:e.create,runtime:e.runtime,context:e.context}):n("node:create request context must contain cwd"):n("node:create request runtime contains invalid fields"):n("node:create request create contains invalid fields"):n("node:create request contains unknown fields"):e.phase==="on"?l(e,["protocolVersion","op","event","phase","operationId","node","runtime","context"])?e.event!=="node:start"&&e.event!=="node:close"?n("unsupported lifecycle event"):z(e.node)?F(e.runtime)?q(e.context)?w({protocolVersion:1,op:e.op,event:e.event,phase:"on",operationId:e.operationId,node:e.node,runtime:e.runtime,context:e.context}):n("lifecycle request context must contain cwd"):n("lifecycle request runtime contains invalid fields"):n("lifecycle request node contains invalid fields"):n("lifecycle request contains unknown fields"):l(e,["protocolVersion","op","phase","command","operationId","input","context","result"])?!S(e.command)||e.command.length===0?n("command must be a non-empty string array"):!y(e.input)||!k(e.input)?n("input must be a JSON object"):A(e.context)?e.phase==="after"?!Object.hasOwn(e,"result")||!k(e.result)?n("after requests require a JSON result"):w({protocolVersion:1,op:e.op,phase:"after",command:e.command,operationId:e.operationId,input:e.input,context:e.context,result:e.result}):e.phase!=="before"&&e.phase!=="replace"?n("phase must be before, after, or replace"):Object.hasOwn(e,"result")?n("only after requests may contain result"):e.phase==="before"?w({protocolVersion:1,op:e.op,phase:"before",command:e.command,operationId:e.operationId,input:e.input,context:e.context}):w({protocolVersion:1,op:e.op,phase:"replace",command:e.command,operationId:e.operationId,input:e.input,context:e.context}):n("context must contain cwd and providedParams"):n("request contains unknown fields"):n("request must be an object")}o(P,"validateRequest");function I(e,r){if(!y(e))return n("response must be an object");if(e.protocolVersion!==1)return n("response has an unsupported hook protocol version");if(e.ok===!0){if(!l(e,["protocolVersion","ok","result"]))return n("successful response contains unknown fields");const t=Object.hasOwn(e,"result");if(r.phase==="replace"&&!t)return n("replace response requires result");if(r.phase!=="replace"&&t)return n("only replace responses may contain result");if(t){const s=e.result;return k(s)?w({protocolVersion:1,ok:!0,result:s}):n("response result must be JSON")}return w({protocolVersion:1,ok:!0})}return e.ok!==!1||!l(e,["protocolVersion","ok","error"])?n("response must contain protocolVersion, ok, and error or result"):G(e.error)?w({protocolVersion:1,ok:!1,error:e.error}):n("response error must contain code and message strings")}o(I,"validateResponse");function A(e){return y(e)&&l(e,["cwd","providedParams"])&&typeof e.cwd=="string"&&S(e.providedParams)}o(A,"isContext");function q(e){return y(e)&&l(e,["cwd"])&&typeof e.cwd=="string"}o(q,"isLifecycleContext");function E(e){return y(e)&&l(e,["kind","mode","cwd","profile","root","parentId","requestingNodeId","lifecycle","replaces"])&&typeof e.kind=="string"&&typeof e.mode=="string"&&typeof e.cwd=="string"&&(typeof e.profile=="string"||e.profile===null)&&typeof e.root=="boolean"&&(typeof e.parentId=="string"||e.parentId===null)&&(typeof e.requestingNodeId=="string"||e.requestingNodeId===null)&&(e.lifecycle==="resident"||e.lifecycle==="terminal")&&(typeof e.replaces=="string"||e.replaces===null)}o(E,"isNodeCreate");function L(e){return y(e)&&l(e,["canvasHome","profile"])&&typeof e.canvasHome=="string"&&(typeof e.profile=="string"||e.profile===null)}o(L,"isCreateRuntime");function z(e){return y(e)&&l(e,["id","name","kind","mode","lifecycle","cwd","nodeDir","contextDir","jobDir","reportsDir"])&&["id","name","kind","mode","lifecycle","cwd","nodeDir","contextDir","jobDir","reportsDir"].every(r=>typeof e[r]=="string")}o(z,"isLifecycleNode");function F(e){return y(e)&&l(e,["isBirth","canvasHome","profile"])&&typeof e.isBirth=="boolean"&&typeof e.canvasHome=="string"&&(typeof e.profile=="string"||e.profile===null)}o(F,"isLifecycleRuntime");function G(e){return y(e)&&l(e,["code","message","field","next"])&&typeof e.code=="string"&&e.code!==""&&typeof e.message=="string"&&e.message!==""&&(e.field===void 0||typeof e.field=="string")&&(e.next===void 0||typeof e.next=="string")}o(G,"isHookError");function y(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}o(y,"isRecord");function S(e){return Array.isArray(e)&&e.every(r=>typeof r=="string")}o(S,"isStringArray");function k(e){return e===null||typeof e=="boolean"||typeof e=="string"?!0:typeof e=="number"?Number.isFinite(e):Array.isArray(e)?e.every(k):y(e)&&Object.values(e).every(k)}o(k,"isJson");function l(e,r){return Object.keys(e).every(t=>r.includes(t))}o(l,"hasOnlyKeys");function w(e){return{valid:!0,value:e}}o(w,"valid");function n(e){return{valid:!1,message:e}}o(n,"invalid");function b(e){return e instanceof Error?e.message:String(e)}o(b,"describeError");class N extends Error{static{o(this,"ResponseTooLargeError")}}export{Z as forwardHook,d as hookError,X as runHookExecutable,Y as runLocalHookProcess};

package/dist/hook-process.js

@@ -1,34 +1 @@
-export const PROCESS_GROUP_KILL_GRACE_MS = 250;
-export function posixProcessGroupSpawnOptions() {
-    if (process.platform === 'win32') {
-        throw new Error('hook process execution requires POSIX process groups');
-    }
-    return { detached: true };
-}
-/** Signal the isolated group, then unconditionally reap survivors after grace. */
-export async function terminateProcessGroup(child, graceMs = PROCESS_GROUP_KILL_GRACE_MS) {
-    const pid = child.pid;
-    if (pid === undefined)
-        return;
-    signalProcessGroup(pid, 'SIGTERM');
-    await delay(graceMs);
-    signalProcessGroup(pid, 'SIGKILL');
-}
-function signalProcessGroup(pid, signal) {
-    try {
-        process.kill(-pid, signal);
-    }
-    catch (error) {
-        if (!isMissingProcess(error))
-            throw error;
-    }
-}
-function isMissingProcess(error) {
-    return typeof error === 'object'
-        && error !== null
-        && 'code' in error
-        && error.code === 'ESRCH';
-}
-function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
+var s=Object.defineProperty;var t=(o,e)=>s(o,"name",{value:e,configurable:!0});const p=250;function f(){if(process.platform==="win32")throw new Error("hook process execution requires POSIX process groups");return{detached:!0}}t(f,"posixProcessGroupSpawnOptions");async function S(o,e=250){const n=o.pid;n!==void 0&&(r(n,"SIGTERM"),await c(e),r(n,"SIGKILL"))}t(S,"terminateProcessGroup");function r(o,e){try{process.kill(-o,e)}catch(n){if(!i(n))throw n}}t(r,"signalProcessGroup");function i(o){return typeof o=="object"&&o!==null&&"code"in o&&o.code==="ESRCH"}t(i,"isMissingProcess");function c(o){return new Promise(e=>setTimeout(e,o))}t(c,"delay");export{p as PROCESS_GROUP_KILL_GRACE_MS,f as posixProcessGroupSpawnOptions,S as terminateProcessGroup};

package/dist/index.js

@@ -1,52 +1 @@
-// @north-light/crouter — the sanctioned library surface (design D1).
-//
-// This barrel is the ONLY supported way to import crouter as a library; the
-// `exports` map gates off deep subpath imports, so consumers depend on exactly
-// the symbols re-exported here.
-// Everything below is a stable, server-facing surface: runtime control that
-// keeps the canvas-row ⇄ pi-session lockstep guarantees, read-only canvas/
-// telemetry queries, and the broker socket client + wire protocol. Nothing
-// internal (CLI plumbing, helpers) is exported. This module has no load-time
-// side effects and no circular imports — keep it that way.
-// ── Runtime control ──────────────────────────────────────────────────────
-// Sanctioned launchers/mutators. reviveNode is the ONLY sanctioned launcher of
-// the broker engine; every node is broker-hosted (no host_kind choice). Broker
-// launches are daemon-owned (fleet-bound): spawn verbs are NOT exported here —
-// an out-of-process consumer creates nodes through the /v1 client like every
-// other caller (D-9), because an unbound launch throws by design (D-2).
-export { reviveNode } from './core/runtime/revive.js';
-export { closeNode } from './core/runtime/close.js';
-export { enqueueNodeMail } from './core/feed/messages.js';
-// Hidden ambient "current situation" sidecar (see runtime/situational-context.ts) —
-// upsert-only, narrow surface so an external composer (e.g. Hearth) never needs to
-// learn the storage file itself.
-export { appendSituationalContext } from './core/runtime/situational-context.js';
-// In-process extensions use crouter's admitted turn classification rather than
-// attempting to reconstruct origin and route state independently.
-export { isTurnInternal } from './core/runtime/turn-visibility.js';
-// ── Canvas reads ─────────────────────────────────────────────────────────
-export { getNode, listNodes } from './core/canvas/canvas.js';
-export { nodeDir } from './core/canvas/paths.js';
-export { ticketCountsForNodes, ticketsAcrossCanvas } from './core/canvas/attention.js';
-export { readTelemetry, readContextTokens } from './core/canvas/telemetry.js';
-// ── Broker client ────────────────────────────────────────────────────────
-export { BrokerClient, BrokerUnavailableError } from './core/broker-client/index.js';
-// ── Broker wire protocol (codec + frame/protocol types) ──────────────────
-export { encodeFrame, FrameDecoder, FrameOverflowError, CLIENT_READ_CAPS, BROKER_READ_CAPS, } from './core/runtime/broker-protocol.js';
-// ── Utility exports ───────────────────────────────────────────────────────
-// Small side-effect-free helpers consumed by external callers that assemble
-// on top of crtr primitives (e.g. a guest-side process reading crtr's error
-// shape and timestamp convention). Intentionally narrow: only `general` (not
-// `CrtrError`/`notFound`/`usage`/the other error helpers) and `nowIso`.
-export { general } from './core/errors.js';
-export { nowIso } from './core/fs-utils.js';
-// ── Event contract ───────────────────────────────────────────────────────
-// Pure envelope helpers only. Local source binding and canonical append remain
-// internal so package consumers cannot select crouter runtime file paths.
-export { validateOperationId, buildEnvelope, operationIdContext, errorClassCodes, serializeEventRecord, errorClassFromError, } from './core/events/index.js';
-// ── Hook authoring ───────────────────────────────────────────────────────
-export { forwardHook, hookError, runHookExecutable, runLocalHookProcess } from './hook-authoring.js';
-// ── Command-manifest compatibility ───────────────────────────────────────
-export { validateCommandManifest } from './core/command-manifests/manifest.js';
-export { validatePluginBundle } from './core/command-plugins/bundle.js';
-export { SUBTREE_NAMES } from './build-root.js';
+import{reviveNode as e}from"./core/runtime/revive.js";import{closeNode as a}from"./core/runtime/close.js";import{enqueueNodeMail as m}from"./core/feed/messages.js";import{appendSituationalContext as l}from"./core/runtime/situational-context.js";import{isTurnInternal as x}from"./core/runtime/turn-visibility.js";import{getNode as i,listNodes as s}from"./core/canvas/canvas.js";import{nodeDir as C}from"./core/canvas/paths.js";import{ticketCountsForNodes as c,ticketsAcrossCanvas as v}from"./core/canvas/attention.js";import{readTelemetry as N,readContextTokens as A}from"./core/canvas/telemetry.js";import{BrokerClient as B,BrokerUnavailableError as F}from"./core/broker-client/index.js";import{encodeFrame as S,FrameDecoder as T,FrameOverflowError as _,CLIENT_READ_CAPS as D,BROKER_READ_CAPS as P}from"./core/runtime/broker-protocol.js";import{general as g}from"./core/errors.js";import{nowIso as H}from"./core/fs-utils.js";import{validateOperationId as O,buildEnvelope as L,operationIdContext as U,errorClassCodes as h,serializeEventRecord as q,errorClassFromError as y}from"./core/events/index.js";import{forwardHook as K,hookError as j,runHookExecutable as G,runLocalHookProcess as J}from"./hook-authoring.js";import{validateCommandManifest as V}from"./core/command-manifests/manifest.js";import{validatePluginBundle as X}from"./core/command-plugins/bundle.js";import{SUBTREE_NAMES as Z}from"./build-root.js";export{P as BROKER_READ_CAPS,B as BrokerClient,F as BrokerUnavailableError,D as CLIENT_READ_CAPS,T as FrameDecoder,_ as FrameOverflowError,Z as SUBTREE_NAMES,l as appendSituationalContext,L as buildEnvelope,a as closeNode,S as encodeFrame,m as enqueueNodeMail,h as errorClassCodes,y as errorClassFromError,K as forwardHook,g as general,i as getNode,j as hookError,x as isTurnInternal,s as listNodes,C as nodeDir,H as nowIso,U as operationIdContext,A as readContextTokens,N as readTelemetry,e as reviveNode,G as runHookExecutable,J as runLocalHookProcess,q as serializeEventRecord,c as ticketCountsForNodes,v as ticketsAcrossCanvas,V as validateCommandManifest,O as validateOperationId,X as validatePluginBundle};