catence 0.0.0 → 0.1.0

package/dist/elt/storage/migrations.legacy.d.ts

@@ -0,0 +1,12 @@
+export type Migration = {
+    version: number;
+    name: string;
+    sql: string;
+    /**
+     * Idempotent statements that must run after the migration transaction
+     * commits. This is reserved for engine operations that cannot safely be
+     * combined with a populated-table rewrite on all supported DuckDB builds.
+     */
+    postCommitSql?: string;
+};
+export declare const migrations: Migration[];

package/dist/elt/storage/migrations.legacy.js

@@ -0,0 +1,332 @@
+export const migrations = [
+    {
+        version: 1,
+        name: 'initial_ingestion_schema',
+        sql: `
+      CREATE TABLE IF NOT EXISTS schema_migrations (
+        version INTEGER PRIMARY KEY,
+        name VARCHAR NOT NULL,
+        applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
+      );
+      CREATE TABLE IF NOT EXISTS source_accounts (
+        provider VARCHAR NOT NULL,
+        remote_account_id VARCHAR NOT NULL,
+        display_name VARCHAR,
+        fetched_at TIMESTAMPTZ NOT NULL,
+        payload_json JSON NOT NULL,
+        PRIMARY KEY (provider, remote_account_id)
+      );
+      CREATE TABLE IF NOT EXISTS sync_runs (
+        run_id VARCHAR PRIMARY KEY,
+        provider VARCHAR NOT NULL,
+        from_date DATE NOT NULL,
+        started_at TIMESTAMPTZ NOT NULL,
+        completed_at TIMESTAMPTZ,
+        status VARCHAR NOT NULL,
+        parser_version INTEGER NOT NULL,
+        error_count INTEGER NOT NULL DEFAULT 0
+      );
+      CREATE TABLE IF NOT EXISTS sync_items (
+        item_id VARCHAR PRIMARY KEY,
+        run_id VARCHAR NOT NULL,
+        provider VARCHAR NOT NULL,
+        endpoint VARCHAR NOT NULL,
+        remote_id VARCHAR,
+        scope_json JSON NOT NULL,
+        status VARCHAR NOT NULL,
+        attempts INTEGER NOT NULL DEFAULT 0,
+        error_message VARCHAR,
+        started_at TIMESTAMPTZ,
+        completed_at TIMESTAMPTZ
+      );
+      CREATE TABLE IF NOT EXISTS raw_objects (
+        content_hash VARCHAR PRIMARY KEY,
+        provider VARCHAR NOT NULL,
+        endpoint VARCHAR NOT NULL,
+        remote_id VARCHAR,
+        fetched_at TIMESTAMPTZ NOT NULL,
+        content_type VARCHAR NOT NULL,
+        relative_path VARCHAR NOT NULL,
+        scope_json JSON NOT NULL,
+        parser_version INTEGER NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS source_entities (
+        provider VARCHAR NOT NULL,
+        entity_type VARCHAR NOT NULL,
+        remote_id VARCHAR NOT NULL,
+        parent_remote_id VARCHAR,
+        occurred_on DATE,
+        source_updated_at TIMESTAMPTZ,
+        raw_object_hash VARCHAR,
+        payload_json JSON NOT NULL,
+        extension_json JSON NOT NULL,
+        normalized_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        PRIMARY KEY (provider, entity_type, remote_id)
+      );
+      CREATE TABLE IF NOT EXISTS normalization_errors (
+        error_id VARCHAR PRIMARY KEY,
+        run_id VARCHAR NOT NULL,
+        provider VARCHAR NOT NULL,
+        endpoint VARCHAR NOT NULL,
+        remote_id VARCHAR,
+        message VARCHAR NOT NULL,
+        retryable BOOLEAN NOT NULL,
+        created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        resolved_at TIMESTAMPTZ
+      );
+      CREATE TABLE IF NOT EXISTS activities (
+        activity_id VARCHAR PRIMARY KEY,
+        started_at_utc TIMESTAMPTZ,
+        started_at_local VARCHAR,
+        timezone VARCHAR,
+        sport VARCHAR,
+        name VARCHAR,
+        link_state VARCHAR NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS activity_sources (
+        activity_source_id VARCHAR PRIMARY KEY,
+        activity_id VARCHAR NOT NULL,
+        provider VARCHAR NOT NULL,
+        remote_activity_id VARCHAR NOT NULL,
+        external_id VARCHAR,
+        raw_object_hash VARCHAR,
+        UNIQUE (provider, remote_activity_id)
+      );
+      CREATE TABLE IF NOT EXISTS activity_summaries (
+        activity_source_id VARCHAR PRIMARY KEY,
+        distance_m DOUBLE,
+        moving_s DOUBLE,
+        elapsed_s DOUBLE,
+        elevation_gain_m DOUBLE,
+        calories DOUBLE,
+        avg_hr DOUBLE,
+        max_hr DOUBLE,
+        avg_power DOUBLE,
+        weighted_power DOUBLE,
+        avg_cadence DOUBLE,
+        training_load DOUBLE,
+        rpe DOUBLE,
+        feel DOUBLE,
+        metrics_json JSON NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS activity_intervals (
+        activity_source_id VARCHAR NOT NULL,
+        interval_key VARCHAR NOT NULL,
+        label VARCHAR,
+        start_s DOUBLE,
+        end_s DOUBLE,
+        distance_m DOUBLE,
+        avg_power DOUBLE,
+        avg_hr DOUBLE,
+        avg_pace DOUBLE,
+        intensity DOUBLE,
+        metrics_json JSON NOT NULL,
+        PRIMARY KEY (activity_source_id, interval_key)
+      );
+      CREATE TABLE IF NOT EXISTS daily_metrics (
+        provider VARCHAR NOT NULL,
+        metric_date DATE NOT NULL,
+        metric_name VARCHAR NOT NULL,
+        value_number DOUBLE,
+        value_text VARCHAR,
+        unit VARCHAR,
+        raw_object_hash VARCHAR,
+        PRIMARY KEY (provider, metric_date, metric_name)
+      );
+      CREATE TABLE IF NOT EXISTS nutrition_days (
+        provider VARCHAR NOT NULL,
+        nutrition_date DATE NOT NULL,
+        energy_kcal DOUBLE,
+        carbohydrates_g DOUBLE,
+        protein_g DOUBLE,
+        fat_g DOUBLE,
+        hydration_ml DOUBLE,
+        metrics_json JSON NOT NULL,
+        raw_object_hash VARCHAR,
+        PRIMARY KEY (provider, nutrition_date)
+      );
+      CREATE TABLE IF NOT EXISTS nutrition_items (
+        provider VARCHAR NOT NULL,
+        remote_item_id VARCHAR NOT NULL,
+        nutrition_date DATE NOT NULL,
+        meal VARCHAR,
+        consumed_at TIMESTAMPTZ,
+        food_name VARCHAR,
+        quantity DOUBLE,
+        energy_kcal DOUBLE,
+        carbohydrates_g DOUBLE,
+        protein_g DOUBLE,
+        fat_g DOUBLE,
+        payload_json JSON NOT NULL,
+        raw_object_hash VARCHAR,
+        PRIMARY KEY (provider, remote_item_id)
+      );
+      CREATE TABLE IF NOT EXISTS domain_entities (
+        provider VARCHAR NOT NULL,
+        entity_type VARCHAR NOT NULL,
+        remote_id VARCHAR NOT NULL,
+        parent_remote_id VARCHAR,
+        occurred_on DATE,
+        payload_json JSON NOT NULL,
+        extension_json JSON NOT NULL,
+        raw_object_hash VARCHAR,
+        PRIMARY KEY (provider, entity_type, remote_id)
+      );
+      CREATE TABLE IF NOT EXISTS stream_manifest (
+        provider VARCHAR NOT NULL,
+        activity_source_id VARCHAR NOT NULL,
+        content_hash VARCHAR NOT NULL,
+        relative_path VARCHAR NOT NULL,
+        row_count BIGINT NOT NULL,
+        start_at TIMESTAMPTZ,
+        end_at TIMESTAMPTZ,
+        columns_json JSON NOT NULL,
+        raw_object_hash VARCHAR,
+        PRIMARY KEY (provider, activity_source_id, content_hash)
+      );
+      CREATE OR REPLACE VIEW daily_health AS
+      SELECT provider, metric_date,
+        max(value_number) FILTER (WHERE metric_name = 'resting_hr_bpm') AS resting_hr_bpm,
+        max(value_number) FILTER (WHERE metric_name = 'hrv_ms') AS hrv_ms,
+        max(value_number) FILTER (WHERE metric_name = 'sleep_seconds') AS sleep_seconds,
+        max(value_number) FILTER (WHERE metric_name = 'sleep_score') AS sleep_score,
+        max(value_number) FILTER (WHERE metric_name = 'stress') AS stress,
+        max(value_number) FILTER (WHERE metric_name = 'body_battery') AS body_battery,
+        max(value_number) FILTER (WHERE metric_name = 'readiness') AS readiness,
+        max(value_number) FILTER (WHERE metric_name = 'spo2_pct') AS spo2_pct,
+        max(value_number) FILTER (WHERE metric_name = 'weight_kg') AS weight_kg,
+        max(value_number) FILTER (WHERE metric_name = 'steps') AS steps
+      FROM daily_metrics
+      GROUP BY provider, metric_date;
+      CREATE OR REPLACE VIEW canonical_activity_training AS
+      SELECT * EXCLUDE (priority, row_rank)
+      FROM (
+        SELECT a.*, s.provider, summary.*, CASE WHEN s.provider = 'intervals' THEN 0 ELSE 1 END AS priority,
+          row_number() OVER (PARTITION BY a.activity_id ORDER BY CASE WHEN s.provider = 'intervals' THEN 0 ELSE 1 END) AS row_rank
+        FROM activities a
+        JOIN activity_sources s USING (activity_id)
+        LEFT JOIN activity_summaries summary USING (activity_source_id)
+      )
+      WHERE row_rank = 1;
+    `,
+    },
+    {
+        version: 2,
+        name: 'domain_projection_views',
+        sql: `
+      CREATE OR REPLACE VIEW events AS
+      SELECT provider, remote_id AS event_id, occurred_on, parent_remote_id, payload_json, extension_json, raw_object_hash
+      FROM domain_entities WHERE entity_type = 'event';
+      CREATE OR REPLACE VIEW workouts AS
+      SELECT provider, remote_id AS workout_id, occurred_on, parent_remote_id, payload_json, extension_json, raw_object_hash
+      FROM domain_entities WHERE entity_type IN ('workout', 'scheduled_workout');
+      CREATE OR REPLACE VIEW workout_documents AS
+      SELECT provider, remote_id AS workout_id, payload_json->'workout_doc' AS workout_doc, payload_json
+      FROM domain_entities WHERE entity_type IN ('workout', 'scheduled_workout');
+      CREATE OR REPLACE VIEW training_plans AS
+      SELECT provider, remote_id AS training_plan_id, occurred_on, payload_json, extension_json, raw_object_hash
+      FROM domain_entities WHERE entity_type = 'training_plan';
+      CREATE OR REPLACE VIEW routes AS
+      SELECT provider, remote_id AS route_id, payload_json, extension_json, raw_object_hash
+      FROM domain_entities WHERE entity_type = 'route';
+      CREATE OR REPLACE VIEW gear AS
+      SELECT provider, remote_id AS gear_id, payload_json, extension_json, raw_object_hash
+      FROM domain_entities WHERE entity_type = 'gear';
+      CREATE OR REPLACE VIEW devices AS
+      SELECT provider, remote_id AS device_id, payload_json, extension_json, raw_object_hash
+      FROM domain_entities WHERE entity_type = 'device';
+      CREATE OR REPLACE VIEW goals AS
+      SELECT provider, remote_id AS goal_id, payload_json, extension_json, raw_object_hash
+      FROM domain_entities WHERE entity_type IN ('goal', 'challenge');
+      CREATE OR REPLACE VIEW achievements AS
+      SELECT provider, remote_id AS achievement_id, payload_json, extension_json, raw_object_hash
+      FROM domain_entities WHERE entity_type IN ('badge', 'personal_record');
+      CREATE OR REPLACE VIEW messages AS
+      SELECT provider, remote_id AS message_id, parent_remote_id, occurred_on, payload_json, extension_json, raw_object_hash
+      FROM domain_entities WHERE entity_type = 'message';
+    `,
+    },
+    {
+        version: 3,
+        name: 'retrieval_documents',
+        sql: `
+      CREATE TABLE IF NOT EXISTS retrieval_documents (
+        document_id VARCHAR PRIMARY KEY,
+        entity_type VARCHAR NOT NULL,
+        entity_id VARCHAR NOT NULL,
+        activity_source_id VARCHAR,
+        provider VARCHAR,
+        occurred_on DATE,
+        document_text VARCHAR NOT NULL,
+        metadata_json JSON NOT NULL,
+        content_hash VARCHAR NOT NULL UNIQUE,
+        generated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+      );
+      CREATE INDEX IF NOT EXISTS retrieval_documents_entity_idx
+        ON retrieval_documents (entity_type, entity_id);
+      CREATE INDEX IF NOT EXISTS retrieval_documents_date_idx
+        ON retrieval_documents (occurred_on);
+      CREATE TABLE IF NOT EXISTS retrieval_index_state (
+        index_name VARCHAR PRIMARY KEY,
+        status VARCHAR NOT NULL,
+        mode VARCHAR NOT NULL,
+        source_watermark VARCHAR,
+        built_at TIMESTAMPTZ,
+        detail_json JSON NOT NULL DEFAULT '{}'
+      );
+      INSERT INTO retrieval_index_state (index_name, status, mode, detail_json)
+      VALUES ('context', 'stale', 'keyword', '{}')
+      ON CONFLICT (index_name) DO NOTHING;
+    `,
+    },
+    {
+        version: 4,
+        name: 'query_projection_views',
+        sql: `
+      CREATE OR REPLACE VIEW activity_summary_facts AS
+      SELECT summary.*, source.activity_id, source.provider, source.remote_activity_id,
+        source.raw_object_hash, activity.started_at_utc, activity.started_at_local,
+        activity.timezone, activity.sport, activity.name
+      FROM activity_summaries summary
+      JOIN activity_sources source USING (activity_source_id)
+      JOIN activities activity USING (activity_id);
+      CREATE OR REPLACE VIEW activity_interval_facts AS
+      SELECT intervals.*, source.activity_id, source.provider,
+        activity.started_at_utc, activity.sport, activity.name
+      FROM activity_intervals intervals
+      JOIN activity_sources source USING (activity_source_id)
+      JOIN activities activity USING (activity_id);
+    `,
+    },
+    {
+        version: 5,
+        name: 'incremental_sync_cursors',
+        sql: `
+      CREATE TABLE IF NOT EXISTS sync_cursors (
+        provider VARCHAR NOT NULL,
+        cursor_name VARCHAR NOT NULL,
+        covered_through_date DATE NOT NULL,
+        latest_source_date DATE,
+        lookback_days INTEGER NOT NULL,
+        last_successful_run_id VARCHAR,
+        last_completed_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        status VARCHAR NOT NULL,
+        detail_json JSON NOT NULL DEFAULT '{}',
+        PRIMARY KEY (provider, cursor_name)
+      );
+      CREATE TABLE IF NOT EXISTS activity_sync_state (
+        provider VARCHAR NOT NULL,
+        remote_activity_id VARCHAR NOT NULL,
+        summary_hash VARCHAR NOT NULL,
+        last_seen_run_id VARCHAR NOT NULL,
+        last_seen_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+        last_detail_sync_at TIMESTAMPTZ,
+        details_status VARCHAR NOT NULL,
+        PRIMARY KEY (provider, remote_activity_id)
+      );
+      CREATE INDEX IF NOT EXISTS activity_sync_state_hash_idx
+        ON activity_sync_state (provider, summary_hash);
+    `,
+    },
+];
+//# sourceMappingURL=migrations.legacy.js.map

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

@@ -0,0 +1,2 @@
+export declare function sqlString(value: string): string;
+export declare function json(value: unknown): string;

package/dist/elt/storage/sql.js

@@ -0,0 +1,7 @@
+export function sqlString(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+export function json(value) {
+    return JSON.stringify(value ?? {});
+}
+//# sourceMappingURL=sql.js.map

package/dist/elt/storage/write-lock.d.ts

@@ -0,0 +1,6 @@
+import type { CatencePaths } from '../../contracts/runtime.js';
+export declare class DataWriteBusyError extends Error {
+    constructor();
+}
+/** Serializes short writer transactions across local CLI and stdio MCP processes. */
+export declare function withDataWriteLock<T>(paths: CatencePaths, work: () => Promise<T>): Promise<T>;

package/dist/elt/storage/write-lock.js

@@ -0,0 +1,28 @@
+import { open, unlink } from 'node:fs/promises';
+export class DataWriteBusyError extends Error {
+    constructor() {
+        super('Another Catence sync or enrichment request currently owns the data directory. Retry after it completes.');
+        this.name = 'DataWriteBusyError';
+    }
+}
+/** Serializes short writer transactions across local CLI and stdio MCP processes. */
+export async function withDataWriteLock(paths, work) {
+    let handle;
+    try {
+        handle = await open(paths.lock, 'wx', 0o600);
+        await handle.writeFile(`${JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() })}\n`);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST')
+            throw new DataWriteBusyError();
+        throw error;
+    }
+    try {
+        return await work();
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+        await unlink(paths.lock).catch(() => undefined);
+    }
+}
+//# sourceMappingURL=write-lock.js.map

package/dist/elt/streams.d.ts

@@ -0,0 +1,24 @@
+import type { CatencePaths } from '../contracts/runtime.js';
+import type { CatenceDatabase } from './storage/database.js';
+export type ActivitySample = {
+    activity_source_id: string;
+    timestamp_utc: string | null;
+    elapsed_s: number | null;
+    distance_m: number | null;
+    latitude: number | null;
+    longitude: number | null;
+    altitude_m: number | null;
+    heart_rate_bpm: number | null;
+    power_w: number | null;
+    cadence_rpm: number | null;
+    speed_mps: number | null;
+    temperature_c: number | null;
+    grade_pct: number | null;
+    extras_json: string;
+};
+export declare function intervalsStreamsToSamples(activitySourceId: string, streams: Array<Record<string, unknown>>, startAt: string | null): ActivitySample[];
+export declare function writeParquetSamples(database: CatenceDatabase, paths: CatencePaths, provider: 'intervals' | 'garmin', activityRemoteId: string, startDate: string, samples: ActivitySample[]): Promise<{
+    relativePath: string;
+    contentHash: string;
+    columns: string[];
+}>;

package/dist/elt/streams.js

@@ -0,0 +1,62 @@
+import { createHash } from 'node:crypto';
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { sqlString } from './storage/sql.js';
+const knownColumns = {
+    time: 'elapsed_s', elapsed_time: 'elapsed_s', elapsed_s: 'elapsed_s', distance: 'distance_m', lat: 'latitude', latitude: 'latitude',
+    lng: 'longitude', lon: 'longitude', longitude: 'longitude', altitude: 'altitude_m', elevation: 'altitude_m', heartrate: 'heart_rate_bpm',
+    heart_rate: 'heart_rate_bpm', hr: 'heart_rate_bpm', watts: 'power_w', power: 'power_w', cadence: 'cadence_rpm', velocity_smooth: 'speed_mps',
+    speed: 'speed_mps', temp: 'temperature_c', temperature: 'temperature_c', grade_smooth: 'grade_pct', grade: 'grade_pct',
+};
+function numeric(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+export function intervalsStreamsToSamples(activitySourceId, streams, startAt) {
+    const arrays = new Map();
+    for (const stream of streams) {
+        const name = typeof stream.type === 'string' ? stream.type : typeof stream.name === 'string' ? stream.name : null;
+        const values = Array.isArray(stream.data) ? stream.data : null;
+        if (name && values)
+            arrays.set(name, values);
+    }
+    const count = Math.max(0, ...[...arrays.values()].map((values) => values.length));
+    const origin = startAt ? Date.parse(startAt) : Number.NaN;
+    return Array.from({ length: count }, (_, index) => {
+        const extras = {};
+        const sample = {
+            activity_source_id: activitySourceId, timestamp_utc: Number.isFinite(origin) ? new Date(origin + (numeric(arrays.get('time')?.[index]) ?? index) * 1000).toISOString() : null,
+            elapsed_s: null, distance_m: null, latitude: null, longitude: null, altitude_m: null, heart_rate_bpm: null, power_w: null,
+            cadence_rpm: null, speed_mps: null, temperature_c: null, grade_pct: null, extras_json: '{}',
+        };
+        for (const [name, values] of arrays) {
+            const value = values[index];
+            const column = knownColumns[name];
+            if (column)
+                sample[column] = numeric(value);
+            else
+                extras[name] = value;
+        }
+        sample.extras_json = JSON.stringify(extras);
+        return sample;
+    });
+}
+export async function writeParquetSamples(database, paths, provider, activityRemoteId, startDate, samples) {
+    const activitySourceId = `${provider}:${activityRemoteId}`;
+    const year = startDate.slice(0, 4) || 'unknown';
+    const month = startDate.slice(5, 7) || 'unknown';
+    const directory = path.join(paths.lake, `provider=${provider}`, `year=${year}`, `month=${month}`);
+    await mkdir(directory, { recursive: true });
+    const jsonPath = path.join(paths.staging, `${provider}-${activityRemoteId}-${process.pid}.ndjson`);
+    await writeFile(jsonPath, samples.map((sample) => JSON.stringify(sample)).join('\n'));
+    const target = path.join(directory, `activity=${activityRemoteId}.parquet`);
+    const temporary = `${target}.${process.pid}.tmp`;
+    await database.run(`COPY (SELECT * FROM read_ndjson_auto(${sqlString(jsonPath)})) TO ${sqlString(temporary)} (FORMAT PARQUET, COMPRESSION ZSTD)`);
+    await rename(temporary, target);
+    const contentHash = createHash('sha256').update(await (await import('node:fs/promises')).readFile(target)).digest('hex');
+    return {
+        relativePath: path.relative(paths.root, target),
+        contentHash,
+        columns: ['activity_source_id', 'timestamp_utc', 'elapsed_s', 'distance_m', 'latitude', 'longitude', 'altitude_m', 'heart_rate_bpm', 'power_w', 'cadence_rpm', 'speed_mps', 'temperature_c', 'grade_pct', 'extras_json'],
+    };
+}
+//# sourceMappingURL=streams.js.map

package/dist/interfaces/cli/commands.d.ts

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

package/dist/interfaces/cli/commands.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { connectStrava, connectStravaWithCallback, createDemoStore, dataStatus, disconnectStravaAccount, initializeDataStore, linkActivity, rebuildRetrievalIndex, resolvePaths, retryDataSync, syncData, 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);
+}
+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);
+}
+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`);
+});
+program.command('demo')
+    .description('Create a generated local demo store without contacting providers. Refuses to overwrite a non-demo data directory.')
+    .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`);
+});
+program.command('sync')
+    .requiredOption('--provider <provider>', 'intervals, garmin, strava, or all')
+    .option('--from <date>', 'explicit ISO date range; otherwise use incremental cursors')
+    .option('--refresh', 're-fetch Garmin activity details, files, and streams even when summaries are unchanged')
+    .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`);
+});
+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)')
+    .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`);
+});
+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`);
+});
+program.command('auth').description('Connect a source account without storing credentials in DuckDB.')
+    .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')
+    .option('--callback', 'wait for a browser OAuth callback on a loopback redirect URI')
+    .option('--timeout-seconds <seconds>', 'maximum callback wait time', '300')
+    .action(async (options) => {
+    if (options.callback && options.code)
+        throw new Error('--code and --callback cannot be used together.');
+    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 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");
+});
+program.command('disconnect').description('Remove locally stored credentials for a source account.')
+    .command('strava')
+    .action(async () => {
+    process.stdout.write(JSON.stringify(await disconnectStravaAccount(currentPaths()), 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");
+});
+activityCommand.command('unlink')
+    .requiredOption('--source <activity-source-id>')
+    .action(async (options) => {
+    process.stdout.write(JSON.stringify(await unlinkActivity(currentPaths(), options.source), null, 2) + "\n");
+});
+program.command('status').action(async () => {
+    process.stdout.write(`${JSON.stringify(await dataStatus(currentPaths()), 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`);
+});
+await program.parseAsync();
+//# sourceMappingURL=commands.js.map

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

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './commands.js';

package/dist/interfaces/cli/main.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import './commands.js';
+//# sourceMappingURL=main.js.map

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

@@ -0,0 +1,9 @@
+export type ServeCliOptions = {
+    dataDir?: 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 function parseServeCliOptions(arguments_: readonly string[]): ServeCliOptions;