Coverage / src/oxy.ts 74.4%

import { execFile } from "node:child_process";

import { SigningInfo, parseIdentityShow } from "./commitbox";

import { existsSync } from "node:fs";

import { homedir } from "node:os";

import { join } from "node:path";

export interface RunResult {

  code: number;

  stdout: Buffer;

  stderr: string;

}

export class OxyError extends Error {

  constructor(

    public readonly args: string[],

    public readonly code: number,

    public readonly stderr: string,

  ) {

    super(stderr.trim() || `oxy ${args.join(" ")} exited with status ${code}`);

    this.name = "OxyError";

  }

}

/** Where to find `oxy`: the configured path, else `oxy` on PATH, else ~/.local/bin/oxy. */

export function findBinary(configured: string | undefined): string {

export type Logger = (line: string) => void;

export class Oxy {

  constructor(

    public readonly binary: string,

    private readonly logger: Logger = () => {},

  ) {}

  /** Run oxy in `cwd`; resolves with the exit status, never rejects on a non-zero status. */

  run(cwd: string, args: string[]): Promise<RunResult> {

    const started = Date.now();

    const full = ["--plain", ...args];

    return new Promise((resolve, reject) => {

      execFile(

        this.binary,

        full,

        { cwd, maxBuffer: 256 * 1024 * 1024, encoding: "buffer", env: { ...process.env, NO_COLOR: "1" } },

        (error, stdout, stderr) => {

          const err = stderr.toString("utf8");

          const code = error && typeof (error as NodeJS.ErrnoException).code === "number" ? ((error as NodeJS.ErrnoException).code as unknown as number) : error ? -1 : 0;

          this.logger(`oxy ${args.join(" ")} (${cwd}) → ${code} in ${Date.now() - started} ms${err.trim() ? `: ${err.trim()}` : ""}`);

          if (error && (error as NodeJS.ErrnoException).code === "ENOENT") {

          resolve({ code, stdout: stdout as Buffer, stderr: err });

        },

      );

    });

  }

  /** Run and require success (exit 0, or one of `okCodes`). */

  async check(cwd: string, args: string[], okCodes: number[] = [0]): Promise<RunResult> {

    const r = await this.run(cwd, args);

    if (!okCodes.includes(r.code)) {

      throw new OxyError(args, r.code, r.stderr);

    }

    return r;

  }

  async json<T>(cwd: string, args: string[], okCodes: number[] = [0]): Promise<T> {

    const r = await this.check(cwd, [...args, "--json"], okCodes);

    const text = r.stdout.toString("utf8").trim();

    try {

      return JSON.parse(text) as T;

    } catch (e) {

  }

  // ---------------------------------------------------------------- commands

  async version(): Promise<VersionInfo> {

    return this.json<VersionInfo>(process.cwd(), ["version"]);

  }

  /** The repository containing `cwd`, or null when there is none. */

  async root(cwd: string): Promise<RootInfo | null> {

    const r = await this.run(cwd, ["root", "--json"]);

    if (r.code !== 0) {

      return null;

    }

    const v = JSON.parse(r.stdout.toString("utf8"));

    return v === null ? null : (v as RootInfo);

  }

  status(root: string): Promise<StatusInfo> {

    return this.json<StatusInfo>(root, ["status"], [0, 2]);

  }

  async prompt(root: string, format?: string): Promise<string> {

    const args = ["prompt", "--glyphs"];

    if (format) {

    const r = await this.run(root, args);

    return r.code === 0 ? r.stdout.toString("utf8").trim() : "";

  }

  /** File content at a state; `change` may be a hash prefix, id prefix, bookmark, or tag. */

  async cat(root: string, path: string, change?: string): Promise<Buffer> {

    const args = ["cat", path];

    if (change) {

      args.push("-r", change);

    }

    return (await this.check(root, args)).stdout;

  }

  log(root: string, limit?: number, path?: string): Promise<LogInfo> {

    const args = ["log"];

    if (limit !== undefined) {

      args.push("-n", String(limit));

    }

    if (path) {

      args.push("--path", path);

    }

    return this.json<LogInfo>(root, args);

  }

  commit(root: string, message: string, paths: string[] = []): Promise<void> {

    return this.check(root, ["commit", "-m", message, ...paths]).then(() => undefined);

  }

  /** The local bookmarks; with `all`, remotes' bookmarks with no local one too, named `REMOTE/NAME`. */

  bookmarks(root: string, all = false): Promise<BookmarkInfo[]> {

    return this.json<BookmarkInfo[]>(root, ["bookmark", "list", ...(all ? ["--all"] : [])]);

  }

  /** Restore paths to the working copy's base. */

  discard(root: string, paths: string[]): Promise<void> {

    return this.check(root, ["discard", ...paths]).then(() => undefined);

  }

  discardHunks(root: string, hunks: number[]): Promise<void> {

  hunks(root: string): Promise<HunkInfo[]> {

    return this.json<HunkInfo[]>(root, ["hunks"]);

  }

  commitHunks(root: string, message: string, hunks: number[]): Promise<void> {

    return this.check(root, ["commit", "-m", message, "--hunks", hunks.join(",")]).then(() => undefined);

  }

  /** Fold the working copy into the head it sits on; with `paths`, only those (the rest stays uncommitted). */

  amend(root: string, message?: string, paths: string[] = []): Promise<void> {

    const args = ["amend"];

    if (message) {

      args.push("-m", message);

    }

    return this.check(root, [...args, ...paths]).then(() => undefined);

  }

  undo(root: string): Promise<string> {

    return this.check(root, ["undo"]).then((r) => r.stdout.toString("utf8").trim());

  }

  opLog(root: string): Promise<OperationInfo[]> {

    return this.json<OperationInfo[]>(root, ["op", "log"]);

  }

  // ---------------------------------------------------------------- bookmarks

  bookmarkCreate(root: string, name: string, changes: string[] = []): Promise<void> {

    return this.check(root, ["bookmark", "create", name, ...changes]).then(() => undefined);

  }

  bookmarkSwitch(root: string, name: string, discard = false): Promise<void> {

    const args = ["bookmark", "switch", name];

    if (discard) {

    return this.check(root, args).then(() => undefined);

  }

  bookmarkDelete(root: string, name: string): Promise<void> {

    return this.check(root, ["bookmark", "delete", name]).then(() => undefined);

  }

  /** Union a bookmark's heads into the current one: a local bookmark, or a remote's (`origin/develop`) as last fetched. */

  merge(root: string, name: string): Promise<string> {

    return this.check(root, ["merge", name]).then((r) => r.stdout.toString("utf8").trim());

  }

  // ---------------------------------------------------------------- remotes and sync

  remotes(root: string): Promise<RemoteInfo[]> {

    return this.json<RemoteInfo[]>(root, ["remote", "list"]);

  }

  fetch(root: string, remote?: string): Promise<FetchInfo> {

    return this.json<FetchInfo>(root, ["fetch", ...(remote ? [remote] : [])]);

  }

  pull(root: string, remote?: string): Promise<PullInfo> {

    return this.json<PullInfo>(root, ["pull", ...(remote ? [remote] : [])]);

  }

  push(root: string, remote?: string, bookmark?: string, force = false): Promise<PushResult[]> {

    const args = ["push", ...(remote ? [remote] : [])];

    if (bookmark) {

      args.push("-b", bookmark);

    }

    if (force) {

    return this.json<PushResult[]>(root, args, [0, 1]);

  }

  /** Clone `url` into `dest`; `depth` makes it shallow (0: the latest state only, from the remote's checkpoint). */

  clone(cwd: string, url: string, dest: string, depth?: number): Promise<void> {

    return this.check(cwd, ["clone", ...(depth !== undefined ? ["--depth", String(depth)] : []), url, dest]).then(() => undefined);

  }

  // ---------------------------------------------------------------- history and blame

  blame(root: string, path: string): Promise<BlameLine[]> {

    return this.json<BlameLine[]>(root, ["blame", path]);

  }

  show(root: string, change: string): Promise<ShowInfo> {

    return this.json<ShowInfo>(root, ["show", change]);

  }

  /** The rendered diff of a change (or the working copy), as `oxy diff` prints it. */

  diffText(root: string, change?: string): Promise<string> {

    return this.check(root, ["diff", ...(change ? [change] : [])]).then((r) => r.stdout.toString("utf8"));

  }

  describe(root: string, change: string, message: string): Promise<void> {

  abandon(root: string, change: string): Promise<string> {

  /** The configured identity and how commits are signed; `null` without one. */

  identity(root: string): Promise<SigningInfo | null> {

    return this.check(root, ["identity", "show"]).then((r) => parseIdentityShow(r.stdout.toString("utf8")));

  }

  /** Split a head: the edits to `paths` become a separate first change. Returns oxy's summary line. */

  split(root: string, change: string, paths: string[]): Promise<string> {

    return this.check(root, ["split", change, ...paths]).then((r) => r.stdout.toString("utf8").trim());

  }

  /** Fold `change` into its dependency `into`, which keeps its ChangeId. */

  squash(root: string, change: string, into: string): Promise<string> {

    return this.check(root, ["squash", change, "--into", into]).then((r) => r.stdout.toString("utf8").trim());

  }

  /** Re-express `change` against the state of `onto` (changes, a bookmark or a tag). */

  rebase(root: string, change: string, onto: string[]): Promise<string> {

    return this.check(root, ["rebase", change, "--onto", ...onto]).then((r) => r.stdout.toString("utf8").trim());

  }

  checkout(root: string, changes: string[], discard = false): Promise<void> {

  tagCreate(root: string, name: string, changes: string[] = [], message = ""): Promise<void> {

    return this.check(root, ["tag", "create", name, ...changes, "-m", message]).then(() => undefined);

  }

  /**

   * Withdraw a tag (`oxy tag delete`): a signed withdrawal kept beside the

   * tag's creation, which push sends on; the name is never used again.

   * Returns oxy's summary line.

   */

  tagWithdraw(root: string, name: string, reason: string): Promise<string> {

    return this.check(root, ["tag", "delete", name, "-r", reason]).then((r) => r.stdout.toString("utf8").trim().split("\n")[0].replace(/^\* /, ""));

  }

  // ---------------------------------------------------------------- settling conflicts

  /**

   * Settle the replace conflicts (binary files, subrepo pins) at `paths`

   * with what the working copy holds there (oxygen#140); the next commit

   * records the resolution. Returns the status after it.

   */

  resolvePaths(root: string, paths: string[]): Promise<StatusInfo> {

    return this.json<StatusInfo>(root, ["resolve", ...paths], [0, 2]);

  }

  /**

   * Settle adjacent insertions (two changes adding lines at the same place)

   * by keeping every side, earliest change first, or latest with `reverse`

   * (oxygen#121). No paths: every conflicted text file. What was kept and

   * what keeps its markers, and why.

   */

  resolveBoth(root: string, paths: string[] = [], reverse = false): Promise<KeptBoth> {

    return this.check(root, ["resolve", "--both", ...(reverse ? ["--reverse"] : []), ...paths], [0, 2]).then((r) => parseKeptBoth(r.stdout.toString("utf8")));

  }

  // ---------------------------------------------------------------- transparency log

  /**

   * Audit a hub's whole transparency log (`oxy tlog verify`): its checkpoint

   * against the log key and the last one seen, and every entry against the

   * root; then this repository's entries. `hub` defaults to the remote.

   */

  tlogVerify(root: string, hub?: string): Promise<TlogInfo> {

    return this.json<TlogInfo>(root, ["tlog", "verify", ...(hub ? [hub] : [])]);

  }

  // ---------------------------------------------------------------- subrepos, bisect, trust, tags, workspaces

  submodules(root: string): Promise<SubrepoInfo[]> {

    return this.json<SubrepoInfo[]>(root, ["submodule", "status"]);

  }

  submoduleUpdate(root: string, init: boolean, paths: string[] = []): Promise<string> {

  bisectStatus(root: string): Promise<BisectStatus | null> {

    return this.json<BisectStatus | null>(root, ["bisect", "status"]);

  }

  bisectStart(root: string): Promise<void> {

    return this.check(root, ["bisect", "start"]).then(() => undefined);

  }

  bisectMark(root: string, verdict: "good" | "bad" | "skip", changes: string[] = []): Promise<string> {

  bisectRun(root: string, command: string[]): Promise<string> {

  bisectReset(root: string): Promise<void> {

    return this.check(root, ["bisect", "reset"]).then(() => undefined);

  }

  policyShow(root: string): Promise<PolicyInfo | null> {

    return this.json<PolicyInfo | null>(root, ["policy", "show"]);

  }

  verify(root: string, change?: string): Promise<VerifyInfo[]> {

    return this.json<VerifyInfo[]>(root, ["verify", ...(change ? [change] : [])], [0, 1]);

  }

  tags(root: string): Promise<TagInfo[]> {

    return this.json<TagInfo[]>(root, ["tag", "list"]);

  }

  workspaces(root: string): Promise<WorkspaceInfo[]> {

    return this.json<WorkspaceInfo[]>(root, ["workspace", "list"]);

  }

  workspaceAdd(root: string, path: string, changes: string[] = []): Promise<void> {

}

export interface SubrepoInfo {

  path: string;

  pin: PinInfo;

  actual: PinInfo | null;

  at_pin: boolean;

  dirty: boolean;

  url: string | null;

}

export type PinInfo = { kind: "oxy"; repo: string; heads: string[]; bookmark: string } | { kind: "git"; sha: string; branch: string };

export type BisectStatus =

  | { state: "need-marks"; good: number; bad: number }

  | { state: "testing"; heads: string[]; remaining: number; steps_left: number }

  | { state: "found"; culprit: string }

  | { state: "inconclusive"; candidates: string[] };

export interface PolicyInfo {

  hash: string;

  serial: number;

  expires_ms: number;

  expired: boolean;

  root_threshold: number;

  roots: { key: string; name: string; email: string }[];

  rules: { pattern: string; keys: { key: string; name: string; email: string }[]; threshold: number; require: string; allow_conflicts: boolean }[];

  revoked: { key: string; name: string; email: string }[];

}

export interface VerifyInfo {

  hash: string;

  change_id: string;

  status: string;

  key: string | null;

  name: string | null;

  revoked: boolean;

  reason: string | null;

}

/** What `oxy resolve --both` did: the conflicts kept on every side, and those left with markers. */

export interface KeptBoth {

  kept: { path: string; conflicts: number[] }[];

  left: { path: string; conflict: number; why: string }[];

}

/** Read `oxy resolve --both`'s report lines (`kept both  PATH: conflict 1, 2`, `markers    PATH: conflict 3: why`). */

export function parseKeptBoth(text: string): KeptBoth {

  const out: KeptBoth = { kept: [], left: [] };

  for (const line of text.split(/\r?\n/)) {

    const kept = /^kept both\s+(.+): conflicts? ([\d, ]+)$/.exec(line);

    if (kept) {

      out.kept.push({ path: kept[1], conflicts: kept[2].split(",").map((n) => Number(n.trim())).filter((n) => n > 0) });

      continue;

    }

    const left = /^markers\s+(.+): conflict (\d+): (.+)$/.exec(line);

    if (left) {

      out.left.push({ path: left[1], conflict: Number(left[2]), why: left[3] });

    }

  }

  return out;

}

/** `oxy tlog verify --json`: the checkpoint verified, who cosigned it, and the entries listed. */

export interface TlogInfo {

  hub: string;

  origin: string;

  /** Entries in the log the checkpoint covers. */

  size: number;

  root: string;

  witnesses: { name: string; time_ms: number }[];

  entries: { index: number; kind: string; repo: string; object: string; signers: string[]; received_ms: number }[];

}

/**

 * A remote's bookmark that `bookmark list --all` adds because there is no

 * local bookmark of that name: named `REMOTE/NAME`, never current, with no

 * ahead or behind counts. `oxy merge` takes the name as it is.

 */

export function isRemoteBookmark(b: BookmarkInfo): boolean {

  return !!b.remote && b.name.startsWith(`${b.remote}/`) && !b.current && b.ahead === null && b.behind === null;

}

/** What Merge Bookmark offers: the other local bookmarks first, then remotes' bookmarks. */

export function mergeChoices(bookmarks: BookmarkInfo[]): { name: string; remote: string | null; heads: number }[] {

  const local = bookmarks.filter((b) => !b.current && !isRemoteBookmark(b)).map((b) => ({ name: b.name, remote: null, heads: b.heads.length }));

  const remote = bookmarks.filter(isRemoteBookmark).map((b) => ({ name: b.name, remote: b.remote ?? null, heads: b.heads.length }));

  return [...local, ...remote];

}