@qduc/term2 0.11.1 → 0.13.0

package/dist/services/hooks/hook-module-loader.js

@@ -0,0 +1,69 @@
+import { pathToFileURL } from 'node:url';
+export class HookModuleLoadError extends Error {
+    path;
+    constructor(path, message, options) {
+        super(`${message}: ${path}`, options);
+        this.name = 'HookModuleLoadError';
+        this.path = path;
+    }
+}
+function registrationFromModule(path, moduleValue) {
+    const candidate = typeof moduleValue === 'function'
+        ? moduleValue
+        : typeof moduleValue === 'object' && moduleValue !== null
+            ? moduleValue.default
+            : undefined;
+    if (typeof candidate !== 'function') {
+        throw new HookModuleLoadError(path, 'Hook module must default-export a registration function');
+    }
+    return candidate;
+}
+/**
+ * Loader for environments where Node's native ESM loader can evaluate the
+ * discovered file (notably JavaScript, and TypeScript under an embedding
+ * loader). It is intentionally injected so the application does not depend on
+ * its development-only tsx runner.
+ */
+export class NativeHookModuleLoader {
+    #importer;
+    constructor(importer) {
+        this.#importer = importer ?? ((path) => import(pathToFileURL(path).href));
+    }
+    async load(path) {
+        let moduleValue;
+        try {
+            moduleValue = await this.#importer(path);
+        }
+        catch (error) {
+            throw new HookModuleLoadError(path, 'Could not evaluate hook module', { cause: error });
+        }
+        return registrationFromModule(path, moduleValue);
+    }
+}
+/**
+ * Adapter for a production jiti instance. jiti is deliberately not imported
+ * here: it is an optional application composition dependency, while tests and
+ * embedders can provide the same small callable interface without installing
+ * it. The adapter supports both jiti's synchronous result and async wrappers.
+ */
+export class JitiHookModuleLoader {
+    #loadWithJiti;
+    constructor(loadWithJiti) {
+        if (typeof loadWithJiti !== 'function') {
+            throw new TypeError('A jiti module loader function is required');
+        }
+        this.#loadWithJiti = loadWithJiti;
+    }
+    async load(path) {
+        let moduleValue;
+        try {
+            moduleValue = await this.#loadWithJiti(path);
+        }
+        catch (error) {
+            throw new HookModuleLoadError(path, 'Could not evaluate hook module', { cause: error });
+        }
+        return registrationFromModule(path, moduleValue);
+    }
+}
+export const validateHookModuleDefaultExport = registrationFromModule;
+//# sourceMappingURL=hook-module-loader.js.map

package/dist/services/hooks/hook-module-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-module-loader.js","sourceRoot":"","sources":["../../../source/services/hooks/hook-module-loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAYzC,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,OAAe,EAAE,OAAsC;QAC/E,KAAK,CAAC,GAAG,OAAO,KAAK,IAAI,EAAE,EAAE,OAAO,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAED,SAAS,sBAAsB,CAAC,IAAY,EAAE,WAAoB;IAChE,MAAM,SAAS,GACb,OAAO,WAAW,KAAK,UAAU;QAC/B,CAAC,CAAC,WAAW;QACb,CAAC,CAAC,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,KAAK,IAAI;YACzD,CAAC,CAAE,WAAqC,CAAC,OAAO;YAChD,CAAC,CAAC,SAAS,CAAC;IAEhB,IAAI,OAAO,SAAS,KAAK,UAAU,EAAE,CAAC;QACpC,MAAM,IAAI,mBAAmB,CAAC,IAAI,EAAE,yDAAyD,CAAC,CAAC;IACjG,CAAC;IACD,OAAO,SAAkC,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,OAAO,sBAAsB;IACxB,SAAS,CAAqB;IAEvC,YAAY,QAA6B;QACvC,IAAI,CAAC,SAAS,GAAG,QAAQ,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5E,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,IAAI,WAAoB,CAAC;QACzB,IAAI,CAAC;YACH,WAAW,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC3C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,mBAAmB,CAAC,IAAI,EAAE,gCAAgC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1F,CAAC;QACD,OAAO,sBAAsB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IACnD,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,oBAAoB;IACtB,aAAa,CAAmB;IAEzC,YAAY,YAA8B;QACxC,IAAI,OAAO,YAAY,KAAK,UAAU,EAAE,CAAC;YACvC,MAAM,IAAI,SAAS,CAAC,2CAA2C,CAAC,CAAC;QACnE,CAAC;QACD,IAAI,CAAC,aAAa,GAAG,YAAY,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,IAAY;QACrB,IAAI,WAAoB,CAAC;QACzB,IAAI,CAAC;YACH,WAAW,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC;QAC/C,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,mBAAmB,CAAC,IAAI,EAAE,gCAAgC,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1F,CAAC;QACD,OAAO,sBAAsB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IACnD,CAAC;CACF;AAED,MAAM,CAAC,MAAM,+BAA+B,GAAG,sBAAsB,CAAC"}

package/dist/services/hooks/hook-registry.d.ts

@@ -0,0 +1,47 @@
+import type { Term2HookEvent, Term2HookEventName, Term2HookRegistration } from './hook-contracts.js';
+export declare const DEFAULT_HOOK_CALLBACK_TIMEOUT_MS = 5000;
+export interface HookRegistrationSource {
+    readonly path?: string;
+    readonly scope?: 'user' | 'project' | string;
+}
+export interface HookDiagnostic {
+    readonly code: 'registration_rejected' | 'callback_failed' | 'callback_timed_out' | 'diagnostic_logger_failed' | 'duplicate_event' | 'discovery_failed' | 'symlink_rejected' | 'project_hooks_untrusted' | 'hook_disabled' | 'module_load_failed';
+    readonly message: string;
+    readonly source?: HookRegistrationSource;
+    readonly eventType?: Term2HookEventName;
+    readonly callbackIndex?: number;
+    readonly eventId?: string;
+    readonly durationMs?: number;
+    readonly error?: unknown;
+}
+export type HookDiagnosticLogger = (diagnostic: HookDiagnostic) => void;
+export interface HookRegistryOptions {
+    readonly callbackTimeoutMs?: number;
+    readonly logger?: HookDiagnosticLogger;
+}
+export declare class HookRegistrationClosedError extends Error {
+    constructor();
+}
+/**
+ * Ordered, passive callback registry.  A registry deliberately has no
+ * behavior-changing callback result: callbacks are observed and failures are
+ * isolated from the application and from one another.
+ */
+export declare class HookRegistry {
+    #private;
+    constructor(options?: HookRegistryOptions);
+    get callbackTimeoutMs(): number;
+    get size(): number;
+    /**
+     * Load one module's registration function transactionally.  If registration
+     * throws, every callback added by that module is removed before the error is
+     * rethrown to the service, so a broken file cannot leave a partial module.
+     */
+    register(source: string | HookRegistrationSource | Term2HookRegistration, registration?: HookRegistrationSource | Term2HookRegistration): Promise<void>;
+    /** Alias that makes the transactional boundary explicit at call sites. */
+    registerModule(source: string | HookRegistrationSource, registration: Term2HookRegistration): Promise<void>;
+    dispatch<Name extends Term2HookEventName>(event: Term2HookEvent<Name>): Promise<void>;
+    /** Remove all callbacks and make a future service run start cleanly. */
+    clear(): void;
+}
+//# sourceMappingURL=hook-registry.d.ts.map

package/dist/services/hooks/hook-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-registry.d.ts","sourceRoot":"","sources":["../../../source/services/hooks/hook-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EAEtB,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,gCAAgC,OAAQ,CAAC;AAEtD,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;CAC9C;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EACT,uBAAuB,GACvB,iBAAiB,GACjB,oBAAoB,GACpB,0BAA0B,GAC1B,iBAAiB,GACjB,kBAAkB,GAClB,kBAAkB,GAClB,yBAAyB,GACzB,eAAe,GACf,oBAAoB,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,sBAAsB,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,kBAAkB,CAAC;IACxC,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,oBAAoB,GAAG,CAAC,UAAU,EAAE,cAAc,KAAK,IAAI,CAAC;AAExE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC;CACxC;AAED,qBAAa,2BAA4B,SAAQ,KAAK;IACpD,cAGC;CACF;AAoBD;;;;GAIG;AACH,qBAAa,YAAY;;IAOvB,YAAY,OAAO,GAAE,mBAAwB,EAO5C;IAED,IAAI,iBAAiB,IAAI,MAAM,CAE9B;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;OAIG;IACG,QAAQ,CACZ,MAAM,EAAE,MAAM,GAAG,sBAAsB,GAAG,qBAAqB,EAC/D,YAAY,CAAC,EAAE,sBAAsB,GAAG,qBAAqB,GAC5D,OAAO,CAAC,IAAI,CAAC,CAoCf;IAED,0EAA0E;IAC1E,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,sBAAsB,EAAE,YAAY,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE1G;IAEK,QAAQ,CAAC,IAAI,SAAS,kBAAkB,EAAE,KAAK,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAmB1F;IAED,wEAAwE;IACxE,KAAK,IAAI,IAAI,CAIZ;CAgFF"}

package/dist/services/hooks/hook-registry.js

@@ -0,0 +1,185 @@
+export const DEFAULT_HOOK_CALLBACK_TIMEOUT_MS = 5_000;
+export class HookRegistrationClosedError extends Error {
+    constructor() {
+        super('Term2Hooks.on() may only be called while a hook registration function is running');
+        this.name = 'HookRegistrationClosedError';
+    }
+}
+function normalizeSource(source) {
+    if (source === undefined)
+        return undefined;
+    return typeof source === 'string' ? { path: source } : source;
+}
+/**
+ * Ordered, passive callback registry.  A registry deliberately has no
+ * behavior-changing callback result: callbacks are observed and failures are
+ * isolated from the application and from one another.
+ */
+export class HookRegistry {
+    #callbacks = [];
+    #seenEventIds = new Set();
+    #timeoutMs;
+    #logger;
+    #activeFrame;
+    constructor(options = {}) {
+        const timeoutMs = options.callbackTimeoutMs ?? DEFAULT_HOOK_CALLBACK_TIMEOUT_MS;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            throw new RangeError('Hook callback timeout must be a finite number greater than zero');
+        }
+        this.#timeoutMs = timeoutMs;
+        this.#logger = options.logger;
+    }
+    get callbackTimeoutMs() {
+        return this.#timeoutMs;
+    }
+    get size() {
+        return this.#callbacks.filter((callback) => callback.active).length;
+    }
+    /**
+     * Load one module's registration function transactionally.  If registration
+     * throws, every callback added by that module is removed before the error is
+     * rethrown to the service, so a broken file cannot leave a partial module.
+     */
+    async register(source, registration) {
+        let registrationFunction;
+        let registrationSource;
+        if (typeof source === 'function') {
+            registrationFunction = source;
+            registrationSource = normalizeSource(registration);
+        }
+        else {
+            if (typeof registration !== 'function') {
+                throw new TypeError('A hook registration function is required');
+            }
+            registrationFunction = registration;
+            registrationSource = normalizeSource(source);
+        }
+        if (this.#activeFrame) {
+            throw new Error('Hook registrations cannot run concurrently');
+        }
+        const frame = { source: registrationSource, callbacks: [], active: true };
+        this.#activeFrame = frame;
+        try {
+            await registrationFunction(this.#createRegistrar(frame));
+        }
+        catch (error) {
+            for (const callback of frame.callbacks)
+                callback.active = false;
+            this.#log({
+                code: 'registration_rejected',
+                message: 'Hook registration failed; all callbacks from the module were rolled back',
+                source: frame.source,
+                error,
+            });
+            throw error;
+        }
+        finally {
+            frame.active = false;
+            if (this.#activeFrame === frame)
+                this.#activeFrame = undefined;
+        }
+    }
+    /** Alias that makes the transactional boundary explicit at call sites. */
+    registerModule(source, registration) {
+        return this.register(source, registration);
+    }
+    async dispatch(event) {
+        if (this.#seenEventIds.has(event.eventId)) {
+            this.#log({
+                code: 'duplicate_event',
+                message: 'Skipped a hook event whose eventId had already been dispatched',
+                eventType: event.type,
+                eventId: event.eventId,
+            });
+            return;
+        }
+        this.#seenEventIds.add(event.eventId);
+        // Keep the registration order, but consult active at invocation time so an
+        // unsubscribe from an earlier callback takes effect immediately.
+        for (let index = 0; index < this.#callbacks.length; index += 1) {
+            const registered = this.#callbacks[index];
+            if (!registered.active || registered.event !== event.type)
+                continue;
+            await this.#dispatchOne(registered, event, index);
+        }
+    }
+    /** Remove all callbacks and make a future service run start cleanly. */
+    clear() {
+        for (const callback of this.#callbacks)
+            callback.active = false;
+        this.#callbacks.length = 0;
+        this.#seenEventIds.clear();
+    }
+    #createRegistrar(frame) {
+        return {
+            on: (event, callback) => {
+                if (!frame.active || this.#activeFrame !== frame)
+                    throw new HookRegistrationClosedError();
+                if (typeof callback !== 'function')
+                    throw new TypeError('A hook callback must be a function');
+                const registered = {
+                    event,
+                    callback: callback,
+                    source: frame.source,
+                    active: true,
+                };
+                frame.callbacks.push(registered);
+                this.#callbacks.push(registered);
+                return () => {
+                    registered.active = false;
+                };
+            },
+        };
+    }
+    async #dispatchOne(registered, event, callbackIndex) {
+        const startedAt = Date.now();
+        let timer;
+        // Attach a rejection handler to the callback promise before racing it.  A
+        // timed-out callback may continue running, and its eventual rejection must
+        // not become an unhandled rejection.
+        const callbackPromise = Promise.resolve()
+            .then(() => registered.callback(event))
+            .then(() => undefined, (error) => {
+            this.#log({
+                code: 'callback_failed',
+                message: 'Hook callback failed; continuing with the next callback',
+                source: registered.source,
+                eventType: event.type,
+                callbackIndex,
+                eventId: event.eventId,
+                durationMs: Date.now() - startedAt,
+                error,
+            });
+        });
+        const timeoutPromise = new Promise((resolve) => {
+            timer = setTimeout(() => resolve('timeout'), this.#timeoutMs);
+        });
+        const result = await Promise.race([callbackPromise.then(() => 'callback'), timeoutPromise]);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        if (result === 'timeout') {
+            this.#log({
+                code: 'callback_timed_out',
+                message: 'Hook callback timed out; the in-process callback cannot be cancelled and may continue running',
+                source: registered.source,
+                eventType: event.type,
+                callbackIndex,
+                eventId: event.eventId,
+                durationMs: Date.now() - startedAt,
+            });
+        }
+    }
+    #log(diagnostic) {
+        if (!this.#logger)
+            return;
+        try {
+            this.#logger(diagnostic);
+        }
+        catch (error) {
+            // Diagnostics must never turn a passive hook failure into an application
+            // failure. There is nowhere safe to report a logger failure from here.
+            void error;
+        }
+    }
+}
+//# sourceMappingURL=hook-registry.js.map

package/dist/services/hooks/hook-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-registry.js","sourceRoot":"","sources":["../../../source/services/hooks/hook-registry.ts"],"names":[],"mappings":"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"}

package/dist/services/hooks/hook-service.d.ts

@@ -0,0 +1,44 @@
+import type { Term2HookEvent, Term2HookEventName } from './hook-contracts.js';
+import { type HookDiscoveryOptions, type HookDiscoveryResult } from './hook-discovery.js';
+import { HookRegistry, type HookDiagnostic, type HookDiagnosticLogger, type HookRegistryOptions } from './hook-registry.js';
+import { type HookModuleLoader } from './hook-module-loader.js';
+export interface HookServiceOptions {
+    readonly discovery?: HookDiscoveryPort;
+    readonly discoveryOptions?: HookDiscoveryOptions;
+    readonly moduleLoader?: HookModuleLoader;
+    readonly registry?: HookRegistry;
+    readonly registryOptions?: HookRegistryOptions;
+    readonly logger?: HookDiagnosticLogger;
+}
+export interface HookDiscoveryPort {
+    discover(): Promise<HookDiscoveryResult>;
+}
+export interface HookStartupResult {
+    readonly loadedFiles: readonly string[];
+    readonly skippedFiles: readonly string[];
+    readonly diagnostics: readonly HookDiagnostic[];
+}
+export interface HookLifecyclePort {
+    emit<Name extends Term2HookEventName>(event: Term2HookEvent<Name>): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Composition boundary for public hooks. Discovery and module evaluation live
+ * here; lifecycle owners only need the HookLifecyclePort and never need to
+ * know where callbacks came from.
+ */
+export declare class HookService implements HookLifecyclePort {
+    #private;
+    constructor(options?: HookServiceOptions);
+    get registry(): HookRegistry;
+    get started(): boolean;
+    get startupResult(): HookStartupResult | undefined;
+    /** Load and register all hooks once, preserving discovery order. */
+    start(): Promise<HookStartupResult>;
+    /** Alias for callers that describe startup as initialization. */
+    initialize(): Promise<HookStartupResult>;
+    emit<Name extends Term2HookEventName>(event: Term2HookEvent<Name>): Promise<void>;
+    shutdown(): Promise<void>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=hook-service.d.ts.map

package/dist/services/hooks/hook-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-service.d.ts","sourceRoot":"","sources":["../../../source/services/hooks/hook-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC9E,OAAO,EAEL,KAAK,oBAAoB,EAEzB,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,YAAY,EACZ,KAAK,cAAc,EACnB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAwB,KAAK,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGtF,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,iBAAiB,CAAC;IACvC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;IACjD,QAAQ,CAAC,YAAY,CAAC,EAAE,gBAAgB,CAAC;IACzC,QAAQ,CAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,mBAAmB,CAAC;IAC/C,QAAQ,CAAC,MAAM,CAAC,EAAE,oBAAoB,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,WAAW,EAAE,SAAS,cAAc,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,IAAI,SAAS,kBAAkB,EAAE,KAAK,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClF,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3B;AAED;;;;GAIG;AACH,qBAAa,WAAY,YAAW,iBAAiB;;IASnD,YAAY,OAAO,GAAE,kBAAuB,EAa3C;IAED,IAAI,QAAQ,IAAI,YAAY,CAE3B;IAED,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,IAAI,aAAa,IAAI,iBAAiB,GAAG,SAAS,CAEjD;IAED,oEAAoE;IAC9D,KAAK,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAkExC;IAED,iEAAiE;IACjE,UAAU,IAAI,OAAO,CAAC,iBAAiB,CAAC,CAEvC;IAEK,IAAI,CAAC,IAAI,SAAS,kBAAkB,EAAE,KAAK,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAGtF;IAEK,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC,CAI9B;IAED,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAEvB;CAUF"}

package/dist/services/hooks/hook-service.js

@@ -0,0 +1,138 @@
+import { HookDiscovery, } from './hook-discovery.js';
+import { HookRegistry, } from './hook-registry.js';
+import { JitiHookModuleLoader } from './hook-module-loader.js';
+import { ensureHookEditorShim } from './hook-editor-shim.js';
+/**
+ * Composition boundary for public hooks. Discovery and module evaluation live
+ * here; lifecycle owners only need the HookLifecyclePort and never need to
+ * know where callbacks came from.
+ */
+export class HookService {
+    #discovery;
+    #moduleLoader;
+    #registry;
+    #logger;
+    #started = false;
+    #shutdown = false;
+    #startupResult;
+    constructor(options = {}) {
+        this.#logger = options.logger;
+        this.#discovery = options.discovery ?? new HookDiscovery(options.discoveryOptions);
+        this.#moduleLoader =
+            options.moduleLoader ??
+                new JitiHookModuleLoader((path) => {
+                    // jiti is a production dependency so packaged/global Term2 installs can
+                    // load TypeScript hooks without relying on the development tsx runner.
+                    // Keep the import lazy so embedders that inject a loader need not pay the
+                    // module initialization cost.
+                    return import('jiti').then(({ createJiti }) => createJiti(import.meta.url, { interopDefault: true })(path));
+                });
+        this.#registry = options.registry ?? new HookRegistry({ ...options.registryOptions, logger: options.logger });
+    }
+    get registry() {
+        return this.#registry;
+    }
+    get started() {
+        return this.#started;
+    }
+    get startupResult() {
+        return this.#startupResult;
+    }
+    /** Load and register all hooks once, preserving discovery order. */
+    async start() {
+        if (this.#shutdown)
+            throw new Error('HookService has already been shut down');
+        if (this.#startupResult)
+            return this.#startupResult;
+        const diagnostics = [];
+        const loadedFiles = [];
+        const skippedFiles = [];
+        let discovered = [];
+        try {
+            const result = await this.#discovery.discover();
+            discovered = result.files;
+            diagnostics.push(...result.diagnostics);
+            for (const diagnostic of result.diagnostics)
+                this.#log(diagnostic);
+            if (result.userRoot) {
+                await ensureHookEditorShim(result.userRoot);
+            }
+            if (result.projectRoot && result.files.some((f) => f.scope === 'project')) {
+                await ensureHookEditorShim(result.projectRoot);
+            }
+        }
+        catch (error) {
+            const diagnostic = {
+                code: 'discovery_failed',
+                message: 'Hook discovery failed; continuing without discovered hooks',
+                error,
+            };
+            diagnostics.push(diagnostic);
+            this.#log(diagnostic);
+        }
+        for (const file of discovered) {
+            let registration;
+            try {
+                registration = await this.#moduleLoader.load(file.path);
+            }
+            catch (error) {
+                const diagnostic = {
+                    code: 'module_load_failed',
+                    message: 'Hook module failed to load and was skipped',
+                    source: { path: file.path, scope: file.scope },
+                    error,
+                };
+                diagnostics.push(diagnostic);
+                skippedFiles.push(file.path);
+                this.#log(diagnostic);
+                continue;
+            }
+            try {
+                await this.#registry.register({ path: file.path, scope: file.scope }, registration);
+                loadedFiles.push(file.path);
+            }
+            catch (error) {
+                const diagnostic = {
+                    code: 'registration_rejected',
+                    message: 'Hook registration failed and was rolled back; module was skipped',
+                    source: { path: file.path, scope: file.scope },
+                    error,
+                };
+                diagnostics.push(diagnostic);
+                skippedFiles.push(file.path);
+            }
+        }
+        this.#started = true;
+        this.#startupResult = { loadedFiles, skippedFiles, diagnostics };
+        return this.#startupResult;
+    }
+    /** Alias for callers that describe startup as initialization. */
+    initialize() {
+        return this.start();
+    }
+    async emit(event) {
+        if (this.#shutdown)
+            return;
+        await this.#registry.dispatch(event);
+    }
+    async shutdown() {
+        if (this.#shutdown)
+            return;
+        this.#shutdown = true;
+        this.#registry.clear();
+    }
+    dispose() {
+        return this.shutdown();
+    }
+    #log(diagnostic) {
+        if (!this.#logger)
+            return;
+        try {
+            this.#logger(diagnostic);
+        }
+        catch (error) {
+            void error;
+        }
+    }
+}
+//# sourceMappingURL=hook-service.js.map

package/dist/services/hooks/hook-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-service.js","sourceRoot":"","sources":["../../../source/services/hooks/hook-service.ts"],"names":[],"mappings":"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"}

package/dist/services/hooks/hook-tool-lifecycle.d.ts

@@ -0,0 +1,6 @@
+import type { ToolExecutionLifecyclePort } from '../../tools/types.js';
+import type { HookLifecyclePort } from './hook-service.js';
+import type { HookEventFactory } from './hook-event-factory.js';
+/** Adapts the application run-loop seam to the public observational contract. */
+export declare function createToolExecutionLifecyclePort(lifecycle: HookLifecyclePort, events: HookEventFactory): ToolExecutionLifecyclePort;
+//# sourceMappingURL=hook-tool-lifecycle.d.ts.map

package/dist/services/hooks/hook-tool-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-tool-lifecycle.d.ts","sourceRoot":"","sources":["../../../source/services/hooks/hook-tool-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AACvE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAGhE,iFAAiF;AACjF,wBAAgB,gCAAgC,CAC9C,SAAS,EAAE,iBAAiB,EAC5B,MAAM,EAAE,gBAAgB,GACvB,0BAA0B,CAkD5B"}

package/dist/services/hooks/hook-tool-lifecycle.js

@@ -0,0 +1,33 @@
+import { summarizeHookValue } from './hook-event-factory.js';
+/** Adapts the application run-loop seam to the public observational contract. */
+export function createToolExecutionLifecyclePort(lifecycle, events) {
+    return {
+        async before(context) {
+            await lifecycle.emit(events.create('tool.before', {
+                toolName: context.toolName,
+                normalizedArguments: events.includeToolArguments
+                    ? context.normalizedArguments
+                    : summarizeHookValue(context.normalizedArguments),
+                attempt: context.attempt,
+                ownership: context.scope,
+            }, { turnId: context.turnId, toolCallId: context.toolCallId }, context.scope));
+        },
+        async after(context, result, duration) {
+            await lifecycle.emit(events.create('tool.after', {
+                toolName: context.toolName,
+                duration,
+                normalizedResultSummary: events.includeToolResults ? result : summarizeHookValue(result),
+            }, { turnId: context.turnId, toolCallId: context.toolCallId }, context.scope));
+        },
+        async error(context, error, duration, convertedToModelResult) {
+            await lifecycle.emit(events.create('tool.error', {
+                toolName: context.toolName,
+                duration,
+                errorCategory: 'tool',
+                safeMessage: (error instanceof Error ? error.message : String(error)).slice(0, 500),
+                convertedToModelResult,
+            }, { turnId: context.turnId, toolCallId: context.toolCallId }, context.scope));
+        },
+    };
+}
+//# sourceMappingURL=hook-tool-lifecycle.js.map

package/dist/services/hooks/hook-tool-lifecycle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-tool-lifecycle.js","sourceRoot":"","sources":["../../../source/services/hooks/hook-tool-lifecycle.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,iFAAiF;AACjF,MAAM,UAAU,gCAAgC,CAC9C,SAA4B,EAC5B,MAAwB;IAExB,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,OAAO;YAClB,MAAM,SAAS,CAAC,IAAI,CAClB,MAAM,CAAC,MAAM,CACX,aAAa,EACb;gBACE,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,mBAAmB,EAAE,MAAM,CAAC,oBAAoB;oBAC9C,CAAC,CAAC,OAAO,CAAC,mBAAmB;oBAC7B,CAAC,CAAC,kBAAkB,CAAC,OAAO,CAAC,mBAAmB,CAAC;gBACnD,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,SAAS,EAAE,OAAO,CAAC,KAAK;aACzB,EACD,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,EAC1D,OAAO,CAAC,KAAK,CACd,CACF,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ;YACnC,MAAM,SAAS,CAAC,IAAI,CAClB,MAAM,CAAC,MAAM,CACX,YAAY,EACZ;gBACE,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,QAAQ;gBACR,uBAAuB,EAAE,MAAM,CAAC,kBAAkB,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAC;aACzF,EACD,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,EAC1D,OAAO,CAAC,KAAK,CACd,CACF,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,sBAAsB;YAC1D,MAAM,SAAS,CAAC,IAAI,CAClB,MAAM,CAAC,MAAM,CACX,YAAY,EACZ;gBACE,QAAQ,EAAE,OAAO,CAAC,QAAQ;gBAC1B,QAAQ;gBACR,aAAa,EAAE,MAAM;gBACrB,WAAW,EAAE,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC;gBACnF,sBAAsB;aACvB,EACD,EAAE,MAAM,EAAE,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,EAC1D,OAAO,CAAC,KAAK,CACd,CACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/services/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export type { ApprovalRequestedHookEvent, ApprovalResolvedHookEvent, HookEventBase, SessionEndHookEvent, SessionStartHookEvent, StatusChangeHookEvent, Term2ApprovalKind, Term2ApprovalResolution, Term2ApprovalResolutionSource, Term2ErrorCategory, Term2HookCallback, Term2HookEvent, Term2HookEventMap, Term2HookEventName, Term2HookRegistration, Term2Hooks, Term2HookScope, Term2HookSchemaVersion, Term2SessionMode, Term2Status, Term2StatusChangeReason, Term2SubagentScope, Term2ToolOwnership, Term2TurnOrigin, Term2TurnTerminalKind, ToolAfterHookEvent, ToolBeforeHookEvent, ToolErrorHookEvent, TurnEndHookEvent, TurnErrorHookEvent, TurnStartHookEvent, } from './hook-contracts.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/services/hooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../source/services/hooks/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,0BAA0B,EAC1B,yBAAyB,EACzB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,EACjB,uBAAuB,EACvB,6BAA6B,EAC7B,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,UAAU,EACV,cAAc,EACd,sBAAsB,EACtB,gBAAgB,EAChB,WAAW,EACX,uBAAuB,EACvB,kBAAkB,EAClB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,qBAAqB,CAAC"}

package/dist/services/hooks/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/services/hooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../source/services/hooks/index.ts"],"names":[],"mappings":""}

package/dist/services/input-surge-guard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"input-surge-guard.d.ts","sourceRoot":"","sources":["../../source/services/input-surge-guard.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,2BAA2B,EAAE,MAAM,CAAC;IACpC,kCAAkC,EAAE,MAAM,CAAC;CAC5C;AAED,MAAM,WAAW,qBAAqB;IACpC,kCAAkC,EAAE,MAAM,CAAC;IAC3C,sCAAsC,EAAE,MAAM,CAAC;CAChD;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,eAAe,CAAC;IACvB,aAAa,CAAC,EAAE,eAAe,CAAC;CACjC;AAED,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,cAAc,CAAC;AAE3D,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,uBAAwB,SAAQ,wBAAwB;IACvE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,eAAO,MAAM,gCAAgC,EAAE,qBAG9C,CAAC;AA8CF,eAAO,MAAM,sBAAsB,UAAW,OAAO,KAAG,eAoBvD,CAAC;AAEF,eAAO,MAAM,mCAAmC,UAAW,OAAO,KAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CA+BtG,CAAC;AAEF,qBAAa,eAAe;;IAG1B,YAAY,MAAM,GAAE,OAAO,CAAC,qBAAqB,CAAM,EAEtD;IAED,KAAK,IAAI,IAAI,CAAG;IAEhB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,GAAE,wBAA6B,GAAG,kBAAkB,CAwBnF;IAED,qBAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAE,uBAA4B,GAAG,IAAI,CAAG;CACxF"}
+{"version":3,"file":"input-surge-guard.d.ts","sourceRoot":"","sources":["../../source/services/input-surge-guard.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,eAAe;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,2BAA2B,EAAE,MAAM,CAAC;IACpC,kCAAkC,EAAE,MAAM,CAAC;CAC5C;AAED,MAAM,WAAW,qBAAqB;IACpC,kCAAkC,EAAE,MAAM,CAAC;IAC3C,sCAAsC,EAAE,MAAM,CAAC;CAChD;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,OAAO,GAAG,OAAO,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,eAAe,CAAC;IACvB,aAAa,CAAC,EAAE,eAAe,CAAC;CACjC;AAED,MAAM,MAAM,mBAAmB,GAAG,OAAO,GAAG,cAAc,CAAC;AAE3D,MAAM,WAAW,wBAAwB;IACvC,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,uBAAwB,SAAQ,wBAAwB;IACvE,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,eAAO,MAAM,gCAAgC,EAAE,qBAG9C,CAAC;AAsBF,eAAO,MAAM,sBAAsB,UAAW,OAAO,KAAG,eAoBvD,CAAC;AAEF,eAAO,MAAM,mCAAmC,UAAW,OAAO,KAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CA6BtG,CAAC;AAEF,qBAAa,eAAe;;IAG1B,YAAY,MAAM,GAAE,OAAO,CAAC,qBAAqB,CAAM,EAEtD;IAED,KAAK,IAAI,IAAI,CAAG;IAEhB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,GAAE,wBAA6B,GAAG,kBAAkB,CAwBnF;IAED,qBAAqB,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,GAAE,uBAA4B,GAAG,IAAI,CAAG;CACxF"}