@north-light/api 0.3.579 → 0.3.587

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

@@ -0,0 +1,246 @@
+import { isSandboxedNode } from '../../shared/env.js';
+import { listInstalledPluginsInRoot } from '../resolver.js';
+import { projectScopeRoots, userScopeRoot } from '../scope.js';
+import { validatePluginHookArtifact } from './artifact.js';
+export function hookIdentity(hook) {
+    return JSON.stringify([hook.plugin.name, hook.target, hook.phase, hook.op, hook.declarationIndex]);
+}
+function hasHookDeclaration(plugin) {
+    return plugin.manifest.hooks !== undefined || plugin.manifest.hookExecutable !== undefined;
+}
+function orderedPluginsInScopes(scopes) {
+    const seen = new Set();
+    const result = [];
+    for (const scope of scopes) {
+        const plugins = listInstalledPluginsInRoot(scope.scope, scope.root).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+        for (const plugin of plugins) {
+            if (seen.has(plugin.name))
+                continue;
+            seen.add(plugin.name);
+            if (plugin.enabled && hasHookDeclaration(plugin))
+                result.push(plugin);
+        }
+    }
+    return result;
+}
+/** Project scopes nearest-outward, followed by the user scope. */
+export function hookDiscoveryScopes(startDir = process.cwd(), profileId) {
+    return [
+        ...projectScopeRoots(startDir, profileId).map((root) => ({ scope: 'project', root })),
+        ...(!isSandboxedNode() ? [{ scope: 'user', root: userScopeRoot() }] : []),
+    ];
+}
+/** Effective enabled hook plugins, with disabled nearest copies still shadowing outer copies. */
+export function effectiveHookPlugins(startDir = process.cwd(), profileId) {
+    return orderedPluginsInScopes(hookDiscoveryScopes(startDir, profileId));
+}
+function effectiveHookPluginsWithCandidates(candidates, startDir = process.cwd(), profileId) {
+    const seen = new Set();
+    const result = [];
+    for (const scope of hookDiscoveryScopes(startDir, profileId)) {
+        const replacements = candidates.filter((candidate) => candidate.plugin.scope === scope.scope && candidate.scopeRoot === scope.root);
+        const replacedNames = new Set(replacements.map((candidate) => candidate.plugin.name));
+        const plugins = [
+            ...listInstalledPluginsInRoot(scope.scope, scope.root).filter((plugin) => !replacedNames.has(plugin.name)),
+            ...replacements.map((candidate) => candidate.plugin),
+        ];
+        plugins.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+        for (const plugin of plugins) {
+            if (seen.has(plugin.name))
+                continue;
+            seen.add(plugin.name);
+            if (plugin.enabled && hasHookDeclaration(plugin))
+                result.push(plugin);
+        }
+    }
+    return result;
+}
+function issue(plugin, value) {
+    return { ...value, plugin: plugin.name, scope: plugin.scope };
+}
+function artifactIssues(plugin, issues) {
+    return issues.map((value) => issue(plugin, value));
+}
+function targetIssues(plugin, hooks, catalog) {
+    const issues = [];
+    hooks.forEach((hook, index) => {
+        if (catalog.has(hook.target))
+            return;
+        issues.push(issue(plugin, {
+            code: 'command_hook_target_invalid',
+            path: `hooks[${index}].target`,
+            message: `hook target "${hook.target}" is not an eligible core returned-object leaf`,
+            received: hook.target,
+            expected: 'an exact eligible core leaf path',
+            next: 'Choose a current returned-object core leaf; pkg plugin, sys doctor, JSONL, passthrough, and UI/void surfaces are unavailable.',
+        }));
+    });
+    return issues;
+}
+/** Every command-hook target the plugins' valid hook artifacts declare. The
+ *  registry compiler only asks the core catalog about these paths, so a caller
+ *  can build the catalog over just the subtrees they name. */
+export function declaredCommandHookTargets(plugins) {
+    return plugins.flatMap((plugin) => validatePluginHookArtifact(plugin.root, plugin.manifest).manifest?.hooks.map((hook) => hook.target) ?? []);
+}
+/**
+ * Statically compiles hooks from already-resolved effective plugins. It reads
+ * manifest files to validate them but never executes a plugin executable.
+ */
+export function compileHookRegistry(catalog, plugins, remote = []) {
+    const validations = [];
+    const hooks = [];
+    const issues = [];
+    let order = 0;
+    for (const plugin of plugins) {
+        const artifact = validatePluginHookArtifact(plugin.root, plugin.manifest);
+        const pluginIssues = artifactIssues(plugin, artifact.issues);
+        let compiled = [];
+        if (pluginIssues.length === 0 && artifact.manifest !== undefined && artifact.executablePath !== undefined) {
+            const invalidTargets = targetIssues(plugin, artifact.manifest.hooks, catalog);
+            pluginIssues.push(...invalidTargets);
+            if (pluginIssues.length === 0) {
+                compiled = artifact.manifest.hooks.map((hook, declarationIndex) => Object.freeze({
+                    id: hookIdentity({ plugin: { name: plugin.name }, ...hook, declarationIndex }),
+                    executable: artifact.executablePath,
+                    plugin: Object.freeze({ name: plugin.name, scope: plugin.scope, root: plugin.root }),
+                    target: hook.target,
+                    phase: hook.phase,
+                    op: hook.op,
+                    description: hook.description,
+                    effects: Object.freeze([...hook.effects]),
+                    declarationIndex,
+                    order: order++,
+                }));
+                hooks.push(...compiled);
+            }
+        }
+        validations.push(Object.freeze({
+            plugin,
+            ...(artifact.manifestPath === undefined ? {} : { manifestPath: artifact.manifestPath }),
+            ...(artifact.executablePath === undefined ? {} : { executablePath: artifact.executablePath }),
+            ...(artifact.manifest === undefined ? {} : { manifest: artifact.manifest }),
+            lifecycleCandidates: Object.freeze([...artifact.lifecycleCandidates]),
+            hooks: Object.freeze(compiled),
+            issues: Object.freeze(pluginIssues),
+        }));
+        issues.push(...pluginIssues);
+    }
+    for (const entry of remote) {
+        if (!catalog.has(entry.target))
+            throw new Error(`daemon supplied an ineligible hook target: ${entry.target}`);
+        hooks.push(Object.freeze({ ...entry, executable: '', plugin: Object.freeze({ name: entry.plugin, scope: 'user', root: '' }), order: order++ }));
+    }
+    const byTarget = new Map();
+    for (const hook of hooks) {
+        const entries = byTarget.get(hook.target);
+        if (entries === undefined)
+            byTarget.set(hook.target, [hook]);
+        else
+            entries.push(hook);
+    }
+    const plans = new Map();
+    for (const [target, entries] of byTarget) {
+        const replacements = entries.filter((entry) => entry.phase === 'replace');
+        if (replacements.length > 1) {
+            for (const replacement of replacements) {
+                issues.push(issue(replacement.plugin, {
+                    code: 'command_hook_collision',
+                    path: `hooks[${replacement.declarationIndex}]`,
+                    message: `multiple replacements target "${target}"`,
+                    received: replacements.map((entry) => `${entry.plugin.name}:${entry.op}`).join(', '),
+                    expected: 'exactly one replacement for this core leaf',
+                    next: 'Remove or change one replace declaration; before and after hooks may coexist with one replacement.',
+                }));
+            }
+        }
+        plans.set(target, Object.freeze({
+            target,
+            before: Object.freeze(entries.filter((entry) => entry.phase === 'before')),
+            after: Object.freeze(entries.filter((entry) => entry.phase === 'after').reverse()),
+            replacements: Object.freeze(replacements),
+        }));
+    }
+    return Object.freeze({
+        catalog,
+        hooks: Object.freeze(hooks),
+        plans,
+        validations: Object.freeze(validations),
+        issues: Object.freeze(issues),
+        valid: issues.length === 0,
+    });
+}
+/** Compiles lifecycle declarations from resolved plugins without loading the command tree. */
+export function compileLifecycleHookRegistry(plugins) {
+    const validations = [];
+    const hooks = [];
+    const issues = [];
+    let order = 0;
+    for (const plugin of plugins) {
+        const artifact = validatePluginHookArtifact(plugin.root, plugin.manifest);
+        const pluginIssues = artifactIssues(plugin, artifact.issues);
+        let compiled = [];
+        if (pluginIssues.length === 0 && artifact.manifest !== undefined && artifact.executablePath !== undefined) {
+            const lifecycle = artifact.manifest.schemaVersion === 2 ? artifact.manifest.lifecycle : [];
+            compiled = lifecycle.map((hook, declarationIndex) => Object.freeze({
+                executable: artifact.executablePath,
+                plugin: Object.freeze({ name: plugin.name, scope: plugin.scope, root: plugin.root }),
+                event: hook.event,
+                phase: hook.phase,
+                op: hook.op,
+                description: hook.description,
+                effects: Object.freeze([...hook.effects]),
+                declarationIndex,
+                order: order++,
+            }));
+            hooks.push(...compiled);
+        }
+        validations.push(Object.freeze({
+            plugin,
+            ...(artifact.manifestPath === undefined ? {} : { manifestPath: artifact.manifestPath }),
+            ...(artifact.executablePath === undefined ? {} : { executablePath: artifact.executablePath }),
+            ...(artifact.manifest === undefined ? {} : { manifest: artifact.manifest }),
+            lifecycleCandidates: Object.freeze([...artifact.lifecycleCandidates]),
+            hooks: Object.freeze([]),
+            issues: Object.freeze(pluginIssues),
+        }));
+        issues.push(...pluginIssues);
+    }
+    const plans = new Map();
+    for (const hook of hooks) {
+        const entries = plans.get(hook.event) ?? [];
+        plans.set(hook.event, Object.freeze([...entries, hook]));
+    }
+    return Object.freeze({
+        hooks: Object.freeze(hooks),
+        plans,
+        validations: Object.freeze(validations),
+        issues: Object.freeze(issues),
+        valid: issues.length === 0,
+    });
+}
+/** Discovers lifecycle hooks for one node's resolved cwd and profile. */
+export function discoverLifecycleHookRegistry(startDir, profileId) {
+    if (process.env['CRTR_TEST_DISABLE_LIFECYCLE_HOOK_DISCOVERY'] === '1')
+        return compileLifecycleHookRegistry([]);
+    return compileLifecycleHookRegistry(effectiveHookPlugins(startDir, profileId));
+}
+/** Discovers and compiles the invocation-local effective registry. */
+export function discoverHookRegistry(catalog, startDir = process.cwd(), profileId) {
+    return compileHookRegistry(catalog, effectiveHookPlugins(startDir, profileId));
+}
+/** Compile the exact effective set a source candidate would create before its
+ *  bytes replace the installed plugin. */
+export function discoverCandidateHookRegistry(catalog, candidate, scopeRoot, startDir = process.cwd(), profileId) {
+    return discoverCandidateHookRegistryForCandidates(catalog, [{ plugin: candidate, scopeRoot }], startDir, profileId);
+}
+/** Compile the exact effective set after all supplied source candidates take
+ * their scope/name slots. This lets one transaction reject collisions introduced
+ * only by the combined revision. */
+export function discoverCandidateHookRegistryForCandidates(catalog, candidates, startDir = process.cwd(), profileId) {
+    return compileHookRegistry(catalog, effectiveHookPluginsWithCandidates(candidates, startDir, profileId));
+}
+/** Fixture-friendly discovery seam; production callers should use discoverHookRegistry. */
+export function discoverHookRegistryInScopes(catalog, scopes) {
+    return compileHookRegistry(catalog, orderedPluginsInScopes(scopes));
+}

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

@@ -0,0 +1,5 @@
+import type { EffectiveLeafHelp } from '../help.js';
+import type { EffectiveHookPlan } from './discovery.js';
+/** 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 declare function projectEffectiveLeafHelp(core: EffectiveLeafHelp, plan?: EffectiveHookPlan): EffectiveLeafHelp;

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/lifecycle-catalog.d.ts

@@ -0,0 +1,21 @@
+export declare const LIFECYCLE_CATALOG: {
+    readonly 'node:create': {
+        readonly phase: "before";
+        readonly hookTimeoutMs: 15000;
+        readonly eventBudgetMs: 30000;
+    };
+    readonly 'node:start': {
+        readonly phase: "on";
+        readonly hookTimeoutMs: 15000;
+        readonly eventBudgetMs: 30000;
+    };
+    readonly 'node:close': {
+        readonly phase: "on";
+        readonly hookTimeoutMs: 120000;
+        readonly eventBudgetMs: 180000;
+    };
+};
+export type LifecycleEvent = keyof typeof LIFECYCLE_CATALOG;
+export type LifecycleHookPhase = (typeof LIFECYCLE_CATALOG)[LifecycleEvent]['phase'];
+export declare const LIFECYCLE_EVENTS: readonly ("node:create" | "node:start" | "node:close")[];
+export declare function isLifecycleEvent(value: string): value is LifecycleEvent;

package/dist/core/command-hooks/lifecycle-catalog.js

@@ -0,0 +1,9 @@
+export const LIFECYCLE_CATALOG = {
+    'node:create': { phase: 'before', hookTimeoutMs: 15_000, eventBudgetMs: 30_000 },
+    'node:start': { phase: 'on', hookTimeoutMs: 15_000, eventBudgetMs: 30_000 },
+    'node:close': { phase: 'on', hookTimeoutMs: 120_000, eventBudgetMs: 180_000 },
+};
+export const LIFECYCLE_EVENTS = Object.freeze(Object.keys(LIFECYCLE_CATALOG));
+export function isLifecycleEvent(value) {
+    return Object.hasOwn(LIFECYCLE_CATALOG, value);
+}

package/dist/core/command-hooks/lifecycle-create.d.ts

@@ -0,0 +1,4 @@
+import type { NodeCreateHookRequest } from '../../hook-authoring.js';
+export type NodeCreateRequest = NodeCreateHookRequest['create'];
+/** Admit one node creation and return the release that must run after its row exists. */
+export declare function admitNodeCreate(create: NodeCreateRequest, app: string): Promise<() => void>;

package/dist/core/command-hooks/lifecycle-create.js

@@ -0,0 +1,51 @@
+import { crtrHome } from '../canvas/paths.js';
+import { nodeCreateRefused } from '../errors.js';
+import { discoverLifecycleHookRegistry } from './discovery.js';
+import { invokeBlockingLifecycleHooks } from './transport/exec-lifecycle.js';
+let nodeCreateGate = Promise.resolve();
+async function enterNodeCreateGate() {
+    let resolve;
+    const previous = nodeCreateGate;
+    nodeCreateGate = new Promise((release) => { resolve = release; });
+    await previous;
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        resolve();
+    };
+}
+function refusedCreateHookDiscovery(cwd, profileId) {
+    const registry = discoverLifecycleHookRegistry(cwd, profileId);
+    const plan = registry.plans.get('node:create') ?? [];
+    const failed = registry.validations.flatMap((validation) => validation.lifecycleCandidates
+        .filter((candidate) => candidate.event === 'node:create' && !plan.some((hook) => hook.plugin.name === validation.plugin.name && hook.declarationIndex === candidate.index))
+        .map((candidate) => ({
+        validation,
+        candidate,
+        issue: validation.issues.find((issue) => issue.path === `lifecycle[${candidate.index}]` || issue.path?.startsWith(`lifecycle[${candidate.index}].`)) ?? validation.issues[0],
+    })))[0];
+    if (failed === undefined)
+        return registry;
+    const { validation, candidate, issue } = failed;
+    throw nodeCreateRefused(`plugin "${validation.plugin.name}" lifecycle hook "${candidate.op}" for node:create could not be discovered: ${issue.message}`, `Refused by plugin ${validation.plugin.name}, op ${candidate.op}.`);
+}
+/** Admit one node creation and return the release that must run after its row exists. */
+export async function admitNodeCreate(create, app) {
+    const release = await enterNodeCreateGate();
+    try {
+        const registry = refusedCreateHookDiscovery(create.cwd, create.profile);
+        const refusal = await invokeBlockingLifecycleHooks(registry.plans.get('node:create') ?? [], {
+            app, create,
+            runtime: { canvasHome: crtrHome(), profile: create.profile },
+        });
+        if (refusal !== null)
+            throw nodeCreateRefused(refusal.message, refusal.next);
+        return release;
+    }
+    catch (error) {
+        release();
+        throw error;
+    }
+}

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

@@ -0,0 +1,32 @@
+import type { PluginManifest } from '../../types.js';
+import type { HookDiscoveryIssue, HookPluginValidation } from './discovery.js';
+import type { DeclaredHook, DeclaredLifecycleHook } from './schema.js';
+export declare const HOOK_TRUST_WARNING = "Command hooks receive normalized inputs and may block or replace declared targets. Lifecycle hooks run unprompted at every declared event before node launch. Both run local executables with runtime authority and may transmit received data.";
+export interface HookDeclarationReport {
+    target: string;
+    phase: DeclaredHook['phase'];
+    op: string;
+    description: string;
+    effects: readonly string[];
+}
+export interface LifecycleHookDeclarationReport {
+    event: DeclaredLifecycleHook['event'];
+    phase: DeclaredLifecycleHook['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[];
+    /** Present only for schemaVersion 2 manifests. */
+    lifecycle?: readonly LifecycleHookDeclarationReport[];
+    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,28 @@
+export const HOOK_TRUST_WARNING = 'Command hooks receive normalized inputs and may block or replace declared targets. Lifecycle hooks run unprompted at every declared event before node launch. Both run local executables with runtime authority and may 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]),
+        }))),
+        ...(validation.manifest?.schemaVersion === 2 ? {
+            lifecycle: Object.freeze(validation.manifest.lifecycle.map((hook) => Object.freeze({
+                event: hook.event,
+                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,42 @@
+import { type LifecycleEvent, type LifecycleHookPhase } from './lifecycle-catalog.js';
+export type { LifecycleHookPhase } from './lifecycle-catalog.js';
+export type HookPhase = 'before' | 'after' | 'replace';
+export interface DeclaredHook {
+    target: string;
+    phase: HookPhase;
+    op: string;
+    description: string;
+    effects: string[];
+}
+export interface DeclaredLifecycleHook {
+    event: LifecycleEvent;
+    phase: LifecycleHookPhase;
+    op: string;
+    description: string;
+    effects: string[];
+}
+export interface ValidatedV1HookManifest {
+    schemaVersion: 1;
+    hooks: DeclaredHook[];
+}
+export interface ValidatedV2HookManifest {
+    schemaVersion: 2;
+    hooks: DeclaredHook[];
+    lifecycle: DeclaredLifecycleHook[];
+}
+export type ValidatedHookManifest = ValidatedV1HookManifest | ValidatedV2HookManifest;
+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,157 @@
+import { isRecord } from '../../shared/predicates.js';
+import { LIFECYCLE_CATALOG, LIFECYCLE_EVENTS, isLifecycleEvent } from './lifecycle-catalog.js';
+function typeName(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    return typeof value;
+}
+function validateCommandDeclaration(value, index, issue) {
+    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 undefined;
+    }
+    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 undefined;
+    }
+    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 undefined;
+        }
+    }
+    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 undefined;
+    }
+    if (!isEffects(value['effects'])) {
+        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 undefined;
+    }
+    return {
+        target: value['target'],
+        phase: value['phase'],
+        op: value['op'],
+        description: value['description'],
+        effects: value['effects'],
+    };
+}
+function validateLifecycleDeclaration(value, index, issue) {
+    const path = `lifecycle[${index}]`;
+    if (!isRecord(value)) {
+        issue('hook_manifest_invalid', 'lifecycle hook must be an object', typeName(value), '{ event, phase, op, description, effects }', 'Fix the lifecycle declaration.', path);
+        return undefined;
+    }
+    const keys = Object.keys(value).filter((key) => !['event', 'phase', 'op', 'description', 'effects'].includes(key));
+    if (keys.length > 0) {
+        issue('hook_manifest_invalid', 'unknown lifecycle hook keys', keys.join(', '), 'only: event, phase, op, description, effects', 'Remove the unknown keys.', path);
+        return undefined;
+    }
+    for (const field of ['event', '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 undefined;
+        }
+    }
+    if (!isLifecycleEvent(value['event'])) {
+        issue('hook_manifest_invalid', 'event must name a supported lifecycle event', String(value['event']), LIFECYCLE_EVENTS.join(' | '), `Set event to one of: ${LIFECYCLE_EVENTS.join(', ')}.`, `${path}.event`);
+        return undefined;
+    }
+    const phase = LIFECYCLE_CATALOG[value['event']].phase;
+    if (value['phase'] !== phase) {
+        issue('hook_manifest_invalid', `phase must be ${phase}`, String(value['phase']), phase, `Set phase to ${phase}.`, `${path}.phase`);
+        return undefined;
+    }
+    if (!isEffects(value['effects'])) {
+        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 undefined;
+    }
+    return {
+        event: value['event'],
+        phase,
+        op: value['op'],
+        description: value['description'],
+        effects: value['effects'],
+    };
+}
+function isEffects(value) {
+    return Array.isArray(value) && value.length > 0 && value.every((effect) => typeof effect === 'string' && effect.length > 0);
+}
+function validateV1(raw, issue) {
+    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 (!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 hook = validateCommandDeclaration(raw['hooks'][index], index, issue);
+        if (hook === undefined)
+            return { issues: [] };
+        hooks.push(hook);
+    }
+    return { manifest: { schemaVersion: 1, hooks }, issues: [] };
+}
+/** 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 };
+    }
+    if (raw['schemaVersion'] === 1) {
+        const validation = validateV1(raw, issue);
+        return { ...(validation.manifest === undefined ? {} : { manifest: validation.manifest }), issues };
+    }
+    if (raw['schemaVersion'] !== 2) {
+        issue('hook_schema_version', 'schemaVersion must be exactly 1 or 2', String(raw['schemaVersion']), '1 | 2', 'Update the manifest schema version to 1 or 2.', 'schemaVersion');
+        return { issues };
+    }
+    const unknown = Object.keys(raw).filter((key) => key !== 'schemaVersion' && key !== 'hooks' && key !== 'lifecycle');
+    if (unknown.length > 0) {
+        issue('hook_manifest_invalid', 'unknown top-level keys', unknown.join(', '), 'only: schemaVersion, hooks, lifecycle', 'Remove the unknown keys.');
+        return { issues };
+    }
+    const rawHooks = raw['hooks'];
+    const rawLifecycle = raw['lifecycle'];
+    if (rawHooks !== undefined && !Array.isArray(rawHooks)) {
+        issue('hook_manifest_invalid', 'hooks must be an array when present', typeName(rawHooks), 'an array of hook declarations', 'Fix hooks.', 'hooks');
+        return { issues };
+    }
+    if (rawLifecycle !== undefined && !Array.isArray(rawLifecycle)) {
+        issue('hook_manifest_invalid', 'lifecycle must be an array when present', typeName(rawLifecycle), 'an array of lifecycle hook declarations', 'Fix lifecycle.', 'lifecycle');
+        return { issues };
+    }
+    const hooks = rawHooks ?? [];
+    const lifecycle = rawLifecycle ?? [];
+    if (hooks.length === 0 && lifecycle.length === 0) {
+        issue('hook_manifest_invalid', 'hooks or lifecycle must be a non-empty array', 'both arrays were empty or absent', 'at least one command or lifecycle hook declaration', 'Declare at least one hook.', 'hooks');
+        return { issues };
+    }
+    const declaredHooks = [];
+    for (let index = 0; index < hooks.length; index++) {
+        const hook = validateCommandDeclaration(hooks[index], index, issue);
+        if (hook === undefined)
+            return { issues };
+        declaredHooks.push(hook);
+    }
+    const declaredLifecycle = [];
+    for (let index = 0; index < lifecycle.length; index++) {
+        const hook = validateLifecycleDeclaration(lifecycle[index], index, issue);
+        if (hook === undefined)
+            return { issues };
+        declaredLifecycle.push(hook);
+    }
+    return { manifest: { schemaVersion: 2, hooks: declaredHooks, lifecycle: declaredLifecycle }, issues };
+}

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

@@ -0,0 +1,24 @@
+import type { HookPhase } from '../../../hook-authoring.js';
+import type { Field } from '../../help.js';
+export declare const EXEC_HOOK_TIMEOUT_MS = 15000;
+export interface ExecHookSpec {
+    /** Identity resolved against the daemon's effective hook plan on Linux. */
+    id: string;
+    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>;