catence 0.2.0-beta.8 → 0.2.0

package/dist/core/runtime/secrets.js

@@ -42,27 +42,65 @@ export async function setAthleteSecret(paths, provider, field, value) {
     await rename(temporary, destination);
     await chmod(destination, 0o600);
 }
+function isTruthyEnvValue(value) {
+    if (!value)
+        return false;
+    return ['1', 'true', 'yes', 'on'].includes(value.trim().toLowerCase());
+}
+function isGenericEnvFallbackAllowed(base) {
+    const direct = base.CATENCE_ALLOW_ENV_SECRETS ?? base.CATENCE_SECRETS_FROM_ENV ?? process.env.CATENCE_ALLOW_ENV_SECRETS ?? process.env.CATENCE_SECRETS_FROM_ENV;
+    return isTruthyEnvValue(direct);
+}
+function athleteEnvPrefix(paths) {
+    const athleteId = path.basename(path.dirname(paths.secrets));
+    const normalized = athleteId.replace(/[^a-zA-Z0-9]/g, '_').toUpperCase();
+    return `CATENCE_ATHLETE_${normalized}_`;
+}
+function resolveWithEnvFallback(fileValue, envName, perAthletePrefix, base, allowGeneric) {
+    if (fileValue)
+        return fileValue;
+    const perAthleteName = `${perAthletePrefix}${envName}`;
+    const perAthleteValue = base[perAthleteName] ?? process.env[perAthleteName];
+    if (perAthleteValue)
+        return perAthleteValue;
+    if (!allowGeneric)
+        return undefined;
+    const genericValue = base[envName] ?? process.env[envName];
+    if (genericValue)
+        return genericValue;
+    return undefined;
+}
 /** 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 };
+    const allowGenericEnv = isGenericEnvFallbackAllowed(base);
+    const perAthletePrefix = athleteEnvPrefix(paths);
     // Never let credentials inherited by the shared process leak into an
-    // athlete store that has not explicitly configured that provider.
+    // athlete store that has not explicitly configured that provider, unless
+    // the operator has opted in via CATENCE_ALLOW_ENV_SECRETS or is using a
+    // per-athlete scoped variable (CATENCE_ATHLETE_<ID>_GARMIN_EMAIL etc.).
     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;
+    const garminEmail = resolveWithEnvFallback(secrets.garmin?.email, 'GARMIN_EMAIL', perAthletePrefix, base, allowGenericEnv);
+    const garminPassword = resolveWithEnvFallback(secrets.garmin?.password, 'GARMIN_PASSWORD', perAthletePrefix, base, allowGenericEnv);
+    const intervalsApiKey = resolveWithEnvFallback(secrets.intervals?.apiKey, 'INTERVALS_API_KEY', perAthletePrefix, base, allowGenericEnv);
+    const intervalsAthleteId = resolveWithEnvFallback(secrets.intervals?.athleteId, 'INTERVALS_ATHLETE_ID', perAthletePrefix, base, allowGenericEnv);
+    const stravaClientId = resolveWithEnvFallback(secrets.strava?.clientId, 'STRAVA_CLIENT_ID', perAthletePrefix, base, allowGenericEnv);
+    const stravaClientSecret = resolveWithEnvFallback(secrets.strava?.clientSecret, 'STRAVA_CLIENT_SECRET', perAthletePrefix, base, allowGenericEnv);
+    if (garminEmail)
+        environment.GARMIN_EMAIL = garminEmail;
+    if (garminPassword)
+        environment.GARMIN_PASSWORD = garminPassword;
+    if (intervalsApiKey)
+        environment.INTERVALS_API_KEY = intervalsApiKey;
+    if (intervalsAthleteId)
+        environment.INTERVALS_ATHLETE_ID = intervalsAthleteId;
+    if (stravaClientId)
+        environment.STRAVA_CLIENT_ID = stravaClientId;
+    if (stravaClientSecret)
+        environment.STRAVA_CLIENT_SECRET = stravaClientSecret;
     return environment;
 }
 //# sourceMappingURL=secrets.js.map

package/dist/elt/application/detached-sync.d.ts

@@ -0,0 +1,50 @@
+import { type SpawnOptions } from 'node:child_process';
+import type { CatencePaths } from '../../contracts/runtime.js';
+export declare const DETACHED_SYNC_PROVIDERS: readonly ["intervals", "garmin", "strava", "all"];
+export type DetachedSyncProvider = (typeof DETACHED_SYNC_PROVIDERS)[number];
+export type DetachedSyncRequest = {
+    paths: CatencePaths;
+    athleteId: string;
+    provider?: DetachedSyncProvider;
+    from?: string;
+    refresh?: boolean;
+    /**
+     * The `--home` value the detached `catence-data` child must receive.
+     *
+     * Catalog deployments pass the catalog root here: `paths` points at the
+     * resolved athlete store (for locks/logs), but the child resolves
+     * `--athlete` within a catalog, so pointing `--home` at the store itself
+     * makes it fail with the legacy-store guard. Standalone stores omit this
+     * and default to `paths.root`.
+     */
+    cliHome?: string;
+};
+export type DetachedSyncHandle = {
+    started: true;
+    athleteId: string;
+    provider: DetachedSyncProvider;
+    logFile: string;
+};
+/** Raised when another sync run is already active for this store. */
+export declare class DetachedSyncBusyError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+/** Minimal structural spawner so tests can inject a fake child process. */
+export type DetachedSyncSpawner = (command: string, arguments_: readonly string[], options: SpawnOptions) => {
+    unref(): void;
+};
+/**
+ * Spawn one detached `catence-data sync` process for an athlete store and
+ * return immediately.
+ *
+ * The child outlives this process (SSH deaths, Console restarts), logs to a
+ * file under the catalog home, and is guarded by the same live-progress
+ * heartbeat check the progress tools use. The guard and the spawn are not
+ * atomic; the single-writer DuckDB lock remains the authoritative guard, so a
+ * racing second child fails cleanly in its own log file.
+ */
+export declare function startDetachedSync(request: DetachedSyncRequest, dependencies?: {
+    now?: () => Date;
+    spawnProcess?: DetachedSyncSpawner;
+}): Promise<DetachedSyncHandle>;

package/dist/elt/application/detached-sync.js

@@ -0,0 +1,99 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { open, mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { STALE_RUN_TIMEOUT_MS } from '../../contracts/progress.js';
+import { syncProgress } from './management.js';
+export const DETACHED_SYNC_PROVIDERS = ['intervals', 'garmin', 'strava', 'all'];
+/** Raised when another sync run is already active for this store. */
+export class DetachedSyncBusyError extends Error {
+    runId;
+    constructor(runId) {
+        super(`A Catence sync run is already active (${runId}). Watch it with the progress tools instead of starting another.`);
+        this.name = 'DetachedSyncBusyError';
+        this.runId = runId;
+    }
+}
+/**
+ * Resolve how to launch the `catence-data` CLI next to this module.
+ *
+ * Built installs: both modules live under dist/, so the child is plain
+ * `node …/dist/interfaces/cli/main.js`. Source checkouts run through tsx,
+ * where the same relative path points at a nonexistent `.js` file — there the
+ * TypeScript entry is launched through the checkout's local tsx binary
+ * instead. Tests inject their own spawner and never reach this resolution.
+ */
+function cliInvocation() {
+    const moduleDirectory = path.dirname(fileURLToPath(import.meta.url));
+    const builtEntry = path.resolve(moduleDirectory, '../../interfaces/cli/main.js');
+    if (existsSync(builtEntry))
+        return { command: process.execPath, entry: builtEntry };
+    const sourceEntry = path.resolve(moduleDirectory, '../../interfaces/cli/main.ts');
+    const tsxBinary = path.resolve(moduleDirectory, '../../../node_modules/.bin/tsx');
+    if (!existsSync(sourceEntry) || !existsSync(tsxBinary)) {
+        throw new Error(`Could not locate the catence-data CLI entry (tried ${builtEntry} and ${sourceEntry}). Install the package or run from a checkout with node_modules present.`);
+    }
+    return { command: tsxBinary, entry: sourceEntry };
+}
+function assertValidRequest(request) {
+    if (!request.athleteId || !/^[a-z][a-z0-9-]{0,62}$/.test(request.athleteId)) {
+        throw new Error('athleteId is required and must be a lowercase athlete identifier.');
+    }
+    if (request.provider !== undefined && !DETACHED_SYNC_PROVIDERS.includes(request.provider)) {
+        throw new Error('provider must be intervals, garmin, strava, or all.');
+    }
+    if (request.from !== undefined && !/^\d{4}-\d{2}-\d{2}$/.test(request.from)) {
+        throw new Error('from must use YYYY-MM-DD.');
+    }
+}
+/**
+ * Spawn one detached `catence-data sync` process for an athlete store and
+ * return immediately.
+ *
+ * The child outlives this process (SSH deaths, Console restarts), logs to a
+ * file under the catalog home, and is guarded by the same live-progress
+ * heartbeat check the progress tools use. The guard and the spawn are not
+ * atomic; the single-writer DuckDB lock remains the authoritative guard, so a
+ * racing second child fails cleanly in its own log file.
+ */
+export async function startDetachedSync(request, dependencies = {}) {
+    assertValidRequest(request);
+    const provider = request.provider ?? 'all';
+    const snapshot = await syncProgress(request.paths);
+    // Belt-and-braces: syncProgress already age-filters stale runs, so this
+    // predicate only re-asserts the sidecar contract at the decision point —
+    // a heartbeat older than the stale timeout must never block a new run.
+    const activeRun = snapshot.running.find((state) => {
+        const ageMs = Date.now() - Date.parse(state.heartbeatAt);
+        return Number.isFinite(ageMs) && ageMs <= STALE_RUN_TIMEOUT_MS;
+    });
+    if (activeRun)
+        throw new DetachedSyncBusyError(activeRun.runId);
+    const stamp = (dependencies.now ?? (() => new Date()))().toISOString().replace(/[:.]/g, '-');
+    const logFile = path.join(request.paths.root, 'logs', `sync-${request.athleteId}-${stamp}.log`);
+    await mkdir(path.dirname(logFile), { recursive: true });
+    await writeFile(logFile, `[${new Date().toISOString()}] catence-data --athlete ${request.athleteId} sync --provider ${provider}${request.from ? ` --from ${request.from}` : ''}${request.refresh ? ' --refresh' : ''}\n`, 'utf8');
+    const arguments_ = [cliInvocation().entry, '--home', request.cliHome ?? request.paths.root, '--athlete', request.athleteId, 'sync', '--provider', provider];
+    if (request.from)
+        arguments_.push('--from', request.from);
+    if (request.refresh)
+        arguments_.push('--refresh');
+    // The file handle stays open only for the spawn; the detached child holds
+    // its own duplicate of the descriptor afterwards.
+    const logHandle = await open(logFile, 'a');
+    try {
+        const spawnProcess = dependencies.spawnProcess ?? spawn;
+        const child = spawnProcess(cliInvocation().command, arguments_, {
+            detached: true,
+            stdio: ['ignore', logHandle.fd, logHandle.fd],
+            env: process.env,
+        });
+        child.unref();
+    }
+    finally {
+        await logHandle.close();
+    }
+    return { started: true, athleteId: request.athleteId, provider, logFile };
+}
+//# sourceMappingURL=detached-sync.js.map

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

@@ -1,4 +1,5 @@
 import type { CatencePaths } from '../../contracts/runtime.js';
+import { type SyncProgressSnapshot } from '../../contracts/progress.js';
 type SyncProviderChoice = 'intervals' | 'garmin';
 export type ProviderChoice = SyncProviderChoice | 'strava' | 'all';
 export declare function initializeDataStore(paths: CatencePaths): Promise<Record<string, unknown>>;
@@ -21,5 +22,19 @@ export declare function disconnectStravaAccount(paths: CatencePaths): Promise<{
 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 syncProgress(paths: CatencePaths): Promise<SyncProgressSnapshot>;
 export declare function rebuildRetrievalIndex(paths: CatencePaths): Promise<Record<string, unknown>>;
+export declare function importStagedFile(paths: CatencePaths, provider: ProviderChoice, filePath: string): Promise<Record<string, unknown>>;
+export declare function resolveExtractionErrors(paths: CatencePaths, opts?: {
+    runIds?: string[];
+    provider?: string;
+    before?: string;
+    all?: boolean;
+}): Promise<Record<string, unknown>>;
+/**
+ * Re-run normalization over already-captured nutrition entities without
+ * contacting any provider. Idempotent upserts let a fixed normalizer backfill
+ * previously mis-parsed nutrition_days/nutrition_items from stored payloads.
+ */
+export declare function reimportNutrition(paths: CatencePaths): Promise<Record<string, unknown>>;
 export {};