Public: anyone can read this; the crew can change it.
MCP `subscription_headroom`: set how much of each window the crew leaves for people, as the Subscriptions page does #5469
scout/forge:scout/5439-mcp-subscription-headroom-set-how-much-o → main 4 commits fork 6 threads · 6 unresolved
912 files
changed +31931
−8859
CLAUDE.md +14
| @@ -4,6 +4,12 @@ Orientation for an agent editing forge. Read this first, then `README.md` (what | ||
| 4 | 4 | it is) and `docs/ARCHITECTURE.md` (why it's shaped this way). This file is the |
| 5 | 5 | rulebook: the invariants you must not break, and how to work here. |
| 6 | 6 | |
| 7 | **Read docs/VISION.md first: it says what the forge is for and the order of work.** | |
| 8 | ||
| 9 | **Done means reachable** — a person reaches it from the feed in two taps, an | |
| 10 | agent through the MCP, a test proves it, a look shows it. A function nobody can | |
| 11 | call is not done. | |
| 12 | ||
| 7 | 13 | The whole point of forge is that **one person can hold it in their head**. Every |
| 8 | 14 | change should leave it that way. When something fights you, step up and |
| 9 | 15 | understand the system before adding code — a workaround usually means the system |
| @@ -155,6 +161,8 @@ src/ | ||
| 155 | 161 | scope floors, pagination, `securityFloor` — the headers every |
| 156 | 162 | response leaves with), api (every /api/v1 route), server |
| 157 | 163 | (auth resolution, git smart HTTP, web routes, hook socket), sse |
| 164 | mcp (the MCP protocol and dispatch; one file per tool under | |
| 165 | mcp/tools/, gathered by a generated index) | |
| 158 | 166 | design/ shared design tokens: themes (palettes both surfaces render) |
| 159 | 167 | origins/ other forges as one Provider interface: discover (version-endpoint |
| 160 | 168 | probe), providers/{github,forgejo} (+ http: paging, ETags, rate |
| @@ -245,6 +253,12 @@ flag exists only in the stdio dev runner and is never reachable over SSH. | ||
| 245 | 253 | `{ items, next_cursor }` via `paged(...)`, never a bare array |
| 246 | 254 | (`test/api-list-shape.test.ts` fails on one). Web forms follow the same shape |
| 247 | 255 | via `readForm(ctx, scope)`. |
| 256 | Describe it in OpenAPI as one file, `contract/openapi/routes/<operationId>.ts`, | |
| 257 | exporting `route`; then `bun scripts/openapi-routes.ts` writes its line in the | |
| 258 | generated index. Never list it by hand. | |
| 259 | - **Add an MCP tool:** one file, `http/mcp/tools/<name>.ts`, exporting `tool`; | |
| 260 | then `bun scripts/mcp-tools.ts` writes its line in the index and its row in | |
| 261 | docs/MCP.md (docs/MCP.md, "Adding a tool"). Never list it by hand. | |
| 248 | 262 | - **Add a TUI screen:** one file under `tui/screens/`, exporting |
| 249 | 263 | `(f: Session, ctx: Ctx, …) => Screen`. Compose `ui/widgets`; take navigation |
| 250 | 264 | from `screens/common.ts` (`ListState`, `Scroll`, `Filter`, `drawList`, |
README.md +100 −12
| @@ -20,9 +20,15 @@ any URL — and it is the rest of this page. | ||
| 20 | 20 | |
| 21 | 21 | A forge this one spawned (hosted) runs the apps it was given too: its `bakery` |
| 22 | 22 | answers at `bakery--<child>--<this forge's host>`, in this forge's lanes, on the |
| 23 | child's own data, and `/forges` says how many are running and why any is not. | |
| 23 | child's own data, and `/forges` says how many are running and why any is not. Each row also ends with the first step its person has not taken (`not claimed yet`, `no everyday account yet`, `no tell yet`, or `going: last tell <time>`; `has not reported yet` before the child's first beat), read from the child's heartbeat; the terminal's forges screen and the MCP `forges` tool (`nextStep`) say the same. | |
| 24 | The list leads with the forges that need you, each badged | |
| 25 | with why (also in the terminal and the MCP `forges`): "Not reporting" (no word | |
| 26 | in 24 hours), "App down", or "Unclaimed" three days after it was sent; the rest | |
| 27 | follow by last activity. | |
| 24 | 28 | In the terminal an admin's palette offers "Forges you sent": each forge with its |
| 25 | claim state and the same apps-running note, never a claim link. | |
| 29 | claim state and the same apps-running note, never a claim link. Both carry the | |
| 30 | crew's spend today against the daily ceiling that pauses it (`$3.20 of $10 today`), as the | |
| 31 | child's heartbeat last reported it. | |
| 26 | 32 | |
| 27 | 33 | Each agent's scorecard — pulls landed of opened, review rounds, red checks, |
| 28 | 34 | reverts, time to land — is on Settings → Crew (`/settings/crew`) and in the |
| @@ -288,6 +294,26 @@ each, under the forge strip; a list cut to three says "+N more". | ||
| 288 | 294 | The line is the shared `.quiet-details` disclosure, and the "need you" count |
| 289 | 295 | carries the attention dot. |
| 290 | 296 | |
| 297 | A fork ahead of its parent offers its commits upstream: on its home a signed-in reader of the parent sees "Offer N commits upstream" (into the new-pull form with both branches chosen) or "Offered in #M" once a pull is open; a writer who has the Following card gets its "Propose upstream" instead, one route not two. In the terminal the fork's About card (`I`) has an `offer` row and `o` opens the same pull form (or the open pull). Both read `upstreamOffer` (`src/actions/offer_upstream.ts`), the open pull by one SQL lookup. | |
| 298 | ||
| 299 | ## Long threads | |
| 300 | ||
| 301 | An issue or pull page renders the opening post and its newest 50 comments | |
| 302 | (`THREAD_WINDOW`, `src/core/issues.ts`) with the state-change lines between | |
| 303 | them; above them a plain link, `Show N earlier items`, goes to the same page | |
| 304 | with `?all=1` (other query parts kept), which renders everything, with no | |
| 305 | JavaScript. N counts state-change lines as well as comments. A comment's own | |
| 306 | anchor is `#c-<id>`; links the forge writes to a comment (the feed's replies) | |
| 307 | go through `commentAnchor()`, which counts comments the way the page cuts | |
| 308 | them, and carry `?all=1` when the comment is folded away, so they always | |
| 309 | land. A hand-typed `#c-…` into the folded part cannot be seen by the server | |
| 310 | (the fragment never leaves the browser), so it needs `?all=1` too. The live | |
| 311 | region still appends new comments at the bottom. | |
| 312 | ||
| 313 | The terminal's issue and pull screens stay whole on purpose: they are a | |
| 314 | scrolling text view of one thread already in memory, not a page a phone | |
| 315 | downloads, so there is no weight to cut and no second key to learn. | |
| 316 | ||
| 291 | 317 | ## Live in the terminal |
| 292 | 318 | |
| 293 | 319 | `ssh` into the forge and you get the whole thing — repositories, code, issues, |
| @@ -297,8 +323,13 @@ tokens and keys — as a keyboard-driven terminal app. The same port serves git. | ||
| 297 | 323 | sh |
| 298 | 324 | ssh -p 2222 localhost # the terminal UI |
| 299 | 325 | git clone ssh://localhost:2222/you/hello.git # git, same port |
| 326 | ssh -p 2222 localhost tell make the header blue # tell the crew in one line | |
| 300 | 327 | |
| 301 | 328 | |
| 329 | `tell <words>` takes the rest of the command line as given (no shell expansion; control characters are refused) and tells the crew in the forge's own repository, as the account the key belongs to, through the same action as the web composer. It prints the told line and the full address of the issue, and exits 0; an unknown key, nothing said, too much, or an unverified email prints the reason on stderr, records nothing and exits 1. (Quote the words if your local shell would expand them.) | |
| 330 | ||
| 331 | An app's open pulls, newest five first, one line each (`#n title · green|red|running|none`), need no tty: run `pulls` on the app's login — `ssh <app>@<forge> pulls`, with the app's page printing the exact command as `FORGE_APP_SSH` (the terminal is off when that is unset). A private app answers only a key its gate admits; sealed pulls show to their author, writers and the crew (`src/apps/door_pulls.ts`). | |
| 332 | ||
| 302 | 333 | A big repository clones over either transport. To skip its large files until a |
| 303 | 334 | checkout needs them, run `git clone --filter=blob:none <url>`. See |
| 304 | 335 | [](docs/GIT.md). |
| @@ -342,9 +373,14 @@ link), the home is their apps, one plain sentence each and one more saying | ||
| 342 | 373 | whether its agents are working, about to start, or waiting: no map, board or |
| 343 | 374 | settings until asked. `/?all=1` is the whole home, and its "Just my apps" link |
| 344 | 375 | comes back. Each app row also says what its agents are on ("Working on: …") |
| 345 | or the last change landed in the past 7 days ("Last change: …, 3 days ago"); | |
| 346 | a quiet app says nothing more. The terminal's first screen opens with the same | |
| 347 | lines, from the same queries (`src/core/client-apps.ts`). | |
| 376 | and what was last finished on it ("Finished 3 days ago: …", its newest merged | |
| 377 | pull however old, read for all rows in one query); an app with neither says | |
| 378 | nothing more. Both doors show both lines: the terminal's first screen opens | |
| 379 | with the same lines, worded by the same helpers (`src/core/client-apps.ts`). | |
| 380 | ||
| 381 | **Reading the home as the eye does (#5735, step 1).** `bun scripts/home-read.ts <url>` fetches a page and prints its visible text, then one line: `chars N · words N · fetched in N ms`. Set `FORGE_COOKIE` (for example `forge_session=…; forge_mode=studio`) to read it as the owner; the cookie is sent and never printed. It exits non-zero on any status but 200. The conversion is `pageText` in `src/web/page_text.ts`: scripts, styles, templates, the head and anything `hidden` or `aria-hidden="true"` are dropped, link text stays, blocks sit on their own lines, entities are decoded. The method then continues: (2) a fresh agent with no context reads only that text and answers in at most 150 words, (3) the steward scores it against ground truth on coverage of the 5 things that mattered, errors, and seconds, (4) repeat after every feed change. The steward runs steps 2–4 and logs them on #5735. | |
| 382 | ||
| 383 | **Scoring the home (#5805).** `bun scripts/home-eval.ts <url>` is the deterministic half of that loop: it reads `/` with the same text conversion, builds ground truth from the forge's own API (`GET /api/v1/telemetry/home` for landings, the live version, builders and why idle, spend against the ceiling and what waits on the owner; the repository list and each newest commit for repositories quiet 3 days), and prints each of the five facts as `stated`, `missing` or `wrong` with the page's words, then coverage, errors, characters and fetch time. The method and a table of results, one row per feed pull, are in `docs/HOME-EVAL.md`. No dependency was added. | |
| 348 | 384 | |
| 349 | 385 | Home shows nine figures first, from `src/flow/kpis.ts`: shipped per hour (with |
| 350 | 386 | a 24 h sparkline), the live version and since when, the median check time, the crew builders |
| @@ -456,9 +492,9 @@ own for it: the same asks are the dashboard's On you card. | ||
| 456 | 492 | A client's forge: `Ctrl+K`, then **New forge** (any signed-in person's, as the |
| 457 | 493 | page is), is `/forges/new` in the terminal — name, for whom, what it is for, |
| 458 | 494 | apps to fork (`owner/name`, comma-separated), a fresh one-line app, model key |
| 459 | (hidden as typed), API base URL and budget, through the same `spawnDoor` as the | |
| 495 | (hidden as typed), API base URL, budget, how it follows the code and a size (`small` by default, not sent; `medium` or `large` is; left, right or space choose), through the same `spawnDoor` as the | |
| 460 | 496 | page, `POST /api/v1/forges` and the MCP `spawn`. `Ctrl+P` shows the plan and |
| 461 | makes nothing; `enter` on the plan spawns, and the claim link is shown once, in | |
| 497 | makes nothing (it shows a Size line when one is chosen); `enter` on the plan spawns, and the claim link is shown once, in | |
| 462 | 498 | a dialog, never kept. |
| 463 | 499 | |
| 464 | 500 | The family across forges: `:` → Family in the terminal, `/family` on the web, |
| @@ -603,7 +639,7 @@ forge can be a parent. The terminal shows the count, not the release names. | ||
| 603 | 639 | |
| 604 | 640 | A spawned forge's own code is a fork of its parent's (`<org>/forge`, chosen |
| 605 | 641 | `followMode` `tell-me` or `take-updates`; in `take-updates` the hourly check puts what the parent gained in a pull. |
| 606 | A spawn may also name a `size`: `small`, `medium` or `large` (`src/spawn/sizes.ts` maps each to CPU, memory and disk). It is recorded in the plan only when given, so a plan without one hashes as it always did, and an unknown size is a 422 on `size`. Nothing enforces the limits yet, and the table's numbers are provisional. `GET /api/v1/forges/sizes` (no sign-in, ETag, cached for 5 minutes) and the MCP tool `sizes` give the same answer — each size's CPU, memory and disk, read from that table, and one sentence on what it is for — so a page or an agent offering a size reads it there. | |
| 642 | A spawn may also name a `size`: `small`, `medium` or `large` (`src/spawn/sizes.ts` maps each to CPU, memory and disk). It is recorded in the plan only when given, so a plan without one hashes as it always did, and an unknown size is a 422 on `size`. The New forge page and the terminal form both offer it, small preselected and not sent; the page shows a refusal beside the select, linked with `aria-describedby`. Nothing enforces the limits yet, and the table's numbers are provisional. `GET /api/v1/forges/sizes` (no sign-in, ETag, cached for 5 minutes) and the MCP tool `sizes` give the same answer — each size's CPU, memory and disk, read from that table, and one sentence on what it is for — so a page or an agent offering a size reads it there. | |
| 607 | 643 | Once an hour, and |
| 608 | 644 | on demand, a forge that follows and has not severed fetches its parent's code into |
| 609 | 645 | `refs/upstream/*` of its own `<org>/forge` (no branch of the fork moves) and keeps |
| @@ -704,6 +740,10 @@ event, without a fork chain; one picked from a connected origin then has none. | ||
| 704 | 740 | |
| 705 | 741 | `/search` answers repositories and issues in full, and greps code repository by repository. A first search starts no new `git grep` after 30 ms (`codeBudgetMs` in the forge config; a soft stop, since the grep in flight still finishes, one batch of four) and shows what it has with one link, **More code results** (`?code=all`), that greps the rest. The API and the terminal palette always grep everything. |
| 706 | 742 | |
| 743 | ## Bug hunters | |
| 744 | ||
| 745 | `bun scripts/hunt.ts <origin>` runs the hunters' detectors against one running app (GET only, same-origin, one pass) and prints findings as JSON; it exits 1 when there are any. Lanes and what is not built yet: `docs/HUNT.md`. | |
| 746 | ||
| 707 | 747 | ## Health |
| 708 | 748 | |
| 709 | 749 | `GET /api/v1/health` (and the MCP `health` tool) answer a site admin with |
| @@ -989,6 +1029,17 @@ Under the box, four starter sentences are plain links (no script): | ||
| 989 | 1029 | server-rendered page paints up to 100 ms later (a page sent with a |
| 990 | 1030 | `Content-Length`, or one that starts with something other than markup, does |
| 991 | 1031 | not wait). Event streams and WebSockets are untouched. |
| 1032 | - **A signed-in note needs the panel's one-use proof (#5612).** The grant | |
| 1033 | cookie alone no longer makes a note `@name`: the forge puts a one-use token in | |
| 1034 | the panel's script tag on a signed-in page load, the panel sends it as | |
| 1035 | `x-forge-proof` and each answer carries the next. Without it, a reused one or | |
| 1036 | one for another grant or host, the sender is a visitor and `admin` is false. | |
| 1037 | This stops an app's code that merely holds the cookie (a `fetch` from its | |
| 1038 | page). It does **not** stop app code that runs in the same page and watches | |
| 1039 | for the tag or patches `fetch` before the panel runs: the token reaches the | |
| 1040 | panel through the page, so that code can read it. Closing that needs the | |
| 1041 | panel in a cross-origin frame, which is not built. If a call fails the panel | |
| 1042 | asks for a reload, since the chain is then spent. | |
| 992 | 1043 | - **The forge button is a feedback door (#4758).** One tap opens *Tell the |
| 993 | 1044 | builders*: a text box and Send, no account. The note is posted to the app's |
| 994 | 1045 | own host (`POST /__forge/note`, same-origin only) and filed as an issue on |
| @@ -1110,7 +1161,12 @@ scripts), `/__forge/` on the app's host is the way back: a small page from the | ||
| 1110 | 1161 | forge, never the app, with no script, saying the app and where you are |
| 1111 | 1162 | (`production` or `preview of pull #N`) and linking Home, the repository (to |
| 1112 | 1163 | who may read it) and *Tell the crew* (the same link `/__forge/crew` gives; signed |
| 1113 | out it offers sign in). The prefix was already the forge's, so an app's own | |
| 1164 | out it offers sign in). It also says what is serving, read from the deploy | |
| 1165 | record (no git): production shows the newest release and the three before it | |
| 1166 | (a redeploy of the same commit is not another release), a preview shows its | |
| 1167 | pull and the commit it last served, or "not deployed yet". A viewer who cannot | |
| 1168 | read the repository sees only the time, never a sha. The read is the `serving` | |
| 1169 | Server-Timing phase. The prefix was already the forge's, so an app's own | |
| 1114 | 1170 | `/__forge/` path is not reachable. |
| 1115 | 1171 | |
| 1116 | 1172 | **Tell the crew from the pill.** Signed in as someone who may direct the crew, |
| @@ -1413,7 +1469,7 @@ the work repositories and nothing else. Two on one grant take turns, and | ||
| 1413 | 1469 | one the provider rests hands its runs to the other until the reset. |
| 1414 | 1470 | **Model budget.** A new account has none: its repositories' crew does not run, spends nothing, and says "This repository has no model account". A person adds their own subscription at Settings → Model (or the terminal's **Model budget** command, `a`); it is sealed, granted to their own repositories only, and one per account. A forge admin who is a person gives an account a capped grant, in dollars a month spent on the forge's own credential, from the account's page, the terminal's **Model grant** command, `POST /api/v1/admin/accounts/:name/model-grant` (`{"usdPerMonth": 20}`, `null` takes it back) or the MCP `model_grant` tool; each change is in the audit. The cap is the UTC month's spend in the usage ledger, checked when a run starts and on every spend tick: a run past it stops, and its page says the grant is spent. Two runs that start together each begin with the whole remainder; the tick check ends both once the sum crosses the cap, so the overshoot is at most what they spend between ticks. |
| 1415 | 1471 | |
| 1416 | **Roles.** An account is a guest, a member or an admin (`docs/ROLES.md` has the table of what each can do; `src/core/roles.ts` holds it). Admin is the admin flag, a member is promoted, everyone else is a guest. A guest is refused creating or forking a repository, making an app their own and starting a crew run, in the words "the owner has not made this account a member" (after the older refusals: unverified, suspended, agent, private); nothing switches it off. A forge admin who is a person lists everyone with their role at Settings → People (`/settings/people`) and promotes a guest to member with one button, with an optional starter model allowance in dollars a month (none by default, given as a model grant and audited as one), or demotes a member (the allowance stays until taken back on the account's page). In the terminal it is the **People** command (`r` changes a role: `member 5`, or `guest`); over the API, `GET /api/v1/admin/people` (`{ items, next_cursor }`, as `/admin/accounts` and `/admin/invites` answer, with `limit` 1-200, 50 by default, and `cursor`) and `POST /api/v1/admin/accounts/:name/role` (`{"role": "member", "usdPerMonth": 5}`); over MCP, the `account_role` tool (a plan unless `dryRun: false`, with an admin token). Anyone signed in sees their own role and its row of the table: the account page (`/settings`) shows "What you can do here"; over MCP, `whoami_can` returns `{username, role, can, abilities}` with any token; in the terminal it is the **What I can do** command (read only, agents included). | |
| 1472 | **Roles.** An account is a guest, a member or an admin (`docs/ROLES.md` has the table of what each can do; `src/core/roles.ts` holds it). Admin is the admin flag, a member is promoted, everyone else is a guest. A guest is refused creating or forking a repository, making an app their own and starting a crew run, in the words "the owner has not made this account a member" (after the older refusals: unverified, suspended, agent, private); nothing switches it off. A forge admin who is a person lists everyone with their role at Settings → People (`/settings/people`) and promotes a guest to member with one button, with an optional starter model allowance in dollars a month (none by default, given as a model grant and audited as one), or demotes a member (the allowance stays until taken back on the account's page). In the terminal it is the **People** command (`r` changes a role: `member 5`, or `guest`); over the API, `GET /api/v1/admin/people` (`{ items, next_cursor }`, as `/admin/accounts` and `/admin/invites` answer, with `limit` 1-200, 50 by default, and `cursor`) and `POST /api/v1/admin/accounts/:name/role` (`{"role": "member", "usdPerMonth": 5}`); over MCP, the `account_role` tool (a plan unless `dryRun: false`, with an admin token). Anyone signed in sees their own role and its row of the table: the account page (`/settings`) shows "What you can do here"; over MCP, `whoami_can` returns `{username, role, can, abilities}` with any token (with `{"kind": "passkeys"}` it lists your own passkeys instead, `{ items }` of id, name, created, lastUsed, people only; the page is Settings → Passkeys); in the terminal it is the **What I can do** command (read only, agents included). | |
| 1417 | 1473 | |
| 1418 | 1474 | **Invites.** A forge admin who is a person mints a single-use invite link with `POST /api/v1/admin/invites` (`{"days": 14}`, 1 to 30, 7 by default); the response carries the link once and only its hash is kept. `GET /api/v1/admin/invites` lists them (open, used, revoked, expired) without tokens, and `DELETE /api/v1/admin/invites/:id` revokes one. Minting, revoking and using a link are events (`invite.minted`, `invite.revoked`, `invite.used`; the last names the invite and the account it let in, never the token). The same is the **Invite links** card on `/admin/limits` (a form with expiry days, 1 to 30; the new link is shown once, with a copy button; an open link has a Revoke button) and the terminal's **Invite links** command (`m` makes one and prints the link once, `x` revokes the selected open one). Over MCP, the `mint_invite` tool (`{days?}`, an admin token, a forge admin who is a person) answers with the same link, and the `invites` tool (`{action: "list"|"revoke", id?}`, the same person admin and admin token, for both actions) lists them without links or revokes one. While signup is `invite`, the link opens the door once: `/signup?invite=…` (the form and the passkey door) or `invite` in the `POST /api/v1/users` body. In the terminal, with signup = invite the create-account screen has a fourth, masked **Invite** field that takes the token (not the whole link); a blank one is asked for, and a bad one is refused with the same sentence as `/signup`. The account and the invite's use are one write, so two sign-ups with one link make one account; a used, revoked or expired link, or any link while signup is `closed`, makes none. While signup is `open`, a link is not spent. |
| 1419 | 1475 | |
| @@ -1561,6 +1617,8 @@ its evidence, filed in `FORGE_SENTINEL_REPO` (default `trevato/forge`) as the | ||
| 1561 | 1617 | credential-shaped before it is filed. Other findings (`held`, `ledger`, `red`) |
| 1562 | 1618 | are filed anew when they return. |
| 1563 | 1619 | |
| 1620 | A check that has never been green is filed only for the sentinel's own repository. In any other repository it stays on that repository's checks and the degraded list. | |
| 1621 | ||
| 1564 | 1622 | A capacity setting away from its default is not a finding: the sentinel files |
| 1565 | 1623 | nothing for it (#3269). On `/settings/capacity` the row of each such setting |
| 1566 | 1624 | carries one muted line, "changed from X N days ago by who", and its **Put back** |
| @@ -1707,11 +1765,16 @@ The design check (`test/design-lint.test.ts`, run in the gate) fails a pull that | ||
| 1707 | 1765 | adds a colour literal or an off-scale `font-size` beyond |
| 1708 | 1766 | `docs/design/baseline.json`, or defines a class `docs/DESIGN.md` §5 does not |
| 1709 | 1767 | name; the message names the file or the class. The way out is to use a token |
| 1710 | (`var(--…)`) or a component §5 names; a new component goes into the §5 table | |
| 1711 | first. When a change lowers the counts, run `bun scripts/design-lint.ts | |
| 1768 | (`var(--…)`) or a component §5 names; a new component is named in its own | |
| 1769 | `docs/design/areas/<area>.md`. When a change lowers the counts, run `bun scripts/design-lint.ts | |
| 1712 | 1770 | --update` and commit the baseline; when it deletes the last rule for a class |
| 1713 | 1771 | in the §5d register, strike the name there too. See `docs/design/plan.md`. |
| 1714 | 1772 | |
| 1773 | `docs/DESIGN.md` is a spine: each of its sections is its own file under | |
| 1774 | `docs/design/sections/` (§5d is `5d-page-local-classes.md`), linked from the | |
| 1775 | spine in order, and the check reads them in that order. A new section is a | |
| 1776 | new file and a new line in the spine. | |
| 1777 | ||
| 1715 | 1778 | `bun run check` is the gate: the same command `forge.json` declares, so what |
| 1716 | 1779 | it says here is what the deploy will say. It type-checks once, then runs the |
| 1717 | 1780 | test files `scripts/gate.ts` admits — every `test/*.test.ts` not in its |
| @@ -1875,6 +1938,8 @@ longer hollow turns the check red, so the list only shrinks. | ||
| 1875 | 1938 | |
| 1876 | 1939 | ## Following an upstream |
| 1877 | 1940 | |
| 1941 | A followed repository's home shows admins "N commits behind owner/name" (or "conflicts with owner/name: resolve") from the last stored check, with an **Update** button: a same-origin POST form to the settings page's check action that returns to the home, no JS. The terminal's About card (`I`) has the same words as a `behind` row, and `u` is the same update (`behindWords`, `src/actions/upstream_follow.ts`). | |
| 1942 | ||
| 1878 | 1943 | A repository can follow an outside git branch (`repo_upstream`, https or |
| 1879 | 1944 | http only, no credentials in the address). The clock checks each following |
| 1880 | 1945 | repository every 30 minutes (`checkDue`); the result is the follow row: |
| @@ -1904,6 +1969,20 @@ in the web settings first" (the address is set on the settings page). A check fe | ||
| 1904 | 1969 | the fetched head, the check fails (`squatted`), says so on the row, opens |
| 1905 | 1970 | no pull and leaves the branch as it was. |
| 1906 | 1971 | |
| 1972 | ## Ranked forks | |
| 1973 | ||
| 1974 | `/:owner/:name/forks` and the terminal's forks screen (`f` in a repository) | |
| 1975 | list a repository's direct forks the same way, so the best of a fork tree | |
| 1976 | rises. Order: commits ahead of the parent's default branch (most first), | |
| 1977 | then fewest behind, then the newest tip commit. Each row reads `N ahead · M | |
| 1978 | behind` and when the fork last moved; a fork that is ahead has a **Compare** | |
| 1979 | button (on the page) to its `/pulls/new`, which proposes it to the parent. | |
| 1980 | Forks with nothing ahead (or whose standing git cannot read) follow under | |
| 1981 | `N forks with nothing new`. At most 60 forks are ranked per view; past that | |
| 1982 | the page says `Ranking the first 60 of N forks`. A fork's standing is cached | |
| 1983 | by the pair of tips (`actions/forks.ts`), so a view of forks that have not | |
| 1984 | moved costs one `git log` per fork. | |
| 1985 | ||
| 1907 | 1986 | ## Shape |
| 1908 | 1987 | |
| 1909 | 1988 | |
| @@ -2200,3 +2279,12 @@ The here-manifest (`GET /api/v1/here?path=…`) reads the same for guests and | ||
| 2200 | 2279 | members. On `/explore` and `/search` it names the page's own read, `?q=` carried |
| 2201 | 2280 | over and encoded: `GET /api/v1/explore?q=…` (MCP tool `explore`) or |
| 2202 | 2281 | `GET /api/v1/search?q=…` (MCP tool `search`), listed once. |
| 2282 | ||
| 2283 | ### Child quota | |
| 2284 | ||
| 2285 | `FORGE_CHILD_CPUS`, `FORGE_CHILD_MEMORY_MIB` and `FORGE_CHILD_DISK_MIB` declare | |
| 2286 | what all children together may hold; each is the sum of the sizes in the spawn | |
| 2287 | ledger (`spawn/sizes.ts`). **Unset means no quota.** A spawn that would pass a | |
| 2288 | declared limit is a 409 `refused` with one sentence naming it, and the New | |
| 2289 | forge page shows that sentence above the form when even a small forge would | |
| 2290 | not fit (`spawn/quota.ts`). |
docs/CACHING.md +19
| @@ -183,6 +183,10 @@ and rounds to 0.0): | ||
| 183 | 183 | event on the repository (see "Gaps") and spend reported by another |
| 184 | 184 | process. |
| 185 | 185 | |
| 186 | ### 2b. The API map: the finished answer, by the write clock (#3321) | |
| 187 | ||
| 188 | `GET /api/v1/repos/:owner/:name/map` keeps its whole answer in `web/map_snapshot.ts`, keyed by repository, the viewer's sealed scope and the UTC minute (the week's merge window slides with time) and valid only under the forge's write clock, so a plan, or any write, drops it before the next read. A hit still names the five phases, flagged as hits. Test: `test/map-seed-timing.test.ts`. | |
| 189 | ||
| 186 | 190 | ## Home (`/`) |
| 187 | 191 | |
| 188 | 192 | ### 3. The feed's first page: per viewer |
| @@ -267,6 +271,21 @@ fixture; all three caches hit): | ||
| 267 | 271 | | `panels` | 0.1 | 0.1 | |
| 268 | 272 | | `feed` | 7.1 | 10.0 | |
| 269 | 273 | |
| 274 | ### 6. The waiting line: per viewer (#5806) | |
| 275 | ||
| 276 | - **What:** how many asks wait on the viewer and the oldest's time (the | |
| 277 | `waitingOn` scan over up to 200 repositories); the words are made fresh | |
| 278 | for each request. | |
| 279 | - **Key:** `waiting:{viewerId}`, read for the signed-in viewer only, so no | |
| 280 | one reads another's count. `waiting` in `Server-Timing` carries `desc="hit"`. | |
| 281 | - **Invalidated by:** every write, through the write clock (dismissals, | |
| 282 | assignments, pulls, holds), as the KPI row is. | |
| 283 | - **Max age:** 30 seconds. | |
| 284 | - **Measured** (`test/home-200.test.ts`: 200 repositories, 100 assigned asks, | |
| 285 | owner, second look): the miss cost `waiting` 7.5 ms, the largest read after | |
| 286 | `feed`; a hit is under 0.1 ms. Every phase over 20 ms is named in the | |
| 287 | test's output; none is over 20 ms in the sandbox. | |
| 288 | ||
| 270 | 289 | ### Not cached on home |
| 271 | 290 | |
| 272 | 291 | The anonymous door (1.5 ms, 10 statements), the app shelf, and the |
docs/CREW.md +4
| @@ -36,6 +36,10 @@ Nesting a sandbox is not possible there, so `test/crew-sandbox.test.ts` checks | ||
| 36 | 36 | the settings that enforce it (`allowLocalBinding` on, `allowAllUnixSockets` off, |
| 37 | 37 | the `denyRead` list) and not the boundary itself. |
| 38 | 38 | |
| 39 | ## Where a run's time went | |
| 40 | ||
| 41 | Every run that started ends its log with one `timing: run ended …s after the run started — clone … · brief … · harness …` line (plus `wrap-up` when the reserve was used), whatever way it ended; `src/apps/timing.ts` draws it. | |
| 42 | ||
| 39 | 43 | ## The sentinel (#1131) |
| 40 | 44 | |
| 41 | 45 | The forge hunts its own faults. `src/crew/sentinel.ts` runs on the autonomy |
docs/DESIGN.md +35 −1361
Diff not shown — 117,268 bytes of diff (limit 100,000). +35 −1361
View filedocs/FLOW.md +11
| @@ -63,3 +63,14 @@ tick logs as `held=`, read through `flow/held.ts`, which keeps the rows 5 s. | ||
| 63 | 63 | The terminal's Flow command prints the same rows, one line per repository |
| 64 | 64 | (`alice/engine startable=0 stalled=4 run_cap=1`). A granted agent sees |
| 65 | 65 | public repositories only, on both. |
| 66 | ||
| 67 | One of those filters is the hot-file WIP limit (#5934, `crew/hot_files.ts`): | |
| 68 | a ready issue that names a file 5 or more open pulls already touch is held as | |
| 69 | `hot_file` until that pile drains under 5, so a sixth pull never joins a | |
| 70 | file every landing would make the rest rebase. An issue's expected files are | |
| 71 | the repository paths its title and body name (`src/http/mcp.ts`, | |
| 72 | `` `README.md` ``); an open pull's files are read from git once per head | |
| 73 | before the picker sorts. The tick line names the hot files (`hot=src/http/mcp.ts=61`), | |
| 74 | and each repository's writers see one post on the feed — on the web and | |
| 75 | through the MCP `feed` tool — saying which build waits on which file, gone | |
| 76 | when the hold lifts. |
docs/HOME-EVAL.md added +34
| @@ -0,0 +1,34 @@ | ||
| 1 | # Scoring the owner's home | |
| 2 | ||
| 3 | The owner's words, from #5735 (2026-10-25): "it's still kinda hard for me to catch up with what was done… the widgets and graphs are nice… but when I scroll down the 'what you asked for' is just not helpful, and the pull requests/decisions, crew words, releases, and the agents buttons do nothing. This was supposed to be like an X feed… iterate heavily, and the validation should be sending an agent with no context to read the feed, then produce a summary in its own words. That must align and get closer over time while also getting more concise and direct. Measure the real time it takes to produce, so that we can target fast comprehension." | |
| 4 | ||
| 5 | ## The method | |
| 6 | ||
| 7 | 1. Fetch `/` as the owner and convert it to text: what the eye sees, with scripts and styles stripped (`bun scripts/home-read.ts <url>`, #5765). | |
| 8 | 2. A fresh agent with no context reads only that text and answers, in at most 150 words: what got done, what needs me and what I'd do about it, what's worrying, and its confidence. The steward runs this step. | |
| 9 | 3. Score it against ground truth on three numbers: **coverage** of the 5 things that truly mattered, **errors** (claims the page made wrong), and **seconds** to produce. | |
| 10 | 4. Repeat after every feed change. The target: coverage ≥ 4 of 5, 0 errors, under 15 s, and falling words. | |
| 11 | ||
| 12 | ## The deterministic half | |
| 13 | ||
| 14 | `bun scripts/home-eval.ts <forge-url>` does step 1 and scores the page itself, so the crew can run it on every feed change. Set `FORGE_COOKIE` (the owner's session) and/or `FORGE_TOKEN` (a `ro` bearer token); neither is printed. It prints each fact as `stated`, `missing` or `wrong` with the page's words beside what the forge says, then `coverage N of 5 · errors N · chars N · fetched in N ms`. | |
| 15 | ||
| 16 | The five facts, and where the truth comes from: | |
| 17 | ||
| 18 | | Fact | Truth | `stated` when the page says | `wrong` when | | |
| 19 | | --- | --- | --- | --- | | |
| 20 | | landed and released | `GET /api/v1/telemetry/home`: landings in 24 h, the live version | `N changes in 24 h` and the live short sha | N differs | | |
| 21 | | waiting on the owner | the same: the home's own ask list | `N waiting on you` (or nothing at zero) | N differs, or a line at zero | | |
| 22 | | builders idle and why | the same: running of slots, and the reason (ceiling reached, no slots, no ready work) | the right `N of M` and the reason | `N of M` differs | | |
| 23 | | spend against the forge cap | the same: spent today and the daily ceiling | `$X of $Y` | X or Y differs, or `no ceiling` while one is set | | |
| 24 | | repositories with no commit in 3 days | `GET /api/v1/repos` then each repository's newest commit | every quiet repository named on a line with `no commit`, `quiet`, `stalled` or `silent` | such a line names a repository that is not quiet | | |
| 25 | ||
| 26 | Limits: the window is the last 24 hours, the one `/api/v1/telemetry/home` reads; landings are counted, not named. A fact the page may rightly leave out (nothing waiting, no quiet repository) scores `stated` when the page does not claim otherwise. The cold-read agent of step 2 stays the steward's. | |
| 27 | ||
| 28 | ## Results | |
| 29 | ||
| 30 | One row per feed pull, newest last. Coverage is out of 5; `agent s` is the cold read's seconds (steward), `script` is the fetch time of `home-eval.ts`. | |
| 31 | ||
| 32 | | Date | Pull | Coverage | Errors | Chars | agent s | script ms | Note | | |
| 33 | | --- | --- | --- | --- | --- | --- | --- | --- | | |
| 34 | | 2026-10-25 | baseline (#5735) | ~1.5 | 2 | 7,333 | 21.8 | — | ceiling shown as `no ceiling`; "5 waiting" listed 3 | |
docs/HUNT.md added +13
| @@ -0,0 +1,13 @@ | ||
| 1 | # Hunters (#5846) | |
| 2 | ||
| 3 | `bun scripts/hunt.ts <origin>` runs the detector sets in `src/hunt/` against one app and prints findings as JSON (exit 1 when there are any). It is GET-only by construction (`probe.ts` has no other method), same-origin only, and ends after one pass. | |
| 4 | ||
| 5 | | Lane | Module | Detectors | | |
| 6 | |---|---|---| | |
| 7 | | Front door | `door.ts` | personal pages send anonymous visitors to sign-in with `next=`; public pages answer 200; unknown path is 404 | | |
| 8 | | UI (links) | `links.ts` | every link on the top pages: no 404/5xx, and a link landing on `/` must be labelled Home (#5844) | | |
| 9 | | Contract | `contract.ts` | no OpenAPI GET route answers 5xx; the status is documented or a refusal | | |
| 10 | ||
| 11 | A finding's `key` is stable (`detector:subject`): one issue per key, a comment only when the evidence changes. | |
| 12 | ||
| 13 | Not built yet: headless-browser lane (buttons, console errors, fold, overflow), flows, speed, the schedule (post-release and 08:00Z), filing issues, the KPI card on home, and the weekly retro. |
docs/MCP.md +145 −84
| @@ -25,87 +25,124 @@ for a tunnel and a forge that sleeps. | ||
| 25 | 25 | |
| 26 | 26 | ## Tools |
| 27 | 27 | |
| 28 | | tool | does | writes | | |
| 29 | | -------------- | ------------------------------------------------------------------------------------------------- | ------ | | |
| 30 | | `apps` | the apps you can see: live or not, where served, how each runs itself, what is working | | | |
| 31 | | `new_app` | `{ name, description?, owner?, visibility?, agent?, pick? }`: make an app from a sentence; answers `{ repo, url, issue, agent, run }` (`run` is the first run's state, or `none`) and draws the `ui://forge/app` card: name, production URL, first issue, agent, first run; refused as `POST /api/v1/apps` is (unverified, app_limit, no_such_agent, name_taken) | yes | | |
| 32 | | `repo` | `{ repo }`: one repository's description, visibility, autonomy, `audience { level, sentence }` and `provenance` (where a migrated one came from, `null` when hidden), the same as `GET /api/v1/repos/:owner/:name` | | | |
| 33 | | `repo_settings` | `{ repo, description?, visibility? }` (admin token): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid` | yes | | |
| 34 | | `tell` | a sentence becomes an issue, a builder is picked, a run starts on the crew's next tick | yes | | |
| 35 | | `thought` | `{ id }`: where one of your thoughts went (its id comes from `tell` without a repo): the placement, and the earlier thoughts it repeats or takes back and the later ones that did the same; not yours and not there answer alike, `not_found` | | | |
| 36 | | `say` | speak on an issue or a pull; a working builder hears it as its next step | yes | | |
| 37 | | `issue` | `{ repo, number }`: one issue's title, state, closeReason, body, labels, assignee, comments (author, authorIsAgent, body, at) and blockedBy/blocks, as `GET …/issues/:number`; a sealed one you cannot see is not found | | | |
| 38 | | `pull` | `{ repo, number }`: a pull's title, state, head and base, and for an open pull whether it merges into the base's current head (`mergeable`) and the paths that stop it (`conflicts`), and `check: { state, baseOid }`: the latest check's state and the base tip it was merged with (empty when it merged nothing); `mergeable` and `conflicts` are the same fields as `GET …/pulls/:number`, `check` is `state` and `run.baseOid` from `GET …/pulls/:number/checks` | | | |
| 39 | | `edit` | a new title or body for an issue or a pull: its author's, or a writer's; an agent edits only what it wrote | yes | | |
| 40 | | `close` | `{ repo, number, state?, reason?, into? }`: close an issue or a pull (`state` closed by default) or reopen it (`open`); the same rules and refusals as `PATCH …/issues/:number`: an agent closes only what the rules give it and reopens nothing; answers `state` and `closeReason` | yes | | |
| 41 | | `pulls` | `{ repo, state?, limit? }`: a repository's pulls, newest first, one brief line each: `number`, `title`, `author`, `head`, `check` (state), `approvals`, `changesRequested`, `mergeable` (null once closed); `state` open (default) or closed, `limit` 1-50 (default 20); no bodies, no diffs | no | | |
| 42 | | `read_file` | a file (utf-8, or base64 for binary) or a directory listing at a ref, as GET …/contents | no | | |
| 43 | | `seal` | `{ repo, number, sealed }`: seal a security report (and the pull that fixes it) so only writers and the crew see it, or unseal it for every reader; a writer's, recorded | yes | | |
| 44 | | `secrets` | `{ scope, ref?, action, name?, value? }` (forge admin): `list` the names and timestamps of the forge's sealed secrets, `set` or `remove` one; `scope` is forge, org or repo, `ref` the org or `owner/name`; a value is never read back | yes | | |
| 45 | | `org_teams` | `{ org, action, team, user?, permission? }` (admin-scope token, an org owner): `create` a team (`permission` read, write or admin; read by default), `add_member` a `user`, or `remove` the team; the same as POST/DELETE `/api/v1/orgs/:org/teams` | yes | | |
| 46 | | `now` | what the crew is doing right now: who, on what, since when, at what cost; a planner that declined the direction and waits for you comes first (`run: null`, its words in `says`) | | | |
| 47 | | `next_steps` | on a spawned forge, your first three steps and whether each is done; empty elsewhere or for anyone but its owner | | | |
| 48 | | `returns` | `{ repo?, days? }`: what the crew's tokens bought over the last `days` (1–90, default 7): dollars, runs, changes landed, cost per change; `repo` narrows it to one app of yours | | | |
| 49 | | `stop` | stop one run by its id from `now` | yes | | |
| 50 | | `health` | how this forge is: the version and commit it runs, draining or not, the rollout and its incidents | | | |
| 51 | | `system` | the machine the forge runs on, now: CPU, load, memory, disk, network, processes; a forge admin, or an agent granted `telemetry:read` | | | |
| 52 | | `cloud_accounts` | the forge's cloud accounts, each attached provider token with its use, verification, write permission and today's calls; a forge admin only (counted as a write so a `ro` token never lists them) | yes | | |
| 53 | | `cloud_account` | `{ verb, provider, name, value?, to?, allowed?, repo? }`: change a cloud account: `attach` or `rotate` a token (`value`), `verify` it, `rename` it (`to`), `remove` it, `allow_writes` (`allowed` true or false) or `audit` (`repo` owner/name); a forge admin with an admin-scope token; answers a one-line `says` | yes | | |
| 54 | | `audit` | who can do what, per app, read from its contract.json in git: yes, own or no per door, and whether outsiders may direct its crew (`crewOutsiders`) | | | |
| 55 | | `account_verify` | `{ username }`: mark a person's email verified, as `POST …/admin/accounts/:username/verify` does; a person admin's, with an admin token | yes | | |
| 56 | | `outsiders` | `{ repo, on?, dryRun? }`: whether people who cannot write may direct the crew; with `on`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes | | |
| 57 | | `origins` | `{ action, id? }`: `list` your connected origins, `repos` the repositories one holds (`id`; `mirroredAs` says which are already here), or `sync` one now; the same as `GET /api/v1/user/origins`, `…/:id/repos` and `POST …/:id/sync`, for you only, an admin token as there; never a credential in an answer | yes | | |
| 58 | | `decisions_by` | `{ repo, by?, dryRun? }`: the standing rule for a repository's hand-overs (`me`, `decider`, `decider_tell`); with `by`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes | | |
| 59 | | `archive` | `{ repo | repos, archived?, dryRun? }`: archive (true) or wake (false) a repository, by name; planned first (`dryRun` is true unless `false`); only the repository's admin with an admin token, never an agent. `repos` (at most 50) runs the fleet `archive` operation over them, answers each one's outcome and the `operation` id; `limb` with `action: "undo"`, that `operation` and any one of the repositories as `app` reverts it for a day | yes | | |
| 60 | | `events` | `{ repo, limit?, cursor? }`: the repository's events, newest first, as you may see them (a webhook's URL and an app's variable names are the admins'): `{ items, next_cursor }`, `limit` 1 to 200 (default 50), `cursor` from `next_cursor` | no | | |
| 61 | | `reports` | `{ repo, id?, action? }`: the waiting reports from outsiders, each `from: "outside"` (their words are unchecked); with `id` and `action` (`accept` opens it as an issue marked as from outside, `dismiss` closes it). A person who writes the repository only; needs an `rw` token | yes | | |
| 62 | | `trail` | `{ repo, shown?, dryRun? }`: where a migrated repository came from (`provenance`: source, sourceUrl, parents, migratedAt) and whether it is shown; with `shown`, shows or hides the trail — planned first (`dryRun` is true unless `false`), only the repository's admin with an admin token, never an agent. Hiding keeps the record; a hidden one reads `null` to anyone but an admin | yes | | |
| 63 | | `branches` | `{ repo, name?, action?, from?, kind? }`: without `name`, lists the branches; `kind: "tags"` lists the tags instead (as GET `/api/v1/repos/:owner/:name/tags` does, newest first; no `name` or `action`); with `name` and `action` (`create` from `from`, or `delete`) it does what the branches page does: the default branch is never deleted, only a writer may act | yes | | |
| 64 | | `migrate` | `{ url, name?, crew? }` brings a public repository in by URL (history only; nothing reaches back) and answers `{ job, state, url }`; `{ job }` alone reads that job. Same validation, scope (`rw`) and private-address refusal as `POST /api/v1/migrate` | yes | | |
| 65 | | `commits` | `{ repo, ref?, limit? }`: a branch's recent commits, newest first (`limit` 1–100, default 30; refused outside that, where REST clamps), as `GET …/commits` answers | | | |
| 66 | | `probe` | knock on a running app's doors as nobody, a user and an admin; the ones that disobey its contract | | | |
| 67 | | `following` | where a fork stands against what it follows, and what the crew is doing about it | | | |
| 68 | | `spawn` | `{ name, apps?, crew?, dryRun? }`: a child forge, planned first (`dryRun` is true unless `false`); an admin's, and an `ro` token may plan but not make | yes | | |
| 69 | | `agent` | `{ action, username, … }`: `create` a crew agent, `update` its `model`, `brief` or `budgetUsd`, or `remove` it; an admin's, with an `admin` token, as `/api/v1/agents` | yes | | |
| 70 | | `claim_link` | `{ name }`: a new claim link for a child you spawned that nobody has claimed; the old one stops working. An admin's | yes | | |
| 71 | | `upstream` | `{ repo, enabled?, url?, branch?, check? }`: the repository a fork follows (an admin reads it); with `enabled` sets it, with `check: true` checks it now; setting and checking need an admin token | yes | | |
| 72 | | `take_updates` | a fork takes its parent's updates when git can do it alone; a conflict is refused. On a spawned forge's code repository it opens the one `forge/take-updates` pull and never moves the default branch | yes | | |
| 73 | | `converge` | the fork's crew merges where both sides changed the same files; comes back as a pull | yes | | |
| 74 | | `asked` | `{ repo?, show?, order? }`: what people asked the crew for, by default nothing merged yet and oldest first: who and when, the pulls that close it, the crew's last activity, waiting/building/shipped/closed, stale when not shipped in three days and flagged when stale with nothing built; repositories you can write | | | |
| 75 | | `assigned` | `{ limit? }`: the open issues and pulls assigned to you in every repository you can still read (repository, number, title, kind, state), as `GET /api/v1/user/assigned` | | | |
| 76 | | `app_members` | `{ repo, members?, dryRun? }`: the people a private app names, who may enter it and its previews and nothing else; a writer (never an agent) changes the list with an admin-scope token | yes | | |
| 77 | | `explore` | `{ query? }`: the apps and people you can see, ranked by forks, ships, use and freshness, with their numbers; `kind:` `sort:` and words in one line | | | |
| 78 | | `search` | `{ q, kind?, repo? }`: issues, pulls, repositories and code you can read, the same results as /search; `repo` keeps to one | | | |
| 79 | | `feed` | `{ limit?, cursor? }`: your home timeline — tells, replies, runs, changes and looks — ranked, with who, what, why and a link; the same items as `GET /api/v1/feed` | | | |
| 28 | <!-- tools:begin: generated by `bun scripts/mcp-tools.ts` from each tool's `doc` --> | |
| 29 | ||
| 30 | | tool | does | writes | | |
| 31 | | ---- | ---- | ------ | | |
| 32 | | `access` | `{ since?, ua?, path? }`: what outside agents tried: the redacted log of non-browser requests to public paths, newest first; `since` an ISO time (default a day, at most 14 days), `ua` part of the user agent, `path` a prefix; a forge admin's | yes | | |
| 33 | | `account_role` | `{ username, role, usdPerMonth?, dryRun? }`: make a person a `member`, or a `guest` again, with an optional starter allowance (`usdPerMonth`, 0.01 to 10000, promoting only); planned first (`dryRun` is true unless `false`) | yes | | |
| 34 | | `account_suspend` | `{ username, suspended }`: suspend a person's account, or unsuspend it with `false`; their sessions and tokens stop at once; the API's rules (not yourself, another admin or an agent; not the only owner of an organization); an admin token | yes | | |
| 35 | | `account_verify` | `{ username }`: mark a person's email verified, as `POST …/admin/accounts/:username/verify` does; a person admin's, with an admin token | yes | | |
| 36 | | `accounts` | `{ cursor?, limit? }`: the forge's accounts, newest first: `username`, `role`, `verified`, `suspended`, `created`, and `next` (a cursor, or null); `limit` 1-50 (default 20); a person admin's | | | |
| 37 | | `agent` | `{ action, username, … }`: `create` a crew agent, `update` its `model`, `brief` or `budgetUsd`, or `remove` it; an admin's, with an `admin` token, as `/api/v1/agents` | yes | | |
| 38 | | `app_deploy` | `{ repo, env, action }`: `redeploy` or `stop` an app's `production` or a pull's `pull-N` preview; a writer's, queued as `POST …/app/:env/redeploy` and `…/stop` are; answers `{ queued, run }` or `{ stopped }` | yes | | |
| 39 | | `app_env` | `{ repo, action, name?, value?, scope? }`: `list` an app's variable names and scopes, `set` one, or `unset` it, in `all` (default), `production` or `preview`; the API's rules and errors, an admin of the repository with an admin-scope token; a value is never read back | yes | | |
| 40 | | `app_members` | `{ repo, members?, dryRun? }`: the people a private app names, who may enter it and its previews and nothing else; a writer (never an agent) changes the list with an admin-scope token | yes | | |
| 41 | | `apps` | the apps you can see: live or not, where served, how each runs itself, what is working | | | |
| 42 | | `archive` | `{ repo | repos, archived?, dryRun? }`: archive (true) or wake (false) a repository, by name; planned first (`dryRun` is true unless `false`); only the repository's admin with an admin token, never an agent. `repos` (at most 50) runs the fleet `archive` operation over them, answers each one's outcome and the `operation` id; `limb` with `action: "undo"`, that `operation` and any one of the repositories as `app` reverts it for a day | yes | | |
| 43 | | `asked` | `{ repo?, show?, order? }`: what people asked the crew for, by default nothing merged yet and oldest first: who and when, the pulls that close it, the crew's last activity, waiting/building/shipped/closed, stale when not shipped in three days and flagged when stale with nothing built; repositories you can write | | | |
| 44 | | `assigned` | `{ limit? }`: the open issues and pulls assigned to you in every repository you can still read (repository, number, title, kind, state), as `GET /api/v1/user/assigned` | | | |
| 45 | | `audit` | who can do what, per app, read from its contract.json in git: yes, own or no per door, and whether outsiders may direct its crew (`crewOutsiders`) | | | |
| 46 | | `board_delete` | `{ slug }` (person admins): delete a board by slug; its history keeps it | yes | | |
| 47 | | `board_pins` | `{ op?, slug?, title?, by? }` (person admins): without `op`, the panels pinned to your home (`slug`, `title`); `pin` or `unpin` a panel by board `slug` and panel `title`, or `move` it up or down with `by` (-1 or 1) | yes | | |
| 48 | | `board_write` | `{ slug, board }` (person admins): write a whole board under a slug, made or replaced: `{ title, range, refresh, panels: [{ title, chart, query, w, h }] }` | yes | | |
| 49 | | `boards` | `{ slug?, panel?, from?, to?, step? }` (person admins): without `slug`, lists the forge's boards (slug, title, range, refresh, panels); with `slug`, that board; with `panel` (place from 0, up to 23), that panel's data over the `from`/`to` window and `step` | | | |
| 50 | | `branches` | `{ repo, name?, action?, from?, kind? }`: without `name`, lists the branches; `kind: "tags"` lists the tags instead (as GET `/api/v1/repos/:owner/:name/tags` does, newest first; no `name` or `action`); with `name` and `action` (`create` from `from`, or `delete`) it does what the branches page does: the default branch is never deleted, only a writer may act | yes | | |
| 51 | | `claim_link` | `{ name }`: a new claim link for a child you spawned that nobody has claimed; the old one stops working. An admin's | yes | | |
| 52 | | `close` | `{ repo, number, state?, reason?, into? }`: close an issue or a pull (`state` closed by default) or reopen it (`open`); the same rules and refusals as `PATCH …/issues/:number`: an agent closes only what the rules give it and reopens nothing; answers `state` and `closeReason` | yes | | |
| 53 | | `cloud_account` | `{ verb, provider, name, value?, to?, allowed?, repo? }`: change a cloud account: `attach` or `rotate` a token (`value`), `verify` it, `rename` it (`to`), `remove` it, `allow_writes` (`allowed` true or false) or `audit` (`repo` owner/name); a forge admin with an admin-scope token; answers a one-line `says` | yes | | |
| 54 | | `cloud_accounts` | the forge's cloud accounts, each attached provider token with its use, verification, write permission and today's calls; a forge admin only (counted as a write so a `ro` token never lists them) | yes | | |
| 55 | | `commits` | `{ repo, ref?, limit?, oid? }`: a branch's recent commits, newest first (`limit` 1–100, default 30; refused outside that, where REST clamps), as `GET …/commits` answers; with `oid` (4–64 hex) one commit with its diff and its check, as `GET …/commits/{oid}` and `…/check` answer | | | |
| 56 | | `confirm_wait` | `{ app, issue, blocker }`: a person says `issue` may go ahead although `blocker` closed as dropped or split; the API's confirm action, so writers only and never the crew | yes | | |
| 57 | | `contribute` | for any arriving agent: what this forge is, its bottleneck, open “help wanted” issues, how to propose | | | |
| 58 | | `converge` | the fork's crew merges where both sides changed the same files; comes back as a pull | yes | | |
| 59 | | `decisions_by` | `{ repo, by?, dryRun? }`: the standing rule for a repository's hand-overs (`me`, `decider`, `decider_tell`); with `by`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes | | |
| 60 | | `edit` | a new title or body for an issue or a pull: its author's, or a writer's; an agent edits only what it wrote | yes | | |
| 61 | | `egress_grants` | `{ repo, op?, destination? }`: the private `host:port` destinations an app's forge.json asks for and which are granted; `op` grant or revoke by a site admin (never an agent), and every op needs an admin-scope token; the same as the settings page and `/api/v1/repos/:owner/:name/egress-grants` | yes | | |
| 62 | | `email_verify` | no input: send the caller a new verification email, with the API's rate limit and errors; the answer never carries the link | yes | | |
| 63 | | `events` | `{ repo, limit?, cursor? }`: the repository's events, newest first, as you may see them (a webhook's URL and an app's variable names are the admins'): `{ items, next_cursor }`, `limit` 1 to 200 (default 50), `cursor` from `next_cursor` | | | |
| 64 | | `explore` | `{ query? }`: the apps and people you can see, ranked by forks, ships, use and freshness, with their numbers; `kind:` `sort:` and words in one line | | | |
| 65 | | `family` | the forge that sent this one and, for a site admin, those it sent, with state and version | | | |
| 66 | | `feed` | `{ limit?, cursor? }`: your home timeline — tells, replies, runs, changes and looks — ranked, with who, what, why and a link; the same items as `GET /api/v1/feed`; `quietRuns` counts agent runs of the last 24 h that pushed, opened or said nothing, which the timeline leaves out | | | |
| 80 | 67 | | `feed_chips` | `{ kind?, value?, hidden? }`: the feed chips you switched off, which `feed` and `asks` leave out; with `kind` (`kind` or `person`), `value` and `hidden` it switches one off or on | yes | |
| 81 | | `make_it_yours` | `{ repo, name?, visibility?, dryRun? }`: a fork of an app you can see, as your own app, following the original; code and history copied, data and secrets not; private unless `visibility` is public (a public original only); at most 5 copies an account a day; plans unless `dryRun` is false | yes | | |
| 82 | | `origin_apps` | `{ action, id?, host?, kind?, clientId?, clientSecret? }`: `list` your OAuth apps for connecting origins, `add` one (a `host`, or `kind` github), or `remove` one by `id`; the API's rules and errors, an admin-scope token; a secret is never read back, only `hasSecret` | yes | | |
| 83 | | `front_page` | `{ pinned?, hidden?, weights?, dryRun? }`: the front page as a stranger sees it, ranked, with numbers; a site admin sets what is pinned (first public one featured), hidden, and what counts (weights of forks, ships, use, fresh, 0 to 10) | yes | | |
| 84 | | `invites` | `{ action, id? }`: `list` the outstanding invites (state and expiry, never a link) or `revoke` one by `id`; a person admin with an admin token, stricter than the API's list, which an `ro` token may read | yes | | |
| 85 | | `map` | an app's plan: ready now, waiting on what, the critical path, where the crew is, parked twice and why (`app`); draws the `ui://forge/map` card | | | |
| 86 | | `milestones` | `{ app, issue? }`: how far each thing asked for is (and, with `issue`, whether you watch it: `watching`), from the dependency tree: the plan's limbs with their weights, or one milestone opened (who is building, what is blocked and on what, what merged in 7 days, an estimate, and for an owner `spend`: dollars, changes landed ever, the costliest three issues) | | | |
| 87 | | `limb` | `{ app, issue, action, reason?, pillar?, operation?, dryRun? }`: defer, resume or close a whole limb as not doing, or undo an operation; plans unless `dryRun` is false, and applying takes an admin token | yes | | |
| 88 | | `watch` | `{ app, issue, watch? }`: watch a milestone, or stop with `watch: false`: one item in your feed that follows it, and one push to your phone when it lands | yes | | |
| 89 | | `runs` | `{ repo, limit? }`: the repository's recent runs, newest first (id, kind, state, issue or pull number, started, ended), 1–50, default 20; read as the runs page reads them | | | |
| 90 | | `run_log` | `{ repo, run, tail? }`: a run's log, or its last `tail` lines (1–2000), with the REST route's access: a hidden log or unreadable repository is not found | | | |
| 91 | | `review` | `{ repo, number, verdict, reason? }`: approve a pull (`approve`) or request changes (`changes`, with a `reason`), as the page does; a writer's or the crew's, and never your own pull | yes | | |
| 92 | | `threads` | `{ repo, number, anchor?, resolved? }`: a pull's review threads with their comments; with `anchor` (from the list) resolve it (`resolved` true, the default) or reopen it (false), by the API's rules: a writer or someone who commented in the thread | yes | | |
| 93 | | `usage` | `{ repo, days? }`: what the crew's runs spent — tokens, cost, wall time — by subscription, agent, issue, and each account's 5-hour and weekly standing; a writer's | | | |
| 94 | | `labels` | `{ repo, number, labels }`: set an issue's or a pull's labels to exactly these (`[]` clears); only labels the repository has, by a writer | yes | | |
| 95 | | `repo_labels` | `{ repo, action?, name?, color?, id? }`: list (`list`, the default; a read-only token may), create (`create`, `name`, `color` six hex digits) or remove (`remove`, `id`) the repository's labels, as `GET`/`POST …/labels` and `DELETE …/labels/:id`; create and remove need an admin token and a repository admin | yes | | |
| 96 | | `wait_for` | `{ app, issue, blockedBy, stop? }`: the issue waits for another, or stops with `stop: true`; the page's rules, and the answer carries the issue's URL | yes | | |
| 97 | | `confirm_wait` | `{ app, issue, blocker }`: a person says `issue` may go ahead although `blocker` closed as dropped or split; the API's confirm action, so writers only and never the crew | yes | | |
| 98 | | `hold` | `{ app, pull, why?, release?, dryRun? }`: hold a pull so no rule reviews or lands it, or let it go; a person who can write, never an agent; plans unless `dryRun: false` | yes | | |
| 99 | | `app_env` | `{ repo, action, name?, value?, scope? }`: `list` an app's variable names and scopes, `set` one, or `unset` it, in `all` (default), `production` or `preview`; the API's rules and errors, an admin of the repository with an admin-scope token; a value is never read back | yes | | |
| 100 | | `email_verify` | no input: send the caller a new verification email, with the API's rate limit and errors; the answer never carries the link | yes | | |
| 101 | | `plan` | `{ app, issues }`: open up to 12 linked issues, all or none (see below) | yes | | |
| 102 | | `prompts` | `{ repo, action, kind?, token?, at?, id? }`: list, add, run or remove an app's prompt sources (Instagram), as the `…/prompts` API does; the token goes in once and is never shown; listed only for an admin-scope token, and only the repository's admin may use it | yes | | |
| 103 | | `account_suspend` | `{ username, suspended }`: suspend a person's account, or unsuspend it with `false`; their sessions and tokens stop at once; the API's rules (not yourself, another admin or an agent; not the only owner of an organization); an admin token | yes | | |
| 104 | | `account_role` | `{ username, role, usdPerMonth?, dryRun? }`: make a person a `member`, or a `guest` again, with an optional starter allowance (`usdPerMonth`, 0.01 to 10000, promoting only); planned first (`dryRun` is true unless `false`) | yes | | |
| 105 | | `mint_invite` | `{ days? }`: mint a single-use invite link that expires in `days` (1–30, default 7) and is shown once; a person admin's, with an admin token | yes | | |
| 106 | | `signup` | `{ mode?, dryRun? }`: who may sign up: `open` (default), `invite` (only a person with an open invite link) or `closed` (no new accounts); without `mode` it reads the setting, with `mode` it plans first (`dryRun` is true unless `false`), and applying needs an admin token | yes | | |
| 107 | | `access` | `{ since?, ua?, path? }`: what outside agents tried: the redacted log of non-browser requests to public paths, newest first; `since` an ISO time (default a day, at most 14 days), `ua` part of the user agent, `path` a prefix; a forge admin's | yes | | |
| 108 | | `whoami_can` | no input: your role and that role's row of the roles table, each ability yes or no | | | |
| 68 | | `follow_mode` | `{ repo, … }`: choose how a spawned forge follows its parent, `tell-me` or `take-updates`; its `forge` repository's admin only | yes | | |
| 69 | | `following` | where a fork stands against what it follows, and what the crew is doing about it | | | |
| 70 | | `forge_proposals` | `{ repo }`: what this forge proposed to its parent, newest first; `reachable` is false if the parent did not answer | | | |
| 71 | | `forges` | an admin's list of the forges sent from here: name, address, whom for, apps, claimed or not, last activity | | | |
| 72 | | `front_page` | `{ pinned?, hidden?, weights?, dryRun? }`: the front page as a stranger sees it, ranked, with numbers; a site admin sets what is pinned (first public one featured), hidden, and what counts (weights of forks, ships, use, fresh, 0 to 10) | yes | | |
| 73 | | `health` | how this forge is: the version and commit it runs, draining or not, the rollout and its incidents | | | |
| 74 | | `hold` | `{ app, pull, why?, release?, dryRun? }`: hold a pull so no rule reviews or lands it, or let it go; a person who can write, never an agent; plans unless `dryRun: false` | yes | | |
| 75 | | `hooks` | `{ repo, action, url, secret, kinds, id }`: `list`, `add` (`secret`, 16–200 characters, is required) or `remove` the repository's webhooks, as `…/hooks`; an admin-scope token on a repository you administer, and a secret is never shown | yes | | |
| 76 | | `invites` | `{ action, id? }`: `list` the outstanding invites (state and expiry, never a link) or `revoke` one by `id`; a person admin with an admin token, stricter than the API's list, which an `ro` token may read | yes | | |
| 77 | | `issue` | `{ repo, number }`: one issue's title, state, closeReason, body, labels, assignee, comments (author, authorIsAgent, body, at) and blockedBy/blocks, as `GET …/issues/:number`; a sealed one you cannot see is not found | | | |
| 78 | | `labels` | `{ repo, number, labels }`: set an issue's or a pull's labels to exactly these (`[]` clears); only labels the repository has, by a writer | yes | | |
| 79 | | `limb` | `{ app, issue, action, reason?, pillar?, operation?, dryRun? }`: defer, resume or close a whole limb as not doing, or undo an operation; plans unless `dryRun` is false, and applying takes an admin token | yes | | |
| 80 | | `make_it_yours` | `{ repo, name?, visibility?, dryRun? }`: a fork of an app you can see, as your own app, following the original; code and history copied, data and secrets not; private unless `visibility` is public (a public original only); at most 5 copies an account a day; plans unless `dryRun` is false | yes | | |
| 81 | | `map` | an app's plan: ready now, waiting on what, the critical path, where the crew is, parked twice and why (`app`); draws the `ui://forge/map` card | | | |
| 82 | | `migrate` | `{ url, name?, crew? }` brings a public repository in by URL (history only; nothing reaches back) and answers `{ job, state, url }`; `{ job }` alone reads that job. Same validation, scope (`rw`) and private-address refusal as `POST /api/v1/migrate` | yes | | |
| 83 | | `milestones` | `{ app, issue? }`: how far each thing asked for is (and, with `issue`, whether you watch it: `watching`), from the dependency tree: the plan's limbs with their weights, or one milestone opened (who is building, what is blocked and on what, what merged in 7 days, an estimate, and for an owner `spend`: dollars, changes landed ever, the costliest three issues) | | | |
| 84 | | `mint_invite` | `{ days? }`: mint a single-use invite link that expires in `days` (1–30, default 7) and is shown once; a person admin's, with an admin token | yes | | |
| 85 | | `mirror_set` | `{ action, endpoint?, bucket?, region?, accessKey?, secretKey? }` (forge admin, admin-scope token): `set` seals the off-box snapshot mirror, `forget` clears it; the Backups page's rules and refusals, a blank field keeps what was sealed; answers `{ place, says }`, never a key | yes | | |
| 86 | | `new_app` | `{ name, description?, owner?, visibility?, agent?, pick? }`: make an app from a sentence; answers `{ repo, url, issue, agent, run }` (`run` is the first run's state, or `none`) and draws the `ui://forge/app` card: name, production URL, first issue, agent, first run; refused as `POST /api/v1/apps` is (unverified, app_limit, no_such_agent, name_taken) | yes | | |
| 87 | | `next_steps` | on a spawned forge, your first three steps and whether each is done; empty elsewhere or for anyone but its owner | | | |
| 88 | | `now` | what the crew is doing right now: who, on what, since when, at what cost; a planner that declined the direction and waits for you comes first (`run: null`, its words in `says`) | | | |
| 89 | | `org_teams` | `{ org, action, team, user?, permission? }` (admin-scope token, an org owner): `create` a team (`permission` read, write or admin; read by default), `add_member` a `user`, or `remove` the team; the same as POST/DELETE `/api/v1/orgs/:org/teams` | yes | | |
| 90 | | `origin_apps` | `{ action, id?, host?, kind?, clientId?, clientSecret? }`: `list` your OAuth apps for connecting origins, `add` one (a `host`, or `kind` github), or `remove` one by `id`; the API's rules and errors, an admin-scope token; a secret is never read back, only `hasSecret` | yes | | |
| 91 | | `origins` | `{ action, id? }`: `list` your connected origins, `repos` the repositories one holds (`id`; `mirroredAs` says which are already here), or `sync` one now; the same as `GET /api/v1/user/origins`, `…/:id/repos` and `POST …/:id/sync`, for you only, an admin token as there; never a credential in an answer | yes | | |
| 92 | | `outsiders` | `{ repo, on?, dryRun? }`: whether people who cannot write may direct the crew; with `on`, planned first (`dryRun` is true unless `false`); set only by the app's admin with an admin token, never an agent | yes | | |
| 93 | | `parent_unlink` | no input: stop signing in through the parent forge, as Settings does; refused when it is the account's last way in, and "Nothing to unlink." when nothing is linked; an admin token | yes | | |
| 94 | | `plan` | `{ app, issues }`: open up to 12 linked issues, all or none (see below) | yes | | |
| 95 | | `preview` | `{ url }`: what the forge pill says of an app host's URL (production or a pull's preview): `{ app, environment, pull: { number, title } \| null, check: "green" \| "red" \| "running" \| null, firstFailure, logUrl, working: [names] }`; `firstFailure` is the check's first failing test or its summary, `logUrl` is set only for someone who may read the log (a writer), `working` names the agents with a run going; a URL that is not one of this forge's app hosts is `invalid`, an app you cannot read is `not_found` and a pull you cannot see is `no_such_pull`, as `repo` and `pull` say | | | |
| 96 | | `probe` | knock on a running app's doors as nobody, a user and an admin; the ones that disobey its contract | | | |
| 97 | | `prompts` | `{ repo, action, kind?, token?, at?, id? }`: list, add, run or remove an app's prompt sources (Instagram), as the `…/prompts` API does; the token goes in once and is never shown; listed only for an admin-scope token, and only the repository's admin may use it | yes | | |
| 98 | | `propose_to_parent_forge` | `{ repo }`: offer this forge's landed change to its parent as a pull on `child/<name>/…`; the same tip answers with that pull | yes | | |
| 99 | | `pull` | `{ repo, number }`: a pull's title, state, head and base, and for an open pull whether it merges into the base's current head (`mergeable`) and the paths that stop it (`conflicts`), and `check: { state, baseOid }`: the latest check's state and the base tip it was merged with (empty when it merged nothing); `mergeable` and `conflicts` are the same fields as `GET …/pulls/:number`, `check` is `state` and `run.baseOid` from `GET …/pulls/:number/checks`; draws the `ui://forge/pull` card: `#N title`, state with check and conflicts while open, `head → base` linked to the pull, and the preview link when the pull has an environment | | | |
| 100 | | `pulls` | `{ repo, state?, limit? }`: a repository's pulls, newest first, one brief line each: `number`, `title`, `author`, `head`, `check` (state), `approvals`, `changesRequested`, `mergeable` (null once closed); `state` open (default) or closed, `limit` 1-50 (default 20); no bodies, no diffs | | | |
| 101 | | `read_file` | a file (utf-8, or base64 for binary) or a directory listing at a ref, as GET …/contents | | | |
| 102 | | `repo` | `{ repo }`: one repository's description, visibility, autonomy, `audience { level, sentence }` and `provenance` (where a migrated one came from, `null` when hidden), the same as `GET /api/v1/repos/:owner/:name` | | | |
| 103 | | `repo_labels` | `{ repo, action?, name?, color?, id? }`: list (`list`, the default; a read-only token may), create (`create`, `name`, `color` six hex digits) or remove (`remove`, `id`) the repository's labels, as `GET`/`POST …/labels` and `DELETE …/labels/:id`; create and remove need an admin token and a repository admin | yes | | |
| 104 | | `repo_settings` | `{ repo, description?, visibility? }` (admin token): change a repository's description and visibility as `PATCH /api/v1/repos/:owner/:name` does, for the same callers (a repository admin); answers `{ repo, description, visibility }`; a visibility other than public or private is `invalid` | yes | | |
| 105 | | `reports` | `{ repo, id?, action? }`: the waiting reports from outsiders, each `from: "outside"` (their words are unchecked); with `id` and `action` (`accept` opens it as an issue marked as from outside, `dismiss` closes it). A person who writes the repository only; needs an `rw` token | yes | | |
| 106 | | `returns` | `{ repo?, days? }`: what the crew's tokens bought over the last `days` (1–90, default 7): dollars, runs, changes landed, cost per change; `repo` narrows it to one app of yours | | | |
| 107 | | `review` | `{ repo, number, verdict, reason? }`: approve a pull (`approve`) or request changes (`changes`, with a `reason`), as the page does; a writer's or the crew's, and never your own pull | yes | | |
| 108 | | `run_log` | `{ repo, run, tail? }`: a run's log, or its last `tail` lines (1–2000), with the REST route's access: a hidden log or unreadable repository is not found | | | |
| 109 | | `runs` | `{ repo, limit? }`: the repository's recent runs, newest first (id, kind, state, issue or pull number, started, ended), 1–50, default 20; read as the runs page reads them | | | |
| 110 | | `say` | speak on an issue or a pull; a working builder hears it as its next step | yes | | |
| 111 | | `seal` | `{ repo, number, sealed }`: seal a security report (and the pull that fixes it) so only writers and the crew see it, or unseal it for every reader; a writer's, recorded | yes | | |
| 112 | | `search` | `{ q, kind?, repo? }`: issues, pulls, repositories and code you can read, the same results as /search; `repo` keeps to one | | | |
| 113 | | `secrets` | `{ scope, ref?, action, name?, value? }` (forge admin): `list` the names and timestamps of the forge's sealed secrets, `set` or `remove` one; `scope` is forge, org or repo, `ref` the org or `owner/name`; a value is never read back | yes | | |
| 114 | | `sever` | `{ repo }`: cut a spawned forge's link to the forge its code came from; its `forge` repository's owner only; deletes nothing | yes | | |
| 115 | | `signup` | `{ mode?, dryRun? }`: who may sign up: `open` (default), `invite` (only a person with an open invite link) or `closed` (no new accounts); without `mode` it reads the setting, with `mode` it plans first (`dryRun` is true unless `false`), and applying needs an admin token | yes | | |
| 116 | | `spawn` | `{ name, apps?, crew?, dryRun? }`: a child forge, planned first (`dryRun` is true unless `false`); an admin's, and an `ro` token may plan but not make | yes | | |
| 117 | | `ssh_keys` | `{ action?, title?, key?, id? }`: list your own SSH keys (default), add one (`key` is an authorized_keys line, `title` optional) or remove one by `id`; the API's rules and errors, add and remove need an `rw` token | yes | | |
| 118 | | `stop` | stop one run by its id from `now` | yes | | |
| 119 | | `subscription_budget` | `{ id, usd }`: set an account's whole-life budget in dollars (up to the `subscription.budget_max_usd` limit), or clear it with `usd: null`, as the Subscriptions page does; a locked budget can only be lowered; a forge admin with an admin token | yes | | |
| 120 | | `subscription_headroom` | `{ id, percent }`: set the whole percent (0–90) of each window the crew leaves for people, as the Subscriptions page does; a forge admin's, with an admin token | yes | | |
| 121 | | `system` | the machine the forge runs on, now: CPU, load, memory, disk, network, processes; a forge admin, or an agent granted `telemetry:read` | | | |
| 122 | | `take_updates` | a fork takes its parent's updates when git can do it alone; a conflict is refused. On a spawned forge's code repository it opens the one `forge/take-updates` pull and never moves the default branch | yes | | |
| 123 | | `telemetry_grant` | `{ agent, on }`: grant an agent `telemetry:read`, or take it back with `false`, as the Telemetry page does; a person admin's, with an admin token; answers `says` | yes | | |
| 124 | | `tell` | a sentence becomes an issue, a builder is picked, a run starts on the crew's next tick | yes | | |
| 125 | | `thought` | `{ id }`: where one of your thoughts went (its id comes from `tell` without a repo): the placement, and the earlier thoughts it repeats or takes back and the later ones that did the same; not yours and not there answer alike, `not_found` | | | |
| 126 | | `threads` | `{ repo, number, anchor?, resolved? }`: a pull's review threads with their comments; with `anchor` (from the list) resolve it (`resolved` true, the default) or reopen it (false), by the API's rules: a writer or someone who commented in the thread | yes | | |
| 127 | | `trail` | `{ repo, shown?, dryRun? }`: where a migrated repository came from (`provenance`: source, sourceUrl, parents, migratedAt) and whether it is shown; with `shown`, shows or hides the trail — planned first (`dryRun` is true unless `false`), only the repository's admin with an admin token, never an agent. Hiding keeps the record; a hidden one reads `null` to anyone but an admin | yes | | |
| 128 | | `upstream` | `{ repo, enabled?, url?, branch?, check? }`: the repository a fork follows (an admin reads it); with `enabled` sets it, with `check: true` checks it now; setting and checking need an admin token | yes | | |
| 129 | | `usage` | `{ repo, days? }`: what the crew's runs spent — tokens, cost, wall time — by subscription, agent, issue, and each account's 5-hour and weekly standing; a writer's | | | |
| 130 | | `wait_for` | `{ app, issue, blockedBy, stop? }`: the issue waits for another, or stops with `stop: true`; the page's rules, and the answer carries the issue's URL | yes | | |
| 131 | | `watch` | `{ app, issue, watch? }`: watch a milestone, or stop with `watch: false`: one item in your feed that follows it, and one push to your phone when it lands | yes | | |
| 132 | | `whoami_can` | `{ kind? }`: your role and that role's row of the roles table, each ability yes or no; `kind: "passkeys"` lists your own passkeys (`{ items }`: id, name, created, lastUsed), people only | | | |
| 133 | ||
| 134 | <!-- tools:end --> | |
| 135 | ||
| 136 | ### Adding a tool | |
| 137 | ||
| 138 | One tool, one file (#5924): `src/http/mcp/tools/<name>.ts` exports `tool`, | |
| 139 | its definition and `run`, and nothing else; its arguments' shared helpers | |
| 140 | are in `src/http/mcp/shared.ts`. Its row in the table above is its `doc`. | |
| 141 | Then run `bun scripts/mcp-tools.ts`: it adds one line to the sorted | |
| 142 | `tools/index.ts` and one row to the table, so two pulls adding two tools | |
| 143 | edit no line in common. `test/mcp-tools.test.ts` holds every tool file to | |
| 144 | the same contract and goes red when either generated file is stale; the | |
| 145 | tool's own behaviour is tested in `test/mcp-<name>.test.ts`. | |
| 109 | 146 | |
| 110 | 147 | ### Room for a new tool |
| 111 | 148 | |
| @@ -122,6 +159,26 @@ a failure names the bytes over and the longest descriptions. | ||
| 122 | 159 | Answers are JSON in a text block; most carry a `says` sentence short enough |
| 123 | 160 | to relay as it is. |
| 124 | 161 | |
| 162 | ## Arguments, in full | |
| 163 | ||
| 164 | `tools/list` keeps every argument description to 60 bytes (`test/mcp-size.test.ts` | |
| 165 | enforces it); `dryRun` reads `false to apply` on every tool that takes it. The | |
| 166 | longer sentences: | |
| 167 | ||
| 168 | - `dryRun`: plans unless it is `false`; anything else changes nothing. `limb` applying takes an admin token. | |
| 169 | - `tell.from`: a path on this forge the issue links to, like `/alice/notes/pulls/3`. `tell.context`: where this was told from, for the builder. | |
| 170 | - `spawn.reveal`, `claim_link.reveal`: put the live claim link in the answer (default false); it is a secret, only when its person reads it. `spawn.fresh`: a fresh app beside the copied ones. `spawn.followMode`: `tell-me` (default) or `take-updates`. `spawn.size`: recorded only, not enforced. `spawn.keepAccess`: stay an owner once claimed. | |
| 171 | - `commits.ref`: branch, tag or commit; the default branch when absent. `report.page`: the http(s) address where the problem was seen. `plan.issues.pillar`: the pillar served, as `"P0"` or `"P0 Trust"`; `later: true` means no pillar and needs `why`. | |
| 172 | - `explore.query`: words, plus `kind:app|person|forge` and `sort:score|forks|ships|use|fresh|name`. | |
| 173 | - `archive.repos`: several repositories, as `owner/name`, to archive in one operation. | |
| 174 | - `milestones.issue`: the number of an issue that waits for others; the limbs when absent. `watch.issue` is the same number; `watch.watch` false stops watching, anything else watches. | |
| 175 | - `limb.reason` (close): why it is not being done, in one sentence. `limb.pillar` (resume): the pillar to return it under. `limb.under` (raise, lower): `top` or a milestone number, only when the limb sits in several places. | |
| 176 | - `asks.hide_kinds`, `asks.hide_people`, `feed.*`: leave out these kinds or usernames; replaces your saved filter. | |
| 177 | - `audit.repo`: one app, as `owner/name`; every app you can see when absent. | |
| 178 | - `model_ceiling.dailyUsd`/`perRunUsd`: 0.01–10000; both null clears; one null is refused. `model_grant.usdPerMonth`: 0 takes the grant back. `account_role.usdPerMonth`: omit or null for none. | |
| 179 | - `hold.why`: why, in one line; it shows on the pull. `runs.limit`: how many, 1 to 50; 20 when absent. | |
| 180 | - `boards.step`: with `panel`, seconds per bucket, or a count of `s`, `m`, `h` or `d`. `access.since`: ISO time; default a day, max 14 days. | |
| 181 | ||
| 125 | 182 | ## Connecting |
| 126 | 183 | |
| 127 | 184 | Mint a token under **Settings → Access tokens** (`rw` to act, `ro` to watch), |
| @@ -167,7 +224,7 @@ can call `apps` and is refused `tell`. | ||
| 167 | 224 | `src/http/oauth.ts`, `src/core/oauth.ts`, `src/web/pages/oauth.ts`, |
| 168 | 225 | `test/oauth-flow.test.ts`. |
| 169 | 226 | |
| 170 | `src/http/mcp.ts`, `src/actions/tell.ts`, `test/mcp.test.ts`. | |
| 227 | `src/http/mcp.ts`, `src/http/mcp/tools/`, `src/actions/tell.ts`, `test/mcp.test.ts`. | |
| 171 | 228 | |
| 172 | 229 | ## `plan` |
| 173 | 230 | |
| @@ -223,11 +280,15 @@ answers | ||
| 223 | 280 | |
| 224 | 281 | ## Cards, the contract and the plugins (#1116) |
| 225 | 282 | |
| 226 | - **Cards.** `apps`, `new_app`, `now`, `asks`, `milestones`, `map` and `feed` name a `ui://` resource in | |
| 283 | - **Cards.** `apps`, `new_app`, `now`, `asks`, `milestones`, `map`, `feed` and `pull` name a `ui://` resource in | |
| 227 | 284 | `_meta.ui.resourceUri` (MCP Apps, SEP-1865): `ui://forge/app`, `run`, |
| 228 | `decision`, `wave`, `map`, `feed`. The Plan card (`map`) shows one row per pillar with | |
| 285 | `decision`, `wave`, `map`, `feed`, `pull`. The Plan card (`map`) shows one row per pillar with | |
| 229 | 286 | its ready, working and waiting counts, and the first five ready issues linked |
| 230 | to their pages; it has no actions. `resources/list` and `resources/read` serve one small | |
| 287 | to their pages; it has no actions. | |
| 288 | The Apps card (`apps`) links each `owner/name` row to the app's page on the forge and adds a | |
| 289 | linked production row when the app has an http(s) URL; the `new_app` card links its | |
| 290 | Production row the same way. Any other address stays plain text, never a link. | |
| 291 | `resources/list` and `resources/read` serve one small | |
| 231 | 292 | sandboxed page, which draws the `structuredContent.card` model that the |
| 232 | 293 | tool result carries, with `textContent` only. The model is built in |
| 233 | 294 | `src/web/studio/cards.ts`. A card's |
docs/ORIGINS.md +1 −1
| @@ -607,7 +607,7 @@ POST /api/v1/repos/:o/:n/sync sync this mirror now; on a fork, | ||
| 607 | 607 | POST /api/v1/repos/:o/:n/origin/reconnect {originId} → repo JSON; re-attach a |
| 608 | 608 | detached mirror (admin token, repo |
| 609 | 609 | admin, own origin; else 404/422 code) |
| 610 | GET /api/v1/user/pins PUT/DELETE /api/v1/user/pins/:owner/:name | |
| 610 | GET /api/v1/user/pins ({items, next_cursor}; ?limit=1..200, ?cursor=) PUT/DELETE /api/v1/user/pins/:owner/:name | |
| 611 | 611 | |
| 612 | 612 | POST /api/v1/migrate {source: {url} | {originId, fullName}, |
| 613 | 613 | owner?, name?, visibility?, |
docs/SPAWN.md +1
| @@ -16,6 +16,7 @@ and user accounts. The child mints its own. A test in #420 and #422 proves it. | ||
| 16 | 16 | | ----- | ------------------------------------------------------- | ---------------- | |
| 17 | 17 | | #420 | spawn plan: one validated value, dry-run | #383 | |
| 18 | 18 | | #427 | placement seam; hosted inside the parent today | #420 | |
| 19 | | #2926 | `cell` placement: a child as its own `bun src/main.ts` in a cell held to its size (`spawn/cell.ts`); `hosted` where the host cannot hold a cell. The spawn answer and the children list say `placement` | #2925 | | |
| 19 | 20 | | #421 | spawn action: org, instance, apps as repos, briefs | #420, #427 | |
| 20 | 21 | |
| 21 | 22 | `src/actions/spawn.ts` (#421): the child lives in `<data>/children/<bodyId>`; the parent keeps a ledger line in `<data>/spawn/<name>.json` so a retry resumes or answers. Subscription names are in the plan but not yet created in the child (a subscription is a token). |
docs/STUDIO.md +2
| @@ -463,6 +463,8 @@ page's signals (`core/front.ts`: forks by people, pulls merged this month, | ||
| 463 | 463 | hours in use, how lately it shipped) with the numbers on each row, and — for |
| 464 | 464 | a site admin — the forges this one spawned. One line narrows it and stays in |
| 465 | 465 | the URL: `kind:app|person|forge`, `sort:score|forks|ships|use|fresh|name`, |
| 466 | `owner:<username>` (one account's apps and the person; each person row's | |
| 467 | count of apps links there), `archived:yes` (put-away repositories too), | |
| 466 | 468 | and words to match. An agent's working fork is how the crew builds, not a |
| 467 | 469 | find, and is left out; a private app's hours are told only to those who may |
| 468 | 470 | enter it. Every app row offers **Make it yours** (a fork) to someone signed |
docs/VISION.md added +26
| @@ -0,0 +1,26 @@ | ||
| 1 | # What the forge is for | |
| 2 | The forge is a social place for building. Everyone who joins gets a whole forge of their own: their apps, and a crew that builds them. People share what they make, take what others made and mold it, and the best of it rises through a visible tree of forks, while anyone can stay as private and as different as they like. Opening it should feel like opening X: you get it at once. Steering it should take one thought: type it, go. | |
| 3 | ||
| 4 | ## Order of work | |
| 5 | 0. **Trust, always first.** Agents are contained. Agent pulls are reviewed. The gate runs every test. Admin is a separate account from the everyday one, explained kindly and directly; using AI with admin stays possible but deliberate. Private by default, and always plain about who can see what. | |
| 6 | 1. **One front door: the feed.** Home is an X-style timeline that IS the git primitives: a post is a tell or an issue; a reply is a comment; a repost or quote is a share or a fork; a like is a signal written to the decision ledger; a crew member's posts are its runs, pulls and looks. The crew reads and writes through the same feed. There is no dev/studio split: one interface, with every developer depth (files, diffs, runs, terminal) one step deeper from any post. | |
| 7 | 2. **The explorer.** Apps, forges and people ranked by real metrics (use, forks, ships, likes, freshness), and trivially filterable to exactly what you want. Every app says "make it yours": one action forks it into your forge. | |
| 8 | 3. **The fork tree is the organization.** My forge is the public upstream; an organization's forge forks it; each person's forge forks their organization's. Every fork chooses how it follows its upstream. The tree is visible and a pleasure to browse; good changes bubble up as offers and flow down as updates. | |
| 9 | 4. **A forge in a link.** I (or my agent, through the MCP) create a forge for a person, a client or an organization: chosen apps (some forked from mine, some still autonomous so they see it cooking), a starter budget, an admin account, one link. First login shows their crew working right now in the feed, and three next steps: make your everyday account, open your apps, tell the crew something. They add their people; each new person gets their own forge that follows the organization's. A client list tracks who was sent what and what happened. | |
| 10 | 5. **Open to every agent.** Any agent or harness can find and use a forge: the MCP with OAuth (Claude app, Grok in a car); a role-aware, token-efficient manifest on every page saying what you can do here as who you are; standards metadata; and on a public app or repo, an outside person or agent can file a report or offer a pull without being taught how. | |
| 11 | 6. **Never lost.** A forge toolbar in every app and preview: where you are (app, environment, which pull this previews), who is working on it, comment on this page or its issue or pull, tell the crew from here, make it yours. Later: in a preview, a tint on what changed and its diff on selection. | |
| 12 | 7. **Steering is one thought.** Tell from anywhere: the feed composer, the toolbar, a phone share sheet, the MCP. | |
| 13 | ||
| 14 | ## How we build | |
| 15 | - A deterministic tool with deliberate noise: actions are explicit, previewed and receipted; AI judgment only where we say so. | |
| 16 | - The same action has the same shape for a person and an agent: a page and an MCP tool, in the same words. | |
| 17 | - Done means reachable: a person reaches it from the feed in two taps, an agent through the MCP, a test proves it, a look shows it. A function nobody can call is not done. | |
| 18 | - Far ideas go on the map behind what they depend on, and we trim honestly. | |
| 19 | ||
| 20 | ## The tests | |
| 21 | - **Link test:** someone opens a link to their new forge and, within a minute and without a word from me, sees a crew working and knows what to do next. | |
| 22 | - **Muse test:** an outside agent looking at a public forge app finds out how to report a problem or offer a change, and does it. | |
| 23 | - **Friend test:** someone I send an app to makes it theirs in one action. | |
| 24 | - **Tesla test:** any MCP client connects with OAuth and steers. | |
| 25 | - **Lost test:** from any app or preview you know where you are and can get home, comment, or tell the crew. | |
| 26 | - **Admin test:** a new owner is guided to a separate everyday account, told why in two sentences, and can still choose otherwise on purpose. |
docs/design/areas/README.md +1 −1
| @@ -4,4 +4,4 @@ A new component class is named here, in a file for its area (`docs/design/areas/ | ||
| 4 | 4 | (`` `.my-class` ``) with a line on what it is for. The design check reads every file in this directory as §5 vocabulary, |
| 5 | 5 | so two pulls documenting different components touch different files and never conflict on `docs/DESIGN.md`. |
| 6 | 6 | |
| 7 | Do not edit `docs/DESIGN.md` §5d: it only shrinks. Prefer a component §5 already has. | |
| 7 | Do not add to §5d (`docs/design/sections/5d-page-local-classes.md`): it only shrinks. Prefer a component §5 already has. |
docs/design/areas/backups.md added +3
| @@ -0,0 +1,3 @@ | ||
| 1 | # Backups | |
| 2 | ||
| 3 | - `.restore-command` — the one-line restore command on /settings/backups: a `<pre>` that wraps, scrolls with the keyboard (`tabindex="0"`) and takes its height from its text, so a one-liner is not a log pane. |
docs/design/areas/boards.md added +2
| @@ -0,0 +1,2 @@ | ||
| 1 | # Boards | |
| 2 |
docs/design/areas/chart.md added +11
| @@ -0,0 +1,11 @@ | ||
| 1 | # Chart | |
| 2 | ||
| 3 | - Series colours — the eight colours the fleet graph's stacked bar chart draws its series in, one class per series index, drawn by `windowSvg()` in `src/web/fleet-graph.ts` on each bar's `<rect>` beside `data-series` (the same index `seriesDot()` keys the legend and table dots by). Each sets `fill` and `color` from its `--series-N` token in `src/design/themes.ts`: the Okabe–Ito palette, told apart with the common colour-vision deficiencies, with the folded "others" series grey. | |
| 4 | - `.fg-s0` — series 0. | |
| 5 | - `.fg-s1` — series 1. | |
| 6 | - `.fg-s2` — series 2. | |
| 7 | - `.fg-s3` — series 3. | |
| 8 | - `.fg-s4` — series 4. | |
| 9 | - `.fg-s5` — series 5. | |
| 10 | - `.fg-s6` — series 6. | |
| 11 | - `.fg-s7` — series 7, the folded "others" series (grey). |
docs/design/areas/code.md added +3
| @@ -0,0 +1,3 @@ | ||
| 1 | # Code | |
| 2 | ||
| 3 | - `.blob-view` — the file view in the code browser (`renderBlob` in `src/web/pages/repo.ts`): on a Markdown file, wraps the Source/Rendered `.seg` toggle at the end of the file's bar, set 8px off the line count with its segments at 12.5px. |
docs/design/areas/comments.md added +8
| @@ -0,0 +1,8 @@ | ||
| 1 | # Comments | |
| 2 | ||
| 3 | A comment on an issue or pull, and the form that writes one. Both are a `card()`; these classes give it its comment look. | |
| 4 | ||
| 5 | - `.comment` — one comment as a card: its `.card-head` (byline and time) on the muted ground, the body under it. Written by `commentCard()` in `src/web/comments.ts` and by `reviewRows()` in `src/web/diff-view.ts` (an inline review comment); styled in `src/web/style/components.ts`, and spaced inside a review thread by `.dc-review .comment` in `src/web/style/content.ts`. | |
| 6 | - `.comment-body` — a comment's rendered markdown, always beside `.prose`, padded inside its card. Written by `commentCard()` in `src/web/comments.ts`, `reviewRows()` in `src/web/diff-view.ts` and `reviewEntry()` in `src/web/studio/change.ts`; styled in `src/web/style/components.ts` (tighter in a timeline event's card). | |
| 7 | - `.comment-form` — the card that writes a comment: a textarea and its `.form-actions`. Written by `composer()` and `editForm()` in `src/web/pages/thread.ts`, `reviewRows()` in `src/web/diff-view.ts` (a reply in a review thread) and `studioApp()` in `src/web/studio/app.ts` (the "Tell the crew" box); styled in `src/web/style/components.ts`, with its narrow-screen action line and its review-thread margin in `src/web/style/content.ts`. | |
| 8 | - `.tl-earlier` — the line above a long thread's newest items, `Show N earlier items`, a plain link to `?all=1`. Written by `conversation()` in `src/web/pages/thread.ts`; styled in `src/web/style/components.ts` beside `.tl-item`, indented to the timeline's item column. |
docs/design/areas/dialog.md added +10
| @@ -0,0 +1,10 @@ | ||
| 1 | # Dialog | |
| 2 | ||
| 3 | A §5 `.dialog` is one component in three parts: a head that names it, a body that holds what it asks or shows, and a | |
| 4 | foot of buttons aligned to the end. The shell's keyboard-shortcuts dialog (`overlays()` in `src/web/layout.ts`) and the | |
| 5 | limb page's confirm form (`limbPreviewPage()` in `src/web/pages/limb.ts`) both draw it; the rules live in | |
| 6 | `src/web/style/components.ts`. | |
| 7 | ||
| 8 | - `.dialog-head` — the dialog's first row: its `h2` title (which `aria-labelledby` names) takes the width, anything beside it sits at the end. | |
| 9 | - `.dialog-body` — the dialog's content, padded to the head's inset; add `.stack` when it holds several fields. | |
| 10 | - `.dialog-foot` — the dialog's actions on one row, aligned to the end, the primary or danger button last. |
docs/design/areas/diff.md added +25
| @@ -0,0 +1,25 @@ | ||
| 1 | # Diff | |
| 2 | ||
| 3 | The diff a pull and a commit show is one component, drawn by `renderDiff` in `src/web/diff-view.ts` and styled in | |
| 4 | `src/web/style/content.ts`. It is a `.diff` wrapper holding a summary line and one §5 **diff file** (`.diff-file`) per | |
| 5 | file. | |
| 6 | ||
| 7 | - `.diff-summary` — the card above the files: how many files changed and the `+`/`−` totals, in their add and delete colours. | |
| 8 | - `.diff-head` — a file's `<summary>` row: the fold chevron, path, status badge, line counts and the Viewed checkbox; sticky under the top bar, and wraps when its card is narrower than 420px. | |
| 9 | - `.diff-path` — the file's path (or `old → new` for a rename) in the head, monospace and truncated with its full path as the title. | |
| 10 | - `.diff-stat` — a file's `+`/`−` line counts, in the head and in a stub. | |
| 11 | - `.diff-body` — the file's contents under its head: scrolls sideways for long lines, hidden once the file is marked viewed. | |
| 12 | - `.diff-table` — the table of hunks and rows inside the body, monospace at 12.5px. | |
| 13 | - `.diff-note` — a centred muted line in place of rows: a binary file, no content changes, or files past the cap not shown. | |
| 14 | - `.diff-stub` — a `.diff-note` for a file too large or generated to draw: why, its real counts and a View file button. | |
| 15 | - `.dn-comment` — a line number in the gutter that links to commenting on that line, when the diff is reviewable. | |
| 16 | - `.nonl` — the `↵` mark after a line that has no newline at the end of the file. | |
| 17 | - `.diff` — the wrapper around one whole diff: its summary and every file. | |
| 18 | - `.dl` — one line of a hunk, a table row; its `data-k` says whether it is context, added or deleted. | |
| 19 | - `.dn` — a line number in the gutter. | |
| 20 | - `.dh` — a hunk head, the `@@` row that opens each hunk. | |
| 21 | - `.add` — an added line, in the add colours. | |
| 22 | - `.del` — a deleted line, in the delete colours. | |
| 23 | - `.wd` — a changed word inside an added or deleted line, underlined on a stronger tint. | |
| 24 | - `.tok-inserted` — an inserted token in highlighted code, in the add colour. | |
| 25 | - `.tok-deleted` — a deleted token in highlighted code, in the delete colour. |
docs/design/areas/feed.md added +5
| @@ -0,0 +1,5 @@ | ||
| 1 | # Feed | |
| 2 | ||
| 3 | - `.feed-head` — the head of the home's feed: a §5 `.bar` above the timeline holding the "What you asked for" link, pushed to the end by a spacer. Drawn by `studioHome` in `src/web/studio/home.ts`, styled in `src/web/studio/feed_style.ts`. Under 900px it is hidden, since that link is a tab on a phone and the first post should come next; a bare `.bar` cannot carry this, as it has no reason to vanish on a narrow screen. | |
| 4 | - `.look[data-slot="feed"]` — a look post's thumbnail, drawn by `feedCard` in `src/web/studio/feed.ts`: the §5 `.look` frame fixed at 160×100 (the img carries the same width and height, so nothing shifts), cropped from the top like the other thumbs. A bare `.look` is fluid and would resize the post. | |
| 5 | - `.feed` — the home's timeline list: a one-column grid with no gap that holds the feed's cards, each focusable with a visible outline and removed from layout while `hidden`. Drawn by `drawRegion` in `src/web/studio/feed.ts` (the `#live-feed` section), styled in `src/web/studio/feed_style.ts`. |
docs/design/areas/forms.md added +6
| @@ -0,0 +1,6 @@ | ||
| 1 | # Form layout | |
| 2 | ||
| 3 | A form's fields and its buttons sit in two rows, one for what you fill in and one for what you do with it. | |
| 4 | ||
| 5 | - `.field-row` — a row of `.field`s side by side that wraps on a narrow screen, each at least 160px wide and aligned to the bottom so a labelled input and the button beside it share a baseline. Styled in `style/components.ts`; written by `createForm` in `pages/branches.ts` (the new-branch form), the graph filter in `pages/fleet-graph.ts`, the freeze form in `pages/frozen.ts` and the new-pull form in `pages/pulls.ts`. | |
| 6 | - `.form-actions` — the row of a form's buttons under its fields: 16px above, 8px apart, wrapping. Styled in `style/components.ts`, and in `style/content.ts` for a thread's close reason and "close into" input and for `.comment-form` on a narrow screen; written by nearly every form in `src/web/pages/` (`account.ts`, `settings.ts`, `crew.ts`, `edit.ts`, `issues.ts`, `pulls.ts`, `oauth.ts`, `teams.ts`, `chain.ts`, `everyday.ts`) and by the review comment form in `diff-view.ts`; `client.ts` finds its `.muted` note to report a save. |
docs/design/areas/front.md added +7
| @@ -0,0 +1,7 @@ | ||
| 1 | # Front | |
| 2 | ||
| 3 | The studio's front page (`studioDoor()` in `src/web/studio/home.ts`) shows an admin, under the shelf of public apps, the | |
| 4 | controls that pick what the shelf shows; strangers never see them. The rules live in `src/web/style/content.ts`. | |
| 5 | ||
| 6 | - `.front-admin` — the admin's controls under the front page (`studioDoor()` draws it around `frontControls()`), as wide as the shelf above it and centred with it. | |
| 7 | - `.front-pick` — one row of choices in those controls (drawn by `frontControls()`): the entry's name, then its pin, unpin, hide or show buttons at the end, its inline forms without the end margin `form.inline` would give them. |
docs/design/areas/highlight.md added +23
| @@ -0,0 +1,23 @@ | ||
| 1 | # Code, coloured | |
| 2 | ||
| 3 | The highlighter's token colours (§6b): one component, written as `tok-${kind}` by `tokenClasses` in `src/web/highlight-html.ts` and coloured by the `--tok-*` tokens in `src/design/themes.ts`. A token span carries its colour class, plus a finer kind class when it has one; the file browser, the diff viewer and the editor all draw the same spans. | |
| 4 | ||
| 5 | - `.tok-attribute` — an attribute name, as in markup. | |
| 6 | - `.tok-comment` — a comment. | |
| 7 | - `.tok-constant` — a constant: `true`, `null`, a named constant. | |
| 8 | - `.tok-decorator` — a decorator or annotation. | |
| 9 | - `.tok-emphasis` — emphasised prose, as in markdown. | |
| 10 | - `.tok-function` — a function name. | |
| 11 | - `.tok-heading` — a heading, as in markdown. | |
| 12 | - `.tok-keyword` — a language keyword. | |
| 13 | - `.tok-link` — a link, as in markdown. | |
| 14 | - `.tok-meta` — meta syntax: a preprocessor line, a front-matter fence. | |
| 15 | - `.tok-number` — a numeric literal. | |
| 16 | - `.tok-operator` — an operator; muted, it is a line's scaffolding. | |
| 17 | - `.tok-property` — a property or key name. | |
| 18 | - `.tok-punctuation` — punctuation; muted, it is a line's scaffolding. | |
| 19 | - `.tok-regex` — a regular-expression literal. | |
| 20 | - `.tok-string` — a string literal. | |
| 21 | - `.tok-tag` — a tag name, as in markup. | |
| 22 | - `.tok-type` — a type name. | |
| 23 | - `.tok-variable` — a variable or parameter name. |
docs/design/areas/icons.md added +15
| @@ -0,0 +1,15 @@ | ||
| 1 | # Icons | |
| 2 | ||
| 3 | One icon set, drawn from one sprite: `icon(name)` in `src/web/icons.ts` writes a `<svg>` slot that `<use>`s a | |
| 4 | `<symbol>`, and `iconSprite()` defines each drawing a page used once, at the end of `<body>`. Fragments expand the | |
| 5 | references in place with `inlineIcons()`. Every rule is in `src/web/style/components.ts`. | |
| 6 | ||
| 7 | - `.ico` — every icon slot: written by `icon()` (`src/web/icons.ts`, as `ico ico-<name>`) and by `themeGlyph`, the | |
| 8 | theme menu's half-filled circle. Styled in `src/web/style/components.ts` (a 16px inline-flex box that never shrinks); the | |
| 9 | components that hold one (`.badge`, `.count`, `.menu-item`, `.toast`, `.empty`, and `src/web/style/content.ts`'s | |
| 10 | `.where-place`, `.live-note`, `.origin-chip`) tune its size and colour. | |
| 11 | - `.ico-loader` — the spinning loader, written by `icon("loader")` (`src/web/icons.ts`; used on the pull page, | |
| 12 | `src/web/pages/pull.ts`, and the studio's working word, `src/web/studio/words.ts`). Styled in | |
| 13 | `src/web/style/components.ts`: it spins, and inside a `.btn` it spins only while the button is `aria-busy="true"`. | |
| 14 | - `.sprite` — the zero-sized `<svg>` of `<symbol>`s, written by `iconSprite()` (`src/web/icons.ts`, placed by | |
| 15 | `layout.ts`). Styled in `src/web/style/components.ts`: absolutely positioned at 0×0 so it can never move a layout. |
docs/design/areas/layout.md added +13
| @@ -0,0 +1,13 @@ | ||
| 1 | # Layout utilities | |
| 2 | ||
| 3 | The spacing and layout utilities every page leans on: one component, styled in `style/base.ts`'s `utilities` layer, so a page spaces and sizes its blocks without a class of its own. | |
| 4 | ||
| 5 | - `.mt` — a 12px top margin between a block and the one above it; `pages/commits.ts` (`<div class="mt">`), `pages/issues.ts` and most pages write it. Styled in `style/base.ts`. | |
| 6 | - `.mb` — a 12px bottom margin, the same step downward; `pages/commits.ts` (`<div class="bar mt mb">`) and `pages/settings.ts` write it. Styled in `style/base.ts`. | |
| 7 | - `.stack` — a flex column with a 12px gap, for a run of cards or form rows; `pages/looks.ts`, `pages/returns.ts` and `pages/everyday.ts` write it. Styled in `style/base.ts`; `style/components.ts` drops the card-to-card margin inside it and `style/content.ts` adjusts it under `#needs-you`. | |
| 8 | - `.stack-tight` — beside `.stack`, narrows its gap to 4px; `pages/looks.ts` and `pages/first-admin.ts` write it. Styled in `style/base.ts`. | |
| 9 | - `.spacer` — an empty flex child that takes the free space and pushes what follows to the end of a row; `pages/commits.ts` and `pages/edit.ts` write it. Styled in `style/base.ts` (also inside `.topbar`), `style/components.ts` (`.pager`) and `style/content.ts` (`.app-strip`, `.comment-form`). | |
| 10 | - `.grow` — a flex child that takes the free space and may shrink below its content (`min-width: 0`), so its text can truncate; `pages/edit.ts`, `pages/settings.ts` and `pages/board.ts` write it. Styled in `style/base.ts`; `style/components.ts` ellipsizes it inside `.menu-item` and `.palette-item`. | |
| 11 | - `.narrow` — a 400px column centred a little below the top, for a single short form or notice; `pages/oauth.ts` writes it. Styled in `style/base.ts`. | |
| 12 | - `.narrow-wide` — a 760px reading column for a page of one form or one text; `pages/edit.ts`, `pages/issues.ts` and `pages/forges.ts` write it. Styled in `style/base.ts`. | |
| 13 | - `.page-head-sub` — the one line under a page head's title: `flex-basis: 100%` and a −4px top margin, so it breaks onto its own full-width line. A layout hook, not a look: it rides with `muted small` (or `bar muted small` for a row of facts); `pageHead({ sub })` in `chrome.ts` and the run, tell, change and browse heads write it. Styled in `style/content.ts`; a `.muted.small` child of a page head without it (the system page's Processes sort row) stays beside its heading. |
docs/design/areas/lines.md added +9
| @@ -0,0 +1,9 @@ | ||
| 1 | # Lines | |
| 2 | ||
| 3 | The line-number gutter of a file's source view: one cell per line, holding a link to that line's anchor. | |
| 4 | ||
| 5 | - `.ln` — the number cell of a row in `.code`, written by `blobBody()` in `src/web/pages/repo.ts` as | |
| 6 | `<td class="ln"><a href="#L…">…</a></td>`, styled by `.code .ln` in `src/web/style/content.ts`: right-aligned | |
| 7 | tabular numbers in `--faint` behind a hairline border, unselectable so a copy takes only the code, and `--attn` on a | |
| 8 | `:target` or `[data-hl]` row. `src/web/client.ts` reads `.code .ln a` for shift-click range selection (`#L3-L9`). | |
| 9 | The editor's own gutter is `.editor-gutter`, already named in §5's file editor row. |
docs/design/areas/map.md added +26
| @@ -0,0 +1,26 @@ | ||
| 1 | # Plan map | |
| 2 | ||
| 3 | The map of what waits for what (`/:owner/:name/map`): one SVG of the repository's open issues as cards, laid out by | |
| 4 | dependency, with the edges between them and the pillars beside it. `mapPage` in `src/web/pages/map.ts` draws the page and `drawMap` | |
| 5 | the SVG; `mapCss` there holds every rule below. A card's state (ready, working, blocked, waiting, parked, held, deferred, done) | |
| 6 | is `data-state` on `.map-node`, not a class. | |
| 7 | ||
| 8 | - `.map-wrap` — the page's two-column grid: the canvas, then the 272px side column; one column under 860px. | |
| 9 | - `.map-main` — the canvas column; `min-width: 0` so a wide map never pushes the side column off the page. | |
| 10 | - `.map-canvas` — the bordered frame the SVG sits in; `is-view`, `is-drag` and `is-cut` say whether it pans, is being dragged, or is cut off with a fade. | |
| 11 | - `.map-svg` — the map's SVG itself, full width; its text uses the page font and never takes the pointer. | |
| 12 | - `.map-rule` — the labelled line across the map above the issues that are "not linked" to any other. | |
| 13 | - `.map-node` — one issue's card, a link to the issue; `data-state` sets its colours. | |
| 14 | - `.map-card` — the card's rectangle, filled and stroked by the node's state. | |
| 15 | - `.map-breath` — the soft accent ring around a card being worked on. | |
| 16 | - `.map-title` — the issue's title on the card. | |
| 17 | - `.map-meta` — the issue's number, in tabular figures. | |
| 18 | - `.map-who` — the assignee's mark: a circle with an initial and a name. | |
| 19 | - `.map-who-i` — the assignee's initial inside the circle. | |
| 20 | - `.map-who-n` — the assignee's name beside it. | |
| 21 | - `.map-word` — the state's word at the card's right edge. | |
| 22 | - `.map-dot` — the coloured dot before the state's word. | |
| 23 | - `.map-edge` — one dependency edge between two cards. | |
| 24 | - `.map-edge-crit` — an edge on the critical path, in the accent. | |
| 25 | - `.map-edge-done` — an edge with a closed issue at either end, faded. | |
| 26 | - `.map-ask` — a pillar row's lead-time figures in the side column, inline, with the hover title saying what they measure. |
docs/design/areas/palette.md added +11
| @@ -0,0 +1,11 @@ | ||
| 1 | # Command palette | |
| 2 | ||
| 3 | The command palette is the keyboard-first fuzzy-find overlay (`⌘K` / `Ctrl K`, or the topbar's search button): the §5 `.palette` dialog, with its input, list and foot drawn by `layout.ts` and its results drawn by `openPalette()` in `src/web/client.ts`. Without script it degrades to `/search`. The file finder (`openFinder()`, `.dialog.palette.finder`) draws its rows and its empty note with the same classes. The rules live in `style/components.ts`. | |
| 4 | ||
| 5 | - `.palette-group` — one group of results under a heading (Recent, Go to, a category); consecutive groups sit 4px apart. | |
| 6 | - `.palette-heading` — a group's small, uppercase, faint heading; the group's `aria-labelledby` points at it. | |
| 7 | - `.palette-item` — one result row: an icon, the title truncated on one line, and its category pushed to the end. The row the keyboard or pointer has selected (`aria-selected="true"`) carries the one highlight; the finder keeps plain hover. | |
| 8 | - `.palette-empty` — the note centred in the list when nothing matches the query. | |
| 9 | - `.palette-input` — the search field across the top of the dialog: full width, borderless but for a rule beneath it, 48px tall, with no focus ring of its own (the system outline under forced colours). | |
| 10 | - `.palette-list` — the scrolling results area under the input: a fixed height (not a ceiling) so the dialog does not jump as rows come and go. | |
| 11 | - `.palette-foot` — the faint one-line strip of key hints under the list, set off by a rule above it. |
docs/design/areas/prose.md added +8
| @@ -0,0 +1,8 @@ | ||
| 1 | # Prose (markdown) | |
| 2 | ||
| 3 | Markdown table cell alignment: a column whose delimiter row reads `:-:` or `--:` puts the matching class on each of its | |
| 4 | `th` and `td` cells, written by `cells` in `src/web/markdown.ts` as `ta-${align}` and styled under `.prose` in | |
| 5 | `src/web/style/content.ts`. A left-aligned or unmarked column carries no class. | |
| 6 | ||
| 7 | - `.ta-c` — a centred column (`:-:`); text-align center. | |
| 8 | - `.ta-r` — a right-aligned column (`--:`); text-align right. |
docs/design/areas/repo-head.md added +5
| @@ -0,0 +1,5 @@ | ||
| 1 | # Repository head | |
| 2 | ||
| 3 | The head of a repository page names the repository and what you can do with it. `scopeHeader()` in `src/web/chrome.ts` draws it; the rules live in `src/web/style/content.ts`. | |
| 4 | ||
| 5 | - `.repo-title` — the head's `owner / name` line: the owner muted, the slash faint, the name in full weight. It is an `h1` on a repository's own pages and a `div` where the page has its own `h1`. |
docs/design/areas/search.md added +3
| @@ -0,0 +1,3 @@ | ||
| 1 | # Search box | |
| 2 | ||
| 3 | - `.search` — the search field of a filter or search form: an `.input` that grows to fill its row between 180px and 320px wide. Written by `searchPage` in `src/web/pages/search.ts` (the `/search` form), and by the filter forms in `src/web/pages/browse.ts`, `src/web/pages/org.ts`, `src/web/pages/origins.ts` and `src/web/studio/explore.ts`. Styled in `src/web/style/content.ts` as `.filters .search` and `.bar .search`. |
docs/design/areas/settings.md +18
| @@ -1,3 +1,21 @@ | ||
| 1 | 1 | # Settings page |
| 2 | 2 | |
| 3 | ## Settings rows | |
| 4 | ||
| 5 | A list whose rows are settings — each row a name, its current value, and a control to change it (limits, capacity, | |
| 6 | flags, telemetry, cloud, people, crew roles, subscription headroom and budget) — is §5's list row in a list that lets | |
| 7 | the text wrap and gives the control a place that is always visible. Use `.row-actions` only for secondary actions | |
| 8 | (delete, wake, pin, revoke). | |
| 9 | ||
| 10 | - `.setting-list` — the `<ul class="list setting-list">` around such rows: title and meta wrap instead of ellipsizing, | |
| 11 | and a row's trail takes its own line under 640px. Written by the settings pages, e.g. `appDomainsView()` and | |
| 12 | `appEgressView()` in `src/web/pages/settings.ts`, `limitsPage()` in `src/web/pages/admin-limits.ts`, `capacityPage()` in | |
| 13 | `src/web/pages/capacity.ts`, `flagsPage()` in `src/web/pages/flags.ts`, and by lists of the same shape in | |
| 14 | `src/web/pages/repo.ts`, `src/web/pages/pull.ts`, `src/web/pages/map.ts` and `src/web/studio/make_it_yours.ts`. | |
| 15 | Styled in `src/web/style/components.ts`. | |
| 16 | - `.row-fields` — the form in a settings row's trail (input, Save, Default): always visible, never hover-gated, | |
| 17 | wrapping under the text before it would clip. Written in the trail of `row()` by `src/web/pages/flags.ts`, | |
| 18 | `src/web/pages/telemetry.ts`, `src/web/pages/cloud.ts`, `src/web/pages/people.ts`, `src/web/pages/admin-limits.ts`, | |
| 19 | `src/web/pages/capacity.ts`, `src/web/pages/subscriptions.ts` and `src/web/studio/crew.ts`. Styled in | |
| 20 | `src/web/style/components.ts`. | |
| 3 | 21 | - `.record-value` — a DNS record's value on an app's domain row (`.setting-list` row meta): monospace, wraps instead of ellipsizing, and `user-select: all` so one click selects the whole value to copy. |
docs/design/areas/shell.md added +8
| @@ -0,0 +1,8 @@ | ||
| 1 | # Page shell | |
| 2 | ||
| 3 | The chrome every page sits in: the sticky top bar, the main column and the footer, drawn by `page()` in `src/web/layout.ts` (the top bar by `topbar()`, its search by `searchBar()`). Rules live in `src/web/style/base.ts`, the search field's in `src/web/style/components.ts`. | |
| 4 | ||
| 5 | - `.topbar-tools` — the top bar's right-hand group (search, Asks, the new and user menus): one row that may shrink but never wraps, its bare `a.small` links 44px tall. | |
| 6 | - `.topbar-search` — the top bar's search form: an icon, a borderless input and its `/` key hint in one bordered pill, the border taking the accent on focus. Shown from 720px; below that the icon button carries search. | |
| 7 | - `.hide-lg` — shown under 720px, hidden from 720px: the narrow-screen stand-in for something `.hide-sm` shows on wide screens (the search icon button beside `.topbar-search`). | |
| 8 | - `.shell-wide` — on `<main class="shell">` when a page passes `wide`: from 1200px the column drops its reading width and keeps a 24px gutter, for the one layout that gains from every pixel (a tree beside a file). |
docs/design/areas/table.md added +5
| @@ -0,0 +1,5 @@ | ||
| 1 | # Scrolling table | |
| 2 | ||
| 3 | A §5 `.table` too wide for a narrow screen sits inside a horizontal scroller, so the page itself never scrolls sideways and only the table's figures move. | |
| 4 | ||
| 5 | - `.table-scroll` — the wrapper `<div>` around a wide `.table`: `overflow-x: auto` with a thin scrollbar, styled in `src/web/style/components.ts`. Pair it with `.table[data-sticky-lead]` to keep each row's name in view while the figures scroll. Written by `src/web/pages/account.ts`, `src/web/pages/audit.ts`, `src/web/pages/boards-held.ts`, `src/web/pages/crew.ts`, `src/web/pages/flow-panel.ts`, `src/web/pages/passkeys.ts`, `src/web/pages/proposal-tokens.ts`, `src/web/pages/settings.ts`, `src/web/pages/spend.ts`, `src/web/pages/subscriptions.ts`, `src/web/pages/system.ts`, `fleetGraphSection`'s figures table in `src/web/fleet-graph.ts`, and `vitalsTable` in `src/web/studio/vitals.ts`. |
docs/design/areas/tell.md added +15
| @@ -0,0 +1,15 @@ | ||
| 1 | # Tell here | |
| 2 | ||
| 3 | Telling the crew from any page (tell from anywhere) opens in place: `tellInPlace()` in `src/web/client.ts` fetches the | |
| 4 | server's own composer (the thread's `.comment-form` saying a tell) and lays it over the bottom of the page, so nothing | |
| 5 | shifts and Enter sends it with the page's path as `from`. Any failure falls back to the plain link. | |
| 6 | ||
| 7 | - `.tell-here` — the fixed box holding that composer: pinned to the bottom of the viewport, at most 620px wide and | |
| 8 | centred, above the page; the `.comment-form` inside drops its margin and takes `--shadow-2` so it reads as raised. | |
| 9 | ||
| 10 | ## Client home: `client-app-finished` | |
| 11 | ||
| 12 | A muted line on a client's app row, `Finished <time>: <title>`, for the app's | |
| 13 | newest merged pull. It sits with `client-app-about`, `client-app-agents` and | |
| 14 | `client-app-doing`; it uses `muted` and adds no colour or size. The | |
| 15 | terminal says the same words. |
docs/design/areas/text.md added +29
| @@ -0,0 +1,29 @@ | ||
| 1 | # Text utilities | |
| 2 | ||
| 3 | One component: the small text utilities every page puts on a span, a paragraph or a cell to say how its text reads, | |
| 4 | without a page-local class of its own. Each is styled in `style/base.ts`; they compose (`muted small` is the usual | |
| 5 | quiet line under a card), and a page reaches for them instead of setting a colour or a size by hand. | |
| 6 | ||
| 7 | - `.muted` — low-emphasis text in `--muted-fg`: notes, timestamps, the summary of a tucked disclosure. Written by | |
| 8 | `ui.ts` (`envFacts()`, `terminalLine()`, `disclosure()` with `small`) and most pages | |
| 9 | (`pages/commits.ts`, `pages/settings.ts`, `pages/looks.ts`, …); styled in `style/base.ts`, with contextual rules in | |
| 10 | `style/content.ts`. | |
| 11 | - `.small` — 13px text, the step under body. Written by `ui.ts` beside `.muted`, `layout.ts` (the topbar's Asks | |
| 12 | link) and pages such as `pages/edit.ts` and `pages/boards-view.ts`; styled in `style/base.ts`, with contextual rules | |
| 13 | in `style/content.ts`. | |
| 14 | - `.num` — tabular figures so counts line up in a column. Written by `ui.ts` (`stat()`'s value, `counts()`) | |
| 15 | and pages such as `pages/spend.ts`, `pages/repo.ts` and `pages/crew.ts`; styled in `style/base.ts`, right-aligned | |
| 16 | inside `.table` by `style/components.ts`. | |
| 17 | - `.truncate` — one line that ends in an ellipsis rather than wrapping. Written by `ui.ts` (`envFacts()`'s URL) and | |
| 18 | pages such as `pages/apps.ts`, `pages/refs.ts` and `pages/explorer.ts`; styled in `style/base.ts`, capped at 34ch | |
| 19 | inside `.table` by `style/content.ts`. | |
| 20 | - `.nowrap` — keeps a short run (a token count, a figure with its unit) on one line without clipping it. Written by | |
| 21 | `ui.ts` (`tokenCount()`, with `.num`); styled in `style/base.ts`. | |
| 22 | - `.break` — lets a long unbroken string (a URL, a hash, a path) wrap anywhere rather than overflow its box. Written by | |
| 23 | `ui.ts`, `scope.ts` and pages such as `pages/backups.ts`, `pages/origins.ts` and `studio/feed.ts`; styled in | |
| 24 | `style/base.ts`. | |
| 25 | - `.sr-only` — text for a screen reader only: a table's caption, a select's label, a fieldset's legend. Written by | |
| 26 | pages such as `pages/audit.ts`, `pages/pull.ts` and `pages/thread.ts`, and by `studio/app.ts` and | |
| 27 | `studio/review_act.ts`; styled in `style/base.ts`. | |
| 28 | - `.mark` — the forge's square glyph beside the wordmark and in the footer. Written by `layout.ts` (the topbar's | |
| 29 | `.wordmark` and the `.foot`) and `pages/board.ts`; styled in `style/base.ts` only inside `.wordmark` and `.foot`. |
docs/design/areas/timeline.md added +6
| @@ -0,0 +1,6 @@ | ||
| 1 | # Timeline | |
| 2 | ||
| 3 | The event timeline on an issue or pull thread: a vertical rail of `.tl-item` rows, each with a dot, comments as cards and events as one dim line. | |
| 4 | ||
| 5 | - `.timeline` — the column that holds the rows and draws the rail behind their dots. Written by `conversation()` in `src/web/pages/thread.ts`, `timelineOf()` in `src/web/pages/browse.ts` and `appEgressView()` in `src/web/pages/settings.ts`; styled in `src/web/style/components.ts`. | |
| 6 | - `.tl-dot` — the round glyph on the rail at the head of each row, tinted by the row's `data-tone`. Written by `tlEvent()` and `tlComment()` in `src/web/ui.ts` and `threadComment()` in `src/web/pages/thread.ts`; styled in `src/web/style/components.ts`. |
docs/design/areas/toast.md added +5
| @@ -0,0 +1,5 @@ | ||
| 1 | # Toast | |
| 2 | ||
| 3 | The flash a write leaves after its redirect, and the same one-line banner a page shows for a failure it found itself: one `.toast` per page, toned by `data-tone=success|danger|attn` (§5's toast / flash row), an icon, then the message. | |
| 4 | ||
| 5 | - `.toast-body` — the message beside the toast's icon: it takes the rest of the row (`flex: 1; min-width: 0`) so a long message wraps instead of pushing the icon off. Written by `flashToast` in `src/web/layout.ts` (the cookie-driven flash), and by `src/web/pages/repo.ts` (a fetch error), `src/web/pages/browse.ts` (a failed mirror) and `src/web/pages/origins.ts` (origin connected or failed); styled in `src/web/style/components.ts` under `/* ---- toast / flash ---- */`. |
docs/design/sections/1-principles.md added +19
| @@ -0,0 +1,19 @@ | ||
| 1 | ## 1. Principles | |
| 2 | ||
| 3 | 1. **Border-first, not shadow-first.** Elevation in a light theme is a hairline | |
| 4 | plus a 5%-opacity shadow. In a dark theme it is a lighter surface and a | |
| 5 | stronger border — dark themes have no shadows. If something looks flat in | |
| 6 | the dark, its surface is wrong, not its shadow. | |
| 7 | 2. **One accent per page.** `--accent` means _interaction_: focus rings, links | |
| 8 | on hover, the active choice. It is never a status color. If two things on a | |
| 9 | page are accent-colored and only one is the action, one of them is wrong. | |
| 10 | 3. **Hierarchy from weight and color, not size.** 14px does almost everything. | |
| 11 | A title is 20px because it is a title, not to be noticed. | |
| 12 | 4. **Everything works with JavaScript off.** Script may make a thing instant. | |
| 13 | It may never make a thing possible. A control that does nothing without JS | |
| 14 | is worse than no control. | |
| 15 | 5. **Anything that navigates is `<a>`; anything that mutates is a `<button>` | |
| 16 | in a `<form method=post>`.** There is no third case, and the CSP forbids | |
| 17 | inventing one. | |
| 18 | 6. **Never say what you don't know.** A missing thing and a thing you may not | |
| 19 | see are the same 404, with the same words. |
docs/design/sections/2-tokens.md added +32
| @@ -0,0 +1,32 @@ | ||
| 1 | ## 2. Tokens | |
| 2 | ||
| 3 | Palettes live in `src/design/themes.ts`; the stylesheet only ever reads | |
| 4 | variables, so a theme is data. Six ship today. What each role _means_: | |
| 5 | ||
| 6 | | token | role | | |
| 7 | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | |
| 8 | | `--bg` | the page. Nothing else uses it. | | |
| 9 | | `--card` | any raised surface: card, menu, dialog, input, button. | | |
| 10 | | `--muted` | a recessed surface: row hover, table head, code block, pill. | | |
| 11 | | `--fg` | body text, and the **active tab underline**. | | |
| 12 | | `--muted-fg` | all metadata. Never a hardcoded gray — muted is a desaturated hue of the surface, so it warms and cools with the theme. | | |
| 13 | | `--faint` | decoration only: separators between crumbs, gutter numbers, icons inside rows. Never load-bearing text. | | |
| 14 | | `--border` | every hairline. | | |
| 15 | | `--border-strong` | a raised edge, and hover on a control. | | |
| 16 | | `--primary` / `--primary-fg` | the one filled button per page, and the live-activity pill. | | |
| 17 | | `--accent` / `--accent-fg` | interaction: focus ring, link hover, selection, the review-comment rail. | | |
| 18 | | `--success` | open issue, mergeable pull, additions. | | |
| 19 | | `--danger` | closed, destructive, deletions. | | |
| 20 | | `--merged` | a merged pull. Purple, and only that. | | |
| 21 | | `--attn` | draft, pending, a highlighted line. | | |
| 22 | | `--add-*` / `--del-*` / `--wd-*` | the diff. Tints stay ≤14% so syntax color survives on top. | | |
| 23 | | `--tok-*` | syntax, in two layers: eleven colour classes every consumer knows, plus finer kinds the web paints over them (§6c). | | |
| 24 | | `--shadow-1` / `--shadow-2` | a hint and an overlay. Near-transparent in dark palettes, so one rule serves every theme. | | |
| 25 | | `--series-0…7` / `--qr-ground` | the same in every theme (`FIXED_TOKENS`): chart series (Okabe–Ito, colour-vision safe) and a QR code's white ground. | | |
| 26 | ||
| 27 | **Status surfaces are tinted, never saturated**: `color-mix(in srgb, var(--x) | |
| 28 | 12%, transparent)` for the fill, the pure token for the text, a 34% mix for the | |
| 29 | border. | |
| 30 | ||
| 31 | **Contrast targets**: body ≥7:1 where it's cheap, `--muted-fg` ≥4.5:1 on | |
| 32 | `--bg`, borders ≥1.5:1 against their surface, focus ring ≥3:1. |
docs/design/sections/3-typography.md added +38
| @@ -0,0 +1,38 @@ | ||
| 1 | ## 3. Typography | |
| 2 | ||
| 3 | ||
| 4 | --font: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif | |
| 5 | --mono: ui-monospace, "SF Mono", SFMono-Regular, "Cascadia Code", Menlo, Consolas, monospace | |
| 6 | ||
| 7 | ||
| 8 | | role | size | weight | tracking | line-height | | |
| 9 | | -------------------------------- | -------- | ------ | -------- | ----------- | | |
| 10 | | page title `h1` | 20px | 620 | −0.02em | 1.25 | | |
| 11 | | section `h2` | 16px | 600 | −0.01em | 1.3 | | |
| 12 | | sub `h3` | 14px | 600 | 0 | 1.4 | | |
| 13 | | **body, rows, chrome** | **14px** | 400 | 0 | 1.5 | | |
| 14 | | **prose (`.prose` only)** | **15px** | 400 | 0 | 1.65 | | |
| 15 | | metadata | 13px | 400 | 0 | 1.45 | | |
| 16 | | mono (code, sha, diff) | 12.5px | 400 | 0 | 1.55 | | |
| 17 | | micro (`kbd`, `.pill`, `.badge`) | 11.5px | 500 | 0 | 1 | | |
| 18 | ||
| 19 | Rules: | |
| 20 | ||
| 21 | - **Headings tighten as they grow.** Body text is never tracked. | |
| 22 | - `font-variant-numeric: tabular-nums` on every count, date, line number, | |
| 23 | diff stat and file size — a count going 9 → 10 must not shift its neighbours. | |
| 24 | That is `.num`, `.pill`, `.badge`, `.sha`, `.dn`, `.table td`. | |
| 25 | - `text-wrap: balance` on headings and empty-state titles; `pretty` on prose | |
| 26 | and descriptions. | |
| 27 | - **Truncation is honest**: one line, ellipsis, and a `title` with the whole | |
| 28 | string. Never a fade-out mask — masks lie about whether there is more. | |
| 29 | - **A token count is shown where a byte size is shown, never as a badge on | |
| 30 | its own.** Tokens are a unit, like KB: they sit beside a file's size, a | |
| 31 | directory's total, a run's cost or a window's dollars and percentage, so | |
| 32 | the context intuition grows next to the storage and money ones. One | |
| 33 | formatter (`kernel/tokens-format.ts`, rendered by `tokenCount()` / | |
| 34 | `sizeWithTokens()` in `web/ui.ts`) writes them all: `850 tok`, `1.2k tok`, | |
| 35 | `48k tok`, `1.1M tok`. A count the provider reported is bare; an estimate | |
| 36 | (bytes ÷ a stated bytes-per-token ratio for prose, code or data) carries a | |
| 37 | `~`, and every count's `title` says which tokenizer and whether it is an | |
| 38 | estimate. A binary file has no token count — no number beats a wrong one. |
docs/design/sections/4-space-radius-motion.md added +20
| @@ -0,0 +1,20 @@ | ||
| 1 | ## 4. Space, radius, motion | |
| 2 | ||
| 3 | - **4px grid.** Every padding, margin and gap is divisible by 4; 6px is allowed | |
| 4 | _inside_ a control. Scale: `2 4 6 8 12 16 24 32 48 64`. | |
| 5 | - **Three radii, held to.** `--radius-sm: 6px` on controls (button, input, | |
| 6 | chip, kbd), `--radius: 8px` on surfaces (card, code block), `--radius-lg: | |
| 7 | 12px` on overlays (menu, dialog, palette), `999px` on pills and avatars. | |
| 8 | A nested element uses the outer radius minus the border width, never the same. | |
| 9 | - **Dividers**: `border-top` on `:not(:first-child)`, never `border-bottom` on | |
| 10 | all — that is where the double line at the end of a list comes from. | |
| 11 | - **Density**: dense rows (files, commits, issues) 40px; anything touchable is | |
| 12 | ≥44px under `@media (pointer: coarse)` — via padding, so text stays centered. | |
| 13 | - **Motion**: 100–200ms, `cubic-bezier(.2,0,0,1)`, enter only. Only `color`, | |
| 14 | `background-color`, `border-color`, `opacity` and `transform` are ever | |
| 15 | animated. Never `height`, never `box-shadow` on scroll. Everything is inside | |
| 16 | the `prefers-reduced-motion` kill switch. | |
| 17 | - **Focus** is the accent at 2px with 2px offset, identical on every control, | |
| 18 | and inset (−2px) on full-bleed rows so nothing reflows. Never `outline: none`. | |
| 19 | - **Sticky, and only these**: the topbar, a diff file's header, the file path | |
| 20 | header. Everything anchorable carries `scroll-margin-top`. |
docs/design/sections/5-components.md added +111
| @@ -0,0 +1,111 @@ | ||
| 1 | ## 5. The component vocabulary | |
| 2 | ||
| 3 | Implemented in `src/web/ui.ts` (pure) and `src/web/chrome.ts` (may read the | |
| 4 | database). One class, `data-*` for variants. "Terminal" is the shape the same | |
| 5 | component takes in a TUI — a note for the terminal thread to fill in, not a | |
| 6 | specification. | |
| 7 | ||
| 8 | | component | web class | variants (`data-*`) | states | terminal equivalent | | |
| 9 | | --------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------ | ------ | | |
| 10 | | **button** `btn()` | `.btn` | `variant=primary\|secondary\|outline\|ghost\|danger\|link`, `size=sm\|lg` | hover, active, `:focus-visible`, `[disabled]`, `[aria-busy]` | a labelled key or a highlighted action cell | | |
| 11 | | **icon button** `iconBtn()` | `.btn.btn-icon` | same | `aria-label` required | a single glyph with a status-bar hint | | |
| 12 | | **input / textarea / select** `field()` | `.input` | `size=sm`, `[aria-invalid]` | focus, `:user-invalid`, `[readonly]` | a line editor with an inline error row | | |
| 13 | | **form field** `field()` | `.field` (`label`, `.hint`, `.error`) | `data-invalid` | — | label line, value line, hint line | | |
| 14 | | **checkbox** | `.check` | — | native, `accent-color` themed | `[x]` / `[ ]` | | |
| 15 | | **badge** `badge()` / `stateBadge()` | `.badge` | `variant=secondary\|outline\|success\|danger\|merged\|attn`; `data-state=open\|closed`, `data-pr=merged` | — | a bracketed word in the state color | | |
| 16 | | **stat** `stat()` | `.stat` (`.stat-label`, `.stat-value`, `.stat-note`, `.stat-spark`; grid: `.stats`) | `data-tone=attn` | hover (`--border-strong`, only when `href` makes it a link, named by `aria` when given); fixed heights, so a changing value shifts no neighbour; value is `.num` with its full form in `title`; note clamps to two lines, its whole text in `noteTitle`; the sparkline carries its own `role=img` and `aria-label`, or is decorative; `.stats` auto-fits columns of at least 160px | a number under its label, a note under that, an optional sparkline top right | | |
| 17 | | **label chip** `labelChip()` | `.label` | color via `--label` (see §7) | — | a colored `‹name›` | | |
| 18 | | **author** `userLink()` / `userTag()` | `.byline` (`.byline-name`) | — | `userTag` inside anything already a link — see below | `@name` in the avatar hue | | |
| 19 | | **name mark** `nameMark()` | `.name-mark[data-mark]` | `owner` / `crew`, from the account | never typed: escaped names cannot make it | beside the name, after the link | | |
| 20 | | **avatar** `avatar()` | `.avatar` | `size=md\|lg`, `data-h=0..11` | initials, deterministic hue | two initial letters in the same hue | | |
| 21 | | **count** | `.count` | — | glyph plus a tabular number | `⌸ 3` | | |
| 22 | | **stat pill** `pill()` | `.pill` | `data-tone=accent\|danger` | tabular | a parenthesised count | | |
| 23 | | **status dot** `dot()` | `.dot` | `data-tone=success\|danger\|attn\|merged`; `data-series=0…7` (`seriesDot()`) is a chart series' swatch, in its `--series-N` colour | — | `●` in the tone | | |
| 24 | | **sha** `sha()` | `.sha` | — | first 7 chars | the same 7 chars, dim | | |
| 25 | | **progress bar** `progress()` (`pages/milestones.ts`) | `progress` (element rule in `style/components.ts`; every `<progress>` on the site) | — | native `<progress max value>`, 4px, full width, an `aria-label` saying what is done; no width rule per value | `▓▓▓░░ 3 of 5` | | |
| 26 | | **meter** `meter()` | `meter` | `data-tone=attn` when the share is a limit reached | native `<meter min=0 max=100>`, a whole percentage, an `aria-label` saying what it is a share of; no width rule per value, so no inline style | `▓▓▓░░ 62%` | | |
| 27 | | **kbd** `kbd()` | `kbd` | — | — | a reverse-video key name | | |
| 28 | | **card** `card()` / `listCard()` | `.card` (`.card-head`, `.card-links`, `.card-body`, `.card-foot`) | `data-tone=success\|danger\|merged\|attn` | — | a box with a title bar | | |
| 29 | | **list row** `row()` | `.row` (`.row-lead`, `.row-main`, `.row-title`, `.row-meta`, `.row-trail`, `.row-actions`, `.row-children`; settings: `.setting-list`, `.row-fields`) | `data-state=open\|closed\|merged\|draft` — colours the **lead glyph**, so a list filtered by state carries no badge repeating the filter | hover, focus, `data-nav`; `fold` makes the row a `<details>`'s `<summary>`, its lead the caret turned when open (/map's lanes); `children` nests the rows under a row in a `<ul class="row-children">` inside its `<li>` — a tree (/family), a step in under a rule, real list nesting for assistive tech; `aria-current="true"` on the `<li>` (`current`) tints the row; `.row-meta` is one honest line: nowrap, ellipsis, `title` — except in a `.setting-list`, where it wraps | one line: glyph, title, right-aligned meta | | |
| 30 | | **edit row** | `.edit-row` | — | one line on a desktop, stacked below 720px | a form line | | |
| 31 | | **colour field** | `.color-field` | — | native `<input type=color>` plus its hex; works with no script | a hex entry | | |
| 32 | | **table** | `.table` | `data-dense`; `.num` cells right-aligned | — | aligned columns | | |
| 33 | | **tabs** `tabs()` | `.tabs > a` | — | `aria-current="page"` + 2px `--fg` underline | a header row with the active item underlined | | |
| 34 | | **segmented control** `seg()` | `.seg > a` | — | `aria-current`, or `:has(:checked)` for radios | `‹ Open | Closed | All ›` | | |
| 35 | | **menu** `menu()` | `.menu` (`<details>`) | `data-align=start\|end` | open/closed | a popup list | | |
| 36 | | **disclosure** `disclosure()` | `.disclosure` (`<details>`, a quiet `›` summary) | `small` summary, `label` (aria-label), `extra` classes | open/closed; the chevron turns, the summary is at least 44px tall | a folded section | | |
| 37 | | **dialog** | `.dialog` | `data-side=bottom` (sheet) | JS `showModal()`; every dialog has a real page behind it | a modal box | | |
| 38 | | **tooltip** | `[data-tip]` | `data-tip-side=bottom` | hover/focus; hidden on coarse pointers | a status-bar hint | | |
| 39 | | **toast / flash** `Flash` | `.toast` | `data-tone=success\|danger\|attn` | one per page load, cookie-driven | a one-line banner | | |
| 40 | | **command palette** | `.palette` | — | JS only; degrades to `/search` | a fuzzy-find overlay | | |
| 41 | | **breadcrumb** `crumbs()` | `.crumbs` | `.mono` | `aria-current` on the last | `a / b / c` | | |
| 42 | | **pagination** `pager()` | `.pager` | — | cursor links, absent ends | `‹ Newer Page 2 Older ›` | | |
| 43 | | **timeline item** `tlEvent()` / `tlComment()` | `.tl-item` | `data-kind=comment\|event`, `data-tone` | — | a card, or one dim line with a glyph | | |
| 44 | | **empty state** `empty()` | `.card.empty`, title `.empty-title` | — | icon, one title, one sentence, **exactly one** action | the same three lines, centered | | |
| 45 | | **diff file** | `.diff-file` | `data-status`, `<details open>`, `.diff-viewed` | collapsed, viewed | a foldable file section | | |
| 46 | | **code block** | `.code` | `:target` / `[data-hl]` line highlight | — | a numbered gutter | | |
| 47 | | **prose** | `.prose` | — | 15px, 72ch measure | wrapped markdown | | |
| 48 | | **settings shell** `settingsLayout()` | `.settings` (`.settings-nav`, `.settings-main`) | — | sticky nav ≥860px, scroll strip below | a sidebar and a pane | | |
| 49 | | **repo header** `repoHeader()` | `.repo-head` | — | tab counts, Settings only for admins | a title line and a tab row | | |
| 50 | | **where strip** `whereStrip()` (`scope.ts`) | `.where > .where-place` | `data-state=reading\|present\|absent` — accent dot, success dot, faint dot — the dot is the place's `aria-hidden` glyph span, its aside `.muted` | three places, always in this order and these words; a place is a link where one exists, and the third is the pin toggle | `● codeberg.org · ● workbench · ◆ this machine` | | |
| 51 | | **live-browse banner** `liveBanner()` | `.live-note` | — | only on a live browse, above the content, one sentence | one accent line under the tab row | | |
| 52 | | **where-it-lives block** | `.where-block` | — | origin, last fetch, Sync now and where pushes land, as one block in the About rail | the same four lines under a rule | | |
| 53 | | **mirror stages** `stageList()` | `ol.list.stages[aria-live=polite] > li > .row` | `data-state=done\|now\|todo\|failed` (failed: the stage the job stopped on, a danger "Failed" badge) | the stage order is the markup order; a script updates it in place and goes to the mirror on done; without JavaScript the same markup renders and a `<noscript>` Reload link re-reads it. Nothing here refreshes itself: no `<meta refresh>`, no timer | a checklist with `●`/`◐`/`○` | | |
| 54 | | **origin chip** (`chrome.ts`) | `.repo-origin > .origin-chip` | the forge's mark: `github` / `forgejo` / `gitea` | the older one-line form, still used off the repo header | one `mirrored from owner/name @ host` fact line | | |
| 55 | | **origin state badge** `badge()` | `.badge` | `success` healthy · `danger` needs re-auth · `attn` error | the error message sits under the row, never inside the badge | the same three words beside the row | | |
| 56 | | **imported author** `originTag()` | `.byline.origin-by` | the origin's mark instead of an avatar | never a link to `/name` — that would be a different person | `▲ login` | | |
| 57 | | **pin toggle** `whereRow()` | `.repo-where form.where-pin > .btn` | `outline` unpinned · `secondary` pinned | reads `Keep on my machine` / `On my machine ◆`; the strip's third place submits the same form by id, so a `<button>` can sit in a row of links; the wanted state rides the form, so a double submit is idempotent | `p` on a row, `P` on a repo home; `◆` marks a pinned row | | |
| 58 | | **device code** | `.device-code` | — | the one deliberately large type in the product: monospace, tabular, `user-select: all` | the code spaced out and centred in a card, with a spinner under it | | |
| 59 | | **sticky action** `stickyAction()` | `.sticky-action` | — | static ≥720px | a footer action bar | | |
| 60 | | **count group** `counts()` / `repoCounts()` | `.counts > .count` | — | icon plus a tabular number; **a zero is never drawn** — the absence is the same information | `⊙3 ⑂1` after the row title | | |
| 61 | | **file explorer** `explorerColumn()` | `.code-layout` (`.explorer-panel`, `.explorer`, `.ex-dir`, `.ex-file`, `.ex-more`) | — | the path's ancestors arrive `open`; the current file is `aria-current`; a folder off the spine holds one `.ex-more` link so it works with no script | a left pane the cursor walks | | |
| 62 | | **fuzzy finder** `finderDialog()` | `.dialog.palette.finder` | — | JS only; `t` opens it, the explorer beside it is the fallback | the file picker overlay | | |
| 63 | | **file editor** | `.editor-form` (`.editor-head`, `.editor-wrap`, `textarea.editor`, `.editor-gutter`, `.editor-commit`) | — | a plain `<textarea>` in a `<form>`; the gutter, tab key, auto-indent and Preview tab are all enhancement | a modal buffer with a commit prompt | | |
| 64 | | **branch row** | `.branch-row` (`.branch-div` → `.ahead` / `.behind`) | — | default first, `Default` and `Protected` badges, `↑ahead ↓behind` | one line per branch with the same arrows | | |
| 65 | | **code hit** | `.code-hit` (`.code-line`, `mark`) | — | `path:line` in mono, the matching line beneath it with the query marked | the same two lines, the match reversed | | |
| 66 | | **verdict badge** `verdictBadge()` | `.badge` / `.badge.verdict-stale` | `success` approved · `danger` changes requested · plain commented | a verdict passed before the latest push renders `.verdict-stale`: same words, no colour, and the line says "before the latest push". It is history, not a position — and an approval a push dismissed must never look current | `[✓ approved]` / `[! changes]`, dim when stale | | |
| 67 | | **reviews chip** | `.reviews-chip` | — | one line inside the merge box: `✓ 2 approvals · ! changes requested by bob · an approval is required`. It names people, because a name is somebody to go and talk to and a number is not | the same line under the merge verdict | | |
| 68 | | **review card** | `.card.review-card` (`.review-verdicts`) | — | one form, radios plus an optional body. Which radios appear is the rule made visible: no Approve for the author, none of the gating verdicts for a reader — both refused in `submitReview` too | a three-way prompt with a body field | | |
| 69 | | **review thread** | `.dc-review` (a `card()` per thread) | — | open: the comments, then Resolve. Settled: **one line** — `✓ resolved by alice · 2h ago` — with the conversation behind a small `disclosure()` and Unresolve in the card's foot. Resolving is for getting an answered question out of the way of the unanswered ones | a folded thread with a `✓` header | | |
| 70 | | **propose card** | `fieldset.editor-target.propose` (`.propose-line`) | — | replaces "Where this lands" when the change is a contribution: the whole outcome in one sentence with **both** repository names, then branch, pull title and pull body. There is no "commit directly" radio, because there is no such option | the same sentence above the commit prompt | | |
| 71 | | **run state badge** `runStateBadge()` | `.badge` | `queued` · `running` (attn) · `ok` (success: _Passed_, or _Done_ for an agent run) · `failed` (danger) · `cancelled` (outline) | the one badge a check wears on a pull, a run wears in a list, and a log page wears in its head; the log page's script repaints it on `done` | `[✓ passed]` / `[✗ failed]` / `[· running]` | | |
| 72 | | **env state badge** `envStateBadge()` | `.badge` | `stopped` (outline) · `deploying` (attn) · `running` (success) · `failed` (danger) | what production, or a preview, is doing now; `envTone()` is the same answer as a `dot()` for a list row | the same word in the same tone after the environment's name | | |
| 73 | | **app strip** | `.app-strip` | — | one line under the repo header of a repository that runs: env state badge, `sha`, the production URL as a link **through `…/app/production/open`** (never the bare hostname — a private app would 404), the preview count, the pace (`first preview 2m 14s after New app · in production 9m`, each part once it exists), App (the studio app page)| one line under the where strip: `● running abc1234 · hello.localhost` | | |
| 74 | | **environment card** | `.card.env-card` (`.env-facts`, `.env-error`) | `data-tone=danger` when failed | name and state in the head; `envFacts()` in the body — commit, how fast it came up, uptime, a link to the deploy run, and the deployment's own note and error, each on its own line; Open (or Wake it) below. It is a pull's preview card; the facts and `envActions()` (Redeploy / Stop, writers only) are functions, not markup, so the studio head and its preview rows render the same ones | a box per environment with the same three lines | | |
| 75 | | **checks line** | `.checks-line` (`.ok`, `.bad`, `.now`) | — | inside the merge box, in the reviews chip's voice: `✓ Checks passed · deploy abc1234 · a passing deploy is required`. Rendered only where the repository runs as an app or requires checks; a merge box gains _Waiting on checks_ | the same line under the review line | | |
| 76 | | **run log** | `pre.run-log` | `data-run` while the run is going | the log as written, wrapped so a phone never scrolls sideways; a script appends the run's lines from the page's one `/events` stream and follows the bottom until the reader scrolls up; the page never reloads itself | a scrolling pane that follows the tail | | |
| 77 | | **assignee card** | `.card` with an `.edit-row` form | — | who is on it, then one select and one button for a writer. People first, the crew last and marked `(agent)`, because assigning an agent is what starts it working and the choice is not the same kind of choice | a picker with people, then agents | | |
| 78 | | **inbox** (`asks_page.ts`) | one list above the feed | — | _On you_: what asks you and what is assigned to you, one row each, each with what it waits for (`needsYouSection`), and one count in the top bar. Absent when empty: a card saying nothing is a zero drawn | the same two panes on the dashboard | | |
| 79 | | **look** (`pages/looks.ts`) | `.look` in a `.looks` strip | `.look[data-slot=phone\|desktop\|thumb\|now]` sizes the frame; `.looks[data-compare]` sets two sides (before · main, then after · the pull) beside each other | a picture always carries its own `width`/`height`, so nothing shifts when it loads; a phone keeps 200px, a desktop takes the rest up to its own size, and under 640px a strip stacks; an attached picture is a `figure` in the strip with its line under it | the picture in the terminal (§6·0c) | | |
| 80 | | **board** (`pages/board.ts`) | `.board` (`.board-grid`, `.board-region`) | `data-wall` (across the room: no keys, no pointer, larger), `data-focus=working\|landed\|decided\|today` | the one whole-screen layout: four live regions fill a second monitor ≥1100px and each list scrolls on its own, one column below; above the panels only a collapsed one-line `#notes` (`<details>`: closed by default, an open list stays open across live swaps), the strips below them; inside, only §5 parts (list card rows, badges, meters, `kbd`); a swapped region's heading wears `data-fresh` for a moment | four panes, one focused by its number | | |
| 81 | | **stacked bar chart** `windowSvg()` (`fleet-graph.ts`) | `.plots`, `.plot` (`.plot-name`), `.plot-legend` | bars wear `fg-sN`, the `--series-N` token | server-drawn SVG with `width`/`height` set, so it holds its box before the stylesheet; gridlines `--border`, figures `--muted-fg` in mono, panel names `--faint`; `role="img"` with an `aria-label` totalling it, a `<title>` per bar, and a table of the same numbers beside it | a table of the same numbers | | |
| 82 | | **chart** `chartBox()` (`ui.ts`) | `.chart-box` wrapping `drawChart`'s svg `.chart` (`.big` for the headline figure) | `.is-table` for a table panel | one query or series drawn on the server: the svg carries its own `width`/`height` and the box holds its space, so nothing shifts; `role="img"` with an `aria-label` of its title. Reach for it wherever a page draws a `boards/chart.ts` chart — `/system`'s memory pair and every board panel — and size it from the page (`.bp-*`, `.plots`, `.bgrid`), never inside the frame | the same numbers as a table | | |
| 83 | ||
| 84 | Two things are deliberately **not** in the vocabulary: skeleton loaders (the | |
| 85 | server renders whole pages — there is nothing to skeletonise) and a custom | |
| 86 | switch control (a native checkbox with `accent-color` is themed, keyboard-correct | |
| 87 | and honest about what it is). | |
| 88 | ||
| 89 | Three rules the browser enforces whether or not you meant them: | |
| 90 | ||
| 91 | - **A name says who it is, and nobody types that.** Beside the owner's name | |
| 92 | and each agent's, `userLink()` wears a `nameMark()` — `owner`, `crew` — | |
| 93 | drawn from the account (`core/marks.ts`: an admin who is a person; an | |
| 94 | agent), never from a display name. Every name is escaped, so no typed word, | |
| 95 | alphabet or emoji produces the `data-mark` element; a byline without one is | |
| 96 | nobody the mark vouches for. A page asks `marksByName()` once for the names | |
| 97 | it will show. `test/name-marks.test.ts` tries the disguises. | |
| 98 | - **A link inside a link is not a link.** `<a>` nested in `<a>` is not merely | |
| 99 | invalid — the parser closes the outer anchor and re-parents everything after | |
| 100 | it as a _sibling_, so the row visibly falls apart. Anything rendered inside a | |
| 101 | linked `.row` uses the non-anchor form: `userTag()`, not `userLink()`; plain | |
| 102 | text, not a repo link. `test/web-ui.test.ts` sweeps the list pages for it. | |
| 103 | - **Whitespace is content inside `white-space: pre`.** The diff cell (`.dc`) is | |
| 104 | pre-formatted, so a pretty-printer's newline between `<td>` and its span | |
| 105 | renders as a blank line and an indent. Assemble such a cell into one value | |
| 106 | and interpolate it whole; `.dcx` holds the `pre`, so a stray newline costs a | |
| 107 | collapsed space rather than a broken line. | |
| 108 | - **A grid or flex item's automatic minimum size is its content.** A column | |
| 109 | holding one long unbreakable line pushes the page wider than the phone | |
| 110 | instead of letting its own ellipsis work. Every page grid sets | |
| 111 | `min-width: 0` on its children. |
docs/design/sections/5a-reading-from.md added +35
| @@ -0,0 +1,35 @@ | ||
| 1 | ### 5a. Saying where you are reading from | |
| 2 | ||
| 3 | Every repository page in the product carries the **where strip**, and it says | |
| 4 | the same three things in the same order however you got there: | |
| 5 | ||
| 6 | ||
| 7 | ● codeberg.org · ○ workbench · ○ this machine browsing live, read-only | |
| 8 | ● codeberg.org · ● workbench (synced 3m ago) · ◆ this machine a mirror you keep | |
| 9 | ● workbench · ○ this machine a repository born here | |
| 10 | ||
| 11 | ||
| 12 | - **Filled `●` means present, hollow `○` means absent, `◆` means kept on this | |
| 13 | machine.** The dot carries the colour; the word never does, so a strip reads | |
| 14 | as one fact rather than three competing badges. | |
| 15 | - **Accent marks the place these bytes came from.** That is the page's own | |
| 16 | subject, which is the one thing accent is allowed to be besides interaction | |
| 17 | (§1.2). Exactly one place per strip wears it. | |
| 18 | - **Every place is a link where one exists**: the origin goes to the repository | |
| 19 | on that forge, the workbench to the mirror here, and "this machine" submits | |
| 20 | the pin toggle. | |
| 21 | - A repository that is **your fork of** another one says so in the strip, as | |
| 22 | the origin place's aside: `● codeberg.org (fork of octo/widgets)`. The About | |
| 23 | rail carries the same fact as a linked `Fork of` row — the strip is for | |
| 24 | orienting, the rail is for going there. | |
| 25 | - A live browse also carries `.live-note` above the content, saying it is | |
| 26 | read-only and what to do about that. There is no second way to find out: a | |
| 27 | live page renders no composer, no state form, no labels form, no merge box | |
| 28 | and no settings tab, because `RepoSource` has no mutation on it to submit to. | |
| 29 | The three forms it does carry — Mirror, Fork, Propose a change — create | |
| 30 | something **for you**: a copy here, a fork of your own there, a proposal on | |
| 31 | it. None of them changes the repository being read. | |
| 32 | ||
| 33 | The strip is the visible half of `RepoScope` (`src/web/scope.ts`); the pages it | |
| 34 | sits on are the same renderers for both sides of the world, and a divergence | |
| 35 | between a live browse and the repository we hold would be a bug you could see. |
docs/design/sections/5b-workflow-units.md added +42
| @@ -0,0 +1,42 @@ | ||
| 1 | ### 5b. The workflow units | |
| 2 | ||
| 3 | A unit is a whole intention with one button behind it, not a sequence of | |
| 4 | screens you assemble yourself. Five of them, and the web renders each as one | |
| 5 | form: | |
| 6 | ||
| 7 | **Fork** — on a live browse and on every picker row you cannot push to. It | |
| 8 | POSTs `…/fork`, forks at the origin, and answers with the mirror job page, | |
| 9 | exactly as Mirror does, because the local copy of a fork is a job with stages. | |
| 10 | The flash names both halves and the host: `Forked octo/widgets to me/widgets at | |
| 11 | codeberg.org.` Not offered on a repository the connected account already owns — | |
| 12 | neither forge forks you to yourself. A native repo keeps its own `…/fork`. | |
| 13 | ||
| 14 | **Propose a change** — where the origin says you may not push, Edit and New | |
| 15 | file become Propose a change and open the ordinary editor with the propose card | |
| 16 | under it. One POST to `…/contribute` forks if needed, branches on the fork, | |
| 17 | commits, and opens the pull upstream with the `owner:branch` head form. You land | |
| 18 | on the pull: its page here if we mirror the upstream, its live-browse page if we | |
| 19 | do not — never thrown out to another forge mid-workflow. Every refusal | |
| 20 | re-renders the editor with the text still in the textarea (`§6c`'s rule: never | |
| 21 | lose a keystroke). | |
| 22 | ||
| 23 | **Pass a verdict** — the review card, one POST to `…/review-state`. Verdicts | |
| 24 | land in the timeline as `verdictBadge` items in time order with the comments and | |
| 25 | the state changes, because a verdict is a thing that happened at a time. | |
| 26 | ||
| 27 | **Settle a thread** — every review comment sharing an anchor is one | |
| 28 | conversation, resolved by a writer or by anybody in it, at | |
| 29 | `…/threads/:anchor/{resolve,unresolve}`. The files header counts them: | |
| 30 | `3 threads · 1 unresolved`. | |
| 31 | ||
| 32 | **Merge, or not** — the merge box gains a sixth state, _Waiting on review_, | |
| 33 | whenever `require_review` is unsatisfied or a change is outstanding. The button | |
| 34 | is disabled and the chip says who to talk to; the refusal is `mergePull`'s | |
| 35 | (`review_required`), and the disabled button is only the honest preview of it. | |
| 36 | `Require an approving review before merging` is a checkbox in General settings. | |
| 37 | ||
| 38 | One rule holds all five: **the page never decides.** Every affordance here is | |
| 39 | rendered from the same answer the action will give — `permissions.push` for | |
| 40 | propose, `status.reviews` for the gate, `canWrite` plus thread authorship for | |
| 41 | resolve — so a button that is absent and a call that is refused are the same | |
| 42 | fact said twice, and never two different facts. |
docs/design/sections/5c-apps-runs-crew.md added +51
| @@ -0,0 +1,51 @@ | ||
| 1 | ### 5c. Apps, runs and the crew | |
| 2 | ||
| 3 | `docs/APPS.md` is the contract; these are its units on a page, and the same | |
| 4 | rule holds: the page never decides. Six of them: | |
| 5 | ||
| 6 | **New app** — `/apps/new`, one form: a name, a sentence about what it should | |
| 7 | do, visibility, and an agent from the crew when there is one. One POST makes | |
| 8 | the repository with a working app in it, makes it an app, starts production, | |
| 9 | and — with a sentence and an agent — opens issue #1 assigned. The flash names | |
| 10 | the production URL and the agent. A forge with no agents says so on the form | |
| 11 | in one line and offers the same button without the select. | |
| 12 | ||
| 13 | **Run as an app** — on a repository's settings, the App section: enable with a | |
| 14 | slug, an access choice and the preview-data policy; edit them; disable behind | |
| 15 | a confirm page. The app strip (§5) appears on the repository the moment it is | |
| 16 | on. | |
| 17 | ||
| 18 | **Open** — never the bare hostname. Every link to an environment goes through | |
| 19 | `…/app/:env/open`, which checks `canRead` and answers with the URL — carrying a | |
| 20 | grant for a private app — so the same link works for a public app and a | |
| 21 | private one and a stranger gets `not_found` from the forge rather than a | |
| 22 | guess at a hostname. | |
| 23 | ||
| 24 | **Redeploy / Stop** — two POSTs on the studio app page (`studio/app.ts`; | |
| 25 | dev's old `/:owner/:name/app` redirects there), writers only: production's | |
| 26 | in the head card, each preview's on its row; a stop keeps the data (a | |
| 27 | redeploy brings it back), a stopped environment shows the honest word and | |
| 28 | the run that stopped it. | |
| 29 | ||
| 30 | **Assign** — the assignee card on an issue and a pull: nobody, then people | |
| 31 | who can read the repository, then the crew marked as agents. Assigning an | |
| 32 | agent is the dispatch, so the select says so beside the crew. An agent's own | |
| 33 | pull opens already assigned to it. | |
| 34 | ||
| 35 | **Cancel a run** — one POST on the run page while it is unfinished; the log | |
| 36 | keeps everything up to the cancel and the badge says `cancelled`. | |
| 37 | ||
| 38 | The merge box gains a seventh state, _Waiting on checks_, when | |
| 39 | `require_checks` is on and the head's deploy is not green; the refusal is | |
| 40 | `mergePull`'s (`checks_required`) and the chip links the run. A pull's | |
| 41 | **Preview** card and its **Checks** line read the same run rows a | |
| 42 | `runStateBadge` does elsewhere — a check is a deploy, never a separate | |
| 43 | object that can drift. | |
| 44 | ||
| 45 | **Website spec findings** — under a pull's Checks line, from the preview's | |
| 46 | latest deploy run (`core/preview_findings.ts`): a **disclosure** whose | |
| 47 | summary is the count (edge-owned findings counted apart) and whose body is | |
| 48 | a `.list` of `.row`s, one per finding, with its specification.website | |
| 49 | section as an https link. Report-only, so the words never say failed; the | |
| 50 | summary is at least 44px tall for a thumb. The terminal says the same count | |
| 51 | at the end of the checks row. |
docs/design/sections/5d-page-local-classes.md added +62
| @@ -0,0 +1,62 @@ | ||
| 1 | ### 5d. Page-local classes | |
| 2 | ||
| 3 | The close form on an issue's thread is no class at all: its reason select and | |
| 4 | "close into" input are plain §5 inputs, the height of the Comment button beside them, and `style/content.ts` shows the | |
| 5 | input only while "split into…" is chosen, by attribute selector inside | |
| 6 | `.form-actions` (`select[name="reason"]`, `input[name="into"]`). It is a rule | |
| 7 | about the form, not a component. | |
| 8 | ||
| 9 | Every class a stylesheet defines is named in this section (`bun | |
| 10 | scripts/design-lint.ts` fails one that is not, #2700). The table above is | |
| 11 | the vocabulary; the classes below are what pages built beside it before that | |
| 12 | rule held. They are registered, not endorsed: each belongs to the file it is | |
| 13 | listed under, and a new page reaches for §5's components instead of | |
| 14 | borrowing one. The plan (`docs/design/plan.md`) retires them page by page — | |
| 15 | onto a §5 component, or into the table when a page-local thing turns out to | |
| 16 | be a component — and the check fails a name kept here after its last rule is | |
| 17 | gone, so this list only shrinks. Each class sits on its own line, so to | |
| 18 | retire a class, delete its line: two pulls retiring two classes never edit | |
| 19 | the same line (#4888). | |
| 20 | ||
| 21 | - **`style/base.ts`** — the page shell (topbar, main, footer) and the layout and text utilities every page leans on: | |
| 22 | - `.bar` | |
| 23 | - `.bare` | |
| 24 | - `.foot` | |
| 25 | - `.hide-sm` | |
| 26 | - `.js-only` | |
| 27 | - `.reduced` | |
| 28 | - `.shell` | |
| 29 | - `.skip` | |
| 30 | - `.topbar` | |
| 31 | - `.wordmark` | |
| 32 | ||
| 33 | A `.field` directly inside a `.bar` drops its bottom margin and the bar aligns to the end, so a labelled input and its button share a baseline | |
| 34 | - **`style/components.ts`** — parts of the §5 components that the table does not spell out — the palette's list, the menu's items, a dialog's head and foot, comments, the theme picker — and a few small helpers beside them: | |
| 35 | - `.cat` | |
| 36 | - `.error-note` | |
| 37 | - `.list` | |
| 38 | - `.menu-item` | |
| 39 | - `.preview` | |
| 40 | - `.sep` | |
| 41 | - `.split` | |
| 42 | - `.swatch` | |
| 43 | ||
| 44 | `.split` is the one two-column page: main, then an `<aside>` rail of 260px that sticks from 960px. `data-rail="wide"` on it (the studio's home and an app's page) widens the rail to 320px from 900px, drops the top margin, and lets the rail scroll with the page, since a column of cards runs taller than a screen | |
| 45 | - **`style/content.ts`, page furniture** — what frames a page's content: page and repo heads, the front page and its tiles, explore, backups, boards, the fleet chart's series colours, lineage: | |
| 46 | - `.bgrid` | |
| 47 | - `.bp-h2` | |
| 48 | - `.bp-h3` | |
| 49 | - `.bp-w2` | |
| 50 | - `.bp-w3` | |
| 51 | - `.commit-body` | |
| 52 | - `.commit-head` | |
| 53 | - `.filters` | |
| 54 | - `.owner` | |
| 55 | - `.page-head` | |
| 56 | - `.policy-line` | |
| 57 | - `.repo-actions` | |
| 58 | - `.repo-desc` | |
| 59 | - `.slash` | |
| 60 | - **`style/content.ts`, apps, runs, and the crew** — run pages, their logs and checks (a pull's look is §5's **look**). | |
| 61 | - **`pages/board.ts`** — the board itself is §5's **board**; the spend tables `spend.ts` draws wear §5's `.table` and `.stack`, no class of their own | |
| 62 | - **`studio/feed_style.ts`** — the home feed's cards and its composer (the apps rail is §5's card, row and btn; an admin's tick boxes and Archive are always shown, deliberately, with no Select toggle): |
docs/design/sections/6-0-pointer.md added +50
| @@ -0,0 +1,50 @@ | ||
| 1 | ### 6·0. The pointer | |
| 2 | ||
| 3 | The terminal UI is keyboard-first and mouse-**complete**: everything you can | |
| 4 | see is something you can click, and clicking never reaches somewhere the | |
| 5 | keyboard could not. Reporting is on from the moment a session starts | |
| 6 | (`?1000h ?1002h ?1006h`, SGR coordinates last) and off before the alt screen | |
| 7 | is left. The one cost is real and is said out loud in the `?` overlay: | |
| 8 | **shift-drag** is now how you select text, because the terminal's own | |
| 9 | selection is what mouse reporting takes away. | |
| 10 | ||
| 11 | **The model is a hit table rebuilt every frame.** During `render`, a screen | |
| 12 | claims rectangles with `ctx.hit(rect, handler)`: | |
| 13 | ||
| 14 | ts | |
| 15 | ctx.hit(rect, (e) => open(rows[e.y])); // click only | |
| 16 | ctx.hit(rect, { click, wheel }); // and the wheel | |
| 17 | ||
| 18 | ||
| 19 | The registry is cleared at the top of every paint and rebuilt by whoever | |
| 20 | draws, so a region can never outlive the pixels it stands for — the bug every | |
| 21 | retained hit table eventually has. Regions are searched **newest-first**, so | |
| 22 | whatever drew last is what a click reaches: an overlay draws after the screen | |
| 23 | beneath it, and needs no z-index to win. A region that does not handle _this_ | |
| 24 | gesture is not in the way of one that does, so the wheel over a clickable row | |
| 25 | still scrolls the list the row is in. | |
| 26 | ||
| 27 | Four rules hold the gestures together: | |
| 28 | ||
| 29 | - **A click selects; a second click on the selected row opens it.** So does a | |
| 30 | double-click on any row. A single click has to be safe, because half of | |
| 31 | pointing at a row is looking at it, and a list where looking navigates is a | |
| 32 | list you cannot browse. | |
| 33 | - **One notch is three rows**, delivered to the region under the pointer. A | |
| 34 | notch nobody claimed falls back to arrow keys, which is what a wheel has | |
| 35 | always meant. | |
| 36 | - **Mouse input is never a synthetic keystroke.** Nothing reaches | |
| 37 | `Screen.key`; a screen that wants a click says so with `ctx.hit`. The | |
| 38 | keyboard behaviour of every screen is unchanged by any of this. | |
| 39 | - **A click on an overlay's dimmed backdrop dismisses it**, and does not reach | |
| 40 | the row underneath. | |
| 41 | ||
| 42 | Clickable today: every list row, the dashboard's four panes, the workspace's | |
| 43 | explorer rows and tab chips (including the active tab's `✗`), the file pane | |
| 44 | (focus, and the wheel), the where-strip's three places, the palette's results, | |
| 45 | the appearance picker's rows, the owner, refs, settings, account | |
| 46 | lists, the pull's diff-and-threads pane, and **every | |
| 47 | hint in the help bar** — clicking a hint presses the key it names, taken from | |
| 48 | the binding itself so a label can never drift from the action. A list with no | |
| 49 | `hitList` is a bug, not a design decision: "everything you can see is | |
| 50 | something you can click" is the whole claim. |
docs/design/sections/6-0a-1-terminal-layout.md added +24
| @@ -0,0 +1,24 @@ | ||
| 1 | ### 6·0a·1. Laid out for the terminal it is in | |
| 2 | ||
| 3 | Three numbers in `ui/layout.ts` decide every screen's shape, so every screen | |
| 4 | folds at the same width and none invents its own. At **100 columns** a list | |
| 5 | sits beside its detail; below, `beside()` stacks the two with the detail | |
| 6 | underneath (two fifths of the height unless the screen says otherwise), and | |
| 7 | drops it only when there are fewer than twelve rows to share. Under **40×10** | |
| 8 | no layout survives — a card is narrower than its title — so one line says what | |
| 9 | would help, and every screen keeps its state for the moment the window grows. | |
| 10 | ||
| 11 | A resize re-lays the current screen at once and loses nothing: a list keeps | |
| 12 | its cursor and scrolls it back into view, a log keeps the _line_ at the top | |
| 13 | of the reader's window whatever number of rows it now wraps to, and a program | |
| 14 | holding the pty (`$FORGE_EDITOR`, an app's `tty`) hears the new size before | |
| 15 | the UI does. Long text wraps or ends in an ellipsis at the width, never past | |
| 16 | it. A row's meta gives way before its title starves — the leading pieces | |
| 17 | (`metaOf` order: a commit, then a cost, then the time) go first, the last one | |
| 18 | last — and a table's ranked columns (`drop`) are given up lowest first, the | |
| 19 | same word `local/rows.ts` uses. | |
| 20 | ||
| 21 | An activity row is one line, not two, because a row is a thing you can put a | |
| 22 | cursor on: `who did what · the object`, with the time in a fixed right-hand | |
| 23 | column. The headline already ends with `#4`, so the object drops the repeated | |
| 24 | number rather than truncating the title. |
docs/design/sections/6-0a-dashboard-panes.md added +13
| @@ -0,0 +1,13 @@ | ||
| 1 | ### 6·0a. The dashboard's panes | |
| 2 | ||
| 3 | `Repositories`, `Recent activity`, `On you`, `On your machine`, | |
| 4 | `Organizations`. What is running is the studio's question, on the web; the | |
| 5 | terminal's dashboard is the code and the conversations. Each is a pane with its own cursor: `tab` / `shift+tab` cycles, the focused one wears | |
| 6 | the accent frame, `j`/`k` move inside it and `enter` opens what it is pointing | |
| 7 | at — an activity row opens **the issue, pull or repository it is about**, a | |
| 8 | pin opens its repository, an organization opens its page. `d` on a pinned row | |
| 9 | unpins it (asking first). A click does all of the same. Below 100 columns the | |
| 10 | activity feed stacks under the repository list and the three small cards wait | |
| 11 | for a wider window; shorter than twelve body rows, the repositories have the | |
| 12 | whole body. `tab` reaches exactly the panes the last frame drew: a focus ring | |
| 13 | on a card that is not on screen is worse than no focus ring. |
docs/design/sections/6-0b-icons-appearance.md added +32
| @@ -0,0 +1,32 @@ | ||
| 1 | ### 6·0b. Icons, and the appearance picker | |
| 2 | ||
| 3 | Two vocabularies. **`plain`** is the safe set (§6a) — BMP, width 1, in every | |
| 4 | default terminal font. **`nerd`** is the same vocabulary drawn from a Nerd | |
| 5 | Font, which is a bet on the reader's _font_, a thing `TERM` cannot tell us. | |
| 6 | `auto` takes the bet on Ghostty, kitty and WezTerm, because those are | |
| 7 | terminals people install deliberately and installing a Nerd Font is the next | |
| 8 | thing those people do. Everything else gets `plain`. | |
| 9 | ||
| 10 | The bet is bounded: every glyph in both sets is exactly one cell (asserted by | |
| 11 | `test/tui-icons.test.ts`, since every Nerd codepoint lives in a Private Use | |
| 12 | Area that `width.ts` measures as width 1), so a missing glyph is one tofu box | |
| 13 | and never a shifted row. Where the two sets would say different things, the | |
| 14 | plain set keeps the documented grammar: `◆` still means "kept on your | |
| 15 | machine", and an unpinned row still wears nothing. | |
| 16 | ||
| 17 | `ctrl+t` opens **Appearance**: the six themes, then two more rows — | |
| 18 | ||
| 19 | | row | values | | |
| 20 | | -------- | --------------------------------------------- | | |
| 21 | | `Images` | `auto (kitty)` · kitty · sixel · iterm · none | | |
| 22 | | `Icons` | `auto (nerd)` · nerd · plain | | |
| 23 | ||
| 24 | `j`/`k` move, `left`/`right`/`enter` cycle a setting's value, a theme applies | |
| 25 | as the cursor passes over it, and both settings persist through | |
| 26 | `setPreference` into `user_setting`. It is `ctrl+t` and not `t` because the | |
| 27 | workspace already spends `t` on the file finder, and an appearance picker | |
| 28 | that silently does nothing on the one screen people live in is worse than a | |
| 29 | modifier: one key, every screen, whatever has focus. Under the rows is a **live preview** — | |
| 30 | three real icons in the set currently chosen — because the only honest way to | |
| 31 | settle a bet about somebody's font is to show them three glyphs and let them | |
| 32 | look. If they see boxes, one keypress puts it back. |
docs/design/sections/6-0c-terminal-pictures.md added +22
| @@ -0,0 +1,22 @@ | ||
| 1 | ### 6·0c. Pictures in the terminal | |
| 2 | ||
| 3 | A tab whose path looks like an image and whose bytes git returned as binary is | |
| 4 | a **picture tab**. Where the terminal can show pixels it does | |
| 5 | (§`term/graphics.ts`: kitty for Ghostty/kitty/WezTerm, sixel where detected, | |
| 6 | iTerm2 by setting); where it cannot, a placeholder card names the format, the | |
| 7 | geometry and the size, and says plainly what would show it. | |
| 8 | ||
| 9 | The loop owns the lifecycle. A screen calls `ctx.placeImage(placement)` during | |
| 10 | render and the bytes go out **after** the frame, raw; not calling it removes | |
| 11 | whatever the last frame placed. That one rule makes a tab switch, a close, a | |
| 12 | `pop`, a resize and a theme change all clean up by themselves, with no screen | |
| 13 | having to remember to. A placement is re-sent only when it is genuinely new — | |
| 14 | a different image, a different rectangle, or a repaint that invalidated | |
| 15 | everything — because `drawImage` reserves its cells with the theme ground and | |
| 16 | an ordinary frame emits nothing over them. Re-sending a megabyte of base64 on | |
| 17 | every keystroke is the one thing that would make pictures unusable over SSH. | |
| 18 | ||
| 19 | Aspect ratio comes from the client's own `pty-req` / `window-change` pixel | |
| 20 | fields when it sends them (most send zeros), and from the 1:2 guess otherwise. | |
| 21 | ||
| 22 | `v` toggles a picture between the pixels and the facts about the file. |
docs/design/sections/6-keyboard.md added +34
| @@ -0,0 +1,34 @@ | ||
| 1 | ## 6. Keyboard | |
| 2 | ||
| 3 | Driven entirely from the DOM: `data-shortcut="g i"` on a link, `data-nav` on a | |
| 4 | row. The `?` overlay is generated by walking `[data-shortcut]`, so the help can | |
| 5 | never drift from the app. | |
| 6 | ||
| 7 | | key | action | | |
| 8 | | --------------- | ---------------------------------------------- | | |
| 9 | | `g h` | home | | |
| 10 | | `g c` | repo code | | |
| 11 | | `g i` | issues | | |
| 12 | | `g p` | pull requests | | |
| 13 | | `g m` | commits | | |
| 14 | | `g b` | branches | | |
| 15 | | `g s` | repo settings | | |
| 16 | | `j` / `k` | next / previous row (visible focus ring) | | |
| 17 | | `o` or `Enter` | open the focused row | | |
| 18 | | `c` | the page's create action (new issue, new pull) | | |
| 19 | | `t` | go to file (the fuzzy finder), on a code page | | |
| 20 | | `e` | edit the file you are looking at | | |
| 21 | | `/` | focus search | | |
| 22 | | `⌘K` / `Ctrl K` | command palette | | |
| 23 | | `?` | shortcut help | | |
| 24 | | `Esc` | close a menu or dialog, blur a field | | |
| 25 | ||
| 26 | Inside the code view, shift-clicking a second line number extends `#L3` to | |
| 27 | `#L3-L9` and highlights the range. | |
| 28 | ||
| 29 | `t` and `e` are not a new key layer: they are `data-shortcut` attributes on | |
| 30 | the real controls, so the `?` overlay learns them for free and a page without | |
| 31 | those controls does not answer the key. `j`/`k` are the shell's own row | |
| 32 | traversal, and the explorer's files are `data-nav` rows — which is why | |
| 33 | arrowing through the tree previews as you go without a single extra key | |
| 34 | handler: `codeJs` listens for **focus**, not for keys. |
docs/design/sections/6a-code-browser.md added +33
| @@ -0,0 +1,33 @@ | ||
| 1 | ### 6a. The code browser | |
| 2 | ||
| 3 | Tree and blob pages are one layout, not two: a `.code-layout` grid with the | |
| 4 | explorer on the left and the content on the right at ≥900px, the explorer | |
| 5 | folding into a "Files" `<details>` above the content below it. | |
| 6 | ||
| 7 | - **The spine, not the tree.** A page renders the path's ancestors and their | |
| 8 | siblings, never the whole repository, so a monorepo costs the same markup as | |
| 9 | a toy. Every directory is a `<details>`; the ones on the spine arrive open. | |
| 10 | - **A folder the server did not expand is still a link.** Opening one with no | |
| 11 | script shows a single `Open src/…` link to that folder's own page; with a | |
| 12 | script, `codeJs` fetches `?fragment=explorer` and drops the rows in. | |
| 13 | - **The preview is the page.** Hovering or arrowing a file fetches the blob | |
| 14 | route's own `?fragment=1` — the same renderer, the same markup, the same | |
| 15 | `#code-pane` — so a preview and a real navigation are indistinguishable, and | |
| 16 | `enter` simply follows the link that was already there. Fetches are | |
| 17 | cancelled and cached, and there is no scroll-stealing or URL rewriting. | |
| 18 | - **The explorer opens closed and the stylesheet opens it.** `<details>` | |
| 19 | without `open`, plus `::details-content { content-visibility: visible }` at | |
| 20 | ≥900px. Where that pseudo-element is understood the handle is hidden too; | |
| 21 | where it is not, the handle stays and one click opens the column. Nothing | |
| 22 | can end up invisible with no way back. | |
| 23 | - **The finder is a dialog over JSON.** `t` (or the button) fetches | |
| 24 | `/:owner/:name/paths/:ref` once and scores it client-side with fzf's | |
| 25 | FuzzyMatchV2 constants under its `path` scheme — boundary 8, delimiter 9, | |
| 26 | camel 7, consecutive 4, match 16, gap −1, first character doubled, string | |
| 27 | start treated as though it followed a `/` — on top of a 28-bit | |
| 28 | characters-present bitmask prefilter and a two-pointer subsequence check, so | |
| 29 | the affine-gap DP only ever runs on real candidates. VS Code's tiering sits | |
| 30 | above the score rather than inside it: any match inside a file's own name | |
| 31 | outranks any match that only lands in its directories, and a basename | |
| 32 | _prefix_ outranks that again. Without a script the finder does not exist and | |
| 33 | the explorer beside it is the answer. |
docs/design/sections/6a-counts-and-marks.md added +21
| @@ -0,0 +1,21 @@ | ||
| 1 | ### 6a. Counts and marks on a row | |
| 2 | ||
| 3 | Three glyphs carry the at-a-glance numbers, all of them BMP, all width 1, all | |
| 4 | present in every default terminal font in wide use — no Nerd Font (we cannot | |
| 5 | assume a patched font over SSH) and no emoji (their width is genuinely | |
| 6 | inconsistent, and one column of error shifts an entire row): | |
| 7 | ||
| 8 | | glyph | means | where | | |
| 9 | | ----- | ----------- | ------------------------ | | |
| 10 | | `○` | open issues | every repo row | | |
| 11 | | `↳` | open pulls | every repo row | | |
| 12 | | `▭` | comments | every issue and pull row | | |
| 13 | ||
| 14 | They render muted, right-aligned in the row's meta column, and **tabular**: | |
| 15 | the widths are computed once across the whole page so the numbers form a | |
| 16 | column instead of jittering row to row. **Zero is absent, not `○ 0`** — an | |
| 17 | empty queue should read as quiet, and a column of zeroes reads as noise. | |
| 18 | ||
| 19 | The numbers come from grouped reads (`countsForRepos` / `withCounts`, | |
| 20 | `commentCountsFor`) and never from a query per row. `test/counts.test.ts` and | |
| 21 | `test/tui-code.test.ts` both assert that; a list is where N+1 hurts most. |
docs/design/sections/6b-code-coloured.md added +41
| @@ -0,0 +1,41 @@ | ||
| 1 | ### 6b. Code, coloured | |
| 2 | ||
| 3 | One tokenizer, `src/web/highlight.ts`, serves the file browser, the diff | |
| 4 | viewer, Markdown fences, the terminal UI and the browser bundle the editor | |
| 5 | loads. It is a stateful per-line scanner over rule tables — Prism's model, not | |
| 6 | a parser — and it is bound by three properties the tests assert for every | |
| 7 | language: **lossless** (a line's tokens concatenate back to the line), | |
| 8 | **linear** (10,000 characters in well under a millisecond, no backtracking | |
| 9 | regex), and **total** (random bytes never throw). | |
| 10 | ||
| 11 | Roughly thirty languages have rule tables, including the ones a forge actually | |
| 12 | holds: ts/tsx/js/jsx (template literals, regex-versus-division, decorators, | |
| 13 | JSX tags), python, go, rust, c/c++/objective-c, java, kotlin, swift, ruby, | |
| 14 | php, lua, zig, elixir, nix, sql, json/jsonc, yaml, toml, ini, markdown, | |
| 15 | css/scss, html, shell, dockerfile, makefile and diff. Detection is by | |
| 16 | extension, then by whole filename (`Dockerfile`, `Makefile`, `.zshrc`), then — | |
| 17 | only for a file that has said nothing else — by shebang or editor modeline: | |
| 18 | `detectLanguage(path, firstLine)`. | |
| 19 | ||
| 20 | **Two levels of token.** `cls` is the colour _every_ consumer understands — | |
| 21 | `keyword string comment number function type operator punctuation constant | |
| 22 | meta plain` — and it is what the terminal's theme table maps. `kind` is a | |
| 23 | refinement only the web paints: `property tag attribute regex variable | |
| 24 | decorator heading emphasis link inserted deleted`. A token renders as | |
| 25 | `class="tok-<cls> tok-<kind>"`, the kind rule comes last in the stylesheet and | |
| 26 | so wins at equal specificity, and dropping the kind leaves a page that is less | |
| 27 | specific but never wrong. That is the whole reason the vocabulary can grow on | |
| 28 | the web without the terminal having to agree first. | |
| 29 | ||
| 30 | Punctuation and operators are deliberately **below** body colour | |
| 31 | (`--tok-punctuation`, `--tok-operator`): they are a line's scaffolding, and | |
| 32 | colouring them loudly makes code shout. Diff-inside-a-fence borrows the diff | |
| 33 | tints (`--add-fg` / `--del-fg`) rather than inventing a colour. | |
| 34 | ||
| 35 | **Markdown has two right answers.** A `.md` blob renders as prose by default | |
| 36 | and offers `Source | Rendered` in its path header; `?view=source` is a plain | |
| 37 | link, so both halves work with no JavaScript, are addressable, and survive | |
| 38 | being sent to somebody. The rendered half is the README renderer — fenced code | |
| 39 | is highlighted in the language the fence names, tables are tables, and a | |
| 40 | relative link (`docs/keeping.md`) resolves, while anything carrying a scheme | |
| 41 | other than http(s), or a protocol-relative `//host`, is left as text. |
docs/design/sections/6b-workspace.md added +119
| @@ -0,0 +1,119 @@ | ||
| 1 | ### 6b. The workspace — one screen for a whole repository | |
| 2 | ||
| 3 | Opening a repository in the terminal opens a **workspace**, not a home page: | |
| 4 | the explorer, a tab bar, the file you are reading, and the one commit that | |
| 5 | carries everything you changed. There is no repo card to leave, no directory | |
| 6 | screen to push, no blob screen under it and no editor screen on top. The four | |
| 7 | screens that used to be there were four escapes deep and lost your place at | |
| 8 | each one. | |
| 9 | ||
| 10 | ||
| 11 | forge Ink | |
| 12 | alice › alice/lighthouse | |
| 13 | ● workbench · ○ this machine main ▾ | |
| 14 | README.md src/lamp.ts ● src/weather.ts 3 tabs | |
| 15 | ▾ src/ ┃ 1 # Lighthouse | |
| 16 | lamp.ts ● ┃ 2 | |
| 17 | weather.ts ┃ 3 A beacon. Rotates the lamp, logs the weather, warns the ships. | |
| 18 | package.json ┃ | |
| 19 | ▸ README.md ┃ | |
| 20 | main · 1 modified src/lamp.ts · 22 lines | |
| 21 | tab focus explorer e edit c commit b switch ref t find file i issues | |
| 22 | ||
| 23 | ||
| 24 | The where strip keeps column zero, exactly as it does on every other | |
| 25 | repository screen, and the ref pill (`main ▾`) takes the right-hand end of the | |
| 26 | same row. At **≥100 columns** the explorer is a column beside the file; below | |
| 27 | that it is the pane `tab` toggles onto, never both at once. A repository opens | |
| 28 | on its **README** — the first file at the root if there is none — with the keys | |
| 29 | already in the file pane, so `j` scrolls it without a keystroke of ceremony. | |
| 30 | ||
| 31 | Four rules hold it together, and each one answers something the old | |
| 32 | arrangement got wrong: | |
| 33 | ||
| 34 | - **Moving the explorer's cursor reads nothing.** `j` moves a cursor over | |
| 35 | names; `enter` opens a tab. The preview-that-followed-the-cursor it replaces | |
| 36 | cost a read per keystroke, needed a debounce and a stale-read token to stay | |
| 37 | honest, and left you unable to scroll the file you were looking at because | |
| 38 | the selector lived in the other pane. | |
| 39 | - **A tab owns its buffer.** Scroll position, in-file search, undo history and | |
| 40 | every unsaved edit live in the tab. Switching tabs keeps them; so does going | |
| 41 | to the issue list and coming back, because the workspace stays on the stack | |
| 42 | while something is pushed over it. | |
| 43 | - **Editing is a mode, not a screen.** `e` turns the active tab into the | |
| 44 | buffer from `ui/editor.ts`, in place. `esc` goes back to reading **with the | |
| 45 | edits still there** — losing work takes `u` (discard this tab) or `x` (close | |
| 46 | it), and both ask first. | |
| 47 | - **One commit for the whole change.** Every modified tab and every pending | |
| 48 | deletion goes into a single `editFiles` call. | |
| 49 | ||
| 50 | | key | in the explorer | in the file pane | | |
| 51 | | ------------ | -------------------------------- | ------------------------------- | | |
| 52 | | `j` `k` | move the cursor (reads nothing) | scroll | | |
| 53 | | `ctrl+d` `u` | page | page | | |
| 54 | | `g` `G` | top / bottom | top / bottom | | |
| 55 | | `enter` `l` | expand a directory / open a tab | — | | |
| 56 | | `h` | collapse, or go to the parent | scroll left (`l` scrolls right) | | |
| 57 | | `tab` | focus the file | focus the explorer | | |
| 58 | | `esc` | back | focus the explorer | | |
| 59 | | `/` | filter this level | search in the file (`n` / `N`) | | |
| 60 | | `n` `D` | new file / mark one for deletion | — | | |
| 61 | | `e` | open the file and edit it | edit | | |
| 62 | | `u` | — | discard this tab's changes | | |
| 63 | | `v` | — | the file's other view (below) | | |
| 64 | ||
| 65 | And the keys the whole workspace answers, from either pane: `]` `[` and `1`–`9` | |
| 66 | move between tabs, `x` / `X` close one or the others, `c` commits, `b` lists | |
| 67 | branches and tags, `B` creates a branch, `t` (or `ctrl+p`) is the fuzzy finder, | |
| 68 | `y` copies the path, `i` / `p` / `C` open issues, pulls and commits, `I` shows | |
| 69 | the about card, `W` swaps to the other side of a mirror, `O` opens the file on | |
| 70 | its origin, `P` pins, `S` syncs, `F` forks, `,` is settings, `r` refreshes and | |
| 71 | `E` hands the file to `$FORGE_EDITOR`. | |
| 72 | ||
| 73 | **The tab bar.** One row above the panes: the path, the active tab bold and | |
| 74 | underlined in the accent, `●` on anything modified, `¶` on prose being read | |
| 75 | rather than edited, `‹ ›` when there are more tabs than fit, and the count on | |
| 76 | the right. `¶` (U+00B6) is Latin-1, so it is in every font that can draw a box | |
| 77 | character at all, and it is the one glyph in the safe set that already means | |
| 78 | "formatted prose". A modified file wears the same `●` in the explorer, and one | |
| 79 | marked for deletion is struck through in the danger colour — the same change, | |
| 80 | said in both places. The **active** tab also wears a `✗` you can click; only | |
| 81 | the active one, because a close box on every chip is a row of targets you hit | |
| 82 | by accident, and the tab you mean to close is the one you are looking at. | |
| 83 | ||
| 84 | **Two views, one key.** Some files have two honest ways of being seen, and `v` | |
| 85 | is the toggle for all of them: | |
| 86 | ||
| 87 | | file | opens as | `v` shows | | |
| 88 | | ------------------- | -------------------- | ------------------------ | | |
| 89 | | `*.md`, `README*` | rendered prose (`¶`) | the source, highlighted | | |
| 90 | | `*.png`, `*.jpg`, … | the picture (§6·0c) | format · geometry · size | | |
| 91 | | everything else | code | (nothing else to show) | | |
| 92 | ||
| 93 | Prose opens **rendered**, because that is what a README is for and it is what | |
| 94 | the repo card always did — but the rendered view is a view, not a mode: `j`/`k` | |
| 95 | scroll it, `/` searches it, and `e` always edits the **source**, switching to | |
| 96 | it if you were reading. The web and the terminal render that markdown through | |
| 97 | the same rules, so a README reads the same in both. | |
| 98 | ||
| 99 | **Colour follows the theme.** Switching theme re-tokenises every open tab on | |
| 100 | the next frame; a tab that kept yesterday's palette is exactly the bug a | |
| 101 | screenshot hides. | |
| 102 | ||
| 103 | **Coming back is free.** A workspace's open tabs, its explorer cursor, its ref | |
| 104 | and every uncommitted buffer live on the **session**, keyed by repository — so | |
| 105 | popping to the dashboard and re-entering the same repo restores what you were | |
| 106 | doing, not just where you were. One connection is one identity, so nothing | |
| 107 | another user opened can be reached, and the memory dies with the connection; | |
| 108 | an entry nobody has touched for thirty minutes is dropped on the next lookup. | |
| 109 | `r` is still the refresh, and `x` still closes a tab. | |
| 110 | ||
| 111 | **The about card (`I`).** What used to be the repo home page: visibility, | |
| 112 | description, default branch, counts, where a mirror came from and when it was | |
| 113 | last fetched, and the clone URLs (`y` copies one). It is a card rather than a | |
| 114 | screen because it is something you glance at on the way to doing something | |
| 115 | else. | |
| 116 | ||
| 117 | The finder (`t`) scores with fzf's `--scheme=path` constants plus VS Code's | |
| 118 | rule that any basename match outranks any directory-only match, and it says | |
| 119 | "N files (truncated)" honestly when the listing hit its cap. |
docs/design/sections/6c-1-contributing.md added +65
| @@ -0,0 +1,65 @@ | ||
| 1 | ### 6c·1. Contributing: fork at the origin, propose a change | |
| 2 | ||
| 3 | The workflow the origins layer exists for — _grab their repo, branch, edit, | |
| 4 | propose it back_ — is one intention, so it is two keys and one action call | |
| 5 | (`actions/contribute.ts`), never five screens with five half-finished states | |
| 6 | between them. | |
| 7 | ||
| 8 | **`F` — fork at the origin.** On a live browse (and on the picker's rows) `F` | |
| 9 | forks at the origin rather than here: a local fork of a mirror is a copy of a | |
| 10 | copy with nowhere to propose it back to. One confirm card, saying the whole | |
| 11 | sentence because two machines are involved — | |
| 12 | ||
| 13 | ||
| 14 | ╭─ Fork at the origin ───────────────────────────────╮ | |
| 15 | │ Fork octo/widgets to your account │ | |
| 16 | │ at codeberg.org and mirror it here? │ | |
| 17 | │ │ | |
| 18 | │ The copy here is your workbench. │ | |
| 19 | │ Cancel ▸ Fork │ | |
| 20 | ╰────────────────────────────────────────────────────╯ | |
| 21 | ||
| 22 | ||
| 23 | — then the ordinary mirror card over the job the fork started, then the fork's | |
| 24 | own workspace. A native repository keeps the native fork. Wherever a | |
| 25 | repository forks something at an origin, the where-strip and the about card | |
| 26 | say so: `· fork of octo/widgets`, read from `repo.origin_fork_of` on a mirror | |
| 27 | and from the picker's cached `fork_of` on a live browse. | |
| 28 | ||
| 29 | **`c` — propose a change.** When the source says `permissions.push === false` | |
| 30 | — a live browse of somebody else's repository, or a mirror whose upstream is | |
| 31 | not ours to push to — editing is allowed and the commit dialog becomes a | |
| 32 | proposal dialog. Same buffers, same ticked files, no "commit to `<ref>`" | |
| 33 | option (there is no ref of theirs you may write), and a branch that lands in | |
| 34 | your fork: | |
| 35 | ||
| 36 | ||
| 37 | ╭─ Propose a change ──────────────────────────── octo/widgets ─╮ | |
| 38 | │ Message │ | |
| 39 | │ Update README.md │ | |
| 40 | │ optional — this becomes the pull request's body │ | |
| 41 | │ Files · 1 of 1 │ | |
| 42 | │ [x] ~ README.md │ | |
| 43 | │ Branch in your fork │ | |
| 44 | │ alice/edit-README-md │ | |
| 45 | │ Pull request › octo/widgets · main │ | |
| 46 | │ Update README.md │ | |
| 47 | │ Propose │ | |
| 48 | ╰──────────────────────────────────────────────────────────────╯ | |
| 49 | ||
| 50 | ||
| 51 | `contribute` does the rest in one call: fork if a fork is needed, branch from | |
| 52 | the _upstream's_ base rather than a stale copy of it, commit into the fork, | |
| 53 | push it there, and open the pull upstream with the `owner:branch` head form | |
| 54 | both forges take. The toast reads `opened pull #12 on octo/widgets`, and when | |
| 55 | we hold a mirror of that upstream the imported pull is pushed on the stack so | |
| 56 | the reader lands on what they just proposed. **A refusal keeps every buffer** | |
| 57 | and names which half failed — `fork_timeout`, `origin_refused`, | |
| 58 | `mirror_failed`, an edit reason, or "the commit landed but the pull did not | |
| 59 | open". While such a workspace is open the status row says | |
| 60 | `proposing to octo/widgets via your fork`, on every frame, so nobody has to | |
| 61 | press `c` to find out where their change is going. | |
| 62 | ||
| 63 | A repository the origin says you _may_ push to keeps the ordinary commit | |
| 64 | dialog: on a mirror that is `editFiles` plus push-through, which is | |
| 65 | `contribute`'s own `via: "direct"` path by another name. |
docs/design/sections/6c-editing-commit-dialog.md added +29
| @@ -0,0 +1,29 @@ | ||
| 1 | ### 6c. Editing, and the commit dialog | |
| 2 | ||
| 3 | `e` turns the active tab into a modeless editor: arrows/Home/End/PgUp/PgDn and | |
| 4 | word jumps, shift-arrows to select, `ctrl+c`/`x`/`v` (which also mirror to | |
| 5 | _your_ clipboard over OSC 52), `ctrl+z`/`ctrl+y`, `ctrl+f` find, `ctrl+r` | |
| 6 | replace, horizontal scrolling with no soft wrap, tabs rendered at 4 and kept as | |
| 7 | tabs. The status row reads `path · Ln 12, Col 4 · modified`. | |
| 8 | ||
| 9 | Four rules are non-negotiable because this is attached to a git host: CRLF, a | |
| 10 | BOM and the presence or absence of a trailing newline round-trip exactly; | |
| 11 | nothing is normalised silently. Past 1 MB or 50k lines the buffer opens | |
| 12 | read-only and says which, rather than being slow. | |
| 13 | ||
| 14 | `c` (or `ctrl+s` from inside the buffer) opens the commit dialog. It lists | |
| 15 | **every** change the workspace is holding — each modified tab and each pending | |
| 16 | deletion, ticked, marked `+` added, `~` edited, `-` deleted — then asks the | |
| 17 | three questions `editFiles` takes: message (subject, optional body), target | |
| 18 | (`current branch` or `new branch`, defaulting to **new**, named | |
| 19 | `<you>/edit-<file>`), and `[ ] open a pull request` with the title prefilled | |
| 20 | from the subject. One call: no half-finished state (a branch with no commit, a | |
| 21 | commit with no pull) can be invented. On success the workspace follows the | |
| 22 | commit — the ref pill becomes the new branch and every tab is re-read from it. | |
| 23 | **A refused commit keeps every buffer**, and says why on the dialog: a | |
| 24 | protected branch, a name git will not take, an origin that said no. | |
| 25 | ||
| 26 | Where the change has nowhere to go — a reader without write access, a live | |
| 27 | browse of a repository nobody has offered you a route into — `e`, `c`, `n` and | |
| 28 | `D` say so instead of opening something that could never land. Where it has a | |
| 29 | route, they open the proposal dialog instead; §6c·1 is that route. |
docs/design/sections/6c-editor.md added +100
| @@ -0,0 +1,100 @@ | ||
| 1 | ### 6c. The editor | |
| 2 | ||
| 3 | `GET /:owner/:name/edit/:ref/*path` is a `<textarea>` in a `<form>`, and one | |
| 4 | rule governs it: **a refusal never costs you your typing.** A protected | |
| 5 | branch, a file over the size cap, a branch name git will not take, an origin | |
| 6 | that said no — each re-renders the same page with the text, the message, the | |
| 7 | branch name and the pull-request fields exactly as they were, and the reason | |
| 8 | above them. `test/web-editor.test.ts` asserts that, not just the happy path. | |
| 9 | ||
| 10 | The commit box is one submit, because `editFiles` is one call: message, | |
| 11 | target (`current branch` / `new branch <name>`, defaulting to | |
| 12 | `alice/edit-<file>`), and optionally a pull request from the new branch back | |
| 13 | to where you started. Where committing straight to the ref is not on offer at | |
| 14 | all — a protected default, or a ref that is not a branch — the page says so on | |
| 15 | the disabled radio rather than letting somebody find out after typing. | |
| 16 | ||
| 17 | **The highlighted mirror.** Under the textarea sits a | |
| 18 | `<pre id="editor-mirror">` holding the same text, syntax-coloured; the | |
| 19 | textarea on top of it has transparent text and a visible caret. They share one grid cell and one set | |
| 20 | of metrics — font, size, line height, padding, tab size — because a single | |
| 21 | divergence puts the caret in the wrong place, and the _height ceiling lives on | |
| 22 | `.editor-wrap`_ so the gutter, the mirror and the textarea are always the same | |
| 23 | height and scroll as one. The mirror is rendered by the server for the first | |
| 24 | paint, so there is no flash of uncoloured code, and kept in step by | |
| 25 | `window.forgeHighlight`, which is `web/highlight.ts` itself bundled by | |
| 26 | `Bun.build` at first use and served from `/assets/highlight-<hash>.js`, | |
| 27 | immutable. That asset is the one thing that relaxes the script CSP — from | |
| 28 | "this page's nonce" to "this page's nonce, or a file from this origin" — and | |
| 29 | only the editor page asks for it. | |
| 30 | ||
| 31 | An edit re-scans from the first changed line and stops as soon as the state | |
| 32 | entering an unchanged line matches what it was before, so typing costs one | |
| 33 | line's work; the DOM is patched line by line rather than rebuilt. Tab inserts, | |
| 34 | Enter keeps your indentation, brackets and quotes close themselves (and wrap a | |
| 35 | selection), `⌘/Ctrl+S` submits the commit form, and the current line is | |
| 36 | marked. `⌘/Ctrl+F` is left to the browser on purpose: the mirror holds real | |
| 37 | text, so the page's own find lands on the line you were looking for. | |
| 38 | ||
| 39 | **It degrades, in that order.** Over 200 KB or over 10,000 lines the server | |
| 40 | sends no mirror and no bundle — a file that size is not hand-edited in a | |
| 41 | browser, and a slow editor is worse than an unhighlighted one. If the bundle | |
| 42 | fails to build or never loads, the page keeps the plain textarea, because the | |
| 43 | textarea's own text only turns transparent once the mirror is live. With no | |
| 44 | JavaScript at all it is a `<textarea>` in a `<form>`, which is what it was | |
| 45 | before any of this. The Preview tab is offered on Markdown only, and renders | |
| 46 | through the same `/preview` fragment the server will use for the file. | |
| 47 | ||
| 48 | **Origins are web-only.** Connecting, syncing and browsing an origin live on the web pages (`/origins`) and in migrate; the terminal has no origins screen. On a mirrored repo's home `y` syncs the mirror and `P` pins it — `p` has meant _pulls_ on that | |
| 49 | screen since before pins existed, so the toggle takes the shifted key there | |
| 50 | and the plain `p` everywhere a repo is a _row_ (the dashboard, explore). | |
| 51 | ||
| 52 | The connect chooser is ordered by what actually gets somebody connected: | |
| 53 | **Personal access token — recommended** first (paste a string, no setup at | |
| 54 | all), then **GitHub, one click** (needs a one-time OAuth app setup) and | |
| 55 | **Forgejo / Gitea, one click** (needs an app registration on the instance). | |
| 56 | Each row carries that condition on its own line rather than failing later | |
| 57 | with an error about an environment variable. | |
| 58 | ||
| 59 | **The where strip.** Every repository screen carries one line directly under | |
| 60 | its title, naming the three places a repository can be and marking which one | |
| 61 | the bytes on screen came from: | |
| 62 | ||
| 63 | ||
| 64 | ● codeberg.org · ○ workbench · ○ this machine | |
| 65 | reading live from codeberg.org — read-only · m mirror into your workbench | |
| 66 | ||
| 67 | ● codeberg.org · ● workbench (synced 3m ago) · ◆ this machine | |
| 68 | ||
| 69 | ● workbench · ○ this machine | |
| 70 | ||
| 71 | ||
| 72 | The first is a live browse (and only a live browse gets the second, muted | |
| 73 | banner line); the second is a mirror that is also pinned; the third is a | |
| 74 | native repository, which has no origin and therefore no first place. The dot | |
| 75 | is the grammar — **accent** is the place being read from, **success** is a | |
| 76 | place that has this repository, **muted** is a place that does not: | |
| 77 | ||
| 78 | | glyph | means | | |
| 79 | | ----- | ---------------------------------------------------------- | | |
| 80 | | `●` | this place has the repository (accent = reading from here) | | |
| 81 | | `○` | this place does not have it | | |
| 82 | | `◆` | kept on your machine (pinned) | | |
| 83 | | `▲` | this came from the origin — an imported author or activity | | |
| 84 | ||
| 85 | **Read-only means read-only.** A screen over a live source has no write keys | |
| 86 | at all — no `c` comment, no `x`/`o` state, no `l` labels, no `m` merge, no | |
| 87 | `,` settings, no `F` fork — because `capabilities.write` is false and the | |
| 88 | source has no method that could write. In their place the help bar shows | |
| 89 | `m mirror` and `O open on origin` — first, ahead of the navigation keys, | |
| 90 | because at 80 columns the bar has room for about six bindings and those two | |
| 91 | are the only things you can actually do here. The banner carries the long | |
| 92 | wording; `w` opens the workbench copy when one already exists. | |
| 93 | ||
| 94 | **The mirror card.** `m` opens a checklist over whatever screen you were on: | |
| 95 | `creating → fetching → labels → issues → pulls → comments`, a spinner on the | |
| 96 | stage in progress with the job's own words beside it ("42 issues"), and the | |
| 97 | elapsed time. `esc` hides it and the mirror keeps running, toasting when it | |
| 98 | lands; on `done` the live screen underneath is replaced in place by the same | |
| 99 | screen over the local source, and the strip flips to `● workbench`; on | |
| 100 | `failed` the card shows the scrubbed reason and `r` retries. |
docs/design/sections/6d-forge-editor.md added +33
| @@ -0,0 +1,33 @@ | ||
| 1 | ### 6d. `$FORGE_EDITOR` — the operator's own editor, over a pty | |
| 2 | ||
| 3 | `E` suspends the UI and hands the terminal to `$FORGE_EDITOR` on a real pty. | |
| 4 | **Read this before enabling it:** the editor runs on the forge host as the | |
| 5 | forge user, and nvim's `:!sh`, `:terminal` and a sourced `init.lua` are all | |
| 6 | arbitrary code execution. CVE-2019-12735 was RCE in Neovim from merely opening | |
| 7 | a file with a hostile modeline, which is the exact shape of a host whose job is | |
| 8 | displaying files other people wrote. | |
| 9 | ||
| 10 | It is coherent under one framing only: **this is the operator's own single-user | |
| 11 | workbench, and the editor is their shell reached through the forge.** So it is | |
| 12 | opt-in and absent otherwise — with `FORGE_EDITOR` unset there is no spawn, no | |
| 13 | temp file and one line of explanation; the name is resolved once with | |
| 14 | `Bun.which` and spawned as `[bin, file]` **argv, never a shell** (a name with | |
| 15 | whitespace in it is refused rather than tokenized); and one handoff at a time | |
| 16 | per session, because nested suspends are the wedge behind every "my TUI hung | |
| 17 | after I shelled out" report. Nothing in that path writes to a repository: what | |
| 18 | comes back is spliced into the tab's own buffer — one undoable edit, and a | |
| 19 | modified tab like any other — and reaches git only through `c` and `editFiles`, | |
| 20 | the one way anything does. `E` is the escape hatch rather than the tool, so it | |
| 21 | sits last in the binding list and falls off the end of the help bar. | |
| 22 | ||
| 23 | Resume is unconditional and state-independent — the child may have crashed, so | |
| 24 | "undo what we think it did" is exactly the reasoning that leaves a broken | |
| 25 | terminal. Two fixes beyond re-entering the alt screen, both measured against | |
| 26 | real nvim: `ESC[0 q` because it exits leaving a steady block and never resets | |
| 27 | the cursor shape, and `ESC[>0u` to pop kitty keyboard flags it pushes and does | |
| 28 | not. The input decoder is rebuilt on resume so the Primary DA reply that | |
| 29 | arrives _after_ the child is gone lands nowhere. | |
| 30 | ||
| 31 | **Gap:** a launch should leave an outbox event (invariant 5), and appending one | |
| 32 | from an adapter would break the rule that only `actions/` does. It is a log | |
| 33 | line for now; the action belongs beside `actions/contents.ts`. |
docs/design/sections/6e-1-reviews-merge-gate.md added +47
| @@ -0,0 +1,47 @@ | ||
| 1 | ### 6e·1. Reviews, threads, and the merge gate | |
| 2 | ||
| 3 | A pull is judged in three places, and each says one thing. | |
| 4 | ||
| 5 | **The verdict (`R`).** A card with three radios and an optional note — | |
| 6 | `( ) approve ( ) request changes ( ) comment`, `ctrl+d` submits. Approve is | |
| 7 | **absent** when the viewer wrote the change, because `submitReview` refuses it | |
| 8 | (`self_review`) and a disabled control would only be a slower way to be told | |
| 9 | no. A verdict renders in the conversation as a timeline item with a state chip | |
| 10 | (success / danger / muted), and it is recorded against the head it was passed | |
| 11 | on — so a push dismisses it and the item wears `before the latest push` in | |
| 12 | muted rather than quietly still counting. | |
| 13 | ||
| 14 | **The gate.** The merge box grows a second line saying where the verdicts | |
| 15 | stand: `2 approvals · changes requested by bob`, and `N dismissed by a push` | |
| 16 | when a push has cleared some. When the reviews do not let it land the box | |
| 17 | reads `review` in `attn` and `m` says the reason out loud rather than doing | |
| 18 | nothing: | |
| 19 | ||
| 20 | ||
| 21 | ╭─ Merge ──────────────────────────────────────────────────────────╮ | |
| 22 | │ review Needs an approval of this head before it can merge │ | |
| 23 | │ no approvals yet │ | |
| 24 | ╰────────────────────────────────────── fix › main · 1 file +1 -1 ─╯ | |
| 25 | ||
| 26 | ||
| 27 | That is a rendering of `reviewGate` (`core/pulls.ts`) and nothing more: an | |
| 28 | outstanding request for changes blocks whatever the setting says, and | |
| 29 | `require a review before merging` (repo settings, `R`) additionally demands an | |
| 30 | approval of the current head. The refusal is mechanical in `mergePull`, which | |
| 31 | reads the gate from the live head — a check computed earlier and handed down | |
| 32 | is a check that can be skipped. | |
| 33 | ||
| 34 | **Threads.** Review comments sharing one anchor are one conversation. In the | |
| 35 | files tab the section header reads `3 threads · 1 unresolved`; `x` settles or | |
| 36 | reopens the thread the cursor is standing on (a writer, or whoever raised it); | |
| 37 | `n`/`p` walk the unsettled ones while the cursor is inside one, and go back to | |
| 38 | walking hunks when it is not. A settled thread collapses to a single dim line | |
| 39 | — `✓ resolved by alice · 2h · enter to expand` — because the point of settling | |
| 40 | something is to stop looking at it, and `enter` opens the record back up | |
| 41 | because the point of a record is that it is still there. Standing on the diff | |
| 42 | line a thread hangs from counts as standing on the thread: that is what a | |
| 43 | reader means by "this one". | |
| 44 | ||
| 45 | A pull list row wears the same verdict in one tabular column — `✓` approved, | |
| 46 | `✗` changes requested, `·` nobody has looked — read for the whole page in one | |
| 47 | grouped query, never one per row. |
docs/design/sections/6e-links.md added +23
| @@ -0,0 +1,23 @@ | ||
| 1 | ### 6e. Links that work | |
| 2 | ||
| 3 | The cell buffer has a sixth plane, `link`, holding a 1-based index into the | |
| 4 | frame's URI table — a URL is a property of a _run of cells_ exactly like a | |
| 5 | colour, so it diffs with one integer compare and OSC 8 falls out of the same | |
| 6 | emit loop that already does SGR deltas. Every open carries `id=`, because a | |
| 7 | diff renderer paints dirty runs and one logical link routinely reaches the | |
| 8 | terminal as several disjoint spans. Links are closed **before every cursor | |
| 9 | jump and at the end of every row**: OSC 8 and SGR are independent, so the | |
| 10 | frame-final SGR reset does not close one. | |
| 11 | ||
| 12 | URLs are marked in the connect screens, the repo home's clone lines, the | |
| 13 | "page" fact and rendered markdown. And because **no control sequence exists | |
| 14 | that means "open this in the reader's browser"** — OSC 8 marks text clickable | |
| 15 | and the person clicks — `O`/`o` does three things at once when it cannot open | |
| 16 | one: copies the URL through OSC 52, and pushes the **link dialog**, which | |
| 17 | shows the address plain with **mouse reporting turned off** for as long as it | |
| 18 | is open, so the terminal's own drag-to-select works without Shift; `c` copies | |
| 19 | again, `enter` tries the browser, `esc` puts the mouse back. It really opens | |
| 20 | on the local stdio session, and over SSH from this machine's own address | |
| 21 | (`sshTerminal.local`), because then the browser is on the same screen. Four | |
| 22 | routes to one URL (the hyperlink, the clipboard, the selectable text, the | |
| 23 | opener), because none of them is reliable on its own. |
docs/design/sections/6f-realtime.md added +6
| @@ -0,0 +1,6 @@ | ||
| 1 | ### 6f. Realtime | |
| 2 | ||
| 3 | Dashboard, issue and pull lists, the repo home, and the issue and pull screens | |
| 4 | all subscribe to the outbox for as long as they are on the stack, through one | |
| 5 | helper (`live()` in `screens/common.ts`). Popping the screen unsubscribes it — | |
| 6 | there is no lifecycle to get wrong. A burst is coalesced into one refresh. |
docs/design/sections/6g-terminal-apps-runs-crew.md added +29
| @@ -0,0 +1,29 @@ | ||
| 1 | ### 6g. Apps, runs and the crew, where the terminal still shows them | |
| 2 | ||
| 3 | The terminal's half of §5c is deliberately small: running an app and | |
| 4 | managing the crew are the studio's (`docs/STUDIO.md`), and the terminal has | |
| 5 | no apps, app, runs, run or crew screen and no palette entry for one. What | |
| 6 | remains is where the work is reviewed: | |
| 7 | ||
| 8 | - **Pull** — a preview line when the repository is an app (`O` opens it, | |
| 9 | `P` opens production beside it: comparing the two is the review), a | |
| 10 | checks row in the merge box and a _waiting on checks_ state with the refusal | |
| 11 | in words on `m`, `a` to assign (nobody, people, then the crew with the bot | |
| 12 | glyph on a Nerd Font), and a Crew tab of the agent runs about it. | |
| 13 | - **`T` on a pull's preview** suspends the UI and runs the app's `tty` on | |
| 14 | the same pty — one connection, two programs in turn, exactly as | |
| 15 | `$FORGE_EDITOR` runs — and the UI returns when it exits. Every refusal | |
| 16 | (not running, no `tty`, private to a guest) is a toast in the same words | |
| 17 | the ssh front door uses. | |
| 18 | - **Issue** — `a` to assign; a Crew card when an agent has runs, `tab` moves | |
| 19 | focus to it. | |
| 20 | - **A run** is a row (`screens/runlist.ts`): state dot and word, who, why, | |
| 21 | the summary. `enter` on one hands over its web page, | |
| 22 | `/:owner/:name/runs/:id`, where the live log, cancel and steer are — as a | |
| 23 | link when the forge knows its public URL, as the path otherwise. | |
| 24 | - **Settings** — the App tab (enable with slug, access and preview data; edit; | |
| 25 | `D` to stop running as an app behind a confirm), `C` for require checks on | |
| 26 | General, the Crew tab (`a` adds an agent from the forge's, `d` removes). | |
| 27 | ||
| 28 | A guest is told so in words; nothing here is a way around the actions' | |
| 29 | answers. |
docs/design/sections/7-security-boundaries.md added +22
| @@ -0,0 +1,22 @@ | ||
| 1 | ## 7. Two rules that are security boundaries | |
| 2 | ||
| 3 | **Label colors.** Inline `style=""` is blocked by the CSP — nonces apply to | |
| 4 | elements, not attributes. A page therefore collects the label colors it will | |
| 5 | render and emits one nonce'd rule per color: | |
| 6 | ||
| 7 | css | |
| 8 | .lc-d73a4a { | |
| 9 | : #d73a4a; | |
| 10 | } | |
| 11 | ||
| 12 | ||
| 13 | and the static sheet derives the chip from it with `color-mix`, so one stored | |
| 14 | hex reads correctly in all six themes. `labelCss()` re-validates | |
| 15 | `/^[0-9a-f]{6}$/` immediately before embedding. That check is the boundary — | |
| 16 | treat it like `assertBatchSafe`, not like a nicety. | |
| 17 | ||
| 18 | **The confirm page.** Every destructive button is a link to `/-/confirm?to=…`. | |
| 19 | That page derives its own title, detail and typed-phrase requirement from a | |
| 20 | table of known destructive routes, and 404s on anything else. The wording never | |
| 21 | comes from the link, so a mailed URL cannot put "Continue" on a button that | |
| 22 | deletes a repository. |
docs/design/sections/8-checklist.md added +21
| @@ -0,0 +1,21 @@ | ||
| 1 | ## 8. Checklist before you call a screen done | |
| 2 | ||
| 3 | 1. Every divider is exactly 1px. The only 2px things are the active-tab | |
| 4 | underline and the focus ring. | |
| 5 | 2. Every number that lines up is tabular. | |
| 6 | 3. Icons sit in a fixed 16px slot; the text baseline does not move when one | |
| 7 | appears. | |
| 8 | 4. Secondary actions are in the DOM at `opacity: 0` and revealed on hover — | |
| 9 | never `display: none` → `flex`. A settings row is the exception: its | |
| 10 | control is the point of the row, so it sits in `.row-fields`, visible at | |
| 11 | rest, and the list wears `.setting-list` (see §5d). | |
| 12 | 5. Exactly one accent-colored thing, and it is the action. | |
| 13 | 6. The empty state has exactly one button. | |
| 14 | 7. Nothing on the page needs JavaScript to work. | |
| 15 | 8. It survives 200% zoom and a 320px viewport with no horizontal body scroll — | |
| 16 | diffs and code scroll inside their own card. | |
| 17 | 9. Nothing inside a linked row is itself a link. | |
| 18 | 10. Any control that only works with a script carries `js-only`, so a page | |
| 19 | without JavaScript never shows a dead button. | |
| 20 | 11. Every token count sits beside a byte size, a cost or a percentage, and | |
| 21 | goes through `tokenCount()` — never a hand-written `k`. |
plugins/claude-code/README.md +1 −1
| @@ -1,7 +1,7 @@ | ||
| 1 | 1 | # forge for Claude Code |
| 2 | 2 | |
| 3 | 3 | Set `FORGE_URL` (the forge's address, no trailing slash) and `FORGE_TOKEN` |
| 4 | (an `rw` token; `ro` reads only), then add this directory as a plugin | |
| 4 | (an `rw` token; `ro` reads only; make one at `/settings/tokens` on the forge, which also shows this line filled in), then add this directory as a plugin | |
| 5 | 5 | (`claude --plugin-dir plugins/claude-code`). It registers the forge's MCP |
| 6 | 6 | server and a `/forge` command: `tell`, `status`, `decide`, `plan`. |
| 7 | 7 |
plugins/opencode/README.md +6 −2
| @@ -1,8 +1,12 @@ | ||
| 1 | 1 | # forge for OpenCode |
| 2 | 2 | |
| 3 | 3 | Copy `forge.ts` into `.opencode/plugin/` (or list this package under `plugin` |
| 4 | in `opencode.json`), and set `FORGE_URL` and `FORGE_TOKEN`. It registers the | |
| 5 | forge's MCP server and the `forge` command: `tell`, `status`, `decide`. | |
| 4 | in `opencode.json`), and set `FORGE_URL` and `FORGE_TOKEN` (make the token at `/settings/tokens` on the forge, which shows the line with its own address filled in): | |
| 5 | `mkdir -p .opencode/plugin && cp plugins/opencode/forge.ts .opencode/plugin/ && FORGE_URL=<url> FORGE_TOKEN=<token> opencode`. It registers the | |
| 6 | forge's MCP server and the `forge` command: `tell`, `status`, `decide`, `plan`. | |
| 7 | `/forge plan` shows the planner's next wave (the first wave-proposal row of `asks`); | |
| 8 | `/forge plan approve`, `redirect <words>` or `later` steers it through `asks_proposal`, | |
| 9 | applied only after you say yes. Only the owner may act on a proposal. | |
| 6 | 10 | Code Mode can also read `GET /contract/openapi.json`. |
| 7 | 11 | |
| 8 | 12 | `test/plugins.test.ts` fails when this plugin names an MCP tool the forge does not list, so a rename in `src/http/mcp.ts` cannot leave it behind. |
plugins/opencode/forge.ts +3 −2
| @@ -1,6 +1,6 @@ | ||
| 1 | 1 | /** |
| 2 | 2 | * forge for OpenCode: registers the forge's MCP server and a `forge` |
| 3 | * command (tell, status, decide). Set FORGE_URL and FORGE_TOKEN. | |
| 3 | * command (tell, status, decide, plan). Set FORGE_URL and FORGE_TOKEN. | |
| 4 | 4 | * No logic lives here: the tools are the forge's own (`docs/MCP.md`). |
| 5 | 5 | */ |
| 6 | 6 | import type { Plugin } from "@opencode-ai/plugin"; |
| @@ -9,6 +9,7 @@ const COMMAND = `Use the forge MCP tools for: $ARGUMENTS | ||
| 9 | 9 | - tell <app> <words>: call \`tell\` with repo and text; pass context { page, run, commit, said }. |
| 10 | 10 | - status: call \`now\` and \`asks\`; say in three sentences what runs and what waits on the person. |
| 11 | 11 | - decide approve|redirect|decline: call \`asks\`; approve -> \`asks_act\` ship, decline -> \`asks_act\` close, redirect -> \`say\`. Plan first, apply (dryRun false) only after the person says yes. |
| 12 | - plan [approve|redirect <words>|later]: call \`asks\`; show the first wave-proposal row (the planner's next wave) in a few lines. approve|redirect|later -> \`asks_proposal\` with that row's id and verb (redirect carries the words as \`words\`). Say what it will do and apply only after the person says yes. | |
| 12 | 13 | Never merge: a person lands changes.`; |
| 13 | 14 | |
| 14 | 15 | export const Forge: Plugin = async () => ({ |
| @@ -26,7 +27,7 @@ export const Forge: Plugin = async () => ({ | ||
| 26 | 27 | }; |
| 27 | 28 | config["command"] = { |
| 28 | 29 | ...config["command"], |
| 29 | forge: { description: "Tell, status or decide on your forge", template: COMMAND }, | |
| 30 | forge: { description: "Tell, status, decide or plan on your forge", template: COMMAND }, | |
| 30 | 31 | }; |
| 31 | 32 | }, |
| 32 | 33 | }); |
scripts/design-lint.ts +19 −4
| @@ -33,7 +33,10 @@ | ||
| 33 | 33 | * A red names the file:line, the literal and what to use instead, so one pass |
| 34 | 34 | * fixes it; run `bun scripts/design-lint.ts` before pushing. A new class is named |
| 35 | 35 | * in its own `docs/design/areas/<area>.md` rather than in DESIGN.md, which |
| 36 | * every pull would otherwise edit (#4063). | |
| 36 | * every pull would otherwise edit (#4063). DESIGN.md itself is a spine that | |
| 37 | * links one file per section under `docs/design/sections/` (#5937); `designText` | |
| 38 | * reads the spine and those files in its order, so the § numbers mean what | |
| 39 | * they did when it was one file. | |
| 37 | 40 | * |
| 38 | 41 | * Known gaps, so nobody mistakes the gate for more than it is: colours built |
| 39 | 42 | * in JS strings other than the forms above, `oklch()`, |
| @@ -42,7 +45,7 @@ | ||
| 42 | 45 | * |
| 43 | 46 | * The theme palettes (`src/design/themes.ts`) are where colours live and are |
| 44 | 47 | * not scanned. Plain data in, plain data out: `scan` takes files, `compare` |
| 45 | * takes the baseline, a scan and the text of DESIGN.md. | |
| 48 | * takes the baseline, a scan and the text of DESIGN.md with its sections. | |
| 46 | 49 | */ |
| 47 | 50 | |
| 48 | 51 | import { readdirSync, readFileSync, writeFileSync } from "node:fs"; |
| @@ -230,6 +233,17 @@ export function documentedClasses(design: string, areas: readonly string[] = []) | ||
| 230 | 233 | return [...new Set([...namedIn(section(design, "5.")), ...areas.flatMap(namedIn)])].sort(); |
| 231 | 234 | } |
| 232 | 235 | |
| 236 | /** The section files the spine links, in its order: `](design/sections/<file>.md)`. */ | |
| 237 | export function sectionLinks(spine: string): string[] { | |
| 238 | return [...spine.matchAll(/\]\(design\/sections\/([a-z0-9-]+\.md)\)/g)].map((m) => m[1]!); | |
| 239 | } | |
| 240 | ||
| 241 | /** DESIGN.md as one text: the spine, then each section it links, in order (#5937). */ | |
| 242 | export function designText(root: string): string { | |
| 243 | const spine = readFileSync(join(root, DESIGN), "utf8"); | |
| 244 | return [spine, ...sectionLinks(spine).map((f) => readFileSync(join(root, SECTIONS, f), "utf8"))].join("\n"); | |
| 245 | } | |
| 246 | ||
| 233 | 247 | /** The area files under docs/design/areas/: each is wholly vocabulary, one file per component area (#4063). */ |
| 234 | 248 | export function areaFiles(root: string): string[] { |
| 235 | 249 | try { |
| @@ -289,13 +303,14 @@ export function compare(base: Baseline, now: Scan, design: string, areas: readon | ||
| 289 | 303 | } |
| 290 | 304 | const defined = new Set(now.classes); |
| 291 | 305 | for (const k of registeredClasses(design)) { |
| 292 | if (!defined.has(k)) out.push(`.${k}: no stylesheet defines it any more — strike it from docs/DESIGN.md §5d`); | |
| 306 | if (!defined.has(k)) out.push(`.${k}: no stylesheet defines it any more — strike it from §5d, docs/design/sections/5d-page-local-classes.md`); | |
| 293 | 307 | } |
| 294 | 308 | return out; |
| 295 | 309 | } |
| 296 | 310 | |
| 297 | 311 | const BASELINE = "docs/design/baseline.json"; |
| 298 | 312 | const DESIGN = "docs/DESIGN.md"; |
| 313 | const SECTIONS = "docs/design/sections"; | |
| 299 | 314 | const AREAS = "docs/design/areas"; |
| 300 | 315 | |
| 301 | 316 | if (import.meta.main) { |
| @@ -307,7 +322,7 @@ if (import.meta.main) { | ||
| 307 | 322 | console.log(`wrote ${BASELINE}`); |
| 308 | 323 | } else { |
| 309 | 324 | const base: Baseline = JSON.parse(readFileSync(join(root, BASELINE), "utf8")); |
| 310 | const problems = compare(base, now, readFileSync(join(root, DESIGN), "utf8"), areaFiles(root)); | |
| 325 | const problems = compare(base, now, designText(root), areaFiles(root)); | |
| 311 | 326 | for (const p of problems) console.error(p); |
| 312 | 327 | if (problems.length) process.exit(1); |
| 313 | 328 | console.log("design: no colour, size or component added outside the system"); |
scripts/home-eval.ts added +68
| @@ -0,0 +1,68 @@ | ||
| 1 | /** | |
| 2 | * `bun scripts/home-eval.ts <base-url>` scores the owner's home against | |
| 3 | * ground truth (#5805), the deterministic half of #5735's loop: it reads `/` | |
| 4 | * as text (`pageText`, #5765), asks the forge's own API for the five facts | |
| 5 | * that mattered, and prints each as `stated`, `missing` or `wrong` with the | |
| 6 | * page's words beside it, then coverage, errors, characters and fetch time. | |
| 7 | * `FORGE_COOKIE` is sent as the cookie and `FORGE_TOKEN` as a bearer token; | |
| 8 | * neither is printed. Exits 1 when the page or the API will not answer. | |
| 9 | */ | |
| 10 | import { pageText } from "../src/web/page_text.ts"; | |
| 11 | import { coverage, errors, scoreHome, type Truth } from "../src/system/home_eval.ts"; | |
| 12 | ||
| 13 | const base = process.argv[2]?.replace(/\/+$/, ""); | |
| 14 | if (!base || !/^https?:\/\//i.test(base)) { | |
| 15 | console.error("usage: bun scripts/home-eval.ts <http(s)://forge>"); | |
| 16 | process.exit(2); | |
| 17 | } | |
| 18 | const cookie = process.env.FORGE_COOKIE; | |
| 19 | const token = process.env.FORGE_TOKEN; | |
| 20 | const headers: Record<string, string> = { ...(cookie ? { cookie } : {}), ...(token ? { authorization: `Bearer ${token}` } : {}) }; | |
| 21 | const DAY = 86_400_000; | |
| 22 | ||
| 23 | async function get(path: string): Promise<any> { | |
| 24 | const res = await fetch(`${base}${path}`, { headers, redirect: "manual", signal: AbortSignal.timeout(15_000) }); | |
| 25 | if (res.status !== 200) throw new Error(`${path} answered ${res.status}`); | |
| 26 | return res.json(); | |
| 27 | } | |
| 28 | ||
| 29 | async function truth(): Promise<Truth> { | |
| 30 | const home = await get("/api/v1/telemetry/home"); | |
| 31 | const repos: { ownerName: string; name: string; archivedAt?: string | null }[] = []; | |
| 32 | for (let cursor: string | null = null, page = 0; page < 10; page++) { | |
| 33 | const r: { items: typeof repos; next_cursor: string | number | null } = await get(`/api/v1/repos?limit=100${cursor ? `&cursor=${encodeURIComponent(cursor)}` : ""}`); | |
| 34 | repos.push(...r.items); | |
| 35 | if (r.next_cursor === null) break; | |
| 36 | cursor = String(r.next_cursor); | |
| 37 | } | |
| 38 | const live = repos.filter((r) => !r.archivedAt).map((r) => `${r.ownerName}/${r.name}`); | |
| 39 | const quiet: string[] = []; | |
| 40 | for (let i = 0; i < live.length; i += 8) { | |
| 41 | await Promise.all( | |
| 42 | live.slice(i, i + 8).map(async (full) => { | |
| 43 | const log: { date: string }[] = await get(`/api/v1/repos/${full}/commits?limit=1`); | |
| 44 | if (log[0] !== undefined && Date.now() - Date.parse(log[0].date) > 3 * DAY) quiet.push(full); | |
| 45 | }), | |
| 46 | ); | |
| 47 | } | |
| 48 | return { ...home, repos: live, quiet: quiet.sort() }; | |
| 49 | } | |
| 50 | ||
| 51 | try { | |
| 52 | const started = performance.now(); | |
| 53 | const res = await fetch(`${base}/`, { headers, redirect: "manual", signal: AbortSignal.timeout(15_000) }); | |
| 54 | const html = await res.text(); | |
| 55 | const ms = Math.round(performance.now() - started); | |
| 56 | if (res.status !== 200) throw new Error(`/ answered ${res.status}`); | |
| 57 | const text = pageText(html); | |
| 58 | const facts = scoreHome(text, await truth()); | |
| 59 | for (const f of facts) { | |
| 60 | console.log(`${f.verdict.padEnd(7)} ${f.label}`); | |
| 61 | console.log(` page: ${f.words === "" ? "—" : `“${f.words}”`}`); | |
| 62 | console.log(` forge: ${f.truth}`); | |
| 63 | } | |
| 64 | console.log(`coverage ${coverage(facts)} of 5 · errors ${errors(facts)} · chars ${text.length} · fetched in ${ms} ms`); | |
| 65 | } catch (e) { | |
| 66 | console.error(e instanceof Error ? e.message : String(e)); | |
| 67 | process.exit(1); | |
| 68 | } |
scripts/home-read.ts added +26
| @@ -0,0 +1,26 @@ | ||
| 1 | /** | |
| 2 | * `bun scripts/home-read.ts <url>` prints a page as the eye reads it, then | |
| 3 | * `chars N · words N · fetched in N ms` (#5765): step 1 of the home cold read | |
| 4 | * (#5735), so every read starts from the same text. `FORGE_COOKIE`, when set, | |
| 5 | * is sent as the cookie and never printed. Exits 1 on a non-200 status. | |
| 6 | */ | |
| 7 | import { pageText } from "../src/web/page_text.ts"; | |
| 8 | ||
| 9 | const url = process.argv[2]; | |
| 10 | if (!url || !/^https?:\/\//i.test(url)) { | |
| 11 | console.error("usage: bun scripts/home-read.ts <http(s)://url>"); | |
| 12 | process.exit(2); | |
| 13 | } | |
| 14 | const cookie = process.env.FORGE_COOKIE; | |
| 15 | const started = performance.now(); | |
| 16 | const res = await fetch(url, { headers: cookie ? { cookie } : {}, redirect: "manual", signal: AbortSignal.timeout(15_000) }); | |
| 17 | const html = await res.text(); | |
| 18 | const ms = Math.round(performance.now() - started); | |
| 19 | if (res.status !== 200) { | |
| 20 | console.error(`${url} answered ${res.status}`); | |
| 21 | process.exit(1); | |
| 22 | } | |
| 23 | const text = pageText(html); | |
| 24 | const words = text.split(/\s+/).filter(Boolean).length; | |
| 25 | console.log(text); | |
| 26 | console.log(`chars ${text.length} · words ${words} · fetched in ${ms} ms`); |
scripts/hunt.ts added +16
| @@ -0,0 +1,16 @@ | ||
| 1 | /** | |
| 2 | * `bun scripts/hunt.ts <https-origin>`: run the hunters' detectors (GET only) | |
| 3 | * against one app and print the findings as JSON. Exit 1 when there are any. | |
| 4 | * Never run on a person's machine in a loop: it is one pass, then it ends. | |
| 5 | */ | |
| 6 | ||
| 7 | import { huntTarget } from "../src/hunt/hunt.ts"; | |
| 8 | ||
| 9 | const target = process.argv[2]; | |
| 10 | if (!target || !/^https?:\/\//.test(target)) { | |
| 11 | console.error("usage: bun scripts/hunt.ts <origin>"); | |
| 12 | process.exit(2); | |
| 13 | } | |
| 14 | const report = await huntTarget(target.replace(/\/$/, "")); | |
| 15 | console.log(JSON.stringify(report, null, 2)); | |
| 16 | process.exit(report.findings.length === 0 ? 0 : 1); |
scripts/mcp-tools.ts added +81
| @@ -0,0 +1,81 @@ | ||
| 1 | /** | |
| 2 | * Writes the MCP tools' generated files from `src/http/mcp/tools/*.ts` (#5924): | |
| 3 | * | |
| 4 | * - `src/http/mcp/tools/index.ts`: one sorted line per tool file, so a pull | |
| 5 | * that adds a tool adds one line and never edits another pull's. | |
| 6 | * - the `## Tools` table in `docs/MCP.md`, between its `tools:begin` and | |
| 7 | * `tools:end` markers, from each tool's `doc` and `writes`. | |
| 8 | * | |
| 9 | * bun scripts/mcp-tools.ts write both | |
| 10 | * bun scripts/mcp-tools.ts --check exit 1, naming the file, when either is stale | |
| 11 | * | |
| 12 | * `test/mcp-tools.test.ts` runs the check, so a pull that adds a tool file | |
| 13 | * without running this goes red with the command to run. | |
| 14 | */ | |
| 15 | import { readdirSync, readFileSync, writeFileSync } from "node:fs"; | |
| 16 | import { join } from "node:path"; | |
| 17 | ||
| 18 | const ROOT = join(import.meta.dir, ".."); | |
| 19 | const DIR = join(ROOT, "src/http/mcp/tools"); | |
| 20 | const INDEX = join(DIR, "index.ts"); | |
| 21 | const DOC = join(ROOT, "docs/MCP.md"); | |
| 22 | const BEGIN = "<!-- tools:begin: generated by `bun scripts/mcp-tools.ts` from each tool's `doc` -->"; | |
| 23 | const END = "<!-- tools:end -->"; | |
| 24 | ||
| 25 | /** The tool files, by name: every `<name>.ts` here but the index. */ | |
| 26 | export function toolFiles(dir = DIR): string[] { | |
| 27 | return readdirSync(dir) | |
| 28 | .filter((f) => /^[a-z][a-z0-9_]*\.ts$/.test(f) && f !== "index.ts") | |
| 29 | .map((f) => f.slice(0, -3)) | |
| 30 | .sort(); | |
| 31 | } | |
| 32 | ||
| 33 | export function indexText(names: readonly string[]): string { | |
| 34 | return [ | |
| 35 | "// Generated by `bun scripts/mcp-tools.ts` from the files beside it; do not edit.", | |
| 36 | "// One line per tool, sorted: a new tool is a new file and one new line here.", | |
| 37 | ...names.map((n) => `export { tool as ${n} } from "./${n}.ts";`), | |
| 38 | "", | |
| 39 | ].join("\n"); | |
| 40 | } | |
| 41 | ||
| 42 | type Documented = { readonly name: string; readonly doc?: string; readonly writes: boolean }; | |
| 43 | ||
| 44 | export function tableText(tools: readonly Documented[]): string { | |
| 45 | const rows = [...tools] | |
| 46 | .filter((t) => t.doc !== undefined) | |
| 47 | .sort((a, b) => a.name.localeCompare(b.name)) | |
| 48 | .map((t) => `| \`${t.name}\` | ${t.doc} | ${t.writes ? "yes" : ""} |`); | |
| 49 | return [BEGIN, "", "| tool | does | writes |", "| ---- | ---- | ------ |", ...rows, "", END].join("\n"); | |
| 50 | } | |
| 51 | ||
| 52 | /** docs/MCP.md with its table replaced by `table`. */ | |
| 53 | export function withTable(md: string, table: string): string { | |
| 54 | const from = md.indexOf(BEGIN); | |
| 55 | const to = md.indexOf(END); | |
| 56 | if (from < 0 || to < from) throw new Error(`docs/MCP.md has no ${BEGIN} … ${END} markers`); | |
| 57 | return md.slice(0, from) + table + md.slice(to + END.length); | |
| 58 | } | |
| 59 | ||
| 60 | if (import.meta.main) { | |
| 61 | const check = process.argv.includes("--check"); | |
| 62 | const stale: string[] = []; | |
| 63 | const index = indexText(toolFiles()); | |
| 64 | if (readFileSync(INDEX, "utf8") !== index) { | |
| 65 | stale.push("src/http/mcp/tools/index.ts"); | |
| 66 | if (!check) writeFileSync(INDEX, index); | |
| 67 | } | |
| 68 | // After the index is current, so a new file's row is in the table. | |
| 69 | const { TOOLS } = await import("../src/http/mcp/tools.ts"); | |
| 70 | const md = readFileSync(DOC, "utf8"); | |
| 71 | const doc = withTable(md, tableText(TOOLS)); | |
| 72 | if (md !== doc) { | |
| 73 | stale.push("docs/MCP.md"); | |
| 74 | if (!check) writeFileSync(DOC, doc); | |
| 75 | } | |
| 76 | if (check && stale.length > 0) { | |
| 77 | console.error(`stale: ${stale.join(", ")}; run \`bun scripts/mcp-tools.ts\``); | |
| 78 | process.exit(1); | |
| 79 | } | |
| 80 | if (!check) console.log(stale.length > 0 ? `wrote ${stale.join(", ")}` : "current"); | |
| 81 | } |
scripts/openapi-routes.ts added +45
| @@ -0,0 +1,45 @@ | ||
| 1 | /** | |
| 2 | * Writes `src/contract/openapi/routes/index.ts` from the route files beside | |
| 3 | * it (#5936): one sorted line per file, so a pull that describes a route adds | |
| 4 | * one file and one line, and never edits another pull's. | |
| 5 | * | |
| 6 | * bun scripts/openapi-routes.ts write it | |
| 7 | * bun scripts/openapi-routes.ts --check exit 1 when it is stale | |
| 8 | * | |
| 9 | * `test/openapi-routes.test.ts` runs the same comparison, so a pull that adds | |
| 10 | * a route file without running this goes red with the command to run. | |
| 11 | */ | |
| 12 | import { readdirSync, readFileSync, writeFileSync } from "node:fs"; | |
| 13 | import { join } from "node:path"; | |
| 14 | ||
| 15 | const DIR = join(import.meta.dir, "..", "src/contract/openapi/routes"); | |
| 16 | const INDEX = join(DIR, "index.ts"); | |
| 17 | ||
| 18 | /** The route files, by name: every `<operationId>.ts` here but the index. */ | |
| 19 | export function routeFiles(dir = DIR): string[] { | |
| 20 | return readdirSync(dir) | |
| 21 | .filter((f) => /^[a-z][A-Za-z0-9]*\.ts$/.test(f) && f !== "index.ts") | |
| 22 | .map((f) => f.slice(0, -3)) | |
| 23 | .sort(); | |
| 24 | } | |
| 25 | ||
| 26 | export function indexText(names: readonly string[]): string { | |
| 27 | return [ | |
| 28 | "// Generated by `bun scripts/openapi-routes.ts` from the files beside it; do not edit.", | |
| 29 | "// One line per route, sorted: a new route is a new file and one new line here.", | |
| 30 | ...names.map((n) => `export { route as ${n} } from "./${n}.ts";`), | |
| 31 | "", | |
| 32 | ].join("\n"); | |
| 33 | } | |
| 34 | ||
| 35 | if (import.meta.main) { | |
| 36 | const check = process.argv.includes("--check"); | |
| 37 | const index = indexText(routeFiles()); | |
| 38 | const current = readFileSync(INDEX, "utf8") === index; | |
| 39 | if (check && !current) { | |
| 40 | console.error("stale: src/contract/openapi/routes/index.ts; run `bun scripts/openapi-routes.ts`"); | |
| 41 | process.exit(1); | |
| 42 | } | |
| 43 | if (!check && !current) writeFileSync(INDEX, index); | |
| 44 | if (!check) console.log(current ? "current" : "wrote src/contract/openapi/routes/index.ts"); | |
| 45 | } |
scripts/shards.ts +3 −2
| @@ -445,7 +445,8 @@ export function sliceFiles( | ||
| 445 | 445 | |
| 446 | 446 | /** |
| 447 | 447 | * Parses `--shard N/M` (or the same shape from env). Empty / undefined means |
| 448 | * no matrix slice — run every named file. | |
| 448 | * no matrix slice — run every named file. Four digits a side: the gate | |
| 449 | * passed 999 files, and a slice per file must still be nameable. | |
| 449 | 450 | */ |
| 450 | 451 | export function parseShardSpec( |
| 451 | 452 | spec: string | undefined, |
| @@ -454,7 +455,7 @@ export function parseShardSpec( | ||
| 454 | 455 | | { ok: true; none: true } |
| 455 | 456 | | { ok: false; error: string } { |
| 456 | 457 | if (spec === undefined || spec.trim() === "") return { ok: true, none: true }; |
| 457 | const m = /^([1-9][0-9]{0,2})\/([1-9][0-9]{0,2})$/.exec(spec.trim()); | |
| 458 | const m = /^([1-9][0-9]{0,3})\/([1-9][0-9]{0,3})$/.exec(spec.trim()); | |
| 458 | 459 | if (!m) |
| 459 | 460 | return { |
| 460 | 461 | ok: false, |
src/actions/admin_limits_words.ts added +10
| @@ -0,0 +1,10 @@ | ||
| 1 | /** | |
| 2 | * The quota and usage sentences an admin reads (#5621): said once here and | |
| 3 | * read by the web pages and the terminal screens alike, so they cannot drift. | |
| 4 | */ | |
| 5 | ||
| 6 | /** A quota change was refused because a value was not a positive whole number. */ | |
| 7 | export const QUOTA_INVALID = "A quota is a positive whole number, or empty for no limit."; | |
| 8 | ||
| 9 | /** Someone who is not a forge admin asked for the usage report. */ | |
| 10 | export const USAGE_ADMIN_ONLY = "Usage is read by a forge admin."; |
src/actions/admin_words.ts added +14
| @@ -0,0 +1,14 @@ | ||
| 1 | /** | |
| 2 | * What a forge admin's doors say when they refuse (#5561): one place, so | |
| 3 | * the API, MCP and the OpenAPI contract read the same sentence and cannot | |
| 4 | * drift when one door is edited. | |
| 5 | */ | |
| 6 | ||
| 7 | export const ADMIN_WORDS = { | |
| 8 | /** account_suspend / remove: the owner acting on themselves, an admin, or an agent. */ | |
| 9 | selfSuspend: "an admin cannot suspend or remove themselves, another admin, or an agent", | |
| 10 | /** The crew scorecard, asked for by anyone but a forge admin. */ | |
| 11 | scorecard: "the crew's scorecard is a forge admin's to read", | |
| 12 | /** Setting the front page's picks, asked for by anyone but a site admin. */ | |
| 13 | frontPage: "the front page is a site admin's to set", | |
| 14 | } as const; |
src/actions/app_notes.ts +11 −3
| @@ -9,12 +9,15 @@ import type { App } from "../app.ts"; | ||
| 9 | 9 | import { banVisitor, bannedNotes, unbanVisitor, markSender, getNote, hideNote, insertNote, isBanned, notesOf, notesOfApp, type AppNote } from "../core/app_notes.ts"; |
| 10 | 10 | import type { AppRecord } from "../core/apps.ts"; |
| 11 | 11 | import { createLabel, getIssue, getLabel } from "../core/issues.ts"; |
| 12 | import { mergedPullClosing } from "../core/pulls.ts"; | |
| 13 | import { releaseName, releaseOfPull } from "../release/record.ts"; | |
| 12 | 14 | import { RateLimiter } from "../core/ratelimit.ts"; |
| 13 | 15 | import { canAdmin, type Repo } from "../core/repos.ts"; |
| 14 | 16 | import { plainText } from "../core/reports.ts"; |
| 15 | 17 | import { workingAgentRuns } from "../core/runs.ts"; |
| 16 | 18 | import { getUserById, isActive, type User } from "../core/users.ts"; |
| 17 | 19 | import { unadoptedAmong } from "../crew/direct.ts"; |
| 20 | import { NOTE_EMPTY } from "../apps/note_words.ts"; | |
| 18 | 21 | import { err, ok, type Result } from "../kernel/result.ts"; |
| 19 | 22 | import { openIssueThrough, setIssueLabelsThrough, setIssueStateThrough } from "./issues.ts"; |
| 20 | 23 | |
| @@ -101,8 +104,13 @@ export function statusOf(app: App, repo: Repo, number: number): { status: NoteSt | ||
| 101 | 104 | if (issue.state === "closed") { |
| 102 | 105 | const when = (issue.closedAt ?? issue.updatedAt).slice(0, 10); |
| 103 | 106 | // Only "done" is a promise kept; the other reasons say what they are. |
| 104 | if (issue.closeReason === "done" || issue.closeReason === null) | |
| 105 | return { title: issue.title, status: { state: "shipped", label: `Shipped on ${when}` } }; | |
| 107 | if (issue.closeReason === "done" || issue.closeReason === null) { | |
| 108 | const pull = mergedPullClosing(app.db, repo.id, number); | |
| 109 | const release = pull === undefined ? undefined : releaseOfPull(app.db, repo.id, pull.number); | |
| 110 | const label = | |
| 111 | release !== undefined ? `Shipped in ${releaseName(release)}` : `Shipped on ${(pull?.mergedAt ?? issue.closedAt ?? issue.updatedAt).slice(0, 10)}`; | |
| 112 | return { title: issue.title, status: { state: "shipped", label } }; | |
| 113 | } | |
| 106 | 114 | const label = issue.closeReason === "parked" ? "Set aside for now" : issue.closeReason === "split" ? "Split into smaller pieces" : "Closed without a change"; |
| 107 | 115 | return { title: issue.title, status: { state: "closed", label: `${label} (${when})` } }; |
| 108 | 116 | } |
| @@ -185,7 +193,7 @@ export async function sendNote( | ||
| 185 | 193 | source: string, |
| 186 | 194 | ): Promise<Result<NoteView, Refusal>> { |
| 187 | 195 | const text = plainText(input.text).trim(); |
| 188 | if (text === "") return err({ error: "empty", message: "Write a few words first." }); | |
| 196 | if (text === "") return err({ error: "empty", message: NOTE_EMPTY }); | |
| 189 | 197 | if (text.length > TEXT_MAX) return err({ error: "too_long", message: "That is a bit long. Keep it under 2,000 characters." }); |
| 190 | 198 | if (isBanned(app.db, record.id, sender.key)) return err({ error: "banned", message: "Notes from here are paused." }); |
| 191 | 199 | if (filtered(text)) return err({ error: "filtered", message: "Please put that in other words." }); |
src/actions/ask_state_words.ts added +11
| @@ -0,0 +1,11 @@ | ||
| 1 | /** | |
| 2 | * What the crew says about where an ask stands (#5619), said from one place | |
| 3 | * so the asked and answers views read the same on the web and in the | |
| 4 | * terminal. Plain strings: each caller escapes them as its surface does. | |
| 5 | */ | |
| 6 | ||
| 7 | /** An ask the planner has not yet put on any issue, and nobody has replied to. */ | |
| 8 | export const NOT_PLACED_YET = "the planner has not placed it yet"; | |
| 9 | ||
| 10 | /** An ask whose issue has a run going and no answer yet. */ | |
| 11 | export const CREW_WORKING = "The crew is working on it."; |
src/actions/asks_bulk.ts +4 −2
| @@ -12,6 +12,7 @@ import type { App } from "../app.ts"; | ||
| 12 | 12 | import { listOperations, type Operation } from "../core/fleet_ops.ts"; |
| 13 | 13 | import type { User } from "../core/users.ts"; |
| 14 | 14 | import { err, ok, type Result } from "../kernel/result.ts"; |
| 15 | import { NO_SUCH_OPERATION } from "./asks_words.ts"; | |
| 15 | 16 | import { askTargetsFor } from "../web/studio/asks.ts"; |
| 16 | 17 | import { |
| 17 | 18 | applyFleetIds, |
| @@ -23,6 +24,7 @@ import { | ||
| 23 | 24 | type FleetError, |
| 24 | 25 | type Plan, |
| 25 | 26 | } from "./fleet.ts"; |
| 27 | import { SIGN_IN_TO_ACT } from "./asks_words.ts"; | |
| 26 | 28 | |
| 27 | 29 | /** |
| 28 | 30 | * What a bulk action on asks may be: the fleet verb each one is. Decline is |
| @@ -59,7 +61,7 @@ function resolve( | ||
| 59 | 61 | if (!actor) |
| 60 | 62 | return err({ |
| 61 | 63 | code: "unauthorized", |
| 62 | message: "sign in to act on your asks", | |
| 64 | message: SIGN_IN_TO_ACT, | |
| 63 | 65 | }); |
| 64 | 66 | const verb = |
| 65 | 67 | typeof action === "string" && Object.hasOwn(ASK_ACTIONS, action) |
| @@ -190,6 +192,6 @@ export async function undoAsksBulk( | ||
| 190 | 192 | ): Promise<Result<Operation, FleetError>> { |
| 191 | 193 | const op = ownAsksOperation(app, actor, operationId); |
| 192 | 194 | if (op === undefined) |
| 193 | return err({ code: "not_found", message: "no such operation here" }); | |
| 195 | return err({ code: "not_found", message: NO_SUCH_OPERATION }); | |
| 194 | 196 | return undoFleetOp(app, actor, op.id); |
| 195 | 197 | } |
src/actions/asks_decide.ts +5 −3
| @@ -14,7 +14,9 @@ import type { User } from "../core/users.ts"; | ||
| 14 | 14 | import { guardedHand, letDeciderHandle, undoHandled } from "../crew/handover.ts"; |
| 15 | 15 | import { err, ok, type Result } from "../kernel/result.ts"; |
| 16 | 16 | import { askTargetsFor } from "../web/studio/asks.ts"; |
| 17 | import { NO_LONGER_ASKS } from "./asks_words.ts"; | |
| 17 | 18 | import type { FleetError } from "./fleet.ts"; |
| 19 | import { SIGN_IN_TO_ACT } from "./asks_words.ts"; | |
| 18 | 20 | |
| 19 | 21 | export { HAND_COOLDOWN_MS } from "../crew/handover.ts"; |
| 20 | 22 | |
| @@ -57,7 +59,7 @@ export async function decideAsk( | ||
| 57 | 59 | item: unknown, |
| 58 | 60 | now = Date.now(), |
| 59 | 61 | ): Promise<Result<HandAnswer, FleetError>> { |
| 60 | if (!actor) return fail("unauthorized", "sign in to act on your asks"); | |
| 62 | if (!actor) return fail("unauthorized", SIGN_IN_TO_ACT); | |
| 61 | 63 | if (typeof item !== "string" || !ASK_ID.test(item)) |
| 62 | 64 | return fail("bad_action", "only a hand-over can be handed to the decider"); |
| 63 | 65 | if (app.config.decider === undefined) |
| @@ -68,7 +70,7 @@ export async function decideAsk( | ||
| 68 | 70 | const issue = issueIds[0] === undefined ? undefined : getIssueById(app.db, issueIds[0]); |
| 69 | 71 | const repo = issue === undefined ? undefined : getRepoById(app.db, issue.repoId); |
| 70 | 72 | if (issue === undefined || repo === undefined) |
| 71 | return fail("not_found", "it no longer asks you"); | |
| 73 | return fail("not_found", NO_LONGER_ASKS); | |
| 72 | 74 | const handed = await guardedHand(app, issue.id, now, () => |
| 73 | 75 | letDeciderHandle(app, actor, repo, issue, repo.decisionsBy), |
| 74 | 76 | ); |
| @@ -86,7 +88,7 @@ export function undoDecideAsk( | ||
| 86 | 88 | actor: User | undefined, |
| 87 | 89 | decisionId: unknown, |
| 88 | 90 | ): Result<HandAnswer, FleetError> { |
| 89 | if (!actor) return fail("unauthorized", "sign in to act on your asks"); | |
| 91 | if (!actor) return fail("unauthorized", SIGN_IN_TO_ACT); | |
| 90 | 92 | if (typeof decisionId !== "string" || decisionId === "") |
| 91 | 93 | return fail("not_found", "no such decision"); |
| 92 | 94 | const undone = undoHandled(app, actor, decisionId); |
src/actions/asks_words.ts added +18
| @@ -0,0 +1,18 @@ | ||
| 1 | /** | |
| 2 | * What acting on asks says, said from one place (#5614): bulk decide, | |
| 3 | * decide and proposals read it here, and an ask or a bulk operation whose | |
| 4 | * subject is gone answers from here too, so the web, the API, MCP and the | |
| 5 | * terminal word it the same. | |
| 6 | */ | |
| 7 | ||
| 8 | /** Acting on an ask while signed out. */ | |
| 9 | export const SIGN_IN_TO_ACT = "sign in to act on your asks"; | |
| 10 | ||
| 11 | /** Deciding an ask that has moved on: it no longer waits on this person. */ | |
| 12 | export const NO_LONGER_ASKS = "it no longer asks you"; | |
| 13 | ||
| 14 | /** A bulk operation, or a fleet verb, this place does not know. */ | |
| 15 | export const NO_SUCH_OPERATION = "no such operation here"; | |
| 16 | ||
| 17 | /** A milestone that is not here, or not readable by the one asking. */ | |
| 18 | export const NO_SUCH_MILESTONE = "no such milestone here"; |
src/actions/board_words.ts added +14
| @@ -0,0 +1,14 @@ | ||
| 1 | /** | |
| 2 | * The refusals a board save, a vote and a milestone watch answer with | |
| 3 | * (#5645): one sentence each, said the same by the API and the MCP because | |
| 4 | * both read it from here. Plain strings, no imports. | |
| 5 | */ | |
| 6 | ||
| 7 | /** A board write refused for a reason its error code names. */ | |
| 8 | export const BOARD_NOT_SAVED = "that board could not be saved"; | |
| 9 | ||
| 10 | /** A vote refused for a reason its error code names. */ | |
| 11 | export const VOTE_NOT_RECORDED = "that vote could not be recorded"; | |
| 12 | ||
| 13 | /** An agent asked to watch a milestone; watching is a person's. */ | |
| 14 | export const MILESTONE_WATCH_PERSON_ONLY = "only a person watches a milestone"; |
src/actions/branch_words.ts added +14
| @@ -0,0 +1,14 @@ | ||
| 1 | /** | |
| 2 | * A branch's sentences (#5713): making or deleting a branch reads the same | |
| 3 | * from the branches page, the MCP and the terminal, so each is | |
| 4 | * typed once and read from here. | |
| 5 | */ | |
| 6 | ||
| 7 | /** A branch create refused for a reason with no sentence of its own. */ | |
| 8 | export const BRANCH_NOT_CREATED = "That branch was not created."; | |
| 9 | ||
| 10 | /** A branch delete refused for a reason with no sentence of its own. */ | |
| 11 | export const BRANCH_NOT_DELETED = "That branch was not deleted."; | |
| 12 | ||
| 13 | /** The terminal's answer to a branch name left empty. */ | |
| 14 | export const NAME_THE_BRANCH = "give the branch a name"; |
src/actions/comment_words.ts added +10
| @@ -0,0 +1,10 @@ | ||
| 1 | /** | |
| 2 | * What a comment's refusal says, wherever it is said: the issue page, the | |
| 3 | * pull page and the forge toolbar read these so the words cannot drift. | |
| 4 | */ | |
| 5 | ||
| 6 | /** A comment with nothing in it. */ | |
| 7 | export const COMMENT_EMPTY = "A comment needs something in it."; | |
| 8 | ||
| 9 | /** A comment the forge would not post, when the origin gave no reason. */ | |
| 10 | export const COMMENT_NOT_POSTED = "That comment could not be posted."; |
src/actions/dependencies.ts +2 −1
| @@ -18,11 +18,12 @@ import { canRead, canWrite, type Repo } from "../core/repos.ts"; | ||
| 18 | 18 | import type { User } from "../core/users.ts"; |
| 19 | 19 | import { err, ok, type Result } from "../kernel/result.ts"; |
| 20 | 20 | import type { AccessError } from "./access.ts"; |
| 21 | import { SELF_WAIT } from "./plan_words.ts"; | |
| 21 | 22 | import { followLink } from "./pillars.ts"; |
| 22 | 23 | |
| 23 | 24 | /** What a refused link says, in the words the API and the MCP share. */ |
| 24 | 25 | export const dependencyWords: Record<string, string> = { |
| 25 | self: "an issue cannot wait for itself", | |
| 26 | self: SELF_WAIT, | |
| 26 | 27 | cycle: "that would make a loop", |
| 27 | 28 | cross_repo: "dependencies stay inside one repository", |
| 28 | 29 | not_an_issue: "only issues can depend on issues", |
src/actions/destination.ts +2 −1
| @@ -18,6 +18,7 @@ import { s3FromEnv, type S3Target } from "../snapshot/store.ts"; | ||
| 18 | 18 | import { snapshotsOf } from "../snapshot/service.ts"; |
| 19 | 19 | import type { User } from "../core/users.ts"; |
| 20 | 20 | import { err, ok, type Result } from "../kernel/result.ts"; |
| 21 | import { NOT_SEALED } from "../kernel/seal_words.ts"; | |
| 21 | 22 | |
| 22 | 23 | export interface DestinationInput { |
| 23 | 24 | readonly endpoint: string; |
| @@ -79,7 +80,7 @@ export function saveDestination( | ||
| 79 | 80 | for (const [name, value] of fields) { |
| 80 | 81 | if (value === "") continue; |
| 81 | 82 | const set = putSecret(app, actor, "forge", "", name, value); |
| 82 | if (!set.ok) return err("That could not be sealed."); | |
| 83 | if (!set.ok) return err(NOT_SEALED); | |
| 83 | 84 | } |
| 84 | 85 | snapshotsOf(app)?.forget(); |
| 85 | 86 | const have = sealedSet(app.db); |
src/actions/edit_words.ts added +23
| @@ -0,0 +1,23 @@ | ||
| 1 | /** | |
| 2 | * The words a file edit refuses in (#5544): one sentence per refusal kind, | |
| 3 | * so `POST …/contents` and any other door that writes a file say the same | |
| 4 | * thing for the same failure. | |
| 5 | */ | |
| 6 | export function editMessage(kind: string): string { | |
| 7 | switch (kind) { | |
| 8 | case "protected_branch": | |
| 9 | return "the default branch is protected; only a repo admin may commit to it directly"; | |
| 10 | case "file_too_large": | |
| 11 | return "that file is larger than an edit may carry; push it instead"; | |
| 12 | case "commit_too_large": | |
| 13 | return "the edit is larger than one commit may carry; push it instead"; | |
| 14 | case "branch_moved": | |
| 15 | return "the branch moved while this edit was being written; re-read and retry"; | |
| 16 | case "land_refused": | |
| 17 | return "the origin refused this commit; nothing was changed here either"; | |
| 18 | case "pull_failed": | |
| 19 | return "the commit landed, but the pull request could not be opened"; | |
| 20 | default: | |
| 21 | return "this edit could not be applied"; | |
| 22 | } | |
| 23 | } |
src/actions/explore.ts +16 −2
| @@ -25,6 +25,7 @@ import { | ||
| 25 | 25 | frontWeights, |
| 26 | 26 | type FrontSignals, |
| 27 | 27 | } from "../core/front.ts"; |
| 28 | import { isSafeName } from "../git/guard.ts"; | |
| 28 | 29 | import { canEnterApp, listReposVisibleTo, type Repo } from "../core/repos.ts"; |
| 29 | 30 | import { getUsersByIds, isActive, type User } from "../core/users.ts"; |
| 30 | 31 | import { writeStamp } from "../core/write_clock.ts"; |
| @@ -47,6 +48,8 @@ export interface ExploreQuery { | ||
| 47 | 48 | readonly text: string; |
| 48 | 49 | /** `archived:yes` — put-away repositories are in the list; off, they are not. */ |
| 49 | 50 | readonly archived: boolean; |
| 51 | /** `owner:<name>` — only this account's apps, and the person themself. */ | |
| 52 | readonly owner?: string; | |
| 50 | 53 | } |
| 51 | 54 | |
| 52 | 55 | const KINDS: Record<string, ExploreKind> = { |
| @@ -79,6 +82,7 @@ export function parseExploreQuery(line: string): ExploreQuery { | ||
| 79 | 82 | let kind: ExploreKind | "all" = "all"; |
| 80 | 83 | let sort: ExploreSort = "score"; |
| 81 | 84 | let archived = false; |
| 85 | let owner: string | undefined; | |
| 82 | 86 | const words: string[] = []; |
| 83 | 87 | for (const word of line |
| 84 | 88 | .trim() |
| @@ -94,10 +98,17 @@ export function parseExploreQuery(line: string): ExploreQuery { | ||
| 94 | 98 | sort = value.toLowerCase() as ExploreSort; |
| 95 | 99 | else if (k === "archived" && ["yes", "no"].includes(value.toLowerCase())) |
| 96 | 100 | archived = value.toLowerCase() === "yes"; |
| 101 | else if (k === "owner" && isSafeName(value)) owner = value; | |
| 97 | 102 | else if (k === "q" && value !== "") words.push(value); |
| 98 | 103 | else words.push(word); |
| 99 | 104 | } |
| 100 | return { kind, sort, text: words.join(" ").slice(0, 100), archived }; | |
| 105 | return { | |
| 106 | kind, | |
| 107 | sort, | |
| 108 | text: words.join(" ").slice(0, 100), | |
| 109 | archived, | |
| 110 | ...(owner === undefined ? {} : { owner }), | |
| 111 | }; | |
| 101 | 112 | } |
| 102 | 113 | |
| 103 | 114 | /** The line a query reads as, for links and the query box. */ |
| @@ -106,6 +117,7 @@ export function exploreLine(query: ExploreQuery): string { | ||
| 106 | 117 | query.kind === "all" ? "" : `kind:${query.kind}`, |
| 107 | 118 | query.sort === "score" ? "" : `sort:${query.sort}`, |
| 108 | 119 | query.archived ? "archived:yes" : "", |
| 120 | query.owner === undefined ? "" : `owner:${query.owner}`, | |
| 109 | 121 | query.text, |
| 110 | 122 | ] |
| 111 | 123 | .filter((p) => p !== "") |
| @@ -172,7 +184,7 @@ export async function explore( | ||
| 172 | 184 | |
| 173 | 185 | /** The forges this forge spawned, for a site admin asking for them. */ |
| 174 | 186 | async function forges(app: App, viewer: User | undefined, query: ExploreQuery): Promise<ExploreRow[]> { |
| 175 | if (viewer?.isAdmin !== true || (query.kind !== "all" && query.kind !== "forge")) return []; | |
| 187 | if (query.owner !== undefined || viewer?.isAdmin !== true || (query.kind !== "all" && query.kind !== "forge")) return []; | |
| 176 | 188 | return (await listChildren(app)).map((child) => ({ |
| 177 | 189 | kind: "forge", |
| 178 | 190 | name: child.name, |
| @@ -292,6 +304,7 @@ function rank( | ||
| 292 | 304 | }); |
| 293 | 305 | |
| 294 | 306 | const text = query.text.toLowerCase(); |
| 307 | const only = query.owner?.toLowerCase(); | |
| 295 | 308 | // Kept rows are shared by every request that reads them: none may change. |
| 296 | 309 | const freeze = (row: ExploreRow): ExploreRow => { |
| 297 | 310 | Object.freeze(row.numbers); |
| @@ -301,6 +314,7 @@ function rank( | ||
| 301 | 314 | [...appRows, ...people.values()].map(freeze).filter( |
| 302 | 315 | (row) => |
| 303 | 316 | (query.kind === "all" || row.kind === query.kind) && |
| 317 | (only === undefined || (row.repo?.owner ?? row.name).toLowerCase() === only) && | |
| 304 | 318 | (text === "" || `${row.name} ${row.description}`.toLowerCase().includes(text)), |
| 305 | 319 | ), |
| 306 | 320 | query, |
src/actions/family_words.ts added +13
| @@ -0,0 +1,13 @@ | ||
| 1 | /** | |
| 2 | * The forge family's refusals: what a repository outside the fork tree's | |
| 3 | * rules is told, typed once so the API, MCP and the contract read the same | |
| 4 | * sentence from one place. | |
| 5 | */ | |
| 6 | export const FAMILY_WORDS = { | |
| 7 | /** Proposing to the parent forge with no commit ahead of it. */ | |
| 8 | nothing_to_propose: "nothing here is ahead of the parent forge", | |
| 9 | /** Taking, severing or changing the mode of a repository with no chain across forges. */ | |
| 10 | not_following: "this repository follows nothing across forges", | |
| 11 | /** Showing or hiding a migration trail on a repository that was never migrated. */ | |
| 12 | no_provenance: "this repository was not migrated here", | |
| 13 | } as const; |
src/actions/finish-conflicts.ts +3 −2
| @@ -19,6 +19,7 @@ import { repoDir } from "../git/repos.ts"; | ||
| 19 | 19 | import { commitFiles } from "../git/write.ts"; |
| 20 | 20 | import { err, ok, type Result } from "../kernel/result.ts"; |
| 21 | 21 | import { requireWriter, type AccessError } from "./access.ts"; |
| 22 | import { NO_WRITE_ACCESS, PULL_GONE } from "./pull_words.ts"; | |
| 22 | 23 | |
| 23 | 24 | export type FinishError = |
| 24 | 25 | | AccessError |
| @@ -38,8 +39,8 @@ export type FinishError = | ||
| 38 | 39 | /** What each refusal says, on the page and in the terminal alike. */ |
| 39 | 40 | export const FINISH_REFUSALS: Record<FinishError, string> = { |
| 40 | 41 | unauthorized: "Sign in to finish a conflict.", |
| 41 | forbidden: "You do not have write access to this repository.", | |
| 42 | not_found: "That pull request is no longer here.", | |
| 42 | forbidden: NO_WRITE_ACCESS, | |
| 43 | not_found: PULL_GONE, | |
| 43 | 44 | closed: "This pull request is not open. Nothing was written.", |
| 44 | 45 | elsewhere: "This pull's branch lives elsewhere; resolve it there. Nothing was written.", |
| 45 | 46 | stale: |
src/actions/first_admin.ts +6 −5
| @@ -30,6 +30,7 @@ import { bucketOf } from "../http/peer.ts"; | ||
| 30 | 30 | import { err, ok, type Result } from "../kernel/result.ts"; |
| 31 | 31 | import { limitValue } from "../settings/limits.ts"; |
| 32 | 32 | import { handOver, spawnedOrg } from "../spawn/claim.ts"; |
| 33 | import { EMAIL_TAKEN_MESSAGE, EMAIL_WANTED, INVALID_USERNAME_MESSAGE, NAME_RESERVED, USERNAME_TAKEN } from "./signup_words.ts"; | |
| 33 | 34 | |
| 34 | 35 | const USERNAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,38}$/; |
| 35 | 36 | |
| @@ -48,11 +49,11 @@ export const FIRST_ADMIN_WORDS: Record<FirstAdminError, string> = { | ||
| 48 | 49 | rate_limited: "Too many attempts from here. Wait a minute and try again.", |
| 49 | 50 | refused: |
| 50 | 51 | "That first-admin code does not work: it may be mistyped, used, expired or replaced, or this forge already has an admin. Ask the operator to run --first-admin again.", |
| 51 | invalid_username: "Usernames are letters, digits, dots and dashes.", | |
| 52 | invalid_email: "An email address, please.", | |
| 53 | username_taken: "That username is taken.", | |
| 54 | email_taken: "That email already has an account.", | |
| 55 | username_reserved: "That name is reserved.", | |
| 52 | invalid_username: INVALID_USERNAME_MESSAGE, | |
| 53 | invalid_email: EMAIL_WANTED, | |
| 54 | username_taken: USERNAME_TAKEN, | |
| 55 | email_taken: EMAIL_TAKEN_MESSAGE, | |
| 56 | username_reserved: NAME_RESERVED, | |
| 56 | 57 | unfinished: "The account could not be finished. Try again.", |
| 57 | 58 | }; |
| 58 | 59 |
src/actions/flag_winner.ts +2 −2
| @@ -7,7 +7,7 @@ | ||
| 7 | 7 | */ |
| 8 | 8 | |
| 9 | 9 | import type { App } from "../app.ts"; |
| 10 | import { flagRegistry, mayManageFlags, winnerOffer } from "../core/flags.ts"; | |
| 10 | import { FLAGS_ADMIN_ONLY, flagRegistry, mayManageFlags, winnerOffer } from "../core/flags.ts"; | |
| 11 | 11 | import type { Issue } from "../core/issues.ts"; |
| 12 | 12 | import { getRepo } from "../core/repos.ts"; |
| 13 | 13 | import type { User } from "../core/users.ts"; |
| @@ -19,7 +19,7 @@ export function makeWinnerDefault( | ||
| 19 | 19 | name: string, |
| 20 | 20 | winner: "on" | "off", |
| 21 | 21 | ): { ok: true; issue: Issue } | { ok: false; message: string } { |
| 22 | if (!mayManageFlags(actor)) return { ok: false, message: "Flags are set by a forge admin." }; | |
| 22 | if (!mayManageFlags(actor)) return { ok: false, message: FLAGS_ADMIN_ONLY }; | |
| 23 | 23 | const registry = flagRegistry(); |
| 24 | 24 | const decl = (registry.decls as Record<string, { why: string; issue: number }>)[name]; |
| 25 | 25 | if (!Object.hasOwn(registry.decls, name) || decl === undefined) |
src/actions/fleet.ts +3 −2
| @@ -57,6 +57,7 @@ import { | ||
| 57 | 57 | type FleetKind, |
| 58 | 58 | } from "../fleet/selection.ts"; |
| 59 | 59 | import { VERBS, type Target, type Verb } from "../fleet/verbs.ts"; |
| 60 | import { NO_SUCH_OPERATION } from "./asks_words.ts"; | |
| 60 | 61 | |
| 61 | 62 | export interface FleetError { |
| 62 | 63 | readonly code: |
| @@ -599,7 +600,7 @@ export async function undoFleetOp( | ||
| 599 | 600 | op.actorId !== person.value.id && |
| 600 | 601 | (verb.personal || !parseQuery(op.query).ok) |
| 601 | 602 | ) |
| 602 | return fail("not_found", "no such operation here"); | |
| 603 | return fail("not_found", NO_SUCH_OPERATION); | |
| 603 | 604 | // The day is the same on every door: the card, the API, MCP. |
| 604 | 605 | if (keepsADay(op) && Date.now() - Date.parse(op.createdAt) > UNDO_WINDOW_MS) |
| 605 | 606 | return fail("expired", "an undo is kept for a day, and this one's day is over"); |
| @@ -661,7 +662,7 @@ export function getFleetOp( | ||
| 661 | 662 | ): Result<Operation, FleetError> { |
| 662 | 663 | const op = getOperation(app.db, operationId); |
| 663 | 664 | if (!op || !actor || (op.actorId !== actor.id && !actor.isAdmin)) |
| 664 | return fail("not_found", "no such operation here"); | |
| 665 | return fail("not_found", NO_SUCH_OPERATION); | |
| 665 | 666 | return ok(op); |
| 666 | 667 | } |
| 667 | 668 |
src/actions/follow.ts +2 −1
| @@ -13,6 +13,7 @@ import { ARCHIVED_WHY, canAdmin, canWrite, forkParentFor, type Repo } from "../c | ||
| 13 | 13 | import type { User } from "../core/users.ts"; |
| 14 | 14 | import { err, ok, type Result } from "../kernel/result.ts"; |
| 15 | 15 | import { chainOfRepo, forgeLinkOf, FOLLOW_MODES, isFollowMode, setChainMode, severChain, type FollowMode } from "../spawn/chain.ts"; |
| 16 | import { FAMILY_WORDS } from "./family_words.ts"; | |
| 16 | 17 | import { requireUser } from "./access.ts"; |
| 17 | 18 | import { takeFromParent, type Taken } from "../spawn/take.ts"; |
| 18 | 19 | import { takeUpdates, type ForkSync, type TakeUpdatesError } from "./forks.ts"; |
| @@ -102,7 +103,7 @@ export type FollowModeError = SeverError | "invalid_mode" | "severed"; | ||
| 102 | 103 | export const FOLLOW_MODE_REFUSALS: Record<FollowModeError, { status: number; message: string }> = { |
| 103 | 104 | unauthorized: { status: 401, message: "sign in to change how this forge follows its parent" }, |
| 104 | 105 | forbidden: { status: 403, message: "only this forge's owner can change how it follows" }, |
| 105 | not_following: { status: 404, message: "this repository follows nothing across forges" }, | |
| 106 | not_following: { status: 404, message: FAMILY_WORDS.not_following }, | |
| 106 | 107 | invalid_mode: { status: 422, message: `mode is one of: ${FOLLOW_MODES.join(", ")}` }, |
| 107 | 108 | severed: { status: 409, message: "this forge is severed and follows nothing; there is no mode to change" }, |
| 108 | 109 | }; |
812 more files not shown.
new above
offline