Public: anyone can read this; the crew can change it.
The client timeline says under each open date what the buyer or seller does for it, like "Book your inspector this week", so the handout answers "what do I do now?" #140
Check · Review · Land · Live done — Landed and live in production.
mason/deal-clock:mason/136-the-client-timeline-says-under-each-open → main 2 commits fork 1 thread · 1 unresolved
10 files
changed +160
−8
README.md +3 −1
| @@ -162,7 +162,9 @@ Signed out, `/` shows what deal-clock does, three short points, a still picture | ||
| 162 | 162 | Add all to calendar does the same for every open date of every open deal. Download spreadsheet gives the same dates as one file that opens in Excel or Numbers; the Closed list links one with the closed deals too. |
| 163 | 163 | 13. **Print the client timeline.** On a sample deal's page, tap Client |
| 164 | 164 | timeline: its dates in order, who owes each and whether it is done, |
| 165 | upcoming or overdue, with no controls. Tap Print to make the one-page handout | |
| 165 | upcoming or overdue, with no controls. Under each open date is one line of what the buyer or seller | |
| 166 | does for it (both, labelled, on a deal for both sides); the terminal prints it dim | |
| 167 | under the date and the MCP tool returns it as the date's `todo` list. Tap Print to make the one-page handout | |
| 166 | 168 | for a buyer or seller (the browser's own print works too). In the terminal, open the deal with o and press |
| 167 | 169 | t; over MCP, an agent asks for the `client_timeline` tool. |
| 168 | 170 | 14. **Fix an address.** On a deal's page, Edit address corrects a typo in |
docs/design/areas/timeline.md +1
| @@ -9,3 +9,4 @@ Classes on `/deals/:id/timeline`, the page handed to a client. It prints portrai | ||
| 9 | 9 | - `.timeline-list` — the ordered list of dates, no markers. |
| 10 | 10 | - `.timeline-row` — one date; never split across printed pages. |
| 11 | 11 | - `.timeline-date`, `.timeline-label`, `.timeline-owner`, `.timeline-status` — its four facts; the status is words first, with a mark. |
| 12 | - `.timeline-todo` — under an open date, one line of what the client does; spans the row and prints with it. |
src/guidance.test.ts added +30
| @@ -0,0 +1,30 @@ | ||
| 1 | import { expect, test } from "bun:test"; | |
| 2 | import { KINDS } from "./deadlines.ts"; | |
| 3 | import { guidance, guidanceLine } from "./guidance.ts"; | |
| 4 | ||
| 5 | test("a buyer gets buyer lines", () => { | |
| 6 | expect(guidance("inspection", "buyer", true)).toEqual([{ label: "", line: "Book your inspector this week; the period ends on this date." }]); | |
| 7 | }); | |
| 8 | ||
| 9 | test("a seller gets seller lines", () => { | |
| 10 | expect(guidance("inspection", "listing", true)).toEqual([{ label: "", line: "Expect the buyer's inspector; leave the utilities on." }]); | |
| 11 | }); | |
| 12 | ||
| 13 | test("both sides shows each, labelled", () => { | |
| 14 | const g = guidance("closing", "both", true); | |
| 15 | expect(g.map((x) => x.label)).toEqual(["Buyer", "Seller"]); | |
| 16 | expect(g[0]!.line).toContain("photo ID"); | |
| 17 | }); | |
| 18 | ||
| 19 | test("a done or waived date gets no line", () => { | |
| 20 | expect(guidance("inspection", "buyer", false)).toEqual([]); | |
| 21 | }); | |
| 22 | ||
| 23 | test("every standard kind has a line on each side; custom has none", () => { | |
| 24 | for (const k of KINDS.filter((k) => k !== "custom")) { | |
| 25 | expect(guidanceLine(k, "buyer")).toBeString(); | |
| 26 | expect(guidanceLine(k, "listing")).toBeString(); | |
| 27 | } | |
| 28 | expect(guidanceLine("custom", "buyer")).toBeUndefined(); | |
| 29 | expect(guidanceLine("contract", "buyer")).toBeUndefined(); | |
| 30 | }); |
src/guidance.ts added +55
| @@ -0,0 +1,55 @@ | ||
| 1 | /** | |
| 2 | * What a client does for an open date, in one plain line: kind and side in, | |
| 3 | * a string or nothing out. General advice in line with common US practice; | |
| 4 | * a broker may review the wording. Nothing here is stored. | |
| 5 | */ | |
| 6 | ||
| 7 | import type { Kind } from "./deadlines.ts"; | |
| 8 | import type { Side } from "./side.ts"; | |
| 9 | ||
| 10 | type Lines = Partial<Record<Kind, string>>; | |
| 11 | ||
| 12 | const BUYER: Lines = { | |
| 13 | earnest: "Wire or bring your deposit to the title company. Call them to confirm wiring instructions; never trust emailed ones.", | |
| 14 | inspection: "Book your inspector this week; the period ends on this date.", | |
| 15 | appraisal: "Be ready for the appraiser to visit, and tell your lender about any questions they raise.", | |
| 16 | financing: "Answer your lender's document requests the same day.", | |
| 17 | title: "Read the title company's report and ask your agent about anything you do not understand.", | |
| 18 | walkthrough: "Check that repairs are done and the home is as agreed.", | |
| 19 | closing: "Bring photo ID; funds are wired, not carried.", | |
| 20 | }; | |
| 21 | ||
| 22 | const SELLER: Lines = { | |
| 23 | earnest: "Confirm with the title company that the buyer's deposit has arrived.", | |
| 24 | inspection: "Expect the buyer's inspector; leave the utilities on.", | |
| 25 | appraisal: "Keep the home tidy and easy to get into for the appraiser.", | |
| 26 | financing: "Respond quickly if the buyer's lender asks you for anything.", | |
| 27 | title: "Answer the title company's questions about the property and any loans on it.", | |
| 28 | walkthrough: "Finish agreed repairs, clear out your belongings and leave the home as agreed.", | |
| 29 | closing: "Bring photo ID and your keys, garage openers and codes.", | |
| 30 | }; | |
| 31 | ||
| 32 | const TABLE: Readonly<Record<"buyer" | "listing", Lines>> = { buyer: BUYER, listing: SELLER }; | |
| 33 | ||
| 34 | export interface Guidance { | |
| 35 | /** "" for a single side; "Buyer" or "Seller" when a deal is for both. */ | |
| 36 | readonly label: string; | |
| 37 | readonly line: string; | |
| 38 | } | |
| 39 | ||
| 40 | /** The line for one kind on one side: nothing for the contract date, a custom date or an unknown kind. */ | |
| 41 | export function guidanceLine(kind: string, side: "buyer" | "listing"): string | undefined { | |
| 42 | return (TABLE[side] as Record<string, string | undefined>)[kind]; | |
| 43 | } | |
| 44 | ||
| 45 | /** The lines for an open date: none when it is done or waived; both sides, each labelled, on a deal for both. */ | |
| 46 | export function guidance(kind: string, side: Side, open: boolean): Guidance[] { | |
| 47 | if (!open) return []; | |
| 48 | const sides = side === "both" ? (["buyer", "listing"] as const) : ([side] as const); | |
| 49 | const out: Guidance[] = []; | |
| 50 | for (const s of sides) { | |
| 51 | const line = guidanceLine(kind, s); | |
| 52 | if (line !== undefined) out.push({ label: side === "both" ? (s === "buyer" ? "Buyer" : "Seller") : "", line }); | |
| 53 | } | |
| 54 | return out; | |
| 55 | } |
src/mcp.ts +2 −2
| @@ -84,12 +84,12 @@ export const tools: readonly Tool[] = [ | ||
| 84 | 84 | }, |
| 85 | 85 | { |
| 86 | 86 | name: "client_timeline", |
| 87 | description: "One deal's dates as a client would receive them: address, the agent, and each date in due order with who owes it and whether it is Done, Upcoming or Overdue. No contacts, drafts or reasons.", | |
| 87 | description: "One deal's dates as a client would receive them: address, the agent, and each date in due order with who owes it and whether it is Done, Upcoming or Overdue, and for an open date todo: what the buyer or seller does for it. No contacts, drafts or reasons.", | |
| 88 | 88 | inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] }, |
| 89 | 89 | run: (db, who, args) => { |
| 90 | 90 | const got = getDeal(db, who, { id: Number(args.id) }); |
| 91 | 91 | if (!got.ok) return got; |
| 92 | const dates = timelineRows(got.value, today()).map(({ label, due, role, name, status }) => ({ label, due, owed_by: { role, name: name ?? null }, status })); | |
| 92 | const dates = timelineRows(got.value, today()).map(({ label, due, role, name, status, todo }) => ({ label, due, owed_by: { role, name: name ?? null }, status, todo: todo.map((g) => (g.label === "" ? g.line : `${g.label}: ${g.line}`)) })); | |
| 93 | 93 | return { ok: true, value: { address: got.value.address, sale_price: got.value.sale_price, earnest_amount: got.value.earnest_amount, closing_time: got.value.closing_time, closing_place: got.value.closing_place, agent: agentOf(db), dates } }; |
| 94 | 94 | }, |
| 95 | 95 | }, |
src/pages/timeline.ts +9 −1
| @@ -15,8 +15,16 @@ import { asset, escape } from "../http.ts"; | ||
| 15 | 15 | import { timelineRows } from "../timeline.ts"; |
| 16 | 16 | import type { Who } from "../who.ts"; |
| 17 | 17 | import { contactLinks } from "./contact.ts"; |
| 18 | import type { Guidance } from "../guidance.ts"; | |
| 18 | 19 | import { layout } from "./layout.ts"; |
| 19 | 20 | |
| 21 | /** The "what you do" lines under an open date; each labelled when the deal is for both sides. */ | |
| 22 | function todo(lines: Guidance[]): string { | |
| 23 | return lines | |
| 24 | .map((g) => `<p class="timeline-todo">${g.label === "" ? "" : `<b>${escape(g.label)}:</b> `}${escape(g.line)}</p>`) | |
| 25 | .join(""); | |
| 26 | } | |
| 27 | ||
| 20 | 28 | export function timelinePage(input: { who: Who; agent?: Agent | undefined; deal: DealView; on: string }): string { |
| 21 | 29 | const { who, deal, on } = input; |
| 22 | 30 | const agent = input.agent ?? defaults; |
| @@ -27,7 +35,7 @@ export function timelinePage(input: { who: Who; agent?: Agent | undefined; deal: | ||
| 27 | 35 | <p class="timeline-date">${escape(r.spoken)}</p> |
| 28 | 36 | <p class="timeline-label"><b>${escape(r.label)}</b></p> |
| 29 | 37 | <p class="timeline-owner">${escape(r.role)}${r.name === undefined ? "" : ` · ${escape(r.name)}`}</p> |
| 30 | <p class="timeline-status"><span aria-hidden="true">${r.mark}</span> ${r.doneLine === "" ? r.status : escape(r.doneLine)}</p> | |
| 38 | <p class="timeline-status"><span aria-hidden="true">${r.mark}</span> ${r.doneLine === "" ? r.status : escape(r.doneLine)}</p>${todo(r.todo)} | |
| 31 | 39 | </li>`, |
| 32 | 40 | ) |
| 33 | 41 | .join(""); |
src/terminal.ts +4 −3
| @@ -802,9 +802,10 @@ export function terminal( | ||
| 802 | 802 | if (deal === undefined) lines.push(dim("That deal is gone.")); |
| 803 | 803 | else { |
| 804 | 804 | lines.push(bold(`Client timeline — ${deal.address}`), dim(`${agentNow().name}, ${agentNow().brokerage}`), dim(`${agentNow().phone} · ${agentNow().email}`), ""); |
| 805 | timelineRows(deal, day).forEach((r) => | |
| 806 | lines.push(` ${tint(r.urgency, `${r.spoken.padEnd(16)} ${r.status.padEnd(9)}`)} ${r.label} · ${r.name === undefined ? r.role : `${r.role}: ${r.name}`}`), | |
| 807 | ); | |
| 805 | timelineRows(deal, day).forEach((r) => { | |
| 806 | lines.push(` ${tint(r.urgency, `${r.spoken.padEnd(16)} ${r.status.padEnd(9)}`)} ${r.label} · ${r.name === undefined ? r.role : `${r.role}: ${r.name}`}`); | |
| 807 | r.todo.forEach((g) => lines.push(` ${dim(`${g.label === "" ? "" : `${g.label}: `}${g.line}`)}`)); | |
| 808 | }); | |
| 808 | 809 | } |
| 809 | 810 | } else if (view === "deal") { |
| 810 | 811 | const deal = openDeal(); |
src/timeline.test.ts +49
| @@ -6,6 +6,7 @@ import { join } from "node:path"; | ||
| 6 | 6 | import { addDeadline, addParty, createDeal, getDeal, markDone, removeDeadline } from "./deals.ts"; |
| 7 | 7 | import { terminal } from "./terminal.ts"; |
| 8 | 8 | import { openDb } from "./db.ts"; |
| 9 | import { tools } from "./mcp.ts"; | |
| 9 | 10 | import { timelinePage } from "./pages/timeline.ts"; |
| 10 | 11 | import type { Who } from "./who.ts"; |
| 11 | 12 | |
| @@ -102,3 +103,51 @@ test("prints the agent's name, brokerage, phone and email once, and each status | ||
| 102 | 103 | expect(html).toContain("[email protected]"); |
| 103 | 104 | expect(html).toMatch(/timeline-status"><span aria-hidden="true">\S+<\/span> (Done|Upcoming|Overdue)/); |
| 104 | 105 | }); |
| 106 | ||
| 107 | test("an open inspection shows the buyer's line; a done date shows none", () => { | |
| 108 | const html = page("2026-10-05"); | |
| 109 | expect(html).toContain('<p class="timeline-todo">Book your inspector this week; the period ends on this date.</p>'); | |
| 110 | const done = html.slice(html.indexOf('data-u="done"'), html.indexOf("</li>", html.indexOf('data-u="done"'))); | |
| 111 | expect(done).toContain("Done"); | |
| 112 | expect(done).not.toContain("timeline-todo"); | |
| 113 | }); | |
| 114 | ||
| 115 | test("a seller-side deal shows the seller's line unlabelled; a deal for both labels each", () => { | |
| 116 | const sell = createDeal(db, alice, { openAnyway: true, address: "1 Sell St", buyer: "B", seller: "S", contractDate: "2026-10-01", closingDate: "2026-11-06", side: "listing" }); | |
| 117 | const both = createDeal(db, alice, { openAnyway: true, address: "2 Both St", buyer: "B", seller: "S", contractDate: "2026-10-01", closingDate: "2026-11-06", side: "both" }); | |
| 118 | if (!sell.ok || !both.ok) throw new Error("setup"); | |
| 119 | const render = (i: number): string => { | |
| 120 | const d = getDeal(db, alice, { id: i }); | |
| 121 | if (!d.ok) throw new Error(d.message); | |
| 122 | return timelinePage({ who: alice, deal: d.value, on: "2026-10-05" }); | |
| 123 | }; | |
| 124 | const s = render(sell.value.id); | |
| 125 | expect(s).toContain("leave the utilities on.</p>"); | |
| 126 | expect(s).toContain('<p class="timeline-todo">Expect the buyer'); | |
| 127 | expect(s).not.toContain("<b>Seller:</b>"); | |
| 128 | const b = render(both.value.id); | |
| 129 | expect(b).toContain('<p class="timeline-todo"><b>Buyer:</b> Book your inspector'); | |
| 130 | expect(b).toContain('<p class="timeline-todo"><b>Seller:</b> Expect the buyer'); | |
| 131 | }); | |
| 132 | ||
| 133 | test("the terminal prints the line under an open date and none under a done one", () => { | |
| 134 | const t = terminal(db, alice, { title: "deal-clock", where: "test", agent: { name: "Dana", brokerage: "HP", phone: "555", email: "[email protected]" }, on: () => "2026-10-25" }); | |
| 135 | const row = (): string => t.screen().join("\n").split("\n").find((l) => l.startsWith("▸")) ?? ""; | |
| 136 | for (let i = 0; i < 300 && !row().includes("HOA review ends"); i++) t.press("j"); | |
| 137 | t.press("o"); | |
| 138 | t.press("t"); | |
| 139 | const screen = t.screen().join("\n").replace(/\x1b\[[0-9;]*m/g, ""); | |
| 140 | expect(screen).toContain(" Bring photo ID; funds are wired, not carried."); | |
| 141 | expect(screen).not.toContain("Wire or bring your deposit"); | |
| 142 | }); | |
| 143 | ||
| 144 | test("the MCP tool gives each open date its todo and a done date an empty one", () => { | |
| 145 | const tool = tools.find((x) => x.name === "client_timeline")!; | |
| 146 | const r = tool.run(db, alice, { id }); | |
| 147 | if (!r.ok) throw new Error(r.message); | |
| 148 | const dates = (r.value as { dates: { label: string; status: string; todo: string[] }[] }).dates; | |
| 149 | const closing = dates.find((d) => d.label === "Closing")!; | |
| 150 | expect(closing.todo).toEqual(["Bring photo ID; funds are wired, not carried."]); | |
| 151 | const done = dates.find((d) => d.status === "Done")!; | |
| 152 | expect(done.todo).toEqual([]); | |
| 153 | }); |
src/timeline.ts +4 −1
| @@ -7,6 +7,7 @@ | ||
| 7 | 7 | |
| 8 | 8 | import { doneLine, spoken, urgencyOf, type Urgency } from "./dates.ts"; |
| 9 | 9 | import type { DealView } from "./deals.ts"; |
| 10 | import { guidance, type Guidance } from "./guidance.ts"; | |
| 10 | 11 | import { owner } from "./week.ts"; |
| 11 | 12 | |
| 12 | 13 | export type TimelineStatus = "Done" | "Waived" | "Upcoming" | "Overdue"; |
| @@ -34,12 +35,14 @@ export interface TimelineRow { | ||
| 34 | 35 | readonly doneLine: string; |
| 35 | 36 | readonly mark: string; |
| 36 | 37 | readonly urgency: Urgency; |
| 38 | /** What the client does for it: lines for an open date only, each labelled on a deal for both sides. */ | |
| 39 | readonly todo: Guidance[]; | |
| 37 | 40 | } |
| 38 | 41 | |
| 39 | 42 | export function timelineRows(deal: DealView, on: string): TimelineRow[] { |
| 40 | 43 | return deal.deadlines.map((d) => { |
| 41 | 44 | const u = urgencyOf(d, on); |
| 42 | 45 | const { name, role } = owner(deal, d); |
| 43 | return { label: d.label, due: d.due, spoken: spoken(d.due), role, name, status: STATUS[u].word, doneLine: u === "done" && d.done_on !== null ? doneLine(d.due, d.done_on) : "", mark: STATUS[u].mark, urgency: u }; | |
| 46 | return { label: d.label, due: d.due, spoken: spoken(d.due), role, name, status: STATUS[u].word, doneLine: u === "done" && d.done_on !== null ? doneLine(d.due, d.done_on) : "", mark: STATUS[u].mark, urgency: u, todo: guidance(d.kind, deal.side, u !== "done" && u !== "waived") }; | |
| 44 | 47 | }); |
| 45 | 48 | } |
static/app.css +3
| @@ -869,6 +869,9 @@ a.week-row { | ||
| 869 | 869 | .timeline-status { |
| 870 | 870 | font-weight: 650; |
| 871 | 871 | } |
| 872 | .timeline-row .timeline-todo { | |
| 873 | grid-column: 1 / -1; | |
| 874 | } | |
| 872 | 875 | .timeline-row[data-u="overdue"] .timeline-status { |
| 873 | 876 | color: var(); |
| 874 | 877 | } |
new above
offline
Guidance is rendered only here; the terminal view and MCP tool also show the timeline and should carry the same lines. The label rendering for both-sides is untested at page level.