diff --git a/modules/gitea/delivery.ts b/modules/gitea/delivery.ts index 43277a67..e8dd449c 100644 --- a/modules/gitea/delivery.ts +++ b/modules/gitea/delivery.ts @@ -91,11 +91,21 @@ const states = new Set(["pending", "success", "error", "failure", "warning"]); /** The merge check's contexts (pulls.ts): a branch's protection may require them. */ const mergeCheckContexts = new Set(["mesh/merge-gate", "mesh/repo-check"]); +/** The one status main requires (novox/hq ADR 0447 §1, issue 1301): the checker's verdict, which the forge bridge + * writes through gitea_check_status alone. */ +export const CHECK_STATUS = "mesh/check"; + /** A status mesh-delivery asks for, checked: one of the forge's states, a context of the mesh's own, a * bounded description. */ export function deliveryStatus(context: string, state: string, description: string, target?: string) { if (!/^mesh\/[a-z-]+$/.test(context)) throw new Error(`${context} is not a status of the mesh's own`); if (!states.has(state)) throw new Error(`${state} is not a status the forge keeps`); + // mesh/check is the checker's verdict and the one status main requires (ADR 0447 §1): no hand sets it in any + // state, as issue 293 closed for the two before it. The forge bridge writes it through gitea_check_status, a tool + // only its account may call (issue 1301). + if (context === CHECK_STATUS) { + throw new Error(`${CHECK_STATUS} is the checker's status: the forge bridge writes it through gitea_check_status, never this tool`); + } // The merge check's statuses are its verdict's, set when the controller says it, and a branch may require // them: never set to a verdict by hand, so nothing passes — or fails — a merge past the check (novox/hq // issue 293). Pending is no verdict: it is what this holder says on every new head until the verdict comes, @@ -126,7 +136,7 @@ export interface StatusWriters { export function commitStatusTool(writers: StatusWriters): ToolDefinition { return { name: "gitea_commit_status", - description: "Set one of the mesh's statuses on a commit (mesh/delivery, mesh/delivery-group): pending, success, error, failure or warning, a short description, and the page it links to. The merge check's statuses (mesh/merge-gate, mesh/repo-check) take pending only — a recheck putting them back until the fresh verdict sets them — on the head's whole sha, in their turn after the check's earlier writes.", + description: "Set one of the mesh's statuses on a commit (mesh/delivery, mesh/delivery-group): pending, success, error, failure or warning, a short description, and the page it links to. mesh/check, the status main requires, is refused: the checker's forge bridge writes it through gitea_check_status. hq's mesh/repo-check (and mesh/merge-gate, kept for a revert) take pending only — a recheck putting them back until the fresh verdict sets them — on the head's whole sha, in their turn after the check's earlier writes.", input: { owner: { type: "string", description: "the repository owner" }, repo: { type: "string", description: "the repository name" }, @@ -153,3 +163,48 @@ export function commitStatusTool(writers: StatusWriters): ToolDefinition { }, }; } + +/** What the check's status tool writes with: the forge. */ +export interface CheckStatusWriter { + setCommitStatus(owner: string, repo: string, sha: string, status: CommitStatus): Promise; +} + +/** + * The `gitea_check_status` tool (novox/hq issue 1301, ADR 0447 §1): the one way `mesh/check` is written. Its arguments + * are gitea_commit_status's, so the forge bridge sends an owed status's arguments unchanged to it: owner, repo, sha + * (the head's whole sha), state, description, target_url, and context, which may be left out and is mesh/check when + * given. **Who may write it is the bus's grant**: the runtime tells a tool no caller, so only a module that lists + * `gitea.gitea_check_status` in its manifest's `invokes` may call it, and the forge bridge alone does. Served beside + * gitea_commit_status, from the watcher's bundle. + */ +export function checkStatusTool(writer: CheckStatusWriter): ToolDefinition { + return { + name: "gitea_check_status", + description: "Set mesh/check, the checker's verdict and the one status main requires, on a pull request's head: pending, success, error, failure or warning, a short description, and the page it links to. The checker's forge bridge alone may call it (its manifest's invokes); no other status is written here, and no other tool writes this one.", + input: { + owner: { type: "string", description: "the repository owner" }, + repo: { type: "string", description: "the repository name" }, + sha: { type: "string", description: "the head's whole sha" }, + context: { type: "string", description: "mesh/check, or left out" }, + state: { type: "string", description: "pending | success | error | failure | warning" }, + description: { type: "string", description: "one line" }, + target_url: { type: "string", description: "the page it links to (the check's report)" }, + }, + run: async (args) => { + const owner = checkName("owner", args.owner), repo = checkName("name", args.repo), sha = String(args.sha ?? ""); + if (args.context !== undefined && args.context !== null && String(args.context) !== CHECK_STATUS) { + throw new Error(`${JSON.stringify(args.context)}: this tool writes ${CHECK_STATUS} alone. Nothing was sent`); + } + if (!/^([0-9a-f]{40}|[0-9a-f]{64})$/i.test(sha)) { + throw new Error(`${JSON.stringify(args.sha)} is not a head's whole sha: ${CHECK_STATUS} names the head whole. Nothing was sent`); + } + // deliveryStatus checks the state and cuts the description; it refuses mesh/check, so it is asked for a + // context of the mesh's own and the status is named mesh/check after. + const checked = deliveryStatus("mesh/delivery", String(args.state), String(args.description ?? ""), + args.target_url ? String(args.target_url) : undefined); + const status = { ...checked, context: CHECK_STATUS }; + await writer.setCommitStatus(owner, repo, sha, status); + return { set: status }; + }, + }; +} diff --git a/modules/gitea/index.ts b/modules/gitea/index.ts index 601290e6..abf5c10e 100644 --- a/modules/gitea/index.ts +++ b/modules/gitea/index.ts @@ -38,7 +38,7 @@ import { emit, on } from "@novox/mesh-sdk/events"; import { registerModuleTools } from "@novox/mesh-sdk/tools"; -import { commitStatusTool } from "./delivery.js"; +import { checkStatusTool, commitStatusTool } from "./delivery.js"; import { announce, keepWatermark, readWatermark } from "./announce.js"; import { mergeTool } from "./merge.js"; import { GiteaAdmin, GiteaClient, movedSince } from "./client.js"; @@ -477,6 +477,8 @@ if (!gitea) pace.unheard("the forge is not watched: no way to a token", false); registerModuleTools("gitea", () => [eventsTool(pace), ...(gitea ? [commitStatusTool({ setCommitStatus: (owner, repo, sha, status) => (gitea as GiteaClient).setCommitStatus(owner, repo, sha, status), gates, +}), checkStatusTool({ + setCommitStatus: (owner, repo, sha, status) => (gitea as GiteaClient).setCommitStatus(owner, repo, sha, status), }), mergeTool(gitea, { gates })] : [])]); // **A build machine took an ask** (the build seat's `started`, novox/hq ADR 0157): said on the head it checks, when diff --git a/modules/gitea/test/delivery.test.ts b/modules/gitea/test/delivery.test.ts index 623ec204..9813a3ee 100644 --- a/modules/gitea/test/delivery.test.ts +++ b/modules/gitea/test/delivery.test.ts @@ -61,3 +61,38 @@ test("one view per pull request, found by its marker; only the mesh's statuses", assert.equal(deliveryStatus("mesh/repo-check", "pending", "checking again: main moved on").context, "mesh/repo-check"); assert.equal(deliveryStatus("mesh/delivery", "success", "x", "javascript:alert(1)").target_url, undefined); }); + +// Issue 1301-S4 (ADR 0447 §1; the lead's choice A): main requires mesh/check, so no hand may set it. The status tool +// every caller may use refuses it in every state; it is written only by gitea_check_status, which the forge bridge +// alone lists in its manifest's `invokes`, so only its account may call it. +test("mesh/check is refused by the status tool and written by the check's own tool alone", async () => { + const { commitStatusTool, checkStatusTool, deliveryStatus, CHECK_STATUS } = await import("../delivery.ts"); + assert.equal(CHECK_STATUS, "mesh/check"); + const sha = "0123456789abcdef0123456789abcdef01234567"; + const sent: string[] = []; + const setCommitStatus = async (o: string, r: string, s: string, st: any) => + void sent.push(`${o}/${r}@${s.slice(0, 8)} ${st.context} ${st.state} ${st.description}${st.target_url ? " " + st.target_url : ""}`); + const gates = { rechecked: async () => { throw new Error("not the gate writer's"); } }; + for (const state of ["pending", "success", "failure", "error", "warning"]) { + assert.throws(() => deliveryStatus("mesh/check", state, "x"), /mesh\/check is the checker's status/); + await assert.rejects(commitStatusTool({ setCommitStatus, gates } as any).run({ owner: "novox", repo: "mesh-sdk", sha, + context: "mesh/check", state, description: "by hand" }), /gitea_check_status/); + } + assert.deepEqual(sent, [], "nothing was sent for a hand-set mesh/check"); + + const tool = checkStatusTool({ setCommitStatus }); + assert.equal(tool.name, "gitea_check_status"); + for (const k of ["owner", "repo", "sha", "state", "description", "target_url", "context"]) assert.ok(k in tool.input, k); + // The bridge's arguments as it sends them for gitea_commit_status: the context may be given, and is mesh/check. + await tool.run({ owner: "novox", repo: "mesh-sdk", sha, context: "mesh/check", state: "success", description: "pass", + target_url: "https://forge.invalid/novox/mesh-sdk/pulls/1" }); + await tool.run({ owner: "novox", repo: "mesh-sdk", sha, state: "pending", description: "y".repeat(300) }); + assert.equal(sent[0], "novox/mesh-sdk@01234567 mesh/check success pass https://forge.invalid/novox/mesh-sdk/pulls/1"); + assert.ok(sent[1].startsWith("novox/mesh-sdk@01234567 mesh/check pending yyyy"), sent[1]); + assert.ok(sent[1].length < 200, "the description is cut as every status's is"); + await assert.rejects(tool.run({ owner: "novox", repo: "mesh-sdk", sha, context: "mesh/delivery", state: "success" }), /mesh\/check alone/); + await assert.rejects(tool.run({ owner: "novox", repo: "mesh-sdk", sha: sha.slice(0, 12), state: "success" }), /whole sha/); + await assert.rejects(tool.run({ owner: "novox", repo: "mesh-sdk", sha, state: "green" }), /not a status/); + await assert.rejects(tool.run({ owner: "../x", repo: "mesh-sdk", sha, state: "success" })); + assert.equal(sent.length, 2, "nothing more was sent"); +}); diff --git a/modules/gitea/test/guard.test.ts b/modules/gitea/test/guard.test.ts index c7605f3c..0e5628b2 100644 --- a/modules/gitea/test/guard.test.ts +++ b/modules/gitea/test/guard.test.ts @@ -15,7 +15,7 @@ import { GiteaClient } from "../dist/client.js"; import { ConfiguredToken } from "../dist/token.js"; import { getGiteaTools } from "../dist/tools/index.js"; import { mergeTool } from "../dist/merge.js"; -import { commitStatusTool } from "../dist/delivery.js"; +import { checkStatusTool, commitStatusTool } from "../dist/delivery.js"; import { GateWriter } from "../dist/gate.js"; import { judgeApiCall, judgeProtectionChange, ruleCovers, routedPath } from "../dist/guard.js"; @@ -168,7 +168,7 @@ const gates = { rechecked: (o: string, r: string, sha: string, s: any) => { } }; const tools = [...getGiteaTools(client), commitStatusTool({ setCommitStatus: (o, r, sha, s) => client.setCommitStatus(o, r, sha, s), gates: writer, -}), mergeTool(client, { gates, stateDir, emit: async (type, body) => { state.emitted.push({ type, body }); }, +}), checkStatusTool({ setCommitStatus: (o, r, sha, s) => client.setCommitStatus(o, r, sha, s) }), mergeTool(client, { gates, stateDir, emit: async (type, body) => { state.emitted.push({ type, body }); }, now: () => new Date(2026, 9, 12, 15, 1) })]; const tool = (name: string) => tools.find((t) => t.name === name)!; const writes = () => state.sent.map((s) => `${s.method} ${s.path}`); @@ -568,6 +568,10 @@ test("no tool's caller text becomes another path or another user: `..` and `?sud ["gitea_get_file", { ...repo, path: "README.md?sudo=jschoubben" }], ["gitea_commit_status", { ...repo, sha: "abc1234?sudo=jschoubben", context: "mesh/delivery", state: "success" }], ["gitea_commit_status", { ...repo, sha: "../../../admin/users", context: "mesh/delivery", state: "success" }], + ["gitea_check_status", { ...repo, sha: "abc1234?sudo=jschoubben", state: "success" }], + ["gitea_check_status", { ...repo, sha: "../../../admin/users", state: "success" }], + ["gitea_check_status", { owner: "novox", repo: "..", sha: "0123456789abcdef0123456789abcdef01234567", state: "success" }], + ["gitea_commit_status", { ...repo, sha: "0123456789abcdef0123456789abcdef01234567", context: "mesh/check", state: "success" }], ["gitea_commit_statuses", { ...repo, sha: ".." }], ["gitea_commit_statuses", { ...repo, sha: "main?sudo=jschoubben" }], ["gitea_branch_protection_set", { ...repo, branch: "..", status_checks: "mesh/merge-gate" }],