@vurb/core 3.2.0

package/dist/client/VurbClient.js

@@ -0,0 +1,287 @@
+/**
+ * VurbClient — Type-Safe MCP Client (tRPC-style)
+ *
+ * Provides end-to-end type safety from server to client.
+ * The server exports its router type, and the client consumes it
+ * with full autocomplete and compile-time validation.
+ *
+ * @example
+ * ```typescript
+ * // ── SERVER (mcp-server.ts) ──
+ * export const registry = new ToolRegistry<AppContext>();
+ * registry.register(projects);
+ * registry.register(billing);
+ * export type AppRouter = InferRouter<typeof registry>;
+ *
+ * // ── CLIENT (agent.ts) ──
+ * import { createVurbClient } from 'vurb/client';
+ * import type { AppRouter } from './mcp-server';
+ *
+ * const client = createVurbClient<AppRouter>(transport);
+ * const result = await client.execute('projects.create', { name: 'Vinkius V2' });
+ * //                                   ^^^^^^^^^^^^^^^^    ^^^^^^^^^^^^^^^^^
+ * //                                   autocomplete!       typed args!
+ * ```
+ *
+ * @module
+ */
+import {} from '../core/response.js';
+// ============================================================================
+// Structured Client Error
+// ============================================================================
+/**
+ * Structured error parsed from a `<tool_error>` XML envelope.
+ *
+ * Provides typed access to self-healing fields so client code
+ * can programmatically react to server errors without regex parsing.
+ */
+export class VurbClientError extends Error {
+    /** Error code from the `code` attribute (e.g. `'NOT_FOUND'`). */
+    code;
+    /** Recovery suggestion from `<recovery>` element. */
+    recovery;
+    /** Available actions from `<available_actions>` children. */
+    availableActions;
+    /** Error severity from the `severity` attribute. */
+    severity;
+    /** Raw ToolResponse that caused the error. */
+    raw;
+    constructor(message, code, raw, options) {
+        super(message);
+        this.name = 'VurbClientError';
+        this.code = code;
+        this.raw = raw;
+        this.recovery = options?.recovery;
+        this.availableActions = Object.freeze(options?.availableActions ?? []);
+        this.severity = options?.severity ?? 'error';
+    }
+}
+// ============================================================================
+// XML Error Parser (Internal)
+// ============================================================================
+/**
+ * Decode XML entities back to their original characters.
+ *
+ * Reverses the escaping applied by `escapeXml()` and `escapeXmlAttr()`
+ * so that parsed error messages are human-readable.
+ *
+ * @internal
+ */
+function unescapeXml(str) {
+    return str
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, '&'); // &amp; must be last to avoid double-decode
+}
+/**
+ * Parse a `<tool_error>` XML envelope into structured fields.
+ *
+ * Coupled to the output format of `toolError()` from `response.ts`.
+ * Uses regex for lightweight parsing — acceptable since the XML is
+ * self-produced by the framework, not user-authored.
+ *
+ * @internal
+ */
+function parseToolErrorXml(text) {
+    const codeMatch = text.match(/<tool_error\s[^>]*code="([^"]+)"/);
+    const severityMatch = text.match(/<tool_error\s[^>]*severity="([^"]+)"/);
+    const messageMatch = text.match(/<message>([\s\S]*?)<\/message>/);
+    const recoveryMatch = text.match(/<recovery>([\s\S]*?)<\/recovery>/);
+    if (!messageMatch)
+        return null;
+    const actions = [];
+    const actionMatches = text.matchAll(/<action>([\s\S]*?)<\/action>/g);
+    for (const m of actionMatches) {
+        if (m[1])
+            actions.push(unescapeXml(m[1].trim()));
+    }
+    // Fallback: legacy comma-separated format
+    if (actions.length === 0) {
+        const legacyMatch = text.match(/<available_actions>([\s\S]*?)<\/available_actions>/);
+        if (legacyMatch?.[1]) {
+            actions.push(...legacyMatch[1].split(',').map(a => unescapeXml(a.trim())).filter(Boolean));
+        }
+    }
+    const recovery = recoveryMatch?.[1] != null ? unescapeXml(recoveryMatch[1].trim()) : undefined;
+    const result = {
+        code: codeMatch?.[1] != null ? unescapeXml(codeMatch[1]) : 'UNKNOWN',
+        message: unescapeXml(messageMatch[1].trim()),
+        availableActions: actions,
+        severity: severityMatch?.[1] ?? 'error',
+    };
+    if (recovery !== undefined) {
+        result.recovery = recovery;
+    }
+    return result;
+}
+// ============================================================================
+// Middleware Chain Compiler (Internal)
+// ============================================================================
+/** @internal */
+function compileClientMiddleware(middleware, terminal) {
+    let chain = terminal;
+    // Wrap from right to left: first middleware in array = outermost
+    for (let i = middleware.length - 1; i >= 0; i--) {
+        const mw = middleware[i];
+        const next = chain;
+        chain = (action, args) => mw(action, args, next);
+    }
+    return chain;
+}
+// ============================================================================
+// Factory
+// ============================================================================
+/**
+ * Create a type-safe MCP client.
+ *
+ * The client provides full autocomplete for action names and
+ * compile-time validation for arguments based on the server's
+ * router type.
+ *
+ * @typeParam TRouter - The router map (use `InferRouter<typeof registry>`)
+ * @param transport - The MCP transport layer
+ * @param options - Client options (middleware, error handling)
+ * @returns A typed {@link VurbClient}
+ *
+ * @example
+ * ```typescript
+ * import type { AppRouter } from './mcp-server';
+ *
+ * const client = createVurbClient<AppRouter>(transport);
+ *
+ * // Full autocomplete + type validation:
+ * await client.execute('projects.create', { name: 'Vinkius V2' });
+ *
+ * // TS error: 'projects.nonexistent' is not a valid action
+ * await client.execute('projects.nonexistent', {});
+ *
+ * // TS error: missing required arg 'name'
+ * await client.execute('projects.create', {});
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With client middleware and throwOnError
+ * const client = createVurbClient<AppRouter>(transport, {
+ *     throwOnError: true,
+ *     middleware: [
+ *         async (action, args, next) => {
+ *             console.log(`[Client] calling ${action}`);
+ *             const result = await next(action, args);
+ *             console.log(`[Client] ${action} done`);
+ *             return result;
+ *         },
+ *     ],
+ * });
+ * ```
+ */
+export function createVurbClient(transport, options) {
+    const throwOnError = options?.throwOnError ?? false;
+    const discriminatorKey = options?.discriminatorKey ?? 'action';
+    /** Terminal function: builds the MCP call from the dotted action path */
+    function terminalCall(action, args) {
+        const dotIndex = action.indexOf('.');
+        if (dotIndex === -1) {
+            return transport.callTool(action, args);
+        }
+        const toolName = action.substring(0, dotIndex);
+        const actionName = action.substring(dotIndex + 1);
+        return transport.callTool(toolName, {
+            ...args,
+            [discriminatorKey]: actionName,
+        });
+    }
+    // Compile middleware chain once at creation time
+    const dispatch = (options?.middleware != null && options.middleware.length > 0)
+        ? compileClientMiddleware(options.middleware, terminalCall)
+        : terminalCall;
+    /** Post-process: handle throwOnError */
+    async function executeInternal(action, args) {
+        const result = await dispatch(action, args);
+        if (throwOnError && result.isError) {
+            const text = result.content
+                .filter(c => c.type === 'text')
+                .map(c => c.text)
+                .join('\n');
+            const parsed = parseToolErrorXml(text);
+            if (parsed) {
+                const opts = {
+                    availableActions: parsed.availableActions,
+                    severity: parsed.severity,
+                };
+                if (parsed.recovery !== undefined) {
+                    opts.recovery = parsed.recovery;
+                }
+                throw new VurbClientError(parsed.message, parsed.code, result, opts);
+            }
+            throw new VurbClientError(text || 'Unknown error', 'UNKNOWN', result);
+        }
+        return result;
+    }
+    return {
+        async execute(action, args) {
+            return executeInternal(action, args);
+        },
+        async executeBatch(calls, batchOptions) {
+            const items = calls;
+            if (batchOptions?.sequential) {
+                const results = [];
+                for (const call of items) {
+                    results.push(await executeInternal(call.action, call.args));
+                }
+                return results;
+            }
+            return Promise.all(items.map(call => executeInternal(call.action, call.args)));
+        },
+        proxy: buildFluentProxy(executeInternal),
+    };
+}
+// ============================================================================
+// Fluent Proxy Builder (Internal)
+// ============================================================================
+/**
+ * Creates a recursive Proxy that accumulates path segments
+ * and executes when invoked as a function.
+ *
+ * ```
+ * proxy.projects.create({ name: 'V2' })
+ * //   ^^^^^^^^ ^^^^^^  ^^^^^^^^^^^^^^^^
+ * //   seg[0]   seg[1]  args → execute('projects.create', args)
+ * ```
+ *
+ * @internal
+ */
+// Bug #130: Symbols that debugging / inspection tools access on every object.
+// Returning undefined for these prevents the proxy from recursing into itself
+// when inspected in DevTools, Node REPL, or util.inspect().
+const INSPECTION_SYMBOLS = new Set([
+    Symbol.toPrimitive,
+    Symbol.toStringTag,
+    Symbol.iterator,
+    Symbol.asyncIterator,
+    Symbol.hasInstance,
+    ...(typeof Symbol.for === 'function' ? [Symbol.for('nodejs.util.inspect.custom')] : []),
+]);
+function buildFluentProxy(execute, segments = []) {
+    return new Proxy(function () { }, {
+        get(_target, prop) {
+            if (typeof prop === 'symbol') {
+                // Bug #130: guard inspection symbols
+                if (INSPECTION_SYMBOLS.has(prop))
+                    return undefined;
+                return undefined; // all other symbols → safe no-op
+            }
+            if (prop === 'then')
+                return undefined;
+            return buildFluentProxy(execute, [...segments, prop]);
+        },
+        apply(_target, _thisArg, argsList) {
+            const action = segments.join('.');
+            const args = (argsList[0] ?? {});
+            return execute(action, args);
+        },
+    });
+}
+//# sourceMappingURL=VurbClient.js.map

package/dist/client/VurbClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"VurbClient.js","sourceRoot":"","sources":["../../src/client/VurbClient.ts"],"names":[],"mappings":"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"}

package/dist/client/createTypedRegistry.d.ts

@@ -0,0 +1,25 @@
+import { type ToolBuilder } from '../core/types.js';
+import { type TypedToolRegistry } from './InferRouter.js';
+/**
+ * Create a type-preserving tool registry.
+ *
+ * Uses currying to separate the `TContext` generic (explicitly provided)
+ * from the builder tuple types (automatically inferred).
+ *
+ * @typeParam TContext - Application context type (must be specified explicitly)
+ * @returns A function that accepts builders and creates the typed registry
+ *
+ * @example
+ * ```typescript
+ * // Step 1: Set the context type
+ * const createRegistry = createTypedRegistry<AppContext>();
+ *
+ * // Step 2: Register builders (types are inferred)
+ * const registry = createRegistry(projectsTool, billingTool);
+ *
+ * // Or as a one-liner:
+ * const registry = createTypedRegistry<AppContext>()(projectsTool, billingTool);
+ * ```
+ */
+export declare function createTypedRegistry<TContext>(): <TBuilders extends ToolBuilder<TContext>[]>(...builders: TBuilders) => TypedToolRegistry<TContext, TBuilders>;
+//# sourceMappingURL=createTypedRegistry.d.ts.map

package/dist/client/createTypedRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTypedRegistry.d.ts","sourceRoot":"","sources":["../../src/client/createTypedRegistry.ts"],"names":[],"mappings":"AAuCA,OAAO,EAAE,KAAK,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,MACvB,SAAS,SAAS,WAAW,CAAC,QAAQ,CAAC,EAAE,EACtD,GAAG,UAAU,SAAS,KACvB,iBAAiB,CAAC,QAAQ,EAAE,SAAS,CAAC,CAS5C"}

package/dist/client/createTypedRegistry.js

@@ -0,0 +1,74 @@
+/**
+ * createTypedRegistry — Type-Preserving Registry Factory
+ *
+ * Creates a `ToolRegistry` that preserves the builder types at compile time,
+ * enabling `InferRouter<typeof registry>` to extract a fully typed router map.
+ *
+ * Uses the **curried factory pattern** (like tRPC's `initTRPC.create()`)
+ * to separate the context type parameter from the builder tuple inference.
+ *
+ * @example
+ * ```typescript
+ * import { createTypedRegistry, createTool, success } from 'vurb';
+ *
+ * interface AppContext { db: Database; user: User }
+ *
+ * const projects = createTool<AppContext>('projects')
+ *     .action({ name: 'list', handler: async (ctx) => success([]) })
+ *     .action({ name: 'create', schema: z.object({ name: z.string() }),
+ *               handler: async (ctx, args) => success(args.name) });
+ *
+ * const billing = createTool<AppContext>('billing')
+ *     .action({ name: 'refund', handler: async (ctx) => success('ok') });
+ *
+ * // Curried: first call sets context, second registers builders
+ * const registry = createTypedRegistry<AppContext>()(projects, billing);
+ *
+ * // Runtime: use registry.registry for server attachment
+ * registry.registry.attachToServer(server, { contextFactory });
+ *
+ * // Types: export for client-side inference
+ * export type AppRouter = InferRouter<typeof registry>;
+ * ```
+ *
+ * @typeParam TContext - Application context type
+ * @returns A curried function that accepts builders and returns a typed registry
+ *
+ * @module
+ */
+import { ToolRegistry } from '../core/registry/ToolRegistry.js';
+import {} from '../core/types.js';
+import {} from './InferRouter.js';
+/**
+ * Create a type-preserving tool registry.
+ *
+ * Uses currying to separate the `TContext` generic (explicitly provided)
+ * from the builder tuple types (automatically inferred).
+ *
+ * @typeParam TContext - Application context type (must be specified explicitly)
+ * @returns A function that accepts builders and creates the typed registry
+ *
+ * @example
+ * ```typescript
+ * // Step 1: Set the context type
+ * const createRegistry = createTypedRegistry<AppContext>();
+ *
+ * // Step 2: Register builders (types are inferred)
+ * const registry = createRegistry(projectsTool, billingTool);
+ *
+ * // Or as a one-liner:
+ * const registry = createTypedRegistry<AppContext>()(projectsTool, billingTool);
+ * ```
+ */
+export function createTypedRegistry() {
+    return function (...builders) {
+        const registry = new ToolRegistry();
+        registry.registerAll(...builders);
+        return {
+            registry,
+            _builders: builders,
+            _context: undefined,
+        };
+    };
+}
+//# sourceMappingURL=createTypedRegistry.js.map

package/dist/client/createTypedRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"createTypedRegistry.js","sourceRoot":"","sources":["../../src/client/createTypedRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AAChE,OAAO,EAAoB,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAA0B,MAAM,kBAAkB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,mBAAmB;IAC/B,OAAO,UACH,GAAG,QAAmB;QAEtB,MAAM,QAAQ,GAAG,IAAI,YAAY,EAAY,CAAC;QAC9C,QAAQ,CAAC,WAAW,CAAC,GAAG,QAAQ,CAAC,CAAC;QAClC,OAAO;YACH,QAAQ;YACR,SAAS,EAAE,QAAQ;YACnB,QAAQ,EAAE,SAAgC;SAC7C,CAAC;IACN,CAAC,CAAC;AACN,CAAC"}

package/dist/client/index.d.ts

@@ -0,0 +1,6 @@
+/** Client Bounded Context — Barrel Export */
+export { createVurbClient, VurbClientError } from './VurbClient.js';
+export type { VurbClient, VurbTransport, RouterMap, FluentProxy, ClientMiddleware, VurbClientOptions, } from './VurbClient.js';
+export { createTypedRegistry } from './createTypedRegistry.js';
+export type { InferRouter, TypedToolRegistry } from './InferRouter.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EACR,UAAU,EACV,aAAa,EACb,SAAS,EACT,WAAW,EACX,gBAAgB,EAChB,iBAAiB,GACpB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,4 @@
+/** Client Bounded Context — Barrel Export */
+export { createVurbClient, VurbClientError } from './VurbClient.js';
+export { createTypedRegistry } from './createTypedRegistry.js';
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AASpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/converters/ConverterBase.d.ts

@@ -0,0 +1,68 @@
+/**
+ * ConverterBase — Generic Base for Bidirectional Converters
+ *
+ * Provides batch conversion with null filtering in both directions.
+ * Domain-specific converters extend this class and only implement
+ * the single-item abstract methods: {@link convertFrom} and {@link convertTo}.
+ *
+ * @typeParam TSource - The domain model type (e.g. Group, Tool)
+ * @typeParam TTarget - The external/DTO type
+ *
+ * @example
+ * ```typescript
+ * import { ToolConverterBase, Tool } from 'vurb';
+ *
+ * interface ToolDto { id: string; label: string }
+ *
+ * class MyToolConverter extends ToolConverterBase<ToolDto> {
+ *     convertFrom(tool: Tool): ToolDto {
+ *         return { id: tool.name, label: tool.title ?? tool.name };
+ *     }
+ *     convertTo(dto: ToolDto): Tool {
+ *         const tool = new Tool(dto.id);
+ *         tool.title = dto.label;
+ *         return tool;
+ *     }
+ * }
+ *
+ * const converter = new MyToolConverter();
+ * const dtos = converter.convertFromBatch(tools);  // Tool[] → ToolDto[]
+ * const tools = converter.convertToBatch(dtos);     // ToolDto[] → Tool[]
+ * ```
+ *
+ * @see {@link ToolConverterBase} for tool-specific converters
+ * @see {@link GroupConverterBase} for group-specific converters
+ */
+export declare abstract class ConverterBase<TSource, TTarget> {
+    /**
+     * Convert a batch of source items to target items.
+     * Null/undefined results from single-item conversion are filtered out.
+     *
+     * @param sources - Array of domain model instances
+     * @returns Array of converted DTOs (nulls removed)
+     */
+    convertFromBatch(sources: TSource[]): TTarget[];
+    /**
+     * Convert a single source item to a target item.
+     *
+     * @param source - Domain model instance
+     * @returns The converted DTO
+     */
+    abstract convertFrom(source: TSource): TTarget;
+    /**
+     * Convert a batch of target items back to source items.
+     * Null/undefined results from single-item conversion are filtered out.
+     *
+     * @param targets - Array of DTOs
+     * @returns Array of domain model instances (nulls removed)
+     */
+    convertToBatch(targets: TTarget[]): TSource[];
+    /**
+     * Convert a single target item back to a source item.
+     *
+     * @param target - DTO instance
+     * @returns The domain model instance
+     */
+    abstract convertTo(target: TTarget): TSource;
+}
+//# sourceMappingURL=ConverterBase.d.ts.map

package/dist/converters/ConverterBase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConverterBase.d.ts","sourceRoot":"","sources":["../../src/converters/ConverterBase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,8BAAsB,aAAa,CAAC,OAAO,EAAE,OAAO;IAChD;;;;;;OAMG;IACH,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE;IAM/C;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;IAE9C;;;;;;OAMG;IACH,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE;IAM7C;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,GAAG,OAAO;CAC/C"}

package/dist/converters/ConverterBase.js

@@ -0,0 +1,62 @@
+/**
+ * ConverterBase — Generic Base for Bidirectional Converters
+ *
+ * Provides batch conversion with null filtering in both directions.
+ * Domain-specific converters extend this class and only implement
+ * the single-item abstract methods: {@link convertFrom} and {@link convertTo}.
+ *
+ * @typeParam TSource - The domain model type (e.g. Group, Tool)
+ * @typeParam TTarget - The external/DTO type
+ *
+ * @example
+ * ```typescript
+ * import { ToolConverterBase, Tool } from 'vurb';
+ *
+ * interface ToolDto { id: string; label: string }
+ *
+ * class MyToolConverter extends ToolConverterBase<ToolDto> {
+ *     convertFrom(tool: Tool): ToolDto {
+ *         return { id: tool.name, label: tool.title ?? tool.name };
+ *     }
+ *     convertTo(dto: ToolDto): Tool {
+ *         const tool = new Tool(dto.id);
+ *         tool.title = dto.label;
+ *         return tool;
+ *     }
+ * }
+ *
+ * const converter = new MyToolConverter();
+ * const dtos = converter.convertFromBatch(tools);  // Tool[] → ToolDto[]
+ * const tools = converter.convertToBatch(dtos);     // ToolDto[] → Tool[]
+ * ```
+ *
+ * @see {@link ToolConverterBase} for tool-specific converters
+ * @see {@link GroupConverterBase} for group-specific converters
+ */
+export class ConverterBase {
+    /**
+     * Convert a batch of source items to target items.
+     * Null/undefined results from single-item conversion are filtered out.
+     *
+     * @param sources - Array of domain model instances
+     * @returns Array of converted DTOs (nulls removed)
+     */
+    convertFromBatch(sources) {
+        return sources
+            .map(s => this.convertFrom(s))
+            .filter((item) => item != null);
+    }
+    /**
+     * Convert a batch of target items back to source items.
+     * Null/undefined results from single-item conversion are filtered out.
+     *
+     * @param targets - Array of DTOs
+     * @returns Array of domain model instances (nulls removed)
+     */
+    convertToBatch(targets) {
+        return targets
+            .map(t => this.convertTo(t))
+            .filter((item) => item != null);
+    }
+}
+//# sourceMappingURL=ConverterBase.js.map

package/dist/converters/ConverterBase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConverterBase.js","sourceRoot":"","sources":["../../src/converters/ConverterBase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,MAAM,OAAgB,aAAa;IAC/B;;;;;;OAMG;IACH,gBAAgB,CAAC,OAAkB;QAC/B,OAAO,OAAO;aACT,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;aAC7B,MAAM,CAAC,CAAC,IAAI,EAAgC,EAAE,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;IACtE,CAAC;IAUD;;;;;;OAMG;IACH,cAAc,CAAC,OAAkB;QAC7B,OAAO,OAAO;aACT,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;aAC3B,MAAM,CAAC,CAAC,IAAI,EAAgC,EAAE,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;IACtE,CAAC;CASJ"}

package/dist/converters/GroupConverter.d.ts

@@ -0,0 +1,33 @@
+import { type Group } from '../domain/Group.js';
+import { ConverterBase } from './ConverterBase.js';
+/**
+ * Type-safe Group converter contract.
+ *
+ * @typeParam T - The target DTO type
+ * @see {@link GroupConverterBase} for the base implementation class
+ */
+export type GroupConverter<T> = ConverterBase<Group, T>;
+/**
+ * Base class for Group converters.
+ *
+ * Extend this and implement `convertFrom(group)` and `convertTo(dto)`.
+ *
+ * @typeParam T - The target DTO type
+ *
+ * @example
+ * ```typescript
+ * class MyGroupConverter extends GroupConverterBase<GroupDto> {
+ *     convertFrom(group: Group): GroupDto {
+ *         return { name: group.name, children: group.childGroups.length };
+ *     }
+ *     convertTo(dto: GroupDto): Group {
+ *         return new Group(dto.name);
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link ConverterBase} for batch conversion methods
+ */
+export declare abstract class GroupConverterBase<T> extends ConverterBase<Group, T> {
+}
+//# sourceMappingURL=GroupConverter.d.ts.map

package/dist/converters/GroupConverter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GroupConverter.d.ts","sourceRoot":"","sources":["../../src/converters/GroupConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;AAExD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,8BAAsB,kBAAkB,CAAC,CAAC,CAAE,SAAQ,aAAa,CAAC,KAAK,EAAE,CAAC,CAAC;CAAG"}

package/dist/converters/GroupConverter.js

@@ -0,0 +1,26 @@
+import {} from '../domain/Group.js';
+import { ConverterBase } from './ConverterBase.js';
+/**
+ * Base class for Group converters.
+ *
+ * Extend this and implement `convertFrom(group)` and `convertTo(dto)`.
+ *
+ * @typeParam T - The target DTO type
+ *
+ * @example
+ * ```typescript
+ * class MyGroupConverter extends GroupConverterBase<GroupDto> {
+ *     convertFrom(group: Group): GroupDto {
+ *         return { name: group.name, children: group.childGroups.length };
+ *     }
+ *     convertTo(dto: GroupDto): Group {
+ *         return new Group(dto.name);
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link ConverterBase} for batch conversion methods
+ */
+export class GroupConverterBase extends ConverterBase {
+}
+//# sourceMappingURL=GroupConverter.js.map

package/dist/converters/GroupConverter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"GroupConverter.js","sourceRoot":"","sources":["../../src/converters/GroupConverter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAUnD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,OAAgB,kBAAsB,SAAQ,aAAuB;CAAG"}

package/dist/converters/PromptConverter.d.ts

@@ -0,0 +1,33 @@
+import { type Prompt } from '../domain/Prompt.js';
+import { ConverterBase } from './ConverterBase.js';
+/**
+ * Type-safe Prompt converter contract.
+ *
+ * @typeParam T - The target DTO type
+ * @see {@link PromptConverterBase} for the base implementation class
+ */
+export type PromptConverter<T> = ConverterBase<Prompt, T>;
+/**
+ * Base class for Prompt converters.
+ *
+ * Extend this and implement `convertFrom(prompt)` and `convertTo(dto)`.
+ *
+ * @typeParam T - The target DTO type
+ *
+ * @example
+ * ```typescript
+ * class MyPromptConverter extends PromptConverterBase<PromptDto> {
+ *     convertFrom(prompt: Prompt): PromptDto {
+ *         return { name: prompt.name, args: prompt.promptArguments.length };
+ *     }
+ *     convertTo(dto: PromptDto): Prompt {
+ *         return new Prompt(dto.name);
+ *     }
+ * }
+ * ```
+ *
+ * @see {@link ConverterBase} for batch conversion methods
+ */
+export declare abstract class PromptConverterBase<T> extends ConverterBase<Prompt, T> {
+}
+//# sourceMappingURL=PromptConverter.d.ts.map