catence 0.1.0 → 0.2.0-beta.2

package/dist/core/runtime/catalog.js

@@ -0,0 +1,111 @@
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { z } from 'zod';
+import { resolvePaths } from './configuration.js';
+const CATALOG_FORMAT_VERSION = 1;
+const athleteIdSchema = z.string().regex(/^[a-z][a-z0-9-]{0,62}$/, 'must use lowercase letters, digits, and hyphens, starting with a letter');
+const catalogSchema = z.object({
+    formatVersion: z.literal(CATALOG_FORMAT_VERSION),
+    defaultAthleteId: athleteIdSchema,
+    athletes: z.array(z.object({
+        id: athleteIdSchema,
+        label: z.string().trim().min(1).max(120),
+        createdAt: z.string().datetime(),
+    }).strict()).min(1),
+}).strict().superRefine((catalog, context) => {
+    const ids = catalog.athletes.map((athlete) => athlete.id);
+    if (new Set(ids).size !== ids.length)
+        context.addIssue({ code: 'custom', path: ['athletes'], message: 'athlete IDs must be unique' });
+    if (!ids.includes(catalog.defaultAthleteId))
+        context.addIssue({ code: 'custom', path: ['defaultAthleteId'], message: 'must name a configured athlete' });
+});
+export function defaultCatalogHome() {
+    return path.resolve(process.env.CATENCE_HOME ?? path.join(homedir(), '.catence'));
+}
+export function resolveCatalogPaths(root = defaultCatalogHome()) {
+    const absoluteRoot = path.resolve(root);
+    return {
+        root: absoluteRoot,
+        catalog: path.join(absoluteRoot, 'catalog.json'),
+        athletes: path.join(absoluteRoot, 'athletes'),
+        console: path.join(absoluteRoot, 'console'),
+    };
+}
+export function athleteStorePaths(catalogPaths, athleteId) {
+    const id = athleteIdSchema.parse(athleteId);
+    return resolvePaths(path.join(catalogPaths.athletes, id));
+}
+function legacyStoreMessage(paths) {
+    return `Catence 0.2 uses a catalog at ${paths.root}. The existing directory looks like a 0.1 data store and cannot be migrated automatically. Create a fresh catalog and re-sync each athlete.`;
+}
+async function hasEntries(directory) {
+    return (await readdir(directory).catch((error) => error.code === 'ENOENT' ? [] : Promise.reject(error))).length > 0;
+}
+export async function loadCatalog(paths = resolveCatalogPaths()) {
+    const contents = await readFile(paths.catalog, 'utf8').catch((error) => {
+        if (error.code !== 'ENOENT')
+            throw error;
+        if (existsSync(path.join(paths.root, 'catence.duckdb')))
+            throw new Error(legacyStoreMessage(paths));
+        throw new Error(`No Catence catalog exists at ${paths.root}. Run catence-data setup first.`);
+    });
+    try {
+        return catalogSchema.parse(JSON.parse(contents));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid Catence catalog at ${paths.catalog}: ${message}`);
+    }
+}
+async function writeCatalog(paths, catalog) {
+    await mkdir(paths.root, { recursive: true, mode: 0o700 });
+    const temporary = `${paths.catalog}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(catalog, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await rename(temporary, paths.catalog);
+}
+export async function initializeCatalog(paths = resolveCatalogPaths(), athlete) {
+    if (existsSync(paths.catalog))
+        return loadCatalog(paths);
+    if (await hasEntries(paths.root)) {
+        if (existsSync(path.join(paths.root, 'catence.duckdb')))
+            throw new Error(legacyStoreMessage(paths));
+        throw new Error(`Refusing to initialize ${paths.root}: choose an empty --home directory or remove its unrelated contents.`);
+    }
+    const id = athleteIdSchema.parse(athlete.id);
+    const record = { id, label: athlete.label.trim(), createdAt: new Date().toISOString() };
+    if (!record.label)
+        throw new Error('Athlete label is required.');
+    const catalog = { formatVersion: CATALOG_FORMAT_VERSION, defaultAthleteId: id, athletes: [record] };
+    await writeCatalog(paths, catalog);
+    return catalog;
+}
+export async function addAthlete(paths, athlete) {
+    const catalog = await loadCatalog(paths);
+    const id = athleteIdSchema.parse(athlete.id);
+    if (catalog.athletes.some((entry) => entry.id === id))
+        throw new Error(`Athlete ${id} already exists.`);
+    const label = athlete.label.trim();
+    if (!label)
+        throw new Error('Athlete label is required.');
+    const next = {
+        ...catalog,
+        defaultAthleteId: athlete.setDefault ? id : catalog.defaultAthleteId,
+        athletes: [...catalog.athletes, { id, label, createdAt: new Date().toISOString() }],
+    };
+    await writeCatalog(paths, next);
+    return next;
+}
+export async function resolveAthlete(paths, athleteId) {
+    const catalog = await loadCatalog(paths);
+    const athlete = catalog.athletes.find((entry) => entry.id === athleteId);
+    if (!athlete)
+        throw new Error(`Unknown athlete ${athleteId}. Call list_athletes to inspect the configured catalog.`);
+    return { athlete, paths: athleteStorePaths(paths, athlete.id) };
+}
+export async function defaultAthlete(paths = resolveCatalogPaths()) {
+    const catalog = await loadCatalog(paths);
+    return resolveAthlete(paths, catalog.defaultAthleteId);
+}
+//# sourceMappingURL=catalog.js.map

package/dist/core/runtime/configuration.d.ts

@@ -4,7 +4,7 @@ export type { CatencePaths } from '../../contracts/runtime.js';
 export declare function resolvePaths(root?: string): CatencePaths;
 export declare function ensurePaths(paths: CatencePaths): Promise<void>;
 export declare function defaultFromDate(now?: Date): string;
-export declare function requireIntervalsConfig(): {
+export declare function requireIntervalsConfig(environment?: NodeJS.ProcessEnv): {
     apiKey: string;
     athleteId: string;
 };

package/dist/core/runtime/configuration.js

@@ -23,11 +23,11 @@ export function defaultFromDate(now = new Date()) {
     const date = new Date(Date.UTC(now.getUTCFullYear() - 1, now.getUTCMonth(), now.getUTCDate()));
     return date.toISOString().slice(0, 10);
 }
-export function requireIntervalsConfig() {
-    const apiKey = process.env.INTERVALS_API_KEY;
+export function requireIntervalsConfig(environment = process.env) {
+    const apiKey = environment.INTERVALS_API_KEY;
     if (!apiKey)
         throw new Error('INTERVALS_API_KEY is required for an Intervals sync.');
-    return { apiKey, athleteId: process.env.INTERVALS_ATHLETE_ID ?? '0' };
+    return { apiKey, athleteId: environment.INTERVALS_ATHLETE_ID ?? '0' };
 }
 const rateLimitSchema = z.object({ requests: z.number().int().positive(), windowSeconds: z.number().int().positive() }).strict();
 const nullableRateLimitSchema = rateLimitSchema.nullable();

package/dist/core/runtime/secrets.d.ts

@@ -0,0 +1,24 @@
+import { z } from 'zod';
+import type { CatencePaths } from '../../contracts/runtime.js';
+declare const secretSchema: z.ZodObject<{
+    garmin: z.ZodOptional<z.ZodObject<{
+        email: z.ZodOptional<z.ZodString>;
+        password: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    intervals: z.ZodOptional<z.ZodObject<{
+        apiKey: z.ZodOptional<z.ZodString>;
+        athleteId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    strava: z.ZodOptional<z.ZodObject<{
+        clientId: z.ZodOptional<z.ZodString>;
+        clientSecret: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type AthleteSecrets = z.infer<typeof secretSchema>;
+export type SecretProvider = keyof AthleteSecrets;
+export declare function providerSecretPath(paths: CatencePaths): string;
+export declare function readAthleteSecrets(paths: CatencePaths): Promise<AthleteSecrets>;
+export declare function setAthleteSecret(paths: CatencePaths, provider: SecretProvider, field: string, value: string): Promise<void>;
+/** Build only the provider environment needed by a selected athlete worker. */
+export declare function athleteProviderEnvironment(paths: CatencePaths, base?: NodeJS.ProcessEnv): Promise<NodeJS.ProcessEnv>;
+export {};

package/dist/core/runtime/secrets.js

@@ -0,0 +1,68 @@
+import { chmod } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { ensurePaths } from './configuration.js';
+const secretSchema = z.object({
+    garmin: z.object({ email: z.string().min(1).optional(), password: z.string().min(1).optional() }).strict().optional(),
+    intervals: z.object({ apiKey: z.string().min(1).optional(), athleteId: z.string().min(1).optional() }).strict().optional(),
+    strava: z.object({ clientId: z.string().min(1).optional(), clientSecret: z.string().min(1).optional() }).strict().optional(),
+}).strict();
+const secretFields = {
+    garmin: ['email', 'password'],
+    intervals: ['apiKey', 'athleteId'],
+    strava: ['clientId', 'clientSecret'],
+};
+export function providerSecretPath(paths) {
+    return path.join(paths.secrets, 'providers.json');
+}
+export async function readAthleteSecrets(paths) {
+    const { readFile } = await import('node:fs/promises');
+    const contents = await readFile(providerSecretPath(paths), 'utf8').catch((error) => error.code === 'ENOENT' ? '{}' : Promise.reject(error));
+    try {
+        return secretSchema.parse(JSON.parse(contents));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid provider secrets at ${providerSecretPath(paths)}: ${message}`);
+    }
+}
+export async function setAthleteSecret(paths, provider, field, value) {
+    if (!secretFields[provider].includes(field))
+        throw new Error(`${field} is not a supported ${provider} secret field.`);
+    if (!value.trim())
+        throw new Error('Secret values cannot be empty.');
+    await ensurePaths(paths);
+    const secrets = await readAthleteSecrets(paths);
+    const next = { ...secrets, [provider]: { ...(secrets[provider] ?? {}), [field]: value } };
+    const { writeFile, rename } = await import('node:fs/promises');
+    const destination = providerSecretPath(paths);
+    const temporary = `${destination}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(next, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    await chmod(temporary, 0o600);
+    await rename(temporary, destination);
+    await chmod(destination, 0o600);
+}
+/** Build only the provider environment needed by a selected athlete worker. */
+export async function athleteProviderEnvironment(paths, base = process.env) {
+    const secrets = await readAthleteSecrets(paths);
+    const environment = { ...base };
+    // Never let credentials inherited by the shared process leak into an
+    // athlete store that has not explicitly configured that provider.
+    for (const name of ['GARMIN_EMAIL', 'GARMIN_PASSWORD', 'INTERVALS_API_KEY', 'INTERVALS_ATHLETE_ID', 'STRAVA_CLIENT_ID', 'STRAVA_CLIENT_SECRET']) {
+        delete environment[name];
+    }
+    if (secrets.garmin?.email)
+        environment.GARMIN_EMAIL = secrets.garmin.email;
+    if (secrets.garmin?.password)
+        environment.GARMIN_PASSWORD = secrets.garmin.password;
+    if (secrets.intervals?.apiKey)
+        environment.INTERVALS_API_KEY = secrets.intervals.apiKey;
+    if (secrets.intervals?.athleteId)
+        environment.INTERVALS_ATHLETE_ID = secrets.intervals.athleteId;
+    if (secrets.strava?.clientId)
+        environment.STRAVA_CLIENT_ID = secrets.strava.clientId;
+    if (secrets.strava?.clientSecret)
+        environment.STRAVA_CLIENT_SECRET = secrets.strava.clientSecret;
+    return environment;
+}
+//# sourceMappingURL=secrets.js.map

package/dist/elt/application/management.js

@@ -8,6 +8,7 @@ import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { buildRetrievalIndex } from '../../core/retrieval/index.js';
 import { defaultFromDate, ensurePaths, requireIntervalsConfig } from '../../core/runtime/configuration.js';
+import { athleteProviderEnvironment } from '../../core/runtime/secrets.js';
 import { importJsonl } from '../ingestion/importer.js';
 import { IntervalsExtractor } from '../ingestion/providers/intervals.js';
 import { completeStravaAuthorization, disconnectStrava, getStravaAuthorizationUrl, syncStravaGear } from '../ingestion/providers/strava/service.js';
@@ -45,7 +46,8 @@ async function syncProvider(database, paths, provider, options) {
     let extractionStarted = false;
     try {
         if (provider === 'intervals') {
-            const config = requireIntervalsConfig();
+            const environment = await athleteProviderEnvironment(paths);
+            const config = requireIntervalsConfig(environment);
             extractionStarted = true;
             await new IntervalsExtractor(database, paths, config.apiKey, config.athleteId).sync(runId, activityWindow, !options.backfill || options.refreshActivities);
         }
@@ -71,7 +73,7 @@ async function syncProvider(database, paths, provider, options) {
                 arguments_.push('--historical-only');
             await execFileAsync('uv', arguments_, {
                 cwd: packageRoot(),
-                env: { ...process.env, UV_PROJECT_ENVIRONMENT: process.env.UV_PROJECT_ENVIRONMENT ?? path.join(paths.root, 'python-venv') },
+                env: { ...(await athleteProviderEnvironment(paths)), UV_PROJECT_ENVIRONMENT: process.env.UV_PROJECT_ENVIRONMENT ?? path.join(paths.root, 'python-venv') },
             });
             if (!existsSync(output))
                 throw new Error('Garmin staging worker completed without writing a JSONL manifest.');

package/dist/elt/ingestion/providers/strava/service.js

@@ -5,6 +5,7 @@ import path from 'node:path';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { ensurePaths, loadCatenceConfig } from '../../../../core/runtime/configuration.js';
+import { athleteProviderEnvironment } from '../../../../core/runtime/secrets.js';
 import { CatenceDatabase, openReadOnlyRepository } from '../../../storage/database.js';
 import { importJsonl } from '../../importer.js';
 import { withDataWriteLock } from '../../../storage/write-lock.js';
@@ -50,7 +51,7 @@ async function invokeWorker(paths, args, resultPath) {
     try {
         await execFileAsync('uv', ['run', 'python', '-m', 'python.catence.providers.strava.cli', ...args, '--data-dir', paths.root, '--result', resultPath], {
             cwd: packageRoot(),
-            env: { ...process.env, UV_PROJECT_ENVIRONMENT: process.env.UV_PROJECT_ENVIRONMENT ?? path.join(paths.root, 'python-venv') },
+            env: { ...(await athleteProviderEnvironment(paths)), UV_PROJECT_ENVIRONMENT: process.env.UV_PROJECT_ENVIRONMENT ?? path.join(paths.root, 'python-venv') },
         });
     }
     catch (error) {

package/dist/interfaces/cli/commands.js

@@ -1,33 +1,98 @@
 #!/usr/bin/env node
+import { createInterface } from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
 import { Command } from 'commander';
-import { connectStrava, connectStravaWithCallback, createDemoStore, dataStatus, disconnectStravaAccount, initializeDataStore, linkActivity, rebuildRetrievalIndex, resolvePaths, retryDataSync, syncData, unlinkActivity } from '../../runtime/index.js';
+import { addAthlete, athleteStorePaths, createDemoStore, dataStatus, defaultCatalogHome, disconnectStravaAccount, initializeCatalog, linkActivity, loadCatalog, rebuildRetrievalIndex, resolveAthlete, resolveCatalogPaths, retryDataSync, setAthleteSecret, syncData, connectStrava, connectStravaWithCallback, unlinkActivity, } from '../../runtime/index.js';
 const program = new Command()
     .name('catence-data')
-    .description('Local fitness data extraction, targeted enrichment, and normalization.')
-    .option('--data-dir <directory>', 'directory holding the local Catence database and artifacts', process.env.CATENCE_DATA_DIR ?? '.catence');
-function currentPaths() {
-    return resolvePaths(program.opts().dataDir);
+    .description('Athlete-scoped Catence data setup, extraction, and normalization.')
+    .option('--home <directory>', 'Catence catalog home directory', defaultCatalogHome())
+    .option('--athlete <id>', 'athlete ID for a data operation');
+function currentCatalog() {
+    return resolveCatalogPaths(program.opts().home);
 }
-function demoPaths() {
-    const dataDirWasProvided = process.argv.some((argument) => argument === '--data-dir' || argument.startsWith('--data-dir='));
-    const dataDir = dataDirWasProvided || process.env.CATENCE_DATA_DIR
-        ? program.opts().dataDir
-        : './catence-demo';
-    return resolvePaths(dataDir);
+async function currentAthlete() {
+    const athleteId = program.opts().athlete;
+    if (!athleteId)
+        throw new Error('--athlete is required for this command. Run catence-data athlete list to inspect the catalog.');
+    return resolveAthlete(currentCatalog(), athleteId);
 }
-program.command('init')
-    .description('Create an empty local data store without contacting a provider.')
-    .action(async () => {
-    process.stdout.write(`${JSON.stringify(await initializeDataStore(currentPaths()), null, 2)}\n`);
+async function prompt(question) {
+    if (!input.isTTY)
+        throw new Error(`Missing required setup value. Re-run with the matching option (${question}).`);
+    const terminal = createInterface({ input, output });
+    try {
+        return (await terminal.question(question)).trim();
+    }
+    finally {
+        terminal.close();
+    }
+}
+async function stdinSecret() {
+    const chunks = [];
+    for await (const chunk of input)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    const value = Buffer.concat(chunks).toString('utf8').replace(/\r?\n$/, '');
+    if (!value)
+        throw new Error('--value-stdin received an empty secret.');
+    return value;
+}
+program.command('setup')
+    .description('Create a home catalog and its first athlete store. Existing 0.1 stores must be re-synced.')
+    .option('--athlete <id>', 'first athlete ID')
+    .option('--label <label>', 'display label for the first athlete')
+    .action(async (options) => {
+    // Commander resolves the global --athlete option first when it appears
+    // after this subcommand, so accept either scope without making the setup
+    // command order-sensitive.
+    const athlete = options.athlete ?? program.opts().athlete ?? await prompt('First athlete ID (for example, alex): ');
+    const label = options.label ?? await prompt('First athlete display name: ');
+    const catalog = await initializeCatalog(currentCatalog(), { id: athlete, label });
+    process.stdout.write(`${JSON.stringify({ home: currentCatalog().root, catalog, message: 'Catence catalog is ready. Add provider values with catence-data secret set --athlete <id> --value-stdin, then run sync.' }, null, 2)}\n`);
+});
+const athleteCommand = program.command('athlete').description('Manage isolated athlete stores in this Catence catalog.');
+athleteCommand.command('list').action(async () => {
+    process.stdout.write(`${JSON.stringify(await loadCatalog(currentCatalog()), null, 2)}\n`);
+});
+athleteCommand.command('add')
+    .requiredOption('--id <id>', 'stable athlete ID')
+    .requiredOption('--label <label>', 'display label')
+    .option('--default', 'make this the default athlete for Console setup')
+    .action(async (options) => {
+    process.stdout.write(`${JSON.stringify(await addAthlete(currentCatalog(), { id: options.id, label: options.label, setDefault: options.default }), null, 2)}\n`);
+});
+const secretCommand = program.command('secret').description('Write a provider value into one athlete’s owner-only secret store.');
+secretCommand.command('set')
+    .requiredOption('--provider <provider>', 'garmin, intervals, or strava')
+    .requiredOption('--field <field>', 'provider secret field')
+    .requiredOption('--value-stdin', 'read the secret from stdin without putting it in shell history')
+    .action(async (options) => {
+    if (!['garmin', 'intervals', 'strava'].includes(options.provider))
+        throw new Error('--provider must be garmin, intervals, or strava.');
+    const { paths } = await currentAthlete();
+    await setAthleteSecret(paths, options.provider, options.field, await stdinSecret());
+    process.stdout.write(`${JSON.stringify({ athleteId: program.opts().athlete, provider: options.provider, field: options.field, stored: true }, null, 2)}\n`);
 });
 program.command('demo')
-    .description('Create a generated local demo store without contacting providers. Refuses to overwrite a non-demo data directory.')
+    .description('Create a generated demo athlete in an isolated demo catalog without contacting providers.')
     .option('--days <days>', 'generated days of wellness and training data', '90')
     .option('--seed <seed>', 'deterministic generator seed', '17')
     .action(async (options) => {
-    const days = Number(options.days);
-    const seed = Number(options.seed);
-    process.stdout.write(`${JSON.stringify(await createDemoStore(demoPaths(), { days, seed }), null, 2)}\n`);
+    const explicitHome = process.argv.some((argument) => argument === '--home' || argument.startsWith('--home='));
+    const demoCatalog = resolveCatalogPaths(explicitHome ? currentCatalog().root : `${defaultCatalogHome()}-demo`);
+    let catalog;
+    try {
+        catalog = await loadCatalog(demoCatalog);
+    }
+    catch {
+        catalog = await initializeCatalog(demoCatalog, { id: 'demo', label: 'Generated demo athlete' });
+    }
+    if (!catalog.athletes.some((athlete) => athlete.id === 'demo')) {
+        catalog = await addAthlete(demoCatalog, { id: 'demo', label: 'Generated demo athlete' });
+    }
+    const paths = athleteStorePaths(demoCatalog, 'demo');
+    const result = await createDemoStore(paths, { days: Number(options.days), seed: Number(options.seed) });
+    process.stdout.write(`${JSON.stringify({ ...result, home: demoCatalog.root, athleteId: 'demo' }, null, 2)}\n`);
 });
 program.command('sync')
     .requiredOption('--provider <provider>', 'intervals, garmin, strava, or all')
@@ -36,23 +101,26 @@ program.command('sync')
     .action(async (options) => {
     if (!['intervals', 'garmin', 'strava', 'all'].includes(options.provider))
         throw new Error('--provider must be intervals, garmin, strava, or all.');
-    process.stdout.write(`${JSON.stringify(await syncData(currentPaths(), options.provider, options.from, true, options.refresh ?? false), null, 2)}\n`);
+    const { paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await syncData(paths, options.provider, options.from, true, options.refresh ?? false), null, 2)}\n`);
 });
 program.command('backfill')
     .requiredOption('--from <date>', 'ISO date at which to begin backfill')
     .option('--provider <provider>', 'intervals, garmin, strava, or all', 'all')
-    .option('--refresh', 're-fetch and upsert data already covered by the requested range (including Garmin activity details, files, and streams)')
+    .option('--refresh', 're-fetch and upsert data already covered by the requested range')
     .action(async (options) => {
     if (!['intervals', 'garmin', 'strava', 'all'].includes(options.provider))
         throw new Error('--provider must be intervals, garmin, strava, or all.');
-    process.stdout.write(`${JSON.stringify(await syncData(currentPaths(), options.provider, options.from, false, options.refresh ?? false, true), null, 2)}\n`);
+    const { paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await syncData(paths, options.provider, options.from, false, options.refresh ?? false, true), null, 2)}\n`);
 });
 program.command('retry')
     .requiredOption('--run <run-id>', 'failed run to retry')
     .action(async (options) => {
-    process.stdout.write(`${JSON.stringify(await retryDataSync(currentPaths(), options.run), null, 2)}\n`);
+    const { paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await retryDataSync(paths, options.run), null, 2)}\n`);
 });
-program.command('auth').description('Connect a source account without storing credentials in DuckDB.')
+program.command('auth').description('Connect a source account using one athlete’s local credentials.')
     .command('strava')
     .option('--code <authorization-code>', 'OAuth authorization code returned by Strava')
     .option('--redirect-uri <uri>', 'OAuth redirect URI; defaults depend on the selected flow')
@@ -64,38 +132,35 @@ program.command('auth').description('Connect a source account without storing cr
     const timeoutSeconds = Number(options.timeoutSeconds);
     if (!Number.isInteger(timeoutSeconds) || timeoutSeconds < 1 || timeoutSeconds > 900)
         throw new Error('--timeout-seconds must be an integer between 1 and 900.');
+    const { paths } = await currentAthlete();
     const redirectUri = options.redirectUri ?? (options.callback ? 'http://127.0.0.1:8765/strava/callback' : 'http://localhost');
     const result = options.callback
-        ? await connectStravaWithCallback(currentPaths(), redirectUri, (url) => {
-            process.stderr.write(`Open this URL in your browser to connect Strava:\n${url}\nWaiting for the local callback…\n`);
-        }, timeoutSeconds * 1_000)
-        : await connectStrava(currentPaths(), options.code, redirectUri);
-    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+        ? await connectStravaWithCallback(paths, redirectUri, (url) => process.stderr.write(`Open this URL in your browser to connect Strava:\n${url}\nWaiting for the local callback…\n`), timeoutSeconds * 1_000)
+        : await connectStrava(paths, options.code, redirectUri);
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
 });
-program.command('disconnect').description('Remove locally stored credentials for a source account.')
+program.command('disconnect').description('Remove one athlete’s stored provider connection.')
     .command('strava')
     .action(async () => {
-    process.stdout.write(JSON.stringify(await disconnectStravaAccount(currentPaths()), null, 2) + "\n");
+    const { paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await disconnectStravaAccount(paths), null, 2)}\n`);
 });
-const activityCommand = program.command('activity').description('Audit and correct logical activity links.');
-activityCommand.command('link')
-    .requiredOption('--source <activity-source-id>')
-    .requiredOption('--activity <activity-id>')
-    .action(async (options) => {
-    process.stdout.write(JSON.stringify(await linkActivity(currentPaths(), options.source, options.activity), null, 2) + "\n");
+const activityCommand = program.command('activity').description('Audit and correct logical activity links for one athlete.');
+activityCommand.command('link').requiredOption('--source <activity-source-id>').requiredOption('--activity <activity-id>').action(async (options) => {
+    const { paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await linkActivity(paths, options.source, options.activity), null, 2)}\n`);
 });
-activityCommand.command('unlink')
-    .requiredOption('--source <activity-source-id>')
-    .action(async (options) => {
-    process.stdout.write(JSON.stringify(await unlinkActivity(currentPaths(), options.source), null, 2) + "\n");
+activityCommand.command('unlink').requiredOption('--source <activity-source-id>').action(async (options) => {
+    const { paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await unlinkActivity(paths, options.source), null, 2)}\n`);
 });
 program.command('status').action(async () => {
-    process.stdout.write(`${JSON.stringify(await dataStatus(currentPaths()), null, 2)}\n`);
+    const { paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await dataStatus(paths), null, 2)}\n`);
 });
-program.command('build-retrieval-index')
-    .description('Build the derived local text-retrieval index after a completed sync.')
-    .action(async () => {
-    process.stdout.write(`${JSON.stringify(await rebuildRetrievalIndex(currentPaths()), null, 2)}\n`);
+program.command('build-retrieval-index').description('Build derived local retrieval context for one athlete.').action(async () => {
+    const { paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await rebuildRetrievalIndex(paths), null, 2)}\n`);
 });
 await program.parseAsync();
 //# sourceMappingURL=commands.js.map

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

@@ -1,9 +1,9 @@
 export type ServeCliOptions = {
-    dataDir?: string;
+    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  --data-dir <directory>     Catence data directory. Overrides CATENCE_DATA_DIR.\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 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

@@ -3,7 +3,7 @@ export const SERVE_USAGE = `Usage: catence serve [options]
 Run Catence as a local Streamable HTTP MCP server.
 
 Options:
-  --data-dir <directory>     Catence data directory. Overrides CATENCE_DATA_DIR.
+  --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.
@@ -23,23 +23,23 @@ function parsePort(value) {
     return port;
 }
 export function parseServeCliOptions(arguments_) {
-    let dataDir;
+    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 { dataDir, host, port, allowedOrigins, help: true };
-        if (argument === '--data-dir') {
-            dataDir = requiredValue(arguments_, index, '--data-dir');
+            return { home, host, port, allowedOrigins, help: true };
+        if (argument === '--home') {
+            home = requiredValue(arguments_, index, '--home');
             index++;
             continue;
         }
-        if (argument.startsWith('--data-dir=')) {
-            dataDir = argument.slice('--data-dir='.length);
-            if (!dataDir)
-                throw new Error('--data-dir requires a value.');
+        if (argument.startsWith('--home=')) {
+            home = argument.slice('--home='.length);
+            if (!home)
+                throw new Error('--home requires a value.');
             continue;
         }
         if (argument === '--host') {
@@ -76,6 +76,6 @@ export function parseServeCliOptions(arguments_) {
         }
         throw new Error(`Unknown option: ${argument}`);
     }
-    return { dataDir, host, port, allowedOrigins, help: false };
+    return { home, host, port, allowedOrigins, help: false };
 }
 //# sourceMappingURL=cli-options.js.map

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

@@ -1,6 +1,9 @@
 import { type Server } from 'node:http';
-import { type CatencePaths } from '../../runtime/index.js';
+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[];
 };

package/dist/interfaces/http/server.js

@@ -1,6 +1,6 @@
 import { createServer } from 'node:http';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
-import { catenceRuntimeHealth, DashboardSnapshotService, jsonSafe, openReadOnlyRepository, resolvePaths } from '../../runtime/index.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) {
@@ -74,6 +74,17 @@ async function dashboardSnapshot(paths, url) {
         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);
@@ -129,7 +140,8 @@ async function handleMcpRequest(request, response, paths) {
  * process-wide MCP session state or a second query implementation.
  */
 export function createCatenceHttpServer(options = {}) {
-    const paths = options.paths ?? resolvePaths();
+    const catalogPaths = options.catalogPaths ?? (options.paths ? null : resolveCatalogPaths());
+    const staticPaths = options.paths ?? null;
     const allowedOrigins = options.allowedOrigins ?? [];
     return createServer((request, response) => {
         void (async () => {
@@ -146,9 +158,24 @@ export function createCatenceHttpServer(options = {}) {
                 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 {
-                    json(response, 200, await dashboardSnapshot(paths, new URL(request.url ?? '/', 'http://localhost')));
+                    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) } });
@@ -156,7 +183,7 @@ export function createCatenceHttpServer(options = {}) {
                 return;
             }
             if (pathname === '/mcp') {
-                await handleMcpRequest(request, response, paths);
+                await handleMcpRequest(request, response, catalogPaths ?? staticPaths ?? resolveCatalogPaths());
                 return;
             }
             json(response, 404, { error: { code: 'not_found', message: 'No Catence endpoint matches this request.' } });