incremnt 0.3.0 → 0.5.0

package/src/increment-score-replay-data.js

@@ -0,0 +1,486 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { promisify } from 'node:util';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { anonymizeAccountId } from './anonymize.js';
+import { exerciseAliasMapping } from './exercise-aliases.js';
+import { canonicalExerciseName, normalizeExerciseName } from './queries.js';
+
+const execFileAsync = promisify(execFile);
+
+export const incrementScoreReplayDataVersion = 'increment-score-replay-input.v0';
+export const incrementScoreProdAdapterVersion = 'increment-score-prod-data-adapter.v0';
+export const defaultIncrementScoreFormulaVersion = 'increment-score-formula.v0-pending';
+
+const knownCanonicalExercises = new Set(Object.keys(exerciseAliasMapping).map((name) => normalizeExerciseName(name)));
+const safeAliasPattern = /^[a-z0-9][a-z0-9_-]{1,63}$/;
+
+function adapterError(message, code) {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function isoNow(now = new Date()) {
+  return now.toISOString();
+}
+
+function dateOnly(value) {
+  if (typeof value !== 'string' || !value) return null;
+  if (/^\d{4}-\d{2}-\d{2}$/.test(value)) return value;
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime())) return null;
+  return parsed.toISOString().slice(0, 10);
+}
+
+function completionDateForSession(session) {
+  return session?.completedAt ?? session?.summary?.date ?? session?.date ?? null;
+}
+
+function numberOrNull(value) {
+  const numeric = Number(value);
+  return Number.isFinite(numeric) ? numeric : null;
+}
+
+function stringOrNull(value) {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed ? trimmed : null;
+}
+
+function stableHash(parts, length = 16) {
+  return createHash('sha256')
+    .update(parts.map((part) => String(part ?? '')).join(':'))
+    .digest('hex')
+    .slice(0, length);
+}
+
+function hashedId(prefix, accountId, value) {
+  if (value == null || value === '') return null;
+  return `${prefix}:${stableHash([prefix, accountId, value])}`;
+}
+
+function dateRange(items, getDate) {
+  const dates = (items ?? [])
+    .map(getDate)
+    .map(dateOnly)
+    .filter(Boolean)
+    .sort();
+
+  return {
+    count: dates.length,
+    firstDate: dates[0] ?? null,
+    lastDate: dates.at(-1) ?? null
+  };
+}
+
+function normalizeMetricEntries(entries, valueMapper) {
+  return (Array.isArray(entries) ? entries : [])
+    .map((entry) => valueMapper(entry))
+    .filter((entry) => entry.date)
+    .sort((lhs, rhs) => lhs.date.localeCompare(rhs.date));
+}
+
+function normalizeExerciseNameForReplay(name, accountId) {
+  const normalized = normalizeExerciseName(name);
+  const canonical = canonicalExerciseName(name);
+
+  if (knownCanonicalExercises.has(canonical)) {
+    return {
+      canonicalName: canonical,
+      customExerciseHash: null,
+      customExercise: false
+    };
+  }
+
+  return {
+    canonicalName: `custom:${stableHash(['exercise', accountId, normalized], 12)}`,
+    customExerciseHash: stableHash(['exercise-name', accountId, normalized], 16),
+    customExercise: true
+  };
+}
+
+function normalizeSet(set) {
+  return {
+    weightKg: numberOrNull(set?.weight),
+    reps: numberOrNull(set?.reps),
+    rir: numberOrNull(set?.rir ?? set?.repsInReserve),
+    isComplete: set?.isComplete !== false
+  };
+}
+
+function normalizeExercise(exercise, accountId) {
+  const name = normalizeExerciseNameForReplay(exercise?.name ?? exercise?.exerciseName, accountId);
+  return {
+    ...name,
+    muscleGroup: stringOrNull(exercise?.muscleGroup),
+    sets: (Array.isArray(exercise?.sets) ? exercise.sets : [])
+      .map(normalizeSet)
+      .filter((set) => set.weightKg != null || set.reps != null)
+  };
+}
+
+function normalizePlannedExercise(exercise, accountId) {
+  const name = normalizeExerciseNameForReplay(exercise?.exerciseName ?? exercise?.name, accountId);
+  const sourceSets = Array.isArray(exercise?.targetSets)
+    ? exercise.targetSets
+    : (Array.isArray(exercise?.sets) ? exercise.sets : []);
+
+  return {
+    ...name,
+    targetReps: numberOrNull(exercise?.targetReps),
+    targetWeightKg: numberOrNull(exercise?.targetWeight),
+    plannedSets: sourceSets.length
+  };
+}
+
+function normalizeSession(session, accountId) {
+  const completedAt = completionDateForSession(session);
+  const prescriptionExercises = Array.isArray(session?.prescriptionSnapshot?.exercises)
+    ? session.prescriptionSnapshot.exercises
+    : [];
+
+  return {
+    id: hashedId('session', accountId, session?.id),
+    date: dateOnly(completedAt),
+    completedAt: stringOrNull(completedAt),
+    programId: hashedId('program', accountId, session?.programId),
+    programDayIndex: numberOrNull(session?.programDayIndex),
+    totalVolume: numberOrNull(session?.summary?.totalVolume ?? session?.volume),
+    durationSeconds: numberOrNull(session?.summary?.durationSeconds),
+    effortScore: numberOrNull(session?.summary?.effortScore),
+    readiness: session?.readinessBandSnapshot
+      ? {
+          band: stringOrNull(session.readinessBandSnapshot.band),
+          dominantSignal: stringOrNull(session.readinessBandSnapshot.dominantSignal),
+          adaptationApplied: stringOrNull(session.readinessBandSnapshot.adaptationApplied)
+        }
+      : null,
+    exercises: (Array.isArray(session?.exercises) ? session.exercises : [])
+      .map((exercise) => normalizeExercise(exercise, accountId)),
+    prescription: prescriptionExercises.length > 0
+      ? {
+          plannedExercises: prescriptionExercises.map((exercise) => normalizePlannedExercise(exercise, accountId))
+        }
+      : null
+  };
+}
+
+function normalizeProgram(program, accountId) {
+  return {
+    id: hashedId('program', accountId, program?.id),
+    active: false,
+    completedCyclesCount: numberOrNull(program?.completedCyclesCount),
+    currentDayIndex: numberOrNull(program?.currentDayIndex),
+    days: (Array.isArray(program?.days) ? program.days : []).map((day, index) => ({
+      index,
+      plannedExercises: (Array.isArray(day?.exercises) ? day.exercises : [])
+        .map((exercise) => normalizePlannedExercise(exercise, accountId))
+    }))
+  };
+}
+
+function normalizeHealthMetrics(metrics) {
+  const source = metrics ?? {};
+  return {
+    restingHR: normalizeMetricEntries(source.restingHR, (entry) => ({
+      date: dateOnly(entry?.date),
+      value: numberOrNull(entry?.value)
+    })),
+    hrv: normalizeMetricEntries(source.hrv, (entry) => ({
+      date: dateOnly(entry?.date),
+      value: numberOrNull(entry?.value)
+    })),
+    sleep: normalizeMetricEntries(source.sleep, (entry) => ({
+      date: dateOnly(entry?.date),
+      durationMins: numberOrNull(entry?.durationMins)
+    })),
+    bodyWeight: normalizeMetricEntries(source.bodyWeight, (entry) => ({
+      date: dateOnly(entry?.date),
+      value: numberOrNull(entry?.value)
+    })),
+    vo2Max: normalizeMetricEntries(source.vo2Max, (entry) => ({
+      date: dateOnly(entry?.date),
+      value: numberOrNull(entry?.value)
+    })),
+    otherWorkouts: normalizeMetricEntries(source.otherWorkouts, (entry) => ({
+      date: dateOnly(entry?.date),
+      workoutType: stringOrNull(entry?.workoutType),
+      durationSecs: numberOrNull(entry?.durationSecs),
+      distanceKm: numberOrNull(entry?.distanceKm),
+      avgHR: numberOrNull(entry?.avgHR),
+      calories: numberOrNull(entry?.calories)
+    }))
+  };
+}
+
+function availabilityForMetric(entries) {
+  const range = dateRange(entries, (entry) => entry?.date);
+  return {
+    available: range.count > 0,
+    ...range
+  };
+}
+
+function buildDataAvailability(snapshot, normalized) {
+  const sessionRange = dateRange(normalized.sessions, (session) => session.date);
+  const healthSignals = Object.fromEntries(
+    Object.entries(normalized.healthMetrics).map(([key, entries]) => [key, availabilityForMetric(entries)])
+  );
+  const availableHealthSignalCount = Object.values(healthSignals).filter((signal) => signal.available).length;
+
+  return {
+    sessions: {
+      available: normalized.sessions.length > 0,
+      ...sessionRange
+    },
+    programs: {
+      available: normalized.programs.length > 0,
+      count: normalized.programs.length
+    },
+    strengthPlans: {
+      available: Array.isArray(snapshot.strengthPlans) && snapshot.strengthPlans.length > 0,
+      count: Array.isArray(snapshot.strengthPlans) ? snapshot.strengthPlans.length : 0
+    },
+    cycleSummaries: {
+      available: Array.isArray(snapshot.cycleSummaries) && snapshot.cycleSummaries.length > 0,
+      count: Array.isArray(snapshot.cycleSummaries) ? snapshot.cycleSummaries.length : 0
+    },
+    exerciseRecommendations: {
+      available: Boolean(snapshot.exerciseRecommendations && Object.keys(snapshot.exerciseRecommendations).length > 0),
+      count: snapshot.exerciseRecommendations ? Object.keys(snapshot.exerciseRecommendations).length : 0
+    },
+    health: {
+      available: availableHealthSignalCount > 0,
+      signalCount: availableHealthSignalCount,
+      signals: healthSignals
+    }
+  };
+}
+
+export function parseReplayAllowlist(raw) {
+  if (typeof raw !== 'string' || !raw.trim()) {
+    throw adapterError(
+      'Missing Increment Score replay allowlist. Set INCREMENT_SCORE_REPLAY_ALLOWLIST or pass --allowlist alias=account-id[,alias=account-id].',
+      'INCREMENT_SCORE_REPLAY_ALLOWLIST_REQUIRED'
+    );
+  }
+
+  const allowlist = new Map();
+  for (const token of raw.split(',').map((entry) => entry.trim()).filter(Boolean)) {
+    const separator = token.indexOf('=');
+    if (separator <= 0 || separator === token.length - 1) {
+      throw adapterError(`Invalid allowlist entry "${token}". Expected alias=account-id.`, 'INCREMENT_SCORE_REPLAY_ALLOWLIST_INVALID');
+    }
+
+    const alias = token.slice(0, separator).trim();
+    const accountId = token.slice(separator + 1).trim();
+    if (!safeAliasPattern.test(alias)) {
+      throw adapterError(`Invalid replay alias "${alias}". Use lowercase letters, numbers, "_" or "-".`, 'INCREMENT_SCORE_REPLAY_ALIAS_INVALID');
+    }
+    if (!accountId) {
+      throw adapterError(`Missing account id for replay alias "${alias}".`, 'INCREMENT_SCORE_REPLAY_ACCOUNT_INVALID');
+    }
+    if (allowlist.has(alias)) {
+      throw adapterError(`Duplicate replay alias "${alias}".`, 'INCREMENT_SCORE_REPLAY_ALLOWLIST_DUPLICATE');
+    }
+
+    allowlist.set(alias, accountId);
+  }
+
+  if (allowlist.size === 0) {
+    throw adapterError('Increment Score replay allowlist is empty.', 'INCREMENT_SCORE_REPLAY_ALLOWLIST_EMPTY');
+  }
+
+  return allowlist;
+}
+
+export function resolveReplaySelection({ requestedAliases = [], allowlist }) {
+  const selectedAliases = requestedAliases.length > 0 ? requestedAliases : [...allowlist.keys()];
+  const selected = [];
+
+  for (const alias of selectedAliases) {
+    if (!allowlist.has(alias)) {
+      throw adapterError(`Replay alias "${alias}" is not allowlisted.`, 'INCREMENT_SCORE_REPLAY_ALIAS_NOT_ALLOWLISTED');
+    }
+    selected.push({ alias, accountId: allowlist.get(alias) });
+  }
+
+  return selected;
+}
+
+export function buildHostedSnapshotSelect(accountId) {
+  const literal = `'${String(accountId).replaceAll('\'', '\'\'')}'`;
+  return [
+    'SELECT data::text',
+    'FROM snapshots',
+    `WHERE user_id = ${literal}`,
+    'ORDER BY updated_at DESC',
+    'LIMIT 1;'
+  ].join(' ');
+}
+
+export async function fetchHostedSnapshotJson(databaseId, accountId, {
+  env = process.env,
+  execFileAsyncImpl = execFileAsync
+} = {}) {
+  if (!databaseId) {
+    throw adapterError('Missing Increment Score replay database id. Pass --database or set INCREMENT_SCORE_REPLAY_DATABASE.', 'INCREMENT_SCORE_REPLAY_DATABASE_REQUIRED');
+  }
+  if (!env.RENDER_API_KEY) {
+    throw adapterError('Missing RENDER_API_KEY. Increment Score replay adapter refuses to access hosted snapshots without credentials.', 'INCREMENT_SCORE_REPLAY_CREDENTIALS_REQUIRED');
+  }
+
+  const query = buildHostedSnapshotSelect(accountId);
+  if (!query.trim().toUpperCase().startsWith('SELECT ')) {
+    throw adapterError('Hosted snapshot query must be read-only.', 'INCREMENT_SCORE_REPLAY_QUERY_NOT_READ_ONLY');
+  }
+
+  let stdout;
+  try {
+    ({ stdout } = await execFileAsyncImpl('render', [
+      'psql',
+      databaseId,
+      '--command',
+      query,
+      '--output',
+      'text',
+      '--',
+      '-A',
+      '-q',
+      '-t'
+    ], {
+      env: {
+        ...env,
+        CI: 'true'
+      },
+      maxBuffer: 20 * 1024 * 1024
+    }));
+  } catch (error) {
+    const wrapped = adapterError(
+      `Hosted snapshot export failed for account ${accountId}.`,
+      'INCREMENT_SCORE_REPLAY_EXPORT_FAILED'
+    );
+    wrapped.cause = error;
+    throw wrapped;
+  }
+
+  const trimmed = stdout.trimEnd();
+  if (!trimmed.startsWith('{')) {
+    throw adapterError(`Hosted snapshot export for allowlisted replay source did not return JSON.`, 'INCREMENT_SCORE_REPLAY_SNAPSHOT_NOT_FOUND');
+  }
+  try {
+    return JSON.parse(trimmed);
+  } catch (error) {
+    const wrapped = adapterError(
+      `Hosted snapshot export returned invalid JSON for account ${accountId}.`,
+      'INCREMENT_SCORE_REPLAY_SNAPSHOT_INVALID_JSON'
+    );
+    wrapped.cause = error;
+    throw wrapped;
+  }
+}
+
+export function normalizeSnapshotForIncrementScoreReplay(snapshot, {
+  accountId,
+  alias,
+  databaseId = null,
+  extractedAt = isoNow(),
+  formulaVersion = defaultIncrementScoreFormulaVersion
+} = {}) {
+  if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+    throw adapterError('Hosted snapshot payload must be a JSON object.', 'INCREMENT_SCORE_REPLAY_SNAPSHOT_INVALID');
+  }
+  if (!accountId) {
+    throw adapterError('accountId is required to normalize replay snapshot identifiers.', 'INCREMENT_SCORE_REPLAY_ACCOUNT_REQUIRED');
+  }
+  if (!alias || !safeAliasPattern.test(alias)) {
+    throw adapterError('A safe source alias is required to normalize replay snapshot data.', 'INCREMENT_SCORE_REPLAY_ALIAS_REQUIRED');
+  }
+
+  const sessions = (Array.isArray(snapshot.sessions) ? snapshot.sessions : [])
+    .map((session) => normalizeSession(session, accountId))
+    .sort((lhs, rhs) => String(lhs.completedAt ?? lhs.date ?? '').localeCompare(String(rhs.completedAt ?? rhs.date ?? '')));
+  const programs = (Array.isArray(snapshot.programs) ? snapshot.programs : [])
+    .map((program) => normalizeProgram(program, accountId));
+  const activeProgramHash = hashedId('program', accountId, snapshot.activeProgramId);
+  const normalizedPrograms = programs.map((program) => ({
+    ...program,
+    active: activeProgramHash != null && program.id === activeProgramHash
+  }));
+  const healthMetrics = normalizeHealthMetrics(snapshot.healthMetrics);
+  const normalized = { sessions, programs: normalizedPrograms, healthMetrics };
+  const dataAvailability = buildDataAvailability(snapshot, normalized);
+
+  return {
+    kind: 'incrementScoreReplayInput',
+    version: incrementScoreReplayDataVersion,
+    adapterVersion: incrementScoreProdAdapterVersion,
+    formulaVersion,
+    extractedAt,
+    source: {
+      type: 'hostedSnapshot',
+      accountAlias: alias,
+      accountHash: anonymizeAccountId(accountId),
+      databaseHash: databaseId ? `db:${stableHash(['database', databaseId], 12)}` : null,
+      snapshotExportedAt: stringOrNull(snapshot.exportedAt),
+      snapshotSchemaVersion: snapshot.schemaVersion ?? null,
+      appVersion: stringOrNull(snapshot.appVersion),
+      rawSnapshotCommitted: false
+    },
+    dataAvailability,
+    replayWindow: {
+      startDate: dataAvailability.sessions.firstDate,
+      endDate: dataAvailability.sessions.lastDate
+    },
+    sessions,
+    programs: normalizedPrograms,
+    healthMetrics
+  };
+}
+
+export async function loadAllowlistedHostedReplayInput({
+  databaseId,
+  alias,
+  allowlist,
+  fetchSnapshot = fetchHostedSnapshotJson,
+  extractedAt = isoNow(),
+  formulaVersion = defaultIncrementScoreFormulaVersion
+} = {}) {
+  if (!(allowlist instanceof Map)) {
+    throw adapterError('allowlist must be a Map returned by parseReplayAllowlist.', 'INCREMENT_SCORE_REPLAY_ALLOWLIST_REQUIRED');
+  }
+  if (!allowlist.has(alias)) {
+    throw adapterError(`Replay alias "${alias}" is not allowlisted.`, 'INCREMENT_SCORE_REPLAY_ALIAS_NOT_ALLOWLISTED');
+  }
+
+  const accountId = allowlist.get(alias);
+  const snapshot = await fetchSnapshot(databaseId, accountId);
+  return normalizeSnapshotForIncrementScoreReplay(snapshot, {
+    accountId,
+    alias,
+    databaseId,
+    extractedAt,
+    formulaVersion
+  });
+}
+
+export async function writeReplayInputFile(replayInput, outDir) {
+  const alias = replayInput?.source?.accountAlias;
+  if (!alias || !safeAliasPattern.test(alias)) {
+    throw adapterError('Replay input missing valid source account alias.', 'INCREMENT_SCORE_REPLAY_INPUT_INVALID');
+  }
+
+  const baseDir = path.resolve(outDir);
+  await mkdir(baseDir, { recursive: true });
+  const outputPath = path.resolve(baseDir, `${alias}.increment-score-replay.json`);
+  const boundaryPrefix = baseDir.endsWith(path.sep) ? baseDir : `${baseDir}${path.sep}`;
+  if (!outputPath.startsWith(boundaryPrefix)) {
+    throw adapterError('Replay output path escaped configured output directory.', 'INCREMENT_SCORE_REPLAY_OUTPUT_PATH_INVALID');
+  }
+
+  await writeFile(outputPath, `${JSON.stringify(replayInput, null, 2)}\n`, 'utf8');
+  return outputPath;
+}