@webship.co/workspace 0.0.0-stage → 1.0.0-alpha1

package/ddev-mail-page.js

@@ -0,0 +1,167 @@
+/**
+ * Mailpit, as one feature: its menu item, its route, its panel and where its mailbox is.
+ *
+ * `server.js` knows four things about mail, and each of them is one line: which URL a listing row
+ * carries, the menu item for a project, the fragment route, and the lookup the actions are handed.
+ * Everything else — the markup, the wiring, the "is it running" rule — lives here, so adding a column
+ * to the panel or a verb to the toolbar never touches the server file.
+ *
+ * The API client is `ddev-mail.js`; the three write verbs are `actions/ddev-mail.js`. This module is
+ * what joins them to the dashboard.
+ */
+
+const path = require('path');
+
+const { esc } = require('./html');
+const { humanSize, humanTime } = require('./format');
+const { workspaceDir } = require('./workspaces');
+const { ddevProjectName } = require('./jobs');
+const { NAME_RE } = require('./validate');
+const mail = require('./ddev-mail');
+
+// `/fragments/projects/mail/<workspace>/<project>` — the one path this feature answers on, matched
+// here rather than in the server's chain of patterns.
+const FRAGMENT_RE = /^\/fragments\/projects\/mail\/([a-z0-9_-]+)\/([a-zA-Z0-9_-]+)$/;
+
+/**
+ * The Mailpit URL a `ddev list` row carries, if any.
+ *
+ * https first: it is the same service on the other port, with the certificate DDEV issued.
+ */
+const urlFromListing = (row) => String((row && (row.mailpit_https_url || row.mailpit_url)) || '');
+
+/**
+ * Where a project's mailbox is, given the status map the dashboard already keeps.
+ *
+ * Takes a GETTER rather than the map, because the map is replaced on every refresh — holding the
+ * object would pin whichever one happened to be current when this was wired up. And it is ASYNCHRONOUS,
+ * because straight after a restart that map is empty for a second or two: a synchronous read answers
+ * "this project has no Mailpit — is it running?" about a project that is running perfectly well.
+ * Awaiting the dashboard's own getter refreshes a cold cache first.
+ *
+ * A stopped project answers '': DDEV reports a URL for one (51 of them here), but Mailpit only runs
+ * while the containers do, and a link that cannot answer is worse than none.
+ */
+function mailpitFor(statusMap) {
+  return async (workspace, project) => {
+    try {
+      const dir = workspaceDir(workspace);
+      if (!dir) return '';
+      const st = (await statusMap()) || {};
+      const projectPath = path.join(dir, project);
+      const byPath = st[`@${projectPath}`];
+      const byName = st[ddevProjectName(projectPath)];
+      // The same rule the row's status uses: an entry whose approot is some other directory is a
+      // stale registration, not this project.
+      const entry = byPath || (byName && (!byName.approot || byName.approot === projectPath) ? byName : null);
+      return entry && entry.status === 'running' ? (entry.mailpit || '') : '';
+    } catch (_) {
+      return '';
+    }
+  };
+}
+
+/**
+ * The DDEV-menu entry, or '' when there is no mailbox to open.
+ *
+ * DDEV captures every mail a project sends rather than delivering it, and Mailpit holds them on the
+ * project's own hostname — so a site that "sends no email" locally has almost always sent them all,
+ * into here. The URL costs nothing to know, because the 20-second status refresh already carries it.
+ */
+function menuItemHtml({ workspace, project, running, mailpit }) {
+  if (!running || !mailpit) return '';
+  return `<li><a href hx-get="/fragments/projects/mail/${encodeURIComponent(workspace)}/${encodeURIComponent(project)}"
+      hx-target="#editor-modal-body" hx-swap="innerHTML"
+      hx-on::after:request="UIkit.modal('#editor-modal').show()"
+      title="Every mail this project sends is captured rather than delivered — read, search and clear it"><span uk-icon="icon: mail; ratio: .7"></span> Mail it captured (Mailpit)…</a></li>`;
+}
+
+/**
+ * The fragment route. Returns true when it answered, false when the path was not ours — so the
+ * server's chain asks one question rather than carrying the whole branch.
+ */
+async function handleFragment({ pathname, req, res, isValidWorkspace, mailpit }) {
+  const m = FRAGMENT_RE.exec(pathname);
+  if (!m || !isValidWorkspace(m[1]) || !NAME_RE.test(m[2])) return false;
+  const q = new URL(req.url, 'http://localhost').searchParams.get('q') || '';
+  const html = await mailPanelHtml({ workspace: m[1], project: m[2], base: await mailpit(m[1], m[2]), q });
+  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
+  res.end(html);
+  return true;
+}
+
+const SHOW = 25;
+
+async function mailPanelHtml({ workspace, project, base, q = '' }) {
+  const panelUrl = `/fragments/projects/mail/${encodeURIComponent(workspace)}/${encodeURIComponent(project)}`;
+  const vals = (extra) => esc(JSON.stringify({ workspace, projectName: project, ...extra }));
+  const info = await mail.mailInfo(base);
+
+  // Mailpit not answering is not an empty mailbox, and saying so is the whole reason this panel is
+  // worth more than a link: "no mail" would send somebody looking for a bug in their site.
+  if (!info.ok) {
+    return `
+    <div class="editor-card">
+      <h3 class="uk-margin-small-bottom">Mail from ${esc(project)}</h3>
+      <div class="msg error">Mailpit is not answering: ${esc(info.error)}.
+        <p class="uk-text-meta">It runs with the project, so start the project and try again. This is not the same as
+          an empty mailbox — nothing here says whether the site sent anything.</p></div>
+    </div>`;
+  }
+
+  const listed = await mail.mailList(base, { limit: SHOW, query: q });
+  const messages = listed.ok ? listed.messages : [];
+  const rows = messages.map((m) => `
+    <li class="${m.read ? '' : 'mail-unread'}">
+      <div class="mail-line">
+        <a class="mail-subject" href="${esc(mail.messageUrl(base, m.id))}" target="_blank" rel="noopener"
+           title="Open this message in Mailpit">${m.read ? '' : '<span class="mail-dot" aria-label="unread">●</span> '}${esc(m.subject)}</a>
+        <span class="uk-text-meta mail-meta">${esc(m.created ? humanTime(m.created) : '')} · ${esc(humanSize(m.size))}${
+  m.attachments ? ` · ${m.attachments} attachment${m.attachments === 1 ? '' : 's'}` : ''}</span>
+        <span class="mail-actions">
+          <button class="uk-button uk-button-link mail-drop arm-step" title="Delete this message"
+            hx-post="/actions/ddev-mail-delete" hx-vals='${vals({ id: m.id, confirm: 'yes' })}'
+            hx-target="#editor-modal-body" hx-swap="innerHTML" hx-trigger="confirmed-remove">✕</button>
+        </span>
+      </div>
+      <p class="uk-text-meta mail-who">${esc(m.fromName ? `${m.fromName} <${m.from}>` : m.from)} → ${esc(m.to.join(', ') || '(nobody)')}</p>
+    </li>`).join('');
+
+  return `
+    <div class="editor-card">
+      <h3 class="uk-margin-small-bottom">Mail from ${esc(project)}
+        <span class="uk-badge">${info.total}</span>${info.unread ? ` <span class="uk-label uk-label-warning">${info.unread} unread</span>` : ''}</h3>
+      <p class="uk-text-meta">DDEV captures every mail this project sends instead of delivering it, so this is
+        where a password reset, a webform notification or a cron warning actually went. Nothing here has left
+        the machine.</p>
+
+      <div class="mail-tools">
+        <form class="mail-search" hx-get="${esc(panelUrl)}" hx-target="#editor-modal-body" hx-swap="innerHTML"
+              hx-trigger="submit, keyup[key=='Enter'] from:find input">
+          <input class="uk-input uk-form-small" type="search" name="q" value="${esc(q)}"
+                 placeholder="Search subject, address, body…" aria-label="Search this mailbox">
+          <button class="uk-button uk-button-default uk-button-small" type="submit">Search</button>
+          ${q ? `<a class="uk-button uk-button-link uk-button-small" href hx-get="${esc(panelUrl)}" hx-target="#editor-modal-body" hx-swap="innerHTML">clear</a>` : ''}
+        </form>
+        <span class="mail-bulk">
+          ${info.unread ? `<button class="uk-button uk-button-default uk-button-small" hx-post="/actions/ddev-mail-read"
+            hx-vals='${vals({})}' hx-target="#editor-modal-body" hx-swap="innerHTML">Mark all read</button>` : ''}
+          ${info.total ? `<button class="uk-button uk-button-danger uk-button-small arm-step"
+            hx-post="/actions/ddev-mail-clear" hx-vals='${vals({ confirm: 'yes' })}'
+            hx-target="#editor-modal-body" hx-swap="innerHTML" hx-trigger="confirmed-remove"
+            title="Delete every message in this mailbox">Empty the mailbox</button>` : ''}
+          <a class="uk-button uk-button-default uk-button-small" href="${esc(base)}" target="_blank" rel="noopener"
+             title="Mailpit's own interface, which renders a message properly">Open Mailpit</a>
+        </span>
+      </div>
+
+      ${messages.length
+    ? `<ul class="uk-list uk-list-divider mail-list">${rows}</ul>${
+      listed.total > messages.length ? `<p class="uk-text-meta">Showing the newest ${messages.length} of ${listed.total} — the rest are in Mailpit.</p>` : ''}`
+    : q
+      ? `<p class="uk-text-meta">Nothing in this mailbox matches “${esc(q)}”.</p>`
+      : '<p class="uk-text-meta">The mailbox is empty. This project has sent nothing since it was last cleared — which, for a site under test, is worth knowing before you go looking for the mail somewhere else.</p>'}
+    </div>`;
+}
+
+module.exports = { mailPanelHtml, menuItemHtml, handleFragment, mailpitFor, urlFromListing, FRAGMENT_RE, SHOW };

package/ddev-mail.js

@@ -0,0 +1,110 @@
+/**
+ * A project's captured mail, over Mailpit's own API.
+ *
+ * DDEV does not deliver a project's outgoing email — it captures it. Which means Mailpit is not a
+ * curiosity: it is where every password reset, webform notification and cron warning a site "sent"
+ * actually went, and until something reads it, nobody can tell a mail that was never sent from one
+ * that was sent and never looked at.
+ *
+ * The link to Mailpit's own UI stays (it renders a message better than anything here would), but the
+ * things you do REPEATEDLY belong on the row: how many are waiting, what the last ones were, is the
+ * one I just triggered there, and clear them out before a test run.
+ *
+ * Three things shape this module:
+ *
+ *   - **The API is reachable from here.** This container resolves the project hostnames and the
+ *     router terminates their TLS, so `https://<project>.ddev.site:8026/api/v1/…` answers directly —
+ *     no `ddev exec`, no shelling out per request.
+ *   - **Mailpit is only up while the project is.** Every call is given a short timeout and a failure
+ *     is reported as "not answering" rather than as an empty mailbox: an empty inbox and an inbox
+ *     that could not be read are different facts, and only one of them means the mail was not sent.
+ *   - **Nothing is cached.** A mailbox is what you are looking at right now — you trigger a reset
+ *     mail and refresh — so a cache here would only ever be a way of showing yesterday's answer.
+ */
+
+const MAIL_TIMEOUT_MS = 8000;
+
+/** One call to a project's Mailpit, or a reason it could not be made. */
+async function api(base, path, { method = 'GET', body } = {}) {
+  if (!base) return { ok: false, error: 'This project has no Mailpit URL — is it running?' };
+  const url = `${base.replace(/\/$/, '')}/api/v1${path}`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), MAIL_TIMEOUT_MS);
+  try {
+    const res = await fetch(url, {
+      method,
+      signal: controller.signal,
+      headers: body ? { 'Content-Type': 'application/json' } : undefined,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) return { ok: false, error: `Mailpit answered ${res.status}` };
+    const text = (await res.text()).trim();
+    if (!text) return { ok: true, data: null };
+    if (!/^[[{]/.test(text)) return { ok: true, data: text };
+    try {
+      return { ok: true, data: JSON.parse(text) };
+    } catch (_) {
+      return { ok: false, error: 'Mailpit sent something this could not read' };
+    }
+  } catch (err) {
+    // A project that is stopped, a Mailpit that is still starting, a certificate nobody trusts: all
+    // of them are "it did not answer", and none of them is "there is no mail".
+    return { ok: false, error: err.name === 'AbortError' ? 'Mailpit did not answer in time' : String(err.message || err) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** How much is in there: total and unread. */
+async function mailInfo(base) {
+  const r = await api(base, '/info');
+  if (!r.ok) return r;
+  return { ok: true, total: Number(r.data.Messages || 0), unread: Number(r.data.Unread || 0), version: r.data.Version || '' };
+}
+
+/**
+ * The messages themselves, newest first — a search when one was typed, the plain list otherwise.
+ *
+ * Only the fields a list needs are kept. A message's body is one click away in Mailpit, which renders
+ * HTML mail, attachments and the raw source far better than this panel ever would.
+ */
+async function mailList(base, { limit = 25, query = '' } = {}) {
+  const q = String(query || '').trim();
+  const r = q
+    ? await api(base, `/search?query=${encodeURIComponent(q)}&limit=${limit}`)
+    : await api(base, `/messages?limit=${limit}`);
+  if (!r.ok) return r;
+  const messages = (r.data.messages || []).map((m) => ({
+    id: String(m.ID || ''),
+    subject: String(m.Subject || '(no subject)'),
+    from: (m.From && m.From.Address) || '',
+    fromName: (m.From && m.From.Name) || '',
+    to: (m.To || []).map((t) => t.Address).filter(Boolean),
+    created: m.Created ? new Date(m.Created) : null,
+    size: Number(m.Size || 0),
+    read: !!m.Read,
+    attachments: Number(m.Attachments || 0),
+  }));
+  return { ok: true, messages, total: Number(r.data.messages_count ?? r.data.total ?? messages.length) };
+}
+
+/** Everything in the mailbox, gone. The confirm belongs to the caller; this is the call. */
+const deleteAllMail = (base) => api(base, '/messages', { method: 'DELETE' });
+
+/** One message, gone — the id comes from a listing, never from a path. */
+const deleteOneMail = (base, id) => api(base, '/messages', { method: 'DELETE', body: { IDs: [String(id)] } });
+
+/** Everything marked read, which is how you tell the next one apart from all of these. */
+const markAllRead = (base) => api(base, '/messages', { method: 'PUT', body: { Read: true } });
+
+/** Where Mailpit shows one message, for the link out. */
+const messageUrl = (base, id) => `${String(base).replace(/\/$/, '')}/view/${encodeURIComponent(id)}`;
+
+// A Mailpit message id, as its API hands them out: a short URL-safe token. Checked before it is put
+// in a URL or a delete, because it arrives from a browser.
+const MAIL_ID_RE = /^[A-Za-z0-9_-]{6,64}$/;
+
+module.exports = {
+  MAIL_ID_RE, MAIL_TIMEOUT_MS,
+  mailInfo, mailList, deleteAllMail, deleteOneMail, markAllRead, messageUrl,
+};

package/ddev-options.js

@@ -0,0 +1,145 @@
+/**
+ * What `ddev config` accepts, as the DDEV docs list it (docs.ddev.com, users/configuration/config and
+ * users/quickstart, checked against `ddev config --help` on v1.25.4), and the form that offers it.
+ *
+ * Every value is picked from a list, never typed into a shell line.
+ */
+
+const { esc } = require('./html');
+
+const PROJECT_TYPES = ['php', 'generic', 'drupal12', 'drupal11', 'drupal10', 'drupal9', 'drupal8', 'drupal7', 'drupal6', 'drupal',
+  'backdrop', 'wordpress', 'wp-bedrock', 'typo3', 'laravel', 'symfony', 'craftcms', 'shopware6', 'magento2', 'magento', 'maho',
+  'joomla', 'silverstripe', 'cakephp', 'codeigniter', 'modx', 'asterios'];
+
+const PHP_VERSIONS = ['8.5', '8.4', '8.3', '8.2', '8.1', '8.0', '7.4', '7.3', '7.2', '7.1', '7.0', '5.6'];
+
+const range = (a, b) => Array.from({ length: b - a + 1 }, (_, i) => String(b - i));
+const DATABASES = [
+  ...['12.3', '11.8', '11.4', '10.11', '10.8', '10.7', '10.6', '10.5', '10.4', '10.3', '10.2', '10.1', '10.0', '5.5'].map((v) => `mariadb:${v}`),
+  ...['9.7', '8.4', '8.0', '5.7', '5.6', '5.5'].map((v) => `mysql:${v}`),
+  ...range(9, 18).map((v) => `postgres:${v}`),
+];
+
+const WEBSERVERS = ['nginx-fpm', 'apache-fpm', 'generic'];
+// "" uses the version already in the image; auto and engine read it from the project's own files.
+const NODE_VERSIONS = ['24', '22', '20', '18', 'auto', 'engine', ''];
+const COMPOSER_VERSIONS = ['2', '2.2', 'stable', 'preview', 'snapshot', ''];
+// The packages DDEV's own Python quickstart (Wagtail) adds; the version is the one Debian ships in the web image.
+const PYTHON_PACKAGES = 'python3-pip,python3-venv';
+const DOCROOT_RE = /^(?:[a-zA-Z0-9_-]+(?:\/[a-zA-Z0-9_-]+)*)?$/;
+
+const CHOICES = {
+  project_type: PROJECT_TYPES, php_version: PHP_VERSIONS, database: DATABASES,
+  webserver_type: WEBSERVERS, nodejs_version: NODE_VERSIONS, composer_version: COMPOSER_VERSIONS,
+};
+
+// The DDEV quickstarts, with the settings each one's `ddev config` uses. Unset fields keep DDEV's defaults.
+const PRESETS = [
+  { id: 'php', label: 'Plain PHP', project_type: 'php' },
+  { id: 'asterios', label: 'Asterios', project_type: 'asterios', docroot: 'public' },
+  { id: 'backdrop', label: 'Backdrop', project_type: 'backdrop' },
+  { id: 'cakephp', label: 'CakePHP', project_type: 'cakephp', docroot: 'webroot' },
+  { id: 'codeigniter', label: 'CodeIgniter', project_type: 'codeigniter', docroot: 'public' },
+  { id: 'contao', label: 'Contao', project_type: 'php', docroot: 'public', php_version: '8.4', webserver_type: 'apache-fpm' },
+  { id: 'craftcms', label: 'Craft CMS', project_type: 'craftcms', docroot: 'web', database: 'mysql:8.0' },
+  { id: 'drupal12', label: 'Drupal 12', project_type: 'drupal12', docroot: 'web' },
+  { id: 'drupal11', label: 'Drupal 11 / Drupal CMS', project_type: 'drupal11', docroot: 'web' },
+  { id: 'drupal10', label: 'Drupal 10', project_type: 'drupal10', docroot: 'web' },
+  { id: 'expressionengine', label: 'ExpressionEngine', project_type: 'php', database: 'mysql:8.0' },
+  { id: 'grav', label: 'Grav', project_type: 'php', php_version: '8.3', omit_db: true },
+  { id: 'ibexa', label: 'Ibexa DXP', project_type: 'php', docroot: 'public' },
+  { id: 'joomla', label: 'Joomla', project_type: 'joomla' },
+  { id: 'kirby', label: 'Kirby CMS', project_type: 'php', webserver_type: 'apache-fpm', omit_db: true },
+  { id: 'laravel', label: 'Laravel', project_type: 'laravel', docroot: 'public' },
+  { id: 'magento2', label: 'Magento 2', project_type: 'magento2', docroot: 'pub' },
+  { id: 'maho', label: 'Maho', project_type: 'maho', docroot: 'public' },
+  { id: 'modx', label: 'MODX Revolution', project_type: 'modx' },
+  { id: 'moodle', label: 'Moodle', project_type: 'php', docroot: 'public', webserver_type: 'apache-fpm' },
+  { id: 'nodejs', label: 'Node.js (Express, SvelteKit)', project_type: 'generic', webserver_type: 'generic' },
+  { id: 'openmage', label: 'OpenMage', project_type: 'magento', php_version: '8.1' },
+  { id: 'october', label: 'October CMS', project_type: 'laravel', webserver_type: 'apache-fpm' },
+  { id: 'pimcore', label: 'Pimcore', project_type: 'php', docroot: 'public' },
+  { id: 'processwire', label: 'ProcessWire', project_type: 'php', webserver_type: 'apache-fpm' },
+  { id: 'shopware6', label: 'Shopware 6', project_type: 'shopware6', docroot: 'public' },
+  { id: 'silverstripe', label: 'Silverstripe', project_type: 'silverstripe', docroot: 'public' },
+  { id: 'statamic', label: 'Statamic', project_type: 'laravel', docroot: 'public' },
+  { id: 'sulu', label: 'Sulu', project_type: 'php', docroot: 'public', database: 'mysql:8.0' },
+  { id: 'symfony', label: 'Symfony', project_type: 'symfony', docroot: 'public' },
+  { id: 'tempest', label: 'Tempest', project_type: 'php', docroot: 'public', php_version: '8.5', omit_db: true },
+  { id: 'typo3', label: 'TYPO3', project_type: 'typo3', docroot: 'public' },
+  { id: 'wagtail', label: 'Wagtail (Python)', project_type: 'generic', webserver_type: 'generic', python: true, omit_db: true },
+  { id: 'wordpress', label: 'WordPress', project_type: 'wordpress' },
+  { id: 'wp-bedrock', label: 'WordPress (Bedrock)', project_type: 'wp-bedrock' },
+];
+
+/** The `ddev config` flags a form asks for, each checked against the lists above. Unchosen values are left to DDEV. */
+function configArgs(form) {
+  const args = [];
+  const pick = (field, flag) => {
+    const v = form[field];
+    if (v === undefined || v === null || v === '__default') return;
+    if (CHOICES[field].includes(String(v))) args.push(`${flag}=${String(v)}`);
+  };
+  pick('project_type', '--project-type');
+  const docroot = String(form.docroot === undefined ? '' : form.docroot).trim();
+  if (form.docroot !== undefined && DOCROOT_RE.test(docroot) && !docroot.split('/').includes('..')) args.push(`--docroot=${docroot}`);
+  pick('php_version', '--php-version');
+  pick('database', '--database');
+  pick('webserver_type', '--webserver-type');
+  pick('nodejs_version', '--nodejs-version');
+  pick('composer_version', '--composer-version');
+  if (form.omit_db === '1') args.push('--omit-containers=db');
+  if (form.python === '1') args.push(`--webimage-extra-packages=${PYTHON_PACKAGES}`);
+  return args;
+}
+
+/** Shell-quote each argument, for a line run in a screen session. */
+function shellArgs(args) {
+  return args.map((a) => `'${a.replace(/'/g, `'\\''`)}'`).join(' ');
+}
+
+/**
+ * The fields, for a form. `current` holds the values a project already has (Configure DDEV on an existing
+ * project); a field with no current value starts on "DDEV's default", so nothing is changed unasked.
+ */
+function fieldsHtml({ current = {}, prefix = 'ddev' } = {}) {
+  const sel = (name, label, values, hint, def = '__default') => {
+    const now = current[name] !== undefined ? String(current[name]) : def;
+    const opts = [`<option value="__default"${now === '__default' ? ' selected' : ''}>DDEV's default</option>`]
+      .concat(values.map((v) => `<option value="${esc(v)}"${now === v ? ' selected' : ''}>${esc(v === '' ? '(empty: what the image has)' : v)}</option>`));
+    return `<div><label class="uk-form-label" for="${prefix}-${name}">${esc(label)}</label>
+        <select class="uk-select uk-form-small" id="${prefix}-${name}" name="${name}">${opts.join('')}</select>
+        <div class="uk-text-meta">${hint}</div></div>`;
+  };
+  const presetOpts = PRESETS.map((p) => {
+    const data = ['project_type', 'docroot', 'php_version', 'database', 'webserver_type']
+      .map((k) => `data-${k.replace(/_/g, '-')}="${esc(p[k] === undefined ? '__default' : p[k])}"`).join(' ');
+    return `<option value="${esc(p.id)}" ${data} data-omit-db="${p.omit_db ? 1 : 0}" data-python="${p.python ? 1 : 0}">${esc(p.label)}</option>`;
+  }).join('');
+  return `
+      <div class="ddev-options">
+        <label class="uk-form-label" for="${prefix}-preset">Start from a DDEV quickstart <span class="uk-text-meta">(fills the fields below; change any of them)</span></label>
+        <select class="uk-select uk-form-small uk-margin-small-bottom" id="${prefix}-preset" data-ddev-preset>
+          <option value="">Choose…</option>${presetOpts}
+        </select>
+        <div class="uk-grid-small uk-child-width-1-2@m" uk-grid>
+          ${sel('project_type', 'Project type', PROJECT_TYPES, 'What DDEV configures the container for.', current.project_type ? current.project_type : 'php')}
+          <div><label class="uk-form-label" for="${prefix}-docroot">Docroot</label>
+            <input class="uk-input uk-form-small" id="${prefix}-docroot" name="docroot" value="${esc(current.docroot || '')}"
+                   pattern="[a-zA-Z0-9_/-]*" maxlength="80" placeholder="(the folder itself)">
+            <div class="uk-text-meta">The folder the web server serves, like <code>web</code> or <code>public</code>.</div></div>
+          ${sel('php_version', 'PHP version', PHP_VERSIONS, 'In the web container.')}
+          ${sel('database', 'Database', DATABASES, 'Engine and version; the volume is made on first start.')}
+          ${sel('webserver_type', 'Web server', WEBSERVERS, '<code>generic</code> runs your own server, for Node.js or Python.')}
+          ${sel('nodejs_version', 'Node.js version', NODE_VERSIONS, '<code>auto</code> reads it from the project, like <code>.nvmrc</code>.')}
+          ${sel('composer_version', 'Composer version', COMPOSER_VERSIONS, 'Composer 2 unless the project needs another.')}
+          <div><span class="uk-form-label">Extras</span>
+            <label class="uk-display-block"><input class="uk-checkbox" type="checkbox" name="omit_db" value="1"${current.omit_db ? ' checked' : ''}> No database container</label>
+            <label class="uk-display-block"><input class="uk-checkbox" type="checkbox" name="python" value="1"${current.python ? ' checked' : ''}> Python (pip and venv) in the web container</label>
+            <div class="uk-text-meta">DDEV has no Python version setting; this is the Python the web image ships.</div></div>
+        </div>
+      </div>`;
+}
+
+module.exports = { PROJECT_TYPES, PHP_VERSIONS, DATABASES, WEBSERVERS, NODE_VERSIONS, COMPOSER_VERSIONS, PRESETS, CHOICES,
+  PYTHON_PACKAGES, configArgs, shellArgs, fieldsHtml };

package/ddev-snapshots.js

@@ -0,0 +1,126 @@
+/**
+ * A project's database snapshots: what there is, and what can be done with one.
+ *
+ * The row could already TAKE a snapshot and never do anything else with it — no list, no restore, no
+ * way to remove one. A backup you cannot restore is a file, and the whole reason snapshots exist is
+ * that restoring one is fast: they are a physical copy of the database's own files (mariabackup /
+ * xtrabackup, or pg_basebackup), not a SQL dump replayed statement by statement.
+ *
+ * Two facts about them shape everything here, and both come from DDEV's own documentation:
+ *
+ *   - **A snapshot belongs to a database engine and version.** The file is named
+ *     `<name>-<engine>_<version>.zst`, and a `mariadb_11.8` snapshot does not restore into a
+ *     `mariadb_10.11` project. So the version is listed beside every one: it is the difference
+ *     between a restore and an error nobody expected.
+ *   - **Restoring replaces the database.** There is no merge and no undo, which is why it is behind
+ *     the confirm dialog like the other things here that cannot be taken back.
+ *
+ * They are read from `.ddev/db_snapshots/` rather than from `ddev snapshot --list`: it is the same
+ * answer, and a project row must not cost a subprocess to draw.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// `<name>-<engine>_<version>` plus the compression's extension, which is how DDEV writes them. The
+// engine and version are part of the FILE name rather than metadata beside it, which is what makes
+// listing them a readdir.
+const SNAPSHOT_FILE_RE = /^(.+)-([a-z]+)_([0-9.]+)(\.zst|\.gz|\.tgz)?$/i;
+
+// What may be typed into the name box. DDEV puts the name straight into a filename, so a path
+// separator or a leading dot in it is a file somewhere else.
+const SNAPSHOT_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,60}$/;
+
+const snapshotDir = (projectDir) => path.join(projectDir, '.ddev', 'db_snapshots');
+
+/**
+ * Every snapshot this project holds, newest first.
+ *
+ * An uncompressed snapshot is a DIRECTORY of the same name shape, so both are listed — the entry
+ * type is what says whether it was compressed, since that is exactly what the extension encodes.
+ */
+function listSnapshots(projectDir) {
+  const dir = snapshotDir(projectDir);
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (_) {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    if (e.name.startsWith('.')) continue;
+    const m = SNAPSHOT_FILE_RE.exec(e.name);
+    if (!m) continue;
+    const full = path.join(dir, e.name);
+    let st;
+    try { st = fs.statSync(full); } catch (_) { continue; }
+    out.push({
+      name: m[1],
+      file: e.name,
+      engine: m[2].toLowerCase(),
+      version: m[3],
+      dbVersion: `${m[2].toLowerCase()}_${m[3]}`,
+      compression: m[4] === '.zst' ? 'zstd' : m[4] ? m[4].replace('.', '') : 'none',
+      size: st.isDirectory() ? dirSize(full) : st.size,
+      mtime: st.mtime,
+    });
+  }
+  return out.sort((a, b) => b.mtime - a.mtime);
+}
+
+/** An uncompressed snapshot is a folder, and its size is what is in it. One level is enough: that is
+ *  how the backup tools write them. */
+function dirSize(dir) {
+  let n = 0;
+  try {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!e.isFile()) continue;
+      try { n += fs.statSync(path.join(dir, e.name)).size; } catch (_) { /* skip */ }
+    }
+  } catch (_) { /* unreadable */ }
+  return n;
+}
+
+/**
+ * Does this project have a snapshot by this name, and what is it?
+ *
+ * The name comes from the browser, so it is matched against what is actually on disk rather than
+ * pasted into a command line — a snapshot that is not there is refused here rather than by ddev,
+ * three seconds later, in a screen session somebody has to open to read.
+ */
+const findSnapshot = (projectDir, name) => listSnapshots(projectDir).find((s) => s.name === name) || null;
+
+/**
+ * Can this snapshot restore into this project as it stands?
+ *
+ * The file names the engine and version it was taken from, and the project's own config names the
+ * one it runs. When they differ DDEV refuses the restore, so the row says so first — with both
+ * versions, because "it did not work" is not the useful half of that sentence.
+ */
+function restorable(snapshot, projectDbVersion) {
+  if (!snapshot) return { ok: false, why: 'No such snapshot.' };
+  if (!projectDbVersion) return { ok: true, why: '' };          // unknown: let DDEV be the judge
+  if (snapshot.dbVersion === projectDbVersion) return { ok: true, why: '' };
+  return { ok: false,
+    why: `This snapshot is ${snapshot.dbVersion} and the project runs ${projectDbVersion}.`
+      + ' A snapshot restores only into the database engine and version it was taken from.' };
+}
+
+/** What the project's `.ddev/config.yaml` says it runs, as `<engine>_<version>`, or ''. */
+function projectDbVersion(projectDir) {
+  let raw = '';
+  try { raw = fs.readFileSync(path.join(projectDir, '.ddev', 'config.yaml'), 'utf8'); } catch (_) { return ''; }
+  // database:
+  //   type: mariadb
+  //   version: "11.8"
+  const block = raw.match(/^database:\s*$([\s\S]*?)(?=^\S|\Z)/m);
+  if (!block) return '';
+  const type = block[1].match(/^\s+type:\s*["']?([a-z]+)["']?\s*$/m);
+  const version = block[1].match(/^\s+version:\s*["']?([0-9.]+)["']?\s*$/m);
+  return type && version ? `${type[1].toLowerCase()}_${version[1]}` : '';
+}
+
+module.exports = {
+  SNAPSHOT_NAME_RE, SNAPSHOT_FILE_RE, snapshotDir, listSnapshots, findSnapshot, restorable, projectDbVersion,
+};