@zgeoff/atc 2.11.0 → 2.12.0

package/src/workspace/check-workspace-completeness.ts

@@ -0,0 +1,90 @@
+import { runGit } from './run-git';
+
+type CompletenessFinding =
+  | { readonly ok: true }
+  | {
+      readonly ok: false;
+      readonly code: 'has_submodules' | 'unreadable_tree';
+      readonly message: string;
+    }
+  | {
+      readonly ok: false;
+      readonly code: 'lfs_unsupported';
+      readonly message: string;
+      readonly count: number;
+      readonly paths: readonly string[];
+    };
+
+const LFS_PATHS_SHOWN = 5;
+
+/**
+ * Checks that a checked-out commit is the whole workspace, so a checkout is
+ * never handed on with holes in it. The commit's own tree must hold no
+ * gitlink and no `.gitmodules`, since submodules are never initialized, and
+ * no tracked path may carry the `lfs` filter, since its content would be a
+ * pointer file rather than the object it points at.
+ */
+export async function checkWorkspaceCompleteness(
+  dir: string,
+  sha: string,
+): Promise<CompletenessFinding> {
+  const tree = await runGit(['ls-tree', '-r', '--full-tree', sha], { cwd: dir, isolated: true });
+
+  if (tree.exitCode !== 0) {
+    return {
+      ok: false,
+      code: 'unreadable_tree',
+      message: `cannot list the tree of ${sha}: ${tree.stderr.trim()}`,
+    };
+  }
+
+  const entries = tree.stdout.split('\n');
+
+  if (entries.some((line) => line.startsWith('160000 ') || line.endsWith('\t.gitmodules'))) {
+    return { ok: false, code: 'has_submodules', message: `${sha} uses submodules` };
+  }
+
+  const tracked = await runGit(['ls-files', '-z'], { cwd: dir, isolated: true });
+
+  const attributes = await runGit(['check-attr', '--stdin', '-z', 'filter'], {
+    cwd: dir,
+    input: tracked.stdout,
+    isolated: true,
+  });
+
+  if (tracked.exitCode !== 0 || attributes.exitCode !== 0) {
+    return {
+      ok: false,
+      code: 'unreadable_tree',
+      message: `cannot read the attributes of ${sha}: ${tracked.stderr.trim()}${attributes.stderr.trim()}`,
+    };
+  }
+
+  const lfsPaths = collectLFSPaths(attributes.stdout);
+
+  if (lfsPaths.length > 0) {
+    return {
+      ok: false,
+      code: 'lfs_unsupported',
+      message: `${sha} tracks ${lfsPaths.length} path(s) through Git LFS`,
+      count: lfsPaths.length,
+      paths: lfsPaths.slice(0, LFS_PATHS_SHOWN),
+    };
+  }
+
+  return { ok: true };
+}
+
+// `check-attr -z` writes one path, attribute, value triple per path.
+function collectLFSPaths(output: string): string[] {
+  const fields = output.split('\0');
+  const paths: string[] = [];
+
+  for (let index = 0; index + 2 < fields.length; index += 3) {
+    if (fields[index + 2] === 'lfs') {
+      paths.push(fields[index] ?? '');
+    }
+  }
+
+  return paths;
+}

package/src/workspace/create-workspace-clone.ts

@@ -0,0 +1,239 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { checkWorkspaceCompleteness } from './check-workspace-completeness';
+import { runGit } from './run-git';
+import type { WorkspaceSource } from './workspace-source';
+
+interface GitCredential {
+  readonly kind: 'env';
+  readonly name: string;
+}
+
+interface CloneRequest {
+  readonly source: Extract<WorkspaceSource, { readonly kind: 'git' }>;
+  readonly dir: string;
+  readonly credential?: GitCredential;
+}
+
+interface CreatedClone {
+  readonly ok: true;
+  readonly sha: string;
+  readonly branch: string | null;
+}
+
+interface CloneRefusal {
+  readonly ok: false;
+  readonly code: 'credential_missing' | 'ref_not_found' | 'clone_failed';
+  readonly message: string;
+}
+
+type IncompleteCheckout = Exclude<
+  Awaited<ReturnType<typeof checkWorkspaceCompleteness>>,
+  { readonly ok: true }
+>;
+
+/**
+ * Clones a repository into an empty directory and checks out the commit its
+ * ref points at that moment. A branch ref is checked out as that branch; a tag
+ * or a full commit id leaves HEAD detached at the commit. The clone copies
+ * objects rather than hard-linking them, takes no hook templates, and runs no
+ * hooks on checkout.
+ *
+ * The checked-out commit must be the whole workspace: one that uses
+ * submodules or tracks paths through Git LFS is refused and the directory is
+ * removed. The clone fetches without checking out, and the checkout then
+ * runs isolated from the host's system and global git config, so no filter
+ * the host configured, LFS or otherwise, runs or reaches the network.
+ *
+ * Without a credential, git authenticates through the host's own git
+ * config. An env credential is read from the named variable and handed to git
+ * only through a private askpass helper for the network commands, never
+ * through the command line or the URL, and the helper is deleted before this
+ * returns. The host's credential helpers are switched off for those commands
+ * so none of them stores the token.
+ */
+export async function createWorkspaceClone(
+  request: CloneRequest,
+): Promise<CloneRefusal | CreatedClone | IncompleteCheckout> {
+  const askpass = await createAskpass(request.credential);
+
+  if (!askpass.ok) {
+    return askpass;
+  }
+
+  try {
+    return await createCloneAtRef(request, askpass.env, askpass.args);
+  } finally {
+    await askpass[Symbol.asyncDispose]();
+  }
+}
+
+interface Askpass {
+  readonly ok: true;
+  readonly env: Readonly<Record<string, string>>;
+  readonly args: readonly string[];
+  [Symbol.asyncDispose]: () => Promise<void>;
+}
+
+const ASKPASS_SECRET_VAR = 'ATC_GIT_ASKPASS_SECRET';
+
+// Username prompts get a fixed name that GitHub and GitLab both accept
+// alongside a token; password prompts get the token.
+const ASKPASS_SCRIPT = `#!/bin/sh
+case "$1" in
+  Username*) printf '%s\\n' x-access-token ;;
+  *) printf '%s\\n' "$${ASKPASS_SECRET_VAR}" ;;
+esac
+`;
+
+async function createAskpass(
+  credential: GitCredential | undefined,
+): Promise<Askpass | CloneRefusal> {
+  if (credential === undefined) {
+    return { ok: true, env: {}, args: [], [Symbol.asyncDispose]: async () => {} };
+  }
+
+  const secret = process.env[credential.name];
+
+  if (secret === undefined || secret === '') {
+    return {
+      ok: false,
+      code: 'credential_missing',
+      message: 'the credential environment variable is unset or empty',
+    };
+  }
+
+  const dir = await mkdtemp(join(tmpdir(), 'atc-askpass-'));
+
+  const helper = join(dir, 'askpass');
+
+  await writeFile(helper, ASKPASS_SCRIPT, { mode: 0o700 });
+
+  return {
+    ok: true,
+    env: { GIT_ASKPASS: helper, [ASKPASS_SECRET_VAR]: secret },
+    args: ['-c', 'credential.helper='],
+    [Symbol.asyncDispose]: async () => {
+      await rm(dir, { recursive: true, force: true });
+    },
+  };
+}
+
+async function createCloneAtRef(
+  request: CloneRequest,
+  env: Readonly<Record<string, string>>,
+  args: readonly string[],
+): Promise<CloneRefusal | CreatedClone | IncompleteCheckout> {
+  const target = await resolveRef(request.source, env, args);
+
+  if (!target.ok) {
+    return target;
+  }
+
+  const clone = await runGit(
+    [
+      ...args,
+      'clone',
+      '--quiet',
+      '--no-local',
+      '--no-hardlinks',
+      '--no-checkout',
+      '--template=',
+      '--',
+      request.source.url,
+      request.dir,
+    ],
+    { env },
+  );
+
+  if (clone.exitCode !== 0) {
+    return { ok: false, code: 'clone_failed', message: clone.stderr.trim() };
+  }
+
+  const checkout = await runGit(
+    [
+      '-c',
+      'core.hooksPath=/dev/null',
+      'checkout',
+      '--quiet',
+      ...(target.branch === null ? ['--detach', target.sha] : ['-B', target.branch, target.sha]),
+    ],
+    { cwd: request.dir, isolated: true },
+  );
+
+  if (checkout.exitCode !== 0) {
+    await rm(request.dir, { recursive: true, force: true });
+
+    return { ok: false, code: 'clone_failed', message: checkout.stderr.trim() };
+  }
+
+  const complete = await checkWorkspaceCompleteness(request.dir, target.sha);
+
+  if (!complete.ok) {
+    await rm(request.dir, { recursive: true, force: true });
+
+    return complete;
+  }
+
+  return { ok: true, sha: target.sha, branch: target.branch };
+}
+
+interface ResolvedRef {
+  readonly ok: true;
+  readonly sha: string;
+  readonly branch: string | null;
+}
+
+const SHA_PATTERN = /^(?:[\da-f]{40}|[\da-f]{64})$/u;
+
+/**
+ * Pins a ref to a commit before cloning, so the checkout is exactly the
+ * commit the ref pointed at when asked, whatever lands on the branch meanwhile.
+ * A branch wins over a same-named tag, and an annotated tag resolves to the
+ * commit it points at.
+ */
+async function resolveRef(
+  source: Extract<WorkspaceSource, { readonly kind: 'git' }>,
+  env: Readonly<Record<string, string>>,
+  args: readonly string[],
+): Promise<CloneRefusal | ResolvedRef> {
+  if (SHA_PATTERN.test(source.ref)) {
+    return { ok: true, sha: source.ref, branch: null };
+  }
+
+  const listed = await runGit(
+    [...args, 'ls-remote', '--', source.url, source.ref, `${source.ref}^{}`],
+    { env },
+  );
+
+  if (listed.exitCode !== 0) {
+    return { ok: false, code: 'clone_failed', message: listed.stderr.trim() };
+  }
+
+  const refs = new Map(
+    listed.stdout
+      .split('\n')
+      .filter((line) => line !== '')
+      .map((line) => {
+        const [sha = '', name = ''] = line.split('\t');
+
+        return [name, sha] as const;
+      }),
+  );
+
+  const name = source.ref.replace(/^refs\/(?:heads|tags)\//u, '');
+  const branchSHA = refs.get(`refs/heads/${name}`);
+
+  if (branchSHA !== undefined && !source.ref.startsWith('refs/tags/')) {
+    return { ok: true, sha: branchSHA, branch: name };
+  }
+
+  const tagSHA = refs.get(`refs/tags/${name}^{}`) ?? refs.get(`refs/tags/${name}`);
+
+  if (tagSHA !== undefined && !source.ref.startsWith('refs/heads/')) {
+    return { ok: true, sha: tagSHA, branch: null };
+  }
+
+  return { ok: false, code: 'ref_not_found', message: `origin has no branch or tag '${name}'` };
+}

package/src/workspace/normalize-git-url.ts

@@ -0,0 +1,59 @@
+type NormalizedGitURL =
+  | { readonly ok: true; readonly url: string }
+  | { readonly ok: false; readonly code: 'invalid_git_url'; readonly message: string };
+
+const SCHEME_PATTERN = /^[a-z][a-z\d+.-]*:\/\//iu;
+const SCP_PATTERN = /^(?:[^@/:\s]+@)?[^@/:\s]+:[^@\s]+$/u;
+const SHORTHAND_PATTERN = /^[\w.-]+\/[\w.-]+$/u;
+
+/**
+ * Reduces a repository URL to a form that carries no credential, so it can be
+ * recorded, shown, and handed to another host. An http(s) URL loses its
+ * userinfo, query, and fragment, where tokens ride. Any other scheme URL
+ * loses its password but keeps its user, which is a login name such as
+ * `git`. An scp-style `git@host:owner/repo` and a local path pass through,
+ * and a bare `owner/repo` expands to its GitHub https URL.
+ */
+export function normalizeGitURL(raw: string): NormalizedGitURL {
+  const trimmed = raw.trim();
+
+  if (SCHEME_PATTERN.test(trimmed)) {
+    return normalizeSchemeURL(trimmed);
+  }
+
+  if (trimmed.startsWith('/')) {
+    return { ok: true, url: trimmed };
+  }
+
+  if (SHORTHAND_PATTERN.test(trimmed) && !trimmed.startsWith('.')) {
+    return { ok: true, url: `https://github.com/${trimmed.replace(/\.git$/u, '')}.git` };
+  }
+
+  if (SCP_PATTERN.test(trimmed)) {
+    return { ok: true, url: trimmed };
+  }
+
+  return { ok: false, code: 'invalid_git_url', message: 'not a git repository URL' };
+}
+
+const HTTP_PROTOCOLS: ReadonlySet<string> = new Set(['http:', 'https:']);
+
+function normalizeSchemeURL(raw: string): NormalizedGitURL {
+  let url: URL;
+
+  try {
+    url = new URL(raw);
+  } catch {
+    return { ok: false, code: 'invalid_git_url', message: 'not a parseable repository URL' };
+  }
+
+  url.password = '';
+
+  if (HTTP_PROTOCOLS.has(url.protocol)) {
+    url.username = '';
+    url.search = '';
+    url.hash = '';
+  }
+
+  return { ok: true, url: url.toString() };
+}

package/src/workspace/read-workspace-tar.ts

@@ -0,0 +1,38 @@
+type TarOutcome =
+  | { readonly ok: true }
+  | { readonly ok: false; readonly code: 'tar_failed'; readonly message: string };
+
+interface WorkspaceTar {
+  readonly stream: ReadableStream<Uint8Array>;
+  readonly done: Promise<TarOutcome>;
+}
+
+/**
+ * Streams an uncompressed tar of a directory, `.git` included, with entries
+ * relative to the directory. The archive is read as it is produced and never
+ * written to disk. A failure partway through still ends the stream, so a
+ * consumer drains it and then awaits the outcome before trusting what it
+ * received. Options the host passes to GNU tar through `TAR_OPTIONS` are
+ * ignored, since one could follow symlinks out of the directory or leave
+ * files out.
+ */
+export function readWorkspaceTar(dir: string): WorkspaceTar {
+  const { TAR_OPTIONS: _ignored, ...env } = process.env;
+
+  const proc = Bun.spawn(['tar', '-c', '-f', '-', '-C', dir, '.'], {
+    env,
+    stdin: 'ignore',
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  const done = (async (): Promise<TarOutcome> => {
+    const [stderr, exitCode] = await Promise.all([new Response(proc.stderr).text(), proc.exited]);
+
+    return exitCode === 0
+      ? { ok: true }
+      : { ok: false, code: 'tar_failed', message: stderr.trim() };
+  })();
+
+  return { stream: proc.stdout, done };
+}

package/src/workspace/resolve-path-source.ts

@@ -0,0 +1,170 @@
+import { statSync } from 'node:fs';
+import { normalizeGitURL } from './normalize-git-url';
+import { runGit } from './run-git';
+
+interface PathSourceOptions {
+  readonly allowDirty?: 'refuse' | 'warn';
+}
+
+interface ResolvedPathSource {
+  readonly ok: true;
+  readonly url: string;
+  readonly sha: string;
+  readonly branch: string | null;
+  readonly dirty: boolean;
+  readonly warnings: readonly string[];
+}
+
+type PathSourceRefusalCode =
+  | 'not_a_git_repo'
+  | 'no_commits'
+  | 'unreadable_tree'
+  | 'has_submodules'
+  | 'workspace_dirty'
+  | 'no_origin'
+  | 'invalid_git_url'
+  | 'unpushed_head';
+
+interface PathSourceRefusal {
+  readonly ok: false;
+  readonly code: PathSourceRefusalCode;
+  readonly message: string;
+}
+
+/**
+ * Turns a local checkout into the repository URL and commit another host
+ * can clone, so a workspace never carries files that exist only here. The
+ * commit is HEAD, and it must already be on origin: a remote-tracking ref
+ * under origin contains it, or origin advertises it as a ref tip. A tree
+ * with uncommitted or untracked changes is refused, or with `allowDirty:
+ * 'warn'` resolves to HEAD and leaves those changes behind with a warning.
+ * Submodules are refused. The URL is origin's, with any credential stripped.
+ */
+export async function resolvePathSource(
+  path: string,
+  options: PathSourceOptions = {},
+): Promise<PathSourceRefusal | ResolvedPathSource> {
+  if (statSync(path, { throwIfNoEntry: false })?.isDirectory() !== true) {
+    return { ok: false, code: 'not_a_git_repo', message: `${path} is not a directory` };
+  }
+
+  const toplevel = await runGit(['rev-parse', '--show-toplevel'], { cwd: path });
+
+  if (toplevel.exitCode !== 0) {
+    return { ok: false, code: 'not_a_git_repo', message: `${path} is not inside a git work tree` };
+  }
+
+  const root = toplevel.stdout.trim();
+
+  const head = await runGit(['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], { cwd: root });
+
+  if (head.exitCode !== 0) {
+    return { ok: false, code: 'no_commits', message: `${root} has no commit to check out` };
+  }
+
+  const sha = head.stdout.trim();
+
+  const tree = await runGit(['ls-tree', '-r', '--full-tree', sha], { cwd: root });
+
+  if (tree.exitCode !== 0) {
+    return {
+      ok: false,
+      code: 'unreadable_tree',
+      message: `cannot list the tree of ${sha} in ${root}: ${tree.stderr.trim()}`,
+    };
+  }
+
+  if (hasSubmodules(tree.stdout)) {
+    return { ok: false, code: 'has_submodules', message: `${root} uses submodules` };
+  }
+
+  const status = await runGit(['status', '--porcelain', '--untracked-files=normal'], { cwd: root });
+
+  if (status.exitCode !== 0) {
+    return {
+      ok: false,
+      code: 'unreadable_tree',
+      message: `cannot read the status of ${root}: ${status.stderr.trim()}`,
+    };
+  }
+
+  const dirty = status.stdout.trim() !== '';
+  const warnings: string[] = [];
+
+  if (dirty && options.allowDirty !== 'warn') {
+    return {
+      ok: false,
+      code: 'workspace_dirty',
+      message: `${root} has uncommitted or untracked changes`,
+    };
+  }
+
+  if (dirty) {
+    warnings.push(`uncommitted and untracked changes in ${root} stay behind; using ${sha}`);
+  }
+
+  const origin = await runGit(['ls-remote', '--get-url', 'origin'], { cwd: root });
+
+  const originURL = origin.stdout.trim();
+
+  // With no origin configured, git echoes the remote name back.
+  if (origin.exitCode !== 0 || originURL === '' || originURL === 'origin') {
+    return { ok: false, code: 'no_origin', message: `${root} has no origin remote` };
+  }
+
+  const url = normalizeGitURL(originURL);
+
+  if (!url.ok) {
+    return { ok: false, code: url.code, message: `origin of ${root}: ${url.message}` };
+  }
+
+  const pushed = await isOnOrigin(root, sha);
+
+  if (!pushed) {
+    return { ok: false, code: 'unpushed_head', message: `${sha} is not on origin; push it first` };
+  }
+
+  const branch = await runGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], { cwd: root });
+
+  return {
+    ok: true,
+    url: url.url,
+    sha,
+    branch: branch.exitCode === 0 ? branch.stdout.trim() : null,
+    dirty,
+    warnings,
+  };
+}
+
+/**
+ * Whether a recursive tree listing holds a gitlink or a `.gitmodules` file at
+ * its root. A workspace clone never initializes submodules, so either would
+ * ship an incomplete tree.
+ */
+function hasSubmodules(listing: string): boolean {
+  return listing
+    .split('\n')
+    .some((line) => line.startsWith('160000 ') || line.endsWith('\t.gitmodules'));
+}
+
+/**
+ * Whether origin already has the commit. A local remote-tracking ref proves
+ * it without network access; failing that, origin's advertised ref tips are
+ * checked, which catches a push whose tracking ref was never fetched.
+ */
+async function isOnOrigin(root: string, sha: string): Promise<boolean> {
+  const tracking = await runGit(['branch', '-r', '--contains', sha, '--list', 'origin/*'], {
+    cwd: root,
+  });
+
+  if (tracking.exitCode === 0 && tracking.stdout.trim() !== '') {
+    return true;
+  }
+
+  const advertised = await runGit(['ls-remote', 'origin'], { cwd: root });
+
+  return (
+    advertised.exitCode === 0 &&
+    advertised.stdout.split('\n').some((line) => line.split('\t')[0] === sha)
+  );
+}

package/src/workspace/run-git.ts

@@ -0,0 +1,103 @@
+interface GitRunOptions {
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string>>;
+  readonly input?: string;
+  readonly isolated?: boolean;
+}
+
+interface GitRun {
+  readonly exitCode: number;
+  readonly stdout: string;
+  readonly stderr: string;
+}
+
+/**
+ * Runs one git command to completion, feeding it any given input, and
+ * returns its exit code and output.
+ * git never prompts on a terminal here, since the daemon has none to answer
+ * with, and its messages stay in the C locale so callers can read them.
+ * Variables that pin git to some other repository, such as the `GIT_DIR` a
+ * git hook exports, are dropped so the command acts on its own directory.
+ *
+ * An isolated command reads only the repository's own config and
+ * attributes: the host's system and global config and its system and global
+ * attributes files are ignored, and every LFS filter is switched off. A
+ * checkout run this way runs no filter the host configured, so it can
+ * neither execute host code nor reach the network with the host's
+ * credentials.
+ */
+const ISOLATED_ARGS = [
+  '-c',
+  'core.attributesFile=/dev/null',
+  '-c',
+  'filter.lfs.smudge=',
+  '-c',
+  'filter.lfs.process=',
+  '-c',
+  'filter.lfs.required=false',
+];
+
+const ISOLATED_ENV = {
+  GIT_CONFIG_NOSYSTEM: '1',
+  GIT_ATTR_NOSYSTEM: '1',
+  GIT_CONFIG_GLOBAL: '/dev/null',
+  GIT_LFS_SKIP_SMUDGE: '1',
+};
+
+export async function runGit(
+  args: readonly string[],
+  options: GitRunOptions = {},
+): Promise<GitRun> {
+  const isolated = options.isolated === true;
+
+  const proc = Bun.spawn(['git', ...(isolated ? ISOLATED_ARGS : []), ...args], {
+    ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+    env: {
+      ...collectHostEnv(),
+      ...options.env,
+      ...(isolated ? ISOLATED_ENV : {}),
+      GIT_TERMINAL_PROMPT: '0',
+      LC_ALL: 'C',
+    },
+    stdin: options.input === undefined ? 'ignore' : Buffer.from(options.input),
+    stdout: 'pipe',
+    stderr: 'pipe',
+  });
+
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+
+  return { exitCode, stdout, stderr };
+}
+
+const REPOSITORY_ENV_VARS: ReadonlySet<string> = new Set([
+  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
+  'GIT_COMMON_DIR',
+  'GIT_CONFIG',
+  'GIT_CONFIG_COUNT',
+  'GIT_CONFIG_PARAMETERS',
+  'GIT_DIR',
+  'GIT_GRAFT_FILE',
+  'GIT_IMPLICIT_WORK_TREE',
+  'GIT_INDEX_FILE',
+  'GIT_NO_REPLACE_OBJECTS',
+  'GIT_OBJECT_DIRECTORY',
+  'GIT_PREFIX',
+  'GIT_REPLACE_REF_BASE',
+  'GIT_SHALLOW_FILE',
+  'GIT_WORK_TREE',
+]);
+
+function collectHostEnv(): Record<string, string | undefined> {
+  return Object.fromEntries(
+    Object.entries(process.env).filter(
+      ([name]) =>
+        !REPOSITORY_ENV_VARS.has(name) &&
+        !name.startsWith('GIT_CONFIG_KEY_') &&
+        !name.startsWith('GIT_CONFIG_VALUE_'),
+    ),
+  );
+}