7b8ea94 · 3c7b573
@@ -23,8 +23,9 @@
decide nothing themselves. `AGENTS.md` says how to add to it.
| file                               | what it is                                                   |
| ---------------------------------- | ------------------------------------------------------------ |
| `src/actions.ts`                   | propose, list, read, withdraw, health — and who may          |
| `src/actions.ts`                   | propose, list, read, withdraw, remark, health — and who may  |
| `src/quorum.ts`                    | the three rules as plain data: read one, say it, count it    |
| `src/plain.ts`                     | somebody else's text, safe to print on a terminal            |
| `src/who.ts`                       | who is asking, from the forge's signed headers               |
| `src/db.ts`                        | SQLite under `FORGE_APP_DATA`, WAL, forward-only migrations  |
| `src/live.ts`                      | the event log, the bus, and `GET /events`                    |
@@ -44,8 +45,11 @@
verifies the signature (`src/who.ts`); nothing else is trusted. Three tiers:
- **anon** — anyone. Reads.
- **user** — signed in to the forge and able to see this app. Makes
  proposals, as themselves, and withdraws their own.
- **admin** — able to write this repository. Withdraws any proposal.
  proposals, as themselves, withdraws their own, says things on anybody's
  and deletes what they said; on a proposal they opened, they can accept a
  counter.
- **admin** — able to write this repository. Withdraws any proposal, deletes
  any remark, accepts a counter on any proposal.
"Sign in" is `/__forge/signin?to=<path>` and "Sign out" is
`/__forge/signout`; the forge answers both on the app's own host.
@@ -64,6 +68,14 @@
names and count a `named:` rule needs; `/p/<id>` says the rule in words above
the options. A guest sees both pages and no forms. With nothing proposed yet,
`/` says in four sentences what a proposal is rather than that it is empty.
Under the proposal is the argument about it: a composer for whoever is signed
in, and then the thread, oldest first, each remark labelled with its kind. The
thread is the last thing on the page and grows at the bottom, so a remark
arriving live moves nothing above it — least of all the box somebody is typing
in. An author sees a Delete on their own remark and an admin on every one; the
proposal's author and an admin see Accept on a counter that names an option
the proposal does not have yet.
`/about`, linked from the footer of every page, is the longer version: how a
proposal is decided, the three rules printed from `src/quorum.ts`, two plain
lists of what is built and what is not (voting, deliberation, a roster and
@@ -79,6 +91,11 @@
curl https://<app>/api/proposals/1          # one, with its options in order
curl -X POST https://<app>/api/proposals -H 'content-type: application/json' \
  -d '{"title":"Adopt the four-day week","body":"A trial for one quarter.","options":["Yes","No"],"rule":"named:alice,bob,carol:2"}'
curl -X POST https://<app>/api/proposals/1/withdraw
curl https://<app>/api/proposals/1/remarks  # the thread, oldest first
curl -X POST https://<app>/api/proposals/1/remarks -H 'content-type: application/json' \
  -d '{"kind":"counter","body":"Neither room is warm in winter.","optionLabel":"The library"}'
curl -X POST https://<app>/api/remarks/1/accept   # the proposal's author, or an admin
curl -X DELETE https://<app>/api/remarks/1        # its author, or an admin
curl https://<app>/api/health              # 200 while sound, 503 when it is not
```
@@ -111,9 +128,34 @@
named:alice,bob,carol:2   2 of those three agree; nobody else counts
Anything else is refused with a sentence naming the three forms, and no rule
at all means `majority`. A proposal keeps the rule it was opened with.
## Deliberation
The argument happens on the proposal and stays part of the record. A remark
is 1 to 2000 characters by a signed-in person, and it is one of three kinds:
- **comment** — something to say about the proposal: an opinion, a fact, a
  caveat, anything that is not a question or a demand for another option.
- **question** — something to ask its author, asked in the open so the
  answer is in the open too.
- **counter** — an argument for another option, which may name the option it
  wants in `optionLabel` (1–80 characters).
A remark's author or an admin deletes it. The proposal's author or an admin
can **accept** a counter that names an option, while the proposal is open:
the label is appended to the proposal as one more option and the counter is
stamped as accepted. Nothing else about the proposal moves, so every ballot
already cast still means what it meant — the page says so where the accepted
counter is. Accepting twice, accepting a counter that names nothing, naming
an option the proposal already has, and accepting on a proposal that is
withdrawn or decided are each refused.
A withdrawn or decided proposal still takes remarks: the record continues
after the decision, and an argument about what was decided belongs where the
decision is.
As an MCP server, for Claude Code or Claude Desktop — `list_proposals`,
`get_proposal`, `propose`, `withdraw_proposal`, `health` (the same action
behind `/api/health`, gated the same way):
`get_proposal`, `propose`, `withdraw_proposal`, `list_remarks`, `add_remark`,
`health` (the same action behind `/api/health`, gated the same way):
```sh
claude mcp add --transport http __TITLE__ https://<app>/mcp
@@ -126,7 +168,8 @@
claude mcp add --transport http __TITLE__ https://<app>/mcp
```
The page stays current over `/events`: a proposal someone else opens or
withdraws appears without a reload — including one written at the terminal,
withdraws, and a remark someone else writes, deletes or has accepted, appears
without a reload — including one written at the terminal,
which is another process on the same file. Every event is a row in `event`,
so the server follows what it did not write itself while anyone is
watching, and a browser that reconnects with `Last-Event-ID` is replayed
@@ -138,11 +181,14 @@
The terminal opens with the exact command in `FORGE_APP_SSH` when the app
runs (`ssh -p 2222 <name>@<forge>` — the app is the login name, the forge
the host; `<name>--<pull>@<forge>` for a preview's). It is `src/tty.ts` on
a real pty over the same data, as the account at the keyboard: `j`/`k`
moves, Enter opens the proposal under the cursor, `n` proposes (a title,
then the paragraph, then options one per line until a blank line, then the
rule — Enter alone for `majority`), `w` withdraws, Esc goes back and `q`
quits. A guest is told to sign in rather
than shown a composer.
moves, Enter opens the proposal under the cursor — with the thread on it
underneath — `n` proposes (a title, then the paragraph, then options one per
line until a blank line, then the rule — Enter alone for `majority`), `c`
says something (`1`, `2` or `3` for the kind, then the text, then the option
a counter wants), `w` withdraws, Esc goes back and `q` quits. A guest is told
to sign in rather than shown a composer. Nothing anyone else wrote reaches
that screen as a control character: it goes through `src/plain.ts` on the way
out, so the only escape sequences a terminal here sees are the app's own.
The forge sets `PORT`, `FORGE_APP_DATA`, `FORGE_APP_ENV` (`production` or
`preview`), `FORGE_APP_URL`, `FORGE_APP_COMMIT`, `FORGE_APP_SSH` and
@@ -3,10 +3,15 @@
import { mkdtempSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import {
  acceptCounter,
  addRemark,
  canDeleteRemark,
  canWithdraw,
  deleteRemark,
  getProposal,
  health,
  listProposals,
  listRemarks,
  propose,
  withdrawProposal,
  type AdminHealth,
@@ -247,6 +252,286 @@
test("a state that is not a state is refused, and a limit is bounded", () => {
  expect(capped.ok && capped.value.length).toBe(1);
});
/** A remark, or the reason it was refused, so a test reads as one line. */
const say = (
  who: Who,
  proposalId: number,
  input: Record<string, unknown> = {},
) =>
  addRemark(db, who, {
    proposalId,
    kind: "comment",
    body: "Sounds right to me.",
    ...input,
  } as { proposalId: number; kind: string; body: string });
test("anyone reads the thread; only a signed-in person writes in it", () => {
  const p = made(alice);
  expect(listRemarks(db, anon, { proposalId: p.id })).toEqual({
    ok: true,
    value: [],
  });
  const refused = say(anon, p.id);
  expect(refused.ok).toBe(false);
  if (!refused.ok) expect(refused.error).toBe("signin_required");
  const first = say(bob, p.id, { body: "  The kitchen has no chairs.  " });
  expect(first.ok && first.value.body).toBe("The kitchen has no chairs.");
  expect(first.ok && first.value.kind).toBe("comment");
  expect(first.ok && first.value.author_name).toBe("bob");
  expect(first.ok && first.value.option_label).toBeNull();
  expect(first.ok && first.value.accepted_at).toBeNull();
  const second = say(alice, p.id, {
    kind: "question",
    body: "Whose chairs are they?",
  });
  expect(second.ok).toBe(true);
  // Oldest first, and a guest reads all of it.
  const thread = listRemarks(db, anon, { proposalId: p.id });
  expect(thread.ok && thread.value.map((r) => r.kind)).toEqual([
    "comment",
    "question",
  ]);
  expect(thread.ok && thread.value.map((r) => r.body)).toEqual([
    "The kitchen has no chairs.",
    "Whose chairs are they?",
  ]);
  // The thread belongs to its proposal and to no other.
  const other = made(alice);
  expect(listRemarks(db, anon, { proposalId: other.id })).toEqual({
    ok: true,
    value: [],
  });
  const nowhere = listRemarks(db, anon, { proposalId: 9999 });
  expect(nowhere.ok).toBe(false);
  if (!nowhere.ok) expect(nowhere.error).toBe("not_found");
});
test("a remark is one of three kinds, 1 to 2000 characters, on a proposal that is there", () => {
  const p = made(alice);
  for (const input of [
    { kind: "shout" },
    { kind: "" },
    { kind: "COMMENT" },
    { body: "" },
    { body: "   " },
    { body: "x".repeat(2001) },
    // Only a counter names an option, and a label has a length like any other.
    { kind: "comment", optionLabel: "Neither" },
    { kind: "counter", optionLabel: "x".repeat(81) },
  ]) {
    const r = say(bob, p.id, input);
    expect(r.ok, JSON.stringify(input).slice(0, 40)).toBe(false);
    if (!r.ok) {
      expect(r.error).toBe("invalid");
      expect(r.message.length).toBeGreaterThan(10);
    }
  }
  expect(say(bob, p.id, { body: "x".repeat(2000) }).ok).toBe(true);
  const nowhere = say(bob, 9999);
  expect(nowhere.ok).toBe(false);
  if (!nowhere.ok) expect(nowhere.error).toBe("not_found");
  const odd = say(bob, 1.5);
  expect(odd.ok).toBe(false);
  if (!odd.ok) expect(odd.error).toBe("invalid");
});
test("the record continues after the decision: a withdrawn proposal still takes remarks", () => {
  const p = made(alice);
  expect(withdrawProposal(db, alice, { id: p.id }).ok).toBe(true);
  const after = say(bob, p.id, {
    kind: "question",
    body: "Why was this dropped?",
  });
  expect(after.ok).toBe(true);
  expect(listRemarks(db, anon, { proposalId: p.id }).ok).toBe(true);
});
test("the author deletes their own remark, an admin deletes any", () => {
  const p = made(alice);
  const bobs = say(bob, p.id);
  if (!bobs.ok) throw new Error(bobs.message);
  expect(canDeleteRemark(bob, bobs.value)).toBe(true);
  expect(canDeleteRemark(alice, bobs.value)).toBe(false);
  expect(canDeleteRemark(root, bobs.value)).toBe(true);
  expect(canDeleteRemark(anon, bobs.value)).toBe(false);
  // The proposal's author is not the remark's author.
  const byAlice = deleteRemark(db, alice, { id: bobs.value.id });
  expect(byAlice.ok).toBe(false);
  if (!byAlice.ok) expect(byAlice.error).toBe("forbidden");
  const byAnon = deleteRemark(db, anon, { id: bobs.value.id });
  expect(byAnon.ok).toBe(false);
  if (!byAnon.ok) expect(byAnon.error).toBe("signin_required");
  expect(deleteRemark(db, bob, { id: bobs.value.id }).ok).toBe(true);
  const again = deleteRemark(db, bob, { id: bobs.value.id });
  expect(again.ok).toBe(false);
  if (!again.ok) expect(again.error).toBe("not_found");
  const mine = say(alice, p.id);
  if (!mine.ok) throw new Error(mine.message);
  expect(deleteRemark(db, root, { id: mine.value.id }).ok).toBe(true);
  expect(listRemarks(db, anon, { proposalId: p.id })).toEqual({
    ok: true,
    value: [],
  });
});
test("an accepted counter adds exactly one option, once, and leaves the rest alone", () => {
  const p = made(alice);
  const counter = say(bob, p.id, {
    kind: "counter",
    body: "Neither room works in winter.",
    optionLabel: "The library",
  });
  if (!counter.ok) throw new Error(counter.message);
  expect(counter.value.option_label).toBe("The library");
  expect(counter.value.accepted_at).toBeNull();
  // Whoever wrote the counter does not get to take it themselves.
  const byBob = acceptCounter(db, bob, { id: counter.value.id });
  expect(byBob.ok).toBe(false);
  if (!byBob.ok) expect(byBob.error).toBe("forbidden");
  const byAnon = acceptCounter(db, anon, { id: counter.value.id });
  expect(byAnon.ok).toBe(false);
  if (!byAnon.ok) expect(byAnon.error).toBe("signin_required");
  const taken = acceptCounter(db, alice, { id: counter.value.id });
  expect(taken.ok && taken.value.option.label).toBe("The library");
  expect(taken.ok && taken.value.remark.accepted_at).not.toBeNull();
  const after = getProposal(db, anon, { id: p.id });
  expect(after.ok && after.value.options.map((o) => o.label)).toEqual([
    "The kitchen",
    "The garden",
    "The library",
  ]);
  expect(after.ok && after.value.options.map((o) => o.position)).toEqual([
    0, 1, 2,
  ]);
  // Nothing else about the proposal moved: the ballots people cast stand.
  expect(after.ok && after.value.state).toBe("open");
  expect(after.ok && after.value.decided_option_id).toBeNull();
  const twice = acceptCounter(db, alice, { id: counter.value.id });
  expect(twice.ok).toBe(false);
  if (!twice.ok) expect(twice.error).toBe("invalid");
  expect(
    getProposal(db, anon, { id: p.id }).ok &&
      (getProposal(db, anon, { id: p.id }) as { value: { options: unknown[] } })
        .value.options.length,
  ).toBe(3);
  // A label already on the proposal is not a second option.
  const same = say(bob, p.id, {
    kind: "counter",
    body: "The library again.",
    optionLabel: "the LIBRARY",
  });
  if (!same.ok) throw new Error(same.message);
  const clash = acceptCounter(db, alice, { id: same.value.id });
  expect(clash.ok).toBe(false);
  if (!clash.ok) expect(clash.error).toBe("invalid");
  // A counter with nothing to add, and a remark that is not a counter.
  const wordy = say(bob, p.id, { kind: "counter", body: "Not this way." });
  if (!wordy.ok) throw new Error(wordy.message);
  const nothing = acceptCounter(db, alice, { id: wordy.value.id });
  expect(nothing.ok).toBe(false);
  if (!nothing.ok) expect(nothing.error).toBe("invalid");
  const plain = say(bob, p.id);
  if (!plain.ok) throw new Error(plain.message);
  const notCounter = acceptCounter(db, alice, { id: plain.value.id });
  expect(notCounter.ok).toBe(false);
  if (!notCounter.ok) expect(notCounter.error).toBe("invalid");
  const nowhere = acceptCounter(db, alice, { id: 9999 });
  expect(nowhere.ok).toBe(false);
  if (!nowhere.ok) expect(nowhere.error).toBe("not_found");
});
test("a counter on a proposal that is no longer open cannot be accepted", () => {
  const p = made(alice);
  const counter = say(bob, p.id, {
    kind: "counter",
    body: "Ask again in March.",
    optionLabel: "Wait until March",
  });
  if (!counter.ok) throw new Error(counter.message);
  expect(withdrawProposal(db, alice, { id: p.id }).ok).toBe(true);
  const late = acceptCounter(db, alice, { id: counter.value.id });
  expect(late.ok).toBe(false);
  if (!late.ok) {
    expect(late.error).toBe("invalid");
    expect(late.message).toContain("withdrawn");
  }
  // An admin is not a way around a proposal that has stopped taking options.
  expect(acceptCounter(db, root, { id: counter.value.id }).ok).toBe(false);
  // Nor is a decided one. Nothing votes yet, so the state is set by hand —
  // the rule is the proposal's state and not how it got there.
  const chosen = made(alice);
  const late2 = say(bob, chosen.id, {
    kind: "counter",
    body: "Too late, but still.",
    optionLabel: "Somewhere else",
  });
  if (!late2.ok) throw new Error(late2.message);
  db.query("UPDATE proposal SET state = 'decided' WHERE id = ?1").run(
    chosen.id,
  );
  const decided = acceptCounter(db, alice, { id: late2.value.id });
  expect(decided.ok).toBe(false);
  if (!decided.ok) {
    expect(decided.error).toBe("invalid");
    expect(decided.message).toContain("decided");
  }
  const still = getProposal(db, anon, { id: chosen.id });
  expect(still.ok && still.value.options.length).toBe(2);
  // And the thread on a decided proposal still takes remarks.
  expect(say(bob, chosen.id, { body: "Glad that is settled." }).ok).toBe(true);
  const after = getProposal(db, anon, { id: p.id });
  expect(after.ok && after.value.options.length).toBe(2);
  expect(
    listRemarks(db, anon, { proposalId: p.id }).ok &&
      counter.value.accepted_at,
  ).toBeNull();
});
test("a proposal full of options takes no more from a counter", () => {
  const p = made(alice, {
    options: Array.from({ length: 8 }, (_, i) => `Option ${i}`),
  });
  const counter = say(bob, p.id, {
    kind: "counter",
    body: "One more.",
    optionLabel: "Option 9",
  });
  if (!counter.ok) throw new Error(counter.message);
  const full = acceptCounter(db, alice, { id: counter.value.id });
  expect(full.ok).toBe(false);
  if (!full.ok) expect(full.error).toBe("invalid");
  expect(getProposal(db, anon, { id: p.id }).ok).toBe(true);
});
test("a remark goes when its proposal does", () => {
  const p = made(alice);
  expect(say(bob, p.id).ok).toBe(true);
  db.query("DELETE FROM proposal WHERE id = ?1").run(p.id);
  expect(
    db
      .query<
        { n: number },
        [number]
      >("SELECT count(*) AS n FROM remark WHERE proposal_id = ?1")
      .get(p.id)!.n,
  ).toBe(0);
});
const PUBLIC_HEALTH = ["commit", "env", "ok", "schemaVersion", "uptimeSeconds"];
test("health tells anyone how the app is and nobody else where it lives", () => {
@@ -70,6 +70,27 @@
export interface FullProposal extends Proposal {
  readonly options: readonly Option[];
}
/**
 * What someone can say about a proposal. A `comment` is a remark on it, a
 * `question` asks its author something, and a `counter` argues for another
 * option — naming it in `option_label` when it has one to name.
 */
export type Kind = "comment" | "question" | "counter";
export const KINDS: readonly Kind[] = ["comment", "question", "counter"];
export interface Remark {
  readonly id: number;
  readonly proposal_id: number;
  readonly kind: Kind;
  readonly body: string;
  readonly option_label: string | null;
  /** When a counter's label was appended to the proposal, or null. */
  readonly accepted_at: string | null;
  readonly author_id: string;
  readonly author_name: string;
  readonly created_at: string;
}
export type Failure = "signin_required" | "forbidden" | "not_found" | "invalid";
export type Result<T> =
  | { ok: true; value: T }
@@ -240,6 +261,187 @@
export function withdrawProposal(
  return ok(withdrawn);
}
/**
 * The argument on a proposal, oldest first. Anyone reads it, including a
 * guest: what was said about a decision is part of the decision.
 */
export function listRemarks(
  db: Database,
  _who: Who,
  input: { proposalId: number },
): Result<Remark[]> {
  if (!Number.isInteger(input.proposalId))
    return fail("invalid", "A proposal id is a whole number.");
  if (!exists(db, input.proposalId))
    return fail("not_found", "No such proposal.");
  return ok(
    db
      .query<
        Remark,
        [number]
      >("SELECT * FROM remark WHERE proposal_id = ?1 ORDER BY id")
      .all(input.proposalId),
  );
}
/**
 * Say something about a proposal. A withdrawn or decided one still takes
 * remarks: the record continues after the decision, and an argument about
 * what was decided belongs where the decision is.
 */
export function addRemark(
  db: Database,
  who: Who,
  input: {
    proposalId: number;
    kind: string;
    body: string;
    optionLabel?: string | undefined;
  },
): Result<Remark> {
  if (who.role === "anon")
    return fail("signin_required", "Sign in to say something.");
  if (!Number.isInteger(input.proposalId))
    return fail("invalid", "A proposal id is a whole number.");
  const kind = String(input.kind ?? "");
  if (!KINDS.includes(kind as Kind))
    return fail("invalid", `A remark is one of ${KINDS.join(", ")}.`);
  const body = String(input.body ?? "").trim();
  if (body.length === 0 || body.length > BODY_MAX)
    return fail("invalid", `A remark is 1 to ${BODY_MAX} characters.`);
  const label = String(input.optionLabel ?? "").trim();
  // A label is what a counter is for; on anything else it would be stored
  // and never looked at, which is worse than being told.
  if (label !== "" && kind !== "counter")
    return fail("invalid", "Only a counter names an option.");
  if (label.length > LABEL_MAX)
    return fail(
      "invalid",
      `An option label is at most ${LABEL_MAX} characters.`,
    );
  if (!exists(db, input.proposalId))
    return fail("not_found", "No such proposal.");
  const remark = db
    .query<
      Remark,
      [number, string, string, string | null, string, string]
    >("INSERT INTO remark (proposal_id, kind, body, option_label, author_id, author_name) VALUES (?1, ?2, ?3, ?4, ?5, ?6) RETURNING *")
    .get(
      input.proposalId,
      kind,
      body,
      label === "" ? null : label,
      who.id,
      who.name,
    )!;
  emit("remark.added", remark);
  return ok(remark);
}
/** Take a remark back: its author, or an admin. */
export function deleteRemark(
  db: Database,
  who: Who,
  input: { id: number },
): Result<{ id: number; proposal_id: number }> {
  if (who.role === "anon")
    return fail("signin_required", "Sign in to delete a remark.");
  if (!Number.isInteger(input.id))
    return fail("invalid", "A remark id is a whole number.");
  const remark = db
    .query<Remark, [number]>("SELECT * FROM remark WHERE id = ?1")
    .get(input.id);
  if (remark === null) return fail("not_found", "No such remark.");
  if (!canDeleteRemark(who, remark))
    return fail("forbidden", "Only the author or an admin can delete a remark.");
  db.query("DELETE FROM remark WHERE id = ?1").run(remark.id);
  const gone = { id: remark.id, proposal_id: remark.proposal_id };
  emit("remark.removed", gone);
  return ok(gone);
}
/**
 * Take the option a counter asks for: append it to the proposal and stamp
 * the remark. Only the proposal's author or an admin, only while it is
 * open, and only once — and nothing else about the proposal moves, so every
 * ballot already cast still means what it meant.
 */
export function acceptCounter(
  db: Database,
  who: Who,
  input: { id: number },
): Result<{ remark: Remark; option: Option }> {
  if (who.role === "anon")
    return fail("signin_required", "Sign in to accept a counter.");
  if (!Number.isInteger(input.id))
    return fail("invalid", "A remark id is a whole number.");
  const remark = db
    .query<Remark, [number]>("SELECT * FROM remark WHERE id = ?1")
    .get(input.id);
  if (remark === null) return fail("not_found", "No such remark.");
  const proposal = db
    .query<ProposalRow, [number]>("SELECT * FROM proposal WHERE id = ?1")
    .get(remark.proposal_id);
  if (proposal === null) return fail("not_found", "No such proposal.");
  if (!canAcceptCounter(who, proposal))
    return fail(
      "forbidden",
      "Only the proposal's author or an admin can accept a counter.",
    );
  if (remark.kind !== "counter")
    return fail("invalid", "Only a counter proposes an option.");
  if (remark.option_label === null)
    return fail("invalid", "This counter names no option to add.");
  if (remark.accepted_at !== null)
    return fail("invalid", "This counter has already been accepted.");
  if (proposal.state !== "open")
    return fail(
      "invalid",
      `This proposal is ${proposal.state}; only an open one takes another option.`,
    );
  const options = db
    .query<
      Option,
      [number]
    >("SELECT * FROM option WHERE proposal_id = ?1 ORDER BY position")
    .all(proposal.id);
  const label = remark.option_label;
  if (options.some((o) => o.label.toLowerCase() === label.toLowerCase()))
    return fail("invalid", "That option is already on this proposal.");
  if (options.length >= OPTIONS_MAX)
    return fail(
      "invalid",
      `A proposal has at most ${OPTIONS_MAX} options; this one is full.`,
    );
  // The option and the stamp are one thing: both rows or neither.
  const done = db.transaction(() => {
    const option = db
      .query<
        Option,
        [number, string, number]
      >("INSERT INTO option (proposal_id, label, position) VALUES (?1, ?2, ?3) RETURNING *")
      .get(proposal.id, label, options.length)!;
    const stamped = db
      .query<
        Remark,
        [number]
      >("UPDATE remark SET accepted_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = ?1 RETURNING *")
      .get(remark.id)!;
    db.query(
      "UPDATE proposal SET updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = ?1",
    ).run(proposal.id);
    return { remark: stamped, option };
  })();
  emit("remark.accepted", done);
  return ok(done);
}
/** Whether a proposal with this id is there at all. */
const exists = (db: Database, id: number): boolean =>
  db
    .query<{ id: number }, [number]>("SELECT id FROM proposal WHERE id = ?1")
    .get(id) !== null;
/** What anyone may know about this process: nothing about anybody's data. */
export interface Health {
  readonly ok: boolean;
@@ -327,6 +529,14 @@
function soundness(db: Database, now = Date.now()): string {
  return verdict;
}
/**
 * Ownership, once: whoever wrote the row, or an admin. Every "only the
 * author or an admin" in this file is this function, so a door that asks
 * gets the same answer the action will give it.
 */
const mine = (who: Who, row: { author_id: string }): boolean =>
  who.role === "admin" || (who.role === "user" && who.id === row.author_id);
/**
 * Whether `who` may withdraw `proposal` at all. The state is the action's
 * own check; the page and the terminal ask this and the state together, so
@@ -335,6 +545,20 @@
function soundness(db: Database, now = Date.now()): string {
export const canWithdraw = (
  who: Who,
  proposal: Pick<Proposal, "author_id">,
): boolean =>
  who.role === "admin" ||
  (who.role === "user" && who.id === proposal.author_id);
): boolean => mine(who, proposal);
/** Whether `who` may delete `remark`: its author, or an admin. */
export const canDeleteRemark = (
  who: Who,
  remark: Pick<Remark, "author_id">,
): boolean => mine(who, remark);
/**
 * Whether `who` may accept a counter on `proposal` — the proposal's author
 * or an admin. Whether this counter can be accepted is `acceptCounter`'s
 * own check; the page asks both to decide whether to draw the button.
 */
export const canAcceptCounter = (
  who: Who,
  proposal: Pick<Proposal, "author_id">,
): boolean => mine(who, proposal);
@@ -58,6 +58,22 @@
export const migrations: string[] = [
    data TEXT NOT NULL,
    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
  )`,
  // The argument, kept with what it argues about: a remark is a comment, a
  // question, or a counter that names the option it wants instead
  // (`option_label`, stamped `accepted_at` when the proposal's author takes
  // it). It goes when its proposal goes.
  `CREATE TABLE remark (
    id INTEGER PRIMARY KEY,
    proposal_id INTEGER NOT NULL REFERENCES proposal (id) ON DELETE CASCADE,
    kind TEXT NOT NULL CHECK (kind IN ('comment', 'question', 'counter')),
    body TEXT NOT NULL CHECK (length(body) BETWEEN 1 AND 2000),
    option_label TEXT CHECK (option_label IS NULL OR length(option_label) BETWEEN 1 AND 80),
    accepted_at TEXT,
    author_id TEXT NOT NULL,
    author_name TEXT NOT NULL,
    created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
  );
  CREATE INDEX remark_proposal ON remark (proposal_id)`,
];
export function openDb(dir = dataDir): Database {
@@ -8,12 +8,15 @@
import type { Database } from "bun:sqlite";
import {
  addRemark,
  getProposal,
  health,
  listProposals,
  listRemarks,
  propose,
  withdrawProposal,
  BODY_MAX,
  KINDS,
  LABEL_MAX,
  OPTIONS_MAX,
  OPTIONS_MIN,
@@ -123,6 +126,51 @@
export const tools: readonly Tool[] = [
    },
    run: (db, who, args) => withdrawProposal(db, who, { id: Number(args.id) }),
  },
  {
    name: "list_remarks",
    description:
      "The argument on one proposal — comments, questions and counters — oldest first. Anyone may read it.",
    inputSchema: {
      type: "object",
      properties: {
        proposal_id: { type: "integer", minimum: 1 },
      },
      required: ["proposal_id"],
    },
    run: (db, who, args) =>
      listRemarks(db, who, { proposalId: Number(args.proposal_id) }),
  },
  {
    name: "add_remark",
    description:
      "Say something on a proposal as the signed-in person: a comment on it, a question for its author, or a counter arguing for another option. A counter may name that option in option_label, and the proposal's author can then add it. A withdrawn or decided proposal still takes remarks. Anonymous callers cannot.",
    inputSchema: {
      type: "object",
      properties: {
        proposal_id: { type: "integer", minimum: 1 },
        kind: { type: "string", enum: [...KINDS] },
        body: { type: "string", minLength: 1, maxLength: BODY_MAX },
        option_label: {
          type: "string",
          minLength: 1,
          maxLength: LABEL_MAX,
          description:
            "The option this counter wants the proposal to offer instead. Counters only.",
        },
      },
      required: ["proposal_id", "kind", "body"],
    },
    run: (db, who, args) =>
      addRemark(db, who, {
        proposalId: Number(args.proposal_id),
        kind: String(args.kind ?? ""),
        body: String(args.body ?? ""),
        optionLabel:
          args.option_label === undefined || args.option_label === null
            ? undefined
            : String(args.option_label),
      }),
  },
  {
    name: "health",
    description:
@@ -24,6 +24,8 @@
interface RuleEntry {
const WORKS: readonly string[] = [
  "Open a proposal: a title, a paragraph, two to eight options, and the rule that will decide it.",
  "Read every proposal and any one of them, signed in or not.",
  "Say something on a proposal: a comment, a question for its author, or a counter arguing for another option — and delete your own again.",
  "Accept a counter on a proposal you opened: the option it names is added to it, and every ballot already cast still stands.",
  "Withdraw a proposal you opened while it is open; an admin withdraws any.",
  "Watch the list stay current as other people write, without reloading.",
];
@@ -35,7 +37,7 @@
const WORKS: readonly string[] = [
 */
const NOT_YET: readonly string[] = [
  "Voting. The counting in the quorum module is written and tested, but nothing casts a ballot yet, so nothing is decided yet either.",
  "Deliberation. There is no way to ask a question or argue a point on a proposal before it decides.",
  "Answers. A question on a proposal is asked in the open and answered in the open; nothing here tells its author that one is waiting.",
  "A roster. Who counts as a member of this group has no page and no list; a “named few” rule is the only way to say who counts.",
  "Bindings. A decision is a record here and does nothing elsewhere — no webhook, no issue, no file.",
];
@@ -1,21 +1,50 @@
/**
 * One proposal: its title, its paragraph, its options in order, who wrote
 * it and where it stands — and a Withdraw form for whoever may withdraw it
 * while it is open. A guest sees all of it and no forms.
 * while it is open. Below it the argument: a composer for whoever is signed
 * in, and then the thread, oldest first. A guest sees all of it and no forms.
 *
 * The composer sits above the thread on purpose. The thread is the live
 * region, it grows at the bottom, and it is the last thing on the page — so
 * a remark that arrives while someone is typing moves nothing they can see,
 * and the box they are typing in is never the thing that gets replaced.
 */
import { canWithdraw, type FullProposal } from "../actions.ts";
import {
  canAcceptCounter,
  canDeleteRemark,
  canWithdraw,
  KINDS,
  BODY_MAX,
  LABEL_MAX,
  type FullProposal,
  type Kind,
  type Remark,
} from "../actions.ts";
import { escape } from "../http.ts";
import { describeRule } from "../quorum.ts";
import type { Who } from "../who.ts";
import { ago, layout, toast } from "./layout.ts";
/** What each kind is called on the page, and what it is for in one line. */
const KIND_LABEL: Record<Kind, string> = {
  comment: "Comment",
  question: "Question",
  counter: "Counter",
};
const KIND_HINT: Record<Kind, string> = {
  comment: "something to say about this proposal",
  question: "something to ask its author",
  counter: "another option it should offer instead",
};
export function proposalPage(input: {
  who: Who;
  proposal: FullProposal;
  remarks: readonly Remark[];
  notice?: string | undefined;
}): string {
  const { who, proposal, notice } = input;
  const { who, proposal, remarks, notice } = input;
  const withdraw =
    proposal.state === "open" && canWithdraw(who, proposal)
      ? `<form method="post" action="/proposals/${proposal.id}/withdraw">
@@ -23,7 +52,7 @@
export function proposalPage(input: {
        </form>`
      : "";
  return layout(
    `<section id="proposal" data-live="proposal.opened proposal.withdrawn" class="card">
    `<section id="proposal" data-live="proposal.opened proposal.withdrawn remark.accepted" class="card">
    <div class="head-row">
      <h2>${escape(proposal.title)}</h2>
      <span class="pill" data-state="${escape(proposal.state)}">${escape(proposal.state)}</span>
@@ -39,12 +68,87 @@
export function proposalPage(input: {
      .join("")}</ol>
    <div class="row">${withdraw}<a class="button button-quiet" href="/">All proposals</a></div>
  </section>
  <section class="card">${composer(who, proposal)}</section>
  <section id="thread" data-live="remark.added remark.removed remark.accepted">
    ${thread(who, proposal, remarks)}
  </section>
  ${toast(notice)}`,
    who,
    `/p/${proposal.id}`,
  );
}
/** Where a remark is written. A guest is told how to get one instead. */
const composer = (who: Who, proposal: FullProposal): string =>
  who.role === "anon"
    ? `<p class="muted">Reading as a guest. <a href="/__forge/signin?to=${escape(encodeURIComponent(`/p/${proposal.id}`))}">Sign in</a> to comment, ask a question or counter with another option.</p>`
    : `<form class="stack composer remark-form" method="post" action="/proposals/${proposal.id}/remarks">
      <label class="field">
        <span>Say something</span>
        <textarea class="input" name="body" rows="3" placeholder="What you think, what you want to know, or the option you would rather have" required maxlength="${BODY_MAX}"></textarea>
      </label>
      <label class="field">
        <span>As a</span>
        <select class="input" name="kind">${KINDS.map(
          (kind) =>
            `<option value="${kind}"${kind === "comment" ? " selected" : ""}>${KIND_LABEL[kind]} — ${KIND_HINT[kind]}</option>`,
        ).join("")}</select>
      </label>
      <label class="field counter-field">
        <span>The option you want instead, for a counter only</span>
        <input class="input" name="option_label" autocomplete="off" maxlength="${LABEL_MAX}" placeholder="Neither — ask again in March">
        <span class="muted small">Left empty a counter is only an argument. Filled in, the proposal's author can add it to the options with one press; every ballot already cast still stands.</span>
      </label>
      <div class="row"><button class="button">Say it</button></div>
    </form>`;
/** The argument, oldest first. */
const thread = (
  who: Who,
  proposal: FullProposal,
  remarks: readonly Remark[],
): string =>
  remarks.length === 0
    ? `<p class="muted small">Nothing said yet.</p>`
    : `<p class="muted small">${remarks.length} remark${remarks.length === 1 ? "" : "s"}, oldest first.</p>
    <ol class="list thread">${remarks.map((remark) => item(who, proposal, remark)).join("")}</ol>`;
const item = (who: Who, proposal: FullProposal, remark: Remark): string => {
  const accept =
    remark.kind === "counter" &&
    remark.option_label !== null &&
    remark.accepted_at === null &&
    proposal.state === "open" &&
    canAcceptCounter(who, proposal)
      ? `<form method="post" action="/remarks/${remark.id}/accept">
          <input type="hidden" name="proposal" value="${proposal.id}">
          <button class="button button-quiet">Accept as an option</button>
        </form>`
      : "";
  const remove = canDeleteRemark(who, remark)
    ? `<form method="post" action="/remarks/${remark.id}/delete">
        <input type="hidden" name="proposal" value="${proposal.id}">
        <button class="button button-quiet">Delete</button>
      </form>`
    : "";
  return `<li class="remark" data-kind="${escape(remark.kind)}">
    <p class="muted small"><span class="pill" data-kind="${escape(remark.kind)}">${KIND_LABEL[remark.kind] ?? escape(remark.kind)}</span> ${escape(remark.author_name)} · <time datetime="${escape(remark.created_at)}">${ago(remark.created_at)}</time></p>
    <p class="body">${escape(remark.body)}</p>
    ${wanted(remark)}
    <div class="row">${accept}${remove}</div>
  </li>`;
};
/** The option a counter names, and whether it was taken. */
const wanted = (remark: Remark): string =>
  remark.option_label === null
    ? ""
    : `<p class="small wanted">Instead: <b>${escape(remark.option_label)}</b>${
        remark.accepted_at === null
          ? ""
          : ` · <span class="muted">added to the options <time datetime="${escape(remark.accepted_at)}">${ago(remark.accepted_at)}</time>; earlier ballots stand</span>`
      }</p>`;
/**
 * How this one is decided, in words, above the options. The rule was read
 * once in the action; a rule this app cannot read — a row from before the
@@ -0,0 +1,27 @@
import { expect, test } from "bun:test";
import { oneLine, plain } from "./plain.ts";
test("text someone else wrote carries no instruction to a terminal", () => {
  // A remark that tries to clear the screen, move the cursor and colour the
  // rest of the session red comes out as the words it is made of.
  const attack = "\x1b[2J\x1b[H\x1b[31mall clear\x07 \x00 \x9b1m";
  const printed = plain(attack);
  expect(printed).not.toContain("\x1b");
  expect(printed).not.toContain("\x07");
  expect(printed).not.toContain("\x00");
  expect(printed).not.toContain("\x9b");
  expect(printed).toContain("all clear");
  // Every control character becomes a space, so the words stay apart.
  expect(plain("a\x1bb")).toBe("a b");
  // A paragraph is still a paragraph: the terminal wraps those itself.
  expect(plain("one\ntwo\r\nthree")).toBe("one\ntwo\r\nthree");
  // On one line it is one line, whatever it was.
  expect(oneLine("one\ntwo")).toBe("one two");
  // What is left of an escape sequence is the letters in it, printed.
  expect(oneLine("one\x1b[31m\ntwo")).toBe("one [31m two");
  // Ordinary text is untouched, accents and all.
  expect(plain("Räume — “the garden”, 2 × 3")).toBe(
    "Räume — “the garden”, 2 × 3",
  );
});
@@ -0,0 +1,17 @@
/**
 * Text someone else wrote, printed on a terminal that reads escape
 * sequences as instructions. `escape` in `http.ts` is this for HTML; this is
 * it for a pty: every C0 and C1 control character becomes a space, so the
 * only thing that moves the cursor in `src/tty.ts` is `src/tty.ts`.
 *
 * Newline and carriage return survive: the terminal wraps paragraphs itself
 * and they are the shape of the text, not a command.
 */
const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g;
export const plain = (text: string): string => text.replace(CONTROL, " ");
/** The same, on one line: a title in a list is a line and not three. */
export const oneLine = (text: string): string =>
  plain(text).replace(/[\r\n]+/g, " ");
@@ -6,9 +6,13 @@
import type { Database } from "bun:sqlite";
import {
  acceptCounter,
  addRemark,
  deleteRemark,
  getProposal,
  health,
  listProposals,
  listRemarks,
  propose,
  withdrawProposal,
  type Failure,
@@ -45,7 +49,7 @@
export interface Context {
}
export interface Route {
  readonly method: "GET" | "POST";
  readonly method: "GET" | "POST" | "DELETE";
  readonly path: string;
  readonly handle: (ctx: Context) => Response | Promise<Response>;
}
@@ -121,8 +125,14 @@
export const routes: readonly Route[] = [
      const found = getProposal(c.db, c.who, { id: Number(c.params.id) });
      // Anything that is not a proposal — a bad id or a gone one — is a 404.
      if (!found.ok) return html(missing(found.message, c.who), 404, clear);
      const said = listRemarks(c.db, c.who, { proposalId: found.value.id });
      return html(
        proposalPage({ who: c.who, proposal: found.value, notice }),
        proposalPage({
          who: c.who,
          proposal: found.value,
          remarks: said.ok ? said.value : [],
          notice,
        }),
        200,
        clear,
      );
@@ -159,6 +169,50 @@
export const routes: readonly Route[] = [
        pathOf(c.params.id ?? ""),
      ),
  },
  // The thread. A remark form comes back to the proposal it was written on:
  // the page puts that id in the form, and `pathOf` makes a path out of a
  // whole number or out of nothing at all.
  {
    method: "POST",
    path: "/proposals/:id/remarks",
    handle: async (c) => {
      const form = await readForm(c.request);
      if (form === undefined) return text("too large", 413);
      return done(
        addRemark(c.db, c.who, {
          proposalId: Number(c.params.id),
          kind: String(form.get("kind") ?? ""),
          body: String(form.get("body") ?? ""),
          optionLabel: String(form.get("option_label") ?? ""),
        }),
        pathOf(c.params.id ?? ""),
      );
    },
  },
  {
    method: "POST",
    path: "/remarks/:id/delete",
    handle: async (c) => {
      const form = await readForm(c.request);
      if (form === undefined) return text("too large", 413);
      return done(
        deleteRemark(c.db, c.who, { id: Number(c.params.id) }),
        pathOf(String(form.get("proposal") ?? "")),
      );
    },
  },
  {
    method: "POST",
    path: "/remarks/:id/accept",
    handle: async (c) => {
      const form = await readForm(c.request);
      if (form === undefined) return text("too large", 413);
      return done(
        acceptCounter(c.db, c.who, { id: Number(c.params.id) }),
        pathOf(String(form.get("proposal") ?? "")),
      );
    },
  },
  // The JSON API: the same actions, the same identity, plain status codes.
  {
@@ -202,6 +256,42 @@
export const routes: readonly Route[] = [
    handle: (c) =>
      answer(withdrawProposal(c.db, c.who, { id: Number(c.params.id) })),
  },
  {
    method: "GET",
    path: "/api/proposals/:id/remarks",
    handle: (c) =>
      answer(listRemarks(c.db, c.who, { proposalId: Number(c.params.id) })),
  },
  {
    method: "POST",
    path: "/api/proposals/:id/remarks",
    handle: async (c) => {
      const body = await readJson(c.request);
      if (body === undefined) return json({ error: "too_large" }, 413);
      const input = fields(body);
      return answer(
        addRemark(c.db, c.who, {
          proposalId: Number(c.params.id),
          kind: String(input.kind ?? ""),
          body: String(input.body ?? ""),
          optionLabel: given(input.optionLabel ?? input.option_label),
        }),
        201,
      );
    },
  },
  {
    method: "DELETE",
    path: "/api/remarks/:id",
    handle: (c) =>
      answer(deleteRemark(c.db, c.who, { id: Number(c.params.id) })),
  },
  {
    method: "POST",
    path: "/api/remarks/:id/accept",
    handle: (c) =>
      answer(acceptCounter(c.db, c.who, { id: Number(c.params.id) })),
  },
  // What a probe asks, forever: 200 while the app is sound, 503 when it is
  // not, and never a word about anybody's data.
@@ -136,9 +136,12 @@
test("/about says what this is, from the modules that own the facts", async () =
      ? "off in this environment"
      : escape(process.env.FORGE_APP_SSH),
  );
  // Honest about what is not built: voting, deliberation, bindings.
  for (const missing of ["Voting.", "Deliberation.", "Bindings."])
  // Honest about what is not built: voting, notifying, bindings — and
  // deliberation has landed, so it is no longer on that list.
  for (const missing of ["Voting.", "Answers.", "Bindings."])
    expect(page).toContain(missing);
  expect(page).toContain("Say something on a proposal");
  expect(page).not.toContain("Deliberation.");
  expect(page).toContain("reading as a guest");
  expect(page).not.toContain("Signed in as");
@@ -453,6 +456,8 @@
test("the MCP server lists the tools and calls them as the caller", async () =>
    "get_proposal",
    "propose",
    "withdraw_proposal",
    "list_remarks",
    "add_remark",
    "health",
  ]);
  const call = (name: string, args: unknown, who = {}) =>
@@ -492,6 +497,253 @@
test("the MCP server lists the tools and calls them as the caller", async () =>
  expect(notified.status).toBe(202);
});
/** A remark over the API, for the tests that need a thread to look at. */
const remark = async (
  who: Record<string, string>,
  id: number,
  body: unknown,
) => {
  const made = await api(
    `/api/proposals/${id}/remarks`,
    { method: "POST", ...jsonBody(body) },
    who,
  );
  expect(made.status).toBe(201);
  return (await made.json()) as { id: number; kind: string };
};
test("the thread reads for a guest, writes for a person, and escapes what it shows", async () => {
  const p = await open(alice, { title: "Where to eat" });
  const guest = await (await fetch(`${base}/p/${p.id}`)).text();
  expect(guest).toContain("Nothing said yet.");
  expect(guest).not.toContain('action="/proposals/' + p.id + '/remarks"');
  expect(guest).toContain("Sign in");
  // A guest cannot write, at either door.
  const form = new FormData();
  form.set("kind", "comment");
  form.set("body", "Not mine to say.");
  expect(
    (
      await api(`/proposals/${p.id}/remarks`, {
        method: "POST",
        body: form,
        redirect: "manual",
      })
    ).headers.get("set-cookie"),
  ).toContain("notice=");
  expect(
    (
      await api(`/api/proposals/${p.id}/remarks`, {
        method: "POST",
        ...jsonBody({ kind: "comment", body: "Nor here." }),
      })
    ).status,
  ).toBe(401);
  expect(
    ((await (await fetch(`${base}/api/proposals/${p.id}/remarks`)).json()) as
      unknown[]).length,
  ).toBe(0);
  // A person writes, over the form, and lands back on the proposal.
  const said = new FormData();
  said.set("kind", "question");
  said.set("body", "Is <script>alert(1)</script> a place?");
  const posted = await api(
    `/proposals/${p.id}/remarks`,
    { method: "POST", body: said, redirect: "manual" },
    bob,
  );
  expect(posted.status).toBe(303);
  expect(posted.headers.get("location")).toBe(`/p/${p.id}`);
  expect(posted.headers.get("set-cookie")).toBeNull();
  const page = await (await fetch(`${base}/p/${p.id}`)).text();
  expect(page).toContain("&lt;script&gt;alert(1)&lt;/script&gt;");
  expect(page).not.toContain("<script>alert(1)");
  expect(page).toContain("Question");
  expect(page).toContain("bob ·");
  // The thread is its own live region, and it comes after the composer: a
  // remark arriving grows the bottom of the page and moves nothing above it,
  // least of all the box someone is typing in.
  expect(page).toContain(
    '<section id="thread" data-live="remark.added remark.removed remark.accepted">',
  );
  const writing = await (await api(`/p/${p.id}`, {}, bob)).text();
  expect(writing).toContain(`action="/proposals/${p.id}/remarks"`);
  expect(writing.indexOf('id="thread"')).toBeGreaterThan(
    writing.indexOf(`action="/proposals/${p.id}/remarks"`),
  );
  // A kind that is not a kind, and a body past two thousand characters.
  for (const bad of [
    { kind: "shout", body: "Hey" },
    { kind: "comment", body: "x".repeat(2001) },
  ]) {
    const refused = await api(
      `/api/proposals/${p.id}/remarks`,
      { method: "POST", ...jsonBody(bad) },
      bob,
    );
    expect(refused.status, JSON.stringify(bad).slice(0, 30)).toBe(422);
  }
  expect(
    (
      await api(
        "/api/proposals/9999/remarks",
        { method: "POST", ...jsonBody({ kind: "comment", body: "Nowhere" }) },
        bob,
      )
    ).status,
  ).toBe(404);
  expect((await fetch(base + "/api/proposals/9999/remarks")).status).toBe(404);
});
test("the author deletes a remark, an admin deletes any, at both doors", async () => {
  const p = await open(alice, { title: "What to delete" });
  const mine = await remark(bob, p.id, {
    kind: "comment",
    body: "Said in haste.",
  });
  expect(
    (await api(`/api/remarks/${mine.id}`, { method: "DELETE" }, alice)).status,
  ).toBe(403);
  expect(
    (await api(`/api/remarks/${mine.id}`, { method: "DELETE" })).status,
  ).toBe(401);
  expect(
    (await api(`/api/remarks/${mine.id}`, { method: "DELETE" }, bob)).status,
  ).toBe(200);
  expect(
    (await api(`/api/remarks/${mine.id}`, { method: "DELETE" }, bob)).status,
  ).toBe(404);
  // And over the form the page draws, which an admin sees on anybody's.
  const theirs = await remark(bob, p.id, {
    kind: "comment",
    body: "Said again.",
  });
  const seen = await (await api(`/p/${p.id}`, {}, root)).text();
  expect(seen).toContain(`action="/remarks/${theirs.id}/delete"`);
  expect(await (await api(`/p/${p.id}`, {}, alice)).text()).not.toContain(
    `action="/remarks/${theirs.id}/delete"`,
  );
  const form = new FormData();
  form.set("proposal", String(p.id));
  const gone = await api(
    `/remarks/${theirs.id}/delete`,
    { method: "POST", body: form, redirect: "manual" },
    root,
  );
  expect(gone.headers.get("location")).toBe(`/p/${p.id}`);
  expect(gone.headers.get("set-cookie")).toBeNull();
  expect(await (await fetch(`${base}/p/${p.id}`)).text()).not.toContain(
    "Said again.",
  );
});
test("accepting a counter adds one option and says the ballots stand", async () => {
  const p = await open(alice, { title: "Where to meet in winter" });
  const counter = await remark(bob, p.id, {
    kind: "counter",
    body: "Neither room is warm.",
    optionLabel: "The library",
  });
  expect(counter.kind).toBe("counter");
  // Only the proposal's author or an admin is offered the button.
  const asBob = await (await api(`/p/${p.id}`, {}, bob)).text();
  expect(asBob).not.toContain(`action="/remarks/${counter.id}/accept"`);
  expect(asBob).toContain("Instead: <b>The library</b>");
  const asAlice = await (await api(`/p/${p.id}`, {}, alice)).text();
  expect(asAlice).toContain(`action="/remarks/${counter.id}/accept"`);
  expect(
    (await api(`/api/remarks/${counter.id}/accept`, { method: "POST" }, bob))
      .status,
  ).toBe(403);
  const form = new FormData();
  form.set("proposal", String(p.id));
  const taken = await api(
    `/remarks/${counter.id}/accept`,
    { method: "POST", body: form, redirect: "manual" },
    alice,
  );
  expect(taken.headers.get("location")).toBe(`/p/${p.id}`);
  expect(taken.headers.get("set-cookie")).toBeNull();
  const page = await (await fetch(`${base}/p/${p.id}`)).text();
  expect(page).toContain("<li>The library</li>");
  expect(page).toContain("earlier ballots stand");
  expect(page).not.toContain(`action="/remarks/${counter.id}/accept"`);
  const one = (await (await fetch(`${base}/api/proposals/${p.id}`)).json()) as {
    options: { label: string }[];
  };
  expect(one.options.map((o) => o.label)).toEqual([
    "The kitchen",
    "The garden",
    "The library",
  ]);
  // Twice is not twice: the second press changes nothing.
  expect(
    (await api(`/api/remarks/${counter.id}/accept`, { method: "POST" }, alice))
      .status,
  ).toBe(422);
  expect(
    (
      (await (await fetch(`${base}/api/proposals/${p.id}`)).json()) as {
        options: unknown[];
      }
    ).options.length,
  ).toBe(3);
});
test("the thread is on the event stream and the MCP tools speak it too", async () => {
  const talker = as("u7", "talker");
  const p = await open(talker, { title: "Something to discuss" });
  const stream = await fetch(base + "/events");
  const reader = stream.body!.getReader();
  const seen = async (type: string): Promise<void> => {
    let buffer = "";
    for (;;) {
      const { value } = await reader.read();
      buffer += new TextDecoder().decode(value);
      if (buffer.includes(type)) return;
    }
  };
  const call = (name: string, args: unknown, who = {}) =>
    rpc(
      {
        jsonrpc: "2.0",
        id: 7,
        method: "tools/call",
        params: { name, arguments: args },
      },
      who,
    );
  const added = await call(
    "add_remark",
    { proposal_id: p.id, kind: "comment", body: "Through MCP." },
    talker,
  );
  expect(added.result.isError).toBeUndefined();
  await seen("remark.added");
  const listed = JSON.parse(
    (await call("list_remarks", { proposal_id: p.id })).result.content[0].text,
  ) as { body: string }[];
  expect(listed.map((r) => r.body)).toEqual(["Through MCP."]);
  // A bare caller reads and cannot write.
  expect(
    (await call("add_remark", { proposal_id: p.id, kind: "comment", body: "No" }))
      .result.isError,
  ).toBe(true);
  const made = JSON.parse(added.result.content[0].text) as { id: number };
  await api(`/api/remarks/${made.id}`, { method: "DELETE" }, talker);
  await seen("remark.removed");
  await reader.cancel();
});
test("/api/health answers a probe, and only an admin sees the environment", async () => {
  const PUBLIC = ["commit", "env", "ok", "schemaVersion", "uptimeSeconds"];
  for (const who of [{}, alice]) {
@@ -2,21 +2,32 @@
 * The app in a terminal. The forge runs this on a pty when someone
 * `ssh`es to the app, over the same data as the page and through the same
 * actions, as the account at the keyboard. j/k move, Enter opens the
 * proposal under the cursor, n proposes, w withdraws, Esc goes back and q
 * leaves. Plain ANSI, no dependencies.
 * proposal under the cursor — with the argument on it underneath — n
 * proposes, c says something, w withdraws, Esc goes back and q leaves.
 * Plain ANSI, no dependencies.
 *
 * Nothing anyone wrote reaches this screen as a control character: what
 * someone else typed goes through `plain.ts` on the way out, so the only
 * escape sequences a terminal here sees are the ones in this file.
 */
import {
  addRemark,
  canWithdraw,
  getProposal,
  listProposals,
  listRemarks,
  propose,
  withdrawProposal,
  KINDS,
  OPTIONS_MAX,
  type FullProposal,
  type Kind,
  type ProposalSummary,
  type Remark,
} from "./actions.ts";
import { openDb } from "./db.ts";
import { oneLine, plain } from "./plain.ts";
import { ssh, title, where } from "./env.ts";
import { describeRule, RULE_FORMS } from "./quorum.ts";
import { whoAtTty } from "./who.ts";
@@ -40,9 +51,19 @@
interface Draft {
  typing: string;
}
/** A remark being written on the proposal that is open. */
interface RemarkDraft {
  step: "kind" | "body" | "label";
  proposalId: number;
  kind: Kind;
  body: string;
  typing: string;
}
let cursor = 0;
let open: number | undefined;
let draft: Draft | undefined;
let remarkDraft: RemarkDraft | undefined;
let said = "";
const proposals = (): ProposalSummary[] => {
@@ -55,23 +76,30 @@
const one = (id: number): FullProposal | undefined => {
  return found.ok ? found.value : undefined;
};
/** Long text, broken at spaces so a narrow terminal still reads. */
/**
 * Long text, broken at spaces so a narrow terminal still reads — and
 * stripped of the control characters that would otherwise let what someone
 * wrote drive the cursor (`plain.ts`). Every line of somebody else's text
 * printed here comes through this.
 */
const wrap = (text: string, width = 72): string[] =>
  text.split(/\r?\n/).flatMap((paragraph) => {
    const lines: string[] = [];
    let line = "";
    for (const word of paragraph.split(/\s+/)) {
      if (word === "") continue;
      if (line === "") line = word;
      else if (line.length + 1 + word.length <= width) line += ` ${word}`;
      else {
        lines.push(line);
        line = word;
  plain(text)
    .split(/\r?\n/)
    .flatMap((paragraph) => {
      const lines: string[] = [];
      let line = "";
      for (const word of paragraph.split(/\s+/)) {
        if (word === "") continue;
        if (line === "") line = word;
        else if (line.length + 1 + word.length <= width) line += ` ${word}`;
        else {
          lines.push(line);
          line = word;
        }
      }
    }
    lines.push(line);
    return lines;
  });
      lines.push(line);
      return lines;
    });
function draw(): void {
  const lines = [
@@ -80,6 +108,7 @@
function draw(): void {
    "",
  ];
  if (draft !== undefined) lines.push(...composer(draft));
  else if (remarkDraft !== undefined) lines.push(...remarkComposer(remarkDraft));
  else if (open !== undefined) lines.push(...detail(open));
  else lines.push(...list());
  lines.push("");
@@ -98,8 +127,9 @@
const list = (): string[] => {
      ),
    ];
  return rows.map((p, i) => {
    const line = `${p.title}  ${dim(`${p.author_name} · ${p.option_count} options · ${p.created_at.slice(0, 16).replace("T", " ")}`)}`;
    return `${i === cursor ? "▸" : " "} ${i === cursor ? bold(p.title) + line.slice(p.title.length) : line}`;
    const title = oneLine(p.title);
    const line = `${title}  ${dim(`${oneLine(p.author_name)} · ${p.option_count} options · ${p.created_at.slice(0, 16).replace("T", " ")}`)}`;
    return `${i === cursor ? "▸" : " "} ${i === cursor ? bold(title) + line.slice(title.length) : line}`;
  });
};
@@ -107,23 +137,59 @@
const detail = (id: number): string[] => {
  const proposal = one(id);
  if (proposal === undefined) return [dim("That proposal is gone.")];
  return [
    bold(proposal.title),
    bold(oneLine(proposal.title)),
    dim(
      `${proposal.author_name} · ${proposal.state} · ${proposal.created_at.slice(0, 16).replace("T", " ")}`,
      `${oneLine(proposal.author_name)} · ${proposal.state} · ${proposal.created_at.slice(0, 16).replace("T", " ")}`,
    ),
    "",
    ...wrap(proposal.body),
    "",
    dim(
      proposal.rule_parsed === undefined
        ? `A rule this app cannot read: ${proposal.rule}`
        ? `A rule this app cannot read: ${oneLine(proposal.rule)}`
        : describeRule(proposal.rule_parsed),
    ),
    "",
    ...proposal.options.map((o) => `  ${o.position + 1}. ${o.label}`),
    ...proposal.options.map((o) => `  ${o.position + 1}. ${oneLine(o.label)}`),
    "",
    ...thread(id),
  ];
};
/** The argument under the proposal, oldest first, as anyone reads it. */
const thread = (id: number): string[] => {
  const said = listRemarks(db, me, { proposalId: id });
  const remarks = said.ok ? said.value : [];
  if (remarks.length === 0)
    return [
      dim(
        me.role === "anon"
          ? "Nothing said yet."
          : "Nothing said yet. Press c to say something.",
      ),
    ];
  return [
    dim(`${remarks.length} remark${remarks.length === 1 ? "" : "s"}:`),
    ...remarks.flatMap(line),
  ];
};
/** One remark: who said what kind of thing, the text, and what it wants. */
const line = (remark: Remark): string[] => [
  "",
  dim(
    `  [${remark.kind}] ${oneLine(remark.author_name)} · ${remark.created_at.slice(0, 16).replace("T", " ")}`,
  ),
  ...wrap(remark.body, 68).map((l) => `  ${l}`),
  ...(remark.option_label === null
    ? []
    : [
        `  ${dim("instead:")} ${oneLine(remark.option_label)}${
          remark.accepted_at === null ? "" : dim(" (accepted)")
        }`,
      ]),
];
const composer = (d: Draft): string[] => {
  const cell = `${esc}7m ${esc}0m`;
  const lines = [bold("A new proposal"), ""];
@@ -156,9 +222,45 @@
const composer = (d: Draft): string[] => {
  return lines;
};
/**
 * A remark being typed: the kind first — one key, so nobody types the word
 * — then the text, then the option a counter wants instead.
 */
const remarkComposer = (d: RemarkDraft): string[] => {
  const cell = `${esc}7m ${esc}0m`;
  const lines = [bold("Saying something"), ""];
  if (d.step === "kind") {
    lines.push(dim("What kind of thing is it?"));
    KINDS.forEach((kind, i) =>
      lines.push(`  ${i + 1}. ${kind}${kind === d.kind ? dim("  ←") : ""}`),
    );
    lines.push("");
    lines.push(dim("1, 2 or 3 — or Enter for a comment."));
    return lines;
  }
  lines.push(dim(`Kind: ${d.kind}`));
  lines.push(
    d.step === "body"
      ? `Remark: ${d.typing}${cell}`
      : dim(`Remark: ${plain(d.body)}`),
  );
  if (d.step === "label") {
    lines.push("");
    lines.push(
      dim("The option you want instead. Enter alone to name none."),
    );
    lines.push(`Instead: ${d.typing}${cell}`);
  }
  return lines;
};
const keys = (): string => {
  if (draft !== undefined) return "Enter accepts · Esc cancels";
  if (open !== undefined) return "Esc back · w withdraw · q quit";
  if (remarkDraft !== undefined) return "Enter accepts · Esc cancels";
  if (open !== undefined)
    return me.role === "anon"
      ? "Esc back · q quit · sign in through the forge to say something"
      : "Esc back · c say something · w withdraw · q quit";
  return me.role === "anon"
    ? "j/k move · Enter open · q quit · sign in through the forge to propose"
    : "j/k move · Enter open · n propose · w withdraw · q quit";
@@ -186,6 +288,27 @@
function submit(d: Draft): void {
  }
}
/** The remark, finished: the same action the page and the API call. */
function say(d: RemarkDraft, optionLabel: string): void {
  const made = addRemark(db, me, {
    proposalId: d.proposalId,
    kind: d.kind,
    body: d.body,
    optionLabel,
  });
  if (made.ok) {
    said = `Said, as a ${made.value.kind}.`;
    remarkDraft = undefined;
    open = d.proposalId;
  } else {
    // Keep what was typed: the message says what to change.
    said = made.message;
    d.step = "body";
    d.typing = d.body;
    d.body = "";
  }
}
function withdraw(id: number | undefined): void {
  if (id === undefined) {
    said = "Nothing to withdraw.";
@@ -244,6 +367,35 @@
process.stdin.on("data", (key: string) => {
    draw();
    return;
  }
  if (remarkDraft !== undefined) {
    const d = remarkDraft;
    if (key === "\x1b") {
      remarkDraft = undefined;
      said = "Cancelled.";
    } else if (key === "\x03") {
      remarkDraft = undefined;
    } else if (d.step === "kind") {
      // One key for the kind: the list is numbered on the screen above.
      const picked = KINDS[Number(key) - 1];
      if (key === "\r" || picked !== undefined) {
        if (picked !== undefined) d.kind = picked;
        d.step = "body";
        d.typing = "";
      }
    } else if (key === "\r") {
      if (d.step === "body") {
        d.body = d.typing.trim();
        // Only a counter names an option; anything else is said and done.
        if (d.kind === "counter") {
          d.step = "label";
          d.typing = "";
        } else say(d, "");
      } else say(d, d.typing.trim());
    } else if (key === "\x7f") d.typing = d.typing.slice(0, -1);
    else if (key >= " ") d.typing += key;
    draw();
    return;
  }
  if (key === "q" || key === "\x03") {
    out(`${esc}2J${esc}H`);
    process.exit(0);
@@ -273,6 +425,19 @@
process.stdin.on("data", (key: string) => {
        typing: "",
      };
  }
  if (key === "c") {
    if (me.role === "anon")
      said = "Sign in through the forge to say something.";
    else if (under === undefined) said = "Nothing to say it about.";
    else
      remarkDraft = {
        step: "kind",
        proposalId: under,
        kind: "comment",
        body: "",
        typing: "",
      };
  }
  if (key === "w") withdraw(under);
  draw();
});
@@ -218,6 +218,52 @@
code,
  font-weight: 650;
  color: var(--accent);
}
/* The argument. The thread is the last thing on the page and grows at the
   bottom, so a remark arriving over /events moves nothing above it. */
.thread {
  display: grid;
  gap: var(--s3);
  margin: var(--s3) 0 0;
  padding: 0;
}
.remark {
  background: var(--surface);
  border: 1px solid var(--line);
  border-left: 3px solid var(--line);
  border-radius: var(--radius);
  padding: var(--s3);
}
.remark[data-kind="question"] {
  border-left-color: var(--accent);
}
.remark[data-kind="counter"] {
  border-left-color: var(--danger);
}
.remark .body {
  margin: var(--s2) 0 0;
}
.remark .row:empty {
  display: none;
}
.pill[data-kind="question"] {
  color: var(--accent);
  border-color: currentColor;
}
.pill[data-kind="counter"] {
  color: var(--danger);
  border-color: currentColor;
}
.wanted {
  margin-top: var(--s2);
  overflow-wrap: anywhere;
}
/* The option a counter wants matters only to a counter. Shown plainly
   wherever :has is not understood, so the field is never unreachable. */
.remark-form:has(select[name="kind"] option:checked:not([value="counter"]))
  .counter-field {
  display: none;
}
/* Nothing to show yet: the same card, drawn as an outline, saying what this
   app is rather than that it is empty. */
.empty {
		@@ -23,8 +23,9 @@ decide nothing themselves. `AGENTS.md` says how to add to it.
23	23
24	24	\| file \| what it is \|
25	25	\| ---------------------------------- \| ------------------------------------------------------------ \|
26		\| `src/actions.ts` \| propose, list, read, withdraw, health — and who may \|
	26	\| `src/actions.ts` \| propose, list, read, withdraw, remark, health — and who may \|
27	27	\| `src/quorum.ts` \| the three rules as plain data: read one, say it, count it \|
	28	\| `src/plain.ts` \| somebody else's text, safe to print on a terminal \|
28	29	\| `src/who.ts` \| who is asking, from the forge's signed headers \|
29	30	\| `src/db.ts` \| SQLite under `FORGE_APP_DATA`, WAL, forward-only migrations \|
30	31	\| `src/live.ts` \| the event log, the bus, and `GET /events` \|
		@@ -44,8 +45,11 @@ verifies the signature (`src/who.ts`); nothing else is trusted. Three tiers:
44	45
45	46	- anon — anyone. Reads.
46	47	- user — signed in to the forge and able to see this app. Makes
47		proposals, as themselves, and withdraws their own.
48		- admin — able to write this repository. Withdraws any proposal.
	48	proposals, as themselves, withdraws their own, says things on anybody's
	49	and deletes what they said; on a proposal they opened, they can accept a
	50	counter.
	51	- admin — able to write this repository. Withdraws any proposal, deletes
	52	any remark, accepts a counter on any proposal.
49	53
50	54	"Sign in" is `/__forge/signin?to=<path>` and "Sign out" is
51	55	`/__forge/signout`; the forge answers both on the app's own host.
		@@ -64,6 +68,14 @@ names and count a `named:` rule needs; `/p/<id>` says the rule in words above
64	68	the options. A guest sees both pages and no forms. With nothing proposed yet,
65	69	`/` says in four sentences what a proposal is rather than that it is empty.
66	70
	71	Under the proposal is the argument about it: a composer for whoever is signed
	72	in, and then the thread, oldest first, each remark labelled with its kind. The
	73	thread is the last thing on the page and grows at the bottom, so a remark
	74	arriving live moves nothing above it — least of all the box somebody is typing
	75	in. An author sees a Delete on their own remark and an admin on every one; the
	76	proposal's author and an admin see Accept on a counter that names an option
	77	the proposal does not have yet.
	78
67	79	`/about`, linked from the footer of every page, is the longer version: how a
68	80	proposal is decided, the three rules printed from `src/quorum.ts`, two plain
69	81	lists of what is built and what is not (voting, deliberation, a roster and
		@@ -79,6 +91,11 @@ curl https://<app>/api/proposals/1 # one, with its options in order
79	91	curl -X POST https://<app>/api/proposals -H 'content-type: application/json' \
80	92	-d '{"title":"Adopt the four-day week","body":"A trial for one quarter.","options":["Yes","No"],"rule":"named:alice,bob,carol:2"}'
81	93	curl -X POST https://<app>/api/proposals/1/withdraw
	94	curl https://<app>/api/proposals/1/remarks # the thread, oldest first
	95	curl -X POST https://<app>/api/proposals/1/remarks -H 'content-type: application/json' \
	96	-d '{"kind":"counter","body":"Neither room is warm in winter.","optionLabel":"The library"}'
	97	curl -X POST https://<app>/api/remarks/1/accept # the proposal's author, or an admin
	98	curl -X DELETE https://<app>/api/remarks/1 # its author, or an admin
82	99	curl https://<app>/api/health # 200 while sound, 503 when it is not
83	100	```
84	101
		@@ -111,9 +128,34 @@ named:alice,bob,carol:2 2 of those three agree; nobody else counts
111	128	Anything else is refused with a sentence naming the three forms, and no rule
112	129	at all means `majority`. A proposal keeps the rule it was opened with.
113	130
	131	## Deliberation
	132
	133	The argument happens on the proposal and stays part of the record. A remark
	134	is 1 to 2000 characters by a signed-in person, and it is one of three kinds:
	135
	136	- comment — something to say about the proposal: an opinion, a fact, a
	137	caveat, anything that is not a question or a demand for another option.
	138	- question — something to ask its author, asked in the open so the
	139	answer is in the open too.
	140	- counter — an argument for another option, which may name the option it
	141	wants in `optionLabel` (1–80 characters).
	142
	143	A remark's author or an admin deletes it. The proposal's author or an admin
	144	can accept a counter that names an option, while the proposal is open:
	145	the label is appended to the proposal as one more option and the counter is
	146	stamped as accepted. Nothing else about the proposal moves, so every ballot
	147	already cast still means what it meant — the page says so where the accepted
	148	counter is. Accepting twice, accepting a counter that names nothing, naming
	149	an option the proposal already has, and accepting on a proposal that is
	150	withdrawn or decided are each refused.
	151
	152	A withdrawn or decided proposal still takes remarks: the record continues
	153	after the decision, and an argument about what was decided belongs where the
	154	decision is.
	155
114	156	As an MCP server, for Claude Code or Claude Desktop — `list_proposals`,
115		`get_proposal`, `propose`, `withdraw_proposal`, `health` (the same action
116		behind `/api/health`, gated the same way):
	157	`get_proposal`, `propose`, `withdraw_proposal`, `list_remarks`, `add_remark`,
	158	`health` (the same action behind `/api/health`, gated the same way):
117	159
118	160	```sh
119	161	claude mcp add --transport http __TITLE__ https://<app>/mcp
		@@ -126,7 +168,8 @@ claude mcp add --transport http __TITLE__ https://<app>/mcp
126	168	```
127	169
128	170	The page stays current over `/events`: a proposal someone else opens or
129		withdraws appears without a reload — including one written at the terminal,
	171	withdraws, and a remark someone else writes, deletes or has accepted, appears
	172	without a reload — including one written at the terminal,
130	173	which is another process on the same file. Every event is a row in `event`,
131	174	so the server follows what it did not write itself while anyone is
132	175	watching, and a browser that reconnects with `Last-Event-ID` is replayed
		@@ -138,11 +181,14 @@ The terminal opens with the exact command in `FORGE_APP_SSH` when the app
138	181	runs (`ssh -p 2222 <name>@<forge>` — the app is the login name, the forge
139	182	the host; `<name>--<pull>@<forge>` for a preview's). It is `src/tty.ts` on
140	183	a real pty over the same data, as the account at the keyboard: `j`/`k`
141		moves, Enter opens the proposal under the cursor, `n` proposes (a title,
142		then the paragraph, then options one per line until a blank line, then the
143		rule — Enter alone for `majority`), `w` withdraws, Esc goes back and `q`
144		quits. A guest is told to sign in rather
145		than shown a composer.
	184	moves, Enter opens the proposal under the cursor — with the thread on it
	185	underneath — `n` proposes (a title, then the paragraph, then options one per
	186	line until a blank line, then the rule — Enter alone for `majority`), `c`
	187	says something (`1`, `2` or `3` for the kind, then the text, then the option
	188	a counter wants), `w` withdraws, Esc goes back and `q` quits. A guest is told
	189	to sign in rather than shown a composer. Nothing anyone else wrote reaches
	190	that screen as a control character: it goes through `src/plain.ts` on the way
	191	out, so the only escape sequences a terminal here sees are the app's own.
146	192
147	193	The forge sets `PORT`, `FORGE_APP_DATA`, `FORGE_APP_ENV` (`production` or
148	194	`preview`), `FORGE_APP_URL`, `FORGE_APP_COMMIT`, `FORGE_APP_SSH` and
		@@ -3,10 +3,15 @@ import { mkdtempSync } from "node:fs";
3	3	import { tmpdir } from "node:os";
4	4	import { join } from "node:path";
5	5	import {
	6	acceptCounter,
	7	addRemark,
	8	canDeleteRemark,
6	9	canWithdraw,
	10	deleteRemark,
7	11	getProposal,
8	12	health,
9	13	listProposals,
	14	listRemarks,
10	15	propose,
11	16	withdrawProposal,
12	17	type AdminHealth,
		@@ -247,6 +252,286 @@ test("a state that is not a state is refused, and a limit is bounded", () => {
247	252	expect(capped.ok && capped.value.length).toBe(1);
248	253	});
249	254
	255	/** A remark, or the reason it was refused, so a test reads as one line. */
	256	const say = (
	257	who: Who,
	258	proposalId: number,
	259	input: Record<string, unknown> = {},
	260	) =>
	261	addRemark(db, who, {
	262	proposalId,
	263	kind: "comment",
	264	body: "Sounds right to me.",
	265	...input,
	266	} as { proposalId: number; kind: string; body: string });
	267
	268	test("anyone reads the thread; only a signed-in person writes in it", () => {
	269	const p = made(alice);
	270	expect(listRemarks(db, anon, { proposalId: p.id })).toEqual({
	271	ok: true,
	272	value: [],
	273	});
	274
	275	const refused = say(anon, p.id);
	276	expect(refused.ok).toBe(false);
	277	if (!refused.ok) expect(refused.error).toBe("signin_required");
	278
	279	const first = say(bob, p.id, { body: " The kitchen has no chairs. " });
	280	expect(first.ok && first.value.body).toBe("The kitchen has no chairs.");
	281	expect(first.ok && first.value.kind).toBe("comment");
	282	expect(first.ok && first.value.author_name).toBe("bob");
	283	expect(first.ok && first.value.option_label).toBeNull();
	284	expect(first.ok && first.value.accepted_at).toBeNull();
	285	const second = say(alice, p.id, {
	286	kind: "question",
	287	body: "Whose chairs are they?",
	288	});
	289	expect(second.ok).toBe(true);
	290
	291	// Oldest first, and a guest reads all of it.
	292	const thread = listRemarks(db, anon, { proposalId: p.id });
	293	expect(thread.ok && thread.value.map((r) => r.kind)).toEqual([
	294	"comment",
	295	"question",
	296	]);
	297	expect(thread.ok && thread.value.map((r) => r.body)).toEqual([
	298	"The kitchen has no chairs.",
	299	"Whose chairs are they?",
	300	]);
	301
	302	// The thread belongs to its proposal and to no other.
	303	const other = made(alice);
	304	expect(listRemarks(db, anon, { proposalId: other.id })).toEqual({
	305	ok: true,
	306	value: [],
	307	});
	308	const nowhere = listRemarks(db, anon, { proposalId: 9999 });
	309	expect(nowhere.ok).toBe(false);
	310	if (!nowhere.ok) expect(nowhere.error).toBe("not_found");
	311	});
	312
	313	test("a remark is one of three kinds, 1 to 2000 characters, on a proposal that is there", () => {
	314	const p = made(alice);
	315	for (const input of [
	316	{ kind: "shout" },
	317	{ kind: "" },
	318	{ kind: "COMMENT" },
	319	{ body: "" },
	320	{ body: " " },
	321	{ body: "x".repeat(2001) },
	322	// Only a counter names an option, and a label has a length like any other.
	323	{ kind: "comment", optionLabel: "Neither" },
	324	{ kind: "counter", optionLabel: "x".repeat(81) },
	325	]) {
	326	const r = say(bob, p.id, input);
	327	expect(r.ok, JSON.stringify(input).slice(0, 40)).toBe(false);
	328	if (!r.ok) {
	329	expect(r.error).toBe("invalid");
	330	expect(r.message.length).toBeGreaterThan(10);
	331	}
	332	}
	333	expect(say(bob, p.id, { body: "x".repeat(2000) }).ok).toBe(true);
	334	const nowhere = say(bob, 9999);
	335	expect(nowhere.ok).toBe(false);
	336	if (!nowhere.ok) expect(nowhere.error).toBe("not_found");
	337	const odd = say(bob, 1.5);
	338	expect(odd.ok).toBe(false);
	339	if (!odd.ok) expect(odd.error).toBe("invalid");
	340	});
	341
	342	test("the record continues after the decision: a withdrawn proposal still takes remarks", () => {
	343	const p = made(alice);
	344	expect(withdrawProposal(db, alice, { id: p.id }).ok).toBe(true);
	345	const after = say(bob, p.id, {
	346	kind: "question",
	347	body: "Why was this dropped?",
	348	});
	349	expect(after.ok).toBe(true);
	350	expect(listRemarks(db, anon, { proposalId: p.id }).ok).toBe(true);
	351	});
	352
	353	test("the author deletes their own remark, an admin deletes any", () => {
	354	const p = made(alice);
	355	const bobs = say(bob, p.id);
	356	if (!bobs.ok) throw new Error(bobs.message);
	357	expect(canDeleteRemark(bob, bobs.value)).toBe(true);
	358	expect(canDeleteRemark(alice, bobs.value)).toBe(false);
	359	expect(canDeleteRemark(root, bobs.value)).toBe(true);
	360	expect(canDeleteRemark(anon, bobs.value)).toBe(false);
	361
	362	// The proposal's author is not the remark's author.
	363	const byAlice = deleteRemark(db, alice, { id: bobs.value.id });
	364	expect(byAlice.ok).toBe(false);
	365	if (!byAlice.ok) expect(byAlice.error).toBe("forbidden");
	366	const byAnon = deleteRemark(db, anon, { id: bobs.value.id });
	367	expect(byAnon.ok).toBe(false);
	368	if (!byAnon.ok) expect(byAnon.error).toBe("signin_required");
	369
	370	expect(deleteRemark(db, bob, { id: bobs.value.id }).ok).toBe(true);
	371	const again = deleteRemark(db, bob, { id: bobs.value.id });
	372	expect(again.ok).toBe(false);
	373	if (!again.ok) expect(again.error).toBe("not_found");
	374
	375	const mine = say(alice, p.id);
	376	if (!mine.ok) throw new Error(mine.message);
	377	expect(deleteRemark(db, root, { id: mine.value.id }).ok).toBe(true);
	378	expect(listRemarks(db, anon, { proposalId: p.id })).toEqual({
	379	ok: true,
	380	value: [],
	381	});
	382	});
	383
	384	test("an accepted counter adds exactly one option, once, and leaves the rest alone", () => {
	385	const p = made(alice);
	386	const counter = say(bob, p.id, {
	387	kind: "counter",
	388	body: "Neither room works in winter.",
	389	optionLabel: "The library",
	390	});
	391	if (!counter.ok) throw new Error(counter.message);
	392	expect(counter.value.option_label).toBe("The library");
	393	expect(counter.value.accepted_at).toBeNull();
	394
	395	// Whoever wrote the counter does not get to take it themselves.
	396	const byBob = acceptCounter(db, bob, { id: counter.value.id });
	397	expect(byBob.ok).toBe(false);
	398	if (!byBob.ok) expect(byBob.error).toBe("forbidden");
	399	const byAnon = acceptCounter(db, anon, { id: counter.value.id });
	400	expect(byAnon.ok).toBe(false);
	401	if (!byAnon.ok) expect(byAnon.error).toBe("signin_required");
	402
	403	const taken = acceptCounter(db, alice, { id: counter.value.id });
	404	expect(taken.ok && taken.value.option.label).toBe("The library");
	405	expect(taken.ok && taken.value.remark.accepted_at).not.toBeNull();
	406	const after = getProposal(db, anon, { id: p.id });
	407	expect(after.ok && after.value.options.map((o) => o.label)).toEqual([
	408	"The kitchen",
	409	"The garden",
	410	"The library",
	411	]);
	412	expect(after.ok && after.value.options.map((o) => o.position)).toEqual([
	413	0, 1, 2,
	414	]);
	415	// Nothing else about the proposal moved: the ballots people cast stand.
	416	expect(after.ok && after.value.state).toBe("open");
	417	expect(after.ok && after.value.decided_option_id).toBeNull();
	418
	419	const twice = acceptCounter(db, alice, { id: counter.value.id });
	420	expect(twice.ok).toBe(false);
	421	if (!twice.ok) expect(twice.error).toBe("invalid");
	422	expect(
	423	getProposal(db, anon, { id: p.id }).ok &&
	424	(getProposal(db, anon, { id: p.id }) as { value: { options: unknown[] } })
	425	.value.options.length,
	426	).toBe(3);
	427
	428	// A label already on the proposal is not a second option.
	429	const same = say(bob, p.id, {
	430	kind: "counter",
	431	body: "The library again.",
	432	optionLabel: "the LIBRARY",
	433	});
	434	if (!same.ok) throw new Error(same.message);
	435	const clash = acceptCounter(db, alice, { id: same.value.id });
	436	expect(clash.ok).toBe(false);
	437	if (!clash.ok) expect(clash.error).toBe("invalid");
	438
	439	// A counter with nothing to add, and a remark that is not a counter.
	440	const wordy = say(bob, p.id, { kind: "counter", body: "Not this way." });
	441	if (!wordy.ok) throw new Error(wordy.message);
	442	const nothing = acceptCounter(db, alice, { id: wordy.value.id });
	443	expect(nothing.ok).toBe(false);
	444	if (!nothing.ok) expect(nothing.error).toBe("invalid");
	445	const plain = say(bob, p.id);
	446	if (!plain.ok) throw new Error(plain.message);
	447	const notCounter = acceptCounter(db, alice, { id: plain.value.id });
	448	expect(notCounter.ok).toBe(false);
	449	if (!notCounter.ok) expect(notCounter.error).toBe("invalid");
	450
	451	const nowhere = acceptCounter(db, alice, { id: 9999 });
	452	expect(nowhere.ok).toBe(false);
	453	if (!nowhere.ok) expect(nowhere.error).toBe("not_found");
	454	});
	455
	456	test("a counter on a proposal that is no longer open cannot be accepted", () => {
	457	const p = made(alice);
	458	const counter = say(bob, p.id, {
	459	kind: "counter",
	460	body: "Ask again in March.",
	461	optionLabel: "Wait until March",
	462	});
	463	if (!counter.ok) throw new Error(counter.message);
	464	expect(withdrawProposal(db, alice, { id: p.id }).ok).toBe(true);
	465
	466	const late = acceptCounter(db, alice, { id: counter.value.id });
	467	expect(late.ok).toBe(false);
	468	if (!late.ok) {
	469	expect(late.error).toBe("invalid");
	470	expect(late.message).toContain("withdrawn");
	471	}
	472	// An admin is not a way around a proposal that has stopped taking options.
	473	expect(acceptCounter(db, root, { id: counter.value.id }).ok).toBe(false);
	474
	475	// Nor is a decided one. Nothing votes yet, so the state is set by hand —
	476	// the rule is the proposal's state and not how it got there.
	477	const chosen = made(alice);
	478	const late2 = say(bob, chosen.id, {
	479	kind: "counter",
	480	body: "Too late, but still.",
	481	optionLabel: "Somewhere else",
	482	});
	483	if (!late2.ok) throw new Error(late2.message);
	484	db.query("UPDATE proposal SET state = 'decided' WHERE id = ?1").run(
	485	chosen.id,
	486	);
	487	const decided = acceptCounter(db, alice, { id: late2.value.id });
	488	expect(decided.ok).toBe(false);
	489	if (!decided.ok) {
	490	expect(decided.error).toBe("invalid");
	491	expect(decided.message).toContain("decided");
	492	}
	493	const still = getProposal(db, anon, { id: chosen.id });
	494	expect(still.ok && still.value.options.length).toBe(2);
	495	// And the thread on a decided proposal still takes remarks.
	496	expect(say(bob, chosen.id, { body: "Glad that is settled." }).ok).toBe(true);
	497	const after = getProposal(db, anon, { id: p.id });
	498	expect(after.ok && after.value.options.length).toBe(2);
	499	expect(
	500	listRemarks(db, anon, { proposalId: p.id }).ok &&
	501	counter.value.accepted_at,
	502	).toBeNull();
	503	});
	504
	505	test("a proposal full of options takes no more from a counter", () => {
	506	const p = made(alice, {
	507	options: Array.from({ length: 8 }, (_, i) => `Option ${i}`),
	508	});
	509	const counter = say(bob, p.id, {
	510	kind: "counter",
	511	body: "One more.",
	512	optionLabel: "Option 9",
	513	});
	514	if (!counter.ok) throw new Error(counter.message);
	515	const full = acceptCounter(db, alice, { id: counter.value.id });
	516	expect(full.ok).toBe(false);
	517	if (!full.ok) expect(full.error).toBe("invalid");
	518	expect(getProposal(db, anon, { id: p.id }).ok).toBe(true);
	519	});
	520
	521	test("a remark goes when its proposal does", () => {
	522	const p = made(alice);
	523	expect(say(bob, p.id).ok).toBe(true);
	524	db.query("DELETE FROM proposal WHERE id = ?1").run(p.id);
	525	expect(
	526	db
	527	.query<
	528	{ n: number },
	529	[number]
	530	>("SELECT count(*) AS n FROM remark WHERE proposal_id = ?1")
	531	.get(p.id)!.n,
	532	).toBe(0);
	533	});
	534
250	535	const PUBLIC_HEALTH = ["commit", "env", "ok", "schemaVersion", "uptimeSeconds"];
251	536
252	537	test("health tells anyone how the app is and nobody else where it lives", () => {
		@@ -70,6 +70,27 @@ export interface FullProposal extends Proposal {
70	70	readonly options: readonly Option[];
71	71	}
72	72
	73	/**
	74	* What someone can say about a proposal. A `comment` is a remark on it, a
	75	* `question` asks its author something, and a `counter` argues for another
	76	* option — naming it in `option_label` when it has one to name.
	77	*/
	78	export type Kind = "comment" \| "question" \| "counter";
	79	export const KINDS: readonly Kind[] = ["comment", "question", "counter"];
	80
	81	export interface Remark {
	82	readonly id: number;
	83	readonly proposal_id: number;
	84	readonly kind: Kind;
	85	readonly body: string;
	86	readonly option_label: string \| null;
	87	/** When a counter's label was appended to the proposal, or null. */
	88	readonly accepted_at: string \| null;
	89	readonly author_id: string;
	90	readonly author_name: string;
	91	readonly created_at: string;
	92	}
	93
73	94	export type Failure = "signin_required" \| "forbidden" \| "not_found" \| "invalid";
74	95	export type Result<T> =
75	96	\| { ok: true; value: T }
		@@ -240,6 +261,187 @@ export function withdrawProposal(
240	261	return ok(withdrawn);
241	262	}
242	263
	264	/**
	265	* The argument on a proposal, oldest first. Anyone reads it, including a
	266	* guest: what was said about a decision is part of the decision.
	267	*/
	268	export function listRemarks(
	269	db: Database,
	270	_who: Who,
	271	input: { proposalId: number },
	272	): Result<Remark[]> {
	273	if (!Number.isInteger(input.proposalId))
	274	return fail("invalid", "A proposal id is a whole number.");
	275	if (!exists(db, input.proposalId))
	276	return fail("not_found", "No such proposal.");
	277	return ok(
	278	db
	279	.query<
	280	Remark,
	281	[number]
	282	>("SELECT * FROM remark WHERE proposal_id = ?1 ORDER BY id")
	283	.all(input.proposalId),
	284	);
	285	}
	286
	287	/**
	288	* Say something about a proposal. A withdrawn or decided one still takes
	289	* remarks: the record continues after the decision, and an argument about
	290	* what was decided belongs where the decision is.
	291	*/
	292	export function addRemark(
	293	db: Database,
	294	who: Who,
	295	input: {
	296	proposalId: number;
	297	kind: string;
	298	body: string;
	299	optionLabel?: string \| undefined;
	300	},
	301	): Result<Remark> {
	302	if (who.role === "anon")
	303	return fail("signin_required", "Sign in to say something.");
	304	if (!Number.isInteger(input.proposalId))
	305	return fail("invalid", "A proposal id is a whole number.");
	306	const kind = String(input.kind ?? "");
	307	if (!KINDS.includes(kind as Kind))
	308	return fail("invalid", `A remark is one of ${KINDS.join(", ")}.`);
	309	const body = String(input.body ?? "").trim();
	310	if (body.length === 0 \|\| body.length > BODY_MAX)
	311	return fail("invalid", `A remark is 1 to ${BODY_MAX} characters.`);
	312	const label = String(input.optionLabel ?? "").trim();
	313	// A label is what a counter is for; on anything else it would be stored
	314	// and never looked at, which is worse than being told.
	315	if (label !== "" && kind !== "counter")
	316	return fail("invalid", "Only a counter names an option.");
	317	if (label.length > LABEL_MAX)
	318	return fail(
	319	"invalid",
	320	`An option label is at most ${LABEL_MAX} characters.`,
	321	);
	322	if (!exists(db, input.proposalId))
	323	return fail("not_found", "No such proposal.");
	324	const remark = db
	325	.query<
	326	Remark,
	327	[number, string, string, string \| null, string, string]
	328	>("INSERT INTO remark (proposal_id, kind, body, option_label, author_id, author_name) VALUES (?1, ?2, ?3, ?4, ?5, ?6) RETURNING *")
	329	.get(
	330	input.proposalId,
	331	kind,
	332	body,
	333	label === "" ? null : label,
	334	who.id,
	335	who.name,
	336	)!;
	337	emit("remark.added", remark);
	338	return ok(remark);
	339	}
	340
	341	/** Take a remark back: its author, or an admin. */
	342	export function deleteRemark(
	343	db: Database,
	344	who: Who,
	345	input: { id: number },
	346	): Result<{ id: number; proposal_id: number }> {
	347	if (who.role === "anon")
	348	return fail("signin_required", "Sign in to delete a remark.");
	349	if (!Number.isInteger(input.id))
	350	return fail("invalid", "A remark id is a whole number.");
	351	const remark = db
	352	.query<Remark, [number]>("SELECT * FROM remark WHERE id = ?1")
	353	.get(input.id);
	354	if (remark === null) return fail("not_found", "No such remark.");
	355	if (!canDeleteRemark(who, remark))
	356	return fail("forbidden", "Only the author or an admin can delete a remark.");
	357	db.query("DELETE FROM remark WHERE id = ?1").run(remark.id);
	358	const gone = { id: remark.id, proposal_id: remark.proposal_id };
	359	emit("remark.removed", gone);
	360	return ok(gone);
	361	}
	362
	363	/**
	364	* Take the option a counter asks for: append it to the proposal and stamp
	365	* the remark. Only the proposal's author or an admin, only while it is
	366	* open, and only once — and nothing else about the proposal moves, so every
	367	* ballot already cast still means what it meant.
	368	*/
	369	export function acceptCounter(
	370	db: Database,
	371	who: Who,
	372	input: { id: number },
	373	): Result<{ remark: Remark; option: Option }> {
	374	if (who.role === "anon")
	375	return fail("signin_required", "Sign in to accept a counter.");
	376	if (!Number.isInteger(input.id))
	377	return fail("invalid", "A remark id is a whole number.");
	378	const remark = db
	379	.query<Remark, [number]>("SELECT * FROM remark WHERE id = ?1")
	380	.get(input.id);
	381	if (remark === null) return fail("not_found", "No such remark.");
	382	const proposal = db
	383	.query<ProposalRow, [number]>("SELECT * FROM proposal WHERE id = ?1")
	384	.get(remark.proposal_id);
	385	if (proposal === null) return fail("not_found", "No such proposal.");
	386	if (!canAcceptCounter(who, proposal))
	387	return fail(
	388	"forbidden",
	389	"Only the proposal's author or an admin can accept a counter.",
	390	);
	391	if (remark.kind !== "counter")
	392	return fail("invalid", "Only a counter proposes an option.");
	393	if (remark.option_label === null)
	394	return fail("invalid", "This counter names no option to add.");
	395	if (remark.accepted_at !== null)
	396	return fail("invalid", "This counter has already been accepted.");
	397	if (proposal.state !== "open")
	398	return fail(
	399	"invalid",
	400	`This proposal is ${proposal.state}; only an open one takes another option.`,
	401	);
	402	const options = db
	403	.query<
	404	Option,
	405	[number]
	406	>("SELECT * FROM option WHERE proposal_id = ?1 ORDER BY position")
	407	.all(proposal.id);
	408	const label = remark.option_label;
	409	if (options.some((o) => o.label.toLowerCase() === label.toLowerCase()))
	410	return fail("invalid", "That option is already on this proposal.");
	411	if (options.length >= OPTIONS_MAX)
	412	return fail(
	413	"invalid",
	414	`A proposal has at most ${OPTIONS_MAX} options; this one is full.`,
	415	);
	416	// The option and the stamp are one thing: both rows or neither.
	417	const done = db.transaction(() => {
	418	const option = db
	419	.query<
	420	Option,
	421	[number, string, number]
	422	>("INSERT INTO option (proposal_id, label, position) VALUES (?1, ?2, ?3) RETURNING *")
	423	.get(proposal.id, label, options.length)!;
	424	const stamped = db
	425	.query<
	426	Remark,
	427	[number]
	428	>("UPDATE remark SET accepted_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = ?1 RETURNING *")
	429	.get(remark.id)!;
	430	db.query(
	431	"UPDATE proposal SET updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now') WHERE id = ?1",
	432	).run(proposal.id);
	433	return { remark: stamped, option };
	434	})();
	435	emit("remark.accepted", done);
	436	return ok(done);
	437	}
	438
	439	/** Whether a proposal with this id is there at all. */
	440	const exists = (db: Database, id: number): boolean =>
	441	db
	442	.query<{ id: number }, [number]>("SELECT id FROM proposal WHERE id = ?1")
	443	.get(id) !== null;
	444
243	445	/** What anyone may know about this process: nothing about anybody's data. */
244	446	export interface Health {
245	447	readonly ok: boolean;
		@@ -327,6 +529,14 @@ function soundness(db: Database, now = Date.now()): string {
327	529	return verdict;
328	530	}
329	531
	532	/**
	533	* Ownership, once: whoever wrote the row, or an admin. Every "only the
	534	* author or an admin" in this file is this function, so a door that asks
	535	* gets the same answer the action will give it.
	536	*/
	537	const mine = (who: Who, row: { author_id: string }): boolean =>
	538	who.role === "admin" \|\| (who.role === "user" && who.id === row.author_id);
	539
330	540	/**
331	541	* Whether `who` may withdraw `proposal` at all. The state is the action's
332	542	* own check; the page and the terminal ask this and the state together, so
		@@ -335,6 +545,20 @@ function soundness(db: Database, now = Date.now()): string {
335	545	export const canWithdraw = (
336	546	who: Who,
337	547	proposal: Pick<Proposal, "author_id">,
338		): boolean =>
339		who.role === "admin" \|\|
340		(who.role === "user" && who.id === proposal.author_id);
	548	): boolean => mine(who, proposal);
	549
	550	/** Whether `who` may delete `remark`: its author, or an admin. */
	551	export const canDeleteRemark = (
	552	who: Who,
	553	remark: Pick<Remark, "author_id">,
	554	): boolean => mine(who, remark);
	555
	556	/**
	557	* Whether `who` may accept a counter on `proposal` — the proposal's author
	558	* or an admin. Whether this counter can be accepted is `acceptCounter`'s
	559	* own check; the page asks both to decide whether to draw the button.
	560	*/
	561	export const canAcceptCounter = (
	562	who: Who,
	563	proposal: Pick<Proposal, "author_id">,
	564	): boolean => mine(who, proposal);
		@@ -58,6 +58,22 @@ export const migrations: string[] = [
58	58	data TEXT NOT NULL,
59	59	created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
60	60	)`,
	61	// The argument, kept with what it argues about: a remark is a comment, a
	62	// question, or a counter that names the option it wants instead
	63	// (`option_label`, stamped `accepted_at` when the proposal's author takes
	64	// it). It goes when its proposal goes.
	65	`CREATE TABLE remark (
	66	id INTEGER PRIMARY KEY,
	67	proposal_id INTEGER NOT NULL REFERENCES proposal (id) ON DELETE CASCADE,
	68	kind TEXT NOT NULL CHECK (kind IN ('comment', 'question', 'counter')),
	69	body TEXT NOT NULL CHECK (length(body) BETWEEN 1 AND 2000),
	70	option_label TEXT CHECK (option_label IS NULL OR length(option_label) BETWEEN 1 AND 80),
	71	accepted_at TEXT,
	72	author_id TEXT NOT NULL,
	73	author_name TEXT NOT NULL,
	74	created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
	75	);
	76	CREATE INDEX remark_proposal ON remark (proposal_id)`,
61	77	];
62	78
63	79	export function openDb(dir = dataDir): Database {
		@@ -8,12 +8,15 @@
8	8
9	9	import type { Database } from "bun:sqlite";
10	10	import {
	11	addRemark,
11	12	getProposal,
12	13	health,
13	14	listProposals,
	15	listRemarks,
14	16	propose,
15	17	withdrawProposal,
16	18	BODY_MAX,
	19	KINDS,
17	20	LABEL_MAX,
18	21	OPTIONS_MAX,
19	22	OPTIONS_MIN,
		@@ -123,6 +126,51 @@ export const tools: readonly Tool[] = [
123	126	},
124	127	run: (db, who, args) => withdrawProposal(db, who, { id: Number(args.id) }),
125	128	},
	129	{
	130	name: "list_remarks",
	131	description:
	132	"The argument on one proposal — comments, questions and counters — oldest first. Anyone may read it.",
	133	inputSchema: {
	134	type: "object",
	135	properties: {
	136	proposal_id: { type: "integer", minimum: 1 },
	137	},
	138	required: ["proposal_id"],
	139	},
	140	run: (db, who, args) =>
	141	listRemarks(db, who, { proposalId: Number(args.proposal_id) }),
	142	},
	143	{
	144	name: "add_remark",
	145	description:
	146	"Say something on a proposal as the signed-in person: a comment on it, a question for its author, or a counter arguing for another option. A counter may name that option in option_label, and the proposal's author can then add it. A withdrawn or decided proposal still takes remarks. Anonymous callers cannot.",
	147	inputSchema: {
	148	type: "object",
	149	properties: {
	150	proposal_id: { type: "integer", minimum: 1 },
	151	kind: { type: "string", enum: [...KINDS] },
	152	body: { type: "string", minLength: 1, maxLength: BODY_MAX },
	153	option_label: {
	154	type: "string",
	155	minLength: 1,
	156	maxLength: LABEL_MAX,
	157	description:
	158	"The option this counter wants the proposal to offer instead. Counters only.",
	159	},
	160	},
	161	required: ["proposal_id", "kind", "body"],
	162	},
	163	run: (db, who, args) =>
	164	addRemark(db, who, {
	165	proposalId: Number(args.proposal_id),
	166	kind: String(args.kind ?? ""),
	167	body: String(args.body ?? ""),
	168	optionLabel:
	169	args.option_label === undefined \|\| args.option_label === null
	170	? undefined
	171	: String(args.option_label),
	172	}),
	173	},
126	174	{
127	175	name: "health",
128	176	description:
		@@ -24,6 +24,8 @@ interface RuleEntry {
24	24	const WORKS: readonly string[] = [
25	25	"Open a proposal: a title, a paragraph, two to eight options, and the rule that will decide it.",
26	26	"Read every proposal and any one of them, signed in or not.",
	27	"Say something on a proposal: a comment, a question for its author, or a counter arguing for another option — and delete your own again.",
	28	"Accept a counter on a proposal you opened: the option it names is added to it, and every ballot already cast still stands.",
27	29	"Withdraw a proposal you opened while it is open; an admin withdraws any.",
28	30	"Watch the list stay current as other people write, without reloading.",
29	31	];
		@@ -35,7 +37,7 @@ const WORKS: readonly string[] = [
35	37	*/
36	38	const NOT_YET: readonly string[] = [
37	39	"Voting. The counting in the quorum module is written and tested, but nothing casts a ballot yet, so nothing is decided yet either.",
38		"Deliberation. There is no way to ask a question or argue a point on a proposal before it decides.",
	40	"Answers. A question on a proposal is asked in the open and answered in the open; nothing here tells its author that one is waiting.",
39	41	"A roster. Who counts as a member of this group has no page and no list; a “named few” rule is the only way to say who counts.",
40	42	"Bindings. A decision is a record here and does nothing elsewhere — no webhook, no issue, no file.",
41	43	];
		@@ -1,21 +1,50 @@
1	1	/**
2	2	* One proposal: its title, its paragraph, its options in order, who wrote
3	3	* it and where it stands — and a Withdraw form for whoever may withdraw it
4		* while it is open. A guest sees all of it and no forms.
	4	* while it is open. Below it the argument: a composer for whoever is signed
	5	* in, and then the thread, oldest first. A guest sees all of it and no forms.
	6	*
	7	* The composer sits above the thread on purpose. The thread is the live
	8	* region, it grows at the bottom, and it is the last thing on the page — so
	9	* a remark that arrives while someone is typing moves nothing they can see,
	10	* and the box they are typing in is never the thing that gets replaced.
5	11	*/
6	12
7		import { canWithdraw, type FullProposal } from "../actions.ts";
	13	import {
	14	canAcceptCounter,
	15	canDeleteRemark,
	16	canWithdraw,
	17	KINDS,
	18	BODY_MAX,
	19	LABEL_MAX,
	20	type FullProposal,
	21	type Kind,
	22	type Remark,
	23	} from "../actions.ts";
8	24	import { escape } from "../http.ts";
9	25	import { describeRule } from "../quorum.ts";
10	26	import type { Who } from "../who.ts";
11	27	import { ago, layout, toast } from "./layout.ts";
12	28
	29	/** What each kind is called on the page, and what it is for in one line. */
	30	const KIND_LABEL: Record<Kind, string> = {
	31	comment: "Comment",
	32	question: "Question",
	33	counter: "Counter",
	34	};
	35	const KIND_HINT: Record<Kind, string> = {
	36	comment: "something to say about this proposal",
	37	question: "something to ask its author",
	38	counter: "another option it should offer instead",
	39	};
	40
13	41	export function proposalPage(input: {
14	42	who: Who;
15	43	proposal: FullProposal;
	44	remarks: readonly Remark[];
16	45	notice?: string \| undefined;
17	46	}): string {
18		const { who, proposal, notice } = input;
	47	const { who, proposal, remarks, notice } = input;
19	48	const withdraw =
20	49	proposal.state === "open" && canWithdraw(who, proposal)
21	50	? `<form method="post" action="/proposals/${proposal.id}/withdraw">
		@@ -23,7 +52,7 @@ export function proposalPage(input: {
23	52	</form>`
24	53	: "";
25	54	return layout(
26		`<section id="proposal" data-live="proposal.opened proposal.withdrawn" class="card">
	55	`<section id="proposal" data-live="proposal.opened proposal.withdrawn remark.accepted" class="card">
27	56	<div class="head-row">
28	57	<h2>${escape(proposal.title)}</h2>
29	58	<span class="pill" data-state="${escape(proposal.state)}">${escape(proposal.state)}</span>
		@@ -39,12 +68,87 @@ export function proposalPage(input: {
39	68	.join("")}</ol>
40	69	<div class="row">${withdraw}<a class="button button-quiet" href="/">All proposals</a></div>
41	70	</section>
	71	<section class="card">${composer(who, proposal)}</section>
	72	<section id="thread" data-live="remark.added remark.removed remark.accepted">
	73	${thread(who, proposal, remarks)}
	74	</section>
42	75	${toast(notice)}`,
43	76	who,
44	77	`/p/${proposal.id}`,
45	78	);
46	79	}
47	80
	81	/** Where a remark is written. A guest is told how to get one instead. */
	82	const composer = (who: Who, proposal: FullProposal): string =>
	83	who.role === "anon"
	84	? `<p class="muted">Reading as a guest. <a href="/__forge/signin?to=${escape(encodeURIComponent(`/p/${proposal.id}`))}">Sign in</a> to comment, ask a question or counter with another option.</p>`
	85	: `<form class="stack composer remark-form" method="post" action="/proposals/${proposal.id}/remarks">
	86	<label class="field">
	87	<span>Say something</span>
	88	<textarea class="input" name="body" rows="3" placeholder="What you think, what you want to know, or the option you would rather have" required maxlength="${BODY_MAX}"></textarea>
	89	</label>
	90	<label class="field">
	91	<span>As a</span>
	92	<select class="input" name="kind">${KINDS.map(
	93	(kind) =>
	94	`<option value="${kind}"${kind === "comment" ? " selected" : ""}>${KIND_LABEL[kind]} — ${KIND_HINT[kind]}</option>`,
	95	).join("")}</select>
	96	</label>
	97	<label class="field counter-field">
	98	<span>The option you want instead, for a counter only</span>
	99	<input class="input" name="option_label" autocomplete="off" maxlength="${LABEL_MAX}" placeholder="Neither — ask again in March">
	100	<span class="muted small">Left empty a counter is only an argument. Filled in, the proposal's author can add it to the options with one press; every ballot already cast still stands.</span>
	101	</label>
	102	<div class="row"><button class="button">Say it</button></div>
	103	</form>`;
	104
	105	/** The argument, oldest first. */
	106	const thread = (
	107	who: Who,
	108	proposal: FullProposal,
	109	remarks: readonly Remark[],
	110	): string =>
	111	remarks.length === 0
	112	? `<p class="muted small">Nothing said yet.</p>`
	113	: `<p class="muted small">${remarks.length} remark${remarks.length === 1 ? "" : "s"}, oldest first.</p>
	114	<ol class="list thread">${remarks.map((remark) => item(who, proposal, remark)).join("")}</ol>`;
	115
	116	const item = (who: Who, proposal: FullProposal, remark: Remark): string => {
	117	const accept =
	118	remark.kind === "counter" &&
	119	remark.option_label !== null &&
	120	remark.accepted_at === null &&
	121	proposal.state === "open" &&
	122	canAcceptCounter(who, proposal)
	123	? `<form method="post" action="/remarks/${remark.id}/accept">
	124	<input type="hidden" name="proposal" value="${proposal.id}">
	125	<button class="button button-quiet">Accept as an option</button>
	126	</form>`
	127	: "";
	128	const remove = canDeleteRemark(who, remark)
	129	? `<form method="post" action="/remarks/${remark.id}/delete">
	130	<input type="hidden" name="proposal" value="${proposal.id}">
	131	<button class="button button-quiet">Delete</button>
	132	</form>`
	133	: "";
	134	return `<li class="remark" data-kind="${escape(remark.kind)}">
	135	<p class="muted small"><span class="pill" data-kind="${escape(remark.kind)}">${KIND_LABEL[remark.kind] ?? escape(remark.kind)}</span> ${escape(remark.author_name)} · <time datetime="${escape(remark.created_at)}">${ago(remark.created_at)}</time></p>
	136	<p class="body">${escape(remark.body)}</p>
	137	${wanted(remark)}
	138	<div class="row">${accept}${remove}</div>
	139	</li>`;
	140	};
	141
	142	/** The option a counter names, and whether it was taken. */
	143	const wanted = (remark: Remark): string =>
	144	remark.option_label === null
	145	? ""
	146	: `<p class="small wanted">Instead: <b>${escape(remark.option_label)}</b>${
	147	remark.accepted_at === null
	148	? ""
	149	: ` · <span class="muted">added to the options <time datetime="${escape(remark.accepted_at)}">${ago(remark.accepted_at)}</time>; earlier ballots stand</span>`
	150	}</p>`;
	151
48	152	/**
49	153	* How this one is decided, in words, above the options. The rule was read
50	154	* once in the action; a rule this app cannot read — a row from before the
		@@ -0,0 +1,27 @@
	1	import { expect, test } from "bun:test";
	2	import { oneLine, plain } from "./plain.ts";
	3
	4	test("text someone else wrote carries no instruction to a terminal", () => {
	5	// A remark that tries to clear the screen, move the cursor and colour the
	6	// rest of the session red comes out as the words it is made of.
	7	const attack = "\x1b[2J\x1b[H\x1b[31mall clear\x07 \x00 \x9b1m";
	8	const printed = plain(attack);
	9	expect(printed).not.toContain("\x1b");
	10	expect(printed).not.toContain("\x07");
	11	expect(printed).not.toContain("\x00");
	12	expect(printed).not.toContain("\x9b");
	13	expect(printed).toContain("all clear");
	14	// Every control character becomes a space, so the words stay apart.
	15	expect(plain("a\x1bb")).toBe("a b");
	16
	17	// A paragraph is still a paragraph: the terminal wraps those itself.
	18	expect(plain("one\ntwo\r\nthree")).toBe("one\ntwo\r\nthree");
	19	// On one line it is one line, whatever it was.
	20	expect(oneLine("one\ntwo")).toBe("one two");
	21	// What is left of an escape sequence is the letters in it, printed.
	22	expect(oneLine("one\x1b[31m\ntwo")).toBe("one [31m two");
	23	// Ordinary text is untouched, accents and all.
	24	expect(plain("Räume — “the garden”, 2 × 3")).toBe(
	25	"Räume — “the garden”, 2 × 3",
	26	);
	27	});
		@@ -0,0 +1,17 @@
	1	/**
	2	* Text someone else wrote, printed on a terminal that reads escape
	3	* sequences as instructions. `escape` in `http.ts` is this for HTML; this is
	4	* it for a pty: every C0 and C1 control character becomes a space, so the
	5	* only thing that moves the cursor in `src/tty.ts` is `src/tty.ts`.
	6	*
	7	* Newline and carriage return survive: the terminal wraps paragraphs itself
	8	* and they are the shape of the text, not a command.
	9	*/
	10
	11	const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g;
	12
	13	export const plain = (text: string): string => text.replace(CONTROL, " ");
	14
	15	/** The same, on one line: a title in a list is a line and not three. */
	16	export const oneLine = (text: string): string =>
	17	plain(text).replace(/[\r\n]+/g, " ");
		@@ -6,9 +6,13 @@
6	6
7	7	import type { Database } from "bun:sqlite";
8	8	import {
	9	acceptCounter,
	10	addRemark,
	11	deleteRemark,
9	12	getProposal,
10	13	health,
11	14	listProposals,
	15	listRemarks,
12	16	propose,
13	17	withdrawProposal,
14	18	type Failure,
		@@ -45,7 +49,7 @@ export interface Context {
45	49	}
46	50
47	51	export interface Route {
48		readonly method: "GET" \| "POST";
	52	readonly method: "GET" \| "POST" \| "DELETE";
49	53	readonly path: string;
50	54	readonly handle: (ctx: Context) => Response \| Promise<Response>;
51	55	}
		@@ -121,8 +125,14 @@ export const routes: readonly Route[] = [
121	125	const found = getProposal(c.db, c.who, { id: Number(c.params.id) });
122	126	// Anything that is not a proposal — a bad id or a gone one — is a 404.
123	127	if (!found.ok) return html(missing(found.message, c.who), 404, clear);
	128	const said = listRemarks(c.db, c.who, { proposalId: found.value.id });
124	129	return html(
125		proposalPage({ who: c.who, proposal: found.value, notice }),
	130	proposalPage({
	131	who: c.who,
	132	proposal: found.value,
	133	remarks: said.ok ? said.value : [],
	134	notice,
	135	}),
126	136	200,
127	137	clear,
128	138	);
		@@ -159,6 +169,50 @@ export const routes: readonly Route[] = [
159	169	pathOf(c.params.id ?? ""),
160	170	),
161	171	},
	172	// The thread. A remark form comes back to the proposal it was written on:
	173	// the page puts that id in the form, and `pathOf` makes a path out of a
	174	// whole number or out of nothing at all.
	175	{
	176	method: "POST",
	177	path: "/proposals/:id/remarks",
	178	handle: async (c) => {
	179	const form = await readForm(c.request);
	180	if (form === undefined) return text("too large", 413);
	181	return done(
	182	addRemark(c.db, c.who, {
	183	proposalId: Number(c.params.id),
	184	kind: String(form.get("kind") ?? ""),
	185	body: String(form.get("body") ?? ""),
	186	optionLabel: String(form.get("option_label") ?? ""),
	187	}),
	188	pathOf(c.params.id ?? ""),
	189	);
	190	},
	191	},
	192	{
	193	method: "POST",
	194	path: "/remarks/:id/delete",
	195	handle: async (c) => {
	196	const form = await readForm(c.request);
	197	if (form === undefined) return text("too large", 413);
	198	return done(
	199	deleteRemark(c.db, c.who, { id: Number(c.params.id) }),
	200	pathOf(String(form.get("proposal") ?? "")),
	201	);
	202	},
	203	},
	204	{
	205	method: "POST",
	206	path: "/remarks/:id/accept",
	207	handle: async (c) => {
	208	const form = await readForm(c.request);
	209	if (form === undefined) return text("too large", 413);
	210	return done(
	211	acceptCounter(c.db, c.who, { id: Number(c.params.id) }),
	212	pathOf(String(form.get("proposal") ?? "")),
	213	);
	214	},
	215	},
162	216
163	217	// The JSON API: the same actions, the same identity, plain status codes.
164	218	{
		@@ -202,6 +256,42 @@ export const routes: readonly Route[] = [
202	256	handle: (c) =>
203	257	answer(withdrawProposal(c.db, c.who, { id: Number(c.params.id) })),
204	258	},
	259	{
	260	method: "GET",
	261	path: "/api/proposals/:id/remarks",
	262	handle: (c) =>
	263	answer(listRemarks(c.db, c.who, { proposalId: Number(c.params.id) })),
	264	},
	265	{
	266	method: "POST",
	267	path: "/api/proposals/:id/remarks",
	268	handle: async (c) => {
	269	const body = await readJson(c.request);
	270	if (body === undefined) return json({ error: "too_large" }, 413);
	271	const input = fields(body);
	272	return answer(
	273	addRemark(c.db, c.who, {
	274	proposalId: Number(c.params.id),
	275	kind: String(input.kind ?? ""),
	276	body: String(input.body ?? ""),
	277	optionLabel: given(input.optionLabel ?? input.option_label),
	278	}),
	279	201,
	280	);
	281	},
	282	},
	283	{
	284	method: "DELETE",
	285	path: "/api/remarks/:id",
	286	handle: (c) =>
	287	answer(deleteRemark(c.db, c.who, { id: Number(c.params.id) })),
	288	},
	289	{
	290	method: "POST",
	291	path: "/api/remarks/:id/accept",
	292	handle: (c) =>
	293	answer(acceptCounter(c.db, c.who, { id: Number(c.params.id) })),
	294	},
205	295
206	296	// What a probe asks, forever: 200 while the app is sound, 503 when it is
207	297	// not, and never a word about anybody's data.