gcb-host 0.7.0 → 0.8.0

package/lib/commands/host.js

@@ -2,10 +2,11 @@
  * `host` — the host broker for typed person actions: create, review, reply, edit, run catalogued
  * actions, and fork with the gh account each request names.
  *
- * This runs on the host, beside the checkout the container also sees, and it does exactly one thing:
- * it turns a request file into a pull request, review, reply, pull request edit, catalogued action
- * or fork, using the gh account the request names. That is the whole point — content authored by a person is what automated reviewers will
- * actually review, and the app cannot be that person.
+ * This runs on the host, beside the checkout the container also sees, and it does exactly one
+ * thing: it turns a request file into a pull request, review, reply, pull request edit, catalogued
+ * action or fork, using the gh account the request names. That is the whole point — content
+ * authored by a person is what automated reviewers will actually review, and the app cannot be that
+ * person.
  *
  * It has no other power than the catalogued actions: it cannot push or merge, and it never runs a
  * shell; the program it calls is configuration, and it is called with an argument list built here.
@@ -13,13 +14,12 @@
 import { execFile, spawn } from 'node:child_process';
 import { existsSync, mkdtempSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
-import { StringDecoder } from 'node:string_decoder';
 import { join, resolve } from 'node:path';
+import { StringDecoder } from 'node:string_decoder';
 import { promisify } from 'node:util';
-import { channelDir, clearHostBroker, discoverCheckouts, findGitDir, listRequests, reclaimAbandoned, readHostBroker, claimRequest, removeRequest, requestProblems, writeHostBroker, writeJsonAtomic, readJson, writeResult, PACKAGE_VERSION, canonicalPath, apiBodyJson, HOST, REPOSITORY, ANSWER_TIMEOUT_MS, buildGhArgv, getGhAction, } from 'gcb-core';
-import { fail, listFlag, parseArgs, say, validateArgs, warn } from 'gcb-core';
-import { applyProxyChoice, fetcherFor, parseProxy } from '../http.js';
+import { channelDir, clearHostBroker, discoverCheckouts, findGitDir, listRequests, reclaimAbandoned, readHostBroker, claimRequest, removeRequest, requestProblems, writeHostBroker, writeJsonAtomic, readJson, writeResult, PACKAGE_VERSION, canonicalPath, apiBodyJson, HOST, REPOSITORY, ANSWER_TIMEOUT_MS, buildGhArgv, getGhAction, fail, listFlag, parseArgs, say, validateArgs, warn, } from 'gcb-core';
 import { loadConfig, resolveConfigPath } from '../config.js';
+import { applyProxyChoice, fetcherFor, parseProxy } from '../http.js';
 import { hostConfig, parseAllowEntry, repoAllowed } from '../policy.js';
 import { isForkOfRepository, isPublicRepository } from '../public-repo.js';
 const run = promisify(execFile);
@@ -29,17 +29,20 @@ const CREATE_TIMEOUT_MS = 120_000;
 export function hostStatusPath() {
     return join(homedir(), '.gcb-host', 'status.json');
 }
-/** Per-stream byte budget for a host action, small enough that JSON escaping stays under readResult's cap. */
+/**
+ * Per-stream byte budget for a host action, small enough that JSON escaping stays under
+ * readResult's cap.
+ */
 const HOST_ACTION_OUTPUT_BYTES = 48_000;
 /**
  * Run an action with streaming output caps.
  *
- * execFile's maxBuffer kills the child once a fixed buffer fills; a large diff or log would then be
+ * ExecFile's maxBuffer kills the child once a fixed buffer fills; a large diff or log would then be
  * reported as a gh failure even though only the excess output is unusable. Read both streams to the
  * end, keep the first bytes of each, and tell the caller where the cut is.
  */
 export function runBounded(command, args, options) {
-    return new Promise((resolve) => {
+    return new Promise(resolve => {
         let child;
         try {
             child = spawn(command, [...args], {
@@ -74,10 +77,12 @@ export function runBounded(command, args, options) {
             const limit = stream === 'out' ? outKeep : errKeep;
             const used = stream === 'out' ? outBytes : errBytes;
             if (used >= limit) {
-                if (stream === 'out')
+                if (stream === 'out') {
                     outCut = true;
-                else
+                }
+                else {
                     errCut = true;
+                }
                 return;
             }
             const piece = chunk.subarray(0, limit - used);
@@ -85,19 +90,21 @@ export function runBounded(command, args, options) {
             if (stream === 'out') {
                 out += text;
                 outBytes += piece.length;
-                if (piece.length < chunk.length)
+                if (piece.length < chunk.length) {
                     outCut = true;
+                }
             }
             else {
                 err += text;
                 errBytes += piece.length;
-                if (piece.length < chunk.length)
+                if (piece.length < chunk.length) {
                     errCut = true;
+                }
             }
         };
         child.stdout?.on('data', (chunk) => append(stdout, chunk, 'out'));
         child.stderr?.on('data', (chunk) => append(stderr, chunk, 'err'));
-        child.on('error', (error) => finish({ stdout: out, stderr: err || error.message, code: 1 }));
+        child.on('error', error => finish({ stdout: out, stderr: err || error.message, code: 1 }));
         const timer = setTimeout(() => {
             timedOut = true;
             if (child.pid !== undefined) {
@@ -110,21 +117,26 @@ export function runBounded(command, args, options) {
             }
         }, options.timeoutMs);
         function finish(result) {
-            if (settled)
+            if (settled) {
                 return;
+            }
             settled = true;
             clearTimeout(timer);
             out += stdout.end();
             err += stderr.end();
-            if (outCut)
+            if (outCut) {
                 out += suffix;
-            if (errCut)
+            }
+            if (errCut) {
                 err += suffix;
-            if (err === '' && result.stderr !== '')
+            }
+            if (err === '' && result.stderr !== '') {
                 err = result.stderr;
+            }
             if (timedOut) {
-                if (err !== '' && !err.endsWith('\n'))
+                if (err !== '' && !err.endsWith('\n')) {
                     err += '\n';
+                }
                 err += timeoutNote;
             }
             resolve({ ...result, stdout: out, stderr: err });
@@ -163,24 +175,25 @@ directory, and only the roots this process scans are host-side paths.
 /**
  * Read a pull request's number and URL out of a program's output.
  *
- * `gh pr create` prints the URL, and so does anything that behaves like it. Nothing else is trusted:
- * without a URL in the output the host broker reports a failure rather than guessing.
+ * `gh pr create` prints the URL, and so does anything that behaves like it. Nothing else is
+ * trusted: without a URL in the output the host broker reports a failure rather than guessing.
  *
- * @param output - the program's standard output.
- * @returns the number and URL, or `undefined`.
+ * @param output - The program's standard output.
+ * @returns The number and URL, or `undefined`.
  */
 export function pullRequestUrl(output) {
     const match = /https:\/\/[^\s]+\/pull\/(\d+)/.exec(output);
     const digits = match?.[1];
-    if (!match || digits === undefined)
+    if (!match || digits === undefined) {
         return undefined;
+    }
     return { number: Number(digits), url: match[0] };
 }
 /**
  * Run the `host` command.
  *
- * @param argv - arguments after the command name.
- * @returns the process exit code.
+ * @param argv - Arguments after the command name.
+ * @returns The process exit code.
  */
 export async function runHostBroker(argv) {
     const statusMode = argv[0] === 'status';
@@ -193,14 +206,16 @@ export async function runHostBroker(argv) {
     const explicit = args.value('repo');
     const single = explicit === undefined ? undefined : resolve(explicit);
     const roots = listFlag(args, 'root');
-    const scanned = roots.length > 0 ? roots.map((root) => resolve(root)) : [homedir()];
+    const scanned = roots.length > 0 ? roots.map(root => resolve(root)) : [homedir()];
     const depth = Number(args.value('depth') ?? '4');
     const command = args.value('command') ?? process.env['GCB_HOST_COMMAND'] ?? 'gh';
     const configPath = args.value('config');
     const resolvedConfig = resolveConfigPath(configPath);
     const statusFile = hostStatusPath();
     const startedAt = new Date().toISOString();
-    let loadedConfig = null;
+    // The selected path is what a fork or explicit repository would load; it may not exist yet.
+    const configSelected = Boolean(configPath) || Boolean(process.env['GIT_BROKER_CONFIG']) || existsSync(resolvedConfig);
+    let loadedConfig = configSelected ? resolvedConfig : null;
     /** Remove the status file only when this process owns it. */
     function removeOwnStatus() {
         try {
@@ -218,8 +233,9 @@ export async function runHostBroker(argv) {
     }
     /** Rewrite the host-private status file; the channel marker is not trusted for this. */
     function writeStatus() {
-        if (once)
+        if (once) {
             return;
+        }
         let collision;
         try {
             collision = canonicalPath(resolvedConfig) === canonicalPath(statusFile);
@@ -228,8 +244,9 @@ export async function runHostBroker(argv) {
             warn(`could not compare the config and status paths: ${error.message}`);
             return;
         }
-        if (collision)
+        if (collision) {
             fail('the config cannot be the host status file');
+        }
         try {
             writeJsonAtomic(statusFile, {
                 pid: process.pid,
@@ -248,17 +265,20 @@ export async function runHostBroker(argv) {
     const blockFor = (host) => {
         if (config === undefined) {
             try {
-                config = loadConfig(resolveConfigPath(configPath));
+                config = loadConfig(resolvedConfig);
                 loadedConfig = resolvedConfig;
                 writeStatus();
             }
             catch (error) {
-                throw new Error(`a fork, reply or explicit repository needs the broker config allowlist: ${error.message}; pass --config or set GIT_BROKER_CONFIG`);
+                throw new Error(`a fork, reply or explicit repository needs the broker config allowlist: ${error.message}; pass --config or set GIT_BROKER_CONFIG`, { cause: error });
             }
         }
         return hostConfig(config, host);
     };
-    /** Whether the broker config allowlist permits this host/repository for a fork, reply or explicit repository. */
+    /**
+     * Whether the broker config allowlist permits this host/repository for a fork, reply or explicit
+     * repository.
+     */
     const allowed = (host, repo) => {
         const block = blockFor(host);
         return block !== null && repoAllowed(block.allow, repo);
@@ -273,17 +293,20 @@ export async function runHostBroker(argv) {
     }
     /** The checkouts to serve: one named checkout, or everything under the roots. */
     const targets = () => {
-        if (single === undefined)
-            return scanned.flatMap((root) => discoverCheckouts(root, depth));
+        if (single === undefined) {
+            return scanned.flatMap(root => discoverCheckouts(root, depth));
+        }
         const gitDir = findGitDir(single);
-        if (gitDir === undefined)
+        if (gitDir === undefined) {
             fail(`no git repository at or above ${single}`);
+        }
         return [{ repo: single, dir: channelDir(gitDir) }];
     };
     if (statusMode) {
         validateArgs(args, argv.slice(1), new Set(), 'status');
-        if (args.positionals.length > 0)
+        if (args.positionals.length > 0) {
             fail('status takes no arguments');
+        }
         const parsed = readJson(statusFile);
         if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
             fail('no host broker is running');
@@ -298,8 +321,9 @@ export async function runHostBroker(argv) {
             process.kill(pid, 0);
         }
         catch (error) {
-            if (error.code === 'ESRCH')
+            if (error.code === 'ESRCH') {
                 fail('no host broker is running');
+            }
         }
         const output = {
             pid,
@@ -332,8 +356,9 @@ export async function runHostBroker(argv) {
         removeOwnStatus();
         for (const dir of advertised) {
             try {
-                if (readHostBroker(dir)?.pid === process.pid)
+                if (readHostBroker(dir)?.pid === process.pid) {
                     clearHostBroker(dir);
+                }
             }
             catch {
                 // Nothing useful is left to do while exiting.
@@ -343,7 +368,9 @@ export async function runHostBroker(argv) {
     const stop = () => process.exit(0);
     process.on('SIGINT', stop);
     process.on('SIGTERM', stop);
-    say(single === undefined ? `serving the checkouts under ${scanned.join(', ')}` : `serving ${single}`);
+    say(single === undefined
+        ? `serving the checkouts under ${scanned.join(', ')}`
+        : `serving ${single}`);
     say(`creating pull requests, issues, reviews, replies and forks with ${command}${extra.length > 0 ? ` ${extra.join(' ')}` : ''}, as the request's account or this user`);
     for (;;) {
         for (const { repo, dir } of targets()) {
@@ -357,19 +384,20 @@ export async function runHostBroker(argv) {
                 warn(`could not serve ${repo}: ${error.message}`);
             }
         }
-        if (once)
+        if (once) {
             return 0;
-        await new Promise((done) => setTimeout(done, Math.max(interval, 0) * 1000));
+        }
+        await new Promise(done => setTimeout(done, Math.max(interval, 0) * 1000));
     }
 }
 /**
  * Answer everything waiting in the channel.
  *
- * @param dir - the channel directory.
- * @param repo - the checkout to create pull requests or issues in.
- * @param command - the program to call.
- * @param extra - arguments to pass before the subcommand.
- * @returns how many requests were answered.
+ * @param dir - The channel directory.
+ * @param repo - The checkout to create pull requests or issues in.
+ * @param command - The program to call.
+ * @param extra - Arguments to pass before the subcommand.
+ * @returns How many requests were answered.
  */
 async function sweep(dir, repo, command, extra, allowed, blockFor) {
     let answered = 0;
@@ -422,20 +450,7 @@ async function sweep(dir, repo, command, extra, allowed, blockFor) {
         const result = await openOne(repo, command, extra, { ...request, proxy }, allowed, blockFor);
         writeResult(dir, id, result);
         removeRequest(dir, id);
-        if (result.error !== undefined) {
-            warn(`failed to open ${request.kind === 'fork'
-                ? 'fork'
-                : request.kind === 'reply'
-                    ? `reply on #${request.number}`
-                    : request.kind === 'review'
-                        ? `review on #${request.number}`
-                        : request.kind === 'edit'
-                            ? `edit on #${request.number}`
-                            : request.kind === 'action'
-                                ? request.action
-                                : request.head}: ${result.error}`);
-        }
-        else {
+        if (result.error === undefined) {
             say(request.kind === 'fork'
                 ? `forked ${request.repo} as ${request.account ?? 'this user'}: ${result.url}`
                 : request.kind === 'reply'
@@ -448,6 +463,19 @@ async function sweep(dir, repo, command, extra, allowed, blockFor) {
                                 ? `ran ${request.action} as ${request.account ?? 'this user'}`
                                 : `opened #${result.number} as ${request.account ?? 'this user'}: ${result.url}`);
         }
+        else {
+            warn(`failed to open ${request.kind === 'fork'
+                ? 'fork'
+                : request.kind === 'reply'
+                    ? `reply on #${request.number}`
+                    : request.kind === 'review'
+                        ? `review on #${request.number}`
+                        : request.kind === 'edit'
+                            ? `edit on #${request.number}`
+                            : request.kind === 'action'
+                                ? request.action
+                                : request.head}: ${result.error}`);
+        }
         answered += 1;
     }
     return answered;
@@ -480,32 +508,37 @@ function hostEnv(proxy, account) {
 }
 /** Unauthenticated public-repository check for the host route. */
 async function repoIsPublic(host, repository, proxy, apiBaseUrl, apiVersion = '2022-11-28') {
-    const base = apiBaseUrl ?? (host.toLowerCase() === 'github.com' ? 'https://api.github.com' : `https://${host}/api/v3`);
+    const base = apiBaseUrl ??
+        (host.toLowerCase() === 'github.com' ? 'https://api.github.com' : `https://${host}/api/v3`);
     return isPublicRepository(fetcherFor(proxy), base, repository, apiVersion);
 }
 /**
  * Whether an allowlisted fork's parent is the requested repository.
  *
- * @param host - the forge host.
- * @param allow - the configured allowlist entries.
- * @param repository - the requested parent repository.
- * @param proxy - the proxy choice for the check.
- * @param apiBaseUrl - an optional API base.
- * @param apiVersion - the API version header.
- * @returns true when one allowlisted fork names the repository as its parent.
+ * @param host - The forge host.
+ * @param allow - The configured allowlist entries.
+ * @param repository - The requested parent repository.
+ * @param proxy - The proxy choice for the check.
+ * @param apiBaseUrl - An optional API base.
+ * @param apiVersion - The API version header.
+ * @returns True when one allowlisted fork names the repository as its parent.
  */
 async function forkAllows(host, allow, repository, proxy, apiBaseUrl, apiVersion = '2022-11-28') {
-    const base = apiBaseUrl ?? (host.toLowerCase() === 'github.com' ? 'https://api.github.com' : `https://${host}/api/v3`);
+    const base = apiBaseUrl ??
+        (host.toLowerCase() === 'github.com' ? 'https://api.github.com' : `https://${host}/api/v3`);
     for (const raw of allow) {
         const entry = parseAllowEntry(raw);
-        if (!entry || entry.owner === '*' || entry.repo === '*')
+        if (!entry || entry.owner === '*' || entry.repo === '*') {
             continue;
+        }
         const fork = `${entry.owner}/${entry.repo}`;
-        if (fork === repository.toLowerCase())
+        if (fork === repository.toLowerCase()) {
             continue;
+        }
         try {
-            if (await isForkOfRepository(fetcherFor(proxy), base, fork, repository, apiVersion))
+            if (await isForkOfRepository(fetcherFor(proxy), base, fork, repository, apiVersion)) {
                 return true;
+            }
         }
         catch {
             // A failed check is not evidence of a relationship; keep looking, then fail closed.
@@ -514,14 +547,16 @@ async function forkAllows(host, allow, repository, proxy, apiBaseUrl, apiVersion
     return false;
 }
 /**
- * Run one person operation: check the allowlist, then call the program and turn its failure into a result.
+ * Run one person operation: check the allowlist, then call the program and turn its failure into a
+ * result.
  *
  * The typed routes differ only in the argv they build, so the check and the catch live here once
  * instead of being copied per route.
  */
 async function personRun(host, repository, allowed, work) {
-    if (!HOST.test(host))
+    if (!HOST.test(host)) {
         return { error: `not a host: ${JSON.stringify(host)}` };
+    }
     try {
         if (!allowed(host, repository)) {
             return { error: `repository ${repository} is not in the allowlist for ${host}` };
@@ -554,11 +589,11 @@ async function withBodyFile(body, work, name = 'body.md') {
 /**
  * Create one pull request, issue, review, reply, edit or comment.
  *
- * @param repo - the checkout to run it in.
- * @param command - the program to call.
- * @param extra - arguments to pass before the subcommand.
- * @param request - what to do.
- * @returns the number and URL, or the reason it did not work.
+ * @param repo - The checkout to run it in.
+ * @param command - The program to call.
+ * @param extra - Arguments to pass before the subcommand.
+ * @param request - What to do.
+ * @returns The number and URL, or the reason it did not work.
  */
 async function openOne(repo, command, extra, request, allowed, blockFor) {
     if (request.kind === 'fork') {
@@ -582,15 +617,18 @@ async function openOne(repo, command, extra, request, allowed, blockFor) {
                 env: forkEnv(request.proxy, request.account, host),
             });
             const match = /https:\/\/[^\s]+\/[^\s/]+\/[^\s/]+/.exec(stdout);
-            if (match?.[0] !== undefined)
+            if (match?.[0] !== undefined) {
                 return { url: match[0] };
+            }
             // With no TTY, gh prints the URL only for a fresh fork; an existing fork older than a minute
             // is `owner/name already exists` on stderr with empty stdout and exit 0.
             const existing = /^([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+) already exists$/m.exec(stderr);
             if (existing?.[1] !== undefined) {
                 return { url: `https://${host}/${existing[1]}` };
             }
-            return { error: `no fork URL in the output: ${(stdout.trim() || stderr.trim()).slice(0, 300)}` };
+            return {
+                error: `no fork URL in the output: ${(stdout.trim() || stderr.trim()).slice(0, 300)}`,
+            };
         }
         catch (error) {
             const failure = error;
@@ -626,7 +664,13 @@ async function openOne(repo, command, extra, request, allowed, blockFor) {
                 if (!Number.isSafeInteger(number) || number <= 0) {
                     return { error: `${String(number)} is not an issue number` };
                 }
-                const probe = await runBounded(command, [...extra, 'api', `repos/${request.repo}/issues/${String(number)}`, '--jq', '.pull_request != null'], {
+                const probe = await runBounded(command, [
+                    ...extra,
+                    'api',
+                    `repos/${request.repo}/issues/${String(number)}`,
+                    '--jq',
+                    '.pull_request != null',
+                ], {
                     cwd: repo,
                     env,
                     timeoutMs: Math.max(1, deadline - Date.now()),
@@ -645,12 +689,13 @@ async function openOne(repo, command, extra, request, allowed, blockFor) {
                     cwd: repo,
                     env,
                     timeoutMs: Math.max(1, deadline - Date.now()),
-                    writeCaveat: Object.values(action.permissions).some((permission) => permission === 'write'),
+                    writeCaveat: Object.values(action.permissions).some(permission => permission === 'write'),
                 });
                 return result;
             };
-            if (body === undefined)
+            if (body === undefined) {
                 return invoke();
+            }
             if (action.api?.jsonBody === true) {
                 return withBodyFile(apiBodyJson(body), invoke, 'body.json');
             }
@@ -722,7 +767,9 @@ async function openOne(repo, command, extra, request, allowed, blockFor) {
             }
             const reply = (answer ?? {});
             if (typeof reply.html_url !== 'string' || reply.html_url === '') {
-                return { error: `no reply URL in the output: ${(stdout.trim() || stderr.trim()).slice(0, 300)}` };
+                return {
+                    error: `no reply URL in the output: ${(stdout.trim() || stderr.trim()).slice(0, 300)}`,
+                };
             }
             return { number: request.number, url: reply.html_url };
         });
@@ -773,7 +820,9 @@ async function openOne(repo, command, extra, request, allowed, blockFor) {
                 env: forkEnv(request.proxy, request.account, host),
             }).then(({ stdout }) => {
                 const match = /https:\/\/[^\s]+\/pull\/\d+(?:#pullrequestreview-\d+)?/.exec(stdout);
-                return match?.[0] === undefined ? { number: request.number } : { number: request.number, url: match[0] };
+                return match?.[0] === undefined
+                    ? { number: request.number }
+                    : { number: request.number, url: match[0] };
             });
             return request.body.trim() === '' ? invoke() : withBodyFile(request.body, invoke);
         });
@@ -782,8 +831,9 @@ async function openOne(repo, command, extra, request, allowed, blockFor) {
     // repository this machine has no checkout of. Without one, gh still resolves the checkout.
     const target = request.repo;
     if (target !== undefined) {
-        if (!REPOSITORY.test(target))
+        if (!REPOSITORY.test(target)) {
             return { error: `not a repository: ${JSON.stringify(target)}` };
+        }
         try {
             if (!allowed('github.com', target)) {
                 return { error: `repository ${target} is not in the allowlist for github.com` };
@@ -804,7 +854,10 @@ async function openOne(repo, command, extra, request, allowed, blockFor) {
                 // above is the boundary, and no checkout of the target is required.
                 ...(request.draft === true ? ['--draft'] : []),
                 ...(target === undefined ? [] : ['--repo', target]),
-                '--base', request.base, '--head', request.head,
+                '--base',
+                request.base,
+                '--head',
+                request.head,
                 `--title=${request.title}`,
                 '--body-file',
                 bodyFile,
@@ -818,7 +871,9 @@ async function openOne(repo, command, extra, request, allowed, blockFor) {
             });
             const found = pullRequestUrl(stdout);
             if (!found) {
-                return { error: `no pull request URL in the output: ${(stdout.trim() || stderr.trim()).slice(0, 300)}` };
+                return {
+                    error: `no pull request URL in the output: ${(stdout.trim() || stderr.trim()).slice(0, 300)}`,
+                };
             }
             return found;
         });