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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

mason/deal-clock:mason/136-the-client-timeline-says-under-each-open → main 2 commits fork 1 thread · 1 unresolved

  • Merged. mason/136-the-client-timeline-says-under-each-open was merged into main as b57bd67.

Review

Sign in to review this change.
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
162162 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.
163163 13. **Print the client timeline.** On a sample deal's page, tap Client
164164 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
166168 for a buyer or seller (the browser's own print works too). In the terminal, open the deal with o and press
167169 t; over MCP, an agent asks for the `client_timeline` tool.
168170 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
99 - `.timeline-list` — the ordered list of dates, no markers.
1010 - `.timeline-row` — one date; never split across printed pages.
1111 - `.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[] = [
8484 },
8585 {
8686 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.",
8888 inputSchema: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
8989 run: (db, who, args) => {
9090 const got = getDeal(db, who, { id: Number(args.id) });
9191 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}`)) }));
9393 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 } };
9494 },
9595 },
src/pages/timeline.ts +9 −1
@@ -15,8 +15,16 @@ import { asset, escape } from "../http.ts";
1515 import { timelineRows } from "../timeline.ts";
1616 import type { Who } from "../who.ts";
1717 import { contactLinks } from "./contact.ts";
18 import type { Guidance } from "../guidance.ts";
1819 import { layout } from "./layout.ts";
1920
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
2028 export function timelinePage(input: { who: Who; agent?: Agent | undefined; deal: DealView; on: string }): string {
2129 const { who, deal, on } = input;
2230 const agent = input.agent ?? defaults;
@@ -27,7 +35,7 @@ export function timelinePage(input: { who: Who; agent?: Agent | undefined; deal:
2735 <p class="timeline-date">${escape(r.spoken)}</p>
2836 <p class="timeline-label"><b>${escape(r.label)}</b></p>
2937 <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)}
3139 </li>`,
3240 )
outdated

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.

3341 .join("");
src/terminal.ts +4 −3
@@ -802,9 +802,10 @@ export function terminal(
802802 if (deal === undefined) lines.push(dim("That deal is gone."));
803803 else {
804804 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 });
808809 }
809810 } else if (view === "deal") {
810811 const deal = openDeal();
src/timeline.test.ts +49
@@ -6,6 +6,7 @@ import { join } from "node:path";
66 import { addDeadline, addParty, createDeal, getDeal, markDone, removeDeadline } from "./deals.ts";
77 import { terminal } from "./terminal.ts";
88 import { openDb } from "./db.ts";
9 import { tools } from "./mcp.ts";
910 import { timelinePage } from "./pages/timeline.ts";
1011 import type { Who } from "./who.ts";
1112
@@ -102,3 +103,51 @@ test("prints the agent's name, brokerage, phone and email once, and each status
102103 expect(html).toContain("[email protected]");
103104 expect(html).toMatch(/timeline-status"><span aria-hidden="true">\S+<\/span> (Done|Upcoming|Overdue)/);
104105 });
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 @@
77
88 import { doneLine, spoken, urgencyOf, type Urgency } from "./dates.ts";
99 import type { DealView } from "./deals.ts";
10 import { guidance, type Guidance } from "./guidance.ts";
1011 import { owner } from "./week.ts";
1112
1213 export type TimelineStatus = "Done" | "Waived" | "Upcoming" | "Overdue";
@@ -34,12 +35,14 @@ export interface TimelineRow {
3435 readonly doneLine: string;
3536 readonly mark: string;
3637 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[];
3740 }
3841
3942 export function timelineRows(deal: DealView, on: string): TimelineRow[] {
4043 return deal.deadlines.map((d) => {
4144 const u = urgencyOf(d, on);
4245 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") };
4447 });
4548 }
static/app.css +3
@@ -869,6 +869,9 @@ a.week-row {
869869 .timeline-status {
870870 font-weight: 650;
871871 }
872 .timeline-row .timeline-todo {
873 grid-column: 1 / -1;
874 }
872875 .timeline-row[data-u="overdue"] .timeline-status {
873876 color: var(--color-overdue);
874877 }

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs