hono-apcore 0.1.0

package/dist/tools/define-tool.js

@@ -0,0 +1,122 @@
+import { createScannedModule, enrichSchemaDescriptions } from 'apcore-toolkit';
+import { defaultSchemaExtractor } from '../schema/schema-extractor.js';
+import { generateModuleId, normalizeMethodName, applyModulePrefix } from '../utils/id-generator.js';
+import { EMPTY_OBJECT_SCHEMA, normalizeResult, toModuleAnnotations, } from '../utils/module-factory.js';
+/**
+ * Identity helper that gives a tool literal full type inference and a single
+ * obvious place to look for the shape.
+ *
+ * This is the Hono counterpart to NestJS's `@ApTool` decorator: Hono has no
+ * classes or DI container to decorate, so a tool is a plain object carrying
+ * its own metadata and handler.
+ *
+ * @example
+ * ```ts
+ * const listTodos = defineTool({
+ *   namespace: 'todo',
+ *   name: 'list',
+ *   description: 'List all todos',
+ *   inputSchema: Type.Object({ done: Type.Optional(Type.Boolean()) }),
+ *   annotations: { readonly: true, idempotent: true },
+ *   handler: (inputs) => ({ todos: store.filter(...) }),
+ * });
+ * ```
+ */
+export function defineTool(definition) {
+    return definition;
+}
+/**
+ * Group several tools under one namespace, applying shared tags and
+ * annotations to each.
+ *
+ * The record key becomes the tool's `name` when the entry does not set one,
+ * so `{ list: {...} }` under namespace `todo` yields `todo.list`.
+ *
+ * @example
+ * ```ts
+ * const todoTools = defineToolset({
+ *   namespace: 'todo',
+ *   tags: ['todo'],
+ *   tools: {
+ *     list:   { description: 'List todos', handler: list },
+ *     create: { description: 'Add a todo', handler: create },
+ *   },
+ * });
+ * ```
+ */
+export function defineToolset(options) {
+    const { namespace, description, tags, annotations, tools } = options;
+    return Object.entries(tools).map(([key, tool]) => ({
+        ...tool,
+        namespace,
+        name: tool.name ?? key,
+        description: tool.description || description || key,
+        tags: tool.tags ?? tags,
+        annotations: tool.annotations ?? annotations,
+    }));
+}
+/** Resolve the module ID a tool definition will be registered under. */
+export function resolveToolId(tool, modulePrefix) {
+    if (tool.id != null) {
+        return applyModulePrefix(tool.id, modulePrefix);
+    }
+    // An anonymous handler written inline picks up the property key as its
+    // name — `{ handler: () => {} }` yields `"handler"` — which would silently
+    // produce a module called `<namespace>.handler`, so it is not a usable
+    // fallback.
+    const inferred = tool.handler.name === 'handler' ? '' : tool.handler.name;
+    const name = tool.name ?? inferred;
+    if (!name) {
+        throw new Error('Tool definition needs an "id", a "name", or a named handler function to derive its module ID from.');
+    }
+    const base = generateModuleId(tool.namespace ?? '', normalizeMethodName(name), false, null);
+    return applyModulePrefix(base, modulePrefix);
+}
+function extractSchema(extractor, input, moduleId, field) {
+    if (input == null)
+        return { ...EMPTY_OBJECT_SCHEMA };
+    try {
+        return extractor.extractJsonSchema(input);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to extract ${field} for tool "${moduleId}": ${reason}`);
+    }
+}
+/**
+ * Convert a {@link ApToolDefinition} into the toolkit's `ScannedModule`
+ * intermediate plus the bound execute function the registry needs.
+ *
+ * Schemas are normalised to JSON Schema, and JSDoc on the handler fills in
+ * missing documentation and per-parameter descriptions.
+ */
+export function toolToScannedModule(tool, options = {}) {
+    const extractor = options.schemaExtractor ?? defaultSchemaExtractor;
+    const moduleId = resolveToolId(tool, options.modulePrefix);
+    let inputSchema = extractSchema(extractor, tool.inputSchema, moduleId, 'inputSchema');
+    const outputSchema = extractSchema(extractor, tool.outputSchema, moduleId, 'outputSchema');
+    // JavaScript gives no runtime access to a function's leading comments — the
+    // way Python reads a docstring — so per-parameter prose is declared with the
+    // explicit `params` field instead of inferred from JSDoc.
+    if (tool.params && Object.keys(tool.params).length > 0) {
+        inputSchema = enrichSchemaDescriptions(inputSchema, tool.params);
+    }
+    const tags = [...new Set([...(tool.tags ?? []), ...(options.tags ?? [])])];
+    const module = createScannedModule({
+        moduleId,
+        description: tool.description,
+        inputSchema,
+        outputSchema,
+        tags,
+        target: tool.handler.name || moduleId,
+        annotations: toModuleAnnotations(tool.annotations),
+        documentation: tool.documentation ?? null,
+        examples: tool.examples ?? [],
+    });
+    const execute = async (inputs, context) => {
+        const raw = await tool.handler(inputs, context);
+        return normalizeResult(raw);
+    };
+    return { module, execute };
+}
+//# sourceMappingURL=define-tool.js.map

package/dist/tools/define-tool.js.map

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

package/dist/tools/index.d.ts

@@ -0,0 +1,3 @@
+export { defineTool, defineToolset, resolveToolId, toolToScannedModule } from './define-tool.js';
+export type { ToolConversionOptions } from './define-tool.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACjG,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,2 @@
+export { defineTool, defineToolset, resolveToolId, toolToScannedModule } from './define-tool.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,246 @@
+export type { ModuleAnnotations, ModuleExample, Module, Context, Identity, ModuleDescriptor, PreflightResult, PreflightCheckResult, ValidationResult, } from 'apcore-js';
+/** Annotations describing tool behaviour characteristics. */
+export interface ApToolAnnotations {
+    readonly?: boolean;
+    destructive?: boolean;
+    idempotent?: boolean;
+    requiresApproval?: boolean;
+    openWorld?: boolean;
+    streaming?: boolean;
+    cacheable?: boolean;
+    cacheTtl?: number;
+    cacheKeyFields?: string[] | null;
+    paginated?: boolean;
+    paginationStyle?: 'cursor' | 'offset' | 'page';
+}
+/** Example entry for a tool invocation. */
+export interface ApToolExample {
+    title: string;
+    inputs: Record<string, unknown>;
+    output: Record<string, unknown>;
+    description?: string;
+}
+/**
+ * Handler signature for a tool defined with {@link defineTool}.
+ *
+ * `inputs` is the validated argument object; `context` is the apcore
+ * `Context` for the current call (identity, trace, data), or `undefined`
+ * when the caller did not supply one.
+ */
+export type ApToolHandler = (inputs: Record<string, unknown>, context?: unknown) => unknown | Promise<unknown>;
+/**
+ * A tool definition — the Hono counterpart to NestJS's `@ApTool` decorator.
+ *
+ * Either `id` or `name` must be present: `id` is used verbatim, while `name`
+ * is combined with `namespace` to produce `"<namespace>.<name>"`.
+ */
+export interface ApToolDefinition {
+    /** Fully-qualified module ID. Takes precedence over `namespace`/`name`. */
+    id?: string;
+    /** Namespace segment of the generated module ID. */
+    namespace?: string;
+    /** Name segment of the generated module ID (snake_cased if camelCase). */
+    name?: string;
+    /** Human-readable description surfaced to AI clients. Required. */
+    description: string;
+    /** TypeBox, Zod, or plain JSON Schema describing the inputs. */
+    inputSchema?: unknown;
+    /** TypeBox, Zod, or plain JSON Schema describing the output. */
+    outputSchema?: unknown;
+    annotations?: ApToolAnnotations | null;
+    tags?: string[];
+    documentation?: string | null;
+    examples?: ApToolExample[];
+    /**
+     * Per-parameter prose merged into the input schema's property descriptions.
+     *
+     * JavaScript cannot read a function's leading comments at run time — the way
+     * Python reads a docstring — so parameter documentation is declared here
+     * rather than inferred from JSDoc.
+     */
+    params?: Record<string, string>;
+    /** The function executed when the tool is called. */
+    handler: ApToolHandler;
+}
+/** Shared defaults applied to every tool in a {@link defineToolset} group. */
+export interface ApToolsetOptions {
+    namespace: string;
+    description?: string | null;
+    tags?: string[];
+    annotations?: ApToolAnnotations | null;
+    tools: Record<string, Omit<ApToolDefinition, 'namespace' | 'name' | 'description'> & {
+        name?: string;
+        /** Falls back to the toolset description, then the record key. */
+        description?: string;
+    }>;
+}
+/** Options accepted by {@link createApcore} / the {@link HonoApcore} constructor. */
+export interface HonoApcoreOptions {
+    /** Directory scanned by `Registry.discover()` for filesystem extensions. */
+    extensionsDir?: string | null;
+    /** apcore `ACL` instance enforced by the Executor on every call. */
+    acl?: unknown | null;
+    /** apcore `Middleware` instances installed on the Executor. */
+    middleware?: unknown[];
+    /** Path to a YAML bindings file loaded during {@link HonoApcore.init}. */
+    bindings?: string | null;
+    /** Tools registered eagerly during construction. */
+    tools?: ApToolDefinition[];
+    /** MCP surface configuration. Presence enables the MCP service. */
+    mcp?: ApcoreMcpOptions;
+    /** CLI surface configuration. Presence enables the CLI service. */
+    cli?: ApcoreCliOptions;
+    /** A2A surface configuration. Presence enables the A2A service. */
+    a2a?: ApcoreA2aOptions;
+    /** Route-scanner configuration used by {@link HonoApcore.scanRoutes}. */
+    routes?: RouteScanOptions;
+    /** Overrides merged over the `APCORE_*` environment settings. */
+    settings?: Partial<import('./config.js').ApcoreSettings>;
+}
+/** Options for the MCP surface. Mirrors `apcore-mcp`'s serve options. */
+export interface ApcoreMcpOptions {
+    transport?: 'stdio' | 'streamable-http' | 'sse';
+    host?: string;
+    port?: number;
+    name?: string;
+    version?: string;
+    tags?: string[] | null;
+    prefix?: string | null;
+    explorer?: boolean;
+    explorerPrefix?: string;
+    allowExecute?: boolean;
+    explorerTitle?: string;
+    explorerProjectName?: string;
+    explorerProjectUrl?: string;
+    dynamic?: boolean;
+    validateInputs?: boolean;
+    logLevel?: 'DEBUG' | 'INFO' | 'WARNING' | 'ERROR' | 'CRITICAL';
+    onStartup?: () => void | Promise<void>;
+    onShutdown?: () => void | Promise<void>;
+    metricsCollector?: unknown;
+    authenticator?: unknown;
+    requireAuth?: boolean;
+    exemptPaths?: string[];
+    approvalHandler?: unknown;
+    outputFormatter?: (result: Record<string, unknown>) => string;
+    /** Enable the full observability stack (metrics + usage middleware). */
+    observability?: unknown;
+    /** Built-in output format ("json", "csv", "jsonl"). */
+    outputFormat?: 'json' | 'csv' | 'jsonl';
+    /** Redact sensitive fields from tool output. Default: true. */
+    redactOutput?: boolean;
+    /** Attach a pipeline trace to tool responses. Default: false. */
+    trace?: boolean;
+    /** Execution strategy name. */
+    strategy?: string;
+    /** Additional apcore middleware installed on the MCP executor. */
+    mcpMiddleware?: unknown[];
+    /** Optional ACL instance for this MCP server. */
+    mcpAcl?: unknown;
+    /** Pluggable ApprovalStore for async approval polling. */
+    approvalStore?: unknown;
+    /** Callback invoked when a new approval is requested. */
+    approvalNotify?: (approvalId: string, moduleId: string, args: Record<string, unknown>) => Promise<void>;
+}
+/** Options for mounting the MCP endpoint into a Hono app. */
+export interface MountMcpOptions {
+    /** Path the MCP endpoint is served at. Default: `"/mcp"`. */
+    endpoint?: string;
+    /** Enable the Tool Explorer UI. Defaults to the MCP surface setting. */
+    explorer?: boolean;
+    /** URL prefix for the Explorer. Default: `"/explorer"`. */
+    explorerPrefix?: string;
+    /** Allow tool execution from the Explorer UI. */
+    allowExecute?: boolean;
+    /** Also mount `/health` and `/metrics`. Default: true. */
+    builtinRoutes?: boolean;
+}
+/** Options for the CLI surface. */
+export interface ApcoreCliOptions {
+    /** Path to the extensions directory (default: `./extensions`). */
+    extensionsDir?: string;
+    /** Program name shown in help output. */
+    progName?: string;
+    /** Show built-in apcore options in `--help`. Default: false. */
+    verboseHelp?: boolean;
+    /** Base URL for online documentation. */
+    docsUrl?: string | null;
+}
+/** Options for the A2A surface. */
+export interface ApcoreA2aOptions {
+    name?: string;
+    description?: string;
+    version?: string;
+    url?: string;
+    host?: string;
+    /** Port for a standalone A2A server. Omit to embed via `asyncServe()`. */
+    port?: number;
+    auth?: unknown;
+    taskStore?: unknown;
+    corsOrigins?: string[];
+    explorer?: boolean;
+    explorerPrefix?: string;
+    executionTimeout?: number;
+    metrics?: boolean;
+    logLevel?: string;
+    shutdownTimeout?: number;
+}
+/** Options controlling how Hono routes are turned into apcore modules. */
+export interface RouteScanOptions {
+    /** Prefix prepended to every generated module ID. */
+    modulePrefix?: string;
+    /** Only scan routes whose path matches one of these glob-ish patterns. */
+    includePaths?: string[];
+    /** Skip routes whose path matches one of these patterns. */
+    excludePaths?: string[];
+    /** Skip these HTTP methods. Default: `["HEAD", "OPTIONS"]`. */
+    excludeMethods?: string[];
+    /** Regex applied to generated module IDs — only matches are kept. */
+    include?: string;
+    /** Regex applied to generated module IDs — matches are removed. */
+    exclude?: string;
+    /** Tags attached to every scanned module. Default: `["http"]`. */
+    tags?: string[];
+    /** Per-route overrides keyed by `"<METHOD> <path>"`. */
+    overrides?: Record<string, RouteOverride>;
+    /** Base URL used when replaying requests through `app.request()`. */
+    baseUrl?: string;
+}
+/** Per-route metadata overrides applied during scanning. */
+export interface RouteOverride {
+    id?: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    annotations?: ApToolAnnotations | null;
+    tags?: string[];
+    documentation?: string | null;
+    examples?: ApToolExample[];
+    /** Skip this route entirely. */
+    skip?: boolean;
+}
+/** Options for registering a single method of a plain object as a module. */
+export interface RegisterMethodOptions {
+    instance: object;
+    method: string;
+    description: string;
+    id?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    annotations?: ApToolAnnotations;
+    tags?: string[];
+    documentation?: string | null;
+    examples?: ApToolExample[];
+}
+/** Options for registering every method of an object at once. */
+export interface RegisterObjectOptions {
+    instance: object;
+    description?: string;
+    methods: string[] | '*';
+    exclude?: string[];
+    namespace?: string;
+    annotations?: ApToolAnnotations;
+    tags?: string[];
+    methodOptions?: Record<string, Partial<RegisterMethodOptions>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

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

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/dist/utils/id-generator.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Convert a PascalCase or camelCase string to snake_case.
+ *
+ * Handles consecutive uppercase letters (acronyms) by inserting an
+ * underscore before the last uppercase letter of the run when it is
+ * followed by a lowercase letter — `"HTTPClient"` becomes `"http_client"`.
+ */
+export declare function toSnakeCase(value: string): string;
+/**
+ * Normalise a service/object name into a namespace segment: strip a trailing
+ * service suffix, then convert the remainder to snake_case.
+ *
+ * A name consisting *only* of a suffix is kept as-is (lowercased) rather than
+ * collapsing to an empty string.
+ *
+ * @example
+ * normalizeName('TodoService')  // 'todo'
+ * normalizeName('WeatherRoutes') // 'weather'
+ * normalizeName('HTTPClient')   // 'http_client'
+ */
+export declare function normalizeName(name: string): string;
+/**
+ * Normalise a method / tool name by converting camelCase to snake_case.
+ *
+ * @example
+ * normalizeMethodName('sendEmail')  // 'send_email'
+ * normalizeMethodName('send_email') // 'send_email'
+ */
+export declare function normalizeMethodName(name: string): string;
+/**
+ * Build a fully-qualified module ID of the form `"namespace.name"`.
+ *
+ * @param namespace  - Namespace portion of the ID.
+ * @param name       - Name portion of the ID.
+ * @param normalizeInputs - Apply {@link normalizeName} / {@link normalizeMethodName}
+ *   to the two segments before joining.
+ * @param explicitId - Returned verbatim when non-null, bypassing generation.
+ *
+ * @example
+ * generateModuleId('todo', 'list')                         // 'todo.list'
+ * generateModuleId('TodoService', 'listAll', true)         // 'todo.list_all'
+ * generateModuleId('a', 'b', false, 'custom.override')     // 'custom.override'
+ */
+export declare function generateModuleId(namespace: string, name: string, normalizeInputs?: boolean, explicitId?: string | null): string;
+/**
+ * Prepend a module-ID prefix, inserting the separating dot only when needed.
+ *
+ * An empty prefix returns the ID unchanged, and a prefix that already ends
+ * with `"."` is not given a second one.
+ */
+export declare function applyModulePrefix(moduleId: string, prefix?: string): string;
+//# sourceMappingURL=id-generator.d.ts.map

package/dist/utils/id-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../../src/utils/id-generator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAMjD;AAUD;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAWlD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,eAAe,CAAC,EAAE,OAAO,EACzB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GACzB,MAAM,CASR;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAG3E"}

package/dist/utils/id-generator.js

@@ -0,0 +1,87 @@
+/**
+ * Convert a PascalCase or camelCase string to snake_case.
+ *
+ * Handles consecutive uppercase letters (acronyms) by inserting an
+ * underscore before the last uppercase letter of the run when it is
+ * followed by a lowercase letter — `"HTTPClient"` becomes `"http_client"`.
+ */
+export function toSnakeCase(value) {
+    return value
+        .replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2')
+        .replace(/([a-z0-9])([A-Z])/g, '$1_$2')
+        .replace(/[\s-]+/g, '_')
+        .toLowerCase();
+}
+/**
+ * Suffixes stripped from handler/object names before normalisation.
+ *
+ * Hono has no class conventions of its own, so this covers the names people
+ * actually give the plain service objects they register.
+ */
+const SERVICE_SUFFIXES = ['Service', 'Handler', 'Handlers', 'Controller', 'Routes', 'Router'];
+/**
+ * Normalise a service/object name into a namespace segment: strip a trailing
+ * service suffix, then convert the remainder to snake_case.
+ *
+ * A name consisting *only* of a suffix is kept as-is (lowercased) rather than
+ * collapsing to an empty string.
+ *
+ * @example
+ * normalizeName('TodoService')  // 'todo'
+ * normalizeName('WeatherRoutes') // 'weather'
+ * normalizeName('HTTPClient')   // 'http_client'
+ */
+export function normalizeName(name) {
+    let stripped = name;
+    for (const suffix of SERVICE_SUFFIXES) {
+        if (name.endsWith(suffix) && name.length > suffix.length) {
+            stripped = name.slice(0, -suffix.length);
+            break;
+        }
+    }
+    return toSnakeCase(stripped);
+}
+/**
+ * Normalise a method / tool name by converting camelCase to snake_case.
+ *
+ * @example
+ * normalizeMethodName('sendEmail')  // 'send_email'
+ * normalizeMethodName('send_email') // 'send_email'
+ */
+export function normalizeMethodName(name) {
+    return toSnakeCase(name);
+}
+/**
+ * Build a fully-qualified module ID of the form `"namespace.name"`.
+ *
+ * @param namespace  - Namespace portion of the ID.
+ * @param name       - Name portion of the ID.
+ * @param normalizeInputs - Apply {@link normalizeName} / {@link normalizeMethodName}
+ *   to the two segments before joining.
+ * @param explicitId - Returned verbatim when non-null, bypassing generation.
+ *
+ * @example
+ * generateModuleId('todo', 'list')                         // 'todo.list'
+ * generateModuleId('TodoService', 'listAll', true)         // 'todo.list_all'
+ * generateModuleId('a', 'b', false, 'custom.override')     // 'custom.override'
+ */
+export function generateModuleId(namespace, name, normalizeInputs, explicitId) {
+    if (explicitId != null) {
+        return explicitId;
+    }
+    const ns = normalizeInputs ? normalizeName(namespace) : namespace;
+    const n = normalizeInputs ? normalizeMethodName(name) : name;
+    return ns.length > 0 ? `${ns}.${n}` : n;
+}
+/**
+ * Prepend a module-ID prefix, inserting the separating dot only when needed.
+ *
+ * An empty prefix returns the ID unchanged, and a prefix that already ends
+ * with `"."` is not given a second one.
+ */
+export function applyModulePrefix(moduleId, prefix) {
+    if (!prefix)
+        return moduleId;
+    return prefix.endsWith('.') ? `${prefix}${moduleId}` : `${prefix}.${moduleId}`;
+}
+//# sourceMappingURL=id-generator.js.map

package/dist/utils/id-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-generator.js","sourceRoot":"","sources":["../../src/utils/id-generator.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,KAAK;SACT,OAAO,CAAC,uBAAuB,EAAE,OAAO,CAAC;SACzC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC;SACtC,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,WAAW,EAAE,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,gBAAgB,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;AAE9F;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,QAAQ,GAAG,IAAI,CAAC;IAEpB,KAAK,MAAM,MAAM,IAAI,gBAAgB,EAAE,CAAC;QACtC,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC;YACzD,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACzC,MAAM;QACR,CAAC;IACH,CAAC;IAED,OAAO,WAAW,CAAC,QAAQ,CAAC,CAAC;AAC/B,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAC9B,SAAiB,EACjB,IAAY,EACZ,eAAyB,EACzB,UAA0B;IAE1B,IAAI,UAAU,IAAI,IAAI,EAAE,CAAC;QACvB,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,MAAM,EAAE,GAAG,eAAe,CAAC,CAAC,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAClE,MAAM,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAE7D,OAAO,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,MAAe;IACjE,IAAI,CAAC,MAAM;QAAE,OAAO,QAAQ,CAAC;IAC7B,OAAO,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,GAAG,QAAQ,EAAE,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,QAAQ,EAAE,CAAC;AACjF,CAAC"}

package/dist/utils/module-factory.d.ts

@@ -0,0 +1,34 @@
+import { FunctionModule } from 'apcore-js';
+import type { ModuleAnnotations } from 'apcore-js';
+import type { ScannedModule } from 'apcore-toolkit';
+import type { ApToolAnnotations } from '../types.js';
+/**
+ * Execute-function signature for Hono-bound modules.
+ *
+ * Unlike apcore-toolkit's `RegistryWriter` — which resolves a `target` string
+ * via dynamic import — a Hono integration already holds the closure, so the
+ * bound function is passed in directly.
+ */
+export type BoundExecuteFn = (inputs: Record<string, unknown>, context: unknown) => Promise<Record<string, unknown>> | Record<string, unknown>;
+/**
+ * Normalise a raw handler return value to a plain `Record<string, unknown>`.
+ *
+ * `null` / `undefined` become `{}`; arrays and primitives are wrapped as
+ * `{ result }` so every module honours the object-output contract.
+ */
+export declare function normalizeResult(raw: unknown): Record<string, unknown>;
+/**
+ * Widen partial {@link ApToolAnnotations} (all-optional booleans) into a full
+ * `ModuleAnnotations` by spreading over apcore-js's `DEFAULT_ANNOTATIONS`.
+ *
+ * Returns `null` when the input is nullish.
+ */
+export declare function toModuleAnnotations(partial: ApToolAnnotations | null | undefined): ModuleAnnotations | null;
+/**
+ * Convert a toolkit {@link ScannedModule} plus a pre-bound execute function
+ * into an apcore-js `FunctionModule` ready for registry registration.
+ */
+export declare function scannedModuleToFunctionModule(mod: ScannedModule, execute: BoundExecuteFn): FunctionModule;
+/** An empty JSON Schema object, used when a tool declares no schema. */
+export declare const EMPTY_OBJECT_SCHEMA: Record<string, unknown>;
+//# sourceMappingURL=module-factory.d.ts.map

package/dist/utils/module-factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"module-factory.d.ts","sourceRoot":"","sources":["../../src/utils/module-factory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAA4C,MAAM,WAAW,CAAC;AACrF,OAAO,KAAK,EAAE,iBAAiB,EAAiB,MAAM,WAAW,CAAC;AAElE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,OAAO,KACb,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIrE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,iBAAiB,GAAG,IAAI,GAAG,SAAS,GAC5C,iBAAiB,GAAG,IAAI,CAG1B;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,aAAa,EAClB,OAAO,EAAE,cAAc,GACtB,cAAc,CAuBhB;AAED,wEAAwE;AACxE,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAGtD,CAAC"}

package/dist/utils/module-factory.js

@@ -0,0 +1,59 @@
+import { FunctionModule, DEFAULT_ANNOTATIONS, jsonSchemaToTypeBox } from 'apcore-js';
+import { annotationsToDict } from 'apcore-toolkit';
+/**
+ * Normalise a raw handler return value to a plain `Record<string, unknown>`.
+ *
+ * `null` / `undefined` become `{}`; arrays and primitives are wrapped as
+ * `{ result }` so every module honours the object-output contract.
+ */
+export function normalizeResult(raw) {
+    if (raw === null || raw === undefined)
+        return {};
+    if (typeof raw === 'object' && !Array.isArray(raw))
+        return raw;
+    return { result: raw };
+}
+/**
+ * Widen partial {@link ApToolAnnotations} (all-optional booleans) into a full
+ * `ModuleAnnotations` by spreading over apcore-js's `DEFAULT_ANNOTATIONS`.
+ *
+ * Returns `null` when the input is nullish.
+ */
+export function toModuleAnnotations(partial) {
+    if (partial == null)
+        return null;
+    return { ...DEFAULT_ANNOTATIONS, ...partial };
+}
+/**
+ * Convert a toolkit {@link ScannedModule} plus a pre-bound execute function
+ * into an apcore-js `FunctionModule` ready for registry registration.
+ */
+export function scannedModuleToFunctionModule(mod, execute) {
+    // Strip internal keys (leading underscore) from metadata so they do not
+    // leak into the module's public descriptor.
+    const cleanMetadata = {};
+    for (const [k, v] of Object.entries(mod.metadata)) {
+        if (!k.startsWith('_')) {
+            cleanMetadata[k] = v;
+        }
+    }
+    return new FunctionModule({
+        execute,
+        moduleId: mod.moduleId,
+        inputSchema: jsonSchemaToTypeBox(mod.inputSchema),
+        outputSchema: jsonSchemaToTypeBox(mod.outputSchema),
+        description: mod.description,
+        documentation: mod.documentation,
+        tags: mod.tags.length > 0 ? [...mod.tags] : null,
+        version: mod.version,
+        annotations: annotationsToDict(mod.annotations),
+        metadata: Object.keys(cleanMetadata).length > 0 ? cleanMetadata : null,
+        examples: mod.examples.length > 0 ? [...mod.examples] : null,
+    });
+}
+/** An empty JSON Schema object, used when a tool declares no schema. */
+export const EMPTY_OBJECT_SCHEMA = Object.freeze({
+    type: 'object',
+    properties: {},
+});
+//# sourceMappingURL=module-factory.js.map