@sous-io/sous 0.2.37 → 1.0.1

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

@@ -1,332 +0,0 @@
-/**
- * The GitLab provider: the read path, and as much of the write path as GitLab
- * honestly gives sous.
- *
- * The read shape is the same as the GitHub provider's: the index file is one raw
- * HTTPS GET, and a recipe's subtree comes from git. A token is used when one is
- * available, read from GITLAB_TOKEN or asked of the `glab` command line tool
- * when that is installed and signed in; a missing `glab` is never an error on
- * the read path.
- *
- * The write path is one merge request opened by `glab mr create`, from a branch
- * the contributor can already push. Sous does not fork on GitLab: there is no
- * fork-and-track flow here that sous can carry out without guessing, so
- * `canPush` answers "cannot tell" rather than inventing a permission, and `fork`
- * refuses with the manual route spelled out. Saying so is the point; pretending
- * otherwise would strand a contributor halfway through a submission.
- *
- * Self-hosted instances are supported: any host whose name begins with `gitlab.`
- * is recognized automatically, and a repository entry may always name its
- * provider outright for a host that gives nothing away.
- */
-
-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,
-  readingsAfterRepository,
-  splitRepoUrl,
-  withoutGitSuffix,
-  type LocationReading,
-  type WrittenLocation,
-  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 GITLAB_HOST = "gitlab.com";
-
-/** The environment variable a GitLab token is read from. */
-export const GITLAB_TOKEN_ENV = "GITLAB_TOKEN";
-
-/**
- * Finds a GitLab token: the environment first, then `glab auth token` when the
- * `glab` 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 findGitlabToken(options: {
-  env?: NodeJS.ProcessEnv;
-  run?: CommandRunner;
-} = {}): Promise<string | undefined> {
-  return new GitlabProvider().token(options);
-}
-
-/** The GitLab provider. */
-export class GitlabProvider extends ProviderBase {
-  readonly id = "gitlab" as const;
-
-  /**
-   * Reads the index and recipe subtrees, and proposes a change through
-   * the GitLab CLI ('glab').
-   */
-  readonly features: ProviderFeature[] = ["fetch", "submit"];
-
-  /** The command line tool the write path is built on. */
-  readonly cli: ProviderCli = {
-    command: "glab",
-    label: "the GitLab CLI",
-    install: "https://gitlab.com/gitlab-org/cli",
-  };
-
-  /** What GitLab calls a proposal. */
-  readonly proposalNoun = "merge request";
-
-  /** The host a `gitlab://` locator means when it names none. */
-  readonly defaultHost = GITLAB_HOST;
-
-  /**
-   * A GitLab project path nests (`group/subgroup/project`), so where it ends is
-   * only certain when the location says so: a `-` segment (GitLab's own
-   * separator, as in `/-/tree/main/...`) or a `.git` suffix ends it. Otherwise
-   * every split that leaves a project of at least two segments and at most a
-   * namespace and a recipe after it is a reading, and the caller keeps the one
-   * an index confirms.
-   *
-   * readLocation({ host: "gitlab.com", segments: ["a", "b", "c", "d"] });
-   * // -> project "a/b" naming "c/d", project "a/b/c" naming "d",
-   * //    and project "a/b/c/d" naming nothing
-   *
-   * @param location - The host and the segments after it.
-   */
-  readLocation(location: WrittenLocation): LocationReading[] {
-    const { segments } = location;
-
-    const separator = segments.indexOf("-");
-    if (separator >= 2) {
-      return readingsAfterRepository(
-        this.projectPath(segments.slice(0, separator)),
-        segments.slice(separator)
-      );
-    }
-
-    const suffixed = segments.findIndex((segment) => /\.git$/i.test(segment));
-    if (suffixed >= 1) {
-      return readingsAfterRepository(
-        this.projectPath(segments.slice(0, suffixed + 1)),
-        segments.slice(suffixed + 1)
-      );
-    }
-
-    const readings: LocationReading[] = [];
-    for (let end = 2; end <= segments.length; end++) {
-      const rest = segments.slice(end);
-      if (rest.length > 2) continue;
-      readings.push({ repoPath: this.projectPath(segments.slice(0, end)), named: rest });
-    }
-    return readings;
-  }
-
-  /**
-   * The canonical locator always marks where the project path ends with `-`,
-   * because without it a nested group reads more than one way.
-   *
-   * @param host - The project's host.
-   * @param repoPath - The project'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}`}`;
-  }
-
-  /** A project path from its segments, with the last one's `.git` gone. */
-  private projectPath(segments: string[]): string {
-    const last = segments.length - 1;
-    return segments.map((segment, index) => (index === last ? withoutGitSuffix(segment) : segment)).join("/");
-  }
-
-  matches(url: string): boolean {
-    const parts = splitRepoUrl(url);
-    if (parts === undefined) return false;
-    return parts.host === GITLAB_HOST || parts.host.startsWith("gitlab.");
-  }
-
-  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 GitLab token, from the environment or from `glab`.
-   *
-   * @param options - Environment and subprocess runner overrides.
-   */
-  async token(options: ProviderOptions = {}): Promise<string | undefined> {
-    return this.findToken(GITLAB_TOKEN_ENV, ["auth", "token"], options);
-  }
-
-  /**
-   * Fetches the repo's index file from the instance's raw file endpoint at the
-   * repository's default branch.
-   *
-   * @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 }),
-      ...(options.signal === undefined ? {} : { signal: options.signal }),
-      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://${repo.host}/${repo.owner}/${repo.name}/-/raw/HEAD/${INDEX_FILENAME}`;
-  }
-
-  // --- The write path --------------------------------------------------------
-
-  /**
-   * Whether `glab` is installed and signed 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'.`,
-    };
-  }
-
-  /**
-   * Always undefined: sous has no cheap, reliable way to ask GitLab whether the
-   * contributor may push, and guessing would send them down a fork path this
-   * provider cannot finish.
-   *
-   * @param _repo - The canonicalized repository; unused.
-   * @param _options - Unused, because nothing is run.
-   */
-  async canPush(
-    _repo: CanonicalRepo,
-    _options: ProviderOptions = {}
-  ): Promise<boolean | undefined> {
-    return undefined;
-  }
-
-  /**
-   * Refuses, with the manual route. Sous opens a merge request from a branch
-   * the contributor can already push; forking on their behalf is not something
-   * this provider does.
-   *
-   * @param repo - The canonicalized repository.
-   */
-  async fork(repo: CanonicalRepo): Promise<ForkedRepo> {
-    throw new ConfigError(
-      `Sous does not fork ${repo.owner}/${repo.name} for you on ${this.cli.label}; it opens a ` +
-        `${this.proposalNoun} from a branch you can already push.\n` +
-        `  Fork the project yourself, push your branch to the fork, then open the ` +
-        `${this.proposalNoun} from there.`
-    );
-  }
-
-  /**
-   * Opens a merge request from the branch in the checkout the command is run
-   * in, which is why the working directory matters here.
-   *
-   * @param _repo - The canonicalized repository; `glab` reads the checkout instead.
-   * @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 args = ["mr", "create", "--source-branch", proposal.branch];
-    if (proposal.base !== undefined) args.push("--target-branch", proposal.base);
-    args.push(
-      "--title",
-      proposal.title,
-      "--description",
-      proposal.body,
-      "--yes"
-    );
-    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} mr 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}.` };
-  }
-}

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

@@ -1,128 +0,0 @@
-/**
- * The tiny HTTPS client the providers use to fetch a repo's index file.
- *
- * Only one kind of request is ever made: a plain GET of a raw file, optionally
- * carrying a bearer token so private repositories work. `fetch` is Node's own
- * global, and it is injectable so tests never reach the network.
- */
-
-import { ConfigError } from "../../errors.js";
-
-/** The shape of `fetch` this module needs; the global satisfies it. */
-export type FetchLike = (
-  url: string,
-  init?: { headers?: Record<string, string>; signal?: AbortSignal }
-) => Promise<{
-  ok: boolean;
-  status: number;
-  statusText: string;
-  text: () => Promise<string>;
-  headers: { get: (name: string) => string | null };
-}>;
-
-/** What a successful raw-file GET returns. */
-export type FetchedText = {
-  /** The file's contents. */
-  text: string;
-  /** The entity tag the server sent, when it sent one. */
-  etag?: string;
-};
-
-/** Options for a raw-file GET. */
-export type FetchTextOptions = {
-  /** A bearer token, when one is available for the host. */
-  token?: string;
-  /** The fetch implementation to use. Defaults to the global `fetch`. */
-  fetchImpl?: FetchLike;
-  /** What the URL is, named in error messages (for example "repo index"). */
-  label?: string;
-  /** Cancels the request, for a caller that will not wait past a deadline. */
-  signal?: AbortSignal;
-  /** The `Accept` header to send. Defaults to `application/json`. */
-  accept?: string;
-  /**
-   * The lines that explain a failed status to the reader. Defaults to the
-   * hints about a sous repository (a missing index, a private repository), so
-   * a caller fetching anything else names its own.
-   */
-  statusHints?: (status: number) => string[];
-};
-
-/**
- * What a failed status usually means when the URL names a file in a sous
- * repository: the default for `FetchTextOptions.statusHints`.
- *
- * @param status - The HTTP status the server answered with.
- */
-function repositoryStatusHints(status: number): string[] {
-  if (status === 404) {
-    return [
-      "  Either the repository publishes no sous index yet, or the URL names a " +
-        "repository that does not exist.",
-    ];
-  }
-  if (status === 401 || status === 403) {
-    return [
-      "  The repository is private or the request was not authorized. Sous uses a " +
-        "token from the environment, or from the provider's command line tool when " +
-        "one is installed and signed in.",
-    ];
-  }
-  return [];
-}
-
-/**
- * GETs a URL and returns its body as text. Any non-2xx response, or a transport
- * failure, becomes a ConfigError that names the URL and the status, and says
- * plainly what the status usually means (for a sous repository, unless the
- * caller passes `statusHints`).
- *
- * @param url - The absolute HTTPS URL to fetch.
- * @param options - Bearer token, fetch implementation, error label, `Accept`
- *   header and status hints.
- */
-export async function fetchText(
-  url: string,
-  options: FetchTextOptions = {}
-): Promise<FetchedText> {
-  const fetchImpl = options.fetchImpl ?? (globalThis.fetch as unknown as FetchLike);
-  const label = options.label ?? "file";
-
-  if (typeof fetchImpl !== "function") {
-    throw new ConfigError(
-      `Sous cannot fetch the ${label} at ${url}: this Node runtime provides no global fetch.\n` +
-        `  Sous requires Node 22 or newer.`
-    );
-  }
-
-  const headers: Record<string, string> = { Accept: options.accept ?? "application/json" };
-  if (options.token !== undefined && options.token.length > 0) {
-    headers["Authorization"] = `Bearer ${options.token}`;
-  }
-
-  let response: Awaited<ReturnType<FetchLike>>;
-  try {
-    response = await fetchImpl(
-      url,
-      options.signal === undefined ? { headers } : { headers, signal: options.signal }
-    );
-  } catch (error) {
-    throw new ConfigError(
-      `Sous could not reach ${url} while fetching the ${label}.\n` +
-        `  ${(error as Error).message}`
-    );
-  }
-
-  if (!response.ok) {
-    const lines = [
-      `Sous could not fetch the ${label} from ${url}.`,
-      `  The server answered ${response.status} ${response.statusText}.`,
-    ];
-    lines.push(...(options.statusHints ?? repositoryStatusHints)(response.status));
-    throw new ConfigError(lines.join("\n"));
-  }
-
-  const text = await response.text();
-  const etag = response.headers.get("etag");
-  return etag === null ? { text } : { text, etag };
-}