@bongos/core 1.19.953 → 1.19.955

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.953",
+  "version": "1.19.955",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.953",
+      "version": "1.19.955",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.953",
+  "version": "1.19.955",
   "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.953'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.955'; // 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');

package/tests/provisioning_env_manifest.mjs

@@ -0,0 +1,435 @@
+// tests/provisioning_env_manifest.mjs
+//
+// The project ENV VAR MANIFEST — names and purposes, never values (task 1004062,
+// ADR 0323 decision 6).
+//
+// THE LOAD-BEARING ASSERTION IS AN ABSENCE. The task's own done-when is "no route in this
+// work accepts, stores, logs or returns a secret value, and a test asserts the value field
+// does not exist", so this file proves the negative three ways rather than once: the
+// migration declares no value column, the row projection carries no value key, and a
+// caller who POSTs one is REFUSED — loudly, with nothing written. The third is the one
+// that matters most: a silent strip would hand the caller a 201 and leave them believing
+// this platform had taken custody of a secret, which is worse than storing it, because
+// they may then delete it from the place that really holds it.
+//
+// The "secret" in these fixtures is a marker word, deliberately NOT credential-shaped:
+// the repo's secret gate refuses a realistic connection string in any path, and a test
+// that needs a real-looking one to be meaningful would be testing the wrong thing. What
+// matters is that the marker never appears in a response body, and a marker proves that
+// as well as a plausible URL would.
+//
+// Also pinned: the name rule with its reason-giving refusals, environment normalisation
+// (absent means everywhere, and an unknown environment is refused rather than filtered),
+// re-declaring a name as an EDIT not a duplicate, and the own-or-archon 404 that keeps a
+// guessed id from confirming another project's manifest.
+//
+// DB-free: the pool is a fake, data access is stubbed on the cached module objects, auth
+// is faked — the tests/provisioning_disconnect.mjs harness.
+//
+// Run:  node tests/provisioning_env_manifest.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const provisioning = require('../modules/provisioning/provisioning.js');
+const envManifest = require('../modules/provisioning/env-manifest.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// The marker a "value" carries in these fixtures. If it ever appears in a response, a
+// value reached a surface it must never reach.
+const MARKER = 'VALUE-MUST-NOT-APPEAR';
+
+const MIGRATION = readFileSync(new URL('../modules/provisioning/migrations/provisioning_023_env_manifest.sql', import.meta.url), 'utf8');
+
+console.log('no value, anywhere — the schema:');
+
+t('the migration declares NO value column, under any spelling', () => {
+  // Read the CREATE TABLE body only, so the header prose (which necessarily talks ABOUT
+  // values) cannot make this pass or fail. Comment lines are dropped for the same reason.
+  const body = /CREATE TABLE IF NOT EXISTS provisioning_env_vars \(([\s\S]*?)\n\);/.exec(MIGRATION);
+  assert.ok(body, 'the table is declared');
+  const columns = body[1]
+    .split('\n')
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('--'))
+    .map((l) => l.split(/\s+/)[0]);
+  assert.ok(columns.includes('name'), `sanity: the columns were parsed (${columns.join(', ')})`);
+  for (const forbidden of envManifest.VALUE_FIELDS) {
+    assert.ok(!columns.includes(forbidden),
+      `provisioning_env_vars must not have a "${forbidden}" column — the deployment platform is the system of record for values (ADR 0323 D6). Columns: ${columns.join(', ')}`);
+  }
+});
+
+t('the migration self-registers and touches no core table', () => {
+  assert.match(MIGRATION, /CREATE TABLE IF NOT EXISTS provisioning_env_vars/, 'additive create');
+  assert.doesNotMatch(MIGRATION, /ALTER TABLE (?!provisioning_)/, 'no non-provisioning table is altered (ADR 0083 §5)');
+  assert.match(MIGRATION, /UNIQUE INDEX IF NOT EXISTS ux_provisioning_env_vars_instance_name/, 'one declaration per name per project');
+});
+
+t('the environments CHECK admits exactly the known set, and the code agrees with it', () => {
+  const m = /CHECK \(environments <@ ARRAY\[([^\]]*)\]/.exec(MIGRATION);
+  assert.ok(m, 'the CHECK is a containment test, so any subset is legal');
+  const inSql = m[1].split(',').map((s) => s.trim().replace(/^'|'$/g, '')).sort();
+  assert.deepEqual(inSql, [...envManifest.ENVIRONMENTS].sort(),
+    'the migration and ENVIRONMENTS carry the same set — a drift here silently refuses a legal row at write time');
+});
+
+console.log('\nno value, anywhere — the projection:');
+
+t('envVarRow returns no value key even when the row it is handed carries one', () => {
+  // The projection NAMES its columns rather than spreading the row, so a value column
+  // that somehow reached the table still could not leave through it. Handing it a poisoned
+  // row is how that is proved rather than asserted.
+  const out = envManifest.envVarRow({
+    id: 1, instance_id: 2, name: 'DATABASE_URL', description: 'the connection string',
+    environments: ['production'], required: true, created_at: 'now', updated_at: 'now',
+    value: MARKER, secret: MARKER,
+  });
+  for (const forbidden of envManifest.VALUE_FIELDS) {
+    assert.ok(!(forbidden in out), `the projection leaked "${forbidden}"`);
+  }
+  assert.equal(JSON.stringify(out).includes(MARKER), false, 'and no value rides along inside another field');
+  assert.deepEqual(Object.keys(out).sort(),
+    ['created_at', 'description', 'environments', 'id', 'instance_id', 'name', 'required', 'updated_at']);
+});
+
+t('rejectsValueField catches every spelling, and is silent on a clean body', () => {
+  assert.equal(envManifest.rejectsValueField({ name: 'PORT', description: 'the port' }), null);
+  assert.equal(envManifest.rejectsValueField(null), null);
+  for (const f of envManifest.VALUE_FIELDS) {
+    const r = envManifest.rejectsValueField({ name: 'PORT', [f]: MARKER });
+    assert.ok(r, `"${f}" must be refused`);
+    assert.equal(r.code, 'value_not_accepted');
+    assert.match(r.message, /never values/i, 'the message says what the platform does instead');
+    assert.ok(!r.message.includes(MARKER), 'and the refusal does not echo the value back');
+  }
+});
+
+console.log('\nthe name rule:');
+
+t('valid names are accepted and the refusals say WHY', () => {
+  for (const ok of ['DATABASE_URL', 'PORT', '_INTERNAL', 'npm_config_registry', 'A1']) {
+    assert.ok(envManifest.isValidEnvName(ok), `${ok} is a legal name`);
+    assert.equal(envManifest.envNameRefusal(ok), null);
+  }
+  assert.match(envManifest.envNameRefusal(''), /needs a name/);
+  assert.match(envManifest.envNameRefusal('MY VAR'), /space/, 'a space is named as the problem');
+  assert.match(envManifest.envNameRefusal('1ST_RUN'), /starts with a digit/);
+  assert.match(envManifest.envNameRefusal('MY-VAR'), /letters, digits and underscores/);
+  assert.match(envManifest.envNameRefusal('X'.repeat(envManifest.ENV_NAME_MAX + 1)), /the limit is/);
+  for (const bad of ['MY VAR', '1ST_RUN', 'MY-VAR', '', 'a'.repeat(129)]) {
+    assert.ok(!envManifest.isValidEnvName(bad), `${JSON.stringify(bad)} is not a legal name`);
+  }
+});
+
+console.log('\nenvironments:');
+
+t('absent or empty means EVERYWHERE, stored explicitly and in canonical order', () => {
+  assert.deepEqual(envManifest.normalizeEnvironments(undefined), ['production', 'preview', 'development']);
+  assert.deepEqual(envManifest.normalizeEnvironments(null), ['production', 'preview', 'development']);
+  assert.deepEqual(envManifest.normalizeEnvironments([]), ['production', 'preview', 'development']);
+  // Canonical order, so two callers naming the same set produce equal rows and a diff of
+  // two manifests is about content rather than ordering.
+  assert.deepEqual(envManifest.normalizeEnvironments(['development', 'production']), ['production', 'development']);
+  assert.deepEqual(envManifest.normalizeEnvironments(['PRODUCTION', ' production ']), ['production'], 'case and whitespace folded, duplicates collapsed');
+  assert.deepEqual(envManifest.normalizeEnvironments('preview'), ['preview'], 'a bare string is accepted as a one-element list');
+});
+
+t('an unknown environment is REPORTED, not quietly filtered', () => {
+  assert.deepEqual(envManifest.unknownEnvironments(['production', 'staging']), ['staging']);
+  assert.deepEqual(envManifest.unknownEnvironments(['production']), []);
+  assert.deepEqual(envManifest.unknownEnvironments(undefined), []);
+  // The two functions disagree on purpose: normalize DROPS the unknown (the backstop) and
+  // the route refuses on unknownEnvironments (the answer). Keeping the remainder silently
+  // would tell an owner their variable applies somewhere it does not.
+  assert.deepEqual(envManifest.normalizeEnvironments(['production', 'staging']), ['production']);
+});
+
+console.log('\nstorage:');
+
+// A fake pool that records the SQL and answers the shapes env-manifest.js expects.
+function fakeDb({ rows = [], rowCount = 1, inserted = true } = {}) {
+  const calls = [];
+  return {
+    calls,
+    query: async (sql, params) => {
+      calls.push({ sql: sql.replace(/\s+/g, ' ').trim(), params });
+      if (/^SELECT \* FROM provisioning_env_vars/.test(sql.trim())) return { rows };
+      if (/INSERT INTO provisioning_env_vars/.test(sql)) {
+        return { rows: [{ id: 5, instance_id: params[0], name: params[1], description: params[2], environments: params[3], required: params[4], created_at: 'c', updated_at: 'u', inserted }] };
+      }
+      if (/UPDATE provisioning_env_vars/.test(sql)) {
+        return { rows: rows.length ? [rows[0]] : [] };
+      }
+      if (/DELETE FROM provisioning_env_vars/.test(sql)) return { rowCount, rows: [] };
+      throw new Error(`unexpected SQL: ${sql}`);
+    },
+  };
+}
+
+await ta('declaring stores the name, the sentence, the environments and required — and nothing else', async () => {
+  const db = fakeDb();
+  const { row, created } = await envManifest.declareEnvVar(db, {
+    instanceId: 40, name: '  DATABASE_URL  ', description: 'Postgres connection string', environments: ['production'],
+  });
+  assert.equal(created, true);
+  assert.equal(row.name, 'DATABASE_URL', 'the name is trimmed');
+  assert.equal(row.required, true, 'required is the default — an omission stays visible on a setup checklist');
+  assert.deepEqual(row.environments, ['production']);
+  assert.equal(db.calls.length, 1);
+  // Five parameters: instance, name, description, environments, required. A sixth would
+  // be the thing this table exists to not have.
+  assert.equal(db.calls[0].params.length, 5, `the insert binds exactly the manifest columns: ${JSON.stringify(db.calls[0].params)}`);
+  assert.match(db.calls[0].sql, /ON CONFLICT \(instance_id, name\) DO UPDATE/, 're-declaring is an edit, not a duplicate row');
+});
+
+await ta('re-declaring an existing name reports created:false — the same declaration, edited', async () => {
+  const db = fakeDb({ inserted: false });
+  const { created } = await envManifest.declareEnvVar(db, { instanceId: 40, name: 'PORT' });
+  assert.equal(created, false);
+});
+
+await ta('a patch touches ONLY the fields it names, and is scoped to the project', async () => {
+  const db = fakeDb({ rows: [{ id: 5, instance_id: 40, name: 'PORT', description: 'new text', environments: ['production'], required: false, created_at: 'c', updated_at: 'u' }] });
+  const row = await envManifest.updateEnvVar(db, 40, '5', { description: 'new text' });
+  assert.equal(row.description, 'new text');
+  const sql = db.calls[0].sql;
+  assert.match(sql, /WHERE instance_id = \$1 AND id = \$2/, 'a guessed id cannot reach another project');
+  assert.match(sql, /SET updated_at = now\(\), description = \$3/, 'environments and required are left alone');
+  assert.doesNotMatch(sql, /required =/);
+});
+
+await ta('an explicit null description erases it; an omitted one does not', async () => {
+  const db = fakeDb({ rows: [{ id: 5, instance_id: 40, name: 'PORT', description: null, environments: [], required: true }] });
+  await envManifest.updateEnvVar(db, 40, '5', { description: null });
+  assert.equal(db.calls[0].params[2], null, 'null is the un-answer, not a dropped field');
+});
+
+await ta('removing is scoped to the project too, and reports whether a row went', async () => {
+  const gone = fakeDb({ rowCount: 1 });
+  assert.equal(await envManifest.removeEnvVar(gone, 40, '5'), true);
+  assert.match(gone.calls[0].sql, /WHERE instance_id = \$1 AND id = \$2/);
+  const missing = fakeDb({ rowCount: 0 });
+  assert.equal(await envManifest.removeEnvVar(missing, 40, '999'), false);
+});
+
+await ta('the list is name-ordered, so two reads of an unchanged manifest are identical', async () => {
+  const db = fakeDb({ rows: [] });
+  await envManifest.listEnvVars(db, 40);
+  assert.match(db.calls[0].sql, /ORDER BY name ASC/);
+});
+
+console.log('\nthe routes:');
+
+let instance = null;
+provisioning.getInstanceById = async (_db, id) => (instance ? { ...instance, id } : null);
+
+const api = require('../src/module-api.js');
+let builder = { id: 7, rank: 'xenos', github_login: 'owner' };
+api.requireBuilder = (req, _res, next) => { req.builder = builder; next(); };
+
+let store = [];
+envManifest.listEnvVars = async () => store;
+envManifest.declareEnvVar = async (_db, d) => {
+  const row = envManifest.envVarRow({
+    id: 5, instance_id: 40, name: String(d.name).trim(), description: d.description ?? null,
+    environments: envManifest.normalizeEnvironments(d.environments), required: d.required !== false,
+    created_at: 'c', updated_at: 'u',
+  });
+  store = [row];
+  return { row, created: true };
+};
+envManifest.updateEnvVar = async (_db, _inst, id) => (id === '5' ? store[0] || null : null);
+envManifest.removeEnvVar = async (_db, _inst, id) => id === '5';
+
+const express = require('express');
+const envRoutes = require('../modules/provisioning/routes/env-manifest.js');
+const app = express();
+app.use(express.json());
+app.use((_req, res, next) => {
+  res.fail = (code, opts, details) => {
+    const status = typeof opts === 'number' ? opts : (opts && opts.status) || 400;
+    const extra = typeof opts === 'object' ? opts : {};
+    res.status(status).json({ error: { code, message: extra.message || code, details: details || extra.details } });
+  };
+  next();
+});
+app.use('/api/bongos', envRoutes());
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+
+function call(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const payload = body === undefined ? null : JSON.stringify(body);
+    const headers = payload ? { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) } : {};
+    const req = http.request(`${base}${path}`, { method, headers }, (res) => {
+      let d = '';
+      res.on('data', (c) => { d += c; });
+      res.on('end', () => { let j = null; try { j = JSON.parse(d); } catch { /* non-JSON */ } resolve({ status: res.statusCode, body: j, raw: d }); });
+    });
+    req.on('error', reject);
+    if (payload) req.write(payload);
+    req.end();
+  });
+}
+
+const URL_ = '/provisioning/instances/40/env-manifest';
+function reset({ inst = { owner_builder_id: 7, slug: 'lantern', status: 'active', hosting_shape: 'byo-host' }, who = { id: 7, rank: 'xenos', github_login: 'owner' } } = {}) {
+  instance = inst; builder = who; store = [];
+}
+
+await ta('the owner declares a variable and reads it back, values_held:false on both', async () => {
+  reset();
+  const created = await call('POST', URL_, { name: 'DATABASE_URL', description: 'Postgres connection string', environments: ['production'] });
+  assert.equal(created.status, 201, created.raw);
+  assert.equal(created.body.env_var.name, 'DATABASE_URL');
+  assert.equal(created.body.values_held, false);
+  const read = await call('GET', URL_);
+  assert.equal(read.status, 200, read.raw);
+  assert.equal(read.body.env_vars.length, 1);
+  assert.equal(read.body.values_held, false, 'a reader must not go looking for a value field and think the API is broken');
+  assert.deepEqual(read.body.environments, envManifest.ENVIRONMENTS, 'the vocabulary ships with the list');
+});
+
+// THE done-when assertion, at the boundary.
+for (const field of ['value', 'secret', 'secret_value']) {
+  await ta(`POSTing a "${field}" is REFUSED with nothing written, and the value is not echoed back`, async () => {
+    reset();
+    const res = await call('POST', URL_, { name: 'DATABASE_URL', [field]: MARKER });
+    assert.equal(res.status, 400, res.raw);
+    assert.equal(res.body.error.code, 'value_not_accepted');
+    assert.ok(!res.raw.includes(MARKER), 'the refusal does not repeat the value into a response body or a log');
+    assert.deepEqual(store, [], 'and nothing was stored — a 201 here would have the caller believe we hold it');
+  });
+}
+
+await ta('a value sent alongside a BAD name is still answered as the value problem first', async () => {
+  reset();
+  const res = await call('POST', URL_, { name: '1BAD NAME', value: MARKER });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'value_not_accepted', 'the value is the urgent half of that mistake');
+});
+
+await ta('PATCHing a value is refused the same way', async () => {
+  reset();
+  const res = await call('PATCH', `${URL_}/5`, { value: MARKER });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'value_not_accepted');
+});
+
+await ta('an unknown environment is refused and NAMES both sets', async () => {
+  reset();
+  const res = await call('POST', URL_, { name: 'PORT', environments: ['production', 'staging'] });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'bad_environment');
+  assert.deepEqual(res.body.error.details.unknown, ['staging']);
+  assert.deepEqual(res.body.error.details.known, envManifest.ENVIRONMENTS);
+});
+
+await ta('a malformed name is refused with the rule, not a generic 400', async () => {
+  reset();
+  const res = await call('POST', URL_, { name: 'MY VAR' });
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'bad_env_name');
+  assert.match(res.body.error.message, /space/);
+});
+
+await ta("another builder's project is a 404, not a 403 — a guessed id confirms nothing", async () => {
+  reset({ who: { id: 99, rank: 'xenos', github_login: 'stranger' } });
+  for (const [m, p] of [['GET', URL_], ['POST', URL_], ['PATCH', `${URL_}/5`], ['DELETE', `${URL_}/5`]]) {
+    const res = await call(m, p, m === 'GET' || m === 'DELETE' ? undefined : { name: 'PORT' });
+    assert.equal(res.status, 404, `${m} ${p} → ${res.raw}`);
+    assert.equal(res.body.error.code, 'instance_not_found');
+  }
+});
+
+await ta('an archon may read and edit any project (fleet support)', async () => {
+  reset({ who: { id: 99, rank: 'archon', github_login: 'archon' } });
+  const res = await call('GET', URL_);
+  assert.equal(res.status, 200, res.raw);
+});
+
+await ta('a missing project is the same 404', async () => {
+  reset({ inst: null });
+  const res = await call('GET', URL_);
+  assert.equal(res.status, 404, res.raw);
+});
+
+await ta("a declaration id that is not this project's is a 404, and removing says the value was never ours", async () => {
+  reset();
+  const miss = await call('DELETE', `${URL_}/999`);
+  assert.equal(miss.status, 404, miss.raw);
+  assert.equal(miss.body.error.code, 'env_var_not_found');
+  const hit = await call('DELETE', `${URL_}/5`);
+  assert.equal(hit.status, 200, hit.raw);
+  assert.match(hit.body.message, /untouched/, 'removing a name must not read as removing the secret');
+});
+
+await ta('a non-numeric declaration id is a 400 naming the field, not a 404', async () => {
+  reset();
+  const res = await call('DELETE', `${URL_}/abc`);
+  assert.equal(res.status, 400, res.raw);
+  assert.equal(res.body.error.code, 'bad_id');
+});
+
+console.log('\nthe owner-facing card:');
+
+t('the manage card has NO value input, and says why there is nowhere to type one', () => {
+  // The UI is the other place a value field could appear, so the absence is asserted here
+  // too rather than left to the API's refusal. A form about environment variables with no
+  // value box reads as unfinished unless it explains itself, which is why the copy check
+  // is part of the same assertion: removing the explanation to "tidy up" would leave a
+  // card that invites the very question the API refuses.
+  const page = readFileSync(new URL('../modules/public-landing/public/projects.html', import.meta.url), 'utf8');
+  const card = /<div class="card mSec" id="mEnvVars">([\s\S]*?)<\/details>/.exec(page);
+  assert.ok(card, 'the env-var card is on the manage page');
+  assert.match(card[1], /Why there is nowhere to type the value/, 'the fold answers the question the missing field raises');
+  assert.match(card[1], /Vercel|Netlify|Render|your own machine/, 'and names where the value does belong');
+
+  // The card's own client code: no input whose purpose is a value, and no request body
+  // field that could carry one.
+  const code = /Its environment variables \(task 1004062([\s\S]*?)function renderDisconnect/.exec(page);
+  assert.ok(code, 'the card\'s client code is on the page');
+  const inputIds = [...code[1].matchAll(/id="(mEnv[A-Za-z]*)"/g)].map((m) => m[1]);
+  assert.deepEqual(inputIds.sort(), ['mEnvAdd', 'mEnvName', 'mEnvNewDesc'],
+    `the card's only fields are the name and the purpose: ${inputIds.join(', ')}`);
+  for (const forbidden of envManifest.VALUE_FIELDS) {
+    assert.ok(!new RegExp(`\\b${forbidden}:`).test(code[1]),
+      `the card must not put "${forbidden}" in a request body`);
+  }
+});
+
+t('the card is guarded against the once-a-minute manage tick', () => {
+  // renderManage runs on a timer. Every other section there is fetch-free and so is safe
+  // to re-render; this one fetches AND holds a form, so a blind re-render would throw away
+  // what the owner is typing. The guard is the reason loadEnvManifest is called rather
+  // than a renderX, and this pins it.
+  const page = readFileSync(new URL('../modules/public-landing/public/projects.html', import.meta.url), 'utf8');
+  assert.match(page, /loadEnvManifest\(inst\);/, 'renderManage calls the loader');
+  assert.match(page, /if \(mEnvSlug === inst\.slug && mEnvVars && \(mEnvAdding \|\| mEnvEditing\)\) return;/,
+    'a tick during an edit leaves the DOM alone');
+});
+
+await ta('the routes file is DECLARED in module.json, or none of the above is reachable in production', async () => {
+  const mod = JSON.parse(readFileSync(new URL('../modules/provisioning/module.json', import.meta.url), 'utf8'));
+  assert.ok((mod.contributes.routes || []).includes('env-manifest'),
+    'a routes file the manifest does not list is a silent no-op (ADR 0289)');
+});
+
+server.close();
+
+console.log(`\nprovisioning_env_manifest: ${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);