@opsee/cli 0.11.9

package/src/foreman/process-group.ts

@@ -0,0 +1,160 @@
+import { execFileSync, type ChildProcess } from "node:child_process";
+
+/**
+ * Stopping a child and everything it started. Both the Run Recipe (an app under a `make` or `bun
+ * run` wrapper) and the Worker Adapters (a coding agent running shells) spawn their child in its
+ * own process group (`detached: true`, everywhere but Windows) so that a stop reaches the whole
+ * group: SIGTERM first, SIGKILL to whatever is still there after a grace period.
+ */
+
+/** Whether children are put in their own process group on this platform. */
+export const PROCESS_GROUPS = process.platform !== "win32";
+
+/** Signals the child's whole process group, or the child alone where groups are unavailable or the
+ * group is already gone. */
+export function signalProcessGroup(child: ChildProcess, signal: NodeJS.Signals): void {
+  const pid = child.pid;
+  try {
+    if (PROCESS_GROUPS && pid !== undefined) process.kill(-pid, signal);
+    else child.kill(signal);
+  } catch {
+    try {
+      child.kill(signal);
+    } catch {
+      // Already gone.
+    }
+  }
+}
+
+/** Whether anything in the child's process group is still alive: the shell may be gone while the
+ * server it started is still shutting down or ignored the signal. `childDone` is the caller's
+ * knowledge that the child itself has exited, for platforms without groups. */
+export function processGroupAlive(child: ChildProcess, childDone: boolean): boolean {
+  const pid = child.pid;
+  if (pid === undefined || !PROCESS_GROUPS) return !childDone;
+  try {
+    process.kill(-pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * SIGTERM to the group, SIGKILL to whatever is still in it after `graceMs`, then wait for the
+ * child's own exit (`exited`, which must never reject). Resolves once the group is gone.
+ */
+export async function stopProcessGroup(child: ChildProcess, exited: Promise<unknown>, graceMs: number, isDone: () => boolean): Promise<void> {
+  const deadline = Date.now() + graceMs;
+  if (!isDone()) signalProcessGroup(child, "SIGTERM");
+  while (processGroupAlive(child, isDone()) && Date.now() < deadline) await sleep(50);
+  if (processGroupAlive(child, isDone())) signalProcessGroup(child, "SIGKILL");
+  await exited;
+}
+
+/** A stop by pid that could not be carried out safely; nothing was signalled, or the process
+ * outlived SIGKILL. The caller reports it and leaves the Process Table as it was. */
+export class StopRefusedError extends Error {}
+
+/** What `ps` says about a process, for telling a Worker from a recycled pid. */
+export interface ProcessIdentity {
+  /** The process group id; a Worker is spawned detached, so its own pid. */
+  pgid: number;
+  /** When the process started, epoch milliseconds; undefined when `ps` printed nothing parseable. */
+  startedAt?: number;
+}
+
+export interface StopByPidOptions {
+  /** When the Process Table row was created (`WorkerRow.startedAt`): a process that started before
+   * it cannot be the Worker the row is about. */
+  startedAt?: number;
+  /** How long the pid may take to disappear after SIGKILL before the stop is given up as refused;
+   * `graceMs` by default. */
+  killWaitMs?: number;
+  /** Test seams: the signal (or probe, with signal 0) and the identity lookup. */
+  kill?: (pid: number, signal: NodeJS.Signals | 0) => void;
+  identity?: (pid: number) => ProcessIdentity | undefined;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+/** `ps -o pgid=,lstart= -p <pid>`: the group id and the start time, or undefined when the process
+ * is gone (ps exits non-zero) or the platform has no ps. */
+export function processIdentity(pid: number): ProcessIdentity | undefined {
+  let text: string;
+  try {
+    text = execFileSync("ps", ["-o", "pgid=,lstart=", "-p", String(pid)], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+  } catch {
+    return undefined;
+  }
+  const line = text.trim().split("\n")[0]?.trim() ?? "";
+  const match = /^(\d+)\s*(.*)$/.exec(line);
+  if (!match) return undefined;
+  const started = new Date(match[2].trim().replace(/\s+/g, " ")).getTime();
+  return { pgid: Number(match[1]), startedAt: Number.isNaN(started) ? undefined : started };
+}
+
+/**
+ * Stops a Worker this process does not own, by the pid the Process Table recorded (`foreman
+ * attach` and `cancel` run in another process than the daemon): SIGTERM to its process group,
+ * SIGKILL to what is still there after `graceMs`, then wait until the pid is gone. Resolves false
+ * when there was nothing alive to stop.
+ *
+ * A pid is only a name, and the OS reuses names: before anything is signalled the process must
+ * still look like the Worker (its own group leader, since Workers are spawned detached, and not
+ * started before the row was), else it is a stranger wearing a dead Worker's pid, the Worker is
+ * gone, and this resolves false without signalling; the caller forgets the pid either way. A pid
+ * this user may not signal (EPERM: another user's process) is refused outright rather than waited
+ * on, since `kill -0` would report it alive forever; so is a pid that is still there `killWaitMs`
+ * after SIGKILL.
+ */
+export async function stopProcessByPid(pid: number, graceMs: number, options: StopByPidOptions = {}): Promise<boolean> {
+  const kill = options.kill ?? ((target, signal) => process.kill(target, signal));
+  const identity: (pid: number) => ProcessIdentity | undefined = options.identity ?? (PROCESS_GROUPS ? processIdentity : () => ({ pgid: pid }));
+  const pause = options.sleep ?? sleep;
+  const alive = (): boolean => {
+    try {
+      kill(pid, 0);
+      return true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "EPERM") {
+        throw new StopRefusedError(`pid ${pid} belongs to another user, so it cannot be the Worker (its pid was reused after the Worker died); nothing was signalled`);
+      }
+      return false;
+    }
+  };
+  if (!alive()) return false;
+  const who = identity(pid);
+  if (!who) return false;
+  // Not a group leader, or older than the row: not the Worker, whose pid the OS has handed on.
+  if (who.pgid !== pid) return false;
+  if (options.startedAt !== undefined && who.startedAt !== undefined && who.startedAt < options.startedAt - START_SLACK_MS) return false;
+  const signal = (sig: NodeJS.Signals) => {
+    try {
+      if (PROCESS_GROUPS) kill(-pid, sig);
+      else kill(pid, sig);
+    } catch {
+      try {
+        kill(pid, sig);
+      } catch {
+        // Already gone.
+      }
+    }
+  };
+  const graceDeadline = Date.now() + graceMs;
+  signal("SIGTERM");
+  while (alive() && Date.now() < graceDeadline) await pause(50);
+  if (!alive()) return true;
+  signal("SIGKILL");
+  const killDeadline = Date.now() + (options.killWaitMs ?? graceMs);
+  while (alive() && Date.now() < killDeadline) await pause(50);
+  if (alive()) throw new StopRefusedError(`pid ${pid} is still there ${options.killWaitMs ?? graceMs}ms after SIGKILL; the Worker could not be stopped`);
+  return true;
+}
+
+/** `ps` prints start times to the second, and the row's clock and the kernel's need not agree
+ * exactly, so a process may look a little older than its row. */
+const START_SLACK_MS = 60_000;
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/foreman/remote-api.ts

@@ -0,0 +1,283 @@
+/**
+ * Remote API seam: the little the Hand-off (see ../CONTEXT.md, ADR-0003) needs from the code host,
+ * which is to find, open and update one draft pull request for a branch. Nothing here can merge:
+ * the interface has no such method, and foreman-remote-api.test.ts checks that at compile time,
+ * so "the Foreman never merges" (story 26) is a shape, not a promise.
+ *
+ * Two implementations, both through the user's own CLI so the Foreman never holds a token of its
+ * own: GitLab through `glab api` and GitHub through `gh api`, chosen from the origin URL. The one
+ * write beyond the pull request itself is a comment on it, where the Gates report (OPS-271).
+ */
+import { execToString } from "./core/exec.js";
+
+export interface RemotePullRequest {
+  /** The number a human sees (GitLab's iid, GitHub's number). */
+  number: number;
+  url: string;
+  title: string;
+  draft: boolean;
+  headBranch: string;
+  baseBranch: string;
+}
+
+export interface NewPullRequest {
+  headBranch: string;
+  baseBranch: string;
+  title: string;
+  body: string;
+}
+
+/** What a later Hand-off on the same branch rewrites. */
+export type PullRequestPatch = Pick<NewPullRequest, "title" | "body">;
+
+export interface RemoteApi {
+  /** The open pull request from `headBranch`, if there is one. */
+  findPullRequest(headBranch: string): Promise<RemotePullRequest | undefined>;
+  /** The open pull request titled exactly `title` (a draft marker the host adds aside), if there
+   * is one: how the learnings pull request of an Initiative is found again across Runs, since its
+   * branch carries a timestamp (core/learnings.ts). */
+  findPullRequestByTitle(title: string): Promise<RemotePullRequest | undefined>;
+  openDraftPullRequest(input: NewPullRequest): Promise<RemotePullRequest>;
+  updatePullRequest(number: number, patch: PullRequestPatch): Promise<RemotePullRequest>;
+  /** A comment (GitLab: a note) on the pull request's thread: where the Gates' summary and the
+   * Verdict go. */
+  addPullRequestComment(number: number, body: string): Promise<void>;
+  /** Puts a file (a Verifier's screenshot) where a comment on the pull request can show it, and
+   * returns the markdown that embeds it; undefined when the host has no way to (GitHub has no
+   * upload for issue comments), in which case the caller says where the file is kept instead. */
+  uploadAttachment(number: number, filePath: string): Promise<Attachment | undefined>;
+}
+
+/** An uploaded file as the host hands it back. */
+export interface Attachment {
+  url: string;
+  /** What to put in a comment body to show it: `![name](url)` for an image. */
+  markdown: string;
+}
+
+export type RemoteProvider = "gitlab" | "github";
+
+export interface ParsedRemote {
+  provider: RemoteProvider | undefined;
+  host: string;
+  /** `group/subgroup/repo` or `owner/repo`, without `.git`. */
+  fullName: string;
+}
+
+/** Reads host and project path out of the usual remote URL forms; undefined for a local path. */
+export function parseRemoteUrl(url: string): ParsedRemote | undefined {
+  let host: string | undefined;
+  let path: string | undefined;
+  const scp = /^(?:[^@/]+@)?([^:/]+):(?!\/\/)(.+)$/.exec(url);
+  if (scp) {
+    [, host, path] = scp;
+  } else {
+    try {
+      const parsed = new URL(url);
+      if (!parsed.hostname) return undefined;
+      host = parsed.hostname;
+      path = parsed.pathname;
+    } catch {
+      return undefined;
+    }
+  }
+  const fullName = path.replace(/^\/+/, "").replace(/\/+$/, "").replace(/\.git$/, "");
+  if (!host || !fullName.includes("/")) return undefined;
+  const provider: RemoteProvider | undefined = /(^|\.)github\.com$/.test(host) ? "github" : /gitlab/.test(host) ? "gitlab" : undefined;
+  return { provider, host, fullName };
+}
+
+/** Runs one CLI (`glab` or `gh`) and resolves with its stdout. The seam the tests script. */
+export type CliRunner = (bin: "glab" | "gh", argv: string[], cwd: string) => Promise<string>;
+
+export const runCli: CliRunner = (bin, argv, cwd) => execToString(bin, argv, cwd, `${bin} ${argv.slice(0, 5).join(" ")}...`);
+
+/** The RemoteApi for an origin URL, or a refusal naming the host when no implementation fits. */
+export function remoteApiFor(originUrl: string, run: CliRunner = runCli, cwd = process.cwd()): RemoteApi {
+  const remote = parseRemoteUrl(originUrl);
+  if (!remote) throw new Error(`origin "${originUrl}" is not a GitLab or GitHub remote, so the Foreman cannot open a draft pull request there`);
+  switch (remote.provider) {
+    case "gitlab":
+      return new GitLabRemoteApi(remote.host, remote.fullName, run, cwd);
+    case "github":
+      return new GitHubRemoteApi(remote.host, remote.fullName, run, cwd);
+    default:
+      throw new Error(`origin host "${remote.host}" is neither GitLab nor GitHub; the Foreman can only open a draft pull request on those`);
+  }
+}
+
+function parseJson<T>(bin: string, text: string): T {
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new Error(`${bin} returned something that is not JSON: ${text.slice(0, 200)}`);
+  }
+}
+
+interface GitLabMergeRequest {
+  iid: number;
+  web_url: string;
+  title: string;
+  draft?: boolean;
+  source_branch: string;
+  target_branch: string;
+}
+
+const GITLAB_DRAFT_PREFIX = "Draft: ";
+
+/** The first `glab` with `api --form` (multipart uploads): its v1.91.0 changelog, "feat: add
+ * multipart/form-data support to `glab api` via `--form` flag". An older `glab` rejects the flag,
+ * the upload fails, and the Verdict comment names the screenshot's evidence directory instead. */
+export const GLAB_MIN_VERSION_FOR_FORM = "1.91.0";
+
+/** GitLab through `glab api`, addressing the project by its URL-encoded path. A draft is a title
+ * prefix on GitLab: it is set when the Hand-off opens the request and left as the humans have it
+ * afterwards, so a later attempt never puts a request a reviewer marked ready back into draft. */
+export class GitLabRemoteApi implements RemoteApi {
+  private readonly project: string;
+
+  constructor(
+    private readonly host: string,
+    fullName: string,
+    private readonly run: CliRunner = runCli,
+    private readonly cwd: string = process.cwd(),
+  ) {
+    this.project = encodeURIComponent(fullName);
+  }
+
+  private async api<T>(method: "GET" | "POST" | "PUT", path: string, fields: string[] = []): Promise<T> {
+    const out = await this.run("glab", ["api", "--hostname", this.host, "--method", method, path, ...fields], this.cwd);
+    return parseJson<T>("glab", out);
+  }
+
+  private static toPullRequest(mr: GitLabMergeRequest): RemotePullRequest {
+    return { number: mr.iid, url: mr.web_url, title: mr.title, draft: mr.draft ?? mr.title.startsWith(GITLAB_DRAFT_PREFIX), headBranch: mr.source_branch, baseBranch: mr.target_branch };
+  }
+
+  private static draftTitle(title: string): string {
+    return title.startsWith(GITLAB_DRAFT_PREFIX) ? title : `${GITLAB_DRAFT_PREFIX}${title}`;
+  }
+
+  async findPullRequest(headBranch: string): Promise<RemotePullRequest | undefined> {
+    const list = await this.api<GitLabMergeRequest[]>("GET", `projects/${this.project}/merge_requests?state=opened&source_branch=${encodeURIComponent(headBranch)}`);
+    return list.length > 0 ? GitLabRemoteApi.toPullRequest(list[0]) : undefined;
+  }
+
+  /** `search` matches substrings, so the title is compared exactly afterwards, draft prefix aside. */
+  async findPullRequestByTitle(title: string): Promise<RemotePullRequest | undefined> {
+    const list = await this.api<GitLabMergeRequest[]>("GET", `projects/${this.project}/merge_requests?state=opened&in=title&search=${encodeURIComponent(title)}`);
+    const hit = list.find((mr) => mr.title === title || mr.title === GitLabRemoteApi.draftTitle(title));
+    return hit ? GitLabRemoteApi.toPullRequest(hit) : undefined;
+  }
+
+  async openDraftPullRequest(input: NewPullRequest): Promise<RemotePullRequest> {
+    const mr = await this.api<GitLabMergeRequest>("POST", `projects/${this.project}/merge_requests`, [
+      "--raw-field", `source_branch=${input.headBranch}`,
+      "--raw-field", `target_branch=${input.baseBranch}`,
+      "--raw-field", `title=${GitLabRemoteApi.draftTitle(input.title)}`,
+      "--raw-field", `description=${input.body}`,
+      "--field", "remove_source_branch=true",
+    ]);
+    return GitLabRemoteApi.toPullRequest(mr);
+  }
+
+  async updatePullRequest(number: number, patch: PullRequestPatch): Promise<RemotePullRequest> {
+    const current = await this.api<GitLabMergeRequest>("GET", `projects/${this.project}/merge_requests/${number}`);
+    const stillDraft = current.draft ?? current.title.startsWith(GITLAB_DRAFT_PREFIX);
+    const mr = await this.api<GitLabMergeRequest>("PUT", `projects/${this.project}/merge_requests/${number}`, [
+      "--raw-field", `title=${stillDraft ? GitLabRemoteApi.draftTitle(patch.title) : patch.title}`,
+      "--raw-field", `description=${patch.body}`,
+    ]);
+    return GitLabRemoteApi.toPullRequest(mr);
+  }
+
+  async addPullRequestComment(number: number, body: string): Promise<void> {
+    await this.api<unknown>("POST", `projects/${this.project}/merge_requests/${number}/notes`, ["--raw-field", `body=${body}`]);
+  }
+
+  /** `POST /projects/:id/uploads` (https://docs.gitlab.com/api/projects/#upload-a-file): the file
+   * as a `multipart/form-data` field, and the response's `markdown` is what a note shows it with.
+   * That is `glab api --form file=@<path>` (`GLAB_MIN_VERSION_FOR_FORM` and later): `--field
+   * name=@path` reads the file's bytes as a JSON string value, which the uploads endpoint refuses
+   * with 400, and `--form` cannot be combined with `--field`, `--raw-field` or `--input`. The
+   * project's upload URL is relative to the project on GitLab (`/uploads/<hash>/<name>`);
+   * `full_path` is absolute. */
+  async uploadAttachment(_number: number, filePath: string): Promise<Attachment> {
+    const upload = await this.api<{ url: string; full_path?: string; markdown: string }>("POST", `projects/${this.project}/uploads`, ["--form", `file=@${filePath}`]);
+    return { url: upload.full_path ? `https://${this.host}${upload.full_path}` : upload.url, markdown: upload.markdown };
+  }
+}
+
+interface GitHubPullRequest {
+  number: number;
+  html_url: string;
+  title: string;
+  draft: boolean;
+  head: { ref: string };
+  base: { ref: string };
+}
+
+/** GitHub through `gh api`. */
+export class GitHubRemoteApi implements RemoteApi {
+  private readonly owner: string;
+
+  constructor(
+    private readonly host: string,
+    private readonly fullName: string,
+    private readonly run: CliRunner = runCli,
+    private readonly cwd: string = process.cwd(),
+  ) {
+    this.owner = fullName.split("/")[0];
+  }
+
+  private async api<T>(method: "GET" | "POST" | "PATCH", path: string, fields: string[] = []): Promise<T> {
+    const out = await this.run("gh", ["api", "--hostname", this.host, "--method", method, path, ...fields], this.cwd);
+    return parseJson<T>("gh", out);
+  }
+
+  private static toPullRequest(pr: GitHubPullRequest): RemotePullRequest {
+    return { number: pr.number, url: pr.html_url, title: pr.title, draft: pr.draft, headBranch: pr.head.ref, baseBranch: pr.base.ref };
+  }
+
+  async findPullRequest(headBranch: string): Promise<RemotePullRequest | undefined> {
+    const list = await this.api<GitHubPullRequest[]>("GET", `repos/${this.fullName}/pulls?state=open&head=${encodeURIComponent(`${this.owner}:${headBranch}`)}`);
+    return list.length > 0 ? GitHubRemoteApi.toPullRequest(list[0]) : undefined;
+  }
+
+  /** The open pull requests are listed and the title compared exactly here. The issue search
+   * would do it in one query, but its index lags a pull request just opened, and a Run that then
+   * missed the learnings pull request of the Run before would open a second one. */
+  async findPullRequestByTitle(title: string): Promise<RemotePullRequest | undefined> {
+    const list = await this.api<GitHubPullRequest[]>("GET", `repos/${this.fullName}/pulls?state=open&per_page=100`);
+    const hit = list.find((pr) => pr.title === title);
+    return hit ? GitHubRemoteApi.toPullRequest(hit) : undefined;
+  }
+
+  async openDraftPullRequest(input: NewPullRequest): Promise<RemotePullRequest> {
+    const pr = await this.api<GitHubPullRequest>("POST", `repos/${this.fullName}/pulls`, [
+      "--raw-field", `head=${input.headBranch}`,
+      "--raw-field", `base=${input.baseBranch}`,
+      "--raw-field", `title=${input.title}`,
+      "--raw-field", `body=${input.body}`,
+      "--field", "draft=true",
+    ]);
+    return GitHubRemoteApi.toPullRequest(pr);
+  }
+
+  async updatePullRequest(number: number, patch: PullRequestPatch): Promise<RemotePullRequest> {
+    const pr = await this.api<GitHubPullRequest>("PATCH", `repos/${this.fullName}/pulls/${number}`, ["--raw-field", `title=${patch.title}`, "--raw-field", `body=${patch.body}`]);
+    return GitHubRemoteApi.toPullRequest(pr);
+  }
+
+  /** A pull request's conversation is its issue's on GitHub. */
+  async addPullRequestComment(number: number, body: string): Promise<void> {
+    await this.api<unknown>("POST", `repos/${this.fullName}/issues/${number}/comments`, ["--raw-field", `body=${body}`]);
+  }
+
+  /** GitHub's REST API has no upload for issue or review comments (the web UI's attachments go
+   * through a browser-only endpoint), so a screenshot cannot be shown on the pull request from
+   * here; the Verifier keeps it on the Foreman's machine and the comment names the path. */
+  async uploadAttachment(): Promise<undefined> {
+    return undefined;
+  }
+}