@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/surface.js

@@ -0,0 +1,101 @@
+// scripts/bongos/surface.js — who is reading this output: an agent, or a person in a terminal?
+// (task 1003680, follow-up to ADR 0258.)
+//
+// WHY THIS EXISTS
+// The CLI's cards were written for exactly one reader: a Claude Code session. They carry
+// `[otb-card]` directives addressed to the model, `/builder-ship N` slash commands, and markdown
+// link syntax — all correct in a chat feed, all wrong in a terminal. That stayed invisible while
+// the CLI lived inside the private core, because the only way to run it was from a session.
+// `@cloudbongos/cli` (ADR 0258) put the same output in front of newcomers on a bare laptop, where
+// the first thing they read is an instruction written to somebody else and a command that does
+// not exist.
+//
+// HOW THE SURFACE IS DECIDED — and why not isTTY
+// AGENT is the default, so nothing about the Claude Code path changes unless something opts out.
+// The opt-out is `BONGOS_SURFACE=terminal`, set by the `bongos` DISPATCHER (bin/bongos.js, and the
+// generated one in the public package) when it spawns a verb. The skills and the card-delivery
+// hook run `node scripts/bongos/<verb>.js` DIRECTLY, never through the dispatcher, so they keep the
+// agent shape byte-for-byte.
+//
+// `process.stdout.isTTY` would get this exactly backwards: a Claude Code session's stdout is not a
+// TTY either, so TTY-sniffing would classify every agent run as a terminal and break the card
+// contract the skills depend on. The signal has to be an explicit statement of intent, not a guess.
+
+'use strict';
+
+const AGENT = 'agent';
+const TERMINAL = 'terminal';
+
+// Which reader is this output for? Pure: takes the env, returns a string.
+function resolveSurface(env = process.env) {
+  const raw = String((env && env.BONGOS_SURFACE) || '').trim().toLowerCase();
+  return raw === TERMINAL ? TERMINAL : AGENT;
+}
+
+function isTerminal(env = process.env) {
+  return resolveSurface(env) === TERMINAL;
+}
+
+// A task reference. Agents get a hall link because a bare `#NNN` autolinks to GitHub issues and
+// 404s (the CLAUDE.md ref rule); a terminal reader gets the plain id and the URL beside it, since
+// `[#123](https://…)` is just noise on a console.
+function taskRef(id, url, env = process.env) {
+  return isTerminal(env) ? `#${id}` : `[#${id}](${url}${id})`;
+}
+
+// How a reader runs the CLI (task 1004621). The `bongos` bin ships inside @bongos/core and is not
+// on PATH — in a project it sits at node_modules/.bin/bongos, and the global @cloudbongos/cli that
+// once put a bare `bongos` on PATH is retired (ADR 0324). `npx` finds the local bin with no setup,
+// in a project and in a core checkout alike, so every printed command uses it. A bare `bongos …`
+// sent the first command of a project's session into `command not found`.
+const CLI = 'npx bongos';
+
+// A CLI command line to print: `cli('claim <id>')` → `npx bongos claim <id>`.
+function cli(rest) {
+  return rest ? `${CLI} ${rest}` : CLI;
+}
+
+// An action the reader can actually run. In a session that is the slash command; in a terminal it
+// is the `npx bongos` verb. `/builder-ship 123` does not exist outside Claude Code.
+function action(verb, arg, env = process.env) {
+  const tail = arg == null ? '' : ` ${arg}`;
+  return isTerminal(env) ? cli(`${verb}${tail}`) : `/builder-${verb}${tail}`;
+}
+
+// Markdown emphasis is decoration in a feed and literal asterisks on a console.
+function strong(s, env = process.env) {
+  return isTerminal(env) ? String(s) : `**${s}**`;
+}
+function em(s, env = process.env) {
+  return isTerminal(env) ? String(s) : `_${s}_`;
+}
+function code(s, env = process.env) {
+  return isTerminal(env) ? String(s) : `\`${s}\``;
+}
+
+// A table. Agents get GitHub-flavoured markdown (the feed renders it); a terminal gets columns
+// padded to width with a rule under the header, which is what a console can actually align.
+function table(headers, rows, env = process.env) {
+  if (!isTerminal(env)) {
+    return [
+      `| ${headers.join(' | ')} |`,
+      `|${headers.map(() => '---').join('|')}|`,
+      ...rows.map((r) => `| ${r.join(' | ')} |`),
+    ].join('\n');
+  }
+  const widths = headers.map((h, i) => Math.max(
+    String(h).length,
+    ...rows.map((r) => String(r[i] == null ? '' : r[i]).length),
+  ));
+  const line = (cells) => cells
+    .map((c, i) => String(c == null ? '' : c).padEnd(widths[i]))
+    .join('  ')
+    .replace(/\s+$/, '');
+  return [
+    line(headers),
+    widths.map((w) => '─'.repeat(w)).join('  '),
+    ...rows.map(line),
+  ].join('\n');
+}
+
+module.exports = { AGENT, TERMINAL, CLI, cli, resolveSurface, isTerminal, taskRef, action, strong, em, code, table };

package/scripts/bongos/task.js

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+// scripts/bongos/task.js — `bongos task` : create + show a Bongos task from the terminal.
+//
+// task 2123 (demo-audit fix C1). The bongos CLI had start/claim/ship/status/… but no
+// way to CREATE a task — so seeding the first task (a new owner's opening move) meant
+// hand-driving POST /api/bongos/tasks through `bongos exec scripts/bongos/api.js`. This is
+// the first-class front door.
+//
+// Usage:
+//   bongos task new --title "…" --description "…" [--kind feature] [--discipline engineer]
+//                   [--priority 3] [--version <id>] [--goal <id>] [--criteria C1,C2]
+//                   [--touches a/,b/] [--est-minutes N] [--credits N] [--ready] [--json]
+//   bongos task show <id> [--json]
+//   bongos task visual <id> <image> [--alt "caption"]   attach/replace the ship-time visual
+//   bongos task visual <id> --remove                    take it back off
+//   bongos task visual <id> <image> --slot <name>       attach/replace a NAMED visual (task 1004322)
+//   bongos task visual <id> --slot <name> --remove      take a named one back off
+//
+// Task CREATION is Archon-gated SERVER-SIDE (creating work shapes scope, ADR 0016). This
+// CLI adds no authority — a lower rank gets a clear 403 message pointing at idea capture.
+
+const { cliClient, requireSession, arg, hasFlag, errCode } = require('./cli-lib');
+// task 1003109: the ship-time VISUAL. The CLI screens the file with the SERVER's
+// own constants, so what it accepts is exactly what the upload route accepts.
+const taskVisuals = require('../../modules/lifecycle/task-visuals');
+// task 1004597: the one spelling of "this is platform upkeep" (kind infra, no goal).
+const { UPKEEP_KIND } = require('../../modules/lifecycle/upkeep-home');
+
+// Valid enums (mirrors the server's task-classifier vocab; a friendly client-side check
+// so an obvious typo fails before the round-trip — the server stays authoritative).
+const VALID_KINDS = ['feature', 'bug', 'infra', 'refactor', 'spike', 'learning-capture', 'cleanup', 'decision', 'blocker-resolution', 'verify'];
+const VALID_DISCIPLINES = ['engineer', 'artist', 'ideator', 'ui'];
+
+function csv(v) {
+  return String(v || '').split(',').map((s) => s.trim()).filter(Boolean);
+}
+
+// PURE argv → { body, criteria, errors } — exported for the unit test (no network).
+// `args` is the argv slice AFTER the `new` subcommand.
+function buildTaskBody(args) {
+  const errors = [];
+  const title = arg('--title', args);
+  const description = arg('--description', args);
+  if (!title) errors.push('--title is required');
+  if (!description) errors.push('--description is required');
+
+  const kind = arg('--kind', args) || 'feature';
+  if (!VALID_KINDS.includes(kind)) errors.push(`--kind must be one of: ${VALID_KINDS.join(', ')}`);
+  const discipline = arg('--discipline', args) || 'engineer';
+  if (!VALID_DISCIPLINES.includes(discipline)) errors.push(`--discipline must be one of: ${VALID_DISCIPLINES.join(', ')}`);
+
+  const num = (flag) => { const v = arg(flag, args); return v == null ? undefined : Number(v); };
+  const priority = num('--priority');
+  if (priority !== undefined && (!Number.isInteger(priority) || priority < 1 || priority > 5)) {
+    errors.push('--priority must be an integer 1–5');
+  }
+  const goalRaw = arg('--goal', args);
+  const goalId = goalRaw == null ? undefined : Number(goalRaw);
+  if (goalRaw != null && (!Number.isInteger(goalId) || goalId <= 0)) errors.push('--goal must be a positive integer task-goal id');
+
+  const body = {
+    title,
+    description,
+    kind,
+    discipline,
+    status: hasFlag('--ready', args) ? 'ready' : 'backlog',
+    source: 'bongos-task-cli',
+  };
+  const version = arg('--version', args);
+  if (version) body.version_id = version;
+  if (goalId !== undefined) body.goal_id = goalId;
+  if (priority !== undefined) body.priority = priority;
+  const est = num('--est-minutes'); if (est !== undefined) body.est_minutes = est;
+  const md = num('--manual-degree'); if (md !== undefined) body.manual_degree = md;
+  const credits = num('--credits'); if (credits !== undefined) body.credits_reward = credits;
+  const touches = csv(arg('--touches', args)); if (touches.length) body.touches = touches;
+  const criteria = csv(arg('--criteria', args));
+  if (criteria.length) body.criterion_ids = criteria;
+
+  return { body, criteria, errors };
+}
+
+function usage() {
+  console.error('usage:');
+  console.error('  bongos task new --title "…" --description "…" [--kind feature] [--discipline engineer]');
+  console.error('                  [--priority 3] [--version <id>] [--goal <id>] [--criteria C1,C2]');
+  console.error('                  [--touches a/,b/] [--est-minutes N] [--credits N] [--ready] [--json]');
+  console.error('  bongos task show <id> [--json]');
+  console.error('  bongos task visual <id> <image> [--alt "caption"]   attach or replace the ship-time visual');
+  console.error('  bongos task visual <id> --remove                    remove it again');
+  console.error('  bongos task visual <id> <image> --slot <name>       attach or replace a named visual (e.g. after-phone-dark)');
+  console.error('\n  Platform upkeep (a Bongos upgrade, maintenance) needs no goal: pass --kind infra');
+  console.error("  and leave out --goal, and it is filed under the version's maintenance goal.");
+  console.error(`\n  kinds: ${VALID_KINDS.join(' | ')}`);
+  console.error(`  disciplines: ${VALID_DISCIPLINES.join(' | ')}`);
+}
+
+function hallLink(base, id) {
+  try { return `${new URL(base).origin}/builders#/task/${id}`; } catch { return `task #${id}`; }
+}
+
+// The version_id a task defaults to when --version is omitted: the most-recent
+// BUILDING version (the capture.js precedent, so idea-capture and task-create agree).
+// Returns null when none is building — the caller then requires an explicit --version.
+async function resolveDefaultVersion(api) {
+  const r = await api.versions.getVersions();
+  if (!r.ok) return null;
+  const building = (r.data?.versions ?? []).filter((v) => v.status === 'building');
+  if (building.length === 0) return null;
+  building.sort((a, b) => {
+    const ta = a.started_at ? new Date(a.started_at).getTime() : 0;
+    const tb = b.started_at ? new Date(b.started_at).getTime() : 0;
+    return tb - ta;
+  });
+  return building[0].id;
+}
+
+// goalRequiredHelp — PURE: what a builder reads when a task names no goal
+// (task 1004597). Two ways forward: name a product goal, or — when the work is
+// platform upkeep such as a Bongos upgrade — file it as kind infra with no goal.
+function goalRequiredHelp(body) {
+  const lines = ['Every task belongs to a goal, and this one did not name one.'];
+  if (body && body.kind === UPKEEP_KIND) {
+    lines.push(`Version ${body.version_id} is not being built right now, so it has no maintenance goal.`);
+    lines.push('Re-run with --version <the version being built> (see `bongos status`).');
+  } else {
+    lines.push('  - Product work: re-run with --goal <id> (`bongos status` lists the goals).');
+    lines.push('  - Platform upkeep (a Bongos upgrade or other maintenance): re-run with --kind infra and no --goal.');
+    lines.push("    It goes into this version's maintenance goal.");
+  }
+  return lines.join('\n');
+}
+
+async function cmdNew(args) {
+  const { body, errors } = buildTaskBody(args);
+  if (errors.length) { console.error('task new: ' + errors.join('; ') + '\n'); usage(); process.exit(2); }
+  const api = await cliClient();
+  // version_id is required by the API; default to the active (building) version so a
+  // new owner never has to know the id, but keep --version as the explicit override.
+  if (!body.version_id) {
+    body.version_id = await resolveDefaultVersion(api);
+    if (!body.version_id) {
+      console.error('task new: could not resolve an active version — pass --version <id> (see `npx bongos status`).');
+      process.exit(2);
+    }
+  }
+  const r = await api.tasks.postTasks({ body });
+  if (r.status === 403) {
+    console.error('Creating a task is Archon-gated (creating work shapes scope). Your rank is lower, so the server declined.');
+    console.error('To propose it instead, capture an idea for triage:');
+    console.error('  npx bongos exec scripts/bongos/capture.js "<your idea>"');
+    process.exit(1);
+  }
+  // task 1004597: a goal-less filing is refused unless it is platform upkeep.
+  // Say both ways forward in plain words instead of dumping the raw error.
+  if (r.status === 400 && errCode(r.data) === 'goal_id_required') {
+    console.error(goalRequiredHelp(body));
+    process.exit(1);
+  }
+  if (r.status !== 201 || !r.data?.task) {
+    console.error(`task new failed (${r.status}):`, r.data);
+    process.exit(1);
+  }
+  const task = r.data.task;
+  if (hasFlag('--json', args)) { console.log(JSON.stringify(task, null, 2)); return; }
+  const { API_BASE } = require('./cli-lib');
+  console.log(`✓ Created task #${task.id} [${task.status}] — ${task.title}`);
+  console.log(`  kind=${task.kind} · discipline=${task.discipline}${task.priority ? ` · P${task.priority}` : ''}${task.goal_id ? ` · goal ${task.goal_id}` : ''}`);
+  console.log(`  ${hallLink(API_BASE, task.id)}`);
+  if (r.data.goal_home === 'maintenance') console.log(`  Filed under ${body.version_id}'s maintenance goal, the standing home for platform upkeep.`);
+  if (task.status !== 'ready') console.log(`  (status '${task.status}' — pass --ready to make it claimable now, deps permitting)`);
+  console.log(`  next: npx bongos claim ${task.id}`);
+}
+
+async function cmdShow(args) {
+  const id = Number(args[0]);
+  if (!Number.isInteger(id) || id <= 0) { console.error('usage: bongos task show <id>'); process.exit(2); }
+  const api = await cliClient();
+  const r = await api.tasks.getTasksId({ id });
+  if (r.status === 404) { console.error(`task #${id} not found.`); process.exit(1); }
+  if (r.status !== 200 || !r.data?.task) { console.error(`task show failed (${r.status}):`, r.data); process.exit(1); }
+  const task = r.data.task;
+  if (hasFlag('--json', args)) { console.log(JSON.stringify(task, null, 2)); return; }
+  console.log(`#${task.id} [${task.status}] — ${task.title}`);
+  console.log(`kind=${task.kind} · discipline=${task.discipline}${task.priority ? ` · P${task.priority}` : ''}${task.goal_id ? ` · goal ${task.goal_id}` : ''}${task.version_id ? ` · ${task.version_id}` : ''}`);
+  if (task.description) console.log(`\n${task.description}`);
+}
+
+
+// ---- bongos task visual (task 1003109, goal 1000072) ------------------------
+//
+// A shipped task can carry a VISUAL alongside its value summary — a screenshot of
+// the surface that changed, a before/after, a diagram — so a reader who does not
+// read code can SEE what changed. `ship.js --visual` is the usual path; this is
+// the after-the-fact one: attach the picture you forgot, replace the wrong one,
+// or take it back off. Same server gate either way — the task's claim holder (or
+// an Archon). Always optional: no task needs one.
+async function cmdVisual(args) {
+  const id = Number(args[0]);
+  if (!Number.isInteger(id) || id <= 0) {
+    console.error('usage: bongos task visual <id> <image> [--alt "caption"]');
+    console.error('       bongos task visual <id> --remove');
+    process.exit(2);
+  }
+  const api = await cliClient();
+
+  // task 1004322: --slot names the visual (lifecycle_013). Validated here with the
+  // server's own rule, so a bad name costs a retyped command, not an upload.
+  const slot = arg('--slot', args) || null;
+  if (slot !== null && !taskVisuals.isSafeSlot(slot)) {
+    console.error(`--slot "${slot}" is not a slot name: lowercase words joined by dashes, such as ${taskVisuals.TWEAK_RENDER_SLOTS[0]}.`);
+    process.exit(2);
+  }
+  if (slot && hasFlag('--remove', args)) {
+    const r = await api.tasks.deleteTasksIdVisualsSlot({ id, slot });
+    if (r.status === 404) { console.error(`task #${id} not found.`); process.exit(1); }
+    if (!r.ok) { console.error(`visual remove failed (${r.status}):`, r.data); process.exit(1); }
+    console.log(`✓ Task #${id} no longer carries the "${slot}" visual.`);
+    return;
+  }
+
+  if (hasFlag('--remove', args)) {
+    const r = await api.tasks.deleteTasksIdVisual({ id });
+    if (r.status === 404) { console.error(`task #${id} not found.`); process.exit(1); }
+    if (!r.ok) { console.error(`visual remove failed (${r.status}):`, r.data); process.exit(1); }
+    console.log(`✓ Task #${id} no longer carries a visual.`);
+    return;
+  }
+
+  // The image is POSITIONAL — `visual <id> <image>`. Deliberately not "the first
+  // arg that isn't a flag": with `--alt "a caption" shot.png` that heuristic
+  // picks up the caption as the filename.
+  const file = args[1] && !args[1].startsWith('--') ? args[1] : null;
+  if (!file) {
+    console.error('usage: bongos task visual <id> <image> [--alt "caption"]');
+    process.exit(2);
+  }
+  // Reading + screening is the SERVER's own lib (shared with ship.js --visual),
+  // so a terminal refuses exactly what the upload route would refuse.
+  const visual = taskVisuals.readImageFile(file);
+  if (!visual.ok) {
+    console.error(`${file} — ${visual.message}`);
+    process.exit(2);
+  }
+
+  const alt = arg('--alt', args) || '';
+  const body = { image_b64: visual.buf.toString('base64'), content_type: visual.contentType, ...(alt ? { alt } : {}) };
+  const r = slot
+    ? await api.tasks.postTasksIdVisualsSlot({ id, slot, body })
+    : await api.tasks.postTasksIdVisual({ id, body });
+  if (r.status === 404) { console.error(`task #${id} not found.`); process.exit(1); }
+  if (r.status === 403) { console.error(`Only task #${id}'s claim holder (or an Archon) may attach its visual.`); process.exit(1); }
+  if (!r.ok) { console.error(`visual upload failed (${r.status}):`, r.data); process.exit(1); }
+  console.log(`✓ Task #${id} now carries ${slot ? `the "${slot}" visual` : 'a visual'} (${Math.round(visual.buf.length / 1024)} KB).`);
+  console.log('  It renders wherever this task\'s value summary does.');
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const sub = args[0];
+  if (!sub || sub === 'help' || sub === '--help' || sub === '-h') { usage(); process.exit(sub ? 0 : 2); }
+  await requireSession();
+  if (sub === 'new') return cmdNew(args.slice(1));
+  if (sub === 'show') return cmdShow(args.slice(1));
+  if (sub === 'visual') return cmdVisual(args.slice(1));
+  console.error(`task: unknown subcommand "${sub}"\n`); usage(); process.exit(2);
+}
+
+if (require.main === module) {
+  main().catch((err) => { console.error('fatal:', err); process.exit(1); });
+}
+
+module.exports = { buildTaskBody, goalRequiredHelp, VALID_KINDS, VALID_DISCIPLINES, csv, hallLink };

package/scripts/bongos/test-path-guard.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+// scripts/bongos/test-path-guard.js — a test must not build a filesystem path from
+// `URL.pathname` (task 1002889).
+//
+// THE BUG THIS EXISTS TO STOP. `new URL('..', import.meta.url).pathname` is a URL
+// path, not a filesystem path: percent-encoding survives (a space stays `%20`) and
+// on Windows it carries a leading slash before the drive letter. Handed to
+// require() or fs it resolves nowhere — four tests threw MODULE_NOT_FOUND at load
+// on the owner's checkout, whose path has a space in it.
+//
+// WHY A FITNESS CHECK AND NOT A TEST. CI checks out to a path with no space, so the
+// broken form passes there and the suite reads green while being unrunnable on a
+// Windows dev machine. CI can never catch the regression on its own; a static scan
+// at a different altitude can.
+//
+// THE FIX IT POINTS AT. `fileURLToPath(new URL('..', import.meta.url))` from
+// node:url (tests/fitness.mjs), or a plain relative require through
+// createRequire(import.meta.url) (tests/provisioning_teardown_intent.mjs).
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const NAME = 'a test builds its repo root with fileURLToPath, never URL.pathname (task 1002889)';
+
+// `import.meta.url).pathname` — the URL-path-as-filesystem-path defect, in both its
+// forms: new URL('..', import.meta.url).pathname and new URL(import.meta.url).pathname.
+const PATHNAME_ROOT = /import\.meta\.url\s*\)\s*\.pathname\b/;
+
+// Every tracked test file. Only tests use import.meta.url this way; source is CJS.
+function trackedTestFiles() {
+  try {
+    const out = execFileSync('git', ['ls-files', 'tests/*.mjs', 'tests/*.js', 'tests/**/*.mjs', 'tests/**/*.js'],
+      { cwd: REPO_ROOT, encoding: 'utf8' });
+    return [...new Set(out.split('\n').map((s) => s.trim()).filter(Boolean))];
+  } catch {
+    return [];
+  }
+}
+
+function scanTests(files, read) {
+  const violations = [];
+  let scanned = 0;
+  for (const rel of files) {
+    const src = read(rel);
+    if (src == null) continue;
+    scanned += 1;
+    const lines = src.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+      if (!PATHNAME_ROOT.test(lines[i])) continue;
+      violations.push(
+        `${rel}:${i + 1} builds a filesystem path from URL.pathname — a space becomes %20 and a Windows `
+        + 'drive gains a leading slash, so require()/fs throw MODULE_NOT_FOUND at load. Use '
+        + "fileURLToPath(new URL('..', import.meta.url)) from node:url, or a relative require via "
+        + 'createRequire(import.meta.url).',
+      );
+    }
+  }
+  return { violations, scanned };
+}
+
+function checkTestsUseFileUrlToPath({ files, read } = {}) {
+  const list = files || trackedTestFiles();
+  if (!list.length) {
+    return {
+      name: NAME, ok: false, hardFail: true,
+      violations: ['scan defect — enumerated 0 tracked test files; a broken enumeration, not a clean result.'],
+      warnings: [], note: 'static scan of tests/ for a URL.pathname used as a filesystem path.',
+    };
+  }
+  const reader = read || ((rel) => {
+    try { return fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8'); } catch { return null; }
+  });
+  const { violations, scanned } = scanTests(list, reader);
+  return {
+    name: NAME,
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} test file(s) scanned: none may hand \`import.meta.url).pathname\` to require()/fs — `
+      + 'it keeps %20 and a Windows drive slash, so the file is unrunnable on a checkout with a space '
+      + 'in its path while CI (no space) stays green. fileURLToPath() or a relative require is the form.',
+  };
+}
+
+function main() {
+  const r = checkTestsUseFileUrlToPath();
+  for (const v of r.violations) console.error(`✗ ${v}`);
+  console.log(`${r.hardFail ? 'FAIL' : 'PASS'}  ${r.note}`);
+  process.exit(r.hardFail ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = { checkTestsUseFileUrlToPath, scanTests, trackedTestFiles, PATHNAME_ROOT };