@roastcodes/ttdash 6.2.0 → 6.2.2

package/server.js

@@ -2,6 +2,7 @@
 
 const http = require('http');
 const fs = require('fs');
+const fsPromises = require('fs/promises');
 const os = require('os');
 const path = require('path');
 const readline = require('readline/promises');
@@ -271,6 +272,9 @@ const BACKGROUND_LOG_DIR = path.join(APP_PATHS.cacheDir, 'background');
 const BACKGROUND_INSTANCES_LOCK_DIR = path.join(APP_PATHS.configDir, 'background-instances.lock');
 const BACKGROUND_INSTANCES_LOCK_TIMEOUT_MS = 5000;
 const BACKGROUND_INSTANCES_LOCK_STALE_MS = 10000;
+const FILE_MUTATION_LOCK_TIMEOUT_MS = 10000;
+const FILE_MUTATION_LOCK_STALE_MS = 30000;
+const fileMutationLocks = new Map();
 
 const MIME_TYPES = {
   '.html': 'text/html; charset=utf-8',
@@ -314,6 +318,214 @@ function writeJsonAtomic(filePath, data) {
   fs.renameSync(tempPath, filePath);
 }
 
+async function writeJsonAtomicAsync(filePath, data) {
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  let tempPathCreated = false;
+
+  try {
+    await fsPromises.mkdir(path.dirname(filePath), { recursive: true, mode: SECURE_DIR_MODE });
+    tempPathCreated = true;
+    await fsPromises.writeFile(tempPath, JSON.stringify(data, null, 2), {
+      mode: SECURE_FILE_MODE,
+    });
+
+    if (!IS_WINDOWS) {
+      await fsPromises.chmod(tempPath, SECURE_FILE_MODE);
+    }
+
+    await fsPromises.rename(tempPath, filePath);
+  } catch (error) {
+    if (tempPathCreated) {
+      try {
+        await fsPromises.unlink(tempPath);
+      } catch (unlinkError) {
+        if (unlinkError?.code !== 'ENOENT') {
+          // Ignore temp-file cleanup failures so the original error wins.
+        }
+      }
+    }
+    throw error;
+  }
+}
+
+async function unlinkIfExists(filePath) {
+  try {
+    await fsPromises.unlink(filePath);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+}
+
+function getFileMutationLockDir(filePath) {
+  return `${filePath}.lock`;
+}
+
+function getFileMutationLockOwnerPath(lockDir) {
+  return path.join(lockDir, 'owner.json');
+}
+
+async function removeFileMutationLockDir(lockDir) {
+  try {
+    await fsPromises.rm(lockDir, { recursive: true, force: true });
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+}
+
+async function writeFileMutationLockOwner(lockDir) {
+  const ownerPath = getFileMutationLockOwnerPath(lockDir);
+  const owner = {
+    pid: process.pid,
+    createdAt: new Date().toISOString(),
+    instanceId: RUNTIME_INSTANCE.id,
+  };
+  await fsPromises.writeFile(ownerPath, JSON.stringify(owner, null, 2), {
+    mode: SECURE_FILE_MODE,
+  });
+  if (!IS_WINDOWS) {
+    await fsPromises.chmod(ownerPath, SECURE_FILE_MODE);
+  }
+}
+
+async function shouldReapFileMutationLock(lockDir) {
+  const ownerPath = getFileMutationLockOwnerPath(lockDir);
+  let owner = null;
+
+  try {
+    const rawOwner = await fsPromises.readFile(ownerPath, 'utf-8');
+    owner = JSON.parse(rawOwner);
+  } catch (error) {
+    if (error?.code !== 'ENOENT') {
+      // Fall back to age-based cleanup if the owner metadata is missing or malformed.
+    }
+  }
+
+  try {
+    const ownerCreatedAt = owner?.createdAt ? Date.parse(owner.createdAt) : Number.NaN;
+    const stats = await fsPromises.stat(lockDir);
+    const lockAgeMs = Number.isFinite(ownerCreatedAt)
+      ? Date.now() - ownerCreatedAt
+      : Date.now() - stats.mtimeMs;
+
+    if (lockAgeMs > FILE_MUTATION_LOCK_STALE_MS) {
+      return true;
+    }
+
+    if (Number.isInteger(owner?.pid)) {
+      return !isProcessRunning(owner.pid);
+    }
+
+    return false;
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return false;
+    }
+    throw error;
+  }
+}
+
+async function withCrossProcessFileMutationLock(
+  filePath,
+  operation,
+  timeoutMs = FILE_MUTATION_LOCK_TIMEOUT_MS,
+) {
+  const lockDir = getFileMutationLockDir(filePath);
+  const startedAt = Date.now();
+
+  while (true) {
+    try {
+      await fsPromises.mkdir(path.dirname(lockDir), {
+        recursive: true,
+        mode: SECURE_DIR_MODE,
+      });
+      await fsPromises.mkdir(lockDir, { mode: SECURE_DIR_MODE });
+      if (!IS_WINDOWS) {
+        await fsPromises.chmod(lockDir, SECURE_DIR_MODE);
+      }
+
+      try {
+        await writeFileMutationLockOwner(lockDir);
+      } catch (error) {
+        await removeFileMutationLockDir(lockDir).catch(() => undefined);
+        throw error;
+      }
+
+      break;
+    } catch (error) {
+      if (!error || error.code !== 'EEXIST') {
+        throw error;
+      }
+
+      if (await shouldReapFileMutationLock(lockDir)) {
+        await removeFileMutationLockDir(lockDir).catch(() => undefined);
+        continue;
+      }
+
+      if (Date.now() - startedAt >= timeoutMs) {
+        throw new Error(`Could not acquire file mutation lock for ${path.basename(filePath)}.`, {
+          cause: error,
+        });
+      }
+
+      await sleep(50);
+    }
+  }
+
+  try {
+    return await operation();
+  } finally {
+    try {
+      await removeFileMutationLockDir(lockDir);
+    } catch {
+      // Ignore cleanup races so the original operation result wins.
+    }
+  }
+}
+
+async function withFileMutationLock(filePath, operation) {
+  const previous = fileMutationLocks.get(filePath) || Promise.resolve();
+  let releaseCurrent;
+  const current = new Promise((resolve) => {
+    releaseCurrent = resolve;
+  });
+
+  fileMutationLocks.set(filePath, current);
+
+  await previous.catch(() => undefined);
+
+  try {
+    return await withCrossProcessFileMutationLock(filePath, operation);
+  } finally {
+    releaseCurrent();
+    if (fileMutationLocks.get(filePath) === current) {
+      fileMutationLocks.delete(filePath);
+    }
+  }
+}
+
+async function withOrderedFileMutationLocks(filePaths, operation) {
+  const uniquePaths = Array.from(new Set(filePaths)).sort();
+
+  const runWithLock = async (index) => {
+    if (index >= uniquePaths.length) {
+      return operation();
+    }
+
+    const filePath = uniquePaths[index];
+    return withFileMutationLock(filePath, () => runWithLock(index + 1));
+  };
+
+  return runWithLock(0);
+}
+
+async function withSettingsAndDataMutationLock(operation) {
+  return withOrderedFileMutationLocks([SETTINGS_FILE, DATA_FILE], operation);
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -1389,8 +1601,8 @@ function readData() {
   }
 }
 
-function writeData(data) {
-  writeJsonAtomic(DATA_FILE, data);
+async function writeData(data) {
+  await writeJsonAtomicAsync(DATA_FILE, data);
 }
 
 function readSettings() {
@@ -1420,53 +1632,43 @@ function readSettingsForWrite() {
   }
 }
 
-function writeSettings(settings) {
-  writeJsonAtomic(SETTINGS_FILE, normalizeSettings(settings));
+async function writeSettings(settings) {
+  await writeJsonAtomicAsync(SETTINGS_FILE, normalizeSettings(settings));
 }
 
-function updateSettings(patch) {
+async function updateDataLoadState(patch) {
   const current = readSettingsForWrite();
   const next = {
     ...current,
-    ...(patch && typeof patch === 'object' ? patch : {}),
+    ...patch,
   };
 
-  if (patch && Object.prototype.hasOwnProperty.call(patch, 'providerLimits')) {
-    next.providerLimits = normalizeProviderLimits(patch.providerLimits);
-  } else {
-    next.providerLimits = current.providerLimits;
-  }
-
-  next.language = normalizeLanguage(next.language);
-  next.theme = normalizeTheme(next.theme);
-
-  writeSettings(next);
+  await writeSettings(next);
   return toSettingsResponse(next);
 }
 
-function recordDataLoad(source) {
-  const current = readSettingsForWrite();
-  const next = {
-    ...current,
-    lastLoadedAt: new Date().toISOString(),
-    lastLoadSource: source,
-  };
+async function updateSettings(patch) {
+  return withFileMutationLock(SETTINGS_FILE, async () => {
+    const current = readSettingsForWrite();
+    const next = {
+      ...current,
+      ...(patch && typeof patch === 'object' ? patch : {}),
+    };
 
-  writeSettings(next);
-  return toSettingsResponse(next);
-}
+    if (patch && Object.prototype.hasOwnProperty.call(patch, 'providerLimits')) {
+      next.providerLimits = normalizeProviderLimits(patch.providerLimits);
+    } else {
+      next.providerLimits = current.providerLimits;
+    }
 
-function clearDataLoadState() {
-  const current = readSettingsForWrite();
-  const next = {
-    ...current,
-    lastLoadedAt: null,
-    lastLoadSource: null,
-  };
+    next.language = normalizeLanguage(next.language);
+    next.theme = normalizeTheme(next.theme);
 
-  writeSettings(next);
-  return toSettingsResponse(next);
+    await writeSettings(next);
+    return toSettingsResponse(next);
+  });
 }
+
 const { json, readBody, resolveApiPath, sendBuffer, validateMutationRequest } = createHttpUtils({
   apiPrefix: API_PREFIX,
   maxBodySize: MAX_BODY_SIZE,
@@ -1647,8 +1849,13 @@ async function performAutoImport({
     });
 
     const normalized = normalizeIncomingData(JSON.parse(rawJson));
-    writeData(normalized);
-    recordDataLoad(source);
+    await withSettingsAndDataMutationLock(async () => {
+      await writeData(normalized);
+      await updateDataLoadState({
+        lastLoadedAt: new Date().toISOString(),
+        lastLoadSource: source,
+      });
+    });
 
     return {
       days: normalized.daily.length,
@@ -1743,12 +1950,13 @@ const server = http.createServer(async (req, res) => {
       if (validationError) {
         return json(res, validationError.status, { message: validationError.message });
       }
-      try {
-        fs.unlinkSync(DATA_FILE);
-      } catch {
-        // Ignore missing data files during reset.
-      }
-      clearDataLoadState();
+      await withSettingsAndDataMutationLock(async () => {
+        await unlinkIfExists(DATA_FILE);
+        await updateDataLoadState({
+          lastLoadedAt: null,
+          lastLoadSource: null,
+        });
+      });
       return json(res, 200, { success: true });
     }
     return json(res, 405, { message: 'Method Not Allowed' });
@@ -1786,11 +1994,9 @@ const server = http.createServer(async (req, res) => {
       if (validationError) {
         return json(res, validationError.status, { message: validationError.message });
       }
-      try {
-        fs.unlinkSync(SETTINGS_FILE);
-      } catch {
-        // Ignore missing settings files during reset.
-      }
+      await withFileMutationLock(SETTINGS_FILE, async () => {
+        await unlinkIfExists(SETTINGS_FILE);
+      });
       return json(res, 200, { success: true, settings: readSettings() });
     }
 
@@ -1801,7 +2007,7 @@ const server = http.createServer(async (req, res) => {
       }
       try {
         const body = await readBody(req);
-        return json(res, 200, updateSettings(body));
+        return json(res, 200, await updateSettings(body));
       } catch (e) {
         if (isPayloadTooLargeError(e)) {
           return json(res, 413, { message: 'Settings request too large' });
@@ -1826,7 +2032,9 @@ const server = http.createServer(async (req, res) => {
     try {
       const body = await readBody(req);
       const importedSettings = normalizeSettings(extractSettingsImportPayload(body));
-      writeSettings(importedSettings);
+      await withFileMutationLock(SETTINGS_FILE, async () => {
+        await writeSettings(importedSettings);
+      });
       return json(res, 200, toSettingsResponse(importedSettings));
     } catch (e) {
       if (isPayloadTooLargeError(e)) {
@@ -1846,8 +2054,13 @@ const server = http.createServer(async (req, res) => {
       try {
         const body = await readBody(req);
         const normalized = normalizeIncomingData(body);
-        writeData(normalized);
-        recordDataLoad('file');
+        await withSettingsAndDataMutationLock(async () => {
+          await writeData(normalized);
+          await updateDataLoadState({
+            lastLoadedAt: new Date().toISOString(),
+            lastLoadSource: 'file',
+          });
+        });
         const days = normalized.daily.length;
         const totalCost = normalized.totals.totalCost;
         return json(res, 200, { days, totalCost });
@@ -1875,10 +2088,16 @@ const server = http.createServer(async (req, res) => {
     try {
       const body = await readBody(req);
       const importedData = normalizeIncomingData(extractUsageImportPayload(body));
-      const currentData = readData();
-      const result = mergeUsageData(currentData, importedData);
-      writeData(result.data);
-      recordDataLoad('file');
+      const result = await withSettingsAndDataMutationLock(async () => {
+        const currentData = readData();
+        const merged = mergeUsageData(currentData, importedData);
+        await writeData(merged.data);
+        await updateDataLoadState({
+          lastLoadedAt: new Date().toISOString(),
+          lastLoadSource: 'file',
+        });
+        return merged;
+      });
       return json(res, 200, result.summary);
     } catch (e) {
       if (isPayloadTooLargeError(e)) {
@@ -2096,6 +2315,12 @@ module.exports = {
     commandExists,
     getExecutableName,
     listenOnAvailablePort,
+    getFileMutationLockDir,
+    unlinkIfExists,
+    writeJsonAtomicAsync,
+    withFileMutationLock,
+    withOrderedFileMutationLocks,
+    getPendingFileMutationLockCount: () => fileMutationLocks.size,
   },
 };
 

package/shared/dashboard-domain.d.ts

@@ -1,19 +1,31 @@
 import type { DailyUsage, DashboardMetrics, ViewMode } from './dashboard-types'
 
+/** Aggregates usage rows to the requested dashboard view mode. */
 export function aggregateToDailyFormat(data: DailyUsage[], viewMode: ViewMode): DailyUsage[]
+/** Returns the busiest rolling seven-day window by cost. */
 export function computeBusiestWeek(
   data: DailyUsage[],
 ): { start: string; end: string; cost: number } | null
+/** Computes the core dashboard metrics for a dataset. */
 export function computeMetrics(data: DailyUsage[]): DashboardMetrics
+/** Computes a simple moving average over numeric values. */
 export function computeMovingAverage(
   values: Array<number | undefined>,
   window?: number,
 ): Array<number | undefined>
+/** Computes the relative week-over-week cost change. */
 export function computeWeekOverWeekChange(data: DailyUsage[]): number | null
+/** Filters usage rows by an inclusive ISO date range. */
 export function filterByDateRange(data: DailyUsage[], start?: string, end?: string): DailyUsage[]
+/** Filters usage rows to entries that contain selected models. */
 export function filterByModels(data: DailyUsage[], selectedModels: string[]): DailyUsage[]
+/** Filters usage rows to a specific calendar month. */
 export function filterByMonth(data: DailyUsage[], month: string | null): DailyUsage[]
+/** Filters usage rows to entries that contain selected providers. */
 export function filterByProviders(data: DailyUsage[], selectedProviders: string[]): DailyUsage[]
+/** Resolves the provider name for a model identifier. */
 export function getModelProvider(raw: string): string
+/** Normalizes raw model names to their dashboard label. */
 export function normalizeModelName(raw: string): string
+/** Sorts usage rows in ascending date order. */
 export function sortByDate(data: DailyUsage[]): DailyUsage[]

package/shared/dashboard-domain.js

@@ -132,6 +132,12 @@ function parseOSeries(name) {
   return `${name.slice(0, separatorIndex)} ${capitalize(name.slice(separatorIndex + 1))}`
 }
 
+/**
+ * Normalizes raw model names to their dashboard label.
+ *
+ * @param raw - The raw model identifier.
+ * @returns The normalized display name.
+ */
 function normalizeModelName(raw) {
   const canonical = canonicalizeModelName(raw)
 
@@ -178,6 +184,12 @@ function normalizeModelName(raw) {
   return canonical.split('-').filter(Boolean).map(titleCaseSegment).join(' ') || String(raw || '')
 }
 
+/**
+ * Resolves the provider name for a model identifier.
+ *
+ * @param raw - The raw model identifier.
+ * @returns The normalized provider name.
+ */
 function getModelProvider(raw) {
   const canonical = canonicalizeModelName(raw)
   for (const matcher of PROVIDER_MATCHERS) {
@@ -223,6 +235,14 @@ function recalculateDayFromBreakdowns(day, filteredBreakdowns) {
   }
 }
 
+/**
+ * Filters usage rows by an inclusive ISO date range.
+ *
+ * @param data - The source usage rows.
+ * @param start - The optional start date.
+ * @param end - The optional end date.
+ * @returns The filtered usage rows.
+ */
 function filterByDateRange(data, start, end) {
   return data.filter((entry) => {
     if (start && entry.date < start) return false
@@ -231,6 +251,13 @@ function filterByDateRange(data, start, end) {
   })
 }
 
+/**
+ * Filters usage rows to entries that contain selected models.
+ *
+ * @param data - The source usage rows.
+ * @param selectedModels - The normalized model names to keep.
+ * @returns The filtered usage rows.
+ */
 function filterByModels(data, selectedModels) {
   if (!selectedModels || selectedModels.length === 0) return data
   const selected = new Set(selectedModels)
@@ -247,6 +274,13 @@ function filterByModels(data, selectedModels) {
     .filter(Boolean)
 }
 
+/**
+ * Filters usage rows to entries that contain selected providers.
+ *
+ * @param data - The source usage rows.
+ * @param selectedProviders - The provider names to keep.
+ * @returns The filtered usage rows.
+ */
 function filterByProviders(data, selectedProviders) {
   if (!selectedProviders || selectedProviders.length === 0) return data
   const selected = new Set(selectedProviders)
@@ -263,15 +297,35 @@ function filterByProviders(data, selectedProviders) {
     .filter(Boolean)
 }
 
+/**
+ * Filters usage rows to a specific calendar month.
+ *
+ * @param data - The source usage rows.
+ * @param month - The month in YYYY-MM format.
+ * @returns The filtered usage rows.
+ */
 function filterByMonth(data, month) {
   if (!month) return data
   return data.filter((entry) => entry.date.startsWith(month))
 }
 
+/**
+ * Sorts usage rows in ascending date order.
+ *
+ * @param data - The source usage rows.
+ * @returns A date-sorted copy of the input.
+ */
 function sortByDate(data) {
   return [...data].sort((left, right) => left.date.localeCompare(right.date))
 }
 
+/**
+ * Aggregates usage rows to the requested dashboard view mode.
+ *
+ * @param data - The source daily usage rows.
+ * @param viewMode - The target aggregation mode.
+ * @returns The aggregated usage rows.
+ */
 function aggregateToDailyFormat(data, viewMode) {
   if (viewMode === 'daily') return data
 
@@ -309,6 +363,13 @@ function aggregateToDailyFormat(data, viewMode) {
   return Array.from(groups.values()).sort((left, right) => left.date.localeCompare(right.date))
 }
 
+/**
+ * Computes a simple moving average over numeric values.
+ *
+ * @param values - The source numeric values.
+ * @param window - The moving average window size.
+ * @returns The moving-average series.
+ */
 function computeMovingAverage(values, window = 7) {
   const result = Array(values.length)
   let sum = 0
@@ -343,6 +404,12 @@ function stdDev(values) {
   return Math.sqrt(variance)
 }
 
+/**
+ * Returns the busiest rolling seven-day window by cost.
+ *
+ * @param data - The source usage rows.
+ * @returns The top seven-day window or null when unavailable.
+ */
 function computeBusiestWeek(data) {
   const sorted = data
     .filter((entry) => /^\d{4}-\d{2}-\d{2}$/.test(entry.date))
@@ -383,6 +450,12 @@ function computeBusiestWeek(data) {
   return bestWindow
 }
 
+/**
+ * Computes the relative week-over-week cost change.
+ *
+ * @param data - The source usage rows.
+ * @returns The relative week-over-week delta.
+ */
 function computeWeekOverWeekChange(data) {
   if (data.some((entry) => !/^\d{4}-\d{2}-\d{2}$/.test(entry.date))) return null
   if (data.length < 14) return null
@@ -395,6 +468,12 @@ function computeWeekOverWeekChange(data) {
   return ((lastSum - prevSum) / prevSum) * 100
 }
 
+/**
+ * Computes the core dashboard metrics for a dataset.
+ *
+ * @param data - The source usage rows.
+ * @returns The derived dashboard metrics.
+ */
 function computeMetrics(data) {
   if (data.length === 0) {
     return {

package/shared/dashboard-types.d.ts

@@ -1,3 +1,4 @@
+/** Describes per-model usage totals for one period. */
 export interface ModelBreakdown {
   modelName: string
   inputTokens: number
@@ -9,6 +10,7 @@ export interface ModelBreakdown {
   requestCount: number
 }
 
+/** Describes aggregated usage for one daily, monthly, or yearly period. */
 export interface DailyUsage {
   date: string
   inputTokens: number
@@ -24,8 +26,10 @@ export interface DailyUsage {
   _aggregatedDays?: number
 }
 
+/** Lists the supported dashboard aggregation modes. */
 export type ViewMode = 'daily' | 'monthly' | 'yearly'
 
+/** Collects high-level metrics derived from the current dataset. */
 export interface DashboardMetrics {
   totalCost: number
   totalTokens: number

package/shared/model-colors.d.ts

@@ -1,17 +1,24 @@
+/** Lists the supported shared model color themes. */
 export type ModelColorTheme = 'dark' | 'light'
 
+/** Describes the HSL values assigned to one model color. */
 export interface ModelColorSpec {
   h: number
   s: number
   l: number
 }
 
+/** Configures shared model color resolution. */
 export interface ModelColorOptions {
   theme?: ModelColorTheme
   alpha?: number
 }
 
+/** Normalizes an unknown theme value to a supported color theme. */
 export function normalizeTheme(theme?: string): ModelColorTheme
+/** Returns the shared color spec for a normalized model name. */
 export function getModelColorSpec(name: string, options?: ModelColorOptions): ModelColorSpec
+/** Returns the shared model color as an HSL string. */
 export function getModelColor(name: string, options?: ModelColorOptions): string
+/** Returns the shared model color as an RGB string. */
 export function getModelColorRgb(name: string, options?: ModelColorOptions): string