catence 0.2.0-beta.2 → 0.2.0-beta.21

package/dist/core/runtime/opencode-go.js

@@ -0,0 +1,246 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { catenceConfigSchema } from './configuration.js';
+export const OPENCODE_GO_DEFAULT_BASE_URL = 'https://opencode.ai/zen/go/v1';
+export const OPENCODE_GO_API_KEY_ENV = 'OPENCODE_GO_API_KEY';
+export const OPENCODE_GO_API_BASE_ENV = 'OPENCODE_GO_API_BASE';
+export const OPENCODE_GO_MESSAGES_API_BASE_ENV = 'OPENCODE_GO_MESSAGES_API_BASE';
+// LiteLLM appends a fixed suffix to the profile base URL per provider, so the
+// three APIs need different prefixes and two base URLs:
+//   openai/<id>             -> {base}/chat/completions
+//   openai/responses/<id>   -> {base}/responses
+//   anthropic/<id>          -> {base minus /v1}/v1/messages
+const RESPONSES_MODELS = new Set(['grok-4.5', 'gpt-5.6-luna']);
+const MESSAGES_MODELS = new Set([
+    'minimax-m2.5',
+    'minimax-m2.7',
+    'minimax-m3',
+    'qwen3.5-plus',
+    'qwen3.6-plus',
+    'qwen3.7-plus',
+    'qwen3.7-max',
+    'qwen3.8-max',
+]);
+const BRAND_NAMES = new Map([
+    ['deepseek', 'DeepSeek'],
+    ['glm', 'GLM'],
+    ['gpt', 'GPT'],
+    ['grok', 'Grok'],
+    ['hy3', 'Hy3'],
+    ['kimi', 'Kimi'],
+    ['mimo', 'MiMo'],
+    ['minimax', 'MiniMax'],
+    ['qwen', 'Qwen'],
+]);
+const CHAT_PROFILE_ID = 'opencode-go';
+const MESSAGES_PROFILE_ID = 'opencode-go-messages';
+/** Live model ids plus trusted routing metadata ("live discovery + trusted metadata"). */
+export function classifyOpenCodeGoModel(id) {
+    if (RESPONSES_MODELS.has(id))
+        return { route: 'responses', guessed: false };
+    if (MESSAGES_MODELS.has(id))
+        return { route: 'messages', guessed: false };
+    if (/^(grok-|gpt-)/.test(id))
+        return { route: 'responses', guessed: true };
+    if (/^(minimax-|qwen)/.test(id))
+        return { route: 'messages', guessed: true };
+    return { route: 'chat', guessed: false };
+}
+function modelReference(id, route) {
+    if (route === 'responses')
+        return `openai/responses/${id}`;
+    if (route === 'messages')
+        return `anthropic/${id}`;
+    return `openai/${id}`;
+}
+function labelFor(id) {
+    return id
+        .split('-')
+        .map((segment) => BRAND_NAMES.get(segment) ?? segment.charAt(0).toUpperCase() + segment.slice(1))
+        .join(' ');
+}
+/**
+ * Build the two ready-made Console profiles from live model ids.
+ *
+ * The public `GET /models` endpoint returns only ids, not which API each model
+ * needs, so routing comes from the trusted table intersected with the live
+ * list; prefix-guessed routes are reported so callers can warn.
+ */
+export function buildOpenCodeGoConsoleProfiles(modelIds, baseUrl = OPENCODE_GO_DEFAULT_BASE_URL) {
+    const groups = { chat: [], responses: [], messages: [] };
+    const guessedRoutes = [];
+    for (const id of modelIds) {
+        if (!id)
+            continue;
+        const { route, guessed } = classifyOpenCodeGoModel(id);
+        groups[route].push(id);
+        if (guessed)
+            guessedRoutes.push(`${id} -> ${route}`);
+    }
+    for (const route of Object.keys(groups))
+        groups[route].sort();
+    const chatModels = {};
+    for (const id of [...groups.chat, ...groups.responses]) {
+        chatModels[id] = { label: labelFor(id), model: modelReference(id, groups.chat.includes(id) ? 'chat' : 'responses') };
+    }
+    const messagesModels = {};
+    for (const id of groups.messages) {
+        messagesModels[id] = { label: labelFor(id), model: modelReference(id, 'messages') };
+    }
+    const chatDefault = groups.chat[0] ?? groups.responses[0];
+    const profiles = {
+        [CHAT_PROFILE_ID]: {
+            label: 'OpenCode Go',
+            ...(chatDefault ? { defaultModel: chatDefault } : {}),
+            models: chatModels,
+            apiKeyEnv: OPENCODE_GO_API_KEY_ENV,
+            apiBaseEnv: OPENCODE_GO_API_BASE_ENV,
+        },
+    };
+    if (groups.messages.length) {
+        profiles[MESSAGES_PROFILE_ID] = {
+            label: 'OpenCode Go (Anthropic)',
+            defaultModel: groups.messages[0],
+            models: messagesModels,
+            apiKeyEnv: OPENCODE_GO_API_KEY_ENV,
+            apiBaseEnv: OPENCODE_GO_MESSAGES_API_BASE_ENV,
+        };
+    }
+    return {
+        profiles,
+        defaultProfile: CHAT_PROFILE_ID,
+        counts: { chat: groups.chat.length, responses: groups.responses.length, messages: groups.messages.length },
+        guessedRoutes,
+    };
+}
+export async function fetchOpenCodeGoModelIds(baseUrl = OPENCODE_GO_DEFAULT_BASE_URL) {
+    const modelsUrl = `${baseUrl.replace(/\/$/, '')}/models`;
+    let response;
+    try {
+        response = await fetch(modelsUrl, { headers: { accept: 'application/json' } });
+    }
+    catch (error) {
+        throw new Error(`Could not reach ${modelsUrl}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok)
+        throw new Error(`GET ${modelsUrl} returned HTTP ${response.status}.`);
+    const payload = (await response.json());
+    const ids = (payload.data ?? []).map((entry) => entry.id).filter((id) => typeof id === 'string' && Boolean(id));
+    if (!ids.length)
+        throw new Error(`GET ${modelsUrl} returned no models.`);
+    return ids;
+}
+async function readConfigRoot(configPath) {
+    try {
+        const root = JSON.parse(await readFile(configPath, 'utf8'));
+        if (typeof root !== 'object' || root === null || Array.isArray(root)) {
+            throw new Error(`${configPath} must contain a JSON object.`);
+        }
+        return root;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw error;
+    }
+}
+/** Per-model fields a human may have customized after the initial discovery. */
+function preservedModelFields(previous) {
+    if (typeof previous !== 'object' || previous === null || Array.isArray(previous))
+        return {};
+    const raw = previous;
+    const preserved = {};
+    if (typeof raw.label === 'string' && raw.label.trim())
+        preserved.label = raw.label;
+    if (typeof raw.reasoningEffort === 'string')
+        preserved.reasoningEffort = raw.reasoningEffort;
+    if (raw.variants !== undefined)
+        preserved.variants = raw.variants;
+    return preserved;
+}
+/**
+ * Fetch the live OpenCode Go catalog and merge the two Console profiles into
+ * `configPath`, preserving every other section plus existing console fields
+ * (`limits`, other profiles) and the existing `defaultProfile` unless
+ * `setDefault` is passed. Model routing (`model`) is refreshed from the live
+ * catalog, per-model customizations (custom label, `reasoningEffort`,
+ * `variants`) survive for models still in the catalog, and models that
+ * disappeared upstream are pruned so the Console never offers stale routes.
+ * The written file is re-validated with the same strict schema the runtime
+ * applies on load, then replaced atomically.
+ */
+export async function mergeOpenCodeGoConsoleProfiles(options) {
+    const baseUrl = options.baseUrl ?? OPENCODE_GO_DEFAULT_BASE_URL;
+    const modelIds = await fetchOpenCodeGoModelIds(baseUrl);
+    const built = buildOpenCodeGoConsoleProfiles(modelIds, baseUrl);
+    const root = await readConfigRoot(options.configPath);
+    const existingConsole = typeof root.console === 'object' && root.console !== null && !Array.isArray(root.console)
+        ? root.console
+        : {};
+    const existingProfiles = typeof existingConsole.profiles === 'object' && existingConsole.profiles !== null && !Array.isArray(existingConsole.profiles)
+        ? existingConsole.profiles
+        : {};
+    const defaultProfile = typeof existingConsole.defaultProfile === 'string' && existingConsole.defaultProfile && !options.setDefault
+        ? existingConsole.defaultProfile
+        : built.defaultProfile;
+    // Merge per model, not per profile: discovery owns routing and the id list,
+    // but a human's label, reasoningEffort, and variants must survive every
+    // re-discovery. Models that vanished upstream are pruned so the managed
+    // profiles mirror the live catalog instead of going stale; a failed or
+    // empty catalog fetch never reaches this loop (fetch throws first).
+    const mergedProfiles = {};
+    const prunedModelIds = [];
+    for (const [profileId, builtProfile] of Object.entries(built.profiles)) {
+        const previousProfile = existingProfiles[profileId];
+        const rawModels = typeof previousProfile === 'object' && previousProfile !== null
+            ? previousProfile.models
+            : undefined;
+        const previousModels = typeof rawModels === 'object' && rawModels !== null && !Array.isArray(rawModels)
+            ? rawModels
+            : {};
+        const models = {};
+        for (const [modelId, entry] of Object.entries(builtProfile.models)) {
+            models[modelId] = {
+                ...preservedModelFields(previousModels[modelId]),
+                label: entry.label,
+                model: entry.model,
+            };
+        }
+        for (const modelId of Object.keys(previousModels)) {
+            if (!(modelId in models))
+                prunedModelIds.push(`${profileId}:${modelId}`);
+        }
+        const previousDefaultModel = typeof previousProfile === 'object' && previousProfile !== null
+            ? previousProfile.defaultModel
+            : undefined;
+        mergedProfiles[profileId] = {
+            ...builtProfile,
+            ...(typeof previousDefaultModel === 'string' && previousDefaultModel in models
+                ? { defaultModel: previousDefaultModel }
+                : {}),
+            models,
+        };
+    }
+    const updatedConsole = {
+        ...existingConsole,
+        defaultProfile,
+        profiles: { ...existingProfiles, ...mergedProfiles },
+    };
+    // Validate before writing anything: the runtime rejects invalid configs at
+    // load time, so a bad merge must never reach disk.
+    const candidate = { ...root, console: updatedConsole };
+    catenceConfigSchema.parse(candidate);
+    await mkdir(path.dirname(options.configPath), { recursive: true });
+    const temporaryPath = `${options.configPath}.tmp`;
+    await writeFile(temporaryPath, `${JSON.stringify(candidate, null, 2)}\n`, 'utf8');
+    await rename(temporaryPath, options.configPath);
+    return {
+        configPath: options.configPath,
+        mergedProfileIds: Object.keys(built.profiles),
+        defaultProfile,
+        counts: built.counts,
+        guessedRoutes: built.guessedRoutes,
+        prunedModelIds,
+    };
+}
+//# sourceMappingURL=opencode-go.js.map

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/core/runtime/self-update.d.ts

@@ -0,0 +1,44 @@
+export type UpdateChannel = 'stable' | 'beta';
+export type ParsedRelease = {
+    major: number;
+    minor: number;
+    patch: number;
+    /** Present only for prerelease builds; a stable release beats every beta of the same tuple. */
+    beta?: number;
+};
+export type SelfUpdatePlan = {
+    channel: UpdateChannel;
+    runtime: {
+        current: string;
+        target?: string;
+        updateAvailable: boolean;
+    };
+    console: {
+        installed?: string;
+        target?: string;
+        updateAvailable: boolean;
+    };
+    /** True when neither component has anything to apply. */
+    ok: boolean;
+};
+export declare function parseReleaseVersion(version: string): ParsedRelease | null;
+export declare function compareReleaseVersions(left: ParsedRelease, right: ParsedRelease): -1 | 0 | 1;
+export declare function channelForVersion(version: string): UpdateChannel;
+export declare function latestRelease(versions: string[], channel: UpdateChannel): string | undefined;
+export declare function planSelfUpdate(options: {
+    runtimeVersion: string;
+    channel: UpdateChannel;
+    npmDistTags: Record<string, string>;
+    pypiReleases: string[];
+    consoleInstalled?: string;
+}): SelfUpdatePlan;
+export declare function fetchNpmDistTags(packageName: string, fetchImpl?: typeof fetch): Promise<Record<string, string>>;
+export declare function fetchPypiReleases(packageName: string, fetchImpl?: typeof fetch): Promise<string[]>;
+/** Run an update command (npm or uv) with the user's terminal attached. */
+export declare function runSelfUpdateCommand(command: string, args: string[]): Promise<number>;
+export declare function hasCommand(command: string): Promise<boolean>;
+/** Read `catence-console --version` from PATH; undefined when the Console is not installed. */
+export declare function readInstalledConsoleVersion(): Promise<string | undefined>;
+/** Global npm package root, used to decide whether `catence` can update itself in place. */
+export declare function npmGlobalPrefix(): Promise<string | undefined>;
+export declare function isGlobalNpmInstall(moduleUrl: string, npmPrefix: string | undefined): boolean;

package/dist/core/runtime/self-update.js

@@ -0,0 +1,138 @@
+/**
+ * Self-update support for the Catence runtime and its Console.
+ *
+ * The runtime tracks npm dist-tags on the `catence` package; the Console
+ * tracks PEP 440 releases on PyPI (`catence-console`). A release is "newer"
+ * only when it strictly dominates the installed version inside the tracked
+ * channel: `stable` for non-prerelease installs, or the beta prerelease
+ * channel for beta installs. Channel names match npm dist-tags, so a beta
+ * runtime consults the `beta` tag and an explicit `--channel stable` moves a
+ * beta install onto the `latest` tag.
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+const NPM_VERSION = /^(\d+)\.(\d+)\.(\d+)(?:-beta\.(\d+))?$/;
+const PEP440_BETA = /^(\d+)\.(\d+)\.(\d+)b(\d+)$/;
+export function parseReleaseVersion(version) {
+    const npm = NPM_VERSION.exec(version.trim());
+    if (npm) {
+        return {
+            major: Number(npm[1]),
+            minor: Number(npm[2]),
+            patch: Number(npm[3]),
+            beta: npm[4] === undefined ? undefined : Number(npm[4]),
+        };
+    }
+    const pep440 = PEP440_BETA.exec(version.trim());
+    if (pep440) {
+        return { major: Number(pep440[1]), minor: Number(pep440[2]), patch: Number(pep440[3]), beta: Number(pep440[4]) };
+    }
+    return null;
+}
+export function compareReleaseVersions(left, right) {
+    for (const field of ['major', 'minor', 'patch']) {
+        if (left[field] !== right[field])
+            return left[field] < right[field] ? -1 : 1;
+    }
+    const leftBeta = left.beta ?? Number.POSITIVE_INFINITY;
+    const rightBeta = right.beta ?? Number.POSITIVE_INFINITY;
+    if (leftBeta === rightBeta)
+        return 0;
+    return leftBeta < rightBeta ? -1 : 1;
+}
+export function channelForVersion(version) {
+    return parseReleaseVersion(version)?.beta !== undefined ? 'beta' : 'stable';
+}
+export function latestRelease(versions, channel) {
+    let best;
+    for (const version of versions) {
+        const parsed = parseReleaseVersion(version);
+        if (!parsed)
+            continue;
+        const isBeta = parsed.beta !== undefined;
+        if (channel === 'beta' ? !isBeta : isBeta)
+            continue;
+        if (!best || compareReleaseVersions(parsed, best.parsed) > 0)
+            best = { version, parsed };
+    }
+    return best?.version;
+}
+export function planSelfUpdate(options) {
+    const distTag = options.channel === 'beta' ? 'beta' : 'latest';
+    const runtimeTarget = options.npmDistTags[distTag];
+    const consoleTarget = latestRelease(options.pypiReleases, options.channel);
+    const runtimeUpdateAvailable = isNewer(runtimeTarget, parseReleaseVersion(options.runtimeVersion));
+    const consoleUpdateAvailable = options.consoleInstalled
+        ? isNewer(consoleTarget, parseReleaseVersion(options.consoleInstalled))
+        : consoleTarget !== undefined;
+    return {
+        channel: options.channel,
+        runtime: { current: options.runtimeVersion, target: runtimeTarget, updateAvailable: runtimeUpdateAvailable },
+        console: { installed: options.consoleInstalled, target: consoleTarget, updateAvailable: consoleUpdateAvailable },
+        ok: !runtimeUpdateAvailable && !consoleUpdateAvailable,
+    };
+}
+function isNewer(target, current) {
+    if (!target || !current)
+        return false;
+    const parsed = parseReleaseVersion(target);
+    return parsed !== null && compareReleaseVersions(parsed, current) > 0;
+}
+export async function fetchNpmDistTags(packageName, fetchImpl = fetch) {
+    const response = await fetchImpl(`https://registry.npmjs.org/${packageName}`);
+    if (!response.ok)
+        throw new Error(`npm registry returned HTTP ${response.status} for ${packageName}.`);
+    const payload = (await response.json());
+    return payload['dist-tags'] ?? {};
+}
+export async function fetchPypiReleases(packageName, fetchImpl = fetch) {
+    const response = await fetchImpl(`https://pypi.org/pypi/${packageName}/json`);
+    if (!response.ok)
+        throw new Error(`PyPI returned HTTP ${response.status} for ${packageName}.`);
+    const payload = (await response.json());
+    return Object.keys(payload.releases ?? {});
+}
+/** Run an update command (npm or uv) with the user's terminal attached. */
+export function runSelfUpdateCommand(command, args) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: 'inherit' });
+        child.once('error', reject);
+        child.once('close', (code) => resolve(code ?? 1));
+    });
+}
+export function hasCommand(command) {
+    return new Promise((resolve) => {
+        const child = spawn(command, ['--version'], { stdio: 'ignore' });
+        child.once('error', () => resolve(false));
+        child.once('close', (code) => resolve(code === 0));
+    });
+}
+/** Read `catence-console --version` from PATH; undefined when the Console is not installed. */
+export function readInstalledConsoleVersion() {
+    return new Promise((resolve) => {
+        const child = spawn('catence-console', ['--version'], { stdio: ['ignore', 'pipe', 'inherit'] });
+        let stdout = '';
+        child.stdout?.on('data', (chunk) => (stdout += chunk.toString('utf8')));
+        child.once('error', () => resolve(undefined));
+        child.once('close', (code) => {
+            const match = /^catence-console (\S+)/.exec(stdout.trim());
+            resolve(code === 0 && match ? match[1] : undefined);
+        });
+    });
+}
+/** Global npm package root, used to decide whether `catence` can update itself in place. */
+export function npmGlobalPrefix() {
+    return new Promise((resolve) => {
+        const child = spawn('npm', ['prefix', '-g'], { stdio: ['ignore', 'pipe', 'inherit'] });
+        let stdout = '';
+        child.stdout?.on('data', (chunk) => (stdout += chunk.toString('utf8')));
+        child.once('error', () => resolve(undefined));
+        child.once('close', (code) => resolve(code === 0 ? stdout.trim() : undefined));
+    });
+}
+export function isGlobalNpmInstall(moduleUrl, npmPrefix) {
+    if (!npmPrefix)
+        return false;
+    return fileURLToPath(moduleUrl).startsWith(`${npmPrefix}/lib/node_modules/`);
+}
+//# sourceMappingURL=self-update.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