catence 0.2.1-beta.2 → 0.2.1-beta.21

package/dist/elt/ingestion/providers/intervals.js

@@ -243,14 +243,33 @@ export class IntervalsExtractor {
             }
         }
     }
+    /**
+     * Intervals.icu enforces 2500 requests per rolling 15 minutes and 5000 per
+     * day; over-limit calls answer 429 with a Retry-After header. Back off
+     * cooperatively and retry a bounded number of times so one auto-sync run
+     * degrades instead of recording a wall of retryable errors.
+     */
+    async request(route, accept) {
+        for (let attempt = 0;; attempt++) {
+            const headers = { Authorization: basicAuth(this.apiKey) };
+            if (accept)
+                headers.Accept = accept;
+            const response = await fetch(`${apiBaseUrl}${route}`, { headers });
+            if (response.status !== 429 || attempt >= 2)
+                return response;
+            const retryAfterSeconds = Math.min(Math.max(Number(response.headers.get('retry-after')) || 30, 1), 300);
+            this.log.warn('Intervals rate limit hit; backing off', { route, retryAfterSeconds, attempt: attempt + 1 });
+            await new Promise((resolve) => setTimeout(resolve, retryAfterSeconds * 1_000));
+        }
+    }
     async getJson(route) {
-        const response = await fetch(`${apiBaseUrl}${route}`, { headers: { Authorization: basicAuth(this.apiKey), Accept: 'application/json' } });
+        const response = await this.request(route, 'application/json');
         if (!response.ok)
             throw new Error(`Intervals ${route} failed with HTTP ${response.status}`);
         return response.json();
     }
     async getBinary(route) {
-        const response = await fetch(`${apiBaseUrl}${route}`, { headers: { Authorization: basicAuth(this.apiKey) } });
+        const response = await this.request(route, null);
         if (!response.ok)
             throw new Error(`Intervals ${route} failed with HTTP ${response.status}`);
         return new Uint8Array(await response.arrayBuffer());

package/dist/elt/normalization/normalizers.js

@@ -254,6 +254,7 @@ export async function importSourceEntity(database, entity) {
     if (entity.entityType === 'activity') {
         await importActivity(database, entity.provider, entity.remoteId, payload, rawHash);
         await importActivityDecoupling(database, entity.provider, entity.remoteId, payload, rawHash);
+        await importActivityRunDynamics(database, entity.provider, entity.remoteId, payload, rawHash);
         if (entity.provider === 'intervals')
             await importIntervalsAutoSwimSets(database, entity.remoteId, payload, rawHash);
         if (entity.provider === 'garmin') {
@@ -271,6 +272,8 @@ export async function importSourceEntity(database, entity) {
     }
     if (entity.entityType === 'wellness' || entity.entityType === 'daily_health')
         await importDailyMetrics(database, entity.provider, entity.remoteId, entity.occurredOn, payload, rawHash);
+    if (entity.provider === 'garmin' && entity.entityType === 'body_composition')
+        await importGarminWeight(database, entity.occurredOn, payload, rawHash);
     if (entity.entityType === 'nutrition_day' || entity.entityType === 'nutrition_log')
         await importNutrition(database, entity.provider, entity.occurredOn, entity.remoteId, payload, rawHash);
     if (entity.provider === 'garmin' && entity.entityType === 'training_metric')
@@ -567,6 +570,67 @@ async function importActivityDecoupling(database, provider, remoteId, payload, r
          unit = excluded.unit, source_type = excluded.source_type, caveats_json = excluded.caveats_json, raw_object_hash = excluded.raw_object_hash`, { provider, activitySourceId, sport: fields.sport, startedAtUtc: fields.startAtUtc, metric: spec.metric, value, unit: spec.unit, caveats: json({}), rawHash });
     }
 }
+/** Containers searched for provider-supplied run dynamics: the payload itself,
+ * the multisport summary object, common nested analysis/metrics objects, and
+ * the stored metrics_json. Single-activity Garmin payloads carry flat keys;
+ * multisport legs carry the same fields under summaryDTO. */
+function runDynamicsContainers(payload) {
+    const containers = [payload];
+    for (const key of ['summaryDTO', 'analysis', 'data', 'metrics', 'icuAnalysis', 'summaries']) {
+        const nested = payload[key];
+        if (nested !== null && typeof nested === 'object' && !Array.isArray(nested))
+            containers.push(nested);
+    }
+    const metricsJson = payload.metrics_json;
+    if (metricsJson !== undefined && metricsJson !== null)
+        containers.push(objectFromJson(metricsJson));
+    return containers;
+}
+const RUN_DYNAMICS_METRICS = [
+    { column: 'vertical_oscillation_cm', keys: ['avgVerticalOscillation', 'verticalOscillation'] },
+    { column: 'ground_contact_time_ms', keys: ['avgGctTime', 'groundContactTime', 'avgGroundContactTime'] },
+    { column: 'flight_time_ms', keys: ['avgFlightTime', 'flightTime'] },
+    { column: 'stride_length_cm', keys: ['avgStrideLength', 'strideLength'] },
+    { column: 'vertical_ratio_pct', keys: ['avgVerticalRatio', 'verticalRatio'] },
+    { column: 'cadence_spm', keys: ['averageRunningCadenceInStepsPerMinute', 'avgRunCadence', 'averageCadence'] },
+];
+function firstReportedNumber(containers, keys) {
+    for (const container of containers) {
+        const found = firstNumber(container, keys);
+        if (found !== null)
+            return found;
+    }
+    return null;
+}
+/** A5 (persistence): persist provider-supplied running form metrics (vertical
+ * oscillation, ground contact time, flight time, stride length, vertical ratio,
+ * running cadence) so they are queryable across activities instead of only
+ * inside one activity's raw metrics_json. A row is stored only when the payload
+ * reported at least one dynamics value; null columns in a stored row mean the
+ * provider did not report that metric. */
+async function importActivityRunDynamics(database, provider, remoteId, payload, rawHash) {
+    const containers = runDynamicsContainers(payload);
+    const reported = RUN_DYNAMICS_METRICS.map((spec) => firstReportedNumber(containers, spec.keys));
+    if (reported.every((value) => value === null))
+        return;
+    const values = Object.fromEntries(RUN_DYNAMICS_METRICS.map((spec, index) => [spec.column, reported[index]]));
+    const fields = activityFields(provider, payload);
+    await database.run(`INSERT INTO run_dynamics_facts
+      (provider, activity_source_id, sport, started_at_utc, vertical_oscillation_cm, ground_contact_time_ms, flight_time_ms, stride_length_cm, vertical_ratio_pct, cadence_spm, source_type, caveats_json, raw_object_hash)
+     VALUES ($provider, $activitySourceId, $sport, try_cast($startedAtUtc AS TIMESTAMPTZ), $verticalOscillation, $groundContactTime, $flightTime, $strideLength, $verticalRatio, $cadence, 'provider', $caveats, $rawHash)
+     ON CONFLICT (provider, activity_source_id) DO UPDATE SET
+       sport = excluded.sport, started_at_utc = excluded.started_at_utc,
+       vertical_oscillation_cm = excluded.vertical_oscillation_cm, ground_contact_time_ms = excluded.ground_contact_time_ms,
+       flight_time_ms = excluded.flight_time_ms, stride_length_cm = excluded.stride_length_cm,
+       vertical_ratio_pct = excluded.vertical_ratio_pct, cadence_spm = excluded.cadence_spm,
+       source_type = excluded.source_type, caveats_json = excluded.caveats_json, raw_object_hash = excluded.raw_object_hash`, {
+        provider, activitySourceId: providerActivityId(provider, remoteId), sport: fields.sport, startedAtUtc: fields.startAtUtc,
+        verticalOscillation: values.vertical_oscillation_cm, groundContactTime: values.ground_contact_time_ms,
+        flightTime: values.flight_time_ms, strideLength: values.stride_length_cm,
+        verticalRatio: values.vertical_ratio_pct, cadence: values.cadence_spm,
+        caveats: json({}), rawHash,
+    });
+}
 /** Pull a course's ordered geometry samples, tolerating the several shapes a
  * Garmin course payload may use (a flat ``geoPoints`` array on the live course
  * endpoint, legacy ``coursePoints``, or points nested under a geo/route object).
@@ -968,6 +1032,64 @@ async function importDailyMetrics(database, provider, remoteId, date, payload, r
     if (provider === 'garmin')
         await importGarminDailyDetails(database, remoteId, metricDate, payload, rawHash);
 }
+/**
+ * Weight-only projection for Garmin weigh-ins. The range endpoint returns
+ * `{dailyWeightSummaries: [{summaryDate, allWeightMetrics: [{weight, ...}]}]}`
+ * with weight in grams, while dayview returns `{dateWeightList: [...]}`.
+ * The worker stages a whole range window as one `body_composition` entity,
+ * so dates are derived per entry here. Multiple weigh-ins on one day resolve
+ * to the latest timestamp. Body-composition fields (fat, muscle, ...) are
+ * deliberately ignored.
+ */
+function weightKgFromValue(value) {
+    if (value === null)
+        return null;
+    return value > 1000 ? value / 1000 : value;
+}
+function weightEntryDate(entry, fallbackDay) {
+    // Prefer the parent summaryDate (Garmin's local day) over the entry's UTC
+    // timestampGMT, which can fall on a different UTC date.
+    return fallbackDay
+        ?? datePart(firstString(entry, ['summaryDate', 'calendarDate', 'date']))
+        ?? datePart(timestamp(entry.timestampGMT));
+}
+function collectGarminWeightEntries(payload, fallbackDay) {
+    const entries = [];
+    const pushEntry = (entry, fallback) => {
+        const kg = weightKgFromValue(firstNumber(entry, ['weight', 'weightValue', 'weightInKg']));
+        if (kg === null)
+            return;
+        const day = weightEntryDate(entry, fallback ?? fallbackDay);
+        if (!day)
+            return;
+        const ts = typeof entry.timestampGMT === 'number' && Number.isFinite(entry.timestampGMT) ? entry.timestampGMT : 0;
+        entries.push({ date: day, kg, ts });
+    };
+    for (const summary of objectArray(payload.dailyWeightSummaries)) {
+        const day = datePart(firstString(summary, ['summaryDate', 'calendarDate', 'date'])) ?? fallbackDay;
+        for (const metric of objectArray(summary.allWeightMetrics))
+            pushEntry(metric, day);
+    }
+    for (const key of ['dateWeightList', 'allWeightMetrics']) {
+        for (const entry of objectArray(payload[key]))
+            pushEntry(entry, fallbackDay);
+    }
+    if (firstNumber(payload, ['weight', 'weightValue', 'weightInKg']) !== null)
+        pushEntry(payload, fallbackDay);
+    return entries;
+}
+async function importGarminWeight(database, date, payload, rawHash) {
+    const fallbackDay = datePart(date);
+    const latestByDay = new Map();
+    for (const entry of collectGarminWeightEntries(payload, fallbackDay)) {
+        const current = latestByDay.get(entry.date);
+        if (!current || entry.ts >= current.ts)
+            latestByDay.set(entry.date, { kg: entry.kg, ts: entry.ts });
+    }
+    for (const [metricDate, { kg }] of latestByDay) {
+        await upsertDailyMetric(database, 'garmin', metricDate, 'weight_kg', kg, null, 'kg', rawHash);
+    }
+}
 async function importNutrition(database, provider, date, remoteId, payload, rawHash) {
     const nutritionDate = datePart(date) ?? datePart(firstString(payload, ['id', 'date', 'calendarDate'])) ?? null;
     if (!nutritionDate)

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

@@ -60,7 +60,12 @@ export declare class CatenceDatabase implements WriteDataStore {
     knownActivitySummaryHashes(provider: Provider): Promise<Record<string, string>>;
     hasGarminLactateThresholdHistory(): Promise<boolean>;
     earliestActivityStartDate(provider: Provider): Promise<string | null>;
-    garminSwimActivitySources(): Promise<Array<{
+    /**
+     * Swim activities that still lack per-length rows: the FIT backfill only
+     * has work to do for these, so syncs skip re-parsing already-derived
+     * archives entirely.
+     */
+    garminSwimActivitySourcesWithoutLengths(): Promise<Array<{
         remote_activity_id: string;
         started_on: string | null;
     }>>;

package/dist/elt/storage/database.js

@@ -319,13 +319,19 @@ export class CatenceDatabase {
          JOIN activity_sources source USING (activity_id) WHERE source.provider = $provider`, { provider });
         return toIsoDate(rows[0]?.earliest ?? null);
     }
-    async garminSwimActivitySources() {
+    /**
+     * Swim activities that still lack per-length rows: the FIT backfill only
+     * has work to do for these, so syncs skip re-parsing already-derived
+     * archives entirely.
+     */
+    async garminSwimActivitySourcesWithoutLengths() {
         const sports = ['lap_swimming', 'swimming', 'open_water_swimming', 'openwaterswimming'];
         return this.rows(`SELECT source.remote_activity_id, cast(activity.started_at_utc AS VARCHAR) AS started_on
          FROM activity_sources AS source
          JOIN activities AS activity USING (activity_id)
         WHERE source.provider = 'garmin'
           AND lower(coalesce(activity.sport, '')) IN (${sports.map((sport) => `'${sport}'`).join(', ')})
+          AND NOT EXISTS (SELECT 1 FROM swim_lengths WHERE swim_lengths.activity_source_id = source.activity_source_id)
         ORDER BY activity.started_at_utc`);
     }
     async latestSourceDate(provider, cursorName) {

package/dist/elt/storage/migrations.js

@@ -972,5 +972,49 @@ const activityDecouplingFactsMigration = {
     UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
   `,
 };
-export const migrations = [...baseMigrations, stravaAndIdentityMigration, garminPrimaryAndTrainingMetricsMigration, garminActivitySportAndFtpBackfillMigration, garminPrimaryDailyHealthMigration, garminHistoricalMetricsAndStreamsMigration, garminUtcActivityTimestampMigration, garminLactateThresholdMetricsMigration, swimFactsAndQualityMigration, syncRunProgressMigration, canonicalTrainingDerivedAvgPowerMigration, courseGeometryMigration, activityDecouplingFactsMigration];
+const runDynamicsFactsMigration = {
+    version: 18,
+    name: 'run_dynamics_facts',
+    sql: `
+    -- A5 (persistence): make provider-supplied running dynamics queryable
+    -- historically instead of only inside one activity's raw metrics_json.
+    -- Values are provider-normalized running form metrics; a null column means
+    -- the provider did not report that metric for the activity. Only activities
+    -- with at least one reported value get a row. Single activities carry the
+    -- fields flat; multisport legs carry them nested under summaryDTO, and the
+    -- normalizer searches both shapes. Rows are written by the activity
+    -- normalizer on import (matching activity_decoupling, with no SQL backfill),
+    -- so previously imported activities gain rows when their source entity is
+    -- refreshed or re-imported; the upsert is idempotent.
+    CREATE TABLE IF NOT EXISTS run_dynamics_facts (
+      provider VARCHAR NOT NULL,
+      activity_source_id VARCHAR NOT NULL,
+      sport VARCHAR,
+      started_at_utc TIMESTAMPTZ,
+      vertical_oscillation_cm DOUBLE,
+      ground_contact_time_ms DOUBLE,
+      flight_time_ms DOUBLE,
+      stride_length_cm DOUBLE,
+      vertical_ratio_pct DOUBLE,
+      cadence_spm DOUBLE,
+      source_type VARCHAR NOT NULL,
+      caveats_json JSON,
+      raw_object_hash VARCHAR,
+      PRIMARY KEY (provider, activity_source_id)
+    );
+
+    -- Join view so callers can filter or group by logical activity without
+    -- hand-joining activity_sources/activities. Every facts row is current by
+    -- construction (the primary key is the source row), so no ranking filter is
+    -- applied and provider rows are never hidden.
+    CREATE OR REPLACE VIEW run_dynamics AS
+    SELECT facts.*, source.activity_id, source.remote_activity_id, activity.name
+    FROM run_dynamics_facts AS facts
+    JOIN activity_sources AS source USING (activity_source_id)
+    JOIN activities AS activity USING (activity_id);
+
+    UPDATE retrieval_index_state SET status = 'stale' WHERE index_name = 'context';
+  `,
+};
+export const migrations = [...baseMigrations, stravaAndIdentityMigration, garminPrimaryAndTrainingMetricsMigration, garminActivitySportAndFtpBackfillMigration, garminPrimaryDailyHealthMigration, garminHistoricalMetricsAndStreamsMigration, garminUtcActivityTimestampMigration, garminLactateThresholdMetricsMigration, swimFactsAndQualityMigration, syncRunProgressMigration, canonicalTrainingDerivedAvgPowerMigration, courseGeometryMigration, activityDecouplingFactsMigration, runDynamicsFactsMigration];
 //# sourceMappingURL=migrations.js.map

package/dist/elt/storage/progress-sidecar.d.ts

@@ -48,7 +48,16 @@ export declare class ProgressPump {
     private lastHeartbeatAt;
     private interval;
     private stageOverride;
+    /**
+     * Serializes heartbeat writes in call order. publish() used to fire its
+     * database and sidecar writes without awaiting them, so a throttled write
+     * could win the sidecar rename race against a later publishFinal() and
+     * leave a stale non-terminal stage behind.
+     */
+    private writeTail;
     constructor(runId: string, provider: string, options: ProgressPumpOptions);
+    private enqueueHeartbeat;
+    private writeHeartbeat;
     start(): void;
     publish(state: SyncProgressState): void;
     /** Force subsequent keep-alive heartbeats to report the given stage. */

package/dist/elt/storage/progress-sidecar.js

@@ -133,11 +133,36 @@ export class ProgressPump {
     lastHeartbeatAt = 0;
     interval = null;
     stageOverride = null;
+    /**
+     * Serializes heartbeat writes in call order. publish() used to fire its
+     * database and sidecar writes without awaiting them, so a throttled write
+     * could win the sidecar rename race against a later publishFinal() and
+     * leave a stale non-terminal stage behind.
+     */
+    writeTail = Promise.resolve();
     constructor(runId, provider, options) {
         this.runId = runId;
         this.provider = provider;
         this.options = options;
     }
+    enqueueHeartbeat(state) {
+        const run = this.writeTail.then(() => this.writeHeartbeat(state));
+        // A write failure is already logged inside writeHeartbeat; never let it
+        // break the chain (or surface as an unhandled rejection) for later beats.
+        this.writeTail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async writeHeartbeat(state) {
+        const { database, paths, log } = this.options;
+        await Promise.all([
+            database.heartbeatRun(this.runId, state).catch((error) => {
+                log.debug('Progress heartbeat failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
+            }),
+            writeProgressSidecar(paths, this.runId, state).catch((error) => {
+                log.debug('Progress sidecar write failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
+            }),
+        ]);
+    }
     start() {
         if (this.interval)
             return;
@@ -156,13 +181,7 @@ export class ProgressPump {
         }
         this.lastHeartbeatAt = now;
         this.lastProgress = state;
-        const { database, paths, log } = this.options;
-        void database.heartbeatRun(this.runId, state).catch((error) => {
-            log.debug('Progress heartbeat failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
-        });
-        void writeProgressSidecar(paths, this.runId, state).catch((error) => {
-            log.debug('Progress sidecar write failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
-        });
+        void this.enqueueHeartbeat(state).catch(() => undefined);
     }
     /** Force subsequent keep-alive heartbeats to report the given stage. */
     setStage(stage) {
@@ -180,15 +199,11 @@ export class ProgressPump {
     async publishFinal(state) {
         this.lastHeartbeatAt = Date.now();
         this.lastProgress = state;
-        const { database, paths, log } = this.options;
-        // Both terminal writes complete before the caller removes the sidecar, so
-        // a finished run can never resurrect its own progress file after cleanup.
-        await database.heartbeatRun(this.runId, state).catch((error) => {
-            log.debug('Progress heartbeat failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
-        });
-        await writeProgressSidecar(paths, this.runId, state).catch((error) => {
-            log.debug('Progress sidecar write failed', { runId: this.runId, error: error instanceof Error ? error.message : String(error) });
-        });
+        // Awaiting the chained write guarantees every earlier heartbeat (in
+        // particular a throttled publish still in flight) lands first, so the
+        // terminal stage is always the last one persisted before the caller
+        // removes the sidecar.
+        await this.enqueueHeartbeat(state);
     }
     stop() {
         if (this.interval) {

package/dist/interfaces/cli/commands.js

@@ -2,7 +2,8 @@
 import { createInterface } from 'node:readline/promises';
 import { stdin as input, stdout as output } from 'node:process';
 import { Command } from 'commander';
-import { addAthlete, athleteStorePaths, CATENCE_RUNTIME_VERSION, CatenceDatabase, channelForVersion, createDemoStore, dataStatus, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, importStagedFile, initializeCatalog, isGlobalNpmInstall, linkActivity, loadCatalog, npmGlobalPrefix, planSelfUpdate, readInstalledConsoleVersion, rebuildRetrievalIndex, reimportNutrition, resolveExtractionErrors, resolveAthlete, resolveCatalogPaths, retryDataSync, runSelfUpdateCommand, setAthleteSecret, syncData, syncProgress, connectStrava, connectStravaWithCallback, unlinkActivity, } from '../../runtime/index.js';
+import { defaultBearerTokenPath, defaultMcpKeysPath, defaultOauthSettingsPath, disableBearerToken, ensureBearerToken, mcpExposureStatus, oauthStatusFromSettings, readBearerToken, } from '../http/cli-options.js';
+import { addAthlete, addMcpKey, athleteStorePaths, CATENCE_RUNTIME_VERSION, CatenceDatabase, channelForVersion, createDemoStore, dataStatus, deleteAthleteSecret, defaultCatalogHome, disconnectStravaAccount, fetchNpmDistTags, fetchPypiReleases, hasCommand, importStagedFile, initializeCatalog, isGlobalNpmInstall, linkActivity, listMcpKeys, loadCatalog, npmGlobalPrefix, parseAutoSyncInterval, planSelfUpdate, readAutoSyncSchedule, readInstalledConsoleVersion, rebuildRetrievalIndex, reimportNutrition, reimportWeight, resolveExtractionErrors, resolveAthlete, resolveCatalogPaths, retryDataSync, revokeMcpKey, rollMcpKey, runSelfUpdateCommand, setAthleteSecret, syncData, syncProgress, connectStrava, connectStravaWithCallback, unlinkActivity, updateAutoSyncSchedule, } from '../../runtime/index.js';
 const program = new Command()
     .name('catence-data')
     .description('Athlete-scoped Catence data setup, extraction, and normalization.')
@@ -37,6 +38,85 @@ async function stdinSecret() {
         throw new Error('--value-stdin received an empty secret.');
     return value;
 }
+const mcpCommand = program.command('mcp').description('Manage Streamable HTTP MCP exposure: the bearer-token gate, its token, per-account keys, and endpoint URLs.');
+const mcpLocalEndpoint = () => `http://127.0.0.1:${process.env.CATENCE_HTTP_PORT ?? '8787'}`;
+// The keys registry resolves like the serve option: --file, then the
+// environment, then the catalog home default.
+const mcpKeysFile = (file) => file ?? process.env.CATENCE_MCP_KEYS_FILE ?? defaultMcpKeysPath(currentCatalog().root);
+// The OAuth settings file resolves like the serve option: the environment,
+// then the catalog home default.
+const mcpOauthSettingsFile = () => process.env.CATENCE_OAUTH_SETTINGS_FILE ?? defaultOauthSettingsPath(currentCatalog().root);
+mcpCommand.command('status')
+    .description('Report whether the bearer-token gate is enabled, the token, the per-account key counts, and the endpoint URLs.')
+    .option('--file <path>', 'non-default token file path')
+    .action(async (options) => {
+    const tokenFile = options.file ?? defaultBearerTokenPath(currentCatalog().root);
+    const keys = await listMcpKeys(mcpKeysFile());
+    const status = {
+        ...mcpExposureStatus(tokenFile, mcpLocalEndpoint()),
+        keys: { total: keys.length, active: keys.filter((key) => key.revokedAt === undefined).length },
+        oauth: oauthStatusFromSettings(mcpOauthSettingsFile()),
+    };
+    process.stdout.write(`${JSON.stringify(status, null, 2)}\n`);
+});
+mcpCommand.command('enable')
+    .description('Enable the bearer-token gate: generate the token file (mode 0600) if it does not exist.')
+    .option('--file <path>', 'non-default token file path')
+    .action(async (options) => {
+    const tokenFile = options.file ?? defaultBearerTokenPath(currentCatalog().root);
+    ensureBearerToken(tokenFile);
+    process.stdout.write(`${JSON.stringify(mcpExposureStatus(tokenFile, mcpLocalEndpoint()), null, 2)}\n`);
+});
+mcpCommand.command('disable')
+    .description('Disable the bearer-token gate by removing the token file. Remote access is refused again.')
+    .option('--file <path>', 'non-default token file path')
+    .action(async (options) => {
+    const tokenFile = options.file ?? defaultBearerTokenPath(currentCatalog().root);
+    disableBearerToken(tokenFile);
+    process.stdout.write(`${JSON.stringify(mcpExposureStatus(tokenFile, mcpLocalEndpoint()), null, 2)}\n`);
+});
+mcpCommand.command('token')
+    .description('Print only the bearer token for pasting into an MCP client credential flow.')
+    .option('--file <path>', 'non-default token file path')
+    .action(async (options) => {
+    const tokenFile = options.file ?? defaultBearerTokenPath(currentCatalog().root);
+    const token = readBearerToken(tokenFile);
+    if (token === null)
+        throw new Error(`MCP exposure is not enabled; run 'catence-data mcp enable' first.`);
+    process.stdout.write(`${token}\n`);
+});
+const mcpKeyCommand = mcpCommand.command('key').description('Manage per-account MCP bearer keys; raw tokens are printed exactly once and stored only as hashes.');
+mcpKeyCommand.command('add')
+    .description('Create a per-account MCP key and print its raw token exactly once.')
+    .requiredOption('--account <username>', 'Console account username the key acts for')
+    .option('--label <label>', 'human-readable key label')
+    .option('--file <path>', 'non-default MCP keys file path')
+    .action(async (options) => {
+    const { record, token } = await addMcpKey(mcpKeysFile(options.file), { account: options.account, label: options.label });
+    process.stdout.write(`${JSON.stringify({ id: record.id, label: record.label, account: record.account, createdAt: record.createdAt, token }, null, 2)}\n`);
+});
+mcpKeyCommand.command('list')
+    .description('List MCP keys without their token hashes.')
+    .option('--file <path>', 'non-default MCP keys file path')
+    .action(async (options) => {
+    process.stdout.write(`${JSON.stringify({ keys: await listMcpKeys(mcpKeysFile(options.file)) }, null, 2)}\n`);
+});
+mcpKeyCommand.command('revoke')
+    .description('Revoke an MCP key by id; its token stops working immediately.')
+    .argument('<id>', 'key id')
+    .option('--file <path>', 'non-default MCP keys file path')
+    .action(async (id, options) => {
+    await revokeMcpKey(mcpKeysFile(options.file), id);
+    process.stdout.write(`${JSON.stringify({ revoked: id }, null, 2)}\n`);
+});
+mcpKeyCommand.command('roll')
+    .description('Replace an MCP key’s token and print the new raw token exactly once.')
+    .argument('<id>', 'key id')
+    .option('--file <path>', 'non-default MCP keys file path')
+    .action(async (id, options) => {
+    const { record, token } = await rollMcpKey(mcpKeysFile(options.file), id);
+    process.stdout.write(`${JSON.stringify({ id: record.id, label: record.label, account: record.account, createdAt: record.createdAt, token }, null, 2)}\n`);
+});
 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')
@@ -61,7 +141,7 @@ athleteCommand.command('add')
     .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.');
+const secretCommand = program.command('secret').description('Write or remove a provider value in one athlete’s owner-only secret store.');
 secretCommand.command('set')
     .requiredOption('--provider <provider>', 'garmin, intervals, or strava')
     .requiredOption('--field <field>', 'provider secret field')
@@ -73,6 +153,16 @@ secretCommand.command('set')
     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`);
 });
+secretCommand.command('remove')
+    .requiredOption('--provider <provider>', 'garmin, intervals, or strava')
+    .requiredOption('--field <field>', 'provider secret field')
+    .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 deleteAthleteSecret(paths, options.provider, options.field);
+    process.stdout.write(`${JSON.stringify({ athleteId: program.opts().athlete, provider: options.provider, field: options.field, removed: true }, null, 2)}\n`);
+});
 program.command('demo')
     .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')
@@ -120,6 +210,27 @@ program.command('retry')
     const { paths } = await currentAthlete();
     process.stdout.write(`${JSON.stringify(await retryDataSync(paths, options.run), null, 2)}\n`);
 });
+const autoSyncCommand = program.command('auto-sync').description('Manage the automatic sync schedule for one athlete. The scheduler runs inside the Catence server (default: enabled, every 2 hours).');
+autoSyncCommand.command('status')
+    .description('Report the athlete’s automatic sync schedule: enabled flag, interval, and next run.')
+    .action(async () => {
+    const { athlete, paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await readAutoSyncSchedule(paths, athlete.id), null, 2)}\n`);
+});
+autoSyncCommand.command('enable')
+    .description('Turn automatic syncing on, optionally changing the interval (15m, 30m, 1h, 2h, 6h, 12h, 24h).')
+    .option('--interval <interval>', 'sync interval label or minutes', '2h')
+    .action(async (options) => {
+    const { athlete, paths } = await currentAthlete();
+    const intervalMinutes = parseAutoSyncInterval(options.interval);
+    process.stdout.write(`${JSON.stringify(await updateAutoSyncSchedule(paths, athlete.id, { enabled: true, intervalMinutes }), null, 2)}\n`);
+});
+autoSyncCommand.command('disable')
+    .description('Turn automatic syncing off. Manual sync keeps working.')
+    .action(async () => {
+    const { athlete, paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await updateAutoSyncSchedule(paths, athlete.id, { enabled: false }), null, 2)}\n`);
+});
 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')
@@ -256,6 +367,10 @@ program.command('reimport-nutrition').description('Re-run normalization over cap
     const { paths } = await currentAthlete();
     process.stdout.write(`${JSON.stringify(await reimportNutrition(paths), null, 2)}\n`);
 });
+program.command('reimport-weight').description('Backfill weight_kg from captured Garmin weigh-in entities without contacting providers.').action(async () => {
+    const { paths } = await currentAthlete();
+    process.stdout.write(`${JSON.stringify(await reimportWeight(paths), null, 2)}\n`);
+});
 program
     .command('import')
     .description('Import a staged JSONL file (for example a swim-length backfill) into one athlete’s data store.')

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

@@ -3,7 +3,70 @@ export type ServeCliOptions = {
     host: string;
     port: number;
     allowedOrigins: string[];
+    authTokenFile?: string;
+    mcpKeysFile?: string;
+    oauthSettingsFile?: string;
+    oauth: boolean;
+    publicUrl?: 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 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  --auth-token-file <path>   Bearer-token file for the HTTP gate. Its presence switches authentication on;\n                             generate/inspect it with 'catence-data mcp enable|token'.\n                             Defaults to CATENCE_MCP_TOKEN_FILE or <catalog-home>/mcp-token.\n  --mcp-keys-file <path>     Per-account MCP key registry for the HTTP gate. Any active key in it\n                             switches authentication on; manage keys with 'catence-data mcp key'.\n                             Defaults to CATENCE_MCP_KEYS_FILE or <catalog-home>/mcp-keys.json.\n  --oauth                    Run the OAuth 2.1 authorization server (issuer = --public-url) so\n                             ChatGPT/Codex-style MCP clients connect with a per-account consent\n                             login. Requires --public-url. Defaults to CATENCE_OAUTH_ENABLED=1/true.\n                             The Console settings file overrides this at runtime.\n  --public-url <url>         Public https URL of this server (no query string or fragment), e.g.\n                             the tunnel URL. Required when --oauth is enabled.\n                             Defaults to CATENCE_PUBLIC_URL.\n  --oauth-settings-file <path>\n                             Console-managed OAuth settings that override --oauth/--public-url\n                             at runtime. Defaults to CATENCE_OAUTH_SETTINGS_FILE or\n                             <catalog-home>/oauth/settings.json.\n  -h, --help                 Show this help text.";
+/** The canonical token location inside a catalog home. */
+export declare function defaultBearerTokenPath(catalogRoot: string): string;
+/** The canonical per-account MCP key registry location inside a catalog home. */
+export declare function defaultMcpKeysPath(catalogRoot: string): string;
+/** The canonical Console-managed OAuth settings location inside a catalog home. */
+export declare function defaultOauthSettingsPath(catalogRoot: string): string;
+/** Read and validate a stored bearer token: trimmed, non-empty, or fail loudly. */
+export declare function loadBearerToken(filePath: string): string;
+/**
+ * The bearer token for the server: the stored one, or a freshly generated
+ * token written to the file (mode 0600) when it does not exist yet. Users
+ * never hand-craft tokens; they enable auth and read the result with
+ * `catence-data mcp-token`.
+ */
+export declare function ensureBearerToken(filePath: string): string;
+export declare function disableBearerToken(filePath: string): void;
+/** The bearer token when exposure is enabled, or null when no token file exists. */
+export declare function readBearerToken(filePath: string): string | null;
+/**
+ * The currently active bearer token for the HTTP gate, cached by the token
+ * file's mtime so enabling or disabling is picked up without a restart. A
+ * missing file disables the gate; an existing but unreadable or empty file
+ * fails closed (the gate rejects everything except health probes).
+ */
+export declare function activeBearerToken(filePath: string): string | null | 'invalid';
+export type McpExposureStatus = {
+    enabled: boolean;
+    tokenFile: string;
+    endpoint: string;
+    healthEndpoint: string;
+    token?: string;
+    oauth?: {
+        enabled: boolean;
+        publicUrl?: string;
+    };
+};
+export declare function mcpExposureStatus(filePath: string, endpointBase: string, oauth?: {
+    enabled: boolean;
+    publicUrl?: string;
+}): McpExposureStatus;
+/** True when CATENCE_OAUTH_ENABLED is 1/true. */
+export declare function oauthEnabledFromEnv(env?: NodeJS.ProcessEnv): boolean;
+/** The OAuth exposure reported by `catence-data mcp status`, read from the environment. */
+export declare function oauthStatusFromEnv(env?: NodeJS.ProcessEnv): {
+    enabled: boolean;
+    publicUrl?: string;
+};
+export type McpOauthStatusSource = 'console' | 'environment' | 'disabled';
+/**
+ * The effective OAuth exposure: the Console settings file when a valid one
+ * exists (a malformed one fails closed to disabled), else the environment.
+ * `source` records where the effective values come from.
+ */
+export declare function oauthStatusFromSettings(settingsFile: string, env?: NodeJS.ProcessEnv): {
+    enabled: boolean;
+    publicUrl?: string;
+    source: McpOauthStatusSource;
+};
 export declare function parseServeCliOptions(arguments_: readonly string[]): ServeCliOptions;