chore: sync docs + api reference for core@1.34.0

public/llms-full.txt

@@ -9029,6 +9029,23 @@ e2e = target().waitsFor((s) =>
 ```
 @module
 
+function assertRefName(name: string, what: string): void
+  Reject a branch or tag name that git itself would.
+
+  Not cosmetic. These names are interpolated into request paths, and URL
+  normalisation resolves `..` before the request is sent — so
+  `../../../user/repos` as a branch turns `/repos/o/n/git/ref/heads/<branch>`
+  into `/repos/o/n/user/repos`, sending a write-scoped token somewhere the
+  caller never named. Validating here rather than trusting every caller is the
+  difference between an API that is safe to hand a string and one that is safe
+  only when used carefully.
+
+  The rules are git's own (see `git check-ref-format`), minus those that only
+  matter for multi-level refs.
+
+async function commitFiles(configure?: (settings: GhCommitSettings) => GhCommitSettings): Promise<GhCommitResult>
+  Perform the configured commit.
+
 function githubWorkflow(configure: (settings: GithubWorkflowSettings) => GithubWorkflowSettings): WaitTrigger
   A {@link "@zuke/core".WaitTrigger} that dispatches a GitHub Actions workflow,
   suspends the run until it finishes, and records its per-job conclusions to the
@@ -9048,12 +9065,30 @@ function readWorkflowResult(state: TargetStateHandle): WorkflowResult | undefine
   not a github-workflow gate). Call it from a dependent target's body with
   the gate's handle: `readWorkflowResult(ctx.stateOf("<gate-target>"))`.
 
+async function tagCommit(configure?: (settings: GhTagSettings) => GhTagSettings): Promise<void>
+  Perform the configured tag.
+
 async function uploadSarifReport(configure?: Configure<GhSarifSettings>): Promise<GhSarifUploadResult>
   Upload the SARIF report the settings describe.
 
 const GhTasks: GhTasksApi
   Typed task functions for GitHub: the `gh` CLI and the REST-only operations.
 
+class GhApiError extends Error
+  A GitHub REST call that did not succeed, carrying the status.
+
+  The status is the point. One caller here recovers from a missing ref, and
+  doing that on a bare `catch` would swallow an expired token or a missing
+  permission and retry them as though the ref simply did not exist — turning an
+  authorisation failure into a confusing one about creating a tag.
+
+  constructor(method: string, path: string, status: number, body: string)
+    Build the error from the failing call's method, path, status and body.
+  override name: string
+    The error name.
+  readonly status: number
+    The HTTP status of the failing response.
+
 class GhAppTokenSettings
   Settings for {@link GhAppTokenApi.appToken}.
 
@@ -9108,6 +9143,51 @@ class GhAppTokenSettings
   tokenRequest_(): Record<string, unknown>
     The `access_tokens` request body — only the fields that were narrowed.
 
+class GhCommitSettings
+  Settings for committing files through the API.
+
+  `owner/repo` and the token fall back to the Actions environment, so a job
+  that already has them needs to name only what it is committing.
+
+  files_: Map<string, string>
+    The files to write, by path.
+  branch_?: string
+    The branch to commit onto. Set by {@link branch}.
+  from_?: string
+    The branch to create from, when creating one. Set by {@link from}.
+  message_?: string
+    The commit message. Set by {@link message}.
+  repo_?: string
+    `owner/repo`. Set by {@link repo}.
+  token_?: string
+    The token. Set by {@link token}.
+  baseUrl_: string
+    The API root. Set by {@link baseUrl}.
+  fetch_: typeof fetch
+    The `fetch` implementation. Set by {@link fetch}.
+  file(path: string, content: string): this
+    Add a file to the commit, replacing any earlier one at the same path.
+  branch(name: string): this
+    The branch to commit onto. It must exist unless {@link from} is set.
+  from(base: string): this
+    Create {@link branch} from this one rather than committing onto an
+    existing branch. Creating a ref and moving one are different calls, and
+    which is wanted is the caller's to say rather than something to infer.
+  message(text: string): this
+    The commit message.
+  repo(slug: string): this
+    `owner/repo`. Defaults to `GITHUB_REPOSITORY`.
+  token(value: string): this
+    The token to authenticate with. Defaults to `GITHUB_TOKEN`.
+  baseUrl(url: string): this
+    The API root, for GitHub Enterprise.
+  fetch(fn: typeof fetch): this
+    Override the `fetch` implementation (a test seam).
+  repoSlug_(): string
+    The effective `owner/repo`, from the setting or the environment.
+  authToken_(): string
+    The effective token, from the setting or the environment.
+
 class GhSarifSettings
   Settings for {@link GhSarifApi.uploadSarif}.
 
@@ -9160,6 +9240,50 @@ class GhSettings extends SubcommandSettings
   override protected middleTokens(): string[]
     Emit `--repo <slug>` between the command path and the flags, when set.
 
+class GhTagSettings
+  Settings for pointing a tag at a commit.
+
+  name_?: string
+    The tag name. Set by {@link name}.
+  commit_?: string
+    The commit the tag points at. Set by {@link commit}.
+  message_?: string
+    The annotation message. Set by {@link message}.
+  move_: boolean
+    Whether to move an existing tag. Set by {@link move}.
+  repo_?: string
+    `owner/repo`. Set by {@link repo}.
+  token_?: string
+    The token. Set by {@link token}.
+  baseUrl_: string
+    The API root. Set by {@link baseUrl}.
+  fetch_: typeof fetch
+    The `fetch` implementation. Set by {@link fetch}.
+  name(value: string): this
+    The tag name, e.g. `v1.2.3`.
+  commit(sha: string): this
+    The commit SHA to tag. Defaults to `GITHUB_SHA`.
+  message(text: string): this
+    The annotation message. Defaults to the tag name.
+  move(): this
+    Move the tag if it already exists, rather than failing.
+
+    Forced by necessity: pointing a major tag at a newer release is a
+    non-fast-forward by definition. A tag that does not exist yet is created,
+    since for the first release of a major those are the same intent.
+  repo(slug: string): this
+    `owner/repo`. Defaults to `GITHUB_REPOSITORY`.
+  token(value: string): this
+    The token to authenticate with. Defaults to `GITHUB_TOKEN`.
+  baseUrl(url: string): this
+    The API root, for GitHub Enterprise.
+  fetch(fn: typeof fetch): this
+    Override the `fetch` implementation (a test seam).
+  repoSlug_(): string
+    The effective `owner/repo`, from the setting or the environment.
+  authToken_(): string
+    The effective token, from the setting or the environment.
+
 class GithubWorkflowSettings
   Configuration for {@link githubWorkflow}, set through a settings lambda. Every
   setter returns `this` so calls chain; `repo` and `workflow` are required.
@@ -9233,6 +9357,26 @@ interface GhAppTokenResult
   installationId: number
     The installation the token was minted for.
 
+interface GhCommitApi
+  The commit and tag operations {@link GhTasks} exposes.
+
+  commit(configure?: (settings: GhCommitSettings) => GhCommitSettings): Promise<GhCommitResult>
+    Commit files through the API, with no git credential on disk.
+
+    Commits onto `.branch(...)`, or creates it from `.from(...)` when that is
+    set. The ref update is not forced, so a commit landing between reading the
+    head and writing it is rejected rather than silently overwritten.
+  tag(configure?: (settings: GhTagSettings) => GhTagSettings): Promise<void>
+    Point an annotated tag at a commit, creating or moving its ref.
+
+interface GhCommitResult
+  The commit a {@link GhTasksApi.commit} call created.
+
+  sha: string
+    The new commit's SHA.
+  branch: string
+    The branch it landed on.
+
 interface GhSarifApi
   The shape of the SARIF task, mixed into `GhTasks`.
 
@@ -9248,7 +9392,7 @@ interface GhSarifUploadResult
   url: string
     The URL that reports whether GitHub finished processing the report.
 
-interface GhTasksApi extends GhAppTokenApi, GhSarifApi
+interface GhTasksApi extends GhAppTokenApi, GhSarifApi, GhCommitApi
   The shape of {@link GhTasks}: the `gh` CLI plus the GitHub operations that
   have no CLI subcommand (see {@link GhAppTokenApi}, {@link GhSarifApi}) and
   would otherwise force a build back to a marketplace action.