ai-wrapped 1.3.3 → 1.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-wrapped",
-  "version": "1.3.3",
+  "version": "1.3.4",
   "description": "Your year in AI — a Spotify Wrapped-style dashboard for AI coding agents",
   "license": "MIT",
   "repository": {

package/src/bun/aggregator.test.ts

@@ -34,7 +34,7 @@ describe("aggregateSessionsByDate", () => {
       makeSession({ id: "s2", totalCostUsd: 0.75 }),
       makeSession({ id: "s3", repoName: "other-repo", totalCostUsd: 2.0 }),
       makeSession({ id: "s4", repoName: null, totalCostUsd: 3.0 }),
-    ]);
+    ], { timeZone: "UTC" });
 
     const entry = daily["2026-02-21"];
     expect(entry).toBeDefined();
@@ -59,7 +59,7 @@ describe("aggregateSessionsByDate", () => {
         startTime: null,
         parsedAt: "2026-02-21T13:40:00.000Z",
       }),
-    ]);
+    ], { timeZone: "UTC" });
 
     const entry = daily["2026-02-21"];
     expect(entry).toBeDefined();
@@ -68,20 +68,33 @@ describe("aggregateSessionsByDate", () => {
     expect(entry?.totals.sessions).toBe(2);
   });
 
-  test("uses UTC consistently for day and hour buckets", () => {
+  test("uses requested timezone consistently for day and hour buckets", () => {
     const daily = aggregateSessionsByDate([
       makeSession({
         id: "tz-1",
-        startTime: "2026-02-21T00:30:00+09:00",
-        parsedAt: "2026-02-21T00:45:00+09:00",
+        startTime: "2026-02-21T07:30:00.000Z",
+        parsedAt: "2026-02-21T07:45:00.000Z",
       }),
-    ]);
+    ], { timeZone: "America/Los_Angeles" });
 
     const entry = daily["2026-02-20"];
     expect(entry).toBeDefined();
-    expect(entry?.byHour["15"]?.sessions).toBe(1);
-    expect(entry?.byHourSource["15"]?.codex?.sessions).toBe(1);
+    expect(entry?.byHour["23"]?.sessions).toBe(1);
+    expect(entry?.byHourSource["23"]?.codex?.sessions).toBe(1);
     expect(entry?.totals.sessions).toBe(1);
     expect(daily["2026-02-21"]).toBeUndefined();
   });
+
+  test("falls back to UTC when timezone is invalid", () => {
+    const daily = aggregateSessionsByDate([
+      makeSession({
+        id: "tz-invalid",
+        startTime: "2026-02-21T10:10:00.000Z",
+      }),
+    ], { timeZone: "Invalid/Timezone" });
+
+    const entry = daily["2026-02-21"];
+    expect(entry).toBeDefined();
+    expect(entry?.byHour["10"]?.sessions).toBe(1);
+  });
 });

package/src/bun/aggregator.ts

@@ -6,6 +6,8 @@ import {
   type DayStats,
 } from "./store";
 
+const DEFAULT_TIME_ZONE = "UTC";
+
 const addStats = (target: DayStats, source: DayStats): void => {
   target.sessions += source.sessions;
   target.messages += source.messages;
@@ -33,10 +35,51 @@ const parseSessionTimestamp = (session: Session): Date | null => {
   return parsed;
 };
 
-const toDayKey = (session: Session): string => {
+const resolveFormatterTimeZone = (timeZone?: string): string => {
+  const candidate =
+    typeof timeZone === "string" && timeZone.trim().length > 0
+      ? timeZone.trim()
+      : Intl.DateTimeFormat().resolvedOptions().timeZone;
+  if (!candidate) {
+    return DEFAULT_TIME_ZONE;
+  }
+
+  try {
+    // Validate the zone before use. Falls back to UTC for invalid identifiers.
+    void new Intl.DateTimeFormat("en-US", { timeZone: candidate });
+    return candidate;
+  } catch {
+    return DEFAULT_TIME_ZONE;
+  }
+};
+
+const formatDateKey = (date: Date, formatter: Intl.DateTimeFormat): string => {
+  const parts = formatter.formatToParts(date);
+  const year = parts.find((part) => part.type === "year")?.value;
+  const month = parts.find((part) => part.type === "month")?.value;
+  const day = parts.find((part) => part.type === "day")?.value;
+
+  if (!year || !month || !day) {
+    return date.toISOString().slice(0, 10);
+  }
+
+  return `${year}-${month}-${day}`;
+};
+
+const formatHourKey = (date: Date, formatter: Intl.DateTimeFormat): string | null => {
+  const hourValue = formatter.formatToParts(date).find((part) => part.type === "hour")?.value;
+  if (!hourValue) return null;
+
+  const hourNum = Number(hourValue);
+  if (!Number.isFinite(hourNum)) return null;
+
+  return String(hourNum).padStart(2, "0");
+};
+
+const toDayKey = (session: Session, dateFormatter: Intl.DateTimeFormat): string => {
   const parsed = parseSessionTimestamp(session);
   if (parsed) {
-    return parsed.toISOString().slice(0, 10);
+    return formatDateKey(parsed, dateFormatter);
   }
 
   const fallback = session.startTime ?? session.parsedAt;
@@ -44,13 +87,14 @@ const toDayKey = (session: Session): string => {
     return fallback.slice(0, 10);
   }
 
-  return new Date().toISOString().slice(0, 10);
+  return formatDateKey(new Date(), dateFormatter);
 };
 
-const toHourKey = (session: Session): string | null => {
+const toHourKey = (session: Session, hourFormatter: Intl.DateTimeFormat): string | null => {
   const parsed = parseSessionTimestamp(session);
   if (!parsed) return null;
-  return String(parsed.getUTCHours()).padStart(2, "0");
+
+  return formatHourKey(parsed, hourFormatter);
 };
 
 const toSessionStats = (session: Session): DayStats => ({
@@ -123,11 +167,34 @@ const sortDailyStore = (daily: DailyStore): DailyStore => {
   return output;
 };
 
-export const aggregateSessionsByDate = (sessions: Session[]): DailyStore => {
+export interface AggregateSessionsOptions {
+  timeZone?: string;
+}
+
+export const resolveAggregationTimeZone = (timeZone?: string): string =>
+  resolveFormatterTimeZone(timeZone);
+
+export const aggregateSessionsByDate = (
+  sessions: Session[],
+  options: AggregateSessionsOptions = {},
+): DailyStore => {
+  const timeZone = resolveFormatterTimeZone(options.timeZone);
+  const dateFormatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+  });
+  const hourFormatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    hour: "2-digit",
+    hourCycle: "h23",
+  });
+
   const daily: DailyStore = {};
 
   for (const session of sessions) {
-    const date = toDayKey(session);
+    const date = toDayKey(session, dateFormatter);
     const entry = ensureDateEntry(daily, date);
     const modelKey = session.model && session.model.trim().length > 0 ? session.model : "unknown";
     const repoKey = toRepoKey(session.repoName);
@@ -143,7 +210,7 @@ export const aggregateSessionsByDate = (sessions: Session[]): DailyStore => {
       entry.byRepo[repoKey] = createEmptyDayStats();
     }
 
-    const hourKey = toHourKey(session);
+    const hourKey = toHourKey(session, hourFormatter);
     if (hourKey !== null) {
       if (!entry.byHour[hourKey]) {
         entry.byHour[hourKey] = createEmptyDayStats();

package/src/bun/scan.ts

@@ -1,14 +1,25 @@
 import type { SessionSource } from "../shared/schema";
-import { aggregateSessionsByDate, mergeDailyAggregates } from "./aggregator";
+import {
+  aggregateSessionsByDate,
+  mergeDailyAggregates,
+  resolveAggregationTimeZone,
+} from "./aggregator";
 import { discoverAll } from "./discovery";
 import { normalizeSession } from "./normalizer";
 import { parseFile } from "./parsers";
 import type { Session } from "./session-schema";
-import { readDailyStore, readScanState, writeDailyStore, writeScanState } from "./store";
+import {
+  readDailyStore,
+  readScanState,
+  writeAggregationMeta,
+  writeDailyStore,
+  writeScanState,
+} from "./store";
 
 export interface ScanOptions {
   fullScan?: boolean;
   sources?: SessionSource[];
+  timeZone?: string;
 }
 
 export interface ScanResult {
@@ -18,6 +29,7 @@ export interface ScanResult {
 }
 
 export const runScan = async (options: ScanOptions = {}): Promise<ScanResult> => {
+  const aggregationTimeZone = resolveAggregationTimeZone(options.timeZone);
   const candidates = await discoverAll(options.sources);
   const scanState = await readScanState();
 
@@ -62,11 +74,16 @@ export const runScan = async (options: ScanOptions = {}): Promise<ScanResult> =>
   await writeScanState(scanState);
 
   if (options.fullScan) {
-    await writeDailyStore(aggregateSessionsByDate(sessions));
+    await writeDailyStore(aggregateSessionsByDate(sessions, { timeZone: aggregationTimeZone }));
+    await writeAggregationMeta(aggregationTimeZone);
   } else if (sessions.length > 0) {
     const existingDaily = await readDailyStore();
-    const nextDaily = mergeDailyAggregates(existingDaily, aggregateSessionsByDate(sessions));
+    const nextDaily = mergeDailyAggregates(
+      existingDaily,
+      aggregateSessionsByDate(sessions, { timeZone: aggregationTimeZone }),
+    );
     await writeDailyStore(nextDaily);
+    await writeAggregationMeta(aggregationTimeZone);
   }
 
   return {

package/src/bun/store.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from "bun:test";
-import { rawDailyStoreMissingHourDimension } from "./store";
+import { rawAggregationMetaNeedsTimeZoneBackfill, rawDailyStoreMissingHourDimension } from "./store";
 
 describe("rawDailyStoreMissingHourDimension", () => {
   test("returns false for non-record input", () => {
@@ -101,3 +101,43 @@ describe("rawDailyStoreMissingHourDimension", () => {
     ).toBe(false);
   });
 });
+
+describe("rawAggregationMetaNeedsTimeZoneBackfill", () => {
+  test("returns true when meta is missing or malformed", () => {
+    expect(rawAggregationMetaNeedsTimeZoneBackfill(null, "America/Los_Angeles")).toBe(true);
+    expect(rawAggregationMetaNeedsTimeZoneBackfill({}, "America/Los_Angeles")).toBe(true);
+    expect(
+      rawAggregationMetaNeedsTimeZoneBackfill(
+        { version: "1", timeZone: "America/Los_Angeles" },
+        "America/Los_Angeles",
+      ),
+    ).toBe(true);
+  });
+
+  test("returns true when version changes", () => {
+    expect(
+      rawAggregationMetaNeedsTimeZoneBackfill(
+        { version: 2, timeZone: "America/Los_Angeles" },
+        "America/Los_Angeles",
+      ),
+    ).toBe(true);
+  });
+
+  test("returns true when timezone changes", () => {
+    expect(
+      rawAggregationMetaNeedsTimeZoneBackfill(
+        { version: 1, timeZone: "UTC" },
+        "America/Los_Angeles",
+      ),
+    ).toBe(true);
+  });
+
+  test("returns false for matching version and timezone", () => {
+    expect(
+      rawAggregationMetaNeedsTimeZoneBackfill(
+        { version: 1, timeZone: "America/Los_Angeles" },
+        "America/Los_Angeles",
+      ),
+    ).toBe(false);
+  });
+});

package/src/bun/store.ts

@@ -37,10 +37,17 @@ export interface DailyAggregateEntry {
 
 export type DailyStore = Record<string, DailyAggregateEntry>;
 
+export interface AggregationMeta {
+  version: number;
+  timeZone: string;
+}
+
 const DATA_DIR = join(homedir(), ".ai-wrapped");
 const SCAN_STATE_PATH = join(DATA_DIR, "scan-state.json");
 const DAILY_PATH = join(DATA_DIR, "daily.json");
+const AGGREGATION_META_PATH = join(DATA_DIR, "aggregation-meta.json");
 const SETTINGS_PATH = join(DATA_DIR, "settings.json");
+const AGGREGATION_META_VERSION = 1;
 
 const DEFAULT_SETTINGS: AppSettings = {
   scanOnLaunch: true,
@@ -179,6 +186,29 @@ const normalizeDailyStore = (value: unknown): DailyStore => {
   return output;
 };
 
+const normalizeAggregationMeta = (value: unknown): AggregationMeta | null => {
+  if (!isRecord(value)) {
+    return null;
+  }
+
+  const version = value.version;
+  const timeZone = value.timeZone;
+  if (
+    typeof version !== "number" ||
+    !Number.isFinite(version) ||
+    !Number.isInteger(version) ||
+    typeof timeZone !== "string" ||
+    timeZone.trim().length === 0
+  ) {
+    return null;
+  }
+
+  return {
+    version,
+    timeZone: timeZone.trim(),
+  };
+};
+
 const normalizeScanState = (value: unknown): ScanStateStore => {
   if (!isRecord(value)) {
     return {};
@@ -264,6 +294,26 @@ export const writeDailyStore = async (daily: DailyStore): Promise<void> => {
   await writeJson(DAILY_PATH, dailyCache);
 };
 
+const rawDailyStoreHasSessions = (raw: unknown): boolean => {
+  if (!isRecord(raw)) {
+    return false;
+  }
+
+  for (const rawEntry of Object.values(raw)) {
+    if (!isRecord(rawEntry)) {
+      continue;
+    }
+
+    const totals = isRecord(rawEntry.totals) ? rawEntry.totals : null;
+    const hasSessions = totals && typeof totals.sessions === "number" && totals.sessions > 0;
+    if (hasSessions) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
 export const dailyStoreMissingRepoDimension = async (): Promise<boolean> => {
   const raw = await readJson<unknown>(DAILY_PATH, {});
   if (!isRecord(raw)) {
@@ -321,11 +371,52 @@ export const rawDailyStoreMissingHourDimension = (raw: unknown): boolean => {
   return false;
 };
 
+export const rawAggregationMetaNeedsTimeZoneBackfill = (
+  rawMeta: unknown,
+  currentTimeZone: string,
+): boolean => {
+  const normalizedCurrent =
+    typeof currentTimeZone === "string" && currentTimeZone.trim().length > 0
+      ? currentTimeZone.trim()
+      : "UTC";
+  const meta = normalizeAggregationMeta(rawMeta);
+  if (!meta) {
+    return true;
+  }
+
+  if (meta.version !== AGGREGATION_META_VERSION) {
+    return true;
+  }
+
+  return meta.timeZone !== normalizedCurrent;
+};
+
 export const dailyStoreMissingHourDimension = async (): Promise<boolean> => {
   const raw = await readJson<unknown>(DAILY_PATH, {});
   return rawDailyStoreMissingHourDimension(raw);
 };
 
+export const dailyStoreNeedsTimeZoneBackfill = async (
+  currentTimeZone: string,
+): Promise<boolean> => {
+  const rawDaily = await readJson<unknown>(DAILY_PATH, {});
+  if (!rawDailyStoreHasSessions(rawDaily)) {
+    return false;
+  }
+
+  const rawMeta = await readJson<unknown>(AGGREGATION_META_PATH, null);
+  return rawAggregationMetaNeedsTimeZoneBackfill(rawMeta, currentTimeZone);
+};
+
+export const writeAggregationMeta = async (timeZone: string): Promise<void> => {
+  const normalizedTimeZone =
+    typeof timeZone === "string" && timeZone.trim().length > 0 ? timeZone.trim() : "UTC";
+  await writeJson<AggregationMeta>(AGGREGATION_META_PATH, {
+    version: AGGREGATION_META_VERSION,
+    timeZone: normalizedTimeZone,
+  });
+};
+
 export const getSettings = async (): Promise<AppSettings> => {
   if (settingsCache === null) {
     const raw = await readJson<unknown>(SETTINGS_PATH, DEFAULT_SETTINGS);
@@ -344,5 +435,6 @@ export const paths = {
   dataDir: DATA_DIR,
   scanState: SCAN_STATE_PATH,
   daily: DAILY_PATH,
+  aggregationMeta: AGGREGATION_META_PATH,
   settings: SETTINGS_PATH,
 };