@sous-io/sous 0.1.1 → 0.2.1

package/src/lib/repos/providers/git.ts

@@ -0,0 +1,233 @@
+/**
+ * The one place the Repositories layer shells out.
+ *
+ * Every subprocess a provider runs (git itself, and the `gh` / `glab` CLIs when
+ * they are present and can hand over a token) goes through the helpers here, so
+ * failures are reported the same way everywhere: the command that was run, the
+ * exit code it returned, and whatever it wrote to stderr.
+ *
+ * The runner is injectable. Tests substitute their own, so no test in this
+ * layer ever spawns a process or touches the network.
+ */
+
+import { spawn } from "node:child_process";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { ConfigError } from "../../errors.js";
+
+/** What a finished subprocess reports back. */
+export type CommandResult = {
+  /** The process exit code; 0 on success. */
+  code: number;
+  stdout: string;
+  stderr: string;
+};
+
+/** How a command is run. Tests replace this with a function of their own. */
+export type CommandRunner = (
+  command: string,
+  args: string[],
+  options: { cwd?: string }
+) => Promise<CommandResult>;
+
+/**
+ * The default runner: spawns the command, captures both streams, and resolves
+ * once it exits. A command that cannot be started at all (it is not installed)
+ * resolves with exit code 127, so callers treat it as an ordinary failure.
+ *
+ * @param command - The executable to run.
+ * @param args - Its arguments, already split.
+ * @param options - Optional working directory.
+ */
+export const spawnCommand: CommandRunner = (command, args, options = {}) =>
+  new Promise<CommandResult>((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString();
+    });
+    child.stderr?.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString();
+    });
+
+    child.on("error", (error: Error) => {
+      resolve({ code: 127, stdout, stderr: `${stderr}${error.message}` });
+    });
+    child.on("close", (code) => {
+      resolve({ code: code ?? 1, stdout, stderr });
+    });
+  });
+
+/** Options shared by every subprocess helper here. */
+export type RunOptions = {
+  /** Directory to run in. */
+  cwd?: string;
+  /** The runner to use. Defaults to spawning a real process. */
+  run?: CommandRunner;
+};
+
+/** Renders a command and its arguments the way a user would have typed them. */
+function describeCommand(command: string, args: string[]): string {
+  return [command, ...args].join(" ");
+}
+
+/**
+ * Runs `git` with the given arguments and returns its standard output, trimmed.
+ * A non-zero exit is a ConfigError naming the command, the exit code and the
+ * error output, because that is what a user needs in order to fix it.
+ *
+ * @param args - Arguments to pass to git.
+ * @param options - Working directory and an optional runner override.
+ */
+export async function runGit(args: string[], options: RunOptions = {}): Promise<string> {
+  const run = options.run ?? spawnCommand;
+  const result = await run("git", args, { cwd: options.cwd });
+
+  if (result.code !== 0) {
+    const lines = [
+      `The command '${describeCommand("git", args)}' failed with exit code ${result.code}.`,
+    ];
+    if (options.cwd !== undefined) lines.push(`  It was run in ${options.cwd}.`);
+    const detail = result.stderr.trim() || result.stdout.trim();
+    if (detail.length > 0) {
+      for (const line of detail.split("\n")) lines.push(`  ${line}`);
+    }
+    if (result.code === 127) {
+      lines.push(
+        "  Sous fetches recipes with git, so git must be installed and on your PATH."
+      );
+    }
+    throw new ConfigError(lines.join("\n"));
+  }
+
+  return result.stdout.trim();
+}
+
+/**
+ * Runs a command that sous can do without, returning its trimmed output or
+ * undefined when it is missing, unauthenticated, or otherwise unhappy. Used for
+ * the optional `gh auth token` and `glab auth token` lookups: a missing CLI is
+ * never a reason to fail.
+ *
+ * @param command - The executable to try.
+ * @param args - Its arguments.
+ * @param options - Working directory and an optional runner override.
+ */
+export async function tryCommand(
+  command: string,
+  args: string[],
+  options: RunOptions = {}
+): Promise<string | undefined> {
+  const run = options.run ?? spawnCommand;
+  try {
+    const result = await run(command, args, { cwd: options.cwd });
+    if (result.code !== 0) return undefined;
+    const output = result.stdout.trim();
+    return output.length > 0 ? output : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Fetches ONE subtree of a repository at one tag, and nothing else.
+ *
+ * A shallow, blobless, sparse checkout is what makes this cheap: git downloads
+ * the commit at the tag, then only the blobs inside the recipe folder. Sous
+ * never copies a whole repository in order to install one recipe.
+ *
+ * The temporary checkout is made beside the destination rather than in the
+ * system temporary directory, so moving the subtree into place is a rename on
+ * one filesystem; a cross-device move still works, it just copies.
+ *
+ * @param options - The clone URL, the tag, the subtree and where it should land.
+ */
+export async function fetchSubtree(options: {
+  /** The repository's HTTPS clone URL. */
+  cloneUrl: string;
+  /** The git tag to fetch. */
+  tag: string;
+  /** The subtree's path, relative to the repository root. */
+  subPath: string;
+  /** Where the subtree's contents should end up. */
+  destDir: string;
+  /** How subprocesses are run. Defaults to spawning a real process. */
+  run?: CommandRunner;
+}): Promise<void> {
+  const { cloneUrl, tag, subPath, destDir } = options;
+  const parent = path.dirname(destDir);
+  await fs.mkdir(parent, { recursive: true });
+
+  const workDir = await fs.mkdtemp(path.join(parent, ".sous-fetch-"));
+  const checkoutDir = path.join(workDir, "checkout");
+
+  try {
+    await runGit(
+      [
+        "clone",
+        "--depth",
+        "1",
+        "--filter=blob:none",
+        "--sparse",
+        "--branch",
+        tag,
+        // Everything after this is a path or a URL, never an option, whatever it
+        // starts with. `repoUrlSchema` already refuses a leading hyphen; this is
+        // the second lock on the same door, and it is what `git-clone.ts` does.
+        "--",
+        cloneUrl,
+        checkoutDir,
+      ],
+      { run: options.run }
+    );
+    await runGit(["sparse-checkout", "set", subPath], {
+      cwd: checkoutDir,
+      run: options.run,
+    });
+
+    const source = path.join(checkoutDir, subPath);
+    if (!(await isDirectory(source))) {
+      throw new ConfigError(
+        `The repository ${cloneUrl} has no folder '${subPath}' at the tag '${tag}'.\n` +
+          `  The repository's index says the recipe lives there, so either the index is ` +
+          `out of date or the tag points at the wrong commit.`
+      );
+    }
+
+    await fs.rm(destDir, { recursive: true, force: true });
+    await movePath(source, destDir);
+  } finally {
+    await fs.rm(workDir, { recursive: true, force: true });
+  }
+}
+
+/** True when the path exists and is a directory. */
+async function isDirectory(candidate: string): Promise<boolean> {
+  try {
+    return (await fs.stat(candidate)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Moves a directory, falling back to a recursive copy when the source and the
+ * destination live on different filesystems.
+ *
+ * @param source - The directory to move.
+ * @param destination - Where it should end up.
+ */
+async function movePath(source: string, destination: string): Promise<void> {
+  try {
+    await fs.rename(source, destination);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EXDEV") throw error;
+    await fs.cp(source, destination, { recursive: true });
+    await fs.rm(source, { recursive: true, force: true });
+  }
+}

package/src/lib/repos/providers/github.ts

@@ -0,0 +1,294 @@
+/**
+ * The GitHub provider: the read path, and the write path behind it.
+ *
+ * Reading a repo needs no GitHub API and no `gh`: the index file is one raw
+ * HTTPS GET, and a recipe's subtree comes from git itself. A token is used when
+ * one is available, so private repositories work; it is read from GITHUB_TOKEN,
+ * or asked of the `gh` command line tool when that is installed and signed in.
+ * A missing `gh` is never an error on the read path.
+ *
+ * The write path is where `gh` becomes load-bearing, and this file is the ONLY
+ * place in sous that knows the command exists. Proposing a change is a pull
+ * request opened by `gh pr create`, a contributor without push permission works
+ * through a fork made by `gh repo fork`, and both are reported back as plain
+ * data, so the service that sequences them never learns a GitHub-shaped fact.
+ */
+
+import { ConfigError } from "../../errors.js";
+import { INDEX_FILENAME } from "../formats/common.js";
+import { ProviderBase, firstUrlIn } from "./base.js";
+import { fetchSubtree, type CommandRunner } from "./git.js";
+import { fetchText, type FetchLike } from "./http.js";
+import {
+  buildCanonicalRepo,
+  invalidRepoUrl,
+  splitRepoUrl,
+  type AuthStatus,
+  type CanonicalRepo,
+  type ChangeProposal,
+  type FetchedIndex,
+  type ForkedRepo,
+  type ProposedChange,
+  type ProviderCli,
+  type ProviderFeature,
+  type ProviderOptions,
+} from "./provider.js";
+
+/** The host this provider serves when a URL does not say otherwise. */
+export const GITHUB_HOST = "github.com";
+
+/** The environment variable a GitHub token is read from. */
+export const GITHUB_TOKEN_ENV = "GITHUB_TOKEN";
+
+/**
+ * Finds a GitHub token: the environment first, then `gh auth token` when the
+ * `gh` command line tool is installed and signed in. Returns undefined when
+ * there is none, because public repositories need no token at all.
+ *
+ * @param options - Environment and subprocess runner overrides.
+ */
+export async function findGithubToken(options: {
+  env?: NodeJS.ProcessEnv;
+  run?: CommandRunner;
+} = {}): Promise<string | undefined> {
+  return new GithubProvider().token(options);
+}
+
+/** The GitHub provider. */
+export class GithubProvider extends ProviderBase {
+  readonly id = "github" as const;
+
+  /**
+   * Reads the index and recipe subtrees, and proposes a change through
+   * the GitHub CLI ('gh').
+   */
+  readonly features: ProviderFeature[] = ["fetch", "submit"];
+
+  /** The command line tool the write path is built on. */
+  readonly cli: ProviderCli = {
+    command: "gh",
+    label: "the GitHub CLI",
+    install: "https://cli.github.com",
+  };
+
+  /** What GitHub calls a proposal. */
+  readonly proposalNoun = "pull request";
+
+  matches(url: string): boolean {
+    const parts = splitRepoUrl(url);
+    return parts !== undefined && parts.host === GITHUB_HOST;
+  }
+
+  canonicalize(url: string): CanonicalRepo {
+    const parts = splitRepoUrl(url);
+    if (parts === undefined) throw invalidRepoUrl(this.id, url);
+    return buildCanonicalRepo(parts.host, parts.owner, parts.name);
+  }
+
+  /**
+   * A GitHub token, from the environment or from `gh`. Public, because the
+   * index cache and the exported `findGithubToken` both ask for one.
+   *
+   * @param options - Environment and subprocess runner overrides.
+   */
+  async token(options: ProviderOptions = {}): Promise<string | undefined> {
+    return this.findToken(GITHUB_TOKEN_ENV, ["auth", "token"], options);
+  }
+
+  /**
+   * Fetches the repo's index file from the raw content host at the repository's
+   * default branch, which is what `HEAD` names there.
+   *
+   * @param repo - The canonicalized repository.
+   * @param options - Environment, fetch and subprocess overrides.
+   */
+  async fetchIndex(
+    repo: CanonicalRepo,
+    options: ProviderOptions = {}
+  ): Promise<FetchedIndex> {
+    const token = await this.token(options);
+    const url = this.indexUrl(repo);
+    const fetched = await fetchText(url, {
+      ...(token === undefined ? {} : { token }),
+      ...(options.fetchImpl === undefined
+        ? {}
+        : { fetchImpl: options.fetchImpl as FetchLike }),
+      label: "repo index",
+    });
+
+    return fetched.etag === undefined
+      ? { text: fetched.text, ref: "HEAD" }
+      : { text: fetched.text, ref: "HEAD", etag: fetched.etag };
+  }
+
+  /**
+   * Fetches one recipe folder at one tag. Private repositories work through
+   * git's own credential helpers, the same way a manual clone would.
+   *
+   * @param repo - The canonicalized repository.
+   * @param recipePath - The recipe folder, relative to the repository root.
+   * @param tag - The git tag carrying the version.
+   * @param destDir - Where the recipe's files should end up.
+   * @param options - Subprocess runner override.
+   */
+  async fetchRecipeTree(
+    repo: CanonicalRepo,
+    recipePath: string,
+    tag: string,
+    destDir: string,
+    options: ProviderOptions = {}
+  ): Promise<void> {
+    await fetchSubtree({
+      cloneUrl: repo.httpsUrl,
+      tag,
+      subPath: recipePath,
+      destDir,
+      ...(options.run === undefined ? {} : { run: options.run }),
+    });
+  }
+
+  /**
+   * The raw URL of a repository's index file at its default branch.
+   *
+   * @param repo - The canonicalized repository.
+   */
+  indexUrl(repo: CanonicalRepo): string {
+    return `https://raw.githubusercontent.com/${repo.owner}/${repo.name}/HEAD/${INDEX_FILENAME}`;
+  }
+
+  // --- The write path --------------------------------------------------------
+
+  /**
+   * Whether `gh` is installed and signed in. The detail is the whole
+   * explanation, ready to print, because only this provider knows what to
+   * install and which command signs in.
+   *
+   * @param options - Subprocess runner and working directory overrides.
+   */
+  async authStatus(options: ProviderOptions = {}): Promise<AuthStatus> {
+    const ok = await this.commandSucceeds(this.cli.command, ["auth", "status"], options);
+    if (ok) {
+      return {
+        ok: true,
+        detail: `${this.cli.label} ('${this.cli.command}') is installed and signed in.`,
+      };
+    }
+    return {
+      ok: false,
+      detail:
+        `Sous proposes a change through ${this.cli.label} ('${this.cli.command}'), and it is ` +
+        `either not installed or not signed in.\n` +
+        `  Install it from ${this.cli.install}, then run '${this.cli.command} auth login'.`,
+    };
+  }
+
+  /**
+   * Whether the signed-in contributor may push to the repository itself, as
+   * GitHub reports it. Undefined when `gh` could not answer at all, which is
+   * not the same as a refusal.
+   *
+   * @param repo - The canonicalized repository.
+   * @param options - Subprocess runner and working directory overrides.
+   */
+  async canPush(
+    repo: CanonicalRepo,
+    options: ProviderOptions = {}
+  ): Promise<boolean | undefined> {
+    const answer = await this.capturedOutput(
+      this.cli.command,
+      ["api", `repos/${repo.owner}/${repo.name}`, "--jq", ".permissions.push"],
+      options
+    );
+    if (answer === undefined) return undefined;
+    const value = answer.trim();
+    if (value === "true") return true;
+    if (value === "false") return false;
+    return undefined;
+  }
+
+  /**
+   * Forks the repository onto the contributor's own account and says where the
+   * fork landed. No remote is added here; that is git's business, and the
+   * service above does it with the URLs returned.
+   *
+   * @param repo - The canonicalized repository.
+   * @param options - Subprocess runner and working directory overrides.
+   */
+  async fork(repo: CanonicalRepo, options: ProviderOptions = {}): Promise<ForkedRepo> {
+    const forked = await this.runCommand(
+      this.cli.command,
+      ["repo", "fork", `${repo.owner}/${repo.name}`, "--remote=false"],
+      options
+    );
+    if (forked.code !== 0) {
+      throw new ConfigError(
+        `'${this.cli.command} repo fork' did not succeed.\n  ` +
+          `${forked.stderr.trim() || forked.stdout.trim()}`
+      );
+    }
+
+    const who = await this.capturedOutput(
+      this.cli.command,
+      ["api", "user", "--jq", ".login"],
+      options
+    );
+    if (who === undefined) {
+      throw new ConfigError(
+        "The fork was requested, but sous could not read your GitHub login from " +
+          `'${this.cli.command} api user', so it does not know where the fork lives.`
+      );
+    }
+
+    const owner = who.trim();
+    return {
+      owner,
+      name: repo.name,
+      httpsUrl: `https://${repo.host}/${owner}/${repo.name}.git`,
+      sshUrl: `git@${repo.host}:${owner}/${repo.name}.git`,
+    };
+  }
+
+  /**
+   * Opens a pull request for a branch that has already been pushed. A proposal
+   * carrying a head owner came from a fork, which is what a cross-repository
+   * pull request spells as `owner:branch`.
+   *
+   * @param repo - The canonicalized repository the proposal targets.
+   * @param proposal - The branch, the text and whether it is a draft.
+   * @param options - Subprocess runner and working directory overrides.
+   */
+  async proposeChange(
+    repo: CanonicalRepo,
+    proposal: ChangeProposal,
+    options: ProviderOptions = {}
+  ): Promise<ProposedChange> {
+    const head =
+      proposal.head === undefined
+        ? proposal.branch
+        : `${proposal.head.owner}:${proposal.branch}`;
+
+    const args = ["pr", "create", "--repo", `${repo.owner}/${repo.name}`];
+    if (proposal.base !== undefined) args.push("--base", proposal.base);
+    args.push("--head", head, "--title", proposal.title, "--body", proposal.body);
+    if (proposal.draft) args.push("--draft");
+
+    const result = await this.runCommand(this.cli.command, args, options);
+    if (result.code !== 0) {
+      const reported = result.stderr.trim() || result.stdout.trim();
+      throw new ConfigError(
+        `'${this.cli.command} pr create' did not succeed, so no proposal was opened.` +
+          (reported.length === 0 ? "" : `\n  ${reported}`)
+      );
+    }
+
+    const url = firstUrlIn(result.stdout);
+    if (url === undefined) {
+      return {
+        detail:
+          `The ${this.proposalNoun} was opened, but '${this.cli.command}' printed no address ` +
+          `for it.`,
+      };
+    }
+    return { url, detail: `The ${this.proposalNoun} is at ${url}.` };
+  }
+}