@bongos/core 1.18.0 → 1.18.18

package/tests/criterion_authoring_gate.mjs

@@ -0,0 +1,272 @@
+// tests/criterion_authoring_gate.mjs — who may author a goal's done-when criteria
+// (task 1002538 / ADR 0154).
+//
+// POST /versions/:id/done-when was Archon-only. It is now Metic+ WALLED BY GOAL
+// OWNERSHIP: a non-Archon must name a goal they own or manage, on an open
+// (planning|building) version. The wall is load-bearing, not decoration — creating an unsatisfied
+// criterion is a backward ratchet with no undo:
+//   - version-close.js counts satisfied === total per VERSION (regardless of goal),
+//     so one unsatisfied row parks the version's close suggestion indefinitely;
+//   - db.achieveGoalIfComplete refuses while unsatisfied > 0, so it also parks the
+//     goal and the dependents its achievement would release;
+//   - there is NO delete route — descoping is direct SQL only.
+// That is why this is not a flat re-rank, and why the pins below matter.
+//
+// Runs the PURE decision core (no DB, no network): the ordered gate
+// authorizeCriterionCreate, the route-source contract, and the route-rank PIN.
+//
+// Run:  node tests/criterion_authoring_gate.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+import { makeRunner } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+
+const require = createRequire(import.meta.url);
+const buildDoneWhenRouter = require('../modules/lifecycle/routes/done-when.js');
+const { authorizeCriterionCreate } = buildDoneWhenRouter;
+const { authorizeGoalManagement, isGoalOwnerOrManager } = require('../modules/lifecycle/goal-authz.js');
+const { MODULE_EXPECTED_RANKS } = require('../src/bongos/route-rank-check.js');
+
+const doneWhenSrc = readFileSync(new URL('../modules/lifecycle/routes/done-when.js', import.meta.url), 'utf8');
+const { test, summary } = makeRunner();
+
+// ---- fixtures ----
+const OWNER = 1001;
+const MANAGER = 1002;
+const MEMBER = 1003;
+const STRANGER = 1004;
+
+const V_BUILDING = { id: 'BONGOS-V1', status: 'building' };
+const V_SHIPPED = { id: 'GDS-V4', status: 'shipped' };
+const V_PLANNING = { id: 'CB-V2', status: 'planning' };
+const V_FROZEN = { id: 'CB-V3', status: 'frozen' };
+
+const G_OPEN = { id: 42, version_id: 'BONGOS-V1', status: 'open', created_by: OWNER };
+const G_ACHIEVED = { id: 43, version_id: 'BONGOS-V1', status: 'achieved', created_by: OWNER };
+const G_ARCHIVED = { id: 44, version_id: 'BONGOS-V1', status: 'archived', created_by: OWNER };
+const G_SYSTEM = { id: 45, version_id: 'BONGOS-V1', status: 'open', created_by: null };
+
+const LEAD = { role: 'lead' };
+const PLAIN = { role: 'member' };
+
+const ask = (o) => authorizeCriterionCreate({ version: V_BUILDING, actorRank: 'metic', ...o });
+
+// ---- the allow cases ----
+
+await test('the goal OWNER may author their goal\'s criterion', () => {
+  const d = ask({ goal: G_OPEN, actorId: OWNER, actorMembership: LEAD });
+  assert.equal(d.ok, true);
+});
+
+await test('owner authority is created_by, not the role row — an owner with no membership still passes', () => {
+  const d = ask({ goal: G_OPEN, actorId: OWNER, actorMembership: null });
+  assert.equal(d.ok, true, 'created_by is the fixed authority (goal-authz isGoalOwner)');
+});
+
+await test('a MANAGER (goal_members.role=lead) may author', () => {
+  const d = ask({ goal: G_OPEN, actorId: MANAGER, actorMembership: LEAD });
+  assert.equal(d.ok, true);
+});
+
+// ---- the refusals, in gate order ----
+
+await test('a non-Archon with NO goal_id is refused — version-level criteria stay Archon-only', () => {
+  const d = ask({ goal: null, actorId: OWNER, actorMembership: null });
+  assert.equal(d.ok, false);
+  assert.equal(d.status, 403);
+  assert.equal(d.body.error, 'goal_id_required');
+});
+
+await test('a plain MEMBER may not author — membership is not management', () => {
+  const d = ask({ goal: G_OPEN, actorId: MEMBER, actorMembership: PLAIN });
+  assert.equal(d.ok, false);
+  assert.equal(d.maskAsBadGoalId, true);
+});
+
+await test('a STRANGER (no membership at all) may not author', () => {
+  const d = ask({ goal: G_OPEN, actorId: STRANGER, actorMembership: null });
+  assert.equal(d.ok, false);
+  assert.equal(d.maskAsBadGoalId, true);
+});
+
+await test('an ACHIEVED goal is closed to new criteria (409) — no reopening settled scope', () => {
+  const d = ask({ goal: G_ACHIEVED, actorId: OWNER, actorMembership: LEAD });
+  assert.equal(d.ok, false);
+  assert.equal(d.status, 409);
+  assert.equal(d.body.error, 'goal_not_open');
+});
+
+await test('an ARCHIVED goal is closed to new criteria (409)', () => {
+  const d = ask({ goal: G_ARCHIVED, actorId: OWNER, actorMembership: LEAD });
+  assert.equal(d.ok, false);
+  assert.equal(d.status, 409);
+  assert.equal(d.body.error, 'goal_not_open');
+});
+
+// ---- NO-LEAK: the route must not become a goal-existence oracle (ADR 0112) ----
+// Before ADR 0154 this route was Archon-only and Archons read every goal, so no
+// probe existed. Now a Metic may call it — so an unauthorized caller must not be
+// able to tell "this goal id exists but isn't mine" from "no such goal".
+
+await test('an unauthorized caller is MASKED — no status/body of its own to compare', () => {
+  const d = ask({ goal: G_OPEN, actorId: STRANGER, actorMembership: null });
+  assert.equal(d.maskAsBadGoalId, true);
+  assert.equal(d.status, undefined, 'the gate must not pick a distinguishable status');
+  assert.equal(d.body, undefined, 'the route renders the identical bad_goal_id 400');
+});
+
+await test('the mask is IDENTICAL across every unauthorized shape — open, achieved, archived, private-ish', () => {
+  const probes = [G_OPEN, G_ACHIEVED, G_ARCHIVED, G_SYSTEM].map((goal) =>
+    ask({ goal, actorId: STRANGER, actorMembership: null }));
+  for (const d of probes) assert.deepEqual(d, { ok: false, maskAsBadGoalId: true });
+  // A goal's STATE must not leak either: an outsider cannot learn that a goal id
+  // exists-but-is-archived, which `goal_not_open` would have told them.
+  assert.equal(new Set(probes.map((d) => JSON.stringify(d))).size, 1);
+});
+
+await test('authority is checked BEFORE goal state — the ordering that makes the mask total', () => {
+  // An owner on an archived goal DOES get goal_not_open (useful, and they already
+  // know the goal exists). A stranger on the same goal gets the mask instead.
+  assert.equal(ask({ goal: G_ARCHIVED, actorId: OWNER, actorMembership: LEAD }).body.error, 'goal_not_open');
+  assert.equal(ask({ goal: G_ARCHIVED, actorId: STRANGER, actorMembership: null }).maskAsBadGoalId, true);
+});
+
+await test('the route renders the mask through the SAME bad_goal_id helper as a truly absent goal', () => {
+  assert.match(doneWhenSrc, /const badGoalId = \(\) => res\.fail\('bad_goal_id'/, 'one helper builds the refusal');
+  assert.match(doneWhenSrc, /if \(!goal \|\| String\(goal\.version_id\) !== String\(versionId\)\) return badGoalId\(\);/, 'absent/foreign goal path');
+  assert.match(doneWhenSrc, /if \(decision\.maskAsBadGoalId\) return badGoalId\(\);/, 'masked path — same helper, so same code+message+envelope');
+});
+
+await test('a SHIPPED version is refused (409) — closed scope', () => {
+  const d = authorizeCriterionCreate({
+    goal: G_OPEN, version: V_SHIPPED, actorId: OWNER, actorRank: 'metic', actorMembership: LEAD,
+  });
+  assert.equal(d.ok, false);
+  assert.equal(d.status, 409);
+  assert.equal(d.body.error, 'version_closed');
+  assert.equal(d.body.status, 'shipped', 'the refusal names the version status');
+});
+
+await test('a FROZEN version is refused (409) — freezing exists to stop scope writes', () => {
+  const d = authorizeCriterionCreate({
+    goal: G_OPEN, version: V_FROZEN, actorId: OWNER, actorRank: 'metic', actorMembership: LEAD,
+  });
+  assert.equal(d.ok, false);
+  assert.equal(d.body.error, 'version_closed');
+});
+
+// The bug this test exists to prevent: gating on `status === 'building'` blocks a
+// PLANNING version, which is exactly when a planning session writes its criteria.
+await test('a PLANNING version is ALLOWED — that is when criteria get written', () => {
+  const d = authorizeCriterionCreate({
+    goal: G_OPEN, version: V_PLANNING, actorId: OWNER, actorRank: 'metic', actorMembership: LEAD,
+  });
+  assert.equal(d.ok, true, 'planning is an OPEN version state, not a closed one');
+});
+
+await test('a system goal (created_by NULL) has no owner — a Metic cannot claim it', () => {
+  const d = ask({ goal: G_SYSTEM, actorId: OWNER, actorMembership: null });
+  assert.equal(d.ok, false);
+  assert.equal(d.maskAsBadGoalId, true);
+  // ...but a manager row still admits, and an Archon always does (below).
+  assert.equal(ask({ goal: G_SYSTEM, actorId: OWNER, actorMembership: LEAD }).ok, true);
+});
+
+// ---- fail-closed on ambiguity ----
+
+await test('FAIL-CLOSED: a missing version denies rather than allows', () => {
+  const d = authorizeCriterionCreate({
+    goal: G_OPEN, version: null, actorId: OWNER, actorRank: 'metic', actorMembership: LEAD,
+  });
+  assert.equal(d.ok, false);
+  assert.equal(d.body.error, 'version_closed');
+  assert.equal(d.body.status, null);
+});
+
+await test('FAIL-CLOSED: an unknown rank is treated as a non-Archon', () => {
+  const d = authorizeCriterionCreate({
+    goal: null, version: V_BUILDING, actorId: STRANGER, actorRank: 'xenos', actorMembership: null,
+  });
+  assert.equal(d.ok, false, 'xenos never reaches here (requireRank stops it) but the gate must not allow');
+  assert.equal(d.body.error, 'goal_id_required');
+});
+
+// ---- the Archon arm ----
+
+await test('an ARCHON short-circuits every branch — goal-less, achieved goal, shipped version', () => {
+  const archon = { actorId: STRANGER, actorRank: 'archon', actorMembership: null };
+  assert.equal(authorizeCriterionCreate({ goal: null, version: V_BUILDING, ...archon }).ok, true);
+  assert.equal(authorizeCriterionCreate({ goal: G_ACHIEVED, version: V_BUILDING, ...archon }).ok, true);
+  assert.equal(authorizeCriterionCreate({ goal: G_OPEN, version: V_SHIPPED, ...archon }).ok, true);
+});
+
+// ---- ordering (no information leaks, cheapest check first) ----
+
+await test('ordering: goal_id_required precedes the version check', () => {
+  const d = authorizeCriterionCreate({
+    goal: null, version: V_SHIPPED, actorId: STRANGER, actorRank: 'metic', actorMembership: null,
+  });
+  assert.equal(d.body.error, 'goal_id_required', 'a caller who named no goal never learns the version state');
+});
+
+await test('ordering: an unauthorized caller never reaches the goal-state branch', () => {
+  const d = ask({ goal: G_ARCHIVED, actorId: STRANGER, actorMembership: null });
+  assert.equal(d.maskAsBadGoalId, true, 'goal_not_open would confirm the goal exists');
+});
+
+// ---- the wall is the SAME one the sibling goal routes use ----
+
+await test('the gate reuses the SAME owner|manager predicate as routes/goals.js — one definition', () => {
+  // It cannot delegate to authorizeGoalManagement wholesale (that checks goal state
+  // FIRST, which is exactly the leak); it shares the authority predicate instead.
+  for (const [membership, actorId, expected] of [
+    [LEAD, MANAGER, true], [PLAIN, MEMBER, false], [null, OWNER, true], [null, STRANGER, false],
+  ]) {
+    assert.equal(
+      isGoalOwnerOrManager({ goal: G_OPEN, actorId, actorRank: 'metic', actorMembership: membership }),
+      expected
+    );
+    assert.equal(ask({ goal: G_OPEN, actorId, actorMembership: membership }).ok === true, expected,
+      'the gate agrees with the shared predicate');
+  }
+  // ...and authorizeGoalManagement is built on that same predicate.
+  assert.equal(authorizeGoalManagement({ goal: G_OPEN, actorId: MEMBER, actorRank: 'metic', actorMembership: PLAIN }).ok, false);
+  assert.equal(authorizeGoalManagement({ goal: G_OPEN, actorId: OWNER, actorRank: 'metic', actorMembership: null }).ok, true);
+});
+
+// ---- route-source + pin contracts (drift catchers) ----
+
+await test('the route is gated metic+archon and calls the pure gate', () => {
+  assert.match(
+    doneWhenSrc,
+    /router\.post\('\/versions\/:id\/done-when',\s*auth\.requireBuilder,\s*auth\.requireRank\('metic',\s*'archon'\)/,
+    'the middleware must be requireRank(metic, archon)'
+  );
+  assert.match(doneWhenSrc, /authorizeCriterionCreate\(\{/, 'the handler must call the pure gate, not inline the decision');
+});
+
+await test('the `// rank:` annotation matches the middleware (gen-api-docs reads the annotation)', () => {
+  assert.match(
+    doneWhenSrc,
+    /\/\/ rank: metic\+archon — criterion create/,
+    'a stale annotation publishes the wrong rank to openapi.json + the typed client'
+  );
+});
+
+await test('unsatisfy stays ARCHON — the backward ratchet is not part of this grant', () => {
+  assert.match(
+    doneWhenSrc,
+    /router\.post\('\/done-when\/:criterionId\/unsatisfy',\s*auth\.requireBuilder,\s*auth\.requireRank\('archon'\)/,
+    'un-flipping a confirmed criterion rewrites shipped scope-truth'
+  );
+  assert.equal(MODULE_EXPECTED_RANKS.lifecycle['POST /done-when/:criterionId/unsatisfy'], 'archon');
+});
+
+await test('the route-rank PIN records metic+archon (fitness reds the build on drift)', () => {
+  assert.equal(MODULE_EXPECTED_RANKS.lifecycle['POST /versions/:id/done-when'], 'metic+archon');
+});
+
+summary();

package/tests/criterion_progress.mjs

@@ -17,7 +17,7 @@ import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const { buildCriterionProgress, buildGoals } = require('../modules/lifecycle/done-when.js');
+const { buildCriterionProgress, buildGoals, isPendingReview } = require('../modules/lifecycle/done-when.js');
 
 let passed = 0;
 let failed = 0;
@@ -215,6 +215,38 @@ test('buildGoals: pure grouping, empty goalRows → []', () => {
   assert.deepEqual(buildGoals([], []), []);
 });
 
+// isPendingReview — the ONE derivation of the "met — pending review" flag
+// (task 1002164). Extracted so the rollup here and the hall's goal-detail read
+// (db.listCriteriaForGoal) cannot drift apart; the SQL HAVING clause in
+// listPendingReviewCriteria is the third expression of the same rule.
+test('isPendingReview: every linked task shipped + not yet confirmed → true', () => {
+  assert.equal(isPendingReview({ satisfied: false, linked: 2, unshipped: 0 }), true);
+});
+
+test('isPendingReview: an already-confirmed criterion is never pending', () => {
+  assert.equal(isPendingReview({ satisfied: true, linked: 2, unshipped: 0 }), false);
+});
+
+test('isPendingReview: zero linked tasks is NOT pending (no vacuous auto-flag)', () => {
+  assert.equal(isPendingReview({ satisfied: false, linked: 0, unshipped: 0 }), false);
+});
+
+test('isPendingReview: any unshipped linked task blocks the flag', () => {
+  assert.equal(isPendingReview({ satisfied: false, linked: 3, unshipped: 1 }), false);
+});
+
+test('isPendingReview: agrees with the rollup it was extracted from', () => {
+  // Same fixture through buildCriterionProgress — the two must never disagree.
+  const shipped = [row(1, 10, 'c', false, 100, 'a', 'shipped'), row(1, 10, 'c', false, 101, 'b', 'shipped')];
+  const mixed = [row(1, 11, 'd', false, 200, 'c', 'shipped'), row(1, 11, 'd', false, 201, 'd', 'ready')];
+  const a = buildCriterionProgress('V', shipped, 0).criteria[0];
+  const b = buildCriterionProgress('V', mixed, 0).criteria[0];
+  assert.equal(a.pending_review, isPendingReview({ satisfied: a.satisfied, linked: a.counts.total, unshipped: a.counts.remaining }));
+  assert.equal(b.pending_review, isPendingReview({ satisfied: b.satisfied, linked: b.counts.total, unshipped: b.counts.remaining }));
+  assert.equal(a.pending_review, true);
+  assert.equal(b.pending_review, false);
+});
+
 console.log('');
 console.log(`criterionProgress aggregation tests: ${passed} passed, ${failed} failed`);
 if (failed > 0) process.exit(1);

package/tests/dev_lib.mjs

@@ -0,0 +1,253 @@
+// tests/dev_lib.mjs — hermetic unit smoke for scripts/gds/dev-lib.js (the `bongos
+// dev` local launcher core, ADR 0149). NO real spawn, DB, network, or fs writes:
+// fs / spawn / kill / fetchImpl / env / userInfo are all injected.
+//
+// Run:  node tests/dev_lib.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const lib = require('../scripts/gds/dev-lib.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.stack || e.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); }
+}
+
+// A fake fs.readFileSync that maps by path suffix; unknown paths throw ENOENT.
+function fakeFs(map) {
+  return {
+    readFileSync(p) {
+      for (const [suffix, body] of Object.entries(map)) {
+        if (String(p).endsWith(suffix)) return body;
+      }
+      const e = new Error('ENOENT'); e.code = 'ENOENT'; throw e;
+    },
+  };
+}
+
+const NEUTRAL = JSON.stringify({
+  domains: { publicOrigin: 'http://localhost:3000' },
+  db: { database: null }, firstAdmin: '', envPrefix: 'CLOUDBONGOS', configDir: 'cloudbongos',
+});
+
+// ---------- port derivation ----------
+t('parsePort: reads the branding port, falls back when none/invalid', () => {
+  assert.equal(lib.parsePort('http://localhost:3006'), 3006);
+  assert.equal(lib.parsePort('https://cloudbongos.com'), 3000); // no explicit port
+  assert.equal(lib.parsePort('not-a-url'), 3000);
+  assert.equal(lib.parsePort('http://localhost:3006', 9999), 3006);
+});
+
+// ---------- db name coercion + precedence ----------
+t('sanitizeDbName: legal pg identifier, leading digit fixed, junk -> null', () => {
+  assert.equal(lib.sanitizeDbName('Test4'), 'test4');
+  assert.equal(lib.sanitizeDbName('my cool app!'), 'my_cool_app');
+  assert.equal(lib.sanitizeDbName('9lives'), 'db_9lives');
+  assert.equal(lib.sanitizeDbName('---'), null);
+  assert.equal(lib.sanitizeDbName(''), null);
+});
+
+t('deriveDbName: override > branding > repo dir > default', () => {
+  assert.equal(lib.deriveDbName({ override: 'Chosen', brandingDbName: 'b', instanceRoot: '/x/r' }), 'chosen');
+  assert.equal(lib.deriveDbName({ brandingDbName: 'brandDb', instanceRoot: '/x/r' }), 'branddb');
+  assert.equal(lib.deriveDbName({ brandingDbName: null, instanceRoot: '/Users/x/test4' }), 'test4');
+  assert.equal(lib.deriveDbName({ brandingDbName: null, instanceRoot: null }), 'cloudbongos_dev');
+});
+
+// ---------- branding facts (instance over neutral) ----------
+t('loadBrandingFacts: instance pack wins, neutral fills gaps', () => {
+  const f = fakeFs({
+    'config/branding.json': JSON.stringify({ domains: { publicOrigin: 'http://localhost:3006' }, firstAdmin: 'lars589', envPrefix: 'CLOUDBONGOS' }),
+    'config/branding.neutral.json': NEUTRAL,
+  });
+  const facts = lib.loadBrandingFacts({ instanceRoot: '/x/test4', coreRoot: '/core', f });
+  assert.equal(facts.publicOrigin, 'http://localhost:3006');
+  assert.equal(facts.firstAdmin, 'lars589');
+  assert.equal(facts.configDir, 'cloudbongos');
+});
+
+// ---------- full run params ----------
+t('resolveRunParams: port from branding, db from repo dir, TCP localhost, gdsOnly', () => {
+  const f = fakeFs({
+    'config/branding.json': JSON.stringify({ domains: { publicOrigin: 'http://localhost:3006' }, firstAdmin: 'lars589' }),
+    'config/branding.neutral.json': NEUTRAL,
+    'config/modules.json': JSON.stringify({ modules: { game: false } }),
+  });
+  const p = lib.resolveRunParams({ instanceRoot: '/Users/x/test4', coreRoot: '/core', f, env: {}, userInfo: () => ({ username: 'lars' }), argv: [] });
+  assert.equal(p.port, 3006);
+  assert.equal(p.dbName, 'test4');
+  assert.equal(p.pgHost, 'localhost');   // NOT the /var/run/postgresql linux socket
+  assert.equal(p.pgUser, 'lars');
+  assert.equal(p.gdsOnly, true);         // game off -> skip OTB seeds
+  assert.equal(p.publicOrigin, 'http://localhost:3006');
+  assert.equal(p.firstAdmin, 'lars589');
+});
+
+t('resolveRunParams: game module ON -> not GDS-only; env PGHOST/PGUSER honored', () => {
+  const f = fakeFs({
+    'config/branding.json': JSON.stringify({ domains: { publicOrigin: 'http://localhost:3006' } }),
+    'config/branding.neutral.json': NEUTRAL,
+    'config/modules.json': JSON.stringify({ modules: { game: true } }),
+  });
+  const p = lib.resolveRunParams({ instanceRoot: '/x/g', coreRoot: '/core', f, env: { PGHOST: '/tmp', PGUSER: 'bob' }, userInfo: () => ({ username: 'ignored' }), argv: [] });
+  assert.equal(p.gdsOnly, false);
+  assert.equal(p.pgHost, '/tmp');
+  assert.equal(p.pgUser, 'bob');
+});
+
+t('resolveRunParams: --port and --db overrides win', () => {
+  const f = fakeFs({
+    'config/branding.json': JSON.stringify({ domains: { publicOrigin: 'http://localhost:3006' } }),
+    'config/branding.neutral.json': NEUTRAL,
+    'config/modules.json': JSON.stringify({ modules: {} }),
+  });
+  const p = lib.resolveRunParams({ instanceRoot: '/x/test4', coreRoot: '/core', f, env: {}, userInfo: () => ({ username: 'lars' }), argv: ['--port', '4010', '--db', 'Scratch'] });
+  assert.equal(p.port, 4010);
+  assert.equal(p.dbName, 'scratch');
+});
+
+// ---------- child env assembly ----------
+t('buildEnv: server role sets PORT/HOST + PG trio + seed policy + instance-root', () => {
+  const params = { pgHost: 'localhost', pgUser: 'lars', dbName: 'test4', gdsOnly: true, port: 3006, host: '127.0.0.1', envPrefix: 'CLOUDBONGOS', instanceRoot: '/x/test4' };
+  const env = lib.buildEnv(params, { baseEnv: { PATH: '/bin' }, role: 'server' });
+  assert.equal(env.PORT, '3006');
+  assert.equal(env.HOST, '127.0.0.1');
+  assert.equal(env.PGDATABASE, 'test4');
+  assert.equal(env.PGHOST, 'localhost');
+  assert.equal(env.PGUSER, 'lars');
+  assert.equal(env.MEDUSA_GDS_ONLY, '1');
+  assert.equal(env.CLOUDBONGOS_INSTANCE_ROOT, '/x/test4');
+  assert.equal(env.PATH, '/bin'); // baseEnv preserved
+});
+
+t('buildEnv: migrate role sets PGDATABASE but NOT PORT', () => {
+  const params = { pgHost: 'localhost', pgUser: 'lars', dbName: 'test4', gdsOnly: false, port: 3006, host: '127.0.0.1', envPrefix: 'CLOUDBONGOS', instanceRoot: '/x/test4' };
+  const env = lib.buildEnv(params, { baseEnv: {}, role: 'migrate' });
+  assert.equal(env.PGDATABASE, 'test4');
+  assert.equal(env.PORT, undefined);
+  assert.equal(env.MEDUSA_GDS_ONLY, undefined); // gdsOnly false -> not set
+});
+
+// ---------- auth prediction (mirrors auth.js loadGithubCreds) ----------
+t('authWillWork: true from env creds', () => {
+  assert.equal(lib.authWillWork({ resolveEnv: (s) => (s === 'GITHUB_CLIENT_ID' ? 'id' : s === 'GITHUB_CLIENT_SECRET' ? 'sec' : undefined), readConfigFileSync: () => null }), true);
+});
+t('authWillWork: true from config file', () => {
+  assert.equal(lib.authWillWork({ resolveEnv: () => undefined, readConfigFileSync: (n) => (n === 'gds-github.json' ? JSON.stringify({ client_id: 'i', client_secret: 's' }) : null) }), true);
+});
+t('authWillWork: false when neither', () => {
+  assert.equal(lib.authWillWork({ resolveEnv: () => undefined, readConfigFileSync: () => null }), false);
+});
+
+// ---------- managed process (pid/log per instance; probes) ----------
+t('pid/log paths are keyed per (dbName, port)', () => {
+  const a = lib.pidPath({ dbName: 'test4', port: 3006 });
+  const b = lib.pidPath({ dbName: 'test3', port: 3005 });
+  assert.notEqual(a, b);
+  assert.match(a, /bongos-dev-test4-3006\.pid$/);
+});
+
+t('readPid / pidAlive / isRunning with injected fs + kill', () => {
+  const params = { dbName: 'test4', port: 3006 };
+  const deps = { fs: { readFileSync: () => '4242\n' }, kill: (pid, sig) => { if (pid !== 4242) { const e = new Error('ESRCH'); e.code = 'ESRCH'; throw e; } } };
+  assert.equal(lib.readPid(params, deps), 4242);
+  assert.equal(lib.pidAlive(4242, deps), true);
+  assert.equal(lib.isRunning(params, deps), true);
+  assert.equal(lib.pidAlive(0, deps), false);
+});
+
+t('startDetached: no-op when already running', () => {
+  const params = { dbName: 'test4', port: 3006, publicOrigin: 'http://localhost:3006' };
+  const deps = { fs: { readFileSync: () => '99\n' }, kill: () => true };
+  const r = lib.startDetached(params, deps);
+  assert.equal(r.already, true);
+  assert.equal(r.pid, 99);
+});
+
+t('startDetached: spawns the server entry with the server env, detached', () => {
+  let spawnCall = null;
+  const params = { dbName: 'test4', port: 3006, host: '127.0.0.1', pgHost: 'localhost', pgUser: 'lars', gdsOnly: true, envPrefix: 'CLOUDBONGOS', instanceRoot: '/x/test4', coreRoot: '/core', publicOrigin: 'http://localhost:3006' };
+  const writes = {};
+  const deps = {
+    fs: { readFileSync: () => { const e = new Error('ENOENT'); e.code = 'ENOENT'; throw e; }, openSync: () => 7, writeFileSync: (p, v) => { writes[p] = v; } },
+    kill: () => { const e = new Error('ESRCH'); e.code = 'ESRCH'; throw e; },
+    spawn: (bin, args, opts) => { spawnCall = { bin, args, opts }; return { pid: 555, unref() {} }; },
+    env: { PATH: '/bin' }, nodePath: '/usr/bin/node',
+  };
+  const r = lib.startDetached(params, deps);
+  assert.equal(r.already, false);
+  assert.equal(r.pid, 555);
+  assert.equal(spawnCall.args[0], '/core/src/platform-server.js');
+  assert.equal(spawnCall.opts.cwd, '/x/test4');
+  assert.equal(spawnCall.opts.detached, true);
+  assert.equal(spawnCall.opts.env.PORT, '3006');
+  assert.equal(spawnCall.opts.env.PGDATABASE, 'test4');
+  assert.match(writes[lib.pidPath(params, deps)], /555/);
+});
+
+t('stop: kills a live pid, reports not-running otherwise', () => {
+  const params = { dbName: 'test4', port: 3006 };
+  let killed = null;
+  const live = { fs: { readFileSync: () => '77\n', rmSync() {} }, kill: (pid, sig) => { if (sig === 0) return true; killed = pid; } };
+  assert.equal(lib.stop(params, live).wasRunning, true);
+  assert.equal(killed, 77);
+  const dead = { fs: { readFileSync: () => { const e = new Error('ENOENT'); e.code = 'ENOENT'; throw e; }, rmSync() {} }, kill: () => {} };
+  assert.equal(lib.stop(params, dead).wasRunning, false);
+});
+
+await ta('health: up + authConfigured parsed from the two healthz routes', async () => {
+  const params = { port: 3006 };
+  const deps = { fetchImpl: async (url) => {
+    if (url.endsWith('/api/gds/healthz')) return { status: 200, json: async () => ({ ok: true, auth_configured: true }) };
+    if (url.endsWith('/healthz')) return { status: 200 };
+    return { status: 404 };
+  } };
+  const h = await lib.health(params, deps);
+  assert.equal(h.up, true);
+  assert.equal(h.authConfigured, true);
+});
+
+await ta('health: down when /healthz unreachable', async () => {
+  const params = { port: 3006 };
+  const deps = { fetchImpl: async () => { throw new Error('ECONNREFUSED'); } };
+  const h = await lib.health(params, deps);
+  assert.equal(h.up, false);
+  assert.equal(h.authConfigured, false);
+});
+
+// ---------- depsInstallPlan (task 1002405) ----------
+// A fake fs.existsSync: a path "exists" iff it ends with one of the given suffixes.
+function fakeExists(present = []) {
+  return { existsSync: (p) => present.some((suf) => String(p).endsWith(suf)) };
+}
+
+t('depsInstallPlan: node_modules present → not needed', () => {
+  const plan = lib.depsInstallPlan({ instanceRoot: '/x/inst', f: fakeExists(['node_modules']) });
+  assert.equal(plan.needed, false);
+  assert.equal(plan.cmd, null);
+  assert.deepEqual(plan.args, []);
+});
+
+t('depsInstallPlan: no node_modules + lockfile → npm ci (reproducible)', () => {
+  const plan = lib.depsInstallPlan({ instanceRoot: '/x/inst', f: fakeExists(['package-lock.json']) });
+  assert.equal(plan.needed, true);
+  assert.equal(plan.cmd, 'ci');
+  assert.deepEqual(plan.args, ['ci']);
+});
+
+t('depsInstallPlan: no node_modules + no lockfile → npm install', () => {
+  const plan = lib.depsInstallPlan({ instanceRoot: '/x/inst', f: fakeExists([]) });
+  assert.equal(plan.needed, true);
+  assert.equal(plan.cmd, 'install');
+  assert.deepEqual(plan.args, ['install']);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/tests/devbox_artifact_gate.mjs

@@ -0,0 +1,75 @@
+// tests/devbox_artifact_gate.mjs — task 1001463 (from idea 308).
+//
+// Guards the Actions-storage quota invariant in .github/workflows/build-devbox-app.yml:
+// an ungated upload of ~500MB of installers on every `claude/**` push filled the shared
+// storage cap and blocked ALL artifact uploads repo-wide. So every upload-artifact step
+// must be ref-gated to `main` AND retention-bounded — while the BUILD jobs stay ungated
+// (feature-branch CI feedback is the point of building there at all).
+//
+// Regex/line based like scripts/gds/lint-workflow-exec.js — the repo carries no YAML
+// parser in its declared deps, and a test in tests/ must stay publishable (no transitive
+// imports). DB-free, no network. Run: node tests/devbox_artifact_gate.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const WF = path.resolve(__dirname, '..', '.github', 'workflows', 'build-devbox-app.yml');
+const MAX_RETENTION_DAYS = 7; // installers are republished to the releases repo; CI is not the archive
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (err) { console.error(`  FAIL ${name}`); console.error('    ', err.message); failed++; }
+}
+
+const lines = fs.readFileSync(WF, 'utf8').split(/\r?\n/);
+// A step starts at a `- key:` list item; its block runs to the next list item at any indent.
+const stepStarts = lines.reduce((acc, l, i) => (/^\s+-\s+\S/.test(l) ? [...acc, i] : acc), []);
+function stepBlockAt(lineIdx) {
+  const start = stepStarts.filter((i) => i <= lineIdx).pop();
+  const end = stepStarts.find((i) => i > lineIdx) ?? lines.length;
+  return lines.slice(start, end);
+}
+
+const uploadLines = lines.reduce(
+  (acc, l, i) => (l.includes('uses: actions/upload-artifact@') ? [...acc, i] : acc), []);
+
+test('both installer uploads are still present (mac dmg + win exe)', () => {
+  assert.equal(uploadLines.length, 2, `expected 2 upload-artifact steps, found ${uploadLines.length}`);
+});
+
+test('every upload is ref-gated to main (quota) — ref-based so workflow_dispatch on main uploads', () => {
+  for (const i of uploadLines) {
+    const block = stepBlockAt(i).join('\n');
+    const m = /^\s+if:\s*(.+?)\s*$/m.exec(block);
+    assert.ok(m, `upload step at line ${i + 1} has no if: gate — an ungated upload refills the quota`);
+    assert.equal(m[1], "github.ref == 'refs/heads/main'",
+      `upload step at line ${i + 1} gate must be the trusted-ref test, not an event_name test (got: ${m[1]})`);
+  }
+});
+
+test('every upload is retention-bounded', () => {
+  for (const i of uploadLines) {
+    const block = stepBlockAt(i).join('\n');
+    const m = /^\s+retention-days:\s*(\d+)\s*$/m.exec(block);
+    assert.ok(m, `upload step at line ${i + 1} has no retention-days — GitHub defaults to 90`);
+    const days = Number(m[1]);
+    assert.ok(days >= 1 && days <= MAX_RETENTION_DAYS,
+      `upload step at line ${i + 1} retention-days=${days}, want 1..${MAX_RETENTION_DAYS}`);
+  }
+});
+
+test('the BUILD jobs stay ungated — feature branches must still compile (CI feedback)', () => {
+  const jobLevelIf = lines.filter((l) => /^ {4}if:/.test(l));
+  assert.deepEqual(jobLevelIf, [], `a job-level if: would stop feature branches from building: ${jobLevelIf}`);
+});
+
+test('claude/** push trigger intact — the gate is on upload, not on running the workflow', () => {
+  assert.ok(lines.some((l) => /^\s+-\s+'claude\/\*\*'\s*$/.test(l)), "push trigger lost 'claude/**'");
+});
+
+console.log(`\ndevbox_artifact_gate: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);