diff --git a/public/llms-full.txt b/public/llms-full.txt index ad8b744..3076332 100644 --- a/public/llms-full.txt +++ b/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/` + 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 + 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(""))`. +async function tagCommit(configure?: (settings: GhTagSettings) => GhTagSettings): Promise + Perform the configured tag. + async function uploadSarifReport(configure?: Configure): Promise 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 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 + 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 ` 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 + 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 + 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. diff --git a/src/data/api.json b/src/data/api.json index 5c47685..4f668d2 100644 --- a/src/data/api.json +++ b/src/data/api.json @@ -17988,6 +17988,20 @@ "dir": "gh", "summary": "`@zuke/gh` — typed GitHub tooling for Zuke builds: the `gh` (GitHub CLI) task", "symbols": [ + { + "name": "assertRefName", + "kind": "function", + "doc": "Reject a branch or tag name that git itself would.\n\nNot cosmetic. These names are interpolated into request paths, and URL\nnormalisation resolves `..` before the request is sent — so\n`../../../user/repos` as a branch turns `/repos/o/n/git/ref/heads/`\ninto `/repos/o/n/user/repos`, sending a write-scoped token somewhere the\ncaller never named. Validating here rather than trusting every caller is the\ndifference between an API that is safe to hand a string and one that is safe\nonly when used carefully.\n\nThe rules are git's own (see `git check-ref-format`), minus those that only\nmatter for multi-level refs.", + "signature": "function assertRefName(name: string, what: string): void", + "deprecated": false + }, + { + "name": "commitFiles", + "kind": "function", + "doc": "Perform the configured commit.", + "signature": "async function commitFiles(configure?: unknown): Promise", + "deprecated": false + }, { "name": "CorrelateMode", "kind": "typeAlias", @@ -17995,6 +18009,29 @@ "signature": "type CorrelateMode = marker | created-window", "deprecated": false }, + { + "name": "GhApiError", + "kind": "class", + "doc": "A GitHub REST call that did not succeed, carrying the status.\n\nThe status is the point. One caller here recovers from a missing ref, and\ndoing that on a bare `catch` would swallow an expired token or a missing\npermission and retry them as though the ref simply did not exist — turning an\nauthorisation failure into a confusing one about creating a tag.", + "signature": "class GhApiError extends Error", + "deprecated": false, + "members": [ + { + "name": "name", + "kind": "property", + "optional": false, + "signature": "name: string", + "doc": "The error name." + }, + { + "name": "status", + "kind": "property", + "optional": false, + "signature": "status: number", + "doc": "The HTTP status of the failing response." + } + ] + }, { "name": "GhAppTokenApi", "kind": "interface", @@ -18183,6 +18220,187 @@ } ] }, + { + "name": "GhCommitApi", + "kind": "interface", + "doc": "The commit and tag operations {@link GhTasks} exposes.", + "signature": "interface GhCommitApi", + "deprecated": false, + "members": [ + { + "name": "commit", + "kind": "method", + "optional": false, + "signature": "commit(configure?: unknown): Promise", + "doc": "Commit files through the API, with no git credential on disk.\n\nCommits onto `.branch(...)`, or creates it from `.from(...)` when that is\nset. The ref update is not forced, so a commit landing between reading the\nhead and writing it is rejected rather than silently overwritten." + }, + { + "name": "tag", + "kind": "method", + "optional": false, + "signature": "tag(configure?: unknown): Promise", + "doc": "Point an annotated tag at a commit, creating or moving its ref." + } + ] + }, + { + "name": "GhCommitResult", + "kind": "interface", + "doc": "The commit a {@link GhTasksApi.commit} call created.", + "signature": "interface GhCommitResult", + "deprecated": false, + "members": [ + { + "name": "sha", + "kind": "property", + "optional": false, + "signature": "sha: string", + "doc": "The new commit's SHA." + }, + { + "name": "branch", + "kind": "property", + "optional": false, + "signature": "branch: string", + "doc": "The branch it landed on." + } + ] + }, + { + "name": "GhCommitSettings", + "kind": "class", + "doc": "Settings for committing files through the API.\n\n`owner/repo` and the token fall back to the Actions environment, so a job\nthat already has them needs to name only what it is committing.", + "signature": "class GhCommitSettings", + "deprecated": false, + "members": [ + { + "name": "file", + "kind": "method", + "optional": false, + "signature": "file(path: string, content: string): this", + "doc": "Add a file to the commit, replacing any earlier one at the same path." + }, + { + "name": "branch", + "kind": "method", + "optional": false, + "signature": "branch(name: string): this", + "doc": "The branch to commit onto. It must exist unless {@link from} is set." + }, + { + "name": "from", + "kind": "method", + "optional": false, + "signature": "from(base: string): this", + "doc": "Create {@link branch} from this one rather than committing onto an\nexisting branch. Creating a ref and moving one are different calls, and\nwhich is wanted is the caller's to say rather than something to infer." + }, + { + "name": "message", + "kind": "method", + "optional": false, + "signature": "message(text: string): this", + "doc": "The commit message." + }, + { + "name": "repo", + "kind": "method", + "optional": false, + "signature": "repo(slug: string): this", + "doc": "`owner/repo`. Defaults to `GITHUB_REPOSITORY`." + }, + { + "name": "token", + "kind": "method", + "optional": false, + "signature": "token(value: string): this", + "doc": "The token to authenticate with. Defaults to `GITHUB_TOKEN`." + }, + { + "name": "baseUrl", + "kind": "method", + "optional": false, + "signature": "baseUrl(url: string): this", + "doc": "The API root, for GitHub Enterprise." + }, + { + "name": "fetch", + "kind": "method", + "optional": false, + "signature": "fetch(fn: fetch): this", + "doc": "Override the `fetch` implementation (a test seam)." + }, + { + "name": "repoSlug_", + "kind": "method", + "optional": false, + "signature": "repoSlug_(): string", + "doc": "The effective `owner/repo`, from the setting or the environment." + }, + { + "name": "authToken_", + "kind": "method", + "optional": false, + "signature": "authToken_(): string", + "doc": "The effective token, from the setting or the environment." + }, + { + "name": "files_", + "kind": "property", + "optional": false, + "signature": "files_: Map", + "doc": "The files to write, by path." + }, + { + "name": "branch_", + "kind": "property", + "optional": true, + "signature": "branch_?: string", + "doc": "The branch to commit onto. Set by {@link branch}." + }, + { + "name": "from_", + "kind": "property", + "optional": true, + "signature": "from_?: string", + "doc": "The branch to create from, when creating one. Set by {@link from}." + }, + { + "name": "message_", + "kind": "property", + "optional": true, + "signature": "message_?: string", + "doc": "The commit message. Set by {@link message}." + }, + { + "name": "repo_", + "kind": "property", + "optional": true, + "signature": "repo_?: string", + "doc": "`owner/repo`. Set by {@link repo}." + }, + { + "name": "token_", + "kind": "property", + "optional": true, + "signature": "token_?: string", + "doc": "The token. Set by {@link token}." + }, + { + "name": "baseUrl_", + "kind": "property", + "optional": false, + "signature": "baseUrl_: string", + "doc": "The API root. Set by {@link baseUrl}." + }, + { + "name": "fetch_", + "kind": "property", + "optional": false, + "signature": "fetch_: fetch", + "doc": "The `fetch` implementation. Set by {@link fetch}." + } + ] + }, { "name": "GhPermissionLevel", "kind": "typeAlias", @@ -18380,6 +18598,141 @@ } ] }, + { + "name": "GhTagSettings", + "kind": "class", + "doc": "Settings for pointing a tag at a commit.", + "signature": "class GhTagSettings", + "deprecated": false, + "members": [ + { + "name": "name", + "kind": "method", + "optional": false, + "signature": "name(value: string): this", + "doc": "The tag name, e.g. `v1.2.3`." + }, + { + "name": "commit", + "kind": "method", + "optional": false, + "signature": "commit(sha: string): this", + "doc": "The commit SHA to tag. Defaults to `GITHUB_SHA`." + }, + { + "name": "message", + "kind": "method", + "optional": false, + "signature": "message(text: string): this", + "doc": "The annotation message. Defaults to the tag name." + }, + { + "name": "move", + "kind": "method", + "optional": false, + "signature": "move(): this", + "doc": "Move the tag if it already exists, rather than failing.\n\nForced by necessity: pointing a major tag at a newer release is a\nnon-fast-forward by definition. A tag that does not exist yet is created,\nsince for the first release of a major those are the same intent." + }, + { + "name": "repo", + "kind": "method", + "optional": false, + "signature": "repo(slug: string): this", + "doc": "`owner/repo`. Defaults to `GITHUB_REPOSITORY`." + }, + { + "name": "token", + "kind": "method", + "optional": false, + "signature": "token(value: string): this", + "doc": "The token to authenticate with. Defaults to `GITHUB_TOKEN`." + }, + { + "name": "baseUrl", + "kind": "method", + "optional": false, + "signature": "baseUrl(url: string): this", + "doc": "The API root, for GitHub Enterprise." + }, + { + "name": "fetch", + "kind": "method", + "optional": false, + "signature": "fetch(fn: fetch): this", + "doc": "Override the `fetch` implementation (a test seam)." + }, + { + "name": "repoSlug_", + "kind": "method", + "optional": false, + "signature": "repoSlug_(): string", + "doc": "The effective `owner/repo`, from the setting or the environment." + }, + { + "name": "authToken_", + "kind": "method", + "optional": false, + "signature": "authToken_(): string", + "doc": "The effective token, from the setting or the environment." + }, + { + "name": "name_", + "kind": "property", + "optional": true, + "signature": "name_?: string", + "doc": "The tag name. Set by {@link name}." + }, + { + "name": "commit_", + "kind": "property", + "optional": true, + "signature": "commit_?: string", + "doc": "The commit the tag points at. Set by {@link commit}." + }, + { + "name": "message_", + "kind": "property", + "optional": true, + "signature": "message_?: string", + "doc": "The annotation message. Set by {@link message}." + }, + { + "name": "move_", + "kind": "property", + "optional": false, + "signature": "move_: boolean", + "doc": "Whether to move an existing tag. Set by {@link move}." + }, + { + "name": "repo_", + "kind": "property", + "optional": true, + "signature": "repo_?: string", + "doc": "`owner/repo`. Set by {@link repo}." + }, + { + "name": "token_", + "kind": "property", + "optional": true, + "signature": "token_?: string", + "doc": "The token. Set by {@link token}." + }, + { + "name": "baseUrl_", + "kind": "property", + "optional": false, + "signature": "baseUrl_: string", + "doc": "The API root. Set by {@link baseUrl}." + }, + { + "name": "fetch_", + "kind": "property", + "optional": false, + "signature": "fetch_: fetch", + "doc": "The `fetch` implementation. Set by {@link fetch}." + } + ] + }, { "name": "GhTasks", "kind": "variable", @@ -18552,6 +18905,13 @@ "signature": "function readWorkflowResult(state: TargetStateHandle): WorkflowResult | undefined", "deprecated": false }, + { + "name": "tagCommit", + "kind": "function", + "doc": "Perform the configured tag.", + "signature": "async function tagCommit(configure?: unknown): Promise", + "deprecated": false + }, { "name": "uploadSarifReport", "kind": "function",