@bongos/core 1.21.94 → 1.21.96

package/docs/api/openapi.json

@@ -6381,6 +6381,89 @@
         ]
       }
     },
+    "/github/orgs": {
+      "get": {
+        "operationId": "get_github_orgs",
+        "tags": [
+          "github"
+        ],
+        "summary": "GET /github/orgs",
+        "description": "the caller's OWN GitHub organisations (task 1004651), for the project page's \"on an organisation\" choice. Each row says whether the caller can make an app there and, when not, why. `listed` says how much GitHub showed this token (github-repos.listUserOrgs): the page always offers a typed name beside the list.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "src/bongos/routes/github.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/github/orgs/{org}": {
+      "get": {
+        "operationId": "get_github_orgs_org",
+        "tags": [
+          "github"
+        ],
+        "summary": "GET /github/orgs/:org",
+        "description": "checks ONE organisation name the caller typed, as their own GitHub credential sees it (task 1004651). The name is checked against GitHub's login rules before it reaches a URL.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "src/bongos/routes/github.js",
+        "parameters": [
+          {
+            "name": "org",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string"
+            },
+            "description": "Path parameter `org`."
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetGithubOrgsOrgResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          },
+          "404": {
+            "$ref": "#/components/responses/NotFound"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/github/repo": {
       "get": {
         "operationId": "get_github_repo",
@@ -6511,7 +6594,7 @@
           "github"
         ],
         "summary": "POST /github/repos",
-        "description": "creates a repo in the caller's OWN account.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "description": "creates a repo in the caller's OWN account, or (task 1004651) under an organisation they name in `org`. GitHub decides whether they may; its refusals come back as 409s with the reason, never as a 403 (the page reads a 403 as \"sign in again\").\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
         "x-rank": "any-builder",
         "x-source": "src/bongos/routes/github.js",
         "requestBody": {
@@ -16460,6 +16543,65 @@
         "security": []
       }
     },
+    "/provisioning/github-app/resume": {
+      "get": {
+        "operationId": "get_provisioning_github_app_resume",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/github-app/resume",
+        "description": "GET /provisioning/github-app/resume[?id=<n>] — the project page's \"which project am I connecting?\" read when its tab remembers nothing (task 1004650): a hand-back on another device, a fresh tab, a cleared browser. With an id: that project, if the caller owns it. Without: the caller's newest project whose GitHub checklist is not connected yet, made or last tried within a week — so opening the create page later resumes part 03 from the server's view. Either way { project: null } when there is none; never the state token. rank: any authenticated builder (requireBuilder), own projects only — no Archon override.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/provisioning/routes/github-setup.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetProvisioningGithubAppResumeResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
+    "/provisioning/github-app/return": {
+      "get": {
+        "operationId": "get_provisioning_github_app_return",
+        "tags": [
+          "provisioning"
+        ],
+        "summary": "GET /provisioning/github-app/return",
+        "description": "GET /provisioning/github-app/return?state=<> — where the callback and setup pages send the founder back (task 1004650). The SERVER resolves the one-time state to the project it was minted for and 302s that project's signed-in OWNER to its part 03 (/projects?view=new&id=<id>), so the hand-back works from any tab, window or device — nothing in browser storage is read. Not signed in → through the web sign-in and back here. Signed in as anyone else, an unknown or malformed state, or a gone project → one refusal page that names no project (no oracle about which). The state stays single-use where it matters: only the manifest callback's code exchange consumes it, and this route changes nothing — it reveals a project's page only to the person who already owns it. rank: public — as a GATE: it is a browser redirect, so no middleware 401s a signed-out visitor (they are sent through sign-in instead). WHO lands is decided in-handler from the live session: the project's own owner, no Archon override, and nobody else ever learns which project the state names. It reveals no secret and writes nothing.\n\n**Rank:** `public` — No authentication — any caller.",
+        "x-rank": "public",
+        "x-source": "modules/provisioning/routes/github-setup.js",
+        "responses": {
+          "200": {
+            "description": "Success."
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          }
+        },
+        "security": []
+      }
+    },
     "/provisioning/github-app/setup": {
       "get": {
         "operationId": "get_provisioning_github_app_setup",
@@ -17312,7 +17454,7 @@
           "provisioning"
         ],
         "summary": "POST /provisioning/instances/:id/github-app",
-        "description": "POST /provisioning/instances/:id/github-app — mint a GitHub-App-Manifest onboarding link for the caller's OWN instance (task 2080, ADR 0133). rank: any authenticated builder (own resource). Returns the pre-filled manifest + the GitHub form-POST target (personal + org variants) + a one-time `state`; the browser POSTs the manifest to GitHub, the owner approves, and GitHub redirects back to the public callback below. The web tier only RECORDS the attempt (state token) — the control-plane runner does the token exchange + cred placement (trust boundary intact, ADR 0111 §2). Body: { account? ('personal'|'org') }.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "description": "POST /provisioning/instances/:id/github-app — mint a GitHub-App-Manifest onboarding link for the caller's OWN instance (task 2080, ADR 0133). rank: any authenticated builder (own resource). Returns the pre-filled manifest + the GitHub form-POST target (personal + org variants) + a one-time `state`; the browser POSTs the manifest to GitHub, the owner approves, and GitHub redirects back to the public callback below. The web tier only RECORDS the attempt (state token) — the control-plane runner does the token exchange + cred placement (trust boundary intact, ADR 0111 §2). Body: { account? ('personal'|'org'), org? (a GitHub organisation login) }. A personal or an organisation account (task 1004651): account 'org' makes the app on the organisation the founder chose on the page (`org`), else on the repo's owner. The org name is checked against GitHub's login rules here, never trusted from the page; whether the founder may make an app there is GitHub's to enforce on its own page (this module holds no GitHub token to ask with, ADR 0111 §2). Anything other than account 'org' is the founder's personal account, exactly as before.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
         "x-rank": "any-builder",
         "x-source": "modules/provisioning/routes/provisioning.js",
         "parameters": [
@@ -25887,6 +26029,15 @@
           "count"
         ]
       },
+      "GetGithubOrgsOrgResponse": {
+        "type": "object",
+        "properties": {
+          "org": {}
+        },
+        "required": [
+          "org"
+        ]
+      },
       "GetGithubRepoResponse": {
         "type": "object",
         "properties": {
@@ -26773,6 +26924,19 @@
           "capacity"
         ]
       },
+      "GetProvisioningGithubAppResumeResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "project": {}
+        },
+        "required": [
+          "ok",
+          "project"
+        ]
+      },
       "GetProvisioningGithubAppStatusResponse": {
         "type": "object",
         "properties": {
@@ -26789,7 +26953,8 @@
           "checklist": {},
           "install_url": {},
           "repo": {},
-          "verifying": {}
+          "verifying": {},
+          "app_org": {}
         },
         "required": [
           "ok",
@@ -26803,7 +26968,8 @@
           "checklist",
           "install_url",
           "repo",
-          "verifying"
+          "verifying",
+          "app_org"
         ]
       },
       "GetProvisioningHealthResponse": {
@@ -29738,6 +29904,10 @@
           "name": {
             "type": "string",
             "maxLength": 100
+          },
+          "org": {
+            "type": "string",
+            "maxLength": 39
           }
         },
         "required": [
@@ -31931,6 +32101,10 @@
           "account": {
             "type": "string",
             "maxLength": 12
+          },
+          "org": {
+            "type": "string",
+            "maxLength": 39
           }
         },
         "additionalProperties": false
@@ -34253,9 +34427,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 534,
-  "x-schema-count": 574,
+  "x-endpoint-count": 538,
+  "x-schema-count": 576,
   "x-undocumented-bodies": 12,
-  "x-response-schemas": 380,
+  "x-response-schemas": 382,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 534 endpoints across 95 route files.
+> **Generated from the live route files** — the route file is authoritative. 538 endpoints across 95 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust-boundary-server-enforced-permissions.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -286,14 +286,16 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/gate-approvals` | `metic+archon` | — | GET /gate-approvals — open PRs awaiting owner approval (gate-review red), with the verdict + per-file reasons + changed files + diff link. |
 | POST | `/api/bongos/gate-approvals/:pr/approve` | `archon` | — | POST /gate-approvals/:pr/approve — record owner approval for a stuck gate PR and re-run the gate-review check so it clears. |
 
-## `github` (4)
+## `github` (6)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
+| GET | `/api/bongos/github/orgs` | `any-builder` | — | the caller's OWN GitHub organisations (task 1004651), for the project page's "on an organisation" choice. |
+| GET | `/api/bongos/github/orgs/:org` | `any-builder` | — | checks ONE organisation name the caller typed, as their own GitHub credential sees it (task 1004651). |
 | GET | `/api/bongos/github/repo` | `any-builder` | — | reads one repo AS the caller's own GitHub credential sees it (the manage page's repo-visibility read, task 1003045). |
 | POST | `/api/bongos/github/repo/visibility` | `any-builder` | `repo`, `visibility` | flips one of the caller's repos PUBLIC, with their own credential. |
 | GET | `/api/bongos/github/repos` | `any-builder` | — | acts only on the caller's OWN GitHub identity (the token they granted). |
-| POST | `/api/bongos/github/repos` | `any-builder` | `name` | creates a repo in the caller's OWN account. |
+| POST | `/api/bongos/github/repos` | `any-builder` | `name`, `org` | creates a repo in the caller's OWN account, or (task 1004651) under an organisation they name in `org`. |
 
 ## `goal-task-relevance` (2)
 
@@ -636,7 +638,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | POST | `/api/bongos/projects/invite` | `metic+archon` | `client_id`, `github_login` | own-or-metic in effect: where to invite a builder into a project, asked by a `project.curate` holder OR the project's OWN OWNER (task 100… |
 | POST | `/api/bongos/projects/invite-guild` | `metic+archon` | `client_id`, `guild` | own-or-metic in effect, the SAME gate as POST /projects/invite above and for the same reasons (a non-inviter gets that route's unchanged … |
 
-## `provisioning` (43)
+## `provisioning` (45)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -644,6 +646,8 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | GET | `/api/bongos/provisioning/fleet` | `metic+archon` | — | GET /provisioning/fleet — the full instance roster across all owners. |
 | GET | `/api/bongos/provisioning/fleet/cost-ledger` | `metic+archon` | — | GET /provisioning/fleet/cost-ledger — per-instance monthly cost to us + estimated cost to its owner, with totals. |
 | GET | `/api/bongos/provisioning/github-app/callback` | `public` | — | GET /provisioning/github-app/callback?code=&state= — GitHub redirects the owner's BROWSER here after they approve the App Manifest (task … |
+| GET | `/api/bongos/provisioning/github-app/resume` | `any-builder` | — | GET /provisioning/github-app/resume[?id=<n>] — the project page's "which project am I connecting?" read when its tab remembers nothing (t… |
+| GET | `/api/bongos/provisioning/github-app/return` | `public` | — | GET /provisioning/github-app/return?state=<> — where the callback and setup pages send the founder back (task 1004650). |
 | GET | `/api/bongos/provisioning/github-app/setup` | `public` | — | GET /provisioning/github-app/setup?installation_id=&setup_action=&state= — the App's setup_url (task 1004649). |
 | GET | `/api/bongos/provisioning/github-app/status` | `public` | — | GET /provisioning/github-app/status?state=<> — the PUBLIC progress read (task 1004548; the checklist since task 1004649). |
 | GET | `/api/bongos/provisioning/health` | `public` | — | GET /provisioning/health — liveness + the core version this module mounted against. |
@@ -661,7 +665,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/0016-trust
 | PATCH | `/api/bongos/provisioning/instances/:id/env-manifest/:varId` | `any-builder` | `name`, `description`, `environments`, `required` | PATCH — edit one declaration. |
 | DELETE | `/api/bongos/provisioning/instances/:id/env-manifest/:varId` | `any-builder` | — | DELETE — remove one declaration. |
 | POST | `/api/bongos/provisioning/instances/:id/force-teardown` | `metic+archon` | — | POST /provisioning/instances/:id/force-teardown — Archon tears down ANY instance. |
-| POST | `/api/bongos/provisioning/instances/:id/github-app` | `any-builder` | `account` | POST /provisioning/instances/:id/github-app — mint a GitHub-App-Manifest onboarding link for the caller's OWN instance (task 2080, ADR 01… |
+| POST | `/api/bongos/provisioning/instances/:id/github-app` | `any-builder` | `account`, `org` | POST /provisioning/instances/:id/github-app — mint a GitHub-App-Manifest onboarding link for the caller's OWN instance (task 2080, ADR 01… |
 | GET | `/api/bongos/provisioning/instances/:id/invite-suggestions` | `any-builder` | — | ── Who is worth inviting (BV1.R28, task 1002347, goal 1000046 C6) ──────── GET /provisioning/instances/:id/invite-suggestions — turn the … |
 | PUT | `/api/bongos/provisioning/instances/:id/logo` | `any-builder` | `image_b64`, `content_type` | PUT …/logo — rank: any authenticated builder (own resource; archon may change any). |
 | DELETE | `/api/bongos/provisioning/instances/:id/logo` | `any-builder` | validated | DELETE …/logo — rank: any authenticated builder (own resource; archon may change any). |