@bongos/core 1.19.314 → 1.19.315

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.314",
-  "core_contract": "1.19.314",
-  "source_commit": "7d49e680ed9b88bc3fd32760e275bc2f52348673",
+  "core_version": "1.19.315",
+  "core_contract": "1.19.315",
+  "source_commit": "fa29b8da2f1429be8b46153157348ad0893bb702",
   "source_ref": "HEAD",
-  "built_at": "2026-08-23T21:48:01.343Z",
+  "built_at": "2026-08-23T21:55:22.014Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 323,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1766,
-  "tree_sha256": "59daa4e8041f110026fee1110197d244eb74cd075b36da6d4fc0d18f4bac0b18",
+  "tree_sha256": "194e6d23ae1dc848c9e95e48b8383a33a401686fe98169758b9084884818966b",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1797,7 +1797,7 @@
     {
       "path": "docs/recipes/upgrading-the-core.md",
       "mode": "0000644",
-      "sha256": "732f3b01b7d2e6cc238dd5f48d5ed774f6c2c27ecc737710047758bf85f2d9e5"
+      "sha256": "82a8a5b17d465b9048ce645e2bc13acaa492f766726cc79981fff1352a92d1b0"
     },
     {
       "path": "docs/recipes/windows-builders.md",
@@ -4582,12 +4582,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "e2b6abac7133ee151991f267ba79cb55ed677547ebc8adaf573288a959aecc01"
+      "sha256": "501134bb188ffffca60077b5b43b4e068e5713ff2c35002380cddad4a86076b4"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "47771a7e9c28952af15efa1c8f64fb44cae34698bc385484d1250878145dfc18"
+      "sha256": "4e8358d26d8d6cdd6c5378b0860ebc58671a75d40ad790bb896000e91f9bd0c7"
     },
     {
       "path": "public-docs/index.html",
@@ -5477,7 +5477,7 @@
     {
       "path": "scripts/gds/npmrc.js",
       "mode": "0000644",
-      "sha256": "9dfd27e75def392a73d7de7fd23d462afc97b17a8199acfe6563a80692570026"
+      "sha256": "1beffeed111e8528cfa0a629d5ef81c766023de5c6820a81659a390070868228"
     },
     {
       "path": "scripts/gds/oauth-secret.js",
@@ -5877,7 +5877,7 @@
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "04ee659f61c79a1dbc2302f047d1d7870352d0892c2df974f6f000184794d3f8"
+      "sha256": "80856db9974df9b3451decf55385eeb78bcba61e523ca09a2ea070deb48991ab"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -6257,7 +6257,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "eac68b3c94db0a8eb79241d515a0df3d19d96f6fb41165c32ea4a963753bd5b1"
+      "sha256": "ce9693c479994dbf2f113c783048cd9b3dca8c3cdbc14c655ffdc0f893227eb3"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -7977,7 +7977,7 @@
     {
       "path": "tests/npmrc.mjs",
       "mode": "0000644",
-      "sha256": "87cbb8a5fd896f36197957be56c9107f672a49b2ae8afc3ba69fe00bde11c3ca"
+      "sha256": "1aaa68ee1a4c4a58563cef86aac44cfa0e046ad7376d3a2108bf6dd455580942"
     },
     {
       "path": "tests/oauth_secret.mjs",

package/docs/recipes/upgrading-the-core.md

@@ -116,6 +116,8 @@ Each subscribed instance: read its installed core → ask the registry (`npm vie
 
 ## Gotchas
 
+- **`--registry` no longer needs a hand-exported `NPM_TOKEN`** (task 1002754). The instance `.npmrc` reads `_authToken=<redacted>, and npm gives that per-project key precedence — so with the env var unset it expanded EMPTY and **masked a perfectly valid literal token in `~/.npmrc`** (npm went anonymous; the private core 404'd; the error blamed a "missing" credential the box actually held). `bongos upgrade --registry` now resolves the credential itself: env `NPM_TOKEN` wins, else the **user-level `~/.npmrc`'s literal `//registry.npmjs.org/:_authToken=…`** is injected into the install's environment (forward install and rollback reinstall both). A pin bump on a box whose `~/.npmrc` authenticates therefore succeeds with **no exported env var**. Resolver: `resolveNpmToken()` in [`scripts/gds/npmrc.js`](../../scripts/gds/npmrc.js).
+- **A green `publish` run is not evidence of a publish.** The publish-on-merge lane succeeds on its no-op paths too (cascade terminator, armed-gate). Read the run's **job summary**, which now states the verdict explicitly: `PUBLISHED @bongos/core@<v>` vs `NO-OP — nothing was published this run`.
 - **`PGDATABASE` is load-bearing on a co-tenant droplet.** `migrate.sh` defaults `PGDATABASE` to `example` — **production**. Always set `PGDATABASE=<instance-db>` explicitly, or you migrate the wrong database.
 - **The health check polls the restart** (fixed in task [#1984](https://example.com/builders#/task/1984)). The service binds its port ~1s after `systemctl restart`, so `--health-url` now polls up to ~30s for a 2xx before reporting a warning — an immediate `fetch failed` no longer means a failed upgrade. (Pre-1984 cores fetched once and spuriously reported `fetch failed`; there, confirm with `is-active` + a manual `curl`.)
 - **The ledger auto-inserts via `PGDATABASE` too** (fixed in task [#1984](https://example.com/builders#/task/1984)). A consumer on `PGDATABASE` + peer auth now gets its `core_upgrades` row written automatically — the channel delegates the insert to `psql -d "$PGDATABASE"`, exactly like `migrate.sh`, so no manual `psql INSERT` is needed. (`DATABASE_URL` still works, via the `pg` driver.) Pre-1984 cores only auto-wrote with `DATABASE_URL`; on those, record the row manually.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.314",
+  "version": "1.19.315",
   "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/scripts/gds/npmrc.js

@@ -48,6 +48,37 @@ function hasNpmToken(env = process.env) {
   return !!String(env[TOKEN_ENV] || '').trim();
 }
 
+// resolveNpmToken (task 1002754) — the install-time credential resolver that removes
+// the hand-exported-NPM_TOKEN step from deploys.
+//
+// THE TRAP. The committed instance `.npmrc` reads `_authToken=${NPM_TOKEN}`; npm gives
+// a per-project key precedence over the user-level one, so with NPM_TOKEN unset the
+// expansion is EMPTY and it MASKS a perfectly valid literal token in ~/.npmrc — npm
+// goes anonymous and the private core 404s. Every deploy then silently depended on the
+// operator remembering `export NPM_TOKEN=…` (the ADR-0162 shape: a human-gated step in
+// the ship path). npm's config syntax cannot express "env var, else fall through", so
+// the fix is to RESOLVE the credential here and feed it to the child install's env —
+// the committed file stays secret-free and unchanged.
+//
+// Order: env NPM_TOKEN wins (explicit operator intent), else the user-level ~/.npmrc's
+// literal `//<host>/:_authToken=<value>` (ignoring env-fed `${…}` values — those are
+// the trap, not a credential). Returns { token, source: 'env'|'user-npmrc'|null }.
+function resolveNpmToken({ env = process.env, homedir, fsImpl = fs, host = REGISTRY_HOST } = {}) {
+  const fromEnv = String(env[TOKEN_ENV] || '').trim();
+  if (fromEnv) return { token: fromEnv, source: 'env' };
+  const home = homedir || (env.HOME || env.USERPROFILE || '');
+  if (home) {
+    try {
+      const raw = fsImpl.readFileSync(path.join(home, '.npmrc'), 'utf8');
+      const re = new RegExp(`^\\s*//${host.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}/:_authToken\\s*=\\s*(.+?)\\s*$`, 'm');
+      const m = re.exec(raw);
+      const val = m && m[1].replace(/^["']|["']$/g, '');
+      if (val && !val.includes('${')) return { token: val, source: 'user-npmrc' };
+    } catch { /* no user npmrc, unreadable — fall through to null */ }
+  }
+  return { token: null, source: null };
+}
+
 // Has the operator opted the standalone scaffold into the registry path? OFF by
 // default — the vendored tarball stays the default until the registry path is proven
 // end-to-end (ADR 0134). '1'/'true'/'yes'/'on' (case-insensitive) → true.
@@ -76,7 +107,7 @@ function writeNpmrc(dir, { fsImpl = fs, dryRun = false, overwrite = true, log =
 
 module.exports = {
   REGISTRY_HOST, CORE_SCOPE, TOKEN_ENV, REQUEST_ENV,
-  npmrcContent, hasNpmToken, registryCoreRequested, writeNpmrc,
+  npmrcContent, hasNpmToken, resolveNpmToken, registryCoreRequested, writeNpmrc,
 };
 
 // Tiny CLI: `node scripts/gds/npmrc.js [--print | --write <dir>]` — print the `.npmrc`

package/scripts/gds/upgrade.js

@@ -30,7 +30,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const { spawnSync } = require('node:child_process');
 const { arg, hasFlag } = require('./cli-lib');
-const { writeNpmrc, hasNpmToken } = require('./npmrc'); // ADR 0134 (task 2090): the --registry channel's env-fed .npmrc
+const { writeNpmrc, hasNpmToken, resolveNpmToken } = require('./npmrc'); // ADR 0134 (task 2090): the --registry channel's env-fed .npmrc; resolveNpmToken task 1002754
 
 const CORE_PKG = '@bongos/core';
 const ARTIFACT = 'bongos-core';
@@ -284,10 +284,14 @@ function reportModulePreflight(mods, targetVersion, { log = console.log, err = c
   return lines;
 }
 
-function npmInstall(instanceDir, run = spawnSync) {
+function npmInstall(instanceDir, run = spawnSync, extraEnv = null) {
   // `npm install` (NOT `npm ci`): the pin just changed, so the lockfile must be regenerated from the
   // new tarball; `npm ci` would refuse on the package.json↔lock divergence.
-  const r = run('npm', ['install', '--no-audit', '--no-fund'], { cwd: instanceDir, stdio: 'inherit' });
+  // extraEnv (task 1002754): the registry path injects a resolved NPM_TOKEN here so the
+  // instance `.npmrc`'s `${NPM_TOKEN}` expansion never shadows a valid user-level token.
+  const opts = { cwd: instanceDir, stdio: 'inherit' };
+  if (extraEnv) opts.env = { ...process.env, ...extraEnv };
+  const r = run('npm', ['install', '--no-audit', '--no-fund'], opts);
   return !r || r.error ? { ok: false, reason: r && r.error ? r.error.message : 'spawn failed' } : { ok: r.status === 0, code: r.status };
 }
 
@@ -703,8 +707,11 @@ async function rollback({ instanceDir, snapshot, fromVersion, toVersion, opts },
   try { restore(instanceDir, snapshot.prevPin, fsImpl); result.restoreOk = true; log(`  ✓ restored pin → ${snapshot.prevPin}`); }
   catch (e) { result.restoreOk = false; err(`  ! could not restore pin (${e.message}) — package.json may need manual repair`); }
 
-  // 2. reinstall the previous core.
-  const inst = npmInstall(instanceDir, run);
+  // 2. reinstall the previous core. Same credential resolution as the forward path
+  //    (task 1002754): the previous pin may be a registry pin too, and a rollback
+  //    must never fail on the env-shadowing trap the forward install just avoided.
+  const rbCred = resolveNpmToken();
+  const inst = npmInstall(instanceDir, run, rbCred.source === 'user-npmrc' ? { NPM_TOKEN: rbCred.token } : null);
   result.reinstallOk = !!inst.ok;
   if (inst.ok) log('  ✓ reinstalled previous core');
   else err(`  ! reinstall of previous core failed (${inst.reason || 'exit ' + inst.code}) — the instance may need manual repair`);
@@ -813,9 +820,17 @@ async function runUpgrade(opts, deps = {}) {
   //    REGISTRY (--registry): pin @bongos/core@<version> + ensure the env-fed .npmrc, so
   //      the `npm install` below pulls the PRIVATE package from the registry (needs NPM_TOKEN).
   //    VENDORED (default, --from <tgz>): copy the .tgz into vendor/ + rewrite the file: dep.
+  let installEnv = null;
   if (opts.registry) {
     if (opts.from) return { ok: false, error: '--registry and --from are mutually exclusive (registry pull vs vendored tarball) — pick one core source' };
-    if (!hasNpmToken()) log('  ! no NPM_TOKEN in env — `npm install` will 404 on the PRIVATE @bongos/core until a read-only automation token is provided (ADR 0134).');
+    // task 1002754 — resolve the credential HERE instead of demanding a hand-exported
+    // env var: env NPM_TOKEN wins, else the user-level ~/.npmrc's literal token is
+    // injected into the install's env so the instance `.npmrc`'s `${NPM_TOKEN}`
+    // expansion (which OUTRANKS the user-level key and expands EMPTY when unset)
+    // can never shadow a working credential again.
+    const cred = resolveNpmToken();
+    if (!cred.token) log('  ! no NPM_TOKEN in env and no literal token in ~/.npmrc — `npm install` will 404 on the PRIVATE @bongos/core until a read-only automation token is provided (ADR 0134).');
+    else if (cred.source === 'user-npmrc') { installEnv = { NPM_TOKEN: cred.token }; log('  ✓ registry credential: inherited from the user-level ~/.npmrc (no NPM_TOKEN export needed — task 1002754)'); }
     const prevPin = dryRun ? null : writeRegistryPin(instanceDir, targetVersion, fsImpl);
     if (!dryRun) { writeNpmrc(instanceDir, { fsImpl, overwrite: false, log }); snapshot = { prevPin, prevVersion: fromVersion }; }
     log(`  ${dryRun ? '[dry-run] would pin' : '✓ pinned'} ${CORE_PKG} → ${targetVersion} (registry)${dryRun ? ' + write an env-fed .npmrc' : ''}${prevPin ? `  (was ${prevPin})` : ''}`);
@@ -837,7 +852,7 @@ async function runUpgrade(opts, deps = {}) {
   if (dryRun) { log('  [dry-run] would: npm install → npm run migrate → materialize .claude → regen API docs+client → restart → verify'); return { ok: true, dryRun: true, fromVersion, toVersion: targetVersion }; }
 
   // 3. npm install.
-  const inst = npmInstall(instanceDir, run);
+  const inst = npmInstall(instanceDir, run, installEnv);
   if (!inst.ok) {
     const error = `npm install failed (${inst.reason || 'exit ' + inst.code})`;
     if (rollbackOnFailure && snapshot) {

package/src/module-api.js

@@ -1055,8 +1055,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.312 with no explicit bump. run 32668457836. (task 1002620)
 //   1.19.314 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.313 with no explicit bump. run 32668599111. (task 1002620)
+//   1.19.315 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.314 with no explicit bump. run 32668969037. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.314'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.315'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/npmrc.mjs

@@ -100,6 +100,55 @@ test('writeNpmrc: overwrite:true (default) replaces an existing .npmrc', () => {
   } finally { rmSync(dir, { recursive: true, force: true }); }
 });
 
+// ---- resolveNpmToken (task 1002754) ----------------------------------------
+// The install-time credential resolver that removes the hand-exported-NPM_TOKEN
+// deploy step: env wins, else the user-level ~/.npmrc's LITERAL token; env-fed
+// `${…}` values in the user file are the trap, never a credential.
+test('resolveNpmToken: env NPM_TOKEN wins over everything', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    writeFileSync(join(home, '.npmrc'), '//registry.npmjs.org/:_authToken=npm_userlevel\n');
+    const r = n.resolveNpmToken({ env: { NPM_TOKEN: ' npm_fromenv ' }, homedir: home });
+    assert.deepEqual(r, { token: 'npm_fromenv', source: 'env' });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test('resolveNpmToken: falls back to the user-level ~/.npmrc literal token', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    writeFileSync(join(home, '.npmrc'),
+      'registry=https://registry.npmjs.org/\n//registry.npmjs.org/:_authToken=npm_ABC123\nfund=false\n');
+    const r = n.resolveNpmToken({ env: {}, homedir: home });
+    assert.deepEqual(r, { token: 'npm_ABC123', source: 'user-npmrc' });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test('resolveNpmToken: an env-fed ${…} value in the user file is the trap, not a credential', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    writeFileSync(join(home, '.npmrc'), '//registry.npmjs.org/:_authToken=${NPM_TOKEN}\n');
+    const r = n.resolveNpmToken({ env: {}, homedir: home });
+    assert.deepEqual(r, { token: null, source: null });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test('resolveNpmToken: a token for a DIFFERENT host is not borrowed', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    writeFileSync(join(home, '.npmrc'), '//npm.pkg.github.com/:_authToken=ghp_other\n');
+    const r = n.resolveNpmToken({ env: {}, homedir: home });
+    assert.deepEqual(r, { token: null, source: null });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test('resolveNpmToken: no user npmrc at all → null, never a throw', () => {
+  const home = mkdtempSync(join(tmpdir(), 'npmrc-home-'));
+  try {
+    const r = n.resolveNpmToken({ env: {}, homedir: home });
+    assert.deepEqual(r, { token: null, source: null });
+  } finally { rmSync(home, { recursive: true, force: true }); }
+});
+
 console.log('');
 console.log(`npmrc tests: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);