Effect Gh

Effect GH

Prefer @timmo001/effect-gh when an Effect application needs the GitHub CLI's authentication, repository context or command behaviour. Use its services and operations instead of rebuilding subprocess execution, JSON decoding and cancellation. It wraps the actual gh executable; direct GitHub HTTP integrations have a different transport contract.

Read the current contract

1. Inspect the consumer's manifest and lockfile for the SDK and Effect versions. Read the installed SDK README and declarations, and match the platform adapter to the SDK's Effect peer. If adding the dependency, verify its available release and peer requirements before choosing versions.
2. Read the relevant current docs before coding:
   • README: setup, operations, errors, pagination and streams.
   • Package manifest and exports: dependency requirements and public surface.
   • Notification example: nullable responses and mutations with empty output.
   • Workflow example: REST page envelopes and run attempts. These links follow development. Prefer the installed release's docs and source when they differ. Inspect installed gh help for required flags.

Use the package

1. Choose the smallest public operation that fits. Use Repository, Issue, PullRequest and Workflow for their typed operations; use Api for other endpoints. Use the Gh service's raw execution or stream methods when a CLI command has no wrapper. Confirm signatures from the current exports.

2. Provide the SDK layer with the consumer's ChildProcessSpawner. Keep runtime execution at the application boundary. A Node consumer can compose it like this:

   import { NodeServices } from "@effect/platform-node";
   import { Api, layer } from "@timmo001/effect-gh";
   import { Effect, Layer, Schema } from "effect";
   
   const ghLayer = layer({ timeout: "30 seconds" }).pipe(
     Layer.provide(NodeServices.layer),
   );
   
   const viewer = Api.json(
     { endpoint: "user", method: "GET" },
     Schema.Struct({ login: Schema.String }),
   ).pipe(Effect.provide(ghLayer));
   

   This constructs an effect; the caller decides when to run it. Supply working directory, repository, host and timeout deliberately where context matters. Reuse gh authentication rather than retrieving or logging tokens.

3. Preserve boundary semantics:

   • Decode JSON with a response Schema. Use raw output for empty or non-JSON responses, and JSON request bodies rather than CLI field interpolation.
   • Specify API methods explicitly. Paginated results are arrays of decoded pages; flatten only after decoding each endpoint's page shape.
   • Treat pending and failed PR checks as structured results where the wrapper supports them. Preserve genuine typed failures and Effect interruption.
   • Consume output and watches as Streams. Keep their scope owned by the caller; early termination cancels work and does not prove a successful final exit.
   • Keep retries explicit and bounded at a known-idempotent boundary. A failed mutation may already have taken effect; replaying emitted streams can duplicate output.

4. Verify the integration through the public SDK boundary. Typecheck layer and Schema requirements, test argument construction and relevant failure paths with a supplied test spawner, and run the consumer's normal checks. When replacing an existing wrapper, account for its pagination, retry, timeout and error contracts rather than assuming it is a drop-in replacement.