@sous-io/sous 0.2.37 → 1.0.2

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

@@ -1,268 +0,0 @@
-/**
- * The base class every built-in provider extends.
- *
- * It carries the plumbing no provider should repeat: running a subprocess
- * through the injectable runner, capturing what one printed, finding a token in
- * the environment or from the host's own command line tool, and pulling the
- * address out of a tool's output.
- *
- * It also answers the whole write path with a refusal. A provider that does not
- * declare the `submit` feature (the local one, for instance) inherits four
- * methods that raise a ConfigError naming the provider and what was asked of
- * it, so a caller that skips the feature check gets a sentence rather than a
- * `TypeError`. The three calls behind the `proposals` feature are refused the
- * same way.
- */
-
-import { ConfigError } from "../../errors.js";
-import {
-  spawnCommand,
-  tryCommand,
-  type CommandResult,
-  type CommandRunner,
-} from "./git.js";
-import type {
-  AuthStatus,
-  CanonicalRepo,
-  ChangeProposal,
-  FetchedIndex,
-  ForkedRepo,
-  ProposalQuery,
-  ProposalStatus,
-  ProposalSummary,
-  ProposalUpdate,
-  ProposedChange,
-  ProviderCli,
-  ProviderFeature,
-  ProviderId,
-  ProviderOptions,
-  RepoProvider,
-  LocationReading,
-  WrittenLocation,
-} from "./provider.js";
-
-/**
- * The first URL in a command's output, which is where a host's own tool prints
- * the thing it just created.
- *
- * firstUrlIn("https://github.com/o/r/pull/7\n"); // -> "https://github.com/o/r/pull/7"
- *
- * @param output - Whatever the command printed.
- */
-export function firstUrlIn(output: string): string | undefined {
-  const match = /https?:\/\/\S+/.exec(output);
-  return match === null ? undefined : match[0];
-}
-
-/** Everything a provider inherits rather than writes for itself. */
-export abstract class ProviderBase implements RepoProvider {
-  abstract readonly id: ProviderId;
-  abstract readonly features: ProviderFeature[];
-
-  abstract matches(url: string): boolean;
-  abstract canonicalize(url: string): CanonicalRepo;
-  abstract fetchIndex(repo: CanonicalRepo, options?: ProviderOptions): Promise<FetchedIndex>;
-  abstract fetchRecipeTree(
-    repo: CanonicalRepo,
-    recipePath: string,
-    tag: string,
-    destDir: string,
-    options?: ProviderOptions
-  ): Promise<void>;
-
-  // --- Reading a location ----------------------------------------------------
-
-  /** This provider's public host, declared by a provider that has one. */
-  declare readonly defaultHost?: string;
-
-  /**
-   * No readings: a provider that does not override this reads no location
-   * inside its repositories, so a ref naming one is refused with a sentence.
-   *
-   * @param _location - The written location; unused.
-   */
-  readLocation(_location: WrittenLocation): LocationReading[] {
-    return [];
-  }
-
-  /**
-   * `<id>://<host>/<repoPath>/<rest>`, with the host left out when it is this
-   * provider's default.
-   *
-   * @param host - The repository's host.
-   * @param repoPath - The repository's path on that host.
-   * @param rest - What is named inside it.
-   */
-  formatLocator(host: string, repoPath: string, rest: string): string {
-    const where = host === this.defaultHost ? repoPath : `${host}/${repoPath}`;
-    return `${this.id}://${where}${rest.length === 0 ? "" : `/${rest}`}`;
-  }
-
-  // --- Subprocess plumbing ---------------------------------------------------
-
-  /**
-   * The runner a call should use: the injected one when a caller supplied it,
-   * and a real process otherwise. Tests substitute their own, which is why no
-   * provider reaches for `spawn` directly.
-   *
-   * @param options - The call's options.
-   */
-  protected runnerFor(options: ProviderOptions): CommandRunner {
-    return options.run ?? spawnCommand;
-  }
-
-  /**
-   * Runs a command and hands back everything it reported, including a non-zero
-   * exit. A command that cannot be started at all comes back as exit code 127.
-   *
-   * @param command - The executable to run.
-   * @param args - Its arguments, already split.
-   * @param options - The call's options; `cwd` and `run` are used.
-   */
-  protected async runCommand(
-    command: string,
-    args: string[],
-    options: ProviderOptions = {}
-  ): Promise<CommandResult> {
-    return this.runnerFor(options)(command, args, { cwd: options.cwd });
-  }
-
-  /**
-   * True when a command ran and exited successfully, whatever it printed. Used
-   * for the checks whose answer is the exit code itself, such as `auth status`.
-   *
-   * @param command - The executable to run.
-   * @param args - Its arguments.
-   * @param options - The call's options.
-   */
-  protected async commandSucceeds(
-    command: string,
-    args: string[],
-    options: ProviderOptions = {}
-  ): Promise<boolean> {
-    try {
-      const result = await this.runCommand(command, args, options);
-      return result.code === 0;
-    } catch {
-      return false;
-    }
-  }
-
-  /**
-   * A command's trimmed standard output, or undefined when it did not succeed,
-   * is not installed, or printed nothing at all.
-   *
-   * @param command - The executable to run.
-   * @param args - Its arguments.
-   * @param options - The call's options.
-   */
-  protected async capturedOutput(
-    command: string,
-    args: string[],
-    options: ProviderOptions = {}
-  ): Promise<string | undefined> {
-    return tryCommand(command, args, {
-      ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
-      ...(options.run === undefined ? {} : { run: options.run }),
-    });
-  }
-
-  /**
-   * Finds a host token: the environment first, then the host's own command line
-   * tool when it is installed and signed in. Undefined is a normal answer,
-   * because a public repository needs no token at all.
-   *
-   * @param envName - The environment variable to read, such as `GITHUB_TOKEN`.
-   * @param args - The arguments that make the tool print a token.
-   * @param options - Environment and subprocess runner overrides.
-   */
-  protected async findToken(
-    envName: string,
-    args: string[],
-    options: ProviderOptions = {}
-  ): Promise<string | undefined> {
-    const env = options.env ?? process.env;
-    const fromEnv = env[envName];
-    if (fromEnv !== undefined && fromEnv.trim().length > 0) return fromEnv.trim();
-    if (this.cli === undefined) return undefined;
-    return this.capturedOutput(this.cli.command, args, options);
-  }
-
-  // --- The write path, refused unless a provider overrides it ----------------
-
-  /**
-   * The command line tool this provider drives, and what its proposals are
-   * called. Both are declared by the provider that has them; `declare` here
-   * only tells the type system they may exist, so a subclass's own field is the
-   * one that ends up on the instance.
-   */
-  declare readonly cli?: ProviderCli;
-  declare readonly proposalNoun?: string;
-
-  async authStatus(_options: ProviderOptions = {}): Promise<AuthStatus> {
-    throw this.unsupported("submit", "check whether you are signed in to it");
-  }
-
-  async canPush(
-    _repo: CanonicalRepo,
-    _options: ProviderOptions = {}
-  ): Promise<boolean | undefined> {
-    throw this.unsupported("submit", "check whether you can push to it");
-  }
-
-  async fork(_repo: CanonicalRepo, _options: ProviderOptions = {}): Promise<ForkedRepo> {
-    throw this.unsupported("submit", "fork it on your behalf");
-  }
-
-  async proposeChange(
-    _repo: CanonicalRepo,
-    _proposal: ChangeProposal,
-    _options: ProviderOptions = {}
-  ): Promise<ProposedChange> {
-    throw this.unsupported("submit", "propose a change to it");
-  }
-
-  // --- Proposals after the fact, refused unless a provider overrides them ----
-
-  async findProposal(
-    _repo: CanonicalRepo,
-    _query: ProposalQuery,
-    _options: ProviderOptions = {}
-  ): Promise<ProposalSummary | undefined> {
-    throw this.unsupported("proposals", "look for a proposal that is already open");
-  }
-
-  async proposalStatus(
-    _repo: CanonicalRepo,
-    _id: string,
-    _options: ProviderOptions = {}
-  ): Promise<ProposalStatus> {
-    throw this.unsupported("proposals", "report where a proposal stands");
-  }
-
-  async updateProposal(
-    _repo: CanonicalRepo,
-    _id: string,
-    _update: ProposalUpdate,
-    _options: ProviderOptions = {}
-  ): Promise<ProposedChange> {
-    throw this.unsupported("proposals", "change a proposal's title or body");
-  }
-
-  /**
-   * The refusal a provider gives when it is asked for something it never
-   * claimed. It names the provider and the feature, so the caller learns why
-   * rather than only that.
-   *
-   * @param feature - The feature the call belongs to.
-   * @param what - What was being attempted, in plain language.
-   */
-  protected unsupported(feature: ProviderFeature, what: string): ConfigError {
-    return new ConfigError(
-      `The '${this.id}' provider does not support the '${feature}' feature, so sous cannot ` +
-        `${what}.\n` +
-        `  A provider answers only what its features promise; this one promises ` +
-        `${this.features.map((entry) => `'${entry}'`).join(", ")}.`
-    );
-  }
-}

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

@@ -1,245 +0,0 @@
-/**
- * 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";
-import { LF_CHECKOUT_OPTIONS } from "../store/hash.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;
-    /**
-     * Start the command through the shell. Only for a fixed command line: it
-     * is how Windows finds a `.cmd` shim such as npm's.
-     */
-    shell?: boolean;
-  }
-) => 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, and whether to start it through the shell.
- */
-export const spawnCommand: CommandRunner = (command, args, options = {}) =>
-  new Promise<CommandResult>((resolve) => {
-    const child = spawn(command, args, {
-      cwd: options.cwd,
-      stdio: ["ignore", "pipe", "pipe"],
-      shell: options.shell === true,
-    });
-
-    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",
-        // The fetched subtree is hashed against its pin, so its bytes must be the
-        // committed ones whatever this machine's line-ending settings are.
-        ...LF_CHECKOUT_OPTIONS,
-        "--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 });
-  }
-}