asynthetic 0.1.0-beta

package/dist/index.js

@@ -0,0 +1,160 @@
+#!/usr/bin/env node
+/**
+ * Asynthetic — MCP server entry point with dual transport.
+ *
+ * Transport is chosen by environment:
+ * - PORT set (Railway/cloud): Express HTTP server exposing the modern
+ *   Streamable HTTP endpoint (POST/GET/DELETE /mcp) plus the legacy
+ *   HTTP+SSE endpoints (GET /sse + POST /messages) for older clients.
+ * - No PORT: stdio, so local use in Claude Code / Cursor / MCP Inspector
+ *   is completely unaffected.
+ *
+ * In stdio mode stdout is the protocol channel — all logging goes to stderr.
+ */
+import { randomUUID } from 'node:crypto';
+import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import express from 'express';
+import { buildServer, SERVER_NAME, SERVER_VERSION } from './server.js';
+import { createStore } from './store/create-store.js';
+// Load .env when present (dev convenience, no dotenv dependency).
+try {
+    process.loadEnvFile();
+}
+catch {
+    // no .env file — fine, env vars may come from the MCP client config
+}
+const store = createStore();
+async function startStdio() {
+    await buildServer(store).connect(new StdioServerTransport());
+    console.error('[asynthetic] Ready on stdio');
+}
+async function startHttp(port) {
+    const app = express();
+    app.use(express.json());
+    // --- Modern Streamable HTTP transport (one session per client) ---
+    const streamableTransports = {};
+    app.post('/mcp', async (req, res) => {
+        try {
+            const sessionId = req.headers['mcp-session-id'];
+            const existing = sessionId ? streamableTransports[sessionId] : undefined;
+            if (existing) {
+                await existing.handleRequest(req, res, req.body);
+                return;
+            }
+            if (sessionId || !isInitializeRequest(req.body)) {
+                res.status(400).json({
+                    jsonrpc: '2.0',
+                    error: { code: -32000, message: 'Bad Request: no valid session. Send an initialize request first.' },
+                    id: null,
+                });
+                return;
+            }
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (sid) => {
+                    streamableTransports[sid] = transport;
+                },
+            });
+            transport.onclose = () => {
+                const sid = transport.sessionId;
+                if (sid)
+                    delete streamableTransports[sid];
+            };
+            await buildServer(store).connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (err) {
+            console.error('[asynthetic] /mcp error:', err);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: '2.0',
+                    error: { code: -32603, message: 'Internal server error' },
+                    id: null,
+                });
+            }
+        }
+    });
+    // GET /mcp = server->client notification stream; DELETE /mcp = session end.
+    const handleSessionRequest = async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        const transport = sessionId ? streamableTransports[sessionId] : undefined;
+        if (!transport) {
+            res.status(400).send('Invalid or missing Mcp-Session-Id');
+            return;
+        }
+        await transport.handleRequest(req, res);
+    };
+    app.get('/mcp', handleSessionRequest);
+    app.delete('/mcp', handleSessionRequest);
+    // --- Legacy HTTP+SSE transport (protocol 2024-11-05) for older clients ---
+    const sseTransports = {};
+    app.get('/sse', async (_req, res) => {
+        try {
+            const transport = new SSEServerTransport('/messages', res);
+            sseTransports[transport.sessionId] = transport;
+            res.on('close', () => {
+                delete sseTransports[transport.sessionId];
+            });
+            await buildServer(store).connect(transport);
+        }
+        catch (err) {
+            console.error('[asynthetic] /sse error:', err);
+            if (!res.headersSent)
+                res.status(500).send('Internal server error');
+        }
+    });
+    app.post('/messages', async (req, res) => {
+        const sessionId = req.query.sessionId;
+        const transport = sessionId ? sseTransports[sessionId] : undefined;
+        if (!transport) {
+            res.status(400).send('No transport found for sessionId');
+            return;
+        }
+        try {
+            await transport.handlePostMessage(req, res, req.body);
+        }
+        catch (err) {
+            console.error('[asynthetic] /messages error:', err);
+            if (!res.headersSent)
+                res.status(500).send('Internal server error');
+        }
+    });
+    // Health/info endpoint for platform checks and humans.
+    app.get('/', (_req, res) => {
+        res.json({
+            name: SERVER_NAME,
+            version: SERVER_VERSION,
+            store: store.describe(),
+            transports: { streamable_http: '/mcp', sse_legacy: '/sse' },
+        });
+    });
+    const httpServer = app.listen(port, () => {
+        console.error(`[asynthetic] Ready on HTTP :${port} (Streamable HTTP at /mcp, legacy SSE at /sse)`);
+    });
+    // Railway sends SIGTERM on redeploy/scale-down — close cleanly.
+    const shutdown = () => {
+        console.error('[asynthetic] Shutting down');
+        httpServer.close(() => process.exit(0));
+        setTimeout(() => process.exit(0), 5000).unref();
+    };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+}
+async function main() {
+    console.error(`[asynthetic] Starting (store: ${store.describe()})`);
+    const port = process.env.PORT ? Number.parseInt(process.env.PORT, 10) : Number.NaN;
+    if (Number.isFinite(port)) {
+        await startHttp(port);
+    }
+    else {
+        await startStdio();
+    }
+}
+main().catch((err) => {
+    console.error('[asynthetic] Fatal:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/server.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Asynthetic — MCP server factory.
+ *
+ * builds a fully-registered McpServer instance. A factory (rather than a
+ * module-level singleton) because HTTP mode serves many concurrent sessions
+ * and a Protocol instance binds to exactly one transport; stdio mode simply
+ * builds one.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type MigrationStore } from './store/store.js';
+export declare const SERVER_NAME = "asynthetic";
+export declare const SERVER_VERSION = "0.1.0-beta";
+export declare function buildServer(store: MigrationStore): McpServer;

package/dist/server.js

@@ -0,0 +1,166 @@
+/**
+ * Asynthetic — MCP server factory.
+ *
+ * builds a fully-registered McpServer instance. A factory (rather than a
+ * module-level singleton) because HTTP mode serves many concurrent sessions
+ * and a Protocol instance binds to exactly one transport; stdio mode simply
+ * builds one.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { interpretDescriptor, majorOf, normalizeVersion, resolveMigration, resolvedViaOf, toSummary, } from './store/store.js';
+export const SERVER_NAME = 'asynthetic';
+export const SERVER_VERSION = '0.1.0-beta';
+const NOT_FOUND_GUIDANCE = 'No verified migration map exists for this request. Do NOT fabricate migration steps from model memory — ' +
+    'consult the official changelog / release notes for this package instead.';
+function jsonResult(payload, isError = false) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+function storeError(err) {
+    console.error('[asynthetic] Store error:', err);
+    return jsonResult({ error: `Store lookup failed: ${err instanceof Error ? err.message : String(err)}` }, true);
+}
+const packageArg = z.string().min(1).describe('Package name as published, e.g. "@modelcontextprotocol/sdk"');
+const ecosystemArg = z.string().default('npm').describe('Package ecosystem (default "npm")');
+export function buildServer(store) {
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
+    server.registerTool('get_migration', {
+        title: 'Get migration map',
+        description: 'Returns the verified migration map for upgrading a package between two versions: ordered breaking ' +
+            'changes with before/after code, deprecations, source-citation URLs, and a last_verified date. ' +
+            'Accepts concrete versions or SemVer ranges (e.g. "^14.2.0", "~14.1.0", "15.x"); non-exact lookups ' +
+            'resolve to the covering map and disclose how via match_type/resolved_via/match_note. ' +
+            'If found=false, no verified data exists — do not guess.',
+        inputSchema: {
+            package: packageArg,
+            from_version: z
+                .string()
+                .min(1)
+                .describe('Version or SemVer range currently in use, e.g. "1.29.0", "^14.2.0", "1.x"'),
+            to_version: z
+                .string()
+                .min(1)
+                .describe('Version or SemVer range upgrading to, e.g. "2.0.0", "^15.0.0", "2.x"'),
+            ecosystem: ecosystemArg,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ package: pkg, from_version, to_version, ecosystem }) => {
+        const requested = { package: pkg, ecosystem, from_version, to_version };
+        try {
+            const maps = await store.getMapsForPackage(ecosystem, pkg);
+            const resolved = resolveMigration(maps, from_version, to_version);
+            if (!resolved) {
+                const available = maps.length > 0 ? maps.map(toSummary) : await store.listMaps();
+                return jsonResult({
+                    found: false,
+                    requested,
+                    message: NOT_FOUND_GUIDANCE,
+                    available_maps: available,
+                });
+            }
+            const { map, match_type } = resolved;
+            const match_note = match_type === 'exact'
+                ? undefined
+                : match_type === 'semver-range'
+                    ? `Resolved via SemVer range processing: the requested window ${from_version} -> ${to_version} ` +
+                        `falls inside the map verified for ${map.from_version} -> ${map.to_version}. ` +
+                        'Details specific to intermediate minor/patch versions may not be covered.'
+                    : `No map exists for exactly ${from_version} -> ${to_version}; returning the map verified for ` +
+                        `${map.from_version} -> ${map.to_version} (same major-version jump). ` +
+                        'Details specific to intermediate minor/patch versions may not be covered.';
+            return jsonResult({
+                found: true,
+                requested,
+                match_type,
+                resolved_via: resolvedViaOf(match_type),
+                ...(match_note ? { match_note } : {}),
+                migration: map,
+            });
+        }
+        catch (err) {
+            return storeError(err);
+        }
+    });
+    server.registerTool('get_breaking_changes', {
+        title: 'Get breaking changes in a version',
+        description: 'Returns the breaking changes introduced when upgrading TO the given version of a package (matched by ' +
+            'major version against curated migration maps), with source citations and last_verified dates. ' +
+            'Accepts concrete versions or SemVer ranges ("15", "^15.0.0", "15.x"); resolution is disclosed via ' +
+            'match_type/resolved_via. If found=false, no verified data exists — do not guess.',
+        inputSchema: {
+            package: packageArg,
+            version: z
+                .string()
+                .min(1)
+                .describe('The version (or SemVer range) whose breaking changes you want, e.g. "2.0.0", "^15.0.0"'),
+            ecosystem: ecosystemArg,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ package: pkg, version, ecosystem }) => {
+        const requested = { package: pkg, ecosystem, version };
+        try {
+            const target = interpretDescriptor(version);
+            const maps = await store.getMapsForPackage(ecosystem, pkg);
+            const matching = target === null ? [] : maps.filter((m) => majorOf(m.to_version) === target.major);
+            if (matching.length === 0) {
+                const available = maps.length > 0 ? maps.map(toSummary) : await store.listMaps();
+                return jsonResult({
+                    found: false,
+                    requested,
+                    message: NOT_FOUND_GUIDANCE,
+                    available_maps: available,
+                });
+            }
+            return jsonResult({
+                found: true,
+                requested,
+                results: matching.map((map) => {
+                    const match_type = normalizeVersion(map.to_version) === normalizeVersion(version)
+                        ? 'exact'
+                        : target.kind === 'range'
+                            ? 'semver-range'
+                            : 'major-version';
+                    return {
+                        from_version: map.from_version,
+                        to_version: map.to_version,
+                        match_type,
+                        resolved_via: resolvedViaOf(match_type),
+                        status: map.status,
+                        last_verified: map.last_verified,
+                        source_urls: map.source_urls,
+                        summary: map.summary,
+                        breaking_changes: map.breaking_changes,
+                        deprecations: map.deprecations,
+                    };
+                }),
+            });
+        }
+        catch (err) {
+            return storeError(err);
+        }
+    });
+    // Stub per brief §7/§11: declared so agents can discover it, but explicitly
+    // returns "not implemented" — it must never look like real compatibility data.
+    server.registerTool('check_compatibility', {
+        title: 'Check cross-package compatibility (not yet implemented)',
+        description: 'PLANNED: known compatibility issues between two package versions. Currently returns implemented=false ' +
+            'and no data. Do not infer compatibility (or incompatibility) from this response.',
+        inputSchema: {
+            package_a: z.string().min(1),
+            version_a: z.string().min(1),
+            package_b: z.string().min(1),
+            version_b: z.string().min(1),
+            ecosystem: ecosystemArg,
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => jsonResult({
+        implemented: false,
+        message: 'Cross-package compatibility lookup is planned but not yet available. This response contains no ' +
+            'compatibility data — do not treat it as evidence that the packages are (or are not) compatible.',
+    }));
+    return server;
+}
+//# 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/store/create-store.d.ts

@@ -0,0 +1,2 @@
+import type { MigrationStore } from './store.js';
+export declare function createStore(): MigrationStore;

package/dist/store/create-store.js

@@ -0,0 +1,18 @@
+/**
+ * Store selection: Supabase when env vars are present, local JSON files
+ * otherwise. Never throws on missing configuration — the local fallback
+ * guarantees the server starts in development.
+ */
+import { LocalFileStore } from './local-store.js';
+import { SupabaseStore } from './supabase-store.js';
+export function createStore() {
+    const url = process.env.SUPABASE_URL;
+    const key = process.env.SUPABASE_ANON_KEY ?? process.env.SUPABASE_KEY;
+    if (url && key)
+        return new SupabaseStore(url, key);
+    if (url || key) {
+        console.error('[asynthetic] Incomplete Supabase config (need both SUPABASE_URL and SUPABASE_ANON_KEY); falling back to local files.');
+    }
+    return new LocalFileStore();
+}
+//# sourceMappingURL=create-store.js.map

package/dist/store/create-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-store.js","sourceRoot":"","sources":["../../src/store/create-store.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAEpD,MAAM,UAAU,WAAW;IACzB,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IACrC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IACtE,IAAI,GAAG,IAAI,GAAG;QAAE,OAAO,IAAI,aAAa,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAEnD,IAAI,GAAG,IAAI,GAAG,EAAE,CAAC;QACf,OAAO,CAAC,KAAK,CACX,sHAAsH,CACvH,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,cAAc,EAAE,CAAC;AAC9B,CAAC"}

package/dist/store/local-store.d.ts

@@ -0,0 +1,14 @@
+import { type MigrationMap } from '../types/migration-map.js';
+import { type MapSummary, type MigrationStore } from './store.js';
+export declare function loadLocalMaps(dataDir: string, opts?: {
+    includeStale?: boolean;
+}): MigrationMap[];
+export declare class LocalFileStore implements MigrationStore {
+    private readonly dataDir;
+    private cache;
+    constructor(dataDir?: string);
+    private load;
+    getMapsForPackage(ecosystem: string, pkg: string): Promise<MigrationMap[]>;
+    listMaps(): Promise<MapSummary[]>;
+    describe(): string;
+}

package/dist/store/local-store.js

@@ -0,0 +1,69 @@
+/**
+ * Local-file fallback store: reads migration maps from data/maps/**\/*.json.
+ *
+ * Used when Supabase env vars are absent so the server always starts in
+ * development. Every file is validated with MigrationMapSchema on load;
+ * invalid files are skipped with a stderr warning, never served.
+ */
+import { readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { MigrationMapSchema } from '../types/migration-map.js';
+import { toSummary } from './store.js';
+// Resolves to <project>/data/maps from both src/store (tsx) and dist/store (build).
+const DEFAULT_DATA_DIR = fileURLToPath(new URL('../../data/maps', import.meta.url));
+export function loadLocalMaps(dataDir, opts = {}) {
+    let entries;
+    try {
+        entries = readdirSync(dataDir, { recursive: true, withFileTypes: true });
+    }
+    catch (err) {
+        console.error(`[asynthetic] Cannot read data directory ${dataDir}:`, err);
+        return [];
+    }
+    const maps = [];
+    for (const entry of entries) {
+        if (!entry.isFile() || !entry.name.endsWith('.json'))
+            continue;
+        const filePath = path.join(entry.parentPath, entry.name);
+        try {
+            const parsed = MigrationMapSchema.safeParse(JSON.parse(readFileSync(filePath, 'utf8')));
+            if (!parsed.success) {
+                console.error(`[asynthetic] Skipping invalid map ${filePath}: ${parsed.error.issues
+                    .slice(0, 3)
+                    .map((i) => `${i.path.join('.')}: ${i.message}`)
+                    .join('; ')}`);
+                continue;
+            }
+            if (!opts.includeStale && parsed.data.status === 'stale')
+                continue;
+            maps.push(parsed.data);
+        }
+        catch (err) {
+            console.error(`[asynthetic] Skipping unreadable map ${filePath}:`, err);
+        }
+    }
+    return maps;
+}
+export class LocalFileStore {
+    dataDir;
+    cache = null;
+    constructor(dataDir = process.env.MIGRATION_DATA_DIR ?? DEFAULT_DATA_DIR) {
+        this.dataDir = dataDir;
+    }
+    load() {
+        this.cache ??= loadLocalMaps(this.dataDir);
+        return this.cache;
+    }
+    async getMapsForPackage(ecosystem, pkg) {
+        const wanted = pkg.trim().toLowerCase();
+        return this.load().filter((m) => m.ecosystem === ecosystem && m.package.toLowerCase() === wanted);
+    }
+    async listMaps() {
+        return this.load().map(toSummary);
+    }
+    describe() {
+        return `local JSON files (${this.dataDir})`;
+    }
+}
+//# sourceMappingURL=local-store.js.map

package/dist/store/local-store.js.map

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

package/dist/store/store.d.ts

@@ -0,0 +1,50 @@
+import type { MigrationMap, MigrationStatus } from '../types/migration-map.js';
+export interface MapSummary {
+    ecosystem: string;
+    package: string;
+    from_version: string;
+    to_version: string;
+    status: MigrationStatus;
+    last_verified: string;
+}
+export interface MigrationStore {
+    /** All non-stale maps for a package (case-insensitive package match). */
+    getMapsForPackage(ecosystem: string, pkg: string): Promise<MigrationMap[]>;
+    /** Summaries of every non-stale map in the store. */
+    listMaps(): Promise<MapSummary[]>;
+    /** Human-readable description of the backing store, for stderr logging. */
+    describe(): string;
+}
+export declare function toSummary(map: MigrationMap): MapSummary;
+export declare function normalizeVersion(v: string): string;
+export type MatchType = 'exact' | 'semver-range' | 'major-version';
+/** Wire-format disclosure of how a lookup was resolved. */
+export type ResolvedVia = 'exact_string' | 'semver_range' | 'major_version';
+export declare function resolvedViaOf(match: MatchType): ResolvedVia;
+export interface DescriptorInfo {
+    major: number;
+    kind: 'version' | 'range';
+}
+/**
+ * Interpret a user-supplied version descriptor.
+ *
+ * - Concrete/partial versions ("14.2.35", "2.0.0-beta.2", "14", "14.2") ->
+ *   kind 'version'.
+ * - SemVer ranges ("^14.2.0", "~14.1.0", "14.x", ">=14.2 <15") -> kind
+ *   'range', anchored at the range's minimum satisfying version. A range
+ *   spanning multiple majors resolves to its lowest major.
+ */
+export declare function interpretDescriptor(desc: string): DescriptorInfo | null;
+/** Major version of a descriptor ("2.0.0-beta.2" -> 2, "^14.2.0" -> 14). */
+export declare function majorOf(v: string): number | null;
+/**
+ * Exact from/to string match first; otherwise interpret both descriptors via
+ * SemVer and match maps whose from/to majors cover the requested window
+ * (e.g. "^14.2.0" -> "^15.0.0" finds the map verified for 14.2.35 -> 15.0.0).
+ * Callers must surface non-exact matches to the agent — the map's verified
+ * endpoints may differ from what was asked.
+ */
+export declare function resolveMigration(maps: MigrationMap[], fromDesc: string, toDesc: string): {
+    map: MigrationMap;
+    match_type: MatchType;
+} | null;

package/dist/store/store.js

@@ -0,0 +1,90 @@
+/**
+ * Store abstraction + version-matching logic shared by every backend.
+ *
+ * Stores are deliberately dumb: they return all maps for a package and let
+ * `resolveMigration` do the matching, so Supabase and the local-file fallback
+ * can never disagree on semantics.
+ *
+ * Matching is SemVer-aware: descriptors may be concrete versions ("14.2.35"),
+ * partial versions ("14", "14.2"), or ranges ("^14.2.0", "~14.1.0", "14.x").
+ */
+import semver from 'semver';
+export function toSummary(map) {
+    return {
+        ecosystem: map.ecosystem,
+        package: map.package,
+        from_version: map.from_version,
+        to_version: map.to_version,
+        status: map.status,
+        last_verified: map.last_verified,
+    };
+}
+export function normalizeVersion(v) {
+    return v.trim().replace(/^v/i, '');
+}
+export function resolvedViaOf(match) {
+    switch (match) {
+        case 'exact':
+            return 'exact_string';
+        case 'semver-range':
+            return 'semver_range';
+        case 'major-version':
+            return 'major_version';
+    }
+}
+/**
+ * Interpret a user-supplied version descriptor.
+ *
+ * - Concrete/partial versions ("14.2.35", "2.0.0-beta.2", "14", "14.2") ->
+ *   kind 'version'.
+ * - SemVer ranges ("^14.2.0", "~14.1.0", "14.x", ">=14.2 <15") -> kind
+ *   'range', anchored at the range's minimum satisfying version. A range
+ *   spanning multiple majors resolves to its lowest major.
+ */
+export function interpretDescriptor(desc) {
+    const norm = normalizeVersion(desc);
+    const exact = semver.valid(norm, { loose: true });
+    if (exact)
+        return { major: semver.major(exact), kind: 'version' };
+    // Partial versions count as versions, not ranges, even though semver
+    // technically parses "14" as an X-range.
+    if (/^\d+(\.\d+)?$/.test(norm)) {
+        return { major: Number.parseInt(norm, 10), kind: 'version' };
+    }
+    if (semver.validRange(norm, { loose: true })) {
+        const min = semver.minVersion(norm, { loose: true });
+        if (min)
+            return { major: min.major, kind: 'range' };
+    }
+    // Last resort for non-semver strings like "1.x-legacy": leading digits.
+    const lead = norm.match(/^(\d+)/);
+    return lead ? { major: Number(lead[1]), kind: 'version' } : null;
+}
+/** Major version of a descriptor ("2.0.0-beta.2" -> 2, "^14.2.0" -> 14). */
+export function majorOf(v) {
+    return interpretDescriptor(v)?.major ?? null;
+}
+/**
+ * Exact from/to string match first; otherwise interpret both descriptors via
+ * SemVer and match maps whose from/to majors cover the requested window
+ * (e.g. "^14.2.0" -> "^15.0.0" finds the map verified for 14.2.35 -> 15.0.0).
+ * Callers must surface non-exact matches to the agent — the map's verified
+ * endpoints may differ from what was asked.
+ */
+export function resolveMigration(maps, fromDesc, toDesc) {
+    const from = normalizeVersion(fromDesc);
+    const to = normalizeVersion(toDesc);
+    const exact = maps.find((m) => normalizeVersion(m.from_version) === from && normalizeVersion(m.to_version) === to);
+    if (exact)
+        return { map: exact, match_type: 'exact' };
+    const fromInfo = interpretDescriptor(fromDesc);
+    const toInfo = interpretDescriptor(toDesc);
+    if (!fromInfo || !toInfo)
+        return null;
+    const candidate = maps.find((m) => majorOf(m.from_version) === fromInfo.major && majorOf(m.to_version) === toInfo.major);
+    if (!candidate)
+        return null;
+    const match_type = fromInfo.kind === 'range' || toInfo.kind === 'range' ? 'semver-range' : 'major-version';
+    return { map: candidate, match_type };
+}
+//# sourceMappingURL=store.js.map

package/dist/store/store.js.map

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

package/dist/store/supabase-store.d.ts

@@ -0,0 +1,11 @@
+import type { MigrationMap } from '../types/migration-map.js';
+import { toSummary, type MapSummary, type MigrationStore } from './store.js';
+export declare class SupabaseStore implements MigrationStore {
+    private readonly url;
+    private readonly client;
+    constructor(url: string, key: string);
+    getMapsForPackage(ecosystem: string, pkg: string): Promise<MigrationMap[]>;
+    listMaps(): Promise<MapSummary[]>;
+    describe(): string;
+}
+export { toSummary };