@bongos/core 1.21.48 → 1.21.50

package/modules/hall-ui/public/hall-render.js

@@ -808,11 +808,11 @@
       ? `Stuck on any step? <a href="${API}/auth/discord/start">Join our Discord</a> and ask in <strong>#support</strong>.`
       : `Stuck on any step? See the project's README and docs.`;
     const setupSteps = `
-        <p class="setup__intro">Build from your own machine — clone the repository, run the platform locally, and sign in from the terminal.</p>
+        <p class="setup__intro">Build from your own machine — get a copy of the project, sign in once, then work in Claude.</p>
         <ol class="setup__steps">
           <li><strong>Clone the repository</strong> and install dependencies (<code>npm install</code>).</li>
-          <li><strong><a href="https://claude.com/download" target="_blank" rel="noopener noreferrer">Download Claude</a></strong> (or use the Claude Code CLI) and open the project.</li>
-          <li><strong>Run <code>/builder-setup</code></strong> to authenticate this machine, then <code>/builder-start</code> to claim your first task.</li>
+          <li><strong>Run <code>npx bongos setup</code></strong> in that folder to sign this machine in.</li>
+          <li><strong><a href="https://claude.com/download" target="_blank" rel="noopener noreferrer">Download Claude</a></strong> (or use the Claude Code CLI), open the project, and run <code>/builder-start</code> to claim your first task.</li>
         </ol>
     `;
     // task 469: a "Set up your machine / get the code" door. The steps above
@@ -821,24 +821,26 @@
     // how do I get it onto my own laptop?". It's the hall mirror of the primer's
     // "Step 0 — get the project onto your machine". Collapsed by default so it
     // doesn't crowd the recommended path; the clone block is click-to-copy
-    // (copy-on-click.js picks up .welcome__paste). The commands mirror
-    // scripts/setup-builder.sh's own header verbatim so they can't drift.
+    // (copy-on-click.js picks up .welcome__paste). Sign-in is `npx bongos setup`
+    // (bin/bongos.js → scripts/gds/setup.js), one line on every OS — bare
+    // `bongos` is not on a fresh clone's PATH, `npx` finds the repo's own bin.
     // The clone commands come from the instance's own repo coords (loaded from
     // GET /api/bongos/instance), not a hardcoded repo, so a fresh instance's newcomer
     // clones ITS project (ADR 0062 §3, task 1705). Falls back to generic guidance
     // until the coords load (or if they're unavailable).
     const cloneBlock = ctx.instanceRepo
-      ? `git clone ${escapeHtml(ctx.instanceRepo.url)}.git\ncd ${escapeHtml(ctx.instanceRepo.repo)}\n./scripts/setup-builder.sh`
-      : `# clone your instance's repository, cd into it, then run:\n./scripts/setup-builder.sh`;
+      ? `git clone ${escapeHtml(ctx.instanceRepo.url)}.git\ncd ${escapeHtml(ctx.instanceRepo.repo)}\nnpm install\nnpx bongos setup`
+      : `# clone your instance's repository, cd into it, then run:\nnpm install\nnpx bongos setup`;
     const getCode = `
         <details class="setup__getcode">
           <summary class="setup__getcode-summary">Set up your machine / get the code</summary>
           <div class="setup__getcode-body">
-            <p class="setup__hint">First install <a href="https://git-scm.com/downloads" target="_blank" rel="noopener noreferrer">Git</a>
+            <p class="setup__hint">First install <a href="https://git-scm.com/downloads" target="_blank" rel="noopener noreferrer">Git</a>,
+              <a href="https://nodejs.org" target="_blank" rel="noopener noreferrer">Node</a> (version 22 or newer)
               and <a href="https://claude.com/download" target="_blank" rel="noopener noreferrer">Claude Code</a> — that's all the tooling you need up front.</p>
-            <p class="setup__getcode-lede">Then copy the project onto your machine and run the one-shot bootstrap (it checks your setup, installs dependencies, and signs you in):</p>
+            <p class="setup__getcode-lede">Then copy the project onto your machine, install its dependencies, and sign in:</p>
             <code class="welcome__paste">${cloneBlock}</code>
-            <p class="setup__hint">On Windows, run <code>node scripts/setup-builder.js</code> instead of the last line. New to the steps? The
+            <p class="setup__hint">The same commands work on Mac, Windows and Linux. New to the steps? The
               <a href="/primer">primer</a> walks the whole path in plain language.</p>
           </div>
         </details>`;
@@ -898,7 +900,7 @@
         <span class="onboarding-item__mark" aria-hidden="true">›</span>
         <div class="onboarding-item__body">
           <p class="onboarding-item__label">First — obtain the repo</p>
-          <p class="onboarding-item__hint">Clone the project to your machine. The build commands live inside the repo, so this comes first. The remaining steps below are tracked automatically.</p>
+          <p class="onboarding-item__hint">Clone the project to your machine and run <code>npm install</code> in it. The build commands live inside the repo, so this comes first. The remaining steps below are tracked automatically.</p>
         </div>
       </li>`;
 

package/modules/hall-ui/public/settings.html

@@ -140,13 +140,13 @@
             <section class="scroll" id="cli-scroll" aria-labelledby="cli-h" data-group="access" hidden>
               <h2 id="cli-h" class="scroll__h">CLI access</h2>
               <p class="scroll__lede">
-                Mint a fresh CLI token using this browser session and paste it into
-                your terminal — the quick way back in when a <code>/builder-*</code>
-                command says your session expired.
+                Mint a fresh CLI token using this browser session and paste the
+                command it gives you into a terminal in your project folder — the quick
+                way back in when a <code>/builder-*</code> command says your session expired.
               </p>
               <div class="settings-card">
                 <button type="button" class="settings-btn" id="cli-reissue-btn">Re-issue CLI token</button>
-                <span class="settings-card__hint">paste it into your terminal — bypasses Device Flow.</span>
+                <span class="settings-card__hint">no GitHub code to type in.</span>
                 <div id="cli-reissue-result" class="cli-result" hidden></div>
               </div>
               <p class="section-note">Tokens refresh on use; re-issuing never signs you out anywhere else.</p>

package/modules/hall-ui/public/settings.js

@@ -792,7 +792,7 @@
       // three out of the copy registry, blinding the artist's queue to this panel.
       const el = (tag, cls) => Object.assign(document.createElement(tag), { className: cls });
       const say = el('p', 'cli-result__say');
-      say.textContent = 'Fresh CLI token issued. Paste it in your terminal:';
+      say.textContent = 'Fresh CLI token issued. Paste this into a terminal in your project folder:';
       const eyebrow = el('p', 'quote__eyebrow');
       eyebrow.textContent = 'paste command';
       const pre = el('pre', 'quote__pre');

package/modules/hall-ui/public/style.css

@@ -3206,6 +3206,15 @@ main [id] { scroll-margin-top: calc(var(--topbar-h) + 16px); }
   padding: 8px 12px;
   overflow-x: auto;
 }
+/* The get-the-code block is several commands, one per line. Without `pre` the
+   line breaks collapse on screen AND in copy-on-click (it copies innerText),
+   so a builder pasted every command onto one line. Both axes named: see the
+   one-axis-strip rule in this module's CLAUDE.md. */
+.setup__getcode .welcome__paste {
+  display: block;
+  white-space: pre;
+  overflow-y: hidden;
+}
 
 .setup { margin-top: 12px; }
 .setup__intro { font-size: 13px; color: var(--ink-soft); }

package/modules/onboarding/onboarding-state.js

@@ -92,7 +92,7 @@ const ALL_STAGES = [...STAGES, GRADUATED];
 const PRE_AUTH_STEP = {
   id: 'obtain_repo',
   label: 'Obtain the repo',
-  hint: 'Clone the project to thy machine. The build commands live inside the repo, so this comes first.',
+  hint: 'Clone the project to thy machine and run npm install in it. The build commands live inside the repo, so this comes first.',
   informational: true,
 };
 
@@ -126,7 +126,7 @@ const STAGE_LABELS = {
 // onboarding model never named that step, so the hint now points at it ahead of
 // the sign-in itself. See PRE_AUTH_STEP below for the standalone representation.
 const STAGE_HINTS = {
-  auth_complete:    'First obtain the repo — clone it — then sign in via GitHub Device Flow or the web sign-in.',
+  auth_complete:    'First obtain the repo — clone it — then sign in with npx bongos setup in that folder.',
   pick_disciplines: 'Pick the work that calls thee — engineer, artist, ideator, or any mix.',
   first_start:      'Run /builder-start to see claimable works.',
   first_claim:      'Claim a task with /builder-claim N — it is thine alone until thou shippest it.',
@@ -153,7 +153,7 @@ function isKnownStage(stage) {
 //                         clears the step. `source: 'discord'`.
 //   2. pick_disciplines — the real engine stage, cleared by the craft picker.
 //   3. cli_setup        — cleared once the builder has authenticated the CLI
-//                         (ran /builder-setup, which mints a source='cli'
+//                         (ran `npx bongos setup`, which mints a source='cli'
 //                         session). Detected via db.hasCliSession; passed in as
 //                         `cliAuthed`. `source: 'cli'`.
 //   4. ship_three       — the real engine stage. Auto, live "N of 3" counter,
@@ -178,14 +178,14 @@ const DISPLAY_STEPS = [
 const DISPLAY_LABELS = {
   join_discord:     'Join the Discord server',
   pick_disciplines: 'Choose thy craft — engineer, artist, or ideator',
-  cli_setup:        'Run /builder-setup',
+  cli_setup:        'Run npx bongos setup',
   ship_three:       'Ship three works — and rise to Thetes',
 };
 
 const DISPLAY_HINTS = {
   join_discord:     'Connect Discord — thou art auto-joined to the city\'s server and given thy rank.',
   pick_disciplines: 'Pick the work that calls thee — engineer, artist, ideator, or any mix.',
-  cli_setup:        'Sign the CLI in with /builder-setup — this ticks itself once thou art signed in.',
+  cli_setup:        'In thy copy of the project, run npx bongos setup — this ticks itself once thou art signed in.',
   ship_three:       'Carry three tasks through with /builder-ship — the third makes thee a Thetes.',
 };
 

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.48",
+  "version": "1.21.50",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -9056,5 +9056,17 @@
       "id": "1004573",
       "text": "A project brought in from an existing repo now always picks up the sign-in and settings the platform gives it, instead of silently ignoring them."
     }
+  ],
+  "1.21.49": [
+    {
+      "id": "1004575",
+      "text": "New builders get setup steps that actually work end to end: the sign-in commands in Settings and the primer now run from a fresh copy of the project, the primer's terminal commands display properly, and the setup no longer lea"
+    }
+  ],
+  "1.21.50": [
+    {
+      "id": "1004574",
+      "text": "The builders hall now tells newcomers one sign-in command, npx bongos setup, the same on Mac, Windows and Linux — and copying the setup commands now pastes them line by line instead of jammed onto one line."
+    }
   ]
 }

package/scripts/gds/claude-materialize.js

@@ -346,6 +346,9 @@ const STARTER_COMMANDS = [
   'bongos release:*',
   'bongos reauth:*',
   'bongos paste-token:*',
+  // What Settings → CLI access hands out since task 1004575: a clone has no
+  // bare `bongos` on PATH, so the copied command runs through npx.
+  'npx bongos paste-token:*',
   'bongos exec scripts/gds/api.js:*',
   // The read-only subset (task 1003992, ADR 0304). `git branch` and `git fetch`
   // are exact forms on purpose: a flag turns either into a write or an exec. No

package/src/bongos/routes/auth.js

@@ -1306,17 +1306,18 @@ module.exports = function buildAuthRouter() {
         // THERE — on an instance, where the core is an installed dependency and
         // `scripts/gds/` does not exist, so the previous
         // `node scripts/gds/paste-token.js <token>` named a file the builder did not
-        // have and the copy button handed out a command that could not run. `bongos`
-        // is on PATH in any installed instance, so the verb form is layout- and
-        // directory-independent.
+        // have and the copy button handed out a command that could not run. The verb
+        // is run through `npx` (task 1004575): a builder's clone does not put bare
+        // `bongos` on PATH, and `npx bongos` resolves the project's own bin there.
+        // The hall tells them to paste it in their project folder.
         //
         // The --api-base flag carries the issuer above. Omitted when this instance
         // cannot state its own origin, because a flag with an empty value would be
         // worse than none: paste-token would take '' as an explicit instruction and
         // stop falling back to the resolution that works today.
         paste_command: issuer
-          ? `bongos paste-token ${token} --api-base ${issuer}`
-          : `bongos paste-token ${token}`,
+          ? `npx bongos paste-token ${token} --api-base ${issuer}`
+          : `npx bongos paste-token ${token}`,
       });
     } catch (err) {
       log.error('[gds] POST /auth/cli-token/issue', err);

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.48'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.50'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/bongos_cli.mjs

@@ -75,7 +75,8 @@ test('the server emits exactly the verb the CLI registers', () => {
   const cmds = [...tail.matchAll(/`([^`]*bongos paste-token[^`]*)`/g)].map((x) => x[1]);
   assert.ok(cmds.length > 0, 'auth.js should emit at least one paste_command template literal');
   for (const cmd of cmds) {
-    const verb = cmd.split(' ')[1];
+    // `npx bongos <verb> …` since task 1004575 — a clone has no bare `bongos` on PATH.
+    const verb = cmd.replace(/^npx /, '').split(' ')[1];
     assert.ok(cli.VERBS[verb], `server emits "bongos ${verb}" but the CLI has no such verb`);
   }
 });

package/tests/cli_allowlist_permissions.mjs

@@ -210,6 +210,10 @@ const GIT_GH_COMMANDS = [
   'git branch --list', 'git branch --show-current', 'git branch -a', 'git branch -vv',
   'git fetch', 'git fetch origin', 'git fetch origin main',
   'gh pr view:*', 'gh pr checks:*', 'gh pr list:*', 'gh run view:*', 'gh run list:*',
+  // Not git/gh, but the one non-script verb a session is handed to paste: Settings →
+  // CLI access gives `npx bongos paste-token <token>` (task 1004575), a blessed writer
+  // (see BLESSED_WRITERS) spelled the way a clone can run it.
+  'npx bongos paste-token:*',
 ];
 // gds CLIs audited read-only under EVERY flag they take — a prefix rule allows them all.
 // Audited and left OUT: backlog-review.js (POSTs from its default walk) and

package/tests/cli_token_reissue.mjs

@@ -176,8 +176,10 @@ t('paste_command names a CLI VERB, never a filesystem path', () => {
   const cmds = [...tail.matchAll(/`([^`]*bongos paste-token[^`]*)`/g)].map((m) => m[1]);
   assert.equal(cmds.length, 2, `expected both ternary branches, got ${cmds.length}`);
   for (const cmd of cmds) {
-  assert.ok(/^bongos paste-token /.test(cmd),
-    `paste_command must start with the verb form, got: ${cmd}`);
+  // Through npx (task 1004575): a builder's clone does not put bare `bongos` on
+  // PATH, so a bare verb was "command not found" when pasted in the project folder.
+  assert.ok(/^npx bongos paste-token /.test(cmd),
+    `paste_command must start with the npx verb form, got: ${cmd}`);
   // The invariant is "names no FILE ON THE RECIPIENT'S DISK", which the original
   // spelling approximated as "contains no slash". That was too broad once the command
   // had to carry the issuer URL (task 1003722) — `https://host` is not a filesystem
@@ -208,7 +210,7 @@ t('paste_command carries the issuing instance, so the CLI cannot guess wrong', (
 t('an instance that cannot state its own origin omits the flag rather than sending an empty one', () => {
   // `--api-base ''` would read at the far end as an explicit instruction and suppress
   // the fallback that works today — strictly worse than sending no flag at all.
-  assert.ok(/:\s*`bongos paste-token \$\{token\}`/.test(issueBlock),
+  assert.ok(/:\s*`npx bongos paste-token \$\{token\}`/.test(issueBlock),
     'there must be a flagless branch for the empty-issuer case');
 });
 

package/tests/hall_onboarding_bongos_setup.mjs

@@ -0,0 +1,101 @@
+// task 1004574 — every builders-hall onboarding surface names ONE sign-in
+// command, `npx bongos setup`, the same on every OS. Bare `bongos` is not on a
+// fresh clone's PATH; `npx` resolves the repo's own bin after `npm install`.
+// The old three (`/builder-setup`, `./scripts/setup-builder.sh`,
+// `node scripts/setup-builder.js`) must not come back on these surfaces.
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (p) => fs.readFileSync(path.join(ROOT, p), 'utf8');
+const OLD = /\/builder-setup|setup-builder\.(sh|js)/;
+
+// The welcome panel's markup, from the setupSteps literal to the panel's innerHTML.
+function welcomeMarkup() {
+  const src = read('modules/hall-ui/public/hall-render.js');
+  const start = src.indexOf('const setupSteps = `');
+  const end = src.indexOf('body.innerHTML = `', start);
+  assert.ok(start > 0 && end > start, 'welcome panel markup located');
+  return src.slice(start, end).split('\n').filter((l) => !/^\s*\/\//.test(l)).join('\n');
+}
+
+test('welcome panel: the steps and the clone block say npx bongos setup', () => {
+  const w = welcomeMarkup();
+  assert.match(w, /Run <code>npx bongos setup<\/code>/);
+  assert.match(w, /\\nnpm install\\nnpx bongos setup`/, 'clone block ends npm install + npx bongos setup');
+  assert.doesNotMatch(w, OLD, 'no legacy setup command on the welcome panel');
+  assert.doesNotMatch(w, /On Windows, run/, 'one command on every OS — no Windows-only line');
+  assert.match(w, /nodejs\.org/, 'the tooling list names Node, which npm install needs');
+});
+
+test('onboarding checklist: the cli_setup step names npx bongos setup', () => {
+  const src = read('modules/onboarding/onboarding-state.js');
+  const labels = src.slice(src.indexOf('const DISPLAY_LABELS'), src.indexOf('function nextStage'));
+  assert.match(labels, /cli_setup:\s+'Run npx bongos setup'/);
+  assert.match(labels, /cli_setup:\s+'[^']*npx bongos setup[^']*'/);
+  assert.doesNotMatch(labels, OLD);
+});
+
+test('primer: both routes sign in with npx bongos setup', () => {
+  const md = read('docs/onboarding/primer.md');
+  assert.match(md, /```sh\nnpm install\nnpx bongos setup\n```/);
+  // Not inside a `>` quote: the hall's reader garbles a fence there (task 1004575).
+  assert.doesNotMatch(md, /^> ```/m);
+  assert.match(md, /run `npx bongos setup` again/);
+  assert.doesNotMatch(md, OLD);
+});
+
+test('the get-the-code block keeps one command per line (screen and copy)', () => {
+  const css = read('modules/hall-ui/public/style.css');
+  const m = /\.setup__getcode \.welcome__paste\s*\{([^}]*)\}/.exec(css);
+  assert.ok(m, 'scoped rule present');
+  assert.match(m[1], /white-space:\s*pre/, 'copy-on-click reads innerText, so pre is what keeps the line breaks');
+  assert.match(m[1], /overflow-y:\s*hidden/, 'a one-axis strip names both axes');
+});
+
+// task 1004575 — the audit of the above, across the rest of the hall.
+
+test('bin/bongos.js is committed executable, so npx leaves a fresh clone clean', () => {
+  // Committed 100644, `npx bongos` chmods it on first run: the clone then reads as
+  // changed, and a reverted mode makes the next run fail "Permission denied".
+  const entry = execFileSync('git', ['ls-files', '-s', 'bin/bongos.js'], { cwd: ROOT, encoding: 'utf8' });
+  assert.match(entry, /^100755 /, `expected mode 100755, got: ${entry.trim()}`);
+});
+
+test('welcome intro and checklist lead ask only for what a builder needs', () => {
+  const src = read('modules/hall-ui/public/hall-render.js');
+  assert.doesNotMatch(src, /run the platform locally/, 'a builder does not run the platform');
+  assert.match(src, /Clone the project to your machine and run <code>npm install<\/code> in it\./);
+  const st = read('modules/onboarding/onboarding-state.js');
+  assert.doesNotMatch(st, /Device Flow or the web sign-in/);
+  assert.match(st, /auth_complete:\s+'[^']*npx bongos setup[^']*'/);
+});
+
+test('primer no-terminal route installs dependencies (and Node) before signing in', () => {
+  const md = read('docs/onboarding/primer.md');
+    assert.match(md, /Node\*\* \(version 22 or newer\)/);
+  assert.match(md, /send this one message — \*Install this project's dependencies, then run npx bongos setup\.\* —/);
+  assert.match(md, /have four things ready/);
+});
+
+test('Settings CLI access says where to paste the npx command', () => {
+  const html = read('modules/hall-ui/public/settings.html');
+  const js = read('modules/hall-ui/public/settings.js');
+  assert.match(html, /into a terminal in your project folder/);
+  assert.doesNotMatch(html, /bypasses Device Flow/);
+  assert.match(js, /Paste this into a terminal in your project folder:/);
+});
+
+test('the npx paste command Settings hands out is pre-approved for a Claude session', () => {
+  // Both lists: the core's own settings (Bash + PowerShell twins) and the starter
+  // list materialized into every instance. Without them the copied command prompts.
+  const settings = JSON.parse(read('.claude/settings.json'));
+  for (const tool of ['Bash', 'PowerShell']) {
+    assert.ok(settings.permissions.allow.includes(`${tool}(npx bongos paste-token:*)`), `${tool} twin`);
+  }
+  assert.match(read('scripts/gds/claude-materialize.js'), /^\s*'npx bongos paste-token:\*',$/m);
+});