@bongos/core 1.21.175 → 1.21.177

package/scripts/bongos/artifact-format.js

@@ -0,0 +1,203 @@
+// scripts/bongos/artifact-format.js — the ONE packaging format Bongos ships code in:
+// a deterministic ustar+gzip tarball plus a compression-independent tree pin
+// (per-file sha256 + tree_sha256). Split out of package-core.js (task 1004271) so the
+// module store (ADR 0338 D1: "no second packaging format") builds and VERIFIES module
+// versions with the exact functions the core release uses — and so the always-on
+// server can read a tarball without loading package-core.js's release machinery.
+// Pure: no I/O beyond zlib/crypto, no git, no network.
+
+const zlib = require('node:zlib');
+const crypto = require('node:crypto');
+
+function sha256hex(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+// The PIN. A canonical, compression-independent digest of a packaged tree: one
+// "path\0mode\0filesha256\n" line per file, byte-sorted by path. A consumer
+// recomputes this from the unpacked tree to prove an install matches the pin.
+// `files` = [{ path, mode, sha256 }]. Modes are normalized so the pin is stable
+// regardless of the checkout's umask.
+function canonicalTreeHash(files) {
+  const lines = (files || [])
+    .map((f) => `${f.path}\u0000${normalizeMode(f.mode)}\u0000${f.sha256}`)
+    .sort();
+  return sha256hex(Buffer.from(lines.join('\n') + '\n', 'utf8'));
+}
+
+// Collapse ANY mode form — git's 100644/100755, our canonical 0000644/0000755, or a
+// raw filesystem octal string like "755" — to two canonical tar modes, keyed only on
+// the executable bit. IDEMPOTENT (normalizeMode(normalizeMode(x)) === normalizeMode(x))
+// AND exec-aware, so the tree pin reproduces byte-identically whether a consumer
+// recomputes it from the manifest's files[] (already-canonical modes) or from the
+// unpacked tree's stat() modes. Expects a STRING (git mode / canonical mode / octal).
+function normalizeMode(mode) {
+  const s = String(mode);
+  if (s === '100755' || s === '0000755' || s === '755') return '0000755';
+  const n = parseInt(s, 8);
+  if (Number.isFinite(n) && (n & 0o111)) return '0000755';
+  return '0000644';
+}
+
+// ---- a minimal, correct, DETERMINISTIC ustar+gzip writer (node-only, #686) ----
+// Deterministic (fixed mtime/uid/gid, normalized mode, sorted entries) so the same
+// source yields byte-identical bytes — a bonus over the tree_sha256 pin. Long paths
+// use the ustar name/prefix split, falling back to a GNU 'L' longname entry (read
+// by GNU tar, bsdtar/macOS, and node-tar) for the rare path that won't split.
+
+function octal(n, width) {
+  // width-1 octal digits, zero-padded, then a NUL — the classic numeric field.
+  return Buffer.from(n.toString(8).padStart(width - 1, '0').slice(-(width - 1)) + '\0', 'ascii');
+}
+
+function tarChecksum(block) {
+  let sum = 0;
+  for (let i = 0; i < 512; i++) sum += (i >= 148 && i < 156) ? 0x20 : block[i];
+  return sum;
+}
+
+// Build one 512-byte ustar header. `name`/`prefix` must already fit (<=100 / <=155).
+function ustarHeader({ name, prefix = '', mode, size, typeflag }) {
+  const h = Buffer.alloc(512, 0);
+  h.write(name, 0, 100, 'utf8');
+  octal(mode, 8).copy(h, 100);
+  octal(0, 8).copy(h, 108);   // uid
+  octal(0, 8).copy(h, 116);   // gid
+  octal(size, 12).copy(h, 124);
+  octal(0, 12).copy(h, 136);  // mtime = 0 (determinism)
+  h.write(typeflag, 156, 1, 'ascii');
+  h.write('ustar\0', 257, 6, 'ascii');
+  h.write('00', 263, 2, 'ascii');
+  if (prefix) h.write(prefix, 345, 155, 'utf8');
+  // checksum field: 6 octal digits + NUL + space, computed with the field = spaces.
+  const cksum = tarChecksum(h);
+  h.write(cksum.toString(8).padStart(6, '0').slice(-6) + '\0 ', 148, 8, 'ascii');
+  return h;
+}
+
+// Split a >100-byte path into { name<=100, prefix<=155 } at a '/' boundary, or
+// return null if no split fits (→ caller uses the GNU longname fallback).
+function splitUstarName(fullPath) {
+  const bytes = Buffer.byteLength(fullPath, 'utf8');
+  if (bytes <= 100) return { name: fullPath, prefix: '' };
+  // Find the LAST '/' such that the tail (after it) is <=100 and the head <=155.
+  for (let i = fullPath.length - 1; i > 0; i--) {
+    if (fullPath[i] !== '/') continue;
+    const prefix = fullPath.slice(0, i);
+    const name = fullPath.slice(i + 1);
+    if (Buffer.byteLength(name, 'utf8') <= 100 && Buffer.byteLength(prefix, 'utf8') <= 155) {
+      return { name, prefix };
+    }
+  }
+  return null;
+}
+
+function padTo512(buf) {
+  const rem = buf.length % 512;
+  return rem === 0 ? buf : Buffer.concat([buf, Buffer.alloc(512 - rem, 0)]);
+}
+
+// GNU longname pseudo-entry: a header (typeflag 'L', name '././@LongLink') whose
+// BODY is the full path (incl. trailing NUL), immediately followed by the real
+// file entry. Read by GNU tar, bsdtar/macOS, and node-tar.
+function gnuLongName(fullPath) {
+  const payload = Buffer.from(fullPath + '\0', 'utf8');
+  const hdr = ustarHeader({ name: '././@LongLink', mode: 0o644, size: payload.length, typeflag: 'L' });
+  return Buffer.concat([hdr, padTo512(payload)]);
+}
+
+// entries: [{ name, mode, buf }] — `name` includes the TAR_ROOT prefix. Returns a
+// gzip'd tar Buffer. Pure + deterministic given sorted entries.
+function buildTar(entries) {
+  const sorted = [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  const chunks = [];
+  for (const e of sorted) {
+    const mode = e.mode & 0o7777;
+    const split = splitUstarName(e.name);
+    if (split) {
+      chunks.push(ustarHeader({ name: split.name, prefix: split.prefix, mode, size: e.buf.length, typeflag: '0' }));
+    } else {
+      chunks.push(gnuLongName(e.name));
+      chunks.push(ustarHeader({ name: e.name.slice(0, 100), mode, size: e.buf.length, typeflag: '0' }));
+    }
+    chunks.push(padTo512(e.buf));
+  }
+  // two zero blocks terminate the archive
+  chunks.push(Buffer.alloc(1024, 0));
+  const tar = Buffer.concat(chunks);
+  return zlib.gzipSync(tar, { level: 9 });
+}
+
+
+
+// ---- the matching READER (task 1004271) -------------------------------------
+// Reads back exactly what buildTar writes — plain ustar file entries (name/prefix
+// split) and GNU 'L' longname entries — into [{ name, mode, buf }]. It is the store's
+// side of the format, so it is strict rather than permissive: any other entry type
+// (a directory, a symlink, a pax header), a size or count over the caps, a truncated
+// archive or a bad header checksum is a THROWN error, never a skipped entry. A server
+// that verifies uploads must not quietly accept a shape it did not check.
+//
+// Two entry points over one parser: readTar (sync — the CLI and tests) and
+// readTarAsync, which inflates on libuv's thread pool so a server verifying an upload
+// does not hold the event loop for the decompression. The parse itself is a single
+// linear pass over the inflated bytes.
+const DEFAULT_READ_LIMITS = { maxUnpackedBytes: 64 * 1024 * 1024, maxFiles: 5000 };
+const gunzipAsync = require('node:util').promisify(zlib.gunzip);
+
+const unreadable = (maxUnpackedBytes, e) =>
+  new Error(`not a readable gzip tarball within ${maxUnpackedBytes} bytes (${e.code || e.message})`);
+
+function readTar(tgz, { maxUnpackedBytes = DEFAULT_READ_LIMITS.maxUnpackedBytes, maxFiles = DEFAULT_READ_LIMITS.maxFiles } = {}) {
+  let tar;
+  try { tar = zlib.gunzipSync(tgz, { maxOutputLength: maxUnpackedBytes }); }
+  catch (e) { throw unreadable(maxUnpackedBytes, e); }
+  return parseTar(tar, { maxFiles });
+}
+
+async function readTarAsync(tgz, { maxUnpackedBytes = DEFAULT_READ_LIMITS.maxUnpackedBytes, maxFiles = DEFAULT_READ_LIMITS.maxFiles } = {}) {
+  let tar;
+  try { tar = await gunzipAsync(tgz, { maxOutputLength: maxUnpackedBytes }); }
+  catch (e) { throw unreadable(maxUnpackedBytes, e); }
+  return parseTar(tar, { maxFiles });
+}
+
+function parseTar(tar, { maxFiles }) {
+  const cstr = (b, from, len) => {
+    const s = b.subarray(from, from + len);
+    const z = s.indexOf(0);
+    return (z < 0 ? s : s.subarray(0, z)).toString('utf8');
+  };
+  const out = [];
+  let off = 0;
+  let longName = null;
+  while (true) {
+    if (off + 512 > tar.length) throw new Error('tarball is truncated (no end-of-archive marker)');
+    const h = tar.subarray(off, off + 512);
+    if (h.every((x) => x === 0)) break;
+    const stored = parseInt(cstr(h, 148, 8).trim(), 8);
+    if (stored !== tarChecksum(h)) throw new Error(`tar header checksum mismatch at byte ${off}`);
+    const size = parseInt(cstr(h, 124, 12).trim() || '0', 8);
+    if (!Number.isFinite(size) || size < 0) throw new Error(`bad entry size at byte ${off}`);
+    const type = String.fromCharCode(h[156] || 48);
+    const bodyStart = off + 512;
+    const bodyEnd = bodyStart + size;
+    if (bodyEnd > tar.length) throw new Error('tarball is truncated mid-entry');
+    const body = tar.subarray(bodyStart, bodyEnd);
+    off = bodyStart + size + ((512 - (size % 512)) % 512);
+    if (type === 'L') { longName = cstr(body, 0, body.length); continue; }
+    if (type !== '0' && type !== '\u0000') throw new Error(`unsupported tar entry type "${type}" — only regular files are allowed`);
+    const prefix = cstr(h, 345, 155);
+    const name = longName || (prefix ? `${prefix}/${cstr(h, 0, 100)}` : cstr(h, 0, 100));
+    longName = null;
+    out.push({ name, mode: parseInt(cstr(h, 100, 8).trim() || '0', 8), buf: Buffer.from(body) });
+    if (out.length > maxFiles) throw new Error(`tarball has more than ${maxFiles} files`);
+  }
+  return out;
+}
+
+module.exports = {
+  sha256hex, canonicalTreeHash, normalizeMode,
+  octal, tarChecksum, ustarHeader, splitUstarName, padTo512, gnuLongName, buildTar,
+  readTar, readTarAsync,
+};

package/scripts/bongos/ask.js

@@ -0,0 +1,231 @@
+#!/usr/bin/env node
+'use strict';
+//
+// scripts/bongos/ask.js — the rewrite helper an agent runs BEFORE it asks a person
+// anything (task 1004704, goal 1000111: "agents must ask like humans").
+//
+// WHY. The owner's ruling: an AI agent asks a person the way a person would —
+// short, decidable, no slop. The shape is the ask (modules/government/asks.js,
+// task 1004703): one question of at most twelve words, two or three tap answers
+// each with a one-line result, a pick and why, the seat it waits on, what
+// happens if nobody answers; the long text rides along as `detail`. The server
+// refuses anything else, and a blocker an AI session files by hand without one
+// is refused too (`ask_required`). This helper is the loop that turns prose into
+// a card: write the card, check it, read every fix the server names, rewrite,
+// check again — and only then file it, or print it.
+//
+//   node scripts/bongos/ask.js template            a blank card to fill in
+//   node scripts/bongos/ask.js check <file|->      the server's verdict; on a pass,
+//                                               the card as a person reads it
+//
+// `check` asks the server (POST /government/asks/check, the dry run: nothing is
+// stored). With no session, or a server that cannot answer, it checks with the
+// same rules locally and says so. The file holds the ask bare or as { ask }, so
+// the body you will POST to /blockers can be checked as it is.
+//
+// The printed card is also what an agent puts in CHAT for an ask that is not a
+// stored matter: the "please confirm" list at the end of a run, a review
+// request, a help request. Same shape everywhere a person reads it.
+//
+// For scripts that file templated blockers: `checkedAsk` and `postWithAsk`
+// below. A templated card is checked here before it is sent, and a filing whose
+// card is refused is re-sent without it — a script's blocker always files.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const asks = require(path.join(__dirname, '..', '..', 'modules', 'government', 'asks.js'));
+
+const TEMPLATE = Object.freeze({
+  question: 'One question, twelve words at most?',
+  options: [
+    { key: 'yes', label: 'Do it', result: 'One line: what happens if they pick this.' },
+    { key: 'no', label: 'Leave it', result: 'One line: what happens if they pick this.' },
+  ],
+  recommend: { key: 'yes', why: 'One line: why you would pick it.' },
+  waits_on: 'owner',
+  if_nobody_answers: 'One line: what happens if nobody answers.',
+  detail: 'Optional. The long text rides along here; it is never the ask.',
+});
+
+// The ask in a body: bare, or as { ask } (the shape POST /blockers takes).
+function askOf(body) {
+  return body && typeof body === 'object' && !Array.isArray(body) && body.ask !== undefined ? body.ask : body;
+}
+
+// A templated card, checked with the server's own rules. → the stored form, or
+// null when it breaks a rule (the caller files without it rather than not at all).
+function checkedAsk(ask) {
+  const r = asks.checkAsk(ask);
+  return r.ok ? r.ask : null;
+}
+
+// File a blocker with its card. `post(body)` → { ok, status, data } (the shape
+// cli-lib's apiCall and the generated client both answer). A card that breaks a
+// rule is never sent; a server that refuses the card or cannot check it gets the
+// same blocker again without it, so the filing never depends on the card.
+const CARD_REFUSALS = new Set(['ask_refused', 'asks_unavailable', 'validation_failed']);
+async function postWithAsk(post, body, ask) {
+  const card = ask ? checkedAsk(ask) : null;
+  if (!card) return post(body);
+  const r = await post({ ...body, ask: card });
+  const code = r && r.data && r.data.error && r.data.error.code;
+  if (r && !r.ok && (r.status === 400 || r.status === 503) && CARD_REFUSALS.has(code)) return post(body);
+  return r;
+}
+
+// The verdict as plain lines. ok → the card; refused → the refusal and each fix.
+function verdictLines({ ok, ask, message, errors, where }) {
+  const out = [];
+  if (ok) {
+    out.push(`✓ This ask has the shape${where === 'local' ? ' (checked here; the server could not be asked)' : ''}. As a person reads it:`);
+    out.push('');
+    out.push(asks.cardText(ask));
+    return out;
+  }
+  out.push(`✗ ${message || asks.refusalLine(errors)}`);
+  if (where === 'local') out.push('  (checked here; the server could not be asked)');
+  const list = Array.isArray(errors) ? errors : [];
+  if (list.length) {
+    out.push('');
+    out.push('Fix each, then check again:');
+    for (const e of list) out.push(`  - ${e.field}: ${e.message}`);
+  }
+  return out;
+}
+
+function readJson(file) {
+  const raw = file === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(file, 'utf8');
+  return JSON.parse(raw.replace(/^/, ''));
+}
+
+// The server's verdict, or null when it could not give one (no session, offline,
+// no government module, not allowed) — the caller then checks locally.
+async function serverVerdict(ask, { client } = {}) {
+  let api = client;
+  try {
+    if (!api) {
+      const lib = require('./cli-lib');
+      if (!lib.readSessionToken()) return null;
+      api = await lib.cliClient({ allowUnauthenticated: true });
+    }
+    const r = await api.request('POST', '/government/asks/check', { body: { ask } });
+    if (r && r.ok && r.data && r.data.ok) return { ok: true, ask: r.data.ask, where: 'server' };
+    const err = r && r.data && r.data.error;
+    if (r && r.status === 400 && err && err.code === 'ask_refused') {
+      return { ok: false, message: err.message, errors: (err.details && err.details.errors) || [], where: 'server' };
+    }
+    return null;
+  } catch (_) {
+    return null;
+  }
+}
+
+async function check(file, deps = {}) {
+  let body;
+  try { body = readJson(file); } catch (e) {
+    return { code: 2, lines: [`ask: could not read the card as JSON (${e.message}). Start from: node scripts/bongos/ask.js template`] };
+  }
+  const ask = askOf(body);
+  let v = deps.local ? null : await serverVerdict(ask, deps);
+  if (!v) {
+    const r = asks.checkAsk(ask);
+    v = { ok: r.ok, ask: r.ask, errors: r.errors, where: 'local' };
+  }
+  return { code: v.ok ? 0 : 1, lines: verdictLines(v) };
+}
+
+// ---------- the reword list (owner, 2026-10-23) ----------
+// A reader pressed "?" on a city card: the matter's words did not make sense.
+// `unclear` prints what waits for a rewrite (the flagged matters, or with
+// --legacy every open matter that waits on a person and has no stored card
+// yet), each with the words it has now; `put` stores the rewritten card
+// (PUT /government/asks/:matter), which closes the matter's flag.
+async function client(deps) {
+  if (deps && deps.client) return deps.client;
+  const lib = require('./cli-lib');
+  if (!lib.readSessionToken()) throw new Error('no Bongos session — run /builder-setup first');
+  return lib.cliClient();
+}
+function matterLines(m) {
+  const out = [`${m.id}  [${m.building}]${m.flag && m.flag.times > 1 ? `  flagged ${m.flag.times}x` : ''}`];
+  out.push(`  title:  ${String(m.title || '').trim()}`);
+  if (m.detail) out.push(`  detail: ${String(m.detail).replace(/\s+/g, ' ').trim().slice(0, 600)}`);
+  if (m.ask) out.push(`  card:   ${m.ask.question} (${(m.ask.options || []).map((o) => o.label).join(' / ')})`);
+  if (m.flag && m.flag.note) out.push(`  why unclear: ${m.flag.note}`);
+  if (Array.isArray(m.acts) && m.acts.length) out.push(`  acts:   ${m.acts.map((a) => a.key + (Array.isArray(a.options) && a.options.length ? '(' + a.options.map((o) => o.key).join('|') + ')' : '')).join(', ')}`);
+  return out;
+}
+async function unclear({ legacy = false, json = false } = {}, deps = {}) {
+  const api = await client(deps);
+  let list;
+  if (legacy) {
+    const r = await api.request('GET', '/government/docket');
+    if (!r || !r.ok) return { code: 1, lines: [`ask: the docket could not be read (${r && r.status}).`] };
+    list = ((r.data && r.data.matters) || []).filter((m) => m && m.state === 'needs' && !m.ask)
+      .map((m) => ({ id: m.id, building: m.building, source: m.source, title: m.title, detail: m.detail || null, ask: null, acts: m.acts || [], flag: m.unclear || null }));
+  } else {
+    const r = await api.request('GET', '/government/asks/unclear');
+    if (!r || !r.ok) return { code: 1, lines: [`ask: the reword list could not be read (${r && r.status}).`] };
+    list = (r.data && r.data.matters) || [];
+  }
+  if (json) return { code: 0, lines: [JSON.stringify(list, null, 2)] };
+  if (!list.length) return { code: 0, lines: [legacy ? 'ask: every open matter already carries a card.' : 'ask: nothing on the reword list.'] };
+  const lines = [`${list.length} ${legacy ? 'open matter(s) with no card yet' : 'matter(s) flagged as unclear'}:`, ''];
+  list.forEach((m) => { lines.push(...matterLines(m), ''); });
+  lines.push('Write each one a card (node scripts/bongos/ask.js template), check it, then: node scripts/bongos/ask.js put <matter-id> <file>');
+  return { code: 0, lines };
+}
+async function put(matterId, file, deps = {}) {
+  let body;
+  try { body = readJson(file); } catch (e) { return { code: 2, lines: [`ask: could not read the card as JSON (${e.message}).`] }; }
+  const local = asks.checkAsk(askOf(body));
+  if (!local.ok) return { code: 1, lines: verdictLines({ ok: false, ask: null, errors: local.errors, where: 'local' }) };
+  const api = await client(deps);
+  const r = await api.request('PUT', '/government/asks/' + encodeURIComponent(matterId), { body: { ask: askOf(body) } });
+  if (r && r.ok && r.data && r.data.ok) return { code: 0, lines: [`ask: saved the card on ${matterId}; its "?" flag is closed.`, '', ...verdictLines({ ok: true, ask: r.data.ask, where: 'server' })] };
+  const err = r && r.data && r.data.error;
+  return { code: 1, lines: [`ask: ${matterId} was not saved (${r && r.status}${err ? ' ' + err.code : ''}). ${err && err.message ? err.message : ''}`.trim()] };
+}
+
+const USAGE = [
+  'usage:',
+  '  node scripts/bongos/ask.js template          print a blank card to fill in',
+  '  node scripts/bongos/ask.js check <file|->    check a card; on a pass, print it as a person reads it',
+  '      --local                               check with the rules here, without the server',
+  '  node scripts/bongos/ask.js unclear           the reword list: matters a reader flagged with "?"',
+  '      --legacy                              instead: every open matter on a person with no card yet',
+  '      --json                                as JSON',
+  '  node scripts/bongos/ask.js put <matter> <file>  store a rewritten card on a matter (closes its flag)',
+].join('\n');
+
+async function main(argv = process.argv.slice(2)) {
+  const cmd = argv[0];
+  if (cmd === 'template') {
+    console.log(JSON.stringify(TEMPLATE, null, 2));
+    return 0;
+  }
+  if (cmd === 'check' && argv[1]) {
+    const r = await check(argv[1], { local: argv.includes('--local') });
+    console.log(r.lines.join('\n'));
+    return r.code;
+  }
+  if (cmd === 'unclear') {
+    const r = await unclear({ legacy: argv.includes('--legacy'), json: argv.includes('--json') });
+    console.log(r.lines.join('\n'));
+    return r.code;
+  }
+  if (cmd === 'put' && argv[1] && argv[2]) {
+    const r = await put(argv[1], argv[2]);
+    console.log(r.lines.join('\n'));
+    return r.code;
+  }
+  console.error(USAGE);
+  return 2;
+}
+
+if (require.main === module) {
+  main().then((code) => { process.exitCode = code; }, (e) => { console.error(`ask: ${e && e.message}`); process.exitCode = 1; });
+}
+
+module.exports = { TEMPLATE, askOf, checkedAsk, postWithAsk, verdictLines, serverVerdict, check, unclear, put, main };