@procedures/gh 0.3.0 → 0.5.0

package/src/module.ts

@@ -3,7 +3,8 @@
  *
  * Each procedure runs the GitHub CLI (`gh`) through `shell.run`, with an argument list and no
  * shell (roadmap R42). The reads declare `reads: ["network"]`. The procedures that make or change
- * something on GitHub declare `writes: ["network"]`.
+ * something on GitHub declare `writes: ["network"]`. `gh.run.download` writes files, so it
+ * declares `writes: ["fs"]`.
  *
  * Scaffold a procedure with: mark procedure new <name> --path packages/gh
  */
@@ -24,11 +25,23 @@ import { ghIssueList } from "./procedures/gh/issue/list.js";
 import { ghIssueView } from "./procedures/gh/issue/view.js";
 import { ghIssueCreate } from "./procedures/gh/issue/create.js";
 import { ghIssueComment } from "./procedures/gh/issue/comment.js";
+import { ghWorkflowRun } from "./procedures/gh/workflow/run.js";
+import { ghRunDownload } from "./procedures/gh/run/download.js";
+import { ghApi } from "./procedures/gh/api.js";
 
 /** A read of GitHub: it changes nothing. */
 const READS: Effects = { reads: ["network"], writes: [] };
 /** A write to GitHub that makes something new: not destructive, and a second call makes a second one. */
 const MAKES: Effects = { reads: ["network"], writes: ["network"], destructive: false, idempotent: false };
+/** A download from GitHub into files of the host. gh does not replace a file that exists, so it is not destructive. */
+const DOWNLOADS: Effects = { reads: ["network"], writes: ["fs"], destructive: false, idempotent: false };
+/**
+ * Any call of the GitHub API. The method is an input, and a procedure that writes by an input
+ * declares the writes (CAPABILITIES-2026-10, decision 14). PUT and DELETE can replace or remove
+ * data, so the declaration keeps the default: destructive. The temporary file of a body is not
+ * a file of the host that the call changes.
+ */
+const CALLS_API: Effects = { reads: ["network"], writes: ["network"] };
 
 const common = {
   repo: z.string().regex(/^[\w.-]+\/[\w.-]+$/, "owner/name").optional().describe("The repository as owner/name (default: the repository of the folder)"),
@@ -152,6 +165,59 @@ const procedures: AnyProcedure[] = [
     ghIssueComment,
     ["issue"],
   ),
+  gh(
+    ["gh", "workflow", "run"],
+    "Start a workflow run (a workflow_dispatch event) on a branch or a tag, with the inputs of the workflow",
+    z.object({
+      ...common,
+      workflow: z.string().min(1).describe("The name, the file name or the id of the workflow"),
+      ref: z.string().min(1).optional().describe("The branch or the tag (default: the default branch)"),
+      inputs: z.record(z.string(), z.string()).optional().describe("The inputs of the workflow, each one as -f key=value"),
+    }),
+    z.object({
+      workflow: z.string().describe("The workflow"),
+      ref: z.string().optional().describe("The branch or the tag"),
+      url: z.string().optional().describe("The URL of the new run, when gh prints it"),
+      run: z.number().optional().describe("The id of the new run, when gh prints its URL"),
+    }),
+    MAKES,
+    ghWorkflowRun,
+    ["workflow"],
+  ),
+  gh(
+    ["gh", "run", "download"],
+    "Download the artifacts of a workflow run into a folder",
+    z.object({
+      ...common,
+      run: z.number().int().min(1).describe("The id of the run"),
+      names: z.array(z.string().min(1)).optional().describe("Only the artifacts with these names"),
+      patterns: z.array(z.string().min(1)).optional().describe("Only the artifacts with names that match these glob patterns"),
+      dir: z.string().min(1).optional().describe("The folder for the artifacts (default: the folder where gh runs)"),
+    }),
+    z.object({ run: z.number().describe("The id of the run"), dir: z.string().describe("The folder of the artifacts") }),
+    DOWNLOADS,
+    ghRunDownload,
+    ["run"],
+  ),
+  gh(
+    ["gh", "api"],
+    "Call the GitHub API and give the parsed JSON. A method other than GET can change or delete data",
+    z.object({
+      ...common,
+      endpoint: z.string().min(1).describe("The endpoint, for example repos/{owner}/{repo}/pulls or graphql"),
+      method: z.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]).optional().describe("The HTTP method (default GET)"),
+      fields: z
+        .record(z.string(), z.union([z.string(), z.number(), z.boolean(), z.null()]))
+        .optional()
+        .describe("The parameters: a string goes as -f, another value as -F. GET sends them in the query"),
+      body: z.unknown().optional().describe("A JSON body, sent with --input from a temporary file"),
+      paginate: z.boolean().optional().describe("Get all the pages. The pages of an array become one array"),
+    }),
+    z.object({ data: z.unknown().describe("The parsed JSON of the response (null when it is empty)") }),
+    CALLS_API,
+    ghApi,
+    ["endpoint"],
+  ),
 ];
 
 export const ghModule: ProcedureModule = defineModule("@procedures/gh", procedures, [shellModule]);

package/src/procedures/gh/api.ts

@@ -0,0 +1,99 @@
+/**
+ * gh.api procedure
+ *
+ * A request to the GitHub API, and its parsed JSON
+ */
+
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ProcedureContext } from "@procedures/client";
+import type { GhApiInput, GhApiOutput } from "../../types.js";
+import { fieldArg, ghArg, GhError, runGh } from "./shared.js";
+
+/**
+ * This function splits text that has JSON objects and arrays one after the other, as
+ * `gh api --paginate` writes one value for each page. It throws for other text.
+ */
+export function jsonValues(text: string): unknown[] {
+  const values: unknown[] = [];
+  let depth = 0;
+  let start = 0;
+  let inString = false;
+  let escaped = false;
+  for (let at = 0; at < text.length; at++) {
+    const char = text[at]!;
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (char === "\\") escaped = true;
+      else if (char === '"') inString = false;
+    } else if (char === "{" || char === "[") {
+      if (depth === 0) start = at;
+      depth++;
+    } else if (char === "}" || char === "]") {
+      depth--;
+      if (depth < 0) throw new Error(`Unexpected "${char}" at ${at}`);
+      if (depth === 0) values.push(JSON.parse(text.slice(start, at + 1)));
+    } else if (depth === 0) {
+      if (!/\s/.test(char)) throw new Error(`Unexpected "${char}" at ${at}`);
+    } else if (char === '"') {
+      inString = true;
+    }
+  }
+  if (depth !== 0 || inString) throw new Error("The JSON ends too early");
+  return values;
+}
+
+/**
+ * This function reads the output of `gh api`. An empty output (for example HTTP 204) gives
+ * null. With `paginate`, the pages of an array become one array, and the pages of an object
+ * become an array of the pages.
+ */
+export function parseGhApiOutput(output: string, paginate = false): unknown {
+  const text = output.trim();
+  if (text.length === 0) return null;
+  let values: unknown[];
+  try {
+    values = [JSON.parse(text)];
+  } catch {
+    try {
+      if (!paginate) throw new Error("not one JSON value");
+      values = jsonValues(text);
+    } catch {
+      throw new GhError(`gh api gave no JSON: ${text.slice(0, 200)}`, 0, "");
+    }
+  }
+  if (!paginate) return values[0];
+  return values.every((value) => Array.isArray(value)) ? values.flat(1) : values;
+}
+
+/**
+ * This function sends a request to the GitHub API with `gh api` and gives the parsed JSON. It always sends
+ * `--method`, because without it gh changes GET to POST when the call has fields. A string field
+ * goes as `-f` (gh sends it as text). Another value goes as `-F`, and gh converts its type. A
+ * `body` goes to gh as `--input` from a temporary file, which the call removes. A `repo` goes to
+ * gh as `GH_REPO`: gh replaces `{owner}` and `{repo}` in the endpoint with it.
+ */
+export async function ghApi(input: GhApiInput, ctx: ProcedureContext): Promise<GhApiOutput> {
+  const args = ["api", ghArg("endpoint", input.endpoint), "--method", input.method ?? "GET"];
+  for (const [key, value] of Object.entries(input.fields ?? {})) {
+    // -F reads a value that starts with "@" from a file. A number, a boolean and null cannot start with "@".
+    if (typeof value === "string") args.push("-f", fieldArg("field", key, value));
+    else args.push("-F", fieldArg("field", key, String(value)));
+  }
+  if (input.paginate) args.push("--paginate");
+  const env = input.repo === undefined ? undefined : { GH_REPO: input.repo };
+
+  if (input.body === undefined) {
+    return { data: parseGhApiOutput(await runGh(args, input, ctx, env), input.paginate) };
+  }
+  const folder = await mkdtemp(join(tmpdir(), "procedures-gh-api-"));
+  try {
+    const file = join(folder, "body.json");
+    await writeFile(file, JSON.stringify(input.body), "utf8");
+    args.push("--input", file);
+    return { data: parseGhApiOutput(await runGh(args, input, ctx, env), input.paginate) };
+  } finally {
+    await rm(folder, { recursive: true, force: true });
+  }
+}

package/src/procedures/gh/index.ts

@@ -11,3 +11,6 @@ export { ghIssueList } from "./issue/list.js";
 export { ghIssueView } from "./issue/view.js";
 export { ghIssueCreate } from "./issue/create.js";
 export { ghIssueComment } from "./issue/comment.js";
+export { ghWorkflowRun } from "./workflow/run.js";
+export { ghRunDownload } from "./run/download.js";
+export { ghApi } from "./api.js";

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

@@ -0,0 +1,23 @@
+/**
+ * gh.run.download procedure
+ *
+ * Download the artifacts of a workflow run
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhRunDownloadInput, GhRunDownloadOutput } from "../../../types.js";
+import { ghArg, repoArgs, runGh } from "../shared.js";
+
+/**
+ * This function downloads the artifacts of a run with `gh run download`. gh puts each artifact in
+ * a folder with its name. When the input selects one artifact, gh puts its files directly in `dir`.
+ * gh does not replace a file that exists: the download then fails.
+ */
+export async function ghRunDownload(input: GhRunDownloadInput, ctx: ProcedureContext): Promise<GhRunDownloadOutput> {
+  const args = ["run", "download", String(input.run), ...repoArgs(input)];
+  for (const name of input.names ?? []) args.push("--name", ghArg("name", name));
+  for (const pattern of input.patterns ?? []) args.push("--pattern", ghArg("pattern", pattern));
+  if (input.dir !== undefined) args.push("--dir", ghArg("dir", input.dir));
+  await runGh(args, input, ctx);
+  return { run: input.run, dir: input.dir ?? "." };
+}

package/src/procedures/gh/shared.ts

@@ -13,6 +13,7 @@ interface ShellRunInput {
   args: string[];
   cwd?: string;
   timeout?: number;
+  env?: Record<string, string>;
 }
 
 /** A failed gh command: its exit code and its error text. */
@@ -38,11 +39,15 @@ 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> {
+/**
+ * This function runs `gh <args>` and gives its output. It throws a GhError for a failed command.
+ * The `env` variables go to gh in addition to the environment of the host.
+ */
+export async function runGh(args: string[], input: GhCommonInput, ctx: ProcedureContext, env?: Record<string, string>): Promise<string> {
   const shellInput: ShellRunInput = { command: "gh", args };
   if (input.cwd !== undefined) shellInput.cwd = input.cwd;
   if (input.timeoutMs !== undefined) shellInput.timeout = input.timeoutMs;
+  if (env !== undefined) shellInput.env = env;
   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();
@@ -68,6 +73,15 @@ export function listArgs(input: { limit?: number | undefined; search?: string |
   return args;
 }
 
+/**
+ * This function gives the `key=value` argument of a field (`-f`, `-F`). The key cannot be empty,
+ * contain "=" or start with "-".
+ */
+export function fieldArg(name: string, key: string, value: string): string {
+  if (key.length === 0 || key.includes("=") || key.startsWith("-")) throw new Error(`Invalid ${name} name (empty, with "=", or starts with "-"): ${key}`);
+  return `${key}=${value}`;
+}
+
 /** 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/);

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

@@ -0,0 +1,30 @@
+/**
+ * gh.workflow.run procedure
+ *
+ * Start a workflow run: a `workflow_dispatch` event
+ */
+
+import type { ProcedureContext } from "@procedures/client";
+import type { GhWorkflowRunInput, GhWorkflowRunOutput } from "../../../types.js";
+import { fieldArg, ghArg, repoArgs, runGh } from "../shared.js";
+
+/**
+ * This function starts a workflow run with `gh workflow run`. Each input goes as `-f key=value`.
+ * When GitHub gives the new run, gh prints its URL, and the output has the URL and the run id.
+ */
+export async function ghWorkflowRun(input: GhWorkflowRunInput, ctx: ProcedureContext): Promise<GhWorkflowRunOutput> {
+  const args = ["workflow", "run", ghArg("workflow", input.workflow), ...repoArgs(input)];
+  if (input.ref !== undefined) args.push("--ref", ghArg("ref", input.ref));
+  // -f gives each value as a string. -F reads a value that starts with "@" from a file, so it is not used.
+  for (const [key, value] of Object.entries(input.inputs ?? {})) args.push("-f", fieldArg("input", key, value));
+  const output = await runGh(args, input, ctx);
+
+  const result: GhWorkflowRunOutput = { workflow: input.workflow };
+  if (input.ref !== undefined) result.ref = input.ref;
+  const url = output.split(/\r?\n/).find((line) => /^https:\/\/\S+\/actions\/runs\/\d+/.test(line.trim()))?.trim();
+  if (url !== undefined) {
+    result.url = url;
+    result.run = Number(/\/actions\/runs\/(\d+)/.exec(url)![1]);
+  }
+  return result;
+}

package/src/types.ts

@@ -122,3 +122,60 @@ export interface GhIssueCommentInput extends GhCommonInput {
   body: string;
 }
 export type GhIssueCommentOutput = GhCreatedOutput;
+
+export interface GhWorkflowRunInput extends GhCommonInput {
+  /** The name, the file name or the id of the workflow */
+  workflow: string;
+  /** The branch or the tag to run the workflow on (default: the default branch) */
+  ref?: string | undefined;
+  /** The inputs of the workflow. Each one goes to gh as `-f key=value`. */
+  inputs?: Record<string, string> | undefined;
+}
+export interface GhWorkflowRunOutput {
+  workflow: string;
+  ref?: string | undefined;
+  /** The URL of the new run, when gh prints it */
+  url?: string | undefined;
+  /** The id of the new run, when gh prints its URL */
+  run?: number | undefined;
+}
+
+export interface GhRunDownloadInput extends GhCommonInput {
+  /** The id of the run */
+  run: number;
+  /** Only the artifacts with these names */
+  names?: string[] | undefined;
+  /** Only the artifacts with names that match these glob patterns */
+  patterns?: string[] | undefined;
+  /** The folder for the artifacts (default: the folder where gh runs) */
+  dir?: string | undefined;
+}
+export interface GhRunDownloadOutput {
+  run: number;
+  /** The folder of the artifacts */
+  dir: string;
+}
+
+/** A value of a field of gh.api. A string goes as `-f`, another value as `-F` (gh converts its type). */
+export type GhApiFieldValue = string | number | boolean | null;
+
+/** The HTTP methods of gh.api. */
+export type GhApiMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+
+export interface GhApiInput extends GhCommonInput {
+  /** The endpoint, for example `repos/{owner}/{repo}/pulls` or `graphql` */
+  endpoint: string;
+  /** The HTTP method (default GET) */
+  method?: GhApiMethod | undefined;
+  /** The parameters. GET sends them in the query, the other methods in the JSON body. */
+  fields?: Record<string, GhApiFieldValue> | undefined;
+  /** A JSON body. gh reads it from a temporary file (`--input`). */
+  body?: unknown;
+  /** Get all the pages of the result */
+  paginate?: boolean | undefined;
+}
+export interface GhApiOutput {
+  /** The parsed JSON of the response. An empty response gives null. */
+  data: unknown;
+}
+