@north-light/crouter 0.3.220 → 0.3.221

package/dist/core/command-hooks/help.js

@@ -0,0 +1,18 @@
+function attributedEffects(hook) {
+    const attribution = `plugin=${hook.plugin.name} phase=${hook.phase} op=${hook.op}`;
+    return hook.effects.map((effect) => `[${attribution}] ${effect}`);
+}
+/** Build a frozen help view whose Effects order matches the effective pipeline.
+ *  Core help is never modified; all non-effects fields retain their references. */
+export function projectEffectiveLeafHelp(core, plan) {
+    const before = plan?.before.flatMap(attributedEffects) ?? [];
+    const replacement = plan?.replacements.length === 1 ? plan.replacements[0] : undefined;
+    const primary = replacement === undefined
+        ? core.effects
+        : attributedEffects(replacement);
+    const after = plan?.after.flatMap(attributedEffects) ?? [];
+    return Object.freeze({
+        ...core,
+        effects: Object.freeze([...before, ...primary, ...after]),
+    });
+}

package/dist/core/command-hooks/index.d.ts

@@ -0,0 +1,6 @@
+export { createCoreHookCatalog, type CoreHookCatalog, type CoreHookTarget } from './catalog.js';
+export { projectEffectiveLeafHelp } from './help.js';
+export { compileHookRegistry, discoverCandidateHookRegistry, discoverHookRegistry, discoverHookRegistryInScopes, effectiveHookPlugins, hookDiscoveryScopes, type EffectiveHook, type EffectiveHookPlan, type HookDiscoveryIssue, type HookPluginAttribution, type HookPluginValidation, type HookRegistry, type HookScope, } from './discovery.js';
+export { validatePluginHookArtifact, type HookArtifactValidation } from './artifact.js';
+export { hasDeclaredHooks, hookReport, HOOK_TRUST_WARNING, type HookDeclarationReport, type HookReport } from './report.js';
+export { validateHookManifest, type DeclaredHook, type HookManifestIssue, type HookManifestValidation, type HookPhase, type ValidatedHookManifest, } from './schema.js';

package/dist/core/command-hooks/index.js

@@ -0,0 +1,6 @@
+export { createCoreHookCatalog } from './catalog.js';
+export { projectEffectiveLeafHelp } from './help.js';
+export { compileHookRegistry, discoverCandidateHookRegistry, discoverHookRegistry, discoverHookRegistryInScopes, effectiveHookPlugins, hookDiscoveryScopes, } from './discovery.js';
+export { validatePluginHookArtifact } from './artifact.js';
+export { hasDeclaredHooks, hookReport, HOOK_TRUST_WARNING } from './report.js';
+export { validateHookManifest, } from './schema.js';

package/dist/core/command-hooks/report.d.ts

@@ -0,0 +1,23 @@
+import type { PluginManifest } from '../../types.js';
+import type { HookDiscoveryIssue, HookPluginValidation } from './discovery.js';
+import type { DeclaredHook } from './schema.js';
+export declare const HOOK_TRUST_WARNING = "Hooks receive normalized inputs; after hooks receive results. They run implicitly and may block or replace declared targets. The local executable runs with caller authority and can transmit received data.";
+export interface HookDeclarationReport {
+    target: string;
+    phase: DeclaredHook['phase'];
+    op: string;
+    description: string;
+    effects: readonly string[];
+}
+/** One static hook artifact report shared by plugin inspection and lifecycle
+ * output. It only reads declarations and filesystem metadata; it never runs
+ * the hook executable. */
+export interface HookReport {
+    manifestPath?: string;
+    executablePath?: string;
+    declarations: readonly HookDeclarationReport[];
+    issues: readonly HookDiscoveryIssue[];
+    trust: typeof HOOK_TRUST_WARNING;
+}
+export declare function hasDeclaredHooks(manifest: Pick<PluginManifest, 'hooks' | 'hookExecutable'>): boolean;
+export declare function hookReport(validation: HookPluginValidation, issues?: readonly HookDiscoveryIssue[]): HookReport;

package/dist/core/command-hooks/report.js

@@ -0,0 +1,19 @@
+export const HOOK_TRUST_WARNING = 'Hooks receive normalized inputs; after hooks receive results. They run implicitly and may block or replace declared targets. The local executable runs with caller authority and can transmit received data.';
+export function hasDeclaredHooks(manifest) {
+    return manifest.hooks !== undefined || manifest.hookExecutable !== undefined;
+}
+export function hookReport(validation, issues = validation.issues) {
+    return Object.freeze({
+        ...(validation.manifestPath === undefined ? {} : { manifestPath: validation.manifestPath }),
+        ...(validation.executablePath === undefined ? {} : { executablePath: validation.executablePath }),
+        declarations: Object.freeze((validation.manifest?.hooks ?? []).map((hook) => Object.freeze({
+            target: hook.target,
+            phase: hook.phase,
+            op: hook.op,
+            description: hook.description,
+            effects: Object.freeze([...hook.effects]),
+        }))),
+        issues: Object.freeze([...issues]),
+        trust: HOOK_TRUST_WARNING,
+    });
+}

package/dist/core/command-hooks/schema.d.ts

@@ -0,0 +1,27 @@
+export type HookPhase = 'before' | 'after' | 'replace';
+export interface DeclaredHook {
+    target: string;
+    phase: HookPhase;
+    op: string;
+    description: string;
+    effects: string[];
+}
+export interface ValidatedHookManifest {
+    schemaVersion: 1;
+    hooks: DeclaredHook[];
+}
+export type HookIssueCode = 'hook_manifest_unreadable' | 'hook_manifest_invalid' | 'hook_schema_version' | 'hook_path_unsafe' | 'hook_not_executable';
+export interface HookManifestIssue {
+    code: HookIssueCode;
+    path?: string;
+    message: string;
+    received: string;
+    expected: string;
+    next: string;
+}
+export interface HookManifestValidation {
+    manifest?: ValidatedHookManifest;
+    issues: HookManifestIssue[];
+}
+/** Validates the declarative hooks.json payload without filesystem access. */
+export declare function validateHookManifest(raw: unknown): HookManifestValidation;

package/dist/core/command-hooks/schema.js

@@ -0,0 +1,68 @@
+import { isRecord } from '../../shared/predicates.js';
+function typeName(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+/** Validates the declarative hooks.json payload without filesystem access. */
+export function validateHookManifest(raw) {
+    const issues = [];
+    const issue = (code, message, received, expected, next, path) => {
+        issues.push({ code, message, received, expected, next, ...(path === undefined ? {} : { path }) });
+    };
+    if (!isRecord(raw)) {
+        issue('hook_manifest_invalid', 'manifest must be an object', typeName(raw), '{ schemaVersion, hooks }', 'Provide a valid hooks.json manifest.');
+        return { issues };
+    }
+    const unknown = Object.keys(raw).filter((key) => key !== 'schemaVersion' && key !== 'hooks');
+    if (unknown.length > 0) {
+        issue('hook_manifest_invalid', 'unknown top-level keys', unknown.join(', '), 'only: schemaVersion, hooks', 'Remove the unknown keys.');
+        return { issues };
+    }
+    if (raw['schemaVersion'] !== 1) {
+        issue('hook_schema_version', 'schemaVersion must be exactly 1', String(raw['schemaVersion']), '1', 'Update the manifest schema version to 1.', 'schemaVersion');
+        return { issues };
+    }
+    if (!Array.isArray(raw['hooks']) || raw['hooks'].length === 0) {
+        issue('hook_manifest_invalid', 'hooks must be a non-empty array', typeName(raw['hooks']), 'a non-empty array of hook declarations', 'Declare at least one hook.', 'hooks');
+        return { issues };
+    }
+    const hooks = [];
+    for (let index = 0; index < raw['hooks'].length; index++) {
+        const value = raw['hooks'][index];
+        const path = `hooks[${index}]`;
+        if (!isRecord(value)) {
+            issue('hook_manifest_invalid', 'hook must be an object', typeName(value), '{ target, phase, op, description, effects }', 'Fix the hook declaration.', path);
+            return { issues };
+        }
+        const keys = Object.keys(value).filter((key) => !['target', 'phase', 'op', 'description', 'effects'].includes(key));
+        if (keys.length > 0) {
+            issue('hook_manifest_invalid', 'unknown hook keys', keys.join(', '), 'only: target, phase, op, description, effects', 'Remove the unknown keys.', path);
+            return { issues };
+        }
+        for (const field of ['target', 'op', 'description']) {
+            if (typeof value[field] !== 'string' || value[field].length === 0) {
+                issue('hook_manifest_invalid', `${field} must be a non-empty string`, typeName(value[field]), 'a non-empty string', `Set ${field}.`, `${path}.${field}`);
+                return { issues };
+            }
+        }
+        if (value['phase'] !== 'before' && value['phase'] !== 'after' && value['phase'] !== 'replace') {
+            issue('hook_manifest_invalid', 'phase must be before|after|replace', String(value['phase']), 'before | after | replace', 'Set phase to a supported hook phase.', `${path}.phase`);
+            return { issues };
+        }
+        if (!Array.isArray(value['effects']) || value['effects'].length === 0 || !value['effects'].every((effect) => typeof effect === 'string' && effect.length > 0)) {
+            issue('hook_manifest_invalid', 'effects must be a non-empty string array', typeName(value['effects']), 'a non-empty array of non-empty strings', 'Declare every persistent effect.', `${path}.effects`);
+            return { issues };
+        }
+        hooks.push({
+            target: value['target'],
+            phase: value['phase'],
+            op: value['op'],
+            description: value['description'],
+            effects: value['effects'],
+        });
+    }
+    return { manifest: { schemaVersion: 1, hooks }, issues };
+}

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

@@ -0,0 +1,22 @@
+import type { HookPhase } from '../../../hook-authoring.js';
+import type { Field } from '../../help.js';
+export declare const EXEC_HOOK_TIMEOUT_MS = 15000;
+export interface ExecHookSpec {
+    plugin: string;
+    /** Absolute, validated hookExecutable path. */
+    executable: string;
+    op: string;
+    phase: HookPhase;
+    commandPath: readonly string[];
+    /** Required for replacement hooks; ignored for before and after hooks. */
+    output?: Field[];
+}
+export interface ExecHookInvocation {
+    operationId: string;
+    input: Record<string, unknown>;
+    providedParams: readonly string[];
+    /** The completed primary result, present only for an after hook. */
+    result?: Record<string, unknown>;
+}
+/** Invoke one hook executable; after failures retain the completed primary result. */
+export declare function invokeExecHook(spec: ExecHookSpec, invocation: ExecHookInvocation): Promise<Record<string, unknown> | void>;

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

@@ -0,0 +1,274 @@
+import { spawn } from 'node:child_process';
+import { posixProcessGroupSpawnOptions, terminateProcessGroup } from '../../../hook-process.js';
+import { ExitCode } from '../../../types.js';
+import { isRecord } from '../../../shared/predicates.js';
+import { validateCoreDeclaredResult } from '../../command-plugins/transport/exec-invoke.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 = validateCoreDeclaredResult(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}: ${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) {
+    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');
+    }
+    return { ...base, phase: spec.phase };
+}
+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-plugins/presence.d.ts

@@ -0,0 +1,2 @@
+/** Whether an enabled command plugin survives nearest-scope name shadowing. */
+export declare function hasEffectiveCommandPlugins(startDir?: string, profileId?: string | null): boolean;

package/dist/core/command-plugins/presence.js

@@ -0,0 +1,17 @@
+import { listInstalledPlugins, listInstalledPluginsInRoot } from '../resolver.js';
+import { projectScopeRoots } from '../scope.js';
+/** Whether an enabled command plugin survives nearest-scope name shadowing. */
+export function hasEffectiveCommandPlugins(startDir = process.cwd(), profileId) {
+    const seen = new Set();
+    const consider = (plugin) => {
+        if (seen.has(plugin.name))
+            return false;
+        seen.add(plugin.name);
+        return plugin.enabled && (plugin.manifest.commands !== undefined || plugin.manifest.transport !== undefined);
+    };
+    for (const root of projectScopeRoots(startDir, profileId)) {
+        if (listInstalledPluginsInRoot('project', root).some(consider))
+            return true;
+    }
+    return listInstalledPlugins('user').some(consider);
+}

package/dist/core/command-plugins/transport/exec-invoke.d.ts

@@ -16,6 +16,11 @@ export declare function validateDeclaredResult(output: Field[], result: Record<s
     field: string;
     receivedType?: string;
 } | null;
+/** Core leaf declarations may explicitly require a nullable field. */
+export declare function validateCoreDeclaredResult(output: Field[], result: Record<string, unknown>): {
+    field: string;
+    receivedType?: string;
+} | null;
 /** Execute one external leaf and return its result object (crtr renders it via
  *  the generic renderer; `--json` mirrors it). Throws a CrtrError for any
  *  protocol violation or the plugin's own recoverable error. */

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

@@ -21,13 +21,23 @@ const NEXT = 'Run `crtr pkg plugin show` or `crtr sys doctor` to inspect the plu
  *  Returns null if valid; otherwise returns a { field, receivedType } error.
  *  Transport-neutral: used by exec and HTTP transport adapters. */
 export function validateDeclaredResult(output, result) {
+    return validateFields(output, result, false);
+}
+/** Core leaf declarations may explicitly require a nullable field. */
+export function validateCoreDeclaredResult(output, result) {
+    return validateFields(output, result, true);
+}
+function validateFields(output, result, honorDeclaredNull) {
     for (const f of output) {
-        const present = Object.prototype.hasOwnProperty.call(result, f.name) && result[f.name] !== undefined && result[f.name] !== null;
-        if (f.required && !present) {
+        const value = result[f.name];
+        const present = Object.prototype.hasOwnProperty.call(result, f.name)
+            && value !== undefined
+            && (honorDeclaredNull || value !== null);
+        if (f.required && !present)
             return { field: f.name };
-        }
-        if (present && !typeMatches(f.type, result[f.name])) {
-            return { field: f.name, receivedType: typeof result[f.name] };
+        const matches = honorDeclaredNull ? coreTypeMatches(f.type, value) : typeMatches(f.type, value);
+        if (present && !matches) {
+            return { field: f.name, receivedType: value === null ? 'null' : typeof value };
         }
     }
     return null;
@@ -150,6 +160,49 @@ function typeMatches(type, v) {
         return isRecord(v);
     return true;
 }
+function coreTypeMatches(type, v) {
+    const alternatives = type.split('|').map((part) => part.trim()).filter(Boolean);
+    if (alternatives.length === 1 && !knownType(alternatives[0]))
+        return true;
+    const allKnown = alternatives.every((part) => knownType(part) || /^[a-z][a-z0-9_-]*$/.test(part));
+    if (!allKnown)
+        return true;
+    return alternatives.some((part) => atomMatches(part, v));
+}
+function knownType(type) {
+    const t = type.toLowerCase();
+    return t === 'null'
+        || t === 'string'
+        || t === 'path'
+        || t === 'markdown'
+        || t === 'int'
+        || t === 'integer'
+        || t === 'number'
+        || t === 'float'
+        || t === 'bool'
+        || t === 'boolean'
+        || t === 'array'
+        || t.endsWith('[]')
+        || t === 'object';
+}
+function atomMatches(type, v) {
+    const t = type.toLowerCase();
+    if (t === 'null')
+        return v === null;
+    if (t === 'string' || t === 'path' || t === 'markdown')
+        return typeof v === 'string';
+    if (t === 'int' || t === 'integer')
+        return typeof v === 'number' && Number.isInteger(v);
+    if (t === 'number' || t === 'float')
+        return typeof v === 'number';
+    if (t === 'bool' || t === 'boolean')
+        return typeof v === 'boolean';
+    if (t === 'array' || t.endsWith('[]'))
+        return Array.isArray(v);
+    if (t === 'object')
+        return isRecord(v);
+    return typeof v === 'string' && v === type;
+}
 function protocolError(spec, received, expected) {
     return new CrtrError('plugin_protocol_error', `${label(spec)}: ${received}. Expected ${expected}.`, ExitCode.GENERAL, { received, next: NEXT });
 }

package/dist/core/command.d.ts

@@ -1,4 +1,4 @@
-import type { RootHelp, RootEntry, BranchHelp, LeafHelp, InputParam, SubTier } from './help.js';
+import type { RootHelp, RootEntry, BranchHelp, LeafHelp, EffectiveLeafHelp, InputParam, SubTier } from './help.js';
 import { CrtrError } from './errors.js';
 /** Runtime context passed to a leaf's run function. Includes metadata about
  *  which parameters were explicitly provided vs. defaulted. Used by configured
@@ -47,6 +47,11 @@ export interface LeafDef {
      *  'hidden' keeps an internal leaf out of every listing. */
     tier?: SubTier;
     help: LeafHelp;
+    /** Invocation-local immutable help view. Present only on hook-eligible core
+     *  leaves; static discovery may change Effects but never executes hooks. */
+    effectiveHelp?: () => Promise<EffectiveLeafHelp>;
+    /** Opt this conditionally-void leaf out of core command hooks. */
+    hookEligible?: false;
     /** Opt into editor slash-command exposure (see SlashSpec). */
     slash?: SlashSpec;
     run: (input: Record<string, unknown>, context?: LeafRunContext) => Promise<Record<string, unknown> | void>;
@@ -100,6 +105,8 @@ export declare function defineLeaf(opts: {
     tier?: SubTier;
     help: LeafHelp;
     slash?: SlashSpec;
+    /** Opt this conditionally-void leaf out of core command hooks. */
+    hookEligible?: false;
     run: (input: Record<string, unknown>, context?: LeafRunContext) => Promise<Record<string, unknown> | void>;
     render?: (result: Record<string, unknown>) => string;
 }): LeafDef;

package/dist/core/command.js

@@ -34,6 +34,7 @@ export function defineLeaf(opts) {
         tier: opts.tier,
         help: freezeCommandMetadata(opts.help),
         slash: opts.slash === undefined ? undefined : freezeCommandMetadata(opts.slash),
+        hookEligible: opts.hookEligible,
         run: opts.run,
         render: opts.render,
     });
@@ -187,19 +188,20 @@ function renderNode(node) {
         return renderBranch(node.help);
     return renderLeafArgv(node.help);
 }
-/** Render a node's help plus any plugin help addenda targeting its walked
- *  command path — append-only, attributed blocks a plugin adds beneath core
- *  contract text, never inside it. Plugin discovery loads only here (dynamic
- *  import on the help path), so the dispatch path's module graph and cold
- *  start are unchanged; the lookup reads stored manifest bytes only. The
- *  lookup receives the install gate's exact strict-validation inputs (reserved
- *  core names + the full core command path set, both from build-root), so a
- *  manifest rejected at ingress contributes nothing here either — loading
- *  every subtree for that path set is a help-path-only cost. */
+/** Render effective Effects for a hook-eligible core leaf, then append any
+ *  commands.json helpAddenda beneath the contract. Both lookups read stored
+ *  manifest bytes only. Addenda validation receives the install gate's exact
+ *  reserved core names and full core path set, so a manifest rejected at
+ *  ingress contributes nothing here either. */
 async function renderNodeWithAddenda(node, path) {
-    const body = renderNode(node);
+    const body = node.kind === 'leaf' && node.effectiveHelp !== undefined
+        ? renderLeafArgv(await node.effectiveHelp())
+        : renderNode(node);
     if (path.length === 0)
         return body;
+    const { hasEffectiveCommandPlugins } = await import('./command-plugins/presence.js');
+    if (!hasEffectiveCommandPlugins())
+        return body;
     const [{ collectHelpAddenda }, { SUBTREE_NAMES, coreCommandPaths }] = await Promise.all([
         import('./command-plugins/help-addenda.js'),
         import('../build-root.js'),