@effected/github 0.3.0 → 0.4.1

package/CodeScanning.js

@@ -0,0 +1,80 @@
+import { GitHubClient } from "./GitHubClient.js";
+import { Repo } from "./Repo.js";
+import { Context, Effect, Layer } from "effect";
+
+//#region src/CodeScanning.ts
+/**
+* CodeQL default setup.
+*
+* @public
+*/
+var CodeScanning = class CodeScanning extends Context.Service()("@effected/github/CodeScanning") {
+	/**
+	* @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 layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
+	/** An in-memory double; unstubbed members die naming themselves. */
+	static makeTest = (overrides = {}) => ({
+		configure: overrides.configure ?? (() => unstubbed("configure")),
+		languages: overrides.languages ?? (() => unstubbed("languages"))
+	});
+	/** {@link CodeScanning.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(CodeScanning, CodeScanning.makeTest(overrides));
+};
+const unstubbed = (member) => {
+	throw new Error(`CodeScanning.makeTest: ${member}() was called but not stubbed — pass an override.`);
+};
+const SETUP_KEYS = [
+	"state",
+	"languages",
+	"query_suite",
+	"threat_model",
+	"runner_type",
+	"runner_label"
+];
+/**
+* Every method resolves {@link Repo} per call rather than once at layer
+* construction, for the reason `GitBranch` states: capturing the coordinate
+* would make a scoped `Repo.provide` silently do nothing.
+*/
+const make = (client) => {
+	return {
+		configure: Effect.fn("CodeScanning.configure")(function* (setup) {
+			const { owner, repo } = yield* Repo;
+			yield* Effect.annotateCurrentSpan({
+				owner,
+				repo
+			});
+			const body = {};
+			for (const key of SETUP_KEYS) {
+				const value = setup[key];
+				if (value !== void 0) body[key] = key === "languages" ? [...value] : value;
+			}
+			yield* client.request("PATCH /repos/{owner}/{repo}/code-scanning/default-setup", {
+				owner,
+				repo,
+				...body
+			});
+		}),
+		languages: Effect.fn("CodeScanning.languages")(function* () {
+			const { owner, repo } = yield* Repo;
+			yield* Effect.annotateCurrentSpan({
+				owner,
+				repo
+			});
+			const detected = yield* client.request("GET /repos/{owner}/{repo}/languages", {
+				owner,
+				repo
+			});
+			return Object.keys(detected);
+		})
+	};
+};
+
+//#endregion
+export { CodeScanning };

package/DeploymentEnvironment.js

@@ -0,0 +1,75 @@
+import { GitHubClient } from "./GitHubClient.js";
+import { Repo } from "./Repo.js";
+import { Context, Effect, Layer } from "effect";
+
+//#region src/DeploymentEnvironment.ts
+/**
+* Deployment environments.
+*
+* @public
+*/
+var DeploymentEnvironment = class DeploymentEnvironment extends Context.Service()("@effected/github/DeploymentEnvironment") {
+	/**
+	* @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 layer = Layer.effect(this, Effect.map(GitHubClient, (client) => make(client)));
+	/** An in-memory double; unstubbed members die naming themselves. */
+	static makeTest = (overrides = {}) => ({
+		upsert: overrides.upsert ?? (() => unstubbed("upsert")),
+		list: overrides.list ?? (() => unstubbed("list")),
+		delete: overrides.delete ?? (() => unstubbed("delete"))
+	});
+	/** {@link DeploymentEnvironment.makeTest} behind a `Layer`. */
+	static layerTest = (overrides = {}) => Layer.succeed(DeploymentEnvironment, DeploymentEnvironment.makeTest(overrides));
+};
+const unstubbed = (member) => {
+	throw new Error(`DeploymentEnvironment.makeTest: ${member}() was called but not stubbed — pass an override.`);
+};
+const make = (client) => {
+	return {
+		upsert: Effect.fn("DeploymentEnvironment.upsert")(function* (name, config = {}) {
+			const { owner, repo } = yield* Repo;
+			yield* Effect.annotateCurrentSpan({
+				owner,
+				repo,
+				environment: name
+			});
+			yield* client.request("PUT /repos/{owner}/{repo}/environments/{environment_name}", {
+				...config,
+				owner,
+				repo,
+				environment_name: name
+			});
+		}),
+		list: Effect.fn("DeploymentEnvironment.list")(function* () {
+			const { owner, repo } = yield* Repo;
+			yield* Effect.annotateCurrentSpan({
+				owner,
+				repo
+			});
+			return (yield* client.paginate("GET /repos/{owner}/{repo}/environments", {
+				owner,
+				repo
+			})).map((environment) => ({ name: environment.name }));
+		}),
+		delete: Effect.fn("DeploymentEnvironment.delete")(function* (name) {
+			const { owner, repo } = yield* Repo;
+			yield* Effect.annotateCurrentSpan({
+				owner,
+				repo,
+				environment: name
+			});
+			yield* client.request("DELETE /repos/{owner}/{repo}/environments/{environment_name}", {
+				owner,
+				repo,
+				environment_name: name
+			});
+		})
+	};
+};
+
+//#endregion
+export { DeploymentEnvironment };

package/GitHubClient.js

@@ -160,27 +160,60 @@ const makeClientShape = (options) => Effect.gen(function* () {
 const makeFixture = (fixtures) => {
 	const requested = fixtures.requested;
 	const paginateStream = (route, _params, options) => {
-		const items = fixtures.paginate?.[route];
-		if (items === void 0) return Stream.fail(GitHubError.notFound("GitHubClient.paginate", `fixture for ${route}`));
 		const perPage = perPageOf(options);
 		requested?.push({
+			kind: "paginate",
 			route,
+			params: _params,
 			perPage
 		});
+		const recorded = fixtures.paginate?.[route];
+		if (recorded instanceof GitHubError) return Stream.fail(recorded);
+		const items = recorded;
+		if (items === void 0) switch (fixtures.unstubbed ?? "die") {
+			case "fail": return Stream.fail(GitHubError.notFound("GitHubClient.paginate", `fixture for ${route}`));
+			case "empty": return Stream.empty;
+			default: return Stream.die(/* @__PURE__ */ new Error(`GitHubClient.paginate: no fixture for ${route}`));
+		}
 		return paginate(() => fromArray(items, perPage), options?.maxPages);
 	};
+	const missing = (method, route) => {
+		switch (fixtures.unstubbed ?? "die") {
+			case "fail": return Effect.fail(GitHubError.notFound(method, `fixture for ${route}`));
+			case "empty": return Effect.succeed({});
+			default: return Effect.die(/* @__PURE__ */ new Error(`${method}: no fixture for ${route}`));
+		}
+	};
 	return {
-		request: (route, _params) => {
+		request: (route, params) => {
+			requested?.push({
+				kind: "request",
+				route,
+				params
+			});
 			const data = fixtures.request?.[route];
-			return data === void 0 ? Effect.fail(GitHubError.notFound("GitHubClient.request", `fixture for ${route}`)) : Effect.succeed(data);
+			if (data === void 0) return missing("GitHubClient.request", route);
+			return data instanceof GitHubError ? Effect.fail(data) : Effect.succeed(data);
 		},
-		requestDecoded: (route, _params, schema) => {
+		requestDecoded: (route, params, schema) => {
+			requested?.push({
+				kind: "requestDecoded",
+				route,
+				params
+			});
 			const data = fixtures.request?.[route];
-			return data === void 0 ? Effect.fail(GitHubError.notFound("GitHubClient.requestDecoded", `fixture for ${route}`)) : Schema.decodeUnknownEffect(schema)(data).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubError.decode(route, "fixture did not match its schema", error))));
+			if (data === void 0) return missing("GitHubClient.requestDecoded", route);
+			if (data instanceof GitHubError) return Effect.fail(data);
+			return Schema.decodeUnknownEffect(schema)(data).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubError.decode(route, "fixture did not match its schema", error))));
 		},
 		paginate: (route, params, options) => Stream.runCollect(paginateStream(route, params, options)),
 		paginateStream,
-		graphql: (document, _variables) => {
+		graphql: (document, variables) => {
+			requested?.push({
+				kind: "graphql",
+				route: document.name,
+				params: variables
+			});
 			const raw = fixtures.graphql?.[document.name];
 			return raw === void 0 ? Effect.die(/* @__PURE__ */ new Error(`GitHubClient.layerFixture: no graphql fixture for ${document.name}`)) : document.decode(raw).pipe(Effect.catchTag("SchemaError", (error) => Effect.fail(GitHubGraphQLError.decode(document.name, "fixture did not match its schema", error))));
 		},

package/GitHubRepository.js

@@ -1,9 +1,130 @@
+import { GraphQLDocument } from "./GraphQL.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
-import { Context, Effect, Layer } from "effect";
+import { Context, Effect, Layer, Schema } from "effect";
 
 //#region src/GitHubRepository.ts
 /**
+* 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
+*/
+const SECURITY_ANALYSIS_STATUS_FIELDS = /* @__PURE__ */ new Set([
+	"advanced_security",
+	"code_security",
+	"secret_scanning",
+	"secret_scanning_push_protection",
+	"secret_scanning_ai_detection",
+	"secret_scanning_non_provider_patterns",
+	"secret_scanning_delegated_alert_dismissal",
+	"secret_scanning_delegated_bypass",
+	"dependabot_security_updates"
+]);
+/**
+* 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
+*/
+const GRAPHQL_ONLY_SETTINGS = {
+	has_sponsorships: "hasSponsorshipsEnabled",
+	has_pull_requests: "hasPullRequestsEnabled"
+};
+/** `{ status: "enabled" | "disabled" }` — the form GitHub accepts and the type declares. */
+const isStatusObject = (raw) => {
+	if (raw === null || typeof raw !== "object") return false;
+	const status = raw.status;
+	return status === "enabled" || status === "disabled";
+};
+/**
+* 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
+*/
+const transformSecurityAndAnalysis = (value) => {
+	if (value === null || typeof value !== "object") return void 0;
+	const input = value;
+	const out = {};
+	for (const [key, raw] of Object.entries(input)) {
+		if (raw === void 0) continue;
+		if (SECURITY_ANALYSIS_STATUS_FIELDS.has(key) && (raw === "enabled" || raw === "disabled")) out[key] = { status: raw };
+		else if (SECURITY_ANALYSIS_STATUS_FIELDS.has(key) && isStatusObject(raw)) out[key] = raw;
+		else if (key === "delegated_bypass_reviewers" && Array.isArray(raw) && raw.length > 0) out.secret_scanning_delegated_bypass_options = { reviewers: raw };
+	}
+	return Object.keys(out).length > 0 ? out : void 0;
+};
+/** The mutation's answer. Only its shape matters — the id is never read. */
+const UpdateRepositoryResponse = Schema.Struct({ updateRepository: Schema.Struct({ repository: Schema.Struct({ id: Schema.String }) }) });
+/**
+* The `updateRepository` mutation, as an owned document.
+*
+* @remarks
+* Named `UpdateRepository`; {@link GitHubClient.layerFixture} keys its GraphQL
+* fixtures by that name.
+*/
+const UpdateRepository = GraphQLDocument.make({
+	name: "UpdateRepository",
+	document: `mutation UpdateRepository($input: UpdateRepositoryInput!) {
+	updateRepository(input: $input) {
+		repository { id }
+	}
+}`,
+	response: UpdateRepositoryResponse
+})();
+/**
+* Keys GitHub rejects when the strategy that owns them is being turned off.
+*
+* @remarks
+* Sending `merge_commit_title` in the same request that sets
+* `allow_merge_commit: false` is a 422, so the dependent keys go out with the
+* strategy that owns them rather than alone.
+*/
+const DEPENDENT_MERGE_KEYS = {
+	allow_merge_commit: ["merge_commit_title", "merge_commit_message"],
+	allow_squash_merge: ["squash_merge_commit_title", "squash_merge_commit_message"]
+};
+/**
+* Everything both write paths owe the API before a patch is sent.
+*
+* @remarks
+* Shared by `updateSettings` and `applySettings` deliberately: a caller should
+* not get a different `security_and_analysis` shape depending on which one they
+* reached for.
+*/
+const preparePatch = (patch) => {
+	const out = { ...patch };
+	const securityAndAnalysis = transformSecurityAndAnalysis(out.security_and_analysis);
+	if (securityAndAnalysis === void 0) delete out.security_and_analysis;
+	else out.security_and_analysis = securityAndAnalysis;
+	for (const [strategy, dependents] of Object.entries(DEPENDENT_MERGE_KEYS)) if (out[strategy] === false) for (const dependent of dependents) delete out[dependent];
+	return out;
+};
+/**
 * Repository settings and coordinates.
 *
 * @public
@@ -15,7 +136,9 @@ var GitHubRepository = class GitHubRepository extends Context.Service()("@effect
 		settings: overrides.settings ?? Effect.sync(() => unstubbed("settings")),
 		updateSettings: overrides.updateSettings ?? (() => unstubbed("updateSettings")),
 		defaultBranch: overrides.defaultBranch ?? Effect.sync(() => unstubbed("defaultBranch")),
-		nodeId: overrides.nodeId ?? Effect.sync(() => unstubbed("nodeId"))
+		nodeId: overrides.nodeId ?? Effect.sync(() => unstubbed("nodeId")),
+		ownerType: overrides.ownerType ?? Effect.sync(() => unstubbed("ownerType")),
+		applySettings: overrides.applySettings ?? (() => unstubbed("applySettings"))
 	});
 	/** {@link GitHubRepository.makeTest} behind a `Layer`. */
 	static layerTest = (overrides = {}) => Layer.succeed(GitHubRepository, GitHubRepository.makeTest(overrides));
@@ -35,6 +158,11 @@ const make = (client) => {
 			repo
 		});
 	})();
+	const ownerType = Effect.fn("GitHubRepository.ownerType")(function* () {
+		const { owner } = yield* Repo;
+		yield* Effect.annotateCurrentSpan({ owner });
+		return (yield* client.request("GET /users/{username}", { username: owner })).type === "Organization" ? "Organization" : "User";
+	})();
 	return {
 		settings,
 		updateSettings: Effect.fn("GitHubRepository.updateSettings")(function* (patch) {
@@ -45,15 +173,56 @@ const make = (client) => {
 				fields: Object.keys(patch).length
 			});
 			return yield* client.request("PATCH /repos/{owner}/{repo}", {
-				...patch,
+				...preparePatch(patch),
 				owner,
 				repo
 			});
 		}),
 		defaultBranch: Effect.map(settings, (repository) => repository.default_branch),
-		nodeId: Effect.map(settings, (repository) => repository.node_id)
+		nodeId: Effect.map(settings, (repository) => repository.node_id),
+		ownerType,
+		applySettings: Effect.fn("GitHubRepository.applySettings")(function* (input) {
+			const { owner, repo } = yield* Repo;
+			yield* Effect.annotateCurrentSpan({
+				owner,
+				repo
+			});
+			const rest = {};
+			const graphql = {};
+			const graphqlKeys = [];
+			for (const [key, value] of Object.entries(input)) {
+				const graphqlField = Object.hasOwn(GRAPHQL_ONLY_SETTINGS, key) ? GRAPHQL_ONLY_SETTINGS[key] : void 0;
+				if (graphqlField !== void 0) {
+					graphql[graphqlField] = value;
+					graphqlKeys.push(key);
+					continue;
+				}
+				rest[key] = value;
+			}
+			const prepared = preparePatch(rest);
+			const restKeys = Object.keys(prepared);
+			if (restKeys.length > 0) yield* client.request("PATCH /repos/{owner}/{repo}", {
+				...prepared,
+				owner,
+				repo
+			});
+			if (Object.keys(graphql).length > 0) {
+				const repository = yield* client.request("GET /repos/{owner}/{repo}", {
+					owner,
+					repo
+				});
+				yield* client.graphql(UpdateRepository, { input: {
+					repositoryId: repository.node_id,
+					...graphql
+				} });
+			}
+			return {
+				rest: restKeys,
+				graphql: graphqlKeys
+			};
+		})
 	};
 };
 
 //#endregion
-export { GitHubRepository };
+export { GRAPHQL_ONLY_SETTINGS, GitHubRepository, SECURITY_ANALYSIS_STATUS_FIELDS, transformSecurityAndAnalysis };

package/README.md

@@ -5,7 +5,7 @@
 [![Node.js %3E%3D24.11.0](https://img.shields.io/badge/Node.js-%3E%3D24.11.0-5fa04e.svg)](https://nodejs.org/)
 [![TypeScript 7.0](https://img.shields.io/badge/TypeScript-7.0-3178c6.svg)](https://www.typescriptlang.org/)
 
-Typed GitHub REST and GraphQL for [Effect](https://effect.website) v4. `client.request("GET /repos/{owner}/{repo}", { owner, repo })` types both the parameters and the returned `data` from the route literal alone — no `operation: string`, no callback, no cast. One `GitHubError` covers every REST failure with a `kind` you branch on instead of grepping a message, one pagination engine backs every paginating route and `client.request`'s `Stream` form, and a set of resource services (`GitBranch`, `GitTag`, `CheckRun`, `PullRequest`, `PullRequestComment`, `GitHubRelease`, `Attestation`) turn multi-call dances — "does this branch already exist?", "conclude this check run no matter how the program exits" — into one call. `GitHubApp` mints and revokes installation tokens for App auth.
+Typed GitHub REST and GraphQL for [Effect](https://effect.website) v4. `client.request("GET /repos/{owner}/{repo}", { owner, repo })` types both the parameters and the returned `data` from the route literal alone — no `operation: string`, no callback, no cast. One `GitHubError` covers every REST failure with a `kind` you branch on instead of grepping a message, one pagination engine backs every paginating route and `client.request`'s `Stream` form, and a set of resource services (`GitBranch`, `GitTag`, `CheckRun`, `PullRequest`, `PullRequestComment`, `GitHubRelease`, `Attestation`) turn multi-call dances — "does this branch already exist?", "conclude this check run no matter how the program exits" — into one call. A second tier writes the configuration half: secrets, variables, rulesets, deployment environments, the security toggles and CodeQL default setup. `GitHubApp` mints and revokes installation tokens for App auth.
 
 > **Pre-release.** This package is part of the `@effected/*` kit, in pre-`1.0.0`
 > development against a single pinned Effect v4 beta. Packages graduate to
@@ -101,6 +101,55 @@ const program = Effect.gen(function* () {
 
 `GitTag.latestSemver` walks tags and picks the newest version-shaped one in a single pass, over `@effected/semver`'s synchronous comparator — no round trip per candidate. `PullRequest.upsert` and `PullRequestComment.upsert` (a marker-tagged sticky comment) follow the same one-call-one-intent shape.
 
+## Repository configuration
+
+Six services cover the half of a repository that is policy rather than content: `RepositorySecret`, `RepositoryVariable`, `Ruleset`, `DeploymentEnvironment`, `RepositorySecurity` and `CodeScanning`. They are shaped for a program applying the same configuration across a fleet, so every list read paginates to the end and a truncated page never becomes a wrong decision.
+
+Secrets carry the libsodium sealed box GitHub's API requires, which is why the value is a `Redacted<string>` rather than a plain one:
+
+```ts
+import { RepositorySecret } from "@effected/github";
+import { Effect, Redacted } from "effect";
+
+declare const token: string;
+
+const program = Effect.gen(function* () {
+  const secrets = yield* RepositorySecret;
+  yield* secrets.set("NPM_TOKEN", Redacted.make(token)); // the "actions" store by default
+  yield* secrets.setForEnvironment("production", "DEPLOY_KEY", Redacted.make(token));
+  return yield* secrets.list("dependabot");
+});
+// ReadonlyArray<SecretInfo> — names only. GitHub returns a secret's value from no endpoint,
+// so a diff against desired state detects a deleted secret and never an edited one.
+```
+
+`actions`, `dependabot` and `codespaces` are three stores on the same repository, each with its own public key, and the `scope` argument picks between them. The encryption lives in one module that only `RepositorySecret` imports, so a consumer that never writes a secret never links the crypto pair. `RepositoryVariable` mirrors the same six methods for the values that are not secret, where `set` lists first because GitHub splits create and update across two routes.
+
+`Ruleset.upsert` matches an existing ruleset by name **and** `source_type`. That second field is why the projection carries it: `GET /repos/{owner}/{repo}/rulesets` returns the rulesets a repository inherits from its organization alongside its own, and matching on name alone would let a repository-scoped write `PUT` the organization's ruleset id — rewriting policy for every repository that organization owns. `Ruleset.teamId` and `Ruleset.roleId` resolve the numeric ids a bypass actor needs, scoped to the organization in `Repo`.
+
+The rest follow their endpoints' own grain. `DeploymentEnvironment.upsert` is a plain `PUT` because GitHub's route is idempotent, and its `delete` takes the environment's secrets and variables with it, which fixes the order of any cleanup pass. `RepositorySecurity` reads and writes the three toggles GitHub keeps off the repository endpoint: vulnerability alerts, automated security fixes and private vulnerability reporting. `CodeScanning.configure` applies a CodeQL default setup and returns as soon as GitHub accepts it — the endpoint answers `202` and configures asynchronously, and nothing here polls — while `CodeScanning.languages` reports what GitHub detects in the repository, which is what you filter a configured language list against before calling `configure`.
+
+`GitHubRepository` owns the repository's own settings. `updateSettings` is the faithfully typed `PATCH`; `applySettings` is the applicator above it, taking an open map, routing each key to whichever API can actually set it, and reporting what went out:
+
+```ts
+import { GitHubRepository } from "@effected/github";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const repository = yield* GitHubRepository;
+  return yield* repository.applySettings({
+    has_issues: true,
+    has_sponsorships: false, // GraphQL-only: costs one extra read for the node id
+    security_and_analysis: { secret_scanning: "enabled" },
+  });
+});
+// AppliedSettings — { rest: [...], graphql: [...] }, in the caller's own key names.
+// The two lists agree with the input right up until preparation drops a field
+// GitHub would reject, which is what a person reading a dry run is checking for.
+```
+
+`security_and_analysis` accepts both the bare `"enabled"` a human writes in a config file and the `{ status: "enabled" }` GitHub's own parameter type declares. A map touching neither GraphQL-only setting never reads the node id, so the common case stays one request. `ownerType` answers `"User"` or `"Organization"` for the repository in `Repo`, which is how a shared settings template drops the fields GitHub accepts only on an organization-owned repository before applying itself to a personal one.
+
 ## GitHub App authentication
 
 `GitHubApp.clientLayer` builds a `GitHubClient` authenticated as an app installation. The token is minted on build, re-minted a minute before it expires, and revoked on release — best effort — so a workflow does not leave live credentials behind:
@@ -150,12 +199,34 @@ const TestBranches = GitBranch.layerTest({
 });
 ```
 
-`GitHubClient.layerFixture(fixtures)` is the one recorded-response double that pages for real: it builds a `PageSource` over the recorded array and hands it to the same pagination engine the live client uses, so a truncation path behaves identically under test and in production.
+`GitHubClient.layerFixture(fixtures)` is the one recorded-response double that pages for real: it builds a `PageSource` over the recorded array and hands it to the same pagination engine the live client uses, so a truncation path behaves identically under test and in production. Three things about its contract are worth knowing before you write against it:
+
+```ts
+import { GitHubClient, GitHubError } from "@effected/github";
+
+const fixtures = {
+  request: {
+    "GET /repos/{owner}/{repo}": { default_branch: "main" },
+    // A recorded GitHubError *is* the response: this route fails with it.
+    "PATCH /repos/{owner}/{repo}": GitHubError.notFound("updateSettings", "repo"),
+  },
+  paginate: { "GET /repos/{owner}/{repo}/rulesets": [{ id: 1, name: "main", source_type: "Repository" }] },
+  requested: [], // filled in as the test runs
+};
+
+const TestClient = GitHubClient.layerFixture(fixtures);
+// A route with no entry above DIES naming itself, rather than failing typed.
+```
+
+- **An unstubbed route dies by default.** A missing fixture is test wiring rather than a domain outcome, and a typed failure is only loud in code that does not catch — a program handling `GitHubError` per resource turns a missing stub into a different execution path, and the assertions then fail for reasons that name no fixture. `unstubbed: "fail"` restores the old typed not-found, and `"empty"` serves an empty value for a suite whose subject is decisions rather than endpoints.
+- **A recorded `GitHubError` value is the response.** That is how a suite stubs a 404, a 422 or a rate limit deliberately. Leaning on a route's absence says only "unwired"; a recorded error says which route fails and why.
+- **`fixtures.requested` records every call.** Each `RecordedCall` carries the `kind` of surface used, the `route` (the document name for `graphql`), the `params` the call was made with, and `perPage` for a paginated read. Params are what let a test assert what a method *sent*, which is the question any normalising write turns on.
 
 ## Features
 
 - `GitHubClient` — the typed transport: `request`, `requestDecoded` (a mandatory-schema escape hatch for routes outside the generated map), `paginate` / `paginateStream`, `graphql`, and `rateLimit` (observation only — nothing here throttles on your behalf).
 - `Repo` / `RepoRef` — the `{ owner, repo }` coordinate, resolved per call through `R`, with `Repo.provide` for multi-repository programs.
+- `GitHubRepository` — the repository's settings as GitHub's own generated type, plus `defaultBranch`, `nodeId`, `ownerType` for gating organization-only fields, and `applySettings` reporting the keys it actually sent.
 - `GitHubError` / `GitHubGraphQLError` — one error per transport, `kind`-routed with `hasKind` for `Effect.catchIf`.
 - `RetryPolicy` — the client's one retry policy: full-jitter backoff, server-advised delays honored up to a ceiling.
 - `GitHubApp` — App JWT signing, installation token minting/revocation, app and installation identity, and `clientLayer` for an App-authenticated `GitHubClient`.
@@ -163,6 +234,9 @@ const TestBranches = GitBranch.layerTest({
 - `CheckRun` — `withCheckRun` concludes on every exit path; `CheckRunOutput.truncated()` cuts rendered output to GitHub's byte limits.
 - `PullRequest` / `PullRequestComment` — upserts for both, `listFiles` answering with the same full `CommitFile` records a commit read returns, `headSha`/`baseSha` on `PullRequestInfo`, plus `CommentMarker` for finding a sticky comment again.
 - `GitHubRelease` — releases and asset uploads, including the one route (`uploadAsset`, with the endpoint's optional display label) outside GitHub's generated endpoint map.
+- `RepositorySecret` / `RepositoryVariable` — repository and environment secrets and variables, with the sealed-box encryption GitHub's secrets API demands kept in one module nothing else imports.
+- `Ruleset` / `DeploymentEnvironment` / `RepositorySecurity` / `CodeScanning` — the rest of the configuration tier: rulesets matched by name and scope, idempotent environment writes, the three security toggles GitHub keeps off the repository endpoint, and CodeQL default setup with the language detection that gates it.
+- `WorkflowDispatch` — fire a `workflow_dispatch` event, `list` the repository's workflows with the state string GitHub reports, or dispatch and wait for the run it created.
 - `BotIdentity` — the author and committer a bot commits as, with `signoff` rendering the DCO trailer that a commit made through the Git Data API never gets from `git commit -s`.
 - `Attestation` — upload and list attestations against a subject digest; building and signing the bundle is `@effected/sbom`'s job.
 - `TokenPermissions` — a pure comparator between granted and required permissions, reaching nothing but `effect`.