@effected/github 0.1.0 → 0.2.1

package/ArtifactMetadata.js

@@ -1,4 +1,5 @@
 import { GitHubClient } from "./GitHubClient.js";
+import { Repo } from "./Repo.js";
 import { Context, Effect, Layer, Schema } from "effect";
 
 //#region src/ArtifactMetadata.ts
@@ -42,13 +43,14 @@ var ArtifactMetadata = class ArtifactMetadata extends Context.Service()("@effect
 const unstubbed = (member) => {
 	throw new Error(`ArtifactMetadata.makeTest: ${member}() was called but not stubbed — pass an override.`);
 };
-const make = (client) => ({ createStorageRecord: Effect.fn("ArtifactMetadata.createStorageRecord")(function* (org, input) {
+const make = (client) => ({ createStorageRecord: Effect.fn("ArtifactMetadata.createStorageRecord")(function* (input) {
+	const { owner } = yield* Repo;
 	yield* Effect.annotateCurrentSpan({
-		org,
+		org: owner,
 		artifact: input.name
 	});
 	return ((yield* client.request("POST /orgs/{org}/artifacts/metadata/storage-record", {
-		org,
+		org: owner,
 		name: input.name,
 		digest: input.digest,
 		registry_url: input.registryUrl,

package/GitHubApp.js

@@ -122,6 +122,22 @@ var BotIdentity = class BotIdentity extends Schema.Class("BotIdentity")({
 		name: "github-actions[bot]",
 		email: "41898282+github-actions[bot]@users.noreply.github.com"
 	});
+	/**
+	* The DCO sign-off trailer for this identity.
+	*
+	* @remarks
+	* `Signed-off-by: name <email>` — DCO 1.1's fixed casing and spacing, with
+	* only the email in angle brackets, rendered by the type that owns the
+	* data. Commits created
+	* through the Git Data API bypass `git commit -s`, so no porcelain adds
+	* the trailer, and a hand-built one that is subtly wrong fails late as a
+	* red DCO check on someone else's pull request. Whether a missing
+	* identity falls back to {@link BotIdentity.githubActions} stays the
+	* caller's policy.
+	*/
+	get signoff() {
+		return `Signed-off-by: ${this.name} <${this.email}>`;
+	}
 };
 /**
 * What GitHub knows about the app itself.

package/GitHubCommit.js

@@ -19,7 +19,16 @@ var CommitSummary = class extends Schema.Class("CommitSummary")({
 	/** The GitHub login of the authoring account, when GitHub could attribute one. */
 	authorLogin: Schema.optionalKey(Schema.String),
 	/** The web URL for the commit. */
-	url: Schema.String
+	url: Schema.String,
+	/**
+	* The parent commit shas, in the order GitHub lists them.
+	*
+	* @remarks
+	* Empty for a root commit, two or more for a merge commit. A required field,
+	* not an optional one: every commit endpoint this package reads reports
+	* `parents`, so "which commit(s) did this come from" never needs a raw route.
+	*/
+	parents: Schema.Array(Schema.String)
 }) {
 	/** The message's first line. */
 	get subject() {
@@ -104,8 +113,13 @@ const summarize = (raw) => CommitSummary.make({
 	message: raw.commit.message,
 	author: raw.commit.author?.name ?? "Unknown",
 	...raw.author?.login !== void 0 ? { authorLogin: raw.author.login } : {},
-	url: raw.html_url
+	url: raw.html_url,
+	parents: raw.parents.map((parent) => parent.sha)
 });
+/**
+* Project a `diff-entry` to a {@link CommitFile}. Shared with
+* `PullRequest.listFiles`; not re-exported from the package entrypoint.
+*/
 const fileOf = (raw) => CommitFile.make({
 	path: raw.filename,
 	status: raw.status,
@@ -195,4 +209,4 @@ const make = (client) => ({
 });
 
 //#endregion
-export { CommitComparison, CommitFile, CommitSummary, FileStatus, GitHubCommit };
+export { CommitComparison, CommitFile, CommitSummary, FileStatus, GitHubCommit, fileOf };

package/GitHubRelease.js

@@ -155,11 +155,12 @@ const make = (client) => {
 				release: release.id,
 				asset: asset.name
 			});
-			const raw = yield* client.requestDecoded("POST /repos/{owner}/{repo}/releases/{release_id}/assets", {
+			const raw = yield* client.requestDecoded(asset.label === void 0 ? "POST /repos/{owner}/{repo}/releases/{release_id}/assets{?name}" : "POST /repos/{owner}/{repo}/releases/{release_id}/assets{?name,label}", {
 				owner,
 				repo,
 				release_id: release.id,
 				name: asset.name,
+				...asset.label === void 0 ? {} : { label: asset.label },
 				data: asset.data,
 				baseUrl: UPLOADS_BASE_URL,
 				headers: { "content-type": asset.contentType }

package/PullRequest.js

@@ -2,6 +2,7 @@ import { GitHubError } from "./GitHubError.js";
 import { GraphQLDocument } from "./GraphQL.js";
 import { GitHubClient } from "./GitHubClient.js";
 import { Repo } from "./Repo.js";
+import { fileOf } from "./GitHubCommit.js";
 import { PageOptions } from "./Rest.js";
 import { Context, DateTime, Effect, Layer, Option, Schema } from "effect";
 
@@ -28,8 +29,12 @@ var PullRequestInfo = class extends Schema.Class("PullRequestInfo")({
 	state: Schema.Literals(["open", "closed"]),
 	/** The source branch name. */
 	head: Schema.String,
+	/** The sha the source branch pointed at when GitHub answered. */
+	headSha: Schema.String,
 	/** The target branch name. */
 	base: Schema.String,
+	/** The sha the target branch pointed at when GitHub answered — the commit the pull request branches from. */
+	baseSha: Schema.String,
 	draft: Schema.Boolean,
 	merged: Schema.Boolean,
 	/**
@@ -104,7 +109,9 @@ const project = (raw) => Effect.try({
 		title: raw.title,
 		state: raw.state === "closed" ? "closed" : "open",
 		head: raw.head.ref,
+		headSha: raw.head.sha,
 		base: raw.base.ref,
+		baseSha: raw.base.sha,
 		draft: raw.draft ?? false,
 		merged: raw.merged ?? raw.merged_at != null,
 		mergedAt: raw.merged_at == null ? Option.none() : Option.some(DateTime.makeUnsafe(raw.merged_at)),
@@ -193,7 +200,7 @@ const make = (client) => {
 				owner,
 				repo,
 				pull_number: number
-			}, options?.page)).map((file) => file.filename);
+			}, options?.page)).map(fileOf);
 		}),
 		listAssociatedWithCommit: Effect.fn("PullRequest.listAssociatedWithCommit")(function* (sha, options) {
 			const { owner, repo } = yield* Repo;

package/README.md

@@ -0,0 +1,172 @@
+# @effected/github
+
+[![npm](https://img.shields.io/npm/v/@effected%2Fgithub?label=npm&color=cb3837)](https://www.npmjs.com/package/@effected/github)
+[![License: MIT](https://img.shields.io/badge/License-MIT-4caf50.svg)](https://opensource.org/licenses/MIT)
+[![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.
+
+> **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
+> `1.0.0` once Effect `4.0.0` ships. To hold your own `effect` versions at
+> exactly the ones the kit is built and tested against, install
+> [`@effected/pnpm-plugin-effect`](https://www.npmjs.com/package/@effected/pnpm-plugin-effect).
+>
+> **Stability: unstable.** This package's API surface is not yet considered
+> complete and may change across `0.x` releases. Pin an exact version — even a
+> package marked *stable* before `1.0.0` can introduce a breaking change by
+> accident, and an exact pin turns that into a type-check error rather than a
+> runtime surprise. Full policy: [release strategy](https://github.com/spencerbeggs/effected#release-strategy).
+
+## Why @effected/github
+
+Hand-rolled octokit wrappers tend to converge on the same shape: a `rest<T>(operation: string, fn: (octokit) => Promise<{ data: T }>)` helper where `T` is whatever the caller wrote and nothing connects it to the endpoint. This package's route-keyed `request` closes that gap — `@octokit/types` already generates a map from GitHub's own OpenAPI description, and `@octokit/core`'s `request` already consumes it, so there was no reason to reinvent either.
+
+The error model gets the same treatment. `GitHubError.kind` is a literal union (`notFound`, `alreadyExists`, `rejected`, `unauthorized`, `rateLimited`, `transport`, `decode`) produced by one classification step, `GitHubError.fromOctokit`, instead of one hand-written mapper per resource. `kind: "alreadyExists"` is what makes `GitBranch.upsert` and `GitTag.upsert` a single round trip in the common case, rather than a create-then-catch-then-check-then-reset dance repeated at every call site that needs it.
+
+This package also owns the octokit runtime so nothing downstream has to. `@octokit/rest` and `@octokit/auth-app` are deliberately absent — the rest wrapper is a request-logging plugin plus 1.4 MB of duplicate endpoint types, and `auth-app` drags in `createOAuthUserAuth`, roughly 492 KB of OAuth machinery this package never calls. GitHub App JWTs are signed by `universal-github-app-jwt` instead, the same zero-dependency signer `@octokit/auth-app` itself uses. A consumer that only authenticates with a token it already holds never links the JWT signer at all: the App-authenticated layer lives in its own module (`GitHubApp`), and nothing here is gathered into a namespace object that would defeat that split.
+
+## Install
+
+```bash
+npm install @effected/github effect
+```
+
+```bash
+pnpm add @effected/github effect
+```
+
+Requires Node.js >=24.11.0. `effect` v4 is a peer dependency.
+
+All `@effected/*` packages are ESM-only: the exports maps publish only `import` conditions, so `require()` — including tools that resolve in CJS mode — fails with Node's `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a CJS build that does not exist. Import from an ES module.
+
+## Quick start
+
+```ts
+import { GitHubClient, Repo, RepoRef } from "@effected/github";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const client = yield* GitHubClient;
+  const repo = yield* client.request("GET /repos/{owner}/{repo}", { owner: "effect-ts", repo: "effect" });
+  return repo.default_branch; // string — typed from the route literal, no cast
+});
+
+const ClientLayer = GitHubClient.layerFromConfig(); // reads GITHUB_TOKEN through the ambient ConfigProvider
+const RepoLayer = Repo.layer(RepoRef.make({ owner: "effect-ts", repo: "effect" }));
+
+Effect.runPromise(program.pipe(Effect.provide(ClientLayer), Effect.provide(RepoLayer))).then(console.log);
+// the repository's default branch name, e.g. "main"
+```
+
+`Repo` carries the `{ owner, repo }` coordinate in `R` rather than as a per-call argument, so every resource method below reads as a single expression. A program acting on more than one repository uses `Repo.provide(otherRef)` around the part that needs it.
+
+## Resource services
+
+Each resource is a service over `GitHubClient`, with its own `layer`, `makeTest` and `layerTest`. `GitBranch.upsert` is the case that motivated the whole set:
+
+```ts
+import { GitBranch, GitHubClient, Repo } from "@effected/github";
+import { Effect } from "effect";
+
+const program = Effect.gen(function* () {
+  const branches = yield* GitBranch;
+  return yield* branches.upsert("release/1.2", "abc123");
+});
+// Effect<"created" | "reset", GitHubError, GitBranch | Repo>
+// one round trip in the common case, two in the raced one — never four
+```
+
+`CheckRun.withCheckRun` runs a program inside a check run and concludes it on every exit path — success, typed failure, defect or interrupt — so a run never gets stuck `in_progress`:
+
+```ts
+import { CheckRun } from "@effected/github";
+import { Effect } from "effect";
+
+declare const lint: () => Effect.Effect<ReadonlyArray<string>>;
+declare const deriveConclusion: (findings: ReadonlyArray<string>) => "success" | "neutral" | "failure";
+
+const program = Effect.gen(function* () {
+  const check = yield* CheckRun;
+  return yield* check.withCheckRun("lint", "abc123", (_id, conclude) =>
+    Effect.gen(function* () {
+      const findings = yield* lint();
+      yield* conclude(deriveConclusion(findings));
+      return findings;
+    }),
+  );
+});
+```
+
+`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.
+
+## 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:
+
+```ts
+import { GitHubApp } from "@effected/github";
+import { Redacted } from "effect";
+
+// bind once — layers memoize by reference
+const AppClient = GitHubApp.clientLayer({
+  appId: "123456",
+  privateKey: Redacted.make(process.env.GITHUB_APP_PRIVATE_KEY as string),
+  owner: "effect-ts",
+});
+// Layer<GitHubClient, GitHubAppError> — provide it wherever a GitHubClient is needed
+```
+
+Only `GitHubApp` and its statics import the JWT signer — a consumer authenticating with a plain token never reaches it.
+
+## Errors
+
+`GitHubError` covers REST, `GitHubGraphQLError` covers GraphQL, `GitHubAppError` covers app authentication, and `TokenPermissions` produces its own `TokenPermissionError` — four kinds, not one per resource:
+
+```ts
+import { GitHubError } from "@effected/github";
+import { Effect } from "effect";
+
+declare const upsertBranch: Effect.Effect<"created" | "reset", GitHubError>;
+
+const program = upsertBranch.pipe(
+  Effect.catchIf(GitHubError.hasKind("rateLimited"), (error) => Effect.logWarning(`retry after ${error.retryAfterMillis}ms`)),
+);
+```
+
+Retrying is handled once, in the client: `RetryPolicy.default` retries a `transport` or `rateLimited` failure with full-jitter backoff, honoring GitHub's `retry-after` header up to a configurable ceiling. `RetryPolicy.none` disables it. A `notFound`, `rejected` or `unauthorized` failure never retries — it cannot change its mind between attempts.
+
+## Testing
+
+Every resource ships `makeTest(overrides?)` and `layerTest(overrides?)`: stub the members a test exercises, and every other member dies naming itself, so a test proves it touches nothing it did not stub:
+
+```ts
+import { GitBranch } from "@effected/github";
+import { Effect } from "effect";
+
+const TestBranches = GitBranch.layerTest({
+  upsert: () => Effect.succeed("created"),
+});
+```
+
+`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.
+
+## 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.
+- `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`.
+- `GitBranch` / `GitTag` — Git Database API refs, with `upsert` collapsing the create-or-reset dance to one call and `GitTag.latestSemver` picking the newest version-shaped tag in one pass.
+- `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.
+- `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`.
+
+## License
+
+[MIT](LICENSE)

package/index.d.ts

@@ -684,60 +684,6 @@ declare class GitHubClient extends GitHubClient_base {
   static readonly layerFixture: (fixtures: GitHubFixtures) => Layer.Layer<GitHubClient>;
 }
 //#endregion
-//#region src/ArtifactMetadata.d.ts
-declare const StorageRecordInput_base: Schema.Class<StorageRecordInput, Schema.Struct<{
-  /** The artifact's package URL (purl). */
-  readonly name: Schema.NonEmptyString;
-  /** Its content digest, as `algorithm:hex`. */
-  readonly digest: Schema.NonEmptyString;
-  /** The registry's base URL. */
-  readonly registryUrl: Schema.NonEmptyString;
-  /** The repository name **within the registry**. */
-  readonly repository: Schema.NonEmptyString;
-  /** Where the artifact is stored, when there is a direct URL. */
-  readonly artifactUrl: Schema.optionalKey<Schema.String>;
-  /** The artifact's path within the registry, when there is one. */
-  readonly path: Schema.optionalKey<Schema.String>;
-}>, {}>;
-/**
- * What to record about a published artifact.
- *
- * @remarks
- * These are the fields the endpoint actually accepts. The version this replaces
- * declared a `version` field the endpoint has no notion of — a fabricated key
- * that a `Record<string, unknown>` body accepted silently and the generated
- * types reject outright.
- *
- * @public
- */
-declare class StorageRecordInput extends StorageRecordInput_base {}
-/**
- * Organization-level artifact metadata.
- *
- * @remarks
- * Org-scoped rather than repository-scoped, so it takes the organization as an
- * argument and does **not** read {@link Repo}.
- *
- * @public
- */
-interface ArtifactMetadataShape {
-  /** Record where a published artifact lives; returns the ids GitHub stored. */
-  readonly createStorageRecord: (org: string, input: StorageRecordInput) => Effect.Effect<ReadonlyArray<number>, GitHubError>;
-}
-declare const ArtifactMetadata_base: Context.ServiceClass<ArtifactMetadata, "@effected/github/ArtifactMetadata", ArtifactMetadataShape>;
-/**
- * Artifact metadata.
- *
- * @public
- */
-declare class ArtifactMetadata extends ArtifactMetadata_base {
-  static readonly layer: Layer.Layer<ArtifactMetadata, never, GitHubClient>;
-  /** An in-memory double; unstubbed members die naming themselves. */
-  static readonly makeTest: (overrides?: Partial<ArtifactMetadataShape>) => ArtifactMetadataShape;
-  /** {@link ArtifactMetadata.makeTest} behind a `Layer`. */
-  static readonly layerTest: (overrides?: Partial<ArtifactMetadataShape>) => Layer.Layer<ArtifactMetadata>;
-}
-//#endregion
 //#region src/Repo.d.ts
 declare const InvalidRepoRefError_base: Schema.Class<InvalidRepoRefError, Schema.TaggedStruct<"InvalidRepoRefError", {
   /** What was handed in. */
@@ -835,6 +781,63 @@ declare class Repo extends Repo_base {
   static readonly provide: (ref: RepoRef) => <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, Repo>>;
 }
 //#endregion
+//#region src/ArtifactMetadata.d.ts
+declare const StorageRecordInput_base: Schema.Class<StorageRecordInput, Schema.Struct<{
+  /** The artifact's package URL (purl). */
+  readonly name: Schema.NonEmptyString;
+  /** Its content digest, as `algorithm:hex`. */
+  readonly digest: Schema.NonEmptyString;
+  /** The registry's base URL. */
+  readonly registryUrl: Schema.NonEmptyString;
+  /** The repository name **within the registry**. */
+  readonly repository: Schema.NonEmptyString;
+  /** Where the artifact is stored, when there is a direct URL. */
+  readonly artifactUrl: Schema.optionalKey<Schema.String>;
+  /** The artifact's path within the registry, when there is one. */
+  readonly path: Schema.optionalKey<Schema.String>;
+}>, {}>;
+/**
+ * What to record about a published artifact.
+ *
+ * @remarks
+ * These are the fields the endpoint actually accepts. The version this replaces
+ * declared a `version` field the endpoint has no notion of — a fabricated key
+ * that a `Record<string, unknown>` body accepted silently and the generated
+ * types reject outright.
+ *
+ * @public
+ */
+declare class StorageRecordInput extends StorageRecordInput_base {}
+/**
+ * Organization-level artifact metadata.
+ *
+ * @remarks
+ * The endpoint is org-scoped rather than repository-scoped, but the
+ * organization is resolved from {@link Repo}'s `owner` per call like every
+ * other resource — an earlier version took it as a positional argument, the
+ * one method on the surface that did. `Repo.provide` covers the cross-org
+ * case, exactly as it covers the cross-repository one.
+ *
+ * @public
+ */
+interface ArtifactMetadataShape {
+  /** Record where a published artifact lives; returns the ids GitHub stored. */
+  readonly createStorageRecord: (input: StorageRecordInput) => Effect.Effect<ReadonlyArray<number>, GitHubError, Repo>;
+}
+declare const ArtifactMetadata_base: Context.ServiceClass<ArtifactMetadata, "@effected/github/ArtifactMetadata", ArtifactMetadataShape>;
+/**
+ * Artifact metadata.
+ *
+ * @public
+ */
+declare class ArtifactMetadata extends ArtifactMetadata_base {
+  static readonly layer: Layer.Layer<ArtifactMetadata, never, GitHubClient>;
+  /** An in-memory double; unstubbed members die naming themselves. */
+  static readonly makeTest: (overrides?: Partial<ArtifactMetadataShape>) => ArtifactMetadataShape;
+  /** {@link ArtifactMetadata.makeTest} behind a `Layer`. */
+  static readonly layerTest: (overrides?: Partial<ArtifactMetadataShape>) => Layer.Layer<ArtifactMetadata>;
+}
+//#endregion
 //#region src/Attestation.d.ts
 declare const AttestationRecord_base: Schema.Class<AttestationRecord, Schema.Struct<{
   /** GitHub's id for it, when the response carried one. */
@@ -1094,6 +1097,18 @@ interface GitBranchShape {
    * This is one round trip in the common case and two in the raced one, and the
    * recovery **resets** rather than inheriting a branch a concurrent creator
    * rooted somewhere else — which is the semantics that comment was defending.
+   *
+   * **A reset is observable, and open pull requests react to it.** Resetting a
+   * branch to its PR's base — `upsert(branch, targetHead)` — makes that PR's
+   * head equal its base, and GitHub **auto-closes a PR whose diff is empty**.
+   * The window is invisible at this call site: a consumer ran
+   * `upsert(releaseBranch, mainHead)` intending to re-add content with a commit
+   * ~3 seconds later, and GitHub closed the open release PR inside that window
+   * while the run reported success. When the end state is "the target head plus
+   * a commit", build the commit first — `GitCommit.get` the target for its
+   * `treeSha`, `createTree` on it, `createCommit` with the target as parent —
+   * and upsert **once**, straight to the finished sha, so the ref never rests
+   * on the bare target head.
    */
   readonly upsert: (name: string, sha: string) => Effect.Effect<BranchOutcome, GitHubError, Repo>;
   /** Is the branch there? A 404 is `false`, not an error. */
@@ -1233,6 +1248,19 @@ interface GitCommitShape {
    * tree, create the commit, move the ref — as one operation. The ref update is
    * **not** forced: a branch that moved underneath you is a conflict worth
    * hearing about, not one to overwrite.
+   *
+   * **This is "commit onto a branch you own", not a rebase.** Putting a commit
+   * on top of *another* branch's head — the release-branch pattern — is a
+   * different operation, and it composes from the members above with no
+   * observable intermediate state: {@link GitCommitShape.get} the target head
+   * for its `treeSha`, {@link GitCommitShape.createTree} on it,
+   * {@link GitCommitShape.createCommit} with the target as parent, then one
+   * `GitBranch.upsert` straight to the finished commit. Do **not** spell a
+   * rebase as `upsert(branch, targetHead)` followed by `commitFiles`: between
+   * those calls the branch *is* the target head, an open pull request from it
+   * has an empty diff, and GitHub auto-closes PRs in that state — a real
+   * consumer lost its open release PR to that ~3-second window while the run
+   * went green.
    */
   readonly commitFiles: (options: {
     readonly branch: string;
@@ -1390,6 +1418,20 @@ declare class BotIdentity extends BotIdentity_base {
   }): BotIdentity;
   /** The well-known identity of the `github-actions` bot. */
   static readonly githubActions: BotIdentity;
+  /**
+   * The DCO sign-off trailer for this identity.
+   *
+   * @remarks
+   * `Signed-off-by: name <email>` — DCO 1.1's fixed casing and spacing, with
+   * only the email in angle brackets, rendered by the type that owns the
+   * data. Commits created
+   * through the Git Data API bypass `git commit -s`, so no porcelain adds
+   * the trailer, and a hand-built one that is subtly wrong fails late as a
+   * red DCO check on someone else's pull request. Whether a missing
+   * identity falls back to {@link BotIdentity.githubActions} stays the
+   * caller's policy.
+   */
+  get signoff(): string;
 }
 declare const AppIdentity_base: Schema.Class<AppIdentity, Schema.Struct<{
   /** The URL slug, e.g. `"my-app"`. */
@@ -1559,6 +1601,15 @@ declare const CommitSummary_base: Schema.Class<CommitSummary, Schema.Struct<{
   readonly authorLogin: Schema.optionalKey<Schema.String>;
   /** The web URL for the commit. */
   readonly url: Schema.String;
+  /**
+   * The parent commit shas, in the order GitHub lists them.
+   *
+   * @remarks
+   * Empty for a root commit, two or more for a merge commit. A required field,
+   * not an optional one: every commit endpoint this package reads reports
+   * `parents`, so "which commit(s) did this come from" never needs a raw route.
+   */
+  readonly parents: Schema.$Array<Schema.String>;
 }>, {}>;
 /**
  * A commit, projected to what callers read.
@@ -1835,11 +1886,19 @@ interface GitHubReleaseShape {
    * endpoint map: asset upload goes to `uploads.github.com` with a raw binary
    * body, and the map omits it. So it goes through `requestDecoded` with an
    * owned schema — the escape hatch is from the route table, never from typing.
+   *
+   * Being outside the map cuts the other way too: octokit has no schema
+   * saying `name` is a **query** parameter, so the route template must carry
+   * it (`assets{?name}`) or octokit silently drops it and GitHub answers 400
+   * `Invalid name for request` — a hand-written route owns its query
+   * parameters in the template, always. `label` is the endpoint's optional
+   * display label, shown in place of the file name on the release page.
    */
   readonly uploadAsset: (release: ReleaseInfo, asset: {
     readonly name: string;
     readonly data: Uint8Array | string;
     readonly contentType: string;
+    readonly label?: string | undefined;
   }) => Effect.Effect<ReleaseAsset, GitHubError, Repo>;
   readonly listAssets: (id: number, options?: {
     readonly page?: PageOptions | undefined;
@@ -2039,8 +2098,12 @@ declare const PullRequestInfo_base: Schema.Class<PullRequestInfo, Schema.Struct<
   readonly state: Schema.Literals<readonly ["open", "closed"]>;
   /** The source branch name. */
   readonly head: Schema.String;
+  /** The sha the source branch pointed at when GitHub answered. */
+  readonly headSha: Schema.String;
   /** The target branch name. */
   readonly base: Schema.String;
+  /** The sha the target branch pointed at when GitHub answered — the commit the pull request branches from. */
+  readonly baseSha: Schema.String;
   readonly draft: Schema.Boolean;
   readonly merged: Schema.Boolean;
   /**
@@ -2081,10 +2144,20 @@ interface PullRequestShape {
     readonly state?: "open" | "closed" | "all" | undefined;
     readonly page?: PageOptions | undefined;
   }) => Effect.Effect<ReadonlyArray<PullRequestInfo>, GitHubError, Repo>;
-  /** The files a pull request changes. */
+  /**
+   * The files a pull request changes.
+   *
+   * @remarks
+   * Each entry is a full {@link CommitFile} — path **and** status, plus the
+   * line counts and any pre-rename path — the same projection
+   * `GitHubCommit.changedFiles` returns, because GitHub answers both
+   * endpoints with the same `diff-entry` shape. An earlier version projected
+   * to the path alone, and consumers who needed the status fell back to a raw
+   * route.
+   */
   readonly listFiles: (number: number, options?: {
     readonly page?: PageOptions | undefined;
-  }) => Effect.Effect<ReadonlyArray<string>, GitHubError, Repo>;
+  }) => Effect.Effect<ReadonlyArray<CommitFile>, GitHubError, Repo>;
   /**
    * The pull requests associated with a commit.
    *

package/index.js

@@ -2,8 +2,8 @@ import { GitHubError, GitHubErrorKind } from "./GitHubError.js";
 import { GitHubGraphQLError, GraphQLDocument, GraphQLErrorEntry } from "./GraphQL.js";
 import { RateLimitSnapshot, RetryPolicy } from "./Resilience.js";
 import { GitHubClient } from "./GitHubClient.js";
-import { ArtifactMetadata, StorageRecordInput } from "./ArtifactMetadata.js";
 import { InvalidRepoRefError, Repo, RepoRef } from "./Repo.js";
+import { ArtifactMetadata, StorageRecordInput } from "./ArtifactMetadata.js";
 import { Attestation, AttestationListEntry, AttestationRecord } from "./Attestation.js";
 import { Annotation, AnnotationLevel, CheckConclusion, CheckRun, CheckRunOutput, CheckRunRef } from "./CheckRun.js";
 import { GitBranch } from "./GitBranch.js";

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@effected/github",
-	"version": "0.1.0",
+	"version": "0.2.1",
 	"private": false,
 	"description": "Typed GitHub REST and GraphQL services over the octokit core request surface, with app auth and resource helpers.",
 	"keywords": [
@@ -38,7 +38,7 @@
 		"./package.json": "./package.json"
 	},
 	"dependencies": {
-		"@effected/semver": "~0.2.1",
+		"@effected/semver": "~0.3.0",
 		"@octokit/core": "^7.0.6",
 		"@octokit/plugin-paginate-rest": "^14.0.0",
 		"@octokit/types": "^16.0.0",