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

An addendum moves several of a deal's dates at once with one reason, and each party gets one "dates changed" notice listing every change #71

Merged opened this

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

Merged

mason/deal-clock:mason/66-an-addendum-moves-several-of-a-deal-s-da → main 2 commits fork

  • Merged. mason/66-an-addendum-moves-several-of-a-deal-s-da was merged into main as 809a6c0.

Review

Sign in to review this change.
15 files changed +551 −43
README.md +3 −1
@@ -85,7 +85,9 @@ Signed out, `/` shows what deal-clock does, three short points, a still picture
8585 decline it. Move the date again and an unsent notice is replaced. If you move a date to or past the closing date, the move
8686 still happens, but the notice says so, the date's marker on the clock
8787 carries a ! and the sheet and the deal page say which dates now fall
88 after closing.
88 after closing. For an addendum that moves several dates, use *Amend the
89 contract* on the deal page instead: one reason, and each party gets one
90 notice listing every change.
8991 6. **See a date that was moved.** On 9 Orchard Row, open the appraisal
9092 marker. The sheet shows where it moved from and to, with the reason
9193 the appraiser gave.
contract/openapi.json +72
@@ -766,6 +766,78 @@
766766 }
767767 }
768768 },
769 "/api/deals/{id}/amend": {
770 "post": {
771 "summary": "Amend the contract: move several open dates at once with one reason (1 to 200 characters). Every date is checked first and none moves if one is wrong (422); a date given its current due is left alone, and nothing changed is refused. Each party is drafted one notice listing every change.",
772 "operationId": "postApiDealsIdAmend",
773 "parameters": [
774 {
775 "name": "id",
776 "in": "path",
777 "required": true,
778 "schema": {
779 "type": "integer"
780 }
781 }
782 ],
783 "requestBody": {
784 "required": true,
785 "content": {
786 "application/json": {
787 "schema": {
788 "type": "object",
789 "properties": {
790 "dates": {
791 "type": "object",
792 "description": "Open date id to its new due date (YYYY-MM-DD).",
793 "additionalProperties": {
794 "type": "string",
795 "format": "date"
796 }
797 },
798 "reason": {
799 "type": "string",
800 "minLength": 1,
801 "maxLength": 200
802 }
803 },
804 "required": [
805 "dates",
806 "reason"
807 ]
808 }
809 }
810 }
811 },
812 "responses": {
813 "200": {
814 "description": "Amend the contract: move several open dates at once with one reason (1 to 200 characters). Every date is checked first and none moves if one is wrong (422); a date given its current due is left alone, and nothing changed is refused. Each party is drafted one notice listing every change.",
815 "content": {
816 "application/json": {
817 "schema": {
818 "$ref": "#/components/schemas/Deal"
819 }
820 }
821 }
822 },
823 "default": {
824 "description": "{ error, message }: why not",
825 "content": {
826 "application/json": {
827 "schema": {
828 "$ref": "#/components/schemas/Error"
829 }
830 }
831 }
832 }
833 },
834 "x-contract": {
835 "resource": "deal",
836 "verb": "update",
837 "least": "user"
838 }
839 }
840 },
769841 "/api/deals/{id}/deadlines/{deadline}": {
770842 "delete": {
771843 "summary": "Remove a custom date the contract dropped, and its unsent reminders. A standard contract date is refused (422): move it or mark it done.",
docs/TECHNICAL.md +1 −1
@@ -77,7 +77,7 @@ tools at `POST /mcp` (`list_deals`, `get_deal`, `client_timeline`, `reminders_to
7777 `open_deal`, `add_date`, `update_address`, `add_party`, `edit_party`, `remove_party`,
7878 `remove_date` — custom dates only — `remove_deal` — its author or an admin —
7979 `mark_done` — with `done: false` to
80 reopen a date — `move_date`, `send_reminder`, `restore_samples` — admin only: puts the
80 reopen a date — `move_date`, `amend_deal` (several dates, one reason), `send_reminder`, `restore_samples` — admin only: puts the
8181 four sample deals back and leaves every other deal alone). `send_reminder` takes an
8282 optional `subject` and `body` to send edited words; without them the draft
8383 goes as it is.
src/amend.test.ts added +196
@@ -0,0 +1,196 @@
1 /**
2 * Amending the contract: several dates move at once with one reason, and
3 * each party is drafted one notice for the whole addendum — through the
4 * action, then the page, the API and MCP.
5 */
6 import { afterAll, beforeEach, expect, test } from "bun:test";
7 import { mkdtempSync } from "node:fs";
8 import { tmpdir } from "node:os";
9 import { join } from "node:path";
10 import { openDb } from "./db.ts";
11 import { amendDeal, createDeal, declineReminder, getDeal, moveDeadline, sendReminder, undoDecline, type DealView } from "./deals.ts";
12 import { drafts } from "./reminders.ts";
13 import { serve } from "./server.ts";
14 import { forgetRationing } from "./security.ts";
15 import { sign, type Who } from "./who.ts";
16
17 const db = openDb(mkdtempSync(join(tmpdir(), "app-amend-")));
18 const alice: Who = { role: "user", id: "u1", name: "alice" };
19 const agent = { name: "Dana", brokerage: "Harbor", phone: "555", email: "[email protected]" };
20
21 const open = (): DealView => {
22 const made = createDeal(db, alice, { address: "4 Addendum Way", buyer: "Ann Buyer", seller: "Sam Seller", contractDate: "2026-10-01", closingDate: "2026-12-01" });
23 if (!made.ok) throw new Error(made.message);
24 return made.value;
25 };
26 const fresh = (id: number): DealView => {
27 const got = getDeal(db, alice, { id });
28 if (!got.ok) throw new Error(got.message);
29 return got.value;
30 };
31 const kind = (deal: DealView, k: string) => deal.deadlines.find((d) => d.kind === k)!;
32 const notices = (deal: DealView) => drafts(deal, agent).filter((d) => d.moment === "moved");
33
34 test("an amendment moving two dates writes two moves and one notice per party naming both", () => {
35 const deal = open();
36 const inspection = kind(deal, "inspection");
37 const financing = kind(deal, "financing");
38 const done = amendDeal(db, alice, {
39 dealId: deal.id,
40 dates: { [inspection.id]: "2026-10-20", [financing.id]: "2026-11-20" },
41 reason: "Addendum 1",
42 });
43 expect(done.ok).toBe(true);
44 const after = fresh(deal.id);
45 expect(kind(after, "inspection").moves).toHaveLength(1);
46 expect(kind(after, "financing").moves[0]).toMatchObject({ reason: "Addendum 1", by_name: "alice", to_due: "2026-11-20" });
47 const sheet = notices(after);
48 const byParty = Map.groupBy(sheet, (d) => d.party_id);
49 for (const [, mine] of byParty) expect(mine).toHaveLength(1);
50 // The buyer owes both, so is told of both, in one message.
51 const buyer = sheet.find((d) => d.party_role === "buyer")!;
52 expect(buyer.body).toContain(inspection.label);
53 expect(buyer.body).toContain(financing.label);
54 expect(buyer.body).toContain("Oct 20");
55 });
56
57 test("a single move keeps its own notice, one per date", () => {
58 const deal = open();
59 moveDeadline(db, alice, { id: kind(deal, "inspection").id, due: "2026-10-20", reason: "x" });
60 moveDeadline(db, alice, { id: kind(deal, "financing").id, due: "2026-11-20", reason: "y" });
61 const buyer = notices(fresh(deal.id)).filter((d) => d.party_role === "buyer");
62 expect(buyer).toHaveLength(2);
63 });
64
65 test("one bad date refuses the whole amendment and nothing moves", () => {
66 const deal = open();
67 const before = fresh(deal.id);
68 for (const dates of [
69 { [kind(deal, "inspection").id]: "2026-10-20", [kind(deal, "financing").id]: "soon" },
70 { [kind(deal, "inspection").id]: "2026-10-20", 99999: "2026-10-21" },
71 ]) {
72 const refused = amendDeal(db, alice, { dealId: deal.id, dates, reason: "Addendum" });
73 expect(refused.ok).toBe(false);
74 }
75 expect(amendDeal(db, alice, { dealId: deal.id, dates: { [kind(deal, "inspection").id]: "2026-10-20" }, reason: " " }).ok).toBe(false);
76 expect(amendDeal(db, alice, { dealId: deal.id, dates: { [kind(deal, "inspection").id]: "2026-10-20" }, reason: "x".repeat(201) }).ok).toBe(false);
77 expect(fresh(deal.id).deadlines.map((d) => [d.due, d.moves.length])).toEqual(before.deadlines.map((d) => [d.due, d.moves.length]));
78 });
79
80 test("an unchanged form is refused", () => {
81 const deal = open();
82 const same = Object.fromEntries(deal.deadlines.map((d) => [d.id, d.due]));
83 const refused = amendDeal(db, alice, { dealId: deal.id, dates: same, reason: "Addendum" });
84 expect(refused.ok).toBe(false);
85 if (!refused.ok) expect(refused.message).toContain("Nothing changed");
86 });
87
88 test("a stranger may not amend; the table decides, as it does for a move", () => {
89 const deal = open();
90 const refused = amendDeal(db, { role: "anon" }, { dealId: deal.id, dates: { [kind(deal, "inspection").id]: "2026-10-20" }, reason: "x" });
91 expect(refused.ok).toBe(false);
92 expect(kind(fresh(deal.id), "inspection").moves).toHaveLength(0);
93 });
94
95 test("an amendment notice is sent, declined and undone as one, and stays sent when a date moves again", () => {
96 const deal = open();
97 const inspection = kind(deal, "inspection");
98 const financing = kind(deal, "financing");
99 amendDeal(db, alice, { dealId: deal.id, dates: { [inspection.id]: "2026-10-20", [financing.id]: "2026-11-20" }, reason: "Addendum 1" });
100 const buyer = () => notices(fresh(deal.id)).find((d) => d.party_role === "buyer")!;
101 const first = buyer();
102 expect(declineReminder(db, alice, { deadlineId: first.deadline_id, partyId: first.party_id, moment: "moved", reason: "told by phone", agent }).ok).toBe(true);
103 expect(buyer().declined).not.toBeNull();
104 expect(undoDecline(db, alice, { deadlineId: first.deadline_id, partyId: first.party_id, moment: "moved", agent }).ok).toBe(true);
105 expect(buyer().declined).toBeNull();
106 expect(sendReminder(db, alice, { deadlineId: first.deadline_id, partyId: first.party_id, moment: "moved", agent }).ok).toBe(true);
107 expect(buyer().sent_at).not.toBeNull();
108 // The first date of the notice moves again: the others are not re-drafted for a party already told.
109 const anchor = first.deadline_id;
110 moveDeadline(db, alice, { id: anchor, due: "2026-10-25", reason: "again" });
111 const buyerNotices = notices(fresh(deal.id)).filter((d) => d.party_role === "buyer");
112 const amended = buyerNotices.filter((d) => d.subject.includes("dates changed") || d.deadline_id !== anchor);
113 for (const d of amended) expect(d.sent_at).not.toBeNull();
114 });
115
116 test("an amendment leaving a date on or after closing shows the closing-order flag", () => {
117 const deal = open();
118 amendDeal(db, alice, { dealId: deal.id, dates: { [kind(deal, "financing").id]: "2026-12-05", [kind(deal, "inspection").id]: "2026-10-20" }, reason: "Addendum" });
119 expect(fresh(deal.id).conflicts.length).toBeGreaterThan(0);
120 });
121
122 // ---- the doors ----
123
124 const KEY = "a-key-only-the-forge-holds";
125 const server = serve({ port: 0, dataDir: mkdtempSync(join(tmpdir(), "app-amend-srv-")), identityKey: KEY });
126 const base = `http://${server.hostname}:${server.port}`;
127 afterAll(() => server.stop(true));
128 beforeEach(forgetRationing);
129 const as = (id: string, name: string): Record<string, string> => {
130 const identity = `${id}|${name}|user|${Date.now() + 60_000}`;
131 return { "x-forge-identity": identity, "x-forge-signature": sign(identity, KEY) };
132 };
133 const me = as("u7", "mia");
134 const get = (path: string) => fetch(base + path, { headers: me });
135 const postJson = (path: string, body: unknown) =>
136 fetch(base + path, { method: "POST", headers: { ...me, "content-type": "application/json" }, body: JSON.stringify(body) });
137
138 const served = async (): Promise<DealView> => {
139 const made = await postJson("/api/deals", { address: "9 Door Lane", buyer: "A", seller: "B", contract_date: "2026-10-01", closing_date: "2026-12-01" });
140 return (await made.json()) as DealView;
141 };
142
143 test("the deal page offers the form, and the form amends without JavaScript", async () => {
144 const deal = await served();
145 const page = await (await get(`/deals/${deal.id}`)).text();
146 expect(page).toContain("Amend the contract");
147 for (const d of deal.deadlines) expect(page).toContain(`name="due_${d.id}" required value="${d.due}"`);
148 const body = new FormData();
149 for (const d of deal.deadlines) body.set(`due_${d.id}`, d.kind === "inspection" ? "2026-10-20" : d.due);
150 body.set("reason", "Addendum 1");
151 const ok = await fetch(`${base}/deals/${deal.id}/amend`, { method: "POST", body, headers: me, redirect: "manual" });
152 expect(ok.status).toBe(303);
153 const after = (await (await get(`/api/deals/${deal.id}`)).json()) as DealView;
154 expect(after.deadlines.find((d) => d.kind === "inspection")!.due).toBe("2026-10-20");
155 });
156
157 test("a refused form keeps what was typed and names the field", async () => {
158 const deal = await served();
159 const body = new FormData();
160 for (const d of deal.deadlines) body.set(`due_${d.id}`, d.kind === "inspection" ? "2026-10-20" : d.due);
161 body.set("reason", "");
162 const refused = await fetch(`${base}/deals/${deal.id}/amend`, { method: "POST", body, headers: me });
163 expect(refused.status).toBe(422);
164 const page = await refused.text();
165 expect(page).toContain('value="2026-10-20"');
166 expect(page).toContain('aria-invalid="true"');
167 expect(page).toContain("Say why the dates moved");
168 const same = new FormData();
169 for (const d of deal.deadlines) same.set(`due_${d.id}`, d.due);
170 same.set("reason", "x");
171 const nothing = await fetch(`${base}/deals/${deal.id}/amend`, { method: "POST", body: same, headers: me });
172 expect(nothing.status).toBe(422);
173 expect(await nothing.text()).toContain("Nothing changed");
174 });
175
176 test("the API and MCP apply the same rules as the page", async () => {
177 const deal = await served();
178 const inspection = deal.deadlines.find((d) => d.kind === "inspection")!;
179 const bad = await postJson(`/api/deals/${deal.id}/amend`, { dates: { [inspection.id]: "nope" }, reason: "x" });
180 expect(bad.status).toBe(422);
181 const same = await postJson(`/api/deals/${deal.id}/amend`, { dates: { [inspection.id]: inspection.due }, reason: "x" });
182 expect(same.status).toBe(422);
183 const good = await postJson(`/api/deals/${deal.id}/amend`, { dates: { [inspection.id]: "2026-10-20" }, reason: "Addendum 1" });
184 expect(good.status).toBe(200);
185 const guest = await fetch(`${base}/api/deals/${deal.id}/amend`, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ dates: {}, reason: "x" }) });
186 expect([401, 403]).toContain(guest.status);
187
188 const financing = deal.deadlines.find((d) => d.kind === "financing")!;
189 const call = async (args: unknown) =>
190 (await (await postJson("/mcp", { jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: "amend_deal", arguments: args } })).json()) as any;
191 expect((await call({ deal: deal.id, dates: { [financing.id]: "bad" }, reason: "x" })).result.isError).toBe(true);
192 const through = await call({ deal: deal.id, dates: { [financing.id]: "2026-11-20" }, reason: "Addendum 2" });
193 expect(through.result.isError).not.toBe(true);
194 const after = (await (await get(`/api/deals/${deal.id}`)).json()) as DealView;
195 expect(after.deadlines.find((d) => d.id === financing.id)!.due).toBe("2026-11-20");
196 });
src/db.ts +4
@@ -306,6 +306,10 @@ export const migrations: string[] = [
306306 DROP TABLE reminder_declined;
307307 ALTER TABLE reminder_declined_new RENAME TO reminder_declined;
308308 CREATE INDEX reminder_declined_deal ON reminder_declined (deal_id)`,
309 // Which amendment a move belongs to: the moves one addendum made share a
310 // number, so the parties get one "dates changed" notice for them; 0 is a
311 // move made on its own.
312 `ALTER TABLE deadline_move ADD COLUMN amendment INTEGER NOT NULL DEFAULT 0`,
309313 ];
310314
311315 export function openDb(dir = dataDir): Database {
src/deals.ts +66 −6
@@ -23,7 +23,7 @@ import { agent as defaultAgent, LENGTH_MAX, standard } from "./env.ts";
2323 import { emit } from "./live.ts";
2424 import { outbox } from "./outbox.ts";
2525 import { conflictLine, conflicts, type Conflict } from "./order.ts";
26 import { draftsFor, moveKey, type Agent, type Draft } from "./reminders.ts";
26 import { draftsFor, type Agent, type Draft } from "./reminders.ts";
2727 import { audited, fail, ok, refuse, type Result } from "./result.ts";
2828 import type { Who } from "./who.ts";
2929
@@ -69,6 +69,8 @@ export interface Move {
6969 readonly at: string;
7070 /** 1 when the move owes the parties a "date changed" notice; 0 for a move made before notices existed. */
7171 readonly notify: 0 | 1;
72 /** The addendum that made this move together with others; 0 for a move made on its own. */
73 readonly amendment: number;
7274 }
7375 export interface Sent {
7476 readonly id: number;
@@ -618,6 +620,64 @@ export function moveDeadline(
618620 return within(db, who, dealId, ok(reread(db, deadline.id)));
619621 }
620622
623 /** One amendment, checked: the moves it makes, or the field that was wrong and why. */
624 export type Amendment =
625 | { readonly ok: true; readonly moves: readonly { readonly deadline: Deadline; readonly to: string }[]; readonly reason: string }
626 | { readonly ok: false; readonly field: string; readonly message: string };
627
628 /**
629 * What an addendum would do to `deal`: `dates` maps an open date's id to the
630 * date it now has; a date given its current due is left alone. Every date is
631 * checked before any is moved, so one bad date refuses the whole amendment.
632 * `field` names what to blame: `due_<id>` or `reason`.
633 */
634 export function amendment(deal: DealView, dates: unknown, reasonText: unknown): Amendment {
635 const reason = line(reasonText, 1, REASON_MAX);
636 if (typeof dates !== "object" || dates === null || Array.isArray(dates))
637 return { ok: false, field: "dates", message: "Give the dates as { date id: new date }." };
638 const moves: { deadline: Deadline; to: string }[] = [];
639 for (const [key, to] of Object.entries(dates)) {
640 const deadline = deal.deadlines.find((d) => String(d.id) === key && d.done_at === null);
641 if (deadline === undefined)
642 return { ok: false, field: `due_${key}`, message: `Date ${key} is not an open date of this deal.` };
643 if (!isDate(to))
644 return { ok: false, field: `due_${key}`, message: `${deadline.label}: the new date is a date (YYYY-MM-DD).` };
645 if (to !== deadline.due) moves.push({ deadline, to });
646 }
647 if (reason === undefined)
648 return { ok: false, field: "reason", message: `Say why the dates moved (up to ${REASON_MAX} characters).` };
649 if (moves.length === 0) return { ok: false, field: "", message: "Nothing changed: move at least one date." };
650 return { ok: true, moves, reason };
651 }
652
653 /**
654 * Amend the contract: move several of a deal's dates at once, with one reason.
655 * All or none; each move shows in its date's history, and the parties are
656 * drafted one "dates changed" notice for them together.
657 */
658 export function amendDeal(
659 db: Database,
660 who: Who,
661 input: { dealId: number; dates: unknown; reason: unknown },
662 ): Result<DealView> {
663 const found = dealFor(db, who, "update", input.dealId);
664 if (!found.ok) return within(db, who, undefined, found);
665 const seen = view(db, found.value);
666 const plan = amendment(seen, input.dates, input.reason);
667 if (!plan.ok) return within(db, who, found.value.id, fail("invalid", plan.message));
668 const name = authorOf(who).name;
669 db.transaction(() => {
670 const number = db.query<{ n: number }, []>("SELECT coalesce(max(amendment), 0) + 1 AS n FROM deadline_move").get()!.n;
671 for (const { deadline, to } of plan.moves) {
672 db.query("UPDATE deadline SET due = ?1 WHERE id = ?2").run(to, deadline.id);
673 db.query(
674 "INSERT INTO deadline_move (deadline_id, from_due, to_due, reason, by_name, notify, amendment) VALUES (?1, ?2, ?3, ?4, ?5, 1, ?6)",
675 ).run(deadline.id, deadline.due, to, plan.reason, name, number);
676 }
677 })();
678 return within(db, who, found.value.id, ok(view(db, found.value)));
679 }
680
621681 export function addDeadline(
622682 db: Database,
623683 who: Who,
@@ -809,7 +869,7 @@ export function sendReminder(
809869 `INSERT INTO reminder (deal_id, deadline_id, party_id, label, party_name, party_role, moment, due, move_id, by_name, subject, body) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)
810870 ON CONFLICT (deadline_id, party_id, moment, due, move_id) DO UPDATE SET sent_at = sent_at RETURNING *`,
811871 )
812 .get(found.value.deal.id, deadline.id, party.id, deadline.label, party.name, party.role, input.moment, deadline.due, moveKey(seen.deadlines.find((d) => d.id === deadline.id)!, input.moment), authorOf(who).name, subject, body)!;
872 .get(found.value.deal.id, deadline.id, party.id, draft?.label ?? deadline.label, party.name, party.role, input.moment, draft?.due ?? deadline.due, draft?.move_id ?? 0, authorOf(who).name, subject, body)!;
813873 return within(db, who, dealId, ok(withHref(sent, [party])));
814874 }
815875
@@ -853,7 +913,7 @@ export function declineReminder(
853913 const reason = line(input.reason, 1, REASON_MAX);
854914 if (reason === undefined)
855915 return within(db, who, dealId, fail("invalid", `Say why in 1 to ${REASON_MAX} characters.`));
856 const { draft, deal, deadline } = found.value;
916 const { draft, deal } = found.value;
857917 if (draft.sent_at !== null)
858918 return within(db, who, dealId, fail("invalid", "This reminder was already sent."));
859919 const declined = db
@@ -861,7 +921,7 @@ export function declineReminder(
861921 `INSERT INTO reminder_declined (deal_id, deadline_id, party_id, label, party_name, moment, due, move_id, reason, by_name) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)
862922 ON CONFLICT (deadline_id, party_id, moment, due, move_id) DO UPDATE SET reason = excluded.reason, by_name = excluded.by_name, at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') RETURNING *`,
863923 )
864 .get(deal.id, draft.deadline_id, draft.party_id, draft.label, draft.party_name, draft.moment, draft.due, moveKey(deadline, draft.moment), reason, authorOf(who).name)!;
924 .get(deal.id, draft.deadline_id, draft.party_id, draft.label, draft.party_name, draft.moment, draft.due, draft.move_id, reason, authorOf(who).name)!;
865925 return within(db, who, dealId, ok(declined));
866926 }
867927
@@ -873,12 +933,12 @@ export function undoDecline(
873933 ): Result<{ id: number }> {
874934 const { dealId, found } = draftOf(db, who, input);
875935 if (!found.ok) return within(db, who, dealId, found);
876 const { draft, deadline } = found.value;
936 const { draft } = found.value;
877937 const gone = db
878938 .query<{ id: number }, [number, number, string, string, number]>(
879939 "DELETE FROM reminder_declined WHERE deadline_id = ?1 AND party_id = ?2 AND moment = ?3 AND due = ?4 AND move_id = ?5 RETURNING id",
880940 )
881 .get(draft.deadline_id, draft.party_id, draft.moment, draft.due, moveKey(deadline, draft.moment));
941 .get(draft.deadline_id, draft.party_id, draft.moment, draft.due, draft.move_id);
882942 if (gone === null)
883943 return within(db, who, dealId, fail("invalid", "This reminder was not declined."));
884944 return within(db, who, dealId, ok({ id: gone.id }));
src/mcp.ts +19
@@ -22,6 +22,7 @@ import {
2222 getDeal,
2323 listDeals,
2424 markDone,
25 amendDeal,
2526 moveDeadline,
2627 removeDeadline,
2728 removeParty,
@@ -142,6 +143,24 @@ export const tools: readonly Tool[] = [
142143 return moved.ok ? ok({ ...moved.value, conflicts: conflictsOf(db, who, moved.value.deal_id) }) : moved;
143144 },
144145 },
146 {
147 name: "amend_deal",
148 description:
149 "Amend the contract: move several open dates of a deal at once, with one reason. dates maps a date's id to its new due date (YYYY-MM-DD). Every date is checked first and none moves if one is wrong; a date given its current due is left alone, and nothing changed is refused. Each party is drafted one \"dates changed\" notice listing every change. The answer is the deal with its conflicts.",
150 inputSchema: {
151 type: "object",
152 properties: {
153 deal: { type: "integer" },
154 dates: { type: "object", additionalProperties: { type: "string", format: "date" } },
155 reason: { type: "string", maxLength: 200 },
156 },
157 required: ["deal", "dates", "reason"],
158 },
159 run: (db, who, args) => {
160 const amended = amendDeal(db, who, { dealId: Number(args.deal), dates: args.dates, reason: args.reason });
161 return amended.ok ? ok({ ...amended.value, conflicts: conflictsOf(db, who, amended.value.id) }) : amended;
162 },
163 },
145164 {
146165 name: "send_reminder",
147166 description:
src/pages/amend.ts added +43
@@ -0,0 +1,43 @@
1 /**
2 * The deal page's "Amend the contract" form: one date input for each open
3 * date, filled with its due date, and the one reason the addendum gives.
4 * It posts to `/deals/:id/amend` and works without JavaScript; a refused
5 * form comes back with what was typed and the field that was wrong.
6 */
7
8 import type { DealView } from "../deals.ts";
9 import { escape } from "../http.ts";
10
11 /** What the form was last sent with, and what was wrong with it. */
12 export interface AmendState {
13 readonly values: Readonly<Record<string, string>>;
14 /** `field` is `due_<id>`, `reason`, or empty when the whole form is at fault. */
15 readonly problem: { readonly field: string; readonly message: string };
16 }
17
18 export function amendForm(deal: DealView, path: string, state?: AmendState): string {
19 const open = deal.deadlines.filter((d) => d.done_at === null);
20 if (open.length === 0) return "";
21 const { values = {}, problem } = state ?? {};
22 const bad = (field: string): string =>
23 problem?.field === field ? ` aria-invalid="true" aria-describedby="amend-why"` : "";
24 const why = (field: string): string =>
25 problem?.field === field ? `<span class="field-error" id="amend-why" role="alert">${escape(problem.message)}</span>` : "";
26 const general = problem !== undefined && problem.field === "" ? `<p class="field-error" role="alert">${escape(problem.message)}</p>` : "";
27 const rows = open
28 .map(
29 (d) =>
30 `<label>${escape(d.label)}<input class="input" type="date" name="due_${d.id}" required value="${escape(values[`due_${d.id}`] ?? d.due)}"${bad(`due_${d.id}`)}>${why(`due_${d.id}`)}</label>`,
31 )
32 .join("");
33 return `<section class="card" id="amend">
34 <h2>Amend the contract</h2>
35 <p class="muted small">An addendum that moves several dates: change them here, give the one reason, and each party gets one notice listing every change.</p>
36 <form class="stack" method="post" action="${path}/amend">
37 ${general}
38 ${rows}
39 <label>Why<input class="input" name="reason" required maxlength="200" placeholder="Addendum 1: financing and closing pushed 7 days" value="${escape(values.reason ?? "")}"${bad("reason")}>${why("reason")}</label>
40 <button class="button">Save the amendment</button>
41 </form>
42 </section>`;
43 }
src/pages/deal.ts +4 −1
@@ -11,6 +11,7 @@ import { DEFAULT_LENGTHS, PARTY_LABEL, PARTY_ROLES } from "../deadlines.ts";
1111 import { escape } from "../http.ts";
1212 import { MOMENT_LABEL } from "../reminders.ts";
1313 import type { Who } from "../who.ts";
14 import { amendForm, type AmendState } from "./amend.ts";
1415 import { confirmRemove } from "./confirm.ts";
1516 import { layout } from "./layout.ts";
1617 import { badge, conflictLines, dueLine, outboxLine, owedBy, sheet, sheetId } from "./sheet.ts";
@@ -68,6 +69,8 @@ export function dealPage(input: {
6869 open?: number | undefined;
6970 /** An address that was refused: what was typed and why, to show beside the field. */
7071 problem?: { readonly value: string; readonly message: string } | undefined;
72 /** An amendment that was refused: what was typed and what was wrong. */
73 amend?: AmendState | undefined;
7174 }): string {
7275 const { who, deal, on, notice, problem } = input;
7376 const opened = input.open === undefined ? undefined : deal.sent.find((m) => m.id === input.open);
@@ -104,7 +107,7 @@ export function dealPage(input: {
104107 )
105108 .join("")}</ul>`;
106109 const forms = may
107 ? `<section class="card">
110 ? `${amendForm(deal, path, input.amend)}<section class="card">
108111 <h2>Add a date</h2>
109112 <p class="muted small">A date the contract adds: an HOA review, a repair deadline, a rate lock.</p>
110113 <form class="stack" method="post" action="${path}/deadlines">
src/reminders.ts +64 −29
@@ -34,6 +34,8 @@ export interface Draft {
3434 readonly party_role: PartyRole;
3535 readonly contact: string;
3636 readonly moment: Moment;
37 /** The move a "date changed" notice is about (for an amendment, its first); 0 for every other moment. */
38 readonly move_id: number;
3739 /** The morning it goes out. */
3840 readonly on: string;
3941 readonly subject: string;
@@ -61,14 +63,6 @@ const lastMove = (deadline: DeadlineView): Move | undefined => {
6163 return move !== undefined && move.notify === 1 ? move : undefined;
6264 };
6365
64 /**
65 * Which move a sent or declined row is about: the id of the latest move for a
66 * "date changed" notice, 0 for every other moment. A date that moves back and
67 * forth is told of each move afresh.
68 */
69 export const moveKey = (deadline: DeadlineView, moment: Moment): number =>
70 moment === "moved" ? (lastMove(deadline)?.id ?? 0) : 0;
71
7266 /**
7367 * The parties a moment tells: whoever owes the date, then whoever its kind
7468 * notifies; an overdue follow-up goes to whoever owes it alone.
@@ -82,15 +76,60 @@ export function recipients(deal: DealView, deadline: DeadlineView, moment: Momen
8276
8377 const first = (name: string): string => name.split(" ")[0] ?? name;
8478
79 /** What a "date changed" notice tells one party: the dates it lists, the date it hangs on, and its key. */
80 interface Notice {
81 /** Each date told, with the move that changed it, in the order they moved. */
82 readonly items: readonly { readonly deadline: DeadlineView; readonly move: Move }[];
83 /** The id of the first move told: what a sent or declined notice is remembered by. */
84 readonly key: number;
85 }
86
87 /**
88 * The notice `party` is owed for `deadline`'s latest move, if this date is the
89 * one it hangs on. A move made alone is its own notice. The moves of one
90 * amendment are a single notice per party, hung on the first of the dates
91 * still at that amendment's move that the party is told about, and keyed by
92 * the first move they were ever told of, so a notice already sent or declined
93 * stays so when one of its dates later moves again.
94 */
95 function noticeFor(deal: DealView, deadline: DeadlineView, party: Party): Notice | undefined {
96 const last = lastMove(deadline);
97 if (last === undefined) return undefined;
98 if (last.amendment === 0) return { items: [{ deadline, move: last }], key: last.id };
99 const told = (d: DeadlineView): boolean => recipients(deal, d, "moved").some((p) => p.id === party.id);
100 const items = deal.deadlines
101 .filter((d) => d.done_at === null && told(d))
102 .flatMap((d) => {
103 const move = lastMove(d);
104 return move !== undefined && move.amendment === last.amendment ? [{ deadline: d, move }] : [];
105 })
106 .sort((x, y) => x.move.id - y.move.id);
107 if (items[0]?.deadline.id !== deadline.id) return undefined;
108 const key = Math.min(
109 ...deal.deadlines.filter(told).flatMap((d) => d.moves.filter((m) => m.amendment === last.amendment && m.notify === 1).map((m) => m.id)),
110 );
111 return { items, key };
112 }
113
85114 function words(
86115 deal: DealView,
87116 deadline: DeadlineView,
88117 party: Party,
89118 moment: Moment,
90119 agent: Agent,
120 notice: Notice | undefined,
91121 ): { subject: string; body: string } {
92122 const owner = deal.parties.find((p) => p.role === deadline.owes);
93123 const owed = deadline.what === "" ? "" : `${deadline.what}. `;
124 if (moment === "moved" && notice !== undefined && notice.items.length > 1) {
125 const changes = notice.items
126 .map(({ deadline: d, move }) => `• ${d.label}: from ${spoken(move.from_due)} to ${spoken(move.to_due)}`)
127 .join("\n");
128 return {
129 subject: `${deal.address} — dates changed`,
130 body: `Hi ${first(party.name)}, the contract for ${deal.address} has been amended, and these dates have changed:\n\n${changes}\n\nPlease work to the new dates, and let me know if any of them causes a problem.\n\n${signOff(agent)}`,
131 };
132 }
94133 if (moment === "moved") {
95134 const move = lastMove(deadline)!;
96135 return {
@@ -130,26 +169,21 @@ const remembered = memoizer<Draft[]>(400);
130169 /** The reminders one date has, sent or not. */
131170 export function draftsFor(deal: DealView, deadline: DeadlineView, agent: Agent): Draft[] {
132171 return MOMENTS.filter((moment) => moment !== "moved" || lastMove(deadline) !== undefined).flatMap((moment) =>
133 recipients(deal, deadline, moment).map((party) => {
134 const key = moveKey(deadline, moment);
135 const sent = deal.sent.find(
136 (s) =>
137 s.deadline_id === deadline.id &&
138 s.party_id === party.id &&
139 s.moment === moment &&
140 s.due === deadline.due &&
141 s.move_id === key,
142 );
143 const declined = deal.declined.find(
144 (s) =>
145 s.deadline_id === deadline.id &&
146 s.party_id === party.id &&
147 s.moment === moment &&
148 s.due === deadline.due &&
149 s.move_id === key,
150 );
151 const drafted = words(deal, deadline, party, moment, agent);
152 return {
172 recipients(deal, deadline, moment).flatMap((party) => {
173 const notice = moment === "moved" ? noticeFor(deal, deadline, party) : undefined;
174 // A notice that hangs on another date of its amendment is drafted there.
175 if (moment === "moved" && notice === undefined) return [];
176 const key = notice?.key ?? 0;
177 const amended = notice !== undefined && notice.items[0]!.move.amendment !== 0;
178 const mine = (s: { deadline_id: number; party_id: number; moment: Moment; due: string; move_id: number }): boolean =>
179 s.party_id === party.id &&
180 s.moment === moment &&
181 s.move_id === key &&
182 (amended || (s.deadline_id === deadline.id && s.due === deadline.due));
183 const sent = deal.sent.find(mine);
184 const declined = deal.declined.find(mine);
185 const drafted = words(deal, deadline, party, moment, agent, notice);
186 return [{
153187 deal_id: deal.id,
154188 address: deal.address,
155189 deadline_id: deadline.id,
@@ -160,13 +194,14 @@ export function draftsFor(deal: DealView, deadline: DeadlineView, agent: Agent):
160194 party_role: party.role,
161195 contact: party.contact,
162196 moment,
197 move_id: key,
163198 on: moment === "moved" ? today(new Date(lastMove(deadline)!.at)) : sendOn(deadline.due, moment),
164199 // A sent reminder keeps the words it went with, whatever the deal says now.
165200 subject: sent !== undefined && sent.subject !== "" ? sent.subject : drafted.subject,
166201 body: sent !== undefined && sent.subject !== "" ? sent.body : drafted.body,
167202 sent_at: sent?.sent_at ?? null,
168203 declined: declined === undefined ? null : { reason: declined.reason, by_name: declined.by_name },
169 };
204 }];
170205 }),
171206 );
172207 }
src/routes.ts +42
@@ -52,6 +52,8 @@ import {
5252 mayOpen,
5353 plan,
5454 plannedDates,
55 amendDeal,
56 amendment,
5557 moveDeadline,
5658 nameOf,
5759 removeDeadline,
@@ -581,6 +583,23 @@ export const routes: readonly Route[] = [
581583 return html(dealPage({ who: c.who, deal: found.value, on: today(), problem: { value: f.address, message: saved.message } }), STATUS.invalid);
582584 },
583585 },
586 {
587 method: "POST",
588 path: "/deals/:id/amend",
589 handle: async (c) => {
590 const f = await form(c);
591 if (f instanceof Response) return f;
592 const id = Number(c.params.id);
593 const dates = Object.fromEntries(Object.entries(f).filter(([key]) => /^due_\d+$/.test(key)).map(([key, due]) => [key.slice(4), due]));
594 const amended = amendDeal(c.db, c.who, { dealId: id, dates, reason: f.reason });
595 if (amended.ok) return back(withConflicts(c.db, c.who, id, "Contract amended."), `/deals/${id}`);
596 const found = getDeal(c.db, c.who, { id });
597 if (amended.error !== "invalid" || !found.ok) return back(amended.message, `/deals/${id}`);
598 const refused = amendment(found.value, dates, f.reason);
599 const problem = refused.ok ? { field: "", message: amended.message } : { field: refused.field, message: refused.message };
600 return html(dealPage({ who: c.who, deal: found.value, on: today(), amend: { values: f, problem } }), STATUS.invalid);
601 },
602 },
584603 {
585604 method: "POST",
586605 path: "/deals/:id/delete",
@@ -847,6 +866,29 @@ export const routes: readonly Route[] = [
847866 answer: { type: "object", properties: { id: { type: "integer" } }, required: ["id"] },
848867 },
849868 },
869 {
870 method: "POST",
871 path: "/api/deals/:id/amend",
872 handle: async (c) => {
873 const body = await readJson(c.request);
874 if (body === undefined) return json({ error: "too_large" }, 413);
875 const f = fields(body);
876 return answer(amendDeal(c.db, c.who, { dealId: Number(c.params.id), dates: f.dates, reason: f.reason }));
877 },
878 api: {
879 summary:
880 "Amend the contract: move several open dates at once with one reason (1 to 200 characters). Every date is checked first and none moves if one is wrong (422); a date given its current due is left alone, and nothing changed is refused. Each party is drafted one notice listing every change.",
881 body: {
882 type: "object",
883 properties: {
884 dates: { type: "object", description: "Open date id to its new due date (YYYY-MM-DD).", additionalProperties: { type: "string", format: "date" } },
885 reason: { type: "string", minLength: 1, maxLength: 200 },
886 },
887 required: ["dates", "reason"],
888 },
889 answer: DEAL,
890 },
891 },
850892 {
851893 method: "DELETE",
852894 path: "/api/deals/:id/deadlines/:deadline",
src/security.ts +1 −1
@@ -99,7 +99,7 @@ export function doorOf(
9999 return verb === undefined ? undefined : { resource, verb };
100100 }
101101 // `<api>/:id/<children>/:child` (or `/:action`, posted): a change inside the row is an update of it.
102 if (rest !== undefined && /^[^/]+\/[^/]+\/[^/]+$/.test(rest))
102 if (rest !== undefined && (/^[^/]+\/[^/]+\/[^/]+$/.test(rest) || (method === "POST" && /^[^/]+\/amend$/.test(rest))))
103103 return method === "PATCH" || method === "DELETE" || method === "POST" ? { resource, verb: "update" } : undefined;
104104 }
105105 return undefined;
src/server.test.ts +3 −1
@@ -176,6 +176,7 @@ test("the MCP server lists the tools and calls them as the caller", async () =>
176176 "list_people",
177177 "mark_done",
178178 "move_date",
179 "amend_deal",
179180 "send_reminder",
180181 "decline_reminder",
181182 "undo_decline_reminder",
@@ -264,7 +265,8 @@ test("an agent opens a deal, adds a date and a party and reopens a date over MCP
264265 });
265266
266267 test("a change is on the event stream, and a late client hears what it missed", async () => {
267 const stream = await fetch(base + "/events");
268 // Nothing earlier replays: this test listens for its own change, however many earlier tests made some.
269 const stream = await fetch(base + "/events", { headers: { "last-event-id": "999999999" } });
268270 expect(stream.headers.get("content-type")).toBe("text/event-stream");
269271 const reader = stream.body!.getReader();
270272 const next = async (): Promise<{ id: string; type: string }> => {
src/terminal.test.ts +21
@@ -602,3 +602,24 @@ test("a reader who may not change a deal sees no contact and no link", () => {
602602 expect(narrowed.parties.every((p) => p.contact === "")).toBe(true);
603603 expect(narrowed.sent.every((m) => m.href === null)).toBe(true);
604604 });
605
606 test("M amends the contract: a blank answer keeps a date, the rest move together with one reason", () => {
607 const own = createDeal(db, alice, { address: "8 Amend Rd", buyer: "Bea Buyer", seller: "Sid Seller", contractDate: today(), closingDate: addDays(today(), 60) });
608 if (!own.ok) throw new Error(own.message);
609 const read = () => {
610 const got = getDeal(db, alice, { id: own.value.id });
611 if (!got.ok) throw new Error(got.message);
612 return got.value;
613 };
614 const t = terminal(db, alice, context);
615 goTo(t, "Closing — 8 Amend Rd");
616 t.press("o");
617 const open = read().deadlines.filter((d) => d.done_at === null);
618 const answers = open.map((d) => (d.kind === "inspection" ? addDays(d.due, 2) : "")).flatMap((a) => [...a, "\r"]);
619 press(t, "M", ...answers, ..."Addendum", "\r");
620 const after = read();
621 expect(after.deadlines.filter((d) => d.moves.length > 0).map((d) => d.kind)).toEqual(["inspection"]);
622 expect(after.deadlines.find((d) => d.kind === "inspection")!.moves[0]!.reason).toBe("Addendum");
623 press(t, "M", ...open.flatMap(() => ["\r"]), ..."x", "\r");
624 expect(lines(t).join("\n")).toContain("Nothing changed");
625 });
src/terminal.ts +12 −3
@@ -8,7 +8,7 @@
88 * reminders what goes out today; enter reads a draft, e edits its words, s sends it
99 * people each person on the deals with every open date they owe (P)
1010 * timeline a deal's dates as a client would get them (t on a deal)
11 * deal one deal's dates and parties; a adds a date, p a party, A corrects the address, D removes it
11 * deal one deal's dates and parties; a adds a date, p a party, A corrects the address, M amends the contract, D removes it
1212 *
1313 * On a date (dates or deal view): x marks it done, u reopens it, m moves it
1414 * (a new date, then the reason). o or enter opens its deal; n opens a new
@@ -37,6 +37,7 @@ import {
3737 plan,
3838 plannedDates,
3939 type NewDeal,
40 amendDeal,
4041 moveDeadline,
4142 withConflicts,
4243 removeDeadline,
@@ -183,13 +184,21 @@ export function terminal(
183184
184185 function onDeal(key: string): boolean {
185186 const deal = openDeal();
186 if (deal === undefined || !["a", "p", "D", "e", "X", "A"].includes(key)) return false;
187 if (deal === undefined || !["a", "p", "D", "e", "X", "A", "M"].includes(key)) return false;
187188 const party = deal.parties[cursor - deal.deadlines.length];
188189 const date = deal.deadlines[cursor];
189190 if (key === "A")
190191 ask(deal, [`Address (now ${deal.address})`], ([address]) =>
191192 report(updateDeal(db, me, { id: deal.id, address }), `Address is now ${address!.trim()}.`),
192193 );
194 if (key === "M") {
195 const open = deal.deadlines.filter((d) => d.done_at === null);
196 ask(deal, [...open.map((d) => `${d.label} (now ${d.due}; blank keeps it)`), "Why the dates moved"], (answers) => {
197 const dates = Object.fromEntries(open.flatMap((d, i) => (answers[i]!.trim() === "" ? [] : [[String(d.id), answers[i]!.trim()]])));
198 const count = Object.keys(dates).length;
199 return report(amendDeal(db, me, { dealId: deal.id, dates, reason: answers[open.length] }), () => withConflicts(db, me, deal.id, `Amended the contract: ${count} date${count === 1 ? "" : "s"} considered.`));
200 });
201 }
193202 if (key === "e") {
194203 if (party === undefined) said = "Move to a party to edit it.";
195204 else
@@ -564,7 +573,7 @@ export function terminal(
564573 : view === "timeline"
565574 ? "b back to the deal · d dates · q quit"
566575 : view === "deal"
567 ? "j/k move · t client timeline · s messages · x done · u reopen · m move · a add date · p add party · e edit party · A edit address · X remove date/party · D remove deal · b back · q quit"
576 ? "j/k move · t client timeline · s messages · x done · u reopen · m move · a add date · p add party · e edit party · A edit address · M amend the contract · X remove date/party · D remove deal · b back · q quit"
568577 : `j/k move · x done · u reopen · m move · o open deal · n new deal · c check dates · / find · R restore samples · h ${showDone ? "hide" : "show"} done · w this week · r reminders · P people · q quit`;
569578 lines.push(dim(me.role === "anon" ? `${keys} · sign in with a key the forge knows to change anything` : keys));
570579 }

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs