snapshot-file.ts

apps/dashboard/src/snapshot-file.ts

1. /**
2. * Caching the last sync to `data/last-snapshot.json`. Node only.
3. *
4. * `pnpm morning` renders the page, writes the briefings from that render's
5. * numbers, then renders again so the prose appears on the board. A second
6. * render that re-synced would move `snap.syncedAt`, so the briefings would no
7. * longer match the numbers beside them and every clean run would end by
8. * declaring its own output stale. `--render-only` reads this file and
9. * re-renders from the same sync, so the check passes because the
10. * prose and the numbers genuinely do describe one moment, not because the check
11. * was loosened. Loosening it would remove the only thing telling a reader whether
12. * the two halves of the page agree.
13. *
14. * Not re-rendered from briefing-payload.json because That file is deliberately
15. * distilled (roughly 4k tokens where the snapshot is 300k), and `render()` needs
16. * the whole snapshot. Widening the payload to serve the renderer would throw away
17. * the entire cost strategy.
18. *
19. * Node-only IO lives in a `*-file.ts` module because a static `node:fs` import
20. * resolves even behind `import type` and breaks the Worker build (rule 7). See
21. * also history-file.ts and briefings-file.ts.
22. */
24. import { readFile, writeFile, mkdir } from 'node:fs/promises'
25. import { dirname } from 'node:path'
26. import { fileURLToPath } from 'node:url'
27. import type { Snapshot } from './collect.js'
28. import { errorMessage } from '@meridian/shared'
30. export const SNAPSHOT_FILE = new URL('../../../data/last-snapshot.json', import.meta.url)
32. /**
33. * Plain JSON throughout: no Date, Map or Set anywhere in Snapshot, and
34. * `ninetySpread` is four numbers. If a future field breaks that,
35. * `--render-only` is where it will show up.
36. */
37. export async function writeSnapshot(snap: Snapshot, file: URL = SNAPSHOT_FILE): Promise<void> {
38. try {
39. await mkdir(dirname(fileURLToPath(file)), { recursive: true })
40. await writeFile(file, `${JSON.stringify(snap)}\n`, 'utf8')
41. } catch {
42. // Read-only checkout, CI, a full disk. `--render-only` stops working and
43. // says so; a live build must not fail because a cache could not be written.
44. }
45. }
47. /**
48. * Missing and unusable are different answers, so this does not collapse them
49. * into null. "No cache yet" means run a sync; "there is a cache and it is not a
50. * snapshot" means something wrote a bad file, which is a problem of its own and
51. * the caller should be able to say so instead of guessing.
52. */
53. export type SnapshotRead =
54. | { ok: true; snap: Snapshot }
55. | { ok: false; missing: boolean; reason: string }
57. /**
58. * The fields checked are the ones decisions are made from. `syncedAt` dates every
59. * number on the page and is what the staleness check compares; the four sources
60. * carry both the data and whether it can be trusted. Everything else is left
61. * alone deliberately: being strict about fields nothing reads discards good
62. * records (rule 4).
63. *
64. * Rendering half a snapshot would put up a page that looks complete and is not,
65. * which is the one outcome this whole board exists to prevent. So a file failing
66. * these checks is refused rather than rendered around.
67. */
68. export async function readSnapshot(file: URL = SNAPSHOT_FILE): Promise<SnapshotRead> {
69. let raw: string
70. try {
71. raw = await readFile(file, 'utf8')
72. } catch {
73. return { ok: false, missing: true, reason: 'no file there yet' }
74. }
76. let parsed: unknown
77. try {
78. parsed = JSON.parse(raw)
79. } catch (err) {
80. return {
81. ok: false,
82. missing: false,
83. reason: `it is not valid JSON (${errorMessage(err)})`,
84. }
85. }
86. if (!parsed || typeof parsed !== 'object') {
87. return { ok: false, missing: false, reason: `it holds ${typeof parsed}, not an object` }
88. }
90. const s = parsed as Snapshot
91. if (typeof s.syncedAt !== 'string' || !s.syncedAt) {
92. return { ok: false, missing: false, reason: 'it has no syncedAt, so nothing on it can be dated' }
93. }
94. if (s.mode !== 'live' && s.mode !== 'fixtures') {
95. return { ok: false, missing: false, reason: `mode is ${JSON.stringify(s.mode)}, not 'live' or 'fixtures'` }
96. }
97. for (const key of ['leads', 'orderLines', 'tasks', 'ninety'] as const) {
98. const src = s[key]
99. if (!src || typeof src !== 'object' || typeof src.ok !== 'boolean' || !Array.isArray(src.data)) {
100. return { ok: false, missing: false, reason: `the '${key}' source is missing or malformed` }
101. }
102. }
103. // A cache without orderWindow is refused, not defaulted. Defaulting
104. // `truncated` to false would have this file assert that a sweep it knows
105. // nothing about was complete. The cache is disposable; re-syncing
106. // costs one run.
107. if (!s.orderWindow || typeof s.orderWindow.truncated !== 'boolean') {
108. return {
109. ok: false,
110. missing: false,
111. reason: 'it predates the orderWindow field, so whether its order counts are ' +
112. 'complete or truncated cannot be known',
113. }
114. }
115. // The same reasoning one field deeper. A cache without assignment coverage
116. // cannot say
117. // whether its per-person counts were complete or blind, and --render-only would
118. // put them on the page as though it could.
119. if (!s.orderWindow.assignmentFields || typeof s.orderWindow.assignmentFields.total !== 'number') {
120. return {
121. ok: false,
122. missing: false,
123. reason: 'it predates assignment field coverage, so whether its per-person counts are ' +
124. 'complete or blind cannot be known',
125. }
126. }
127. // Same reasoning again for the multi-key Fathom source. A cache without this
128. // field cannot say how many
129. // keys were asked or whether any of them was dark, and neither default is
130. // safe: `[]` renders as "live, from no keys", and leaving it undefined throws
131. // somewhere inside the view-model instead of here, where the reason is known.
132. if (s.fathomConfigured && !Array.isArray(s.fathomSources)) {
133. return {
134. ok: false,
135. missing: false,
136. reason: 'it predates per-key Fathom status, so whether every meeting key was ' +
137. 'read or one of them was dark cannot be known',
138. }
139. }
140. return { ok: true, snap: s }
141. }