@north-light/crouter 0.3.220 → 0.3.222

package/dist/core/canvas/render.js

@@ -155,6 +155,8 @@ export function dashboardRows(rootId) {
         return [{
                 node_id: id,
                 name: fullName(node),
+                handle: node.name,
+                description: node.description,
                 status: node.status,
                 kind: node.kind,
                 mode: node.mode,
@@ -189,8 +191,11 @@ export function enrichRow(row) {
     if (row.enriched === true)
         return row;
     const meta = getNode(row.node_id);
-    if (meta !== null)
+    if (meta !== null) {
         row.name = fullName(meta);
+        row.handle = meta.name;
+        row.description = meta.description;
+    }
     row.ctx_tokens = readNodeTelemetry(row.node_id).tokens_in ?? 0;
     row.asks = countTickets(row.node_id);
     row.enriched = true;
@@ -206,8 +211,11 @@ export function enrichRows(rows) {
     const asks = ticketCountsForNodes(todo.map((r) => r.node_id));
     for (const row of todo) {
         const meta = getNode(row.node_id);
-        if (meta !== null)
+        if (meta !== null) {
             row.name = fullName(meta);
+            row.handle = meta.name;
+            row.description = meta.description;
+        }
         row.ctx_tokens = readNodeTelemetry(row.node_id).tokens_in ?? 0;
         row.asks = asks[row.node_id] ?? 0;
         row.enriched = true;

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

@@ -0,0 +1,10 @@
+import type { PluginManifest } from '../../types.js';
+import { type HookManifestIssue, type ValidatedHookManifest } from './schema.js';
+export interface HookArtifactValidation {
+    manifestPath?: string;
+    executablePath?: string;
+    manifest?: ValidatedHookManifest;
+    issues: HookManifestIssue[];
+}
+/** Statically validates the local hook artifact a source plugin ships. */
+export declare function validatePluginHookArtifact(root: string, manifest: Pick<PluginManifest, 'hooks' | 'hookExecutable'>): HookArtifactValidation;

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

@@ -0,0 +1,129 @@
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { isAbsolute, resolve, sep } from 'node:path';
+import { validateHookManifest } from './schema.js';
+function safeFilePath(root, pointer) {
+    if (isAbsolute(pointer))
+        return null;
+    try {
+        const rootReal = realpathSync(root);
+        const path = realpathSync(resolve(root, pointer));
+        return (path === rootReal || path.startsWith(rootReal + sep)) && statSync(path).isFile() ? path : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Statically validates the local hook artifact a source plugin ships. */
+export function validatePluginHookArtifact(root, manifest) {
+    const hooks = manifest.hooks;
+    const executable = manifest.hookExecutable;
+    const issues = [];
+    const hasHooks = hooks !== undefined;
+    const hasExecutable = executable !== undefined;
+    if (hasHooks !== hasExecutable) {
+        issues.push({
+            code: 'hook_manifest_invalid',
+            path: hasHooks ? 'hookExecutable' : 'hooks',
+            message: 'hooks and hookExecutable must be declared together',
+            received: hasHooks ? 'hooks without hookExecutable' : 'hookExecutable without hooks',
+            expected: 'both hooks and hookExecutable',
+            next: hasHooks ? 'Add plugin.json.hookExecutable or remove hooks.' : 'Add plugin.json.hooks or remove hookExecutable.',
+        });
+        return { issues };
+    }
+    if (!hasHooks)
+        return { issues };
+    if (typeof hooks !== 'string' || hooks.length === 0) {
+        issues.push({
+            code: 'hook_manifest_invalid',
+            path: 'hooks',
+            message: 'hooks must be a non-empty plugin-root-relative path',
+            received: typeof hooks === 'string' ? '(empty)' : Array.isArray(hooks) ? 'array' : typeof hooks,
+            expected: 'a non-empty relative path to hooks.json',
+            next: 'Fix plugin.json.hooks.',
+        });
+    }
+    if (typeof executable !== 'string' || executable.length === 0) {
+        issues.push({
+            code: 'hook_manifest_invalid',
+            path: 'hookExecutable',
+            message: 'hookExecutable must be a non-empty plugin-root-relative path',
+            received: typeof executable === 'string' ? '(empty)' : Array.isArray(executable) ? 'array' : typeof executable,
+            expected: 'a non-empty relative path to an executable file',
+            next: 'Fix plugin.json.hookExecutable.',
+        });
+    }
+    if (issues.length > 0)
+        return { issues };
+    const hooksPointer = hooks;
+    const executablePointer = executable;
+    const manifestPath = safeFilePath(root, hooksPointer);
+    if (manifestPath === null) {
+        issues.push({
+            code: 'hook_path_unsafe',
+            path: 'hooks',
+            message: 'hooks pointer escapes the plugin root or is not a regular file',
+            received: hooksPointer,
+            expected: 'a relative path to a regular file inside the plugin root',
+            next: 'Fix plugin.json.hooks.',
+        });
+    }
+    const executablePath = safeFilePath(root, executablePointer);
+    if (executablePath === null) {
+        issues.push({
+            code: 'hook_path_unsafe',
+            path: 'hookExecutable',
+            message: 'hookExecutable escapes the plugin root or is not a regular file',
+            received: executablePointer,
+            expected: 'a relative path to a regular file inside the plugin root',
+            next: 'Fix plugin.json.hookExecutable.',
+        });
+    }
+    if (executablePath !== null && (statSync(executablePath).mode & 0o111) === 0) {
+        issues.push({
+            code: 'hook_not_executable',
+            path: 'hookExecutable',
+            message: 'hookExecutable lacks the POSIX exec bit',
+            received: executablePointer,
+            expected: 'a file with an executable permission bit',
+            next: 'chmod +x the hook executable, then update the plugin.',
+        });
+    }
+    if (manifestPath === null)
+        return { ...(executablePath === null ? {} : { executablePath }), issues };
+    let text;
+    try {
+        text = readFileSync(manifestPath, 'utf8');
+    }
+    catch {
+        issues.push({
+            code: 'hook_manifest_unreadable',
+            message: 'hooks.json is missing or unreadable',
+            received: manifestPath,
+            expected: 'a readable JSON file',
+            next: 'Reinstall or update the plugin.',
+        });
+        return { manifestPath, ...(executablePath === null ? {} : { executablePath }), issues };
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        issues.push({
+            code: 'hook_manifest_invalid',
+            message: 'hooks.json is not valid JSON',
+            received: manifestPath,
+            expected: 'a JSON object',
+            next: 'Regenerate hooks.json.',
+        });
+        return { manifestPath, ...(executablePath === null ? {} : { executablePath }), issues };
+    }
+    const validation = validateHookManifest(raw);
+    return {
+        manifestPath,
+        ...(executablePath === null ? {} : { executablePath }),
+        ...(validation.manifest === undefined ? {} : { manifest: validation.manifest }),
+        issues: [...issues, ...validation.issues],
+    };
+}

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

@@ -0,0 +1,14 @@
+import type { BranchDef, LeafDef } from '../command.js';
+export interface CoreHookTarget {
+    /** Exact space-joined core leaf path named by hooks.json. */
+    path: string;
+    segments: readonly string[];
+    leaf: LeafDef;
+}
+export interface CoreHookCatalog {
+    targets: readonly CoreHookTarget[];
+    byPath: ReadonlyMap<string, CoreHookTarget>;
+    has(path: string): boolean;
+}
+/** Projects every composed core subtree to leaves whose objects flow through central rendering. */
+export declare function createCoreHookCatalog(subtrees: readonly BranchDef[]): CoreHookCatalog;

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

@@ -0,0 +1,38 @@
+const NON_RETURNING_OBJECT_LEAVES = new Set([
+    'pkg browse',
+    'sys settings',
+    'sys setup',
+    'canvas browse',
+    'surface inspect',
+]);
+function excluded(path) {
+    return path === 'sys doctor'
+        || path === 'pkg plugin'
+        || path.startsWith('pkg plugin ')
+        || NON_RETURNING_OBJECT_LEAVES.has(path);
+}
+/** Projects every composed core subtree to leaves whose objects flow through central rendering. */
+export function createCoreHookCatalog(subtrees) {
+    const targets = [];
+    const visit = (node, segments) => {
+        const path = segments.join(' ');
+        if (node.kind === 'leaf') {
+            if (node.help.outputKind === 'object' && node.hookEligible !== false && !excluded(path)) {
+                targets.push({ path, segments: Object.freeze([...segments]), leaf: node });
+            }
+            return;
+        }
+        if (node.passthrough !== undefined || excluded(path))
+            return;
+        for (const child of node.children)
+            visit(child, [...segments, child.name]);
+    };
+    for (const subtree of subtrees)
+        visit(subtree, [subtree.name]);
+    const byPath = new Map(targets.map((target) => [target.path, target]));
+    return Object.freeze({
+        targets: Object.freeze(targets),
+        byPath,
+        has: (path) => byPath.has(path),
+    });
+}

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

@@ -0,0 +1,15 @@
+import type { BranchDef } from '../command.js';
+import type { HookRegistry } from './discovery.js';
+/** Registry compilation never executes hook code. */
+export type HookRegistryLoader = () => Promise<HookRegistry>;
+/** Wrap every hook-eligible core leaf so its run is the before → primary →
+ *  after pipeline. Nothing else about the leaf changes: path, params, frozen
+ *  help, renderer, and output declaration are carried through untouched, and
+ *  ineligible leaves (JSONL, UI/void, `pkg plugin`, `sys doctor`, passthrough)
+ *  keep their original run function so recovery dispatch never depends on hook
+ *  discovery.
+ *
+ *  Eligibility is per-path, so projecting the passed subtrees answers it for
+ *  those subtrees exactly as the complete catalog would; the complete catalog
+ *  is what the loaded registry validates hook targets against. */
+export declare function composeCoreHooks(subtrees: readonly BranchDef[], loadRegistry: HookRegistryLoader): BranchDef[];

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

@@ -0,0 +1,99 @@
+import { ExitCode } from '../../types.js';
+import { CrtrError } from '../errors.js';
+import { operationIdContext } from '../events/operation-id.js';
+import { createCoreHookCatalog } from './catalog.js';
+/** Wrap every hook-eligible core leaf so its run is the before → primary →
+ *  after pipeline. Nothing else about the leaf changes: path, params, frozen
+ *  help, renderer, and output declaration are carried through untouched, and
+ *  ineligible leaves (JSONL, UI/void, `pkg plugin`, `sys doctor`, passthrough)
+ *  keep their original run function so recovery dispatch never depends on hook
+ *  discovery.
+ *
+ *  Eligibility is per-path, so projecting the passed subtrees answers it for
+ *  those subtrees exactly as the complete catalog would; the complete catalog
+ *  is what the loaded registry validates hook targets against. */
+export function composeCoreHooks(subtrees, loadRegistry) {
+    const eligible = createCoreHookCatalog(subtrees);
+    const visit = (node, segments) => {
+        if (node.kind === 'leaf') {
+            const path = segments.join(' ');
+            if (!eligible.has(path))
+                return node;
+            return Object.freeze({
+                ...node,
+                effectiveHelp: projectedHelp(node, path, loadRegistry),
+                run: hookedRun(node, segments, loadRegistry),
+            });
+        }
+        return { ...node, children: node.children.map((child) => visit(child, [...segments, child.name])) };
+    };
+    return subtrees.map((subtree) => visit(subtree, [subtree.name]));
+}
+function projectedHelp(leaf, path, loadRegistry) {
+    return async () => {
+        const { projectEffectiveLeafHelp } = await import('./help.js');
+        try {
+            const registry = await loadRegistry();
+            // Invalid configuration fails closed on dispatch, but help remains the
+            // bounded static core contract so recovery is never stranded.
+            return projectEffectiveLeafHelp(leaf.help, registry.valid ? registry.plans.get(path) : undefined);
+        }
+        catch {
+            return projectEffectiveLeafHelp(leaf.help);
+        }
+    };
+}
+function hookedRun(leaf, segments, loadRegistry) {
+    const core = leaf.run;
+    const path = segments.join(' ');
+    return async (input, context) => {
+        const registry = await loadRegistry();
+        if (!registry.valid)
+            throw registryError(path, registry.issues);
+        const plan = registry.plans.get(path);
+        if (plan === undefined)
+            return core(input, context);
+        // The one fresh operation identity runCli already entered surrounds this
+        // whole pipeline; hooks and the core primary share that ambient ID.
+        const operationId = operationIdContext.current();
+        if (operationId === undefined)
+            throw new CrtrError('internal', `\`${path}\` ran outside a crouter operation identity, so its plugin hooks cannot be dispatched.`, ExitCode.GENERAL, { command: [...segments] });
+        const { invokeExecHook } = await import('./transport/exec-invoke.js');
+        const spec = (hook) => ({
+            plugin: hook.plugin.name,
+            executable: hook.executable,
+            op: hook.op,
+            phase: hook.phase,
+            commandPath: segments,
+            ...(hook.phase === 'replace' ? { output: leaf.help.output } : {}),
+        });
+        const providedParams = [...(context?.providedParams ?? [])];
+        for (const hook of plan.before)
+            await invokeExecHook(spec(hook), { operationId, input, providedParams });
+        const replacement = plan.replacements[0];
+        const result = replacement === undefined
+            ? await core(input, context)
+            : await invokeExecHook(spec(replacement), { operationId, input, providedParams });
+        // `after` is reverse discovery order, preserving middleware nesting.
+        for (const hook of plan.after)
+            await invokeExecHook(spec(hook), { operationId, input, providedParams, ...(result === undefined ? {} : { result }) });
+        return result;
+    };
+}
+/** Fail closed on an invalid manifest, stale target, or replacement collision:
+ *  silently dropping a declared hook would run the command without behavior the
+ *  caller expects. Every issue is spelled out in the message, because the
+ *  central error payload carries only code/message/received/field/next — an
+ *  issue list parked in `details` would never reach the caller. */
+function registryError(path, issues) {
+    const first = issues[0];
+    const detail = issues
+        .map((issue) => `${issue.plugin} (${issue.scope}) ${issue.path ?? 'hooks'}: ${issue.message} — received ${issue.received}, expected ${issue.expected}`)
+        .join('; ');
+    const plugins = [...new Set(issues.map((issue) => issue.plugin))];
+    return new CrtrError(first.code, `\`${path}\` cannot run: ${String(issues.length)} unusable hook declaration${issues.length === 1 ? '' : 's'} — ${detail}.`, ExitCode.GENERAL, {
+        received: first.received,
+        ...(first.path === undefined ? {} : { field: first.path }),
+        next: `${first.next} ${plugins.map((plugin) => `\`crtr pkg plugin show ${plugin}\``).join(' and ')} or \`crtr sys doctor\` reports the same issues; disabling the plugin also clears them.`,
+    });
+}

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

@@ -0,0 +1,87 @@
+import type { InstalledPlugin } from '../../types.js';
+import type { CoreHookCatalog } from './catalog.js';
+import type { HookManifestIssue, HookPhase, ValidatedHookManifest } from './schema.js';
+export type HookDiscoveryIssueCode = HookManifestIssue['code'] | 'command_hook_target_invalid' | 'command_hook_collision';
+export interface HookDiscoveryIssue {
+    code: HookDiscoveryIssueCode;
+    plugin: string;
+    scope: 'project' | 'user';
+    path?: string;
+    message: string;
+    received: string;
+    expected: string;
+    next: string;
+}
+export interface HookPluginAttribution {
+    name: string;
+    scope: 'project' | 'user';
+    root: string;
+}
+/** One declaration resolved to the local executable that will receive it. */
+export interface EffectiveHook {
+    executable: string;
+    plugin: HookPluginAttribution;
+    target: string;
+    phase: HookPhase;
+    op: string;
+    description: string;
+    effects: readonly string[];
+    /** Index in this plugin's hooks.json declaration array. */
+    declarationIndex: number;
+    /** Stable discovery order: scope, lexical plugin name, declaration index. */
+    order: number;
+}
+export interface EffectiveHookPlan {
+    target: string;
+    before: readonly EffectiveHook[];
+    /** Reverse discovery order: execute directly after the primary. */
+    after: readonly EffectiveHook[];
+    replacements: readonly EffectiveHook[];
+}
+export interface HookPluginValidation {
+    plugin: InstalledPlugin;
+    manifestPath?: string;
+    executablePath?: string;
+    manifest?: ValidatedHookManifest;
+    hooks: readonly EffectiveHook[];
+    issues: readonly HookDiscoveryIssue[];
+}
+export interface HookRegistry {
+    catalog: CoreHookCatalog;
+    hooks: readonly EffectiveHook[];
+    plans: ReadonlyMap<string, EffectiveHookPlan>;
+    validations: readonly HookPluginValidation[];
+    issues: readonly HookDiscoveryIssue[];
+    valid: boolean;
+}
+export interface HookScope {
+    scope: 'project' | 'user';
+    root: string;
+}
+/** Project scopes nearest-outward, followed by the user scope. */
+export declare function hookDiscoveryScopes(startDir?: string, profileId?: string | null): HookScope[];
+/** Effective enabled hook plugins, with disabled nearest copies still shadowing outer copies. */
+export declare function effectiveHookPlugins(startDir?: string, profileId?: string | null): InstalledPlugin[];
+/** Effective hook plugins with one source-install candidate taking the exact
+ *  scope/name slot it would occupy after activation. The candidate remains
+ *  subject to normal nearer-scope shadowing and no plugin code is executed. */
+export interface HookPluginCandidate {
+    plugin: InstalledPlugin;
+    scopeRoot: string;
+}
+/**
+ * Statically compiles hooks from already-resolved effective plugins. It reads
+ * manifest files to validate them but never executes a plugin executable.
+ */
+export declare function compileHookRegistry(catalog: CoreHookCatalog, plugins: readonly InstalledPlugin[]): HookRegistry;
+/** Discovers and compiles the invocation-local effective registry. */
+export declare function discoverHookRegistry(catalog: CoreHookCatalog, startDir?: string, profileId?: string | null): HookRegistry;
+/** Compile the exact effective set a source candidate would create before its
+ *  bytes replace the installed plugin. */
+export declare function discoverCandidateHookRegistry(catalog: CoreHookCatalog, candidate: InstalledPlugin, scopeRoot: string, startDir?: string, profileId?: string | null): HookRegistry;
+/** 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 declare function discoverCandidateHookRegistryForCandidates(catalog: CoreHookCatalog, candidates: readonly HookPluginCandidate[], startDir?: string, profileId?: string | null): HookRegistry;
+/** Fixture-friendly discovery seam; production callers should use discoverHookRegistry. */
+export declare function discoverHookRegistryInScopes(catalog: CoreHookCatalog, scopes: readonly HookScope[]): HookRegistry;

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

@@ -0,0 +1,174 @@
+import { listInstalledPluginsInRoot } from '../resolver.js';
+import { projectScopeRoots, userScopeRoot } from '../scope.js';
+import { validatePluginHookArtifact } from './artifact.js';
+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 })),
+        { 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;
+}
+/**
+ * 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) {
+    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({
+                    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 }),
+            hooks: Object.freeze(compiled),
+            issues: Object.freeze(pluginIssues),
+        }));
+        issues.push(...pluginIssues);
+    }
+    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,
+    });
+}
+/** 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, LeafHelp } 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: LeafHelp, 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/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';