@timmo001/effect-gh 0.1.0-0

package/dist/workflow.js

@@ -0,0 +1,138 @@
+import { Effect, Schema, Stream } from "effect";
+import { Gh } from "./gh.js";
+const positiveInteger = Schema.Int.check(Schema.isGreaterThan(0));
+const repository = Schema.String.check(Schema.isPattern(/^(?:[a-zA-Z0-9.-]+(?::[0-9]+)?\/)?[a-zA-Z0-9_.-]+\/[a-zA-Z0-9_.-]+$/));
+export const Run = Schema.Struct({
+    databaseId: positiveInteger,
+    attempt: positiveInteger,
+    headBranch: Schema.NullOr(Schema.String),
+    headSha: Schema.String,
+    status: Schema.String,
+    conclusion: Schema.NullOr(Schema.String),
+    url: Schema.String,
+    workflowName: Schema.NullOr(Schema.String),
+});
+const fields = Object.keys(Run.fields).join(",");
+const listOptions = Schema.Struct({
+    repo: repository,
+    limit: Schema.optionalKey(positiveInteger),
+    branch: Schema.optionalKey(Schema.NonEmptyString),
+    commit: Schema.optionalKey(Schema.NonEmptyString),
+    workflow: Schema.optionalKey(Schema.NonEmptyString),
+    status: Schema.optionalKey(Schema.Literals([
+        "queued",
+        "completed",
+        "in_progress",
+        "requested",
+        "waiting",
+        "pending",
+        "action_required",
+        "cancelled",
+        "failure",
+        "neutral",
+        "skipped",
+        "stale",
+        "startup_failure",
+        "success",
+        "timed_out",
+    ])),
+});
+const viewOptions = Schema.Struct({
+    repo: repository,
+    runId: positiveInteger,
+    attempt: Schema.optionalKey(positiveInteger),
+});
+const logsOptions = Schema.Struct({
+    ...viewOptions.fields,
+    failedOnly: Schema.optionalKey(Schema.Boolean),
+    job: Schema.optionalKey(positiveInteger),
+});
+const watchOptions = Schema.Struct({
+    repo: repository,
+    runId: positiveInteger,
+    interval: Schema.optionalKey(positiveInteger),
+});
+export class InvalidOptions extends Schema.TaggedError()("WorkflowInvalidOptions", { cause: Schema.Defect() }) {
+}
+const decodeOptions = Effect.fn("Workflow.decodeOptions")(function* (schema, input) {
+    return yield* Schema.decodeUnknownEffect(schema)(input).pipe(Effect.mapError((cause) => new InvalidOptions({ cause })));
+});
+/** Fetch at most `limit` recent runs (default 20), without unbounded pagination. */
+export const list = Effect.fn("Workflow.list")(function* (input, options) {
+    const query = yield* decodeOptions(listOptions, input);
+    const gh = yield* Gh;
+    const args = [
+        "run",
+        "list",
+        "--repo",
+        query.repo,
+        "--limit",
+        String(query.limit ?? 20),
+        "--json",
+        fields,
+    ];
+    if (query.branch !== undefined)
+        args.push("--branch", query.branch);
+    if (query.commit !== undefined)
+        args.push("--commit", query.commit);
+    if (query.workflow !== undefined)
+        args.push("--workflow", query.workflow);
+    if (query.status !== undefined)
+        args.push("--status", query.status);
+    return yield* gh.json(args, Schema.Array(Run), options);
+});
+/** View the latest attempt unless an explicit attempt is supplied. */
+export const view = Effect.fn("Workflow.view")(function* (input, options) {
+    const query = yield* decodeOptions(viewOptions, input);
+    const gh = yield* Gh;
+    const args = [
+        "run",
+        "view",
+        String(query.runId),
+        "--repo",
+        query.repo,
+        "--json",
+        fields,
+    ];
+    if (query.attempt !== undefined)
+        args.push("--attempt", String(query.attempt));
+    return yield* gh.json(args, Run, options);
+});
+/** Fetch full logs or failed steps, optionally for one attempt and job. */
+export const logs = Effect.fn("Workflow.logs")(function* (input, options) {
+    const query = yield* decodeOptions(logsOptions, input);
+    const gh = yield* Gh;
+    const args = [
+        "run",
+        "view",
+        String(query.runId),
+        "--repo",
+        query.repo,
+        query.failedOnly ? "--log-failed" : "--log",
+    ];
+    if (query.attempt !== undefined)
+        args.push("--attempt", String(query.attempt));
+    if (query.job !== undefined)
+        args.push("--job", String(query.job));
+    return (yield* gh.execute(args, options)).stdout;
+});
+/**
+ * Stream native CLI progress, failing if the run fails. Requires gh with
+ * `--compact` support; gh watch cannot authenticate with fine-grained PATs.
+ * Inherits the core timeout; pass `{ timeout: null }` to disable it.
+ */
+export const watch = (input, options) => Stream.unwrap(Effect.gen(function* () {
+    const query = yield* decodeOptions(watchOptions, input);
+    const gh = yield* Gh;
+    return gh.stream([
+        "run",
+        "watch",
+        String(query.runId),
+        "--repo",
+        query.repo,
+        "--compact",
+        "--exit-status",
+        "--interval",
+        String(query.interval ?? 3),
+    ], options);
+}));

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@timmo001/effect-gh",
+  "version": "0.1.0-0",
+  "description": "An Effect v4 SDK for the GitHub CLI",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "packageManager": "bun@1.4.2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/timmo001/effect-gh.git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "check": "bun run lint && bun run typecheck && bun run format:check && bun run test",
+    "lint": "oxlint .",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
+    "test": "bun test",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "effect-tsgo patch",
+    "prepack": "bun run build"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-rc.117"
+  },
+  "devDependencies": {
+    "@effect/platform-node": "4.0.0-rc.117",
+    "@effect/tsgo": "0.46.1",
+    "@oxlint/plugins": "1.85.0",
+    "@timmo001/oxlint-rules": "0.3.6",
+    "@types/bun": "1.4.2",
+    "effect": "4.0.0-rc.117",
+    "oxlint": "1.85.0",
+    "oxlint-tsgolint": "7.0.2003",
+    "prettier": "3.9.9",
+    "typescript": "7.0.2"
+  },
+  "trustedDependencies": [
+    "@effect/tsgo"
+  ]
+}

package/src/api.ts

@@ -0,0 +1,165 @@
+import { Effect, Schema } from "effect";
+import { GhDecodeError, type GhError } from "./errors.js";
+import { Gh, type GhOptions, type GhOutput } from "./gh.js";
+
+export const Method = Schema.Literals([
+  "GET",
+  "HEAD",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "OPTIONS",
+  "TRACE",
+  "CONNECT",
+]);
+
+export type Method = typeof Method.Type;
+
+const queryValue = Schema.Union([Schema.String, Schema.Finite, Schema.Boolean]);
+
+const requestSchema = Schema.Struct({
+  endpoint: Schema.NonEmptyString,
+  method: Method,
+  hostname: Schema.optionalKey(Schema.NonEmptyString),
+  query: Schema.optionalKey(
+    Schema.Record(
+      Schema.String,
+      Schema.Union([queryValue, Schema.Array(queryValue)]),
+    ),
+  ),
+  headers: Schema.optionalKey(Schema.Record(Schema.String, Schema.String)),
+  body: Schema.optionalKey(Schema.Json),
+});
+
+export interface Request extends Schema.Schema.Type<typeof requestSchema> {
+  /** Gh overrides. Stdin is owned by body; bodyless calls clear any layer stdin. */
+  readonly options?: Omit<GhOptions, "stdin">;
+}
+
+export interface PageRequest extends Omit<Request, "method" | "body"> {
+  readonly method: "GET";
+  readonly body?: never;
+}
+
+const pageRequestSchema = Schema.Struct({
+  ...requestSchema.fields,
+  endpoint: Schema.NonEmptyString.check(
+    Schema.isPattern(/^(?!\/?graphql(?:[?#]|$))/),
+  ),
+  method: Schema.Literal("GET"),
+  body: Schema.optionalKey(Schema.Never),
+});
+
+const prepare = Effect.fn("Api.prepare")(function* (request: Request) {
+  const input = yield* Schema.decodeEffect(requestSchema)(request).pipe(
+    Effect.mapError((cause) => new GhDecodeError({ cause })),
+  );
+
+  const endpoint = yield* Effect.try({
+    try: () => {
+      const query: Array<string> = [];
+
+      for (const [key, value] of Object.entries(input.query ?? {})) {
+        for (const item of Array.isArray(value) ? value : [value]) {
+          query.push(
+            `${encodeURIComponent(key)}=${encodeURIComponent(String(item))}`,
+          );
+        }
+      }
+
+      if (query.length === 0) return input.endpoint;
+      const fragmentIndex = input.endpoint.indexOf("#");
+
+      const path =
+        fragmentIndex === -1
+          ? input.endpoint
+          : input.endpoint.slice(0, fragmentIndex);
+
+      const fragment =
+        fragmentIndex === -1 ? "" : input.endpoint.slice(fragmentIndex);
+
+      const separator = !path.includes("?")
+        ? "?"
+        : path.endsWith("?") || path.endsWith("&")
+          ? ""
+          : "&";
+
+      return `${path}${separator}${query.join("&")}${fragment}`;
+    },
+    catch: (cause) => new GhDecodeError({ cause }),
+  });
+
+  const args = ["api", "--method", input.method];
+
+  if (input.hostname !== undefined) args.push(`--hostname=${input.hostname}`);
+
+  for (const [name, value] of Object.entries(input.headers ?? {})) {
+    args.push(`--header=${name}: ${value}`);
+  }
+
+  let stdin: string | undefined;
+
+  if (input.body !== undefined) {
+    stdin = yield* Schema.encodeEffect(Schema.fromJsonString(Schema.Json))(
+      input.body,
+    ).pipe(Effect.mapError((cause) => new GhDecodeError({ cause })));
+    args.push("--input", "-");
+  }
+
+  return { args, endpoint, options: { ...request.options, stdin } };
+});
+
+/** Returns stdout, stderr and the CLI exit code, including empty or non-JSON responses. Never retries. */
+export const raw = Effect.fn("Api.raw")(function* (
+  request: Request,
+): Effect.fn.Return<GhOutput, GhError, Gh> {
+  const command = yield* prepare(request);
+  const gh = yield* Gh;
+
+  return yield* gh.execute(
+    [...command.args, "--", command.endpoint],
+    command.options,
+  );
+});
+
+/** Decodes one JSON response. Encoding and decoding failures are GhDecodeError; requests never retry. */
+export const json = Effect.fn("Api.json")(function* <
+  S extends Schema.Constraint,
+>(
+  request: Request,
+  schema: S,
+): Effect.fn.Return<S["Type"], GhError, Gh | S["DecodingServices"]> {
+  const command = yield* prepare(request);
+  const gh = yield* Gh;
+
+  return yield* gh.json(
+    [...command.args, "--", command.endpoint],
+    schema,
+    command.options,
+  );
+});
+
+/** Fetches REST GET pages with --paginate --slurp. The schema describes each page, preserving envelopes. Never retries. */
+export const pages = Effect.fn("Api.pages")(function* <
+  S extends Schema.Constraint,
+>(
+  request: PageRequest,
+  schema: S,
+): Effect.fn.Return<
+  ReadonlyArray<S["Type"]>,
+  GhError,
+  Gh | S["DecodingServices"]
+> {
+  yield* Schema.decodeEffect(pageRequestSchema)(request).pipe(
+    Effect.mapError((cause) => new GhDecodeError({ cause })),
+  );
+  const command = yield* prepare(request);
+  const gh = yield* Gh;
+
+  return yield* gh.json(
+    [...command.args, "--paginate", "--slurp", "--", command.endpoint],
+    Schema.Array(schema),
+    command.options,
+  );
+});

package/src/errors.ts

@@ -0,0 +1,29 @@
+import { Schema } from "effect";
+
+export class GhCommandError extends Schema.TaggedError<GhCommandError>()(
+  "GhCommandError",
+  {
+    executable: Schema.String,
+    exitCode: Schema.Int,
+    stderr: Schema.String,
+    stderrTruncated: Schema.Boolean,
+  },
+) {}
+
+export class GhPlatformError extends Schema.TaggedError<GhPlatformError>()(
+  "GhPlatformError",
+  { executable: Schema.String, cause: Schema.Defect() },
+) {}
+
+export class GhTimeoutError extends Schema.TaggedError<GhTimeoutError>()(
+  "GhTimeoutError",
+  { executable: Schema.String, timeoutMs: Schema.Finite },
+) {}
+
+export class GhDecodeError extends Schema.TaggedError<GhDecodeError>()(
+  "GhDecodeError",
+  { cause: Schema.Defect() },
+) {}
+
+export type GhError =
+  GhCommandError | GhPlatformError | GhTimeoutError | GhDecodeError;

package/src/gh.ts

@@ -0,0 +1,236 @@
+import {
+  Context,
+  Duration,
+  Effect,
+  Layer,
+  Match,
+  Predicate,
+  Schema,
+  Stream,
+} from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/unstable/process";
+import {
+  GhCommandError,
+  GhDecodeError,
+  GhPlatformError,
+  GhTimeoutError,
+  type GhError,
+} from "./errors.js";
+
+export interface GhOptions {
+  readonly executable?: string;
+  readonly cwd?: string;
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** Explicit undefined clears stdin inherited from the layer. */
+  readonly stdin?: string | Uint8Array | undefined;
+  /** Total subprocess duration, including output draining. Null disables a layer timeout. */
+  readonly timeout?: Duration.Input | null;
+}
+
+export const GhOutput = Schema.Struct({
+  stdout: Schema.String,
+  stderr: Schema.String,
+  exitCode: Schema.Int,
+});
+
+export interface GhOutput extends Schema.Schema.Type<typeof GhOutput> {}
+
+export const GhChunk = Schema.TaggedUnion({
+  Stdout: { text: Schema.String },
+  Stderr: { text: Schema.String },
+});
+
+export type GhChunk = typeof GhChunk.Type;
+
+export interface Interface {
+  readonly execute: (
+    args: ReadonlyArray<string>,
+    options?: GhOptions,
+  ) => Effect.Effect<GhOutput, GhError>;
+  readonly json: <S extends Schema.Constraint>(
+    args: ReadonlyArray<string>,
+    schema: S,
+    options?: GhOptions,
+  ) => Effect.Effect<S["Type"], GhError, S["DecodingServices"]>;
+  readonly stream: (
+    args: ReadonlyArray<string>,
+    options?: GhOptions,
+  ) => Stream.Stream<GhChunk, GhError>;
+}
+
+export class Gh extends Context.Service<Gh, Interface>()(
+  "@timmo001/effect-gh/Gh",
+) {}
+
+const stderrLimit = 65_536;
+
+export const layer = (
+  defaults: GhOptions = {},
+): Layer.Layer<Gh, never, ChildProcessSpawner.ChildProcessSpawner> =>
+  Layer.effect(
+    Gh,
+    Effect.gen(function* () {
+      const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+
+      const open = Effect.fn("Gh.stream")(function* (
+        args: ReadonlyArray<string>,
+        options: GhOptions,
+      ) {
+        const executable = options.executable ?? "gh";
+
+        const handle = yield* spawner
+          .spawn(
+            ChildProcess.make(executable, args, {
+              cwd: options.cwd,
+              env: {
+                ...defaults.env,
+                ...options.env,
+                GH_PROMPT_DISABLED: "1",
+                GH_PAGER: "cat",
+                PAGER: "cat",
+                NO_COLOR: "1",
+                CLICOLOR: "0",
+                CLICOLOR_FORCE: "0",
+                GH_FORCE_TTY: undefined,
+                GH_SPINNER_DISABLED: "1",
+              },
+              extendEnv: true,
+              shell: false,
+              stdin: options.stdin === undefined ? "ignore" : "pipe",
+              stdout: "pipe",
+              stderr: "pipe",
+              forceKillAfter: "1 second",
+            }),
+          )
+          .pipe(
+            Effect.mapError(
+              (cause) => new GhPlatformError({ executable, cause }),
+            ),
+          );
+
+        let stderr = "";
+        let stderrTruncated = false;
+
+        const output = Stream.merge(
+          handle.stdout.pipe(
+            Stream.decodeText(),
+            Stream.map((text) => GhChunk.cases.Stdout.make({ text })),
+          ),
+          handle.stderr.pipe(
+            Stream.decodeText(),
+            Stream.map((text) => {
+              stderrTruncated ||= stderr.length + text.length > stderrLimit;
+              stderr = (stderr + text).slice(-stderrLimit);
+
+              return GhChunk.cases.Stderr.make({ text });
+            }),
+          ),
+        ).pipe(
+          Stream.mapError(
+            (cause) => new GhPlatformError({ executable, cause }),
+          ),
+        );
+
+        const completion = Effect.gen(function* () {
+          const exitCode = yield* handle.exitCode.pipe(
+            Effect.mapError(
+              (cause) => new GhPlatformError({ executable, cause }),
+            ),
+          );
+
+          if (exitCode !== 0) {
+            return yield* new GhCommandError({
+              executable,
+              exitCode,
+              stderr,
+              stderrTruncated,
+            });
+          }
+        });
+
+        const completed = output.pipe(
+          Stream.concat(Stream.fromEffect(completion).pipe(Stream.drain)),
+        );
+
+        if (options.stdin === undefined) return completed;
+
+        const input = Predicate.isString(options.stdin)
+          ? new TextEncoder().encode(options.stdin)
+          : options.stdin;
+
+        return completed.pipe(
+          Stream.mergeEffect(
+            Stream.run(Stream.succeed(input), handle.stdin).pipe(
+              Effect.mapError(
+                (cause) => new GhPlatformError({ executable, cause }),
+              ),
+            ),
+          ),
+        );
+      });
+
+      const stream: Interface["stream"] = (args, overrides) =>
+        Stream.suspend(() => {
+          const options = { ...defaults, ...overrides };
+          const output = Stream.unwrap(open(args, options));
+
+          if (options.timeout == null) return output;
+
+          if (!Duration.isFinite(Duration.fromInputUnsafe(options.timeout)))
+            return output;
+          const timeoutMs = Duration.toMillis(options.timeout);
+
+          return output.pipe(
+            Stream.mergeEffect(
+              Effect.sleep(options.timeout).pipe(
+                Effect.andThen(
+                  Effect.fail(
+                    new GhTimeoutError({
+                      executable: options.executable ?? "gh",
+                      timeoutMs,
+                    }),
+                  ),
+                ),
+              ),
+            ),
+          );
+        });
+
+      const execute = Effect.fn("Gh.execute")(function* (
+        args: ReadonlyArray<string>,
+        options?: GhOptions,
+      ) {
+        return yield* stream(args, options).pipe(
+          Stream.runFold(
+            () => ({ stdout: "", stderr: "", exitCode: 0 }) satisfies GhOutput,
+            (output, chunk) =>
+              Match.value(chunk).pipe(
+                Match.tag("Stdout", ({ text }) => ({
+                  ...output,
+                  stdout: output.stdout + text,
+                })),
+                Match.tag("Stderr", ({ text }) => ({
+                  ...output,
+                  stderr: output.stderr + text,
+                })),
+                Match.exhaustive,
+              ),
+          ),
+        );
+      });
+
+      const json = Effect.fn("Gh.json")(function* <S extends Schema.Constraint>(
+        args: ReadonlyArray<string>,
+        schema: S,
+        options?: GhOptions,
+      ) {
+        const output = yield* execute(args, options);
+
+        return yield* Schema.decodeEffect(Schema.fromJsonString(schema))(
+          output.stdout,
+        ).pipe(Effect.mapError((cause) => new GhDecodeError({ cause })));
+      });
+
+      return Gh.of({ execute, json, stream });
+    }),
+  );

package/src/index.ts

@@ -0,0 +1,26 @@
+export {
+  Gh,
+  GhChunk,
+  GhOutput,
+  layer,
+  type GhOptions,
+  type Interface,
+} from "./gh.js";
+
+export {
+  GhCommandError,
+  GhDecodeError,
+  GhPlatformError,
+  GhTimeoutError,
+  type GhError,
+} from "./errors.js";
+
+export * as Api from "./api.js";
+
+export * as Repository from "./repository.js";
+
+export * as Issue from "./issue.js";
+
+export * as PullRequest from "./pull-request.js";
+
+export * as Workflow from "./workflow.js";