@bongos/core 1.21.69 → 1.21.71

package/scripts/gds/claude-materialize.js

@@ -33,7 +33,7 @@ const { spawnSync } = require('node:child_process');
 const { VERBS } = require('../../bin/bongos.js'); // side-effect-free require (guarded main)
 const ic = require('../../src/instance-config'); // neutral configDir/envPrefix fallbacks (never a founder literal)
 const { isCorePackageName, CORE_PACKAGE_NAMES } = require('../../src/module-loader/catalog'); // one definition of "this checkout IS the core"
-const { renderInstanceClaudeMd } = require('./claude-md-template'); // task 2104 — the starter CLAUDE.md
+const { renderInstanceClaudeMd, refreshStarterCliLines } = require('./claude-md-template'); // task 2104 — the starter CLAUDE.md
 
 // script basename (e.g. "ship.js") → dedicated bongos verb, for verbs that map to a bare script with
 // NO prefixArgs. Verbs whose script is driven by prefixArgs (box → api.js) are EXCLUDED so a generic
@@ -61,16 +61,40 @@ const GDS_INVOCATION_RE = new RegExp(LAUNCHER + String.raw`\s+"?(?:\$CLAUDE_PROJ
 // A non-gds core script under scripts/ (rare in skills, but keep the transform total).
 const OTHER_SCRIPT_RE = new RegExp(LAUNCHER + String.raw`\s+"?(?:\$CLAUDE_PROJECT_DIR\/|\.\/)?scripts\/((?!gds\/)[a-zA-Z0-9_./-]+\.js)"?`, 'g');
 
-// Pure: rewrite core-script invocations in a skill/settings command string to the bongos bin.
-// Idempotent (a string with no matching invocation is returned unchanged).
+// How a project runs the CLI (task 1004621). The `bongos` bin ships inside the @bongos/core
+// dependency (node_modules/.bin/bongos), which is NOT on PATH, so a bare `bongos ship` written
+// into a project's skills failed with `command not found` on every session's first call and the
+// assistant had to recover by retrying through npx. `npx` finds the project's own bin right after
+// `npm install`, with no setup, on every OS and shell — so that is the spelling a project reads.
+const PROJECT_CLI = 'npx bongos';
+
+// A hand-written bare `bongos <verb>` in skill prose (e.g. "`bongos paste-token <token>`"), so it
+// takes the npx spelling too. Case-sensitive on purpose ("Bongos status" is a product noun), only a
+// KNOWN verb, and never when already prefixed by `npx ` or glued to a path/name (`@bongos/core`,
+// `bongos-feedback`, `bongos: command not found` all stay). The `npx ` lookbehind is what keeps a
+// second run from writing `npx npx bongos`.
+function bareVerbRe(verbs) {
+  const names = Object.keys(verbs || {}).filter((v) => /^[a-z][a-z-]*$/.test(v));
+  if (!names.length) return null;
+  names.sort((a, b) => b.length - a.length); // `paste-token` before a shorter prefix of it
+  return new RegExp(String.raw`(?<![\w@/.\-])(?<!npx )bongos (${names.join('|')})(?![\w-])`, 'g');
+}
+
+// Pure: rewrite core-script invocations in a skill/settings command string to the project's CLI
+// spelling (`npx bongos <verb>`, else `npx bongos exec scripts/gds/<x>.js`), and give any bare
+// `bongos <verb>` the same npx prefix. Idempotent: its own output contains neither a
+// `node scripts/…` invocation nor an un-prefixed `bongos <verb>`, so a second run changes nothing.
 function bongosify(text, verbs = VERBS) {
   const map = scriptToVerb(verbs);
-  return String(text == null ? '' : text)
+  const bare = bareVerbRe(verbs);
+  let out = String(text == null ? '' : text);
+  if (bare) out = out.replace(bare, (_whole, verb) => `${PROJECT_CLI} ${verb}`);
+  return out
     .replace(GDS_INVOCATION_RE, (_whole, script) => {
       const verb = map[`${script}.js`];
-      return verb ? `bongos ${verb}` : `bongos exec scripts/gds/${script}.js`;
+      return verb ? `${PROJECT_CLI} ${verb}` : `${PROJECT_CLI} exec scripts/gds/${script}.js`;
     })
-    .replace(OTHER_SCRIPT_RE, (_whole, rel) => `bongos exec scripts/${rel}`);
+    .replace(OTHER_SCRIPT_RE, (_whole, rel) => `${PROJECT_CLI} exec scripts/${rel}`);
 }
 
 // ---- instance rebrand (task 2103) -----------------------------------------
@@ -340,34 +364,38 @@ function copyTreeTransformed(srcDir, destDir, { dryRun, onFile, overwrite = true
 // path and is the agent's escape hatch, so allow-listing it would be a blanket
 // grant wearing a narrow rule's clothes. The one script the core's own list
 // blesses (`api.js`) is named in full instead.
+//
+// EVERY RULE IS THE `npx bongos` SPELLING (task 1004621): a project has no bare
+// `bongos` on PATH, so its skills, its CLAUDE.md and Settings → CLI access
+// (task 1004575) all say `npx bongos …`, and a bare-`bongos` rule would allow a
+// command nothing runs. An instance that took the older bare starter gains the
+// npx twin of each bare rule it still holds on its next upgrade
+// (topUpNpxAllowTwins below).
 const STARTER_COMMANDS = [
-  'bongos claim:*',
-  'bongos ship:*',
-  '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 claim:*',
+  'npx bongos ship:*',
+  'npx bongos release:*',
+  'npx bongos reauth:*',
   'npx bongos paste-token:*',
-  'bongos exec scripts/gds/api.js:*',
+  'npx 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
   // `git diff|log|show` rule, also on purpose: the harness already runs their
   // read-only forms unprompted, and a prefix rule would switch off its flag check
   // (`--output=<file>` writes anywhere, `diff --no-index` reads any file).
   // tests/cli_allowlist_permissions.mjs pins this list to the core's, rule for rule.
-  'bongos start:*',
-  'bongos status:*',
-  'bongos recall:*',
-  'bongos exec scripts/gds/me.js:*',
-  'bongos doctor:*',
-  'bongos exec scripts/gds/preflight.js:*',
-  'bongos exec scripts/gds/skill-preflight.js:*',
-  'bongos exec scripts/gds/ship-check.js:*',
-  'bongos exec scripts/gds/fitness.js:*',
-  'bongos exec scripts/gds/strand-watch.js:*',
-  'bongos exec scripts/gds/stale-worktrees.js:*',
-  'bongos exec scripts/gds/read-session-export.js:*',
+  'npx bongos start:*',
+  'npx bongos status:*',
+  'npx bongos recall:*',
+  'npx bongos exec scripts/gds/me.js:*',
+  'npx bongos doctor:*',
+  'npx bongos exec scripts/gds/preflight.js:*',
+  'npx bongos exec scripts/gds/skill-preflight.js:*',
+  'npx bongos exec scripts/gds/ship-check.js:*',
+  'npx bongos exec scripts/gds/fitness.js:*',
+  'npx bongos exec scripts/gds/strand-watch.js:*',
+  'npx bongos exec scripts/gds/stale-worktrees.js:*',
+  'npx bongos exec scripts/gds/read-session-export.js:*',
   'git status:*',
   'git branch --list',
   'git branch --show-current',
@@ -473,6 +501,37 @@ function topUpStarterDeny(existingText, wanted) {
   return { text: `${JSON.stringify(next, null, 2)}\n`, added, reason: null };
 }
 
+// topUpNpxAllowTwins — the `npx bongos` twin of every bare-`bongos` allow rule an instance's OWN
+// settings.json holds (task 1004621). The skills an upgrade lands now say `npx bongos ship`, and a
+// `Bash(bongos ship:*)` rule does not match that, so without the twin the upgrade would trade a
+// `command not found` for a permission prompt on every blessed command. This is NOT the shell-rule
+// top-up task 1004158 ruled out: nothing new is offered. Each twin is a rule the owner already
+// holds, respelled for the one launcher that reaches the same project-local bin — a rule they
+// removed gets no twin, and nothing they wrote is removed or rewritten. Same { text, added, reason }
+// contract as topUpStarterDeny; an unreadable shape is left alone and reported.
+const BARE_BONGOS_RULE_RE = /^(\w+)\(bongos (.+)\)$/;
+function topUpNpxAllowTwins(existingText) {
+  const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+  const cannotCheck = (reason) => ({ text: null, added: [], reason });
+  let doc;
+  try { doc = JSON.parse(existingText); } catch (err) { return cannotCheck(`not valid JSON (${err.message})`); }
+  if (!isObject(doc)) return cannotCheck('its top level is not a JSON object');
+  const perms = doc.permissions === undefined ? {} : doc.permissions;
+  if (!isObject(perms)) return cannotCheck('its "permissions" is not an object');
+  const allow = perms.allow === undefined ? [] : perms.allow;
+  if (!Array.isArray(allow)) return cannotCheck('its "permissions.allow" is not an array');
+  const have = new Set(allow);
+  const added = [];
+  for (const rule of allow) {
+    const m = typeof rule === 'string' && rule.match(BARE_BONGOS_RULE_RE);
+    const twin = m && `${m[1]}(${PROJECT_CLI} ${m[2]})`;
+    if (twin && !have.has(twin)) { have.add(twin); added.push(twin); }
+  }
+  if (!added.length) return { text: null, added: [], reason: null };
+  const next = { ...doc, permissions: { ...perms, allow: [...allow, ...added] } };
+  return { text: `${JSON.stringify(next, null, 2)}\n`, added, reason: null };
+}
+
 // The starter an instance gets when the core root carries no settings.json — a
 // package-only install. Permissions ONLY: no hooks (they are topology), no env.
 function renderStarterSettings(branding = {}) {
@@ -778,9 +837,26 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
       // The read is guarded: existsSync passing does not mean readable (a directory at that path,
       // a locked or root-owned file), and this runs AFTER the pin moved and the migrations ran, so
       // a throw here would leave a half-applied upgrade. It fails soft, like its sibling above.
+      // The npx twins of the owner's own bare-`bongos` allow rules ride the same single read and
+      // write (task 1004621): applied first, so the deny top-up below works on — and writes — the
+      // text that already carries them. An unparseable file trips both the same way and is
+      // reported once, by the deny half.
       let topUp;
-      try { topUp = topUpStarterDeny(fs.readFileSync(settingsDest, 'utf8'), credentialDeny(toBranding)); }
-      catch (err) { topUp = { text: null, added: [], reason: `it could not be read (${err.code || err.message})` }; }
+      let twins = { text: null, added: [], reason: null };
+      try {
+        const raw = fs.readFileSync(settingsDest, 'utf8');
+        twins = topUpNpxAllowTwins(raw);
+        topUp = topUpStarterDeny(twins.text || raw, credentialDeny(toBranding));
+      } catch (err) { topUp = { text: null, added: [], reason: `it could not be read (${err.code || err.message})` }; }
+      if (twins.added.length) {
+        summary.settingsAllowTwinsAdded = twins.added;
+        summary.notes.push(`.claude/settings.json kept every rule it already had and GAINED the \`npx bongos\` twin of ${twins.added.length} bare-\`bongos\` allow rule(s) it held — the skills now say \`npx bongos …\`, which a bare rule does not match: ${twins.added.join(', ')}`);
+        log(`  ${dryRun ? '[dry-run] would add' : '✓ added'} the npx twin of ${twins.added.length} bare-bongos allow rule(s) to .claude/settings.json (skills now run \`npx bongos …\`; every rule you wrote is kept): ${twins.added.join(', ')}`);
+        if (!topUp.text && !topUp.reason) {
+          if (!dryRun) fs.writeFileSync(settingsDest, twins.text);
+          if (!dryRun) addWritten('.claude/settings.json'); // real run only — the same reasoning as the deny write below
+        }
+      }
       if (topUp.text) {
         if (!dryRun) fs.writeFileSync(settingsDest, topUp.text);
         // Reported as written only on the REAL run, deliberately. writtenPaths doubles as the set
@@ -803,7 +879,7 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
         summary.settingsDenyUncheckable = topUp.reason;
         summary.notes.push(`.claude/settings.json could not be checked for missing deny rules — ${topUp.reason}. It was left exactly as it is, so if it predates task 1003966 its local agent can still read keys and session tokens; compare its permissions.deny against the starter by hand, or fix the file and upgrade again.`);
         log(`  ! .claude/settings.json could NOT be checked for missing deny rules — ${topUp.reason}. Left untouched; its deny half may still be missing.`);
-      } else {
+      } else if (!twins.added.length) {
         summary.skippedFiles.push('settings.json');
         log('  • .claude/settings.json already present — left untouched (the instance owns it; it already carries every credential deny rule. The starter\'s shelf rules are not offered here — they guard a workflow, not a secret, and are starter-only: task 1004158).');
       }
@@ -859,9 +935,27 @@ function materializeClaude({ coreRoot, instanceDir, dryRun = false, overwrite =
   //    branding. Written only when ABSENT — never clobber a CLAUDE.md the instance has
   //    grown (safe for init, adopt, and upgrade alike; the self-copy guard above already
   //    keeps this from ever touching the core/OTB checkout's own CLAUDE.md).
+  //    One narrow exception (task 1004621): the starter's OWN sentences that told the assistant to
+  //    type a bare `bongos …` — not on PATH in a project — are swapped for their `npx bongos …` form
+  //    where they still read exactly as the starter wrote them (refreshStarterCliLines). Not in
+  //    adopt mode, which never touches what the owner already had.
   const claudeMdPath = path.join(instanceDir, 'CLAUDE.md');
   if (fs.existsSync(claudeMdPath)) {
-    summary.notes.push('CLAUDE.md already present — left untouched (the instance owns it).');
+    let refreshed = { changed: 0 };
+    if (overwrite) {
+      try { refreshed = refreshStarterCliLines(fs.readFileSync(claudeMdPath, 'utf8')); } catch { /* unreadable: leave it, as before */ }
+    }
+    if (refreshed.changed) {
+      if (!dryRun) fs.writeFileSync(claudeMdPath, refreshed.text);
+      // Real run only, like the settings top-up: it preserves content, so the upgrade pre-flight's
+      // "materialize overwrites this anyway" waiver must not cover an owner's uncommitted edit.
+      if (!dryRun) addWritten('CLAUDE.md');
+      summary.claudeMdCliLines = refreshed.changed;
+      summary.notes.push(`CLAUDE.md kept as the instance's own, except ${refreshed.changed} unedited starter sentence(s) now say \`npx bongos …\` — the CLI is not on PATH in a project, so a bare \`bongos\` failed with command not found.`);
+      log(`  ${dryRun ? '[dry-run] would update' : '✓ updated'} ${refreshed.changed} unedited starter sentence(s) in CLAUDE.md to \`npx bongos …\` (everything else untouched)`);
+    } else {
+      summary.notes.push('CLAUDE.md already present — left untouched (the instance owns it).');
+    }
   } else {
     if (!dryRun) {
       fs.mkdirSync(instanceDir, { recursive: true });
@@ -1018,4 +1112,4 @@ if (require.main === module) {
   process.exit(s.refused.length ? 1 : 0);
 }
 
-module.exports = { scriptToVerb, bongosify, transformSettings, readSettingsTransform, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeWillRewrite, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };
+module.exports = { scriptToVerb, bongosify, PROJECT_CLI, topUpNpxAllowTwins, transformSettings, readSettingsTransform, renderStarterSettings, STARTER_ALLOW, copyTreeTransformed, materializeClaude, materializeWillRewrite, materializeModuleSkillsIntoCore, isCoreCheckoutRoot, readModuleSkillsManifest, MODULE_SKILLS_MANIFEST, readInstanceSkillsManifest, INSTANCE_SKILLS_MANIFEST, GDS_INVOCATION_RE, buildRebrandRules, rebrandText, disabledModuleSkills, moduleSkillRoster, moduleSkillSources, vendoredSkillGate, SKILL_NAME_RE, VENDOR_DEFAULT_POLICY };

package/scripts/gds/claude-md-template.js

@@ -56,15 +56,15 @@ function renderInstanceClaudeMd(branding = {}) {
 
 Read this at the start of every session. Keep it lean — it loads in full every time.
 
-## First run — before any \`bongos\` command
+## First run — before any \`npx bongos\` command
 
-**If \`node_modules/@bongos/core\` is missing, run \`npm install\` first.** The \`bongos\` CLI ships *inside* that dependency, so until the install completes there is no \`bongos\` command and every instruction below fails with \`command not found\`:
+**If \`node_modules/@bongos/core\` is missing, run \`npm install\` first.** The \`bongos\` CLI ships *inside* that dependency and is **not on your PATH**, so it always runs through npx — \`npx bongos <command>\`, never a bare \`bongos\` (that fails with \`command not found\`). Until the install completes, every \`npx bongos\` instruction below fails too:
 
 \`\`\`bash
 npm install
 \`\`\`
 
-Once per machine, per clone — it is not committed (\`node_modules/\` is ignored on purpose), so a fresh \`git clone\` always needs it. If a \`bongos\` command then still misbehaves, \`bongos doctor\` checks the toolchain and session and prints the fix.
+Once per machine, per clone — it is not committed (\`node_modules/\` is ignored on purpose), so a fresh \`git clone\` always needs it. If an \`npx bongos\` command then still misbehaves, \`npx bongos doctor\` checks the toolchain and session and prints the fix.
 
 ## What this is
 
@@ -74,17 +74,17 @@ ${ident}
 
 **Every change is backed by a claimed Bongos task. No exceptions.** Code, docs, migrations, config — if you are about to change project state and do not hold an active claim covering it, stop: create or find the task, claim it, then make the change. There is no "tiny fix" or "just a doc" loophole; the database is the complete ledger of what happened to this project.
 
-- **Start every session with \`bongos start\`** (or \`/builder-start\`) — it lists the tasks you can claim right now, parallel-safe against everyone else's active claims.
-- **\`bongos claim <id>\`** locks a task to your session. If it refuses (already claimed, not ready, dependencies not shipped), pick another.
-- **\`bongos ship\`** runs the smoke + grade, then merges and deploys; **\`bongos release <id>\`** drops a claim with no credit. Ship or release before you sign off.
+- **Start every session with \`npx bongos start\`** (or \`/builder-start\`) — it lists the tasks you can claim right now, parallel-safe against everyone else's active claims.
+- **\`npx bongos claim <id>\`** locks a task to your session. If it refuses (already claimed, not ready, dependencies not shipped), pick another.
+- **\`npx bongos ship\`** runs the smoke + grade, then merges and deploys; **\`npx bongos release <id>\`** drops a claim with no credit. Ship or release before you sign off.
 - **Dependencies gate everything** — a task becomes claimable only once every task it depends on has shipped.
 - **Code you write or touch carries a doc-comment** — each module a header, each public function/class a line or two, saying *what* it does and *why* it exists (never how), in the words someone would search for. Agents find code by searching text, so meaning written into the source is what makes it findable.
 
 ## Where things live
 
-- **Live work state** (tasks, versions, ranks, ${currency}): the Bongos DB — \`bongos start\` / \`bongos status\`, or ${hallLine}.${statusLine}
+- **Live work state** (tasks, versions, ranks, ${currency}): the Bongos DB — \`npx bongos start\` / \`npx bongos status\`, or ${hallLine}.${statusLine}
 - **This instance's identity** (product, world, brand, addresses): \`config/branding.json\`. **Which features are on**: \`config/modules.json\`.
-- **The platform you stand on** (rank ladder, the ship/grade/deploy pipeline, permissions, migrations) is vendored **Cloud Bongos core** — build the product, not the platform under it. Landing code is Bongos's job: claim a task and run \`bongos ship\`, never a raw \`git push\`/deploy.
+- **The platform you stand on** (rank ladder, the ship/grade/deploy pipeline, permissions, migrations) is vendored **Cloud Bongos core** — build the product, not the platform under it. Landing code is Bongos's job: claim a task and run \`npx bongos ship\`, never a raw \`git push\`/deploy.
 
 ## Permissions
 
@@ -96,8 +96,45 @@ Builders are rewarded in **${currency}** for shipped work.
 
 ---
 
-*This is a starter, authored by \`bongos init\`. Grow it as the project grows — add your architecture, versioning methodology, and hard-won gotchas — but keep it lean: every line spends context budget in every session.*
+*This is a starter, authored by \`npx bongos init\`. Grow it as the project grows — add your architecture, versioning methodology, and hard-won gotchas — but keep it lean: every line spends context budget in every session.*
 `;
 }
 
-module.exports = { renderInstanceClaudeMd };
+// The starter's own sentences as an earlier `bongos init` wrote them, each beside its `npx bongos`
+// form (task 1004621). Every pair is branding-independent text this template authored, so an exact
+// match can only be a line the owner never changed.
+const LEGACY_CLI_LINES = [
+  ['## First run — before any `bongos` command\n\n**If `node_modules/@bongos/core` is missing, run `npm install` first.** The `bongos` CLI ships *inside* that dependency, so until the install completes there is no `bongos` command and every instruction below fails with `command not found`:',
+    '## First run — before any `npx bongos` command\n\n**If `node_modules/@bongos/core` is missing, run `npm install` first.** The `bongos` CLI ships *inside* that dependency and is **not on your PATH**, so it always runs through npx — `npx bongos <command>`, never a bare `bongos` (that fails with `command not found`). Until the install completes, every `npx bongos` instruction below fails too:'],
+  ['If a `bongos` command then still misbehaves, `bongos doctor` checks', 'If an `npx bongos` command then still misbehaves, `npx bongos doctor` checks'],
+  ['- **Start every session with `bongos start`** (or `/builder-start`)', '- **Start every session with `npx bongos start`** (or `/builder-start`)'],
+  ['- **`bongos claim <id>`** locks a task to your session.', '- **`npx bongos claim <id>`** locks a task to your session.'],
+  ['- **`bongos ship`** runs the smoke + grade, then merges and deploys; **`bongos release <id>`** drops', '- **`npx bongos ship`** runs the smoke + grade, then merges and deploys; **`npx bongos release <id>`** drops'],
+  ['the Bongos DB — `bongos start` / `bongos status`, or', 'the Bongos DB — `npx bongos start` / `npx bongos status`, or'],
+  ['claim a task and run `bongos ship`, never', 'claim a task and run `npx bongos ship`, never'],
+  ['*This is a starter, authored by `bongos init`.', '*This is a starter, authored by `npx bongos init`.'],
+];
+
+// refreshStarterCliLines — bring an EXISTING project's CLAUDE.md onto the `npx bongos` spelling
+// (task 1004621). The starter is written only when CLAUDE.md is absent, so every project scaffolded
+// before this kept telling its assistant to type a bare `bongos start` — a command that is not on
+// PATH — in the one file loaded every session. The instance owns the file, so this replaces ONLY
+// the starter's own sentences, matched exactly: a line the owner reworded is left alone, nothing
+// is added or removed, and a file grown from the starter keeps everything else byte for byte.
+// Pure: returns { text, changed } where `changed` counts the sentences replaced.
+function refreshStarterCliLines(text) {
+  let out = String(text == null ? '' : text);
+  let changed = 0;
+  // A Windows checkout (git autocrlf) holds the file with CRLF endings; match it in its own.
+  const eol = out.includes('\r\n') ? (s) => s.replace(/\n/g, '\r\n') : (s) => s;
+  for (const [legacyLf, currentLf] of LEGACY_CLI_LINES) {
+    const legacy = eol(legacyLf);
+    const current = eol(currentLf);
+    if (!out.includes(legacy)) continue;
+    out = out.split(legacy).join(current);
+    changed += 1;
+  }
+  return { text: out, changed };
+}
+
+module.exports = { renderInstanceClaudeMd, refreshStarterCliLines, LEGACY_CLI_LINES };

package/scripts/gds/cli-lib.js

@@ -512,7 +512,7 @@ function printUnauthGuidanceAndExit() {
     console.error(`  Recover the fast (UI-first) way — run ${surfaceAction('reauth')}`);
     console.error('  (opens your Settings page; under "CLI Access" click "Re-issue CLI');
     console.error('   token", copy the one-liner, paste it back — no terminal Device Flow.)');
-    console.error('  Fallback (browser sign-in): bongos login <instance-url>');
+    console.error('  Fallback (browser sign-in): npx bongos login <instance-url>');
   } else {
     console.error('  Recover the fast (UI-first) way — run /builder-reauth, or:');
     console.error('    node scripts/gds/reauth.js');
@@ -609,7 +609,7 @@ function printInstanceMismatchAndExit({ expected, actual }) {
   console.error(`    Your session is signed in to:         ${actual}`);
   console.error('');
   console.error('  Sign in to THIS instance, then re-run your command:');
-  console.error(`    bongos login ${expected}`);
+  console.error(`    npx bongos login ${expected}`);
   console.error(`    (or, from a checkout without the bongos bin:  node scripts/gds/login.js ${expected})`);
   console.error('');
   console.error('  Intentionally targeting another instance? Set the base explicitly, e.g.');
@@ -764,8 +764,8 @@ async function requireSession() {
     if (isTerminalSurface()) {
       // A terminal reader may have no instance configured at all — naming one is the whole point
       // of `login`, and `/builder-*` does not exist outside a Claude Code session (task 1003730).
-      console.error(`  • First time here            → run bongos login <instance-url>  (sign in with a browser click)`);
-      console.error(`  • Signed in before / expired → run bongos reauth                (re-issue your CLI token)`);
+      console.error(`  • First time here            → run npx bongos login <instance-url>  (sign in with a browser click)`);
+      console.error(`  • Signed in before / expired → run npx bongos reauth                (re-issue your CLI token)`);
     } else {
       console.error(`  • First time on the project  → run /builder-setup   (one-time GitHub sign-in that also registers you)`);
       console.error(`  • Signed in before / expired → run /builder-reauth  (fast UI re-issue of your CLI token)`);

package/scripts/gds/feedback-send.js

@@ -1,40 +1,58 @@
 #!/usr/bin/env node
-// Send feedback about Bongos itself to the Cloud Bongos maintainers (task 1004462).
+// Send feedback about Bongos itself to the Cloud Bongos maintainers (tasks 1004462, 1004591).
 //
 // Usage:
 //   bongos feedback "the claim command hung for two minutes"
 //   bongos feedback --idea "let me filter the task list by goal"
-//   bongos feedback --message-file notes.md
-//   [--json]
+//   bongos feedback --message-file notes.md      (or --message-file - for stdin)
+//   [--wait]   send in the foreground and print the outcome (debugging)
 //
-// Not the /feedback skill, which loads a locally recorded walkthrough into a
-// session. This SENDS: it posts to the builder's OWN project (POST /feedback,
-// src/bongos/routes/feedback.js), which relays it to the hub. A bug lands on the
-// hub as a 'backlog' task in the maintenance goal awaiting a maintainer's nod; an
-// idea lands in the hub's idea inbox. Only the typed text and version stamps
-// travel — never code, a transcript or file contents.
+// Straight to the hub, never through the project: a project with no hub link can
+// still send. The builder's OWN project vouches for who sent it — the CLI asks it
+// for a one-time receipt (src/bongos/routes/feedback.js) and the hub redeems that
+// receipt before filing (modules/platform-identity/instance-feedback.js). So a
+// signed-in builder does nothing extra.
+//
+// Fast and quiet by design (the owner, 2026-10-06): the command prints one line
+// and returns at once; a detached background process does the network. No task
+// number comes back. Only the typed text (secret-scrubbed) and version stamps travel.
 
 'use strict';
 
+const fs = require('node:fs');
 const os = require('node:os');
-const { cliClient, requireSession, argText, hasFlag, errCode, errDetails, cliExit } = require('./cli-lib');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { spawn } = require('node:child_process');
+const { cliClient, requireSession, loadSessionSync, argText, hasFlag, errCode, cliExit } = require('./cli-lib');
+const ic = require('../../src/instance-config');
 
 const USAGE = [
   'usage:',
-  '  bongos feedback "what went wrong"          report a problem with Bongos',
-  '  bongos feedback --idea "what you wish for" suggest an improvement',
-  '  bongos feedback --message-file notes.md    send a longer note from a file',
+  '  npx bongos feedback "what went wrong"          report a problem with Bongos',
+  '  npx bongos feedback --idea "what you wish for" suggest an improvement',
+  '  npx bongos feedback --message-file notes.md    send a longer note from a file (- for stdin)',
   '',
   'Goes to the Cloud Bongos maintainers. Only the text you type and the Bongos',
   'versions you run are sent — no code, chat or files from your project.',
 ].join('\n');
 
-// The CLI release, as `bongos version` reports it: config/bongos-cli.json where
-// the core checkout carries it (an instance does not — task 1824), else the
-// package version. Read from disk, never required, so a vanilla core still runs.
+const SENT_LINE = 'Sent to the Bongos team.';
+const REPEAT_WINDOW_MS = 6 * 60 * 60 * 1000;
+
+// Plain lines for the refusals the builder can see (everything else happens in
+// the background and is written to the outcome file, never to the terminal).
+const REFUSALS = {
+  message_required: 'Nothing to send — add your feedback after the command, in quotes.',
+  too_long: 'That is too long to send — keep it under 4,000 characters, or split it into two.',
+  local_only: 'This project runs only on your computer, so Cloud Bongos cannot confirm who sent the report. Nothing was sent.',
+  no_scrubber: 'Feedback was not sent: the secret filter that checks every report is missing from this install.',
+};
+
+function stateDir() { return path.join(os.homedir(), '.config', ic.FALLBACK_DIR || 'cloudbongos'); }
+
+// The CLI release, as `bongos version` reports it. Read from disk, never required.
 function cliVersion() {
-  const fs = require('node:fs');
-  const path = require('node:path');
   for (const rel of ['../../config/bongos-cli.json', '../../package.json']) {
     try {
       const f = path.join(__dirname, rel);
@@ -44,17 +62,19 @@ function cliVersion() {
   return null;
 }
 
-// The message: --message / --message-file, else every positional word joined.
-function readMessage(args) {
-  if (args.includes('--message') || args.includes('--message-file')) return argText('--message', args);
-  return args.filter((a) => !a.startsWith('--')).join(' ');
+// The message: --message / --message-file (incl. - for stdin), else every
+// positional word joined, else whatever was piped in.
+function readMessage(args, io = {}) {
+  if (args.includes('--message') || args.includes('--message-file')) return argText('--message', args, io).value || '';
+  const words = args.filter((a) => !a.startsWith('--')).join(' ');
+  if (words) return words;
+  const stdinIsPiped = io.stdinIsPiped !== undefined ? io.stdinIsPiped : !process.stdin.isTTY;
+  if (!stdinIsPiped) return '';
+  try { return (io.readStdin || (() => fs.readFileSync(0, 'utf8')))(); } catch { return ''; }
 }
 
 // Every report goes through the transcript-grade secret scrubber before it leaves
-// this machine (task 1004467). An assistant may file unasked when a builder vents,
-// so nobody reviews the text first — the scrubber is the check that does not
-// depend on the assistant's judgment. FAIL CLOSED: no scrubber, nothing is sent.
-// It also strips the builder's environment secrets by value, whatever their shape.
+// this machine (task 1004467). FAIL CLOSED: no scrubber, nothing is sent.
 function scrubReport(message, env = process.env) {
   let scrub;
   try { scrub = require('../../modules/security/secret-scrub.js'); } catch { return null; }
@@ -63,69 +83,122 @@ function scrubReport(message, env = process.env) {
   return { text, removed };
 }
 
-// Plain-language lines for each refusal the route can give.
-const REFUSALS = {
-  message_required: 'Nothing to send — add your feedback after the command, in quotes.',
-  validation_failed: 'That could not be sent as written — keep it under 4,000 characters, or split it into two.',
-  not_hub_connected: 'This project is not connected to Cloud Bongos, so feedback cannot be relayed from here.\n'
-    + 'Report it to the Bongos maintainers on the Bongos core repository instead.',
-  membership_required: 'Cloud Bongos does not yet know you as a member of this project.\n'
-    + 'Sign in to this project once through Cloud Bongos in a browser, then try again.',
-  rate_limited: 'Too much feedback from you or this project in the last hour. Try again later.',
-  feedback_unavailable: 'Cloud Bongos is not taking bug reports right now (no version is being built). Try again later.',
-  hub_unreachable: 'Could not reach Cloud Bongos. Check your connection and try again.',
-};
+// A project the hub cannot reach can never vouch for a report — say so up front
+// rather than send something that is certain to be dropped.
+function isLocalBase(base) {
+  let host;
+  try { host = new URL(base).hostname.toLowerCase(); } catch { return true; }
+  if (require('node:net').isIP(host.replace(/^\[|\]$/g, ''))) return true;
+  return !host.includes('.') || /(^|\.)(localhost|local|internal|test|invalid)$/.test(host);
+}
+
+// Repeat guard: the same report (same first line) inside REPEAT_WINDOW_MS is not
+// sent twice, so an assistant filing on every rant cannot spam the maintainers.
+function repeatKey(message) {
+  const first = String(message).split('\n').map((l) => l.trim().toLowerCase()).find(Boolean) || '';
+  return crypto.createHash('sha256').update(first).digest('hex').slice(0, 16);
+}
+function checkAndRecordRepeat(message, { file = path.join(stateDir(), 'feedback-sent.json'), now = Date.now() } = {}) {
+  let seen = {};
+  try { seen = JSON.parse(fs.readFileSync(file, 'utf8')) || {}; } catch { /* first report */ }
+  for (const [k, t] of Object.entries(seen)) if (!(now - t < REPEAT_WINDOW_MS)) delete seen[k];
+  const key = repeatKey(message);
+  if (Object.prototype.hasOwnProperty.call(seen, key)) return true;
+  seen[key] = now;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(seen), { mode: 0o600 });
+  } catch { /* a guard that cannot write still lets the report through */ }
+  return false;
+}
+
+// deliver — the network half: receipt from the project, then the report to the
+// hub. Returns an outcome object; never prints. Runs in the background child.
+async function deliver({ message, kind }, deps = {}) {
+  const api = deps.api || await cliClient();
+  const base = deps.base || ic.resolveApiBase({ session: loadSessionSync() });
+  const doFetch = deps.fetchImpl || fetch;
+  const sha256 = crypto.createHash('sha256').update(message, 'utf8').digest('hex');
+  const r = await api.request('POST', '/feedback/receipt', { body: { sha256, kind } });
+  if (!r.ok) return { ok: false, step: 'receipt', code: errCode(r.data) || `http_${r.status}` };
+  const origin = new URL(base).origin;
+  const hub = String((r.data && r.data.hub) || origin).replace(/\/+$/, '');
+  const res = await doFetch(`${hub}/api/bongos/sso/feedback/direct`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+    body: JSON.stringify({
+      origin, receipt: r.data.receipt, message, kind,
+      context: { cli_version: cliVersion(), os: `${os.platform()} ${os.release()}` },
+    }),
+    signal: AbortSignal.timeout(15000),
+  });
+  if (res.status === 202) return { ok: true, hub };
+  let body = null;
+  try { body = await res.json(); } catch { /* non-JSON */ }
+  return { ok: false, step: 'hub', code: errCode(body) || `http_${res.status}` };
+}
+
+// The background child: read the queued report, deliver it, record the outcome
+// where a curious builder (or a maintainer helping them) can look.
+async function runDeliverChild(file) {
+  let job;
+  try { job = JSON.parse(fs.readFileSync(file, 'utf8')); } finally { fs.rmSync(path.dirname(file), { recursive: true, force: true }); }
+  let outcome;
+  try { outcome = await deliver(job); } catch (e) { outcome = { ok: false, step: 'network', code: String(e && e.message || e).slice(0, 200) }; }
+  try {
+    fs.writeFileSync(path.join(stateDir(), 'feedback-last.json'), JSON.stringify({ at: new Date().toISOString(), ...outcome }), { mode: 0o600 });
+  } catch { /* nowhere to record — the report itself is what mattered */ }
+  return outcome.ok ? 0 : 1;
+}
+
+// Hand the job to a detached child and return. The job travels in a 0600 temp
+// file, never argv (visible in ps) or env.
+function spawnDelivery(job, { spawnImpl = spawn } = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-feedback-'));
+  const file = path.join(dir, 'job.json');
+  fs.writeFileSync(file, JSON.stringify(job), { mode: 0o600 });
+  const child = spawnImpl(process.execPath, [__filename, '--deliver', file], { detached: true, stdio: 'ignore' });
+  if (child && child.unref) child.unref();
+  return file;
+}
 
-async function main(argv = process.argv.slice(2)) {
+async function main(argv = process.argv.slice(2), deps = {}) {
   if (hasFlag('--help', argv) || hasFlag('-h', argv)) { console.log(USAGE); return 0; }
-  const json = hasFlag('--json', argv);
   const kind = hasFlag('--idea', argv) ? 'idea' : 'bug';
-  const message = String(readMessage(argv) || '').trim();
-  if (!message) { console.error(USAGE); return 2; }
+  const message = String(readMessage(argv, deps.io) || '').trim();
+  if (!message) { console.error(REFUSALS.message_required); return 2; }
+  if (message.length > 4000) { console.error(REFUSALS.too_long); return 2; }
 
   const scrubbed = scrubReport(message);
-  if (!scrubbed) {
-    console.error('Feedback was not sent: the secret filter that checks every report is missing from this install.');
-    return 1;
-  }
+  if (!scrubbed) { console.error(REFUSALS.no_scrubber); return 1; }
 
-  await requireSession();
-  const api = await cliClient();
-  const res = await api.request('POST', '/feedback', {
-    body: { message: scrubbed.text, kind, context: { cli_version: cliVersion(), os: `${os.platform()} ${os.release()}` } },
-  });
-  if (scrubbed.removed > 0 && !json) {
-    console.log(`Removed ${scrubbed.removed} secret-looking value(s) from the report before sending.`);
-  }
+  const session = await (deps.requireSession || requireSession)();
+  const base = deps.base || ic.resolveApiBase({ session });
+  if (isLocalBase(base)) { console.error(REFUSALS.local_only); return 1; }
 
-  if (json) { console.log(JSON.stringify(res.data, null, 2)); return res.ok ? 0 : 1; }
-  if (!res.ok) {
-    const code = errCode(res.data);
-    const details = errDetails(res.data) || {};
-    let line = REFUSALS[code] || `Feedback was not sent (${code || `HTTP ${res.status}`}).`;
-    if (code === 'rate_limited' && details.retry_after_seconds) {
-      line += ` (in about ${Math.ceil(details.retry_after_seconds / 60)} min)`;
-    }
-    console.error(line);
-    return 1;
+  const job = { message: scrubbed.text, kind };
+  if ((deps.checkRepeat || checkAndRecordRepeat)(job.message)) {
+    console.log('Already sent — the Bongos team has this one.');
+    return 0;
   }
-  const d = res.data || {};
-  if (d.landed === 'task') {
-    console.log(`Thanks — sent to the Cloud Bongos maintainers as task ${d.task_id}.`);
-    console.log('It waits for a maintainer to approve it before anyone works on it.');
-    if (d.hub_origin) console.log(`${String(d.hub_origin).replace(/\/+$/, '')}/builders#/task/${d.task_id}`);
-  } else {
-    console.log(`Thanks — your idea is in the Cloud Bongos idea inbox (idea ${d.idea_id}) for the maintainers to review.`);
+  if (hasFlag('--wait', argv)) {
+    const outcome = await (deps.deliver || deliver)(job);
+    console.log(outcome.ok ? SENT_LINE : `Not sent (${outcome.step}: ${outcome.code}).`);
+    return outcome.ok ? 0 : 1;
   }
+  (deps.spawnDelivery || spawnDelivery)(job);
+  console.log(SENT_LINE);
   return 0;
 }
 
 if (require.main === module) {
+  const argv = process.argv.slice(2);
+  const run = argv[0] === '--deliver' ? runDeliverChild(argv[1]) : main(argv);
   // cliExit, never process.exit, after a request (task 1002734 — the Windows abort).
-  main().then((code) => cliExit(code), (err) => {
+  run.then((code) => cliExit(code), (err) => {
     console.error(`Feedback was not sent: ${err && err.message ? err.message : err}`);
     cliExit(1);
   });
 }
 
-module.exports = { main, readMessage, REFUSALS, scrubReport };
+module.exports = { main, deliver, readMessage, REFUSALS, scrubReport, isLocalBase, repeatKey, checkAndRecordRepeat, SENT_LINE };