@procedures/gh 0.0.0-stage → 0.2.3

package/src/procedures/gh/issue/create.ts

@@ -0,0 +1,19 @@
+/**
+ * gh.issue.create procedure
+ *
+ * Open an issue
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhIssueCreateInput, GhIssueCreateOutput } from "../../../types.js";
+import { ghArg, repoArgs, runGh, urlOf } from "../shared.js";
+
+/**
+ * Open an issue
+ */
+export async function ghIssueCreate(input: GhIssueCreateInput, ctx: ProcedureContext): Promise<GhIssueCreateOutput> {
+  // --title and --body take their value as the next argument, so a value that starts with "-" is text
+  const args = ["issue", "create", "--title", input.title, "--body", input.body, ...repoArgs(input)];
+  for (const label of input.labels ?? []) args.push("--label", ghArg("label", label));
+  return { url: urlOf(await runGh(args, input, ctx)) };
+}

package/src/procedures/gh/issue/list.ts

@@ -0,0 +1,21 @@
+/**
+ * gh.issue.list procedure
+ *
+ * The issues of a repository
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhIssueListInput, GhIssueListOutput } from "../../../types.js";
+import { ghArg, ghJson, listArgs, repoArgs } from "../shared.js";
+
+const FIELDS = "number,title,state,url,author,labels,assignees,createdAt,updatedAt";
+
+/**
+ * The issues of a repository
+ */
+export async function ghIssueList(input: GhIssueListInput, ctx: ProcedureContext): Promise<GhIssueListOutput> {
+  const args = ["issue", "list", "--json", FIELDS, "--state", input.state ?? "open", ...listArgs(input), ...repoArgs(input)];
+  if (input.label !== undefined) args.push("--label", ghArg("label", input.label));
+  if (input.author !== undefined) args.push("--author", ghArg("author", input.author));
+  return { items: await ghJson<Array<Record<string, unknown>>>(args, input, ctx) };
+}

package/src/procedures/gh/issue/view.ts

@@ -0,0 +1,19 @@
+/**
+ * gh.issue.view procedure
+ *
+ * One issue, with its comments
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhIssueViewInput, GhIssueViewOutput } from "../../../types.js";
+import { ghArg, ghJson, repoArgs } from "../shared.js";
+
+const FIELDS = "number,title,state,url,body,author,labels,assignees,comments,createdAt,updatedAt";
+
+/**
+ * One issue
+ */
+export async function ghIssueView(input: GhIssueViewInput, ctx: ProcedureContext): Promise<GhIssueViewOutput> {
+  const args = ["issue", "view", ghArg("issue", input.issue), "--json", FIELDS, ...repoArgs(input)];
+  return { item: await ghJson<Record<string, unknown>>(args, input, ctx) };
+}

package/src/procedures/gh/pr/checks.ts

@@ -0,0 +1,25 @@
+/**
+ * gh.pr.checks procedure
+ *
+ * The checks of a pull request. gh exits with 8 while a check runs: that is a result, not a failure.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhPrChecksInput, GhPrChecksOutput } from "../../../types.js";
+import { GhError, ghArg, ghJson, repoArgs } from "../shared.js";
+
+/**
+ * The checks of a pull request
+ */
+export async function ghPrChecks(input: GhPrChecksInput, ctx: ProcedureContext): Promise<GhPrChecksOutput> {
+  const args = ["pr", "checks", ghArg("pr", input.pr), "--json", "name,state,bucket,link,workflow", ...repoArgs(input)];
+  try {
+    return { items: await ghJson<Array<Record<string, unknown>>>(args, input, ctx) };
+  } catch (error) {
+    // Exit 8: a check is pending. gh still prints the JSON on stdout, but runGh threw on the exit code
+    if (error instanceof GhError && error.exitCode === 8) {
+      throw new GhError("gh pr checks: a check is pending, ask again later", 8, error.stderr);
+    }
+    throw error;
+  }
+}

package/src/procedures/gh/pr/create.ts

@@ -0,0 +1,21 @@
+/**
+ * gh.pr.create procedure
+ *
+ * Open a pull request
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhPrCreateInput, GhPrCreateOutput } from "../../../types.js";
+import { ghArg, repoArgs, runGh, urlOf } from "../shared.js";
+
+/**
+ * Open a pull request
+ */
+export async function ghPrCreate(input: GhPrCreateInput, ctx: ProcedureContext): Promise<GhPrCreateOutput> {
+  // --title and --body take their value as the next argument, so a value that starts with "-" is text
+  const args = ["pr", "create", "--title", input.title, "--body", input.body, ...repoArgs(input)];
+  if (input.base !== undefined) args.push("--base", ghArg("base", input.base));
+  if (input.head !== undefined) args.push("--head", ghArg("head", input.head));
+  if (input.draft) args.push("--draft");
+  return { url: urlOf(await runGh(args, input, ctx)) };
+}

package/src/procedures/gh/pr/list.ts

@@ -0,0 +1,22 @@
+/**
+ * gh.pr.list procedure
+ *
+ * The pull requests of a repository
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhPrListInput, GhPrListOutput } from "../../../types.js";
+import { ghArg, ghJson, listArgs, repoArgs } from "../shared.js";
+
+export const PR_FIELDS = "number,title,state,url,author,headRefName,baseRefName,isDraft,createdAt,updatedAt";
+
+/**
+ * The pull requests of a repository
+ */
+export async function ghPrList(input: GhPrListInput, ctx: ProcedureContext): Promise<GhPrListOutput> {
+  const args = ["pr", "list", "--json", PR_FIELDS, "--state", input.state ?? "open", ...listArgs(input), ...repoArgs(input)];
+  if (input.author !== undefined) args.push("--author", ghArg("author", input.author));
+  if (input.base !== undefined) args.push("--base", ghArg("base", input.base));
+  if (input.head !== undefined) args.push("--head", ghArg("head", input.head));
+  return { items: await ghJson<Array<Record<string, unknown>>>(args, input, ctx) };
+}

package/src/procedures/gh/pr/view.ts

@@ -0,0 +1,19 @@
+/**
+ * gh.pr.view procedure
+ *
+ * One pull request
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhPrViewInput, GhPrViewOutput } from "../../../types.js";
+import { ghArg, ghJson, repoArgs } from "../shared.js";
+
+const FIELDS = "number,title,state,url,body,author,headRefName,baseRefName,isDraft,mergeable,reviewDecision,additions,deletions,changedFiles,createdAt,updatedAt";
+
+/**
+ * One pull request
+ */
+export async function ghPrView(input: GhPrViewInput, ctx: ProcedureContext): Promise<GhPrViewOutput> {
+  const args = ["pr", "view", ghArg("pr", input.pr), "--json", FIELDS, ...repoArgs(input)];
+  return { item: await ghJson<Record<string, unknown>>(args, input, ctx) };
+}

package/src/procedures/gh/release/list.ts

@@ -0,0 +1,17 @@
+/**
+ * gh.release.list procedure
+ *
+ * The releases of a repository
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhReleaseListInput, GhReleaseListOutput } from "../../../types.js";
+import { ghJson, listArgs, repoArgs } from "../shared.js";
+
+/**
+ * The releases of a repository
+ */
+export async function ghReleaseList(input: GhReleaseListInput, ctx: ProcedureContext): Promise<GhReleaseListOutput> {
+  const args = ["release", "list", "--json", "tagName,name,isDraft,isPrerelease,isLatest,publishedAt,createdAt", ...listArgs(input), ...repoArgs(input)];
+  return { items: await ghJson<Array<Record<string, unknown>>>(args, input, ctx) };
+}

package/src/procedures/gh/release/view.ts

@@ -0,0 +1,20 @@
+/**
+ * gh.release.view procedure
+ *
+ * One release: the release of a tag, or the latest release
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhReleaseViewInput, GhReleaseViewOutput } from "../../../types.js";
+import { ghArg, ghJson, repoArgs } from "../shared.js";
+
+const FIELDS = "tagName,name,body,url,isDraft,isPrerelease,publishedAt,createdAt,author,assets";
+
+/**
+ * One release
+ */
+export async function ghReleaseView(input: GhReleaseViewInput, ctx: ProcedureContext): Promise<GhReleaseViewOutput> {
+  const tag = input.tag === undefined ? [] : [ghArg("tag", input.tag)];
+  const args = ["release", "view", ...tag, "--json", FIELDS, ...repoArgs(input)];
+  return { item: await ghJson<Record<string, unknown>>(args, input, ctx) };
+}

package/src/procedures/gh/run/list.ts

@@ -0,0 +1,22 @@
+/**
+ * gh.run.list procedure
+ *
+ * The workflow runs of a repository
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhRunListInput, GhRunListOutput } from "../../../types.js";
+import { ghArg, ghJson, listArgs, repoArgs } from "../shared.js";
+
+const FIELDS = "databaseId,workflowName,displayTitle,headBranch,headSha,event,status,conclusion,url,createdAt,updatedAt";
+
+/**
+ * The workflow runs of a repository
+ */
+export async function ghRunList(input: GhRunListInput, ctx: ProcedureContext): Promise<GhRunListOutput> {
+  const args = ["run", "list", "--json", FIELDS, ...listArgs({ limit: input.limit ?? 20 }), ...repoArgs(input)];
+  if (input.workflow !== undefined) args.push("--workflow", ghArg("workflow", input.workflow));
+  if (input.branch !== undefined) args.push("--branch", ghArg("branch", input.branch));
+  if (input.status !== undefined) args.push("--status", ghArg("status", input.status));
+  return { items: await ghJson<Array<Record<string, unknown>>>(args, input, ctx) };
+}

package/src/procedures/gh/run/rerun.ts

@@ -0,0 +1,19 @@
+/**
+ * gh.run.rerun procedure
+ *
+ * Run a workflow run again
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhRunRerunInput, GhRunRerunOutput } from "../../../types.js";
+import { repoArgs, runGh } from "../shared.js";
+
+/**
+ * Run a workflow run again
+ */
+export async function ghRunRerun(input: GhRunRerunInput, ctx: ProcedureContext): Promise<GhRunRerunOutput> {
+  const args = ["run", "rerun", String(input.run), ...repoArgs(input)];
+  if (input.failedOnly) args.push("--failed");
+  await runGh(args, input, ctx);
+  return { run: input.run };
+}

package/src/procedures/gh/run/view.ts

@@ -0,0 +1,19 @@
+/**
+ * gh.run.view procedure
+ *
+ * One workflow run with its jobs
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhRunViewInput, GhRunViewOutput } from "../../../types.js";
+import { ghJson, repoArgs } from "../shared.js";
+
+const FIELDS = "databaseId,workflowName,displayTitle,headBranch,headSha,event,status,conclusion,url,createdAt,updatedAt,jobs";
+
+/**
+ * One workflow run with its jobs
+ */
+export async function ghRunView(input: GhRunViewInput, ctx: ProcedureContext): Promise<GhRunViewOutput> {
+  const args = ["run", "view", String(input.run), "--json", FIELDS, ...repoArgs(input)];
+  return { item: await ghJson<Record<string, unknown>>(args, input, ctx) };
+}

package/src/procedures/gh/shared.ts

@@ -0,0 +1,75 @@
+/**
+ * The way every gh procedure runs the GitHub CLI: an argument list through `shell.run`, no
+ * shell. A value that gh reads as an argument must not start with "-", so it cannot become an
+ * option. The output is the JSON of `--json` where gh has it.
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhCommonInput } from "../../types.js";
+
+/** The fields of a call of shell.run. */
+interface ShellRunInput {
+  command: string;
+  args: string[];
+  cwd?: string;
+  timeout?: number;
+}
+
+/** A failed gh command: its exit code and its error text. */
+export class GhError extends Error {
+  override readonly name = "GhError";
+  constructor(
+    message: string,
+    readonly exitCode: number,
+    readonly stderr: string,
+  ) {
+    super(message);
+  }
+}
+
+/** A value that gh reads as an argument (a branch, a tag, a title): it must not start with "-". */
+export function ghArg(name: string, value: string): string {
+  if (value.startsWith("-")) throw new Error(`Invalid ${name} (starts with "-"): ${value}`);
+  return value;
+}
+
+/** The option `--repo owner/name`, when the input gives a repository. */
+export function repoArgs(input: GhCommonInput): string[] {
+  return input.repo === undefined ? [] : ["--repo", ghArg("repo", input.repo)];
+}
+
+/** This function runs `gh <args>` and gives its output. It throws a GhError for a failed command. */
+export async function runGh(args: string[], input: GhCommonInput, ctx: ProcedureContext): Promise<string> {
+  const shellInput: ShellRunInput = { command: "gh", args };
+  if (input.cwd !== undefined) shellInput.cwd = input.cwd;
+  if (input.timeoutMs !== undefined) shellInput.timeout = input.timeoutMs;
+  const result = await ctx.client.call<ShellRunInput, { exitCode: number; stdout: string; stderr: string }>(["shell", "run"], shellInput);
+  if (result.exitCode !== 0) {
+    const text = result.stderr.trim() || result.stdout.trim();
+    throw new GhError(`gh ${args[0] ?? ""} ${args[1] ?? ""} failed (exit ${result.exitCode}): ${text}`.trim(), result.exitCode, result.stderr);
+  }
+  return result.stdout;
+}
+
+/** This function runs gh with `--json` and gives the parsed value. */
+export async function ghJson<T>(args: string[], input: GhCommonInput, ctx: ProcedureContext): Promise<T> {
+  const output = await runGh(args, input, ctx);
+  try {
+    return JSON.parse(output) as T;
+  } catch {
+    throw new GhError(`gh ${args[0] ?? ""} ${args[1] ?? ""} gave no JSON: ${output.slice(0, 200)}`, 0, "");
+  }
+}
+
+/** The options of a list: its limit and a search. */
+export function listArgs(input: { limit?: number | undefined; search?: string | undefined }): string[] {
+  const args = ["--limit", String(input.limit ?? 30)];
+  if (input.search !== undefined) args.push("--search", input.search);
+  return args;
+}
+
+/** The last line of an output that is a URL: gh prints the URL of what it made. */
+export function urlOf(output: string): string {
+  const lines = output.trim().split(/\r?\n/);
+  return lines.reverse().find((line) => line.startsWith("https://")) ?? lines[0] ?? "";
+}

package/src/register.ts

@@ -0,0 +1,10 @@
+/**
+ * Importing this file registers the procedures of @procedures/gh in the global registry:
+ * `import "@procedures/gh/register"`. The package root registers nothing.
+ */
+
+import { registerGhProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerGhProcedures();

package/src/types.ts

@@ -0,0 +1,124 @@
+/**
+ * Type definitions of the procedures of this package
+ *
+ * mark procedure new adds the types of each new procedure here. The zod schemas are in
+ * `module.ts`: an exported schema needs a written type (isolatedDeclarations).
+ */
+
+/** The fields of each gh procedure. */
+export interface GhCommonInput {
+  /** The repository as owner/name (default: the repository of the folder) */
+  repo?: string | undefined;
+  /** The folder where gh runs */
+  cwd?: string | undefined;
+  /** The time limit of the command, in milliseconds */
+  timeoutMs?: number | undefined;
+}
+
+/** A list of the JSON objects that gh gives. */
+export interface GhListOutput {
+  items: Array<Record<string, unknown>>;
+}
+
+/** One JSON object that gh gives. */
+export interface GhItemOutput {
+  item: Record<string, unknown>;
+}
+
+/** What gh made: its URL. */
+export interface GhCreatedOutput {
+  url: string;
+}
+
+export interface GhPrListInput extends GhCommonInput {
+  state?: "open" | "closed" | "merged" | "all" | undefined;
+  author?: string | undefined;
+  base?: string | undefined;
+  head?: string | undefined;
+  search?: string | undefined;
+  limit?: number | undefined;
+}
+export type GhPrListOutput = GhListOutput;
+
+export interface GhPrViewInput extends GhCommonInput {
+  /** The number, the branch or the URL of the pull request */
+  pr: string;
+}
+export type GhPrViewOutput = GhItemOutput;
+
+export interface GhPrChecksInput extends GhCommonInput {
+  pr: string;
+}
+export type GhPrChecksOutput = GhListOutput;
+
+export interface GhPrCreateInput extends GhCommonInput {
+  title: string;
+  body: string;
+  base?: string | undefined;
+  head?: string | undefined;
+  draft?: boolean | undefined;
+}
+export type GhPrCreateOutput = GhCreatedOutput;
+
+export interface GhRunListInput extends GhCommonInput {
+  workflow?: string | undefined;
+  branch?: string | undefined;
+  status?: string | undefined;
+  limit?: number | undefined;
+}
+export type GhRunListOutput = GhListOutput;
+
+export interface GhRunViewInput extends GhCommonInput {
+  /** The id of the run */
+  run: number;
+}
+export type GhRunViewOutput = GhItemOutput;
+
+export interface GhRunRerunInput extends GhCommonInput {
+  run: number;
+  /** Only the jobs that failed */
+  failedOnly?: boolean | undefined;
+}
+export interface GhRunRerunOutput {
+  run: number;
+}
+
+export interface GhReleaseListInput extends GhCommonInput {
+  limit?: number | undefined;
+}
+export type GhReleaseListOutput = GhListOutput;
+
+export interface GhReleaseViewInput extends GhCommonInput {
+  /** The tag of the release (default: the latest release) */
+  tag?: string | undefined;
+}
+export type GhReleaseViewOutput = GhItemOutput;
+
+export interface GhIssueListInput extends GhCommonInput {
+  state?: "open" | "closed" | "all" | undefined;
+  label?: string | undefined;
+  author?: string | undefined;
+  search?: string | undefined;
+  limit?: number | undefined;
+}
+export type GhIssueListOutput = GhListOutput;
+
+export interface GhIssueViewInput extends GhCommonInput {
+  /** The number or the URL of the issue */
+  issue: string;
+}
+export type GhIssueViewOutput = GhItemOutput;
+
+export interface GhIssueCreateInput extends GhCommonInput {
+  title: string;
+  body: string;
+  labels?: string[] | undefined;
+}
+export type GhIssueCreateOutput = GhCreatedOutput;
+
+export interface GhIssueCommentInput extends GhCommonInput {
+  /** The number or the URL of the issue or the pull request */
+  issue: string;
+  body: string;
+}
+export type GhIssueCommentOutput = GhCreatedOutput;