@bongos/core 1.21.94 → 1.21.95

package/modules/provisioning/routes/github-setup.js

@@ -9,6 +9,12 @@
 // single-use `state` minted for the signed-in owner is the only key, and neither route
 // reveals a secret or changes authority. The checklist they report is derived in
 // ../github-setup.js from what the control-plane runner has VERIFIED.
+//
+// Two signed-in routes join them (task 1004650 — the hand-back from any tab or device):
+// the RETURN route the callback and setup pages send the founder to, which lands the state's
+// own project for its owner and nobody else, and the RESUME read the project page asks when
+// its tab remembers nothing — so a phone, a second window or a fresh tab picks up part 03 of
+// the right project from what the server knows, never from sessionStorage.
 'use strict';
 
 const express = require('express');
@@ -17,10 +23,38 @@ const { pool } = api;
 const provisioning = require('../provisioning');
 const githubSetup = require('../github-setup');
 const { makeAskRateLimiter } = require('../rate-limit');
-const { callbackPage } = require('./callback-page');
+const { callbackPage, returnHref } = require('./callback-page');
 
 const log = api.logger('provisioning');
 
+// The state tokens this leg mints are hex (provisioning.js); anything else is not one of ours.
+const STATE_RE = /^[0-9a-f]{16,128}$/i;
+
+// An attempt or a project older than this is not "in progress" for the resume read: a
+// founder who walked away a week ago and opens the create page gets a fresh page.
+const RESUME_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+// Is this instance one the hand-back may land on for this builder? Strictly the OWNER —
+// no Archon override: the return route names a project to whoever holds the state, and a
+// project page is where its owner, and only its owner, connects GitHub. A gone project is
+// no landing either. PURE.
+function ownsLanding(inst, builderId) {
+  return !!(inst && builderId != null && String(inst.owner_builder_id) === String(builderId)
+    && !inst.torn_down_at && inst.status !== 'torn_down');
+}
+
+// The project page's resume record: just what part 03 needs to name and watch the project
+// (the page reads the rest from the owner's instance read). Never the state token. PURE.
+function resumeRecord(inst) {
+  return { id: inst.id, slug: inst.slug, domain: inst.domain || null, onboard_mode: inst.onboard_mode || 'greenfield', repo: githubSetup.targetRepo(inst) };
+}
+
+// The project page to land on: part 03 of that project, by id. The state rides the
+// FRAGMENT (never sent to a server) so the page can keep watching that attempt. PURE.
+function landingHref(instanceId, state) {
+  return `/projects?view=new&id=${encodeURIComponent(String(instanceId))}${state ? `#ghstate=${encodeURIComponent(state)}` : ''}`;
+}
+
 // GitHub's installation id is digits; anything else is dropped before it reaches a log line.
 function installationIdOf(q) {
   const s = String((q && q.installation_id) || '');
@@ -32,6 +66,7 @@ module.exports = function buildGithubSetupRouter() {
   // the page polls every few seconds, the callback page every two — per-IP, in-module
   const statusRateLimit = makeAskRateLimiter({ max: 120 });
   const setupRateLimit = makeAskRateLimiter({ max: 30 });
+  const returnRateLimit = makeAskRateLimiter({ max: 30 });
 
   // GET /provisioning/github-app/status?state=<> — the PUBLIC progress read (task 1004548;
   // the checklist since task 1004649). Reveals the manifest lifecycle status, the
@@ -85,7 +120,7 @@ module.exports = function buildGithubSetupRouter() {
     const sendPage = (status, page) => res.status(status).type('html').send(page);
     try {
       const state = String(req.query.state || '');
-      const row = /^[0-9a-f]{16,128}$/i.test(state) ? await provisioning.getOAuthManifestByState(pool, state) : null;
+      const row = STATE_RE.test(state) ? await provisioning.getOAuthManifestByState(pool, state) : null;
       if (!row) {
         return sendPage(200, callbackPage({ ok: true, title: 'Installed on GitHub',
           body: '<p>GitHub has installed the app. Go back to your project’s page: it checks the install itself.</p><p><a class="btn" href="/projects?view=mine">Back to my projects →</a></p>' }));
@@ -109,5 +144,78 @@ module.exports = function buildGithubSetupRouter() {
     }
   });
 
+  // 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.
+  router.get('/provisioning/github-app/return', returnRateLimit, async (req, res) => {
+    res.set('Cache-Control', 'no-store');
+    res.set('Referrer-Policy', 'no-referrer');
+    const refuse = () => res.status(404).type('html').send(callbackPage({ ok: false, title: 'This isn’t your project',
+      body: '<p>This link is for a project on another account, or it has expired — sign in with the account that started the project, or open your own projects.</p><p><a class="btn" href="/projects?view=mine">My projects →</a></p>' }));
+    try {
+      const state = String(req.query.state || '');
+      if (!STATE_RE.test(state)) return refuse();
+      const session = await api.resolveSession(req);
+      if (!session) {
+        // the relative return passes the web flow's open-redirect guard (safeReturnTo);
+        // the repo scope rides every hub sign-in door (ADR 0364)
+        return res.redirect(302, `/api/bongos/auth/web/start?return=${encodeURIComponent(returnHref(state))}&repos=1`);
+      }
+      if (session.status === 'inactive') return refuse();
+      const row = await provisioning.getOAuthManifestByState(pool, state);
+      const inst = row ? await provisioning.getInstanceById(pool, row.instance_id).catch(() => null) : null;
+      if (!ownsLanding(inst, session.builder_id)) return refuse();
+      return res.redirect(302, landingHref(inst.id, state));
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/github-app/return', err);
+      return res.status(500).type('html').send(callbackPage({ ok: false, title: 'Something went wrong',
+        body: '<p>We couldn’t find your project just now — it is on your projects page.</p><p><a class="btn" href="/projects?view=mine">My projects →</a></p>' }));
+    }
+  });
+
+  // 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.
+  router.get('/provisioning/github-app/resume', api.requireBuilder, async (req, res) => {
+    try {
+      const me = req.builder && req.builder.id;
+      const asked = String(req.query.id || '');
+      if (asked) {
+        if (!/^\d{1,12}$/.test(asked)) return res.json({ ok: true, project: null });
+        const inst = await provisioning.getInstanceById(pool, Number(asked)).catch(() => null);
+        return res.json({ ok: true, project: ownsLanding(inst, me) ? resumeRecord(inst) : null });
+      }
+      const now = Date.now();
+      const owned = (await provisioning.listInstancesForOwner(pool, me)).filter((i) => ownsLanding(i, me)).slice(0, 5);
+      // the (at most five) candidates are read together; the newest unfinished one wins
+      const open = await Promise.all(owned.map(async (inst) => {
+        const row = await provisioning.getLatestOAuthManifestForInstance(pool, inst.id);
+        const touched = Math.max(Date.parse(inst.created_at) || 0, row ? Date.parse(row.created_at) || 0 : 0);
+        if (now - touched > RESUME_WINDOW_MS) return false;
+        const setup = await githubSetup.githubSetupRead(pool, inst, row, row ? provisioning.publicGithubApp(row).status : null, { withState: false });
+        return !setup.checklist.connected;
+      }));
+      const found = owned.find((_inst, i) => open[i]);
+      return res.json({ ok: true, project: found ? resumeRecord(found) : null });
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/github-app/resume', err);
+      return res.status(500).json({ ok: false, error: 'resume_read_failed' });
+    }
+  });
+
   return router;
 };

package/modules/public-landing/public/projects.html

@@ -4583,6 +4583,9 @@ summary{min-height:24px;padding:3px 0;}
        survives the GitHub round-trip; the server, not this page, names the terms version. */
     var DRAFT_KEY = 'cb-create-draft-v10';
     var CREATED_KEY = 'cb-created-instance';
+    /* the project "Start another project" set down (task 1004650): the server's resume
+       read does not pull this tab back to it */
+    var DECLINED_KEY = 'cb-resume-declined';
     /* `description` + `teamShape` are the optional About step (task 1002334) —
        both legitimately stay empty, and empty is what the create request omits. */
     /* `modules` is the picker's answer (task 1002339) and is THREE-VALUED like
@@ -6926,18 +6929,36 @@ summary{min-height:24px;padding:3px 0;}
       try { localStorage.setItem(AUTO_OPEN_KEY, box.checked ? '1' : '0'); } catch (e) {}
     });
 
-    /* ── C8: the wizard's polls run only on stage, exactly like the sky.
-       Off-view or hidden-tab, a due tick parks itself instead of fetching;
-       enter() and the visibility flip resume whatever was parked. ── */
+    /* ── C8: the wizard's polls run only while the create view is on stage, like the
+       sky. Off-view a due tick parks itself instead of fetching; enter() resumes it.
+       A HIDDEN tab is different (task 1004650): that is exactly when the founder is on
+       GitHub, in another tab or on their phone, so the polls keep checking there at a
+       slower pace (HIDDEN_POLL_MS), and the moment the tab is seen again a waiting tick
+       runs at once — the laptop's checklist ticks on its own. ── */
+    var HIDDEN_POLL_MS = 20000;
     function wizPollActive() {
-      return !document.hidden && currentView === 'new';
+      return currentView === 'new';
+    }
+    /* the next tick's wait: the poll's own pace while the tab is seen, the slow one while hidden */
+    function wizPollDelay(ms) {
+      return document.hidden ? Math.max(ms, HIDDEN_POLL_MS) : ms;
     }
     function resumePolls() {
       if (watchPending && instanceId) { watchPending = false; startProgress(instanceId); }
       if (manifestPending && manifestState) { manifestPending = false; pollManifest(manifestState); }
     }
+    /* each poll's waiting tick, so a return to the tab can run it now instead of later.
+       Only a WAITING tick is run (its timer is set): one mid-fetch re-arms itself, and
+       running it again would start a second chain. */
+    var progressKick = null, manifestKick = null;
+    function kickPolls() {
+      if (pollTimer && progressKick) { clearTimeout(pollTimer); pollTimer = null; progressKick(); }
+      if (manifestPollTimer && manifestKick) { clearTimeout(manifestPollTimer); manifestPollTimer = null; manifestKick(); }
+    }
     document.addEventListener('visibilitychange', function () {
-      if (wizPollActive()) resumePolls();
+      if (document.hidden || !wizPollActive()) return;
+      resumePolls();
+      kickPolls();
     });
 
     /* ── GitHub-App manifest flow (ADR 0133): mint a one-time state for OUR instance,
@@ -6957,6 +6978,17 @@ summary{min-height:24px;padding:3px 0;}
     var handbackState = (function () {
       try { var m = /[#&]ghstate=([0-9a-f]{16,128})/i.exec(location.hash || ''); return m ? m[1] : null; } catch (e) { return null; }
     })();
+    /* …and the PROJECT it is for (task 1004650): the return route resolves the state on
+       the server and lands its owner on ?view=new&id=<project>, so a phone, another
+       window or a fresh tab reaches the right project's part 03 with nothing in this
+       tab's storage. Read once at load, for the same reason as the state above. */
+    var handbackProject = (function () {
+      try {
+        var q = new URLSearchParams(location.search || '');
+        var id = q.get('view') === 'new' ? q.get('id') : null;
+        return id && /^\d{1,12}$/.test(id) ? id : null;
+      } catch (e) { return null; }
+    })();
     /* the manifest leg survives a reload: token + last status ride the CREATED
        record, so enter() re-seeds the step instead of re-offering "Set up
        GitHub sign-in" for an app the founder already approved (task 1003232) */
@@ -7045,6 +7077,7 @@ summary{min-height:24px;padding:3px 0;}
       function tick() {
         if (myGen !== manifestGen) return;
         if (!wizPollActive()) { manifestPending = true; stopManifestPoll(); return; }
+        manifestKick = tick;
         fetch(API + '/provisioning/github-app/status?state=' + encodeURIComponent(stateToken))
           .then(function (res) { if (!res.ok) throw new Error('soft'); return res.json(); })
           .then(function (d) {
@@ -7055,10 +7088,10 @@ summary{min-height:24px;padding:3px 0;}
             var failure = d.failure || null;
             if (next !== live.manifest || failure !== live.manifestFailure) { live.manifest = next; live.manifestFailure = failure; rememberManifest(undefined, next); renderSteps(); }
             else noteManifestWait();
-            if (!d.terminal) manifestPollTimer = setTimeout(tick, 4000);
+            if (!d.terminal) manifestPollTimer = setTimeout(tick, wizPollDelay(4000));
             else manifestPollTimer = null;   /* a stale fired id would read as "still polling" and resume a finished poll */
           })
-          .catch(function () { if (myGen === manifestGen) manifestPollTimer = setTimeout(tick, 8000); });
+          .catch(function () { if (myGen === manifestGen) manifestPollTimer = setTimeout(tick, wizPollDelay(8000)); });
       }
       tick();
     }
@@ -7249,6 +7282,7 @@ summary{min-height:24px;padding:3px 0;}
       function tick() {
         if (myGen !== watchGen) return;
         if (!wizPollActive()) { watchPending = true; stopPolling(); return; }
+        progressKick = tick;
         ticks += 1;
         if (ticks > 400) {
           /* ~33 min: this tab stops watching, but the standup keeps going — hand
@@ -7305,7 +7339,7 @@ summary{min-height:24px;padding:3px 0;}
             var terminal = renderProgress(inst);
             /* a GitHub leg still in flight keeps this read alive even once the
                project is up — after a reload it is the ONLY thing watching it */
-            if (!terminal || manifestInFlight() || setupOpen()) pollTimer = setTimeout(tick, 5000);
+            if (!terminal || manifestInFlight() || setupOpen()) pollTimer = setTimeout(tick, wizPollDelay(5000));
             else stopPolling();
           })
           .catch(function (err) {
@@ -7318,7 +7352,7 @@ summary{min-height:24px;padding:3px 0;}
               return;
             }
             /* transient (network / 5xx): keep the last view, try again a bit later */
-            pollTimer = setTimeout(tick, 10000);
+            pollTimer = setTimeout(tick, wizPollDelay(10000));
           });
       }
       tick();
@@ -7367,6 +7401,11 @@ summary{min-height:24px;padding:3px 0;}
         resetForNewProject();
         /* the deliberate goodbye: the record goes too, so nothing offers to resume
            the project the founder has just said they are finished watching */
+        try {
+          var gone = createdRecord();
+          if (gone && gone.id) sessionStorage.setItem(DECLINED_KEY, String(gone.id));
+        } catch (e) {}
+        serverRecord = null;
         try { sessionStorage.removeItem(CREATED_KEY); } catch (e) {}
         paintResumeOffer(null);
         show(1, true);
@@ -7810,8 +7849,11 @@ summary{min-height:24px;padding:3px 0;}
     })();
 
     /* ── the hub's three doors ── */
+    /* the server's resume answer (task 1004650), kept in memory too: a browser whose
+       storage throws still has the project it was handed */
+    var serverRecord = null;
     function createdRecord() {
-      try { return JSON.parse(sessionStorage.getItem(CREATED_KEY) || 'null'); } catch (e) { return null; }
+      try { return JSON.parse(sessionStorage.getItem(CREATED_KEY) || 'null') || serverRecord; } catch (e) { return serverRecord; }
     }
     /* The "still watching …" offer above step 1 (task 1003503). Its markup is baked
        into the panel, so this only names the project and shows or hides the line —
@@ -7876,6 +7918,12 @@ summary{min-height:24px;padding:3px 0;}
       /* restore the opt-out too — without it resolvedDomain() re-derives the
          assigned address and the done panel promises one that doesn't exist */
       state.noAddress = !!created.noaddr;
+      /* a record the server handed over (another device, a fresh tab) carries the repo
+         the project is on, so the install step names it (task 1004650) */
+      if (created.repo_ref && !state.repo) {
+        var rr = String(created.repo_ref).split('/');
+        if (rr.length === 2) { state.owner = rr[0]; state.repo = rr[1]; }
+      }
       /* a hand-back from the callback page names the attempt GitHub just approved */
       if (handbackState) {
         created.manifest_state = handbackState;
@@ -7898,9 +7946,54 @@ summary{min-height:24px;padding:3px 0;}
        identity settles it shows the draft step optimistically (the page stays
        usable while /me is in flight — the boot's own rule); onAuth() re-enters
        once the answer lands. Focus only moves on a deliberate nav (the flag). */
+    /* askServerResume(focus) — which project is this founder connecting, by the SERVER's
+       view, when this tab cannot say (task 1004650)? Asked once per page load. A hand-back
+       names its project (handbackProject, from the return route): it always lands on that
+       project's part 03, and only its owner gets an answer. With no name, the server picks
+       the founder's newest project whose GitHub is not connected yet: an arrival lands on
+       it unless something is being typed, and a deliberate "New project" only offers it on
+       the resume line. Nothing found → the page as it was. */
+    var resumeAsked = false;
+    function recordFromServer(p) {
+      return { id: p.id, slug: p.slug || '', name: p.slug || '', domain: p.domain || '', noaddr: !p.domain,
+        mode: p.onboard_mode === 'adopt' ? 'adopt' : 'greenfield', repo_ref: p.repo || null, at: Date.now(), from_server: true };
+    }
+    function askServerResume(focus) {
+      resumeAsked = true;
+      var named = handbackProject;
+      handbackProject = null;
+      return fetch(API + '/provisioning/github-app/resume' + (named ? '?id=' + encodeURIComponent(named) : ''), { credentials: 'same-origin' })
+        .then(function (res) { return res.ok ? res.json() : null; })
+        .catch(function () { return null; })
+        .then(function (d) {
+          var p = d && d.project;
+          var had = createdRecord();
+          if (!p || !p.id || (!named && had && had.id)) { if (named) enter(focus); return; }
+          var declined = null;
+          try { declined = sessionStorage.getItem(DECLINED_KEY); } catch (e) {}
+          if (!named && declined === String(p.id)) return;
+          var rec = recordFromServer(p);
+          /* the same project this tab already knew keeps what it knew (a demo's teammates) */
+          if (had && String(had.id) === String(p.id)) rec = Object.assign({}, had, rec, { name: had.name || rec.name });
+          else if (had && had.id) resetForNewProject();   /* a hand-back for a different project */
+          serverRecord = rec;
+          try { sessionStorage.setItem(CREATED_KEY, JSON.stringify(rec)); } catch (e) {}
+          if (currentView !== 'new') return;
+          if (named || (!focus && !String(state.name || '').trim())) { resumeIntent = true; enterCreated(rec, false); }
+          else paintResumeOffer(rec);
+        });
+    }
+
     function enter(focus) {
       if (authKnown && !me) { show(0, !!focus); return; }
       var created = authKnown ? createdRecord() : null;
+      /* this tab cannot say which project — ask the server (task 1004650). A named
+         hand-back waits for that answer instead of painting another project first. */
+      if (authKnown && !resumeAsked && (handbackProject || !(created && created.id))) {
+        var waitForIt = !!handbackProject;
+        askServerResume(!!focus);
+        if (waitForIt) return;
+      }
       /* A draft on the page (step 1) beside a stored create is a SECOND project being
          typed. A reload or a GitHub round-trip (repo access) is that same visit
          continuing, so the draft keeps its place and the earlier project stays one

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.94",
+  "version": "1.21.95",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.94",
+      "version": "1.21.95",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.94",
+  "version": "1.21.95",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -9394,5 +9394,11 @@
       "id": "1004649",
       "text": "Connecting GitHub to a new project is now one trip. The founder clicks \"Connect GitHub\", approves the project's app on GitHub, and GitHub carries straight on to installing it on their repo (already picked when the repo is publ"
     }
+  ],
+  "1.21.95": [
+    {
+      "id": "1004650",
+      "text": "Connecting GitHub no longer depends on staying in one browser tab. After you approve on GitHub, even on your phone or in another window, you land back on your own project's GitHub checklist. Our server remembers which project"
+    }
   ]
 }

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.94'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.95'; // 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');