catence 0.0.0 → 0.2.0-beta.1

package/dist/interfaces/http/cli-options.d.ts

@@ -0,0 +1,9 @@
+export type ServeCliOptions = {
+    home?: string;
+    host: string;
+    port: number;
+    allowedOrigins: string[];
+    help: boolean;
+};
+export declare const SERVE_USAGE = "Usage: catence serve [options]\n\nRun Catence as a local Streamable HTTP MCP server.\n\nOptions:\n  --home <directory>         Catence catalog home. Defaults to CATENCE_HOME or ~/.catence.\n  --host <host>              Listener host. Defaults to 127.0.0.1.\n  --port <port>              Listener port. Defaults to 8787.\n  --allow-origin <origin>    Browser origin allowed to call Catence APIs. May be repeated.\n  -h, --help                 Show this help text.";
+export declare function parseServeCliOptions(arguments_: readonly string[]): ServeCliOptions;

package/dist/interfaces/http/cli-options.js

@@ -0,0 +1,81 @@
+export const SERVE_USAGE = `Usage: catence serve [options]
+
+Run Catence as a local Streamable HTTP MCP server.
+
+Options:
+  --home <directory>         Catence catalog home. Defaults to CATENCE_HOME or ~/.catence.
+  --host <host>              Listener host. Defaults to 127.0.0.1.
+  --port <port>              Listener port. Defaults to 8787.
+  --allow-origin <origin>    Browser origin allowed to call Catence APIs. May be repeated.
+  -h, --help                 Show this help text.`;
+function requiredValue(arguments_, index, option) {
+    const value = arguments_[index + 1];
+    if (!value || value.startsWith('-'))
+        throw new Error(`${option} requires a value.`);
+    return value;
+}
+function parsePort(value) {
+    if (!/^\d+$/.test(value))
+        throw new Error('--port must be an integer between 1 and 65535.');
+    const port = Number(value);
+    if (port < 1 || port > 65_535)
+        throw new Error('--port must be an integer between 1 and 65535.');
+    return port;
+}
+export function parseServeCliOptions(arguments_) {
+    let home;
+    let host = process.env.CATENCE_HTTP_HOST ?? '127.0.0.1';
+    let port = process.env.CATENCE_HTTP_PORT ? parsePort(process.env.CATENCE_HTTP_PORT) : 8787;
+    const allowedOrigins = [];
+    for (let index = 0; index < arguments_.length; index++) {
+        const argument = arguments_[index];
+        if (argument === '-h' || argument === '--help')
+            return { home, host, port, allowedOrigins, help: true };
+        if (argument === '--home') {
+            home = requiredValue(arguments_, index, '--home');
+            index++;
+            continue;
+        }
+        if (argument.startsWith('--home=')) {
+            home = argument.slice('--home='.length);
+            if (!home)
+                throw new Error('--home requires a value.');
+            continue;
+        }
+        if (argument === '--host') {
+            host = requiredValue(arguments_, index, '--host');
+            index++;
+            continue;
+        }
+        if (argument.startsWith('--host=')) {
+            host = argument.slice('--host='.length);
+            if (!host)
+                throw new Error('--host requires a value.');
+            continue;
+        }
+        if (argument === '--port') {
+            port = parsePort(requiredValue(arguments_, index, '--port'));
+            index++;
+            continue;
+        }
+        if (argument.startsWith('--port=')) {
+            port = parsePort(argument.slice('--port='.length));
+            continue;
+        }
+        if (argument === '--allow-origin') {
+            allowedOrigins.push(requiredValue(arguments_, index, '--allow-origin'));
+            index++;
+            continue;
+        }
+        if (argument.startsWith('--allow-origin=')) {
+            const origin = argument.slice('--allow-origin='.length);
+            if (!origin)
+                throw new Error('--allow-origin requires a value.');
+            allowedOrigins.push(origin);
+            continue;
+        }
+        throw new Error(`Unknown option: ${argument}`);
+    }
+    return { home, host, port, allowedOrigins, help: false };
+}
+//# sourceMappingURL=cli-options.js.map

package/dist/interfaces/http/server.d.ts

@@ -0,0 +1,17 @@
+import { type Server } from 'node:http';
+import { type CatalogPaths, type CatencePaths } from '../../runtime/index.js';
+export type CatenceHttpServerOptions = {
+    /** A shared catalog for public servers. All data APIs then require athleteId. */
+    catalogPaths?: CatalogPaths;
+    /** Internal compatibility hook for tests and embedded single-store callers. */
+    paths?: CatencePaths;
+    allowedOrigins?: readonly string[];
+};
+/**
+ * Create Catence's local Streamable HTTP server.
+ *
+ * Each MCP request gets an independent stateless transport and server instance.
+ * This keeps the HTTP surface compatible with local clients without introducing
+ * process-wide MCP session state or a second query implementation.
+ */
+export declare function createCatenceHttpServer(options?: CatenceHttpServerOptions): Server;

package/dist/interfaces/http/server.js

@@ -0,0 +1,196 @@
+import { createServer } from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { catenceRuntimeHealth, DashboardSnapshotService, jsonSafe, loadCatalog, openReadOnlyRepository, resolveAthlete, resolveCatalogPaths } from '../../runtime/index.js';
+import { createCatenceMcpServer } from '../mcp/server.js';
+const MAX_REQUEST_BYTES = 1_000_000;
+function json(response, statusCode, value) {
+    const body = JSON.stringify(jsonSafe(value));
+    response.writeHead(statusCode, { 'content-type': 'application/json; charset=utf-8' });
+    response.end(body);
+}
+function addCorsHeaders(request, response, allowedOrigins) {
+    const origin = request.headers.origin;
+    if (!origin)
+        return true;
+    if (!allowedOrigins.includes(origin))
+        return false;
+    response.setHeader('access-control-allow-origin', origin);
+    response.setHeader('vary', 'Origin');
+    response.setHeader('access-control-allow-methods', 'GET, POST, DELETE, OPTIONS');
+    response.setHeader('access-control-allow-headers', 'content-type, mcp-session-id');
+    return true;
+}
+async function readJsonBody(request) {
+    let size = 0;
+    const chunks = [];
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        size += buffer.length;
+        if (size > MAX_REQUEST_BYTES)
+            throw new Error(`Request body exceeds the ${MAX_REQUEST_BYTES} byte limit.`);
+        chunks.push(buffer);
+    }
+    const body = Buffer.concat(chunks).toString('utf8').trim();
+    if (!body)
+        return undefined;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        throw new Error('Request body must be valid JSON.');
+    }
+}
+function methodNotAllowed(response) {
+    json(response, 405, {
+        jsonrpc: '2.0',
+        error: { code: -32000, message: 'Method not allowed.' },
+        id: null,
+    });
+}
+function parseDate(value, name) {
+    if (value === null)
+        return undefined;
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || Number.isNaN(Date.parse(`${value}T00:00:00.000Z`))) {
+        throw new Error(`${name} must use YYYY-MM-DD.`);
+    }
+    return value;
+}
+function dashboardOptions(url) {
+    const endDate = parseDate(url.searchParams.get('endDate'), 'endDate') ?? new Date().toISOString().slice(0, 10);
+    const daysValue = url.searchParams.get('days') ?? '28';
+    if (!/^\d+$/.test(daysValue))
+        throw new Error('days must be an integer between 1 and 90.');
+    const days = Number(daysValue);
+    if (days < 1 || days > 90)
+        throw new Error('days must be an integer between 1 and 90.');
+    return { endDate, days };
+}
+async function dashboardSnapshot(paths, url) {
+    const repository = await openReadOnlyRepository(paths);
+    try {
+        return await new DashboardSnapshotService(repository).snapshot(dashboardOptions(url));
+    }
+    finally {
+        await repository.close();
+    }
+}
+async function dashboardPaths(catalogPaths, staticPaths, url) {
+    if (catalogPaths) {
+        const athleteId = url.searchParams.get('athleteId');
+        if (!athleteId)
+            throw new Error('athleteId is required. Call /api/v1/athletes to inspect the configured catalog.');
+        return (await resolveAthlete(catalogPaths, athleteId)).paths;
+    }
+    if (staticPaths)
+        return staticPaths;
+    throw new Error('No Catence data store is configured.');
+}
+async function handleMcpRequest(request, response, paths) {
+    if (request.method !== 'POST') {
+        methodNotAllowed(response);
+        return;
+    }
+    let body;
+    try {
+        body = await readJsonBody(request);
+    }
+    catch (error) {
+        json(response, 400, {
+            jsonrpc: '2.0',
+            error: { code: -32700, message: error instanceof Error ? error.message : String(error) },
+            id: null,
+        });
+        return;
+    }
+    const server = createCatenceMcpServer(paths);
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    let cleanedUp = false;
+    const cleanup = async () => {
+        if (cleanedUp)
+            return;
+        cleanedUp = true;
+        await Promise.allSettled([transport.close(), server.close()]);
+    };
+    response.once('close', () => { void cleanup(); });
+    try {
+        await server.connect(transport);
+        await transport.handleRequest(request, response, body);
+    }
+    catch (error) {
+        if (!response.headersSent) {
+            json(response, 500, {
+                jsonrpc: '2.0',
+                error: { code: -32603, message: error instanceof Error ? error.message : 'Internal server error.' },
+                id: null,
+            });
+        }
+    }
+    finally {
+        // The response may already have ended before handleRequest resolves, in
+        // which case adding a close listener here would miss cleanup entirely.
+        if (response.writableEnded || response.destroyed)
+            void cleanup();
+    }
+}
+/**
+ * Create Catence's local Streamable HTTP server.
+ *
+ * Each MCP request gets an independent stateless transport and server instance.
+ * This keeps the HTTP surface compatible with local clients without introducing
+ * process-wide MCP session state or a second query implementation.
+ */
+export function createCatenceHttpServer(options = {}) {
+    const catalogPaths = options.catalogPaths ?? (options.paths ? null : resolveCatalogPaths());
+    const staticPaths = options.paths ?? null;
+    const allowedOrigins = options.allowedOrigins ?? [];
+    return createServer((request, response) => {
+        void (async () => {
+            if (!addCorsHeaders(request, response, allowedOrigins)) {
+                json(response, 403, { error: { code: 'origin_not_allowed', message: 'This browser origin is not allowed to access Catence.' } });
+                return;
+            }
+            const pathname = new URL(request.url ?? '/', 'http://localhost').pathname;
+            if (request.method === 'OPTIONS') {
+                response.writeHead(204).end();
+                return;
+            }
+            if (pathname === '/health' && request.method === 'GET') {
+                json(response, 200, catenceRuntimeHealth());
+                return;
+            }
+            if (pathname === '/api/v1/athletes' && request.method === 'GET') {
+                if (!catalogPaths) {
+                    json(response, 200, { defaultAthleteId: 'local', athletes: [{ id: 'local', label: 'Local athlete' }] });
+                    return;
+                }
+                try {
+                    const catalog = await loadCatalog(catalogPaths);
+                    json(response, 200, { defaultAthleteId: catalog.defaultAthleteId, athletes: catalog.athletes });
+                }
+                catch (error) {
+                    json(response, 400, { error: { code: 'catalog_unavailable', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
+            if (pathname === '/api/v1/dashboard' && request.method === 'GET') {
+                try {
+                    const url = new URL(request.url ?? '/', 'http://localhost');
+                    json(response, 200, await dashboardSnapshot(await dashboardPaths(catalogPaths, staticPaths, url), url));
+                }
+                catch (error) {
+                    json(response, 400, { error: { code: 'dashboard_unavailable', message: error instanceof Error ? error.message : String(error) } });
+                }
+                return;
+            }
+            if (pathname === '/mcp') {
+                await handleMcpRequest(request, response, catalogPaths ?? staticPaths ?? resolveCatalogPaths());
+                return;
+            }
+            json(response, 404, { error: { code: 'not_found', message: 'No Catence endpoint matches this request.' } });
+        })().catch((error) => {
+            if (!response.headersSent)
+                json(response, 500, { error: { code: 'internal_error', message: error instanceof Error ? error.message : String(error) } });
+        });
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/interfaces/mcp/cli-options.d.ts

@@ -0,0 +1,6 @@
+export type McpCliOptions = {
+    home?: string;
+    help: boolean;
+};
+export declare const MCP_USAGE = "Usage: catence [--home <directory>]\n       catence demo [--home <directory>]\n\nRun Catence as a local, stdio-only MCP server. Ordinary data access is read-only; only declared Strava hydration tools write through the locked local store.\n\nThe demo command creates safe generated data in ~/.catence-demo by default, then starts the same shared-athlete MCP server. It refuses to overwrite a non-demo athlete store.\n\nOptions:\n  --home <directory>      Catence catalog home. Defaults to CATENCE_HOME or ~/.catence.\n  -h, --help              Show this help text.";
+export declare function parseMcpCliOptions(arguments_: readonly string[]): McpCliOptions;

package/dist/interfaces/mcp/cli-options.js

@@ -0,0 +1,36 @@
+export const MCP_USAGE = `Usage: catence [--home <directory>]
+       catence demo [--home <directory>]
+
+Run Catence as a local, stdio-only MCP server. Ordinary data access is read-only; only declared Strava hydration tools write through the locked local store.
+
+The demo command creates safe generated data in ~/.catence-demo by default, then starts the same shared-athlete MCP server. It refuses to overwrite a non-demo athlete store.
+
+Options:
+  --home <directory>      Catence catalog home. Defaults to CATENCE_HOME or ~/.catence.
+  -h, --help              Show this help text.`;
+export function parseMcpCliOptions(arguments_) {
+    let home;
+    for (let index = 0; index < arguments_.length; index++) {
+        const argument = arguments_[index];
+        if (argument === '-h' || argument === '--help')
+            return { home, help: true };
+        if (argument === '--home') {
+            const value = arguments_[index + 1];
+            if (!value || value.startsWith('-'))
+                throw new Error('--home requires a directory.');
+            home = value;
+            index++;
+            continue;
+        }
+        if (argument.startsWith('--home=')) {
+            const value = argument.slice('--home='.length);
+            if (!value)
+                throw new Error('--home requires a directory.');
+            home = value;
+            continue;
+        }
+        throw new Error(`Unknown option: ${argument}`);
+    }
+    return { home, help: false };
+}
+//# sourceMappingURL=cli-options.js.map

package/dist/interfaces/mcp/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/interfaces/mcp/main.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { existsSync } from 'node:fs';
+import { addAthlete, athleteStorePaths, createDemoStore, defaultCatalogHome, initializeCatalog, loadCatalog, resolveCatalogPaths } from '../../runtime/index.js';
+import { parseServeCliOptions, SERVE_USAGE } from '../http/cli-options.js';
+import { createCatenceHttpServer } from '../http/server.js';
+import { MCP_USAGE, parseMcpCliOptions } from './cli-options.js';
+import { createCatenceMcpServer } from './server.js';
+async function run() {
+    const arguments_ = process.argv.slice(2);
+    if (arguments_[0] === 'serve') {
+        const options = parseServeCliOptions(arguments_.slice(1));
+        if (options.help) {
+            process.stderr.write(`${SERVE_USAGE}\n`);
+            return;
+        }
+        const httpServer = createCatenceHttpServer({
+            catalogPaths: resolveCatalogPaths(options.home),
+            allowedOrigins: options.allowedOrigins,
+        });
+        await new Promise((resolve, reject) => {
+            httpServer.once('error', reject);
+            httpServer.listen(options.port, options.host, () => {
+                httpServer.off('error', reject);
+                resolve();
+            });
+        });
+        console.error(`Catence Streamable HTTP server is listening at http://${options.host}:${options.port}/mcp`);
+        const close = () => {
+            httpServer.close(() => process.exit(0));
+        };
+        process.once('SIGINT', close);
+        process.once('SIGTERM', close);
+        return;
+    }
+    const demo = arguments_[0] === 'demo';
+    const options = parseMcpCliOptions(demo ? arguments_.slice(1) : arguments_);
+    if (options.help) {
+        process.stderr.write(`${MCP_USAGE}\n`);
+        return;
+    }
+    const catalogPaths = resolveCatalogPaths(demo && !options.home ? `${defaultCatalogHome()}-demo` : options.home);
+    if (demo) {
+        if (!existsSync(catalogPaths.catalog)) {
+            await initializeCatalog(catalogPaths, { id: 'demo', label: 'Generated demo athlete' });
+        }
+        else if (!(await loadCatalog(catalogPaths)).athletes.some((athlete) => athlete.id === 'demo')) {
+            await addAthlete(catalogPaths, { id: 'demo', label: 'Generated demo athlete' });
+        }
+        const paths = athleteStorePaths(catalogPaths, 'demo');
+        const result = await createDemoStore(paths);
+        process.stderr.write(`${String(result.message)}\n`);
+    }
+    const server = createCatenceMcpServer(catalogPaths);
+    await server.connect(new StdioServerTransport());
+    console.error('Catence MCP server is running on stdio; ordinary tools are read-only and Strava hydration is lock-guarded.');
+}
+try {
+    await run();
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`catence: ${message}\n\n${process.argv[2] === 'serve' ? SERVE_USAGE : MCP_USAGE}\n`);
+    process.exitCode = 2;
+}
+//# sourceMappingURL=main.js.map

package/dist/interfaces/mcp/server.d.ts

@@ -0,0 +1,8 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type CatalogPaths, hydrateStravaActivity, type CatencePaths } from '../../runtime/index.js';
+type StravaActivityHydrator = typeof hydrateStravaActivity;
+type McpDependencies = {
+    hydrateStravaActivity?: StravaActivityHydrator;
+};
+export declare function createCatenceMcpServer(paths?: CatencePaths | CatalogPaths, dependencies?: McpDependencies): McpServer;
+export {};