@timmo001/effect-gh 0.2.0 → 0.3.0

package/README.md

@@ -130,10 +130,11 @@ entries override inherited values; `undefined` removes a value. The SDK always
 disables prompts, colour, forced TTY and spinners, and selects `cat` as the pager.
 Stdin is closed unless supplied explicitly. No operation is automatically retried.
 
-Errors are tagged `GhCommandError` (nonzero exit with exit code and stderr),
-`GhPlatformError` (spawn or pipe failure), `GhTimeoutError`, or `GhDecodeError`
-(invalid JSON or a schema mismatch). Command errors retain only the last 65,536
-UTF-16 code units of stderr and flag truncation with `stderrTruncated`.
+Errors are tagged `GhCommandError` (nonzero exit with exit code, stdout and
+stderr), `GhPlatformError` (spawn or pipe failure), `GhTimeoutError`, or
+`GhDecodeError` (invalid JSON or a schema mismatch). Command errors retain only
+the last 65,536 UTF-16 code units of each output and flag truncation with
+`stdoutTruncated` and `stderrTruncated`.
 The stream emits trailing output before reporting a nonzero exit.
 
 Interruption, timeout and early stream termination close the child scope. The
@@ -178,11 +179,36 @@ through the raw `Gh` interface.
 ### Retries
 
 No SDK operation retries automatically. Mutations can have taken effect even
-when the CLI times out or loses the connection. Consumers can apply Effect
-`Schedule` and `Effect.retry` to known-idempotent reads with a bounded policy and
-their own transient-error classification. Decode errors, authentication failures
-and check-status exits are not transient errors. Do not transparently replay a
-stream after it has emitted output.
+when the CLI times out or loses the connection, so only retry known-idempotent
+reads, and do not transparently replay a stream after it has emitted output.
+
+`Gh.retryTransient(options?)` retries an effect failing with `GhError` while
+`isTransient` holds: timeouts, rate limits, HTTP 408, 429 and 5xx gateway
+statuses, and network failures. It defaults to three retries with jittered
+exponential backoff from 250 milliseconds, capped at 10 seconds
+(`defaultRetrySchedule`); pass `schedule` or `times` to change either. Decode
+errors, authentication failures and check-status exits are not transient.
+
+```ts
+import { Api, Gh } from "@timmo001/effect-gh";
+import { Schema } from "effect";
+
+const viewer = Api.json(
+  { endpoint: "user", method: "GET" },
+  Schema.Struct({ login: Schema.String }),
+).pipe(Gh.retryTransient({ times: 2 }));
+```
+
+`isRateLimited(error)` and `httpStatus(error)` expose the same classification
+for consumers mapping `GhError` into their own errors.
+
+### Rate limits
+
+`RateLimit.get(resource?, options?)` reads the `core` (default), `graphql` or
+`search` quota from `gh api rate_limit`, which does not count against it.
+`RateLimit.cached(timeToLive, options?)` builds an Effect `Cache` of those reads
+keyed by resource. Failed reads are not kept, and `Cache.invalidate` forces a
+fresh read after a rate-limited failure.
 
 ## Repository and issues
 

package/dist/errors.d.ts

@@ -2,6 +2,8 @@ import { Schema } from "effect";
 declare const GhCommandError_base: Schema.Class<GhCommandError, Schema.TaggedStruct<"GhCommandError", {
     readonly executable: Schema.String;
     readonly exitCode: Schema.Int;
+    readonly stdout: Schema.String;
+    readonly stdoutTruncated: Schema.Boolean;
     readonly stderr: Schema.String;
     readonly stderrTruncated: Schema.Boolean;
 }>, import("effect/Cause").YieldableError>;

package/dist/errors.js

@@ -2,6 +2,8 @@ import { Schema } from "effect";
 export class GhCommandError extends Schema.TaggedError()("GhCommandError", {
     executable: Schema.String,
     exitCode: Schema.Int,
+    stdout: Schema.String,
+    stdoutTruncated: Schema.Boolean,
     stderr: Schema.String,
     stderrTruncated: Schema.Boolean,
 }) {

package/dist/gh.d.ts

@@ -1,6 +1,7 @@
 import { Context, Duration, Effect, Layer, Schema, Stream } from "effect";
 import { ChildProcessSpawner } from "effect/process";
 import { type GhError } from "./errors.js";
+import { retryTransient } from "./transient.js";
 export interface GhOptions {
     readonly executable?: string;
     readonly cwd?: string;
@@ -33,6 +34,8 @@ export interface Interface {
 }
 declare const Gh_base: Context.ServiceClass<Gh, "@timmo001/effect-gh/Gh", Interface>;
 export declare class Gh extends Gh_base {
+    /** Retries transient `gh` failures with bounded, jittered backoff. See {@link retryTransient}. */
+    static readonly retryTransient: typeof retryTransient;
 }
 export declare const layer: (defaults?: GhOptions) => Layer.Layer<Gh, never, ChildProcessSpawner.ChildProcessSpawner>;
 export {};

package/dist/gh.js

@@ -1,6 +1,7 @@
 import { Context, Duration, Effect, Layer, Match, Predicate, Schema, Stream, } from "effect";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
 import { GhCommandError, GhDecodeError, GhPlatformError, GhTimeoutError, } from "./errors.js";
+import { retryTransient } from "./transient.js";
 export const GhOutput = Schema.Struct({
     stdout: Schema.String,
     stderr: Schema.String,
@@ -11,8 +12,10 @@ export const GhChunk = Schema.TaggedUnion({
     Stderr: { text: Schema.String },
 });
 export class Gh extends Context.Service()("@timmo001/effect-gh/Gh") {
+    /** Retries transient `gh` failures with bounded, jittered backoff. See {@link retryTransient}. */
+    static retryTransient = retryTransient;
 }
-const stderrLimit = 65_536;
+const outputLimit = 65_536;
 export const layer = (defaults = {}) => Layer.effect(Gh, Effect.gen(function* () {
     const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
     const open = Effect.fn("Gh.stream")(function* (args, options) {
@@ -40,11 +43,17 @@ export const layer = (defaults = {}) => Layer.effect(Gh, Effect.gen(function* ()
             forceKillAfter: "1 second",
         }))
             .pipe(Effect.mapError((cause) => new GhPlatformError({ executable, cause })));
+        let stdout = "";
+        let stdoutTruncated = false;
         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);
+        const output = Stream.merge(handle.stdout.pipe(Stream.decodeText(), Stream.map((text) => {
+            stdoutTruncated ||= stdout.length + text.length > outputLimit;
+            stdout = (stdout + text).slice(-outputLimit);
+            return GhChunk.cases.Stdout.make({ text });
+        })), handle.stderr.pipe(Stream.decodeText(), Stream.map((text) => {
+            stderrTruncated ||= stderr.length + text.length > outputLimit;
+            stderr = (stderr + text).slice(-outputLimit);
             return GhChunk.cases.Stderr.make({ text });
         }))).pipe(Stream.mapError((cause) => new GhPlatformError({ executable, cause })));
         const completion = Effect.gen(function* () {
@@ -53,6 +62,8 @@ export const layer = (defaults = {}) => Layer.effect(Gh, Effect.gen(function* ()
                 return yield* new GhCommandError({
                     executable,
                     exitCode,
+                    stdout,
+                    stdoutTruncated,
                     stderr,
                     stderrTruncated,
                 });

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { Gh, GhChunk, GhOutput, layer, type GhOptions, type Interface, } from "./gh.js";
 export { GhCommandError, GhDecodeError, GhPlatformError, GhTimeoutError, type GhError, } from "./errors.js";
+export { defaultRetrySchedule, httpStatus, isRateLimited, isTransient, type RetryTransientOptions, } from "./transient.js";
 export * as Api from "./api.js";
+export * as RateLimit from "./rate-limit.js";
 export * as Repository from "./repository.js";
 export * as Issue from "./issue.js";
 export * as PullRequest from "./pull-request.js";

package/dist/index.js

@@ -1,6 +1,8 @@
 export { Gh, GhChunk, GhOutput, layer, } from "./gh.js";
 export { GhCommandError, GhDecodeError, GhPlatformError, GhTimeoutError, } from "./errors.js";
+export { defaultRetrySchedule, httpStatus, isRateLimited, isTransient, } from "./transient.js";
 export * as Api from "./api.js";
+export * as RateLimit from "./rate-limit.js";
 export * as Repository from "./repository.js";
 export * as Issue from "./issue.js";
 export * as PullRequest from "./pull-request.js";

package/dist/rate-limit.d.ts

@@ -0,0 +1,21 @@
+import { Cache, Duration, Effect, Schema } from "effect";
+import type { GhError } from "./errors.js";
+import type { Gh, GhOptions } from "./gh.js";
+export declare const Resource: Schema.Struct<{
+    readonly limit: Schema.Int;
+    readonly used: Schema.Int;
+    readonly remaining: Schema.Int;
+    /** Reset time in epoch seconds. */
+    readonly reset: Schema.Int;
+}>;
+export interface Resource extends Schema.Schema.Type<typeof Resource> {
+}
+export type ResourceName = "core" | "graphql" | "search";
+/** Reads one REST, GraphQL or search quota from `gh api rate_limit`, which does not count against the quota. */
+export declare const get: (resource?: ResourceName | undefined, options?: Omit<GhOptions, "stdin"> | undefined) => Effect.Effect<Resource, GhError, Gh>;
+/**
+ * Builds a cache of {@link get} reads keyed by resource. Successful reads live
+ * for `timeToLive`; failed reads are not kept. Use `Cache.get` to read and
+ * `Cache.invalidate` after a rate-limited failure.
+ */
+export declare const cached: (timeToLive: Duration.Input, options?: Omit<GhOptions, "stdin">) => Effect.Effect<Cache.Cache<ResourceName, Resource, GhError>, never, Gh>;

package/dist/rate-limit.js

@@ -0,0 +1,30 @@
+import { Cache, Duration, Effect, Exit, Schema } from "effect";
+import * as Api from "./api.js";
+export const Resource = Schema.Struct({
+    limit: Schema.Int,
+    used: Schema.Int,
+    remaining: Schema.Int,
+    /** Reset time in epoch seconds. */
+    reset: Schema.Int,
+});
+const response = Schema.Struct({
+    resources: Schema.Struct({
+        core: Resource,
+        graphql: Resource,
+        search: Resource,
+    }),
+});
+/** Reads one REST, GraphQL or search quota from `gh api rate_limit`, which does not count against the quota. */
+export const get = Effect.fn("RateLimit.get")(function* (resource = "core", options) {
+    const { resources } = yield* Api.json({ endpoint: "rate_limit", method: "GET", ...(options && { options }) }, response);
+    return resources[resource];
+});
+/**
+ * Builds a cache of {@link get} reads keyed by resource. Successful reads live
+ * for `timeToLive`; failed reads are not kept. Use `Cache.get` to read and
+ * `Cache.invalidate` after a rate-limited failure.
+ */
+export const cached = (timeToLive, options) => Cache.makeWith((resource) => get(resource, options), {
+    capacity: 3,
+    timeToLive: (exit) => (Exit.isSuccess(exit) ? timeToLive : Duration.zero),
+});

package/dist/transient.d.ts

@@ -0,0 +1,25 @@
+import { Effect, Option, Schedule } from "effect";
+import { type GhError } from "./errors.js";
+/** HTTP status reported by a failed `gh` command, such as `gh: Not Found (HTTP 404)`. */
+export declare const httpStatus: (error: GhError) => Option.Option<number>;
+/** Whether a `gh` command failed because of a primary or secondary GitHub rate limit. */
+export declare const isRateLimited: (error: GhError) => boolean;
+/**
+ * Whether a failure is worth retrying: timeouts, rate limits, HTTP 408, 429 and
+ * 5xx gateway statuses, and network failures reported by `gh`.
+ */
+export declare const isTransient: (error: GhError) => boolean;
+/** Jittered exponential backoff from 250 milliseconds, capped at 10 seconds. */
+export declare const defaultRetrySchedule: Schedule.Schedule<import("effect/Duration").Duration, unknown, never, never>;
+/** Options for {@link retryTransient}. */
+export interface RetryTransientOptions<B = unknown, ES = never, R = never> {
+    /** Delay policy between attempts. Defaults to {@link defaultRetrySchedule}. */
+    readonly schedule?: Schedule.Schedule<B, GhError, ES, R>;
+    /** Retries after the first attempt. Defaults to 3. */
+    readonly times?: number;
+}
+/**
+ * Retries failures matched by {@link isTransient}. Apply only to idempotent
+ * reads: a mutation can take effect even when the command reports a failure.
+ */
+export declare const retryTransient: <B = unknown, ES = never, R1 = never>(options?: RetryTransientOptions<B, ES, R1>) => <A, E extends GhError, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E | ES, R | R1>;

package/dist/transient.js

@@ -0,0 +1,44 @@
+import { Effect, Match, Option, Schedule } from "effect";
+import { GhCommandError } from "./errors.js";
+const statusPattern = /\b(?:HTTP|status(?: code)?)\s*(\d{3})\b/i;
+const transientStatuses = new Set([
+    408, 429, 500, 502, 503, 504,
+]);
+const networkPattern = /connection reset|could not resolve host|error connecting to|no such host|temporary failure in name resolution|network is unreachable|no route to host|temporarily unavailable|tls handshake|i\/o timeout|timed out|context deadline exceeded/i;
+/** HTTP status reported by a failed `gh` command, such as `gh: Not Found (HTTP 404)`. */
+export const httpStatus = (error) => {
+    if (!(error instanceof GhCommandError))
+        return Option.none();
+    const match = statusPattern.exec(error.stderr);
+    return match?.[1] === undefined
+        ? Option.none()
+        : Option.some(Number(match[1]));
+};
+/** Whether a `gh` command failed because of a primary or secondary GitHub rate limit. */
+export const isRateLimited = (error) => error instanceof GhCommandError &&
+    (Option.contains(httpStatus(error), 429) ||
+        /rate limit/i.test(`${error.stderr}\n${error.stdout}`));
+/**
+ * Whether a failure is worth retrying: timeouts, rate limits, HTTP 408, 429 and
+ * 5xx gateway statuses, and network failures reported by `gh`.
+ */
+export const isTransient = (error) => Match.value(error).pipe(Match.tags({
+    GhTimeoutError: () => true,
+    GhCommandError: (error) => isRateLimited(error) ||
+        Option.exists(httpStatus(error), (status) => transientStatuses.has(status)) ||
+        networkPattern.test(error.stderr),
+}), Match.orElse(() => false));
+/** Jittered exponential backoff from 250 milliseconds, capped at 10 seconds. */
+export const defaultRetrySchedule = Schedule.min([
+    Schedule.exponential("250 millis"),
+    Schedule.spaced("10 seconds"),
+]).pipe(Schedule.jittered);
+/**
+ * Retries failures matched by {@link isTransient}. Apply only to idempotent
+ * reads: a mutation can take effect even when the command reports a failure.
+ */
+export const retryTransient = (options = {}) => (self) => Effect.retry(self, {
+    while: isTransient,
+    schedule: options.schedule ?? defaultRetrySchedule,
+    times: options.times ?? 3,
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@timmo001/effect-gh",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "An Effect v4 SDK for the GitHub CLI",
   "license": "Apache-2.0",
   "type": "module",
@@ -38,7 +38,7 @@
     "test": "bun test",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "prepare": "effect-tsgo patch",
+    "prepare": "effect-tsgo patch --force=false",
     "prepack": "bun run build"
   },
   "peerDependencies": {
@@ -46,9 +46,9 @@
   },
   "devDependencies": {
     "@effect/platform-node": "4.0.0-rc.118",
-    "@effect/tsgo": "0.46.1",
+    "@effect/tsgo": "0.47.0",
     "@oxlint/plugins": "1.86.0",
-    "@timmo001/oxlint-rules": "0.4.0",
+    "@timmo001/oxlint-rules": "0.5.0",
     "@types/bun": "1.4.2",
     "effect": "4.0.0-rc.118",
     "oxlint": "1.86.0",

package/src/errors.ts

@@ -5,6 +5,8 @@ export class GhCommandError extends Schema.TaggedError<GhCommandError>()(
   {
     executable: Schema.String,
     exitCode: Schema.Int,
+    stdout: Schema.String,
+    stdoutTruncated: Schema.Boolean,
     stderr: Schema.String,
     stderrTruncated: Schema.Boolean,
   },

package/src/gh.ts

@@ -16,6 +16,7 @@ import {
   GhTimeoutError,
   type GhError,
 } from "./errors.js";
+import { retryTransient } from "./transient.js";
 
 export interface GhOptions {
   readonly executable?: string;
@@ -60,9 +61,12 @@ export interface Interface {
 
 export class Gh extends Context.Service<Gh, Interface>()(
   "@timmo001/effect-gh/Gh",
-) {}
+) {
+  /** Retries transient `gh` failures with bounded, jittered backoff. See {@link retryTransient}. */
+  static readonly retryTransient = retryTransient;
+}
 
-const stderrLimit = 65_536;
+const outputLimit = 65_536;
 
 export const layer = (
   defaults: GhOptions = {},
@@ -108,19 +112,26 @@ export const layer = (
             ),
           );
 
+        let stdout = "";
+        let stdoutTruncated = false;
         let stderr = "";
         let stderrTruncated = false;
 
         const output = Stream.merge(
           handle.stdout.pipe(
             Stream.decodeText(),
-            Stream.map((text) => GhChunk.cases.Stdout.make({ text })),
+            Stream.map((text) => {
+              stdoutTruncated ||= stdout.length + text.length > outputLimit;
+              stdout = (stdout + text).slice(-outputLimit);
+
+              return GhChunk.cases.Stdout.make({ text });
+            }),
           ),
           handle.stderr.pipe(
             Stream.decodeText(),
             Stream.map((text) => {
-              stderrTruncated ||= stderr.length + text.length > stderrLimit;
-              stderr = (stderr + text).slice(-stderrLimit);
+              stderrTruncated ||= stderr.length + text.length > outputLimit;
+              stderr = (stderr + text).slice(-outputLimit);
 
               return GhChunk.cases.Stderr.make({ text });
             }),
@@ -142,6 +153,8 @@ export const layer = (
             return yield* new GhCommandError({
               executable,
               exitCode,
+              stdout,
+              stdoutTruncated,
               stderr,
               stderrTruncated,
             });

package/src/index.ts

@@ -15,8 +15,18 @@ export {
   type GhError,
 } from "./errors.js";
 
+export {
+  defaultRetrySchedule,
+  httpStatus,
+  isRateLimited,
+  isTransient,
+  type RetryTransientOptions,
+} from "./transient.js";
+
 export * as Api from "./api.js";
 
+export * as RateLimit from "./rate-limit.js";
+
 export * as Repository from "./repository.js";
 
 export * as Issue from "./issue.js";

package/src/rate-limit.ts

@@ -0,0 +1,51 @@
+import { Cache, Duration, Effect, Exit, Schema } from "effect";
+import * as Api from "./api.js";
+import type { GhError } from "./errors.js";
+import type { Gh, GhOptions } from "./gh.js";
+
+export const Resource = Schema.Struct({
+  limit: Schema.Int,
+  used: Schema.Int,
+  remaining: Schema.Int,
+  /** Reset time in epoch seconds. */
+  reset: Schema.Int,
+});
+
+export interface Resource extends Schema.Schema.Type<typeof Resource> {}
+
+export type ResourceName = "core" | "graphql" | "search";
+
+const response = Schema.Struct({
+  resources: Schema.Struct({
+    core: Resource,
+    graphql: Resource,
+    search: Resource,
+  }),
+});
+
+/** Reads one REST, GraphQL or search quota from `gh api rate_limit`, which does not count against the quota. */
+export const get = Effect.fn("RateLimit.get")(function* (
+  resource: ResourceName = "core",
+  options?: Omit<GhOptions, "stdin">,
+): Effect.fn.Return<Resource, GhError, Gh> {
+  const { resources } = yield* Api.json(
+    { endpoint: "rate_limit", method: "GET", ...(options && { options }) },
+    response,
+  );
+
+  return resources[resource];
+});
+
+/**
+ * Builds a cache of {@link get} reads keyed by resource. Successful reads live
+ * for `timeToLive`; failed reads are not kept. Use `Cache.get` to read and
+ * `Cache.invalidate` after a rate-limited failure.
+ */
+export const cached = (
+  timeToLive: Duration.Input,
+  options?: Omit<GhOptions, "stdin">,
+): Effect.Effect<Cache.Cache<ResourceName, Resource, GhError>, never, Gh> =>
+  Cache.makeWith((resource: ResourceName) => get(resource, options), {
+    capacity: 3,
+    timeToLive: (exit) => (Exit.isSuccess(exit) ? timeToLive : Duration.zero),
+  });

package/src/transient.ts

@@ -0,0 +1,76 @@
+import { Effect, Match, Option, Schedule } from "effect";
+import { GhCommandError, type GhError } from "./errors.js";
+
+const statusPattern = /\b(?:HTTP|status(?: code)?)\s*(\d{3})\b/i;
+
+const transientStatuses: ReadonlySet<number> = new Set([
+  408, 429, 500, 502, 503, 504,
+]);
+
+const networkPattern =
+  /connection reset|could not resolve host|error connecting to|no such host|temporary failure in name resolution|network is unreachable|no route to host|temporarily unavailable|tls handshake|i\/o timeout|timed out|context deadline exceeded/i;
+
+/** HTTP status reported by a failed `gh` command, such as `gh: Not Found (HTTP 404)`. */
+export const httpStatus = (error: GhError): Option.Option<number> => {
+  if (!(error instanceof GhCommandError)) return Option.none();
+  const match = statusPattern.exec(error.stderr);
+
+  return match?.[1] === undefined
+    ? Option.none()
+    : Option.some(Number(match[1]));
+};
+
+/** Whether a `gh` command failed because of a primary or secondary GitHub rate limit. */
+export const isRateLimited = (error: GhError): boolean =>
+  error instanceof GhCommandError &&
+  (Option.contains(httpStatus(error), 429) ||
+    /rate limit/i.test(`${error.stderr}\n${error.stdout}`));
+
+/**
+ * Whether a failure is worth retrying: timeouts, rate limits, HTTP 408, 429 and
+ * 5xx gateway statuses, and network failures reported by `gh`.
+ */
+export const isTransient = (error: GhError): boolean =>
+  Match.value(error).pipe(
+    Match.tags({
+      GhTimeoutError: () => true,
+      GhCommandError: (error) =>
+        isRateLimited(error) ||
+        Option.exists(httpStatus(error), (status) =>
+          transientStatuses.has(status),
+        ) ||
+        networkPattern.test(error.stderr),
+    }),
+    Match.orElse(() => false),
+  );
+
+/** Jittered exponential backoff from 250 milliseconds, capped at 10 seconds. */
+export const defaultRetrySchedule = Schedule.min([
+  Schedule.exponential("250 millis"),
+  Schedule.spaced("10 seconds"),
+]).pipe(Schedule.jittered);
+
+/** Options for {@link retryTransient}. */
+export interface RetryTransientOptions<B = unknown, ES = never, R = never> {
+  /** Delay policy between attempts. Defaults to {@link defaultRetrySchedule}. */
+  readonly schedule?: Schedule.Schedule<B, GhError, ES, R>;
+  /** Retries after the first attempt. Defaults to 3. */
+  readonly times?: number;
+}
+
+/**
+ * Retries failures matched by {@link isTransient}. Apply only to idempotent
+ * reads: a mutation can take effect even when the command reports a failure.
+ */
+export const retryTransient =
+  <B = unknown, ES = never, R1 = never>(
+    options: RetryTransientOptions<B, ES, R1> = {},
+  ) =>
+  <A, E extends GhError, R>(
+    self: Effect.Effect<A, E, R>,
+  ): Effect.Effect<A, E | ES, R | R1> =>
+    Effect.retry(self, {
+      while: isTransient,
+      schedule: options.schedule ?? defaultRetrySchedule,
+      times: options.times ?? 3,
+    });