Public: anyone can read this; the crew can change it.

A pull's check.txt door is in the OpenAPI contract and llms.txt, so an agent that reads the contract finds it #12395

Merged opened this

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

Merged

torque/forge:torque/12394-a-pull-s-check-txt-door-is-in-the-openap → main 3 commits fork

  • Merged. torque/12394-a-pull-s-check-txt-door-is-in-the-openap was merged into main as a8ab233.

Review

Sign in to review this change.
8 files changed +40 −3
docs/CONTRACT.md +7
@@ -246,6 +246,13 @@ Two more places the table reaches, so it is never only a page:
246246 row per app, resource, verb and identity, with the answer and what the
247247 door said when last knocked on. The viewer's apps only.
248248
249 ## Agent doors beside the table
250
251 - `GET /<owner>/<repo>/pulls/<n>/check.txt` is a pull's latest check as plain
252 text (line 1 `pending`, `green` or `red`; line 2 `head: <oid>`; on red the
253 log tail where the log door allows it). It is in the OpenAPI description and
254 in `/llms.txt`; `test/openapi-check-txt.test.ts` keeps the three in step.
255
249256 ## What is not here yet
250257
251258 - The weekly policy review as a routine: the same three lists, once a week,
src/contract/openapi/routes/getOwnerNamePullsNumberCheckTxt.ts added +10
@@ -0,0 +1,10 @@
1 import type { Route } from "../shared.ts";
2
3 export const route: Route = {
4 method: "get",
5 path: "/{owner}/{name}/pulls/{number}/check.txt",
6 summary:
7 "A pull's latest check as `text/plain`, for a script: line 1 is `pending`, `green` or `red`, line 2 is `head: <oid>`; on red a blank line and the last 80 log lines follow, only where the run-log door would show that reader the log. Anonymous on a public repository. It differs from `/api/v1/repos/{owner}/{name}/pulls/{number}/checks?format=text` (`state:`, `head:`, `required:` lines, no log tail, state words `none`/`ok`/`failed`): this answers the one word to branch on, plus the failing tail",
8 auth: false,
9 role: "anonymous",
10 };
src/contract/openapi/routes/index.ts +1
@@ -238,6 +238,7 @@ export { route as getApiV1UsersUsernameSignins } from "./getApiV1UsersUsernameSi
238238 export { route as getApiV1Version } from "./getApiV1Version.ts";
239239 export { route as getContractOpenapiJson } from "./getContractOpenapiJson.ts";
240240 export { route as getMetrics } from "./getMetrics.ts";
241 export { route as getOwnerNamePullsNumberCheckTxt } from "./getOwnerNamePullsNumberCheckTxt.ts";
241242 export { route as patchApiV1AdminSettings } from "./patchApiV1AdminSettings.ts";
242243 export { route as patchApiV1AgentsUsername } from "./patchApiV1AgentsUsername.ts";
243244 export { route as patchApiV1ConversationsId } from "./patchApiV1ConversationsId.ts";
src/contract/tags.ts +2 −1
@@ -127,7 +127,8 @@ export const TAG_WORDS: Readonly<Record<string, string>> = {
127127 export function tagOf(path: string): string {
128128 const s = path.split("/").filter(Boolean);
129129 let raw: string;
130 if (s[0] !== "api") raw = s[0] ?? "meta";
130 if (s[0]?.startsWith("{")) raw = s[2] ?? "meta"; // /{owner}/{name}/<resource>/…: a repository's own door
131 else if (s[0] !== "api") raw = s[0] ?? "meta";
131132 else if (s[2] === "repos") raw = s[5] ?? "repos";
132133 else if (s[2] === "openapi.json") raw = "contract";
133134 else raw = s[2] ?? "api";
src/web/standards.ts +1
@@ -504,6 +504,7 @@ function renderLlmsTxt(ctx: Ctx, o: string, tell: string | undefined, running: s
504504 `- Explore repositories: GET ${o}/api/v1/explore?q=kind:app+sort:forks+garden. (MCP "explore": with an account.) In q, kind: is app, person or forge; sort: is score, forks, ships, likes, use, fresh or name; updated: is 1d, 7d or 30d; owner:<name> is one account; archived: is yes or no; any other word is free text matched against name, owner and description.`,
505505 `- Search issues, pulls, repositories and code: GET ${o}/api/v1/search?q=websocket+timeout. (MCP "search": with an account.)`,
506506 "- Both read only what is public to you.",
507 `- A pull's check as text: GET ${o}/{owner}/{name}/pulls/{number}/check.txt (pending, green or red; head: <oid>).`,
507508 "",
508509 "## For agents with an account",
509510 "",
test/llms-anonymous.test.ts +2 −2
@@ -47,8 +47,8 @@ test("the anonymous text is small, varies by reader, and lists report and start
4747 const res = await fetch(`${servers.url}/llms.txt`);
4848 const body = await res.text();
4949 // 6.5 KiB until the three doors (#12015, about 440 bytes) opened the text;
50 // nothing else was cut to make room.
51 expect(Buffer.byteLength(body)).toBeLessThan(7 * 1024);
50 // nothing else was cut to make room. 7.5 KiB since the check.txt door's line.
51 expect(Buffer.byteLength(body)).toBeLessThan(7.5 * 1024);
5252 expect(res.headers.get("vary")).toContain("Cookie");
5353 expect(res.headers.get("vary")).toContain("Authorization");
5454 const listed = section(body);
test/openapi-check-txt.test.ts added +16
@@ -0,0 +1,16 @@
1 import { expect, test } from "bun:test";
2 import { readFileSync } from "node:fs";
3 import { ROUTES } from "../src/contract/openapi.ts";
4
5 const server = readFileSync(new URL("../src/http/server.ts", import.meta.url), "utf8");
6 const m = /router\.add\("GET", "([^"]*\/check\.txt)"/.exec(server);
7
8 test("the check.txt door registered in server.ts is described in the OpenAPI contract", () => {
9 expect(m, "server.ts no longer registers a check.txt door").not.toBeNull();
10 const want = m![1]!.replace(/:(\w+)/g, "{$1}");
11 const row = ROUTES.find((r) => r.method === "get" && r.path === want);
12 expect(row, `GET ${want} is registered but has no OpenAPI row`).toBeDefined();
13 expect(row!.role).toBe("anonymous");
14 expect(row!.summary).toContain("text/plain");
15 expect(row!.summary).toContain("checks?format=text");
16 });
test/openapi-drift.test.ts +1
@@ -10,6 +10,7 @@ const NOT_ROUTED: Readonly<Record<string, string>> = {
1010 "GET /contract/openapi.json": "the document, an alias of /api/v1/openapi.json served outside /api/v1",
1111 "GET /api/v1/repos/{}/{}/app/production/open": "the described form of the routed /app/:env/open, with env fixed to production",
1212 "GET /metrics": "routed outside /api/v1 (src/http/api.ts); the scan reads /api/v1 routes only",
13 "GET /{}/{}/pulls/{}/check.txt": "routed outside /api/v1 (src/http/server.ts, check_text.ts); test/openapi-check-txt.test.ts pins it to server.ts",
1314 "POST /mcp": "routed outside /api/v1 (src/http/mcp.ts); the MCP has its own card and tool list",
1415 };
1516 const NOT_DESCRIBED: Readonly<Record<string, string>> = {};

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs