@sentry/junior-github 0.81.0 → 0.83.0

package/SETUP.md

@@ -135,9 +135,9 @@ Committing and pushing code uses more than one GitHub surface:
 - Creating the local Git commit does not call GitHub. Junior sets the requester as author and the GitHub App bot as committer in the sandbox.
 - Pushing a branch with Git smart HTTP (`git push`) uses the `user-write` grant and requires the GitHub App to have `Contents: write` on the target repository. The requesting user must also have write access to that repository.
 - REST Git database writes used by some `gh` flows also require `Contents: write`: create blob (`POST /git/blobs`), create tree (`POST /git/trees`), create commit (`POST /git/commits`), and create/update refs (`POST /git/refs`, `PATCH /git/refs/{ref}`). Changes to workflow files may also require `Workflows: write`.
-- Opening the PR after the branch exists is separate: `gh pr create --head` needs pull-request write permission, but it should not create or push commits itself.
+- Opening the PR after the branch exists is separate: `github_createPullRequest` needs pull-request write permission, but it should not create or push commits itself.
 
-Fork creation is not part of the default PR path. `POST /repos/{owner}/{repo}/forks` uses the `user-write` grant, but GitHub requires `Administration: write` and `Contents: read`, and the app must be installed on both the source and destination accounts. Do not grant `Administration: write` for routine PR creation; push a branch explicitly and create the PR with `--head` instead.
+Fork creation is not part of the default PR path. `POST /repos/{owner}/{repo}/forks` uses the `user-write` grant, but GitHub requires `Administration: write` and `Contents: read`, and the app must be installed on both the source and destination accounts. Do not grant `Administration: write` for routine PR creation; push a branch explicitly and create the PR with `github_createPullRequest` instead.
 
 GitHub App permission scoping is a safety rail, not a hard sandbox boundary. It helps prevent accidental write scope and wrong-repo mutations, and the host runtime still decides when to mint credentials. Credential injection is provider-domain scoped for sandbox traffic to `api.github.com` and `github.com` during turns with a signed credential context. Keep repo context explicit, and let the plugin choose the required grant for the outbound request.
 
@@ -149,11 +149,21 @@ Be careful with mixed-surface PR commands:
 - `gh pr close --comment` may need `github.issues.write`.
 - `gh pr close --delete-branch` needs `github.contents.write`.
 
-For PR creation in automation, push explicitly and use `--head`:
+For PR creation in automation, push explicitly and pass that branch as `head`:
 
 ```bash
 git -C repo push -u origin BRANCH
-gh pr create --repo owner/repo --head BRANCH --base main --title "Example PR" --body-file /vercel/sandbox/tmp/pr.md
+```
+
+```ts
+github_createPullRequest({
+  repo: "owner/repo",
+  head: "BRANCH",
+  base: "main",
+  title: "Example PR",
+  body: "Example body",
+  draft: true,
+});
 ```
 
 Optional: set a default repository once per channel/thread context so `--repo` is not needed each turn:
@@ -167,7 +177,7 @@ jr-rpc config set github.repo getsentry/junior
 - `pnpm skills:check`
 - Create issue in a test repo.
 - Update/comment/label the same issue.
-- Push a test branch and create a draft PR with `--head`.
+- Push a test branch and create a draft PR with `github_createPullRequest`.
 - Use read-only commands (`gh issue view`, `gh api .../comments`, `gh pr view`) for issue inspection.
 
 ## 6) Production verification (step-by-step)

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { type PluginRegistration } from "@sentry/junior-plugin-api";
+import { type GitHubAppPermissions } from "./permissions.js";
+export type { GitHubAppPermissionLevel } from "./permissions.js";
+/** Configure the built-in GitHub plugin manifest and hooks. */
+export interface GitHubPluginOptions {
+    /**
+     * Extra OAuth `scope` values to request during GitHub App user authorization.
+     *
+     * GitHub App user tokens report empty scopes, so Junior treats this as a
+     * local reauthorization contract only. Effective access still comes from the
+     * app permissions, installation repositories, and requesting user's access.
+     */
+    additionalUserScopes?: string[];
+    /**
+     * GitHub App installation permissions Junior should request for app tokens.
+     *
+     * Keys may use GitHub permission names with underscores or hyphens. Junior
+     * records these as plugin capabilities and requests read-only installation
+     * tokens by scoping read-capable permissions down to `read`.
+     * GitHub remains the source of truth for whether a permission exists.
+     */
+    appPermissions?: GitHubAppPermissions;
+    /** Environment variable containing the GitHub App id. */
+    appIdEnv?: string;
+    /** Environment variable containing Junior's Git committer email. */
+    botEmailEnv?: string;
+    /** Environment variable containing Junior's Git committer name. */
+    botNameEnv?: string;
+    /** Environment variable containing the GitHub App OAuth client id. */
+    clientIdEnv?: string;
+    /** Environment variable containing the GitHub App OAuth client secret. */
+    clientSecretEnv?: string;
+    /** Environment variable containing the GitHub App installation id. */
+    installationIdEnv?: string;
+    /** Environment variable containing the GitHub App private key. */
+    privateKeyEnv?: string;
+}
+/** Register GitHub runtime hooks for repository workflows. */
+export declare function githubPlugin(options?: GitHubPluginOptions): PluginRegistration;