@iworkforces/tracelattice 2.0.3

package/dist/pool/IConnectionPool.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Interface for the connection pool managing concurrent user sessions.
+ *
+ * This module provides the `IConnectionPool` interface which defines the
+ * contract for connection pool implementations. This allows for decoupling
+ * and testability for multi-user transports.
+ *
+ * @module IConnectionPool
+ */
+import type { InferInput } from 'valibot';
+import type { SessionId } from '../contracts/ids.js';
+import type { SequentialThinkingSchema } from '../schema.js';
+import type { IDisposable } from '../types/disposable.js';
+export type SessionThoughtInput = InferInput<typeof SequentialThinkingSchema>;
+/**
+ * Represents a content block in a process result.
+ */
+export type ContentBlock = {
+    type: 'text';
+    text: string;
+};
+export interface ProcessResult {
+    content: ContentBlock[];
+    isError?: boolean;
+}
+export interface SessionServer {
+    processThought(input: SessionThoughtInput): Promise<ProcessResult>;
+    stop(): void | Promise<void>;
+}
+export interface SessionInfo {
+    id: SessionId;
+    server: SessionServer;
+    createdAt: number;
+    lastActivityAt: number;
+    isActive: boolean;
+}
+/**
+ * Result of running callback-scoped work against a pooled session.
+ */
+export type SessionRunResult<T> = {
+    readonly status: 'completed';
+    readonly value: T;
+} | {
+    readonly status: 'inactive';
+} | {
+    readonly status: 'missing';
+};
+/**
+ * Statistics describing the current state of the connection pool.
+ */
+export interface ConnectionPoolStats {
+    totalSessions: number;
+    activeSessions: number;
+    maxSessions: number;
+    cleanupEnabled: boolean;
+    sessionTimeout: number;
+}
+/**
+ * Interface for the connection pool.
+ *
+ * This interface defines the contract for managing multiple concurrent
+ * user sessions, each with its own isolated server instance. Supports
+ * dependency injection and mocking for testing purposes.
+ *
+ * @example
+ * ```typescript
+ * class MockPool implements IConnectionPool {
+ *   async createSession(): Promise<string> { return 'mock'; }
+ *   // ...
+ * }
+ * ```
+ */
+export interface IConnectionPool extends IDisposable {
+    /**
+     * Create a new session.
+     *
+     * @returns The new session ID
+     * @throws PoolTerminatedError if the pool has been terminated
+     * @throws MaxSessionsReachedError if the maximum number of sessions is reached
+     */
+    createSession(): Promise<SessionId>;
+    /**
+     * Process a thought in the specified session.
+     *
+     * @param sessionId - The session ID
+     * @param input - The thought data to process
+     * @returns The processing result
+     * @throws SessionNotFoundError if the session does not exist
+     */
+    process(sessionId: SessionId, input: SessionThoughtInput): Promise<ProcessResult>;
+    /**
+     * Run an operation while atomically holding an active session open.
+     *
+     * @param sessionId - The session ID
+     * @param operation - Callback that receives the admitted child server
+     * @returns The callback value or an explicit unavailable status
+     */
+    runWithSession<T>(sessionId: SessionId, operation: (session: SessionServer) => Promise<T>): Promise<SessionRunResult<T>>;
+    /**
+     * Close a session and release its resources.
+     *
+     * @param sessionId - The session ID to close
+     * @throws SessionNotFoundError if the session does not exist
+     */
+    closeSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Get information about a session.
+     *
+     * @param sessionId - The session ID
+     * @returns Session info, or undefined if not found
+     */
+    getSessionInfo(sessionId: SessionId): SessionInfo | undefined;
+    /**
+     * Get all active sessions.
+     *
+     * @returns Array of session information for currently active sessions
+     */
+    getActiveSessions(): SessionInfo[];
+    /**
+     * Get connection pool statistics.
+     *
+     * @returns A snapshot of the pool's statistics
+     */
+    getStats(): ConnectionPoolStats;
+    /**
+     * Close all sessions and stop the cleanup timer.
+     */
+    terminate(): Promise<void>;
+    /**
+     * Dispose of the connection pool, releasing all resources.
+     *
+     * Implements the {@link IDisposable} interface. Typically delegates
+     * to {@link IConnectionPool.terminate}.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Check if the connection pool is active (not terminated).
+     *
+     * @returns true if the pool is still running
+     */
+    isRunning(): boolean;
+}
+//# sourceMappingURL=IConnectionPool.d.ts.map

package/dist/pool/IConnectionPool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"IConnectionPool.d.ts","sourceRoot":"","sources":["../../src/pool/IConnectionPool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAC1C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,MAAM,MAAM,mBAAmB,GAAG,UAAU,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAE9E;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1D,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC7B,cAAc,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IACnE,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC3B,EAAE,EAAE,SAAS,CAAC;IACd,MAAM,EAAE,aAAa,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAC3B;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACnD;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAA;CAAE,CAAC;AAElC;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,eAAgB,SAAQ,WAAW;IACnD;;;;;;OAMG;IACH,aAAa,IAAI,OAAO,CAAC,SAAS,CAAC,CAAC;IAEpC;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAElF;;;;;;OAMG;IACH,cAAc,CAAC,CAAC,EACf,SAAS,EAAE,SAAS,EACpB,SAAS,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC/C,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC;IAEhC;;;;;OAKG;IACH,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;;;;OAKG;IACH,cAAc,CAAC,SAAS,EAAE,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;IAE9D;;;;OAIG;IACH,iBAAiB,IAAI,WAAW,EAAE,CAAC;IAEnC;;;;OAIG;IACH,QAAQ,IAAI,mBAAmB,CAAC;IAEhC;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3B;;;;;OAKG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB;;;;OAIG;IACH,SAAS,IAAI,OAAO,CAAC;CACrB"}

package/dist/pool/IConnectionPool.js

@@ -0,0 +1 @@
+export { };

package/dist/pool/PoolErrors.d.ts

@@ -0,0 +1,11 @@
+import type { SessionId } from '../contracts/ids.js';
+import { SequentialThinkingError } from '../errors.js';
+/** Error thrown when attempting to process a session that is not active. */
+export declare class SessionNotActiveError extends SequentialThinkingError {
+    constructor(sessionId: SessionId);
+}
+/** Error thrown when a requested session is not found in the pool. */
+export declare class SessionNotFoundError extends SequentialThinkingError {
+    constructor(sessionId: SessionId);
+}
+//# sourceMappingURL=PoolErrors.d.ts.map

package/dist/pool/PoolErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PoolErrors.d.ts","sourceRoot":"","sources":["../../src/pool/PoolErrors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAe,uBAAuB,EAAE,MAAM,cAAc,CAAC;AAEpE,4EAA4E;AAC5E,qBAAa,qBAAsB,SAAQ,uBAAuB;gBACrD,SAAS,EAAE,SAAS;CAIhC;AAED,sEAAsE;AACtE,qBAAa,oBAAqB,SAAQ,uBAAuB;gBACpD,SAAS,EAAE,SAAS;CAIhC"}

package/dist/pool/PoolErrors.js

@@ -0,0 +1,16 @@
+import { ERROR_CODES, SequentialThinkingError } from "../errors.js";
+class SessionNotActiveError extends SequentialThinkingError {
+    constructor(sessionId){
+        super(`Session '${sessionId}' is not active`, ERROR_CODES.SESSION_NOT_ACTIVE);
+        this.name = 'SessionNotActiveError';
+    }
+}
+class SessionNotFoundError extends SequentialThinkingError {
+    constructor(sessionId){
+        super(`Session not found: ${sessionId}`, ERROR_CODES.SESSION_NOT_FOUND);
+        this.name = 'SessionNotFoundError';
+    }
+}
+export { SessionNotActiveError, SessionNotFoundError };
+
+//# sourceMappingURL=PoolErrors.js.map

package/dist/pool/PoolErrors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool/PoolErrors.js","sources":["../../src/pool/PoolErrors.ts"],"sourcesContent":["import type { SessionId } from '../contracts/ids.js';\nimport { ERROR_CODES, SequentialThinkingError } from '../errors.js';\n\n/** Error thrown when attempting to process a session that is not active. */\nexport class SessionNotActiveError extends SequentialThinkingError {\n\tconstructor(sessionId: SessionId) {\n\t\tsuper(`Session '${sessionId}' is not active`, ERROR_CODES.SESSION_NOT_ACTIVE);\n\t\tthis.name = 'SessionNotActiveError';\n\t}\n}\n\n/** Error thrown when a requested session is not found in the pool. */\nexport class SessionNotFoundError extends SequentialThinkingError {\n\tconstructor(sessionId: SessionId) {\n\t\tsuper(`Session not found: ${sessionId}`, ERROR_CODES.SESSION_NOT_FOUND);\n\t\tthis.name = 'SessionNotFoundError';\n\t}\n}\n"],"names":["SessionNotActiveError","SequentialThinkingError","sessionId","ERROR_CODES","SessionNotFoundError"],"mappings":";AAIO,MAAMA,8BAA8BC;IAC1C,YAAYC,SAAoB,CAAE;QACjC,KAAK,CAAC,CAAC,SAAS,EAAEA,UAAU,eAAe,CAAC,EAAEC,YAAY,kBAAkB;QAC5E,IAAI,CAAC,IAAI,GAAG;IACb;AACD;AAGO,MAAMC,6BAA6BH;IACzC,YAAYC,SAAoB,CAAE;QACjC,KAAK,CAAC,CAAC,mBAAmB,EAAEA,WAAW,EAAEC,YAAY,iBAAiB;QACtE,IAAI,CAAC,IAAI,GAAG;IACb;AACD"}

package/dist/registry/BaseRegistry.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Base registry providing shared CRUD, caching, and discovery logic.
+ *
+ * This abstract generic class extracts the common patterns from `ToolRegistry`
+ * and `SkillRegistry` into a single reusable base. Subclasses only need to
+ * implement item-specific parsing, file filtering, and error construction.
+ *
+ * @template T - The registry item type (must have a `name` property)
+ * @module registry
+ */
+import { DiscoveryCache } from '../cache/DiscoveryCache.js';
+import type { Logger } from '../logger/StructuredLogger.js';
+/**
+ * Configuration options for creating a `BaseRegistry` instance.
+ */
+export interface BaseRegistryOptions {
+    /** Optional logger for diagnostics. */
+    logger?: Logger;
+    /** Optional cache for lookups. */
+    cache?: DiscoveryCache<{
+        name: string;
+    }>;
+    /**
+     * Directory paths to search for items.
+     */
+    searchDirs?: string[];
+    /**
+     * Enable lazy discovery (discover on first access instead of startup).
+     * @default false
+     */
+    lazyDiscovery?: boolean;
+}
+/**
+ * Abstract base registry for managing named items with discovery and caching.
+ *
+ * Provides shared CRUD operations, filesystem discovery with deduplication,
+ * and optional LRU caching. Subclasses implement item-specific parsing logic
+ * and error construction.
+ *
+ * @template T - The registry item type (must have a `name` property)
+ */
+export declare abstract class BaseRegistry<T extends {
+    name: string;
+}> {
+    /** Internal storage for items indexed by name. */
+    protected _items: Map<string, T>;
+    private _manualItems;
+    private _discoveredItemsByPath;
+    /** Logger for diagnostics. */
+    protected _logger: Logger;
+    /** Optional cache for lookups. */
+    protected _cache: DiscoveryCache<T>;
+    /** Directory paths to search for items. */
+    protected _searchDirs: string[];
+    /** Whether discovery has been performed. */
+    protected _discovered: boolean;
+    /** Promise for in-progress discovery (null if not in progress). */
+    protected _discoveryPromise: Promise<number> | null;
+    private _refreshRequested;
+    /** File extensions to match during discovery. */
+    protected abstract readonly _fileExtensions: string[];
+    /**
+     * Creates an error for invalid item data.
+     * @param reason - The reason for the validation failure
+     */
+    protected abstract _createInvalidError(reason: string): Error;
+    /**
+     * Creates an error for duplicate items.
+     * @param name - The name of the duplicate item
+     */
+    protected abstract _createDuplicateError(name: string): Error;
+    /**
+     * Creates an error for items not found.
+     * @param name - The name of the missing item
+     * @param action - The action that was attempted
+     */
+    protected abstract _createNotFoundError(name: string, action: string): Error;
+    /**
+     * Parses frontmatter content into a partial item.
+     * @param content - The file content to parse
+     * @returns A partial item, with an `_error` property if parsing failed
+     */
+    protected abstract _parseFrontmatter(content: string): Partial<T> & {
+        _error?: string;
+    };
+    /**
+     * Determines whether a file should be skipped during discovery.
+     * @param fileName - The name of the file to check
+     * @returns true if the file should be skipped
+     */
+    protected abstract _shouldSkipFile(fileName: string): boolean;
+    /**
+     * Constructs a complete item from parsed frontmatter data.
+     * Returns null if the parsed data is insufficient.
+     * @param parsed - The parsed frontmatter data
+     * @returns A complete item, or null if data is insufficient
+     */
+    protected abstract _buildItem(parsed: Partial<T>): T | null;
+    /**
+     * The entity name used in log messages (e.g., 'tool', 'skill').
+     */
+    protected abstract readonly _entityName: string;
+    constructor(options: BaseRegistryOptions);
+    /**
+     * Internal logging method.
+     * @param message - The message to log
+     * @param meta - Optional metadata
+     */
+    protected log(message: string, meta?: Record<string, unknown>): void;
+    /**
+     * Adds an item to the registry.
+     *
+     * @param item - The item to add
+     * @throws If item already exists or name is invalid
+     */
+    add(item: T): void;
+    /**
+     * Removes an item from the registry.
+     *
+     * @param name - The name of the item to remove
+     * @throws If item not found
+     */
+    remove(name: string): void;
+    /**
+     * Updates an existing item with partial data.
+     *
+     * @param name - The name of the item to update
+     * @param updates - Partial item data with fields to update
+     * @throws If item not found
+     */
+    update(name: string, updates: Partial<T>): void;
+    /**
+     * Gets an item by name.
+     *
+     * @param name - The name of the item to get
+     * @returns The item if found, undefined otherwise
+     */
+    get(name: string): T | undefined;
+    /**
+     * Gets all items as an array.
+     *
+     * Uses cache if available for performance.
+     *
+     * @returns An array of all registered items
+     */
+    getAll(): T[];
+    /**
+     * Checks if an item exists in the registry.
+     *
+     * @param name - The name of the item to check
+     * @returns true if the item exists, false otherwise
+     */
+    has(name: string): boolean;
+    /**
+     * Gets all item names as an array.
+     *
+     * @returns An array of item names
+     */
+    getNames(): string[];
+    /**
+     * Clears all items from the registry.
+     */
+    clear(): void;
+    /**
+     * Gets the number of items in the registry.
+     *
+     * @returns The count of registered items
+     */
+    size(): number;
+    /**
+     * Asynchronously discovers items from the configured directories.
+     *
+     * Multiple concurrent calls share the same discovery promise.
+     * Subsequent calls return cached results if discovery has already completed.
+     *
+     * @returns A Promise resolving to the number of items discovered
+     */
+    discoverAsync(): Promise<number>;
+    /**
+     * Re-scans configured directories and atomically reconciles discovered items.
+     *
+     * Calls made during an active scan share its promise and request at most one
+     * follow-up pass, ensuring an event that arrives mid-scan is not lost.
+     *
+     * @returns A Promise resolving to the number of discovered filesystem items
+     */
+    refreshAsync(): Promise<number>;
+    private _beginDiscovery;
+    private _runDiscoveryLoop;
+    /**
+     * Performs the actual discovery operation.
+     *
+     * Scans configured directories for item files, parses their frontmatter,
+     * and adds valid items to the registry.
+     *
+     * @returns A Promise resolving to the number of items discovered
+     */
+    protected _performDiscovery(): Promise<number>;
+    private _retainLastKnownGood;
+    private _retainDirectory;
+    /**
+     * Parses YAML frontmatter from file content.
+     *
+     * This is a shared utility for subclasses that parse YAML frontmatter.
+     *
+     * @param content - The file content to parse
+     * @returns The parsed YAML object, or null if no frontmatter found
+     */
+    protected _extractFrontmatter(content: string): Record<string, unknown> | null;
+    /**
+     * Sets items from an external source.
+     *
+     * Clears existing items and adds new ones from the provided array.
+     *
+     * @param items - Array of items from an external source
+     */
+    setAll(items: T[]): void;
+}
+//# sourceMappingURL=BaseRegistry.d.ts.map

package/dist/registry/BaseRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseRegistry.d.ts","sourceRoot":"","sources":["../../src/registry/BaseRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAG5D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,kCAAkC;IAClC,KAAK,CAAC,EAAE,cAAc,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAEzC;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;IAEtB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,8BAAsB,YAAY,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;IAC5D,kDAAkD;IAClD,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACjC,OAAO,CAAC,YAAY,CAAiB;IACrC,OAAO,CAAC,sBAAsB,CAAiB;IAE/C,8BAA8B;IAC9B,SAAS,CAAC,OAAO,EAAE,MAAM,CAAC;IAE1B,kCAAkC;IAClC,SAAS,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC;IAEpC,2CAA2C;IAC3C,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,CAAC;IAEhC,4CAA4C;IAC5C,SAAS,CAAC,WAAW,EAAE,OAAO,CAAS;IAEvC,mEAAmE;IACnE,SAAS,CAAC,iBAAiB,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAAQ;IAC3D,OAAO,CAAC,iBAAiB,CAAS;IAElC,iDAAiD;IACjD,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,eAAe,EAAE,MAAM,EAAE,CAAC;IAEtD;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK;IAE7D;;;OAGG;IACH,SAAS,CAAC,QAAQ,CAAC,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK;IAE7D;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK;IAE5E;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE;IAEvF;;;;OAIG;IACH,SAAS,CAAC,QAAQ,CAAC,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAE7D;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI;IAE3D;;OAEG;IACH,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;gBAEpC,OAAO,EAAE,mBAAmB;IAUxC;;;;OAIG;IACH,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAIpE;;;;;OAKG;IACI,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI;IAczB;;;;;OAKG;IACI,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAejC;;;;;;OAMG;IACI,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,IAAI;IAiBtD;;;;;OAKG;IACI,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAIvC;;;;;;OAMG;IACI,MAAM,IAAI,CAAC,EAAE;IAepB;;;;;OAKG;IACI,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIjC;;;;OAIG;IACI,QAAQ,IAAI,MAAM,EAAE;IAI3B;;OAEG;IACI,KAAK,IAAI,IAAI;IASpB;;;;OAIG;IACI,IAAI,IAAI,MAAM;IAIrB;;;;;;;OAOG;IACU,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAa7C;;;;;;;OAOG;IACU,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAK5C,OAAO,CAAC,eAAe;YAUT,iBAAiB;IAU/B;;;;;;;OAOG;cACa,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC;IAiEpD,OAAO,CAAC,oBAAoB;IAkB5B,OAAO,CAAC,gBAAgB;IAaxB;;;;;;;OAOG;IACH,SAAS,CAAC,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAQ9E;;;;;;OAMG;IACI,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,IAAI;CAgB/B"}

package/dist/registry/BaseRegistry.js

@@ -0,0 +1,215 @@
+import { existsSync } from "node:fs";
+import { readFile, readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { parse } from "yaml";
+import { DiscoveryCache } from "../cache/DiscoveryCache.js";
+import { NullLogger } from "../logger/NullLogger.js";
+import { getErrorMessage } from "../errors.js";
+class BaseRegistry {
+    _items;
+    _manualItems;
+    _discoveredItemsByPath;
+    _logger;
+    _cache;
+    _searchDirs;
+    _discovered = false;
+    _discoveryPromise = null;
+    _refreshRequested = false;
+    constructor(options){
+        this._items = new Map();
+        this._manualItems = new Map();
+        this._discoveredItemsByPath = new Map();
+        this._logger = options.logger ?? new NullLogger();
+        this._cache = options.cache || new DiscoveryCache({
+            maxSize: 50,
+            ttl: 300000
+        });
+        this._searchDirs = options.searchDirs ?? [];
+    }
+    log(message, meta) {
+        this._logger.info(message, meta);
+    }
+    add(item) {
+        if (!item.name) throw this._createInvalidError(`${this._entityName} must have a valid name`);
+        if (this._items.has(item.name)) throw this._createDuplicateError(item.name);
+        this._items.set(item.name, item);
+        this._manualItems.set(item.name, item);
+        this.log(`Added ${this._entityName}: ${item.name}`, {
+            [`${this._entityName}Name`]: item.name
+        });
+        this._cache?.invalidate('all');
+    }
+    remove(name) {
+        if (!this._items.has(name)) throw this._createNotFoundError(name, 'remove');
+        this._items.delete(name);
+        this._manualItems.delete(name);
+        for (const [filePath, item] of this._discoveredItemsByPath)if (item.name === name) this._discoveredItemsByPath.delete(filePath);
+        this.log(`Removed ${this._entityName}: ${name}`, {
+            [`${this._entityName}Name`]: name
+        });
+        this._cache?.invalidate('all');
+        this._cache?.invalidate(name);
+    }
+    update(name, updates) {
+        if (!this._items.has(name)) throw this._createNotFoundError(name, 'update');
+        const existing = this._items.get(name);
+        const updated = {
+            ...existing,
+            ...updates
+        };
+        this._items.set(name, updated);
+        if (this._manualItems.has(name)) this._manualItems.set(name, updated);
+        for (const [filePath, item] of this._discoveredItemsByPath)if (item.name === name) this._discoveredItemsByPath.set(filePath, updated);
+        this.log(`Updated ${this._entityName}: ${name}`, {
+            [`${this._entityName}Name`]: name
+        });
+        this._cache?.invalidate('all');
+        this._cache?.invalidate(name);
+    }
+    get(name) {
+        return this._items.get(name);
+    }
+    getAll() {
+        if (this._cache) {
+            const cached = this._cache.get('all');
+            if (cached) return cached;
+        }
+        const items = Array.from(this._items.values());
+        this._cache?.set('all', items);
+        return items;
+    }
+    has(name) {
+        return this._items.has(name);
+    }
+    getNames() {
+        return Array.from(this._items.keys());
+    }
+    clear() {
+        this._items.clear();
+        this._manualItems.clear();
+        this._discoveredItemsByPath.clear();
+        this.log(`Cleared all ${this._entityName}s`);
+        this._cache?.clear();
+    }
+    size() {
+        return this._items.size;
+    }
+    async discoverAsync() {
+        if (this._discoveryPromise) return this._discoveryPromise;
+        if (this._discovered) {
+            const cached = this._cache.get('all');
+            return cached?.length ?? 0;
+        }
+        return this._beginDiscovery();
+    }
+    async refreshAsync() {
+        this._refreshRequested = true;
+        return this._discoveryPromise ?? this._beginDiscovery();
+    }
+    _beginDiscovery() {
+        const operation = this._runDiscoveryLoop();
+        this._discoveryPromise = operation;
+        const clearOperation = ()=>{
+            if (this._discoveryPromise === operation) this._discoveryPromise = null;
+        };
+        operation.then(clearOperation, clearOperation);
+        return operation;
+    }
+    async _runDiscoveryLoop() {
+        this._refreshRequested = false;
+        let count = await this._performDiscovery();
+        while(this._refreshRequested){
+            this._refreshRequested = false;
+            count = await this._performDiscovery();
+        }
+        return count;
+    }
+    async _performDiscovery() {
+        const discoveredItems = new Map();
+        const claimedNames = new Set(this._manualItems.keys());
+        for (const dir of this._searchDirs)try {
+            if (!existsSync(dir)) continue;
+            const entries = await readdir(dir, {
+                withFileTypes: true
+            });
+            for (const entry of entries)if (!this._shouldSkipFile(entry.name)) {
+                if (entry.isFile() && this._fileExtensions.some((ext)=>entry.name.endsWith(ext))) {
+                    const filePath = join(dir, entry.name);
+                    try {
+                        const content = await readFile(filePath, 'utf-8');
+                        const parsed = this._parseFrontmatter(content);
+                        if (parsed._error) {
+                            this._retainLastKnownGood(filePath, parsed._error, discoveredItems, claimedNames);
+                            continue;
+                        }
+                        if (parsed.name) {
+                            const item = this._buildItem(parsed);
+                            if (item && !claimedNames.has(item.name)) {
+                                discoveredItems.set(filePath, item);
+                                claimedNames.add(item.name);
+                            }
+                        }
+                    } catch (readError) {
+                        this._retainLastKnownGood(filePath, getErrorMessage(readError), discoveredItems, claimedNames);
+                    }
+                }
+            }
+        } catch (error) {
+            this._logger.warn(`Failed to scan ${this._entityName} directory`, {
+                directory: dir,
+                error: getErrorMessage(error)
+            });
+            this._retainDirectory(dir, discoveredItems, claimedNames);
+        }
+        this._discoveredItemsByPath = discoveredItems;
+        this._items = new Map(this._manualItems);
+        for (const item of discoveredItems.values())if (!this._items.has(item.name)) this._items.set(item.name, item);
+        this._discovered = true;
+        this._cache.clear();
+        this._cache.set('all', Array.from(this._items.values()));
+        this.log(`Discovery complete: found ${discoveredItems.size} ${this._entityName}s`, {
+            discoveredCount: discoveredItems.size
+        });
+        return discoveredItems.size;
+    }
+    _retainLastKnownGood(filePath, reason, discoveredItems, claimedNames) {
+        const previous = this._discoveredItemsByPath.get(filePath);
+        if (previous && !claimedNames.has(previous.name)) {
+            discoveredItems.set(filePath, previous);
+            claimedNames.add(previous.name);
+        }
+        this._logger.warn(`Invalid ${this._entityName} discovery file`, {
+            filePath,
+            reason,
+            retainedLastKnownGood: void 0 !== previous
+        });
+    }
+    _retainDirectory(directory, discoveredItems, claimedNames) {
+        for (const [filePath, item] of this._discoveredItemsByPath)if (dirname(filePath) === directory && !claimedNames.has(item.name)) {
+            discoveredItems.set(filePath, item);
+            claimedNames.add(item.name);
+        }
+    }
+    _extractFrontmatter(content) {
+        const match = content.match(/^---\n([\s\S]+?)\n---/);
+        if (!match) return null;
+        return parse(match[1]);
+    }
+    setAll(items) {
+        this.clear();
+        for (const item of items)try {
+            this.add(item);
+        } catch (error) {
+            this.log(`Error adding ${this._entityName} '${item.name}':`, {
+                [`${this._entityName}Name`]: item.name,
+                error: getErrorMessage(error)
+            });
+        }
+        this.log(`Set ${items.length} ${this._entityName}s from external source`, {
+            [`${this._entityName}Count`]: items.length
+        });
+    }
+}
+export { BaseRegistry };
+
+//# sourceMappingURL=BaseRegistry.js.map