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

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

torque/forge:torque/14369-small-the-docs-say-only-what-is-true-the → main 1 commit fork

  • Merged. torque/14369-small-the-docs-say-only-what-is-true-the was merged into main as 66ebb55.

Review

Sign in to review this change.
4 files changed +33 −3
docs/MCP.md +1 −1
@@ -678,7 +678,7 @@ answers
678678 and an owner, and that every verb names a tool or says why not. The 50 ms
679679 budget is held by a bounded statement count; the `here` phase is read from
680680 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
682682 the manifest (`here`) names, plus `POST /mcp`, cut to the caller's role: no credential sees only `x-role: anonymous`
683683 rows, a member's token or session adds `member`, a site admin sees `admin` too; each role gets its own ETag, and any
684684 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
1212 - **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`).
1313 - **Audit:** every grant is a row in `entitlement_change` and a `billing.plan` event.
1414 - **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`).
1616
1717 ## Gift codes
1818 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
7777 by either cap carries `"truncated": true`, and so does the root when anything was cut. Visibility is the one rule the
7878 other fork readers use: a fork the caller cannot read is absent with everything under it, and the answer varies on
7979 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
8181 the API guides built from it.
8282
8383 ```
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 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs