@ia-qa/self-healing 1.8.2 → 1.9.1

package/dist/ui/page.js

@@ -207,6 +207,61 @@ th{color:var(--muted);font-weight:600;font-size:10.5px;text-transform:uppercase;
 td.n{text-align:right;font-variant-numeric:tabular-nums}
 .axis{fill:#71717a;font-size:10px}
 .note{color:var(--muted);font-size:12px;margin-top:8px}
+/* The setup form, for a folder with no config. Same vocabulary as the rest of the
+   page: the card, the pill CTA, the dashed line that states what leaves the machine. */
+[hidden]{display:none!important}
+.lede-s{font-size:13px;margin-bottom:16px}
+code.k{background:var(--surface2);border:1px solid var(--border);border-radius:5px;padding:1px 6px;font:11.5px ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--orange2)}
+.step{border-top:1px solid var(--border);padding:18px 0}
+.st{display:flex;align-items:center;gap:10px;margin-bottom:10px}
+.st-row{display:flex;align-items:center;gap:10px}
+.st-row .v{font-size:12.5px;color:var(--muted);min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.st-row .aside{margin-left:auto;font-size:12px;color:var(--muted)}
+.st-row a{margin-left:auto;font-size:12px;text-decoration:none}
+.st-lock{opacity:.45}
+.field{font:inherit;font-size:13px;width:100%;background:var(--surface2);color:var(--text);border:1px solid var(--border);border-radius:9px;padding:9px 12px;outline:none}
+.field:focus{border-color:var(--orange)}
+.field.mono{font-family:ui-monospace,SFMono-Regular,Menlo,monospace;font-size:12px}
+.rowf{display:flex;gap:8px;align-items:center}
+.rowb{display:flex;gap:8px;margin-bottom:10px}
+.cta:disabled{opacity:.5;cursor:default}
+.su-found{display:flex;align-items:baseline;gap:10px;margin:16px 0 4px}
+.su-all{margin-left:auto;display:flex;gap:10px;font-size:12px}
+.su-all a,.su-rm{text-decoration:none}
+.su-row{cursor:pointer;align-items:center}
+.su-n{font-size:12.5px;font-weight:600;width:170px;flex:none;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.su-p{font:11.5px ui-monospace,SFMono-Regular,Menlo,monospace;color:var(--muted);word-break:break-all;flex:1}
+.su-rm{font-size:11.5px}
+.chk{width:15px;height:15px;border-radius:4px;border:1.5px solid #3f3f46;flex:none;display:inline-flex;align-items:center;justify-content:center}
+.chk.on{background:var(--orange);border-color:var(--orange)}
+.su-more{margin-top:10px}
+.su-add{margin-top:18px}
+.su-add .note{margin:0 0 6px}
+.btn-s{font-size:12.5px;padding:8px 12px;flex:none}
+.opts{display:flex;flex-direction:column;gap:10px}
+.opt{display:flex;gap:11px;border:1px solid var(--border);border-radius:12px;padding:14px 15px;background:var(--surface2);cursor:pointer}
+.opt-on{border-color:var(--orange);background:#f9731610;cursor:default}
+.opt-b{flex:1;min-width:0}
+.opt-b b{font-size:13px}
+.r{width:15px;height:15px;border-radius:50%;border:1.5px solid #3f3f46;flex:none;margin-top:3px}
+.r-on{border-color:var(--orange);background:radial-gradient(circle,var(--orange) 0 3.5px,transparent 4px)}
+.lbl{font-size:12px;color:var(--muted);margin-bottom:6px}
+.su-sub{margin-top:14px}
+.seg{display:inline-flex;border:1px solid var(--border);border-radius:99px;padding:3px;background:var(--bg);gap:3px}
+.seg span{font-size:12.5px;padding:4px 12px;border-radius:99px;color:var(--muted);border:1px solid transparent;cursor:pointer}
+.seg span.on{font-weight:600;background:#f9731618;color:var(--orange2);border-color:var(--orange)}
+.g2{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px;margin-top:14px}
+.g3{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:10px;margin-top:10px}
+@media(max-width:700px){.g2,.g3{grid-template-columns:1fr}}
+.su-dash{margin-top:12px;font-size:12px;color:var(--muted);border:1px dashed var(--border);border-radius:8px;padding:9px 11px}
+.su-foot{border-top:1px solid var(--border);padding-top:16px;display:flex;align-items:center;gap:12px;flex-wrap:wrap}
+.su-err{margin-top:10px;font-size:12.5px;color:#fda4af;white-space:pre-wrap}
+.su-file{font-size:12.5px;margin-bottom:10px;word-break:break-all}
+.su-json{white-space:pre;max-height:none;overflow:auto;margin-top:0}
+.su-miss{margin-top:10px;font-size:12px;color:#fcd34d}
+.su-miss li{margin-top:3px}
+.su-promise{display:flex;flex-direction:column;gap:8px;margin-top:14px;font-size:12px;color:var(--muted)}
+.su-promise b{color:var(--text)}
 </style>
 </head><body>
 <header><div class="wrap head">
@@ -224,7 +279,24 @@ td.n{text-align:right;font-variant-numeric:tabular-nums}
 </div></header>
 <main><div class="wrap">
   <div id="update"></div>
-  <section class="grid cols">
+  <!-- Shown instead of everything below when the folder has no config: nothing
+       else on this page can say anything true about an app it has no address for. -->
+  <section class="grid cols" id="setupSec" hidden>
+    <div class="card" id="setupForm"></div>
+    <div class="card">
+      <h2>What this writes</h2>
+      <div class="su-file">One file: <code class="k" id="setupPath"></code></div>
+      <div class="log su-json" id="setupJson"></div>
+      <div class="note" id="setupMore"></div>
+      <div id="setupProblems"></div>
+      <div class="su-promise">
+        <div>🔑 <b>References only.</b> A password, a token or a cookie is never written to this file, and no field on this page asks for one.</div>
+        <div>📦 This file is meant to be committed.</div>
+        <div>🔒 Setting up sends nothing anywhere — except the sitemap request in step 2, and only if you click it.</div>
+      </div>
+    </div>
+  </section>
+  <section class="grid cols" id="mainGrid">
     <div class="card" id="verdictCard"><div class="empty">loading…</div></div>
     <div class="card">
       <h2>Actions</h2>
@@ -281,7 +353,13 @@ let LAST_STATE = {};
 
 function render(s) {
   LAST_STATE = s || {};
-  renderPicker(s); renderUpdate(s); renderHead(s); renderVerdict(s); renderActions(s);
+  renderPicker(s); renderUpdate(s); renderHead(s);
+  const setup = Boolean(s.project && s.project.needsSetup);
+  q('#setupSec').hidden = !setup;
+  q('#mainGrid').hidden = setup;
+  ['#decisions', '#project', '#history'].forEach((id) => { q(id).closest('section').hidden = setup; });
+  if (setup) { q('#findingsCard').hidden = true; renderSetup(s); return; }
+  renderVerdict(s); renderActions(s);
   renderDecisions(s); renderHistory(s); renderGoto(s); bindCopy();
 }
 
@@ -329,8 +407,12 @@ function renderPicker(s) {
   // terminal, the feature could never start existing.
   wrap.style.display = '';
   const sel = q('#picker');
+  // A folder being set up is not in the list yet — it joins once its config is
+  // written — but it is the one on screen, so the menu has to say so.
+  const listed = list.some((p) => p.dir === s.activeDir);
   sel.innerHTML =
-    list.map((p) =>
+    (listed ? '' : '<option value="' + esc(s.activeDir) + '" selected>' + esc(shortDir(s.activeDir)) + '  —  not set up yet</option>')
+    + list.map((p) =>
       '<option value="' + esc(p.dir) + '"' + (p.dir === s.activeDir ? ' selected' : '') + '>'
       + esc(shortDir(p.dir)) + (p.baseUrl ? '  —  ' + esc(p.baseUrl) : '') + '</option>'
     ).join('')
@@ -364,8 +446,7 @@ function askForFolder() {
   const v = prompt(
     'Add a project to this console.\\n\\n'
     + 'Paste the full path of the project folder — the one you would open in your '
-    + 'editor. It must already contain a .ia-qa folder (run "ia-qa-heal init" there '
-    + 'if it does not).',
+    + 'editor. If it has never been set up, the console walks you through it.',
     ''
   );
   return v && v.trim() ? v.trim() : null;
@@ -782,6 +863,333 @@ function bindCopy() {
   });
 }
 
+/* ---- setup: a folder with no .ia-qa/config.json ------------------------ */
+
+/* The file ia-qa-heal init writes, asked for in three steps. The panel on the
+   right is the server's own plan for the answers so far — the function the write
+   goes through — so it cannot show one file and write another. No field here
+   takes a secret: the login answers are the NAMES of variables. */
+const ENV_DEFAULTS = { usernameKey: 'E2E_USERNAME', passwordKey: 'E2E_PASSWORD' };
+const SSM_DEFAULTS = { usernameKey: '/staging/app/username', passwordKey: '/staging/app/password' };
+const CHECK_SVG = '<svg width="11" height="11" viewBox="0 0 16 16" fill="none" stroke="#09090b" stroke-width="2.4" stroke-linecap="round" stroke-linejoin="round"><path d="M3.5 8.5l3 3 6-7"/></svg>';
+const setupBlank = () => ({
+  step: 1, baseUrl: '', found: null, foundFor: '', reason: [], capped: false, selected: {}, showAll: false, manual: [],
+  mode: '', store: 'env', usernameKey: ENV_DEFAULTS.usernameKey, passwordKey: ENV_DEFAULTS.passwordKey, region: 'eu-west-3',
+  loginUrl: '/login', usernameSelector: 'input[name="email"]', passwordSelector: 'input[type="password"]',
+  submitSelector: 'button[type="submit"]', busy: false, error: '',
+});
+let SETUP = setupBlank();
+let setupDir = null;
+let previewTimer = null;
+
+async function postJson(pathname, body) {
+  const r = await fetch(pathname + '?t=' + T, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body),
+  });
+  return r.json();
+}
+
+function setupPages() {
+  return (SETUP.found || []).filter((p) => SETUP.selected[p.url]).concat(SETUP.manual);
+}
+
+function setupBody() {
+  const S = SETUP;
+  const login = S.mode === 'form'
+    ? { mode: 'form', store: S.store, usernameKey: S.usernameKey, passwordKey: S.passwordKey, region: S.region,
+        loginUrl: S.loginUrl, usernameSelector: S.usernameSelector, passwordSelector: S.passwordSelector,
+        submitSelector: S.submitSelector }
+    : { mode: S.mode };
+  return { baseUrl: S.baseUrl, pages: setupPages().map((p) => ({ name: p.name, url: p.url })), login: login };
+}
+
+function renderSetup(s) {
+  // Answers typed for one folder must never be written into the next one picked.
+  if (setupDir !== s.activeDir) { SETUP = setupBlank(); setupDir = s.activeDir; }
+  drawSetup();
+  refreshPreview();
+}
+
+function sitemapUrl(base) {
+  try { return new URL('/sitemap.xml', base).toString(); } catch (e) { return base + '/sitemap.xml'; }
+}
+
+function stepRow(n, label, value) {
+  return '<div class="step st-row"><span class="num">' + n + ' of 3</span><b>' + esc(label) + '</b>'
+    + '<span class="v">' + esc(value) + '</span><a href="#" data-goto="' + n + '">change</a></div>';
+}
+
+function drawSetup() {
+  const S = SETUP;
+  let h = '<h2>Set up this folder</h2>'
+    + '<div class="lede-s">This folder has no <code class="k">.ia-qa/config.json</code> yet, so there is nothing to look at. '
+    + 'Answer three questions and the console writes it for you — the same file <code class="k">ia-qa-heal init</code> would.</div>';
+
+  if (S.step === 1) {
+    h += '<div class="step"><div class="st"><span class="num">1 of 3</span><b>Where does the app live?</b></div>'
+      + '<div class="rowf"><input class="field" id="su-url" placeholder="https://staging.example.com" autocomplete="off" spellcheck="false" value="' + esc(S.baseUrl) + '">'
+      + '<button class="cta" id="su-next1">Next</button></div>'
+      + '<div class="note">The address your tests run against. A staging server beats production if you have one.</div></div>'
+      + '<div class="step st-row st-lock"><span class="num">2 of 3</span><b>Which pages should it watch?</b><span class="aside">needs the address first</span></div>';
+  } else {
+    h += stepRow(1, 'App', S.baseUrl);
+    if (S.step === 2) h += pagesStep();
+    else { const n = setupPages().length; h += stepRow(2, 'Pages', n + ' page' + (n === 1 ? '' : 's')); }
+  }
+
+  if (S.step === 3) h += loginStep();
+  else h += '<div class="step st-row' + (S.step === 1 ? ' st-lock' : '') + '"><span class="num">3 of 3</span><b>Does the app ask you to log in?</b>'
+    + (S.step === 2 ? '<span class="aside">not answered yet</span>' : '') + '</div>';
+
+  const ready = S.step === 3 && S.mode && !S.busy;
+  h += '<div class="su-foot"><button class="cta" id="su-write"' + (ready ? '' : ' disabled') + '>'
+    + (S.busy && S.step === 3 ? 'Writing…' : 'Write the config ✎') + '</button>'
+    + '<span class="note" style="margin:0">Changes one file on your computer. Nothing is committed.</span></div>'
+    + (S.error ? '<div class="su-err">' + esc(S.error) + '</div>' : '');
+  q('#setupForm').innerHTML = h;
+  bindSetup();
+}
+
+function pagesStep() {
+  const S = SETUP;
+  let h = '<div class="step"><div class="st"><span class="num">2 of 3</span><b>Which pages should it watch?</b></div>'
+    + '<div class="rowb"><button class="cta" id="su-sitemap"' + (S.busy ? ' disabled' : '') + '>'
+    + (S.busy ? 'Reading the sitemap…' : S.found ? 'Read the sitemap again' : 'Find them in the sitemap') + '</button></div>'
+    + '<div class="net-line" style="margin-top:0">🔗 One request to <b>' + esc(sitemapUrl(S.baseUrl)) + '</b> (and robots.txt if the sitemap lives elsewhere) — plain GET, no browser, no login, nothing else sent.</div>';
+  if (S.found && S.found.length === 0) {
+    h += '<div class="note">' + S.reason.map(esc).join('<br>') + '<br>Add the pages by hand below.</div>';
+  } else if (S.found) {
+    const n = S.found.length;
+    const sel = S.found.filter((p) => S.selected[p.url]).length;
+    h += '<div class="su-found"><b>Found ' + n + ' page' + (n === 1 ? '' : 's') + (S.capped ? ' — the first ' + n + ', the sitemap lists more' : '') + '.</b>'
+      + '<span class="note" style="margin:0">' + sel + ' selected</span>'
+      + '<span class="su-all"><a href="#" id="su-all">select all</a><a href="#" id="su-none">none</a></span></div>'
+      + (S.showAll ? S.found : S.found.slice(0, 8)).map((p) => pageRow(p, Boolean(S.selected[p.url]), 'u', p.url)).join('');
+    if (!S.showAll && n > 8) h += '<button class="cta su-more" id="su-more">Show the ' + (n - 8) + ' others</button>';
+  }
+  h += S.manual.map((p, i) => pageRow(p, true, 'm', String(i))).join('');
+  h += '<div class="su-add"><div class="note">A page the sitemap does not list — a route behind the login, say — can be added by hand.</div>'
+    + '<div class="rowf"><input class="field" id="su-mname" placeholder="name" style="width:170px;flex:none" autocomplete="off">'
+    + '<input class="field mono" id="su-mpath" placeholder="/path" autocomplete="off" spellcheck="false">'
+    + '<button class="btn-s" id="su-madd">Add</button></div></div>'
+    + '<div class="rowb" style="margin:14px 0 0"><button class="cta" id="su-next2"' + (setupPages().length ? '' : ' disabled') + '>Next</button></div></div>';
+  return h;
+}
+
+function pageRow(p, on, kind, key) {
+  return '<div class="frow su-row" data-kind="' + kind + '" data-key="' + esc(key) + '">'
+    + '<span class="chk' + (on ? ' on' : '') + '">' + (on ? CHECK_SVG : '') + '</span>'
+    + '<span class="su-n" title="' + esc(p.name) + '">' + esc(p.name) + '</span><span class="su-p">' + esc(p.url) + '</span>'
+    + (kind === 'm' ? '<a href="#" class="su-rm">remove</a>' : '') + '</div>';
+}
+
+function loginStep() {
+  const S = SETUP;
+  const opt = (mode, title, body) => '<div class="opt' + (S.mode === mode ? ' opt-on' : '') + '" data-mode="' + mode + '">'
+    + '<span class="r' + (S.mode === mode ? ' r-on' : '') + '"></span><div class="opt-b"><b>' + title + '</b>' + body + '</div></div>';
+  return '<div class="step"><div class="st"><span class="num">3 of 3</span><b>Does the app ask you to log in?</b></div><div class="opts">'
+    + opt('none', 'No — the pages are public', '')
+    + opt('session', 'Yes — I will log in myself, in a browser',
+        '<div class="note">Works with any login: single sign-on, two-factor, a code by email. A browser window opens, you sign in the way you always do, and the session is kept for the next captures.</div>'
+        + '<div class="upd-cmd"><code>ia-qa-heal login</code><button class="copy" data-copy="ia-qa-heal login" data-copy-label="copy command">copy command</button></div>'
+        + '<div class="note">Run it once in a terminal, after setup. The console cannot open that window for you: it waits for a person at the keyboard. The session file holds live cookies, so it is kept out of git.</div>')
+    + opt('form', 'Yes — fill a plain login form from stored credentials',
+        '<div class="note">For pipelines: no human needed. A username, a password and a submit button, nothing fancier. Single sign-on and two-factor will not get through this way.</div>'
+        + (S.mode === 'form' ? formFields() : ''))
+    + '</div></div>';
+}
+
+function formFields() {
+  const S = SETUP;
+  const env = S.store === 'env';
+  const field = (key, label) => '<div><div class="lbl">' + label + '</div><input class="field mono" data-f="' + key + '" value="' + esc(S[key]) + '" autocomplete="off" spellcheck="false"></div>';
+  return '<div class="su-sub"><div class="lbl">Where are the credentials kept?</div><div class="seg">'
+      + '<span data-store="env"' + (env ? ' class="on"' : '') + '>Environment variables</span>'
+      + '<span data-store="aws-ssm"' + (env ? '' : ' class="on"') + '>AWS SSM Parameter Store</span></div></div>'
+    + '<div class="g2">' + field('usernameKey', env ? 'Variable holding the username' : 'SSM parameter holding the username')
+      + field('passwordKey', env ? 'Variable holding the password' : 'SSM parameter holding the password') + '</div>'
+    + (env ? '' : '<div class="su-sub" style="max-width:260px">' + field('region', 'AWS region') + '</div>')
+    + '<div class="su-dash">These are the <b style="color:var(--text)">names</b> of ' + (env ? 'variables' : 'parameters') + ', not their values. '
+      + 'There is no password field on this page, on purpose: the value stays ' + (env ? 'in your environment' : 'in SSM') + ' and is only read when a capture logs in.</div>'
+    + '<div class="su-sub" style="max-width:260px">' + field('loginUrl', 'Login page') + '</div>'
+    + '<details class="tech"><summary>Form fields — the defaults fit most plain forms</summary><div class="g3">'
+      + field('usernameSelector', 'Username field') + field('passwordSelector', 'Password field') + field('submitSelector', 'Submit button')
+    + '</div></details>';
+}
+
+function bindSetup() {
+  const S = SETUP;
+  const box = q('#setupForm');
+  const on = (sel, fn) => { const el = q(sel); if (el) el.onclick = (e) => { e.preventDefault(); fn(); }; };
+  const url = q('#su-url');
+  if (url) {
+    url.oninput = () => { S.baseUrl = url.value.trim(); schedulePreview(); };
+    url.onkeydown = (e) => { if (e.key === 'Enter') nextFromUrl(); };
+    url.focus();
+  }
+  on('#su-next1', nextFromUrl);
+  on('#su-sitemap', readSitemapNow);
+  on('#su-all', () => { S.found.forEach((p) => { S.selected[p.url] = true; }); drawSetup(); schedulePreview(); });
+  on('#su-none', () => { S.selected = {}; drawSetup(); schedulePreview(); });
+  on('#su-more', () => { S.showAll = true; drawSetup(); });
+  on('#su-madd', addManualPage);
+  on('#su-next2', () => { S.step = 3; S.error = ''; drawSetup(); schedulePreview(); });
+  on('#su-write', writeSetupNow);
+  const mpath = q('#su-mpath');
+  if (mpath) mpath.onkeydown = (e) => { if (e.key === 'Enter') addManualPage(); };
+  box.querySelectorAll('[data-goto]').forEach((a) => {
+    a.onclick = (e) => { e.preventDefault(); S.step = Number(a.dataset.goto); S.error = ''; drawSetup(); schedulePreview(); };
+  });
+  box.querySelectorAll('.su-row').forEach((row) => {
+    row.onclick = (e) => {
+      if (row.dataset.kind === 'm') {
+        if (e.target.classList.contains('su-rm')) {
+          e.preventDefault();
+          S.manual.splice(Number(row.dataset.key), 1);
+          drawSetup(); schedulePreview();
+        }
+        return;
+      }
+      const k = row.dataset.key;
+      if (S.selected[k]) delete S.selected[k]; else S.selected[k] = true;
+      drawSetup(); schedulePreview();
+    };
+  });
+  box.querySelectorAll('[data-mode]').forEach((el) => {
+    el.onclick = () => {
+      if (S.mode === el.dataset.mode) return;
+      S.mode = el.dataset.mode; S.error = '';
+      drawSetup(); schedulePreview();
+    };
+  });
+  box.querySelectorAll('[data-store]').forEach((el) => {
+    el.onclick = (e) => { e.stopPropagation(); switchStore(el.dataset.store); };
+  });
+  box.querySelectorAll('input[data-f]').forEach((el) => {
+    el.oninput = () => { S[el.dataset.f] = el.value.trim(); schedulePreview(); };
+  });
+  bindCopy();
+}
+
+function nextFromUrl() {
+  const S = SETUP;
+  let ok = false;
+  try { const u = new URL(S.baseUrl); ok = u.protocol === 'http:' || u.protocol === 'https:'; } catch (e) { ok = false; }
+  if (!ok) {
+    S.error = 'Type the full address, starting with http:// or https:// — for example https://staging.example.com';
+    drawSetup();
+    return;
+  }
+  // Pages read from another address belong to another app.
+  if (S.foundFor && S.foundFor !== S.baseUrl) { S.found = null; S.selected = {}; S.foundFor = ''; }
+  S.error = ''; S.step = 2;
+  drawSetup(); schedulePreview();
+}
+
+async function readSitemapNow() {
+  const S = SETUP;
+  S.busy = true; S.error = ''; drawSetup();
+  try {
+    const r = await postJson('/api/setup/sitemap', { baseUrl: S.baseUrl });
+    if (r.error) S.error = r.error;
+    else {
+      S.found = r.pages; S.reason = r.reason || []; S.capped = Boolean(r.capped);
+      S.foundFor = S.baseUrl; S.showAll = false; S.selected = {};
+      r.pages.forEach((p) => { S.selected[p.url] = true; });
+    }
+  } catch (e) {
+    S.error = 'The console lost contact with its server: ' + e;
+  }
+  S.busy = false;
+  drawSetup(); schedulePreview();
+}
+
+function addManualPage() {
+  const S = SETUP;
+  const name = q('#su-mname').value.trim();
+  let where = q('#su-mpath').value.trim();
+  if (!name || !where) { S.error = 'A page needs a name and a path.'; drawSetup(); return; }
+  const low = where.toLowerCase();
+  if (where.charAt(0) !== '/' && low.indexOf('http://') !== 0 && low.indexOf('https://') !== 0) where = '/' + where;
+  S.manual.push({ name: name, url: where });
+  S.error = '';
+  drawSetup(); schedulePreview();
+}
+
+function switchStore(store) {
+  const S = SETUP;
+  if (S.store === store) return;
+  const from = store === 'env' ? SSM_DEFAULTS : ENV_DEFAULTS;
+  const to = store === 'env' ? ENV_DEFAULTS : SSM_DEFAULTS;
+  if (S.usernameKey === from.usernameKey) S.usernameKey = to.usernameKey;
+  if (S.passwordKey === from.passwordKey) S.passwordKey = to.passwordKey;
+  S.store = store;
+  drawSetup(); schedulePreview();
+}
+
+function schedulePreview() {
+  clearTimeout(previewTimer);
+  previewTimer = setTimeout(refreshPreview, 250);
+}
+
+async function refreshPreview() {
+  let r;
+  try { r = await postJson('/api/setup/preview', setupBody()); } catch (e) { return; }
+  const cfg = r.config || {};
+  const pages = cfg.pages || [];
+  const shown = Object.assign({}, cfg, { pages: pages.slice(0, 7) });
+  q('#setupPath').textContent = r.file || '';
+  q('#setupJson').textContent = JSON.stringify(shown, null, 2);
+  const more = pages.length - 7;
+  q('#setupMore').textContent = more > 0 ? '… and ' + more + ' more page' + (more === 1 ? '' : 's') + ' in the file.' : '';
+  const missing = SETUP.step === 3 ? (r.problems || []) : [];
+  q('#setupProblems').innerHTML = missing.length
+    ? '<ul class="su-miss">' + missing.map((p) => '<li>' + esc(p) + '</li>').join('') + '</ul>'
+    : '';
+}
+
+async function writeSetupNow() {
+  const S = SETUP;
+  S.busy = true; S.error = ''; drawSetup();
+  let r;
+  try { r = await postJson('/api/setup/write', setupBody()); }
+  catch (e) { r = { error: 'The console lost contact with its server: ' + e }; }
+  S.busy = false;
+  if (!r.written) { S.error = r.error || 'The config could not be written.'; drawSetup(); return; }
+  SETUP = setupBlank(); setupDir = null;
+  render(r.state);
+  showSetupDone(r);
+}
+
+/* The result lands where every other result does — in the Actions card — and
+   says what the chosen login still needs from a person, because that is the one
+   step this form could not take for them. */
+function showSetupDone(r) {
+  const missing = r.missingEnv || [];
+  let what;
+  if (r.login === 'session') {
+    what = 'Next, log in once from a terminal in this folder. A browser opens, you sign in the way you always do, and the session is kept for every capture after that.';
+  } else if (r.login === 'form' && r.store === 'aws-ssm') {
+    what = 'Only the SSM parameter names were saved. Your local AWS credentials fetch the values when a capture logs in.';
+  } else if (r.login === 'form') {
+    what = 'Only the variable names were saved.' + (missing.length
+      ? ' ' + missing.join(' and ') + (missing.length === 1 ? ' is' : ' are') + ' not set in the environment this console was started from — set '
+        + (missing.length === 1 ? 'it' : 'them') + ' there and reopen the console before the first capture, or it will stop at the login page and say so.'
+      : ' Both are set in the environment this console runs in.');
+  } else {
+    what = 'No login — the pages will be read the way a visitor sees them.';
+  }
+  q('#result').innerHTML = '<div class="res res-ok"><div class="res-head">✅ <span>Done</span></div>'
+    + '<div class="res-what"><b style="color:var(--text)">' + esc(r.headline) + '</b></div>'
+    + '<div class="res-what">' + esc(what) + '</div>'
+    + (r.login === 'session'
+        ? '<div class="upd-cmd"><code>ia-qa-heal login</code><button class="copy" data-copy="ia-qa-heal login" data-copy-label="copy command">copy command</button></div>'
+        : '')
+    + '<div id="next"></div></div>';
+  renderNext(r.next);
+  bindCopy();
+}
+
 /* ---- history ---------------------------------------------------------- */
 
 function renderHistory(s) {

package/dist/ui/page.js.map

@@ -1 +1 @@
-{"version":3,"file":"page.js","sourceRoot":"","sources":["../../src/ui/page.ts"],"names":[],"mappings":";;AAqBA,8CAi2BC;AAt3BD;;;;;;;;;;;;;;;;GAgBG;AACH,qCAAiD;AACjD,sCAAyD;AACzD,iCAAuC;AAEvC,SAAgB,iBAAiB,CAAC,KAAa;IAC7C,yEAAyE;IACzE,EAAE;IACF,+EAA+E;IAC/E,8EAA8E;IAC9E,4EAA4E;IAC5E,4DAA4D;IAC5D,EAAE;IACF,+EAA+E;IAC/E,2EAA2E;IAC3E,8EAA8E;IAC9E,oEAAoE;IACpE,EAAE;IACF,iFAAiF;IACjF,kFAAkF;IAClF,4EAA4E;IAC5E,MAAM,OAAO,GAAG,IAAA,uBAAc,GAAE,CAAC;IACjC,uFAAuF;IACvF,wFAAwF;IACxF,uFAAuF;IACvF,sFAAsF;IACtF,MAAM,IAAI,GAAG,IAAA,oBAAa,GAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,IAAI;QAClB,CAAC,CAAC,gEAAgE,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI;QACnG,CAAC,CAAC,EAAE,CAAC;IACP,OAAO;;;;EAIP,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gHAiKuG,qBAAY,IAAI,OAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAqDxI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA2lBf,8BAAqB;;;;;;;;;;;;;;;;;;eAkBxB,CAAC;AAChB,CAAC"}
+{"version":3,"file":"page.js","sourceRoot":"","sources":["../../src/ui/page.ts"],"names":[],"mappings":";;AAqBA,8CAyvCC;AA9wCD;;;;;;;;;;;;;;;;GAgBG;AACH,qCAAiD;AACjD,sCAAyD;AACzD,iCAAuC;AAEvC,SAAgB,iBAAiB,CAAC,KAAa;IAC7C,yEAAyE;IACzE,EAAE;IACF,+EAA+E;IAC/E,8EAA8E;IAC9E,4EAA4E;IAC5E,4DAA4D;IAC5D,EAAE;IACF,+EAA+E;IAC/E,2EAA2E;IAC3E,8EAA8E;IAC9E,oEAAoE;IACpE,EAAE;IACF,iFAAiF;IACjF,kFAAkF;IAClF,4EAA4E;IAC5E,MAAM,OAAO,GAAG,IAAA,uBAAc,GAAE,CAAC;IACjC,uFAAuF;IACvF,wFAAwF;IACxF,uFAAuF;IACvF,sFAAsF;IACtF,MAAM,IAAI,GAAG,IAAA,oBAAa,GAAE,CAAC;IAC7B,MAAM,OAAO,GAAG,IAAI;QAClB,CAAC,CAAC,gEAAgE,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI;QACnG,CAAC,CAAC,EAAE,CAAC;IACP,OAAO;;;;EAIP,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gHAwNuG,qBAAY,IAAI,OAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;YAsExI,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA26Bf,8BAAqB;;;;;;;;;;;;;;;;;;eAkBxB,CAAC;AAChB,CAAC"}

package/dist/ui/server.js

@@ -51,6 +51,7 @@ const crypto = __importStar(require("crypto"));
 const child_process_1 = require("child_process");
 const config_1 = require("../config");
 const registry_1 = require("./registry");
+const setup_1 = require("./setup");
 const diff_1 = require("../cli/diff");
 const ingest_1 = require("../ingest");
 const evidence_1 = require("../evidence");
@@ -413,6 +414,20 @@ function setActiveProject(dir) {
 function getActiveProject() {
     return activeDir ?? (0, config_1.baseDir)();
 }
+/**
+ * A capture is at least one page contract, not a directory. `saveConfig` creates `mapping/`
+ * empty, and reading that as a capture told a freshly set-up folder "You have a capture of
+ * the app" and offered to promote it — a baseline of nothing. `_`-prefixed entries are
+ * layouts, shots and resolutions, never pages.
+ */
+function hasContracts(dir) {
+    try {
+        return fs.readdirSync(dir).some((f) => f.endsWith('.json') && !f.startsWith('_'));
+    }
+    catch {
+        return false;
+    }
+}
 function buildState() {
     if (activeDir)
         (0, config_1.setBaseDir)(activeDir);
@@ -436,9 +451,17 @@ function buildState() {
             configFile: path.join((0, config_1.baseDir)(), config_1.CONFIG_DIR, 'config.json'),
         };
     }
-    catch {
+    catch (e) {
         project.dir = (0, config_1.baseDir)();
-        project.error = 'No .ia-qa/config.json in this folder — run `ia-qa-heal init` here.';
+        // Absent and broken are two different answers. An absent config gets the setup form; a
+        // broken one is the user's file and gets its error — never a form that would replace it.
+        if (fs.existsSync((0, config_1.configPath)())) {
+            project.error = `.ia-qa/config.json is here but cannot be read — ${e instanceof Error ? e.message : String(e)}`;
+        }
+        else {
+            project.needsSetup = true;
+            project.error = 'No .ia-qa/config.json in this folder yet — set it up below.';
+        }
     }
     // Which frameworks the suite is actually written in, read off the inventory
     // rather than guessed from a folder name — `ingest` already recorded the call
@@ -459,7 +482,7 @@ function buildState() {
         hasBaseline: fs.existsSync(base),
         // Told apart because the empty state's advice differs: with a capture and no
         // reference the next step is to promote one, not to "capture the app" again.
-        hasMapping: fs.existsSync(current),
+        hasMapping: hasContracts(current),
         history: { entries: history, summary: (0, history_1.summarize)(history) },
         actions: actionCatalogue(),
     };
@@ -711,8 +734,11 @@ async function handle(req, res, token, onBye) {
      * the console exists for people who do not have one.
      *
      * So consent can also be given here — but it is still consent, not discovery:
-     * a path is only accepted if it actually holds `.ia-qa/config.json`, and it is
-     * *registered*, which means `ui --forget` can take it back. Nothing scans.
+     * a project is *registered* only once it holds `.ia-qa/config.json`, which means
+     * `ui --forget` can take it back. Nothing scans. A folder that has never been set
+     * up opens on the setup form instead of a refusal — that refusal used to say "run
+     * `ia-qa-heal init` there", a terminal instruction for the people without one —
+     * and joins the list the moment the form has written its config.
      */
     if (req.method === 'POST' && url.pathname === '/api/project/add') {
         let body;
@@ -725,31 +751,98 @@ async function handle(req, res, token, onBye) {
         }
         const raw = typeof body.dir === 'string' ? body.dir.trim().replace(/^["']|["']$/g, '') : '';
         if (raw === '') {
-            send(res, 400, 'application/json', JSON.stringify({ error: 'Give the folder that holds your .ia-qa directory.' }));
+            send(res, 400, 'application/json', JSON.stringify({ error: 'Give the path of the project folder.' }));
             return;
         }
         const dir = path.resolve(raw);
-        if (!(0, registry_1.isProjectDir)(dir)) {
+        if (path.basename(dir) === config_1.CONFIG_DIR) {
             send(res, 400, 'application/json', JSON.stringify({
-                error: `No .ia-qa/config.json in ${dir}\n\n` +
-                    `Pick the project's top folder — the one you would open in your editor, ` +
-                    `not the .ia-qa folder itself. If that project has never been set up, run ` +
-                    `\`ia-qa-heal init\` in it first.`,
+                error: `That is the ${config_1.CONFIG_DIR} folder itself. Pick the project's top folder — the one you would open in your editor.`,
             }));
             return;
         }
-        setActiveProject(dir);
-        let addedUrl;
+        let isFolder = false;
         try {
-            addedUrl = (0, config_1.loadConfig)().baseUrl;
+            isFolder = fs.statSync(dir).isDirectory();
         }
         catch {
-            /* a project whose config will not parse can still be selected, and shown as broken */
+            isFolder = false;
+        }
+        if (!isFolder) {
+            send(res, 400, 'application/json', JSON.stringify({ error: `${dir} is not a folder on this machine.` }));
+            return;
+        }
+        setActiveProject(dir);
+        if ((0, registry_1.isProjectDir)(dir)) {
+            let addedUrl;
+            try {
+                addedUrl = (0, config_1.loadConfig)().baseUrl;
+            }
+            catch {
+                /* a project whose config will not parse can still be selected, and shown as broken */
+            }
+            (0, registry_1.rememberProject)(dir, addedUrl);
         }
-        (0, registry_1.rememberProject)(dir, addedUrl);
         send(res, 200, 'application/json; charset=utf-8', JSON.stringify(buildState()));
         return;
     }
+    /**
+     * The setup form's three calls — see ui/setup.ts. `preview` and `write` run the same
+     * `planSetup`, so the panel on the page is the file that would be written. None of them
+     * spawns anything. The one new authority is writing `.ia-qa/config.json` into the folder
+     * this console is showing, and only where none exists; the sitemap read is the same
+     * plain fetch `init --discover` makes, to an address the user typed.
+     */
+    if (req.method === 'POST' && url.pathname.startsWith('/api/setup/')) {
+        let body;
+        try {
+            body = JSON.parse(await readBody(req));
+        }
+        catch {
+            send(res, 400, 'application/json', JSON.stringify({ error: 'bad request body' }));
+            return;
+        }
+        const dir = getActiveProject();
+        if (url.pathname === '/api/setup/sitemap') {
+            try {
+                const found = await (0, setup_1.readSitemap)(typeof body.baseUrl === 'string' ? body.baseUrl.trim() : '');
+                send(res, 200, 'application/json; charset=utf-8', JSON.stringify(found));
+            }
+            catch (e) {
+                send(res, 400, 'application/json', JSON.stringify({ error: e instanceof Error ? e.message : String(e) }));
+            }
+            return;
+        }
+        if (url.pathname === '/api/setup/preview') {
+            send(res, 200, 'application/json; charset=utf-8', JSON.stringify({ ...(0, setup_1.planSetup)(body, dir), file: (0, config_1.configPath)(dir) }));
+            return;
+        }
+        if (url.pathname === '/api/setup/write') {
+            const result = (0, setup_1.writeSetup)(body, dir);
+            if (!result.written) {
+                send(res, 400, 'application/json', JSON.stringify({ error: result.error, problems: result.plan?.problems ?? [] }));
+                return;
+            }
+            const { config, mode, missingEnv } = result.plan;
+            (0, registry_1.rememberProject)(dir, config.baseUrl);
+            const n = config.pages.length;
+            // `map` stops at a login wall it cannot pass — before `login` has run, or with the
+            // form's variables absent from this process — so it is offered only where it can work.
+            const canLook = mode === 'none' || (mode === 'form' && missingEnv.length === 0);
+            send(res, 200, 'application/json; charset=utf-8', JSON.stringify({
+                written: result.file,
+                headline: `.ia-qa/config.json written — ${n} page${n === 1 ? '' : 's'}`,
+                login: mode,
+                store: config.secrets.username?.source ?? null,
+                missingEnv,
+                next: canLook
+                    ? [{ id: 'map', label: 'Look at the app', means: ACTIONS.map.means, writes: ACTIONS.map.writes }]
+                    : [],
+                state: buildState(),
+            }));
+            return;
+        }
+    }
     if (req.method === 'POST' && url.pathname === '/api/run') {
         let body;
         try {