Public: anyone can read this; the crew can change it.
small: the docs say only what is true: the one OpenAPI URL, and billing's Stripe receiver and checkout as built #14416
Check · Review · Land · Live done — Landed and live in production.
torque/forge:torque/14369-small-the-docs-say-only-what-is-true-the → main 1 commit fork
4 files
changed +33
−3
docs/MCP.md +1 −1
| @@ -678,7 +678,7 @@ answers | ||
| 678 | 678 | and an owner, and that every verb names a tool or says why not. The 50 ms |
| 679 | 679 | budget is held by a bounded statement count; the `here` phase is read from |
| 680 | 680 | Server-Timing and bounded at the flake floor (`WALL_CLOCK_FLOOR_MS`). |
| 681 | - **Contract.** `GET /contract/openapi.json` is the one URL to name (the aliases `/openapi.json` and `/api/v1/openapi.json` answer the same 200 document and ETag, none redirects, and carry `Link: <…/contract/openapi.json>; rel="canonical"`; `servers` is the request's origin, bearer `token` is the default `security`, open routes say `security: []`) is OpenAPI 3.1 for the routes | |
| 681 | - **Contract.** `GET /contract/openapi.json` is the one URL to name (the old aliases answer the same 200 document and ETag, none redirects, and carry `Link: <…/contract/openapi.json>; rel="canonical"`; `servers` is the request's origin, bearer `token` is the default `security`, open routes say `security: []`) is OpenAPI 3.1 for the routes | |
| 682 | 682 | the manifest (`here`) names, plus `POST /mcp`, cut to the caller's role: no credential sees only `x-role: anonymous` |
| 683 | 683 | rows, a member's token or session adds `member`, a site admin sees `admin` too; each role gets its own ETag, and any |
| 684 | 684 | answer but the anonymous one is `cache-control: private` (`vary: authorization, cookie`). It also describes planning: `GET …/map`, `POST …/plan`, |
docs/features/billing.md +1 −1
| @@ -12,7 +12,7 @@ Billing records the plan each forge is on (`src/billing/`): a store of entitleme | ||
| 12 | 12 | - **Preview first:** the page's *Review change* opens `/settings/billing/change?forge=&plan=`, which says in one line `small → medium: $49.00 a month, starts 2026-11-15` (from, to, whole cents a month from the plans setting, the UTC day it starts) and carries those numbers in its *Confirm change* form. A confirm whose numbers differ from what the preview would say now (a price edited, the day rolled over) changes nothing and shows the new preview (409). The terminal's yes/no shows the same line; no Stripe call is made (`src/billing/plan_change.ts`). |
| 13 | 13 | - **Audit:** every grant is a row in `entitlement_change` and a `billing.plan` event. |
| 14 | 14 | - **Terminal:** the palette's *Billing* (admins), `src/tui/screens/billing.ts`: `j`/`k` pick a forge, `s`, `m` or `l` grants that plan after a yes/no; `c` connects Stripe (key shown as dots), `w` saves a signing secret, `x` disconnects after a yes/no. |
| 15 | - **Stripe (#11136):** Settings → Billing → Provider takes one key (`src/billing/stripe.ts`, `connection.ts`); how to connect it is in `docs/PROFIT.md`. Not yet: the `/hooks/stripe` receiver, and checkout, portal and reconcile, which come with the pull that calls them. | |
| 15 | - **Stripe (#11136):** Settings → Billing → Provider takes one key (`src/billing/stripe.ts`, `connection.ts`); how to connect it is in `docs/PROFIT.md`. Built: the `/hooks/stripe` receiver (`src/http/stripe_hook.ts`), hosted checkout (`src/billing/checkout.ts`), and reconcile, which writes an entitlement from the subscription as Stripe has it, on a webhook and in a daily sweep (`src/billing/sync.ts`). Not built: the forge makes no Stripe billing-portal session; the portal is a link the host sets (`billing.portal_url`). | |
| 16 | 16 | |
| 17 | 17 | ## Gift codes |
| 18 | 18 | A code gives a plan for free, with or without a payment provider (`src/billing/codes.ts`, `src/actions/codes.ts`). No provider is asked: a redeemed code writes the entitlement itself, source `code:<id>`. |
docs/features/fork-tree.md +1 −1
| @@ -77,7 +77,7 @@ listed or counted, so the number never hints at a private fork. "All" opens the | ||
| 77 | 77 | by either cap carries `"truncated": true`, and so does the root when anything was cut. Visibility is the one rule the |
| 78 | 78 | other fork readers use: a fork the caller cannot read is absent with everything under it, and the answer varies on |
| 79 | 79 | the caller's identity (`private, no-cache`, `Vary: authorization, cookie`, an `ETag`). It is a separate route so the |
| 80 | flat, paged `GET .../forks` keeps its contract. It is in the OpenAPI document (`/api/v1/openapi.json`) and so in | |
| 80 | flat, paged `GET .../forks` keeps its contract. It is in the OpenAPI document (`/contract/openapi.json`) and so in | |
| 81 | 81 | the API guides built from it. |
| 82 | 82 | |
| 83 | 83 |
test/docs-openapi-alias.test.ts added +30
| @@ -0,0 +1,30 @@ | ||
| 1 | /** | |
| 2 | * The forge describes itself at one URL, `/contract/openapi.json` (#14369). No doc names an alias | |
| 3 | * for it. An app's own `/openapi.json` stays in docs/APPS.md and docs/features/api-reference.md. | |
| 4 | */ | |
| 5 | import { expect, test } from "bun:test"; | |
| 6 | import { readdirSync, readFileSync } from "node:fs"; | |
| 7 | import { join } from "node:path"; | |
| 8 | ||
| 9 | const root = join(import.meta.dir, "..", "docs"); | |
| 10 | const appOwn = new Set(["APPS.md", join("features", "api-reference.md")]); | |
| 11 | ||
| 12 | function files(dir: string): string[] { | |
| 13 | return readdirSync(dir, { withFileTypes: true }).flatMap((e) => | |
| 14 | e.isDirectory() ? files(join(dir, e.name)) : e.name.endsWith(".md") ? [join(dir, e.name)] : [], | |
| 15 | ); | |
| 16 | } | |
| 17 | ||
| 18 | test("no doc names the forge's OpenAPI alias", () => { | |
| 19 | const found: string[] = []; | |
| 20 | for (const f of files(root)) { | |
| 21 | const rel = f.slice(root.length + 1); | |
| 22 | const text = readFileSync(f, "utf8"); | |
| 23 | const re = appOwn.has(rel) ? /\/api\/v1\/openapi\.json/g : /(?<!contract)\/openapi\.json/g; | |
| 24 | for (const [i, line] of text.split("\n").entries()) { | |
| 25 | re.lastIndex = 0; | |
| 26 | if (re.test(line)) found.push(`${rel}:${i + 1}`); | |
| 27 | } | |
| 28 | } | |
| 29 | expect(found).toEqual([]); | |
| 30 | }); |
new above
offline