@zgeoff/atc 2.16.0 → 2.19.0

package/src/shared/collect-workspaces-config.ts

@@ -0,0 +1,120 @@
+import { DEFAULT_GIT_TRANSPORTS } from './default-git-transports';
+import { isRecord } from './report';
+
+/**
+ * Where workspace sources come from and where their checkouts land: the
+ * GitHub owner whose repositories the spawn picker lists by default, or
+ * null to list the gh account's own; the ids of the sources the picker
+ * offers, in order, or null for the default order; the git transports the
+ * daemon fetches over; the root a checkout lands under on any target
+ * without its own, or null for the default; and each target's own root, by
+ * target id. A root is kept as written: whether it fits its target, such
+ * as `~` on a remote target, is checked where the target is known.
+ */
+export interface WorkspacesConfig {
+  readonly githubOwner: string | null;
+  readonly sources: readonly string[] | null;
+  readonly gitTransports: readonly string[] | InvalidGitTransports;
+  readonly root: string | null;
+  readonly targetRoots: ReadonlyMap<string, string>;
+}
+
+/**
+ * A transport list the config holds that atc cannot use, with the config
+ * errors it raised. The daemon runs no git while the list is invalid.
+ */
+export interface InvalidGitTransports {
+  readonly invalid: string;
+}
+
+interface CollectedWorkspacesConfig {
+  readonly workspaces: WorkspacesConfig;
+
+  // The config problems the section holds, one line each.
+  readonly errors: readonly string[];
+}
+
+// A GitHub account or organization login.
+const GITHUB_OWNER_PATTERN = /^[A-Za-z\d][A-Za-z\d-]{0,38}$/u;
+
+/**
+ * Reads the `workspaces` section of config.json. An owner that is not a
+ * GitHub login is dropped, so a typo lists the gh account's own
+ * repositories instead of failing, a source order that is not a list of
+ * ids falls back to the default order, and a root that is not a non-empty
+ * string is dropped. A transport list that is not a
+ * list of transports atc allows is a config error, and the list is then
+ * invalid, never the default, so the daemon runs no git until it is fixed.
+ * An empty list is valid and allows no transport.
+ */
+export function collectWorkspacesConfig(raw: unknown): CollectedWorkspacesConfig {
+  const section = isRecord(raw) ? raw : {};
+  const owner = section['githubOwner'];
+  const sources = section['sources'];
+  const root = section['root'];
+  const targets = isRecord(section['targets']) ? section['targets'] : {};
+  const transports = collectGitTransports(section['gitTransports']);
+
+  return {
+    workspaces: {
+      githubOwner: typeof owner === 'string' && GITHUB_OWNER_PATTERN.test(owner) ? owner : null,
+      sources:
+        Array.isArray(sources) &&
+        sources.every((id): id is string => typeof id === 'string' && id !== '')
+          ? sources
+          : null,
+      gitTransports: transports.transports,
+      root: typeof root === 'string' && root !== '' ? root : null,
+      targetRoots: new Map(
+        Object.entries(targets).flatMap(([id, dir]) =>
+          typeof dir === 'string' && dir !== '' ? [[id, dir] as const] : [],
+        ),
+      ),
+    },
+    errors: transports.errors,
+  };
+}
+
+// The git transports a config may allow: the defaults, and the two
+// opt-ins.
+const KNOWN_TRANSPORTS: ReadonlySet<string> = new Set(['https', 'ssh', 'http', 'file']);
+
+// Transports that run a command or read a descriptor on the daemon's host.
+const REFUSED_TRANSPORTS: ReadonlySet<string> = new Set(['ext', 'fd']);
+
+function collectGitTransports(raw: unknown): {
+  readonly transports: readonly string[] | InvalidGitTransports;
+  readonly errors: readonly string[];
+} {
+  if (raw === undefined) {
+    return { transports: DEFAULT_GIT_TRANSPORTS, errors: [] };
+  }
+
+  const fallback = 'the daemon runs no git until it is fixed';
+
+  if (!Array.isArray(raw)) {
+    const error = `workspaces.gitTransports is not a list of git transports; ${fallback}`;
+
+    return { transports: { invalid: error }, errors: [error] };
+  }
+
+  const errors = raw.flatMap((name: unknown) => {
+    if (typeof name === 'string' && REFUSED_TRANSPORTS.has(name)) {
+      return [
+        `workspaces.gitTransports holds '${name}', which atc never allows because it runs a command or reads a descriptor on the daemon host; ${fallback}`,
+      ];
+    }
+
+    if (typeof name !== 'string' || !KNOWN_TRANSPORTS.has(name)) {
+      return [
+        `workspaces.gitTransports holds ${JSON.stringify(name)}, which is not a git transport atc allows; ${fallback}`,
+      ];
+    }
+
+    return [];
+  });
+
+  return errors.length === 0
+    ? { transports: raw.filter((name): name is string => typeof name === 'string'), errors }
+    : { transports: { invalid: errors.join('; ') }, errors };
+}

package/src/shared/config.ts

@@ -11,6 +11,9 @@ import type { HooksConfig } from './collect-hooks';
 import { collectPrincipals } from './collect-principals';
 import { collectTargets } from './collect-targets';
 import type { TargetConfig, TargetConfigError } from './collect-targets';
+import { collectWorkspacesConfig } from './collect-workspaces-config';
+import type { WorkspacesConfig } from './collect-workspaces-config';
+import { DEFAULT_GIT_TRANSPORTS } from './default-git-transports';
 import { formatJSONKind } from './format-json-kind';
 import { isRecord } from './report';
 import { resolveHomeDir } from './resolve-home-dir';
@@ -23,6 +26,7 @@ export interface Config {
   codexBin: string;
   codexArgs: string[];
   dirs: DirsConfig;
+  workspaces: WorkspacesConfig;
   gateways: GatewayConfig[];
   hooks: HooksConfig;
   leader: LeaderKey;
@@ -40,6 +44,9 @@ export interface Config {
   // principals, which leaves every principal the implicit local target.
   principals: ReadonlyMap<string, readonly string[]> | null;
   principalErrors: readonly string[];
+
+  // The workspace config problems, one line each.
+  workspaceErrors: readonly string[];
 }
 
 /**
@@ -63,6 +70,13 @@ const DEFAULTS: Config = {
   codexBin: 'codex',
   codexArgs: [],
   dirs: { roots: [] },
+  workspaces: {
+    githubOwner: null,
+    sources: null,
+    gitTransports: DEFAULT_GIT_TRANSPORTS,
+    root: null,
+    targetRoots: new Map(),
+  },
   gateways: [],
   hooks: {},
   leader: { code: 0, label: '^Space' },
@@ -71,6 +85,7 @@ const DEFAULTS: Config = {
   targetErrors: [],
   principals: null,
   principalErrors: [],
+  workspaceErrors: [],
 };
 
 const configDir = join(resolveHomeDir(), '.config', 'atc');
@@ -101,6 +116,7 @@ const CONFIG_SCHEMA = z.object({
   codexBin: buildOptionalString(),
   codexArgs: buildOptionalStringArray(),
   dirs: z.unknown().optional(),
+  workspaces: z.unknown().optional(),
   gateways: z.unknown().optional(),
   hooks: z.unknown().optional(),
   leader: buildOptionalString(),
@@ -200,10 +216,20 @@ export function renderDefaultConfig(): string {
     targetErrors: _errors,
     principals: _principals,
     principalErrors: _principalErrors,
+    workspaceErrors: _workspaceErrors,
+    workspaces,
     ...written
   } = DEFAULTS;
 
-  return `${JSON.stringify(written, null, 2)}\n`;
+  // The target roots are a map in memory and an object of target ids in
+  // the file.
+  const { targetRoots, ...rest } = workspaces;
+
+  return `${JSON.stringify(
+    { ...written, workspaces: { ...rest, targets: Object.fromEntries(targetRoots) } },
+    null,
+    2,
+  )}\n`;
 }
 
 /**
@@ -239,6 +265,7 @@ export function parseConfig(raw: unknown, file: string = configFile): Config {
   const codexBin = parsed.data.codexBin ?? DEFAULTS.codexBin;
   const codexArgs = parsed.data.codexArgs ?? DEFAULTS.codexArgs;
   const dirs = { roots: collectDirRoots(parsed.data.dirs) };
+  const workspaces = collectWorkspacesConfig(parsed.data.workspaces);
   const gateways = collectGateways(parsed.data.gateways, claudeBin, claudeArgs);
   const hooks = collectHooks(parsed.data.hooks);
   const targets = collectTargets(parsed.data.targets, parsed.data.defaultTarget);
@@ -255,6 +282,7 @@ export function parseConfig(raw: unknown, file: string = configFile): Config {
     codexBin,
     codexArgs,
     dirs,
+    workspaces: workspaces.workspaces,
     gateways,
     hooks,
     leader,
@@ -263,6 +291,7 @@ export function parseConfig(raw: unknown, file: string = configFile): Config {
     targetErrors: targets.errors,
     principals: principals.principals,
     principalErrors: principals.errors,
+    workspaceErrors: workspaces.errors,
   };
 }
 

package/src/shared/default-git-transports.ts

@@ -0,0 +1,5 @@
+/**
+ * The git transports the daemon fetches workspace sources over when the
+ * config sets none.
+ */
+export const DEFAULT_GIT_TRANSPORTS: readonly string[] = ['https', 'ssh'];

package/src/shared/is-git-url.ts

@@ -0,0 +1,11 @@
+// A URL with a scheme, an scp-style `user@host:path`, or an absolute path.
+const GIT_URL_PATTERN = /^(?:[a-z][a-z\d+.-]*:\/\/|[^@/:\s]+@[^@/:\s]+:|\/)/iu;
+
+/**
+ * Whether typed text is a git repository URL in a form git itself reads:
+ * one with a scheme, the scp-style `user@host:path`, or an absolute path
+ * to a repository on the daemon's host.
+ */
+export function isGitURL(input: string): boolean {
+  return GIT_URL_PATTERN.test(input.trim());
+}

package/src/sources/build-sources.ts

@@ -0,0 +1,40 @@
+import type { SourceProvider } from './types';
+
+// The order sources take when the config gives none.
+const DEFAULT_SOURCE_ORDER = ['dirs', 'github', 'git'];
+
+interface BuiltSources {
+  readonly sources: readonly SourceProvider[];
+
+  // The ids a configured order holds that no available source has.
+  readonly missing: readonly string[];
+}
+
+/**
+ * The sources the spawn picker offers, in the configured order, else the
+ * default one. A source the order leaves out is not offered, and an id
+ * with no available source is skipped, so a source that cannot run on
+ * this host is simply not offered; a configured order reports such ids as
+ * missing.
+ */
+export function buildSources(
+  available: readonly SourceProvider[],
+  order: readonly string[] | null,
+): BuiltSources {
+  const byID = new Map(available.map((source) => [source.id, source]));
+
+  const sources: SourceProvider[] = [];
+  const missing: string[] = [];
+
+  for (const id of new Set(order ?? DEFAULT_SOURCE_ORDER)) {
+    const source = byID.get(id);
+
+    if (source !== undefined) {
+      sources.push(source);
+    } else if (order !== null) {
+      missing.push(id);
+    }
+  }
+
+  return { sources, missing };
+}

package/src/sources/collect-builtin-sources.ts

@@ -0,0 +1,41 @@
+import { buildDirsSource } from './dirs/build-dirs-source';
+import { buildGitSource } from './git/build-git-source';
+import { buildGitHubSource } from './github/build-github-source';
+import type { SourceProvider } from './types';
+
+interface BuiltinSourceOptions {
+  // The configured directory roots.
+  readonly roots: readonly string[];
+
+  // The GitHub owner a listing without a scope lists, or null for the gh
+  // account's own repositories.
+  readonly githubOwner: string | null;
+
+  // The gh executable: a name looked up on PATH, or a path.
+  readonly ghBin: string;
+
+  // The daemon user's home directory.
+  readonly homeDir: string;
+
+  // zoxide's frecency list on the daemon's host.
+  readonly collectZoxideDirs: () => Promise<string[]>;
+}
+
+/**
+ * The built-in sources this host can run, each with its services: the
+ * directories on the daemon's host, GitHub when gh is on this host, and
+ * a typed git URL, which needs nothing beyond git.
+ */
+export function collectBuiltinSources(options: BuiltinSourceOptions): SourceProvider[] {
+  return [
+    buildDirsSource({
+      roots: options.roots,
+      collectZoxideDirs: options.collectZoxideDirs,
+      homeDir: options.homeDir,
+    }),
+    ...(Bun.which(options.ghBin) === null
+      ? []
+      : [buildGitHubSource({ bin: options.ghBin, owner: options.githubOwner })]),
+    buildGitSource(),
+  ];
+}

package/src/sources/dirs/build-dirs-source.ts

@@ -0,0 +1,70 @@
+import { existsSync } from 'node:fs';
+import { isAbsolute } from 'node:path';
+import { collectRootDirs } from '../../shared/collect-root-dirs';
+import type { SourceInterpretation, SourceProvider } from '../types';
+
+// What the source reads besides the spawn history a request brings.
+interface DirsSourceServices {
+  // The configured roots, each listing its child directories and their
+  // worktrees.
+  readonly roots: readonly string[];
+
+  // zoxide's frecency list on the daemon's host, most visited first.
+  readonly collectZoxideDirs: () => Promise<string[]>;
+
+  // The daemon user's home directory, which a leading `~` stands for.
+  readonly homeDir: string;
+}
+
+/**
+ * The directories on the daemon's host a session can run in: the spawn
+ * history the requesting principal may read, most recent first, then the
+ * configured roots, then zoxide's list. A directory that no longer exists
+ * is left out, and a duplicate keeps its first place. Typed input is a
+ * directory when it is absolute or starts with `~`, which stands for the
+ * daemon user's home.
+ */
+export function buildDirsSource(services: DirsSourceServices): SourceProvider {
+  return {
+    id: 'dirs',
+    label: 'directory on the daemon host',
+    kind: 'path',
+    async list(_query, request) {
+      const seen = new Set<string>();
+
+      for (const dir of [
+        ...(await request.collectSpawnDirs()),
+        ...collectRootDirs(services.roots),
+        ...(await services.collectZoxideDirs()),
+      ]) {
+        if (!seen.has(dir) && existsSync(dir)) {
+          seen.add(dir);
+        }
+      }
+
+      return {
+        candidates: [...seen].map((dir) => ({
+          label: formatHomePath(dir, services.homeDir),
+          pick: { kind: 'path', dir },
+        })),
+        scope: null,
+      };
+    },
+    interpret(input) {
+      const text = input.trim();
+
+      const dir =
+        text === '~' || text.startsWith('~/') ? `${services.homeDir}${text.slice(1)}` : text;
+
+      const interpretation: SourceInterpretation = isAbsolute(dir)
+        ? { kind: 'path', dir }
+        : { kind: 'none' };
+
+      return Promise.resolve(interpretation);
+    },
+  };
+}
+
+function formatHomePath(dir: string, home: string): string {
+  return dir === home || dir.startsWith(`${home}/`) ? `~${dir.slice(home.length)}` : dir;
+}

package/src/sources/git/build-git-source.ts

@@ -0,0 +1,25 @@
+import { isGitURL } from '../../shared/is-git-url';
+import type { SourceInterpretation, SourceProvider } from '../types';
+
+/**
+ * A git repository at a typed URL, which needs nothing installed beyond
+ * git. It lists nothing; typed input is a repository when it is a URL git
+ * reads.
+ */
+export function buildGitSource(): SourceProvider {
+  return {
+    id: 'git',
+    label: 'git URL',
+    kind: 'git',
+    list: () => Promise.resolve({ candidates: [], scope: null }),
+    interpret(input) {
+      const url = input.trim();
+
+      const interpretation: SourceInterpretation = isGitURL(url)
+        ? { kind: 'git', url }
+        : { kind: 'none' };
+
+      return Promise.resolve(interpretation);
+    },
+  };
+}

package/src/sources/github/build-github-source.ts

@@ -0,0 +1,113 @@
+import { DaemonError } from '../../protocol/daemon-error';
+import type { SourceProvider } from '../types';
+import { collectGitHubRepos } from './collect-github-repos';
+import { findGitHubAlternateURL } from './find-github-alternate-url';
+import { readGitProtocol } from './read-git-protocol';
+
+interface GitHubSourceOptions {
+  // The gh executable: a name looked up on PATH, or a path.
+  readonly bin: string;
+
+  // The owner a listing without a scope lists; null lists the gh account's
+  // own repositories.
+  readonly owner: string | null;
+
+  // How long each gh command may take; 20 s when unset.
+  readonly timeoutMs?: number;
+}
+
+// How long a gh command may take before the request is refused.
+const GH_TIMEOUT_MS = 20_000;
+
+// A GitHub account or organization login.
+const GITHUB_OWNER_PATTERN = /^[A-Za-z\d][A-Za-z\d-]{0,38}$/u;
+
+// Typed `owner/`, which lists that owner.
+const OWNER_INPUT_PATTERN = /^(?<owner>[A-Za-z\d][A-Za-z\d-]{0,38})\/$/u;
+
+// Typed `owner/repo`, with or without `.git`.
+const REPO_INPUT_PATTERN =
+  /^(?<owner>[A-Za-z\d][A-Za-z\d-]{0,38})\/(?<repo>[\w-][\w.-]*?)(?:\.git)?$/u;
+
+/**
+ * The GitHub repositories gh on the daemon's host can see. A listing's
+ * scope is the owner to list. Typed `owner/` lists that owner, and typed
+ * `owner/repo` is that repository at the clone URL the gh config prefers.
+ * A GitHub URL the host cannot read has the other URL form as its
+ * alternate.
+ * A listing gh cannot give throws `github_unavailable` with the problem.
+ */
+export function buildGitHubSource(options: GitHubSourceOptions): SourceProvider {
+  const timeoutMs = options.timeoutMs ?? GH_TIMEOUT_MS;
+
+  return {
+    id: 'github',
+    label: 'GitHub repository',
+    kind: 'git',
+    async list(query) {
+      const owner = query.scope ?? options.owner;
+
+      if (owner !== null && !GITHUB_OWNER_PATTERN.test(owner)) {
+        throw new DaemonError('bad_args', 'scope must be a GitHub account or organization');
+      }
+
+      const listed = await collectGitHubRepos({ bin: options.bin, owner, timeoutMs });
+
+      if (!listed.ok) {
+        throw new DaemonError(listed.code, listed.message, { problem: listed.problem });
+      }
+
+      return {
+        candidates: listed.repos.map((repo) => {
+          const notes = [
+            ...(repo.isPrivate ? ['private'] : []),
+            ...(repo.description === '' ? [] : [repo.description]),
+          ];
+
+          return {
+            label: repo.nameWithOwner,
+            ...(notes.length === 0 ? {} : { detail: notes.join(' · ') }),
+            pick: {
+              kind: 'git',
+              url: listed.gitProtocol === 'ssh' ? repo.sshUrl : toCloneURL(repo.url),
+            },
+          };
+        }),
+        scope: listed.owner,
+      };
+    },
+    async interpret(input) {
+      const text = input.trim();
+      const owner = OWNER_INPUT_PATTERN.exec(text)?.groups?.['owner'];
+
+      if (owner !== undefined) {
+        return { kind: 'browse', scope: owner };
+      }
+
+      const repo = REPO_INPUT_PATTERN.exec(text)?.groups;
+
+      if (repo === undefined) {
+        return { kind: 'none' };
+      }
+
+      const name = `${repo['owner']}/${repo['repo']}`;
+
+      const protocol = await readGitProtocol(options.bin, timeoutMs);
+
+      return {
+        kind: 'git',
+        url: protocol === 'ssh' ? `git@github.com:${name}.git` : `https://github.com/${name}.git`,
+      };
+    },
+    findAlternateURLs(url) {
+      const alternate = findGitHubAlternateURL(url);
+
+      return alternate === null ? [] : [alternate];
+    },
+  };
+}
+
+// The https clone URL of a repository's web URL.
+function toCloneURL(url: string): string {
+  return url.endsWith('.git') ? url : `${url}.git`;
+}

package/src/sources/github/collect-github-repos.ts

@@ -0,0 +1,165 @@
+import { z } from 'zod';
+import { readGitProtocol } from './read-git-protocol';
+import { runGH } from './run-gh';
+import type { GHRun } from './run-gh';
+
+interface GitHubRepo {
+  // `owner/repo`, which a git workspace source takes as its URL.
+  readonly nameWithOwner: string;
+  readonly description: string;
+  readonly isPrivate: boolean;
+
+  // The repository's https and ssh clone URLs.
+  readonly url: string;
+  readonly sshUrl: string;
+}
+
+interface GitHubRepoListing {
+  readonly ok: true;
+
+  // The owner listed: the requested one, else the gh account's own login
+  // as the first repository holds it, else null for an empty own list.
+  readonly owner: string | null;
+  readonly repos: readonly GitHubRepo[];
+
+  // The clone protocol the gh config prefers, `https` unless it says `ssh`.
+  readonly gitProtocol: 'https' | 'ssh';
+}
+
+interface GitHubUnavailable {
+  readonly ok: false;
+  readonly code: 'github_unavailable';
+  readonly problem: 'failed' | 'not_authenticated' | 'not_installed';
+  readonly message: string;
+}
+
+interface GitHubListRequest {
+  // The gh executable: a name looked up on PATH, or a path.
+  readonly bin: string;
+
+  // The account or organization to list; null lists the gh account's own.
+  readonly owner: string | null;
+
+  // How long each gh command may take; 20 s when unset.
+  readonly timeoutMs?: number;
+}
+
+// How long a gh command may take before the listing is refused.
+const GH_TIMEOUT_MS = 20_000;
+
+// How many repositories one listing holds at most.
+const REPO_LIMIT = 500;
+
+// The fields of each repository gh repo list prints that a listing keeps.
+const REPO_LIST_SCHEMA = z.array(
+  z.object({
+    nameWithOwner: z.string().regex(/^[^/\s]+\/[^/\s]+$/u),
+    description: z
+      .string()
+      .nullable()
+      .optional()
+      .transform((description) => description ?? ''),
+    isPrivate: z.boolean(),
+    url: z.string(),
+    sshUrl: z.string(),
+  }),
+);
+
+/**
+ * Lists one owner's GitHub repositories through the gh CLI on this host,
+ * as the gh account signed in there sees them. gh is optional: a host
+ * without it, or with gh signed out, is refused as `github_unavailable`
+ * with the problem, and any other gh failure carries gh's own message. A gh
+ * that takes longer than the time limit, 20 s unless given, is refused as
+ * failed. gh never prompts here.
+ */
+export async function collectGitHubRepos(
+  request: GitHubListRequest,
+): Promise<GitHubRepoListing | GitHubUnavailable> {
+  const bin = Bun.which(request.bin);
+
+  if (bin === null) {
+    return {
+      ok: false,
+      code: 'github_unavailable',
+      problem: 'not_installed',
+      message: `gh is not installed on the daemon host (no '${request.bin}' on PATH)`,
+    };
+  }
+
+  const timeoutMs = request.timeoutMs ?? GH_TIMEOUT_MS;
+
+  const listed = await runGH(bin, timeoutMs, [
+    'repo',
+    'list',
+    ...(request.owner === null ? [] : [request.owner]),
+    '--limit',
+    String(REPO_LIMIT),
+    '--json',
+    'nameWithOwner,description,isPrivate,url,sshUrl',
+  ]);
+
+  if (listed.timedOut) {
+    return {
+      ok: false,
+      code: 'github_unavailable',
+      problem: 'failed',
+      message: `gh did not answer within ${timeoutMs / 1000} s`,
+    };
+  }
+
+  if (listed.exitCode !== 0) {
+    return buildUnavailable(listed);
+  }
+
+  const parsed = REPO_LIST_SCHEMA.safeParse(parseJSON(listed.stdout));
+
+  if (!parsed.success) {
+    return {
+      ok: false,
+      code: 'github_unavailable',
+      problem: 'failed',
+      message: 'gh repo list printed no repository list',
+    };
+  }
+
+  const repos = parsed.data;
+
+  return {
+    ok: true,
+    owner: request.owner ?? repos[0]?.nameWithOwner.split('/')[0] ?? null,
+    repos,
+    gitProtocol: await readGitProtocol(bin, timeoutMs),
+  };
+}
+
+// gh exits 4 when it needs a sign-in it does not have.
+const GH_AUTH_EXIT = 4;
+
+function buildUnavailable(run: GHRun): GitHubUnavailable {
+  const detail = run.stderr.trim();
+
+  if (run.exitCode === GH_AUTH_EXIT) {
+    return {
+      ok: false,
+      code: 'github_unavailable',
+      problem: 'not_authenticated',
+      message: `gh is not signed in on the daemon host; run gh auth login there${detail === '' ? '' : `: ${detail}`}`,
+    };
+  }
+
+  return {
+    ok: false,
+    code: 'github_unavailable',
+    problem: 'failed',
+    message: detail === '' ? `gh exited with ${run.exitCode}` : detail,
+  };
+}
+
+function parseJSON(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}