diff --git a/modules/gitea/calls.ts b/modules/gitea/calls.ts new file mode 100644 index 000000000..4f22c968f --- /dev/null +++ b/modules/gitea/calls.ts @@ -0,0 +1,72 @@ +// **The call is written before its first merge** (novox/hq design 47 H §766; H-A-18, H-A-47, H-A-71): before it merges +// anything, the forge module writes the call's key `call.` in its own template state `calls` (the seat git's +// definition declares it): `by`, the bus account the tool runner proved, `at`, the members, each with its base `branch` +// and `state` judged, merged with its commit, or refused with why, and `said`, whether its `merge-called` was said. Each +// member is updated as it merges. A call is kept `call-retention` (a setting, default 30 days), then deleted by the forge +// module on each new call's write, oldest first, with no timer (H-A-47). + +import { readFileSync } from "node:fs"; +import type { State } from "@novox/mesh-sdk/state"; +import { callsByCallCallKey, parseCallsByCallCallKey, type Call, type CallMember } from "@novox/mesh-delivery-contracts-git"; + +/** call-retention's default, in days (§766). */ +export const CALL_RETENTION_DAYS = 30; + +/** call-retention as the module's config file says it, in days; the default when it says none (mainrules.ts' form). */ +export function callRetentionDays(env: NodeJS.ProcessEnv = process.env): number { + const file = env.MESH_GITEA_CONFIG_FILE; + if (!file) return CALL_RETENTION_DAYS; + try { + const v = Number((JSON.parse(readFileSync(file, "utf8")) as Record)["call-retention"]); + return Number.isInteger(v) && v >= 1 ? v : CALL_RETENTION_DAYS; + } catch { return CALL_RETENTION_DAYS; } +} + +/** One kept call with its id. */ +export interface KeptCall extends Call { + call: string; +} + +/** The state `calls`: one key per merge call. */ +export class Calls { + constructor(private readonly st: State, private readonly retentionDays: () => number = () => CALL_RETENTION_DAYS, + private readonly log: (line: string) => void = () => {}) {} + + /** Every call kept, newest first. */ + async all(): Promise { + const out: KeptCall[] = []; + for (const key of await this.st.keys()) { + const parsed = parseCallsByCallCallKey(key); + if (!parsed) continue; + const e = await this.st.get(key); + if (e?.value) out.push({ ...(e.value as Call), call: parsed.call }); + } + return out.sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : a.call < b.call ? 1 : -1)); + } + + /** One call, or undefined. */ + async get(call: string): Promise { + const e = await this.st.get(callsByCallCallKey(call)); + return e?.value ? { ...(e.value as Call), call } : undefined; + } + + /** Writes a call. A new call (none kept under its key) first deletes the calls past call-retention, oldest first. */ + async put(call: string, value: Call, now: Date = new Date()): Promise { + if (!(await this.st.get(callsByCallCallKey(call)))?.value) await this.expire(now); + await this.st.put(callsByCallCallKey(call), value); + } + + /** Deletes the calls whose `at` is past call-retention before now, oldest first; answers the calls deleted. */ + async expire(now: Date): Promise { + const before = now.getTime() - this.retentionDays() * 86_400_000; + const old = (await this.all()).filter((c) => (Date.parse(c.at) || 0) < before).reverse(); + for (const c of old) await this.st.delete(callsByCallCallKey(c.call)); + if (old.length) this.log(`${old.length} merge calls past ${this.retentionDays()} days deleted: ${old.map((c) => c.call).join(", ")}`); + return old.map((c) => c.call); + } +} + +/** A kept member of a call. */ +export const keptMember = (m: { repository: string; number: number; branch: string; head: string; state: CallMember["state"]; + commit?: string; why?: string }): CallMember => ({ repository: m.repository, number: m.number, branch: m.branch, head: m.head, + state: m.state, ...(m.commit ? { commit: m.commit } : {}), ...(m.why ? { why: m.why } : {}) }); diff --git a/modules/gitea/index.ts b/modules/gitea/index.ts index 24daa21f7..db90a36a5 100644 --- a/modules/gitea/index.ts +++ b/modules/gitea/index.ts @@ -50,6 +50,7 @@ import { FORGE_CONTAINER, seatTools } from "./seat.js"; import { REGISTRATION_CHANGED_EVENT, Registrations } from "./registrations.js"; import { FailedSteps, Heads, readHeads } from "./failedsteps.js"; import { failedStepsTools } from "./tools/failedsteps.js"; +import { Calls, callRetentionDays } from "./calls.js"; import { seat as GIT, events as GIT_EVENTS, type BranchMovedEvent, type PullClosedEvent, type PullMergedEvent, type PullUpdatedEvent } from "@novox/mesh-delivery-contracts-git"; import { seat as RUNNER, events as RUNNER_EVENTS, type StepEndedEvent } from "@novox/mesh-delivery-contracts-mesh-pipeline-runner"; import { run } from "./delivery.js"; @@ -400,6 +401,8 @@ const registrations = new Registrations((verb, input) => broker().request(verb, // The failed steps the runner's step-ended said, and the heads that keep them (failedsteps.ts; design 47 §39, §475, §487, §135). const heldHeads = new Heads(); let reloadHeads: () => Promise = async () => {}; +// The merge calls, each written before its first merge (calls.ts; design 47 H §766). +const calls = new Calls(state("calls"), () => callRetentionDays(), (line) => console.log(`[gitea] ${line}`)); const failedSteps = new FailedSteps(state("failed-steps"), (line) => console.log(`[gitea] ${line}`), (commit) => heldHeads.has(commit)); // The `seen` keys past their 30 days are deleted at the start, as on each step-ended (design 47 §581). @@ -411,7 +414,7 @@ void failedSteps.expireSeen().catch((err) => console.log(`[gitea] the seen keys registerModuleTools("gitea", () => [eventsTool(pace), ...readAllTools(readAll), ...writeTools(writes), ...statusTools("gitea", "gitea_first_views", "gitea_first_view_again", followers, firstViews, async (act) => { await broker().request("seat:mesh-hand-acts.hand-act", act); }), ...(gitea ? seatTools(gitea, { run, container: FORGE_CONTAINER, statuses: gates, registered: () => registrations.written, judge: (head) => failedSteps.judge(head), - watched: () => registrations.watched }) : []), + watched: () => registrations.watched, calls }) : []), ...failedStepsTools(failedSteps, async (act) => { await broker().request("seat:mesh-hand-acts.hand-act", act); })]); /** What the forge's event asks of the announcer at once (issue 729, 1422): see watch.ts. */ diff --git a/modules/gitea/kept.ts b/modules/gitea/kept.ts index 9288b8aa5..790780182 100644 --- a/modules/gitea/kept.ts +++ b/modules/gitea/kept.ts @@ -6,6 +6,7 @@ // checks/readable every state another manifest reads to a readable announcement. export const KEPT: readonly { readonly name: string; readonly readable?: boolean }[] = [ { name: "announced" }, + { name: "calls" }, { name: "bound", readable: true }, { name: "findings", readable: true }, { name: "failed-steps" }, diff --git a/modules/gitea/mergecall.ts b/modules/gitea/mergecall.ts index 500541908..29fc96005 100644 --- a/modules/gitea/mergecall.ts +++ b/modules/gitea/mergecall.ts @@ -13,6 +13,7 @@ import type { MemberOutcome, MergePullAnswer } from "@novox/mesh-delivery-contra import type { GiteaClient } from "./client.js"; import { Refused, checkName } from "./guard.js"; import type { Judged } from "./failedsteps.js"; +import { keptMember, type Calls } from "./calls.js"; /** What a merge call reaches beside the forge's API. */ export interface CallDeps { @@ -24,6 +25,9 @@ export interface CallDeps { judge: (head: string) => Promise; /** A new call's id: 16 lowercase hex characters (H-A-24). */ newCall?: () => string; + /** The state calls (calls.ts): the call is written before its first merge and as each member merges (§766). */ + calls?: Calls; + now?: () => Date; } /** The forge's API a merge call uses. */ @@ -131,12 +135,22 @@ export async function mergeCall(forge: CallForge, args: Record, refused = true; } } - if (refused) return { call, members: members.map(outcomeOf) }; + const now = deps.now ?? (() => new Date()); + const at = now().toISOString(); + // The call as kept (§766): a call refused at judging merged nothing and has nothing to say. + const keep = (said: boolean) => deps.calls?.put(call, { by, account, at, members: members.map(keptMember), said }, now()); + if (refused) { + await keep(true); + return { call, members: members.map(outcomeOf) }; + } + // Written before the first merge, and again as each member merges. + await keep(false); // Then merged in the order the call names them; a member the forge refuses stops the call (§767). for (const m of members) { try { m.commit = await mergeMember(forge, m); m.state = "merged"; + await keep(false); } catch (err) { m.state = "refused"; m.why = `the forge refused the merge: ${err instanceof Error ? err.message : String(err)}`; @@ -144,6 +158,7 @@ export async function mergeCall(forge: CallForge, args: Record, rest.state = "refused"; rest.why = `not merged: ${m.repository}#${m.number} before it was refused by the forge`; } + await keep(false); break; } } diff --git a/modules/gitea/module.json b/modules/gitea/module.json index 24da1123d..55bc097c4 100644 --- a/modules/gitea/module.json +++ b/modules/gitea/module.json @@ -211,6 +211,13 @@ "trusted": true, "default": {} }, + "call-retention": { + "type": "number", + "description": "How many days the forge module keeps a merge call in its state calls (design 47 H §766): a call older than this is deleted when a new call is written, oldest first.", + "trusted": false, + "minimum": 1, + "default": 30 + }, "keep-main-rules": { "type": "boolean", "description": "Whether the module keeps main's branch protection as the mesh wants it. True: every ten minutes, and at the start, main's rule in every repository of the organisation novox is put to no push and the tools' account alone merging, and each apply of the `repositories` value narrows the main rule of the repositories it lists, requiring no status. False (the default): the module changes no existing repository's branch protection, whoever set it at the forge, but takes away a required status it finds on a rule covering main, once (ADR 0534 §1); a repository listed in `repositories` that does not exist is still made, with its first protection.", @@ -358,7 +365,8 @@ "takes-config": [ "url", "keep-main-rules", - "main-mergers" + "main-mergers", + "call-retention" ] }, { @@ -623,6 +631,10 @@ { "name": "failed-steps", "history": 1 + }, + { + "name": "calls", + "history": 1 } ], "reads": [ diff --git a/modules/gitea/seat.ts b/modules/gitea/seat.ts index ea228255d..969bfff0f 100644 --- a/modules/gitea/seat.ts +++ b/modules/gitea/seat.ts @@ -27,6 +27,7 @@ import { Refused, checkName } from "./guard.js"; import { appendNote, viewBody, viewComment, type Runner } from "./delivery.js"; import type { Judged } from "./failedsteps.js"; import { mergeCall } from "./mergecall.js"; +import type { Calls } from "./calls.js"; /** The verbs of the seat, in its definition's order. */ export const VERBS: readonly string[] = Object.values(GIT_VERBS); @@ -56,6 +57,8 @@ export interface SeatDeps { judge: (head: string) => Promise; /** The watched branches the registrations name, by their origin repository (registrations.ts): a member's base is one. */ watched: () => ReadonlyMap>; + /** The state calls (calls.ts): each merge call written before its first merge (design 47 H §766). */ + calls?: Calls; } /** A failure as the contract says it: the forge's or this holder's refusal, or a forge that failed. */ diff --git a/modules/gitea/test/calls.test.ts b/modules/gitea/test/calls.test.ts new file mode 100644 index 000000000..27a0c8f21 --- /dev/null +++ b/modules/gitea/test/calls.test.ts @@ -0,0 +1,62 @@ +import assert from "node:assert/strict"; +import { test } from "node:test"; + +// **The call is written before its first merge** (novox/hq design 47 H §766; H-A-18, H-A-47, H-A-71): the key +// call. of the state calls holds by, the proved account, at, each member with its base and its state (judged before +// the first merge, merged with its commit as it merges) and said; a call past call-retention is deleted on a new call's +// write, oldest first. + +const A = "a".repeat(40), B = "b".repeat(40); + +export function memory() { + const kv = new Map(); + return { kv, st: { + get: async (k: string) => (kv.has(k) ? { key: k, value: structuredClone(kv.get(k)), revision: 1 } : null), + put: async (k: string, v: unknown) => { kv.set(k, structuredClone(v)); return 1; }, + delete: async (k: string) => { kv.delete(k); }, + keys: async () => [...kv.keys()].sort(), + watch: async () => {}, + } }; +} + +test("a merge call is kept before its first merge, each member judged, then merged with its commit", async () => { + const { mergeCall } = await import("../dist/mergecall.js"); + const { Calls } = await import("../dist/calls.js"); + const { runAs } = await import("@novox/mesh-sdk/callers"); + const { kv, st } = memory(); + const calls = new Calls(st as any); + const seenAtMerge: any[] = []; + const pulls: Record = { 5: { head: A, merged: false }, 9: { head: B, merged: false } }; + const forge = { + getPullRequest: async (_o: string, r: string, n: number) => ({ number: n, state: "open", merged: pulls[n].merged, base: "main", + head_sha: pulls[n].head, ...(pulls[n].merged ? { merge_commit_sha: String(n).repeat(40) } : {}) }), + mergePullRequest: async (_o: string, _r: string, n: number) => { + seenAtMerge.push(structuredClone(kv.get("call.0123456789abcdef"))); + pulls[n].merged = true; + }, + commitParents: async () => [], + }; + const args = { by: "lead@shanks", pulls: [{ repository: "novox/app", number: 5, head: A }, { repository: "novox/app", number: 9, head: B }] }; + const at = new Date("2026-11-20T03:00:00Z"); + await runAs({ "mesh/caller": "shanks.claude-code" }, args, () => mergeCall(forge as any, args, { registered: () => true, + watched: () => new Map([["novox/app", new Set(["main"])]]), judge: async () => null, newCall: () => "0123456789abcdef", + calls, now: () => at } as any)); + const first = seenAtMerge[0]; + assert.deepEqual([first.by, first.account, first.at, first.said], ["lead@shanks", "shanks.claude-code", at.toISOString(), false]); + assert.deepEqual(first.members.map((m: any) => [m.number, m.branch, m.head, m.state]), [[5, "main", A, "judged"], [9, "main", B, "judged"]]); + assert.deepEqual(seenAtMerge[1].members.map((m: any) => [m.state, m.commit]), [["merged", "5".repeat(40)], ["judged", undefined]]); + const kept = await calls.get("0123456789abcdef"); + assert.deepEqual(kept?.members.map((m: any) => m.state), ["merged", "merged"]); +}); + +test("a call past call-retention is deleted on a new call's write, oldest first; a younger one is kept", async () => { + const { Calls } = await import("../dist/calls.js"); + const { kv, st } = memory(); + const calls = new Calls(st as any, () => 30); + const call = (at: string) => ({ by: "a@b", account: "x", at, members: [], said: true }); + await calls.put("1111111111111111", call("2026-09-01T00:00:00Z"), new Date("2026-09-01T00:00:00Z")); + await calls.put("2222222222222222", call("2026-10-25T00:00:00Z"), new Date("2026-10-25T00:00:00Z")); + await calls.put("3333333333333333", call("2026-11-20T00:00:00Z"), new Date("2026-11-20T00:00:00Z")); + assert.deepEqual([...kv.keys()].sort(), ["call.2222222222222222", "call.3333333333333333"]); + assert.deepEqual((await calls.all()).map((c) => c.call), ["3333333333333333", "2222222222222222"], "newest first"); +}); diff --git a/modules/gitea/test/kept.test.ts b/modules/gitea/test/kept.test.ts index b39114667..d4a1cb604 100644 --- a/modules/gitea/test/kept.test.ts +++ b/modules/gitea/test/kept.test.ts @@ -16,8 +16,8 @@ test("the states the module announces are the states its manifest declares", asy test("the announcement has the layout mesh-sdk's go/announce reads: version 1, the module, the node, the states sorted by name", async () => { const { statesAnnouncement } = await import("../kept.ts"); - assert.deepEqual(statesAnnouncement("gitea", "ace"), { v: 1, module: "gitea", node: "ace", states: [{ name: "announced" }, { name: "bound", readable: true }, { name: "failed-steps" }, { name: "findings", readable: true }, { name: "first-views" }, { name: "idle" }, { name: "transfers" }] }); - assert.deepEqual(statesAnnouncement("gitea", undefined), { v: 1, module: "gitea", states: [{ name: "announced" }, { name: "bound", readable: true }, { name: "failed-steps" }, { name: "findings", readable: true }, { name: "first-views" }, { name: "idle" }, { name: "transfers" }] }); + assert.deepEqual(statesAnnouncement("gitea", "ace"), { v: 1, module: "gitea", node: "ace", states: [{ name: "announced" }, { name: "bound", readable: true }, { name: "calls" }, { name: "failed-steps" }, { name: "findings", readable: true }, { name: "first-views" }, { name: "idle" }, { name: "transfers" }] }); + assert.deepEqual(statesAnnouncement("gitea", undefined), { v: 1, module: "gitea", states: [{ name: "announced" }, { name: "bound", readable: true }, { name: "calls" }, { name: "failed-steps" }, { name: "findings", readable: true }, { name: "first-views" }, { name: "idle" }, { name: "transfers" }] }); }); test("index.ts says the announcement as the event `states` before the tools are served", () => {