@timmo001/effect-gh 0.1.0-0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,299 @@
+# effect-gh
+
+An Effect v4 SDK for the GitHub CLI (`gh`).
+
+Inspired by the Effect-native API in
+[dmmulroy/herdr-ts-sdk](https://github.com/dmmulroy/herdr-ts-sdk).
+
+## Requirements
+
+- Effect matching `peerDependencies.effect` in [package.json](package.json), with
+  a compatible consumer-chosen platform adapter.
+- GitHub CLI installed and authenticated through `gh auth login` or its standard
+  token environment variables.
+- An ESM consumer. Bun runs the TypeScript source directly; Node uses the compiled
+  JavaScript in a built package. The platform adapter stays a consumer dependency.
+
+## Install
+
+The commands below read Effect and Node adapter versions from the installed SDK's
+`package.json`. The Node adapter also works in Bun.
+
+### Bun
+
+Run from your application directory:
+
+```sh
+bun add github:timmo001/effect-gh
+bun add "effect@$(bun -p 'require("@timmo001/effect-gh/package.json").peerDependencies.effect')" \
+  "@effect/platform-node@$(bun -p 'require("@timmo001/effect-gh/package.json").devDependencies["@effect/platform-node"]')"
+```
+
+Commit `package.json` and `bun.lock` in your application to preserve the resolved
+GitHub revision and dependency versions. The `bun` export resolves to
+`src/index.ts`, and types resolve to the same source. GitHub installs need no
+build step or consumer patch.
+
+### Node
+
+Run from your application directory to build and install a package from source
+with the [mise](https://mise.jdx.dev/getting-started.html)-pinned tools:
+
+```sh
+git clone https://github.com/timmo001/effect-gh.git .effect-gh
+(
+  cd .effect-gh &&
+    mise install &&
+    mise run install &&
+    mise exec -- npm pack --pack-destination ..
+)
+bun add ./timmo001-effect-gh-*.tgz
+bun add "effect@$(bun -p 'require("@timmo001/effect-gh/package.json").peerDependencies.effect')" \
+  "@effect/platform-node@$(bun -p 'require("@timmo001/effect-gh/package.json").devDependencies["@effect/platform-node"]')"
+```
+
+Keep the archive with your application for repeatable installs. The `.effect-gh`
+checkout is only needed to build it.
+
+The first npm publication is pending. After publication, either runtime can
+install directly from npm:
+
+```sh
+bun add @timmo001/effect-gh
+bun add "effect@$(bun -p 'require("@timmo001/effect-gh/package.json").peerDependencies.effect')" \
+  "@effect/platform-node@$(bun -p 'require("@timmo001/effect-gh/package.json").devDependencies["@effect/platform-node"]')"
+```
+
+### GitHub authentication
+
+Install [GitHub CLI](https://cli.github.com/) separately, then authenticate:
+
+```sh
+gh auth login
+gh auth status
+```
+
+For automation, supply `GH_TOKEN` or another gh-supported authentication
+configuration through the environment. The SDK uses it without a separate login.
+
+## Agent skill
+
+[The effect-gh skill](https://github.com/timmo001/effect-gh/blob/main/skills/effect-gh/SKILL.md)
+guides Effect integrations towards the package and its current documentation.
+It follows the [Agent Skills specification](https://agentskills.io/specification).
+Import the complete `skills/effect-gh/` directory unchanged into your skill
+collection; it has no client-specific configuration or local path dependencies.
+
+## Core SDK
+
+`Gh` is the service tag. `layer(options?)` captures the consumer-provided
+`ChildProcessSpawner` and starts no processes until an operation runs. Consumers
+choose their platform layer and runtime. For example, with `@effect/platform-node`:
+
+```ts
+import { NodeServices } from "@effect/platform-node";
+import { Effect, Layer, Schema } from "effect";
+import { Gh, layer } from "@timmo001/effect-gh";
+
+const ghLayer = layer({ timeout: "30 seconds" }).pipe(
+  Layer.provide(NodeServices.layer),
+);
+
+const program = Effect.gen(function* () {
+  const gh = yield* Gh;
+  return yield* gh.json(
+    ["api", "user"],
+    Schema.Struct({ login: Schema.String }),
+  );
+}).pipe(Effect.provide(ghLayer));
+```
+
+- `execute(args, options?)` returns `{ stdout, stderr, exitCode }` on exit zero.
+  It buffers both UTF-8 outputs in memory, so use `stream` for large output.
+- `json(args, schema, options?)` decodes stdout as JSON through the supplied
+  Schema, preserving its decoding service requirements. Supply any `--json`
+  fields required by the selected `gh` command yourself.
+- `stream(args, options?)` emits `{ _tag: "Stdout" | "Stderr", text }` chunks.
+  It drains both pipes concurrently with backpressure and preserves order within
+  each pipe, with no ordering guarantee between pipes. Chunk boundaries are not
+  line boundaries. Completion waits for both pipes and a successful exit.
+
+`GhOptions` accepts `executable` (default `gh`), `cwd`, `env`, `stdin` (string or
+`Uint8Array`) and `timeout` (an Effect duration). Call options override layer
+defaults; environment entries merge. `timeout: null` disables a layer timeout.
+Timeouts cover spawning, execution and output draining, rather than idle time.
+There is no timeout by default. Schema decoding runs after the subprocess timeout.
+
+Commands pass literal argv without a shell. The platform inherits the environment,
+including existing `gh` authentication and configuration. Supplied environment
+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`.
+The stream emits trailing output before reporting a nonzero exit.
+
+Interruption, timeout and early stream termination close the child scope. The
+platform terminates the child, escalating after one second if needed. An early
+consumer stop does not validate the final exit code. Interruptions remain Effect
+interruptions rather than being converted into SDK errors.
+
+## API requests
+
+`Api.raw(request)` returns buffered output, including empty or non-JSON responses.
+`Api.json(request, schema)` decodes one JSON response. Every request specifies a
+method, which the SDK passes explicitly to `gh api`.
+
+```ts
+import { Api } from "@timmo001/effect-gh";
+import { Schema } from "effect";
+
+const viewer = Api.json(
+  { endpoint: "user", method: "GET" },
+  Schema.Struct({ login: Schema.String }),
+);
+
+const subscription = Api.raw({
+  endpoint: "notifications/threads/123/subscription",
+  method: "PUT",
+  body: { ignored: true },
+});
+```
+
+Requests accept `hostname`, `headers`, `query`, a JSON `body`, and core overrides
+under `options`. Query values are URL-encoded; arrays repeat the key. JSON bodies
+go through stdin rather than CLI field interpolation. Bodyless calls clear any
+layer-level stdin.
+
+`Api.pages(request, pageSchema)` runs a bodyless REST GET with
+`--paginate --slurp`. The result is an array of decoded **pages**, not flattened
+items: use an array schema for array endpoints, or an object schema for envelopes
+such as `{ workflow_runs: [...] }`. It buffers all pages and does not provide a
+snapshot-consistency guarantee. GraphQL cursor pagination remains available
+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.
+
+## Repository and issues
+
+```ts
+import { Issue, Repository } from "@timmo001/effect-gh";
+
+const repository = Repository.view("owner/repo");
+const issues = Issue.list({ repo: "owner/repo", state: "open", limit: 50 });
+const issue = Issue.view(42, { repo: "owner/repo" });
+```
+
+`Repository.view(repo?, options?)` returns the repository name, URL, privacy and
+nullable default branch. Omitting the selector uses gh's working-directory
+context. Issue list/view also accept an optional `repo`, plus core execution
+options as their final argument. Lists default to 30 open issues, and support
+state, limit, labels, assignee and search filters. `Issue.view` includes the body.
+Invalid numeric limits and selectors fail with `IssueInvalidInput` before spawning.
+
+## Pull requests
+
+```ts
+import { PullRequest } from "@timmo001/effect-gh";
+
+const pullRequests = PullRequest.list({ repository: "owner/repo" });
+const pullRequest = PullRequest.view(42, { repository: "owner/repo" });
+const checks = PullRequest.checks(42, {
+  repository: "owner/repo",
+  required: true,
+});
+```
+
+Pull request options require `repository` and accept core execution overrides.
+Lists default to 30 open PRs, with optional state, limit, base and head filters.
+List/view return number, title, URL, state, draft status, head branch and head SHA.
+
+`PullRequest.checks` returns `{ checks, status, exitCode }`. Valid check output
+from exits 0, 1 and 8 is data with status `success`, `failure` or `pending`.
+Genuine command failures retain their typed error; no command is re-executed to
+retrieve its output.
+
+## Workflow runs
+
+```ts
+import { Workflow } from "@timmo001/effect-gh";
+
+const runs = Workflow.list({ repo: "owner/repo", branch: "main", limit: 20 });
+const run = Workflow.view({ repo: "owner/repo", runId: 123, attempt: 2 });
+const logs = Workflow.logs({
+  repo: "owner/repo",
+  runId: 123,
+  attempt: 2,
+  failedOnly: true,
+});
+const progress = Workflow.watch(
+  { repo: "owner/repo", runId: 123, interval: 3 },
+  { timeout: null },
+);
+```
+
+Workflow operations require `repo` and accept core options as a final argument.
+Lists default to at most 20 runs, with branch, commit, workflow and status filters.
+Run data uses gh's camelCase JSON fields, including `databaseId` and `attempt`.
+Log retrieval supports an explicit attempt and job, and returns buffered text.
+Invalid selectors and numeric options fail with `WorkflowInvalidOptions`.
+
+`Workflow.watch` emits core stdout/stderr chunks using
+`gh run watch --compact --exit-status`. It defaults to a three-second refresh
+interval, fails when the run fails and inherits the core timeout. It requires a
+gh version with `--compact` support; gh watch does not support fine-grained PATs.
+Use REST page schemas through `Api` when a consumer needs snake_case fields,
+page envelopes or attempt-specific jobs.
+
+## Consumer examples
+
+- [Notifications](https://github.com/timmo001/effect-gh/blob/main/examples/notifications.ts): nullable notification fields,
+  single-page counts, mark-read/done and subscription requests with empty
+  responses, plus consumer-side NodeServices composition.
+- [Workflow runs](https://github.com/timmo001/effect-gh/blob/main/examples/workflow-runs.ts): REST page envelopes, branch and SHA
+  filtering, retained run attempts, attempt-specific jobs and failed logs.
+
+These examples are typechecked and tested against fixtures matching the dotfiles
+and Herdr Workflow Watch contracts. They preserve the data needed by those
+consumers; filtering policy, reconciliation, completeness checks and runtime
+ownership stay with the application. They are migration references, not drop-in
+replacements for either existing service.
+
+## Development
+
+Use the tool versions pinned in [mise.toml](mise.toml) and Bun for dependencies.
+
+```sh
+mise run install
+mise run check
+mise run build
+```
+
+## Releases
+
+To inspect the package locally, run `mise exec -- npm pack --dry-run`; the pack
+hook builds `dist/`.
+The package includes only the ESM build, declarations, README, licence and package
+metadata.
+
+Before the first automated publication, configure npm trusted publishing for
+`timmo001/effect-gh` and workflow filename `release.yml`. An initial package
+publication may be needed before that configuration is available. The release
+workflow uses the shared npm publisher and resolves Bun and Node versions from
+`mise.toml` through mise.
+
+For a release, set the package version, keep `bun.lock` in sync, and pass
+`mise run check` and `mise run build`. Commit and push the reviewed version, then
+publish a GitHub release with a tag matching the version exactly, such as `0.1.0`.
+The publisher verifies the tag against the package version, validates and builds
+the package, then publishes to npm with provenance.

package/dist/api.d.ts

@@ -0,0 +1,28 @@
+import { Effect, Schema } from "effect";
+import { type GhError } from "./errors.js";
+import { Gh, type GhOptions, type GhOutput } from "./gh.js";
+export declare const Method: Schema.Literals<readonly ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "TRACE", "CONNECT"]>;
+export type Method = typeof Method.Type;
+declare const requestSchema: Schema.Struct<{
+    readonly endpoint: Schema.NonEmptyString;
+    readonly method: Schema.Literals<readonly ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS", "TRACE", "CONNECT"]>;
+    readonly hostname: Schema.optionalKey<Schema.NonEmptyString>;
+    readonly query: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean]>>]>>>;
+    readonly headers: Schema.optionalKey<Schema.$Record<Schema.String, Schema.String>>;
+    readonly body: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+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;
+}
+/** Returns stdout, stderr and the CLI exit code, including empty or non-JSON responses. Never retries. */
+export declare const raw: (request: Request) => Effect.Effect<GhOutput, GhError, Gh>;
+/** Decodes one JSON response. Encoding and decoding failures are GhDecodeError; requests never retry. */
+export declare const json: <S extends Schema.Constraint>(request: Request, schema: S) => Effect.Effect<S["Type"], GhError, Gh | S["DecodingServices"]>;
+/** Fetches REST GET pages with --paginate --slurp. The schema describes each page, preserving envelopes. Never retries. */
+export declare const pages: <S extends Schema.Constraint>(request: PageRequest, schema: S) => Effect.Effect<readonly S["Type"][], GhError, Gh | S["DecodingServices"]>;
+export {};

package/dist/api.js

@@ -0,0 +1,87 @@
+import { Effect, Schema } from "effect";
+import { GhDecodeError } from "./errors.js";
+import { Gh } from "./gh.js";
+export const Method = Schema.Literals([
+    "GET",
+    "HEAD",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "OPTIONS",
+    "TRACE",
+    "CONNECT",
+]);
+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),
+});
+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) {
+    const input = yield* Schema.decodeEffect(requestSchema)(request).pipe(Effect.mapError((cause) => new GhDecodeError({ cause })));
+    const endpoint = yield* Effect.try({
+        try: () => {
+            const query = [];
+            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;
+    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) {
+    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* (request, schema) {
+    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* (request, schema) {
+    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/dist/errors.d.ts

@@ -0,0 +1,28 @@
+import { Schema } from "effect";
+declare const GhCommandError_base: Schema.Class<GhCommandError, Schema.TaggedStruct<"GhCommandError", {
+    readonly executable: Schema.String;
+    readonly exitCode: Schema.Int;
+    readonly stderr: Schema.String;
+    readonly stderrTruncated: Schema.Boolean;
+}>, import("effect/Cause").YieldableError>;
+export declare class GhCommandError extends GhCommandError_base {
+}
+declare const GhPlatformError_base: Schema.Class<GhPlatformError, Schema.TaggedStruct<"GhPlatformError", {
+    readonly executable: Schema.String;
+    readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+export declare class GhPlatformError extends GhPlatformError_base {
+}
+declare const GhTimeoutError_base: Schema.Class<GhTimeoutError, Schema.TaggedStruct<"GhTimeoutError", {
+    readonly executable: Schema.String;
+    readonly timeoutMs: Schema.Finite;
+}>, import("effect/Cause").YieldableError>;
+export declare class GhTimeoutError extends GhTimeoutError_base {
+}
+declare const GhDecodeError_base: Schema.Class<GhDecodeError, Schema.TaggedStruct<"GhDecodeError", {
+    readonly cause: Schema.Defect;
+}>, import("effect/Cause").YieldableError>;
+export declare class GhDecodeError extends GhDecodeError_base {
+}
+export type GhError = GhCommandError | GhPlatformError | GhTimeoutError | GhDecodeError;
+export {};

package/dist/errors.js

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