@bongos/core 1.17.0

package/tests/init.mjs

@@ -0,0 +1,463 @@
+// tests/init.mjs
+//
+// Unit tests for the PURE builders of `bongos init` (scripts/gds/init.js,
+// task 1204 / V4.R65) — config assembly, kickoff-task generation, spec
+// validation, and the version payload. No I/O, no network (writeConfigs /
+// seedViaApi are exercised end-to-end by `bongos init --dry-run` + the C8
+// self-build proof; here we pin the dependency-free logic).
+//
+// Run:  node tests/init.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const init = require('../scripts/gds/init.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+const fullSpec = () => init.normalizeSpec({
+  identity: { productName: 'Cloud Bongos' },
+  tagline: 'Building software is laying down a beat.',
+  repo: { owner: 'lars589', name: 'cloud-bongos' },
+  firstAdmin: 'lars589',
+  currency: { label: 'credits' },
+  domains: { publicOrigin: 'http://localhost:3000' },
+  modules: ['art-pipeline'],
+  version: { id: 'V1', name: 'V1 — Prove the loop', done_when: 'A task goes claim → grade → ship.' },
+});
+
+// ---- slugify ----
+test('slugify: lowercases, dashes, trims, caps length', () => {
+  assert.equal(init.slugify('First Goal!'), 'first-goal');
+  assert.equal(init.slugify('  --weird__id-- '), 'weird-id');
+  assert.equal(init.slugify(''), 'goal');                 // fallback
+  assert.equal(init.slugify('', 'x'), 'x');
+});
+
+// ---- buildBrandingConfig ----
+test('buildBrandingConfig: lean overrides only (no theme block)', () => {
+  const b = init.buildBrandingConfig(fullSpec());
+  assert.equal(b.identity.productName, 'Cloud Bongos');
+  assert.equal(b.identity.worldName, 'Cloud Bongos');     // defaults to productName
+  assert.equal(b.repo.owner, 'lars589');
+  assert.equal(b.firstAdmin, 'lars589');
+  assert.equal(b.currency.label, 'credits');
+  assert.equal(b.envPrefix, 'CLOUDBONGOS');
+  assert.equal(b.copy.tagline, 'Building software is laying down a beat.');
+  assert.equal(b.theme, undefined);                       // lean — neutral fills the look
+  assert.equal(b.domains.buildersOrigin, 'http://localhost:3000');
+});
+
+test('buildBrandingConfig: no tagline → no copy block', () => {
+  const spec = fullSpec(); delete spec.tagline;
+  assert.equal(init.buildBrandingConfig(spec).copy, undefined);
+});
+
+// ---- buildModulesConfig ----
+test('buildModulesConfig: every known module present, enabled ones true', () => {
+  const m = init.buildModulesConfig(fullSpec()).modules;
+  assert.deepEqual(Object.keys(m).sort(), [...init.KNOWN_MODULES].sort());
+  assert.equal(m['art-pipeline'], true);
+  assert.equal(m.game, false);
+  assert.equal(m.discord, false);
+  assert.equal(m['dev-box'], false);
+});
+
+test('buildModulesConfig: vanilla (no modules) = all off', () => {
+  const m = init.buildModulesConfig(init.normalizeSpec({ modules: [] })).modules;
+  assert.ok(init.KNOWN_MODULES.every((k) => m[k] === false));
+});
+
+// ---- buildHierarchyConfig (ADR 0086 §1) ----
+test('buildHierarchyConfig: default = the six-tier preset with goal/criteria roles', () => {
+  const h = init.buildHierarchyConfig(fullSpec());
+  assert.deepEqual(h.tiers.map((t) => t.key), ['project', 'version', 'goal', 'criteria', 'task', 'subtask']);
+  assert.ok(h.tiers.every((t) => t.enabled === true));
+  assert.deepEqual(h.roles, { scope: 'goal', membership: 'goal', criteria: 'criteria' });
+  assert.ok(/Cloud Bongos/.test(h._note)); // note carries the instance name
+});
+
+test('buildHierarchyConfig: owner overrides flow through (label/enabled/roles)', () => {
+  const spec = fullSpec();
+  spec.hierarchy = { labels: { goal: 'Objective' }, enabled: { subtask: false }, roles: { scope: 'goal' } };
+  const h = init.buildHierarchyConfig(spec);
+  assert.equal(h.tiers.find((t) => t.key === 'goal').label, 'Objective');
+  assert.equal(h.tiers.find((t) => t.key === 'subtask').enabled, false);
+  assert.equal(h.tiers.find((t) => t.key === 'version').label, 'Version'); // untouched
+  assert.equal(h.roles.scope, 'goal');
+});
+
+// ---- kickoffTasks ----
+test('kickoffTasks: 7 base steps + 1 per enabled module', () => {
+  const base = init.kickoffTasks(init.normalizeSpec({ modules: [], firstAdmin: 'x', repo: { owner: 'o', name: 'n' } }));
+  assert.equal(base.length, 7);
+  const withArt = init.kickoffTasks(fullSpec());
+  assert.equal(withArt.length, 8);                        // +1 Gemini key task
+  assert.ok(withArt.some((t) => /Gemini/i.test(t.title)));
+  const all = init.kickoffTasks(init.normalizeSpec({ modules: ['art-pipeline', 'discord', 'dev-box'], firstAdmin: 'x', repo: { owner: 'o', name: 'n' } }));
+  assert.equal(all.length, 10);
+});
+
+test('kickoffTasks: includes the load-bearing owner-manual steps', () => {
+  const t = init.kickoffTasks(fullSpec());
+  assert.ok(t.some((x) => /OAuth/i.test(x.title)), 'OAuth app step');
+  assert.ok(t.some((x) => /founding owner/i.test(x.title)), 'first sign-in step');
+  assert.ok(t.every((x) => x.title && x.description), 'every step has a title + description');
+});
+
+// ---- validateSpec ----
+test('validateSpec: complete spec → no errors', () => {
+  assert.deepEqual(init.validateSpec(fullSpec()), []);
+});
+
+test('validateSpec: surfaces every missing required field', () => {
+  const errs = init.validateSpec(init.normalizeSpec({}));
+  assert.ok(errs.some((e) => /productName/.test(e)));
+  assert.ok(errs.some((e) => /repo\.owner/.test(e)));
+  assert.ok(errs.some((e) => /firstAdmin/.test(e)));
+  assert.ok(errs.some((e) => /version\.id/.test(e)));
+  assert.ok(errs.some((e) => /done_when/.test(e)));
+});
+
+test('validateSpec: rejects an unknown module', () => {
+  const spec = init.normalizeSpec(fullSpec());
+  spec.modules = ['payments'];   // normalizeSpec filters unknowns, so push past it
+  // normalizeSpec already strips unknowns; assert the filter happened
+  assert.deepEqual(init.normalizeSpec({ modules: ['payments', 'game'] }).modules, ['game']);
+});
+
+// ---- normalizeSpec ----
+test('normalizeSpec: defaults version.status, filters modules', () => {
+  const s = init.normalizeSpec({ modules: ['game', 'bogus'] });
+  assert.equal(s.version.status, 'building');
+  assert.deepEqual(s.modules, ['game']);
+});
+
+// ---- versionPayload ----
+test('versionPayload: clean default criterion_id when none given', () => {
+  const vp = init.versionPayload(fullSpec());
+  assert.equal(vp.id, 'V1');
+  assert.equal(vp.status, 'building');
+  assert.equal(vp.criteria.length, 1);
+  assert.equal(vp.criteria[0].criterion_id, 'first-goal');
+  assert.equal(vp.criteria[0].criterion_md, 'A task goes claim → grade → ship.');
+});
+
+test('versionPayload: explicit criterion_id is slugified', () => {
+  const spec = fullSpec();
+  spec.version.criterion_id = 'Prove The Loop';
+  assert.equal(init.versionPayload(spec).criteria[0].criterion_id, 'prove-the-loop');
+});
+
+// ---- provisioning arm (ADR 0111 §3, task 1946) ----
+const provSpec = (over = {}) => init.normalizeSpec({
+  identity: { productName: 'Cloud Bongos' },
+  repo: { owner: 'lars589', name: 'cloud-bongos' },
+  firstAdmin: 'lars589',
+  version: { id: 'V1', name: 'V1', done_when: 'x' },
+  provisioning: over,
+});
+
+test('provisioningSlug: derives from productName, clamps to 40, strips trailing dash', () => {
+  assert.equal(init.provisioningSlug(fullSpec()), 'cloud-bongos');       // no block → still derivable
+  assert.equal(init.provisioningSlug(provSpec({ slug: 'My Instance!' })), 'my-instance'); // explicit wins
+  const long = provSpec({ slug: 'a'.repeat(60) });
+  assert.equal(init.provisioningSlug(long).length, 40);                  // clamped
+  const dashy = provSpec({ slug: 'a'.repeat(39) + '-bb' });              // clamp (slice 0,40) lands on the dash
+  assert.equal(init.provisioningSlug(dashy), 'a'.repeat(39), 'trailing dash stripped after clamp');
+});
+
+test('provisioningRequest: null unless opted in; builds the POST body when opted in', () => {
+  assert.equal(init.provisioningRequest(fullSpec()), null);              // no block → not requested
+  const co = init.provisioningRequest(provSpec({}));                     // empty block = opted in, defaults
+  assert.deepEqual(co, { slug: 'cloud-bongos', hosting_shape: 'co-tenant' });
+  const full = init.provisioningRequest(provSpec({ shape: 'dedicated', domain: 'example.com', targetRef: 'do:main', tier: 's-1vcpu-2gb' }));
+  assert.deepEqual(full, { slug: 'cloud-bongos', hosting_shape: 'dedicated', domain: 'example.com', target_ref: 'do:main', tier: 's-1vcpu-2gb' });
+});
+
+test('provisioningRequest: unknown shape falls back to the cheapest co-tenant', () => {
+  // normalizeSpec coerces a bad shape → co-tenant (the budget default, ADR 0111 §6).
+  assert.equal(init.provisioningRequest(provSpec({ shape: 'kubernetes' })).hosting_shape, 'co-tenant');
+});
+
+test('kickoffTasks: provisioning requested → production-topology is AUTOMATED (dropped), manual steps stay', () => {
+  const baseSpec = { identity: { productName: 'Cloud Bongos' }, repo: { owner: 'o', name: 'n' },
+    firstAdmin: 'x', version: { id: 'V1', name: 'V1', done_when: 'x' } };
+  const manual = init.kickoffTasks(init.normalizeSpec(baseSpec));        // no provisioning
+  assert.ok(manual.some((t) => /Production topology/i.test(t.title)), 'manual keeps the production-topology task');
+  const withProv = init.kickoffTasks(init.normalizeSpec({ ...baseSpec, provisioning: { shape: 'dedicated' } }));
+  assert.ok(!withProv.some((t) => /Production topology/i.test(t.title)), 'provisioning drops the production-topology task');
+  assert.equal(withProv.length, manual.length - 1, 'exactly one fewer kickoff task');
+  assert.ok(withProv.some((t) => /OAuth/i.test(t.title)), 'OAuth stays manual');
+  assert.ok(withProv.some((t) => /founding owner/i.test(t.title)), 'first sign-in stays manual');
+});
+
+test('normalizeSpec: coerces the provisioning block; drops it when absent', () => {
+  assert.equal(init.normalizeSpec({}).provisioning, undefined);
+  const n = init.normalizeSpec({ provisioning: { shape: 'DEDICATED', domain: '  Example.com  ', junk: 1 } });
+  assert.equal(n.provisioning.shape, 'co-tenant');                       // unknown shape (case) → default
+  assert.equal(n.provisioning.domain, 'Example.com');                    // trimmed
+  assert.equal(n.provisioning.junk, undefined);                          // stray field dropped
+});
+
+test('validateSpec: valid provisioning passes; flags an underivable slug', () => {
+  assert.deepEqual(init.validateSpec(provSpec({ shape: 'dedicated' })), []);
+  // productName 'x' slugifies to a 1-char slug (< the module's 2-char floor) and no
+  // explicit provisioning.slug overrides it → flagged before the server 400s.
+  const bad = init.normalizeSpec({ identity: { productName: 'x' }, repo: { owner: 'o', name: 'n' }, firstAdmin: 'x',
+    version: { id: 'V1', name: 'V1', done_when: 'x' }, provisioning: {} });
+  assert.ok(init.validateSpec(bad).some((e) => /valid instance slug/.test(e)), 'flags an underivable slug');
+});
+
+// ---- adopt (brownfield) — ADR 0121 / task 2042 -----------------------------
+const rawAdopt = () => ({
+  identity: { productName: 'Mercury' },
+  repo: { owner: 'acme', name: 'mercury' },
+  firstAdmin: 'acme-owner',
+  currency: { label: 'credits' },
+  domains: { publicOrigin: 'https://mercury.example.com' },
+  modules: [],
+  // NO version block — supplied by the interview/spec when adopt seeds real state.
+});
+const adoptSpec = () => init.normalizeSpec(rawAdopt());
+
+test('validateSpec(adopt, noSeed): version NOT required (layering-only); identity/repo/firstAdmin still are', () => {
+  assert.deepEqual(init.validateSpec(adoptSpec(), { adopt: true, noSeed: true }), []);
+  const errs = init.validateSpec(init.normalizeSpec({}), { adopt: true, noSeed: true });
+  assert.ok(errs.some((e) => /productName/.test(e)));
+  assert.ok(errs.some((e) => /repo\.owner/.test(e)));
+  assert.ok(errs.some((e) => /firstAdmin/.test(e)));
+  assert.ok(!errs.some((e) => /version/.test(e)), 'no version errors when adopt --no-seed');
+});
+
+test('validateSpec(adopt, seeding): version IS required — adopt reflects the repo REAL version (task 2044)', () => {
+  assert.ok(init.validateSpec(adoptSpec(), { adopt: true }).some((e) => /version\.id/.test(e)), 'seeding adopt demands a real version');
+  const withV = init.normalizeSpec({ ...rawAdopt(), version: { id: 'v3.2', name: 'Q3 milestone', done_when: 'checkout ships' } });
+  assert.deepEqual(init.validateSpec(withV, { adopt: true }), [], 'a real current version satisfies it');
+});
+
+test('validateSpec(greenfield): version still required (regression)', () => {
+  assert.ok(init.validateSpec(adoptSpec()).some((e) => /version\.id/.test(e)));
+});
+
+test('coreDepRange: caret over the running CORE_VERSION', () => {
+  assert.match(init.coreDepRange(), /^\^\d+\.\d+\.\d+/);
+});
+
+test('mergeCoreDependency: no package.json → mints a minimal private one with the pinned dep', () => {
+  const { pkg, action } = init.mergeCoreDependency(null, { coreRange: '^1.16.0', name: 'mercury' });
+  assert.equal(action, 'created');
+  assert.equal(pkg.name, 'mercury');
+  assert.equal(pkg.private, true);
+  assert.equal(pkg.dependencies[init.CORE_PKG], '^1.16.0');
+});
+
+test('mergeCoreDependency: adds the dep, preserving every existing field + their deps', () => {
+  const existing = { name: 'their-app', version: '2.3.0', scripts: { test: 'jest' }, dependencies: { express: '^4' } };
+  const { pkg, action } = init.mergeCoreDependency(existing, { coreRange: '^1.16.0' });
+  assert.equal(action, 'added');
+  assert.equal(pkg.name, 'their-app');
+  assert.equal(pkg.version, '2.3.0');
+  assert.deepEqual(pkg.scripts, { test: 'jest' });
+  assert.equal(pkg.dependencies.express, '^4');
+  assert.equal(pkg.dependencies[init.CORE_PKG], '^1.16.0');
+});
+
+test('mergeCoreDependency: already a dep (deps OR devDeps) → present, NOT overwritten', () => {
+  const inDeps = { dependencies: { [init.CORE_PKG]: 'file:vendor/x.tgz' } };
+  const r1 = init.mergeCoreDependency(inDeps, { coreRange: '^1.16.0' });
+  assert.equal(r1.action, 'present');
+  assert.equal(r1.pkg.dependencies[init.CORE_PKG], 'file:vendor/x.tgz'); // existing pin kept, not clobbered
+  const inDev = { devDependencies: { [init.CORE_PKG]: '^1.0.0' } };
+  assert.equal(init.mergeCoreDependency(inDev, { coreRange: '^1.16.0' }).action, 'present');
+});
+
+test('layerConfigs + layerPackageJson: additive — writes what is absent, never clobbers what exists', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'adopt-'));
+  try {
+    const ownerPkg = { name: 'their-app', version: '9.9.9', dependencies: { react: '^18' } };
+    writeFileSync(join(dir, 'package.json'), JSON.stringify(ownerPkg, null, 2) + '\n');
+    mkdirSync(join(dir, 'config'), { recursive: true });
+    const preexistingBranding = '{"identity":{"productName":"KEEP ME"}}\n';
+    writeFileSync(join(dir, 'config', 'branding.json'), preexistingBranding);
+
+    const spec = adoptSpec();
+    const cfg = init.layerConfigs(spec, { dir, dryRun: false, log: () => {} });
+    const pkgRes = init.layerPackageJson(spec, { dir, dryRun: false, log: () => {}, coreRange: '^1.16.0' });
+
+    assert.deepEqual(cfg.left, ['branding.json']);                         // existed → left
+    assert.deepEqual(cfg.wrote.sort(), ['hierarchy.json', 'modules.json']); // absent → written
+    assert.equal(readFileSync(join(dir, 'config', 'branding.json'), 'utf8'), preexistingBranding, 'existing branding.json byte-untouched');
+    assert.ok(existsSync(join(dir, 'config', 'modules.json')));
+
+    assert.equal(pkgRes.action, 'added');
+    const merged = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+    assert.equal(merged.name, 'their-app');            // their fields preserved
+    assert.equal(merged.version, '9.9.9');
+    assert.equal(merged.dependencies.react, '^18');
+    assert.equal(merged.dependencies[init.CORE_PKG], '^1.16.0'); // ours added
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('layerPackageJson: no package.json → creates one; second run → present, byte-untouched', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'adopt-'));
+  try {
+    const created = init.layerPackageJson(adoptSpec(), { dir, dryRun: false, log: () => {}, coreRange: '^1.16.0' });
+    assert.equal(created.action, 'created');
+    assert.equal(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies[init.CORE_PKG], '^1.16.0');
+    const before = readFileSync(join(dir, 'package.json'), 'utf8');
+    const again = init.layerPackageJson(adoptSpec(), { dir, dryRun: false, log: () => {}, coreRange: '^9.9.9' });
+    assert.equal(again.action, 'present');
+    assert.equal(readFileSync(join(dir, 'package.json'), 'utf8'), before, 'present dep → no reserialize churn');
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ---- greenfield installability: package.json minting + writeConfigs (ADR 0108 gap 1/4, task 2053) ----
+// PURE — no fs, no npm. The imperative vendor + `npm install` lockfile step lives in main()
+// and is deliberately NOT unit-tested (keeps real npm out of the suite, per the task).
+test('buildInstancePackageJson: no package.json → mints a private one with the caret core dep + start/migrate scripts', () => {
+  const pkg = init.buildInstancePackageJson(null, { name: 'demo' });
+  assert.equal(pkg.name, 'demo');
+  assert.equal(pkg.private, true);
+  assert.equal(pkg.dependencies[init.CORE_PKG], init.coreDepRange());   // caret when no tarball vendored
+  assert.equal(pkg.scripts.start, init.INSTANCE_START_SCRIPT);
+  assert.equal(pkg.scripts.migrate, init.INSTANCE_MIGRATE_SCRIPT);
+  // the start/migrate scripts must target the installed core package so `npm ci` output is runnable
+  assert.match(pkg.scripts.start, /node_modules\/@cloudbongos\/core\/src\/platform-server\.js$/);
+  assert.match(pkg.scripts.migrate, /node_modules\/@cloudbongos\/core\/scripts\/migrate\.sh$/);
+});
+
+test('buildInstancePackageJson: coreDep (file: tarball pin) → the dep is the file: pin, not the caret', () => {
+  const pin = 'file:vendor/cloudbongos-core-1.17.0.tgz';
+  const pkg = init.buildInstancePackageJson(null, { name: 'demo', coreDep: pin });
+  assert.equal(pkg.dependencies[init.CORE_PKG], pin);
+  assert.notEqual(pkg.dependencies[init.CORE_PKG], init.coreDepRange());
+});
+
+test('buildInstancePackageJson: preserves existing fields + never clobbers a custom start/migrate', () => {
+  const existing = { name: 'keep-me', version: '2.0.0', scripts: { start: 'node server.js' }, keywords: ['x'] };
+  const pkg = init.buildInstancePackageJson(existing, { name: 'ignored', coreDep: 'file:vendor/cloudbongos-core-1.17.0.tgz' });
+  assert.equal(pkg.name, 'keep-me');                         // existing name wins
+  assert.equal(pkg.version, '2.0.0');                        // untouched field preserved
+  assert.deepEqual(pkg.keywords, ['x']);
+  assert.equal(pkg.scripts.start, 'node server.js');         // custom start NOT clobbered
+  assert.equal(pkg.scripts.migrate, init.INSTANCE_MIGRATE_SCRIPT); // missing one is filled
+  assert.equal(pkg.dependencies[init.CORE_PKG], 'file:vendor/cloudbongos-core-1.17.0.tgz'); // dep (re)pinned
+});
+
+test('writeConfigs (greenfield): mints package.json with the caret core dep + start/migrate scripts', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'greenfield-'));
+  try {
+    const res = init.writeConfigs(fullSpec(), { dir, force: false, dryRun: false, log: () => {} });
+    assert.ok(existsSync(res.pkgPath), 'package.json written');
+    const pkg = JSON.parse(readFileSync(res.pkgPath, 'utf8'));
+    assert.equal(pkg.name, 'cloud-bongos');                  // slugified productName
+    assert.equal(pkg.private, true);
+    assert.equal(pkg.dependencies[init.CORE_PKG], init.coreDepRange());
+    assert.equal(pkg.scripts.start, init.INSTANCE_START_SCRIPT);
+    assert.equal(pkg.scripts.migrate, init.INSTANCE_MIGRATE_SCRIPT);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('writeConfigs (greenfield, --vendor-core): package.json pins the file: tarball instead of the caret', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'greenfield-'));
+  try {
+    const pin = 'file:vendor/cloudbongos-core-1.17.0.tgz';
+    const res = init.writeConfigs(fullSpec(), { dir, force: false, dryRun: false, coreDep: pin, log: () => {} });
+    const pkg = JSON.parse(readFileSync(res.pkgPath, 'utf8'));
+    assert.equal(pkg.dependencies[init.CORE_PKG], pin);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('writeConfigs (greenfield, dry-run): writes nothing to disk', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'greenfield-'));
+  try {
+    const res = init.writeConfigs(fullSpec(), { dir, force: false, dryRun: true, log: () => {} });
+    assert.equal(res.wrote, false);
+    assert.equal(existsSync(join(dir, 'package.json')), false, 'dry-run mints nothing');
+    assert.equal(existsSync(join(dir, 'config')), false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+// ---- seedViaApi provisioning arm (live path, injected fake api) ----
+// A fake apiCall that records calls and returns a configured response per path
+// substring (default: 200 ok). Lets us exercise the live seedViaApi branching
+// (POST the request; 404/error → fall back to the manual task) with no server.
+function fakeApi(responses = []) {
+  const calls = [];
+  const api = async (method, path, body) => {
+    calls.push({ method, path, body });
+    for (const [match, res] of responses) if (path.includes(match)) return res;
+    return { ok: true, status: 200, data: {} };
+  };
+  api.calls = calls;
+  return api;
+}
+const findTaskPost = (api, re) => api.calls.find((c) => c.path.endsWith('/tasks') && re.test((c.body && c.body.title) || ''));
+
+async function runSeedTests() {
+  const at = async (name, fn) => {
+    try { await fn(); passed++; console.log(`  ok  ${name}`); }
+    catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+  };
+
+  await at('seedViaApi: provisioning success → POSTs the request, no manual topo task, provisioned:true', async () => {
+    const api = fakeApi([['/provisioning/instances', { ok: true, status: 201, data: { instance: { cost_estimate_usd: 12 } } }]]);
+    const out = await init.seedViaApi(provSpec({ shape: 'dedicated', domain: 'x.example.com', tier: 's-1vcpu-2gb' }), { log: () => {}, api });
+    assert.equal(out.provisioned, true);
+    const prov = api.calls.find((c) => c.path.includes('/provisioning/instances'));
+    assert.ok(prov, 'POSTed the provisioning request');
+    assert.equal(prov.body.slug, 'cloud-bongos');
+    assert.equal(prov.body.hosting_shape, 'dedicated');
+    assert.ok(!findTaskPost(api, /Production topology/), 'production-topology NOT filed as a manual task');
+  });
+
+  await at('seedViaApi: provisioning 404 (module off) → falls back to the manual production-topology task', async () => {
+    const api = fakeApi([['/provisioning/instances', { ok: false, status: 404, data: { error: 'not_found' } }]]);
+    const out = await init.seedViaApi(provSpec({ shape: 'co-tenant' }), { log: () => {}, api });
+    assert.equal(out.provisioned, false);
+    assert.ok(findTaskPost(api, /Production topology/), 'filed the manual fallback task');
+  });
+
+  await at('seedViaApi: provisioning error → also files the fallback task', async () => {
+    const api = fakeApi([['/provisioning/instances', { ok: false, status: 500, data: {} }]]);
+    const out = await init.seedViaApi(provSpec({ shape: 'co-tenant' }), { log: () => {}, api });
+    assert.equal(out.provisioned, false);
+    assert.ok(findTaskPost(api, /Production topology/), 'filed the manual fallback task on error');
+  });
+
+  await at('seedViaApi: no provisioning block → no provisioning POST, topo stays a normal kickoff task', async () => {
+    const spec = init.normalizeSpec({ identity: { productName: 'X Co' }, repo: { owner: 'o', name: 'n' },
+      firstAdmin: 'x', version: { id: 'V1', name: 'V1', done_when: 'ship' } });
+    const api = fakeApi();
+    const out = await init.seedViaApi(spec, { log: () => {}, api });
+    assert.equal(out.provisioned, false);
+    assert.ok(!api.calls.some((c) => c.path.includes('/provisioning/')), 'no provisioning call made');
+    assert.ok(findTaskPost(api, /Production topology/), 'production-topology filed as a normal kickoff task');
+  });
+}
+
+await runSeedTests();
+
+console.log('');
+console.log(`init tests: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/tests/instance_config.mjs

@@ -0,0 +1,76 @@
+// tests/instance_config.mjs — the instance config-namespace resolver (R61 / task 1200).
+// Pure: every input is injected, so no env mutation / disk dependence.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import os from 'node:os';
+import path from 'node:path';
+import ic from '../src/instance-config.js';
+
+const {
+  configDirName, envPrefix, configHome, configReadDirs, configReadPaths,
+  resolveEnv, FALLBACK_DIR, FALLBACK_ENV_PREFIX,
+  resolveInstanceRootExplicit, resolveDocsRoot, resolveCoreRoot,
+} = ic;
+
+test('configDirName: from branding, else the vanilla fallback (never OTB)', () => {
+  assert.equal(configDirName({ configDir: 'otb' }), 'otb');
+  assert.equal(configDirName({ configDir: 'acme' }), 'acme');
+  assert.equal(configDirName({}), FALLBACK_DIR);
+  assert.equal(FALLBACK_DIR, 'cloudbongos');
+});
+
+test('envPrefix: from branding, else the vanilla fallback', () => {
+  assert.equal(envPrefix({ envPrefix: 'OTB' }), 'OTB');
+  assert.equal(envPrefix({}), FALLBACK_ENV_PREFIX);
+  assert.equal(FALLBACK_ENV_PREFIX, 'CLOUDBONGOS');
+});
+
+test('configHome: ~/.config/<dir>', () => {
+  assert.equal(configHome({ configDir: 'acme' }), path.join(os.homedir(), '.config', 'acme'));
+});
+
+test('configReadDirs: configured first, legacy otb appended, de-duped', () => {
+  const neutral = configReadDirs({ configDir: 'cloudbongos' });
+  assert.equal(neutral[0], path.join(os.homedir(), '.config', 'cloudbongos'));
+  assert.ok(neutral.includes(path.join(os.homedir(), '.config', 'otb')), 'legacy otb always a read fallback');
+  // OTB instance: configured IS the legacy dir → exactly one entry (no dup).
+  const otb = configReadDirs({ configDir: 'otb' });
+  assert.deepEqual(otb, [path.join(os.homedir(), '.config', 'otb')]);
+});
+
+test('configReadPaths: one candidate per read dir', () => {
+  const paths = configReadPaths('gds-session.json', { configDir: 'cloudbongos' });
+  assert.ok(paths[0].endsWith(path.join('cloudbongos', 'gds-session.json')));
+  assert.ok(paths.some((p) => p.endsWith(path.join('otb', 'gds-session.json'))));
+});
+
+test('resolveEnv: configured prefix wins, then legacy [OTB, GDS, PMS]', () => {
+  // Configured (vanilla) prefix takes precedence.
+  assert.equal(resolveEnv('API_BASE', { prefix: 'CLOUDBONGOS', env: { CLOUDBONGOS_API_BASE: 'neutral', GDS_API_BASE: 'legacy' } }), 'neutral');
+  // OTB instance: configured OTB_ absent for this suffix → falls back to GDS_.
+  assert.equal(resolveEnv('API_BASE', { prefix: 'OTB', env: { GDS_API_BASE: 'legacy' } }), 'legacy');
+  // OTB_ present → wins over the legacy list.
+  assert.equal(resolveEnv('DEPLOY_MODE', { prefix: 'OTB', env: { OTB_DEPLOY_MODE: 'ci', GDS_DEPLOY_MODE: 'x' } }), 'ci');
+  // None set → undefined.
+  assert.equal(resolveEnv('NOPE', { prefix: 'CLOUDBONGOS', env: {} }), undefined);
+  // Empty string is treated as unset (skip to next prefix).
+  assert.equal(resolveEnv('X', { prefix: 'CLOUDBONGOS', env: { CLOUDBONGOS_X: '', GDS_X: 'y' } }), 'y');
+});
+
+test('resolveEnv: legacy PMS prefix still honored (original-name back-compat)', () => {
+  assert.equal(resolveEnv('GITHUB_CLIENT_ID', { prefix: 'CLOUDBONGOS', env: { PMS_GITHUB_CLIENT_ID: 'old' } }), 'old');
+});
+
+// task 2051: docs+client are per-instance artifacts written to the instance root when
+// it is EXPLICITLY pointed at (a consumer running `bongos upgrade`), else the coreRoot.
+test('resolveInstanceRootExplicit: env pointer (branded or fallback prefix), else null', () => {
+  assert.equal(resolveInstanceRootExplicit({ env: { CLOUDBONGOS_INSTANCE_ROOT: '/srv/consumer' } }), path.resolve('/srv/consumer'));
+  assert.equal(resolveInstanceRootExplicit({ env: { OTB_INSTANCE_ROOT: '/srv/otb' } }), path.resolve('/srv/otb'), 'legacy branded prefix honored');
+  // No env pointer set → null (this repo has no bongos.config.json, so no cwd-pointer fallback either).
+  assert.equal(resolveInstanceRootExplicit({ env: {} }), null);
+});
+
+test('resolveDocsRoot: the explicit instance root when set, else coreRoot (no-op in a single checkout)', () => {
+  assert.equal(resolveDocsRoot({ env: { CLOUDBONGOS_INSTANCE_ROOT: '/srv/consumer' } }), path.resolve('/srv/consumer'), 'consumer writes into its own repo');
+  assert.equal(resolveDocsRoot({ env: {} }), resolveCoreRoot(), 'single checkout: coincides with coreRoot');
+});

package/tests/instance_manifest.mjs

@@ -0,0 +1,110 @@
+// tests/instance_manifest.mjs — the instance manifest assembler (task 1249 / V4.R82, Cloud Bongos C8).
+//
+// Drives the PURE buildInstanceManifest() with fixtures (no disk/DB/git), so it
+// proves the manifest shape AND the no-secrets guarantee deterministically.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const instanceMod = require('../src/bongos/routes/instance.js');
+const { buildInstanceManifest, MANIFEST_SCHEMA, AUTH_METHODS } = instanceMod;
+
+const RANK_TIER = { xenos: 1, thetes: 2, metic: 3, archon: 4 };
+
+// A client-safe branding projection (the shape clientBranding() returns).
+const BRAND_OTB = {
+  identity: { productName: 'Off the Boats', worldName: 'Amazonprimea', company: { name: 'Hermeslines' } },
+  currency: { label: 'drachmae', symbol: '' },
+  theme: { colors: {}, fonts: { display: '', body: '', links: [] }, favicon: '', backdrop: '' },
+  copy: { tagline: 'Straight off the boats', hallName: 'Builders’ Hall', notFound: 'Page not found.' },
+  rankLabels: { xenos: 'Xenos', thetes: 'Thetes', metic: 'Metic', archon: 'Archon' },
+};
+const BRAND_VANILLA = {
+  identity: { productName: 'Cloud Bongos', worldName: 'Cloud Bongos', company: { name: '' } },
+  currency: { label: 'credits', symbol: '' },
+  theme: { colors: {}, fonts: { display: '', body: '', links: [] }, favicon: '', backdrop: '' },
+  copy: { tagline: '', hallName: 'Builders’ Hall', notFound: 'Page not found.' },
+  rankLabels: {},
+};
+const MODULES_OTB = {
+  enabled: { game: true, 'art-pipeline': true, discord: true, 'dev-box': true },
+  disciplines: ['engineer', 'artist'],
+};
+const MODULES_VANILLA = {
+  enabled: { game: false, 'art-pipeline': false, discord: false, 'dev-box': false },
+  disciplines: ['engineer'],
+};
+const REPO = { owner: 'lars589', repo: 'amazonprimea', branch: 'main', blob_base: 'x', tree_base: 'y' };
+
+test('manifest: schema id + headline name + embedded brand', () => {
+  const m = buildInstanceManifest({ branding: BRAND_OTB, modules: MODULES_OTB, rankTier: RANK_TIER, repo: REPO, authConfigured: true, openEnrollment: false, devBoxEnabled: true });
+  assert.equal(m.schema, MANIFEST_SCHEMA);
+  assert.equal(m.name, 'Off the Boats');
+  assert.equal(m.brand, BRAND_OTB);
+  assert.deepEqual(m.modules, MODULES_OTB);
+});
+
+test('manifest: rank ladder ordered entry→top, labelled from brand', () => {
+  const m = buildInstanceManifest({ branding: BRAND_OTB, modules: MODULES_OTB, rankTier: RANK_TIER, repo: REPO, authConfigured: true, openEnrollment: false, devBoxEnabled: true });
+  assert.deepEqual(m.ranks.map((r) => r.key), ['xenos', 'thetes', 'metic', 'archon']);
+  assert.deepEqual(m.ranks.map((r) => r.tier), [1, 2, 3, 4]);
+  assert.equal(m.ranks[0].label, 'Xenos');
+  assert.equal(m.ranks[3].label, 'Archon');
+});
+
+test('manifest: rank label falls back to the key when unlabelled', () => {
+  const m = buildInstanceManifest({ branding: BRAND_VANILLA, modules: MODULES_VANILLA, rankTier: RANK_TIER, repo: { error: 'no_repo_info' }, authConfigured: false, openEnrollment: false, devBoxEnabled: false });
+  assert.equal(m.ranks[0].label, 'xenos');
+  assert.equal(m.ranks[2].label, 'metic');
+});
+
+test('manifest: repo projects to public clone coords; null on error', () => {
+  const ok = buildInstanceManifest({ branding: BRAND_OTB, modules: MODULES_OTB, rankTier: RANK_TIER, repo: REPO, authConfigured: true, openEnrollment: false, devBoxEnabled: true });
+  assert.deepEqual(ok.repo, { owner: 'lars589', repo: 'amazonprimea', branch: 'main', url: 'https://github.com/lars589/amazonprimea' });
+  const none = buildInstanceManifest({ branding: BRAND_VANILLA, modules: MODULES_VANILLA, rankTier: RANK_TIER, repo: { error: 'no_repo_info' }, authConfigured: false, openEnrollment: false, devBoxEnabled: false });
+  assert.equal(none.repo, null);
+});
+
+test('manifest: auth methods gated on configured', () => {
+  const on = buildInstanceManifest({ branding: BRAND_OTB, modules: MODULES_OTB, rankTier: RANK_TIER, repo: REPO, authConfigured: true, openEnrollment: false, devBoxEnabled: true });
+  assert.deepEqual(on.auth.methods, AUTH_METHODS);
+  assert.equal(on.auth.configured, true);
+  const off = buildInstanceManifest({ branding: BRAND_VANILLA, modules: MODULES_VANILLA, rankTier: RANK_TIER, repo: { error: 'x' }, authConfigured: false, openEnrollment: false, devBoxEnabled: false });
+  assert.deepEqual(off.auth.methods, []);
+  assert.equal(off.auth.configured, false);
+});
+
+test('manifest: admission policy reflects open-enrollment flag', () => {
+  const invite = buildInstanceManifest({ branding: BRAND_OTB, modules: MODULES_OTB, rankTier: RANK_TIER, repo: REPO, authConfigured: true, openEnrollment: false, devBoxEnabled: true });
+  assert.equal(invite.admission.policy, 'invite-only');
+  const open = buildInstanceManifest({ branding: BRAND_OTB, modules: MODULES_OTB, rankTier: RANK_TIER, repo: REPO, authConfigured: true, openEnrollment: true, devBoxEnabled: true });
+  assert.equal(open.admission.policy, 'open');
+});
+
+test('manifest: dev-box availability mirrors the module flag', () => {
+  const on = buildInstanceManifest({ branding: BRAND_OTB, modules: MODULES_OTB, rankTier: RANK_TIER, repo: REPO, authConfigured: true, openEnrollment: false, devBoxEnabled: true });
+  assert.equal(on.devBox.available, true);
+  const off = buildInstanceManifest({ branding: BRAND_VANILLA, modules: MODULES_VANILLA, rankTier: RANK_TIER, repo: { error: 'x' }, authConfigured: false, openEnrollment: false, devBoxEnabled: false });
+  assert.equal(off.devBox.available, false);
+});
+
+test('manifest: no server-only secrets/topology leak into the body', () => {
+  // The assembler only ever reads the client-safe projections it is handed, so
+  // even if a caller passed a fuller object, these server-only keys must not
+  // appear. We assert on the serialized body (deep, key-name based).
+  const m = buildInstanceManifest({ branding: BRAND_OTB, modules: MODULES_OTB, rankTier: RANK_TIER, repo: REPO, authConfigured: true, openEnrollment: false, devBoxEnabled: true });
+  const json = JSON.stringify(m);
+  for (const forbidden of ['cookieDomain', 'oauthOrigin', 'publicOrigin', 'envPrefix', 'client_secret', 'dbName', 'instanceDbName', 'token']) {
+    assert.ok(!json.includes(forbidden), `manifest leaked "${forbidden}"`);
+  }
+});
+
+test('manifest: vanilla instance is fully populated (every field present)', () => {
+  const m = buildInstanceManifest({ branding: BRAND_VANILLA, modules: MODULES_VANILLA, rankTier: RANK_TIER, repo: { error: 'x' }, authConfigured: false, openEnrollment: false, devBoxEnabled: false });
+  for (const k of ['schema', 'name', 'brand', 'modules', 'ranks', 'repo', 'auth', 'admission', 'devBox']) {
+    assert.ok(k in m, `missing field ${k}`);
+  }
+  assert.equal(m.name, 'Cloud Bongos');
+  assert.deepEqual(m.modules.enabled, MODULES_VANILLA.enabled);
+});