catence 0.0.0 → 0.1.0

package/dist/core/runtime/configuration.js

@@ -0,0 +1,106 @@
+import { config as loadDotenv } from 'dotenv';
+import { mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+loadDotenv({ quiet: true });
+export function resolvePaths(root = process.env.CATENCE_DATA_DIR ?? '.catence') {
+    const absoluteRoot = path.resolve(root);
+    return {
+        root: absoluteRoot,
+        database: path.join(absoluteRoot, 'catence.duckdb'),
+        raw: path.join(absoluteRoot, 'raw'),
+        lake: path.join(absoluteRoot, 'lake', 'activity_samples'),
+        staging: path.join(absoluteRoot, 'staging'),
+        config: path.join(absoluteRoot, 'config.json'),
+        secrets: path.join(absoluteRoot, 'secrets'),
+        lock: path.join(absoluteRoot, '.catence-write.lock'),
+    };
+}
+export async function ensurePaths(paths) {
+    await Promise.all([mkdir(paths.raw, { recursive: true }), mkdir(paths.lake, { recursive: true }), mkdir(paths.staging, { recursive: true }), mkdir(paths.secrets, { recursive: true, mode: 0o700 })]);
+}
+export function defaultFromDate(now = new Date()) {
+    const date = new Date(Date.UTC(now.getUTCFullYear() - 1, now.getUTCMonth(), now.getUTCDate()));
+    return date.toISOString().slice(0, 10);
+}
+export function requireIntervalsConfig() {
+    const apiKey = process.env.INTERVALS_API_KEY;
+    if (!apiKey)
+        throw new Error('INTERVALS_API_KEY is required for an Intervals sync.');
+    return { apiKey, athleteId: process.env.INTERVALS_ATHLETE_ID ?? '0' };
+}
+const rateLimitSchema = z.object({ requests: z.number().int().positive(), windowSeconds: z.number().int().positive() }).strict();
+const nullableRateLimitSchema = rateLimitSchema.nullable();
+const environmentVariableSchema = z.string().regex(/^[A-Z][A-Z0-9_]*$/, 'must be an uppercase environment-variable name');
+const consoleModelSchema = z.object({
+    label: z.string().min(1).optional(),
+    model: z.string().min(1),
+}).strict();
+const consoleProfileSchema = z.object({
+    label: z.string().min(1).optional(),
+    model: z.string().min(1).optional(),
+    models: z.record(z.string().min(1), consoleModelSchema).optional(),
+    defaultModel: z.string().min(1).optional(),
+    defaultReasoningEffort: z.enum(['minimal', 'low', 'medium', 'high', 'xhigh']).optional(),
+    apiKeyEnv: environmentVariableSchema.optional(),
+    apiBaseEnv: environmentVariableSchema.optional(),
+    apiVersionEnv: environmentVariableSchema.optional(),
+}).strict().superRefine((profile, context) => {
+    if (Boolean(profile.model) === Boolean(profile.models)) {
+        context.addIssue({ code: 'custom', message: 'must define exactly one of model or models' });
+    }
+    if (profile.defaultModel && !profile.models) {
+        context.addIssue({ code: 'custom', path: ['defaultModel'], message: 'requires models' });
+    }
+    if (profile.models && profile.defaultModel && !Object.hasOwn(profile.models, profile.defaultModel)) {
+        context.addIssue({ code: 'custom', path: ['defaultModel'], message: 'must name one of models' });
+    }
+});
+const consoleLimitsSchema = z.object({
+    toolRounds: z.number().int().min(1).max(32).optional(),
+    toolResultCharacters: z.number().int().min(1_000).max(250_000).optional(),
+}).strict();
+const catenceConfigSchema = z.object({
+    mcp: z.object({
+        rateLimits: z.object({
+            server: nullableRateLimitSchema.optional(),
+            tools: z.record(z.string(), nullableRateLimitSchema).optional(),
+            resources: z.record(z.string(), nullableRateLimitSchema).optional(),
+        }).strict().optional(),
+    }).strict().optional(),
+    providers: z.object({
+        strava: z.object({
+            budget: z.object({
+                maxConcurrentRequests: z.number().int().positive().nullable().optional(),
+                readRequestsPer15Minutes: z.number().int().positive().nullable().optional(),
+                readRequestsPerDay: z.number().int().positive().nullable().optional(),
+            }).strict().optional(),
+        }).strict().optional(),
+    }).strict().optional(),
+    console: z.object({
+        defaultProfile: z.string().min(1).optional(),
+        limits: consoleLimitsSchema.optional(),
+        profiles: z.record(z.string().min(1), consoleProfileSchema).optional(),
+    }).strict().optional(),
+}).strict();
+export async function loadCatenceConfig(paths) {
+    const contents = await readFile(paths.config, 'utf8').catch((error) => {
+        if (error.code === 'ENOENT')
+            return '';
+        throw error;
+    });
+    if (!contents.trim())
+        return {};
+    try {
+        return catenceConfigSchema.parse(JSON.parse(contents));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Invalid Catence config at ${paths.config}: ${message}`);
+    }
+}
+export function configuredMcpRateLimit(config, type, name) {
+    const scoped = config.mcp?.rateLimits?.[type];
+    return scoped?.[name] ?? scoped?.['*'] ?? config.mcp?.rateLimits?.server ?? null;
+}
+//# sourceMappingURL=configuration.js.map

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

@@ -0,0 +1,13 @@
+export type RateLimit = {
+    requests: number;
+    windowSeconds: number;
+};
+export declare class SlidingWindowLimiter {
+    private readonly entries;
+    check(key: string, limit: RateLimit | null, now?: number): {
+        allowed: true;
+    } | {
+        allowed: false;
+        retryAfterSeconds: number;
+    };
+}

package/dist/core/runtime/limiter.js

@@ -0,0 +1,17 @@
+export class SlidingWindowLimiter {
+    entries = new Map();
+    check(key, limit, now = Date.now()) {
+        if (!limit)
+            return { allowed: true };
+        const windowMs = limit.windowSeconds * 1_000;
+        const recent = (this.entries.get(key) ?? []).filter((entry) => entry > now - windowMs);
+        if (recent.length >= limit.requests) {
+            this.entries.set(key, recent);
+            return { allowed: false, retryAfterSeconds: Math.max(1, Math.ceil((recent[0] + windowMs - now) / 1_000)) };
+        }
+        recent.push(now);
+        this.entries.set(key, recent);
+        return { allowed: true };
+    }
+}
+//# sourceMappingURL=limiter.js.map

package/dist/elt/application/demo.d.ts

@@ -0,0 +1,23 @@
+import type { CatencePaths } from '../../contracts/runtime.js';
+export type DemoStoreMetadata = {
+    formatVersion: number;
+    generated: true;
+    seed: number;
+    days: number;
+    startDate: string;
+    endDate: string;
+    createdAt: string;
+};
+export type CreateDemoStoreOptions = {
+    /** Keep the demo small enough for fast evaluation while still supporting trends. */
+    days?: number;
+    seed?: number;
+    /** Primarily useful for deterministic tests and documentation screenshots. */
+    endDate?: string;
+};
+export declare function demoStoreMetadata(paths: CatencePaths): Promise<DemoStoreMetadata | null>;
+/**
+ * Create generated data only in a fresh directory or one already marked as a
+ * Catence demo.  A real data directory is never opened for mutation here.
+ */
+export declare function createDemoStore(paths: CatencePaths, options?: CreateDemoStoreOptions): Promise<Record<string, unknown>>;

package/dist/elt/application/demo.js

@@ -0,0 +1,165 @@
+import { createHash } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { readdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { ensurePaths } from '../../core/runtime/configuration.js';
+import { importRecord } from '../ingestion/importer.js';
+import { CatenceDatabase } from '../storage/database.js';
+const DEMO_MARKER = 'demo-store.json';
+const DEMO_FORMAT_VERSION = 1;
+function markerPath(paths) {
+    return path.join(paths.root, DEMO_MARKER);
+}
+function hash(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function isoDate(date) {
+    return date.toISOString().slice(0, 10);
+}
+function addDays(date, days) {
+    return isoDate(new Date(Date.parse(`${date}T00:00:00.000Z`) + days * 86_400_000));
+}
+function seededRandom(seed) {
+    let state = seed >>> 0;
+    return () => {
+        state += 0x6D2B79F5;
+        let value = state;
+        value = Math.imul(value ^ (value >>> 15), value | 1);
+        value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+        return ((value ^ (value >>> 14)) >>> 0) / 4_294_967_296;
+    };
+}
+function rounded(value, decimals = 0) {
+    const multiplier = 10 ** decimals;
+    return Math.round(value * multiplier) / multiplier;
+}
+function validDate(date) {
+    return /^\d{4}-\d{2}-\d{2}$/.test(date) && !Number.isNaN(Date.parse(`${date}T00:00:00.000Z`));
+}
+async function hasDirectoryContents(directory) {
+    const entries = await readdir(directory).catch((error) => error.code === 'ENOENT' ? [] : Promise.reject(error));
+    return entries.length > 0;
+}
+export async function demoStoreMetadata(paths) {
+    const contents = await readFile(markerPath(paths), 'utf8').catch((error) => error.code === 'ENOENT' ? null : Promise.reject(error));
+    if (!contents)
+        return null;
+    try {
+        const value = JSON.parse(contents);
+        if (value.formatVersion !== DEMO_FORMAT_VERSION || value.generated !== true || !Number.isInteger(value.seed) || !Number.isInteger(value.days)
+            || typeof value.startDate !== 'string' || typeof value.endDate !== 'string' || typeof value.createdAt !== 'string')
+            return null;
+        return value;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Create generated data only in a fresh directory or one already marked as a
+ * Catence demo.  A real data directory is never opened for mutation here.
+ */
+export async function createDemoStore(paths, options = {}) {
+    const days = options.days ?? 90;
+    const seed = options.seed ?? 17;
+    const endDate = options.endDate ?? isoDate(new Date());
+    if (!Number.isInteger(days) || days < 14 || days > 365)
+        throw new Error('Demo days must be an integer between 14 and 365.');
+    if (!Number.isInteger(seed) || seed < 0 || seed > 2_147_483_647)
+        throw new Error('Demo seed must be an integer between 0 and 2147483647.');
+    if (!validDate(endDate))
+        throw new Error('Demo endDate must use YYYY-MM-DD.');
+    const existing = await demoStoreMetadata(paths);
+    if (!existing && await hasDirectoryContents(paths.root)) {
+        throw new Error(`Refusing to overwrite ${paths.root}: it is not a Catence demo store. Choose an empty --data-dir.`);
+    }
+    if (existsSync(paths.database) && existing) {
+        return {
+            created: false,
+            dataDir: paths.root,
+            demoStore: existing,
+            message: 'Existing generated Catence demo store is ready. Its values are synthetic, not personal measurements.',
+        };
+    }
+    const startDate = addDays(endDate, -(days - 1));
+    const random = seededRandom(seed);
+    await ensurePaths(paths);
+    const database = await CatenceDatabase.open(paths);
+    try {
+        const runId = await database.beginRun('garmin', startDate);
+        let previousTrainingLoad = 0;
+        for (let offset = 0; offset < days; offset++) {
+            const date = addDays(startDate, offset);
+            const weeklyLoad = [0, 26, 58, 76, 18, 54, 118][offset % 7];
+            const illness = offset >= Math.floor(days * 0.48) && offset < Math.floor(days * 0.48) + 6;
+            const recovery = Math.sin(offset / 5) * 0.7 + (random() - 0.5) * 0.45 - (illness ? 1.8 : 0);
+            const trainingLoad = Math.max(0, weeklyLoad + (random() - 0.5) * 12 - (illness ? 28 : 0));
+            const restingHeartRate = rounded(52 - recovery * 3.8 + previousTrainingLoad * 0.045 + (random() - 0.5) * 1.3);
+            const hrv = rounded(53 + recovery * 8.5 - previousTrainingLoad * 0.025 + (random() - 0.5) * 2.5);
+            const sleepScore = rounded(76 + recovery * 9 - previousTrainingLoad * 0.025 + (random() - 0.5) * 4);
+            const stress = rounded(34 - recovery * 8 + previousTrainingLoad * 0.04 + (random() - 0.5) * 4);
+            const bodyBattery = rounded(59 + recovery * 17 - previousTrainingLoad * 0.04 + (random() - 0.5) * 5);
+            const sleepIsMissing = offset % 23 === 8 || offset % 31 === 12;
+            const wellnessPayload = {
+                calendarDate: date,
+                restingHeartRate,
+                hrvSDNN: hrv,
+                sleepTimeSeconds: rounded(7.25 * 3_600 + recovery * 450 + (random() - 0.5) * 420),
+                averageStressLevel: stress,
+                bodyBattery,
+                trainingReadinessScore: rounded(62 + recovery * 16 - previousTrainingLoad * 0.04),
+                averageSpO2: rounded(96.4 + recovery * 0.25 + (random() - 0.5) * 0.3, 1),
+                totalSteps: rounded(8_300 + (random() - 0.5) * 3_000),
+            };
+            if (!sleepIsMissing)
+                wellnessPayload.sleepScore = sleepScore;
+            await importRecord(database, runId, {
+                kind: 'source_entity', schemaVersion: 1, provider: 'garmin', entityType: 'daily_health', remoteId: `demo-wellness:${date}`,
+                parentRemoteId: null, occurredOn: date, sourceUpdatedAt: null, rawObjectHash: hash(`demo-wellness:${seed}:${date}`), payload: wellnessPayload, extension: { generated: true },
+            });
+            if (trainingLoad >= 12) {
+                await importRecord(database, runId, {
+                    kind: 'source_entity', schemaVersion: 1, provider: 'garmin', entityType: 'activity', remoteId: `demo-activity:${date}`,
+                    parentRemoteId: null, occurredOn: date, sourceUpdatedAt: null, rawObjectHash: hash(`demo-activity:${seed}:${date}`), extension: { generated: true },
+                    payload: {
+                        activityId: `demo-activity:${date}`,
+                        startTimeGMT: `${date}T10:00:00Z`,
+                        activityType: offset % 3 === 0 ? 'running' : 'road_biking',
+                        activityName: offset % 3 === 0 ? 'Generated endurance run' : 'Generated endurance ride',
+                        distance: rounded(5_000 + trainingLoad * 360),
+                        duration: rounded(1_800 + trainingLoad * 18),
+                        activityTrainingLoad: rounded(trainingLoad, 1),
+                        averageHR: rounded(132 + trainingLoad * 0.12),
+                    },
+                });
+            }
+            previousTrainingLoad = trainingLoad;
+        }
+        await database.finishRun(runId);
+    }
+    finally {
+        await database.close();
+    }
+    const metadata = {
+        formatVersion: DEMO_FORMAT_VERSION,
+        generated: true,
+        seed,
+        days,
+        startDate,
+        endDate,
+        createdAt: new Date().toISOString(),
+    };
+    await writeFile(markerPath(paths), `${JSON.stringify(metadata, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    return {
+        created: true,
+        dataDir: paths.root,
+        demoStore: metadata,
+        message: 'Generated Catence demo store is ready. Its values are synthetic, not personal measurements.',
+        exampleQuestions: [
+            'Use wellness_correlate with metricA training_load, metricB resting_hr_bpm, and scanLags true.',
+            'Use wellness_anomalies to find the deliberately generated multi-metric recovery disruption.',
+            'Use wellness_coverage to inspect intentionally missing sleep-score dates.',
+        ],
+    };
+}
+//# sourceMappingURL=demo.js.map

package/dist/elt/application/management.d.ts

@@ -0,0 +1,25 @@
+import type { CatencePaths } from '../../contracts/runtime.js';
+type SyncProviderChoice = 'intervals' | 'garmin';
+export type ProviderChoice = SyncProviderChoice | 'strava' | 'all';
+export declare function initializeDataStore(paths: CatencePaths): Promise<Record<string, unknown>>;
+export declare function syncData(paths: CatencePaths, provider: ProviderChoice, explicitFrom?: string, advanceCursor?: boolean, refreshActivities?: boolean, backfill?: boolean): Promise<Record<string, unknown>>;
+export declare function retryDataSync(paths: CatencePaths, previousRunId: string): Promise<Record<string, unknown>>;
+export declare function connectStrava(paths: CatencePaths, code: string | undefined, redirectUri: string): Promise<unknown>;
+/** Validate a local OAuth return address before opening a callback listener. */
+export declare function loopbackStravaRedirect(redirectUri: string): URL;
+/**
+ * Complete Strava OAuth through a short-lived loopback callback listener.
+ *
+ * The authorization URL is emitted through the caller so the CLI can keep
+ * stdout machine-readable for the final connection result.
+ */
+export declare function connectStravaWithCallback(paths: CatencePaths, redirectUri: string, onAuthorizationUrl: (url: string) => void, timeoutMs?: number): Promise<unknown>;
+export declare function disconnectStravaAccount(paths: CatencePaths): Promise<{
+    provider: 'strava';
+    disconnected: true;
+}>;
+export declare function linkActivity(paths: CatencePaths, source: string, activity: string): Promise<Record<string, string>>;
+export declare function unlinkActivity(paths: CatencePaths, source: string): Promise<Record<string, string>>;
+export declare function dataStatus(paths: CatencePaths): Promise<Record<string, unknown>>;
+export declare function rebuildRetrievalIndex(paths: CatencePaths): Promise<Record<string, unknown>>;
+export {};

package/dist/elt/application/management.js

@@ -0,0 +1,283 @@
+import { execFile } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { buildRetrievalIndex } from '../../core/retrieval/index.js';
+import { defaultFromDate, ensurePaths, requireIntervalsConfig } from '../../core/runtime/configuration.js';
+import { importJsonl } from '../ingestion/importer.js';
+import { IntervalsExtractor } from '../ingestion/providers/intervals.js';
+import { completeStravaAuthorization, disconnectStrava, getStravaAuthorizationUrl, syncStravaGear } from '../ingestion/providers/strava/service.js';
+import { setManualActivityLink, unlinkActivitySource } from '../normalization/activities/linking.js';
+import { CatenceDatabase } from '../storage/database.js';
+import { withDataWriteLock } from '../storage/write-lock.js';
+const execFileAsync = promisify(execFile);
+function packageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+}
+async function syncProvider(database, paths, provider, options) {
+    const explicitWindow = options.explicitFrom ? { fromDate: options.explicitFrom, toDate: options.toDate, source: 'explicit' } : null;
+    const uncoveredExplicitWindow = async (cursorName) => {
+        if (!explicitWindow)
+            return null;
+        if (!options.backfill)
+            return explicitWindow;
+        const window = await database.resolveBackfillWindow(provider, cursorName, explicitWindow.fromDate, explicitWindow.toDate, options.refreshActivities);
+        return window ? { ...window, source: 'explicit' } : null;
+    };
+    const dailyWindow = explicitWindow ? await uncoveredExplicitWindow('daily') : await database.resolveIncrementalWindow(provider, 'daily', options.toDate, defaultFromDate(), 3);
+    const activityWindow = explicitWindow ? await uncoveredExplicitWindow('activities') : await database.resolveIncrementalWindow(provider, 'activities', options.toDate, defaultFromDate(), 14);
+    const hasProviderWork = provider === 'intervals' ? activityWindow !== null : dailyWindow !== null || activityWindow !== null;
+    if (!hasProviderWork) {
+        return {
+            runId: null, provider, fromDate: null,
+            dailyFromDate: dailyWindow?.fromDate ?? null, dailyToDate: dailyWindow?.toDate ?? null,
+            activityFromDate: activityWindow?.fromDate ?? null, activityToDate: activityWindow?.toDate ?? null,
+            toDate: options.toDate, dailyCursorSource: dailyWindow?.source ?? null, activityCursorSource: activityWindow?.source ?? null,
+            refreshedActivities: provider === 'garmin' && options.refreshActivities, skipped: true,
+        };
+    }
+    const fromDate = [dailyWindow?.fromDate, activityWindow?.fromDate].filter((date) => Boolean(date)).sort()[0];
+    const runId = await database.beginRun(provider, fromDate);
+    let extractionStarted = false;
+    try {
+        if (provider === 'intervals') {
+            const config = requireIntervalsConfig();
+            extractionStarted = true;
+            await new IntervalsExtractor(database, paths, config.apiKey, config.athleteId).sync(runId, activityWindow, !options.backfill || options.refreshActivities);
+        }
+        else {
+            const output = path.join(paths.staging, 'garmin', `${runId}.jsonl`);
+            const knownActivities = path.join(paths.staging, 'garmin', `${runId}.known-activities.json`);
+            await mkdir(path.dirname(knownActivities), { recursive: true });
+            // An explicit refresh intentionally provides no known hashes, causing
+            // the staging worker to re-fetch Garmin activity details, files, and
+            // streams even when the list-summary hash is unchanged.
+            await writeFile(knownActivities, JSON.stringify(options.refreshActivities ? {} : await database.knownActivitySummaryHashes('garmin')));
+            extractionStarted = true;
+            const arguments_ = ['run', 'python', '-m', 'python.catence.providers.garmin.cli', '--from', fromDate, '--to', options.toDate, '--data-dir', paths.root, '--output', output, '--run-id', runId, '--known-activities', knownActivities];
+            if (dailyWindow)
+                arguments_.push('--daily-from', dailyWindow.fromDate, '--daily-to', dailyWindow.toDate);
+            else
+                arguments_.push('--skip-daily');
+            if (activityWindow)
+                arguments_.push('--activity-from', activityWindow.fromDate, '--activity-to', activityWindow.toDate);
+            else
+                arguments_.push('--skip-activities');
+            if (options.backfill && !options.refreshActivities)
+                arguments_.push('--historical-only');
+            await execFileAsync('uv', arguments_, {
+                cwd: packageRoot(),
+                env: { ...process.env, UV_PROJECT_ENVIRONMENT: process.env.UV_PROJECT_ENVIRONMENT ?? path.join(paths.root, 'python-venv') },
+            });
+            if (!existsSync(output))
+                throw new Error('Garmin staging worker completed without writing a JSONL manifest.');
+            await importJsonl(database, runId, output);
+        }
+    }
+    catch (error) {
+        await database.addError(runId, provider, 'sync', null, error instanceof Error ? error.message : String(error), true);
+    }
+    finally {
+        await database.finishRun(runId);
+    }
+    if (options.advanceCursor && !options.explicitFrom && extractionStarted) {
+        await database.advanceIncrementalCursor(provider, 'daily', runId, options.toDate, 3);
+        await database.advanceIncrementalCursor(provider, 'activities', runId, options.toDate, 14);
+    }
+    return {
+        runId, provider, fromDate,
+        dailyFromDate: dailyWindow?.fromDate ?? null, dailyToDate: dailyWindow?.toDate ?? null,
+        activityFromDate: activityWindow?.fromDate ?? null, activityToDate: activityWindow?.toDate ?? null,
+        toDate: options.toDate, dailyCursorSource: dailyWindow?.source ?? null, activityCursorSource: activityWindow?.source ?? null,
+        refreshedActivities: provider === 'garmin' && options.refreshActivities, skipped: false,
+    };
+}
+export async function initializeDataStore(paths) {
+    await ensurePaths(paths);
+    const database = await CatenceDatabase.open(paths);
+    await database.close();
+    return { dataDir: paths.root, database: paths.database, message: 'Catence data store is ready. Run sync to import provider data.' };
+}
+export async function syncData(paths, provider, explicitFrom, advanceCursor = true, refreshActivities = false, backfill = false) {
+    await ensurePaths(paths);
+    if (provider === 'strava')
+        return { provider, result: await syncStravaGear(paths) };
+    const database = await CatenceDatabase.open(paths);
+    try {
+        const providers = provider === 'all' ? ['intervals', 'garmin'] : [provider];
+        const toDate = new Date().toISOString().slice(0, 10);
+        const runs = [];
+        for (const source of providers)
+            runs.push(await syncProvider(database, paths, source, { explicitFrom, toDate, advanceCursor, refreshActivities, backfill }));
+        return { runIds: runs.flatMap((run) => run.runId ? [run.runId] : []), runs };
+    }
+    finally {
+        await database.close();
+    }
+}
+export async function retryDataSync(paths, previousRunId) {
+    await ensurePaths(paths);
+    const database = await CatenceDatabase.open(paths);
+    try {
+        const previous = await database.getRun(previousRunId);
+        if (!previous)
+            throw new Error(`No sync run found for ${previousRunId}.`);
+        if (previous.provider === 'strava')
+            throw new Error('Retry Strava gear sync with `catence-data sync --provider strava`.');
+        const run = await syncProvider(database, paths, previous.provider, { explicitFrom: previous.from_date, toDate: new Date().toISOString().slice(0, 10), advanceCursor: false, refreshActivities: false, backfill: false });
+        return { retriedRun: previousRunId, runId: run.runId, run };
+    }
+    finally {
+        await database.close();
+    }
+}
+export async function connectStrava(paths, code, redirectUri) {
+    return code ? completeStravaAuthorization(paths, code, redirectUri) : getStravaAuthorizationUrl(paths, redirectUri);
+}
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+/** Validate a local OAuth return address before opening a callback listener. */
+export function loopbackStravaRedirect(redirectUri) {
+    let parsed;
+    try {
+        parsed = new URL(redirectUri);
+    }
+    catch {
+        throw new Error('--redirect-uri must be an absolute URL.');
+    }
+    if (parsed.protocol !== 'http:' || !LOOPBACK_HOSTS.has(parsed.hostname) || !parsed.port) {
+        throw new Error('--callback requires an http loopback --redirect-uri with an explicit port.');
+    }
+    return parsed;
+}
+function readStravaCallback(requestUrl, callback) {
+    const received = new URL(requestUrl ?? '/', callback);
+    if (received.pathname !== callback.pathname)
+        throw new Error('Strava returned to an unexpected callback path.');
+    const error = received.searchParams.get('error');
+    if (error)
+        throw new Error(`Strava authorization was declined or failed: ${error}.`);
+    const code = received.searchParams.get('code');
+    if (!code)
+        throw new Error('Strava callback did not include an authorization code.');
+    return { code, state: received.searchParams.get('state') };
+}
+function callbackPage(response, success) {
+    response.writeHead(success ? 200 : 400, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+    response.end(success
+        ? '<!doctype html><title>Catence connected</title><p>Strava is connected to Catence. You can close this tab.</p>'
+        : '<!doctype html><title>Catence authorization failed</title><p>Strava authorization did not complete. Return to the terminal for details.</p>');
+}
+/**
+ * Complete Strava OAuth through a short-lived loopback callback listener.
+ *
+ * The authorization URL is emitted through the caller so the CLI can keep
+ * stdout machine-readable for the final connection result.
+ */
+export async function connectStravaWithCallback(paths, redirectUri, onAuthorizationUrl, timeoutMs = 300_000) {
+    const callback = loopbackStravaRedirect(redirectUri);
+    if (!Number.isInteger(timeoutMs) || timeoutMs < 1_000)
+        throw new Error('OAuth callback timeout must be at least one second.');
+    const expectedState = randomUUID();
+    const listener = createServer();
+    const callbackResult = new Promise((resolve, reject) => {
+        listener.once('error', reject);
+        listener.on('request', (request, response) => {
+            if (request.method !== 'GET') {
+                response.writeHead(405, { allow: 'GET' }).end();
+                return;
+            }
+            try {
+                const result = readStravaCallback(request.url, callback);
+                if (result.state !== expectedState)
+                    throw new Error('Strava callback state did not match this authorization request.');
+                callbackPage(response, true);
+                resolve(result);
+            }
+            catch (error) {
+                callbackPage(response, false);
+                reject(error);
+            }
+        });
+    });
+    try {
+        await new Promise((resolve, reject) => {
+            listener.once('error', reject);
+            listener.listen(Number(callback.port), callback.hostname.replace(/^\[|\]$/g, ''), () => {
+                listener.off('error', reject);
+                resolve();
+            });
+        });
+        const authorization = await getStravaAuthorizationUrl(paths, callback.toString());
+        if (!authorization.authorizationUrl)
+            throw new Error('Strava did not return an authorization URL.');
+        const authorizationUrl = new URL(authorization.authorizationUrl);
+        authorizationUrl.searchParams.set('state', expectedState);
+        onAuthorizationUrl(authorizationUrl.toString());
+        const timed = Promise.race([
+            callbackResult,
+            new Promise((_, reject) => setTimeout(() => reject(new Error('Timed out waiting for the Strava callback.')), timeoutMs)),
+        ]);
+        const { code } = await timed;
+        return completeStravaAuthorization(paths, code, callback.toString());
+    }
+    finally {
+        if (listener.listening)
+            await new Promise((resolve) => listener.close(() => resolve()));
+    }
+}
+export async function disconnectStravaAccount(paths) {
+    await disconnectStrava(paths);
+    return { provider: 'strava', disconnected: true };
+}
+export async function linkActivity(paths, source, activity) {
+    await ensurePaths(paths);
+    await withDataWriteLock(paths, async () => {
+        const database = await CatenceDatabase.open(paths);
+        try {
+            await setManualActivityLink(database, source, activity);
+        }
+        finally {
+            await database.close();
+        }
+    });
+    return { source, activity, method: 'manual' };
+}
+export async function unlinkActivity(paths, source) {
+    await ensurePaths(paths);
+    await withDataWriteLock(paths, async () => {
+        const database = await CatenceDatabase.open(paths);
+        try {
+            await unlinkActivitySource(database, source);
+        }
+        finally {
+            await database.close();
+        }
+    });
+    return { source, method: 'source' };
+}
+export async function dataStatus(paths) {
+    await ensurePaths(paths);
+    const database = await CatenceDatabase.open(paths);
+    try {
+        return await database.status();
+    }
+    finally {
+        await database.close();
+    }
+}
+export async function rebuildRetrievalIndex(paths) {
+    if (!existsSync(paths.database))
+        throw new Error('No Catence database exists yet. Complete a sync before building the retrieval index.');
+    const database = await CatenceDatabase.open(paths);
+    try {
+        return await buildRetrievalIndex(database);
+    }
+    finally {
+        await database.close();
+    }
+}
+//# sourceMappingURL=management.js.map

package/dist/elt/ingestion/importer.d.ts

@@ -0,0 +1,8 @@
+import type { CatenceDatabase } from '../storage/database.js';
+import { type StagingRecord } from '../../contracts/staging.js';
+export declare function importRecord(database: CatenceDatabase, runId: string, record: StagingRecord): Promise<void>;
+export declare function importJsonl(database: CatenceDatabase, runId: string, filePath: string): Promise<number>;
+export declare function importSingleStagingFile(database: CatenceDatabase, runId: string, filePath: string): Promise<number>;
+export declare function queueWorkItem(database: CatenceDatabase, runId: string, provider: 'intervals' | 'garmin' | 'strava', endpoint: string, remoteId: string | null, scope: unknown): Promise<string>;
+export declare function completeWorkItem(database: CatenceDatabase, itemId: string): Promise<void>;
+export declare function failWorkItem(database: CatenceDatabase, itemId: string, message: string): Promise<void>;