@async/github-app 0.1.1

package/API_SURFACE.md

@@ -0,0 +1,37 @@
+# @async/github-app API Surface Ledger
+
+This file is the generated review ledger for semantic API contract features. It is current-state contract documentation, not a changelog or tutorial.
+
+## Async GitHub App Package Exports
+
+Contract: `@async/github-app.package`
+
+### Exports
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `export.actions` | @async/github-app/actions exports GitHub Actions bridge workflow rendering and pull-based apply helpers | public | preview | active |  | [docs](https://github.com/async/github-app/blob/main/README.md) |
+| `export.content` | @async/github-app/content exports JSON, JSONC, Markdown, MDX, and generic content mapping helpers | public | preview | active |  | [docs](https://github.com/async/github-app/blob/main/README.md) |
+| `export.root` | @async/github-app exports auth providers, GitHub client operations, app metadata, change-set types, receipts, and safety helpers | public | preview | active |  | [docs](https://github.com/async/github-app/blob/main/README.md) |
+| `export.server` | @async/github-app/server exports Fetch-compatible webhook verification and routing handlers | public | preview | active |  | [docs](https://github.com/async/github-app/blob/main/README.md) |
+
+## Async GitHub Integration Runtime
+
+Contract: `@async/github-app.runtime`
+
+### Runtime
+
+| Feature | Title | Release | Stability | Lifecycle | Replacement | Docs |
+| --- | --- | --- | --- | --- | --- | --- |
+| `runtime.actions-bridge` | Actions bridge mode renders workflow YAML and pulls approved change sets with repo-local GITHUB_TOKEN receipts, lease ids, branch-prefix checks, and allowed-path checks | public | preview | active |  | [docs](https://github.com/async/github-app/blob/main/README.md) |
+| `runtime.auth` | Auth providers support GitHub App installation tokens, user tokens, static tokens, and Actions GITHUB_TOKEN fallback | public | preview | active |  | [docs](https://github.com/async/github-app/blob/main/README.md) |
+| `runtime.change-set` | Change sets validate safe paths and commit upserts or deletes serially with branch, commit, PR, and index receipt metadata | public | preview | active |  | [docs](https://github.com/async/github-app/blob/main/README.md) |
+| `runtime.content` | Content helpers map records to JSON, JSONC read-only-by-default, Markdown, and MDX file formats without schema ownership | public | preview | active |  | [docs](https://github.com/async/github-app/blob/main/README.md) |
+| `runtime.webhook` | Webhook handlers verify SHA-256 signatures before JSON routing and treat duplicate delivery ids idempotently | public | preview | active |  | [docs](https://github.com/async/github-app/blob/main/README.md) |
+
+## Supported Surfaces
+
+| Contract | Hash | Features |
+| --- | --- | --- |
+| `@async/github-app.package` | `sha256:9417af3e2ab66056111e0963fb92c2142a0ddba2fd53de1fb981a78af43ddf42` | `export.actions`, `export.content`, `export.root`, `export.server` |
+| `@async/github-app.runtime` | `sha256:f21bef8556025acf31d8cfe0e22e12beefe9c7a8f50b06bd59a39c651d8cacdc` | `runtime.actions-bridge`, `runtime.auth`, `runtime.change-set`, `runtime.content`, `runtime.webhook` |

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.1 - 2026-06-18
+
+- Add branch-prefix, allowed-path, and pull-request controls to the Actions bridge renderer and pull command so generated workflows can scope repo writes without changing backend APIs.
+- Skip change sets whose metadata excludes the Actions worker, reject bridge pulls when the queued target branch is outside the configured prefix, and echo backend lease ids in bridge receipts.
+
+## 0.1.0 - 2026-06-17
+
+- Initial GitHub integration package for Async.
+- Adds GitHub App, token, and Actions bridge auth providers.
+- Adds branch, file commit, pull request, tree snapshot, compare, webhook, receipt, and content mapping helpers.
+- Adds JSON, JSONC read-only by default, Markdown, and MDX content serializers.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Async
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,228 @@
+# @async/github-app
+
+Reusable GitHub integration layer for Async packages.
+
+It supports two operating modes:
+
+- **GitHub App mode** for the normal SaaS path. Use the Async-owned app metadata by default, or pass a consumer-owned app definition with `defineGithubApp`.
+- **GitHub Actions bridge mode** for organizations that cannot approve a GitHub App installation. The repo installs a generated workflow and uses its own `GITHUB_TOKEN`.
+
+The package is content-format agnostic. JSON, JSONC read/index support, Markdown, and MDX use the same branch, commit, pull request, webhook, and receipt machinery.
+
+## Install
+
+```bash
+pnpm add @async/github-app
+```
+
+Requires Node.js 24 or newer.
+
+## Package Exports
+
+```ts
+import {
+  asyncGithubApp,
+  createGitHubClient,
+  defineGithubApp,
+  githubAppAuth
+} from "@async/github-app";
+
+import { createGithubWebhookHandler } from "@async/github-app/server";
+import { renderActionsBridgeWorkflow } from "@async/github-app/actions";
+import { contentMapping, renderJsonContent } from "@async/github-app/content";
+```
+
+## GitHub App Mode
+
+The Async-owned app metadata is exported for product wiring:
+
+```ts
+import { asyncGithubApp } from "@async/github-app";
+
+console.log(asyncGithubApp.installUrl);
+```
+
+Use installation auth at runtime:
+
+```ts
+import { createGitHubClient, githubAppAuth } from "@async/github-app";
+
+const auth = githubAppAuth({
+  appId: process.env.GITHUB_APP_ID,
+  privateKey: process.env.GITHUB_APP_PRIVATE_KEY,
+  installationId: process.env.GITHUB_INSTALLATION_ID
+});
+
+const github = createGitHubClient(auth);
+
+await github.ensureBranch({
+  repo: "acme/site",
+  from: "main",
+  branch: "async/update-homepage"
+});
+
+const receipt = await github.commitChangeSet({
+  repo: "acme/site",
+  branch: "async/update-homepage",
+  baseBranch: "main",
+  message: "Update homepage content",
+  files: [
+    {
+      path: "content/settings.json",
+      action: "upsert",
+      content: renderJsonContent({ title: "Hello" })
+    }
+  ],
+  allowedPathGlobs: ["content/**"]
+});
+```
+
+Do not commit private keys, webhook secrets, installation tokens, PATs, or customer tokens. This package never ships Async-owned credentials.
+
+Consumers can bring their own app definition:
+
+```ts
+import { defineGithubApp } from "@async/github-app";
+
+export const customerApp = defineGithubApp({
+  metadata: {
+    slug: "acme-content-app",
+    installUrl: "https://github.com/apps/acme-content-app/installations/new",
+    callbackUrl: "https://acme.example/github/callback"
+  },
+  permissions: {
+    contents: "write",
+    metadata: "read",
+    pull_requests: "write"
+  }
+});
+```
+
+## Webhooks
+
+`@async/github-app/server` exports Fetch-compatible handlers that work in Workers-style runtimes and can be adapted to Node HTTP.
+
+```ts
+import { createGithubWebhookHandler } from "@async/github-app/server";
+
+export default {
+  fetch: createGithubWebhookHandler({
+    verify: { secret: process.env.GITHUB_WEBHOOK_SECRET },
+    route: {
+      push: async (event) => {
+        await queueReindex(event.payload);
+      },
+      pull_request: async (event) => {
+        await queueReindex(event.payload);
+      }
+    }
+  })
+};
+```
+
+The handler verifies `X-Hub-Signature-256` before parsing trusted JSON, limits body size, and treats duplicate GitHub delivery IDs as idempotent.
+
+## GitHub Actions Bridge Mode
+
+For organizations that cannot approve a GitHub App install, render a repo-local workflow:
+
+```ts
+import { renderActionsBridgeWorkflow } from "@async/github-app/actions";
+
+const yaml = renderActionsBridgeWorkflow({
+  asyncEndpoint: "${{ vars.ASYNC_PROJECT_URL }}",
+  branchPrefix: "async/bridge/",
+  allowedPathGlobs: ["pipeline.ts", "package.json", "docs/**"]
+});
+```
+
+Prefer `@async/pipeline` generated workflows for new repos so workflow triggers,
+permissions, action pins, locks, and secret routing stay centrally managed. The
+standalone renderer remains available for compatibility.
+
+The generated workflow:
+
+- supports `workflow_dispatch`
+- runs on a documented five-minute schedule by default
+- requests `contents: write` and `pull-requests: write`
+- uses `ASYNC_PROJECT_TOKEN` plus repo-local `GITHUB_TOKEN`
+- pulls approved change sets from Async
+- enforces configured branch-prefix and allowed-path constraints
+- commits branches and optionally opens PRs
+- posts lease-aware receipts back to Async
+
+Repo setting required for PR creation: enable “Allow GitHub Actions to create and approve pull requests”. If that is unavailable, Async can use branch-only mode and let a human open the PR.
+
+External dispatch is optional. Async can trigger `workflow_dispatch` only when the customer provides a token with Actions write permission. Without that token, schedule or manual run is the fallback.
+
+## Content Helpers
+
+JSON writes are canonical and stable:
+
+```ts
+import { renderJsonContent } from "@async/github-app/content";
+
+const content = renderJsonContent({ enabled: true });
+```
+
+JSONC is readable by default, but writes are opt-in because comments and formatting cannot be preserved safely:
+
+```ts
+import { parseJsoncContent } from "@async/github-app/content";
+
+const value = parseJsoncContent(`{
+  // allowed on read
+  "enabled": true,
+}`);
+```
+
+Markdown and MDX helpers preserve body text and use frontmatter for record fields:
+
+```ts
+import { parseMarkdownRecord, renderMarkdownRecord } from "@async/github-app/content";
+
+const record = parseMarkdownRecord("---\ntitle: \"Hello\"\n---\nBody text\n");
+const file = renderMarkdownRecord(record);
+```
+
+Generic mappings let future `@async/db` integration point resources at files without hard-coding formats into GitHub auth:
+
+```ts
+import { contentMapping } from "@async/github-app/content";
+
+const posts = contentMapping({
+  resource: "posts",
+  pattern: "content/posts/{id}.json",
+  format: "json"
+});
+
+const path = posts.pathFromRecord({ id: "hello", title: "Hello" });
+```
+
+## Safety Defaults
+
+Change-set paths are rejected when they are absolute, include `..`, include empty segments, duplicate another file in the same change set, or write `.github/workflows/**` without `allowWorkflowPaths`.
+
+Use `allowedPathGlobs` to constrain writes:
+
+```ts
+await github.commitChangeSet({
+  repo: "acme/site",
+  branch: "async/content",
+  message: "Update content",
+  files,
+  allowedPathGlobs: ["content/**", "docs/**"]
+});
+```
+
+Receipts include commit SHAs, branch names, PR URLs, file paths, and index hints. They do not include file contents.
+
+## Verification
+
+```bash
+pnpm install
+pnpm run release:check
+npm pack --dry-run
+```
+
+CI is generated from `pipeline.ts` by `@async/pipeline`; workflow YAML should not be hand-edited.

package/api-contract.json

@@ -0,0 +1,115 @@
+{
+  "format": "api-contract.package.v1",
+  "packageName": "@async/github-app",
+  "catalogs": [
+    {
+      "format": "api-contract.catalog.v1",
+      "contractId": "@async/github-app.package",
+      "title": "Async GitHub App Package Exports",
+      "features": [
+        {
+          "id": "export.root",
+          "title": "@async/github-app exports auth providers, GitHub client operations, app metadata, change-set types, receipts, and safety helpers",
+          "releaseTag": "public",
+          "stability": "preview",
+          "group": "exports",
+          "docsUrl": "https://github.com/async/github-app/blob/main/README.md"
+        },
+        {
+          "id": "export.server",
+          "title": "@async/github-app/server exports Fetch-compatible webhook verification and routing handlers",
+          "releaseTag": "public",
+          "stability": "preview",
+          "group": "exports",
+          "docsUrl": "https://github.com/async/github-app/blob/main/README.md"
+        },
+        {
+          "id": "export.actions",
+          "title": "@async/github-app/actions exports GitHub Actions bridge workflow rendering and pull-based apply helpers",
+          "releaseTag": "public",
+          "stability": "preview",
+          "group": "exports",
+          "docsUrl": "https://github.com/async/github-app/blob/main/README.md"
+        },
+        {
+          "id": "export.content",
+          "title": "@async/github-app/content exports JSON, JSONC, Markdown, MDX, and generic content mapping helpers",
+          "releaseTag": "public",
+          "stability": "preview",
+          "group": "exports",
+          "docsUrl": "https://github.com/async/github-app/blob/main/README.md"
+        }
+      ]
+    },
+    {
+      "format": "api-contract.catalog.v1",
+      "contractId": "@async/github-app.runtime",
+      "title": "Async GitHub Integration Runtime",
+      "features": [
+        {
+          "id": "runtime.auth",
+          "title": "Auth providers support GitHub App installation tokens, user tokens, static tokens, and Actions GITHUB_TOKEN fallback",
+          "releaseTag": "public",
+          "stability": "preview",
+          "group": "runtime",
+          "docsUrl": "https://github.com/async/github-app/blob/main/README.md"
+        },
+        {
+          "id": "runtime.change-set",
+          "title": "Change sets validate safe paths and commit upserts or deletes serially with branch, commit, PR, and index receipt metadata",
+          "releaseTag": "public",
+          "stability": "preview",
+          "group": "runtime",
+          "docsUrl": "https://github.com/async/github-app/blob/main/README.md"
+        },
+        {
+          "id": "runtime.webhook",
+          "title": "Webhook handlers verify SHA-256 signatures before JSON routing and treat duplicate delivery ids idempotently",
+          "releaseTag": "public",
+          "stability": "preview",
+          "group": "runtime",
+          "docsUrl": "https://github.com/async/github-app/blob/main/README.md"
+        },
+        {
+          "id": "runtime.actions-bridge",
+          "title": "Actions bridge mode renders workflow YAML and pulls approved change sets with repo-local GITHUB_TOKEN receipts, lease ids, branch-prefix checks, and allowed-path checks",
+          "releaseTag": "public",
+          "stability": "preview",
+          "group": "runtime",
+          "docsUrl": "https://github.com/async/github-app/blob/main/README.md"
+        },
+        {
+          "id": "runtime.content",
+          "title": "Content helpers map records to JSON, JSONC read-only-by-default, Markdown, and MDX file formats without schema ownership",
+          "releaseTag": "public",
+          "stability": "preview",
+          "group": "runtime",
+          "docsUrl": "https://github.com/async/github-app/blob/main/README.md"
+        }
+      ]
+    }
+  ],
+  "supported": [
+    {
+      "format": "api-contract.surface.v1",
+      "contractId": "@async/github-app.package",
+      "features": [
+        "export.root",
+        "export.server",
+        "export.actions",
+        "export.content"
+      ]
+    },
+    {
+      "format": "api-contract.surface.v1",
+      "contractId": "@async/github-app.runtime",
+      "features": [
+        "runtime.auth",
+        "runtime.actions-bridge",
+        "runtime.change-set",
+        "runtime.content",
+        "runtime.webhook"
+      ]
+    }
+  ]
+}

package/dist/actions.d.ts

@@ -0,0 +1,49 @@
+import type { ChangeSet, CommitReceipt, GitHubAuthProvider } from "./types.js";
+export interface RenderActionsBridgeWorkflowOptions {
+    readonly name?: string;
+    readonly asyncEndpoint?: string;
+    readonly packageVersion?: string;
+    readonly schedule?: string;
+    readonly includePushTrigger?: boolean;
+    readonly nodeVersion?: string | number;
+    readonly pnpmVersion?: string;
+    readonly branchPrefix?: string;
+    readonly allowedPathGlobs?: readonly string[];
+    readonly pullRequest?: boolean;
+}
+export interface PendingChangeSetsResponse {
+    readonly changeSets: readonly ChangeSet[];
+    readonly leases?: readonly ActionsBridgeLease[];
+}
+export interface ActionsBridgeLease {
+    readonly changeSetId: string;
+    readonly repo: string;
+    readonly worker: "actions" | "app";
+    readonly leaseId: string;
+    readonly leaseExpiresAt?: string;
+}
+export interface ApplyActionsBridgeOptions {
+    readonly endpoint: string;
+    readonly projectToken: string;
+    readonly repository: string;
+    readonly auth?: GitHubAuthProvider;
+    readonly fetch?: typeof fetch;
+    readonly requireApproved?: boolean;
+    readonly branchPrefix?: string;
+    readonly allowedPathGlobs?: readonly string[];
+    readonly pullRequest?: boolean;
+}
+export interface ApplyActionsBridgeResult {
+    readonly receipts: readonly ActionsBridgeReceipt[];
+    readonly skipped: number;
+}
+export interface ActionsBridgeReceipt extends CommitReceipt {
+    readonly changeSetId: string;
+    readonly leaseId?: string;
+    readonly leaseExpiresAt?: string;
+    readonly worker: "actions";
+    readonly status: "applied";
+}
+export declare function renderActionsBridgeWorkflow(options?: RenderActionsBridgeWorkflowOptions): string;
+export declare function applyActionsBridge(options: ApplyActionsBridgeOptions): Promise<ApplyActionsBridgeResult>;
+//# sourceMappingURL=actions.d.ts.map

package/dist/actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"actions.d.ts","sourceRoot":"","sources":["../src/actions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,kBAAkB,EAAmB,MAAM,YAAY,CAAC;AAGhG,MAAM,WAAW,kCAAkC;IACjD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;IAC1C,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CACjD;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,SAAS,GAAG,KAAK,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,CAAC,EAAE,kBAAkB,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;IAC9B,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9C,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,QAAQ,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;CAC5B;AAED,wBAAgB,2BAA2B,CAAC,OAAO,GAAE,kCAAuC,GAAG,MAAM,CA6CpG;AAED,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAuE9G"}

package/dist/actions.js

@@ -0,0 +1,190 @@
+import { actionsBridgeAuth } from "./auth.js";
+import { createGitHubClient } from "./github.js";
+import { redactSensitive } from "./util.js";
+export function renderActionsBridgeWorkflow(options = {}) {
+    const name = options.name ?? "Async GitHub Bridge";
+    const asyncEndpoint = options.asyncEndpoint ?? "${{ vars.ASYNC_PROJECT_URL }}";
+    const packageVersion = options.packageVersion ?? "latest";
+    const schedule = options.schedule ?? "*/5 * * * *";
+    const nodeVersion = String(options.nodeVersion ?? 24);
+    const pnpmVersion = options.pnpmVersion ?? "10.20.0";
+    const pushTrigger = options.includePushTrigger ? "\n  push:\n    branches:\n      - main\n" : "";
+    const pullArgs = renderActionsPullArgs({
+        branchPrefix: options.branchPrefix,
+        allowedPathGlobs: options.allowedPathGlobs,
+        pullRequest: options.pullRequest
+    });
+    return `name: ${name}
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "${schedule}"${pushTrigger}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  bridge:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: ${pnpmVersion}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${nodeVersion}
+          cache: pnpm
+      - name: Pull and apply Async change sets
+        run: pnpm dlx @async/github-app@${packageVersion} actions pull${pullArgs}
+        env:
+          ASYNC_PROJECT_URL: ${asyncEndpoint}
+          ASYNC_PROJECT_TOKEN: \${{ secrets.ASYNC_PROJECT_TOKEN }}
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+          GITHUB_REPOSITORY: \${{ github.repository }}
+`;
+}
+export async function applyActionsBridge(options) {
+    const apiFetch = options.fetch ?? fetch;
+    const auth = options.auth ?? actionsBridgeAuth();
+    const client = createGitHubClient(auth);
+    const pending = await requestJson(apiFetch, `${trimSlash(options.endpoint)}/github/actions-bridge/change-sets?repo=${encodeURIComponent(options.repository)}`, {
+        method: "GET",
+        token: options.projectToken
+    });
+    const leases = indexLeases(pending.leases);
+    const receipts = [];
+    let skipped = 0;
+    for (const changeSet of pending.changeSets) {
+        if ((options.requireApproved ?? true) && changeSet.metadata?.approved !== true) {
+            skipped += 1;
+            continue;
+        }
+        if (!isAllowedActionsWorker(changeSet.metadata)) {
+            skipped += 1;
+            continue;
+        }
+        const lease = leases.get(changeSet.id) ?? leaseFromMetadata(changeSet);
+        if (lease && lease.worker !== "actions") {
+            skipped += 1;
+            continue;
+        }
+        if (lease && lease.repo !== formatRepoInput(changeSet.repo)) {
+            throw new Error(`Actions bridge rejected change set ${changeSet.id}: lease repo ${lease.repo} does not match change set repo ${formatRepoInput(changeSet.repo)}.`);
+        }
+        if (options.branchPrefix && !changeSet.targetBranch.startsWith(options.branchPrefix)) {
+            throw new Error(`Actions bridge rejected change set ${changeSet.id}: target branch must start with ${options.branchPrefix}.`);
+        }
+        const receipt = toActionsBridgeReceipt(await client.commitChangeSet({
+            repo: changeSet.repo,
+            branch: changeSet.targetBranch,
+            baseBranch: changeSet.baseBranch,
+            changeSetId: changeSet.id,
+            message: changeSet.message ?? `Apply Async change set ${changeSet.id}`,
+            files: changeSet.files,
+            allowedPathGlobs: options.allowedPathGlobs,
+            metadata: changeSet.metadata
+        }), changeSet, lease);
+        receipts.push(receipt);
+        if (options.pullRequest !== false && (changeSet.mode === "pull_request" || changeSet.mode === "actions-pull")) {
+            const pr = await client.openOrUpdatePullRequest({
+                repo: changeSet.repo,
+                head: changeSet.targetBranch,
+                base: changeSet.baseBranch,
+                title: changeSet.title ?? `Apply Async change set ${changeSet.id}`,
+                body: changeSet.body ?? "Created by the Async GitHub Actions bridge."
+            });
+            receipts[receipts.length - 1] = {
+                ...receipt,
+                pullRequestUrl: pr.url
+            };
+        }
+    }
+    await requestJson(apiFetch, `${trimSlash(options.endpoint)}/github/actions-bridge/receipts`, {
+        method: "POST",
+        token: options.projectToken,
+        body: {
+            repository: options.repository,
+            receipts,
+            skipped
+        }
+    });
+    return { receipts, skipped };
+}
+function toActionsBridgeReceipt(receipt, changeSet, lease) {
+    return {
+        ...receipt,
+        changeSetId: changeSet.id,
+        ...(lease ? { leaseId: lease.leaseId } : {}),
+        ...(lease?.leaseExpiresAt ? { leaseExpiresAt: lease.leaseExpiresAt } : {}),
+        worker: "actions",
+        status: "applied"
+    };
+}
+function indexLeases(leases) {
+    const indexed = new Map();
+    for (const lease of leases ?? []) {
+        indexed.set(lease.changeSetId, lease);
+    }
+    return indexed;
+}
+function leaseFromMetadata(changeSet) {
+    const leaseId = changeSet.metadata?.leaseId;
+    if (typeof leaseId !== "string" || !leaseId)
+        return undefined;
+    const worker = changeSet.metadata?.worker === "app" ? "app" : "actions";
+    const leaseExpiresAt = typeof changeSet.metadata.leaseExpiresAt === "string" ? changeSet.metadata.leaseExpiresAt : undefined;
+    return {
+        changeSetId: changeSet.id,
+        repo: formatRepoInput(changeSet.repo),
+        worker,
+        leaseId,
+        ...(leaseExpiresAt ? { leaseExpiresAt } : {})
+    };
+}
+function formatRepoInput(repo) {
+    return typeof repo === "string" ? repo : `${repo.owner}/${repo.repo}`;
+}
+function renderActionsPullArgs(options) {
+    const args = [];
+    if (options.branchPrefix)
+        args.push("--branch-prefix", options.branchPrefix);
+    if (options.pullRequest !== undefined)
+        args.push("--pull-request", String(options.pullRequest));
+    for (const glob of options.allowedPathGlobs ?? []) {
+        args.push("--allowed-path", glob);
+    }
+    return args.length > 0 ? ` ${args.map(shellWord).join(" ")}` : "";
+}
+function isAllowedActionsWorker(metadata) {
+    const allowedWorkers = metadata?.allowedWorkers;
+    if (!Array.isArray(allowedWorkers))
+        return true;
+    return allowedWorkers.includes("actions");
+}
+async function requestJson(apiFetch, url, options) {
+    const init = {
+        method: options.method,
+        headers: {
+            accept: "application/json",
+            authorization: `Bearer ${options.token}`,
+            "content-type": "application/json"
+        }
+    };
+    if (options.body !== undefined) {
+        init.body = JSON.stringify(options.body);
+    }
+    const response = await apiFetch(url, init);
+    if (!response.ok) {
+        throw new Error(`Async Actions bridge request failed with ${response.status}: ${redactSensitive(await response.text())}`);
+    }
+    return await response.json();
+}
+function trimSlash(value) {
+    return value.replace(/\/+$/u, "");
+}
+function shellWord(value) {
+    return /^[A-Za-z0-9_./:@*-]+$/u.test(value) ? value : JSON.stringify(value);
+}

package/dist/app.d.ts

@@ -0,0 +1,4 @@
+import type { AsyncGithubAppMetadata, DefineGithubAppOptions, GithubAppDefinition } from "./types.js";
+export declare const asyncGithubApp: AsyncGithubAppMetadata;
+export declare function defineGithubApp(options?: DefineGithubAppOptions): GithubAppDefinition;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAEtG,eAAO,MAAM,cAAc,EAAE,sBAiB5B,CAAC;AAEF,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,mBAAmB,CAwBzF"}