Public: anyone can read this; the crew can change it.

Every reminder signs off with the agent's name, brokerage, phone and email, and the README says how to make the app carry your own #41

Merged opened this

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

Merged

mason/deal-clock:mason/36-every-reminder-signs-off-with-the-agent → main 2 commits fork 4 threads · 4 unresolved

  • Merged. mason/36-every-reminder-signs-off-with-the-agent was merged into main as 051e5ff.

Review

Sign in to review this change.
14 files changed +169 −11
README.md +17
@@ -99,6 +99,23 @@ Signed out, `/` shows what deal-clock does, three short points, a still picture
9999 samples return as they were, dated from today, and the deals you opened are
100100 left alone. Only an admin sees it. In the terminal press R; over MCP, the `restore_samples` tool.
101101
102 ## Make it yours
103
104 The app ships with a sample agent. To carry your own, set four settings
105 (Settings → App → Environment):
106
107 - `DEAL_CLOCK_AGENT`: your name.
108 - `DEAL_CLOCK_BROKERAGE`: your brokerage.
109 - `DEAL_CLOCK_PHONE`: your number (digits, spaces, `+ ( ) - .`).
110 - `DEAL_CLOCK_EMAIL`: your email address.
111
112 They show in the header (the phone and email are tap-to-call and
113 tap-to-write), on the client timeline you hand to buyers and sellers, and in
114 the terminal. Every new reminder draft ends with your name and brokerage, then
115 your phone and email, so a party can call or write back straight from it.
116 Reminders you already sent keep the words you approved. A phone or email that
117 does not look right is ignored in favour of the sample, with a line in the log.
118
102119 ## What is real, and what is not yet
103120
104121 - **Real:** the dates and their math, mark done, moves with their reasons,
docs/TECHNICAL.md +5 −3
@@ -6,9 +6,11 @@ everything technical, and `AGENTS.md` says how to add to it.
66
77 ## Settings
88
9 The name and brokerage in the header come from two settings
10 (Settings → App → Environment): `DEAL_CLOCK_AGENT` and
11 `DEAL_CLOCK_BROKERAGE`. Dates follow the server's time zone (`TZ`).
9 The agent in the header, the client timeline and every reminder's sign-off
10 comes from four settings (Settings → App → Environment): `DEAL_CLOCK_AGENT`,
11 `DEAL_CLOCK_BROKERAGE`, `DEAL_CLOCK_PHONE` (digits, spaces, `+ ( ) - .`, at
12 most 30 characters) and `DEAL_CLOCK_EMAIL` (one `@`, at most 254). A bad phone
13 or email falls back to the sample with one line in the log. Dates follow the server's time zone (`TZ`).
1214
1315 ## Running it, the API, MCP and the terminal
1416
src/deals.test.ts +1 −1
@@ -35,7 +35,7 @@ const db = openDb(mkdtempSync(join(tmpdir(), "app-deals-")));
3535 const anon: Who = { role: "anon" };
3636 const alice: Who = { role: "user", id: "u1", name: "alice" };
3737 const bob: Who = { role: "user", id: "u2", name: "bob" };
38 const agent = { name: "Dana Whitfield", brokerage: "Harbor & Pine Realty" };
38 const agent = { name: "Dana Whitfield", brokerage: "Harbor & Pine Realty", phone: "(555) 010-0142", email: "[email protected]" };
3939
4040 const open = (over: Record<string, unknown> = {}): DealView => {
4141 const made = createDeal(db, alice, {
src/env.ts +17
@@ -30,8 +30,25 @@ export const publicOrigin: string = new URL(
3030 export const forgeUrl: string | undefined = process.env.FORGE_URL;
3131 /** The key the forge signs identities with (`who.ts`). Unset, everyone is anonymous. */
3232 export const identityKey: string = process.env.FORGE_APP_IDENTITY_KEY ?? "";
33 /** The checks a phone and an email setting pass at boot. */
34 export const PHONE_PATTERN = /^[0-9 +().-]{1,30}$/;

This doc comment belongs on agent below. Move it, and put the validators under their own comment.

35 export const validPhone = (v: string): boolean => PHONE_PATTERN.test(v) && /\d/.test(v);
36 export const validEmail = (v: string): boolean =>
37 v.length <= 254 && /^[A-Za-z0-9._+-]+@[A-Za-z0-9.-]+$/.test(v);
outdated

This regex lets ?, & and # through, so an email can inject mailto parameters such as ?bcc=. Tighten it or percent-encode the href, and add a test.

38
39 /** A setting that fails its check falls back to the sample, with one line in the log. */
40 function setting(name: string, fallback: string, ok: (v: string) => boolean): string {
41 const v = (process.env[name] ?? "").trim();
42 if (v === "") return fallback;
43 if (ok(v)) return v;
44 console.warn(`${name} is not valid; using the sample value`);
45 return fallback;
46 }
47
3348 /** Whose deals these are: the agent and brokerage the header and every reminder name. */
3449 export const agent = {
3550 name: process.env.DEAL_CLOCK_AGENT || "Dana Whitfield",
3651 brokerage: process.env.DEAL_CLOCK_BROKERAGE || "Harbor & Pine Realty",
52 phone: setting("DEAL_CLOCK_PHONE", "(555) 010-0142", validPhone),
53 email: setting("DEAL_CLOCK_EMAIL", "[email protected]", validEmail),
3754 } as const;
src/pages/contact.ts added +7
@@ -0,0 +1,7 @@
1 /** The agent's phone and email as tap-to-call and tap-to-write links, escaped. */
2
3 import type { Agent } from "../reminders.ts";
4 import { escape } from "../http.ts";
5
6 export const contactLinks = (agent: Agent): string =>
7 `<a href="tel:${escape(agent.phone.replace(/[^0-9+]/g, ""))}">${escape(agent.phone)}</a> · <a href="mailto:${escape(agent.email)}">${escape(agent.email)}</a>`;
src/pages/layout.ts +2
@@ -16,6 +16,7 @@ import {
1616 where,
1717 } from "../env.ts";
1818 import { asset, escape } from "../http.ts";
19 import { contactLinks } from "./contact.ts";
1920 import { token, tokensHref } from "../tokens.ts";
2021 import type { Who } from "../who.ts";
2122
@@ -68,6 +69,7 @@ ${plain || input.live === false ? "" : `<script type="module" src="${asset("live
6869 <span class="brand-mark" aria-hidden="true"></span>
6970 <span><b>${escape(agent.name)}</b><small>${escape(agent.brokerage)}</small></span>
7071 </a>
outdated

This tel/mailto markup is duplicated in timeline.ts. Extract one helper. There is also no test that the header shows the contact line.

72 <p class="agent-contact">${contactLinks(agent)}</p>
7173 ${
7274 plain
7375 ? ""
src/pages/timeline.ts +2
@@ -10,6 +10,7 @@ import { agent } from "../env.ts";
1010 import { escape } from "../http.ts";
1111 import { timelineRows } from "../timeline.ts";
1212 import type { Who } from "../who.ts";
13 import { contactLinks } from "./contact.ts";
1314 import { layout } from "./layout.ts";
1415
1516 export function timelinePage(input: { who: Who; deal: DealView; on: string }): string {
@@ -29,6 +30,7 @@ export function timelinePage(input: { who: Who; deal: DealView; on: string }): s
2930 <section class="timeline">
3031 <h1>${escape(deal.address)}</h1>
3132 <p class="summary">Key dates, prepared by ${escape(agent.name)}, ${escape(agent.brokerage)}</p>
33 <p class="summary">${contactLinks(agent)}</p>
3234 <ol class="timeline-list">${rows}</ol>
3335 </section>`;
3436 return layout({ body, who, path, heading: `Timeline · ${deal.address}`, plain: true, bodyClass: "timeline-page" });
src/reminders.ts +8 −2
@@ -14,8 +14,14 @@ import type { DealView, DeadlineView, Moment, Party } from "./deals.ts";
1414 export interface Agent {
1515 readonly name: string;
1616 readonly brokerage: string;
17 readonly phone: string;
18 readonly email: string;
1719 }
1820
21 /** How every draft ends: who to call or write back. */
22 export const signOff = (agent: Agent): string =>
23 `${agent.name}, ${agent.brokerage}\n${agent.phone} · ${agent.email}`;
24
1925 export interface Draft {
2026 readonly deal_id: number;
2127 readonly address: string;
@@ -71,7 +77,7 @@ function words(
7177 if (moment === "late") {
7278 return {
7379 subject: `${deadline.label} — ${deal.address} — overdue`,
74 body: `Hi ${first(party.name)}, the ${deadline.label.toLowerCase()} for ${deal.address} was due ${spoken(deadline.due)} and has passed without being marked done. ${owed}Could you send me an update today on where it stands and when it will be done?\n\n${agent.name}, ${agent.brokerage}`,
80 body: `Hi ${first(party.name)}, the ${deadline.label.toLowerCase()} for ${deal.address} was due ${spoken(deadline.due)} and has passed without being marked done. ${owed}Could you send me an update today on where it stands and when it will be done?\n\n${signOff(agent)}`,
7581 };
7682 }
7783 const when = moment === "before" ? `in three days, on ${spoken(deadline.due)}` : `today, ${spoken(deadline.due)}`;
@@ -81,7 +87,7 @@ function words(
8187 : `${owner === undefined ? PARTY_LABEL[deadline.owes] : owner.name} (${PARTY_LABEL[deadline.owes].toLowerCase()}) is on it; nothing is needed from you unless you hear otherwise.`;
8288 return {
8389 subject: `${deadline.label} — ${deal.address} — ${moment === "before" ? spoken(deadline.due) : "today"}`,
84 body: `Hi ${first(party.name)}, a reminder that the ${deadline.label.toLowerCase()} for ${deal.address} is ${when}. ${owed}${ask}\n\n${agent.name}, ${agent.brokerage}`,
90 body: `Hi ${first(party.name)}, a reminder that the ${deadline.label.toLowerCase()} for ${deal.address} is ${when}. ${owed}${ask}\n\n${signOff(agent)}`,
8591 };
8692 }
8793
src/sample.test.ts +1 −1
@@ -54,7 +54,7 @@ test("the sample deals hold an overdue date with its follow-up waiting", () => {
5454 const alice: Who = { role: "user", id: "u1", name: "alice" };
5555 const listed = listDeals(db, alice);
5656 if (!listed.ok) throw new Error(listed.message);
57 const agent = { name: "Dana", brokerage: "HP" };
57 const agent = { name: "Dana", brokerage: "HP", phone: "555", email: "[email protected]" };
5858 const late = listed.value.flatMap((d) => drafts(d, agent)).filter((r) => r.moment === "late" && unsent(r));
5959 expect(late.length).toBeGreaterThan(0);
6060 });
src/signoff.test.ts added +101
@@ -0,0 +1,101 @@
1 /** The agent's sign-off: on every new draft, never on words already approved. */
2 import { expect, test } from "bun:test";
3 import { mkdtempSync } from "node:fs";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { createDeal, getDeal, sendReminder } from "./deals.ts";
7 import { openDb } from "./db.ts";
8 import { validEmail, validPhone } from "./env.ts";
9 import { draftsFor, signOff } from "./reminders.ts";
10 import { timelinePage } from "./pages/timeline.ts";
11 import { terminal } from "./terminal.ts";
12 import type { Who } from "./who.ts";
13
14 const db = openDb(mkdtempSync(join(tmpdir(), "app-signoff-")));
15 const alice: Who = { role: "user", id: "u1", name: "alice" };
16 const dana = { name: "Dana", brokerage: "HP", phone: "(555) 010-0142", email: "[email protected]" };
17 const lee = { name: "Lee", brokerage: "Bay", phone: "+1 555 0199", email: "[email protected]" };
18
19 const made = createDeal(db, alice, { address: "1 Oak", buyer: "Ann Buyer", seller: "Sam Seller", contractDate: "2026-10-01", closingDate: "2026-11-20" });
20 if (!made.ok) throw new Error(made.message);
21 const view = () => {
22 const got = getDeal(db, alice, { id: made.value.id });
23 if (!got.ok) throw new Error(got.message);
24 return got.value;
25 };
26
27 test("a draft ends with a two-line sign-off", () => {
28 expect(signOff(dana)).toBe("Dana, HP\n(555) 010-0142 · [email protected]");
29 const deal = view();
30 const draft = draftsFor(deal, deal.deadlines[0]!, dana)[0]!;
31 expect(draft.body.endsWith("\n\nDana, HP\n(555) 010-0142 · [email protected]")).toBe(true);
32 });
33
34 test("a sent reminder keeps its approved words; new drafts take the new agent", () => {
35 const deal = view();
36 const deadline = deal.deadlines[0]!;
37 const first = draftsFor(deal, deadline, dana)[0]!;
38 const ask = { deadlineId: deadline.id, partyId: first.party_id, moment: first.moment, agent: dana };
39 expect(sendReminder(db, alice, ask).ok).toBe(true);
40 const after = view();
41 const again = draftsFor(after, deadline, lee).find((d) => d.party_id === first.party_id && d.moment === first.moment)!;
42 expect(again.body).toBe(first.body);
43 const other = draftsFor(after, deadline, lee).find((d) => d.sent_at === null)!;
44 expect(other.body).toContain("[email protected]");
45 expect(other.body).not.toContain("[email protected]");
46 });
47
48 test("the settings are checked at the boundary", () => {
49 expect(validPhone("+1 (555) 010-0142")).toBe(true);
50 expect(validPhone("call me")).toBe(false);
51 expect(validPhone("1".repeat(31))).toBe(false);
52 expect(validEmail("[email protected]")).toBe(true);
53 expect(validEmail("a@@b.co")).toBe(false);
54 expect(validEmail("nobody")).toBe(false);
55 for (const bad of ["[email protected]?bcc=x", "[email protected]&x=1", "[email protected]#f", "[email protected]"]) expect(validEmail(bad)).toBe(false);
56 expect(validEmail(`${"a".repeat(250)}@b.co`)).toBe(false);
57 });
58
59 test("a bad phone or email falls back to the sample and logs, never crashes", async () => {
60 const proc = Bun.spawn(["bun", "-e", 'import { agent } from "./src/env.ts"; console.log(JSON.stringify(agent))'], {
61 env: { ...process.env, DEAL_CLOCK_PHONE: "<script>", DEAL_CLOCK_EMAIL: "x@y@z" },
62 stdout: "pipe",
63 stderr: "pipe",
64 });
65 const [out, err] = await Promise.all([new Response(proc.stdout).text(), new Response(proc.stderr).text()]);
66 expect(await proc.exited).toBe(0);
67 expect(JSON.parse(out).phone).toBe("(555) 010-0142");
68 expect(JSON.parse(out).email).toBe("[email protected]");
69 expect(err.match(/DEAL_CLOCK_/g)?.length).toBe(2);
70 });
71
72 test("the client timeline links the phone and email, escaped", () => {
73 const html = timelinePage({ who: alice, deal: view(), on: "2026-10-25" });
74 expect(html).toContain('href="tel:5550100142"');
75 expect(html).toContain('href="mailto:[email protected]"');
76 });
77
78 test("the header on every page shows the contact line, linked", async () => {
79 const { layout } = await import("./pages/layout.ts");
80 const html = layout({ body: "<p>x</p>", who: alice, path: "/", heading: "x" });
81 expect(html).toContain('class="agent-contact"');
82 expect(html).toContain('href="tel:5550100142"');
83 expect(html).toContain('href="mailto:[email protected]"');
84 });
85
86 test("contactLinks escapes what it is given", async () => {
87 const { contactLinks } = await import("./pages/contact.ts");
88 const html = contactLinks({ ...dana, phone: '1"><b>', email: "[email protected]" });
89 expect(html).not.toContain("<b>");
90 });
91
92 test("the terminal header and its client timeline print the phone and email", () => {
93 const t = terminal(db, alice, { title: "deal-clock", where: "test", agent: dana, on: () => "2026-10-25" });
94 const strip = (s: string): string => s.replace(/\x1b\[[0-9;]*m/g, "");
95 expect(strip(t.screen().join("\n"))).toContain("(555) 010-0142 · [email protected]");
96 t.press("o");
97 t.press("t");
98 const screen = strip(t.screen().join("\n"));
99 expect(screen).toContain("Client timeline");
100 expect(screen).toContain("(555) 010-0142 · [email protected]");
101 });
src/terminal.test.ts +1 −1
@@ -14,7 +14,7 @@ import type { Who } from "./who.ts";
1414
1515 const db = openDb(mkdtempSync(join(tmpdir(), "app-terminal-")));
1616 const alice: Who = { role: "user", id: "u1", name: "alice" };
17 const context = { title: "deal-clock", where: "test", agent: { name: "Dana", brokerage: "HP" } };
17 const context = { title: "deal-clock", where: "test", agent: { name: "Dana", brokerage: "HP", phone: "555", email: "[email protected]" } };
1818 const plain = (s: string): string => s.replace(/\x1b\[[0-9;]*m/g, "");
1919 const lines = (t: Terminal): string[] => t.screen().map(plain);
2020 const under = (t: Terminal): string => lines(t).find((l) => l.startsWith("▸")) ?? "";
src/terminal.ts +2 −2
@@ -420,7 +420,7 @@ export function terminal(
420420 const day = on();
421421 const all = deals();
422422 const lines = [
423 `${bold(context.title)} ${context.agent.name}, ${context.agent.brokerage} ${dim(context.where)} ${dim(me.role === "anon" ? "guest" : `${me.name}${me.role === "admin" ? " (admin)" : ""}`)}`,
423 `${bold(context.title)} ${context.agent.name}, ${context.agent.brokerage} ${dim(`${context.agent.phone} · ${context.agent.email}`)} ${dim(context.where)} ${dim(me.role === "anon" ? "guest" : `${me.name}${me.role === "admin" ? " (admin)" : ""}`)}`,

The header line and the client timeline line printed here have no test. Add terminal tests that assert the phone and email on both screens.

424424 context.ssh === undefined ? dim("The terminal is off.") : dim(`connect: ${context.ssh}`),
425425 `${spoken(day)} · ${all.length} deals · ${view === "dates" ? bold("[d] dates") : "[d] dates"} · ${view === "week" ? bold("[w] this week") : "[w] this week"} · ${view === "reminders" ? bold("[r] reminders today") : "[r] reminders today"}`,
426426 "",
@@ -468,7 +468,7 @@ export function terminal(
468468 const deal = openDeal();
469469 if (deal === undefined) lines.push(dim("That deal is gone."));
470470 else {
471 lines.push(bold(`Client timeline — ${deal.address}`), dim(`${context.agent.name}, ${context.agent.brokerage}`), "");
471 lines.push(bold(`Client timeline — ${deal.address}`), dim(`${context.agent.name}, ${context.agent.brokerage}`), dim(`${context.agent.phone} · ${context.agent.email}`), "");
472472 timelineRows(deal, day).forEach((r) =>
473473 lines.push(` ${tint(r.urgency, `${r.spoken.padEnd(16)} ${r.status.padEnd(9)}`)} ${r.label} · ${r.name === undefined ? r.role : `${r.role}: ${r.name}`}`),
474474 );
src/timeline.test.ts +1 −1
@@ -64,7 +64,7 @@ test("the print rules are scoped to the timeline page", async () => {
6464 });
6565
6666 test("the terminal shows the same dates and owners for the open deal, ", () => {
67 const t = terminal(db, alice, { title: "deal-clock", where: "test", agent: { name: "Dana", brokerage: "HP" }, on: () => "2026-10-25" });
67 const t = terminal(db, alice, { title: "deal-clock", where: "test", agent: { name: "Dana", brokerage: "HP", phone: "555", email: "[email protected]" }, on: () => "2026-10-25" });
6868 const row = (): string => t.screen().join("\n").split("\n").find((l) => l.startsWith("▸")) ?? "";
6969 for (let i = 0; i < 300 && !row().includes("HOA review ends"); i++) t.press("j");
7070 t.press("o");
static/app.css +4
@@ -27,6 +27,10 @@ body {
2727 gap: var(--space-3) var(--space-4);
2828 margin-bottom: var(--space-5);
2929 }
30 .agent-contact {
31 margin: 0;
32 font-size: var(--text-sm, 0.875rem);
33 }
3034 h1,
3135 h2 {
3236 margin: 0;

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs