@lerianstudio/matcher-mcp 1.0.0-beta.5

package/dist/server.js

@@ -0,0 +1,245 @@
+#!/usr/bin/env node
+// Entry point for the Matcher MCP server.
+//
+// Task 1.1.2: instantiate an McpServer (name/version from package.json), mount
+// the SDK's Streamable HTTP transport on a Node HTTP server (MCP_PORT, default
+// 4019), register a placeholder `mcp_ping` tool so tools/list has content,
+// expose a plain GET /healthz, read MATCHER_API_URL via the config module, and
+// shut down gracefully on SIGTERM.
+//
+// The transport runs in the SDK's documented stateless mode — a fresh McpServer
+// is built per request via `buildMcpServer` (see transport/http.ts). Real tools
+// (generic invoke trio, curated fee-schedule vertical) register here in later
+// tasks; for now only the placeholder lives in `registerTools`.
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { requireMatcherClient, UnauthenticatedError, } from './auth/request-token.js';
+import { loadConfig } from './config.js';
+import { initTelemetry, instrumentToolCall, shutdownTelemetry, } from './observability/otel.js';
+import { loadSpec } from './spec/load.js';
+import { registerContextTools } from './tools/context/index.js';
+import { registerDashboardTools } from './tools/dashboard/index.js';
+import { registerDisputeTools } from './tools/dispute/index.js';
+import { registerExceptionTools } from './tools/exception/index.js';
+import { registerFeeRuleTools } from './tools/fee-rule/index.js';
+import { registerFeeScheduleTools } from './tools/fee-schedule/index.js';
+import { registerDescribeOperationTool } from './tools/generic/describe-operation.js';
+import { registerInvokeTool } from './tools/generic/invoke.js';
+import { registerListOperationsTool } from './tools/generic/list-operations.js';
+import { registerIngestionTools } from './tools/ingestion/index.js';
+import { registerMatchRuleTools } from './tools/match-rule/index.js';
+import { registerMatchingTools } from './tools/matching/index.js';
+import { registerReportTools } from './tools/report/index.js';
+import { registerSourceTools } from './tools/source/index.js';
+import { start } from './transport/http.js';
+/** The static reply the placeholder tool returns. */
+export const PING_REPLY = 'pong';
+/**
+ * Read `name` and `version` from package.json. Resolved relative to this module
+ * so it works both in dev (src/server.ts → ../package.json) and in the built
+ * artifact (dist/server.js → ../package.json), since both sit one level below
+ * the project root.
+ */
+export function readServerInfo() {
+    const pkgPath = fileURLToPath(new URL('../package.json', import.meta.url));
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+    if (!pkg.name || !pkg.version) {
+        throw new Error('package.json is missing name or version');
+    }
+    return { name: pkg.name, version: pkg.version };
+}
+/** Tool reply confirming a caller credential was relayed (never its value). */
+export const WHOAMI_AUTHENTICATED = 'matcher credential present (relayed)';
+/**
+ * The boot operation index, loaded once and memoized. `buildMcpServer` runs per
+ * inbound request (stateless transport), but the embedded spec is immutable boot
+ * data, so we parse + index it exactly once and share the read-only result.
+ * Loading is lazy so importing this module never reads the filesystem (keeps
+ * config/lifecycle tests side-effect free); a missing/unparseable spec still
+ * fails loudly the first time a server is built.
+ */
+let operationIndexCache;
+function getOperationIndex() {
+    if (operationIndexCache === undefined) {
+        operationIndexCache = loadSpec().index;
+    }
+    return operationIndexCache;
+}
+/**
+ * Register all tools on an McpServer. The placeholders `mcp_ping` (proves
+ * transport wiring) and `mcp_whoami` (proves the request-scoped token relay),
+ * plus the generic discovery pair `matcher_list_operations` /
+ * `matcher_describe_operation` over the embedded operation index. Extended by
+ * the rest of the real tool surface in tasks 1.2.3 / 1.3.x.
+ */
+function registerTools(server) {
+    server.registerTool('mcp_ping', {
+        description: 'Placeholder liveness tool. Returns a static string to prove the ' +
+            'MCP transport is wired. Replaced by real tools in later tasks.',
+    }, () => ({
+        content: [{ type: 'text', text: PING_REPLY }],
+    }));
+    // Reports ONLY whether a usable bearer credential reached the handler —
+    // never the token itself. It exercises the relay's fail-closed guard via
+    // requireMatcherClient: an UnauthenticatedError means no credential was
+    // relayed. Any other outcome (a client, or — until task 1.3.1 — the client
+    // factory's "not implemented" throw) means the credential WAS present, since
+    // execution got past the fail-closed guard. We therefore treat only
+    // UnauthenticatedError as "absent" and never inspect the token value.
+    server.registerTool('mcp_whoami', {
+        description: 'Reports whether the caller relayed a matcher bearer credential. ' +
+            'Returns presence only — never the token value. Use it to confirm ' +
+            'your MCP client is sending an `Authorization: Bearer <jwt>` header.',
+    }, (extra) => {
+        try {
+            requireMatcherClient(extra);
+        }
+        catch (err) {
+            if (err instanceof UnauthenticatedError) {
+                // Fail-closed: surface the operator remediation text as a tool error.
+                // The message contains no token material.
+                return { isError: true, content: [{ type: 'text', text: err.message }] };
+            }
+            // Got past the credential guard (e.g. client factory not yet
+            // implemented) — the credential was present.
+        }
+        return { content: [{ type: 'text', text: WHOAMI_AUTHENTICATED }] };
+    });
+    // Generic discovery surface (task 1.2.2): pure reads over the boot operation
+    // index. No matcher call, no token — they describe the contract, not data.
+    const index = getOperationIndex();
+    registerListOperationsTool(server, index);
+    registerDescribeOperationTool(server, index);
+    // Generic invoke (task 1.2.3): assembles + validates + dispatches any of the
+    // 167 operations with the caller's relayed token (fail-closed). Shares the
+    // RFC 9457 → tool-error mapping (toToolError) with the curated surface.
+    registerInvokeTool(server, index);
+    // Curated fee-schedule vertical (task 1.3.2): six typed tools (create/list/
+    // get/update/delete/simulate). They share the fail-closed relay and the
+    // toToolError mapping with the generic invoke, so both surfaces map matcher
+    // errors identically.
+    registerFeeScheduleTools(server);
+    // Phase 2 curated verticals (task 2.2.4): the remaining five families, each
+    // built in parallel and registered here to avoid concurrent server.ts edits.
+    // Every family shares the same fail-closed relay + toToolError mapping as the
+    // fee-schedule vertical and the generic invoke. None carries a tenant field.
+    //   fee_rule_*   (5): create/list/get/update/delete — hybrid path
+    //   match_rule_* (6): create/list/get/update/delete/reorder — context-nested
+    //   context_*    (5): create/list/get/update/delete
+    //   source_*     (5): create/list/get/update/delete — context-nested
+    //   match_run_*  (4): start/list/get/groups — verbs over /v1/matching
+    registerFeeRuleTools(server);
+    registerMatchRuleTools(server);
+    registerContextTools(server);
+    registerSourceTools(server);
+    registerMatchingTools(server);
+    // Phase 4.2 curated verticals: the remaining five families, each built in
+    // parallel and registered here to avoid concurrent server.ts edits. Every
+    // family shares the same fail-closed relay + toToolError mapping as the
+    // fee-schedule vertical and the generic invoke. None carries a tenant field.
+    //   exception_* (13): list/get, history, comments (list/add/delete), action
+    //                     verbs (dispatch/open-dispute/force-match/adjust-entry),
+    //                     and bulk actions (assign/resolve/dispatch)
+    //   dispute_*    (4): list/get/close/submit-evidence
+    //   ingestion_*  (6): jobs-list/job-get/job-errors-list/job-transactions-list/
+    //                     transactions-search/transaction-ignore — context-nested
+    //   dashboard_*  (7): aggregates + cash-impact/match-rate/metrics/sla/
+    //                     source-breakdown/volume — context-nested reads
+    //   report_*    (13): matched/unmatched/variance/summary, four counts, and
+    //                     five base64 exports — context-nested reads
+    registerExceptionTools(server);
+    registerDisputeTools(server);
+    registerIngestionTools(server);
+    registerDashboardTools(server);
+    registerReportTools(server);
+}
+/**
+ * Wrap `server.registerTool` so EVERY tool — curated, generic, and the
+ * placeholders — has its handler routed through `instrumentToolCall(name, fn)`
+ * exactly once, without touching any family tool dir or introducing a single
+ * dispatch chokepoint that doesn't exist. There is no central dispatch in the
+ * SDK (each tool registers its own callback), so the registration boundary IS
+ * the one place that sees every tool exactly once.
+ *
+ * The wrapper preserves the original `registerTool` signature (name + config +
+ * callback). It only swaps the callback for one that opens the tool span/metrics
+ * around the real callback and forwards the same arguments verbatim. The span
+ * records ONLY the tool name + outcome (+ matcher status on failure) — never the
+ * caller's args, headers, or token (enforced inside `instrumentToolCall`).
+ *
+ * Idempotent per server: applied once before `registerTools`, so each tool is
+ * wrapped a single time (no double-counting).
+ */
+function instrumentRegistrations(server) {
+    const original = server.registerTool.bind(server);
+    const wrapped = (name, config, cb) => {
+        // `cb`'s arity varies (`(args, extra)` vs `(extra)`) across the SDK's tool
+        // callback overloads; forward whatever it was given verbatim. The result is
+        // `CallToolResult | Promise<CallToolResult>` — normalize to a promise for
+        // the instrumentation wrapper, which re-throws on error so the SDK still
+        // sees the original failure.
+        const instrumented = ((...callArgs) => instrumentToolCall(name, () => Promise.resolve(cb(...callArgs))));
+        return original(name, config, instrumented);
+    };
+    server.registerTool = wrapped;
+}
+/**
+ * Build a fresh McpServer with all tools registered. Called per request by the
+ * stateless transport (transport/http.ts), so it must be cheap and side-effect
+ * free beyond constructing the server.
+ *
+ * Tool registration is instrumented at the registration boundary first, so the
+ * subsequent `registerTools` call wraps every curated + generic tool's handler
+ * in a span/metrics scope (token-free) without any family dir change.
+ */
+export function buildMcpServer(info) {
+    const server = new McpServer({ name: info.name, version: info.version });
+    instrumentRegistrations(server);
+    registerTools(server);
+    return server;
+}
+/**
+ * Boot the server: load config, read identity, start the HTTP transport, and
+ * wire SIGTERM/SIGINT to a graceful shutdown. Resolves to the running handle so
+ * callers (and tests) can close it deterministically.
+ */
+export async function main(config = loadConfig()) {
+    const info = readServerInfo();
+    // Start telemetry before serving so the first request is already instrumented.
+    // A COMPLETE no-op when ENABLE_TELEMETRY is false (no SDK, no exporters, no
+    // network), so dev/test and single-operator runs pay nothing.
+    initTelemetry(config, { version: info.version });
+    const running = await start(config, info);
+    const shutdown = (signal) => {
+        console.error(`matcher-mcp received ${signal}, shutting down`);
+        running
+            .close()
+            // Flush + stop telemetry as part of the graceful close so buffered
+            // traces/metrics are exported before exit. A no-op when telemetry was
+            // never started.
+            .then(() => shutdownTelemetry())
+            .then(() => {
+            process.exitCode = 0;
+        })
+            .catch((err) => {
+            console.error('matcher-mcp shutdown failed:', err);
+            process.exitCode = 1;
+        });
+    };
+    process.once('SIGTERM', () => shutdown('SIGTERM'));
+    process.once('SIGINT', () => shutdown('SIGINT'));
+    console.error(`matcher-mcp ${info.version} listening on :${config.port} ` +
+        `(matcher API ${config.matcherApiUrl})`);
+    return running;
+}
+// Run only when invoked directly (not when imported by a test).
+// import.meta.url vs the resolved argv[1] is the standard ESM "main module" check.
+if (process.argv[1] &&
+    import.meta.url === new URL(`file://${process.argv[1]}`).href) {
+    main().catch((err) => {
+        console.error('matcher-mcp failed to start:', err);
+        process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/dist/spec/curated-operations.js

@@ -0,0 +1,145 @@
+// Canonical record of which matcher OpenAPI operations the CURATED tool surface
+// covers — the registry the drift guard checks against.
+//
+// WHY THIS EXISTS
+// The server exposes two surfaces over the 167-operation matcher spec:
+//   1. The GENERIC trio (matcher_list_operations / describe / invoke) reads the
+//      spec at runtime, so it tracks the spec automatically. `load.test.ts`
+//      already pins `index.operations.size === 167` as that side's canary.
+//   2. The CURATED tools (the ~72 hand-written Zod tools under `src/tools/*/`)
+//      hard-code their own method+path. NOTHING in those tools consults the
+//      spec, and their unit tests assert against the same hard-coded literal —
+//      tautological w.r.t. the spec. So if matcher renames or removes an
+//      operation, a curated tool silently keeps sending the stale contract.
+//
+// This file closes that gap: it is the single, hand-curated list of which
+// operationIds each curated tool covers, plus the operationIds we deliberately
+// leave to generic-invoke only. `curated-operations.test.ts` keeps it honest
+// against the real spec — STRUCTURAL drift (a covered op no longer exists) and
+// COVERAGE drift (a new op nobody triaged) both fail that test. It does NOT
+// attempt deep Zod-vs-JSONSchema field equivalence — that is out of scope and a
+// false-positive factory; this is a cheap "layer 1" tripwire.
+//
+// HOW IT WAS DERIVED (and how to keep it correct)
+// Each entry was reconciled from the curated tool's dispatched `{ method, path }`
+// (see each `src/tools/<family>/*.ts` and its `shared.ts` path helper) against
+// the spec's method+path → operationId map. It is NOT copied from any external
+// list. When a curated tool is added/removed/retargeted, update the matching
+// array below and re-run `curated-operations.test.ts`.
+/**
+ * Every operationId covered by a curated Zod tool, grouped by tool family.
+ * Order within a family follows the tool files; the test treats this as a set.
+ */
+export const CURATED_OPERATION_IDS = [
+    // fee-schedule (src/tools/fee-schedule/) — 6
+    'createFeeSchedule', // fee_schedule_create   — POST   /v1/fee-schedules
+    'deleteFeeSchedule', // fee_schedule_delete   — DELETE /v1/fee-schedules/{scheduleId}
+    'getFeeSchedule', // fee_schedule_get      — GET    /v1/fee-schedules/{scheduleId}
+    'listFeeSchedules', // fee_schedule_list     — GET    /v1/fee-schedules
+    'simulateFeeSchedule', // fee_schedule_simulate — POST   /v1/fee-schedules/{scheduleId}/simulate
+    'updateFeeSchedule', // fee_schedule_update   — PATCH  /v1/fee-schedules/{scheduleId}
+    // fee-rule (src/tools/fee-rule/) — 5
+    'createFeeRule', // fee_rule_create — POST   /v1/contexts/{contextId}/fee-rules
+    'deleteFeeRule', // fee_rule_delete — DELETE /v1/fee-rules/{feeRuleId}
+    'getFeeRule', // fee_rule_get    — GET    /v1/fee-rules/{feeRuleId}
+    'listFeeRules', // fee_rule_list   — GET    /v1/contexts/{contextId}/fee-rules
+    'updateFeeRule', // fee_rule_update — PATCH  /v1/fee-rules/{feeRuleId}
+    // match-rule (src/tools/match-rule/) — 6
+    'createMatchRule', // match_rule_create  — POST   /v1/contexts/{contextId}/rules
+    'deleteMatchRule', // match_rule_delete  — DELETE /v1/contexts/{contextId}/rules/{ruleId}
+    'getMatchRule', // match_rule_get     — GET    /v1/contexts/{contextId}/rules/{ruleId}
+    'listMatchRules', // match_rule_list    — GET    /v1/contexts/{contextId}/rules
+    'reorderMatchRules', // match_rule_reorder — POST   /v1/contexts/{contextId}/rules/reorder
+    'updateMatchRule', // match_rule_update  — PATCH  /v1/contexts/{contextId}/rules/{ruleId}
+    // context (src/tools/context/) — 4 (delete removed: hard-delete → archive/restore lifecycle)
+    'createContext', // context_create — POST   /v1/contexts
+    'getContext', // context_get    — GET    /v1/contexts/{contextId}
+    'listContexts', // context_list   — GET    /v1/contexts
+    'updateContext', // context_update — PATCH  /v1/contexts/{contextId}
+    // source (src/tools/source/) — 4 (delete removed: hard-delete → archive/restore lifecycle)
+    'createSource', // source_create — POST   /v1/contexts/{contextId}/sources
+    'getSource', // source_get    — GET    /v1/contexts/{contextId}/sources/{sourceId}
+    'listSources', // source_list   — GET    /v1/contexts/{contextId}/sources
+    'updateSource', // source_update — PATCH  /v1/contexts/{contextId}/sources/{sourceId}
+    // matching (src/tools/matching/) — 4
+    'getMatchRun', // match_run_get    — GET  /v1/matching/runs/{runId}
+    'getMatchRunGroups', // match_run_groups — GET  /v1/matching/runs/{runId}/groups
+    'listMatchRuns', // match_run_list   — GET  /v1/matching/contexts/{contextId}/runs
+    'runMatch', // match_run_start  — POST /v1/matching/contexts/{contextId}/run
+    // exception (src/tools/exception/) — 13
+    'addComment', // exception_add_comment    — POST   /v1/exceptions/{exceptionId}/comments
+    'adjustEntryException', // exception_adjust_entry   — POST   /v1/exceptions/{exceptionId}/adjust-entry
+    'bulkAssignExceptions', // exception_bulk_assign    — POST   /v1/exceptions/bulk/assign
+    'bulkDispatchExceptions', // exception_bulk_dispatch  — POST   /v1/exceptions/bulk/dispatch
+    'bulkResolveExceptions', // exception_bulk_resolve   — POST   /v1/exceptions/bulk/resolve
+    'deleteComment', // exception_delete_comment — DELETE /v1/exceptions/{exceptionId}/comments/{commentId}
+    'dispatchException', // exception_dispatch       — POST   /v1/exceptions/{exceptionId}/dispatch
+    'forceMatchException', // exception_force_match    — POST   /v1/exceptions/{exceptionId}/force-match
+    'getException', // exception_get            — GET    /v1/exceptions/{exceptionId}
+    'getExceptionHistory', // exception_history        — GET    /v1/exceptions/{exceptionId}/history
+    'listComments', // exception_list_comments  — GET    /v1/exceptions/{exceptionId}/comments
+    'listExceptions', // exception_list           — GET    /v1/exceptions
+    'openDispute', // exception_open_dispute   — POST   /v1/exceptions/{exceptionId}/disputes
+    // dispute (src/tools/dispute/) — 4
+    'closeDispute', // dispute_close           — POST /v1/disputes/{disputeId}/close
+    'getDispute', // dispute_get             — GET  /v1/disputes/{disputeId}
+    'listDisputes', // dispute_list            — GET  /v1/disputes
+    'submitEvidence', // dispute_submit_evidence — POST /v1/disputes/{disputeId}/evidence
+    // ingestion (src/tools/ingestion/) — 6
+    'listIngestionJobErrors', // ingestion_job_errors_list        — GET  /v1/imports/contexts/{contextId}/jobs/{jobId}/errors
+    'getIngestionJob', // ingestion_job_get                — GET  /v1/imports/contexts/{contextId}/jobs/{jobId}
+    'listJobTransactions', // ingestion_job_transactions_list  — GET  /v1/imports/contexts/{contextId}/jobs/{jobId}/transactions
+    'listIngestionJobs', // ingestion_jobs_list              — GET  /v1/imports/contexts/{contextId}/jobs
+    'ignoreTransaction', // ingestion_transaction_ignore     — POST /v1/imports/contexts/{contextId}/transactions/{transactionId}/ignore
+    'searchTransactions', // ingestion_transactions_search    — GET  /v1/imports/contexts/{contextId}/transactions/search
+    // dashboard (src/tools/dashboard/) — 7
+    'getDashboardAggregates', // dashboard_aggregates       — GET /v1/reports/contexts/{contextId}/dashboard
+    'getCashImpactSummary', // dashboard_cash_impact      — GET /v1/reports/contexts/{contextId}/dashboard/cash-impact
+    'getMatchRateStats', // dashboard_match_rate       — GET /v1/reports/contexts/{contextId}/dashboard/match-rate
+    'getMatcherDashboardMetrics', // dashboard_metrics          — GET /v1/reports/contexts/{contextId}/dashboard/metrics
+    'getSLAStats', // dashboard_sla              — GET /v1/reports/contexts/{contextId}/dashboard/sla
+    'getSourceBreakdown', // dashboard_source_breakdown — GET /v1/reports/contexts/{contextId}/dashboard/source-breakdown
+    'getVolumeStats', // dashboard_volume           — GET /v1/reports/contexts/{contextId}/dashboard/volume
+    // report (src/tools/report/) — 13
+    'countExceptions', // report_count_exceptions   — GET /v1/reports/contexts/{contextId}/exceptions/count
+    'countMatched', // report_count_matched      — GET /v1/reports/contexts/{contextId}/matches/count
+    'countTransactions', // report_count_transactions — GET /v1/reports/contexts/{contextId}/transactions/count
+    'countUnmatched', // report_count_unmatched    — GET /v1/reports/contexts/{contextId}/unmatched/count
+    'exportExceptionsReport', // report_export_exceptions  — GET /v1/reports/contexts/{contextId}/exceptions/export
+    'exportMatchedReport', // report_export_matched     — GET /v1/reports/contexts/{contextId}/matched/export
+    'exportSummaryReport', // report_export_summary     — GET /v1/reports/contexts/{contextId}/summary/export
+    'exportUnmatchedReport', // report_export_unmatched   — GET /v1/reports/contexts/{contextId}/unmatched/export
+    'exportVarianceReport', // report_export_variance    — GET /v1/reports/contexts/{contextId}/variance/export
+    'getMatchedReport', // report_matched            — GET /v1/reports/contexts/{contextId}/matched
+    'getSummaryReport', // report_summary            — GET /v1/reports/contexts/{contextId}/summary
+    'getUnmatchedReport', // report_unmatched          — GET /v1/reports/contexts/{contextId}/unmatched
+    'getVarianceReport', // report_variance           — GET /v1/reports/contexts/{contextId}/variance
+];
+/**
+ * Operations DELIBERATELY left to generic-invoke only — a JSON-shaped curated
+ * tool can't (or shouldn't) express them. Each carries the reason inline. The
+ * drift guard asserts these exist in the spec (so a rename here also fails) and
+ * counts them against total coverage. To curate one later, move it into
+ * `CURATED_OPERATION_IDS` and adjust the frozen counts in the test.
+ */
+export const GENERIC_ONLY_OPERATION_IDS = [
+    // POST /v1/imports/contexts/{contextId}/sources/{sourceId}/upload —
+    // multipart/form-data binary file upload; a JSON tool can't carry the body.
+    'uploadFile',
+    // POST /v1/imports/contexts/{contextId}/sources/{sourceId}/extract-document —
+    // multipart/form-data binary document upload; same as uploadFile.
+    'extractDocument',
+    // POST /v1/exceptions/{exceptionId}/callback — inbound webhook receiver for
+    // external dispatch systems, not an operator-initiated action.
+    'processCallback',
+    // callback-credential (generic-only) — HMAC machine-auth credential lifecycle;
+    // straightforward JSON CRUD nobody has hand-curated a Zod tool for yet.
+    'mintCallbackCredential', // POST   /v1/exceptions/callbacks/credentials
+    'listCallbackCredentials', // GET    /v1/exceptions/callbacks/credentials
+    'rotateCallbackCredential', // POST   /v1/exceptions/callbacks/credentials/{credentialId}/rotate
+    'revokeCallbackCredential', // DELETE /v1/exceptions/callbacks/credentials/{credentialId}
+    // discovery webhook (generic-only) — inbound aggregator webhook receiver, not
+    // an operator-initiated action (cf. processCallback above).
+    'receiveAggregatorWebhook', // POST /v1/discovery/webhooks/{provider}/{webhookToken}
+];
+//# sourceMappingURL=curated-operations.js.map

package/dist/spec/curated-operations.js.map

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

package/dist/spec/index.js

@@ -0,0 +1,155 @@
+// Operation index over the embedded matcher OpenAPI spec.
+//
+// `buildOperationIndex` walks the parsed spec's `paths` × HTTP methods into a
+// flat, in-memory map keyed by `operationId`. Each entry carries everything the
+// generic-invoke trio (task 1.2.2 / 1.2.3) needs to list, describe, and dispatch
+// an operation: method, path, tag, summary, path/query params, and a lightly
+// dereferenced request-body JSON Schema.
+//
+// "Lightly dereferenced" means: request-body `$ref`s are resolved against the
+// spec's `components.schemas` recursively (so nested `$ref`s like a list item's
+// schema are inlined too), enough that `matcher_describe_operation` can hand the
+// model a self-contained JSON Schema. It is NOT a full RFC-compliant resolver —
+// no external documents, and a `$ref` cycle is broken with a placeholder rather
+// than recursing forever.
+/** The HTTP methods we index (lowercased OpenAPI path-item keys). */
+export const HTTP_METHODS = [
+    'get',
+    'put',
+    'post',
+    'delete',
+    'patch',
+];
+const REF_PREFIX = '#/components/schemas/';
+/**
+ * Recursively inline `$ref`s pointing at `#/components/schemas/*` against the
+ * provided schema map. External refs (any `$ref` not under that prefix) and
+ * unresolvable names are left as-is so the caller can still see the dangling
+ * pointer. A `$ref` cycle is broken by tracking the chain of schema names
+ * currently being resolved and replacing a repeat with a `$ref`-only stub.
+ */
+function deref(node, schemas, seen) {
+    if (Array.isArray(node)) {
+        return node.map((item) => deref(item, schemas, seen));
+    }
+    if (node === null || typeof node !== 'object') {
+        return node;
+    }
+    const obj = node;
+    const ref = obj['$ref'];
+    if (typeof ref === 'string' && ref.startsWith(REF_PREFIX)) {
+        const name = ref.slice(REF_PREFIX.length);
+        // Cycle guard: if we're already resolving this schema, stop and keep the ref.
+        if (seen.has(name)) {
+            return { $ref: ref };
+        }
+        const target = schemas[name];
+        if (target === undefined) {
+            // Dangling ref — leave it visible rather than silently dropping it.
+            return { $ref: ref };
+        }
+        const nextSeen = new Set(seen);
+        nextSeen.add(name);
+        return deref(target, schemas, nextSeen);
+    }
+    const out = {};
+    for (const [key, value] of Object.entries(obj)) {
+        out[key] = deref(value, schemas, seen);
+    }
+    return out;
+}
+/** Coerce the spec's `parameters` array into typed param objects. */
+function parseParameters(raw) {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.filter((p) => p !== null && typeof p === 'object');
+}
+/** Pull the dereferenced `application/json` request-body schema, if present. */
+function extractRequestBodySchema(op, schemas) {
+    const json = op.requestBody?.content?.['application/json'];
+    const schema = json?.schema;
+    if (schema === null || typeof schema !== 'object') {
+        return undefined;
+    }
+    const resolved = deref(schema, schemas, new Set());
+    if (resolved === null || typeof resolved !== 'object') {
+        return undefined;
+    }
+    return resolved;
+}
+/** Stable synthetic id for an operation missing one: `METHOD path`. */
+function synthesizeOperationId(method, path) {
+    return `${method.toUpperCase()} ${path}`;
+}
+/**
+ * Build the operation index from a parsed spec. Pure and deterministic: a given
+ * spec always yields the same map and the same warnings (insertion order follows
+ * the spec's path/method declaration order).
+ */
+export function buildOperationIndex(spec) {
+    const operations = new Map();
+    const warnings = [];
+    const schemas = spec.components?.schemas ?? {};
+    const paths = spec.paths ?? {};
+    for (const [path, pathItem] of Object.entries(paths)) {
+        if (pathItem === null || pathItem === undefined) {
+            continue;
+        }
+        for (const method of HTTP_METHODS) {
+            const rawOp = pathItem[method];
+            if (rawOp === null || typeof rawOp !== 'object') {
+                continue;
+            }
+            const op = rawOp;
+            let operationId = typeof op.operationId === 'string' && op.operationId.length > 0
+                ? op.operationId
+                : undefined;
+            if (operationId === undefined) {
+                operationId = synthesizeOperationId(method, path);
+                warnings.push(`operation ${method.toUpperCase()} ${path} has no operationId; ` +
+                    `synthesized "${operationId}"`);
+            }
+            const params = parseParameters(op.parameters);
+            const pathParams = [];
+            const queryParams = {};
+            for (const p of params) {
+                const name = typeof p.name === 'string' ? p.name : undefined;
+                if (name === undefined) {
+                    continue;
+                }
+                if (p.in === 'path') {
+                    pathParams.push(name);
+                }
+                else if (p.in === 'query') {
+                    const type = typeof p.schema?.type === 'string' ? p.schema.type : 'string';
+                    queryParams[name] = { required: p.required === true, type };
+                }
+            }
+            const tags = op.tags;
+            const tag = Array.isArray(tags) && typeof tags[0] === 'string'
+                ? tags[0]
+                : 'Untagged';
+            const summary = typeof op.summary === 'string' ? op.summary : '';
+            const requestBodySchema = extractRequestBodySchema(op, schemas);
+            const indexed = {
+                operationId,
+                method: method.toUpperCase(),
+                path,
+                tag,
+                summary,
+                pathParams,
+                queryParams,
+                ...(requestBodySchema !== undefined ? { requestBodySchema } : {}),
+            };
+            if (operations.has(operationId)) {
+                warnings.push(`duplicate operationId "${operationId}" ` +
+                    `(${method.toUpperCase()} ${path}); keeping the first occurrence`);
+                continue;
+            }
+            operations.set(operationId, indexed);
+        }
+    }
+    return { operations, warnings };
+}
+//# sourceMappingURL=index.js.map

package/dist/spec/index.js.map

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