Public: anyone can read this; the crew can change it.
A realtor reads the README in one go: what it does, a five-minute walk through the sample deals, and what is not real yet, with the technical part kept separate #18
Check · Review · Land · Live done — Landed and live in production.
mason/deal-clock:mason/15-a-realtor-reads-the-readme-in-one-go-wha → main 3 commits fork 3 threads · 3 unresolved
3 files
changed +268
−221
AGENTS.md +10 −1
| @@ -6,6 +6,14 @@ preview at its own address, deployed from your branch as you push. | ||
| 6 | 6 | |
| 7 | 7 | ## The rules |
| 8 | 8 | |
| 9 | - Two readers, two pages. `README.md` is for the agent (the realtor) in | |
| 10 | plain words: what the app does, a walk through the sample deals, what is | |
| 11 | real and what is simulated. Everything technical lives in | |
| 12 | `docs/TECHNICAL.md`: running it, the API, MCP, the terminal, the file | |
| 13 | table, the door, the audit trail, roles. Put a new technical fact there; | |
| 14 | change the README only when what an agent sees changes, and check the walk | |
| 15 | against the running app. | |
| 16 | ||
| 9 | 17 | - Work on the branch you were given. You cannot move the default branch; |
| 10 | 18 | a person merges your pull once it is reviewed. |
| 11 | 19 | - Keep state under `FORGE_APP_DATA`. Never write elsewhere at runtime. |
| @@ -140,4 +148,5 @@ To add a concept: | ||
| 140 | 148 | - Finish: the app boots, `/healthz` answers `{ ok, version, uptime }` |
| 141 | 149 | (the forge polls it; keep it cheap and apart from the page), `/` |
| 142 | 150 | answers, `bun test` is green, the README says how to use it and what is |
| 143 | real versus simulated, `forge.json` says how to run it. | |
| 151 | real versus simulated (and `docs/TECHNICAL.md` how to run it), `forge.json` | |
| 152 | says how to run it. |
README.md +74 −220
| @@ -1,231 +1,85 @@ | ||
| 1 | 1 | # deal-clock |
| 2 | 2 | |
| 3 | Every deadline of every deal on one timeline, so nothing slips. | |
| 3 | Every deadline of every deal on one timeline, so nothing slips. It shows an | |
| 4 | agent each date in a contract, who owes what, and the reminder to send each | |
| 5 | party before it comes due. | |
| 4 | 6 | |
| 5 | ## For the agent | |
| 7 | The technical part (running it, the API, MCP, the terminal, the files, roles) | |
| 8 | is in [](docs/TECHNICAL.md). | |
| 6 | 9 | |
| 7 | **The clock** is the first screen. Each deal is a lane; time runs left to | |
| 8 | right, and today is the dark line down the middle. Every date in a contract | |
| 9 | is a marker on its lane: | |
| 10 | ## Try it on the sample deals | |
| 10 | 11 | |
| 11 | - **red** — overdue | |
| 12 | - **amber** — due within three days | |
| 13 | - **teal** — coming up | |
| 14 | - **grey** — done | |
| 12 | Four sample deals are already in, so the first screen is never empty. Sign in | |
| 13 | first (see below). You land on **the clock**: each deal is a lane, time runs | |
| 14 | left to right, and today is the dark line down the middle. Every date in a | |
| 15 | contract is a marker on its lane: red is overdue, amber is due within three | |
| 16 | days, teal is coming up, grey is done. The samples stay current: each time | |
| 17 | the app starts, the ones nobody has touched move forward together by the days | |
| 18 | since they were last set, so the screen always looks like today. | |
| 15 | 19 | |
| 16 | Tap a marker to see who owes what, the reminder drafts for each party, | |
| 17 | and two buttons: **Mark done**, and **Move this date** (it asks why, and | |
| 18 | keeps the reason). Moving one date moves nothing else. | |
| 20 | 1. **Look at the clock.** You see four lanes: 77 Harbor View Dr, Unit 4B | |
| 21 | (the inspection date has passed, so its marker is red), 1418 Alder Lane | |
| 22 | (closing in a few days, with the earlier dates grey), 9 Orchard Row (the | |
| 23 | appraisal was moved), and 2210 Juniper Court (just signed, everything | |
| 24 | still ahead). | |
| 25 | 2. **Open a marker.** Tap the red inspection marker on Harbor View. A sheet | |
| 26 | opens with the date, who owes it (the buyer), what is owed, and the reminders | |
| 27 | for each party, grouped as three days before and the morning of. It also | |
| 28 | has two buttons: Mark done, and Move this date. | |
| 29 | 3. **Read and edit a reminder.** In the sheet, tap a party's reminder. You | |
Verify against the preview: the page shows no 'simulated' confirmation that I can find. Describe what the realtor really sees after Send, and the real 'N to send' wording ('2 to send' / 'all sent'). |
||
| 30 | see the words it would send, in a subject field and a message field, | |
| 31 | already filled in. Change the message; the subject can run to 150 | |
| 32 | characters and the message to 2000. | |
| 33 | 4. **Send it.** Tap Send. A short notice at the top of the page reads | |
| 34 | "Reminder sent (simulated)." and the reminder now shows "Sent" with | |
| 35 | today's date and your edited words, not the original draft. Under the | |
| 36 | clock, the heading "Reminders for today" counts what is left ("14 to send" | |
| 37 | becomes "13 to send"; when nothing is left it reads "all sent"). | |
| 38 | 5. **Move a date, with a reason.** Open the same marker again and use Move | |
| 39 | this date: pick a new date and say why ("Inspector delayed"). The marker | |
| 40 | jumps to the new date, and the sheet lists the move, the reason and who | |
| 41 | made it. No other date moves. | |
| 42 | 6. **See a date that was moved.** On 9 Orchard Row, open the appraisal | |
| 43 | marker. The sheet shows where it moved from and to, with the reason | |
| 44 | the appraiser gave. | |
| 45 | 7. **Mark a date done.** On Alder Lane, open a coming date and tap Mark | |
| 46 | done. The marker turns grey and its reminders stop. Reopen puts it back. | |
| 47 | 8. **Add a party.** Tap the address 2210 Juniper Court to open the deal's | |
| 48 | page. It lists every date and every party. Under "Add a party" pick a | |
| 49 | role (the title company, say), type a name and an email or phone, and | |
| 50 | add it. The party appears in the list, and the dates that concern them now | |
| 51 | have reminders for them. | |
| 52 | Made a typo? Each party has Edit (fix the name or email; the next | |
| 53 | reminder uses it) and Remove (its unsent reminders go with it). | |
| 54 | 9. **Add a date.** On the same page, add a date the contract added, such as | |
| 55 | an HOA review: a name, a date, who owes it. It joins the deal's list and | |
| 56 | the clock. A date you added has a Remove this date button in its sheet, | |
| 57 | for when the contract drops it; the standard dates cannot be removed, only | |
| 58 | moved or marked done. | |
| 59 | 10. **Open a new deal.** Back on the clock, tap New deal. Type an address, | |
| 60 | buyer, seller, contract date and closing date. The standard lengths are | |
| 61 | already filled in (inspection 10 days, appraisal 21, financing 30, title 14, | |
| 62 | final walkthrough the day before closing) and you can change them; tick | |
| 63 | Count business days to skip weekends. Tap Open deal. You land on the new | |
| 64 | deal's page with every date worked out, and it has its own lane on the clock. | |
| 65 | 11. **Download the calendar file.** On a deal's page, tap Add to calendar. | |
| 66 | You get a calendar file with every date of the deal and an alarm three days | |
| 67 | before and the morning of, to open in your own calendar app. | |
| 19 | 68 | |
| 20 | Under the clock, **Reminders for today** lists what should go out this | |
| 21 | morning. Every open date reminds the parties it concerns — buyer, seller, | |
| 22 | lender, title company, the other agent — **three days before** and **the | |
| 23 | morning of**. Open a draft to edit its subject (up to 150 characters) and message (up to | |
| 24 | 2000) in plain fields, then tap **Send**. What was approved is kept with the | |
| 25 | send: a sent reminder shows those words, not the current draft, on the page, | |
| 26 | in `/api/deals/:id`, in MCP and in the terminal. | |
| 27 | ||
| 28 | **A deal's page** (tap its address) lists every date and party. Add a date | |
| 29 | the contract adds (an HOA review, a repair deadline), add the lender or the | |
| 30 | title company, and **Add to calendar** downloads an `.ics` file with every | |
| 31 | date and its alarms for your own calendar. Nothing is stuck once added: each | |
| 32 | party has **Edit** (a mistyped name or email, which the next reminder draft | |
| 33 | uses) and **Remove**; a date you added opens a sheet with **Remove this | |
| 34 | date** for when the contract drops it. The standard contract dates cannot be | |
| 35 | removed — move them or mark them done. Removing a party or a date drops the | |
| 36 | reminders not yet sent; reminders already marked sent stay on record. Over | |
| 37 | the API: `PATCH` or `DELETE /api/deals/:id/parties/:party` and `DELETE | |
| 38 | /api/deals/:id/deadlines/:deadline`. | |
| 39 | ||
| 40 | **New deal** takes the address, buyer, seller, contract date and closing | |
| 41 | date, and works out the rest from the contingency lengths. The defaults — | |
| 42 | inspection 10 days, appraisal 21, financing 30, title 14, final walkthrough | |
| 43 | the day before closing — are editable on the form. Days are calendar days; | |
| 44 | tick *Count business days* to skip weekends. | |
| 45 | ||
| 46 | Four sample deals are already in: one with an overdue inspection, one | |
| 47 | closing this week, one whose appraisal was moved, and one just signed. | |
| 48 | They stay current: each time the app starts, the samples nobody has | |
| 49 | touched move forward together by the days since they were last set, so the | |
| 50 | first screen always looks like today. A sample you changed (marked done, | |
| 51 | moved, added a date or party to, sent a reminder for) is left alone. | |
| 52 | ||
| 53 | ### What is real, and what is not yet | |
| 69 | ## What is real, and what is not yet | |
| 54 | 70 | |
| 55 | 71 | - **Real:** the dates and their math, mark done, moves with their reasons, |
| 56 | who owes what, the reminder drafts, the record of what was sent, the | |
| 57 | calendar file, and `POST /tick` (below). | |
| 58 | - **Simulated:** sending. *Send* records that a reminder went out; no | |
| 59 | email or text message leaves the app. | |
| 60 | - **Not in this prototype:** real email or SMS, e-signature, document | |
| 61 | storage, and reading the dates out of a contract PDF (phase two). | |
| 72 | who owes what, the reminder drafts and editing them, the record of what was | |
| 73 | sent, the calendar file, and adding parties, dates and deals. | |
| 74 | - **Simulated:** sending. Send records that a reminder went out and keeps the | |
| 75 | words that were approved; no email or text message leaves the app. | |
| 76 | - **Not in this prototype (phase two):** real email or text messages, | |
| 77 | e-signature, document storage, and reading the dates out of a contract PDF. | |
| 62 | 78 | |
| 63 | Deals are private: sign in (the forge's account) to see the clock or a | |
| 64 | deal, and to open deals, mark dates done, move them and send reminders. A | |
| 65 | visitor who is not signed in is asked to sign in, and sees nothing of any | |
| 66 | deal. Only the agent who opened a deal, or an admin, can remove it. | |
| 79 | ## Signing in, and who can remove a deal | |
| 67 | 80 | |
| 68 | The name and brokerage in the header come from two settings | |
| 69 | (Settings → App → Environment): `DEAL_CLOCK_AGENT` and | |
| 70 | `DEAL_CLOCK_BROKERAGE`. Dates follow the server's time zone (`TZ`). | |
| 71 | ||
| 72 | ## For whoever runs it | |
| 73 | ||
| 74 | `POST /tick` answers the reminders that go out today and are not yet | |
| 75 | marked sent, as JSON — call it each morning as a signed-in account (a | |
| 76 | stranger gets 401; it sends nothing and changes nothing). `GET /deals/:id/ics` is a deal's calendar file. The JSON API is | |
| 77 | `/api/deals`, described at `/openapi.json`; the same operations are MCP | |
| 78 | tools at `POST /mcp` (`list_deals`, `get_deal`, `reminders_today`, | |
| 79 | `open_deal`, `add_date`, `add_party`, `mark_done` — with `done: false` to | |
| 80 | reopen a date — `move_date`, `send_reminder`). `send_reminder` takes an | |
| 81 | optional `subject` and `body` to send edited words; without them the draft | |
| 82 | goes as it is. | |
| 83 | ||
| 84 | The terminal does the page's work too. It opens on every open date, soonest | |
| 85 | first: `n` opens a new deal (address, buyer, seller, contract date, closing | |
| 86 | date; the standard lengths do the rest), `x` marks the date under the cursor | |
| 87 | done, `u` reopens it, `m` moves it (the new date, then the reason), `o` opens | |
| 88 | its deal — where `a` adds a date, | |
| 89 | `p` adds a party, `e` edits the party under the cursor (the cursor walks the | |
| 90 | dates, then the parties), `X` removes the date or party under it after you | |
| 91 | type `yes`, and `D` removes the deal likewise — and `h` | |
| 92 | shows done dates. `r` lists today's reminders: enter reads a draft, `e` | |
| 93 | types new words for it (a subject, then a message, where `\n` is a line | |
| 94 | break and an empty answer keeps the draft's), and `s` sends what you read, | |
| 95 | under the same limits as the page. `j`/`k` move, `b` goes back, `q` quits. What you change there | |
| 96 | shows on every open page within a second. | |
| 97 | ||
| 98 | No runtime dependencies: Bun, `bun:sqlite`, and the browser's own popovers | |
| 99 | — the page needs no script to work. | |
| 100 | ||
| 101 | This is an app: the forge runs it. Production follows the default branch; | |
| 102 | every open pull gets a preview at its own address with its own copy of the | |
| 103 | data. Everything the app keeps lives under `FORGE_APP_DATA`, which is what | |
| 104 | makes "production data" and "preview data" two different things. | |
| 105 | ||
| 106 | sh | |
| 107 | PORT=8080 FORGE_APP_DATA=./data bun run src/server.ts # run it here | |
| 108 | bun test # what `forge.json`'s app.test runs on every push | |
| 109 | FORGE_APP_DATA=./data bun run src/tty.ts # the terminal | |
| 110 | FORGE_APP_DATA=./data bun run src/db.ts --check # schema version, integrity | |
| 111 | bun run lint:design # no colour but the tokens' | |
| 112 | bun run contract:emit # rewrite contract/openapi.json from the routes | |
| 113 | ||
| 114 | ||
| 115 | `app.test` in `forge.json` runs beside `app.run` in every deploy, not before | |
| 116 | it: the preview comes up the moment the app answers, and says `live`, or | |
| 117 | `serving · tests failed` the moment the suite disagrees. | |
| 118 | ||
| 119 | ## The shape | |
| 120 | ||
| 121 | One implementation, many doors. `src/actions.ts` is every operation as a | |
| 122 | plain function — `(db, who, input)` in, data or a named failure out — and | |
| 123 | the page, the JSON API, the MCP server and the terminal all call it and | |
| 124 | decide nothing themselves. `AGENTS.md` says how to add to it. | |
| 125 | ||
| 126 | | file | what it is | | |
| 127 | | ---------------------------------- | -------------------------------------------------------------- | | |
| 128 | | `src/deals.ts` | deals: open, read, move a date, mark done, parties, reminders sent | | |
| 129 | | `src/dates.ts`, `src/deadlines.ts` | calendar math; the standard contract dates and who owes them | | |
| 130 | | `src/reminders.ts`, `src/ics.ts` | reminder drafts and `/tick`; the calendar file | | |
| 131 | | `src/sample.ts` | the four sample deals a new database starts with | | |
| 132 | | `src/result.ts` | what an action answers, and the audit habit they share | | |
| 133 | | `src/actions.ts` | the audit trail, read | | |
| 134 | | `contract.json` | who may do what: roles, and the least role each verb needs | | |
| 135 | | `src/contract.ts`, `src/can.ts` | the table, read at boot; the forge's evaluator, verbatim | | |
| 136 | | `src/security.ts` | the door: rationing, same origin, the table before the body | | |
| 137 | | `src/audit.ts` | every change and every refused one, as a row | | |
| 138 | | `src/who.ts` | who is asking, from the forge's signed headers | | |
| 139 | | `src/db.ts` | SQLite under `FORGE_APP_DATA`, WAL, forward-only migrations | | |
| 140 | | `src/live.ts` | the in-process bus and `GET /events` | | |
| 141 | | `src/mcp.ts` | the actions as MCP tools at `POST /mcp` | | |
| 142 | | `src/routes.ts` | every path, in one table, each API route described beside it | | |
| 143 | | `src/openapi.ts` | the routes as OpenAPI; committed at `contract/openapi.json` | | |
| 144 | | `src/pages/` | the clock, a deal, a new deal, a date's sheet; one `layout` | | |
| 145 | | `design/tokens.json`, `src/tokens.ts` | the look as data, light and dark; compiled to `/tokens.css` | | |
| 146 | | `src/http.ts` | the floor: headers, body cap, files | | |
| 147 | | `src/server.ts` | boot: open the database, serve | | |
| 148 | | `src/tty.ts`, `src/terminal.ts` | the terminal: the pty, and the keys and screen over the same actions | | |
| 149 | | `src/env.ts` | what the forge told this process | | |
| 150 | | `static/app.css`, `static/live.js` | the look in the tokens' words, and the clock that stays current | | |
| 151 | ||
| 152 | ## What every app stands on | |
| 153 | ||
| 154 | - **The door.** Before a route sees a request, `src/security.ts` rations | |
| 155 | writes (and a stranger's API calls), refuses a write from another site, | |
| 156 | and turns away — before the body is read — anyone the table lets through | |
| 157 | a resource's door for no row at all: 401 for a stranger, 403 for anyone | |
| 158 | else. The action still decides about the real row. | |
| 159 | - **The audit trail.** Every change, and every change refused, is a row: | |
| 160 | who, which resource and verb, which row, when, and whether they were | |
| 161 | let. Admins read it at `GET /api/audit`. A row that cannot be written | |
| 162 | is a log line, never a failed request. | |
| 163 | - **The API, described.** `GET /openapi.json` is `contract/openapi.json`, | |
| 164 | written from the routes by `bun run contract:emit`; each operation names | |
| 165 | its cell of the table (`x-contract`). `bun test` fails while it is stale. | |
| 166 | It needs a signed-in user: no door of the table is open to a stranger, and | |
| 167 | the description is shut to them when none is. | |
| 168 | - **Up, or not.** `GET /healthz` answers `{ ok, version, uptime }`; the | |
| 169 | forge waits on it before it sends anyone to a deploy. | |
| 170 | - **The look.** `design/tokens.json` holds every colour, space and size, | |
| 171 | light and dark; nothing else spells out a colour (`bun run lint:design`), | |
| 172 | and every pair a person reads meets 4.5:1 in both themes. | |
| 173 | - **The open web.** A shared link unfurls (description, Open Graph, a | |
| 174 | card); `/robots.txt` keeps crawlers to the page, and out of previews | |
| 175 | entirely; `/.well-known/security.txt` sends a reporter to the forge | |
| 176 | that runs the app. | |
| 177 | ||
| 178 | ## Who you are | |
| 179 | ||
| 180 | The forge says who is asking on every request it proxies, and the app | |
| 181 | verifies the signature (`src/who.ts`); nothing else is trusted. Three tiers: | |
| 182 | ||
| 183 | - **anon** — anyone. Sees the sign-in notice; no deal, date or party. | |
| 184 | - **user** — signed in to the forge and able to see this app. Reads every | |
| 185 | deal, its parties and their contacts. Opens deals, | |
| 186 | marks dates done, moves them, adds dates and parties, sends reminders; | |
| 187 | removes the deals they opened. | |
| 188 | - **admin** — able to write this repository. Removes any deal. | |
| 189 | ||
| 190 | "Sign in" is `/__forge/signin?to=<path>` and "Sign out" is | |
| 191 | `/__forge/signout`; the forge answers both on the app's own host, and | |
| 192 | `/__forge/report` too: it sends anyone, with no account, to report a | |
| 193 | problem on this app's repository, if that repository is public. | |
| 194 | ||
| 195 | ## Any interface | |
| 196 | ||
| 197 | The same actions, the same rules, at every door. A script is the person | |
| 198 | whose forge grant it carries; a bare script is anonymous. | |
| 199 | ||
| 200 | sh | |
| 201 | curl https://<app>/api/deals | |
| 202 | curl -X POST https://<app>/tick | |
| 203 | curl https://<app>/deals/1/ics | |
| 204 | ||
| 205 | ||
| 206 | As an MCP server, for Claude Code or Claude Desktop — the deal tools: | |
| 207 | ||
| 208 | sh | |
| 209 | claude mcp add --transport http deal-clock https://<app>/mcp | |
| 210 | ||
| 211 | ||
| 212 | json | |
| 213 | { | |
| 214 | "mcpServers": { "deal-clock": { "type": "http", "url": "https://<app>/mcp" } } | |
| 215 | } | |
| 216 | ||
| 217 | ||
| 218 | The clock stays current over `/events`: a date someone else marks done or | |
| 219 | moves — on the page, over the API, or in the terminal — changes without a | |
| 220 | reload. Without JavaScript it is the same page, one | |
| 221 | reload behind. | |
| 222 | ||
| 223 | The terminal opens with the exact command in `FORGE_APP_SSH` when the app | |
| 224 | runs (`ssh -p 2222 <name>@<forge>` — the app is the login name, the forge | |
| 225 | the host; `<name>--<pull>@<forge>` for a preview's). It is `src/tty.ts` on | |
| 226 | a real pty over the same data, as the account at the keyboard; everything | |
| 227 | it does is `src/terminal.ts`, which `src/terminal.test.ts` drives key by key. | |
| 228 | ||
| 229 | The forge sets `PORT`, `FORGE_APP_DATA`, `FORGE_APP_ENV` (`production` or | |
| 230 | `preview`), `FORGE_APP_URL`, `FORGE_APP_COMMIT`, `FORGE_APP_SSH` and | |
| 231 | `FORGE_APP_IDENTITY_KEY` when it starts the app. `forge.json` says how. | |
| 81 | Deals are private. Sign in with your forge account to see the clock or a | |
| 82 | deal, and to open deals, mark dates done, move them, add dates and parties, | |
| 83 | and send reminders. A visitor who is not signed in is asked to sign in and | |
| 84 | sees nothing of any deal. Only the agent who opened a deal, or an admin, can | |
| 85 | remove it, so the sample deals can be removed by an admin only. |
docs/TECHNICAL.md added +184
| @@ -0,0 +1,184 @@ | ||
| 1 | # deal-clock, technical | |
| 2 | ||
| 3 | For whoever builds, runs or connects to deal-clock. What the app is for, and | |
| 4 | a walk through it, are in the [](../README.md); this page holds | |
| 5 | everything technical, and `AGENTS.md` says how to add to it. | |
| 6 | ||
| 7 | ## Settings | |
| 8 | ||
| 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`). | |
| 12 | ||
| 13 | ## Running it, the API, MCP and the terminal | |
| 14 | ||
| 15 | Parties and dates can be corrected after they are added: a party can be | |
outdated
This paragraph about editing/removing parties and dates is not a setting; move it under 'Running it, the API, MCP and the terminal'. Same for the sending-is-simulated note below. |
||
| 16 | edited (a mistyped name or email, which the next reminder draft uses) or | |
| 17 | removed, and a date you added can be removed when the contract drops it. The | |
| 18 | standard contract dates cannot be removed — move them or mark them done. | |
| 19 | Removing a party or a date drops the reminders not yet sent; reminders already | |
| 20 | marked sent stay on record. Over the API: `PATCH` or `DELETE | |
| 21 | /api/deals/:id/parties/:party` and `DELETE /api/deals/:id/deadlines/:deadline`. | |
| 22 | ||
| 23 | Sending is simulated: *Send* records that a reminder went out and the | |
| 24 | words approved with it; nothing leaves the app. The record is shown on the | |
| 25 | page, in `/api/deals/:id`, in MCP and in the terminal. | |
| 26 | ||
| 27 | `POST /tick` answers the reminders that go out today and are not yet | |
| 28 | marked sent, as JSON — call it each morning as a signed-in account (a | |
| 29 | stranger gets 401; it sends nothing and changes nothing). `GET /deals/:id/ics` is a deal's calendar file. The JSON API is | |
| 30 | `/api/deals`, described at `/openapi.json`; the same operations are MCP | |
| 31 | tools at `POST /mcp` (`list_deals`, `get_deal`, `reminders_today`, | |
| 32 | `open_deal`, `add_date`, `add_party`, `mark_done` — with `done: false` to | |
| 33 | reopen a date — `move_date`, `send_reminder`). `send_reminder` takes an | |
| 34 | optional `subject` and `body` to send edited words; without them the draft | |
| 35 | goes as it is. | |
| 36 | ||
| 37 | The terminal does the page's work too. It opens on every open date, soonest | |
| 38 | first: `n` opens a new deal (address, buyer, seller, contract date, closing | |
| 39 | date; the standard lengths do the rest), `x` marks the date under the cursor | |
| 40 | done, `u` reopens it, `m` moves it (the new date, then the reason), `o` opens | |
| 41 | its deal — where `a` adds a date, | |
| 42 | `p` adds a party, `e` edits the party under the cursor (the cursor walks the | |
| 43 | dates, then the parties), `X` removes the date or party under it after you | |
| 44 | type `yes`, and `D` removes the deal likewise — and `h` | |
| 45 | shows done dates. `r` lists today's reminders: enter reads a draft, `e` | |
| 46 | types new words for it (a subject, then a message, where `\n` is a line | |
| 47 | break and an empty answer keeps the draft's), and `s` sends what you read, | |
| 48 | under the same limits as the page. `j`/`k` move, `b` goes back, `q` quits. What you change there | |
| 49 | shows on every open page within a second. | |
| 50 | ||
| 51 | No runtime dependencies: Bun, `bun:sqlite`, and the browser's own popovers | |
| 52 | — the page needs no script to work. | |
| 53 | ||
| 54 | This is an app: the forge runs it. Production follows the default branch; | |
| 55 | every open pull gets a preview at its own address with its own copy of the | |
| 56 | data. Everything the app keeps lives under `FORGE_APP_DATA`, which is what | |
| 57 | makes "production data" and "preview data" two different things. | |
| 58 | ||
| 59 | sh | |
| 60 | PORT=8080 FORGE_APP_DATA=./data bun run src/server.ts # run it here | |
| 61 | bun test # what `forge.json`'s app.test runs on every push | |
| 62 | FORGE_APP_DATA=./data bun run src/tty.ts # the terminal | |
| 63 | FORGE_APP_DATA=./data bun run src/db.ts --check # schema version, integrity | |
| 64 | bun run lint:design # no colour but the tokens' | |
| 65 | bun run contract:emit # rewrite contract/openapi.json from the routes | |
| 66 | ||
| 67 | ||
| 68 | `app.test` in `forge.json` runs beside `app.run` in every deploy, not before | |
| 69 | it: the preview comes up the moment the app answers, and says `live`, or | |
| 70 | `serving · tests failed` the moment the suite disagrees. | |
| 71 | ||
| 72 | ## The shape | |
| 73 | ||
| 74 | One implementation, many doors. `src/actions.ts` is every operation as a | |
| 75 | plain function — `(db, who, input)` in, data or a named failure out — and | |
| 76 | the page, the JSON API, the MCP server and the terminal all call it and | |
| 77 | decide nothing themselves. `AGENTS.md` says how to add to it. | |
| 78 | ||
| 79 | | file | what it is | | |
| 80 | | ---------------------------------- | -------------------------------------------------------------- | | |
| 81 | | `src/deals.ts` | deals: open, read, move a date, mark done, parties, reminders sent | | |
| 82 | | `src/dates.ts`, `src/deadlines.ts` | calendar math; the standard contract dates and who owes them | | |
| 83 | | `src/reminders.ts`, `src/ics.ts` | reminder drafts and `/tick`; the calendar file | | |
| 84 | | `src/sample.ts` | the four sample deals a new database starts with | | |
| 85 | | `src/result.ts` | what an action answers, and the audit habit they share | | |
| 86 | | `src/actions.ts` | the audit trail, read | | |
| 87 | | `contract.json` | who may do what: roles, and the least role each verb needs | | |
| 88 | | `src/contract.ts`, `src/can.ts` | the table, read at boot; the forge's evaluator, verbatim | | |
| 89 | | `src/security.ts` | the door: rationing, same origin, the table before the body | | |
| 90 | | `src/audit.ts` | every change and every refused one, as a row | | |
| 91 | | `src/who.ts` | who is asking, from the forge's signed headers | | |
| 92 | | `src/db.ts` | SQLite under `FORGE_APP_DATA`, WAL, forward-only migrations | | |
| 93 | | `src/live.ts` | the in-process bus and `GET /events` | | |
| 94 | | `src/mcp.ts` | the actions as MCP tools at `POST /mcp` | | |
| 95 | | `src/routes.ts` | every path, in one table, each API route described beside it | | |
| 96 | | `src/openapi.ts` | the routes as OpenAPI; committed at `contract/openapi.json` | | |
| 97 | | `src/pages/` | the clock, a deal, a new deal, a date's sheet; one `layout` | | |
| 98 | | `design/tokens.json`, `src/tokens.ts` | the look as data, light and dark; compiled to `/tokens.css` | | |
| 99 | | `src/http.ts` | the floor: headers, body cap, files | | |
| 100 | | `src/server.ts` | boot: open the database, serve | | |
| 101 | | `src/tty.ts`, `src/terminal.ts` | the terminal: the pty, and the keys and screen over the same actions | | |
| 102 | | `src/env.ts` | what the forge told this process | | |
| 103 | | `static/app.css`, `static/live.js` | the look in the tokens' words, and the clock that stays current | | |
| 104 | ||
| 105 | ## What every app stands on | |
| 106 | ||
| 107 | - **The door.** Before a route sees a request, `src/security.ts` rations | |
| 108 | writes (and a stranger's API calls), refuses a write from another site, | |
| 109 | and turns away — before the body is read — anyone the table lets through | |
| 110 | a resource's door for no row at all: 401 for a stranger, 403 for anyone | |
| 111 | else. The action still decides about the real row. | |
| 112 | - **The audit trail.** Every change, and every change refused, is a row: | |
| 113 | who, which resource and verb, which row, when, and whether they were | |
| 114 | let. Admins read it at `GET /api/audit`. A row that cannot be written | |
| 115 | is a log line, never a failed request. | |
| 116 | - **The API, described.** `GET /openapi.json` is `contract/openapi.json`, | |
| 117 | written from the routes by `bun run contract:emit`; each operation names | |
| 118 | its cell of the table (`x-contract`). `bun test` fails while it is stale. | |
| 119 | It needs a signed-in user: no door of the table is open to a stranger, and | |
| 120 | the description is shut to them when none is. | |
| 121 | - **Up, or not.** `GET /healthz` answers `{ ok, version, uptime }`; the | |
| 122 | forge waits on it before it sends anyone to a deploy. | |
| 123 | - **The look.** `design/tokens.json` holds every colour, space and size, | |
| 124 | light and dark; nothing else spells out a colour (`bun run lint:design`), | |
| 125 | and every pair a person reads meets 4.5:1 in both themes. | |
| 126 | - **The open web.** A shared link unfurls (description, Open Graph, a | |
| 127 | card); `/robots.txt` keeps crawlers to the page, and out of previews | |
| 128 | entirely; `/.well-known/security.txt` sends a reporter to the forge | |
| 129 | that runs the app. | |
| 130 | ||
| 131 | ## Who you are | |
| 132 | ||
| 133 | The forge says who is asking on every request it proxies, and the app | |
| 134 | verifies the signature (`src/who.ts`); nothing else is trusted. Three tiers: | |
| 135 | ||
| 136 | - **anon** — anyone. Sees the sign-in notice; no deal, date or party. | |
| 137 | - **user** — signed in to the forge and able to see this app. Reads every | |
| 138 | deal, its parties and their contacts. Opens deals, | |
| 139 | marks dates done, moves them, adds dates and parties, sends reminders; | |
| 140 | removes the deals they opened. | |
| 141 | - **admin** — able to write this repository. Removes any deal. | |
| 142 | ||
| 143 | "Sign in" is `/__forge/signin?to=<path>` and "Sign out" is | |
| 144 | `/__forge/signout`; the forge answers both on the app's own host, and | |
| 145 | `/__forge/report` too: it sends anyone, with no account, to report a | |
| 146 | problem on this app's repository, if that repository is public. | |
| 147 | ||
| 148 | ## Any interface | |
| 149 | ||
| 150 | The same actions, the same rules, at every door. A script is the person | |
| 151 | whose forge grant it carries; a bare script is anonymous. | |
| 152 | ||
| 153 | sh | |
| 154 | curl https://<app>/api/deals | |
| 155 | curl -X POST https://<app>/tick | |
| 156 | curl https://<app>/deals/1/ics | |
| 157 | ||
| 158 | ||
| 159 | As an MCP server, for Claude Code or Claude Desktop — the deal tools: | |
| 160 | ||
| 161 | sh | |
| 162 | claude mcp add --transport http deal-clock https://<app>/mcp | |
| 163 | ||
| 164 | ||
| 165 | json | |
| 166 | { | |
| 167 | "mcpServers": { "deal-clock": { "type": "http", "url": "https://<app>/mcp" } } | |
| 168 | } | |
| 169 | ||
| 170 | ||
| 171 | The clock stays current over `/events`: a date someone else marks done or | |
| 172 | moves — on the page, over the API, or in the terminal — changes without a | |
| 173 | reload. Without JavaScript it is the same page, one | |
| 174 | reload behind. | |
| 175 | ||
| 176 | The terminal opens with the exact command in `FORGE_APP_SSH` when the app | |
| 177 | runs (`ssh -p 2222 <name>@<forge>` — the app is the login name, the forge | |
| 178 | the host; `<name>--<pull>@<forge>` for a preview's). It is `src/tty.ts` on | |
| 179 | a real pty over the same data, as the account at the keyboard; everything | |
| 180 | it does is `src/terminal.ts`, which `src/terminal.test.ts` drives key by key. | |
| 181 | ||
| 182 | The forge sets `PORT`, `FORGE_APP_DATA`, `FORGE_APP_ENV` (`production` or | |
| 183 | `preview`), `FORGE_APP_URL`, `FORGE_APP_COMMIT`, `FORGE_APP_SSH` and | |
| 184 | `FORGE_APP_IDENTITY_KEY` when it starts the app. `forge.json` says how. |
new above
offline
Line is far past the file's wrap width; rewrap.