@vibes.diy/prompts 14.3.166 → 14.3.167

package/llms/backend.md

@@ -183,7 +183,10 @@ const routes = await ctx.github.routes(); // [{ repo, accountLogin, binderHandle
   a path outside `/repos/…` + `/installation/repositories`, or one naming a repo
   this vibe is not bound to,
   `unsupported_method`, `streaming_unsupported`, `body_too_large`,
-  `permission_not_granted` — the installation lacks that permission, or
+  `permission_not_declared` — `config.github.permissions` leaves out the
+  permission this call needs, `permission_not_consented` — declared, but the
+  person who connected the repo agreed before it was (they press Connect
+  again), `permission_not_granted` — the installation lacks that permission, or
   `upstream_error`); branch on `err.reason`, and tell the user which one it was.
 
 - **Connecting a repository is a link, not a call.** The page links to the

package/llms/github.md

@@ -31,13 +31,15 @@ the GitHub App carries the repos. An app can use both side by side.
 ### 1. Declare it — `backend.js`
 
 **`backend.js` declares `config.github` with `bind` and a `why` sentence** the
-visitor reads on the platform's consent page before GitHub opens:
+visitor reads on the platform's consent page before GitHub opens, and the
+`permissions` the app uses in each connected repo:
 
 ```js
 export const config = {
   github: {
     bind: "anyone",
     why: "Leaves a short note on each new pull request in the repos you pick.",
+    permissions: ["pull_requests:write"],
   },
 };
 ```
@@ -52,6 +54,38 @@ export const config = {
   remix that opens up to visitors already says what it does.
 - A malformed `config.github` refuses the push, with a message naming the field.
 
+**`config.github.permissions` lists every GitHub permission the app's `ctx.github.fetch` calls use**
+— and only those. The platform lets each call through when its permission is
+declared, and the consent page lists the declaration in plain words, so the
+person sees exactly what the app does in their repos. The names are GitHub's
+own, and `:write` includes `:read`:
+
+| Permission | The consent page says the app can | Calls it covers |
+| --- | --- | --- |
+| `contents:read` | read its code | `/contents`, `/readme`, `/git`, `/commits`, `/compare`, `/branches`, `/tags`, `/releases` (GET) |
+| `contents:write` | read and change its code | the same paths, writing; merging a pull request |
+| `pull_requests:read` | read its pull requests | `/pulls`, `/pulls/{n}`, `/pulls/{n}/files`, `/reviews`, `/comments` (GET) |
+| `pull_requests:write` | review, comment on, edit and close pull requests | reviews, review comments, requested reviewers, comments and labels on a pull request's conversation, and editing a pull request (title, body, base, open or closed) |
+| `issues:read` | read its issues | `/issues`, `/issues/{n}`, `/labels` (GET) |
+| `issues:write` | label and comment on issues | opening, editing, labelling, assigning and commenting on issues |
+| `statuses:read` | read whether commits are passing | `/commits/{ref}/status`, `/commits/{ref}/statuses` |
+| `statuses:write` | mark commits as passing or failing | `POST /statuses/{sha}` |
+| `checks:read` | read check results on commits | `/check-runs`, `/check-suites`, `/commits/{ref}/check-runs` (GET) |
+| `checks:write` | post check results on commits | creating and updating check runs |
+| `actions:read` | read its Actions runs | `/actions/runs`, `/actions/workflows`, `/actions/jobs`, `/actions/artifacts` (GET) |
+
+- A repo's own record (`GET /repos/{owner}/{repo}`) and
+  `/installation/repositories` need no permission; every app has them.
+- A pull request's conversation comments and labels live at
+  `/repos/{owner}/{repo}/issues/{number}/comments` and `…/labels` on GitHub, and
+  `pull_requests:write` covers them when `{number}` is a pull request. An app
+  that comments on issues too declares `issues:write`.
+- Leaving `permissions` out gives `["contents:read", "pull_requests:write"]`.
+  Write the list anyway, so the consent page names what this app does.
+- When a new version of the app declares more, each person who connected a repo
+  keeps the list they agreed to until they press Connect again; the app's owner
+  gets the new list right away.
+
 ### 2. Connect it — `App.jsx`
 
 **The Connect button is a link to `buildGithubInstallUrl()` from `use-vibes`, opened in a new tab**
@@ -97,7 +131,7 @@ await ctx.github.fetch(`/repos/${repo}/pulls/${number}/reviews`, {
 ```
 
 `ctx.github.fetch` attaches the App's credential itself, so a repo call carries only its path, method and body.
-`path` starts at `/`: any `/repos/{owner}/{repo}/…` path for a repo connected to
+`path` starts at `/`: a `/repos/{owner}/{repo}/…` path from the permissions table above, for a repo connected to
 this app, plus `/installation/repositories`, which lists exactly the repos
 connected to this app. **An app sees only the repos connected to it**, so build
 every repo list from `routes()` or that listing. Methods are GET, POST, PUT, PATCH
@@ -105,7 +139,12 @@ and DELETE; an object `body` is sent as JSON. It resolves a normal `Response`
 (GitHub's own 404 or 422 included — read `res.ok` and `res.status`), and it
 rejects with an `Error` whose `err.reason` names what happened:
 `not_connected` (no repo connected yet), `unmodeled_endpoint` (a path outside
-those, or a repo this app has not connected), `permission_not_granted`,
+those, or a repo this app has not connected), `permission_not_declared` (the
+call needs a permission `config.github.permissions` leaves out — add it),
+`permission_not_consented` (declared, and the person connected the repo before
+the app asked for it — show them **Connect again** with the
+`buildGithubInstallUrl()` link), `permission_not_granted` (GitHub itself
+refused: the vibes.diy GitHub App does not hold that permission yet),
 `unsupported_method`, `body_too_large`, `upstream_error`. Branch on
 `err.reason` and tell the person which one it was.
 
@@ -190,6 +229,8 @@ export const config = {
   github: {
     bind: "anyone",
     why: "Leaves a short note on each new pull request in the repos you pick, saying how big the change is.",
+    // Reads each pull request and its files, and posts one review.
+    permissions: ["pull_requests:write"],
   },
 };
 
@@ -199,6 +240,12 @@ const PR_ACTIONS = ["opened", "reopened", "synchronize"];
 // The author_association values GitHub gives the people on a repo's team.
 const TEAM = ["OWNER", "MEMBER", "COLLABORATOR"];
 const DEFAULT_WHO = "team";
+// What each ctx.github refusal means to the person, in a line they can act on.
+const REASONS = {
+  permission_not_consented: "press Connect again to let this app review pull requests here",
+  permission_not_declared: "this app's backend needs to declare that GitHub permission",
+  permission_not_granted: "the vibes.diy GitHub App needs permission to review pull requests",
+};
 
 function json(data, status) {
   return new Response(JSON.stringify(data), { status: status ?? 200, headers: { "content-type": "application/json" } });
@@ -252,7 +299,7 @@ function takesOn(settings, pr) {
 async function finishNote(ctx, id, repo, pr, bigAt) {
   const outcome = await writeNote(ctx, repo, pr, bigAt).catch((err) => ({
     status: "failed",
-    reason: err.reason === "permission_not_granted" ? "the GitHub App needs permission to review pull requests" : String(err.reason ?? err.message),
+    reason: REASONS[err.reason] ?? String(err.reason ?? err.message),
   }));
   const claimed = await ctx.db.get(id, { db: DB });
   await ctx.db.put({ ...claimed, ...outcome }, { db: DB, id, ifRev: claimed._rev });
@@ -552,11 +599,13 @@ channel.
   the app is publishing plus `access.js`. Who sets off AI calls and GitHub
   posts is the repo's `who` setting on deliveries and a `binderHandle` check on
   every spending route. Keep the app published and gate the spend.
-- **What the App may do today:** read repository contents, and write to pull
-  requests — reviews, review comments, and comments on a pull request's
-  conversation. Build on those. Other writes (labels, issue comments, check
-  runs) may answer `permission_not_granted`; record that reason on the
-  person's record and show it, so they see exactly what happened.
+- **Declare what the app uses, and show each refusal.** A call outside the
+  declaration answers `permission_not_declared`; one the person has not agreed
+  to yet answers `permission_not_consented`, and pressing Connect again shows
+  them the new list. `permission_not_granted` means GitHub itself refused,
+  because the vibes.diy GitHub App does not hold that permission. Record the
+  reason on the person's record and show it, so they see exactly what happened
+  and what one tap fixes it.
 - **Each app gets the repos chosen for it.** The person ticks repos per app, and
   each app's connection stands on its own. One repo can feed up to ten apps,
   each hearing its deliveries with its own connector. While that switches on, a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "14.3.166",
+  "version": "14.3.167",
   "type": "module",
   "main": "./index.js",
   "exports": {
@@ -39,10 +39,10 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@adviser/cement": "~0.5.34",
-    "@vibes.diy/api-types": "14.3.166",
-    "@vibes.diy/call-ai-v2": "14.3.166",
-    "@vibes.diy/identity": "14.3.166",
-    "@vibes.diy/use-vibes-types": "14.3.166",
+    "@vibes.diy/api-types": "14.3.167",
+    "@vibes.diy/call-ai-v2": "14.3.167",
+    "@vibes.diy/identity": "14.3.167",
+    "@vibes.diy/use-vibes-types": "14.3.167",
     "arktype": "~2.2.6",
     "json-schema-faker": "~0.6.3"
   },