@bakers-build/addon-forge 0.10.0 → 0.10.1-next.1

package/dist/src/backend.d.ts

@@ -15,6 +15,13 @@ export interface ForgeCheck {
     readonly status: CheckStatus;
     /** Required by the base branch's rules (GitHub) or not allowed to fail (GitLab). */
     readonly required: boolean;
+    /** The forge's own verdict (`cancelled`, `skipped`, `timed_out`, ...); null while running. */
+    readonly conclusion: string | null;
+    /** GitHub Actions run / GitLab pipeline; null for a commit status. */
+    readonly run_id: number | null;
+    /** The id `forge_job_log` reads; null when the row is no job. */
+    readonly job_id: number | null;
+    readonly run_started_at: string | null;
 }
 export interface ForgeMerge {
     readonly method: 'squash' | 'merge';
@@ -35,18 +42,33 @@ export interface ForgeBackend {
         title: string;
         body: string;
     }): Promise<ForgePr>;
+    /** Also retargets the PR to `base`, which may have moved since it opened. */
     updatePr(pr: ForgePr, input: {
         title: string;
         body: string;
+        base: string;
     }): Promise<ForgePr>;
     openPrsWithBase(base: string): Promise<ForgePr[]>;
-    /** Checks on `ref` (a SHA or branch), `required` as `base`'s rules say. */
-    checks(ref: string, base: string): Promise<ForgeCheck[]>;
+    /**
+     * Checks on `ref` (a SHA or branch), `required` as `base`'s rules say. Only
+     * the newest run per workflow unless `allRuns`, where the forge has several.
+     */
+    checks(ref: string, base: string, opts?: {
+        allRuns?: boolean;
+    }): Promise<ForgeCheck[]>;
     /** A conflict or a not yet computed mergeability is a reason. */
     mergeBlocker(pr: ForgePr): Promise<string | undefined>;
     /** Merges with every option sent explicitly; deletes the source when asked. */
     merge(pr: ForgePr, options: ForgeMerge): Promise<void>;
     isMerged(pr: ForgePr): Promise<boolean>;
+    /** The [tail] of a job's log; refuses a job outside the repository. */
+    jobLog(jobId: number, maxBytes: number): Promise<LogTail>;
+}
+export interface LogTail {
+    readonly text: string;
+    /** The whole log's size. */
+    readonly bytes: number;
+    readonly truncated: boolean;
 }
 export type ForgeBackendFactory = (settings: unknown, context: {
     readonly home: string;
@@ -60,7 +82,16 @@ export declare function assertForgeBackend(value: unknown, spec: string): assert
  * Every value read is pushed to `seen`, for the backend's `secrets()`.
  */
 export declare function cliToken(cmd: string, args: string[], seen: string[]): () => Promise<string>;
+/** Text over HTTP for backends: throws status and body text on failure. */
+export declare function requestText(doFetch: typeof fetch, url: string, init: RequestInit & {
+    allow404?: boolean;
+}): Promise<string | undefined>;
 /** JSON over HTTP for backends: throws status and body text on failure. */
 export declare function requestJson(doFetch: typeof fetch, url: string, init: RequestInit & {
     allow404?: boolean;
 }): Promise<unknown>;
+/**
+ * The last `maxBytes` bytes of `log`, from the first whole line in them; when
+ * the last line alone is longer, from the first whole character.
+ */
+export declare function tail(log: string, maxBytes: number): LogTail;

package/dist/src/backend.js

@@ -14,6 +14,7 @@ const METHODS = [
     'mergeBlocker',
     'merge',
     'isMerged',
+    'jobLog',
 ];
 /** Reject a factory result that is not a `ForgeBackend`. */
 export function assertForgeBackend(value, spec) {
@@ -44,13 +45,39 @@ export function cliToken(cmd, args, seen) {
         return value;
     };
 }
-/** JSON over HTTP for backends: throws status and body text on failure. */
-export async function requestJson(doFetch, url, init) {
+/** Text over HTTP for backends: throws status and body text on failure. */
+export async function requestText(doFetch, url, init) {
     const res = await doFetch(url, init);
     if (res.status === 404 && init.allow404)
         return undefined;
     const text = await res.text();
     if (!res.ok)
         throw new Error(`${init.method ?? 'GET'} ${new URL(url).pathname} answered ${res.status}: ${text.slice(0, 500)}`);
+    return text;
+}
+/** JSON over HTTP for backends: throws status and body text on failure. */
+export async function requestJson(doFetch, url, init) {
+    const text = await requestText(doFetch, url, init);
     return text ? JSON.parse(text) : undefined;
 }
+/**
+ * The last `maxBytes` bytes of `log`, from the first whole line in them; when
+ * the last line alone is longer, from the first whole character.
+ */
+export function tail(log, maxBytes) {
+    const buf = Buffer.from(log);
+    if (buf.length <= maxBytes)
+        return { text: log, bytes: buf.length, truncated: false };
+    let start = buf.length - maxBytes;
+    const newline = buf.indexOf(0x0a, start - 1);
+    if (newline !== -1 && newline < buf.length - 1)
+        start = newline + 1;
+    else
+        while (start < buf.length && (buf.readUInt8(start) & 0xc0) === 0x80)
+            start++;
+    return {
+        text: buf.subarray(start).toString(),
+        bytes: buf.length,
+        truncated: true,
+    };
+}

package/dist/src/preset.js

@@ -1,4 +1,4 @@
-// The forge addon: five conductor tools a sandboxed run delivers through,
+// The forge addon: six conductor tools a sandboxed run delivers through,
 // while the token stays with the conductor. Without a forge entry no tool is
 // served and runs deliver as before.
 import { FORGE_TOOL_DEFINITIONS } from './tool-definitions.js';

package/dist/src/tool-definitions.js

@@ -42,17 +42,36 @@ export const FORGE_TOOL_DEFINITIONS = {
         },
     },
     forge_checks: {
-        description: "Status of each check or pipeline job, and whether it is required, on the head of an owned branch's PR/MR, or on any `ref` (branch or SHA); read only, one shot.",
+        description: "Status of each check or pipeline job on the head of an owned branch's PR/MR, or on any `ref` (branch or SHA); read only, one shot. Each row: status, required, the forge's raw conclusion (cancelled, skipped, timed_out, ...), run_id, job_id (for forge_job_log), run_started_at. overall is success only when every required check (flagged, or named required) is green; else failure, pending or no_required_checks.",
         input: {
             type: 'object',
             properties: {
                 branch,
                 ref: { type: 'string', description: 'any branch or SHA, read only' },
+                all_runs: {
+                    type: 'boolean',
+                    description: 'every run on the commit; default: only the newest run per workflow',
+                },
+            },
+        },
+    },
+    forge_job_log: {
+        description: "The end of one job's log, by a job_id from forge_checks, read with the conductor's token; read only. Starts at a whole line; truncated says whether earlier lines were cut.",
+        input: {
+            type: 'object',
+            properties: {
+                job_id: { type: 'integer', minimum: 1 },
+                max_bytes: {
+                    type: 'integer',
+                    minimum: 1,
+                    description: 'bytes from the end; default 16384, at most 262144',
+                },
             },
+            required: ['job_id'],
         },
     },
     forge_merge: {
-        description: "Merge the open PR/MR of an owned branch into its base, once it is conflict free and every required check is green. Human approval is the workflow's merge gate, not this tool's.",
+        description: "Merge the open PR/MR of an owned branch into its base, once it is conflict free and overall is success. Human approval is the workflow's merge gate, not this tool's.",
         input: { type: 'object', properties: { branch } },
     },
 };

package/dist/src/tools.d.ts

@@ -6,8 +6,13 @@ export interface ForgeToolDeps {
     /** The forge entry's `with` (merge rules). */
     settings: unknown;
 }
-/** Failure first, then pending, over the required checks. */
-export declare function overall(checks: readonly ForgeCheck[]): ForgeCheck['status'];
+export declare const LOG_DEFAULT_BYTES = 16384;
+export declare const LOG_MAX_BYTES = 262144;
+export type Overall = 'success' | 'failure' | 'pending' | 'no_required_checks';
+/** Required by the forge, or the aggregate check a workflow names `required`. */
+export declare const isRequired: (c: ForgeCheck) => boolean;
+/** Failure first, then pending, over the required checks; none required is never green. */
+export declare function overall(checks: readonly ForgeCheck[]): Overall;
 export declare function forgeTools(deps: ForgeToolDeps): Record<string, ToolHandler>;
 /** The live tools for the conductor's effective forge entry `with`. */
 export declare function toolsFor(options: unknown): Record<string, ToolHandler>;

package/dist/src/tools.js

@@ -17,19 +17,45 @@ function runOf(req) {
         ...(t.targetBranch ? { targetBranch: t.targetBranch } : {}),
     };
 }
+/**
+ * Where `branch` merges: a variant into the ticket branch, the ticket branch into
+ * the ticket's current target as the server returns it now. A failed read refuses;
+ * the run copy may predate an environment added during the run.
+ */
+async function currentBase(req, branch, run) {
+    if (branch !== run.branchName)
+        return derivedBase(branch, run);
+    const refuse = (why) => new Error(`forge: the ticket's current target_branch could not be read from the server (${why}); nothing was sent`);
+    if (!req.currentTicket)
+        throw refuse('no server read for this call');
+    const t = await req.currentTicket().catch((err) => {
+        throw refuse(err instanceof Error ? err.message : String(err));
+    });
+    const target = t.targetBranch ?? t.baseBranch;
+    if (!target)
+        throw refuse('no target_branch or base_branch returned');
+    return target;
+}
 function ownedBranch(req, run) {
     const branch = req.args.branch ?? run.branchName;
     if (!isOwned(branch, run.branchName))
         throw new Error(ownershipRefusal(branch, run.branchName));
     return branch;
 }
+export const LOG_DEFAULT_BYTES = 16_384;
+export const LOG_MAX_BYTES = 262_144;
 const json = (value) => ({
     text: JSON.stringify(value, null, 2),
 });
-/** Failure first, then pending, over the required checks. */
+/** Required by the forge, or the aggregate check a workflow names `required`. */
+export const isRequired = (c) => c.required || c.name === 'required';
+const isRed = (c) => c.status === 'failure' || c.conclusion === 'skipped';
+/** Failure first, then pending, over the required checks; none required is never green. */
 export function overall(checks) {
-    const required = checks.filter((c) => c.required);
-    if (required.some((c) => c.status === 'failure'))
+    const required = checks.filter(isRequired);
+    if (required.length === 0)
+        return 'no_required_checks';
+    if (required.some(isRed))
         return 'failure';
     if (required.some((c) => c.status !== 'success'))
         return 'pending';
@@ -91,13 +117,14 @@ export function forgeTools(deps) {
             const run = runOf(req);
             const branch = ownedBranch(req, run);
             const body = req.args.body ?? '';
+            const base = await currentBase(req, branch, run);
             const b = await backend();
             const open = await b.findOpenPr(branch);
             const pr = open
-                ? await b.updatePr(open, { title, body })
+                ? await b.updatePr(open, { title, body, base })
                 : await b.createPr({
                     head: branch,
-                    base: derivedBase(branch, run),
+                    base,
                     title,
                     body,
                 });
@@ -122,13 +149,15 @@ export function forgeTools(deps) {
                 ref = pr?.headSha ?? branch;
                 base = pr?.base ?? derivedBase(branch, run);
             }
-            const checks = await b.checks(ref, base);
+            const checks = await b.checks(ref, base, {
+                allRuns: req.args.all_runs === true,
+            });
             return json({ ref, base, overall: overall(checks), checks });
         },
         forge_merge: async (req) => {
             const run = runOf(req);
             const branch = ownedBranch(req, run);
-            const base = derivedBase(branch, run);
+            const base = await currentBase(req, branch, run);
             const b = await backend();
             const pr = await b.findOpenPr(branch);
             if (!pr)
@@ -141,9 +170,11 @@ export function forgeTools(deps) {
             if (blocker)
                 throw new Error(`PR/MR ${pr.url} cannot merge: ${blocker}`);
             const checks = await b.checks(pr.headSha, pr.base);
-            const notGreen = checks.filter((c) => c.required && c.status !== 'success');
+            if (overall(checks) === 'no_required_checks')
+                throw new Error(`PR/MR ${pr.url} cannot merge: no required checks reported`);
+            const notGreen = checks.filter((c) => isRequired(c) && (isRed(c) || c.status !== 'success'));
             if (notGreen.length > 0)
-                throw new Error(`PR/MR ${pr.url} has required checks that are not green: ${notGreen.map((c) => `${c.name} (${c.status})`).join(', ')}`);
+                throw new Error(`PR/MR ${pr.url} has required checks that are not green: ${notGreen.map((c) => `${c.name} (${c.conclusion ?? c.status})`).join(', ')}`);
             const rule = mergeRule(deps.settings, base);
             const dependents = (await b.openPrsWithBase(branch)).filter((p) => p.number !== pr.number);
             const deleteSource = rule.delete_source && dependents.length === 0;
@@ -166,6 +197,24 @@ export function forgeTools(deps) {
                     : {}),
             });
         },
+        forge_job_log: async (req) => {
+            runOf(req);
+            const jobId = req.args.job_id;
+            if (typeof jobId !== 'number' || !Number.isInteger(jobId) || jobId <= 0)
+                throw new Error('job_id must be a job_id from forge_checks');
+            const asked = req.args.max_bytes;
+            const maxBytes = typeof asked === 'number' && asked >= 1
+                ? Math.min(Math.floor(asked), LOG_MAX_BYTES)
+                : LOG_DEFAULT_BYTES;
+            const log = await (await backend()).jobLog(jobId, maxBytes);
+            return json({
+                job_id: jobId,
+                bytes: log.bytes,
+                truncated: log.truncated,
+                max_bytes: maxBytes,
+                log: log.text,
+            });
+        },
     };
     return Object.fromEntries(Object.entries(tools).map(([n, h]) => [n, guarded(h)]));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bakers-build/addon-forge",
-  "version": "0.10.0",
+  "version": "0.10.1-next.1",
   "description": "bakers.build forge tools: a sandboxed run fetches, pushes its own branches, opens its PR/MR, reads checks and merges through the conductor, which holds the token. Backends implement the ForgeBackend contract (./backend).",
   "type": "module",
   "license": "MIT",
@@ -22,11 +22,11 @@
     "directory": "bakers-cli/addons/forge"
   },
   "peerDependencies": {
-    "@bakers-build/conductor": "^0.10.0",
-    "@bakers-build/core": "^0.10.0"
+    "@bakers-build/conductor": "^0.10.1-next.1",
+    "@bakers-build/core": "^0.10.1-next.1"
   },
   "bakersBuild": {
-    "commit": "5857b00008bc0926fd52fdc8d9366d6d52444e35",
-    "channel": "latest"
+    "commit": "f9cee7721df536cac94906e7278d60a13e202502",
+    "channel": "next"
   }
 }