@bongos/core 1.17.0

package/modules/hall-ui/public/new-project-wizard.js

@@ -0,0 +1,186 @@
+// new-project-wizard.js — the "Start a project" hall widget (provisioning module,
+// ADR 0111 / BONGOS-V1 goal 35, task 1983).
+//
+// The most ACCESSIBLE form of the canonical onboarding runbook (the /new-project skill,
+// task 1981; the `bongos onboard` CLI, task 1982) — a point-and-click wizard for a
+// non-technical owner. It files the provisioning REQUEST (the web tier only ENQUEUES —
+// POST /provisioning/instances; the control-plane runner does the real standup, trust
+// boundary intact, ADR 0111 §2) as a STANDALONE instance (ADR 0108), then renders the
+// four irreducibly-human steps UI-first (create the repo, the OAuth app + secret, first
+// sign-in) with the exact pinned values, and points at the Instances panel for status.
+//
+// GATED on the provisioning module (module:'provisioning'), like instances-panel.js —
+// contributeHallWidget drops it entirely when the module is off (ADR 0062 §4).
+(function () {
+  'use strict';
+  if (!window.OTB || typeof window.OTB.contributeHallWidget !== 'function') return;
+  const { escapeHtml } = window.OTB;
+  const API = '/api/bongos';
+
+  // Mirror provisioning.isValidSlug (DNS/db-safe): 2–40 of [a-z0-9-], starts+ends
+  // alnum, no double dash. Client-side pre-check; the server re-validates.
+  function validSlug(s) {
+    const v = String(s || '');
+    return v.length >= 2 && v.length <= 40 && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(v) && !v.includes('--');
+  }
+
+  // The pinned GitHub OAuth-app values for a domain (auth.js WEB_REDIRECT_ORIGIN —
+  // callback is the apex /api/gds/auth/web/callback). Mirrors onboard.oauthAppInstructions.
+  function oauthAppValues(domain) {
+    const origin = `https://${domain}`;
+    return { homepageUrl: origin, callbackUrl: `${origin}/api/gds/auth/web/callback` };
+  }
+
+  let host = null;
+
+  async function postJSON(path, body) {
+    const res = await fetch(path, {
+      method: 'POST', credentials: 'same-origin',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    if (res.status === 401) { window.location.assign(`${API}/auth/web/start`); throw new Error('redirecting to auth'); }
+    const data = await res.json().catch(() => ({}));
+    if (!res.ok) { const e = new Error((data.error && (data.error.message || data.error.code)) || `HTTP ${res.status}`); e.data = data; throw e; }
+    return data;
+  }
+
+  // File a GitHub-App-Manifest onboarding link for the just-created instance (task 2080,
+  // ADR 0133) and NAVIGATE the browser to GitHub's pre-filled "create App" screen. The
+  // manifest rides a hidden form field; GitHub echoes our one-time `state`. After the
+  // owner approves, GitHub redirects to the mothership callback and the control-plane
+  // runner places the creds automatically — no secret is ever pasted. `account` is
+  // 'personal' | 'org'.
+  async function launchGithubApp(instanceId, account) {
+    const data = await postJSON(`${API}/provisioning/instances/${instanceId}/github-app`, account ? { account } : {});
+    const form = document.createElement('form');
+    form.method = 'POST';
+    form.action = data.post_url; // https://github.com/…/settings/apps/new?state=<one-time>
+    const input = document.createElement('input');
+    input.type = 'hidden';
+    input.name = 'manifest';
+    input.value = JSON.stringify(data.manifest);
+    form.appendChild(input);
+    document.body.appendChild(form);
+    form.submit(); // navigates away to GitHub
+  }
+
+  // After the request is filed, render the human-only next steps + a pointer to the
+  // Instances panel for status. The FIRST step branches on greenfield vs adopt (ADR
+  // 0121 §Decision 1 / task 2046). GitHub sign-in is now ONE CLICK via the App Manifest
+  // flow (task 2080) — the manual OAuth-app path is kept as a collapsible fallback.
+  function renderNextSteps(instanceId, slug, domain, mode) {
+    const adopt = mode === 'adopt';
+    const oa = domain ? oauthAppValues(domain) : null;
+    const dnsNote = domain ? '' : '<li>Add a domain you own, then re-run to wire the address (a domain is needed before sign-in works).</li>';
+    const repoStep = adopt
+      ? `<li><strong>Layer onto your existing repo</strong> — in your repo run <code>bongos init --adopt</code>. It shows a conflict pre-flight (migrations, CI, protected paths) and writes <em>nothing</em> until you accept; it never overwrites your files, and it imports your existing backlog (GitHub issues / a TODO/ROADMAP file). Commit + push.</li>`
+      : '<li><strong>Create the empty GitHub repo</strong> — github.com → New repository, leave it empty.</li>';
+    // The one-click GitHub sign-in step + a collapsible manual fallback (only when a
+    // domain is set — the App needs a real callback host).
+    const signInStep = oa ? `<li><strong>Set up GitHub sign-in — one click</strong>. We’ll open GitHub with a pre-filled app; approve it, and we place the credentials on your instance automatically (no secret to copy).
+        <div class="np-signin-actions">
+          <button id="np-github-app" type="button" class="np-create-btn" data-instance="${escapeHtml(String(instanceId))}">Set up GitHub sign-in</button>
+          <span id="np-github-app-msg" class="ledger__note"></span>
+        </div>
+        <details class="np-manual"><summary class="ledger__note">Prefer to do it by hand?</summary>
+          <ol class="np-steps">
+            <li><strong>Create the GitHub OAuth app</strong> — GitHub → <em>your account's</em> Settings → Developer settings → OAuth Apps → New OAuth App.
+              <div class="np-kv"><span>Homepage URL</span><code>${escapeHtml(oa.homepageUrl)}</code></div>
+              <div class="np-kv"><span>Authorization callback URL</span><code>${escapeHtml(oa.callbackUrl)}</code></div>
+            </li>
+            <li><strong>Place the secret — verified</strong> (never hand-edit the env file): on the control plane run
+              <code>bongos … oauth-secret place ${escapeHtml(slug)} --client-id &lt;id&gt; --client-secret &lt;secret&gt; --apply</code>.</li>
+          </ol>
+        </details>
+      </li>` : '';
+    return `<div class="np-done">
+      <p class="scroll__lede">✓ Provisioning requested for <strong>${escapeHtml(slug)}</strong> (standalone${adopt ? ', adopting your existing repo' : ''}). The control plane stands it up — watch its status in <strong>Instances</strong> below.</p>
+      <h3 class="scroll__h" style="font-size:1rem">Your steps (the parts only you can do):</h3>
+      <ol class="np-steps">
+        ${repoStep}
+        ${dnsNote}
+        ${signInStep}
+        ${oa ? `<li><strong>First sign-in</strong> — once the instance is live, open <code>${escapeHtml(oa.homepageUrl)}</code> and sign in with GitHub; that makes you the owner (Archon).</li>
+        <li><strong>Verify</strong> — <code>${escapeHtml(oa.homepageUrl)}/healthz</code> should report <code>auth_configured: true</code>.</li>` : ''}
+      </ol>
+      <p class="ledger__note">This is the same sequence the <code>/new-project</code> assistant and <code>bongos onboard</code> use.</p>
+    </div>`;
+  }
+
+  async function submit() {
+    const q = (id) => host.querySelector(id);
+    const productName = q('#np-name').value.trim();
+    const owner = q('#np-owner').value.trim();
+    const repo = q('#np-repo').value.trim();
+    const slug = q('#np-slug').value.trim().toLowerCase();
+    const domain = q('#np-domain').value.trim();
+    const mode = q('#np-mode') ? q('#np-mode').value : 'greenfield'; // greenfield | adopt (ADR 0121)
+    const err = q('#np-error');
+    err.textContent = '';
+
+    if (!productName) { err.textContent = 'Give the project a name.'; return; }
+    if (!owner || !repo) { err.textContent = 'Give the GitHub repo (owner and name).'; return; }
+    if (!validSlug(slug)) { err.textContent = 'Slug must be 2–40 lowercase letters/numbers/dashes (no leading/trailing/double dash).'; return; }
+
+    const btn = q('#np-create');
+    btn.disabled = true; btn.textContent = 'Requesting…';
+    try {
+      const data = await postJSON(`${API}/provisioning/instances`, {
+        slug,
+        hosting_shape: 'standalone',
+        domain: domain || undefined,
+        target_ref: `${owner}/${repo}`,
+      });
+      const instanceId = data && data.instance ? data.instance.id : null;
+      q('#np-form').hidden = true;
+      q('#np-result').innerHTML = renderNextSteps(instanceId, slug, domain, mode);
+      // Wire the one-click GitHub sign-in button (task 2080), if a domain gave us one.
+      const gh = q('#np-github-app');
+      if (gh) gh.addEventListener('click', async () => {
+        const msg = q('#np-github-app-msg');
+        gh.disabled = true; gh.textContent = 'Opening GitHub…'; if (msg) msg.textContent = '';
+        try {
+          await launchGithubApp(gh.getAttribute('data-instance'));
+        } catch (e2) {
+          gh.disabled = false; gh.textContent = 'Set up GitHub sign-in';
+          if (msg) msg.textContent = e2 && e2.message ? `Couldn’t start it: ${e2.message}` : 'Couldn’t start it — try again.';
+        }
+      });
+    } catch (e) {
+      err.textContent = e && e.message ? `Couldn’t request it: ${e.message}` : 'Couldn’t request it — try again.';
+      btn.disabled = false; btn.textContent = 'Create project';
+    }
+  }
+
+  const SKELETON =
+    '<h2 id="np-h" class="scroll__h">Start a project</h2>' +
+    '<p class="scroll__lede">Stand up a <strong>standalone</strong> Cloud Bongos instance — its own repo running a pinned copy of the platform. Start fresh, or adopt a repo you already have. We file the request and walk you through the few steps only you can do.</p>' +
+    '<div id="np-form" class="np-form">' +
+      '<label class="np-field"><span>Project name</span><input id="np-name" type="text" placeholder="Mercury" autocomplete="off"></label>' +
+      '<label class="np-field"><span>Starting from</span><select id="np-mode">' +
+        '<option value="greenfield">A new, empty repo (greenfield)</option>' +
+        '<option value="adopt">A repo I already have (adopt)</option>' +
+      '</select></label>' +
+      '<label class="np-field"><span>GitHub repo owner</span><input id="np-owner" type="text" placeholder="acme" autocomplete="off"></label>' +
+      '<label class="np-field"><span>GitHub repo name</span><input id="np-repo" type="text" placeholder="mercury" autocomplete="off"></label>' +
+      '<label class="np-field"><span>Instance slug</span><input id="np-slug" type="text" placeholder="mercury" autocomplete="off"></label>' +
+      '<label class="np-field"><span>Domain you own <span class="ledger__note">(optional now)</span></span><input id="np-domain" type="text" placeholder="mercury.example.com" autocomplete="off"></label>' +
+      '<p id="np-error" class="np-error" role="alert"></p>' +
+      '<button id="np-create" type="button" class="np-create-btn">Create project</button>' +
+    '</div>' +
+    '<div id="np-result"></div>';
+
+  function mount(hostEl) {
+    host = hostEl;
+    host.innerHTML = SKELETON;
+    const btn = host.querySelector('#np-create');
+    if (btn) btn.addEventListener('click', submit);
+  }
+
+  window.OTB.contributeHallWidget({
+    id: 'new-project-scroll', label: 'Start a project', order: 33,
+    module: 'provisioning', view: 'home', zone: 'home-main',
+    labelledby: 'np-h', mount,
+  });
+})();

package/modules/hall-ui/public/not-ready.html

@@ -0,0 +1,48 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Not yet available — {{worldName}}</title>
+  <meta name="description" content="This page unlocks as you advance. Ship your first three tasks to open the rest of the builder hub.">
+  <link rel="icon" href="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><text x='16' y='24' font-size='24' text-anchor='middle' font-family='sans-serif'>⌂</text></svg>">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="/builders/style.css?v=2026-07-02-shell1">
+</head>
+<body data-page="not-ready" data-page-title="Locked">
+
+<div class="app">
+  <aside class="app-sidebar" id="app-sidebar" aria-label="Primary"></aside>
+  <div class="app-scrim" id="app-scrim" hidden></div>
+  <div class="app-body">
+    <header class="app-topbar" id="app-topbar"></header>
+    <div class="app-content">
+      <main>
+        <section class="scroll">
+          <h2 class="scroll__h">Not yet available</h2>
+          <p class="scroll__lede">This page unlocks as you advance.</p>
+          <p>
+            Xenos builders start with a focused set of pages — ship your first
+            <strong>three tasks</strong> to graduate and open the rest of
+            {{worldName}}'s builder hub.
+          </p>
+          <p style="margin-top: 18px;">
+            <a href="/ranks">See how ranks work →</a>
+          </p>
+          <p>
+            <a href="/">← Back to Home</a>
+          </p>
+        </section>
+      </main>
+      <footer class="app-foot" id="app-foot"></footer>
+    </div>
+  </div>
+</div>
+
+<div id="toast" class="toast" role="status" aria-live="polite" data-visible="0"></div>
+
+<script src="/builders/shell.js"></script>
+</body>
+</html>

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

@@ -0,0 +1,119 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Approve your Dev Box app — {{worldName}}</title>
+  <meta name="description" content="Approve the Dev Box desktop app's request to sign in as you.">
+  <link rel="icon" href="data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'><text x='16' y='24' font-size='24' text-anchor='middle' font-family='sans-serif'>⌂</text></svg>">
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <link rel="stylesheet" href="/builders/style.css?v=2026-07-02-shell1">
+  <style>
+    /* Page-local styles for the pairing approve page (#904) — built on the
+       shared design-system tokens in style.css. */
+    #pair-scroll { max-width: 640px; }
+
+    .pair-device {
+      display: flex;
+      align-items: center;
+      gap: 14px;
+      background: var(--surface-2);
+      border: 1px solid var(--border);
+      border-radius: var(--radius-sm);
+      padding: 14px 16px;
+      margin: 14px 0 18px;
+    }
+    .pair-device__glyph {
+      font-size: 1.7rem;
+      line-height: 1;
+    }
+    .pair-device__name {
+      font-family: var(--font-display);
+      font-size: 14px;
+      font-weight: 600;
+      color: var(--ink);
+    }
+    .pair-device__meta {
+      font-family: var(--font-body);
+      font-size: 13px;
+      color: var(--ink-soft);
+    }
+    .pair-code {
+      font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+      font-size: 12.5px;
+      letter-spacing: 0.08em;
+      color: var(--ink-soft);
+    }
+    .pair-actions {
+      display: flex;
+      align-items: center;
+      gap: 14px;
+      flex-wrap: wrap;
+    }
+    .pair-approve {
+      font-family: var(--font-body);
+      font-size: 13.5px;
+      font-weight: 600;
+      padding: 10px 22px;
+      background: var(--accent);
+      color: #fff;
+      border: 1px solid var(--accent);
+      border-radius: var(--radius-sm);
+      cursor: pointer;
+    }
+    .pair-approve:hover:not(:disabled) { background: var(--accent-deep); border-color: var(--accent-deep); }
+    .pair-approve:disabled { opacity: 0.55; cursor: default; }
+    .pair-status {
+      font-family: var(--font-body);
+      font-size: 13.5px;
+      color: var(--ink-soft);
+      min-height: 1.2em;
+    }
+    .pair-status--ok { color: var(--ok); font-weight: 600; }
+    .pair-status--err { color: var(--danger); }
+    .pair-note {
+      font-family: var(--font-body);
+      font-size: 13px;
+      color: var(--ink-faint);
+      margin-top: 16px;
+    }
+  </style>
+</head>
+<body data-page="pair" data-page-title="Device pairing">
+
+<div class="app">
+  <aside class="app-sidebar" id="app-sidebar" aria-label="Primary"></aside>
+  <div class="app-scrim" id="app-scrim" hidden></div>
+  <div class="app-body">
+    <header class="app-topbar" id="app-topbar"></header>
+    <div class="app-content">
+      <div class="page-head"><p class="page-head__sub" id="pair-sub">Reading the request…</p></div>
+      <main>
+        <section class="scroll" id="pair-scroll" aria-labelledby="pair-h">
+          <h2 id="pair-h" class="scroll__h">A device is asking to act as you</h2>
+          <div id="pair-body">
+            <p class="scroll__lede">Loading…</p>
+          </div>
+          <p class="pair-note">
+            Approve only if you just clicked “Connect” in the Dev Box app on your own
+            machine. Approving signs that app in as you; the request expires on its own
+            if you do nothing.
+          </p>
+        </section>
+      </main>
+      <footer class="app-foot" id="app-foot"></footer>
+    </div>
+  </div>
+</div>
+
+<div id="toast" class="toast" role="status" aria-live="polite" data-visible="0"></div>
+
+<!-- App shell (sidebar/topbar/footer) — dependency-free, loads FIRST. -->
+<script src="/builders/shell.js?v=2026-07-02-shell1"></script>
+<!-- shared frontend toolkit (window.OTB) — loaded before pair.js, which pulls from it. -->
+<script src="/builders/dom-utils.js?v=2026-06-14-domutils"></script>
+<script src="/builders/pair.js?v=2026-06-14-domutils"></script>
+</body>
+</html>

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

@@ -0,0 +1,132 @@
+// public-builders/pair.js — the Dev Box desktop app's approve page (#904,
+// ADR 0044). The app opened this URL with ?code=<pair_code>; the signed-in
+// builder reviews what asked to connect and clicks ONE button. The server
+// gate (requireBuilderPage in server.js) has already bounced unauthenticated
+// visitors through web sign-in with this URL — code included — as ?return=.
+(() => {
+  'use strict';
+
+  const API = '/api/bongos';
+  // Generated typed client (task 1996 / R09), served as window.BongosClient by
+  // /lib/bongos-client.js. baseUrl:'' passes the full `${API}/...` URLs below
+  // through unchanged; result-mode ({ status, ok, data }) preserves control flow 1:1.
+  const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
+
+  // escapeHtml / $ now come from the shared window.OTB toolkit (dom-utils.js,
+  // loaded first). The shared $ accepts an optional root arg — a superset of
+  // this page's prior single-arg form, so call sites are unchanged.
+  const { escapeHtml, $ } = window.OTB;
+
+  function toAuth() {
+    const here = window.location.pathname + window.location.search;
+    window.location.assign(`${API}/auth/web/start?return=${encodeURIComponent(here)}`);
+  }
+
+  const PLATFORM_LABELS = {
+    mac: 'macOS', windows: 'Windows', linux: 'Linux', unknown: 'an unknown platform',
+  };
+  const PLATFORM_GLYPHS = { mac: '⌘', windows: '⊞', linux: '🐧', unknown: '🖥' };
+
+  function renderError(heading, detail) {
+    $('#pair-sub').textContent = heading;
+    $('#pair-body').innerHTML = `
+      <p class="scroll__lede">${escapeHtml(detail)}</p>
+      <p class="pair-status pair-status--err">Return to the Dev Box app and click “Connect” again for a fresh code.</p>
+    `;
+  }
+
+  function renderApproved(login) {
+    $('#pair-sub').textContent = 'Approved.';
+    $('#pair-body').innerHTML = `
+      <p class="scroll__lede">
+        The Dev Box app now acts as <strong>@${escapeHtml(login)}</strong>.
+        Return to the app — it has already noticed. You can close this tab.
+      </p>
+      <p class="pair-status pair-status--ok">✓ Approved</p>
+    `;
+  }
+
+  function renderRequest(info, login) {
+    const plat = PLATFORM_LABELS[info.platform] || PLATFORM_LABELS.unknown;
+    const glyph = PLATFORM_GLYPHS[info.platform] || PLATFORM_GLYPHS.unknown;
+    $('#pair-sub').textContent = 'One click, and the app can act as you.';
+    $('#pair-body').innerHTML = `
+      <p class="scroll__lede">
+        <strong>${escapeHtml(info.device_name)}</strong> on ${escapeHtml(plat)}
+        is asking to sign in as <strong>@${escapeHtml(login)}</strong> —
+        to start and stop your dev box on your behalf.
+      </p>
+      <div class="pair-device">
+        <span class="pair-device__glyph" aria-hidden="true">${glyph}</span>
+        <div>
+          <div class="pair-device__name">${escapeHtml(info.device_name)}</div>
+          <div class="pair-device__meta">${escapeHtml(plat)} · code <span class="pair-code">${escapeHtml(info.pair_code)}</span></div>
+        </div>
+      </div>
+      <div class="pair-actions">
+        <button type="button" class="pair-approve" id="pair-approve-btn">Approve — sign the app in as me</button>
+        <span class="pair-status" id="pair-status" role="status" aria-live="polite"></span>
+      </div>
+    `;
+    $('#pair-approve-btn').addEventListener('click', () => approve(info.pair_code, login));
+  }
+
+  async function approve(code, login) {
+    const btn = $('#pair-approve-btn');
+    const status = $('#pair-status');
+    btn.disabled = true;
+    status.textContent = 'Approving…';
+    try {
+      const res = await api.request('POST', `${API}/auth/app-pair/approve`, { body: { pair_code: code } });
+      if (res.status === 401) return toAuth();
+      if (res.status === 404 || res.status === 410) {
+        return renderError('Request expired.', 'This pairing code is unknown or has expired (codes last ten minutes).');
+      }
+      if (res.status === 409) {
+        return renderError('Already approved.', 'This pairing was already approved once — a code works exactly one time.');
+      }
+      if (!res.ok) throw new Error(`approve failed (${res.status})`);
+      renderApproved(login);
+    } catch (err) {
+      btn.disabled = false;
+      status.textContent = 'Approval failed — try again.';
+      status.className = 'pair-status pair-status--err';
+      console.error('[pair]', err);
+    }
+  }
+
+  async function load() {
+    const code = new URLSearchParams(window.location.search).get('code');
+    if (!code) {
+      return renderError('No code in this link.', 'The link is missing its pairing code.');
+    }
+    let me;
+    try {
+      const meRes = await api.request('GET', `${API}/me`);
+      if (meRes.status === 401) return toAuth();
+      if (!meRes.ok) throw new Error(`/me ${meRes.status}`);
+      me = meRes.data;
+    } catch (err) {
+      console.error('[pair]', err);
+      return renderError('Could not reach the server.', 'Could not verify your identity. Reload to try again.');
+    }
+    try {
+      const res = await api.request('GET', `${API}/auth/app-pair/info?code=${encodeURIComponent(code)}`);
+      if (res.status === 401) return toAuth();
+      if (res.status === 404) {
+        return renderError('Request expired.', 'This pairing code is unknown or has expired (codes last ten minutes).');
+      }
+      if (!res.ok) throw new Error(`info ${res.status}`);
+      const info = res.data;
+      if (info.status !== 'pending') {
+        return renderError('Already approved.', 'This pairing was already approved once — a code works exactly one time.');
+      }
+      renderRequest(info, me.builder.github_login);
+    } catch (err) {
+      console.error('[pair]', err);
+      renderError('Could not reach the server.', 'Could not read the pairing request. Reload to try again.');
+    }
+  }
+
+  load();
+})();