Fixed wrong update_time in server

Author: Afgan0r

docs/architecture.md

@@ -329,6 +329,10 @@ Nuances:
 6. On success:
    - remove old `results`,
    - move `temp_results` to `results`.
+7. After successful output publish, parse pipeline writes `results/parsing_status.json` with committed `updateTime`.
+   - `updateTime` value is the `replaysListPreparedAt` snapshot captured at parse-run start.
+   - This metadata is committed only on successful full parse run; failed runs must not overwrite previous committed status.
+   - If parse-run-start snapshot is missing, committed status is also left unchanged.
 
 Nuance: output generation is mostly sync (`writeFileSync`, `mkdirSync`, `moveSync`).
 
@@ -390,6 +394,7 @@ Nuance: `processRawReplays` relies on sequential `for ... of` + `await` over rep
 6. Runtime state lives in `~/sg_stats`, not repo-local paths. Repo root `config/` directory is a reference copy; runtime code reads from `~/sg_stats/config/`.
 7. Logger (see section 5) uses `pino.multistream()` combining two async `pino.transport()` instances. File targets use `dedupe: true` (each entry goes to exactly one file target). Log folder is not cleared on restart — runs within the same minute append to existing files.
 8. All game types are parsed concurrently via `Promise.all` sharing one `WorkerPool`, which means worker contention across game types is possible under heavy load.
+9. Do not derive public parse `update_time` from live `replaysList.json`: replay list refresh can complete before parse run finishes. Use committed `results/parsing_status.json` instead.
 
 ## 17. Fast Code Reading Order for New Contributors
 

docs/plans/2026-02-15-committed-update-time-design.md

@@ -0,0 +1,63 @@
+# Committed Update Time Design
+
+## Context
+Current `update_time` can move forward too early because `replaysList.json` is refreshed before parsing finishes. This creates a mismatch between displayed update timestamp and actually published statistics.
+
+## Goal
+Expose `update_time` as the `prepareReplaysList` start timestamp of the replay list actually used by the last successful full parsing run, and publish it only after successful parsing completion.
+
+## Confirmed Semantics
+1. `update_time` value source: `replaysListPreparedAt` captured from `replaysList.json` at parse-run start.
+2. Visibility rule: publish this value only after full run success (`parse + stats + output`).
+3. Failure rule: if run fails, keep previously published `update_time` unchanged.
+
+## Considered Approaches
+1. Use `stats.zip` mtime only.
+   - Pros: minimal changes.
+   - Cons: wrong semantics (file timestamp != replay list snapshot timestamp).
+2. Read live `replaysList.json` from server.
+   - Pros: easy implementation.
+   - Cons: timestamp can advance before parsing completes.
+3. Persist committed parsing status artifact after successful run.
+   - Pros: correct semantics and stable behavior during long/failed runs.
+   - Cons: adds one metadata file.
+
+## Selected Approach
+Use a committed metadata artifact in `results`, e.g. `results/parsing_status.json`, written only after successful full run.
+
+## Data Model
+`results/parsing_status.json`:
+
+```json
+{
+  "updateTime": "2026-02-15T12:34:56.000Z"
+}
+```
+
+## Runtime Flow
+1. Parse run starts.
+2. Parser reads `replaysList.json` and snapshots `replaysListPreparedAt` into run-local variable.
+3. Parser completes full run and publishes output.
+4. Parser writes `results/parsing_status.json` atomically with `updateTime` from step 2.
+5. Server `/parsing_status` returns `update_date` from `results/parsing_status.json`.
+
+## Fallback Policy (Server)
+1. `results/parsing_status.json.updateTime` when valid.
+2. `results/stats.zip` mtime when status file missing/invalid.
+3. `new Date()` as final fallback.
+
+## Error Handling
+1. Missing/invalid `replaysListPreparedAt` at parse start: parser writes `null` or omits update in committed status based on implementation policy.
+2. Parsing failure: do not update committed status file.
+3. Corrupted status file: server falls back safely.
+
+## Testing Scope
+1. Parser unit tests for status commit on success only.
+2. Parser failure-path test: committed status unchanged.
+3. Server date utility tests for normal path and all fallback branches.
+4. Schedule-level behavior check: while parsing, `status=parsing` but `update_date` stays previous committed value.
+
+## Non-Goals
+1. Changing replay list collection timing.
+2. Redefining parsing job orchestration.
+3. Adding new API fields beyond current `update_date` requirement.

docs/plans/2026-02-15-committed-update-time-implementation.md

@@ -0,0 +1,164 @@
+# Committed Update Time Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Publish `/parsing_status.update_date` only after a successful full parse run, while preserving the original replay-list snapshot timestamp (`replaysListPreparedAt`) used by that run.
+
+**Architecture:** Capture run-local `replaysListPreparedAt` at parse start in `replays-parser`, commit it into `results/parsing_status.json` only after successful output generation, and make `server` read update time from that committed artifact. Keep strict fallback behavior for bootstrap and corrupted metadata cases.
+
+**Tech Stack:** TypeScript (replays-parser), Node.js CommonJS (server), Jest, node:test, fs-extra.
+
+---
+
+### Task 1: Add committed parsing status utilities in replays-parser
+
+**Files:**
+- Create: `/home/afgan0r/Projects/SolidGames/replays-parser/src/0 - utils/parsingStatus.ts`
+- Modify: `/home/afgan0r/Projects/SolidGames/replays-parser/src/0 - utils/paths.ts`
+
+**Step 1: Write the failing test**
+
+- Create parser utility tests that expect:
+1. read run snapshot from `replaysList.json.replaysListPreparedAt`
+2. write `results/parsing_status.json` atomically
+
+**Step 2: Run test to verify it fails**
+
+Run: `npm run test -- src/!tests/unit-tests/0 - utils/parsingStatus.test.ts`
+Expected: FAIL (module/functions missing)
+
+**Step 3: Write minimal implementation**
+
+- Add `parsingStatusPath` in `paths.ts` pointing to `results/parsing_status.json`.
+- Implement in `parsingStatus.ts`:
+1. `readRunReplayListPreparedAt(): string | null`
+2. `commitParsingStatus(updateTime: string | null): void`
+3. Atomic write via temp file + rename.
+
+**Step 4: Run test to verify it passes**
+
+Run: `npm run test -- src/!tests/unit-tests/0 - utils/parsingStatus.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/0\ -\ utils/parsingStatus.ts src/0\ -\ utils/paths.ts src/!tests/unit-tests/0\ -\ utils/parsingStatus.test.ts
+git commit -m "feat: add committed parsing status utility"
+```
+
+### Task 2: Wire committed status into parse pipeline
+
+**Files:**
+- Modify: `/home/afgan0r/Projects/SolidGames/replays-parser/src/index.ts`
+- Test: `/home/afgan0r/Projects/SolidGames/replays-parser/src/!tests/unit-tests/schedule.test.ts`
+
+**Step 1: Write the failing test**
+
+- Add test that on successful parse run status commit is called with run snapshot.
+- Add test that on failure commit is not called.
+
+**Step 2: Run test to verify it fails**
+
+Run: `npm run test -- src/!tests/unit-tests/schedule.test.ts`
+Expected: FAIL (missing commit behavior)
+
+**Step 3: Write minimal implementation**
+
+In `src/index.ts`:
+1. read run snapshot before heavy parsing starts
+2. after successful `generateOutput`, call `commitParsingStatus(runSnapshot)`
+3. keep failure path unchanged (no commit)
+
+**Step 4: Run test to verify it passes**
+
+Run: `npm run test -- src/!tests/unit-tests/schedule.test.ts`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/index.ts src/!tests/unit-tests/schedule.test.ts
+git commit -m "feat: commit update time only after successful parse"
+```
+
+### Task 3: Switch server update_date to committed status artifact
+
+**Files:**
+- Modify: `/home/afgan0r/Projects/SolidGames/server/src/utils/date.js`
+- Modify: `/home/afgan0r/Projects/SolidGames/server/src/server.js`
+- Test: `/home/afgan0r/Projects/SolidGames/server/src/utils/date.test.js`
+
+**Step 1: Write the failing test**
+
+Add/adjust tests for `getParsingStatusUpdateDate(listsPath, resultsPath)`:
+1. returns `parsing_status.json.updateTime` when valid
+2. falls back to `stats.zip` mtime when status file missing/invalid
+3. falls back to `new Date()` when all unavailable
+
+**Step 2: Run test to verify it fails**
+
+Run: `npm test`
+Expected: FAIL on old fallback logic
+
+**Step 3: Write minimal implementation**
+
+In `date.js`:
+1. read `results/parsing_status.json`
+2. validate `updateTime` as date
+3. fallback chain: status file -> `stats.zip` mtime -> now
+
+In `server.js`:
+- keep `/parsing_status` using `getParsingStatusUpdateDate(listsPath, resultsPath)`
+
+**Step 4: Run test to verify it passes**
+
+Run: `npm test`
+Expected: PASS
+
+**Step 5: Commit**
+
+```bash
+git add src/utils/date.js src/server.js src/utils/date.test.js
+git commit -m "feat: read parsing update time from committed status file"
+```
+
+### Task 4: Cross-repo verification and docs refresh
+
+**Files:**
+- Modify: `/home/afgan0r/Projects/SolidGames/replays-parser/docs/architecture.md`
+- Modify (if needed): `/home/afgan0r/Projects/SolidGames/replays-parser/docs/plans/2026-02-15-committed-update-time-design.md`
+
+**Step 1: Write failing verification expectation**
+
+- Define acceptance criteria:
+1. During parsing: `status=parsing`, `update_date` unchanged from previous success
+2. After successful run: `update_date` equals committed run snapshot (`replaysListPreparedAt` captured at run start)
+
+**Step 2: Run verification commands**
+
+Replays parser:
+- `npm run lint`
+- `npm run test`
+- `npm run build-dist`
+
+Server:
+- `npm test`
+
+Expected: all PASS
+
+**Step 3: Update architecture docs**
+
+- Document committed status artifact and fallback chain.
+
+**Step 4: Re-run verification**
+
+Run same commands as step 2.
+Expected: all PASS
+
+**Step 5: Commit**
+
+```bash
+git add docs/architecture.md docs/plans/2026-02-15-committed-update-time-design.md
+git commit -m "docs: describe committed update time semantics"
+```

src/!tests/unit-tests/0 - utils/parsingStatus.test.ts

@@ -0,0 +1,117 @@
+import path from 'path';
+
+import fs from 'fs-extra';
+
+import { commitParsingStatus, readRunReplayListPreparedAt } from '../../../0 - utils/parsingStatus';
+import { parsingStatusPath, replaysListPath } from '../../../0 - utils/paths';
+
+jest.mock('fs-extra', () => ({
+  readFileSync: jest.fn(),
+  ensureDirSync: jest.fn(),
+  writeFileSync: jest.fn(),
+  moveSync: jest.fn(),
+}));
+
+const mockedFs = fs as unknown as {
+  readFileSync: jest.Mock;
+  ensureDirSync: jest.Mock;
+  writeFileSync: jest.Mock;
+  moveSync: jest.Mock;
+};
+
+describe('parsingStatus utils', () => {
+  beforeEach(() => {
+    jest.restoreAllMocks();
+    mockedFs.readFileSync.mockReset();
+    mockedFs.ensureDirSync.mockReset();
+    mockedFs.writeFileSync.mockReset();
+    mockedFs.moveSync.mockReset();
+  });
+
+  test('readRunReplayListPreparedAt returns value when present', () => {
+    mockedFs.readFileSync.mockReturnValue(
+      JSON.stringify({ replaysListPreparedAt: '2026-02-15T12:00:00.000Z' }),
+    );
+
+    expect(readRunReplayListPreparedAt()).toBe('2026-02-15T12:00:00.000Z');
+    expect(mockedFs.readFileSync).toHaveBeenCalledWith(replaysListPath, 'utf8');
+  });
+
+  test('readRunReplayListPreparedAt returns null when file missing', () => {
+    mockedFs.readFileSync.mockImplementation(() => {
+      throw new Error('ENOENT');
+    });
+
+    expect(readRunReplayListPreparedAt()).toBeNull();
+  });
+
+  test('readRunReplayListPreparedAt returns null when JSON is invalid', () => {
+    mockedFs.readFileSync.mockReturnValue('{ invalid json');
+
+    expect(readRunReplayListPreparedAt()).toBeNull();
+  });
+
+  test('readRunReplayListPreparedAt returns null when field is missing', () => {
+    mockedFs.readFileSync.mockReturnValue(JSON.stringify({ anotherField: 'value' }));
+
+    expect(readRunReplayListPreparedAt()).toBeNull();
+  });
+
+  test('commitParsingStatus writes atomic temp file then moves to final path with expected payload', () => {
+    const nowSpy = jest.spyOn(Date, 'now').mockReturnValue(1700000000000);
+
+    commitParsingStatus('2026-02-15T13:00:00.000Z');
+
+    const expectedTempPath = `${parsingStatusPath}.tmp-${process.pid}-1700000000000`;
+    const expectedPayload = JSON.stringify({ updateTime: '2026-02-15T13:00:00.000Z' });
+
+    expect(mockedFs.ensureDirSync).toHaveBeenCalledWith(path.dirname(parsingStatusPath));
+    expect(mockedFs.ensureDirSync.mock.invocationCallOrder[0]).toBeLessThan(
+      mockedFs.writeFileSync.mock.invocationCallOrder[0],
+    );
+    expect(mockedFs.writeFileSync).toHaveBeenCalledWith(expectedTempPath, expectedPayload);
+    expect(mockedFs.moveSync).toHaveBeenCalledWith(
+      expectedTempPath,
+      parsingStatusPath,
+      { overwrite: true },
+    );
+    expect(mockedFs.writeFileSync.mock.invocationCallOrder[0]).toBeLessThan(
+      mockedFs.moveSync.mock.invocationCallOrder[0],
+    );
+
+    nowSpy.mockRestore();
+  });
+
+  test('commitParsingStatus serializes null updateTime and preserves operation ordering', () => {
+    const nowSpy = jest.spyOn(Date, 'now').mockReturnValue(1700000000001);
+
+    commitParsingStatus(null);
+
+    const expectedTempPath = `${parsingStatusPath}.tmp-${process.pid}-1700000000001`;
+    const expectedPayload = JSON.stringify({ updateTime: null });
+
+    expect(mockedFs.writeFileSync).toHaveBeenCalledWith(expectedTempPath, expectedPayload);
+    expect(mockedFs.ensureDirSync.mock.invocationCallOrder[0]).toBeLessThan(
+      mockedFs.writeFileSync.mock.invocationCallOrder[0],
+    );
+    expect(mockedFs.writeFileSync.mock.invocationCallOrder[0]).toBeLessThan(
+      mockedFs.moveSync.mock.invocationCallOrder[0],
+    );
+
+    nowSpy.mockRestore();
+  });
+
+  test('commitParsingStatus rethrows when moveSync fails', () => {
+    const nowSpy = jest.spyOn(Date, 'now').mockReturnValue(1700000000002);
+
+    mockedFs.moveSync.mockImplementation(() => {
+      throw new Error('rename failed');
+    });
+
+    expect(() => {
+      commitParsingStatus('2026-02-15T13:00:00.000Z');
+    }).toThrow('rename failed');
+
+    nowSpy.mockRestore();
+  });
+});