hono-apcore 0.1.0

package/dist/mcp/apcore-mcp.service.js

@@ -0,0 +1,189 @@
+/** Options forwarded to both `serve()` and `asyncServe()`. */
+const SHARED_OPTION_KEYS = [
+    'name',
+    'version',
+    'tags',
+    'prefix',
+    'validateInputs',
+    'logLevel',
+    'metricsCollector',
+    'observability',
+    'authenticator',
+    'requireAuth',
+    'exemptPaths',
+    'approvalHandler',
+    'approvalStore',
+    'approvalNotify',
+    'outputFormatter',
+    'outputFormat',
+    'redactOutput',
+    'trace',
+    'strategy',
+];
+/** Options only `serve()` understands (they configure a standalone server). */
+const SERVE_ONLY_KEYS = [
+    'transport',
+    'host',
+    'port',
+    'explorer',
+    'explorerPrefix',
+    'allowExecute',
+    'dynamic',
+    'onStartup',
+    'onShutdown',
+    'explorerTitle',
+    'explorerProjectName',
+    'explorerProjectUrl',
+];
+/** Options renamed on their way to `apcore-mcp`. */
+const RENAMED_OPTIONS = {
+    mcpMiddleware: 'middleware',
+    mcpAcl: 'acl',
+};
+/**
+ * Manages the MCP (Model Context Protocol) server for a Hono app.
+ *
+ * `apcore-mcp` is an **optional** peer dependency and is loaded lazily, so
+ * importing `hono-apcore` stays safe on runtimes without `node:http`
+ * (Workers, Deno, Bun) as long as the MCP surface goes unused there.
+ *
+ * Two deployment shapes are supported:
+ *
+ * - **Standalone** — {@link start} runs an MCP server on its own port, next
+ *   to the Hono HTTP server. Configure `transport` to enable it.
+ * - **Embedded** — {@link asyncServe} returns a request handler that
+ *   {@link mountMcp} wires into the Hono app itself, so one port serves both.
+ */
+export class ApcoreMcpService {
+    registry;
+    executor;
+    options;
+    _isRunning = false;
+    _app = null;
+    constructor(registry, executor, options) {
+        this.registry = registry;
+        this.executor = executor;
+        this.options = options;
+    }
+    // -------------------------------------------------------------------------
+    // Properties
+    // -------------------------------------------------------------------------
+    /** Whether a standalone MCP server has been started. */
+    get isRunning() {
+        return this._isRunning;
+    }
+    /** The embedded MCP app, once {@link asyncServe} has built one. */
+    get app() {
+        return this._app;
+    }
+    /** Number of tools exposed, honouring the module-level `tags` / `prefix`. */
+    get toolCount() {
+        return this.registry.list({
+            tags: this.options.tags ?? undefined,
+            prefix: this.options.prefix ?? undefined,
+        }).length;
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Start a standalone MCP server using the configured transport.
+     *
+     * With `transport: 'stdio'` this occupies the process's stdio, so it is the
+     * right choice for a CLI-launched MCP server and the wrong one for a web
+     * process — use {@link asyncServe} there.
+     *
+     * @param overrides - Per-call option overrides, e.g. the flags the
+     *   `hono-apcore serve` command accepts.
+     */
+    async start(overrides = {}) {
+        const { serve } = await import('apcore-mcp');
+        this._isRunning = true;
+        const serveOptions = {
+            ...this.collectOptions(SHARED_OPTION_KEYS),
+            ...this.collectOptions(SERVE_ONLY_KEYS),
+        };
+        for (const [key, value] of Object.entries(overrides)) {
+            if (value !== undefined)
+                serveOptions[key] = value;
+        }
+        await serve(this.executor.raw, serveOptions);
+    }
+    /**
+     * Build an embeddable MCP request handler without starting a server.
+     *
+     * Repeated calls return the same app; call {@link stop} to tear it down.
+     *
+     * @param options - Per-call overrides for endpoint and Explorer settings.
+     */
+    async asyncServe(options) {
+        if (this._app)
+            return this._app;
+        const { asyncServe } = await import('apcore-mcp');
+        const asyncOptions = {
+            ...this.collectOptions(SHARED_OPTION_KEYS),
+            explorer: options?.explorer ?? this.options.explorer,
+            explorerPrefix: options?.explorerPrefix ?? this.options.explorerPrefix,
+            allowExecute: options?.allowExecute ?? this.options.allowExecute,
+            explorerTitle: this.options.explorerTitle,
+            explorerProjectName: this.options.explorerProjectName,
+            explorerProjectUrl: this.options.explorerProjectUrl,
+        };
+        if (options?.endpoint !== undefined)
+            asyncOptions['endpoint'] = options.endpoint;
+        if (options?.dynamic !== undefined)
+            asyncOptions['dynamic'] = options.dynamic;
+        for (const key of Object.keys(asyncOptions)) {
+            if (asyncOptions[key] === undefined)
+                delete asyncOptions[key];
+        }
+        this._app = (await asyncServe(this.executor.raw, asyncOptions));
+        return this._app;
+    }
+    /** Tear down the embedded MCP app and mark the service stopped. */
+    async stop() {
+        this._isRunning = false;
+        if (this._app) {
+            await this._app.close();
+            this._app = null;
+        }
+    }
+    /** Stop, then start the standalone MCP server. */
+    async restart() {
+        await this.stop();
+        await this.start();
+    }
+    // -------------------------------------------------------------------------
+    // Tool conversion
+    // -------------------------------------------------------------------------
+    /**
+     * Convert the registered modules to OpenAI-compatible tool definitions,
+     * ready to hand to a chat-completions `tools` parameter.
+     */
+    async toOpenaiTools(options) {
+        const { toOpenaiTools } = await import('apcore-mcp');
+        return toOpenaiTools(this.executor.raw, options ?? {
+            tags: this.options.tags ?? undefined,
+            prefix: this.options.prefix ?? undefined,
+        });
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /** Collect the defined values for `keys`, applying any option renames. */
+    collectOptions(keys) {
+        const result = {};
+        for (const key of keys) {
+            const value = this.options[key];
+            if (value !== undefined)
+                result[key] = value;
+        }
+        for (const [from, to] of Object.entries(RENAMED_OPTIONS)) {
+            const value = this.options[from];
+            if (value !== undefined)
+                result[to] = value;
+        }
+        return result;
+    }
+}
+//# sourceMappingURL=apcore-mcp.service.js.map

package/dist/mcp/apcore-mcp.service.js.map

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

package/dist/mcp/index.d.ts

@@ -0,0 +1,5 @@
+export { ApcoreMcpService } from './apcore-mcp.service.js';
+export type { McpApp } from './apcore-mcp.service.js';
+export { mountMcp, toHonoHandler, RESPONSE_ALREADY_SENT } from './mount.js';
+export type { MountableApp } from './mount.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAC3D,YAAY,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAC5E,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,3 @@
+export { ApcoreMcpService } from './apcore-mcp.service.js';
+export { mountMcp, toHonoHandler, RESPONSE_ALREADY_SENT } from './mount.js';
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}

package/dist/mcp/mount.d.ts

@@ -0,0 +1,51 @@
+import type { ApcoreMcpService, McpApp } from './apcore-mcp.service.js';
+import type { MountMcpOptions } from '../types.js';
+/** The subset of a Hono app used for mounting. */
+export interface MountableApp {
+    all: (path: string, handler: (c: unknown) => Promise<Response> | Response) => unknown;
+}
+/**
+ * The sentinel `@hono/node-server` recognises as "the handler already wrote
+ * this response itself".
+ *
+ * Constructed here rather than imported from
+ * `@hono/node-server/utils/response` so mounting never makes the Node adapter
+ * a hard dependency; the header name is the contract.
+ */
+export declare const RESPONSE_ALREADY_SENT: Response;
+/**
+ * Wrap `apcore-mcp`'s Node request handler as a Hono handler.
+ *
+ * The MCP transport speaks Streamable HTTP with SSE, which needs direct
+ * control of the response stream — so the handler writes to the Node
+ * `ServerResponse` and returns the already-sent sentinel instead of a
+ * `Response` Hono would try to serialise itself.
+ */
+export declare function toHonoHandler(mcpApp: McpApp): (c: unknown) => Promise<Response>;
+/**
+ * Mount the MCP endpoint — and, when enabled, the Tool Explorer UI and the
+ * `/health`, `/metrics`, `/usage` routes — into an existing Hono app.
+ *
+ * One process, one port: the app keeps serving its own routes while AI
+ * clients talk MCP at `endpoint`.
+ *
+ * **Node runtime only.** The MCP transport needs the raw Node request and
+ * response objects that `@hono/node-server` exposes on `c.env`. On other
+ * runtimes, run the server standalone with {@link ApcoreMcpService.start}.
+ *
+ * `endpoint` must be the path as the HTTP server sees it — if the Hono app
+ * itself sits under a `basePath`, include that prefix here.
+ *
+ * @example
+ * ```ts
+ * import { serve } from '@hono/node-server';
+ *
+ * await apcore.init();
+ * await mountMcp(app, apcore.mcp!, { endpoint: '/mcp', explorer: true });
+ * serve({ fetch: app.fetch, port: 3000 });
+ * ```
+ *
+ * @returns The embedded MCP app; call `close()` on shutdown.
+ */
+export declare function mountMcp(app: MountableApp, service: ApcoreMcpService, options?: MountMcpOptions): Promise<McpApp>;
+//# sourceMappingURL=mount.d.ts.map

package/dist/mcp/mount.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.d.ts","sourceRoot":"","sources":["../../src/mcp/mount.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,kDAAkD;AAClD,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,KAAK,OAAO,CAAC;CACvF;AAWD;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,EAAE,QAElC,CAAC;AAcH;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,CAAC,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,QAAQ,CAAC,CAa/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,YAAY,EACjB,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,MAAM,CAAC,CA8BjB"}

package/dist/mcp/mount.js

@@ -0,0 +1,95 @@
+import { DEFAULT_EXPLORER_PREFIX, DEFAULT_MCP_ENDPOINT, HONO_ALREADY_SENT_HEADER } from '../constants.js';
+/**
+ * The sentinel `@hono/node-server` recognises as "the handler already wrote
+ * this response itself".
+ *
+ * Constructed here rather than imported from
+ * `@hono/node-server/utils/response` so mounting never makes the Node adapter
+ * a hard dependency; the header name is the contract.
+ */
+export const RESPONSE_ALREADY_SENT = new Response(null, {
+    headers: { [HONO_ALREADY_SENT_HEADER]: 'true' },
+});
+const NODE_ONLY_MESSAGE = 'mountMcp() needs the Node bindings from @hono/node-server (c.env.incoming / c.env.outgoing). ' +
+    'On Workers, Deno, or Bun, run the MCP server standalone with ApcoreMcpService.start() instead.';
+function nodeBindings(c) {
+    const env = c?.env;
+    if (env === null || typeof env !== 'object')
+        return null;
+    const { incoming, outgoing } = env;
+    if (!incoming || !outgoing)
+        return null;
+    return { incoming, outgoing };
+}
+/**
+ * Wrap `apcore-mcp`'s Node request handler as a Hono handler.
+ *
+ * The MCP transport speaks Streamable HTTP with SSE, which needs direct
+ * control of the response stream — so the handler writes to the Node
+ * `ServerResponse` and returns the already-sent sentinel instead of a
+ * `Response` Hono would try to serialise itself.
+ */
+export function toHonoHandler(mcpApp) {
+    return async (c) => {
+        const bindings = nodeBindings(c);
+        if (!bindings) {
+            return new Response(NODE_ONLY_MESSAGE, {
+                status: 501,
+                headers: { 'content-type': 'text/plain; charset=utf-8' },
+            });
+        }
+        await mcpApp.handler(bindings.incoming, bindings.outgoing);
+        return RESPONSE_ALREADY_SENT;
+    };
+}
+/**
+ * Mount the MCP endpoint — and, when enabled, the Tool Explorer UI and the
+ * `/health`, `/metrics`, `/usage` routes — into an existing Hono app.
+ *
+ * One process, one port: the app keeps serving its own routes while AI
+ * clients talk MCP at `endpoint`.
+ *
+ * **Node runtime only.** The MCP transport needs the raw Node request and
+ * response objects that `@hono/node-server` exposes on `c.env`. On other
+ * runtimes, run the server standalone with {@link ApcoreMcpService.start}.
+ *
+ * `endpoint` must be the path as the HTTP server sees it — if the Hono app
+ * itself sits under a `basePath`, include that prefix here.
+ *
+ * @example
+ * ```ts
+ * import { serve } from '@hono/node-server';
+ *
+ * await apcore.init();
+ * await mountMcp(app, apcore.mcp!, { endpoint: '/mcp', explorer: true });
+ * serve({ fetch: app.fetch, port: 3000 });
+ * ```
+ *
+ * @returns The embedded MCP app; call `close()` on shutdown.
+ */
+export async function mountMcp(app, service, options = {}) {
+    const endpoint = options.endpoint ?? DEFAULT_MCP_ENDPOINT;
+    const explorerPrefix = options.explorerPrefix ?? DEFAULT_EXPLORER_PREFIX;
+    const builtinRoutes = options.builtinRoutes ?? true;
+    const mcpApp = await service.asyncServe({
+        endpoint,
+        explorer: options.explorer,
+        explorerPrefix,
+        allowExecute: options.allowExecute,
+    });
+    const handler = toHonoHandler(mcpApp);
+    app.all(endpoint, handler);
+    if (options.explorer) {
+        app.all(explorerPrefix, handler);
+        app.all(`${explorerPrefix}/*`, handler);
+    }
+    if (builtinRoutes) {
+        // Served by the MCP transport itself: /health and /metrics before auth,
+        // /usage after it.
+        for (const path of ['/health', '/metrics', '/usage']) {
+            app.all(path, handler);
+        }
+    }
+    return mcpApp;
+}
+//# sourceMappingURL=mount.js.map

package/dist/mcp/mount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount.js","sourceRoot":"","sources":["../../src/mcp/mount.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,iBAAiB,CAAC;AAkB1G;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAa,IAAI,QAAQ,CAAC,IAAI,EAAE;IAChE,OAAO,EAAE,EAAE,CAAC,wBAAwB,CAAC,EAAE,MAAM,EAAE;CAChD,CAAC,CAAC;AAEH,MAAM,iBAAiB,GACrB,+FAA+F;IAC/F,gGAAgG,CAAC;AAEnG,SAAS,YAAY,CAAC,CAAU;IAC9B,MAAM,GAAG,GAAI,CAA8B,EAAE,GAAG,CAAC;IACjD,IAAI,GAAG,KAAK,IAAI,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IACzD,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,GAAG,GAA4B,CAAC;IAC5D,IAAI,CAAC,QAAQ,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,MAAc;IAC1C,OAAO,KAAK,EAAE,CAAU,EAAqB,EAAE;QAC7C,MAAM,QAAQ,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;QACjC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,IAAI,QAAQ,CAAC,iBAAiB,EAAE;gBACrC,MAAM,EAAE,GAAG;gBACX,OAAO,EAAE,EAAE,cAAc,EAAE,2BAA2B,EAAE;aACzD,CAAC,CAAC;QACL,CAAC;QAED,MAAM,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAC,CAAC;QAC3D,OAAO,qBAAqB,CAAC;IAC/B,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,GAAiB,EACjB,OAAyB,EACzB,UAA2B,EAAE;IAE7B,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,oBAAoB,CAAC;IAC1D,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,uBAAuB,CAAC;IACzE,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,IAAI,CAAC;IAEpD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,UAAU,CAAC;QACtC,QAAQ;QACR,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,cAAc;QACd,YAAY,EAAE,OAAO,CAAC,YAAY;KACnC,CAAC,CAAC;IAEH,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAEtC,GAAG,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAE3B,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;QACrB,GAAG,CAAC,GAAG,CAAC,cAAc,EAAE,OAAO,CAAC,CAAC;QACjC,GAAG,CAAC,GAAG,CAAC,GAAG,cAAc,IAAI,EAAE,OAAO,CAAC,CAAC;IAC1C,CAAC;IAED,IAAI,aAAa,EAAE,CAAC;QAClB,wEAAwE;QACxE,mBAAmB;QACnB,KAAK,MAAM,IAAI,IAAI,CAAC,SAAS,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QACzB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/output/index.d.ts

@@ -0,0 +1,3 @@
+export { modulesToBindings, renderBindingsYaml, writeBindingsFile } from './yaml-writer.js';
+export type { BindingRecord } from './yaml-writer.js';
+//# sourceMappingURL=index.d.ts.map

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

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

package/dist/output/index.js

@@ -0,0 +1,2 @@
+export { modulesToBindings, renderBindingsYaml, writeBindingsFile } from './yaml-writer.js';
+//# sourceMappingURL=index.js.map

package/dist/output/index.js.map

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

package/dist/output/yaml-writer.d.ts

@@ -0,0 +1,31 @@
+import type { ScannedModule } from 'apcore-toolkit';
+/** One entry of the `bindings:` list in a bindings YAML file. */
+export interface BindingRecord {
+    module_id: string;
+    target: string;
+    description: string;
+    input_schema?: Record<string, unknown>;
+    output_schema?: Record<string, unknown>;
+    tags?: string[];
+    annotations?: Record<string, unknown>;
+    documentation?: string;
+}
+/**
+ * Serialise scanned modules into the `bindings:` shape that
+ * {@link ApBindingLoader} reads back.
+ *
+ * Keys are snake_case, matching the wire format shared by every apcore SDK.
+ */
+export declare function modulesToBindings(modules: ScannedModule[]): BindingRecord[];
+/** Render scanned modules as the text of a bindings YAML file. */
+export declare function renderBindingsYaml(modules: ScannedModule[]): string;
+/**
+ * Write scanned modules to a single bindings YAML file, creating parent
+ * directories as needed.
+ *
+ * @param modules  - Modules to serialise.
+ * @param filePath - Destination path, e.g. `./bindings.yaml`.
+ * @returns The path that was written.
+ */
+export declare function writeBindingsFile(modules: ScannedModule[], filePath: string): Promise<string>;
+//# sourceMappingURL=yaml-writer.d.ts.map

package/dist/output/yaml-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-writer.d.ts","sourceRoot":"","sources":["../../src/output/yaml-writer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,iEAAiE;AACjE,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE,CAkB3E;AAED,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,CAKnE;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,aAAa,EAAE,EACxB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,CAIjB"}

package/dist/output/yaml-writer.js

@@ -0,0 +1,49 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import * as yaml from 'js-yaml';
+import { annotationsToDict } from 'apcore-toolkit';
+/**
+ * Serialise scanned modules into the `bindings:` shape that
+ * {@link ApBindingLoader} reads back.
+ *
+ * Keys are snake_case, matching the wire format shared by every apcore SDK.
+ */
+export function modulesToBindings(modules) {
+    return modules.map((module) => {
+        const record = {
+            module_id: module.moduleId,
+            target: module.target,
+            description: module.description,
+            input_schema: { ...module.inputSchema },
+            output_schema: { ...module.outputSchema },
+        };
+        if (module.tags.length > 0)
+            record.tags = [...module.tags];
+        if (module.annotations) {
+            record.annotations = annotationsToDict(module.annotations);
+        }
+        if (module.documentation)
+            record.documentation = module.documentation;
+        return record;
+    });
+}
+/** Render scanned modules as the text of a bindings YAML file. */
+export function renderBindingsYaml(modules) {
+    const header = '# Generated by hono-apcore. Load with HonoApcore.loadBindings() or\n' +
+        '# `hono-apcore serve --bindings <file>`.\n';
+    return header + yaml.dump({ bindings: modulesToBindings(modules) }, { noRefs: true, lineWidth: 100 });
+}
+/**
+ * Write scanned modules to a single bindings YAML file, creating parent
+ * directories as needed.
+ *
+ * @param modules  - Modules to serialise.
+ * @param filePath - Destination path, e.g. `./bindings.yaml`.
+ * @returns The path that was written.
+ */
+export async function writeBindingsFile(modules, filePath) {
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, renderBindingsYaml(modules), 'utf-8');
+    return filePath;
+}
+//# sourceMappingURL=yaml-writer.js.map

package/dist/output/yaml-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml-writer.js","sourceRoot":"","sources":["../../src/output/yaml-writer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,KAAK,IAAI,MAAM,SAAS,CAAC;AAChC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAenD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAwB;IACxD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QAC5B,MAAM,MAAM,GAAkB;YAC5B,SAAS,EAAE,MAAM,CAAC,QAAQ;YAC1B,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,YAAY,EAAE,EAAE,GAAG,MAAM,CAAC,WAAW,EAAE;YACvC,aAAa,EAAE,EAAE,GAAG,MAAM,CAAC,YAAY,EAAE;SAC1C,CAAC;QAEF,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,CAAC,IAAI,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QAC3D,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;YACvB,MAAM,CAAC,WAAW,GAAG,iBAAiB,CAAC,MAAM,CAAC,WAAW,CAA4B,CAAC;QACxF,CAAC;QACD,IAAI,MAAM,CAAC,aAAa;YAAE,MAAM,CAAC,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;QAEtE,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,kBAAkB,CAAC,OAAwB;IACzD,MAAM,MAAM,GACV,sEAAsE;QACtE,4CAA4C,CAAC;IAC/C,OAAO,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,iBAAiB,CAAC,OAAO,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC;AACxG,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,OAAwB,EACxB,QAAgB;IAEhB,MAAM,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACpD,MAAM,SAAS,CAAC,QAAQ,EAAE,kBAAkB,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;IAChE,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/scanners/hono-route-scanner.d.ts

@@ -0,0 +1,60 @@
+import { BaseScanner } from 'apcore-toolkit';
+import type { ScannedModule } from 'apcore-toolkit';
+import type { BoundExecuteFn } from '../utils/module-factory.js';
+import type { RouteScanOptions } from '../types.js';
+/**
+ * The slice of Hono's app surface the scanner needs.
+ *
+ * Typed structurally so the scanner works with any `Hono<Env>` instantiation
+ * without dragging Hono's generics through this package's public API.
+ */
+export interface HonoAppLike {
+    routes: Array<{
+        path: string;
+        method: string;
+        handler: unknown;
+    }>;
+    /**
+     * Hono's own `request()` takes two further optional arguments (`Env` and
+     * `ExecutionContext`); they are omitted here so any `Hono<Env>` remains
+     * structurally assignable regardless of its bindings.
+     */
+    request: (input: Request | string | URL, init?: RequestInit) => Response | Promise<Response>;
+}
+/**
+ * Scans a Hono app's route table and turns each route into an apcore module.
+ *
+ * Registered modules replay the route in-process through `app.request()`, so
+ * middleware, validators, and error handlers all run exactly as they do for a
+ * real HTTP request — no duplicated business logic, no second code path.
+ *
+ * Behavioural annotations are inferred from the HTTP method per RFC 9110
+ * safe-method semantics (`GET` → readonly + cacheable, `DELETE` →
+ * destructive, `PUT` → idempotent).
+ */
+export declare class HonoRouteScanner extends BaseScanner {
+    getSourceName(): string;
+    /**
+     * Scan the app's routes into toolkit `ScannedModule` intermediates.
+     *
+     * Use {@link scanWithExecutors} when you also need the bound execute
+     * functions — `scan()` returns serialisable metadata only, which is what
+     * the `scan` CLI command and YAML binding export want.
+     */
+    scan(app: HonoAppLike, options?: RouteScanOptions): ScannedModule[];
+    /**
+     * Scan the app's routes, returning each module together with the execute
+     * function that replays it through `app.request()`.
+     */
+    scanWithExecutors(app: HonoAppLike, options?: RouteScanOptions): Array<{
+        module: ScannedModule;
+        execute: BoundExecuteFn;
+    }>;
+    private buildEntry;
+}
+/**
+ * Substitute path parameters and append the query string, producing the URL
+ * handed to `app.request()`.
+ */
+export declare function buildRequestUrl(path: string, method: string, inputs: Record<string, unknown>, baseUrl: string): string;
+//# sourceMappingURL=hono-route-scanner.d.ts.map

package/dist/scanners/hono-route-scanner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hono-route-scanner.d.ts","sourceRoot":"","sources":["../../src/scanners/hono-route-scanner.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,WAAW,EAKZ,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAIpD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,KAAK,EAAiB,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;IAClE;;;;OAIG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,GAAG,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAC9F;AAgGD;;;;;;;;;;GAUG;AACH,qBAAa,gBAAiB,SAAQ,WAAW;IAC/C,aAAa,IAAI,MAAM;IAIvB;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,GAAE,gBAAqB,GAAG,aAAa,EAAE;IAIvE;;;OAGG;IACH,iBAAiB,CACf,GAAG,EAAE,WAAW,EAChB,OAAO,GAAE,gBAAqB,GAC7B,KAAK,CAAC;QAAE,MAAM,EAAE,aAAa,CAAC;QAAC,OAAO,EAAE,cAAc,CAAA;KAAE,CAAC;IA+D5D,OAAO,CAAC,UAAU;CAkDnB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,MAAM,GACd,MAAM,CAgBR"}