push-guard.ts

apps/dashboard/src/push-guard.ts

1. /**
2. * Whether the local artifacts are safe to publish to the deployed board.
3. * Runtime-neutral and pure, so it can be tested without a filesystem or a network.
4. *
5. * `pnpm push` writes straight into the Worker's KV, which is what the team
6. * reads. There is no review step between a laptop and that
7. * page, so the checks that would normally be someone noticing have to be here.
8. *
9. * The one that matters most is fixture mode. `pnpm dashboard --fixtures` writes
10. * the same filenames as a live run, so a push immediately after one would put
11. * sample data on the production board under "live" source pills: the exact
12. * failure `Snapshot.mode` exists to prevent, with an audience.
13. */
15. export interface PushInputs {
16. /** `mode` from briefing-payload.json. */
17. payloadMode: string | null | undefined
18. /** `generatedAt` from briefing-payload.json, equal to the sync's syncedAt. */
19. payloadGeneratedAt: string | null | undefined
20. /** Length of dashboard.html, to catch a truncated or empty render. */
21. htmlBytes: number
22. /** `mode` from briefings.json. Null when no briefings exist yet. */
23. briefingsMode?: string | null
24. /** `payloadGeneratedAt` from briefings.json: the sync the prose describes. */
25. briefingsPayloadGeneratedAt?: string | null
26. /** How many briefings were written. */
27. briefingCount?: number
28. }
30. export interface PushVerdict {
31. ok: boolean
32. /** Why the push must not happen. Non-empty means refuse. */
33. refusals: string[]
34. /** Worth saying out loud, but not a reason to stop. */
35. warnings: string[]
36. }
38. /** A page this small is not a dashboard; the last render must have failed. */
39. const MIN_HTML_BYTES = 20_000
41. export function checkPush(input: PushInputs): PushVerdict {
42. const refusals: string[] = []
43. const warnings: string[] = []
45. // Fixtures must never reach the deployed board. Sample data renders under the
46. // same filenames as live data; only `mode` distinguishes them.
47. if (input.payloadMode === 'fixtures') {
48. refusals.push(
49. 'briefing-payload.json is FIXTURE data. Pushing it would put sample orders on ' +
50. 'the board the team reads. Run `pnpm dashboard` (no --fixtures), then push.',
51. )
52. }
53. if (input.briefingsMode === 'fixtures') {
54. refusals.push(
55. 'briefings.json was written from FIXTURE data, so its prose names people as ' +
56. 'holding work that is not real. Regenerate it from a live sync.',
57. )
58. }
59. if (input.payloadMode !== 'live' && input.payloadMode !== 'fixtures') {
60. refusals.push(
61. `briefing-payload.json has mode ${JSON.stringify(input.payloadMode)}, which this ` +
62. 'does not recognise. Refusing rather than guessing whether it is real.',
63. )
64. }
66. if (!input.payloadGeneratedAt) {
67. refusals.push('briefing-payload.json has no generatedAt, so nothing on it can be dated.')
68. }
70. if (input.htmlBytes < MIN_HTML_BYTES) {
71. refusals.push(
72. `dashboard.html is only ${input.htmlBytes} bytes, well under the ${MIN_HTML_BYTES} a ` +
73. 'real render produces. Re-run `pnpm dashboard` and check it for errors.',
74. )
75. }
77. // Briefings are optional. Absent is a normal state and the page says so, but it
78. // is worth naming: a silent push of numbers-only looks identical to a push
79. // that included the prose.
80. if (!input.briefingCount) {
81. warnings.push(
82. 'No written briefings to push. The board will render the deterministic ' +
83. 'briefing and say the written one was not generated. Run `pnpm morning` for both.',
84. )
85. } else if (
86. input.briefingsPayloadGeneratedAt &&
87. input.briefingsPayloadGeneratedAt !== input.payloadGeneratedAt
88. ) {
89. warnings.push(
90. 'The briefings were written from an EARLIER sync than the page being pushed, so ' +
91. 'the board will carry a staleness caveat. Run `pnpm morning` to pair them.',
92. )
93. }
95. return { ok: refusals.length === 0, refusals, warnings }
96. }