catence 0.1.0 → 0.2.0-beta.10

package/dist/elt/storage/database.d.ts

@@ -2,6 +2,7 @@ import { ReadOnlyRepository } from '../../core/query/repository.js';
 import type { CatencePaths } from '../../contracts/runtime.js';
 import type { QueryBindings, WriteDataStore } from '../../contracts/storage.js';
 import type { Provider } from '../../contracts/staging.js';
+import { type InterruptedRuns, type SyncProgressSnapshot, type SyncProgressState } from '../../contracts/progress.js';
 export declare class CatenceDatabase implements WriteDataStore {
     private readonly instance;
     private readonly connection;
@@ -16,6 +17,10 @@ export declare class CatenceDatabase implements WriteDataStore {
     interrupt(): void;
     beginRun(provider: Provider, fromDate: string, runId?: `${string}-${string}-${string}-${string}-${string}`): Promise<string>;
     finishRun(runId: string): Promise<void>;
+    heartbeatRun(runId: string, progress: SyncProgressState): Promise<void>;
+    markRunInterrupted(runId: string, stage?: string): Promise<void>;
+    interruptStaleSyncRuns(timeoutMs?: number): Promise<InterruptedRuns>;
+    syncProgress(): Promise<SyncProgressSnapshot>;
     addError(runId: string, provider: Provider, endpoint: string, remoteId: string | null, message: string, retryable: boolean): Promise<void>;
     status(): Promise<Record<string, unknown>>;
     getRun(runId: string): Promise<{
@@ -66,9 +71,9 @@ export declare class ReadOnlyCatenceDatabase {
     interrupt(): void;
     private withConnection;
 }
-/** Compose core read services with the DuckDB-backed, read-only adapter. */
-export declare function openReadOnlyRepository(paths: CatencePaths): Promise<ReadOnlyRepository>;
 export declare class ReadOnlyDatabaseError extends Error {
     readonly code: 'data_sync_in_progress' | 'data_unavailable';
     constructor(code: 'data_sync_in_progress' | 'data_unavailable', message: string);
 }
+/** Compose core read services with the DuckDB-backed, read-only adapter. */
+export declare function openReadOnlyRepository(paths: CatencePaths): Promise<ReadOnlyRepository>;

package/dist/elt/storage/database.js

@@ -2,6 +2,7 @@ import { DuckDBInstance } from '@duckdb/node-api';
 import { randomUUID } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { ReadOnlyRepository } from '../../core/query/repository.js';
+import { SYNC_STAGES, STALE_RUN_TIMEOUT_MS } from '../../contracts/progress.js';
 import { migrations } from './migrations.js';
 import { json } from './sql.js';
 export class CatenceDatabase {
@@ -81,6 +82,66 @@ export class CatenceDatabase {
         await this.run(`UPDATE sync_runs SET status = CASE WHEN error_count > 0 THEN 'completed_with_errors' ELSE 'completed' END, completed_at = now() WHERE run_id = $runId`, { runId });
         await this.run("UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context'");
     }
+    async heartbeatRun(runId, progress) {
+        await this.run(`INSERT INTO sync_run_progress (run_id, provider, stage, current_step, completed_units, total_units, percent, elapsed_seconds, estimated_remaining_seconds, heartbeat_at, detail_json)
+       VALUES ($runId, $provider, $stage, $currentStep, $completedUnits, $totalUnits, $percent, $elapsedSeconds, $estimatedRemainingSeconds, now(), '{}')
+       ON CONFLICT (run_id) DO UPDATE SET
+         provider = EXCLUDED.provider,
+         stage = EXCLUDED.stage,
+         current_step = EXCLUDED.current_step,
+         completed_units = EXCLUDED.completed_units,
+         total_units = EXCLUDED.total_units,
+         percent = EXCLUDED.percent,
+         elapsed_seconds = EXCLUDED.elapsed_seconds,
+         estimated_remaining_seconds = EXCLUDED.estimated_remaining_seconds,
+         heartbeat_at = now(),
+         detail_json = '{}'`, {
+            runId,
+            provider: progress.provider,
+            stage: progress.stage,
+            currentStep: progress.currentStep,
+            completedUnits: progress.completedUnits,
+            totalUnits: progress.totalUnits,
+            percent: progress.percentComplete,
+            elapsedSeconds: progress.elapsedSeconds,
+            estimatedRemainingSeconds: progress.estimatedRemainingSeconds,
+        });
+    }
+    async markRunInterrupted(runId, stage = 'interrupted') {
+        await this.run("UPDATE sync_runs SET status = 'interrupted', completed_at = now() WHERE run_id = $runId AND status = 'running'", { runId });
+        await this.run('UPDATE sync_run_progress SET stage = $stage, heartbeat_at = now() WHERE run_id = $runId', { runId, stage });
+    }
+    async interruptStaleSyncRuns(timeoutMs = STALE_RUN_TIMEOUT_MS) {
+        const cutoff = new Date(Date.now() - timeoutMs).toISOString();
+        const stale = await this.rows(`SELECT run_id FROM sync_runs WHERE status = 'running' AND started_at < $cutoff`, { cutoff });
+        for (const row of stale) {
+            await this.run("UPDATE sync_runs SET status = 'timed_out', completed_at = now() WHERE run_id = $runId AND status = 'running'", { runId: row.run_id });
+            await this.run("UPDATE sync_run_progress SET stage = 'timed_out', heartbeat_at = now() WHERE run_id = $runId", { runId: row.run_id });
+        }
+        return { runIds: stale.map((row) => row.run_id) };
+    }
+    async syncProgress() {
+        const running = await this.rows(`SELECT runs.run_id, runs.provider,
+         coalesce(progress.stage, 'starting') AS stage,
+         progress.current_step AS current_step,
+         coalesce(progress.completed_units, 0) AS completed_units,
+         progress.total_units AS total_units,
+         coalesce(progress.percent, 0) AS percent,
+         coalesce(progress.elapsed_seconds, 0) AS elapsed_seconds,
+         progress.estimated_remaining_seconds AS estimated_remaining_seconds,
+         cast(coalesce(progress.heartbeat_at, runs.started_at) AS VARCHAR) AS heartbeat_at
+       FROM sync_runs AS runs
+       LEFT JOIN sync_run_progress AS progress USING (run_id)
+       WHERE runs.status = 'running'
+       ORDER BY runs.started_at DESC`);
+        const recent = await this.rows(`SELECT progress.run_id, progress.provider, progress.stage, progress.current_step,
+         progress.completed_units, progress.total_units, progress.percent, progress.elapsed_seconds,
+         progress.estimated_remaining_seconds, cast(progress.heartbeat_at AS VARCHAR) AS heartbeat_at
+       FROM sync_run_progress AS progress
+       ORDER BY progress.heartbeat_at DESC
+       LIMIT 10`);
+        return { running: running.map(toSyncProgressState), recent: recent.map(toSyncProgressState) };
+    }
     async addError(runId, provider, endpoint, remoteId, message, retryable) {
         await this.run(`INSERT INTO normalization_errors (error_id, run_id, provider, endpoint, remote_id, message, retryable)
        VALUES ($errorId, $runId, $provider, $endpoint, $remoteId, $message, $retryable)`, { errorId: randomUUID(), runId, provider, endpoint, remoteId, message, retryable });
@@ -94,9 +155,11 @@ export class CatenceDatabase {
         const rawObjects = await this.rows('SELECT count(*)::INTEGER AS count FROM raw_objects');
         const activities = await this.rows('SELECT count(*)::INTEGER AS count FROM activities');
         const streams = await this.rows('SELECT count(*)::INTEGER AS count FROM stream_manifest');
+        const errorDetails = await this.rows('SELECT run_id, provider, endpoint, remote_id, message, cast(created_at AS VARCHAR) AS created_at FROM normalization_errors WHERE resolved_at IS NULL ORDER BY created_at DESC LIMIT 100');
         const cursors = await this.rows('SELECT provider, cursor_name, cast(covered_through_date AS VARCHAR) AS covered_through_date, cast(latest_source_date AS VARCHAR) AS latest_source_date, lookback_days, last_successful_run_id, cast(last_completed_at AS VARCHAR) AS last_completed_at, status FROM sync_cursors ORDER BY provider, cursor_name');
         return {
             runs, unresolvedErrors: errors[0]?.count ?? 0, rawObjects: rawObjects[0]?.count ?? 0, activities: activities[0]?.count ?? 0, streams: streams[0]?.count ?? 0,
+            errors: errorDetails,
             cursors: cursors.map((cursor) => ({ ...cursor, next_from_date: subtractDays(cursor.covered_through_date, Number(cursor.lookback_days)) })),
         };
     }
@@ -281,10 +344,6 @@ export class ReadOnlyCatenceDatabase {
         }
     }
 }
-/** Compose core read services with the DuckDB-backed, read-only adapter. */
-export async function openReadOnlyRepository(paths) {
-    return new ReadOnlyRepository(await ReadOnlyCatenceDatabase.open(paths), paths);
-}
 export class ReadOnlyDatabaseError extends Error {
     code;
     constructor(code, message) {
@@ -293,4 +352,22 @@ export class ReadOnlyDatabaseError extends Error {
         this.name = 'ReadOnlyDatabaseError';
     }
 }
+/** Compose core read services with the DuckDB-backed, read-only adapter. */
+export async function openReadOnlyRepository(paths) {
+    return new ReadOnlyRepository(await ReadOnlyCatenceDatabase.open(paths), paths);
+}
+function toSyncProgressState(row) {
+    return {
+        runId: row.run_id,
+        provider: row.provider,
+        stage: SYNC_STAGES.includes(row.stage) ? row.stage : 'starting',
+        currentStep: row.current_step,
+        completedUnits: Math.max(0, Number(row.completed_units) || 0),
+        totalUnits: row.total_units === null || row.total_units === undefined ? null : Math.max(0, Number(row.total_units) || 0),
+        percentComplete: Math.min(100, Math.max(0, Number(row.percent) || 0)),
+        elapsedSeconds: Math.max(0, Number(row.elapsed_seconds) || 0),
+        estimatedRemainingSeconds: row.estimated_remaining_seconds === null || row.estimated_remaining_seconds === undefined ? null : Math.max(0, Number(row.estimated_remaining_seconds) || 0),
+        heartbeatAt: row.heartbeat_at,
+    };
+}
 //# sourceMappingURL=database.js.map

package/dist/elt/storage/migrations.js

@@ -828,5 +828,29 @@ const swimFactsAndQualityMigration = {
     UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
   `,
 };
-export const migrations = [...baseMigrations, stravaAndIdentityMigration, garminPrimaryAndTrainingMetricsMigration, garminActivitySportAndFtpBackfillMigration, garminPrimaryDailyHealthMigration, garminHistoricalMetricsAndStreamsMigration, garminUtcActivityTimestampMigration, garminLactateThresholdMetricsMigration, swimFactsAndQualityMigration];
+const syncRunProgressMigration = {
+    version: 14,
+    name: 'sync_run_progress_heartbeats',
+    sql: `
+    -- Live progress heartbeats for in-flight sync runs. Written by the Node
+    -- side from progress records streamed by provider workers; read-only
+    -- surfaces (status, progress CLI, MCP) join against sync_runs.
+    CREATE TABLE IF NOT EXISTS sync_run_progress (
+      run_id VARCHAR PRIMARY KEY,
+      provider VARCHAR NOT NULL,
+      stage VARCHAR NOT NULL,
+      current_step VARCHAR,
+      completed_units INTEGER NOT NULL DEFAULT 0,
+      total_units INTEGER,
+      percent DOUBLE NOT NULL DEFAULT 0,
+      elapsed_seconds DOUBLE NOT NULL DEFAULT 0,
+      estimated_remaining_seconds DOUBLE,
+      heartbeat_at TIMESTAMPTZ NOT NULL,
+      detail_json JSON NOT NULL DEFAULT '{}'
+    );
+
+    UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
+  `,
+};
+export const migrations = [...baseMigrations, stravaAndIdentityMigration, garminPrimaryAndTrainingMetricsMigration, garminActivitySportAndFtpBackfillMigration, garminPrimaryDailyHealthMigration, garminHistoricalMetricsAndStreamsMigration, garminUtcActivityTimestampMigration, garminLactateThresholdMetricsMigration, swimFactsAndQualityMigration, syncRunProgressMigration];
 //# sourceMappingURL=migrations.js.map

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, CATENCE_RUNTIME_VERSION, channelForVersion, createDemoStore, dataStatus, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, initializeCatalog, isGlobalNpmInstall, linkActivity, loadCatalog, npmGlobalPrefix, planSelfUpdate, readInstalledConsoleVersion, rebuildRetrievalIndex, resolveAthlete, resolveCatalogPaths, retryDataSync, runSelfUpdateCommand, setAthleteSecret, syncData, syncProgress, 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,125 @@ 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`);
+function renderProgress(snapshot) {
+    const lines = snapshot.running.map((run) => {
+        const pct = run.percentComplete.toFixed(1).padStart(5);
+        const units = run.totalUnits !== null ? `${run.completedUnits}/${run.totalUnits}` : String(run.completedUnits);
+        const eta = run.estimatedRemainingSeconds !== null ? `${Math.round(run.estimatedRemainingSeconds)}s` : '?';
+        const step = run.currentStep ?? '';
+        return `${pct}%  ${run.stage.padEnd(12)} ${units.padEnd(11)} ${eta.padEnd(6)} ${step}`;
+    });
+    return lines.length === 0 ? 'no active sync runs' : lines.join('\n');
+}
+program.command('progress')
+    .description('Show live progress for active sync runs.')
+    .option('--watch', 'refresh every few seconds until no sync runs are active')
+    .action(async (options) => {
+    const { paths } = await currentAthlete();
+    if (!options.watch) {
+        process.stdout.write(`${JSON.stringify(await syncProgress(paths), null, 2)}\n`);
+        return;
+    }
+    while (true) {
+        const snapshot = await syncProgress(paths);
+        if (output.isTTY) {
+            output.write(`\x1b[2J\x1b[H${renderProgress(snapshot)}\n`);
+        }
+        else {
+            process.stdout.write(`${JSON.stringify(snapshot, null, 2)}\n`);
+        }
+        if (snapshot.running.length === 0)
+            break;
+        await new Promise((resolve) => setTimeout(resolve, 3000));
+    }
+});
+program.command('update')
+    .description('Check for and apply the newest Catence release on the tracked channel (runtime and Console).')
+    .option('--check', 'report available releases without changing anything')
+    .option('--channel <stable|beta>', 'release channel to track; defaults to the installed runtime channel')
+    .option('--runtime', 'only check or update the Catence runtime package')
+    .option('--console', 'only check or update the Catence Console package')
+    .action(async (options) => {
+    if (options.channel !== undefined && options.channel !== 'stable' && options.channel !== 'beta') {
+        throw new Error('--channel must be stable or beta.');
+    }
+    const channel = options.channel ?? channelForVersion(CATENCE_RUNTIME_VERSION);
+    const runtimeOnly = options.runtime ?? false;
+    const consoleOnly = options.console ?? false;
+    const updateRuntime = runtimeOnly || !consoleOnly;
+    const updateConsole = consoleOnly || !runtimeOnly;
+    const [npmDistTags, pypiReleases, consoleInstalled] = await Promise.all([
+        fetchNpmDistTags('catence'),
+        fetchPypiReleases('catence-console'),
+        readInstalledConsoleVersion(),
+    ]);
+    const plan = planSelfUpdate({ runtimeVersion: CATENCE_RUNTIME_VERSION, channel, npmDistTags, pypiReleases, consoleInstalled });
+    const report = { channel, runtime: plan.runtime, console: plan.console };
+    if (options.check) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        process.exit(plan.ok ? 0 : 1);
+    }
+    const applied = [];
+    if (plan.runtime.updateAvailable && updateRuntime) {
+        const runtimeTarget = plan.runtime.target;
+        if (runtimeTarget === undefined)
+            throw new Error('No runtime update target is available.');
+        const npmPrefix = await npmGlobalPrefix();
+        if (isGlobalNpmInstall(import.meta.url, npmPrefix)) {
+            const exitCode = await runSelfUpdateCommand('npm', ['install', '--global', `catence@${runtimeTarget}`]);
+            if (exitCode !== 0)
+                throw new Error(`npm failed to install catence@${runtimeTarget} (exit ${exitCode}).`);
+            applied.push(`runtime: catence@${runtimeTarget}`);
+        }
+        else {
+            process.stderr.write(`Runtime is not a global npm install; run: npm install --global catence@${runtimeTarget}\n`);
+        }
+    }
+    if (plan.console.updateAvailable && updateConsole) {
+        const consoleTarget = plan.console.target;
+        if (consoleTarget === undefined)
+            throw new Error('No Console update target is available.');
+        if (await hasCommand('uv')) {
+            const exitCode = await runSelfUpdateCommand('uv', ['tool', 'install', '--upgrade', `catence-console==${consoleTarget}`]);
+            if (exitCode !== 0)
+                throw new Error(`uv failed to install catence-console==${consoleTarget} (exit ${exitCode}).`);
+            applied.push(`console: catence-console==${consoleTarget}`);
+        }
+        else {
+            process.stderr.write(`uv is not installed; run: pip install --upgrade 'catence-console==${consoleTarget}'\n`);
+        }
+    }
+    process.stdout.write(`${JSON.stringify({ ...report, applied }, 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.' } });