main.ts

apps/dashboard/src/main.ts

1. #!/usr/bin/env tsx
2. /**
3. * Build the dashboard.
4. *
5. * pnpm dashboard live, using BITRIX_WEBHOOK_URL and PLINTH_API_KEY
6. * pnpm dashboard --fixtures sample data, no credentials needed
7. * pnpm dashboard --days 90 widen the Plinth order window (default 60)
8. * pnpm dashboard --render-only re-render the last sync, no API calls at all
9. *
10. * Writes dashboard.html in the repo root and prints a summary. Read-only
11. * throughout: no write method can be reached from here.
12. */
14. import { localStamp } from '@meridian/ninety-client'
15. import { writeFile } from 'node:fs/promises'
16. import { collect, headline, type Snapshot } from './collect.js'
17. import { classifyOrder } from '@meridian/plinth-client'
18. import { LEAD_STAGES, stageName } from '../../../config/bitrix-stages.js'
19. import { render } from './render.js'
20. import { FIXTURE_SNAPSHOT } from './fixtures.js'
21. import { rowFrom } from './history.js'
22. import { readHistory, recordRun } from './history-file.js'
23. import { buildBriefingPayload } from './briefing-payload.js'
24. import { readBriefings } from './briefings-file.js'
25. import { readSnapshot, writeSnapshot, SNAPSHOT_FILE } from './snapshot-file.js'
26. import { errorMessage } from '@meridian/shared'
28. const args = process.argv.slice(2)
29. const useFixtures = args.includes('--fixtures')
30. /**
31. * Re-render the page from the cached snapshot instead of syncing.
32. *
33. * This is the second half of `pnpm morning`. The briefings are written from one
34. * sync's numbers, and the page then has to be rebuilt to show them. Rebuilding
35. * with a fresh sync would move `syncedAt`, so the prose and the numbers would no
36. * longer describe the same moment and every clean run would call its own output
37. * stale. Re-rendering the same sync keeps that warning meaningful (see
38. * snapshot-file.ts).
39. *
40. * Needs no credentials, because it makes no requests.
41. */
42. const renderOnly = args.includes('--render-only')
43. const days = args.includes('--days') ? Number(args[args.indexOf('--days') + 1]) || 60 : 60
44. // Fixture runs must not pollute the real day-over-day history; a demo would
45. // otherwise become "yesterday" for tomorrow's briefing.
46. const historyAllowed = !useFixtures && !args.includes('--no-history')
48. /**
49. * Credentials come from the process environment only.
50. *
51. * There is no `.env` reader anywhere in this repo, on purpose. A credentials
52. * file in the working tree is readable by every tool and agent that touches the
53. * repo, and a secret that has been read is a secret that has to be rotated.
54. * Exporting from the shell profile keeps them out of the tree entirely.
55. *
56. * The trade is that a new terminal must have sourced the profile, and that is
57. * the failure this message exists to name: when nothing is set, the problem is
58. * almost always the shell, not the repo. Saying "not set" without saying where
59. * to look sends people hunting through code for a loader that does not exist.
60. */
61. function preflight(): void {
62. const required = ['NINETY_TOKEN', 'BITRIX_WEBHOOK_URL', 'PLINTH_API_KEY'] as const
63. const missing = required.filter((k) => !process.env[k])
64. if (!missing.length) return
66. console.error(` Missing from the environment: ${missing.join(', ')}`)
67. if (missing.length === required.length) {
68. console.error(` ALL of them are missing, which usually means this shell has not`)
69. console.error(` sourced your profile: a new terminal, or an editor-spawned one.`)
70. } else {
71. console.error(` ${required.length - missing.length} other credential(s) ARE set, so the profile did load.`)
72. console.error(` The ones above are absent from it, or spelled differently there.`)
73. }
74. console.error(`\n Credentials live in the shell profile; this repo has no .env reader.`)
75. console.error(` See what the shell actually has:`)
76. console.error(` env | grep -E 'NINETY|BITRIX|PLINTH_|ANTHROPIC'`)
77. console.error(` Then open a new terminal, or re-source the profile:`)
78. console.error(` source ~/.zshrc # or whichever profile you use\n`)
79. }
81. /** Order lines the team owes a move on, excluding leads. */
82. function orderOurMove(snap: Snapshot): number {
83. return snap.orderLines.data.filter(
84. (l) => classifyOrder(l.orderStatus, l.orderStatusId || null) === 'ours',
85. ).length
86. }
88. async function main(): Promise<void> {
89. let snap: Snapshot
90. if (renderOnly) {
91. const cached = await readSnapshot()
92. if (!cached.ok) {
93. // Fail rather than fall back to a live sync. A silent fallback is how this
94. // flag would quietly stop doing its job: the page would look right and the
95. // staleness warning would be back, with nothing saying the cache was gone.
96. console.error(`Cannot re-render: ${cached.reason}.`)
97. console.error(` ${decodeURIComponent(SNAPSHOT_FILE.pathname)}`)
98. if (cached.missing) {
99. console.error(`--render-only re-renders the last sync, and there has not been one.`)
100. } else {
101. console.error(`There is a file there but it is not a usable snapshot. Refusing to`)
102. console.error(`render half a page rather than rendering one that looks complete.`)
103. }
104. console.error(`Run \`pnpm dashboard\` first, or \`pnpm morning\` for the whole flow.`)
105. process.exit(1)
106. }
107. snap = cached.snap
108. console.log(`Re-rendering the sync from ${localStamp(snap.syncedAt)} CT. No API calls.\n`)
109. } else if (useFixtures) {
110. console.log('Fixture mode: no API calls.\n')
111. snap = FIXTURE_SNAPSHOT
112. } else {
113. preflight()
114. console.log(`Pulling Bitrix leads and Plinth order lines (last ${days} days)...\n`)
115. // The file source is passed explicitly: collect.ts is runtime-neutral so it
116. // can also run in the Worker, which has no filesystem.
117. snap = await collect(process.env, days)
118. }
120. const h = headline(snap)
121. const today = rowFrom(h, new Date(snap.syncedAt))
123. // A run where a source died reports zeros, and a zero recorded today becomes
124. // tomorrow's "yesterday", so the morning after an outage the briefing would
125. // announce that the design queue grew by 37 overnight. It also must not show a
126. // delta of its own: "down 146" is not news, it is the outage. So a broken run
127. // neither writes history nor reads it.
128. const sourcesOk = snap.leads.ok && snap.orderLines.ok && snap.tasks.ok
129. // Read off the snapshot, not off the flag: on a --render-only run the flag is
130. // absent but the cached sync may still be fixture data.
131. const isFixtures = snap.mode === 'fixtures'
132. const keepHistory = historyAllowed && sourcesOk && !renderOnly
134. // Record first, then render against what was on file before this run;
135. // otherwise the page would diff today against itself and every delta is zero.
136. //
137. // A --render-only run reads but never records: the row for today was written by
138. // the sync it is re-rendering, and writing it again would be the second half of
139. // `pnpm morning` overwriting the first. Reading back the full file including
140. // today is safe because `previousRun()` filters to `r.day < today`, so today's
141. // own row cannot become its own comparison, and nothing else on the page
142. // iterates the array.
143. const history = !sourcesOk || isFixtures ? [] : keepHistory ? await recordRun(today) : await readHistory()
145. // Written briefings from the previous brief.py run, if any. Rendering them is
146. // what makes the model output visible on the board instead of only in a
147. // terminal. See briefings-file.ts for why the chain is file-mediated.
148. const briefings = await readBriefings()
150. const html = render(snap, h, history, today.day, briefings)
151. const out = new URL('../../../dashboard.html', import.meta.url)
152. await writeFile(out, html, 'utf8')
154. // Cache the sync so `--render-only` can rebuild this exact page later. Not on
155. // a --render-only run, which would only rewrite what it just read.
156. if (!renderOnly) await writeSnapshot(snap)
158. // The model-facing payload. Written on every run, including fixture runs:
159. // a consumer needs something to develop against without credentials. It is a
160. // separate file from the HTML on purpose: the page is for people, this is for
161. // whatever generates the analysis, and neither should have to parse the other.
162. //
163. // Not rewritten on a --render-only run. `generatedAt` is `snap.syncedAt`, so
164. // rewriting it from the cached snapshot would produce a byte-identical file,
165. // and "render only" should mean what it says. The existing payload is already
166. // the one the briefings were written from.
167. const payload = buildBriefingPayload(snap)
168. const payloadOut = new URL('../../../briefing-payload.json', import.meta.url)
169. if (!renderOnly) {
170. await writeFile(payloadOut, `${JSON.stringify(payload, null, 2)}\n`, 'utf8')
171. }
173. const row = (k: string, v: string | number) => console.log(` ${k.padEnd(22)}${v}`)
174. // Split, because one number covering both is unreadable: leads and order
175. // lines are different kinds of work, with different owners and urgency, and
176. // their sum is a figure nobody can act on.
177. const leadOurs = h.ourMove - orderOurMove(snap)
178. row('our move', `${h.ourMove} (${leadOurs} leads + ${orderOurMove(snap)} order lines)`)
179. row('design queue', h.designQueue)
180. row('client replied', h.needsReply)
181. row('waiting on client', h.waitingOnClient)
182. row('at vendor / transit', h.atVendor)
183. // Three numbers, never one. Open leads can be mostly finished work, and the
184. // excluded counts are shown rather than subtracted, because a number that
185. // quietly shrinks is indistinguishable from one that is wrong.
186. const excluded = [
187. h.completedLeads ? `${h.completedLeads} completed` : null,
188. h.noiseLeads ? `${h.noiseLeads} automated` : null,
189. ].filter(Boolean)
190. row(
191. 'open leads',
192. `${h.realLeads} still open` + (excluded.length ? ` (excluding ${excluded.join(' and ')})` : ''),
193. )
194. // Commitments and assignments, never one alone. A bare row count overstates
195. // the work whenever an item is carried by more than one person.
196. row(
197. 'commitments',
198. h.commitments === null
199. ? 'not tracked (Ninety unavailable)'
200. : `${h.commitments} across ${h.assignments} assignment(s)` +
201. (h.sharedCommitments ? `, ${h.sharedCommitments} shared` : ''),
202. )
203. row('to-dos past a review', h.lateTodos === null ? 'not tracked' : h.lateTodos)
205. // Shape diagnostics. A small number is not automatically a wrong number (a
206. // 60-day window is mostly finished orders), but "4 our move" is unreadable
207. // without knowing whether 4 orders came back or 400. Print the denominator.
208. if (snap.orderLines.ok) {
209. const lines = snap.orderLines.data
210. const orders = new Set(lines.map((l) => l.orderId)).size
211. console.log(`\n Plinth: ${orders} orders, ${lines.length} product lines in the last ${days} days`)
212. const byClass = new Map<string, number>()
213. for (const l of lines) {
214. const c = classifyOrder(l.orderStatus, l.orderStatusId || null)
215. byClass.set(c, (byClass.get(c) ?? 0) + 1)
216. }
217. console.log(` ${[...byClass].map(([c, n]) => `${c}=${n}`).join(' ') || '(none)'}`)
218. console.log(` fetched over ${snap.orderWindow.pages} page(s)`)
219. // Compared in lines, because the cap is in lines: an order count against a
220. // line limit could never fire (100 lines is about 60 orders).
221. if (snap.orderWindow.truncated) {
222. console.error(` TRUNCATED at the page cap: these counts are a FLOOR, not a total.`)
223. console.error(` Narrow --days or raise maxPages before trusting any order number.`)
224. }
225. }
227. if (snap.leads.ok) {
228. const w = snap.leadWindow
229. const real = snap.leads.data.filter((l) => !l.noise)
230. console.log(` Bitrix leads: ${snap.leads.data.length} open` +
231. (w.sinceDays === null ? ' (no date floor)' : `, created in the last ${w.sinceDays} days`) +
232. ` over ${w.pages} page(s)`)
233. if (w.truncated) {
234. console.error(` TRUNCATED at the page cap: this count is a FLOOR, not a total.`)
235. console.error(` Narrow the window or raise maxPages before trusting it.`)
236. }
238. // Stage breakdown, because "our move: 212" is unreadable without it. If one
239. // stage holds almost all of them, that stage is the story, and if that
240. // stage is New/Unassigned, the story is automation pollution rather than
241. // work, since that is where email-captured leads land.
242. const byStage = new Map<string, number>()
243. for (const l of real) {
244. const name = stageName(l.statusId) ?? l.statusId
245. byStage.set(name, (byStage.get(name) ?? 0) + 1)
246. }
247. const top = [...byStage].sort((a, b) => b[1] - a[1]).slice(0, 8)
248. console.log(` ${real.length} after the noise filter, by stage:`)
249. for (const [name, n] of top) {
250. const stage = LEAD_STAGES.find((s) => s.name === name || s.id === name)
251. const cls = stage ? stage.class : 'UNCLASSIFIED -> counted as ours'
252. console.log(` ${String(n).padStart(4)} ${name} (${cls})`)
253. }
255. if (h.unknownLeadStages.length) {
256. const share = Math.round((h.ourMoveUnclassified / Math.max(h.ourMove, 1)) * 100)
257. console.error(``)
258. console.error(` UNCLASSIFIED LEAD STAGES: ${h.ourMoveUnclassified} of "our move" (${share}%) is unclassified.`)
259. console.error(` config/bitrix-stages.ts was written from a small lead sample. The real`)
260. console.error(` pipeline mostly lives in stages it has never seen, and every unknown`)
261. console.error(` stage defaults to "ours", which is why the headline reads the way it does.`)
262. console.error(` Until these are classified, "our move" is not a workload number.`)
263. for (const u of h.unknownLeadStages.slice(0, 10)) {
264. console.error(` ${String(u.count).padStart(4)} ${u.id}`)
265. }
266. console.error(` Add each to LEAD_STAGES with the right class. "JUNK" is almost certainly`)
267. console.error(` 'terminal'; the numeric ids are Bitrix defaults you will recognise in the UI.`)
268. }
269. }
271. if (!snap.leads.ok) console.error(`\n BITRIX FAILED: ${snap.leads.error}`)
272. if (!snap.orderLines.ok) console.error(` Plinth FAILED: ${snap.orderLines.error}`)
273. if (!snap.tasks.ok) console.error(` TASKS FAILED: ${snap.tasks.error}`)
274. // The client's error already says what happened; the 403 carries its own
275. // explanation, so nothing is appended here (rule 1).
276. if (!snap.ninety.ok) console.error(` NINETY FAILED: ${snap.ninety.error}`)
277. if (historyAllowed && !keepHistory && !renderOnly) {
278. console.error(`\n Not recorded in the delta history. A run with a dead source would`)
279. console.error(` become tomorrow's "yesterday" and invent a swing that never happened.`)
280. }
281. if (h.unknownStatuses.length) {
282. console.error(`\n Unclassified product statuses (counted as "our move"):`)
283. for (const s of h.unknownStatuses) console.error(` ${s}`)
284. console.error(` Add them to packages/plinth-client/src/status-taxonomy.ts`)
285. }
287. console.log(`\nWrote ${decodeURIComponent(out.pathname)}`)
288. if (renderOnly) {
289. console.log(`Left ${decodeURIComponent(payloadOut.pathname)} alone. It is the one`)
290. console.log(`the briefings on this page were written from.`)
291. } else {
292. console.log(`Wrote ${decodeURIComponent(payloadOut.pathname)} (schema ${payload.schemaVersion}, ${payload.people.length} people)`)
293. }
294. if (!briefings) {
295. console.log(`\n No written briefing on this page yet. Run \`pnpm morning\` to sync,`)
296. console.log(` write every briefing, and re-render with them included.`)
297. } else if (briefings.payloadGeneratedAt !== snap.syncedAt) {
298. console.log(`\n The written briefing on this page came from an EARLIER sync. Re-run`)
299. console.log(` \`pnpm morning\` so the prose and the numbers describe the same moment.`)
300. }
301. if (!snap.leads.ok || !snap.orderLines.ok) {
302. console.log('One or more sources failed. The page renders the failure rather than showing zero.')
303. }
304. }
306. main().catch((err) => {
307. console.error('\nDashboard build failed:', errorMessage(err))
308. process.exit(1)
309. })