@zgeoff/atc 2.16.0 → 2.17.0

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;
+  }
+}

package/src/sources/github/find-github-alternate-url.ts

@@ -0,0 +1,20 @@
+const HTTPS_PATTERN = /^https:\/\/github\.com\/(?<owner>[\w.-]+)\/(?<repo>[\w.-]+?)(?:\.git)?\/?$/u;
+
+const SSH_PATTERN =
+  /^(?:ssh:\/\/)?git@github\.com[:/](?<owner>[\w.-]+)\/(?<repo>[\w.-]+?)(?:\.git)?$/u;
+
+/**
+ * The other URL form of a GitHub repository: the ssh form of an https URL,
+ * and the https form of an ssh URL. Null for a URL not on GitHub.
+ */
+export function findGitHubAlternateURL(url: string): string | null {
+  const ssh = SSH_PATTERN.exec(url)?.groups;
+
+  if (ssh !== undefined) {
+    return `https://github.com/${ssh['owner']}/${ssh['repo']}.git`;
+  }
+
+  const https = HTTPS_PATTERN.exec(url)?.groups;
+
+  return https === undefined ? null : `git@github.com:${https['owner']}/${https['repo']}.git`;
+}

package/src/sources/github/read-git-protocol.ts

@@ -0,0 +1,11 @@
+import { runGH } from './run-gh';
+
+/**
+ * The clone protocol the gh config on this host prefers: `ssh` when it says
+ * so, else `https`, which a gh that fails or takes too long also gives.
+ */
+export async function readGitProtocol(bin: string, timeoutMs: number): Promise<'https' | 'ssh'> {
+  const run = await runGH(bin, timeoutMs, ['config', 'get', 'git_protocol']);
+
+  return run.exitCode === 0 && run.stdout.trim() === 'ssh' ? 'ssh' : 'https';
+}

package/src/sources/github/run-gh.ts

@@ -0,0 +1,66 @@
+export interface GHRun {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+  readonly timedOut: boolean;
+}
+
+/**
+ * Runs gh with arguments and a time limit, killing its whole process group
+ * once the limit passes, so a wrapper or extension leaves no process
+ * behind. gh reads its own config and the host's environment for its
+ * token, and is kept from prompting, colouring, or checking for updates.
+ */
+export async function runGH(
+  bin: string,
+  timeoutMs: number,
+  args: readonly string[],
+): Promise<GHRun> {
+  const proc = Bun.spawn([bin, ...args], {
+    env: {
+      ...process.env,
+      GH_PROMPT_DISABLED: '1',
+      GH_NO_UPDATE_NOTIFIER: '1',
+      GH_SPINNER_DISABLED: '1',
+      NO_COLOR: '1',
+      LC_ALL: 'C',
+    },
+    stdin: 'ignore',
+    stdout: 'pipe',
+    stderr: 'pipe',
+
+    // gh leads its own process group, so stopping it stops what it
+    // started too.
+    detached: true,
+  });
+
+  const finished = Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  const limit = Promise.withResolvers<null>();
+
+  const timer = setTimeout(() => {
+    limit.resolve(null);
+  }, timeoutMs);
+
+  const settled = await Promise.race([finished, limit.promise]);
+
+  clearTimeout(timer);
+
+  if (settled === null) {
+    try {
+      process.kill(-proc.pid, 'SIGKILL');
+    } catch {
+      // The group already exited.
+    }
+
+    return { exitCode: -1, stdout: '', stderr: '', timedOut: true };
+  }
+
+  const [stdout, stderr, exitCode] = settled;
+
+  return { exitCode, stdout, stderr, timedOut: false };
+}

package/src/sources/types.ts

@@ -0,0 +1,70 @@
+/**
+ * What a candidate or a typed input resolves to: a directory on the
+ * daemon's host, or a git repository URL that a probe pins to a commit
+ * before any spawn uses it.
+ */
+type SourcePick =
+  | { readonly kind: 'path'; readonly dir: string }
+  | { readonly kind: 'git'; readonly url: string };
+
+// The kind of pick every candidate of one source resolves to.
+export type SourceKind = SourcePick['kind'];
+
+// One entry a source lists for the spawn picker.
+interface SourceCandidate {
+  readonly label: string;
+  readonly detail?: string;
+  readonly pick: SourcePick;
+}
+
+// One listing: the candidates, and the scope they were listed under, or
+// null when the source lists without one.
+interface SourceListing {
+  readonly candidates: readonly SourceCandidate[];
+  readonly scope: string | null;
+}
+
+// What a listing asks for: a scope the source defines, such as one account,
+// and filter text for a source that filters on the daemon.
+interface SourceQuery {
+  readonly scope?: string;
+  readonly text?: string;
+}
+
+/**
+ * What a source reads typed input as: a scope to list, a pick, or nothing
+ * it recognizes.
+ */
+export type SourceInterpretation =
+  | { readonly kind: 'browse'; readonly scope: string }
+  | SourcePick
+  | { readonly kind: 'none' };
+
+/**
+ * The request a source serves: the execution target the spawn will use,
+ * and the daemon's spawn history as the requesting principal may read it.
+ */
+export interface SourceRequest {
+  readonly target: string;
+  readonly collectSpawnDirs: () => Promise<string[]>;
+}
+
+/**
+ * A discovery source for the spawn picker. It lists candidates and reads
+ * typed input, and every candidate resolves to a pick of its kind. A source
+ * runs on the daemon, the host that materializes the workspace, and gets
+ * the services it uses when it is built. A failure throws the error the
+ * source defines for it.
+ */
+export interface SourceProvider {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: SourceKind;
+  readonly list: (query: SourceQuery, request: SourceRequest) => Promise<SourceListing>;
+  readonly interpret: (input: string, request: SourceRequest) => Promise<SourceInterpretation>;
+
+  // The other URLs of the repository at a git URL the daemon's host could
+  // not read, for a source that knows its host's URL forms; none when it
+  // does not recognize the URL.
+  readonly findAlternateURLs?: (url: string) => readonly string[];
+}

package/src/workspace/check-git-transport.ts

@@ -0,0 +1,61 @@
+type TransportCheck =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly code: 'invalid_git_url'; readonly message: string };
+
+// `<transport>::<address>`, which runs git's remote helper for the
+// transport, such as `ext::` or `fd::`.
+const HELPER_PATTERN = /^(?<name>[A-Za-z][\w+.-]*)::/u;
+
+// `<scheme>://…`.
+const SCHEME_PATTERN = /^(?<name>[A-Za-z][\w+.-]*):\/\//u;
+
+// The scp-style `user@host:path` or `host:path`, which git reads as ssh.
+const SCP_PATTERN = /^(?:[^@/:\s]+@)?[^@/:\s]+:/u;
+
+// Schemes git treats as ssh.
+const SSH_SCHEMES: ReadonlySet<string> = new Set(['ssh', 'git+ssh', 'ssh+git']);
+
+/**
+ * Checks that a repository URL uses one of the allowed git transports,
+ * without running git. The scp-style form is ssh, a remote-helper URL is
+ * its helper's transport, and a path is the `file` transport. A URL that
+ * git could read as an option is refused whatever the transports.
+ */
+export function checkGitTransport(url: string, transports: readonly string[]): TransportCheck {
+  if (url.startsWith('-')) {
+    return { ok: false, code: 'invalid_git_url', message: 'a git URL must not start with -' };
+  }
+
+  const transport = findTransport(url);
+
+  if (transports.includes(transport)) {
+    return { ok: true };
+  }
+
+  const allowed =
+    transports.length === 0
+      ? 'workspaces.gitTransports allows no transports'
+      : `the daemon fetches over ${transports.join(' and ')}`;
+
+  return {
+    ok: false,
+    code: 'invalid_git_url',
+    message: `git transport '${transport}' is not allowed; ${allowed}`,
+  };
+}
+
+function findTransport(url: string): string {
+  const helper = HELPER_PATTERN.exec(url)?.groups?.['name'];
+
+  if (helper !== undefined) {
+    return helper.toLowerCase();
+  }
+
+  const scheme = SCHEME_PATTERN.exec(url)?.groups?.['name']?.toLowerCase();
+
+  if (scheme !== undefined) {
+    return SSH_SCHEMES.has(scheme) ? 'ssh' : scheme;
+  }
+
+  return SCP_PATTERN.test(url) ? 'ssh' : 'file';
+}

package/src/workspace/check-repository-access.ts

@@ -0,0 +1,108 @@
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { collectRemoteRefs } from './collect-remote-refs';
+import type { RemoteRef } from './collect-remote-refs';
+import type { GitCredential } from './create-git-askpass';
+import { findRemoteRef } from './find-remote-ref';
+import { resolveGitURL } from './resolve-git-url';
+
+interface AccessRequest {
+  readonly url: string;
+
+  // At most one: a branch or tag to resolve to its commit, or a full
+  // commit id taken as it is.
+  readonly ref?: string | undefined;
+  readonly sha?: string | undefined;
+  readonly credential?: GitCredential | undefined;
+
+  // How long the listing may take; 20 s when unset.
+  readonly timeoutMs?: number | undefined;
+
+  // The transports the URL may use and git may fetch over.
+  readonly transports: readonly string[];
+}
+
+interface RepositoryAccess {
+  readonly ok: true;
+
+  // The URL a workspace spawn from this source clones.
+  readonly url: string;
+  readonly head: string | null;
+  readonly refs: readonly RemoteRef[];
+
+  // The commit the requested ref or sha selects, and the branch it is on;
+  // null when the request holds neither.
+  readonly resolved: {
+    readonly sha: string;
+    readonly branch: string | null;
+  } | null;
+}
+
+interface AccessRefusal {
+  readonly ok: false;
+  readonly code:
+    | 'clone_failed'
+    | 'credential_in_url'
+    | 'credential_missing'
+    | 'invalid_git_url'
+    | 'ref_not_found';
+  readonly message: string;
+}
+
+/**
+ * Checks that the daemon's host can read a git workspace source the way a
+ * workspace spawn from it would, without cloning: the URL resolves exactly
+ * as the materializer resolves it, against the git config of a fresh empty
+ * directory, and one `git ls-remote` authenticates exactly as the clone
+ * does. A readable upstream answers with its branches, tags, and default
+ * branch, and with the commit the requested ref points at now. A full
+ * commit id is taken as it is: a listing holds refs, not objects, so only
+ * the clone can tell that the upstream lacks it.
+ */
+export async function checkRepositoryAccess(
+  request: AccessRequest,
+): Promise<AccessRefusal | RepositoryAccess> {
+  const cwd = await mkdtemp(join(tmpdir(), 'atc-repo-access-'));
+
+  try {
+    const resolved = await resolveGitURL(request.url, cwd, request.transports);
+
+    if (!resolved.ok) {
+      return resolved;
+    }
+
+    const listing = await collectRemoteRefs(
+      resolved.url,
+      request.credential,
+      request.transports,
+      request.timeoutMs,
+    );
+
+    if (!listing.ok) {
+      return listing;
+    }
+
+    const access = { ok: true, url: resolved.url, head: listing.head, refs: listing.refs } as const;
+
+    if (request.sha !== undefined) {
+      return { ...access, resolved: { sha: request.sha, branch: null } };
+    }
+
+    if (request.ref === undefined) {
+      return { ...access, resolved: null };
+    }
+
+    const match = findRemoteRef(listing.byName, request.ref);
+
+    if (match === null) {
+      const name = request.ref.replace(/^refs\/(?:heads|tags)\//u, '');
+
+      return { ok: false, code: 'ref_not_found', message: `origin has no branch or tag '${name}'` };
+    }
+
+    return { ...access, resolved: match };
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+}