Add mesh-delivery, the owner of deliveries and delivery groups (hq ADR 0239)

One module answers 'did my change go out' for a commit and orders a
cross-repository change: one compiled state table, its state on the bus,
every transition said, noted on the commit and shown on the pull request.
The forge's holder gains the note, view and status tools it asks with, and
says closed pull requests and a merge's head and statuses.

modules/gitea/tools/index.ts

@@ -11,6 +11,10 @@
 import { registerModuleTools, type ToolDefinition } from "@novox/mesh-sdk/tools";
 import { emit } from "@novox/mesh-sdk/events";
 import { GiteaClient, type BranchProtection } from "../client.js";
+import { appendNote, deliveryStatus, run, viewBody, viewComment } from "../delivery.js";
+
+/** The forge's container, where its repositories and git are: the note is written there (novox/hq ADR 0239). */
+const forgeContainer = process.env.MESH_GITEA_CONTAINER || "gitea";
 
 /** A protection rule as a person reads it: what it guards, not every field the forge keeps. */
 export function summarised(p: BranchProtection) {
@@ -412,6 +416,60 @@ export function getGiteaTools(gitea: GiteaClient): ToolDefinition[] {
       },
     },
 
+    // ---- A delivery's note, view and statuses (novox/hq ADR 0239), asked by mesh-delivery ----
+    {
+      name: "gitea_note_append",
+      description: "Append one line to a commit's git note under refs/notes/<ref> (mesh-plan for a delivery), written in the forge's own repository as the forge's own account; a line the note already holds is not added again. `git log --notes=mesh-plan` shows it.",
+      input: {
+        owner: { type: "string", description: "the repository owner" },
+        repo: { type: "string", description: "the repository name" },
+        sha: { type: "string", description: "the commit" },
+        ref: { type: "string", description: "the notes ref's name (default mesh-plan)" },
+        line: { type: "string", description: "the line, one line" },
+      },
+      run: async (args) => {
+        const said = await appendNote(run, forgeContainer, String(args.owner), String(args.repo), String(args.sha),
+          String(args.ref ?? "mesh-plan") || "mesh-plan", String(args.line ?? ""));
+        return { commit: String(args.sha), ...said };
+      },
+    },
+    {
+      name: "gitea_delivery_view",
+      description: "Keep a delivery's view on its pull request: one comment, marked as the delivery's, created the first time and edited in place after — the page every status of the delivery links to.",
+      input: {
+        owner: { type: "string", description: "the repository owner" },
+        repo: { type: "string", description: "the repository name" },
+        number: { type: "number", description: "the pull request's number" },
+        body: { type: "string", description: "the view, markdown" },
+      },
+      run: async (args) => {
+        const owner = String(args.owner), repo = String(args.repo), number = Number(args.number);
+        const body = viewBody(String(args.body ?? ""));
+        const existing = viewComment(await gitea.listComments(owner, repo, number));
+        if (existing) return { edited: await gitea.editComment(owner, repo, existing.id, body) };
+        return { created: await gitea.addComment(owner, repo, number, body) };
+      },
+    },
+    {
+      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.",
+      input: {
+        owner: { type: "string", description: "the repository owner" },
+        repo: { type: "string", description: "the repository name" },
+        sha: { type: "string", description: "the commit" },
+        context: { type: "string", description: "the status's name, mesh/…" },
+        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 pull request)" },
+      },
+      run: async (args) => {
+        const status = deliveryStatus(String(args.context), String(args.state), String(args.description ?? ""),
+          args.target_url ? String(args.target_url) : undefined);
+        await gitea.setCommitStatus(String(args.owner), String(args.repo), String(args.sha), status);
+        return { set: status };
+      },
+    },
+
     // ---- Labels ----
     {
       name: "gitea_list_labels",