@bongos/core 1.25.16 → 1.25.17

package/modules/provisioning/render-sandbox.js

@@ -0,0 +1,113 @@
+// modules/provisioning/render-sandbox.js — the web tier's half of a project's SANDBOX on
+// Render (task 1005289; ADR 0406, ADR 0327).
+//
+// WHY. Every project whose app runs on Render gets a second, free app from the same
+// repository that follows `main`, so finished work reaches a test copy first (ADR 0406 §2).
+// A new connection asks for one by itself (render-standup.js appHostFrom sets
+// `sandboxWanted`); an existing project adds one here with one action; the owner reads its
+// address and state beside the app's, in the same shape (app-status.js); and a teardown
+// removes it when the owner lends their key with it.
+//
+// Like the rest of this module the web tier never calls Render (ADR 0111 §2): it queues a
+// `render-standup` intent carrying the encrypted key, and the runner
+// (scripts/bongos/provision-render-sandbox.js) does the work and clears the key.
+'use strict';
+
+const { appStatus } = require('./app-status');
+
+// The sandbox's own database starts EMPTY: the platform cannot know an app's tables, so
+// the fake data is the app's own seed, run when it sees BONGOS_SANDBOX=1 (the starter's
+// half, task 1005291). Said to the owner plainly rather than promised.
+const READY_DB_NOTE = 'It has its own database, separate from your live data. It starts empty: your app fills it with test data when it runs as a sandbox.';
+
+// Why a project cannot have a sandbox right now, in the owner's words, or null.
+function noSandboxReason(inst) {
+  const h = (inst && inst.app_host) || {};
+  if (!inst || inst.status === 'torn_down' || inst.status === 'tearing_down') return 'This project has been removed, so it has no sandbox.';
+  if (!h.platform) return 'Your project has no app yet, so there is nothing to run in a sandbox. One is set up as soon as you connect your app to Render.';
+  if (h.platform !== 'render') return 'Sandboxes are set up on Render only, and your app runs somewhere else.';
+  if (!h.serviceId || !['deploying', 'linked', 'live'].includes(h.state)) return 'Your app is not set up on Render yet. Its sandbox is set up with it.';
+  return null;
+}
+
+// The owner's view of the sandbox: app-status.js's shape (stage, address, links, a
+// failure as one sentence) plus what its database is and whether one can be added.
+// Read from the row alone.
+function sandboxStatus(inst, { now = Date.now() } = {}) {
+  const h = (inst && inst.app_host) || {};
+  const sb = h.sandbox;
+  const live = !sb || sb.state === 'removed';
+  if (live && !h.sandboxWanted) {
+    const why = noSandboxReason(inst);
+    return { state: 'none', message: why || 'This project has no sandbox yet.', can_add: !why };
+  }
+  if (!sb || sb.state === 'requested') {
+    const why = h.platform === 'render' && h.state === 'failed' ? 'Your app’s setup on Render stopped, so its sandbox is waiting for it.' : null;
+    return { state: 'requested', stage: 'creating', message: why || 'Your sandbox is set up right after your app.', can_add: false };
+  }
+  if (sb.state === 'left') return { state: 'left', error: sb.error || 'The sandbox is still on your Render account.', can_add: false };
+  const s = appStatus({ platform: 'render', state: sb.state, serviceId: sb.serviceId, serviceUrl: sb.serviceUrl, updatedAt: sb.updatedAt, error: sb.error }, { now });
+  return {
+    ...s,
+    retry: undefined,
+    plan: 'free',
+    follows: 'main',
+    database: { state: sb.database || 'none', note: sb.dbNote || (sb.database === 'ready' ? READY_DB_NOTE : null) },
+    can_add: sb.state === 'failed' && !noSandboxReason(inst),
+  };
+}
+
+// Queue an existing project's sandbox: a render-standup intent holding the key, and the
+// row marked to want one, in ONE statement — the enqueueRenderStandup pattern, so an
+// open-intent collision keeps nothing. Returns { intent } or { conflict, intent }.
+async function enqueueSandboxAdd(db, instanceId, { keyEnc, requestedBy }) {
+  await require('./control-plane-guard').assertIntentAllowed(db, instanceId, 'render-standup');
+  try {
+    const { rows } = await db.query(
+      `WITH i AS (
+         INSERT INTO provisioning_intents (instance_id, action, requested_by, state, borrowed_key_enc)
+         VALUES ($1, 'render-standup', $2, 'pending', $3) RETURNING *
+       ), u AS (
+         UPDATE provisioning_instances
+            SET app_host = app_host || jsonb_build_object('sandboxWanted', true,
+                  'sandbox', COALESCE(app_host->'sandbox', '{}'::jsonb) || jsonb_build_object('state', 'requested', 'error', NULL))
+          WHERE id = $1 RETURNING id
+       )
+       SELECT i.id, i.instance_id, i.action, i.state, i.created_at FROM i`,
+      [instanceId, requestedBy ?? null, keyEnc]);
+    return { intent: rows[0] };
+  } catch (e) {
+    if (e && e.code === '23505') {
+      const { rows } = await db.query(
+        `SELECT id, action, state FROM provisioning_intents
+          WHERE instance_id = $1 AND state IN ('pending', 'running') ORDER BY created_at DESC LIMIT 1`, [instanceId]);
+      return { conflict: 'open_intent', intent: rows[0] || { action: 'unknown', state: 'open' } };
+    }
+    throw e;
+  }
+}
+
+// Put the owner's key on a teardown that is still pending, so the runner can remove the
+// sandbox (and only the sandbox). The table's CHECK refuses a key on a resolved intent.
+async function lendKeyToTeardown(db, intentId, keyEnc) {
+  const { rowCount } = await db.query(
+    `UPDATE provisioning_intents SET borrowed_key_enc = $2, updated_at = now()
+      WHERE id = $1 AND action = 'teardown' AND state = 'pending'`, [intentId, keyEnc]);
+  return rowCount > 0;
+}
+
+// The teardown route's half: the owner's Render key, sent as the `x-render-key` header
+// (a header, not a body: the kernel's audit log keeps a copy of write bodies), lent to the
+// teardown just queued so the runner can remove the sandbox. Returns whether it was lent.
+// A missing or malformed key, a teardown that was not just created, or a platform that
+// cannot seal a key safely each lend nothing, and the teardown goes ahead without it.
+const KEY_RE = /^rnd_[A-Za-z0-9]{16,128}$/;
+async function lendKeyFromRequest(db, req, teardown, secretBox) {
+  if (!teardown || !teardown.created || !teardown.intent) return false;
+  const key = String((req.headers && req.headers['x-render-key']) || '').trim();
+  if (!KEY_RE.test(key)) return false;
+  if (!secretBox || !secretBox.isConfigured()) return false;
+  return module.exports.lendKeyToTeardown(db, teardown.intent.id, secretBox.encrypt(key)); // through the export, so a test can stand in for the write
+}
+
+module.exports = { noSandboxReason, sandboxStatus, enqueueSandboxAdd, lendKeyToTeardown, lendKeyFromRequest };

package/modules/provisioning/render-standup.js

@@ -84,7 +84,9 @@ function badRequest(body) {
 
 // What the row records about the request — ids and plans, never the key.
 function appHostFrom(body) {
-  const h = { platform: 'render', mode: body.mode, ownerId: body.owner_id, state: 'requested', error: null };
+  // Every app on Render gets a sandbox beside it (ADR 0406, task 1005289): the runner sets
+  // it up after the app, with the same key (scripts/bongos/provision-render-sandbox.js).
+  const h = { platform: 'render', mode: body.mode, ownerId: body.owner_id, state: 'requested', error: null, sandboxWanted: true };
   if (body.mode === 'adopt') h.serviceId = body.service_id;
   if (body.mode === 'greenfield') {
     h.runtime = body.runtime;

package/modules/provisioning/routes/provisioning.js

@@ -50,6 +50,7 @@
 const crypto = require('node:crypto');
 const express = require('express');
 const api = require('../../../src/module-api');
+const renderSandbox = require('../render-sandbox');
 const auth = api, { pool, validateOrRespond, parseId } = api;
 const provisioning = require('../provisioning');
 const { costLedger, ownerMonthlyUsd } = require('../cost-ledger');
@@ -1002,6 +1003,8 @@ module.exports = function provisioningRoutes() {
           message: `A '${r.intent.action}' run is currently ${r.intent.state} for this instance — the teardown could not be queued; retry in a moment.`,
           details: { action: r.intent.action, state: r.intent.state } });
       }
+      // An optional Render key (x-render-key) lets the runner remove the project's sandbox — never the live app (ADR 0406 §7, task 1005289).
+      const lent = await renderSandbox.lendKeyFromRequest(pool, req, r, api.secretBox);
       if (r.created) {
         const who = isProjectOwner(inst, req.builder) ? 'owner' : `archon ${req.builder.github_login || req.builder.id}`;
         await provisioning.recordEvent(pool, {
@@ -1010,7 +1013,7 @@ module.exports = function provisioningRoutes() {
           actor,
         }).catch(() => {});
       }
-      res.json({ ok: true, queued: r.created, action: 'teardown', status: inst.status, superseded: r.superseded,
+      res.json({ ok: true, queued: r.created, action: 'teardown', status: inst.status, superseded: r.superseded, sandbox_key_lent: lent,
         message: r.created ? 'Your instance will be torn down shortly.' : 'A teardown is already queued for that instance.' });
     } catch (err) {
       log.error('[provisioning] POST /provisioning/instances/:id/teardown', err);

package/modules/provisioning/routes/render-standup.js

@@ -25,6 +25,7 @@ const renderStandup = require('../render-standup');
 const { failFrom } = require('../public-refusal');
 const { lookupRender, RenderLookupError } = require('../render-lookup');
 const { appStatus } = require('../app-status');
+const renderSandbox = require('../render-sandbox');
 const envManifest = require('../env-manifest');
 const { makeAskRateLimiter } = require('../rate-limit');
 
@@ -51,6 +52,8 @@ module.exports = function buildRenderStandupRouter({ fetchImpl } = {}) {
   const router = express.Router();
   const lookupLimit = makeAskRateLimiter({ windowMs: 60_000, max: 20, key: (req) => `b:${req.builder && req.builder.id}` });
   const statusLimit = makeAskRateLimiter({ windowMs: 60_000, max: 60, key: (req) => `s:${req.builder && req.builder.id}` });
+  // Adding a sandbox queues work on the owner's account, so a handful a minute is plenty.
+  const sandboxLimit = makeAskRateLimiter({ windowMs: 60_000, max: 10, key: (req) => `x:${req.builder && req.builder.id}` });
 
   // POST /provisioning/render/lookup — rank: any authenticated builder. What the owner's
   // Render key can see: its workspaces, and the web services in the one they name. The
@@ -100,13 +103,58 @@ module.exports = function buildRenderStandupRouter({ fetchImpl } = {}) {
       const envVars = app && app.state !== 'disconnected'
         ? (await envManifest.listEnvVars(pool, id)).map((v) => ({ name: v.name, required: v.required !== false, set_for_you: dbSet && v.name === 'DATABASE_URL' }))
         : [];
-      res.json({ ok: true, app, env_vars: envVars, values_held: false });
+      // The sandbox beside it (ADR 0406, task 1005289), in the same shape.
+      const sandbox = renderSandbox.sandboxStatus(inst);
+      res.json({ ok: true, app, sandbox, env_vars: envVars, values_held: false });
     } catch (err) {
       log.error('[provisioning] GET /provisioning/instances/:id/render', err && err.message);
       failFrom(res, err, 'render_status_failed');
     }
   });
 
+  // POST /provisioning/instances/:id/render/sandbox — rank: any authenticated builder, and
+  // OWNER ONLY, like every Render route. An app already on Render adds its sandbox with
+  // one action (ADR 0406, task 1005289): the owner lends the key once, and the runner sets
+  // up a free app that follows main, beside the live one, which it does not touch. A
+  // project with no app on Render is told why it has none. The reply is a receipt.
+  router.post('/provisioning/instances/:id/render/sandbox', api.requireBuilder, sandboxLimit, async (req, res) => {
+    const id = parseId(req, res, { positiveInt: true });
+    if (!id) return;
+    if (validateOrRespond(req, res, { key: { required: true, type: 'string', maxLength: 200 } })) return;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!ownedBy(inst, req.builder)) return res.fail('instance_not_found', 404);
+      if (!renderStandup.KEY_RE.test(req.body.key)) {
+        return res.fail('render_request_invalid', { status: 400, message: 'That doesn’t look like a Render API key. It starts with “rnd_”.' });
+      }
+      const why = renderSandbox.noSandboxReason(inst);
+      if (why) return res.fail('sandbox_unavailable', { status: 409, message: why });
+      const sb = inst.app_host && inst.app_host.sandbox;
+      if (sb && ['creating', 'deploying', 'live'].includes(sb.state)) {
+        return res.fail('sandbox_exists', { status: 409, message: 'This project already has a sandbox.' });
+      }
+      if (!api.secretBox.isConfigured()) {
+        return res.fail('render_unavailable', { status: 503, message: 'The platform can’t take a key safely right now, so nothing was sent. Try again later.' });
+      }
+      const r = await renderSandbox.enqueueSandboxAdd(pool, id, { keyEnc: api.secretBox.encrypt(req.body.key), requestedBy: 'api:self' });
+      if (r.conflict) {
+        return res.fail('intent_conflict', { status: 409,
+          message: `A '${r.intent.action}' run is ${r.intent.state} for this project, so your key was not kept. Try again once it has finished.`,
+          details: { action: r.intent.action, state: r.intent.state } });
+      }
+      await provisioning.recordEvent(pool, {
+        instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'render-standup',
+        detail: 'Render sandbox requested by owner', actor: 'api:self',
+      }).catch(() => {});
+      res.json({ ok: true, queued: true, action: 'render-standup', sandbox: true,
+        message: 'Queued. The platform will add a free sandbox app on your Render account that updates with every finished change. Your live app is not touched. Your key is used once and then thrown away.' });
+    } catch (err) {
+      // Never log the request: it carries the key.
+      log.error('[provisioning] POST /provisioning/instances/:id/render/sandbox', err && err.message);
+      failFrom(res, err, 'render_sandbox_failed');
+    }
+  });
+
   // POST /provisioning/instances/:id/render — rank: any authenticated builder, and OWNER
   // ONLY: the key is the owner's and so is the account it acts in, so an archon on
   // someone else's project gets the same 404 as a stranger. The reply is a receipt;

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

@@ -2250,7 +2250,13 @@ summary{min-height:24px;padding:3px 0;}
      wires. null when there is nothing to show (no platform chosen). */
   function appStatusView(data) {
     var app = data && data.app;
-    if (!app) return null;
+    if (!app) {
+      /* no app on Render yet: the sandbox says plainly why it has none (task 1005289) */
+      if (!data || !data.sandbox || data.sandbox.state !== 'none') return null;
+      var nv = { root: appEl('div', 'appStat') };
+      sandboxView(data.sandbox, nv);
+      return nv;
+    }
     var v = { root: appEl('div', 'appStat') };
     if (app.state === 'disconnected') {
       v.root.appendChild(appPara(['This project is no longer connected to Render. Its services there are still yours; remove them in Render if you want to stop paying.']));
@@ -2304,6 +2310,7 @@ summary{min-height:24px;padding:3px 0;}
       }
     }
     if (app.links) v.root.appendChild(appPara([appLink(app.links.service, 'Open it on Render')]));
+    sandboxView(data.sandbox, v);
     var vars = (data.env_vars || []).filter(function (x) { return !x.set_for_you; });
     if (vars.length) {
       v.root.appendChild(appEl('h3', null, 'Still to set on Render'));
@@ -2320,7 +2327,59 @@ summary{min-height:24px;padding:3px 0;}
     }
     return v;
   }
-  function appTerminal(data) { var a = data && data.app; return !a || a.state === 'disconnected' || !!a.error || a.stage === 'live'; }
+  /* ── the project's sandbox (task 1005289, ADR 0406) ──
+     A free copy of the app on the owner's Render account that takes every finished change
+     first; the live app moves only when a person promotes. Same server-shaped answer as
+     the app's (`data.sandbox`), drawn beside it, node by node. "Add a sandbox" asks for the
+     key once, like every Render action, and never keeps it. */
+  var mSandboxOn = {};   /* project id → has a sandbox to remove, so the teardown asks for the key only then */
+  /* the stage word is the app's own (APP_STAGES), so one page never names one stage two ways */
+  function stageWord(stage) {
+    var s = stage === 'quiet' ? 'building' : stage;
+    for (var i = 0; i < APP_STAGES.length; i++) if (APP_STAGES[i][0] === s) return APP_STAGES[i][1];
+    return APP_STAGES[0][1];
+  }
+  function sandboxView(sb, v) {
+    if (!sb) return;
+    var box = appEl('div', 'appSandbox');
+    box.appendChild(appEl('h3', null, 'Sandbox'));
+    box.appendChild(appPara(['A free test copy of your app. Every finished change reaches it first; your live app only changes when you promote it.'], 'finePrint'));
+    if (sb.state === 'none' || sb.state === 'requested' || sb.state === 'left') {
+      box.appendChild(appPara([String(sb.error || sb.message || '')], sb.state === 'left' ? 'err' : null));
+    } else if (sb.error) {
+      box.appendChild(appPara([String(sb.error)], 'err'));
+    } else {
+      var line = [stageWord(sb.stage)];
+      if (sb.url) line.push(' at ', appLink(sb.url, String(sb.url).replace(/^https:\/\//, '')));
+      line.push('. It sleeps when nobody visits and takes about a minute to wake.');
+      box.appendChild(appPara(line));
+      if (sb.links) box.appendChild(appPara([appLink(sb.links.service, 'Open the sandbox on Render')]));
+    }
+    if (sb.database && sb.database.note) box.appendChild(appPara([String(sb.database.note)], 'finePrint'));
+    if (sb.can_add) {
+      v.sbBtn = appEl('button', 'btn ghost small appSbBtn', sb.state === 'none' ? 'Add a sandbox' : 'Try the sandbox again');
+      v.sbBtn.type = 'button';
+      box.appendChild(v.sbBtn);
+      v.sbForm = appEl('div', 'appRetry appSbForm');
+      v.sbForm.hidden = true;
+      var lab = appEl('label', 'wizField');
+      lab.appendChild(appEl('span', null, 'Render API key'));
+      v.sbKey = appEl('input', 'appRetryKey');
+      v.sbKey.type = 'password'; v.sbKey.autocomplete = 'off'; v.sbKey.spellcheck = false; v.sbKey.maxLength = 200; v.sbKey.placeholder = 'rnd_…';
+      lab.appendChild(v.sbKey);
+      v.sbForm.appendChild(lab);
+      v.sbSend = appEl('button', 'btn small', 'Add the sandbox');
+      v.sbSend.type = 'button';
+      v.sbForm.appendChild(v.sbSend);
+      v.sbHint = appEl('div', 'hint appRetryHint', 'Free on Render. Your key is used once and thrown away.');
+      v.sbHint.setAttribute('role', 'status');
+      v.sbForm.appendChild(v.sbHint);
+      box.appendChild(v.sbForm);
+    }
+    v.root.appendChild(box);
+  }
+  function sandboxSettled(sb) { return !sb || ['none', 'left', 'removed'].indexOf(sb.state) >= 0 || !!sb.error || sb.stage === 'live' || sb.stage === 'quiet'; }
+  function appTerminal(data) { var a = data && data.app; return (!a || a.state === 'disconnected' || !!a.error || a.stage === 'live') && sandboxSettled(data && data.sandbox); }
   function fetchAppStatus(id) {
     return fetch(API + '/provisioning/instances/' + encodeURIComponent(id) + '/render', { credentials: 'same-origin' })
       .then(function (res) { return res.ok ? res.json() : null; })
@@ -2337,6 +2396,8 @@ summary{min-height:24px;padding:3px 0;}
     function paint(data) {
       if (stopped || !alive()) return;
       last = data;
+      var sbNow = data && data.sandbox;
+      mSandboxOn[String(id)] = !!(sbNow && (sbNow.links || sbNow.url));
       /* never repaint over a Retry the owner has opened — it holds a key they are typing */
       /* …whether this watch opened it or an earlier one on the same box did (the project
          page starts a fresh watch on every reload of the project) */
@@ -2352,6 +2413,7 @@ summary{min-height:24px;padding:3px 0;}
     }
     function tick() { fetchAppStatus(id).then(paint); }
     function wire(v) {
+      if (v.sbBtn) wireSandbox(v);
       if (!v.retryBtn) return;
       v.retryBtn.addEventListener('click', function () {
         v.retryForm.hidden = false; v.retryBtn.hidden = true; v.keyEl.focus();
@@ -2381,6 +2443,30 @@ summary{min-height:24px;padding:3px 0;}
         });
       });
     }
+    function wireSandbox(v) {
+      v.sbBtn.addEventListener('click', function () { v.sbForm.hidden = false; v.sbBtn.hidden = true; v.sbKey.focus(); });
+      v.sbSend.addEventListener('click', function () {
+        var key = String(v.sbKey.value || '').trim();
+        if (!/^rnd_[A-Za-z0-9]{16,128}$/.test(key)) {
+          v.sbHint.textContent = 'That doesn’t look like a Render API key. It starts with “rnd_”.'; v.sbHint.className = 'hint appRetryHint err'; return;
+        }
+        var body = JSON.stringify({ key: key });
+        v.sbKey.value = ''; key = '';
+        v.sbSend.disabled = true; v.sbHint.textContent = 'Handing it to Render…'; v.sbHint.className = 'hint appRetryHint';
+        fetch(API + '/provisioning/instances/' + encodeURIComponent(id) + '/render/sandbox', {
+          method: 'POST', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' }, body: body
+        }).then(function (res) {
+          body = '';
+          return res.json().catch(function () { return {}; }).then(function (d) {
+            if (!res.ok) throw new Error((d.error && d.error.message) || 'The sandbox could not be queued.');
+            v.sbForm.hidden = true; view = null; clearTimeout(t); ticks = 0; tick();
+          });
+        }).catch(function (err) {
+          body = '';
+          v.sbSend.disabled = false; v.sbHint.textContent = err.message; v.sbHint.className = 'hint appRetryHint err';
+        });
+      });
+    }
     tick();
     return function stop() { stopped = true; clearTimeout(t); };
   }
@@ -11095,7 +11181,12 @@ summary{min-height:24px;padding:3px 0;}
       '<input type="text" id="mDelName" autocomplete="off" spellcheck="false" maxlength="40" ' +
       'aria-label="Type the project name to confirm" placeholder="' + esc(inst.slug) + '">' +
       '<button type="button" class="btn small danger" data-del-yes disabled>Yes, tear it down</button>' +
-      '<button type="button" class="linklike" data-del-no>Keep it</button></div>');
+      '<button type="button" class="linklike" data-del-no>Keep it</button></div>' +
+      (mSandboxOn[String(inst.id)]
+        ? '<label class="wizField"><span>Render API key, to remove its sandbox too (optional)</span>' +
+          '<input type="password" id="mDelRenderKey" autocomplete="off" spellcheck="false" maxlength="200" placeholder="rnd_…"></label>' +
+          '<p class="finePrint">Only the free sandbox is removed. Your live app on Render is left as it is. The key is used once and thrown away; without it the sandbox stays on your Render account for you to remove.</p>'
+        : ''));
     var field = $('mDelName');
     if (field) field.focus();
   }
@@ -11126,11 +11217,17 @@ summary{min-height:24px;padding:3px 0;}
     /* the typed name is this page's own gate, never the server's — so a click
        on a button that only LOOKS enabled cannot act */
     if (!inst || !delTypedMatches()) return;
+    var rkField = $('mDelRenderKey');
+    var rk = rkField ? String(rkField.value || '').trim() : '';
+    var headers = { 'Content-Type': 'application/json' };
+    if (/^rnd_[A-Za-z0-9]{16,128}$/.test(rk)) headers['x-render-key'] = rk;
+    rk = '';
     mDelAsking = null;
     delMsg('<p class="finePrint">Asking…</p>');
     fetch(API + '/provisioning/instances/' + encodeURIComponent(inst.id) + '/teardown', {
-      method: 'POST', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' }, body: '{}'
+      method: 'POST', credentials: 'same-origin', headers: headers, body: '{}'
     }).then(function (res) {
+      delete headers['x-render-key'];
       return jsonOrEmpty(res).then(function (data) {
         if (res.ok) {
           var note = esc(data.message || 'Teardown requested.');

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.25.16",
+  "version": "1.25.17",
   "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

@@ -11824,5 +11824,15 @@
       "id": "1005116",
       "text": "Founders now write their own strategy. Each setup stage can be done three ways: answer guided questions, write it freely, or get help from your own AI — and you can switch at any time without losing anything. Your answers are"
     }
+  ],
+  "1.25.17": [
+    {
+      "id": "1005289",
+      "text": "Every project on Render now gets a free test copy of its app that takes each finished change first, shown beside the live site, added in one click for existing projects and removed when the project is taken down."
+    },
+    {
+      "id": "1005280",
+      "text": "Owners bringing in an existing project get a prompt for their own AI to read the code and map goals, tasks and what's broken; they then choose what Bongos files as drafts."
+    }
   ]
 }

package/scripts/bongos/first-read.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// scripts/bongos/first-read.js — `bongos first-read`: the command the owner's own AI
+// session runs during the first read-through of a project that already exists (task
+// 1005280, goal 1000106).
+//
+// The session reads the repository on the owner's computer and subscription, writes a
+// map, and uses this to hand it to Bongos. Nothing here sends repository content: only
+// the map file the session wrote, which `check` validates locally first with the same
+// rules the server applies (modules/lifecycle/first-read.js).
+//
+//   bongos first-read prompt                 print the prompt and the map's shape
+//   bongos first-read check  <map.json>      validate locally (no network)
+//   bongos first-read submit <map.json>      send it for review — files nothing
+//   bongos first-read show   [<map id>]      the newest map (or one), with what is filed
+//   bongos first-read accept <map id> --all | --items <ref>,<ref>   ONLY with the owner's yes
+//   bongos first-read reject <map id>        the owner's no — files nothing
+
+'use strict';
+
+const fs = require('node:fs');
+const fr = require('../../modules/lifecycle/first-read');
+
+function readMap(file) {
+  if (!file) { console.error(`usage: bongos first-read check|submit <${fr.MAP_FILE}>`); process.exit(2); }
+  let text;
+  try { text = fs.readFileSync(file, 'utf8').replace(/^/, ''); } catch (e) { console.error(`Cannot read ${file}: ${e.message}`); process.exit(2); }
+  try { return JSON.parse(text); } catch (e) { console.error(`${file} is not valid JSON: ${e.message}`); process.exit(1); }
+}
+
+function printErrors(errors) {
+  console.error('The map needs fixing:');
+  for (const e of errors) console.error(`  - ${e}`);
+}
+
+function printItems(items) {
+  for (const i of items) {
+    const mark = i.filed ? '  [already in Bongos]' : '';
+    const indent = i.type === 'goal' ? '' : '    ';
+    console.log(`${indent}${i.type.padEnd(4)}  ${i.title}${mark}\n${indent}      ref: ${i.ref}`);
+  }
+}
+
+// A refusal prints and returns null; the caller then ends with cliExit — never a hard
+// process.exit after a request (the Windows abort in scripts/bongos/CLAUDE.md).
+async function call(method, path, body) {
+  const { apiCall } = require('./cli-lib');
+  const res = await apiCall(method, path, body);
+  if (!res.ok) {
+    const d = res.data || {};
+    console.error(`Bongos refused (${res.status}): ${d.error || d.code || 'error'}`);
+    if (Array.isArray(d.errors)) printErrors(d.errors);
+    if (d.unknown) console.error(`  unknown refs: ${d.unknown.join(', ')}`);
+    if (d.hint || d.message) console.error(`  ${d.hint || d.message}`);
+    return null;
+  }
+  return res.data;
+}
+
+const fail = () => require('./cli-lib').cliExit(1);
+const flag = (name) => { const i = process.argv.indexOf(name); return i === -1 ? null : (process.argv[i + 1] || ''); };
+
+(async () => {
+  const [verb, arg] = process.argv.slice(2);
+  switch (verb) {
+    case 'prompt':
+      console.log(fr.firstReadPrompt());
+      return;
+    case 'check': {
+      const v = fr.validateRepoMap(readMap(arg));
+      if (!v.ok) { printErrors(v.errors); process.exit(1); }
+      console.log(`The map is in the right shape: ${v.items.length} items.`);
+      printItems(v.items);
+      return;
+    }
+    case 'submit': {
+      const raw = readMap(arg);
+      const v = fr.validateRepoMap(raw);
+      if (!v.ok) { printErrors(v.errors); process.exit(1); }
+      const out = await call('POST', '/api/bongos/first-read/maps', { map: raw });
+      if (!out) return fail();
+      console.log(`Sent as map ${out.map_id}. Nothing is filed yet.`);
+      printItems(out.items);
+      console.log(`\nWalk the owner through it. Only with their yes:\n  bongos first-read accept ${out.map_id} --all\n  bongos first-read accept ${out.map_id} --items <ref>,<ref>\nor, if they want none of it:\n  bongos first-read reject ${out.map_id}`);
+      return;
+    }
+    case 'show': {
+      const out = await call('GET', `/api/bongos/first-read/maps/${arg || 'latest'}`);
+      if (!out) return fail();
+      console.log(`Map ${out.map_id} (${out.status})\n${out.summary}\n`);
+      printItems(out.items);
+      return;
+    }
+    case 'accept': {
+      if (!arg) { console.error('usage: bongos first-read accept <map id> --all | --items <ref>,<ref>'); process.exit(2); }
+      const list = flag('--items');
+      const items = process.argv.includes('--all') ? 'all' : (list ? list.split(',').map((s) => s.trim()).filter(Boolean) : null);
+      if (!items || (Array.isArray(items) && !items.length)) { console.error('Say what the owner accepted: --all, or --items <ref>,<ref>.'); process.exit(2); }
+      const out = await call('POST', `/api/bongos/first-read/maps/${arg}/accept`, items === 'all' ? { all: true } : { items });
+      if (!out) return fail();
+      console.log(`Filed as drafts: ${out.filed.goals.length} goals, ${out.filed.tasks.length} tasks (tasks wait in backlog until promoted).`);
+      for (const g of out.filed.goals) console.log(`  goal ${g.id}  ${g.title}`);
+      for (const t of out.filed.tasks) console.log(`  task ${t.id}  ${t.title}`);
+      for (const s of out.skipped) console.log(`  skipped ${s.ref} (${s.reason.replace('_', ' ')})`);
+      return;
+    }
+    case 'reject': {
+      if (!arg) { console.error('usage: bongos first-read reject <map id>'); process.exit(2); }
+      if (!(await call('POST', `/api/bongos/first-read/maps/${arg}/reject`, {}))) return fail();
+      console.log(`Map ${arg} rejected. Nothing was filed.`);
+      return;
+    }
+    default:
+      console.log('usage: bongos first-read prompt | check <file> | submit <file> | show [id] | accept <id> --all|--items a,b | reject <id>');
+      process.exit(verb ? 2 : 0);
+  }
+})().catch((e) => { console.error(e.message || e); process.exitCode = 1; });

package/scripts/bongos/government-walk.js

@@ -73,10 +73,8 @@ const ACTIVE_IDS = BUILDERS.filter((b) => b.status === 'active').map((b) => b.id
 const FOUNDER = '42';
 const COUNCIL = ['43', '44'];
 
-// Each bound route as a request that, as today, stops in its handler's own first
-// check (a bad id or body) before any database write — the same requests as
-// tests/government_act_alone_buildings.mjs, with People's two carrying a real
-// custom rank and builder of this project.
+// Each bound route as a request that stops in its handler's first check (bad id or body),
+// before any DB write — as tests/government_act_alone_buildings.mjs; People's two carry a real rank + builder.
 const BAD = 'x';
 const REQUESTS = Object.freeze({
   'PATCH /project-settings/rot-days': ['PATCH', '/project-settings/rot-days', { days: 'soon' }],
@@ -98,6 +96,7 @@ const REQUESTS = Object.freeze({
   'POST /goals/reorder': ['POST', '/goals/reorder', {}],
   'POST /work-categories': ['POST', '/work-categories', {}],
   'PUT /versions/focus': ['PUT', '/versions/focus', { version_id: '   ' }],
+  'POST /first-read/maps/:id/accept': ['POST', `/first-read/maps/${BAD}/accept`, { all: true }],
   'POST /autonomy/fence': ['POST', '/autonomy/fence', { enabled: 'yes' }],
   'POST /autonomy/fence/goals': ['POST', '/autonomy/fence/goals', { goal_id: 0 }],
   'DELETE /autonomy/fence/goals/:goalId': ['DELETE', `/autonomy/fence/goals/${BAD}`],
@@ -141,6 +140,7 @@ const ROUTERS = Object.freeze([
   'modules/lifecycle/routes/goals.js',
   'modules/lifecycle/routes/versions.js',
   'modules/lifecycle/routes/project-settings.js',
+  'modules/lifecycle/routes/first-read.js',
   'modules/render-deploy/routes/act.js',
   'modules/npm-release/routes/release.js',
   'modules/provisioning/routes/core-upgrade.js',