@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/render-check.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/bongos/render-check.js — render the pages a branch changed and report text wider than its box and
+// overlapping siblings, naming the element and the page (task 1004203, ADR 0329).
+//
+// Why: nothing else in the pipeline renders a page. The grader reads the diff, so a title clipped by character
+// count that still ran past its card (task 1003480) and a second grid child landing on the first (task 1003078)
+// both shipped looking correct in code and were found only by opening a browser.
+//
+// A SIGNAL, never a gate (ADR 0329, decisions 3-4): /ship-check shows it as an advisory row; ship.js and the grader never
+// read it. The measurement is the kit's `text-fit` + `sibling-overlap` floors (modules/ui-design/kit/lib.js);
+// this file only picks the pages, runs the kit's renderer at 1280 + 390, and keeps those two floors.
+//
+//   node scripts/bongos/render-check.js                     the pages this branch changed against origin/main
+//   node scripts/bongos/render-check.js --base <ref>        ... against another base
+//   node scripts/bongos/render-check.js --files a,b         the pages these repo paths reach
+//
+// Exit 0 nothing found or nothing to render · 1 findings · 3 no system browser.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawn, spawnSync } = require('node:child_process');
+const { isUiSurfacePath } = require('../../modules/lifecycle/cascade');
+const kit = require('../../modules/ui-design/kit/lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const RENDER_JS = path.join(REPO_ROOT, 'modules', 'ui-design', 'kit', 'render.js');
+const HARNESS_JS = path.join(REPO_ROOT, 'scripts', 'hall-preview', 'server.js');
+const FIT_FLOORS = Object.freeze(['text-fit', 'sibling-overlap']);
+const SIZES = Object.freeze([1280, 390]);
+const MAX_STATES_FILES = 6; // a shared sheet reaches every page; past this the builder runs render.js by hand
+// The whole run fits inside ship-check's 15-minute cap on a slow step, so ship-check never has to kill it
+// (a killed parent cannot stop its harness and renderers). Files that would start past it are listed instead.
+const RUN_BUDGET_MS = 12 * 60 * 1000;
+const MIN_RENDER_MS = 60 * 1000;
+const HARNESS_BOOT_MS = 30 * 1000;
+const rel = (file) => path.relative(REPO_ROOT, file).split(path.sep).join('/');
+
+// statesFilesFor — the states files a list of changed repo paths reaches. A page, or a file named like one
+// (goal-map.js), reaches its own <page>.states.json; any other script, sheet or image reaches every page in
+// the same public dir whose HTML names it (text-fit.js → goal-map, goals). Own pages come first, so the
+// MAX_STATES_FILES cut never drops the page the builder changed for pages a shared sheet reaches.
+function statesFilesFor(paths, root = REPO_ROOT) {
+  const own = new Set(), reached = new Set();
+  for (const p of paths) {
+    if (!isUiSurfacePath(p)) continue;
+    const dir = p.slice(0, p.indexOf('/public/') + '/public'.length);
+    const file = p.slice(dir.length + 1);
+    const beside = path.join(root, dir, `${file.replace(/\.[^./]+$/, '')}.states.json`);
+    if (!file.includes('/') && fs.existsSync(beside)) { own.add(beside); continue; }
+    if (/\.html?$/i.test(file) || !fs.existsSync(path.join(root, dir))) continue;
+    const named = new RegExp(`(^|[/"'=\\s])${path.basename(file).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`);
+    for (const html of fs.readdirSync(path.join(root, dir)).filter((f) => f.endsWith('.html'))) {
+      const states = path.join(root, dir, html.replace(/\.html$/, '.states.json'));
+      if (fs.existsSync(states) && named.test(fs.readFileSync(path.join(root, dir, html), 'utf8'))) reached.add(states);
+    }
+  }
+  return [...[...own].sort(), ...[...reached].filter((f) => !own.has(f)).sort()];
+}
+
+// fitFindings — every element the two fit floors named in one render.js report.json, read from the
+// structured facts (auditFloors' problem line stops at five). One finding per element across all the
+// renders it appeared in, with its largest measure — a title past its card at 1280 and 390 is one finding.
+const MEASURE = / (\d+)px past its (?:box|card)$| (\d+)x(\d+)$/;
+function fitFindings(report) {
+  const byElement = new Map();
+  for (const [render, r] of Object.entries((report && report.renders) || {})) {
+    const facts = (r && r.facts) || {};
+    for (const [floor, items] of [['text-fit', facts.textFit], ['sibling-overlap', facts.overlaps]]) {
+      for (const item of items || []) {
+        const m = MEASURE.exec(item);
+        const key = `${floor}: ${m ? item.slice(0, m.index) : item}`;
+        const size = m ? (m[1] ? Number(m[1]) : Number(m[2]) * Number(m[3])) : 0;
+        if (!byElement.has(key)) byElement.set(key, { key, measure: '', size: -1, renders: [] });
+        const f = byElement.get(key);
+        f.renders.push(render);
+        if (size > f.size) { f.size = size; f.measure = m ? m[0].trim() : ''; }
+      }
+    }
+  }
+  return [...byElement.values()].map((f) => ({ page: report.page, problem: f.measure ? `${f.key} — ${f.measure}` : f.key, renders: f.renders }));
+}
+
+// Two pages of one name (hall-ui/index, public-landing/index) must never share a shots folder.
+function shotsDir(outRoot, file) {
+  return path.join(outRoot, rel(file).replace(/\.states\.json$/, '').replace(/[\\/]/g, '_'));
+}
+
+function changedFiles(base) {
+  const git = (...args) => spawnSync('git', args, { cwd: REPO_ROOT, encoding: 'utf8' });
+  const mergeBase = git('merge-base', base, 'HEAD').stdout.trim();
+  if (!mergeBase) return null;
+  const listed = `${git('diff', '--name-only', mergeBase).stdout}\n${git('ls-files', '--others', '--exclude-standard').stdout}`;
+  return [...new Set(listed.split(/\r?\n/).filter(Boolean))];
+}
+
+// Kill a child and everything it started (render.js starts two stubs and a browser).
+const DETACH = process.platform !== 'win32';
+function killTree(child) {
+  if (!child || child.exitCode !== null || child.signalCode !== null) return;
+  try {
+    if (process.platform === 'win32') spawnSync('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore' });
+    else process.kill(-child.pid, 'SIGKILL');
+  } catch { /* already gone */ }
+}
+
+// The hall's states files are written against the hall-preview harness (their notes say so): its fixtures
+// carry the populated pages, where the kit's own stub serves the hall its signed-out, empty reads. Its
+// output is read for the whole run, since a pipe left unread fills and stalls it mid-render.
+async function startHarness({ script = HARNESS_JS, bootMs = HARNESS_BOOT_MS } = {}) {
+  const port = await kit.freePort();
+  const proc = spawn(process.execPath, [script, '--port', String(port), '--fixture-me'], { cwd: REPO_ROOT, stdio: ['ignore', 'pipe', 'pipe'], detached: DETACH });
+  const stop = () => killTree(proc);
+  await new Promise((resolve, reject) => {
+    let said = '', ready = false;
+    const fail = (why) => { clearTimeout(timer); stop(); reject(new Error(`${why}: ${said.trim()}`)); };
+    const timer = setTimeout(() => fail(`the hall-preview harness did not start within ${bootMs / 1000}s`), bootMs);
+    const hear = (d) => {
+      if (ready) return;
+      said += d;
+      if (/hall-preview: http/.test(said)) { ready = true; clearTimeout(timer); resolve(); }
+    };
+    proc.stdout.on('data', hear);
+    proc.stderr.on('data', hear);
+    proc.on('exit', (code) => { if (!ready) fail(`the hall-preview harness exited ${code}`); });
+  });
+  return { base: `http://localhost:${port}`, pid: proc.pid, stop };
+}
+
+// Run a node script without blocking the event loop (the harness's pipes keep draining meanwhile);
+// past timeoutMs the script and everything it started are killed.
+function runNode(args, timeoutMs) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, args, { cwd: REPO_ROOT, stdio: ['ignore', 'ignore', 'pipe'], detached: DETACH });
+    let stderr = '';
+    child.stderr.on('data', (d) => { if (stderr.length < 4000) stderr += d; });
+    const timer = setTimeout(() => killTree(child), timeoutMs);
+    child.on('error', (e) => { clearTimeout(timer); resolve({ status: null, signal: null, stderr: e.message }); });
+    child.on('close', (status, signal) => { clearTimeout(timer); resolve({ status, signal, stderr }); });
+  });
+}
+
+// One states file through the kit's renderer: { findings, note?, noBrowser? }. ONE colour mode (the file's
+// first): the fit floors measure geometry, and the pack's two font stacks are the same in both modes. No
+// reduced-motion pass either — only the fit floors are read. render.js still runs everything when asked.
+async function renderStatesFile(file, { outRoot, harness, timeoutMs }) {
+  const json = kit.readJson(file);
+  const out = shotsDir(outRoot, file);
+  const mode = (json.modes || kit.MODES)[0];
+  const args = [RENDER_JS, '--states', file, '--sizes', SIZES.join(','), '--modes', mode, '--no-reduced-motion', '--out', out];
+  if (json.surface === 'hall-ui' && harness) args.push('--base-in', harness.base, '--base-out', harness.base);
+  const r = await runNode(args, timeoutMs);
+  if (r.status === kit.EXIT.NO_BROWSER) return { findings: [], noBrowser: true, note: String(r.stderr || '').trim().split('\n')[0] };
+  const reportFile = path.join(out, 'report.json');
+  if (r.status === kit.EXIT.USAGE || !fs.existsSync(reportFile)) {
+    const why = String(r.stderr || `exit ${r.status}${r.signal ? ` (${r.signal})` : ''}`).trim().split('\n').slice(0, 2).join(' ');
+    return { findings: [], note: `${rel(file)}: the renderer produced no report — ${why}` };
+  }
+  return { findings: fitFindings(kit.readJson(reportFile)), out };
+}
+
+async function main() {
+  const started = Date.now();
+  const args = process.argv.slice(2);
+  const explicit = kit.listArg(args, '--files', null);
+  const paths = explicit || changedFiles(kit.argOf(args, '--base', 'origin/main'));
+  if (!paths) { console.log('render-check: no merge base with origin/main — nothing to compare against, nothing rendered'); return 0; }
+  const all = statesFilesFor(paths);
+  const uiCount = paths.filter(isUiSurfacePath).length;
+  if (!all.length) {
+    console.log(uiCount
+      ? `render-check: ${uiCount} rendered-surface file(s) changed, but no <page>.states.json reaches them — nothing to measure (docs/recipes/ui-look-before-you-ship.md)`
+      : 'render-check: no rendered surface changed — nothing to render');
+    return 0;
+  }
+  const outRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'render-check-'));
+  console.log(`render-check — text past its box and overlapping siblings at ${SIZES.join(' + ')} (a signal, never a gate)`);
+  let harness = null;
+  const findings = [], notes = [], unrendered = all.slice(MAX_STATES_FILES).map((f) => [f, `past ${MAX_STATES_FILES}`]);
+  try {
+    const files = all.slice(0, MAX_STATES_FILES);
+    if (files.some((f) => kit.readJson(f).surface === 'hall-ui')) harness = await startHarness();
+    for (const [i, file] of files.entries()) {
+      const left = RUN_BUDGET_MS - (Date.now() - started);
+      if (left < MIN_RENDER_MS) { unrendered.unshift(...files.slice(i).map((f) => [f, 'out of time'])); break; }
+      const res = await renderStatesFile(file, { outRoot, harness, timeoutMs: left });
+      if (res.noBrowser) { console.log(`render-check: no system browser, nothing rendered — ${res.note}`); return kit.EXIT.NO_BROWSER; }
+      if (res.note) notes.push(res.note);
+      findings.push(...res.findings.map((x) => ({ ...x, shots: res.out })));
+      console.log(`  ${rel(file)}: ${res.findings.length ? `${res.findings.length} finding(s)` : res.note ? 'no report' : 'clean'}${res.out ? `  (shots: ${res.out})` : ''}`);
+    }
+  } finally {
+    if (harness) harness.stop();
+  }
+  for (const [f, why] of unrendered) console.log(`  not rendered (${why}): node modules/ui-design/kit/render.js --states ${rel(f)} --sizes 1280,390`);
+  for (const n of notes) console.log(`✗ ${n}`);
+  for (const f of findings) console.log(`✗ ${f.page} ${f.problem}  [${f.renders.join(', ')}]  shots: ${f.shots}`);
+  const unmeasured = notes.length ? `; ${notes.length} states file(s) not measured` : '';
+  console.log(findings.length || notes.length ? `${findings.length} finding(s)${unmeasured} — look at the shots, then fix the element or say in the ship notes why it is right` : 'nothing past its box, no overlapping siblings');
+  return findings.length || notes.length ? 1 : 0;
+}
+
+module.exports = { FIT_FLOORS, SIZES, statesFilesFor, fitFindings, shotsDir, startHarness };
+if (require.main === module) {
+  main().then((code) => { process.exitCode = code; }, (e) => { console.error(`render-check: ${e.stack || e.message}`); process.exitCode = 1; });
+}

package/scripts/bongos/render-ideas.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+// Renders generative-ideas.md from the GDS idea_inbox table.
+//
+// Reads via GET /api/bongos/inbox (authenticated). Writes a generated markdown
+// view to the repo's top-level generative-ideas.md. The file is overwritten
+// on every run — manual edits will not survive. Capture via /builder-capture
+// or `node scripts/bongos/capture.js`; triage via /builder-triage or the API.
+//
+// Note (2026-05-10): the current GET /api/bongos/inbox endpoint returns open
+// ideas only (see src/bongos/inbox.js listOpenIdeas). The "Recently Promoted",
+// "Recently Discarded", and "Merged" sections will be empty until the API
+// is extended to expose those statuses. The script is forward-compatible:
+// when /inbox starts returning non-open rows, those sections populate
+// automatically.
+//
+// Usage:
+//   node scripts/bongos/render-ideas.js            # writes generative-ideas.md
+//   node scripts/bongos/render-ideas.js --dry-run  # prints to stdout instead
+
+const path = require('node:path');
+const fsp = require('node:fs/promises');
+const { cliClient, requireSession } = require('./cli-lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const OUT_PATH = path.join(REPO_ROOT, 'generative-ideas.md');
+const RECENT_DAYS = 30;
+
+const HEADER = `<!-- GENERATED FILE — Edit via /builder-capture or /builder-triage. Manual edits will be overwritten. -->
+
+# Generative ideas
+
+> **This file is a read-only view of the GDS \`idea_inbox\` table.** It is regenerated by \`scripts/bongos/render-ideas.js\`. Do not edit by hand.
+>
+> **Capture an idea:** \`node scripts/bongos/capture.js "short title"\` (or the \`/builder-capture\` slash command).
+>
+> **Triage open ideas:** \`/idea-triage\` (or \`PATCH /api/bongos/inbox/<id>\` with \`{ status: 'promoted' | 'discarded' | 'merged', promoted_to_task_id: N }\`).
+`;
+
+function fmtTimestamp(iso) {
+  if (!iso) return '—';
+  try {
+    return new Date(iso).toISOString().replace('T', ' ').slice(0, 16) + ' UTC';
+  } catch (_) {
+    return String(iso);
+  }
+}
+
+function daysAgo(iso) {
+  if (!iso) return Infinity;
+  const ms = Date.now() - new Date(iso).getTime();
+  return ms / (1000 * 60 * 60 * 24);
+}
+
+// The grade, in words, for a triage surface (task 1002924 / BV1.R148). An idea
+// with no ideas_grades row reads as 'quick' — the R140 absence-is-quick design —
+// so a missing grade is a real answer here, not a gap to hide.
+function gradeLabel(idea) {
+  const g = idea.grade || 'quick';
+  if (g === 'full') {
+    const s = idea.completeness_score;
+    return Number.isInteger(s) ? `FULL ${s}/100` : 'FULL (unscored)';
+  }
+  if (g === 'spark') return 'SPARK — awaiting development';
+  return 'quick';
+}
+
+function renderIdea(idea) {
+  const lines = [];
+  const titleSuffix = idea.kind ? ` _(${idea.kind})_` : '';
+  lines.push(`### #${idea.id} — ${idea.title}${titleSuffix}`);
+  lines.push('');
+  const meta = [];
+  // FIRST in the meta run, deliberately: the grade decides what kind of verdict
+  // this idea even needs (a Full Idea gets a recommended shape, R149; a quick one
+  // promotes straight to a task), so it is the first thing a triager should read.
+  meta.push(`**${gradeLabel(idea)}**`);
+  meta.push(`captured ${fmtTimestamp(idea.captured_at)}`);
+  if (idea.reviewed_at) meta.push(`reviewed ${fmtTimestamp(idea.reviewed_at)}`);
+  if (idea.suggested_version) meta.push(`suggested → ${idea.suggested_version}`);
+  if (idea.suggested_priority != null) meta.push(`P${idea.suggested_priority}`);
+  if (idea.promoted_to_task_id != null) meta.push(`→ task #${idea.promoted_to_task_id}`);
+  lines.push(`_${meta.join(' · ')}_`);
+  lines.push('');
+  if (idea.body_md && idea.body_md.trim()) {
+    lines.push(idea.body_md.trim());
+    lines.push('');
+  }
+  return lines.join('\n');
+}
+
+function renderSection(heading, ideas, emptyMsg) {
+  const out = [`## ${heading}`, ''];
+  if (!ideas.length) {
+    out.push(`_${emptyMsg}_`);
+    out.push('');
+    return out.join('\n');
+  }
+  for (const idea of ideas) {
+    out.push(renderIdea(idea));
+  }
+  return out.join('\n');
+}
+
+async function fetchAllIdeas() {
+  // GET /api/bongos/inbox currently returns open ideas only. We request the max
+  // limit so this works as the inbox grows. When the API is extended to
+  // return other statuses, this script will pick them up automatically.
+  const api = await cliClient();
+  const { ok, status, data } = await api.inbox.getInbox({ query: { limit: 500 } });
+  if (!ok) {
+    throw new Error(`GET /api/bongos/inbox failed: HTTP ${status} ${JSON.stringify(data)}`);
+  }
+  return data.ideas || [];
+}
+
+// Full ideas rank by how completely they were answered; everything else by
+// recency. Kept as one comparator per bucket rather than one clever composite:
+// mixing a 0-100 score and a timestamp into a single ordering is how a quick idea
+// ends up sorted by a number it does not have.
+const byCompletenessDesc = (a, b) => {
+  const sa = Number.isInteger(a.completeness_score) ? a.completeness_score : -1;
+  const sb = Number.isInteger(b.completeness_score) ? b.completeness_score : -1;
+  if (sa !== sb) return sb - sa;
+  return new Date(b.captured_at).getTime() - new Date(a.captured_at).getTime();
+};
+
+function partition(ideas) {
+  const open = [];
+  const promoted = [];
+  const discarded = [];
+  const merged = [];
+  for (const idea of ideas) {
+    if (idea.status === 'open') {
+      open.push(idea);
+      continue;
+    }
+    // Recency uses reviewed_at when present, otherwise captured_at.
+    const ref = idea.reviewed_at || idea.captured_at;
+    if (daysAgo(ref) > RECENT_DAYS) continue;
+    if (idea.status === 'promoted') promoted.push(idea);
+    else if (idea.status === 'discarded') discarded.push(idea);
+    else if (idea.status === 'merged') merged.push(idea);
+  }
+  // Newest first within each bucket.
+  const byCapturedDesc = (a, b) =>
+    new Date(b.captured_at).getTime() - new Date(a.captured_at).getTime();
+  promoted.sort(byCapturedDesc);
+  discarded.sort(byCapturedDesc);
+  merged.sort(byCapturedDesc);
+
+  // TWO OPEN SECTIONS, NOT ONE SORTED LIST (task 1002924 / R148). The done-when
+  // wants full ideas ordered by completeness AND quick ideas and sparks still
+  // visible rather than buried under scored ideas — and a single list sorted by
+  // score cannot do both: every unscored idea lands after every scored one, which
+  // for a long inbox means nobody ever reads them. Two labelled runs give each
+  // kind its own ordering and its own top.
+  const openFull = open.filter((i) => (i.grade || 'quick') === 'full').sort(byCompletenessDesc);
+  const openRest = open.filter((i) => (i.grade || 'quick') !== 'full').sort(byCapturedDesc);
+  return { open, openFull, openRest, promoted, discarded, merged };
+}
+
+function render(ideas) {
+  const { open, openFull, openRest, promoted, discarded, merged } = partition(ideas);
+  const renderedAt = new Date().toISOString().replace('T', ' ').slice(0, 16) + ' UTC';
+
+  const parts = [
+    HEADER,
+    `_Last rendered: ${renderedAt} · ${open.length} open (${openFull.length} full, ${openRest.length} quick/spark) · ${promoted.length} promoted (last ${RECENT_DAYS}d) · ${discarded.length} discarded (last ${RECENT_DAYS}d) · ${merged.length} merged (last ${RECENT_DAYS}d)_`,
+    '',
+    '---',
+    '',
+    renderSection(
+      'Open — Full Ideas (best-formed first)',
+      openFull,
+      'No Full Ideas open. One is written at /builders/ideas, or by developing a spark.'
+    ),
+    renderSection(
+      'Open — quick ideas and sparks (newest first)',
+      openRest,
+      'No quick ideas open. Inbox zero — capture one with node scripts/bongos/capture.js.'
+    ),
+    renderSection(
+      `Recently Promoted (last ${RECENT_DAYS} days)`,
+      promoted,
+      'Nothing promoted in the window.'
+    ),
+    renderSection(
+      `Recently Discarded (last ${RECENT_DAYS} days)`,
+      discarded,
+      'Nothing discarded in the window.'
+    ),
+    renderSection(
+      `Merged (last ${RECENT_DAYS} days)`,
+      merged,
+      'Nothing merged in the window.'
+    ),
+  ];
+
+  return parts.join('\n') + '\n';
+}
+
+async function main() {
+  await requireSession();
+  const dryRun = process.argv.includes('--dry-run');
+  const ideas = await fetchAllIdeas();
+  const md = render(ideas);
+  if (dryRun) {
+    process.stdout.write(md);
+    return;
+  }
+  await fsp.writeFile(OUT_PATH, md, 'utf8');
+  console.log(`Wrote ${OUT_PATH} (${ideas.length} idea${ideas.length === 1 ? '' : 's'} fetched)`);
+}
+
+// Exported so the R148 ordering + grade label are unit-testable without a
+// session or the network — they are the whole substance of this file now, and the
+// pure functions are the right seam. Guarded main(), the capture.js pattern:
+// without it a require() for the test would run the renderer.
+module.exports = { gradeLabel, partition };
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err.stack || err.message || err);
+    process.exit(1);
+  });
+}

package/scripts/bongos/render-payload.js

@@ -0,0 +1,85 @@
+// scripts/bongos/render-payload.js — WHAT the Render standup leg creates, kept apart from
+// HOW it creates it (scripts/bongos/provision-render.js) (task 1004183; retargeted by
+// task 1004350).
+//
+// Pure functions, no I/O. What goes to the owner's Render account is their APP, not the
+// Bongos hall: we host every project's hall, and the app deploys where its owner
+// chooses (ADR 0345 D1, D3). So the service is built from the project's own repository
+// and started the way that repository says — the owner's runtime and commands, or the
+// repository's own Dockerfile — never the Bongos core.
+//
+// A database is optional (some apps need none). When there is one, its internal
+// connection string is handed to the app as DATABASE_URL, the one name every mainstream
+// framework reads. That is the only env var the platform sets: every other variable is
+// the owner's to set on Render, and Bongos keeps their NAMES only (task 1004062's
+// manifest) — never a value.
+//
+// The plans are per-project settings (ADR 0327 §5), never constants. The defaults are
+// what the Render pilot (task 1004142) found enough at idle: a `starter` web service and
+// a paid `basic_256mb` Postgres, because Render's free Postgres has no backups.
+
+'use strict';
+
+// The vocabulary lives with the web tier's validation, so the two can never disagree.
+const { WEB_PLANS, DB_PLANS, REGIONS, RUNTIMES, BUILD_DEFAULTS } = require('../../modules/provisioning/render-standup.js');
+const DEFAULTS = Object.freeze({ webPlan: 'starter', dbPlan: 'basic_256mb', region: 'virginia' });
+
+// A Render resource name from the project's slug. Render allows letters, digits and
+// dashes; the slug already is that, this only makes sure.
+function resourceName(inst, suffix) {
+  const base = String(inst.slug || `project-${inst.id}`).toLowerCase().replace(/[^a-z0-9-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 50);
+  return suffix ? `${base}-${suffix}` : base;
+}
+
+// The plan and region a project asked for, with the defaults filled in. A value outside
+// the vocabulary is refused rather than passed through for Render to reject.
+function plansFor(appHost) {
+  const h = appHost || {};
+  const out = {
+    webPlan: h.webPlan || DEFAULTS.webPlan,
+    dbPlan: h.dbPlan || DEFAULTS.dbPlan,
+    region: h.region || DEFAULTS.region,
+  };
+  if (!WEB_PLANS.includes(out.webPlan)) throw new Error(`unknown Render web plan '${out.webPlan}'`);
+  if (!DB_PLANS.includes(out.dbPlan)) throw new Error(`unknown Render database plan '${out.dbPlan}'`);
+  if (!REGIONS.includes(out.region)) throw new Error(`unknown Render region '${out.region}'`);
+  return out;
+}
+
+// How the app is built and started, as the owner said. `docker` builds the repository's
+// own Dockerfile and needs no commands; every other runtime needs a start command AND a
+// build command — Render refuses a native service without one (task 1004464), so a row
+// saved with none (including every row from before that fix) gets the runtime's default.
+function buildFor(appHost) {
+  const h = appHost || {};
+  if (!RUNTIMES.includes(h.runtime)) throw new Error(`unknown Render runtime '${h.runtime || 'none'}'`);
+  if (h.runtime === 'docker') return { runtime: 'docker' };
+  if (!h.startCommand) throw new Error('the app needs a start command');
+  return { runtime: h.runtime, buildCommand: h.buildCommand || BUILD_DEFAULTS[h.runtime], startCommand: h.startCommand };
+}
+
+// POST /postgres. `plan` is never 'free' — see the header.
+function renderPostgresPayload(inst, { ownerId, dbPlan, region }) {
+  return { name: resourceName(inst, 'db'), ownerId, plan: dbPlan, region, version: '16' };
+}
+
+// POST /services, for the owner's app from their repository. `dbUrl` is the database's
+// internal connection string, or null when the app has no database. It is a VALUE sent
+// to Render and held there — the platform keeps none.
+function renderServicePayload(inst, { ownerId, repoUrl, branch, webPlan, region, build, dbUrl }) {
+  const envSpecificDetails = build.runtime === 'docker'
+    ? {}
+    : { buildCommand: build.buildCommand, startCommand: build.startCommand };
+  return {
+    type: 'web_service',
+    name: resourceName(inst),
+    ownerId,
+    repo: repoUrl,
+    branch: branch || 'main',
+    autoDeploy: 'yes',
+    serviceDetails: { runtime: build.runtime, plan: webPlan, region, envSpecificDetails },
+    envVars: dbUrl ? [{ key: 'DATABASE_URL', value: dbUrl }] : [],
+  };
+}
+
+module.exports = { DEFAULTS, resourceName, plansFor, buildFor, renderPostgresPayload, renderServicePayload };