catence 0.0.0 → 0.2.0-beta.1

package/dist/core/runtime/catalog.js

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

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

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import type { CatencePaths } from '../../contracts/runtime.js';
+export type { CatencePaths } from '../../contracts/runtime.js';
+export declare function resolvePaths(root?: string): CatencePaths;
+export declare function ensurePaths(paths: CatencePaths): Promise<void>;
+export declare function defaultFromDate(now?: Date): string;
+export declare function requireIntervalsConfig(environment?: NodeJS.ProcessEnv): {
+    apiKey: string;
+    athleteId: string;
+};
+declare const rateLimitSchema: z.ZodObject<{
+    requests: z.ZodNumber;
+    windowSeconds: z.ZodNumber;
+}, z.core.$strict>;
+declare const catenceConfigSchema: z.ZodObject<{
+    mcp: z.ZodOptional<z.ZodObject<{
+        rateLimits: z.ZodOptional<z.ZodObject<{
+            server: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+                requests: z.ZodNumber;
+                windowSeconds: z.ZodNumber;
+            }, z.core.$strict>>>;
+            tools: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
+                requests: z.ZodNumber;
+                windowSeconds: z.ZodNumber;
+            }, z.core.$strict>>>>;
+            resources: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNullable<z.ZodObject<{
+                requests: z.ZodNumber;
+                windowSeconds: z.ZodNumber;
+            }, z.core.$strict>>>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    providers: z.ZodOptional<z.ZodObject<{
+        strava: z.ZodOptional<z.ZodObject<{
+            budget: z.ZodOptional<z.ZodObject<{
+                maxConcurrentRequests: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                readRequestsPer15Minutes: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+                readRequestsPerDay: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    console: z.ZodOptional<z.ZodObject<{
+        defaultProfile: z.ZodOptional<z.ZodString>;
+        limits: z.ZodOptional<z.ZodObject<{
+            toolRounds: z.ZodOptional<z.ZodNumber>;
+            toolResultCharacters: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>;
+        profiles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            label: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            models: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                label: z.ZodOptional<z.ZodString>;
+                model: z.ZodString;
+            }, z.core.$strict>>>;
+            defaultModel: z.ZodOptional<z.ZodString>;
+            defaultReasoningEffort: z.ZodOptional<z.ZodEnum<{
+                minimal: "minimal";
+                low: "low";
+                medium: "medium";
+                high: "high";
+                xhigh: "xhigh";
+            }>>;
+            apiKeyEnv: z.ZodOptional<z.ZodString>;
+            apiBaseEnv: z.ZodOptional<z.ZodString>;
+            apiVersionEnv: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CatenceConfig = z.infer<typeof catenceConfigSchema>;
+export type ConfigRateLimit = z.infer<typeof rateLimitSchema>;
+export declare function loadCatenceConfig(paths: CatencePaths): Promise<CatenceConfig>;
+export declare function configuredMcpRateLimit(config: CatenceConfig, type: 'tools' | 'resources', name: string): ConfigRateLimit | null;

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(environment = process.env) {
+    const apiKey = environment.INTERVALS_API_KEY;
+    if (!apiKey)
+        throw new Error('INTERVALS_API_KEY is required for an Intervals sync.');
+    return { apiKey, athleteId: environment.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/core/runtime/secrets.d.ts

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

package/dist/core/runtime/secrets.js

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

package/dist/elt/application/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 {};