@north-light/crouter 0.3.219 → 0.3.221

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';

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>;