@bongos/core 1.19.954 → 1.19.956

package/modules/provisioning/routes/env-manifest.js

@@ -0,0 +1,201 @@
+// modules/provisioning/routes/env-manifest.js — the project ENV VAR MANIFEST's HTTP
+// surface (task 1004062, ADR 0323 decision 6).
+//
+//   own-scoped (requireBuilder — the caller's OWN project; archon may read/edit any):
+//     GET    /provisioning/instances/:id/env-manifest          — the declared surface
+//     POST   /provisioning/instances/:id/env-manifest          — declare (or re-declare) one
+//     PATCH  /provisioning/instances/:id/env-manifest/:varId   — edit one
+//     DELETE /provisioning/instances/:id/env-manifest/:varId   — remove one
+//
+// **NO ROUTE HERE ACCEPTS, STORES, LOGS OR RETURNS A VALUE**, and the write routes REFUSE
+// a body that carries one rather than dropping it (../env-manifest.js's
+// `rejectsValueField`, and see that file's header for why loud beats silent). The values
+// live on the deployment platform the running application reads them from.
+//
+// Its own routes file, declared in module.json, because routes/provisioning.js sits at
+// the 1500-line fitness ratchet — the ./disconnect.js and ./core-upgrade.js precedent.
+//
+// A missing or foreign project is 404 for everyone but an archon, the same shape every
+// own-scoped route in this module uses, so another owner's project id is never confirmed.
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { pool, validateOrRespond, parseId } = api;
+const provisioning = require('../provisioning');
+const envManifest = require('../env-manifest');
+
+const log = api.logger('provisioning');
+
+// Resolve the project and decide whether this caller may see it. Returns the instance, or
+// null having already sent the 404 — the same own-or-archon rule as ./disconnect.js.
+async function resolveOwnInstance(req, res) {
+  const id = parseId(req, res); // sends 400 bad_id + returns null on failure
+  if (!id) return null;
+  const inst = await provisioning.getInstanceById(pool, id);
+  const isOwner = !!inst && String(inst.owner_builder_id) === String(req.builder.id);
+  if (!inst || (!isOwner && req.builder.rank !== 'archon')) {
+    res.fail('instance_not_found', 404);
+    return null;
+  }
+  return inst;
+}
+
+// The `:varId` path segment. parseId reads `:id`, which is the PROJECT here, so the
+// declaration's id is parsed separately. A non-numeric id is a 400 naming the field
+// rather than a 404, because it is a malformed request and not a missing row.
+function parseVarId(req, res) {
+  const raw = String(req.params.varId || '');
+  if (!/^[0-9]+$/.test(raw)) {
+    res.fail('bad_id', { status: 400, message: 'varId must be a numeric declaration id.' });
+    return null;
+  }
+  return raw;
+}
+
+// The VALUE refusal, and it runs BEFORE the kernel's strict body validator on purpose.
+//
+// `value` is not in either write route's field list, so `validateOrRespond` already
+// refuses it — correctly, and nothing is stored either way. But it refuses it as a
+// generic `validation_failed` naming an unknown field, and that is the wrong sentence for
+// this particular mistake: a caller who has just sent this platform a credential needs to
+// be told that it stores names and never values, and where the value should live instead.
+// A caller who reads "unknown field: value" is as likely to conclude the field is spelled
+// differently and try again.
+//
+// So this speaks first and the strict validator stays as the backstop behind it. Returns
+// true when it has already failed the response.
+function refusesValue(req, res) {
+  const valueSent = envManifest.rejectsValueField(req.body);
+  if (!valueSent) return false;
+  res.fail(valueSent.code, { status: 400, message: valueSent.message });
+  return true;
+}
+
+// The shared body checks for POST and PATCH, so the two can never disagree about what a
+// valid declaration is. Runs AFTER validateOrRespond (types and lengths are its job) and
+// answers the questions it cannot: is this a legal variable name, and is that a real
+// environment. Returns true when it has already failed the response.
+function badDeclaration(req, res, { nameRequired }) {
+  const hasName = req.body && Object.prototype.hasOwnProperty.call(req.body, 'name');
+  if (nameRequired || hasName) {
+    const refusal = envManifest.envNameRefusal(req.body && req.body.name);
+    if (refusal) {
+      res.fail('bad_env_name', { status: 400, message: refusal });
+      return true;
+    }
+  }
+  const unknown = envManifest.unknownEnvironments(req.body && req.body.environments);
+  if (unknown.length) {
+    // Refused, not quietly filtered: keeping the remainder would tell the owner their
+    // variable applies somewhere it does not.
+    res.fail('bad_environment', { status: 400,
+      message: `Unknown environment ${unknown.map((e) => `"${e}"`).join(', ')} — this platform knows ${envManifest.ENVIRONMENTS.join(', ')}.`,
+      details: { unknown, known: envManifest.ENVIRONMENTS } });
+    return true;
+  }
+  return false;
+}
+
+module.exports = function buildEnvManifestRouter() {
+  const router = express.Router();
+
+  // GET — the declared surface. This is the route a BUILDER SESSION reads to learn which
+  // variables a project has, which is the whole reason the manifest exists.
+  router.get('/provisioning/instances/:id/env-manifest', api.requireBuilder, async (req, res) => {
+    try {
+      const inst = await resolveOwnInstance(req, res);
+      if (!inst) return;
+      const vars = await envManifest.listEnvVars(pool, inst.id);
+      res.json({
+        instance: { id: String(inst.id), slug: inst.slug, hosting_shape: inst.hosting_shape },
+        env_vars: vars,
+        environments: envManifest.ENVIRONMENTS,
+        // Said in the payload, not only in a doc: a reader of this list must not go
+        // looking for a value field and conclude the API is broken when there is none.
+        // For byo-host there is no platform to ask at all (ADR 0323 decision 6).
+        values_held: false,
+        note: 'Names and purposes only — this platform never holds a variable\'s value. Set values where the running application reads them.',
+      });
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/instances/:id/env-manifest', err);
+      res.fail('env_manifest_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST — declare a variable, or re-declare one that exists (an edit, not a duplicate:
+  // see ../env-manifest.js's declareEnvVar).
+  router.post('/provisioning/instances/:id/env-manifest', api.requireBuilder, async (req, res) => {
+    if (refusesValue(req, res)) return;   // before the strict validator — see refusesValue
+    if (validateOrRespond(req, res, {
+      name: { required: true, type: 'string', maxLength: envManifest.ENV_NAME_MAX },
+      description: { type: 'string', maxLength: 2000 },
+      environments: { type: 'array' },
+      required: { type: 'boolean' },
+    })) return;
+    try {
+      const inst = await resolveOwnInstance(req, res);
+      if (!inst) return;
+      if (badDeclaration(req, res, { nameRequired: true })) return;
+      const { row, created } = await envManifest.declareEnvVar(pool, {
+        instanceId: inst.id,
+        name: req.body.name,
+        description: req.body.description ?? null,
+        environments: req.body.environments,
+        required: req.body.required,
+      });
+      res.status(created ? 201 : 200).json({ ok: true, created, env_var: row, values_held: false });
+    } catch (err) {
+      log.error('[provisioning] POST /provisioning/instances/:id/env-manifest', err);
+      res.fail('env_manifest_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH — edit one declaration. Merge-patch: an omitted field is left alone, so the
+  // hall can fix a description without restating the environments.
+  router.patch('/provisioning/instances/:id/env-manifest/:varId', api.requireBuilder, async (req, res) => {
+    if (refusesValue(req, res)) return;   // before the strict validator — see refusesValue
+    if (validateOrRespond(req, res, {
+      name: { type: 'string', maxLength: envManifest.ENV_NAME_MAX },
+      description: { type: 'string', nullable: true, maxLength: 2000 },
+      environments: { type: 'array' },
+      required: { type: 'boolean' },
+    })) return;
+    try {
+      const inst = await resolveOwnInstance(req, res);
+      if (!inst) return;
+      const varId = parseVarId(req, res);
+      if (!varId) return;
+      if (badDeclaration(req, res, { nameRequired: false })) return;
+      const row = await envManifest.updateEnvVar(pool, inst.id, varId, req.body || {});
+      // Not that project's declaration → the same 404 a missing one gets, so a guessed id
+      // never confirms what another project declares.
+      if (!row) return res.fail('env_var_not_found', 404);
+      res.json({ ok: true, env_var: row, values_held: false });
+    } catch (err) {
+      log.error('[provisioning] PATCH /provisioning/instances/:id/env-manifest/:varId', err);
+      res.fail('env_manifest_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // DELETE — remove one declaration. Nothing outside this table is affected: the value,
+  // wherever it lives, is untouched, and the response says so rather than letting an
+  // owner believe removing the name removed the secret.
+  router.delete('/provisioning/instances/:id/env-manifest/:varId', api.requireBuilder, async (req, res) => {
+    try {
+      const inst = await resolveOwnInstance(req, res);
+      if (!inst) return;
+      const varId = parseVarId(req, res);
+      if (!varId) return;
+      const removed = await envManifest.removeEnvVar(pool, inst.id, varId);
+      if (!removed) return res.fail('env_var_not_found', 404);
+      res.json({ ok: true, removed: true,
+        message: 'Declaration removed. The variable\'s value, wherever you keep it, is untouched — this platform never had it.' });
+    } catch (err) {
+      log.error('[provisioning] DELETE /provisioning/instances/:id/env-manifest/:varId', err);
+      res.fail('env_manifest_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};

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

@@ -871,6 +871,22 @@ summary{min-height:24px;padding:3px 0;}
         </details>
       </div>
 
+      <!-- The project's ENVIRONMENT VARIABLE MANIFEST (task 1004062, ADR 0323 decision 6).
+           NAMES and purposes only. There is deliberately no value field anywhere in this
+           card, and the API refuses one — the values live where the running application
+           reads them, on the owner's deployment platform, which already encrypts, audits
+           and rotates them. The fold says so in the owner's words, because a form about
+           environment variables with no value box is otherwise read as unfinished. -->
+      <div class="card mSec" id="mEnvVars">
+        <h2>Its environment variables</h2>
+        <div id="mEnv"><p class="finePrint">Reading the project…</p></div>
+        <details class="finePrint" id="mEnvWhat">
+          <summary>Why there is nowhere to type the value</summary>
+          <p>This is a list of which variables your project needs and what each one is for — not the secrets themselves. The values belong wherever your project actually runs (Vercel, Netlify, Render, or your own machine): that is where the running app reads them, and it already keeps them encrypted, logs who touched them and lets you rotate them. Keeping a second copy here would make this platform the keeper of your credentials and buy you nothing.</p>
+          <p>What the list <i>does</i> buy you: anyone building on the project — you, a teammate, or an AI builder writing code — can see the exact names to use and what each is for, so nothing is invented and nothing is missed at setup.</p>
+        </details>
+      </div>
+
       <!-- live since task 1002346 (BV1.R27): the way to invite a builder AFTER
            creation. The wizard's invite step is skippable, and — the mModules
            argument beside it — an optional step is a default rather than a dead end
@@ -5598,6 +5614,11 @@ summary{min-height:24px;padding:3px 0;}
        answer the widget does not ask for itself. */
     setInviteSlug('mInvite', inst.slug || '');
     loadInviteSuggestions('mInvite', inst.slug ? inst.id : '');
+    /* the env-var manifest (task 1004062) is the one section here that FETCHES, so it is
+       guarded against the once-a-minute tick: a re-render mid-edit would throw away what
+       the owner is typing, and the manifest cannot change under them without their doing
+       it. Only a different project forces a reload. */
+    loadEnvManifest(inst);
     /* the page names its project — the heading holds #mName; and in the tab */
     document.title = (inst.slug ? inst.slug + ' — ' : '') + BASE_TITLE;
     /* the card's own story, on the project's own page (task 1003232): the
@@ -7160,6 +7181,142 @@ summary{min-height:24px;padding:3px 0;}
 
   function discMsg(html) { $('mDisc').innerHTML = html; }
 
+  /* ── Its environment variables (task 1004062, ADR 0323 decision 6) ──────────────
+     NAMES and purposes; never a value. There is no value input in this card and the API
+     refuses one, so there is nothing here that could carry a secret even by mistake. */
+  var mEnvSlug = null;      /* which project the loaded list belongs to */
+  var mEnvVars = null;      /* the declarations, or null before the first read */
+  var mEnvAdding = false;   /* the add form is open — the tick must not wipe it */
+  var mEnvEditing = null;   /* the id being edited, for the same reason */
+
+  function envMsg(html) { var el = $('mEnv'); if (el) el.innerHTML = html; }
+
+  function loadEnvManifest(inst) {
+    if (!inst || !inst.id) return;
+    /* Same project, already read, and the owner is mid-edit → leave the DOM alone. */
+    if (mEnvSlug === inst.slug && mEnvVars && (mEnvAdding || mEnvEditing)) return;
+    if (mEnvSlug === inst.slug && mEnvVars) { renderEnvManifest(); return; }
+    mEnvSlug = inst.slug; mEnvVars = null; mEnvAdding = false; mEnvEditing = null;
+    envMsg('<p class="finePrint">Reading the list…</p>');
+    fetch(API + '/provisioning/instances/' + encodeURIComponent(inst.id) + '/env-manifest', { credentials: 'same-origin' })
+      .then(function (res) {
+        return jsonOrEmpty(res).then(function (data) {
+          if (!res.ok) {
+            envMsg('<div class="projMsg err">' + (res.status === 401 ? signInAgain()
+              : esc(apiError(data, res.status).message || 'The list could not be read — try again.')) + '</div>');
+            return;
+          }
+          mEnvVars = data.env_vars || [];
+          renderEnvManifest();
+        });
+      })
+      .catch(function () { envMsg('<div class="projMsg err">Couldn\u2019t reach the platform — check your connection and try again.</div>'); });
+  }
+
+  function envWhere(list) {
+    /* All three reads as "everywhere" rather than listing them: the list is the common
+       case, and spelling it out three times per row buries the ones that differ. */
+    if (!list || !list.length || list.length === 3) return 'everywhere';
+    return list.join(', ');
+  }
+
+  function envRowHtml(v) {
+    if (mEnvEditing === v.id) {
+      return '<div class="attach" data-env-row="' + esc(v.id) + '">' +
+        '<input type="text" class="envDesc" value="' + esc(v.description || '') + '" maxlength="2000" ' +
+        'aria-label="What ' + esc(v.name) + ' is for" placeholder="What is it for?">' +
+        '<button type="button" class="btn small" data-env-save="' + esc(v.id) + '">Save</button>' +
+        '<button type="button" class="linklike" data-env-cancel>Cancel</button></div>';
+    }
+    return '<div class="addr" data-env-row="' + esc(v.id) + '"><b>' + esc(v.name) + '</b>' +
+      (v.required ? '' : ' <span class="finePrint">(optional)</span>') +
+      ' <span class="finePrint">' + esc(envWhere(v.environments)) + '</span><br>' +
+      '<span class="plain">' + (v.description ? esc(v.description) : '<i>no purpose written yet</i>') + '</span> ' +
+      '<button type="button" class="linklike" data-env-edit="' + esc(v.id) + '">Edit</button> ' +
+      '<button type="button" class="linklike" data-env-del="' + esc(v.id) + '">Remove</button></div>';
+  }
+
+  function renderEnvManifest() {
+    var list = mEnvVars || [];
+    var html = list.length
+      ? list.map(envRowHtml).join('')
+      : '<p class="plain">No variables declared yet. Add the names your project reads, so anyone building on it knows what to set.</p>';
+    if (mEnvAdding) {
+      html += '<div class="attach" id="mEnvAdd">' +
+        '<input type="text" id="mEnvName" autocomplete="off" spellcheck="false" maxlength="128" ' +
+        'aria-label="Variable name" placeholder="DATABASE_URL">' +
+        '<input type="text" id="mEnvNewDesc" maxlength="2000" aria-label="What it is for" placeholder="What is it for?">' +
+        '<button type="button" class="btn small" data-env-add-save>Add it</button>' +
+        '<button type="button" class="linklike" data-env-add-cancel>Cancel</button></div>' +
+        '<p class="finePrint">The name only — not the value. Put the value where your project runs.</p>';
+    } else {
+      html += '<div class="actions"><button type="button" class="btn small" data-env-add>Add a variable</button></div>';
+    }
+    envMsg(html);
+    if (mEnvAdding) { var f = $('mEnvName'); if (f) f.focus(); }
+  }
+
+  function envErr(html) { var el = $('mEnv'); if (el) el.insertAdjacentHTML('beforeend', '<div class="projMsg err">' + html + '</div>'); }
+
+  /* One request shape for all three writes, so the error handling cannot drift between
+     them. NOTHING here ever puts a value in the body — the API would refuse it, and this
+     card has no field that could supply one. */
+  function envWrite(method, path, body) {
+    var inst = manageInst;
+    if (!inst) return Promise.resolve(false);
+    var opts = { method: method, credentials: 'same-origin' };
+    if (body) { opts.headers = { 'Content-Type': 'application/json' }; opts.body = JSON.stringify(body); }
+    return fetch(API + '/provisioning/instances/' + encodeURIComponent(inst.id) + '/env-manifest' + path, opts)
+      .then(function (res) {
+        return jsonOrEmpty(res).then(function (data) {
+          if (res.ok) return true;
+          renderEnvManifest();
+          envErr(res.status === 401 ? signInAgain()
+            : esc(apiError(data, res.status).message || 'That could not be saved — try again.'));
+          return false;
+        });
+      })
+      .catch(function () {
+        renderEnvManifest();
+        envErr('Couldn\u2019t reach the platform — check your connection and try again.');
+        return false;
+      });
+  }
+
+  function envReload() {
+    mEnvAdding = false; mEnvEditing = null; mEnvSlug = null; mEnvVars = null;
+    if (manageInst) loadEnvManifest(manageInst);
+  }
+
+  $('mEnv').addEventListener('click', function (ev) {
+    var t = ev.target.closest && ev.target.closest('button');
+    if (!t) return;
+    if (t.hasAttribute('data-env-add')) { mEnvAdding = true; mEnvEditing = null; renderEnvManifest(); return; }
+    if (t.hasAttribute('data-env-add-cancel')) { mEnvAdding = false; renderEnvManifest(); return; }
+    if (t.hasAttribute('data-env-cancel')) { mEnvEditing = null; renderEnvManifest(); return; }
+    if (t.hasAttribute('data-env-edit')) { mEnvEditing = t.getAttribute('data-env-edit'); mEnvAdding = false; renderEnvManifest(); return; }
+    if (t.hasAttribute('data-env-add-save')) {
+      var name = ($('mEnvName') || {}).value || '';
+      var desc = ($('mEnvNewDesc') || {}).value || '';
+      if (!name.trim()) { envErr('Type the variable\u2019s name.'); return; }
+      envWrite('POST', '', { name: name.trim(), description: desc.trim() || undefined }).then(function (ok) { if (ok) envReload(); });
+      return;
+    }
+    var saveId = t.getAttribute('data-env-save');
+    if (saveId) {
+      var row = $('mEnv').querySelector('[data-env-row="' + saveId + '"] .envDesc');
+      var text = row ? row.value.trim() : '';
+      /* An emptied box is an ERASE, not an omission — null is the un-answer the API
+         reads, the same merge-patch rule the project-detail answers use. */
+      envWrite('PATCH', '/' + encodeURIComponent(saveId), { description: text || null }).then(function (ok) { if (ok) envReload(); });
+      return;
+    }
+    var delId = t.getAttribute('data-env-del');
+    if (delId) {
+      envWrite('DELETE', '/' + encodeURIComponent(delId), null).then(function (ok) { if (ok) envReload(); });
+    }
+  });
+
   function renderDisconnect(inst) {
     if (mDiscAsking && mDiscAsking === inst.slug) return;
     var open = inst.open_intent;

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.954",
+  "version": "1.19.956",
   "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/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.954'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.956'; // 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('dev-box'); log.info('mounted');