@effected/github 0.3.0 → 0.4.1

package/index.d.ts

@@ -577,28 +577,92 @@ interface GitHubClientOptions {
    */
   readonly fetch?: typeof globalThis.fetch | undefined;
 }
+/**
+ * One call served by {@link GitHubClient.layerFixture}, as recorded in
+ * {@link GitHubFixtures.requested}.
+ *
+ * @public
+ */
+interface RecordedCall {
+  /** Which client surface was called. */
+  readonly kind: "request" | "requestDecoded" | "paginate" | "graphql";
+  /** The route literal, or the document name for `graphql`. */
+  readonly route: string;
+  /** The params (or GraphQL variables) the call was made with. */
+  readonly params: Record<string, unknown>;
+  /** The page size asked for; paginated reads only. */
+  readonly perPage?: number;
+}
 /**
  * A recorded response table for {@link GitHubClient.layerFixture}.
  *
  * @public
  */
 interface GitHubFixtures {
-  /** Keyed by route; the value is the `data` payload a request answers with. */
+  /**
+   * Keyed by route; the value is the `data` payload a request answers with.
+   *
+   * @remarks
+   * A recorded **`GitHubError` is the response**: the call fails with it. That
+   * is how a suite stubs a 404 (or a rate-limit, or a 422) deliberately,
+   * rather than relying on a route's absence to produce one — absence is a
+   * wiring mistake and {@link GitHubFixtures.unstubbed} treats it as such.
+   */
   readonly request?: Readonly<Record<string, unknown>> | undefined;
-  /** Keyed by route; the value is the whole collection, paged on demand. */
-  readonly paginate?: Readonly<Record<string, ReadonlyArray<unknown>>> | undefined;
+  /**
+   * Keyed by route; the value is the whole collection, paged on demand — or a
+   * `GitHubError` the paginated read fails with.
+   */
+  readonly paginate?: Readonly<Record<string, ReadonlyArray<unknown> | GitHubError>> | undefined;
   /** Keyed by document name; the value is the raw payload to decode. */
   readonly graphql?: Readonly<Record<string, unknown>> | undefined;
+  /**
+   * What a route with **no fixture entry** does. Defaults to `"die"`.
+   *
+   * @remarks
+   * A missing fixture is a **test wiring** mistake, not a condition the code
+   * under test should handle, so the default kills the fiber rather than
+   * entering the error channel — the same treatment an absent `graphql`
+   * fixture has always had.
+   *
+   * The default used to be `"fail"`, and the reason it changed is worth
+   * knowing before you set it back: **a typed failure is only loud in code
+   * that does not catch.** A consumer whose methods each catch `GitHubError`
+   * and report it — a per-resource sync, say — turns a missing stub into a
+   * *different execution path* rather than a failure, and the assertions then
+   * fail for a new reason with nothing in any message naming a fixture. That
+   * cost `@spencerbeggs/reposets` 28 tests reading as ordinary logic bugs.
+   *
+   * - `"die"` — defect naming the route. Loud in every consumer.
+   * - `"fail"` — the old behaviour: `GitHubError.notFound`. Rarely what you
+   *   want now that a recorded `GitHubError` value stubs a failure explicitly:
+   *   `{ "GET /repos/{owner}/{repo}": GitHubError.notFound("read", "repo") }`
+   *   says which route fails and why, where absence says only "unwired".
+   * - `"empty"` — serve `{}` for a request and no items for a paginated read.
+   *   For a suite whose subject is decisions rather than endpoints.
+   *
+   * `graphql` ignores this and always dies: its payload is decoded against the
+   * document's schema, so there is no empty value that would satisfy it.
+   */
+  readonly unstubbed?: "die" | "fail" | "empty" | undefined;
   /** What `rateLimit` answers. */
   readonly rateLimit?: RateLimitSnapshot | undefined;
   /**
-   * Every route a paginated read requested, in order, with the page size asked
-   * for. Populated by the fixture as the test runs.
-   */
-  readonly requested?: Array<{
-    readonly route: string;
-    readonly perPage: number;
-  }> | undefined;
+   * Every call the fixture served, in order. Populated as the test runs.
+   *
+   * @remarks
+   * `kind` says which surface was used. A paginated read carries the
+   * `perPage` it asked for; `request` and `requestDecoded` carry the
+   * **params** they were called with, which is what lets a suite assert that a
+   * method sent the right `owner`/`repo`/body rather than only the right
+   * route. `graphql` records the document name as `route`.
+   *
+   * Recording params was added for the resource modules ported in from
+   * `@spencerbeggs/reposets`, whose ~80-line hand-rolled harness existed
+   * because every one of their methods goes through `request` and a fixture
+   * could assert nothing about them.
+   */
+  readonly requested?: Array<RecordedCall> | undefined;
 }
 declare const GitHubClient_base: Context.ServiceClass<GitHubClient, "@effected/github/GitHubClient", GitHubClientShape>;
 /**
@@ -1062,6 +1126,149 @@ declare class CheckRun extends CheckRun_base {
   static readonly layerTest: (overrides?: Partial<CheckRunShape>) => Layer.Layer<CheckRun>;
 }
 //#endregion
+//#region src/CodeScanning.d.ts
+/**
+ * A CodeQL default-setup configuration.
+ *
+ * @remarks
+ * Every field is optional and an **omitted field means "leave it alone"**, which
+ * is why this is a partial rather than a full configuration: sending
+ * `undefined` for a key the caller never mentioned would clear a setting they
+ * did not ask to change.
+ *
+ * @public
+ */
+interface CodeScanningSetup {
+  /** Whether default setup is `configured` or `not-configured`. */
+  readonly state?: "configured" | "not-configured" | undefined;
+  /** The CodeQL languages to analyse. */
+  readonly languages?: ReadonlyArray<string> | undefined;
+  /** `default` or `extended`. */
+  readonly query_suite?: string | undefined;
+  /** `remote` or `remote_and_local`. */
+  readonly threat_model?: string | undefined;
+  /** `standard` or `labeled`. */
+  readonly runner_type?: string | undefined;
+  /** The runner label, when `runner_type` is `labeled`. */
+  readonly runner_label?: string | undefined;
+}
+/**
+ * CodeQL default setup, and the language detection that gates it.
+ *
+ * @public
+ */
+interface CodeScanningShape {
+  /**
+   * Apply a default-setup configuration.
+   *
+   * @remarks
+   * The endpoint answers **202 Accepted** and configures asynchronously.
+   * Nothing here polls: a successful call means GitHub accepted the request,
+   * not that scanning is running.
+   *
+   * **Turning it back off does not undo everything it did.** Setting `state`
+   * to `not-configured` stops default setup, but the synthetic CodeQL workflow
+   * GitHub created when it was enabled **survives** — it remains listed among
+   * the repository's workflows afterwards. A caller that treats "default setup
+   * is off" as "no CodeQL workflow exists" will be wrong, and one that counts
+   * workflows to decide whether a repository has any CI will count that one.
+   * Reported by `@spencerbeggs/reposets` (dogfood round 8, 2026-08-14) from a
+   * real organization, not inferred from the API description.
+   */
+  readonly configure: (setup: CodeScanningSetup) => Effect.Effect<void, GitHubError, Repo>;
+  /**
+   * The languages GitHub detects in the repository.
+   *
+   * @remarks
+   * The response maps language name to bytes; only the names are returned, in
+   * GitHub's own order (most bytes first). Use it to filter a configured
+   * language list down to what the repository actually contains — GitHub
+   * rejects a default-setup call naming a language it does not detect.
+   */
+  readonly languages: () => Effect.Effect<ReadonlyArray<string>, GitHubError, Repo>;
+}
+declare const CodeScanning_base: Context.ServiceClass<CodeScanning, "@effected/github/CodeScanning", CodeScanningShape>;
+/**
+ * CodeQL default setup.
+ *
+ * @public
+ */
+declare class CodeScanning extends CodeScanning_base {
+  /**
+   * @remarks
+   * The callback is written `(client) => make(client)` rather than passed as
+   * `make` directly, and that is load-bearing: a static initializer runs while
+   * the module body is still evaluating, so naming a `const` declared further
+   * down throws `Cannot access 'make' before initialization` **at import time**,
+   * with a clean typecheck.
+   */
+  static readonly layer: Layer.Layer<CodeScanning, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<CodeScanningShape>) => CodeScanningShape;
+  /** {@link CodeScanning.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<CodeScanningShape>) => Layer.Layer<CodeScanning>;
+}
+//#endregion
+//#region src/DeploymentEnvironment.d.ts
+/**
+ * A deployment environment, as listing returns it.
+ *
+ * @public
+ */
+interface DeploymentEnvironmentInfo {
+  readonly name: string;
+}
+/**
+ * Deployment environments.
+ *
+ * @public
+ */
+interface DeploymentEnvironmentShape {
+  /**
+   * Create or update a deployment environment.
+   *
+   * @remarks
+   * The route is **idempotent** — a `PUT` on an existing environment updates it
+   * — so there is no list-then-branch here, unlike variables.
+   *
+   * `config` stays an open record because the protection-rule body is a moving
+   * target: wait timers, reviewers, deployment-branch policies and whatever
+   * GitHub adds next.
+   */
+  readonly upsert: (name: string, config?: Record<string, unknown>) => Effect.Effect<void, GitHubError, Repo>;
+  /** The repository's deployment environments. */
+  readonly list: () => Effect.Effect<ReadonlyArray<DeploymentEnvironmentInfo>, GitHubError, Repo>;
+  /**
+   * Remove one deployment environment.
+   *
+   * @remarks
+   * **This deletes the environment's secrets and variables with it.** Anything
+   * sequencing a cleanup pass depends on that: removing an environment after
+   * its secrets is redundant, and removing it before them makes those deletions
+   * fail against a resource that no longer exists.
+   */
+  readonly delete: (name: string) => Effect.Effect<void, GitHubError, Repo>;
+}
+declare const DeploymentEnvironment_base: Context.ServiceClass<DeploymentEnvironment, "@effected/github/DeploymentEnvironment", DeploymentEnvironmentShape>;
+/**
+ * Deployment environments.
+ *
+ * @public
+ */
+declare class DeploymentEnvironment extends DeploymentEnvironment_base {
+  /**
+   * @remarks
+   * `(client) => make(client)` rather than `make`: a static initializer runs
+   * while the module body is still evaluating, so naming a `const` declared
+   * further down throws at import time with a clean typecheck.
+   */
+  static readonly layer: Layer.Layer<DeploymentEnvironment, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<DeploymentEnvironmentShape>) => DeploymentEnvironmentShape;
+  /** {@link DeploymentEnvironment.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<DeploymentEnvironmentShape>) => Layer.Layer<DeploymentEnvironment>;
+}
+//#endregion
 //#region src/GitBranch.d.ts
 /**
  * What {@link GitBranchShape.upsert} did.
@@ -1938,6 +2145,79 @@ type RepositorySettings = Data<"GET /repos/{owner}/{repo}">;
  * @public
  */
 type RepositoryPatch = Omit<Params<"PATCH /repos/{owner}/{repo}">, "owner" | "repo">;
+/**
+ * Whether an account is a user or an organization.
+ *
+ * @public
+ */
+type OwnerType = "User" | "Organization";
+/**
+ * Fields in the user-facing `security_and_analysis` block that GitHub accepts
+ * as `{ status: "enabled" | "disabled" }`.
+ *
+ * @remarks
+ * A caller supplies the bare string; it is wrapped before sending.
+ *
+ * @public
+ */
+declare const SECURITY_ANALYSIS_STATUS_FIELDS: ReadonlySet<string>;
+/**
+ * Settings reachable **only** through the GraphQL `updateRepository` mutation,
+ * mapped from snake_case keys to camelCase GraphQL input fields.
+ *
+ * @remarks
+ * GitHub never exposed these two on the REST repository endpoint. Setting
+ * either forces a second round trip to learn the repository's node id.
+ *
+ * @public
+ */
+declare const GRAPHQL_ONLY_SETTINGS: Readonly<Record<string, string>>;
+/**
+ * Translate a user-facing `security_and_analysis` block into the shape
+ * `PATCH /repos/{owner}/{repo}` expects.
+ *
+ * @remarks
+ * **Both shapes are accepted.** A bare `"enabled"` / `"disabled"` is wrapped;
+ * an already-wrapped `{ status }` — which is what `RepositoryPatch` actually
+ * types, since it is GitHub's own parameter type — passes through untouched.
+ * Accepting only the bare string would silently drop the block for a caller
+ * following the types.
+ *
+ * Reviewer entries must already carry a numeric `reviewer_id` and
+ * `reviewer_type`; resolving those from team slugs is the caller's job — see
+ * `Ruleset.teamId`.
+ *
+ * An **empty** `delegated_bypass_reviewers` array is treated as "no change"
+ * rather than "no reviewers". GitHub rejects `{ reviewers: [] }` outright when
+ * delegated bypass is enabled, so forwarding it would turn an omission into a
+ * failure.
+ *
+ * @public
+ */
+declare const transformSecurityAndAnalysis: (value: unknown) => Record<string, unknown> | undefined;
+/**
+ * What {@link GitHubRepositoryShape.applySettings} actually sent.
+ *
+ * @remarks
+ * **These are the fields that went out, not the fields you asked for**, and the
+ * difference is the point. `applySettings` drops what GitHub would reject —
+ * merge keys whose strategy is being disabled, a `security_and_analysis` block
+ * that normalises to nothing — so a caller reporting `Object.keys(input)` is
+ * describing its own intent while the package decides the content. The two
+ * agree right up until a field is dropped, which is exactly the case anyone
+ * reading a dry run is trying to check.
+ *
+ * Both lists use the **caller's** key names, not the wire names, because the
+ * audience for them is a person reading a plan against the config they wrote.
+ *
+ * @public
+ */
+interface AppliedSettings {
+  /** Keys sent on the REST patch, after preparation dropped anything GitHub would refuse. */
+  readonly rest: ReadonlyArray<string>;
+  /** Keys sent through the GraphQL mutation, named as the caller supplied them. */
+  readonly graphql: ReadonlyArray<string>;
+}
 /**
  * The repository itself.
  *
@@ -1964,6 +2244,41 @@ interface GitHubRepositoryShape {
    * mutations, which is why a second consumer cast `repos.get` for it alone.
    */
   readonly nodeId: Effect.Effect<string, GitHubError, Repo>;
+  /**
+   * Whether the repository's owner is a user or an organization.
+   *
+   * @remarks
+   * Gates the settings that only exist on organization-owned repositories:
+   * sending one to a personal repository is rejected, so a caller applying a
+   * shared settings template filters by this first.
+   *
+   * The route is account-scoped (`GET /users/{username}`) but the question is a
+   * repository question — *may I send org-only fields to this repository?* —
+   * so it sources the login from `Repo.owner` rather than taking an argument.
+   * Shaping the API around the route instead of the question would hand every
+   * caller a login to thread for no reason.
+   */
+  readonly ownerType: Effect.Effect<OwnerType, GitHubError, Repo>;
+  /**
+   * Apply a settings map that may span REST and GraphQL.
+   *
+   * @remarks
+   * `updateSettings` is the thin, faithfully-typed PATCH and returns what
+   * GitHub then reports. This is the **applicator**: it takes an open map,
+   * routes each key to whichever API can actually set it, and returns nothing.
+   *
+   * Two settings — `has_sponsorships` and `has_pull_requests` — have never
+   * existed on the REST endpoint and are only reachable through GraphQL's
+   * `updateRepository`, which addresses a repository by **node id**. So a map
+   * touching either costs an extra read; a map touching neither does not, which
+   * is the common case.
+   *
+   * The map is open by design. GitHub's settings surface is large and moving,
+   * and a closed type here would date the package — but it also means a typo is
+   * forwarded rather than rejected, so a caller that owns a schema should
+   * validate before calling.
+   */
+  readonly applySettings: (settings: Record<string, unknown>) => Effect.Effect<AppliedSettings, GitHubError | GitHubGraphQLError, Repo>;
 }
 declare const GitHubRepository_base: Context.ServiceClass<GitHubRepository, "@effected/github/GitHubRepository", GitHubRepositoryShape>;
 /**
@@ -2345,6 +2660,335 @@ declare class PullRequestComment extends PullRequestComment_base {
   static readonly layerTest: (overrides?: Partial<PullRequestCommentShape>) => Layer.Layer<PullRequestComment>;
 }
 //#endregion
+//#region src/RepositorySecret.d.ts
+/**
+ * Which secret store an operation acts on.
+ *
+ * @remarks
+ * Three separate stores on the same repository, each with **its own public
+ * key** — which is why a key fetch cannot be cached across scopes.
+ *
+ * @public
+ */
+type SecretScope = "actions" | "dependabot" | "codespaces";
+/**
+ * A secret, as listing returns it.
+ *
+ * @remarks
+ * The name only. GitHub never returns a secret's value from any endpoint —
+ * that is the point of a secret store — so there is nothing else to carry, and
+ * a consumer comparing desired against live can detect a **deleted** secret but
+ * never an **edited** one.
+ *
+ * @public
+ */
+interface SecretInfo {
+  readonly name: string;
+}
+/**
+ * Repository and environment secrets.
+ *
+ * @public
+ */
+interface RepositorySecretShape {
+  /** Encrypt and write one repository secret in the given store. */
+  readonly set: (name: string, value: Redacted.Redacted<string>, scope?: SecretScope) => Effect.Effect<void, GitHubError, Repo>;
+  /** The names of the repository's secrets in the given store. */
+  readonly list: (scope?: SecretScope) => Effect.Effect<ReadonlyArray<SecretInfo>, GitHubError, Repo>;
+  /** Remove one repository secret from the given store. */
+  readonly delete: (name: string, scope?: SecretScope) => Effect.Effect<void, GitHubError, Repo>;
+  /** Encrypt and write one environment secret. */
+  readonly setForEnvironment: (environment: string, name: string, value: Redacted.Redacted<string>) => Effect.Effect<void, GitHubError, Repo>;
+  /** The names of one environment's secrets. */
+  readonly listForEnvironment: (environment: string) => Effect.Effect<ReadonlyArray<SecretInfo>, GitHubError, Repo>;
+  /** Remove one environment secret. */
+  readonly deleteForEnvironment: (environment: string, name: string) => Effect.Effect<void, GitHubError, Repo>;
+}
+declare const RepositorySecret_base: Context.ServiceClass<RepositorySecret, "@effected/github/RepositorySecret", RepositorySecretShape>;
+/**
+ * Secrets, encrypted client-side before they leave the process.
+ *
+ * @remarks
+ * Every write is a **two-step**: fetch the store's public key, then `PUT` a
+ * libsodium sealed box. The plaintext never crosses the wire, and the key fetch
+ * cannot be cached across stores because each has its own key.
+ *
+ * ## The value is `Redacted`
+ *
+ * Not decoration. A plaintext secret in a `string` is one interpolation, one
+ * `JSON.stringify` of a params object, or one logged error away from a
+ * transcript — and the log line that leaks it usually looks like a diagnostic
+ * someone added to debug an unrelated failure. `Redacted` closes those paths at
+ * the type; this module performs the single `Redacted.value` unwrap, at the
+ * moment of encryption, and the sealed box is what continues.
+ *
+ * @public
+ */
+declare class RepositorySecret extends RepositorySecret_base {
+  /**
+   * @remarks
+   * `(client) => make(client)` rather than `make`: a static initializer runs
+   * while the module body is still evaluating, so naming a `const` declared
+   * further down throws at import time with a clean typecheck.
+   */
+  static readonly layer: Layer.Layer<RepositorySecret, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<RepositorySecretShape>) => RepositorySecretShape;
+  /** {@link RepositorySecret.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<RepositorySecretShape>) => Layer.Layer<RepositorySecret>;
+}
+//#endregion
+//#region src/RepositorySecurity.d.ts
+/**
+ * The three repository security features that have their own endpoints.
+ *
+ * @public
+ */
+interface RepositorySecurityShape {
+  /** Whether Dependabot vulnerability alerts are on. */
+  readonly vulnerabilityAlerts: () => Effect.Effect<boolean, GitHubError, Repo>;
+  /** Turn Dependabot vulnerability alerts on or off. */
+  readonly setVulnerabilityAlerts: (enabled: boolean) => Effect.Effect<void, GitHubError, Repo>;
+  /** Whether Dependabot security pull requests are on. */
+  readonly automatedSecurityFixes: () => Effect.Effect<boolean, GitHubError, Repo>;
+  /** Turn Dependabot security pull requests on or off. */
+  readonly setAutomatedSecurityFixes: (enabled: boolean) => Effect.Effect<void, GitHubError, Repo>;
+  /** Whether the private vulnerability reporting inbox is on. */
+  readonly privateVulnerabilityReporting: () => Effect.Effect<boolean, GitHubError, Repo>;
+  /** Turn the private vulnerability reporting inbox on or off. */
+  readonly setPrivateVulnerabilityReporting: (enabled: boolean) => Effect.Effect<void, GitHubError, Repo>;
+}
+declare const RepositorySecurity_base: Context.ServiceClass<RepositorySecurity, "@effected/github/RepositorySecurity", RepositorySecurityShape>;
+/**
+ * Repository security features with dedicated endpoints.
+ *
+ * @remarks
+ * These are **not** `security_and_analysis` fields and cannot ride along on the
+ * settings `PATCH`. Each is its own pair of endpoints where **the HTTP verb is
+ * the value**, which is why every setter branches on `enabled` rather than
+ * sending a body.
+ *
+ * ## Reading them is inconsistent, and the inconsistency is GitHub's
+ *
+ * Preserved faithfully rather than smoothed over, because smoothing it would
+ * mean inventing a behaviour for one of the three:
+ *
+ * | Feature | Enabled | Disabled |
+ * | :--- | :--- | :--- |
+ * | `vulnerability-alerts` | `204` | **`404`** |
+ * | `automated-security-fixes` | `200 { enabled: true }` | `200 { enabled: false }` |
+ * | `private-vulnerability-reporting` | `200 { enabled: true }` | `200 { enabled: false }` |
+ *
+ * So `vulnerabilityAlerts` maps `notFound` to `false` — and **only** `notFound`;
+ * every other failure still fails. A 404 from the other two is a real failure
+ * and stays one, which is why the mapping is not applied uniformly.
+ *
+ * @public
+ */
+declare class RepositorySecurity extends RepositorySecurity_base {
+  /**
+   * @remarks
+   * `(client) => make(client)` rather than `make`: a static initializer runs
+   * while the module body is still evaluating, so naming a `const` declared
+   * further down throws at import time with a clean typecheck.
+   */
+  static readonly layer: Layer.Layer<RepositorySecurity, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<RepositorySecurityShape>) => RepositorySecurityShape;
+  /** {@link RepositorySecurity.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<RepositorySecurityShape>) => Layer.Layer<RepositorySecurity>;
+}
+//#endregion
+//#region src/RepositoryVariable.d.ts
+/**
+ * A variable, as listing returns it.
+ *
+ * @remarks
+ * Unlike a secret this carries its **value**: variables are readable, so a
+ * consumer comparing desired against live can detect an *edited* variable and
+ * not merely a deleted one. Discarding the value in a projection here would
+ * throw that away silently.
+ *
+ * @public
+ */
+interface VariableInfo {
+  readonly name: string;
+  readonly value: string;
+}
+/**
+ * Repository and environment variables.
+ *
+ * @public
+ */
+interface RepositoryVariableShape {
+  /**
+   * Create or update one repository variable.
+   *
+   * @remarks
+   * GitHub has **no upsert** for variables: creating uses `POST` on the
+   * collection and updating uses `PATCH` on the item, and each fails if used
+   * for the other case. So this reads first and branches — one extra request
+   * per write, and the reason it is not optional.
+   *
+   * The read is **by name**, not a listing: GitHub answers 404 for an absent
+   * variable, so the check is constant cost rather than growing with a
+   * repository that has nothing to do with the variable being written. Only
+   * `notFound` is absorbed — a 403 from a mis-scoped token still fails, where
+   * treating any error as absence would turn a permissions problem into a
+   * spurious create.
+   *
+   * **The 404-for-absent behaviour is documented, not probed.** Neither this
+   * suite nor the first consumer's has issued this read against real GitHub —
+   * both run against doubles.
+   *
+   * Only `notFound` selects the create branch: a successful read selects the
+   * update branch, and any other failure propagates rather than being guessed
+   * at. So if GitHub answers something *other* than 404 for an absent
+   * variable, the write does not silently take the wrong branch — it either
+   * `PATCH`es a variable that is not there, or fails with the error GitHub
+   * actually sent. Read either as evidence about this assumption rather than
+   * about the caller.
+   */
+  readonly set: (name: string, value: string) => Effect.Effect<void, GitHubError, Repo>;
+  /** The repository's variables, with their values. */
+  readonly list: () => Effect.Effect<ReadonlyArray<VariableInfo>, GitHubError, Repo>;
+  /** Remove one repository variable. */
+  readonly delete: (name: string) => Effect.Effect<void, GitHubError, Repo>;
+  /** Create or update one environment variable, branching the same way. */
+  readonly setForEnvironment: (environment: string, name: string, value: string) => Effect.Effect<void, GitHubError, Repo>;
+  /** One environment's variables, with their values. */
+  readonly listForEnvironment: (environment: string) => Effect.Effect<ReadonlyArray<VariableInfo>, GitHubError, Repo>;
+  /** Remove one environment variable. */
+  readonly deleteForEnvironment: (environment: string, name: string) => Effect.Effect<void, GitHubError, Repo>;
+}
+declare const RepositoryVariable_base: Context.ServiceClass<RepositoryVariable, "@effected/github/RepositoryVariable", RepositoryVariableShape>;
+/**
+ * Repository and environment variables.
+ *
+ * @remarks
+ * No encryption and no public key, unlike secrets — but also **no upsert**,
+ * which is the asymmetry worth knowing: every write costs a read first, because
+ * the create and update routes are different endpoints with different verbs and
+ * neither tolerates the other's case.
+ *
+ * @public
+ */
+declare class RepositoryVariable extends RepositoryVariable_base {
+  /**
+   * @remarks
+   * `(client) => make(client)` rather than `make`: a static initializer runs
+   * while the module body is still evaluating, so naming a `const` declared
+   * further down throws at import time with a clean typecheck.
+   */
+  static readonly layer: Layer.Layer<RepositoryVariable, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<RepositoryVariableShape>) => RepositoryVariableShape;
+  /** {@link RepositoryVariable.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<RepositoryVariableShape>) => Layer.Layer<RepositoryVariable>;
+}
+//#endregion
+//#region src/Ruleset.d.ts
+/**
+ * A ruleset, as listing returns it.
+ *
+ * @remarks
+ * `source_type` is the field that matters and the one easiest to drop from a
+ * projection: a repository's ruleset listing includes rulesets **inherited from
+ * the organization**, and they are indistinguishable from the repository's own
+ * without it.
+ *
+ * @public
+ */
+interface RulesetInfo {
+  readonly id: number;
+  readonly name: string;
+  /** `"Repository"` for the repository's own, `"Organization"` for an inherited one. */
+  readonly source_type?: string | undefined;
+}
+/**
+ * What a ruleset write sends.
+ *
+ * @remarks
+ * `conditions`, `rules` and `bypass_actors` are open records: GitHub's rule
+ * vocabulary is large, versioned and expanding, and pinning it here would date
+ * the package rather than protect the caller.
+ *
+ * @public
+ */
+interface RulesetPayload {
+  readonly name: string;
+  readonly target: string;
+  readonly enforcement: string;
+  readonly conditions?: unknown;
+  readonly rules?: unknown;
+  readonly bypass_actors?: unknown;
+}
+/**
+ * Repository rulesets, and the lookups their bypass actors need.
+ *
+ * @public
+ */
+interface RulesetShape {
+  /**
+   * Create or update a ruleset, matched by name.
+   *
+   * @remarks
+   * A ruleset has **no natural key** on GitHub's side — only a numeric id
+   * assigned at creation — so this matches on `name`. Renaming a ruleset in a
+   * caller's configuration therefore creates a second one rather than renaming
+   * the first; removing the orphan is the caller's cleanup pass.
+   */
+  readonly upsert: (payload: RulesetPayload) => Effect.Effect<void, GitHubError, Repo>;
+  /** Every ruleset the repository sees, its own and the organization's. */
+  readonly list: () => Effect.Effect<ReadonlyArray<RulesetInfo>, GitHubError, Repo>;
+  /** Remove one ruleset by id. */
+  readonly delete: (rulesetId: number) => Effect.Effect<void, GitHubError, Repo>;
+  /**
+   * A team's numeric id, for a bypass actor.
+   *
+   * @remarks
+   * Org-scoped, sourced from `Repo.owner` — the organization that owns the
+   * repository. A team in a *different* organization is not reachable here and
+   * should not be: `Repo` would be lying about the scope.
+   */
+  readonly teamId: (slug: string) => Effect.Effect<number, GitHubError, Repo>;
+  /** An organization role's numeric id, for a bypass actor. */
+  readonly roleId: (name: string) => Effect.Effect<number, GitHubError, Repo>;
+}
+declare const Ruleset_base: Context.ServiceClass<Ruleset, "@effected/github/Ruleset", RulesetShape>;
+/**
+ * Repository rulesets.
+ *
+ * @remarks
+ * ## An inherited ruleset is never written to
+ *
+ * `GET /repos/{owner}/{repo}/rulesets` returns rulesets **inherited from the
+ * organization** alongside the repository's own. Matching by name alone lets a
+ * repository-scoped call issue a `PUT` against the organization's ruleset id —
+ * rewriting policy for **every repository the organization owns**, from a caller
+ * that never mentioned the organization.
+ *
+ * {@link RulesetShape.upsert} filters on `source_type` before matching, so an
+ * inherited ruleset can never be the target of a write. This arrived as a fix
+ * for a live defect in the consumer this module was ported from, where the
+ * filter was absent.
+ *
+ * @public
+ */
+declare class Ruleset extends Ruleset_base {
+  /**
+   * @remarks
+   * `(client) => make(client)` rather than `make`: a static initializer runs
+   * while the module body is still evaluating, so naming a `const` declared
+   * further down throws at import time with a clean typecheck.
+   */
+  static readonly layer: Layer.Layer<Ruleset, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<RulesetShape>) => RulesetShape;
+  /** {@link Ruleset.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<RulesetShape>) => Layer.Layer<Ruleset>;
+}
+//#endregion
 //#region src/TokenPermissions.d.ts
 /**
  * How much access a permission grants.
@@ -2488,6 +3132,29 @@ declare class WorkflowRunStatus extends WorkflowRunStatus_base {
   /** Has the run finished, whatever the outcome? */
   get isDone(): boolean;
 }
+/**
+ * One workflow defined in the repository.
+ *
+ * @remarks
+ * `state` is GitHub's own value — `active`, `disabled_manually`,
+ * `disabled_inactivity`, and so on. It is reported rather than interpreted:
+ * whether a *disabled* workflow counts for a given GitHub feature is that
+ * feature's rule, not this package's, and encoding a guess here would put an
+ * unverified server-side behaviour in a library that cannot test it. Callers
+ * that care filter on it themselves.
+ *
+ * @public
+ */
+interface WorkflowInfo {
+  /** The workflow's numeric id, usable as `workflow_id` on other routes. */
+  readonly id: number;
+  /** The workflow's display name. */
+  readonly name: string;
+  /** Repository-relative path, e.g. `.github/workflows/ci.yml`. */
+  readonly path: string;
+  /** GitHub's state string; see the remarks above before branching on it. */
+  readonly state: string;
+}
 /**
  * How long to wait for a dispatched run.
  *
@@ -2508,6 +3175,21 @@ interface WorkflowDispatchShape {
   /** Fire a `workflow_dispatch` event. GitHub answers 204 with no run id. */
   readonly dispatch: (workflow: string, ref: string, inputs?: Record<string, string>) => Effect.Effect<void, GitHubError, Repo>;
   readonly runStatus: (runId: number) => Effect.Effect<WorkflowRunStatus, GitHubError, Repo>;
+  /**
+   * Every workflow defined in the repository.
+   *
+   * @remarks
+   * The question this answers is "does this repository have workflows at all",
+   * which nothing else in the package could ask: repository *languages* come
+   * from linguist and can never report `actions`, while GitHub validates that
+   * language against workflow **files**. A consumer offering CodeQL setup
+   * otherwise has to either request `actions` blindly and absorb a 422, or
+   * drop it for every repository including the ones where it is valid.
+   *
+   * An empty array is the honest answer for a repository with no workflows,
+   * not an error.
+   */
+  readonly list: Effect.Effect<ReadonlyArray<WorkflowInfo>, GitHubError, Repo>;
   /**
    * Dispatch, find the run it created, and wait for it to finish.
    *
@@ -2536,5 +3218,5 @@ declare class WorkflowDispatch extends WorkflowDispatch_base {
   static readonly layerTest: (overrides?: Partial<WorkflowDispatchShape>) => Layer.Layer<WorkflowDispatch>;
 }
 //#endregion
-export { Annotation, AnnotationLevel, type AppCredentials, AppIdentity, ArtifactMetadata, type ArtifactMetadataShape, Attestation, AttestationListEntry, AttestationRecord, type AttestationShape, BotIdentity, type BranchOutcome, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, type CheckRunShape, CommentMarker, CommentRecord, CommitComparison, CommitFile, CommitRef, CommitSummary, type ConcludeCheckRun, ExtraPermission, FileChange, FileContent, FileDeletion, FileMode, FileStatus, GitBranch, type GitBranchShape, GitCommit, type GitCommitShape, GitHubApp, GitHubAppError, type GitHubAppOptions, type GitHubAppShape, GitHubClient, type GitHubClientOptions, type GitHubClientShape, GitHubCommit, type GitHubCommitShape, GitHubContent, type GitHubContentShape, GitHubError, GitHubErrorKind, type GitHubFixtures, GitHubGraphQLError, GitHubIssue, type GitHubIssueShape, GitHubRelease, type GitHubReleaseShape, GitHubRepository, type GitHubRepositoryShape, GitTag, type GitTagShape, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InvalidRepoRefError, IssueInfo, type LatestSemverOptions, LinkedIssue, MergeMethod, PageOptions, PermissionGap, PermissionLevel, PermissionResult, type PollOptions, PullRequest, PullRequestComment, type PullRequestCommentShape, PullRequestInfo, type PullRequestShape, RateLimitSnapshot, ReleaseAsset, ReleaseInfo, Repo, RepoRef, type RepositoryPatch, type RepositorySettings, type Data as RestData, type RequestExtras as RestExtras, type Item as RestItem, type PaginatingRoute as RestPaginatingRoute, type Params as RestParams, type Response as RestResponse, type Route as RestRoute, RetryPolicy, type RetryableFailure, SemverTag, StorageRecordInput, TagRef, TokenPermissionError, TokenPermissions, type TokenRequest, type UpsertedPullRequest, type VersionFromTag, WorkflowDispatch, type WorkflowDispatchShape, WorkflowRunStatus, versionFromTag };
+export { Annotation, AnnotationLevel, type AppCredentials, AppIdentity, type AppliedSettings, ArtifactMetadata, type ArtifactMetadataShape, Attestation, AttestationListEntry, AttestationRecord, type AttestationShape, BotIdentity, type BranchOutcome, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef, type CheckRunShape, CodeScanning, type CodeScanningSetup, type CodeScanningShape, CommentMarker, CommentRecord, CommitComparison, CommitFile, CommitRef, CommitSummary, type ConcludeCheckRun, DeploymentEnvironment, type DeploymentEnvironmentInfo, type DeploymentEnvironmentShape, ExtraPermission, FileChange, FileContent, FileDeletion, FileMode, FileStatus, GRAPHQL_ONLY_SETTINGS, GitBranch, type GitBranchShape, GitCommit, type GitCommitShape, GitHubApp, GitHubAppError, type GitHubAppOptions, type GitHubAppShape, GitHubClient, type GitHubClientOptions, type GitHubClientShape, GitHubCommit, type GitHubCommitShape, GitHubContent, type GitHubContentShape, GitHubError, GitHubErrorKind, type GitHubFixtures, GitHubGraphQLError, GitHubIssue, type GitHubIssueShape, GitHubRelease, type GitHubReleaseShape, GitHubRepository, type GitHubRepositoryShape, GitTag, type GitTagShape, GraphQLDocument, GraphQLErrorEntry, Installation, InstallationToken, InvalidRepoRefError, IssueInfo, type LatestSemverOptions, LinkedIssue, MergeMethod, type OwnerType, PageOptions, PermissionGap, PermissionLevel, PermissionResult, type PollOptions, PullRequest, PullRequestComment, type PullRequestCommentShape, PullRequestInfo, type PullRequestShape, RateLimitSnapshot, type RecordedCall, ReleaseAsset, ReleaseInfo, Repo, RepoRef, type RepositoryPatch, RepositorySecret, type RepositorySecretShape, RepositorySecurity, type RepositorySecurityShape, type RepositorySettings, RepositoryVariable, type RepositoryVariableShape, type Data as RestData, type RequestExtras as RestExtras, type Item as RestItem, type PaginatingRoute as RestPaginatingRoute, type Params as RestParams, type Response as RestResponse, type Route as RestRoute, RetryPolicy, type RetryableFailure, Ruleset, type RulesetInfo, type RulesetPayload, type RulesetShape, SECURITY_ANALYSIS_STATUS_FIELDS, type SecretInfo, type SecretScope, SemverTag, StorageRecordInput, TagRef, TokenPermissionError, TokenPermissions, type TokenRequest, type UpsertedPullRequest, type VariableInfo, type VersionFromTag, WorkflowDispatch, type WorkflowDispatchShape, type WorkflowInfo, WorkflowRunStatus, transformSecurityAndAnalysis, versionFromTag };
 //# sourceMappingURL=index.d.ts.map