@bongos/core 1.18.3 → 1.18.18

package/scripts/gds/preflight.js

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// scripts/gds/preflight.js — the onboarding ENVIRONMENT PREFLIGHT (task 1002401,
+// onboarding-audit area 4).
+//
+// One shared, PURE check of the three things that used to bite a brand-new
+// builder one reactive crash at a time:
+//   1. Node >= 22        — the very first command (`bongos start`) shells to node;
+//                          on a bare machine it died with `node: command not found`.
+//   2. deps installed    — a missing node_modules is why a ship later blew up with
+//                          `Cannot find module 'pg'`.
+//   3. `claude` launchable — the grader spawns it per worker; without it every ship
+//                          failed grading with SUBAGENT_SPAWN_FAILED.
+// Each finding carries a copy-paste fix.
+//
+// Before this, those checks lived only inside `bongos doctor` (doctor.js) and were
+// never run at setup/start time — so newcomers hit the failures reactively, deep
+// in the session. This module is the front-loadable, testable source of truth:
+//   - `setup.js`  runs it at the top of `/builder-setup` (catch a bare machine up front)
+//   - `doctor.js` `checkToolchain()` delegates to it (one source, no drift)
+//   - `node scripts/gds/preflight.js` runs it standalone (a quick `bongos`-less check)
+//
+// Pure by construction: every OS touch (node version, fs, child_process) is an
+// injectable dep, so the unit test drives it with zero real I/O.
+
+'use strict';
+
+const nodeFs = require('node:fs');
+const nodePath = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const REPO_ROOT = nodePath.resolve(__dirname, '..', '..');
+const MIN_NODE_MAJOR = 22;
+
+// The node_modules-present check, factored out (task 1002403) so a HOT-PATH
+// caller — /builder-start runs on every session open — can reuse THIS exact
+// finding without paying for the `claude --version` spawn the full
+// preflightChecks() does. Pure: injectable fs + repoRoot.
+function depsFinding({ repoRoot = REPO_ROOT, fs = nodeFs } = {}) {
+  let hasDeps = false;
+  try { hasDeps = fs.existsSync(nodePath.join(repoRoot, 'node_modules')); } catch (_) { /* treat as missing */ }
+  if (hasDeps) {
+    return { level: 'ok', title: 'Dependencies', detail: 'node_modules present.' };
+  }
+  return {
+    level: 'warn',
+    title: 'Dependencies',
+    detail: 'node_modules is missing — scripts that need pg/express (a ship, the server) will fail until installed.',
+    fix: 'Run `npm ci` in the repo root.',
+  };
+}
+
+// preflightChecks(deps) → [{ level:'ok'|'warn'|'fail', title, detail, fix? }]
+// No printing, no process.exit — callers (setup, doctor, the test) format it.
+function preflightChecks({
+  repoRoot = REPO_ROOT,
+  nodeVersion = process.version,
+  env = process.env,
+  fs = nodeFs,
+  spawn = spawnSync,
+  platform = process.platform,
+} = {}) {
+  const out = [];
+
+  // 1. Node >= 22.
+  const major = Number(String(nodeVersion).replace(/^v/, '').split('.')[0]) || 0;
+  if (major >= MIN_NODE_MAJOR) {
+    out.push({ level: 'ok', title: 'Node', detail: `${nodeVersion} (>= ${MIN_NODE_MAJOR}).` });
+  } else {
+    out.push({
+      level: 'fail',
+      title: 'Node',
+      detail: `${nodeVersion} is below the required v${MIN_NODE_MAJOR}.`,
+      fix: 'Install Node >= 22 — e.g. `brew install node`, `nvm install 22`, or https://nodejs.org.',
+    });
+  }
+
+  // 2. Dependencies installed (node_modules present) — shared with the hot-path
+  //    /builder-start caller via depsFinding() (task 1002403).
+  out.push(depsFinding({ repoRoot, fs }));
+
+  // 3. `claude` CLI launchable — same resolution order the grader uses.
+  const bin = env.OTB_CLAUDE_BIN || env.CLAUDE_BIN || 'claude';
+  const via = env.OTB_CLAUDE_BIN ? ' (via OTB_CLAUDE_BIN)' : env.CLAUDE_BIN ? ' (via CLAUDE_BIN)' : '';
+  let r;
+  try {
+    r = spawn(bin, ['--version'], { encoding: 'utf8', shell: platform === 'win32', windowsHide: true, timeout: 15000 });
+  } catch (err) { r = { error: err }; }
+  if (r && !r.error && r.status === 0) {
+    const ver = String(r.stdout || '').trim().split('\n')[0] || 'present';
+    out.push({ level: 'ok', title: 'claude CLI', detail: `launches${via}: ${ver} — the grader can spawn its workers.` });
+  } else {
+    const why = r && r.error ? (r.error.code || r.error.message) : `exited ${r ? r.status : '?'}`;
+    out.push({
+      level: 'fail',
+      title: 'claude CLI',
+      detail: `not launchable (${bin}: ${why}) — the grader spawns it per worker, so ships fail grading with SUBAGENT_SPAWN_FAILED.`,
+      fix: 'Run `npm i -g @anthropic-ai/claude-code` (puts a real claude on PATH), or set OTB_CLAUDE_BIN to its full path.',
+    });
+  }
+
+  return out;
+}
+
+const GLYPH = { ok: '✓', warn: '!', fail: '✖' };
+const ANSI = { ok: '\x1b[32m', warn: '\x1b[33m', fail: '\x1b[31m', dim: '\x1b[2m', reset: '\x1b[0m' };
+
+// formatPreflight(results, opts) → a printable multi-line string.
+function formatPreflight(results, { color = false, heading = false } = {}) {
+  const c = (k, s) => (color ? `${ANSI[k]}${s}${ANSI.reset}` : s);
+  const lines = [];
+  if (heading) lines.push('Checking your environment…');
+  for (const r of results) {
+    lines.push(`  ${c(r.level, GLYPH[r.level])} ${r.title}: ${r.detail}`);
+    if (r.fix) lines.push(`      ${c('dim', '→')} ${r.fix}`);
+  }
+  return lines.join('\n');
+}
+
+module.exports = { preflightChecks, depsFinding, formatPreflight, REPO_ROOT, MIN_NODE_MAJOR };
+
+// Standalone: `node scripts/gds/preflight.js` — exit 1 if any hard fail.
+if (require.main === module) {
+  const results = preflightChecks();
+  console.log(formatPreflight(results, { color: process.stdout.isTTY, heading: true }));
+  process.exit(results.some((r) => r.level === 'fail') ? 1 : 0);
+}

package/scripts/gds/provision.js

@@ -296,6 +296,14 @@ function standaloneMigrateCmd(inst, { privileged = false } = {}) {
     ? `sudo -u postgres env PGDATABASE=${dbName(inst)} MEDUSA_GDS_ONLY=1 bash ${CORE_PKG_DIR}/scripts/migrate.sh`
     : `PGDATABASE=${dbName(inst)} MEDUSA_GDS_ONLY=1 bash ${CORE_PKG_DIR}/scripts/migrate.sh`;
 }
+// Regenerate the instance's whole-file navigation docs (session-log index) from the pinned core,
+// AFTER the pull+install+migrate — the standalone analogue of the monorepo's deploy-prod.sh regen
+// block (ADR 0110 §2, task 1002314). Best-effort + LOUD (the script always exits 0 + prints
+// ::ERROR:: on a generator failure) so a stale/absent nav doc never fails a deploy. Run with
+// cwd = standaloneRoot so resolveInstanceRoot() writes into the instance repo. Without this a
+// standalone instance's docs never refresh on deploy — the gap the owner hit ("docs didn't
+// transfer from primea"): its bespoke pull-deploy regenerated nothing.
+function standaloneRegenDocsCmd() { return `node ${CORE_PKG_DIR}/scripts/gds/regen-instance-docs.js`; }
 
 // ── STANDALONE scaffold (ADR 0108 / 0125, task 2055) ──────────────────────────
 // The MISSING first leg of the greenfield "one guided flow": provision.js used to
@@ -342,7 +350,54 @@ function instanceInitSpec(inst, { ownerLogin } = {}) {
 // dist/ + secrets OUT of the commit, while the vendored core tarball (vendor/*.tgz)
 // and package-lock.json stay IN — `npm ci` on deploy resolves the pinned core from
 // the committed tarball (ADR 0108), so they MUST be tracked.
-const INSTANCE_GITIGNORE = ['node_modules/', 'dist/', '.env', '.env.local', '*.log', ''].join('\n');
+//
+// docs/session-log-index.md is a WHOLE-FILE generated navigation doc (ADR 0110): every byte is
+// machine-owned, regenerated at deploy by regen-instance-docs.js (task 1002314) into the served
+// tree. Untracked so `git reset --hard origin/main` never wipes it and no branch can diff it —
+// the same reasoning the core's own .gitignore applies to it. (docs/repo-map.md is listed for
+// parity/forward-compat; it is core-scoped today so a standalone instance doesn't generate its
+// own — see regenerateNavDocs() in upgrade.js — but ignoring it costs nothing and prevents a
+// stray future write from entering the tree.)
+const INSTANCE_GITIGNORE = [
+  'node_modules/', 'dist/', '.env', '.env.local', '*.log',
+  '# Whole-file generated navigation docs — regenerated at deploy (ADR 0110, task 1002314).',
+  'docs/session-log-index.md', 'docs/repo-map.md', '',
+].join('\n');
+
+// A PRE-BUILT @bongos/core tarball this control plane can vendor into a NEW instance
+// WITHOUT rebuilding from source — the consumer-control-plane fix (task 1002275).
+//
+// The scaffold's default core-install path rebuilds the tarball with package-core.js,
+// which enumerates GIT-TRACKED files (`git -C REPO_ROOT ls-tree`). That works from a core
+// SOURCE checkout, but NOT when this runner is ITSELF a consumer instance whose core is an
+// installed npm dependency: provision.js then runs out of node_modules/@bongos/core, so
+// REPO_ROOT points INSIDE gitignored node_modules, git sees ZERO tracked files there, and
+// package-core aborts ("the core set is EMPTY") — the scaffold never pushes and the freshly
+// created repo is left EMPTY (seen live: trial/test on cloudbongos.com).
+//
+// But the exact pinned tarball this instance installed FROM is on disk, named by its own
+// package.json ("@bongos/core": "file:vendor/bongos-core-<v>.tgz"). Reuse it: byte-identical,
+// already proven, and the child pins the SAME core the hub runs. Returns an absolute .tgz
+// path, or null on a source checkout (no `file:` core pin) — where package-core.js is the
+// right, unchanged path. `instanceRoot` defaults to $BONGOS_INSTANCE_ROOT (what
+// infra/core-node.sh resolves against) else process.cwd() (the runner's WorkingDirectory).
+// fs injectable for tests. PURE-ish (fs reads only, no mutation → dry-run safe).
+function installedCoreTarball({ instanceRoot, fsImpl = fs } = {}) {
+  const root = instanceRoot || process.env.BONGOS_INSTANCE_ROOT || process.cwd();
+  let pkg;
+  try { pkg = JSON.parse(fsImpl.readFileSync(path.join(root, 'package.json'), 'utf8')); }
+  catch { return null; }               // no/unreadable package.json → treat as a source checkout
+  const deps = Object.assign({}, pkg.dependencies, pkg.devDependencies);
+  // Both scope aliases the loader accepts (infra/core-node.sh checks the same two).
+  for (const name of ['@bongos/core', '@cloudbongos/core']) {
+    const m = /^file:(.+\.tgz)$/.exec(String(deps[name] || '').trim());
+    if (m) {
+      const abs = path.resolve(root, m[1]);
+      if (fsImpl.existsSync(abs)) return abs;   // a dangling pin (tarball pruned) → fall through to null
+    }
+  }
+  return null;
+}
 
 // Clone the (empty) target_ref → standaloneRoot → materialize config/ + .claude/ + a
 // file:-pinned @bongos/core + lockfile (via `bongos init --vendor-core`, task 2053)
@@ -383,11 +438,19 @@ async function scaffoldStandaloneRepo(inst, deps) {
     } catch { /* fall back to the repo owner */ }
   }
 
-  // 1. clone the (possibly empty) repo, then force the initial branch to `main` (an empty
-  //    clone leaves an unborn HEAD). A re-run after a partial clone reuses the existing dir.
+  // 1. Materialize the working tree + set the initial branch to `main`. A freshly-created
+  //    instance repo is EMPTY (github-repos.createUserRepo, auto_init:false), so there is
+  //    NOTHING to clone — and a git DEPLOY KEY is per-repo, so the shared PROVISION_GIT_SSH_ALIAS
+  //    key (e.g. `github-instances`, a deploy key scoped to ONE repo) can't even READ a
+  //    consumer's brand-new repo under their own account: `git clone` 500s with "Repository not
+  //    found." This is the clone-side twin of the task-1002317 push bug. So `git init` locally
+  //    instead of cloning, and set `origin` to the SSH remote for the no-token fallback push
+  //    below; the OAuth-preferred push (its token CREATED the repo, so it can write) handles the
+  //    upload for consumer repos. A re-run after a partial init reuses the existing dir.
   if (!fs.existsSync(path.join(root, '.git'))) {
-    exec(`mkdir -p ${path.posix.dirname(root)}`);
-    exec(`git clone ${remote} ${root}`);
+    exec(`mkdir -p ${root}`);
+    exec(`git -C ${root} init -q`);
+    exec(`git -C ${root} remote add origin ${remote}`);
   }
   exec(`git -C ${root} checkout -B main`);
 
@@ -417,9 +480,19 @@ async function scaffoldStandaloneRepo(inst, deps) {
     log(`  [scaffold] core install: registry — PRIVATE @bongos/core@${coreV} via env-fed NPM_TOKEN (ADR 0134)`);
     exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed --force --registry-core`);
   } else {
-    log(`  [scaffold] core install: vendored tarball (offline default)`);
-    exec(`node scripts/gds/package-core.js`);                      // cwd = REPO_ROOT → dist/bongos-core-<v>.tgz
-    const tgz = path.join(REPO_ROOT, 'dist', `bongos-core-${coreV}.tgz`);
+    // Vendored tarball. PREFER a pre-built pinned tarball this control plane already has
+    // (a consumer instance's own `file:` core pin) — rebuilding via package-core.js aborts
+    // with an EMPTY core set when this runner IS a consumer instance (REPO_ROOT is inside
+    // gitignored node_modules), which left new repos empty (task 1002275). Only rebuild
+    // from source when there is no such pin (a genuine core source checkout).
+    let tgz = installedCoreTarball({ instanceRoot: deps.instanceRoot });
+    if (tgz) {
+      log(`  [scaffold] core install: reusing the pinned core tarball this control plane runs (${path.basename(tgz)}) — no source rebuild (task 1002275)`);
+    } else {
+      log(`  [scaffold] core install: building a fresh vendored tarball from source (package-core.js)`);
+      exec(`node scripts/gds/package-core.js`);                      // cwd = REPO_ROOT → dist/bongos-core-<v>.tgz
+      tgz = path.join(REPO_ROOT, 'dist', `bongos-core-${coreV}.tgz`);
+    }
     exec(`node scripts/gds/init.js --from ${specPath} --dir ${root} --no-seed --force --vendor-core ${tgz}`);
   }
 
@@ -429,8 +502,38 @@ async function scaffoldStandaloneRepo(inst, deps) {
   exec(`git -C ${root} config user.email "bot@cloudbongos.com"`);
   exec(`git -C ${root} add -A`);
   exec(`git -C ${root} commit -m "chore: scaffold ${inst.slug} on a pinned @bongos/core ${coreV} (provision.js, ADR 0108)"`, { allowFail: true });
-  exec(`git -C ${root} push -u origin main`);
-  log(`  [scaffold] pushed initial scaffold to ${repo.owner}/${repo.name}@main`);
+  // Push. A GitHub DEPLOY KEY is per-repo, so the box's shared key can't write to a NEW
+  // project repo — the second empty-repo cause (task 1002317). PREFER the instance owner's
+  // OAuth token (it CREATED the repo via github-repos.createUserRepo, so `public_repo`
+  // already grants write). The token rides a chmod-600 git credential-store file — never
+  // the logged command or makeExec's env (both are surfaced) — and is removed right after
+  // (finally, so a failed push can't leave it on disk). No token (org-owned repo, or
+  // secret-box off) → fall back to the SSH `origin` push (unchanged; e.g. an instance whose
+  // matching deploy key was cloned into origin). `deps.getGithubToken` is injectable for
+  // tests; production resolves it lazily against the core db slice with the runner's pool.
+  let ownerToken = null;
+  if (inst.owner_builder_id) {
+    try {
+      const fetchTok = deps.getGithubToken
+        || ((bid) => require(path.join(REPO_ROOT, 'src/bongos/db')).getGithubToken({ builderId: bid, p: deps.db }));
+      const r = await fetchTok(inst.owner_builder_id);
+      ownerToken = r && r.token ? r.token : null;
+    } catch (e) { log(`  [scaffold] owner OAuth token lookup failed (${e && e.message}) — using the SSH remote`); }
+  }
+  if (ownerToken) {
+    const credFile = path.join(os.tmpdir(), `bongos-gitcred-${inst.slug}-${process.pid}`);
+    writeFile(credFile, `https://x-access-token:${ownerToken}@github.com\n`, { mode: 0o600 });
+    const httpsUrl = `https://x-access-token@github.com/${repo.owner}/${repo.name}.git`;
+    try {
+      exec(`git -C ${root} -c credential.helper='store --file=${credFile}' push ${httpsUrl} HEAD:main`);
+      log(`  [scaffold] pushed to ${repo.owner}/${repo.name}@main via the owner's GitHub token (task 1002317)`);
+    } finally {
+      exec(`rm -f ${credFile}`, { allowFail: true });
+    }
+  } else {
+    exec(`git -C ${root} push -u origin main`);
+    log(`  [scaffold] pushed initial scaffold to ${repo.owner}/${repo.name}@main (SSH origin)`);
+  }
   return { ok: true, scaffolded: true };
 }
 
@@ -1151,6 +1254,14 @@ async function provisionInstance(inst, deps) {
     // here should surface. Dedicated bakes the same step into cloud-init (dedicatedUserData).
     log('  [seed] first version (only if versions is empty)');
     boxExec(seedFirstVersionCmd(inst, { privileged }));
+    // Regenerate the whole-file navigation docs from the pinned core so a fresh/redeployed
+    // standalone instance's docs/ stays live (ADR 0110 §2, task 1002314) — the deploy-regen the
+    // bespoke pull scripts were missing. Best-effort: regen-instance-docs.js exits 0 even on a
+    // generator hiccup (LOUD ::ERROR::), so a stale nav doc never fails a provision.
+    if (standalone) {
+      log('  [docs] regenerate whole-file navigation docs (session-log index)');
+      boxExec(standaloneRegenDocsCmd(), { cwd: standaloneRoot(inst), allowFail: true });
+    }
   } else { log('    (db create + migrate + first-version seed run via cloud-init on the droplet)'); }
 
   // ── step 3: config + per-instance secrets ─────────────────────────────────
@@ -1654,8 +1765,8 @@ module.exports = {
   dbName, dbCreateCmd, migrateCmd, seedFirstVersionCmd, serviceUnit, serviceUnitPath, webEnvBody, webEnvPath,
   backupUnitName, backupServicePath, backupTimerPath, backupScriptPath, backupService, backupTimer,
   standaloneRoot, standalonePullCmd, standaloneInstallCmd, standaloneMigrateCmd,
-  // standalone scaffold (ADR 0108 / 0125, task 2055)
-  parseTargetRef, instanceRepoRemote, instanceInitSpec, scaffoldStandaloneRepo, coreVersionSafe,
+  // standalone scaffold (ADR 0108 / 0125, task 2055; consumer-core fix task 1002275)
+  parseTargetRef, instanceRepoRemote, instanceInitSpec, installedCoreTarball, scaffoldStandaloneRepo, coreVersionSafe,
   zoneForDomain, dnsUpsertEnv, classifyZoneScope, checkDnsTokenScope,
   caddyBlock, caddySnippetPath, healthzCmd, dedicatedUserData, nextFreePort,
   // executors + orchestration (injectable deps for tests)

package/scripts/gds/publish-manifest.js

@@ -61,17 +61,20 @@ const PUBLISH_ALLOWLIST = [
   'modules/sessions/',
   'modules/autonomy/',
   'modules/security/',
+  'modules/governance/',     // configurable roles & permissions (BV1 goal 1000030, ADR 0151) — the rank/permission machinery publishes AS the open-source methodology (ADR 0065 §4 / ADR 0098); it is in PROTECTED_GLOBS for write-protection, NOT publish-exclusion. default:true.
   'modules/hall-ui/',
   'modules/status-ui/',
   'modules/dev-box/',
   'modules/discord/',
   'modules/provisioning/',   // instance-hosting control plane — CORE like its sibling dev-box (same do-api/cf-tunnel toolchain, all core). Reclassified IN so the core CLI scripts/gds/provision.js resolves it from the core package post-split, not a MODULE_NOT_FOUND (task 2135). default:false — shipped ≠ enabled.
+  'modules/platform-identity/', // hub identity provider (ADR 0141) — ships in core, enabled ONLY on the hub (cloudbongos.com). MUST be here or the hub's enabledModules() throws "unknown module" and provision.js's federation load MODULE_NOT_FOUNDs (task 1002235, same rationale as provisioning above). default:false — shipped ≠ enabled; a vanilla/self-hosted instance never turns it on.
   // --- neutral (customer-0) config starters + their schemas (the filled-in *.json twins are denied) ---
   'config/branding.neutral.json',
   'config/modules.neutral.json',
   'config/design-tokens.neutral.json',
   'config/design-tokens.schema.json',  // the design-token contract (generic schema, no instance values)
   'config/hierarchy.neutral.json',
+  'config/governance.neutral.json',     // the starting role templates a fresh instance inherits (BV1.R96)
   // --- the portable methodology core, governance, and sanitized docs ---
   'CLAUDE.md',
   'README.md',
@@ -86,7 +89,9 @@ const PUBLISH_ALLOWLIST = [
   'docs/architecture.md',
   // Served to the hall / advertised by /api/bongos — a standalone that omits these
   // renders broken onboarding + API-reference pages (task 2078). Redacted like the
-  // rest of this docs section; the diagrams' .png/.svg regenerate on the box.
+  // rest of this docs section. Only the diagram .mmd SOURCES ship: the .png/.svg are
+  // gitignored (ADR 0122) so the tarball cannot carry them, and `bongos upgrade`
+  // regenerates them on the box via healDocAssets() (upgrade.js, task 1002441).
   'docs/onboarding/',                // primer.md + drachmae-and-karma.md + diagram sources (/builders/primer · /drachmae · /diagrams)
   // API artifacts (classification settled, task 2141): CORE-shipped STARTERS so a fresh
   // hall/docs render before first regen — but per-instance GENERATED. init + `bongos
@@ -206,6 +211,7 @@ const INSTANCE_EXCLUDE = [
   'config/modules.json',
   'config/devbox-app.json',
   'config/hierarchy.json',
+  'config/governance.json',
   'CODEOWNERS',              // names the owner (a protected surface, excluded as identity)
   // instance SEED migrations — this host's scope-truth SQL (planning seeds, world data).
   // ADR 0105: a consumer's core must not carry them; migrate.sh reads instance seeds from

package/scripts/gds/reauth.js

@@ -39,6 +39,9 @@
 const { spawn } = require('node:child_process');
 const lib = require('./cli-lib');
 
+// lib.API_BASE is session-aware (task 1002427), so both URLs name the instance the
+// builder is actually signed into — not this checkout's branding default, which is
+// what sent a cloudbongos.com builder to a localhost:3000 click-path.
 const HALL_URL = `${lib.API_BASE}/builders`;
 // The "Re-issue CLI token" button lives on the Settings page (under "CLI
 // Access"), not the hall profile — open the builder right where the button is.
@@ -56,9 +59,10 @@ function openInBrowser(url) {
     case 'win32':
       // rundll32's FileProtocolHandler opens a URL without going through a
       // shell, so (unlike `cmd /c start`) shell metacharacters in the URL are
-      // never interpreted. Defense-in-depth: today the URL is a constant
-      // (GDS_API_BASE + '/builders'), but this keeps it safe if that ever
-      // becomes influenced by less-trusted input.
+      // never interpreted. This is now load-bearing, not hypothetical: since
+      // task 1002427 the URL derives from the session file's api_base (via the
+      // session-aware lib.API_BASE), not from a bare env/branding constant. That
+      // file is the builder's own 0600 config, but it IS file-derived input.
       cmd = 'rundll32';
       args = ['url.dll,FileProtocolHandler', url];
       break;

package/scripts/gds/regen-instance-docs.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+'use strict';
+// regen-instance-docs.js — regenerate a STANDALONE instance's live navigation docs (task 1002314).
+//
+// THE GAP. On the monorepo, the gitignored whole-file navigation docs are regenerated at deploy by
+// scripts/deploy/deploy-prod.sh + infra/box-source-fetch.sh (ADR 0110 §2/§3). STANDALONE instances
+// (ADR 0108 — their own lean repo with @bongos/core vendored) never got that step: their bespoke
+// pull-deploy regenerated NOTHING, so a fresh instance shipped with an empty docs/ and nothing kept
+// the session-log index live. This script is the STANDALONE analogue of deploy-prod.sh's regen block
+// — one line for an instance's deploy.sh to call after `git reset --hard` + migrate.
+//
+// USAGE (from the instance repo, core vendored in node_modules):
+//   node node_modules/@bongos/core/scripts/gds/regen-instance-docs.js
+// It resolves the INSTANCE root (bongos.config.json instanceRoot / <PREFIX>_INSTANCE_ROOT / cwd) and
+// writes docs/session-log-index.md THERE (gitignored on the instance, so the next
+// `git reset --hard origin/main` never wipes it and no branch can ever diff it).
+//
+// SCOPE + CONTRACT: see regenerateNavDocs() in upgrade.js — it owns the generator list and the
+// rationale for what is and isn't deploy-regenerated (repo-map is core-scoped; file-map + API docs
+// are tracked/committed; diagrams are the headless-browser exception). Best-effort + LOUD per
+// ADR 0110 §2 "accepted staleness": a broken generator prints `::ERROR::` (journald greps it) but
+// this script ALWAYS exits 0 — a stale nav doc is tolerable; a failed deploy is not.
+
+const path = require('node:path');
+const { resolveInstanceRoot } = require('../../src/instance-config');
+const { regenerateNavDocs } = require('./upgrade');
+
+function main() {
+  const coreRoot = path.resolve(__dirname, '..', '..'); // the @bongos/core package this script ships in
+  const instanceDir = resolveInstanceRoot();
+  const res = regenerateNavDocs({ instanceDir, coreRoot });
+  if (res.ran.length) {
+    console.log(`regen-instance-docs: regenerated ${res.ran.join(', ')} → ${instanceDir}/docs/`);
+  }
+  if (!res.ok) {
+    for (const f of res.failed) {
+      // LOUD (ADR 0110 §2): journald greps ::ERROR:: so a broken generator surfaces.
+      console.error(`::ERROR:: regen-instance-docs: ${f.gen} failed — ${f.reason}`);
+    }
+  }
+  // Best-effort: NEVER fail the deploy. A stale/absent nav doc is tolerable; the ::ERROR:: is the alarm.
+  process.exit(0);
+}
+
+if (require.main === module) main();
+
+module.exports = { main };

package/scripts/gds/run-unit-tests.js

@@ -73,8 +73,10 @@ const INTEGRATION = new Set([
   // platform-server — network + package build + a spawned server, run by its own
   // .github/workflows/consumer-layout-boot.yml, not this DB-free gate (task 2142).
   'consumer_layout_boot',
-  'discord_autojoin', 'discord_oauth', 'linkify_refs', 'memory_isolation',
-  'memory_pull', 'parallel-load', 'session_records', 'setup_smoke',
+  'claim_gate_rebase', 'clawback_confirmed_backlog', 'discord_autojoin', 'discord_oauth',
+  'linkify_refs', 'memory_isolation',
+  'memory_pull', 'needs_rebase', 'parallel-load', 'reward_mode_cost_plus_only',
+  'session_records', 'setup_smoke',
   'status-probe', 'subdomain_auth',
 ]);
 

package/scripts/gds/seed-bongos-v1-seo-tasks.js

@@ -0,0 +1,104 @@
+// Seed the tasks for goal 1000048 "SEO & public discoverability — rankable per-project
+// profiles" (BONGOS-V1, internal). Source of truth:
+// docs/specs/bongos-v1-seo-public-discoverability.md (status: final).
+// Idempotent on (source, source_ref). Re-running resolves to the existing rows.
+//
+// Run: node scripts/gds/seed-bongos-v1-seo-tasks.js
+const os = require('os');
+const sess = require(os.homedir() + '/.config/cloudbongos/gds-session.json');
+const BASE = (sess.api_base || 'https://cloudbongos.com').replace(/\/$/, '');
+const TOKEN = sess.token;
+const VER = 'BONGOS-V1';
+const GOAL = 1000048;
+const SRC = 'planning-session';
+const H = { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' };
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function api(method, path, body, _tries = 0) {
+  await sleep(400); // base throttle to stay under the per-IP rate limit
+  const res = await fetch(`${BASE}/api/gds${path}`, {
+    method, headers: H, body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  let json; try { json = JSON.parse(text); } catch { json = { _raw: text.slice(0, 300) }; }
+  if (res.status === 429 && _tries < 8) {
+    const wait = ((json.error && json.error.details && json.error.details.retry_after_seconds) || 30) + 1;
+    console.log(`  …rate-limited, waiting ${wait}s`);
+    await sleep(wait * 1000);
+    return api(method, path, body, _tries + 1);
+  }
+  return { status: res.status, ok: res.ok, json };
+}
+
+// criterion slugs (position-independent — the goal's done_when_criteria.criterion_id)
+const PP = 'seo-project-profile-page', NS = 'seo-toplevel-namespace', PC = 'seo-project-content',
+  PM = 'seo-page-metadata', CC = 'seo-canonical-consolidation', SR = 'seo-sitemap-robots',
+  VG = 'seo-visibility-gated', SB = 'seo-site-baseline';
+
+// disc: engineer (backend/API/spike) | ui (page/markup/meta). kind: spike | feature | refactor | infra | verify (proofs).
+// deps: 'R##' resolve to the just-created id; a NUMBER is a real cross-goal task id, passed through.
+const TASKS = [
+  { ref:'R01', kind:'spike',   disc:'engineer', prio:5, est:180, crit:[PP,NS,PM,CC], deps:[],           title:'R01 · SEO + namespace architecture ADR', desc:'Needs-exploration: profile-page rendering (server-rendered HTML from the Node/Express hub), routing precedence (/<slug> vs /bongos/* vs /api/*), the owner-picked slug model + reserved-word list, the cross-instance canonical mechanism, and how the profile reads goal-1000046 setup content. Output an ADR + confirmed sub-tasks. See docs/specs/bongos-v1-seo-public-discoverability.md.' },
+  { ref:'R02', kind:'feature', disc:'engineer', prio:5, est:240, crit:[PP,NS],       deps:['R01'],      title:'R02 · Owner-picked slug at creation + reserved-name validation + backfill', desc:'Projects get a unique owner-chosen vanity slug at creation (username-style), validated vs a reserved list (bongos, api, sso, gate, create, explore, builders, status, assets, sitemap.xml, robots.txt, ...). Auto-derive + backfill a default slug for existing projects (owner can change). Adds a step to the creation flow — coordinate with goals 1000035/1000046. Deps R01.' },
+  { ref:'R03', kind:'refactor',disc:'engineer', prio:5, est:240, crit:[NS],          deps:['R01'],      title:'R03 · Move platform pages under /bongos/… ; top-level /<slug> resolves to a project', desc:'Serve hall/status/create/explore/gate under /bongos/… with 301 redirects from old paths; never move /api, /sso, /auth, /.well-known. Top-level /<slug> resolves to a project profile after the reserved-word check. Deps R01.' },
+  { ref:'R04', kind:'feature', disc:'ui',       prio:5, est:240, crit:[PP,PM],       deps:['R02','R03'],title:'R04 · Server-rendered project profile page at /<slug>', desc:'Crawlable server-rendered HTML: project name, description, cover art, builders, tech/modules, and a prominent "Open the live app" CTA. This page is the primary shareable destination. Deps R02,R03.' },
+  { ref:'R05', kind:'feature', disc:'ui',       prio:4, est:180, crit:[PC],          deps:['R04'],      title:'R05 · Render goal-1000046 setup content on the profile + auto-derive SEO copy', desc:'Read the project\'s setup content (goal 1000046) and render it on the profile; auto-derive SEO title/description from it. No separate editor (per interview). Coordinate with 1000046 — needs a real description + tags; render current fields (name/tagline) meanwhile and enrich as 1000046 lands. Deps R04.' },
+  { ref:'R06', kind:'feature', disc:'ui',       prio:4, est:150, crit:[PM,CC],       deps:['R04'],      title:'R06 · Per-page SEO metadata (title/description/OG/Twitter/self-canonical)', desc:'Dynamic <title>, meta description, Open Graph + Twitter card tags, and a self-referencing canonical on each profile. Deps R04.' },
+  { ref:'R07', kind:'feature', disc:'ui',       prio:4, est:120, crit:[PM],          deps:['R04'],      title:'R07 · JSON-LD structured data on profiles', desc:'Emit SoftwareApplication/CreativeWork JSON-LD on each profile page. Deps R04.' },
+  { ref:'R08', kind:'feature', disc:'ui',       prio:4, est:150, crit:[PP],          deps:['R04'],      title:'R08 · Route discovery through profiles (orbs + links → /<slug>)', desc:'Make /<slug> the shareable destination: orbs cards and "view project" links point to the profile, which carries the "Open the live app" CTA — maximizing internal links to the ranking page. Deps R04. NOTE: the orbs front door is a separate static site — the orbs-side link change likely lands instance-side.' },
+  { ref:'R09', kind:'feature', disc:'ui',       prio:4, est:180, crit:[PP,SR],       deps:['R04'],      title:'R09 · Crawlable projects directory via the orbs table-view', desc:'Make the orbs page\'s table view a server-rendered, crawlable, indexable HTML index of all Public projects (a plain-link list to each /<slug>), linked from the landing. This IS the directory (no separate directory page, per interview). Deps R04.' },
+  { ref:'R10', kind:'feature', disc:'engineer', prio:4, est:180, crit:[SR],          deps:['R04','R11'],title:'R10 · sitemap.xml (public projects + core pages)', desc:'Auto-generated sitemap.xml at /sitemap.xml listing all Public project profiles + core pages; regenerates on project create/update/visibility-change (cached). Deps R04,R11.' },
+  { ref:'R11', kind:'feature', disc:'engineer', prio:4, est:210, crit:[VG],          deps:['R04'],      title:'R11 · Visibility-gated indexing (visibility metaphor)', desc:'Public→full indexable profile; Private (star)→minimal page + join/request CTA, noindex; Stealth (black hole)→404; Unlisted (dark matter)→no public page until published. HARD conceptual dependency on goal 1000046\'s visibility states (not yet seeded) — coordinate; gate on the state field once it exists. Deps R04.' },
+  { ref:'R12', kind:'feature', disc:'engineer', prio:3, est:120, crit:[SR],          deps:['R10'],      title:'R12 · robots.txt', desc:'Serve robots.txt: allow public pages, disallow /api + internal, reference /sitemap.xml. Deps R10.' },
+  { ref:'R13', kind:'feature', disc:'engineer', prio:3, est:240, crit:[CC],          deps:['R04'],      title:'R13 · Cross-instance canonical (full scope)', desc:'rel=canonical from each live instance back to its hub profile: federated/co-tenant instances emit it; hub-hosted subdomains when that tier lands; publish a documented canonical snippet for self-hosted owners. Touches instance-side core rendering → Metic+ auto-floor. Coordinate with provisioning/federation (goals 1000032/1000041). Deps R04.' },
+  { ref:'R14', kind:'feature', disc:'ui',       prio:3, est:210, crit:[PP,PM],       deps:['R04',1002278], title:'R14 · Public builder-profile SEO page (handle-based path)', desc:'Server-rendered, SEO-optimized public builder profile at a handle path (e.g. /u/<handle>): metadata + Person/ProfilePage JSON-LD, crawlable HTML. Extends goal 1000045\'s builder profiles with a public, rankable rendering. Deps R04 + goal-1000045 profile API (task 1002278).' },
+  { ref:'R15', kind:'feature', disc:'engineer', prio:3, est:150, crit:[SR,VG],       deps:['R14','R10'],title:'R15 · Builder profiles in sitemap, consent-gated', desc:'Add consented/public builder profiles to sitemap.xml; honor goal-1000045\'s hide/opt-out flag (coordinate with 1000045 R03). Non-consented builders excluded/noindex. Deps R14,R10.' },
+  { ref:'R16', kind:'feature', disc:'ui',       prio:2, est:120, crit:[PC],          deps:['R05'],      title:'R16 · SEO content nudges in the setup/edit flow', desc:'Rule-based nudges where owners author content (goal 1000046 setup/edit): description length, tags, cover image — so profiles have enough real text to rank. Coordinate with 1000046. Deps R05.' },
+  { ref:'R17', kind:'feature', disc:'ui',       prio:3, est:150, crit:[SB],          deps:['R01'],      title:'R17 · Landing + Explore SEO metadata', desc:'Give the landing page (goal 1000031) and the Explore page proper title/description/Open Graph/structured data and ensure they are indexable. Coordinate with 1000031. Deps R01.' },
+  { ref:'R18', kind:'infra',   disc:'engineer', prio:2, est:180, crit:[SB],          deps:['R04'],      title:'R18 · Technical-SEO + Core Web Vitals pass', desc:'Audit + fix technical SEO across public pages: mobile-friendly, load speed / Core Web Vitals, indexability. Deps R04.' },
+  { ref:'R19', kind:'verify',  disc:'engineer', prio:2, est:120, crit:[PP,PM,CC,SR,VG,PC], deps:['R04','R06','R07','R10','R11','R14','R15'], title:'R19 · PROOF: a public project + builder profile rank-ready; non-public hidden', desc:'End-to-end proof: a real Public project profile is live at cloudbongos.com/<slug> with correct metadata + JSON-LD, appears in sitemap.xml, passes Google Rich Results + mobile-friendly tests; a public builder profile is likewise rank-ready; and a Private project is noindex + absent from the sitemap (Stealth 404s). Deps R04,R06,R07,R10,R11,R14,R15.' },
+];
+
+const ROOTS = ['R01']; // zero-dep entry task to open for claiming
+
+(async () => {
+  const idByRef = {};
+  let created = 0, existing = 0;
+  console.log(`Seeding ${TASKS.length} tasks under goal ${GOAL} (${VER})…`);
+  for (const t of TASKS) {
+    const r = await api('POST', '/tasks', {
+      version_id: VER, goal_id: GOAL, title: t.title, description: t.desc,
+      kind: t.kind, discipline: t.disc, priority: t.prio, est_minutes: t.est,
+      criterion_ids: t.crit, source: SRC, source_ref: `bv1-seo-${t.ref}`,
+    });
+    if (!r.ok) { console.log(`  ${t.ref}: FAILED ${r.status} ${JSON.stringify(r.json)}`); continue; }
+    const task = r.json.task || r.json;
+    idByRef[t.ref] = task.id;
+    if (r.json.idempotent || r.json.existing) existing++; else created++;
+    console.log(`  ${t.ref} → task ${task.id} (${t.kind}/${t.disc}, P${t.prio}, [${t.crit.join(',')}])`);
+  }
+
+  console.log('Wiring dependencies…');
+  let edges = 0;
+  for (const t of TASKS) {
+    if (!t.deps.length) continue;
+    const id = idByRef[t.ref];
+    const depIds = t.deps.map((d) => (typeof d === 'number' ? d : idByRef[d])).filter(Boolean);
+    if (!id || depIds.length !== t.deps.length) { console.log(`  ${t.ref}: dep resolve gap, skipping`); continue; }
+    const r = await api('POST', `/tasks/${id}/dependencies`, { depends_on_task_ids: depIds });
+    if (!r.ok) { console.log(`  ${t.ref}: dep FAILED ${r.status} ${JSON.stringify(r.json)}`); continue; }
+    edges += (r.json.added || depIds.length);
+    console.log(`  ${t.ref} depends on ${t.deps.join(',')}`);
+  }
+
+  console.log('Promoting root(s) to ready…');
+  for (const ref of ROOTS) {
+    const id = idByRef[ref];
+    if (!id) continue;
+    const r = await api('POST', `/tasks/${id}/promote`, {});
+    console.log(`  ${ref} (task ${id}): ${r.ok ? 'ready' : 'promote note ' + JSON.stringify(r.json).slice(0, 120)}`);
+  }
+
+  console.log(`\nDONE. created=${created} existing=${existing} depEdges=${edges}. Roots opened: ${ROOTS.join(', ')}.`);
+  console.log('ref→id:', JSON.stringify(idByRef));
+})();