@north-light/api 0.3.580 → 0.3.588

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

@@ -0,0 +1,315 @@
+import { spawn } from 'node:child_process';
+import { socketFetch } from '../../../api/node-transport.js';
+import { apiSocketPath } from '../../canvas/paths.js';
+import { posixProcessGroupSpawnOptions, terminateProcessGroup } from '../../../hook-process.js';
+import { ExitCode } from '../../../types.js';
+import { isRecord } from '../../../shared/predicates.js';
+import { envExecutionId, envNodeId } from '../../../shared/env.js';
+import { validateDeclaredResult } from '../../../api/command-manifest/result.js';
+import { CrtrError } from '../../errors.js';
+import { diag } from '../../io.js';
+const MAX_STDOUT = 10 * 1024 * 1024;
+export const EXEC_HOOK_TIMEOUT_MS = 15_000;
+const RESERVED_CODES = new Set([
+    'internal',
+    'unknown_path',
+    'command_collision',
+    'command_hook_collision',
+    'plugin_protocol_error',
+    'hook_protocol_error',
+]);
+const SNAKE = /^[a-z][a-z0-9]*(_[a-z0-9]+)*$/;
+const OPERATION_ID = /^[0-9a-f]{32}$/;
+const NEXT = 'Run `crtr pkg plugin show` or `crtr sys doctor` to inspect the plugin.';
+/** Invoke one hook executable; after failures retain the completed primary result. */
+export async function invokeExecHook(spec, invocation) {
+    const cwd = process.cwd();
+    const request = buildRequest(spec, invocation, cwd);
+    const res = await runHookProcess(spec, invocation, JSON.stringify(request), cwd);
+    if (res.signal !== null) {
+        throw protocolError(spec, invocation, `executable was killed by signal ${res.signal}`, 'a clean exit with one JSON envelope on stdout');
+    }
+    const envelope = parseEnvelope(spec, invocation, res.stdout);
+    if (envelope.ok && res.status !== 0) {
+        diag(`crtr: ${label(spec)} returned ok:true but exited ${res.status} (honoring the envelope)`);
+    }
+    else if (!envelope.ok && res.status === 0) {
+        diag(`crtr: ${label(spec)} returned ok:false but exited 0 (honoring the envelope)`);
+    }
+    if (!envelope.ok)
+        throwHookFailure(spec, invocation, envelope);
+    if (spec.phase !== 'replace')
+        return;
+    const result = envelope.result;
+    if (!isRecord(result)) {
+        throw protocolError(spec, invocation, 'replacement success result was not an object', 'result: an object matching the target output declaration');
+    }
+    const output = spec.output;
+    if (output === undefined) {
+        throw protocolError(spec, invocation, 'replacement target output declaration was missing', 'the target leaf output declaration');
+    }
+    const issue = validateDeclaredResult(output, result);
+    if (issue !== null) {
+        const field = output.find((candidate) => candidate.name === issue.field);
+        if (issue.receivedType !== undefined) {
+            throw protocolError(spec, invocation, `replacement output field "${issue.field}" has the wrong type`, `${issue.field}: ${issue.expected ?? field?.type ?? 'unknown'}`);
+        }
+        throw protocolError(spec, invocation, `replacement result is missing required output field "${issue.field}"`, `a "${issue.field}" field of type ${field?.type ?? 'unknown'}`);
+    }
+    return result;
+}
+async function runHookProcess(spec, invocation, input, cwd) {
+    if (process.platform === 'linux') {
+        const nodeId = envNodeId();
+        const executionId = envExecutionId();
+        const socket = process.env['CRTR_API_SOCKET'] ?? apiSocketPath();
+        if (nodeId && !executionId) {
+            throw protocolError(spec, invocation, 'executable requires a current node execution', 'a current node execution');
+        }
+        let response;
+        try {
+            const route = nodeId ? `/v1/nodes/${encodeURIComponent(nodeId)}/hooks/exec` : '/v1/hooks/exec';
+            response = await socketFetch(socket)(`http://localhost${route}`, {
+                method: 'POST', headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ ...(nodeId ? { expected_execution_id: executionId } : {}), hook_id: spec.id, cwd, request: input }),
+            });
+            const value = await response.json();
+            if (!response.ok) {
+                const failure = isRecord(value) && isRecord(value['error']) ? value['error'] : null;
+                const message = failure && typeof failure['message'] === 'string'
+                    ? failure['message'] : `daemon refused hook execution (${response.status})`;
+                if (failure && (failure['code'] === 'hook_timeout' || failure['code'] === 'hook_output_limit')) {
+                    throw new CrtrError(failure['code'], `${label(spec)}: ${message}`, ExitCode.GENERAL, failureDetails(spec, invocation, undefined, NEXT, message));
+                }
+                throw new Error(message);
+            }
+            if (!isRecord(value) || typeof value['stdout'] !== 'string' ||
+                (value['status'] !== null && typeof value['status'] !== 'number') ||
+                (value['signal'] !== null && typeof value['signal'] !== 'string'))
+                throw new Error('invalid hook execution response');
+            return { stdout: value['stdout'], status: value['status'], signal: value['signal'] };
+        }
+        catch (error) {
+            if (error instanceof CrtrError)
+                throw error;
+            throw protocolError(spec, invocation, `executable could not be run (${describeError(error)})`, 'a registered runnable hook executable');
+        }
+    }
+    let child;
+    try {
+        child = spawn(spec.executable, ['--crtr-hook-protocol', '1'], {
+            cwd,
+            env: process.env,
+            stdio: ['pipe', 'pipe', 'inherit'],
+            ...posixProcessGroupSpawnOptions(),
+        });
+    }
+    catch (error) {
+        throw protocolError(spec, invocation, `executable could not be run (${describeError(error)})`, 'a runnable hook executable');
+    }
+    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') {
+                reject(protocolError(spec, invocation, `executable timed out after ${EXEC_HOOK_TIMEOUT_MS}ms`, 'one JSON envelope before the execution timeout'));
+                return;
+            }
+            if (failure?.kind === 'output_limit') {
+                reject(protocolError(spec, invocation, 'stdout exceeded the 10 MiB cap', 'one JSON envelope under 10 MiB on stdout'));
+                return;
+            }
+            if (failure?.kind === 'spawn') {
+                reject(protocolError(spec, invocation, `executable could not be run (${describeError(failure.error)})`, 'a runnable hook executable'));
+                return;
+            }
+            if (failure?.kind === 'cleanup') {
+                reject(protocolError(spec, invocation, `executable cleanup failed (${describeError(failure.error)})`, 'a hook executable whose process group can be terminated'));
+                return;
+            }
+            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) {
+                terminate({ kind: 'output_limit' });
+                return;
+            }
+            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' }), EXEC_HOOK_TIMEOUT_MS);
+        child.stdin.end(input);
+    });
+}
+function buildRequest(spec, invocation, cwd) {
+    if (!OPERATION_ID.test(invocation.operationId)) {
+        throw protocolError(spec, invocation, 'operationId was not a 32-character lowercase hexadecimal string', 'a valid crouter operation identity');
+    }
+    if (!isJson(invocation.input)) {
+        throw protocolError(spec, invocation, 'input was not JSON-compatible', 'a JSON object');
+    }
+    if (!invocation.providedParams.every((param) => typeof param === 'string')) {
+        throw protocolError(spec, invocation, 'providedParams contained a non-string value', 'an array of parameter names');
+    }
+    const base = {
+        protocolVersion: 1,
+        op: spec.op,
+        command: [...spec.commandPath],
+        operationId: invocation.operationId,
+        input: invocation.input,
+        context: { cwd, providedParams: [...invocation.providedParams] },
+    };
+    if (spec.phase === 'after') {
+        if (invocation.result === undefined || !isJson(invocation.result)) {
+            throw protocolError(spec, invocation, 'after hook result was missing or not JSON-compatible', 'the completed primary result');
+        }
+        return { ...base, phase: 'after', result: invocation.result };
+    }
+    if (invocation.result !== undefined) {
+        throw protocolError(spec, invocation, `${spec.phase} hook invocation included a result`, 'result only for after hooks');
+    }
+    if (spec.phase === 'before')
+        return { ...base, phase: 'before' };
+    return { ...base, phase: 'replace' };
+}
+function parseEnvelope(spec, invocation, stdout) {
+    let value;
+    try {
+        value = JSON.parse(stdout.trim());
+    }
+    catch {
+        throw protocolError(spec, invocation, 'stdout was not a single JSON envelope', 'exactly one JSON envelope on stdout');
+    }
+    if (!isRecord(value)) {
+        throw protocolError(spec, invocation, 'stdout was not a JSON object', 'a { protocolVersion: 1, ok: boolean, ... } envelope');
+    }
+    if (value['protocolVersion'] !== 1) {
+        throw protocolError(spec, invocation, `unsupported protocolVersion ${String(value['protocolVersion'])}`, 'protocolVersion exactly 1');
+    }
+    if (value['ok'] === true) {
+        const expectedKeys = spec.phase === 'replace' ? ['protocolVersion', 'ok', 'result'] : ['protocolVersion', 'ok'];
+        if (!hasExactKeys(value, expectedKeys)) {
+            throw protocolError(spec, invocation, 'success envelope had missing or extra fields', `{ ${expectedKeys.join(', ')} } only`);
+        }
+        if (spec.phase === 'replace') {
+            if (!isJson(value['result'])) {
+                throw protocolError(spec, invocation, 'replacement result was not JSON-compatible', 'a JSON result');
+            }
+            return { protocolVersion: 1, ok: true, result: value['result'] };
+        }
+        return { protocolVersion: 1, ok: true };
+    }
+    if (value['ok'] !== false || !hasExactKeys(value, ['protocolVersion', 'ok', 'error'])) {
+        throw protocolError(spec, invocation, 'failure envelope had missing or extra fields', '{ protocolVersion, ok, error } only');
+    }
+    const error = value['error'];
+    if (!isRecord(error) || !hasExactKeys(error, ['code', 'message'], ['field', 'next'])) {
+        throw protocolError(spec, invocation, 'error envelope was missing fields or contained extra fields', 'error: { code, message, field?, next? }');
+    }
+    if (typeof error['code'] !== 'string' || error['code'] === '' || typeof error['message'] !== 'string' || error['message'] === '') {
+        throw protocolError(spec, invocation, 'error envelope had an empty or non-string code/message', 'non-empty error code and message strings');
+    }
+    if ((error['field'] !== undefined && typeof error['field'] !== 'string') || (error['next'] !== undefined && typeof error['next'] !== 'string')) {
+        throw protocolError(spec, invocation, 'error envelope had a non-string field/next', 'string field and next values when present');
+    }
+    return {
+        protocolVersion: 1,
+        ok: false,
+        error: {
+            code: error['code'],
+            message: error['message'],
+            ...(error['field'] === undefined ? {} : { field: error['field'] }),
+            ...(error['next'] === undefined ? {} : { next: error['next'] }),
+        },
+    };
+}
+function throwHookFailure(spec, invocation, failure) {
+    const { code, message, field, next } = failure.error;
+    if (!SNAKE.test(code) || RESERVED_CODES.has(code)) {
+        throw protocolError(spec, invocation, `error code "${code}" was invalid or reserved`, 'a non-reserved lowercase snake_case code');
+    }
+    throw new CrtrError(code, `${label(spec)}: ${message}`, ExitCode.GENERAL, failureDetails(spec, invocation, field, next));
+}
+function protocolError(spec, invocation, received, expected) {
+    return new CrtrError('hook_protocol_error', `${label(spec)}: ${received}. Expected ${expected}.`, ExitCode.GENERAL, failureDetails(spec, invocation, undefined, NEXT, received));
+}
+function failureDetails(spec, invocation, field, next, received) {
+    const identity = {
+        plugin: spec.plugin,
+        op: spec.op,
+        phase: spec.phase,
+        command: [...spec.commandPath],
+        ...(received === undefined ? {} : { received }),
+        ...(field === undefined ? {} : { field }),
+    };
+    if (spec.phase !== 'after')
+        return { ...identity, next: next ?? NEXT };
+    const guidance = 'Do not retry the original command; its primary action completed. Inspect and reconcile the failed after hook.';
+    return {
+        ...identity,
+        primaryCompleted: true,
+        result: invocation.result,
+        next: next === undefined || next === NEXT ? guidance : `${next} ${guidance}`,
+    };
+}
+function label(spec) {
+    return `plugin "${spec.plugin}" ${spec.phase} hook "${spec.op}" for \`${spec.commandPath.join(' ')}\``;
+}
+function hasExactKeys(value, required, optional = []) {
+    const keys = Object.keys(value);
+    return required.every((key) => Object.hasOwn(value, key))
+        && keys.every((key) => required.includes(key) || optional.includes(key));
+}
+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 describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/core/command-hooks/transport/exec-lifecycle.d.ts

@@ -0,0 +1,23 @@
+import type { LifecycleHookRequest, NodeCreateHookRequest } from '../../../hook-authoring.js';
+import type { EffectiveLifecycleHook } from '../discovery.js';
+export interface NodeLifecycleHookInvocation {
+    node: LifecycleHookRequest['node'];
+    runtime: LifecycleHookRequest['runtime'];
+}
+export interface NodeCreateHookInvocation {
+    app: string;
+    create: NodeCreateHookRequest['create'];
+    runtime: NodeCreateHookRequest['runtime'];
+}
+export interface BlockingLifecycleHookRefusal {
+    hook: EffectiveLifecycleHook;
+    message: string;
+    next: string;
+}
+/** Runs one lifecycle hook. `node:start` and `node:close` remain best-effort. */
+export declare function invokeLifecycleHook(hook: EffectiveLifecycleHook, invocation: NodeLifecycleHookInvocation, timeoutMs: number): Promise<void>;
+/** Executes non-blocking lifecycle hooks in discovery order within the event's catalogued budget. */
+export declare function invokeLifecycleHooks(hooks: readonly EffectiveLifecycleHook[], invocation: NodeLifecycleHookInvocation): Promise<void>;
+/** Runs blocking `node:create` hooks. Every protocol or process failure refuses the create. */
+export declare function invokeBlockingLifecycleHooks(hooks: readonly EffectiveLifecycleHook[], invocation: NodeCreateHookInvocation): Promise<BlockingLifecycleHookRefusal | null>;
+export declare function lifecycleHookAttribution(hook: EffectiveLifecycleHook): string;

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

@@ -0,0 +1,248 @@
+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';
+import { getNode } from '../../canvas/canvas.js';
+import { buildAppProcessEnv } from '../../runtime/spawn-env-rows.js';
+import { appProcessSandboxed, launchAppProcess } from '../../spaces/process.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 = appProcessSandboxed()
+        ? await runSandboxedLifecycleProcess(hook, invocation, JSON.stringify(request), timeoutMs)
+        : 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 runSandboxedLifecycleProcess(hook, invocation, input, timeoutMs) {
+    const creating = hook.event === 'node:create';
+    const cwd = creating ? invocation.create.cwd : invocation.node.cwd;
+    const nodeId = creating ? undefined : invocation.node.id;
+    const app = creating ? invocation.app : (await getNode(nodeId))?.grantee;
+    if (!app)
+        throw new Error(`missing app for lifecycle hook ${hook.event}`);
+    const env = await buildAppProcessEnv(cwd, invocation.runtime.profile, app);
+    const child = await launchAppProcess({
+        ...(creating ? { app } : { nodeId }),
+        command: [hook.executable, '--crtr-hook-protocol', '1'], cwd: hook.plugin.root, pluginRoot: hook.plugin.root,
+        env, stdin: input, stdoutBytes: MAX_STDOUT, stderrBytes: 64 * 1024,
+    });
+    let timer;
+    try {
+        const result = await Promise.race([
+            child.completion,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    void child.stop().then(() => reject(new Error(`executable timed out after ${timeoutMs}ms`)), reject);
+                }, timeoutMs);
+            }),
+        ]);
+        if (result.stdoutTruncated)
+            throw new Error('stdout exceeded the 10 MiB cap');
+        return { stdout: result.stdout, status: result.exitCode, signal: result.signal };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+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);
+}

package/dist/core/command-hooks/transport/plan.d.ts

@@ -0,0 +1,3 @@
+import type { RemoteHookMetadata } from '../discovery.js';
+/** The daemon reads user-installed manifests; no plugin path or executable crosses into the node. */
+export declare function remoteHookPlan(cwd: string): Promise<readonly RemoteHookMetadata[]>;

package/dist/core/command-hooks/transport/plan.js

@@ -0,0 +1,30 @@
+import { socketFetch } from '../../../api/node-transport.js';
+import { isRecord } from '../../../shared/predicates.js';
+import { envExecutionId, envNodeId } from '../../../shared/env.js';
+/** The daemon reads user-installed manifests; no plugin path or executable crosses into the node. */
+export async function remoteHookPlan(cwd) {
+    const nodeId = envNodeId();
+    const executionId = envExecutionId();
+    const socket = process.env['CRTR_API_SOCKET'];
+    if (!nodeId || !executionId || !socket)
+        throw new Error('hook plan requires the current node execution');
+    const query = new URLSearchParams({ cwd, expected_execution_id: executionId });
+    const response = await socketFetch(socket)(`http://localhost/v1/nodes/${encodeURIComponent(nodeId)}/hooks/plan?${query}`);
+    const value = await response.json();
+    if (!response.ok) {
+        const message = isRecord(value) && isRecord(value['error']) && typeof value['error']['message'] === 'string'
+            ? value['error']['message'] : `hook plan refused (${response.status})`;
+        throw new Error(message);
+    }
+    if (!isRecord(value) || !Array.isArray(value['hooks']))
+        throw new Error('invalid hook plan response');
+    return value['hooks'].map((entry) => {
+        if (!isRecord(entry) || typeof entry['id'] !== 'string' || typeof entry['plugin'] !== 'string' ||
+            typeof entry['target'] !== 'string' || !['before', 'after', 'replace'].includes(String(entry['phase'])) ||
+            typeof entry['op'] !== 'string' || typeof entry['description'] !== 'string' ||
+            !Array.isArray(entry['effects']) || !entry['effects'].every((effect) => typeof effect === 'string') ||
+            !Number.isInteger(entry['declarationIndex']))
+            throw new Error('invalid hook plan entry');
+        return entry;
+    });
+}