Skip to content

feat(site): add the todo app on one contract, one store and one binding - #138

Open
systemfsoftware-maker wants to merge 1 commit into
mainfrom
feat/todo-app
Open

systemfsoftware-maker wants to merge 1 commit into
mainfrom
feat/todo-app

Conversation

@systemfsoftware-maker

Copy link
Copy Markdown
Collaborator

What this adds

A todo app in apps/site, served at /todo, that shows the kit's shape end to end.

One declaration, three surfaces. apps/site/src/features/todo/todo.contract.ts declares the six
operations — list, add, complete, rename, reorder, remove — with their request, response and refusal
schemas. The HTTP API the web UI calls (TodoRpcs) and the MCP tools an agent calls (TodoTools) are
both derived from that one declaration; the handlers are the same handlers for both.

Pure decisions, I/O sandwich cells. Each operation is a workflow (*.workflow.ts) that takes a
command and returns a tagged decision or a tagged refusal, wrapped in a cell (*.cell.ts) that reads
the store, decides, and writes the store.

One store, one binding. The todo state lives in its own D1 database (TODO_DB) behind the single
TodoStore binding. d1-todo-store.ts is the only code that knows about SQL, tables or bindings.
The in-memory fake lives in apps/site/fakes/, outside the app code, so the tests drive the real port.

One person, one list. A browser holds a bearer credential in localStorage; the server hashes it
(SHA-256) into the person key that owns the rows. A request carries the credential, never a person id,
so one person's list can never name another person's rows, and one person's failure never reaches
another person's data.

Refusals, not wrong answers. TodoTextMissing, TodoTextTooLong, TodoRateLimited,
TodoNotFound, TodoVersionConflict, TodoNotMovable and TodoStoreUnavailable are typed refusals;
the caller learns which one it got. Every mutation states the version it read, a stale version is
refused instead of applied, and a reorder swaps two rows in one guarded statement.

Observability. The Worker exports traces, logs and metrics over OTLP when
OTEL_EXPORTER_OTLP_ENDPOINT names a collector. Todo text never leaves the process: the domain copies
no field values onto spans, and a store failure never quotes a row.

The interface

Keyboard-first and responsive: n focuses the composer, the list is optimistic with rollback on
refusal, the done state toggles, and todos move one place up or down.

What is verified

  • pnpm --filter @endgame/site test — 35 tests, including a property test per workflow.
  • pnpm --filter @endgame/site lint, pnpm --filter @endgame/site typecheck,
    pnpm --filter @endgame/site-e2e lint, pnpm --filter @endgame/site-e2e typecheck,
    pnpm format:check — all clean.
  • The browser journey in apps/site-e2e/tests/features/todo drives add, complete, rename, reorder,
    delete, the reload that proves the todo survives, and the two-person isolation, in a real Chromium
    against a running site: 4 tests pass.
  • An MCP client drives the derived tools over the site's MCP endpoint: the tools are offered, a todo
    is added, and the list returns it.

Notes

  • The README section for the app is a separate edit; this pull request carries the code, the tests and
    the journeys.
  • Mutation (pnpm --filter @endgame/site mutation) is not run here; it is the nightly job's gate.

The todo feature declares its six operations once, in
apps/site/src/features/todo/todo.contract.ts, and derives the web
surface, the HTTP API and the MCP tools from that declaration. Each
operation is a pure workflow wrapped in an I/O sandwich cell, and the
todo state lives in its own D1 database behind a single store binding.

A browser holds a bearer credential that the server hashes into the
person key owning the rows, so a request can never name another
person's todos. Every operation refuses with a typed reason, every
mutation states the version it read, and a reorder swaps two rows in
one guarded statement.

The Worker exports traces, logs and metrics over OTLP when
OTEL_EXPORTER_OTLP_ENDPOINT names a collector; the domain copies no
field values onto spans and a store failure never quotes a row.

Property tests cover every workflow, the browser journey proves the
add, complete, rename, reorder, delete, reload and two-person
isolation flows, and an MCP client drives the derived tools.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant