@bongos/core 1.21.95 → 1.21.96

package/src/bongos/github-repos.js

@@ -103,6 +103,134 @@ async function createUserRepo(token, { name, fetchImpl = fetch } = {}) {
   throw new GithubApiError(`GitHub create-repo failed (${res.status})`, { status: res.status, code: 'github_error' });
 }
 
+// ---- organisations (task 1004651) ----
+// A founder can put the project under a GitHub organisation instead of their personal
+// account: the empty repo (createOrgRepo) and the project's sign-in app (the manifest
+// flow's /organizations/<org>/settings/apps/new, built by the provisioning module).
+//
+// THE SCOPE LIMIT, said once. The hub's sign-in asks for `read:user repo` (ADR 0155/0364)
+// and not `read:org`, so GitHub may refuse the membership reads below for this token.
+// Widening the sign-in scope is auth-config.js's call, not this file's, so every read
+// here DEGRADES rather than fails: the role-carrying membership list when GitHub allows
+// it, else the organisations the founder's repos sit in (role unknown), and always a
+// typed name the founder can have checked. A role we could not read is said as such,
+// never guessed as "owner", and GitHub's own page still refuses a non-owner.
+
+// A GitHub login: 1-39 chars, letters/digits and single inner hyphens. The gate every
+// org name passes before it reaches a GitHub URL (the page's copy is never trusted).
+const GITHUB_LOGIN_RE = /^[A-Za-z0-9](?:[A-Za-z0-9]|-(?=[A-Za-z0-9])){0,38}$/;
+function validGithubLogin(s) { return typeof s === 'string' && GITHUB_LOGIN_RE.test(s); }
+
+// GitHub's refusal when the org restricts which OAuth apps may act for it. Matched on
+// the message because GitHub gives it no code of its own.
+function isAppRestricted(body) {
+  return /OAuth App access restrictions|third-party application access/i.test(String((body && body.message) || ''));
+}
+async function readBody(res) {
+  try { return await res.json(); } catch (_) { return {}; }
+}
+function unauthorized() {
+  return new GithubApiError('GitHub rejected the stored token', { status: 401, code: 'github_unauthorized' });
+}
+
+// One membership → what the page shows. Only an ACTIVE admin (an org owner) can make
+// an app on the org; anyone else gets the reason in words. role null = unknown. PURE.
+function orgAccess({ login, role = null, state = null }) {
+  if (role === 'admin' && state === 'active') return { login, role, can_create_apps: true, reason: null };
+  if (role && state === 'pending') {
+    return { login, role, can_create_apps: false, reason: `Your invitation to ${login} is still waiting. Accept it on GitHub first.` };
+  }
+  if (role) {
+    return { login, role, can_create_apps: false, reason: `You're a member of ${login}, not an owner. Only its owners can make apps there.` };
+  }
+  return {
+    login, role: null, can_create_apps: null,
+    reason: `GitHub didn't tell us your role in ${login}. Only its owners can make the app there; if you aren't one, GitHub will say so on its own page.`,
+  };
+}
+
+// The founder's organisations: { orgs: [orgAccess...], listed: 'memberships'|'repos'|'none' }.
+// 'memberships' carries real roles; 'repos' is the fallback for a token GitHub will not
+// show memberships to (the orgs the founder's repos live in, roles unknown); 'none' means
+// GitHub showed neither, and the page offers only the typed name. Sorted by login.
+async function listUserOrgs(token, { fetchImpl = fetch } = {}) {
+  const byLogin = (a, b) => a.login.toLowerCase().localeCompare(b.login.toLowerCase());
+  const res = await fetchImpl(`${GH_API}/user/memberships/orgs?per_page=${PER_PAGE}`, { headers: ghHeaders(token) });
+  if (res.status === 401) throw unauthorized();
+  if (res.ok) {
+    const rows = await readBody(res);
+    const orgs = (Array.isArray(rows) ? rows : [])
+      .map((m) => ({ login: m && m.organization && m.organization.login, role: m && m.role, state: m && m.state }))
+      .filter((m) => validGithubLogin(m.login))
+      .map(orgAccess)
+      .sort(byLogin);
+    return { orgs, listed: 'memberships' };
+  }
+  // No membership read for this token: the organisations its repos sit in. One page,
+  // a hint list and never a gate; the typed name covers the rest.
+  const r2 = await fetchImpl(`${GH_API}/user/repos?per_page=${PER_PAGE}&sort=updated&affiliation=organization_member`, { headers: ghHeaders(token) });
+  if (r2.status === 401) throw unauthorized();
+  if (!r2.ok) return { orgs: [], listed: 'none' };
+  const repos = await readBody(r2);
+  const seen = new Map();
+  for (const r of Array.isArray(repos) ? repos : []) {
+    const o = r && r.owner;
+    if (o && o.type === 'Organization' && validGithubLogin(o.login) && !seen.has(o.login.toLowerCase())) {
+      seen.set(o.login.toLowerCase(), orgAccess({ login: o.login }));
+    }
+  }
+  return { orgs: [...seen.values()].sort(byLogin), listed: 'repos' };
+}
+
+// Check ONE organisation the founder typed: its orgAccess, or a typed org_not_found when
+// GitHub has no organisation by that name (a personal account's login included). The
+// membership read answers with the role when this token may read it; otherwise the
+// public org read proves the org exists and the role stays unknown.
+async function getOrgAccess(token, { org, fetchImpl = fetch } = {}) {
+  if (!validGithubLogin(org)) throw new GithubApiError('Not a GitHub organisation name', { status: 400, code: 'bad_org' });
+  const res = await fetchImpl(`${GH_API}/user/memberships/orgs/${encodeURIComponent(org)}`, { headers: ghHeaders(token) });
+  if (res.status === 401) throw unauthorized();
+  if (res.ok) {
+    const m = await readBody(res);
+    const login = m && m.organization && validGithubLogin(m.organization.login) ? m.organization.login : org;
+    return orgAccess({ login, role: (m && m.role) || null, state: (m && m.state) || null });
+  }
+  const r2 = await fetchImpl(`${GH_API}/orgs/${encodeURIComponent(org)}`, { headers: ghHeaders(token) });
+  if (r2.status === 401) throw unauthorized();
+  if (r2.status === 404) throw new GithubApiError('GitHub has no organisation by that name', { status: 404, code: 'org_not_found' });
+  if (!r2.ok) throw new GithubApiError(`GitHub /orgs read failed (${r2.status})`, { status: r2.status, code: 'github_error' });
+  const o = await readBody(r2);
+  if (o && o.type && o.type !== 'Organization') throw new GithubApiError('That name is a personal account', { status: 404, code: 'org_not_found' });
+  return orgAccess({ login: o && validGithubLogin(o.login) ? o.login : org });
+}
+
+// Create an EMPTY repo under an organisation: the org twin of createUserRepo, with the
+// same fixed body (private, no first commit; ADR 0370). GitHub decides who may, and a
+// refusal is typed so the page can say WHY:
+//   org_app_restricted - the org limits which OAuth apps may act for it
+//   org_forbidden      - this member may not create repos there
+//   org_not_found      - no such org, or this account cannot see it
+async function createOrgRepo(token, { org, name, fetchImpl = fetch } = {}) {
+  if (!validGithubLogin(org)) throw new GithubApiError('Not a GitHub organisation name', { status: 400, code: 'bad_org' });
+  const res = await fetchImpl(`${GH_API}/orgs/${encodeURIComponent(org)}/repos`, {
+    method: 'POST',
+    headers: ghHeaders(token, { 'Content-Type': 'application/json' }),
+    body: JSON.stringify({ name, private: true, auto_init: false }),
+  });
+  if (res.status === 201) {
+    const r = await res.json();
+    return { full_name: r.full_name, html_url: r.html_url };
+  }
+  if (res.status === 401) throw unauthorized();
+  if (res.status === 422) throw new GithubApiError('A repository with that name already exists in the organisation', { status: 422, code: 'name_taken' });
+  if (res.status === 403) {
+    const body = await readBody(res);
+    throw new GithubApiError('GitHub refused the org repo', { status: 403, code: isAppRestricted(body) ? 'org_app_restricted' : 'org_forbidden' });
+  }
+  if (res.status === 404) throw new GithubApiError('GitHub answered 404 for that organisation', { status: 404, code: 'org_not_found' });
+  throw new GithubApiError(`GitHub create-org-repo failed (${res.status})`, { status: res.status, code: 'github_error' });
+}
+
 // Read one repo as GitHub answers it FOR THIS TOKEN — the manage page's
 // visibility read (task 1003045). GitHub's own 404 covers both "no such repo"
 // and "no access", which is exactly the no-leak shape the caller wants to
@@ -252,6 +380,7 @@ async function deleteDeployKey(token, { owner, name, keyId, fetchImpl = fetch }
 
 module.exports = {
   listUserRepos, createUserRepo, getUserRepo, makeRepoPublic, makeRepoPrivate,
+  listUserOrgs, getOrgAccess, createOrgRepo, validGithubLogin,
   listDeployKeys, addDeployKey, deleteDeployKey,
   GithubApiError, MAX_PAGES,
 };

package/src/bongos/routes/github.js

@@ -19,12 +19,13 @@ const express = require('express');
 const auth = require('../auth');
 const db = require('../db');
 const secretBox = require('../secret-box');
-const { listUserRepos, createUserRepo } = require('../github-repos');
+const { listUserRepos, createUserRepo, listUserOrgs, getOrgAccess, createOrgRepo, validGithubLogin } = require('../github-repos');
 // Namespace require for the visibility helpers (task 1003045): the route tests
 // stub these on the cached module object, which a load-time destructure would
 // pin to the real implementations.
 const githubRepos = require('../github-repos');
 const { validateOrRespond } = require('./_helpers');
+const log = require('../logger').logger.child({ src: 'github' });
 
 // GitHub repo names: 1–100 chars of [A-Za-z0-9._-]. We validate strictly for a clean
 // 400; anything GitHub still rejects surfaces as the 422→409 name_taken path.
@@ -33,6 +34,14 @@ const REPO_NAME_RE = /^[A-Za-z0-9._-]{1,100}$/;
 // hyphens) over a repo name. Strict for a clean 400; GitHub still owns the truth.
 const REPO_REF_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})?\/[A-Za-z0-9._-]{1,100}$/;
 
+// The two org refusals the org routes share (task 1004651).
+function badOrg(res) {
+  return res.fail('bad_org', { status: 400, message: 'That isn’t a GitHub organisation name: letters, numbers and single dashes, up to 39.' });
+}
+function orgNotFound(res, org) {
+  return res.fail('org_not_found', { status: 404, message: `GitHub didn’t show your account an organisation called ${org}.` });
+}
+
 // Parse + validate the owner/name ref, or send a 400 and return null.
 function parseRepoRef(raw, res) {
   const ref = String(raw || '').trim();
@@ -92,22 +101,79 @@ module.exports = function buildGithubRouter() {
     }
   });
 
-  // rank: any-builder — creates a repo in the caller's OWN account.
+  // rank: any-builder — 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.
+  router.get('/github/orgs', auth.requireBuilder, async (req, res) => {
+    const token = await resolveRepoToken(req, res);
+    if (!token) return;
+    try {
+      res.json(await listUserOrgs(token));
+    } catch (err) {
+      if (err && err.status === 401) {
+        await db.deleteGithubToken({ builderId: req.builder.id }).catch(() => {});
+        return res.fail('repo_scope_required', { status: 403, message: 'Your GitHub authorization expired. Reconnect to list your organisations.' });
+      }
+      log.error('[gds] GET /github/orgs', err && err.message);
+      res.fail('github_error', { status: 502, message: 'GitHub could not be reached. Try again in a moment.' });
+    }
+  });
+
+  // rank: any-builder — 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.
+  router.get('/github/orgs/:org', auth.requireBuilder, async (req, res) => {
+    const org = String(req.params.org || '').trim();
+    if (!validGithubLogin(org)) return badOrg(res);
+    const token = await resolveRepoToken(req, res);
+    if (!token) return;
+    try {
+      res.json({ org: await getOrgAccess(token, { org }) });
+    } catch (err) {
+      if (err && err.status === 401) {
+        await db.deleteGithubToken({ builderId: req.builder.id }).catch(() => {});
+        return res.fail('repo_scope_required', { status: 403, message: 'Your GitHub authorization expired. Reconnect to check the organisation.' });
+      }
+      if (err && err.code === 'org_not_found') return orgNotFound(res, org);
+      log.error('[gds] GET /github/orgs/:org', err && err.message);
+      res.fail('github_error', { status: 502, message: 'GitHub could not be reached. Try again in a moment.' });
+    }
+  });
+
+  // rank: any-builder — 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").
   router.post('/github/repos', auth.requireBuilder, async (req, res) => {
-    if (validateOrRespond(req, res, { name: { required: true, type: 'string', maxLength: 100 } })) return;
+    if (validateOrRespond(req, res, {
+      name: { required: true, type: 'string', maxLength: 100 },
+      org: { type: 'string', maxLength: 39 },
+    })) return;
     const name = String((req.body && req.body.name) || '').trim();
     if (!REPO_NAME_RE.test(name)) {
       return res.fail('bad_repo_name', { status: 400, message: 'Repository names use letters, numbers, and . _ - (1–100 chars).' });
     }
+    const org = req.body && req.body.org != null ? String(req.body.org).trim() : '';
+    if (org && !validGithubLogin(org)) return badOrg(res);
     const token = await resolveRepoToken(req, res);
     if (!token) return;
     try {
-      const repo = await createUserRepo(token, { name });
+      const repo = org ? await createOrgRepo(token, { org, name }) : await createUserRepo(token, { name });
       res.status(201).json({ repo });
     } catch (err) {
       if (err && err.code === 'name_taken') {
-        return res.fail('name_taken', { status: 409, message: 'You already have a repository with that name. Pick another, or adopt the existing one.' });
+        return res.fail('name_taken', { status: 409, message: org
+          ? `${org} already has a repository with that name. Pick another, or adopt the existing one.`
+          : 'You already have a repository with that name. Pick another, or adopt the existing one.' });
+      }
+      if (org && err && err.code === 'org_app_restricted') {
+        return res.fail('org_app_restricted', { status: 409, message: `${org} only lets apps its owners have approved act for it. An owner can approve this platform in the organisation's settings (Third-party access), or create the repo yourself.` });
+      }
+      if (org && err && err.code === 'org_forbidden') {
+        return res.fail('org_forbidden', { status: 409, message: `GitHub didn't let your account create a repository in ${org}. Ask one of its owners, or put the project on your own account.` });
       }
+      if (org && err && err.code === 'org_not_found') return orgNotFound(res, org);
       if (err && err.status === 401) {
         await db.deleteGithubToken({ builderId: req.builder.id }).catch(() => {});
         return res.fail('repo_scope_required', { status: 403, message: 'Your GitHub authorization expired. Reconnect to create the repo.' });

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.95'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.96'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/github_org_account.mjs

@@ -0,0 +1,378 @@
+// tests/github_org_account.mjs — a personal or an organisation GitHub account for the
+// project's repo and its sign-in app (task 1004651).
+//
+// Before: the page always posted `{}` to mint the app, so the server's org support was
+// dead and every app landed on the founder's personal account; and the new repo could only
+// be made on the personal account, so an organisation-owned project needed the manual
+// "create it yourself" fallback.
+//
+// What this pins:
+//   1. the personal path is UNCHANGED: the page posts `{}` to mint the app and `{name}` to
+//      make the repo, and GitHub is asked for /settings/apps/new and POST /user/repos;
+//   2. choosing an organisation builds the org manifest URL and creates the repo with
+//      POST /orgs/{org}/repos, and the app's settings link follows the organisation;
+//   3. an organisation the founder does not own is shown with the reason and cannot be
+//      picked, and the page refuses to start a trip for it;
+//   4. a bad organisation name is refused by the server before it reaches GitHub;
+//   5. GitHub's org refusals never come back as a 403 (the page reads that as "sign in").
+//
+// The whole path runs for real: the REAL routes (core GitHub router + provisioning mint
+// route), over HTTP, with GitHub faked at the fetch boundary, feeding the REAL page code
+// (sliced out of projects.html and run in a vm). DB-free: the token read and the
+// provisioning data-access fns are stubbed on their cached modules.
+//
+// Run:  node --test tests/github_org_account.mjs
+
+import assert from 'node:assert/strict';
+import { test, before, after } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+process.env.BUILDER_SECRET_KEY = process.env.BUILDER_SECRET_KEY || 'ab'.repeat(32);
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+// CRLF on a Windows checkout — a vm cannot run a slice with stray \r in it
+const HUB = fs.readFileSync(path.join(ROOT, 'modules', 'public-landing', 'public', 'projects.html'), 'utf8').replace(/\r\n/g, '\n');
+const SCRIPT = HUB.slice(HUB.lastIndexOf('<script>'), HUB.lastIndexOf('</script>'));
+
+// ── fake GitHub, at the fetch boundary ──────────────────────────────────────────────
+const realFetch = globalThis.fetch;
+let gh = {};            // path → (init) => [status, body]
+const ghCalls = [];
+function ghAnswer(url, init = {}) {
+  const u = new URL(url);
+  const key = `${(init.method || 'GET').toUpperCase()} ${u.pathname}`;
+  ghCalls.push({ key, url, body: init.body ? JSON.parse(init.body) : null });
+  const h = gh[key];
+  const [status, body] = h ? h(init) : [404, { message: 'Not Found' }];
+  return new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
+}
+globalThis.fetch = async (url, init) => (String(url).startsWith('https://api.github.com/') ? ghAnswer(String(url), init) : realFetch(url, init));
+
+// ── the signed-in founder and their stored repo token ───────────────────────────────
+const db = require(path.join(ROOT, 'src/bongos/db.js'));
+db.getGithubToken = async () => ({ token: 'tok', scope: 'read:user,repo' });
+db.deleteGithubToken = async () => {};
+const auth = require(path.join(ROOT, 'src/bongos/auth.js'));
+auth.requireBuilder = (req, _res, next) => { req.builder = { id: 7, github_login: 'founder' }; next(); };
+const api = require(path.join(ROOT, 'src/module-api.js'));
+api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, github_login: 'founder' }; next(); };
+
+// ── the provisioning world: one project, its attempts recorded ──────────────────────
+const provisioning = require(path.join(ROOT, 'modules/provisioning/provisioning.js'));
+let targetRef = 'founder/mercury';
+const events = [];
+provisioning.getInstanceById = async () => ({ id: 42, owner_builder_id: 7, slug: 'mercury', domain: 'mercury.example.com', target_ref: targetRef, status: 'requested' });
+provisioning.createOAuthManifest = async (_db, row) => ({ id: 99, ...row });
+provisioning.recordEvent = async (_db, e) => { events.push(e); };
+const branding = require(path.join(ROOT, 'src/branding.js'));
+const realBranding = branding.branding;
+branding.branding = () => ({ ...realBranding(), identity: { ...(realBranding().identity || {}), productName: 'Cloud Bongos' }, domains: { publicOrigin: 'https://cloudbongos.com' } });
+const GS = require(path.join(ROOT, 'modules/provisioning/github-setup.js'));
+const githubRepos = require(path.join(ROOT, 'src/bongos/github-repos.js'));
+
+const express = require('express');
+const { attachFail } = require(path.join(ROOT, 'src/bongos/middleware/error-envelope.js'));
+const buildGithubRouter = require(path.join(ROOT, 'src/bongos/routes/github.js'));
+const provisioningRoutes = require(path.join(ROOT, 'modules/provisioning/routes/provisioning.js'));
+let server, origin;
+before(async () => {
+  const app = express();
+  app.use(express.json());
+  app.use(attachFail);
+  app.use('/api/bongos', buildGithubRouter());
+  app.use('/api/bongos', provisioningRoutes());
+  server = app.listen(0);
+  await new Promise((r) => server.once('listening', r));
+  origin = `http://127.0.0.1:${server.address().port}`;
+});
+after(() => { server.close(); globalThis.fetch = realFetch; });
+
+// GitHub's answers for a founder who owns acme-studio and is only a member of bigcorp
+function memberships() {
+  return {
+    'GET /user/memberships/orgs': () => [200, [
+      { role: 'member', state: 'active', organization: { login: 'bigcorp' } },
+      { role: 'admin', state: 'active', organization: { login: 'acme-studio' } },
+    ]],
+  };
+}
+
+// ── the page code, sliced (each boundary asserted below) ────────────────────────────
+function region(startMark, endMark) {
+  const s = SCRIPT.indexOf(startMark);
+  const e = s < 0 ? -1 : SCRIPT.indexOf(endMark, s);
+  return s > 0 && e > s ? SCRIPT.slice(s, e) : null;
+}
+const PICKER = region("    /* ── whose GitHub account: mine or an organisation's (task 1004651) ──", "    var repoPick = acctPicker('ra', {");
+const ENSURE_REPO = region('    function ensureFreshRepo() {', "    $('doCreate').addEventListener('click'");
+const NOTE_ORG = region("    /* the organisation the server says this attempt's app is on: change-only */", '    function startManifest(btn) {');
+const START = region('    function startManifest(btn) {', '    /* the "start again" offer once a wait has clearly gone wrong');
+const SETTINGS = region('    /* the organisation that owns the app, when the founder made it on one (task 1004651) */', '    /* oauth-app — the ADR 0133 one-click GitHub-App manifest flow');
+
+test('the page regions are still findable (a rename must fail loudly, not test nothing)', () => {
+  for (const [name, r] of Object.entries({ PICKER, ENSURE_REPO, NOTE_ORG, START, SETTINGS })) assert.ok(r, `${name} region not found`);
+  assert.match(PICKER, /function acctPicker\(p, opts\)/);
+  assert.doesNotMatch(PICKER, /innerHTML/, 'organisation names are DOM text, never markup');
+});
+
+// A miniature DOM: just what the picker, the repo create and the mint touch.
+class El {
+  constructor(id, tag = 'div') { this.id = id; this.tagName = tag; this.hidden = false; this.textContent = ''; this.className = ''; this.children = []; this._v = ''; this.listeners = {}; this.disabled = false; }
+  addEventListener(ev, fn) { (this.listeners[ev] = this.listeners[ev] || []).push(fn); }
+  fire(ev, extra = {}) { (this.listeners[ev] || []).forEach((fn) => fn({ preventDefault() {}, ...extra })); }
+  focus() { this.focused = true; }
+  appendChild(c) { this.children.push(c); return c; }
+  removeChild(c) { this.children = this.children.filter((x) => x !== c); }
+  get firstChild() { return this.children[0] || null; }
+  get value() { return this._v; }
+  set value(v) {
+    // a select takes only a value one of its options has, as a browser does
+    if (this.tagName === 'select') this._v = this.children.some((o) => o.value === v) ? v : '';
+    else this._v = v;
+  }
+  submit() { this.submitted = true; }
+  remove() {}
+}
+function opt(value) { const o = new El(null, 'option'); o.value = value; return o; }
+
+function page({ state = {}, live = {} } = {}) {
+  const els = {};
+  const $ = (id) => {
+    if (!els[id]) {
+      const tag = /(Sel|Org)$/.test(id) ? 'select' : 'div';
+      els[id] = new El(id, tag);
+      if (/Sel$/.test(id)) { els[id].children.push(opt('personal'), opt('org')); els[id]._v = 'personal'; }
+    }
+    return els[id];
+  };
+  const posted = [];
+  const forms = [];
+  const sandbox = {
+    API: '/api/bongos', $, JSON, String, Promise, encodeURIComponent, Error,
+    document: {
+      body: { appendChild() {} },
+      createElement: (tag) => { const e = new El(null, tag); if (tag === 'form') forms.push(e); return e; },
+    },
+    window: { open: () => ({ close() {} }), location: { assign() {} } },
+    fetch: (p, init) => { posted.push({ p, init }); return realFetch(origin + p, { method: (init && init.method) || 'GET', headers: init && init.headers, body: init && init.body }); },
+    state: { repo: 'mercury', mode: 'greenfield', owner: 'founder', ...state },
+    live: { manifest: null, manifestMsg: '', manifestFailure: null, appSlug: null, appOrg: null, setup: null, installUrl: null, ...live },
+    repoAccess: true, instanceId: 42, me: { github_login: 'founder' },
+    hopForRepoAccess: () => false, syncHome() {}, saveDraft() {},
+    rememberManifest() {}, renderSteps() {}, pollManifest() {},
+  };
+  sandbox.manifestStartedAt = 0; sandbox.manifestStale = false;
+  vm.createContext(sandbox);
+  vm.runInContext([PICKER, ENSURE_REPO, NOTE_ORG, START, SETTINGS, "var appPick = acctPicker('aa', { needsOwner: true });"].join('\n'), sandbox);
+  return { sb: sandbox, els, posted, forms, settle: () => new Promise((r) => setTimeout(r, 60)) };
+}
+async function settled(p, n = 6) { for (let i = 0; i < n; i++) await p.settle(); }
+
+// ── 1. the personal path is unchanged ───────────────────────────────────────────────
+test('personal: the page mints with an empty body, and GitHub is asked for the personal app page', async () => {
+  gh = memberships(); events.length = 0;
+  const p = page();
+  p.sb.appPick.load(null);
+  const btn = new El('btn');
+  p.sb.startManifest(btn);
+  await settled(p);
+  const mint = p.posted.find((x) => /\/github-app$/.test(x.p));
+  assert.equal(mint.init.body, '{}', 'byte-for-byte what the page always sent');
+  assert.equal(p.forms.length, 1);
+  assert.match(p.forms[0].action, /^https:\/\/github\.com\/settings\/apps\/new\?state=[0-9a-f]{64}$/);
+  assert.ok(!events.some((e) => e.event === GS.SETUP_EVENTS.appOrg), 'no organisation is recorded for a personal app');
+  assert.ok(!p.posted.some((x) => /\/github\/orgs/.test(x.p)), 'GitHub is not even asked for organisations');
+});
+
+test('personal: the new repo is made with {name} and POST /user/repos, as before', async () => {
+  gh = { 'POST /user/repos': () => [201, { full_name: 'founder/mercury', html_url: 'https://github.com/founder/mercury' }] };
+  ghCalls.length = 0;
+  const p = page();
+  await p.sb.ensureFreshRepo();
+  const sent = p.posted.find((x) => x.p === '/api/bongos/github/repos');
+  assert.equal(sent.init.body, JSON.stringify({ name: 'mercury' }));
+  assert.deepEqual(ghCalls.map((c) => c.key), ['POST /user/repos']);
+  assert.deepEqual(ghCalls[0].body, { name: 'mercury', private: true, auto_init: false });
+  assert.equal(p.sb.state.owner, 'founder');
+});
+
+// ── 2. an organisation ──────────────────────────────────────────────────────────────
+test('organisation: listed from GitHub; one the founder only belongs to is shown with the reason and cannot be picked', async () => {
+  gh = memberships();
+  const p = page();
+  p.sb.appPick.load(null);
+  p.els.aaSel.value = 'org'; p.els.aaSel.fire('change');
+  await settled(p);
+  const opts = p.els.aaOrg.children.map((o) => ({ v: o.value, t: o.textContent, off: o.disabled }));
+  assert.deepEqual(opts, [
+    { v: 'acme-studio', t: 'acme-studio', off: false },
+    { v: 'bigcorp', t: 'bigcorp (you’re a member, not an owner)', off: true },
+    { v: '__other', t: 'Another organisation…', off: false },
+  ]);
+  assert.equal(p.els.aaOrg.value, 'acme-studio', 'the one they own is picked');
+  assert.equal(p.els.aaOrgField.hidden, false);
+  // a refused one forced in (an old browser ignoring disabled) still cannot go ahead
+  p.els.aaOrg._v = 'bigcorp'; p.els.aaOrg.fire('change');
+  assert.equal(p.sb.appPick.value().ok, false);
+  assert.match(p.els.aaNote.textContent, /member of bigcorp, not an owner/);
+  const btn = new El('btn');
+  p.sb.startManifest(btn);
+  await settled(p, 2);
+  assert.ok(!p.posted.some((x) => /\/github-app$/.test(x.p)), 'no link is minted for an organisation they cannot make apps on');
+});
+
+test('organisation: the app is made on it — the org manifest URL, the org recorded, its settings linked there', async () => {
+  gh = memberships(); events.length = 0;
+  const p = page();
+  p.sb.appPick.load('acme-studio');
+  await settled(p);
+  assert.equal(p.sb.appPick.value().org, 'acme-studio');
+  p.sb.startManifest(new El('btn'));
+  await settled(p);
+  const mint = p.posted.find((x) => /\/github-app$/.test(x.p));
+  assert.deepEqual(JSON.parse(mint.init.body), { account: 'org', org: 'acme-studio' });
+  assert.match(p.forms[0].action, /^https:\/\/github\.com\/organizations\/acme-studio\/settings\/apps\/new\?state=[0-9a-f]{64}$/);
+  assert.deepEqual(events.filter((e) => e.event === GS.SETUP_EVENTS.appOrg).map((e) => e.detail), ['acme-studio']);
+  // the page now knows whose app it is, and links its settings under the organisation
+  p.sb.live.appSlug = 'mercury-app';
+  assert.equal(vm.runInContext('appSettingsUrl()', p.sb), 'https://github.com/organizations/acme-studio/settings/apps/mercury-app');
+  p.sb.live.appOrg = null;
+  assert.equal(vm.runInContext('appSettingsUrl()', p.sb), 'https://github.com/settings/apps/mercury-app', 'and under the founder for a personal app');
+});
+
+test('organisation: the new repo is made under it with POST /orgs/{org}/repos, and the project points at it', async () => {
+  gh = { 'POST /orgs/acme-studio/repos': () => [201, { full_name: 'acme-studio/mercury', html_url: 'https://github.com/acme-studio/mercury' }] };
+  ghCalls.length = 0;
+  const p = page({ state: { repoAcct: 'org', repoOrg: 'acme-studio' } });
+  await p.sb.ensureFreshRepo();
+  assert.deepEqual(ghCalls.map((c) => c.key), ['POST /orgs/acme-studio/repos']);
+  assert.deepEqual(ghCalls[0].body, { name: 'mercury', private: true, auto_init: false });
+  assert.equal(p.sb.state.owner, 'acme-studio');
+  assert.equal(p.sb.state.repoUrl, 'https://github.com/acme-studio/mercury');
+  assert.equal(p.sb.state.repoAutoCreated, true);
+});
+
+test('organisation: GitHub refusing the org repo comes back with its reason, never as "sign in again"', async () => {
+  const cases = [
+    [{ message: 'Although you appear to have the correct authorization credentials, the `acme-studio` organization has enabled OAuth App access restrictions' }, 'org_app_restricted', /Third-party access/],
+    [{ message: 'You need admin access to the organization before adding a repository to it.' }, 'org_forbidden', /didn't let your account|didn’t let your account/],
+  ];
+  for (const [body, code, words] of cases) {
+    gh = { 'POST /orgs/acme-studio/repos': () => [403, body] };
+    const res = await realFetch(`${origin}/api/bongos/github/repos`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ name: 'mercury', org: 'acme-studio' }) });
+    const j = await res.json();
+    assert.equal(res.status, 409, code);
+    assert.equal(j.error.code, code);
+    assert.match(j.error.message, words);
+    // the page takes the founder to the Code row with that reason, not to a sign-in hop
+    const p = page({ state: { repoAcct: 'org', repoOrg: 'acme-studio' } });
+    let hopped = false; p.sb.hopForRepoAccess = () => { hopped = true; return true; };
+    await assert.rejects(() => p.sb.ensureFreshRepo(), (e) => e.gotoHome === true && e.homeMsg === j.error.message);
+    assert.equal(hopped, false);
+  }
+});
+
+// ── 3. when GitHub will not show the founder's memberships ──────────────────────────
+test('typed name: GitHub hides the memberships, so the founder types it and it is checked', async () => {
+  gh = {
+    'GET /user/memberships/orgs': () => [403, { message: 'requires read:org' }],
+    'GET /user/repos': () => [403, {}],
+    'GET /user/memberships/orgs/acme-studio': () => [403, { message: 'requires read:org' }],
+    'GET /orgs/acme-studio': () => [200, { login: 'acme-studio', type: 'Organization' }],
+    'GET /orgs/someone': () => [200, { login: 'someone', type: 'User' }],
+  };
+  const p = page();
+  p.sb.appPick.load('');
+  await settled(p);
+  assert.deepEqual(p.els.aaOrg.children.map((o) => o.value), ['__other']);
+  assert.equal(p.els.aaTyped.hidden, false);
+  assert.match(p.els.aaNote.textContent, /didn’t show us your organisations/);
+  assert.equal(p.sb.appPick.value().ok, false, 'nothing to go ahead with until it is checked');
+  p.els.aaName.value = 'acme-studio'; p.els.aaCheck.fire('click');
+  await settled(p);
+  const v = p.sb.appPick.value();
+  assert.equal(v.org, 'acme-studio');
+  assert.equal(v.ok, true, 'an organisation GitHub did not give a role for is offered, said as such');
+  assert.match(p.els.aaNote.textContent, /didn't tell us your role in acme-studio/);
+  // a personal account's login is not an organisation
+  p.els.aaName.value = 'someone'; p.els.aaCheck.fire('click');
+  await settled(p);
+  assert.equal(p.sb.appPick.value().ok, false);
+  assert.match(p.els.aaNote.textContent, /an organisation called someone/);
+});
+
+// ── 4. bad names never reach GitHub ─────────────────────────────────────────────────
+test('bad organisation names are refused by the server before GitHub is asked', async () => {
+  gh = {}; ghCalls.length = 0;
+  for (const bad of ['-acme', 'acme-', 'ac--me', 'a/b', 'acme studio', 'x'.repeat(40), '../etc']) {
+    const mint = await realFetch(`${origin}/api/bongos/provisioning/instances/42/github-app`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ account: 'org', org: bad }) });
+    assert.equal(mint.status, 400, `mint: ${bad}`);
+    const repo = await realFetch(`${origin}/api/bongos/github/repos`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ name: 'mercury', org: bad }) });
+    assert.equal(repo.status, 400, `repo: ${bad}`);
+  }
+  const check = await realFetch(`${origin}/api/bongos/github/orgs/${encodeURIComponent('ac--me')}`);
+  assert.equal(check.status, 400);
+  assert.deepEqual(ghCalls, [], 'GitHub was never called with any of them');
+  for (const bad of ['-acme', 'ac--me', 'acme_', '']) assert.equal(githubRepos.validGithubLogin(bad), false, bad);
+  for (const ok of ['a', 'acme-studio', 'A1-b2', 'x'.repeat(39)]) assert.equal(githubRepos.validGithubLogin(ok), true, ok);
+});
+
+test('mint: an explicit organisation choice never falls back to the personal account unseen', async () => {
+  targetRef = 'founder_x/mercury';   // an owner that is not a login, and nothing typed
+  try {
+    const res = await realFetch(`${origin}/api/bongos/provisioning/instances/42/github-app`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ account: 'org' }) });
+    assert.equal(res.status, 400);
+    assert.equal((await res.json()).error.code, 'org_required');
+  } finally { targetRef = 'founder/mercury'; }
+  // with no org typed, account 'org' still means the repo's own organisation, as before
+  targetRef = 'acme-studio/mercury';
+  try {
+    const j = await (await realFetch(`${origin}/api/bongos/provisioning/instances/42/github-app`, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ account: 'org' }) })).json();
+    assert.equal(j.account, 'org');
+    assert.match(j.post_url, /^https:\/\/github\.com\/organizations\/acme-studio\/settings\/apps\/new\?state=/);
+  } finally { targetRef = 'founder/mercury'; }
+});
+
+// ── 5. the helpers, at unit altitude ────────────────────────────────────────────────
+test('listUserOrgs: roles from the memberships; else the organisations the repos sit in, roles unknown', async () => {
+  gh = { 'GET /user/memberships/orgs': () => [200, [{ role: 'admin', state: 'pending', organization: { login: 'newco' } }, { role: 'admin', state: 'active', organization: { login: 'bad name' } }]] };
+  let out = await githubRepos.listUserOrgs('tok');
+  assert.equal(out.listed, 'memberships');
+  assert.deepEqual(out.orgs.map((o) => [o.login, o.can_create_apps]), [['newco', false]], 'a malformed login is dropped; a pending invite cannot');
+  assert.match(out.orgs[0].reason, /invitation to newco is still waiting/);
+  gh = {
+    'GET /user/memberships/orgs': () => [403, {}],
+    'GET /user/repos': () => [200, [
+      { owner: { login: 'Zeta', type: 'Organization' } }, { owner: { login: 'founder', type: 'User' } },
+      { owner: { login: 'alpha', type: 'Organization' } }, { owner: { login: 'zeta', type: 'Organization' } },
+    ]],
+  };
+  out = await githubRepos.listUserOrgs('tok');
+  assert.equal(out.listed, 'repos');
+  assert.deepEqual(out.orgs.map((o) => [o.login, o.can_create_apps]), [['alpha', null], ['Zeta', null]]);
+  gh = { 'GET /user/memberships/orgs': () => [403, {}], 'GET /user/repos': () => [500, {}] };
+  assert.deepEqual(await githubRepos.listUserOrgs('tok'), { orgs: [], listed: 'none' });
+});
+
+test('getOrgAccess: the role when GitHub gives it, unknown when it only proves the org exists, missing otherwise', async () => {
+  gh = { 'GET /user/memberships/orgs/acme-studio': () => [200, { role: 'admin', state: 'active', organization: { login: 'Acme-Studio' } }] };
+  assert.deepEqual(await githubRepos.getOrgAccess('tok', { org: 'acme-studio' }), { login: 'Acme-Studio', role: 'admin', can_create_apps: true, reason: null });
+  gh = { 'GET /user/memberships/orgs/ghost': () => [404, {}], 'GET /orgs/ghost': () => [404, {}] };
+  await assert.rejects(() => githubRepos.getOrgAccess('tok', { org: 'ghost' }), (e) => e.code === 'org_not_found');
+  await assert.rejects(() => githubRepos.getOrgAccess('tok', { org: 'a--b' }), (e) => e.code === 'bad_org');
+});
+
+test('github-setup: the organisation recorded at the mint rides the checklist read as app_org', async () => {
+  const row = { instance_id: 42, state: 'S1', created_at: '2026-10-08T09:00:00Z', app_slug: 'mercury-app' };
+  const said = await GS.githubSetupRead({ query: async () => ({ rows: [{ event: GS.SETUP_EVENTS.appOrg, at: '2026-10-08T09:00:01Z', detail: 'acme-studio' }] }) }, {}, row, 'done');
+  assert.equal(said.app_org, 'acme-studio');
+  const bad = await GS.githubSetupRead({ query: async () => ({ rows: [{ event: GS.SETUP_EVENTS.appOrg, at: '2026-10-08T09:00:01Z', detail: '<script>' }] }) }, {}, row, 'done');
+  assert.equal(bad.app_org, null, 'a recorded value that is not a login never reaches a link');
+  const none = await GS.githubSetupRead({ query: async () => ({ rows: [] }) }, {}, row, 'done');
+  assert.equal(none.app_org, null, 'nothing recorded = the founder’s own account');
+});