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

package/actions/ddev-addons.js

@@ -0,0 +1,90 @@
+/**
+ * Installing, updating and removing a project's DDEV add-ons.
+ *
+ * All three change what is in `.ddev/` and need a restart before they take effect, and all three can
+ * take a minute on a cold cache — so they run detached in the project's own screen session like the
+ * other long DDEV verbs, and the row's SCREENS group lists them while they work.
+ *
+ * The one thing this module exists to be careful about: `ddev add-on get` accepts a URL or a local
+ * path as readily as a repository, so it is a download-and-run from anywhere. A name that arrives
+ * from a browser is therefore checked against the REGISTRY LISTING — not merely against a pattern —
+ * and when the registry cannot be read nothing is installed at all.
+ */
+
+const path = require('path');
+
+const { esc } = require('../html');
+const { workspaceDir } = require('../workspaces');
+const { ddevProjectName, startInScreen, screenStartedHtml } = require('../jobs');
+const { NAME_RE } = require('../validate');
+const addons = require('../ddev-addons');
+
+// An installed add-on is removed and updated BY NAME (`adminer`), not by repository: that is the name
+// DDEV recorded for it, and the only names accepted are the ones it recorded.
+const INSTALLED_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+async function project(form, workspace) {
+  const projectName = String(form.projectName || '');
+  if (!NAME_RE.test(projectName)) return { error: 'Invalid project name.' };
+  const projectDir = path.join(workspaceDir(workspace), projectName);
+  if (!ddevProjectName(projectDir)) return { error: 'Not a DDEV project.' };
+  return { projectName, projectDir };
+}
+
+async function addon_get({ form, send, workspace }) {
+  const p = await project(form, workspace);
+  if (p.error) return send(`<div class="msg error">${esc(p.error)}</div>`, 400);
+  const repo = String(form.addon || '').trim();
+  // The registry is the allowlist. A repository nobody publishes is not installed from here, and a
+  // registry that could not be read means nothing is installed rather than anything being trusted.
+  const known = await addons.isKnownAddon(repo);
+  if (!known.ok) return send(`<div class="msg error">${esc(known.why)}</div>`, 400);
+  addons.invalidateRegistry();
+  const started = await startInScreen({
+    workspace,
+    project: p.projectName,
+    projectDir: p.projectDir,
+    verb: 'addon-get',
+    cmdLine: `ddev add-on get ${repo} && echo "Installed. Run ddev restart to enable it."`,
+    label: `ddev add-on get ${repo}`,
+  });
+  return send(screenStartedHtml(started, `ddev add-on get ${repo}`, p.projectName),
+    started.ok ? 200 : (started.already ? 409 : 500));
+}
+
+async function addon_verb({ form, send, workspace, pathname }) {
+  const p = await project(form, workspace);
+  if (p.error) return send(`<div class="msg error">${esc(p.error)}</div>`, 400);
+  const name = String(form.addon || '').trim();
+  if (!INSTALLED_NAME_RE.test(name)) return send('<div class="msg error">Invalid add-on name.</div>', 400);
+  // Only what DDEV has actually recorded in this project: removing or updating something that is not
+  // installed is an error worth giving now rather than in a screen session.
+  const installed = addons.installedAddons(p.projectDir);
+  const found = installed.find((a) => a.name === name);
+  if (!found) return send(`<div class="msg error"><strong>${esc(name)}</strong> is not installed in this project.</div>`, 404);
+  const removing = pathname === '/actions/ddev-addon-remove';
+  if (removing && form.confirm !== 'yes') {
+    return send('<div class="msg error">Removing an add-on takes its files out of the project — it needs confirmation.</div>', 400);
+  }
+  addons.invalidateRegistry();
+  const cmdLine = removing
+    ? `ddev add-on remove ${name} && echo "Removed ${name}. Run ddev restart."`
+    : `ddev add-on update ${name} && echo "Updated ${name}. Run ddev restart."`;
+  const started = await startInScreen({
+    workspace,
+    project: p.projectName,
+    projectDir: p.projectDir,
+    verb: removing ? 'addon-remove' : 'addon-update',
+    cmdLine,
+    label: `ddev add-on ${removing ? 'remove' : 'update'} ${name}`,
+  });
+  return send(screenStartedHtml(started, `ddev add-on ${removing ? 'remove' : 'update'} ${name}`, p.projectName),
+    started.ok ? 200 : (started.already ? 409 : 500));
+}
+
+module.exports = {
+  '/actions/ddev-addon-get': addon_get,
+  '/actions/ddev-addon-remove': addon_verb,
+  '/actions/ddev-addon-update': addon_verb,
+  INSTALLED_NAME_RE,
+};

package/actions/ddev-mail.js

@@ -0,0 +1,80 @@
+/**
+ * The three things done to a project's captured mail: mark it read, delete one, empty the mailbox.
+ *
+ * Each answers with the PANEL rather than a toast, because every one of them changes what the panel
+ * says — a delete that leaves the list showing the message it deleted is a control you have to
+ * refresh to believe.
+ *
+ * The Mailpit URL is never taken from the request: it is read from the same DDEV listing the row's
+ * status comes from, so a request can only ever reach the mailbox of the project it named.
+ */
+
+const path = require('path');
+
+const { esc } = require('../html');
+const { workspaceDir } = require('../workspaces');
+const { ddevProjectName } = require('../jobs');
+const { NAME_RE } = require('../validate');
+const mail = require('../ddev-mail');
+const { mailPanelHtml } = require('../ddev-mail-page');
+
+/**
+ * The project a request names, and where its Mailpit is.
+ *
+ * `mailpitFor` is injected by server.js when it merges this map, because the status listing lives
+ * there — this module must not grow its own copy of it, and must not take a URL from a form.
+ */
+async function context(deps, form, workspace) {
+  const projectName = String(form.projectName || '');
+  if (!NAME_RE.test(projectName)) return { error: 'Invalid project name.' };
+  const projectDir = path.join(workspaceDir(workspace), projectName);
+  if (!ddevProjectName(projectDir)) return { error: 'Not a DDEV project.' };
+  const base = await deps.mailpitFor(workspace, projectName);
+  if (!base) return { error: 'This project has no Mailpit — it is probably not running.' };
+  return { projectName, base };
+}
+
+function make(deps) {
+  const panel = (workspace, projectName, base, q = '') =>
+    mailPanelHtml({ workspace, project: projectName, base, q });
+
+  async function mail_read({ form, send, workspace }) {
+    const c = await context(deps, form, workspace);
+    if (c.error) return send(`<div class="msg error">${esc(c.error)}</div>`, 400);
+    const r = await mail.markAllRead(c.base);
+    if (!r.ok) return send(`<div class="msg error">Mailpit did not answer: ${esc(r.error)}</div>`, 502);
+    return send(await panel(workspace, c.projectName, c.base));
+  }
+
+  async function mail_delete({ form, send, workspace }) {
+    const c = await context(deps, form, workspace);
+    if (c.error) return send(`<div class="msg error">${esc(c.error)}</div>`, 400);
+    if (form.confirm !== 'yes') return send('<div class="msg error">Deleting a message needs confirmation.</div>', 400);
+    const id = String(form.id || '');
+    // The id comes from a listing this panel drew, and it goes into a request body — checked against
+    // the shape Mailpit issues rather than passed along.
+    if (!mail.MAIL_ID_RE.test(id)) return send('<div class="msg error">That is not a message id.</div>', 400);
+    const r = await mail.deleteOneMail(c.base, id);
+    if (!r.ok) return send(`<div class="msg error">Mailpit did not answer: ${esc(r.error)}</div>`, 502);
+    return send(await panel(workspace, c.projectName, c.base));
+  }
+
+  async function mail_clear({ form, send, workspace }) {
+    const c = await context(deps, form, workspace);
+    if (c.error) return send(`<div class="msg error">${esc(c.error)}</div>`, 400);
+    // Emptying a mailbox is not undoable, and a mailbox under test is often the evidence somebody is
+    // in the middle of reading.
+    if (form.confirm !== 'yes') return send('<div class="msg error">Emptying the mailbox needs confirmation.</div>', 400);
+    const r = await mail.deleteAllMail(c.base);
+    if (!r.ok) return send(`<div class="msg error">Mailpit did not answer: ${esc(r.error)}</div>`, 502);
+    return send(await panel(workspace, c.projectName, c.base));
+  }
+
+  return {
+    '/actions/ddev-mail-read': mail_read,
+    '/actions/ddev-mail-delete': mail_delete,
+    '/actions/ddev-mail-clear': mail_clear,
+  };
+}
+
+module.exports = { make, context };

package/actions/ddev.js

@@ -0,0 +1,237 @@
+/**
+ * The DDEV verbs a project row offers.
+ *
+ * One module per area of the dashboard, each exporting the handlers it owns keyed by the path that
+ * reaches them. server.js merges the maps and dispatches; nothing here knows about routing, and
+ * adding an action is adding an entry rather than another branch in a 1,250-line function.
+ *
+ * Every handler takes the same context: the parsed form, the response, a `send` that writes an HTML
+ * fragment, and the workspace the request named.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('../html');
+const { humanSize, humanTime } = require('../format');
+const { ROOT, loadWorkspaces, workspaceDir } = require('../workspaces');
+const {
+  run, jobFragment, runningJobKey, startJob, ddevProjectName, listProjects,
+  startInScreen, screenStartedHtml, screenAction,
+} = require('../jobs');
+const { graphStoreDir } = require('../graphs');
+const {
+  milvusProjectName, ragInstances, ragBindings, ragInstanceFor, ragWriteBinding,
+  ragCollectionName, milvusPost, ragCollections, ragInvalidate,
+} = require('../rag');
+const {
+  findTestReports, testReportFor, invalidateTestReports, testMediaHtml, testingStackOf,
+} = require('../test-reports');
+const { NAME_RE, SCRIPT_RE } = require('../validate');
+const { commandBlock } = require('../command-block');
+const { wsUrl } = require('../urls');
+const { findGraphifyScript, findRagifyScript } = require('../workspaces');
+const { DDEV_ACTIONS, projectDdevCommands, serialiseRouter, touchesRouter } = require('../ddev');
+const snapshots = require('../ddev-snapshots');
+const ddevImport = require('../ddev-import');
+
+async function ddev_start({ form, res, send, workspace, pathname }) {
+    const projectName = String(form.projectName || '');
+    if (!NAME_RE.test(projectName)) return send('<div class="msg error">Invalid project name.</div>', 400);
+    const projectDir = path.join(workspaceDir(workspace), projectName);
+    if (!ddevProjectName(projectDir)) return send('<div class="msg error">Not a DDEV project.</div>', 400);
+    const verb = pathname === '/actions/ddev-start' ? 'start' : 'stop';
+    // `ddev start` accepts -y (skip confirmation); `ddev stop` has no such flag.
+    const args = verb === 'start' ? ['start', '-y'] : ['stop'];
+    // Both verbs recreate the shared ddev-router, so they take the router lock: five
+    // concurrent starts is what left the machine with no router and every workspace URL
+    // dead. See serialiseRouter() in ../ddev.js.
+    const cmdLine = serialiseRouter(`ddev ${args.join(' ')}`);
+    const started = await startInScreen({ workspace, project: projectName, projectDir, verb, cmdLine, label: `ddev ${verb}` });
+    return send(screenStartedHtml(started, `ddev ${verb}`, projectName), started.ok ? 200 : (started.already ? 409 : 500));
+}
+
+// Every remaining DDEV verb shares one handler, driven by the table in ddev.js: they differ only
+// in the arguments, the timeout and whether the project has to be running.
+async function ddev_verb({ form, res, send, workspace, pathname }) {
+    const act = DDEV_ACTIONS[pathname];
+    const projectName = String(form.projectName || '');
+    if (!NAME_RE.test(projectName)) return send('<div class="msg error">Invalid project name.</div>', 400);
+    const projectDir = path.join(workspaceDir(workspace), projectName);
+    const ddevName = ddevProjectName(projectDir);
+    if (!ddevName) return send('<div class="msg error">Not a DDEV project.</div>', 400);
+    let args = act.args;
+    // A destructive command is never one click away, and the dashboard is not
+    // the only door — the guard lives here, not only in the markup.
+    if (act.destructive && form.confirm !== 'yes') {
+      return send(`<div class="msg error">${esc(act.label)} ${esc(act.confirmWhy || 'destroys data')} — it needs confirmation.</div>`, 400);
+    }
+    // A verb that takes a snapshot name: the name is checked against what is ON DISK, not merely
+    // against a pattern, so a restore or a delete cannot be asked for something that is not there —
+    // and the answer comes back now rather than from a screen session three seconds later.
+    if (act.named) {
+      const raw = String(form.snapshot || '').trim();
+      if (raw) {
+        if (!snapshots.SNAPSHOT_NAME_RE.test(raw)) {
+          return send('<div class="msg error">A snapshot name starts with a letter or digit and holds letters, digits, dots, dashes and underscores.</div>', 400);
+        }
+        if (pathname === '/actions/ddev-snapshot') {
+          args = [...args, '--name', raw];
+        } else {
+          const found = snapshots.findSnapshot(projectDir, raw);
+          if (!found) return send(`<div class="msg error">No snapshot called <strong>${esc(raw)}</strong> in this project.</div>`, 404);
+          if (pathname === '/actions/ddev-snapshot-restore') {
+            // The engine and version a snapshot was taken from are in its file name, and DDEV will
+            // refuse a restore across them. Saying so here names both versions; ddev's own refusal
+            // arrives inside a screen session somebody has to open to read.
+            const can = snapshots.restorable(found, snapshots.projectDbVersion(projectDir));
+            if (!can.ok) return send(`<div class="msg error">${esc(can.why)}</div>`, 409);
+            // `restore` takes the name as a POSITIONAL argument; `--name` belongs to taking one and
+            // to `--cleanup`. Given the flag, ddev prints its help and the log reads like a crash.
+            args = [...args, raw];
+          } else {
+            args = [...args, '--name', raw];
+          }
+        }
+      } else if (pathname !== '/actions/ddev-snapshot') {
+        return send('<div class="msg error">Name the snapshot.</div>', 400);
+      }
+    }
+    if (act.needsRunning) {
+      // Asked of the project itself rather than the dashboard's status map:
+      // that map lives in server.js, which requires this file — importing it
+      // back would be a cycle, and this is one cheap call on one project.
+      const desc = await run('ddev', ['describe', '--json-output'], projectDir, { timeoutMs: 60 * 1000 });
+      let status = '';
+      try { status = JSON.parse(desc.stdout).raw.status || ''; } catch (_) { status = ''; }
+      if (status !== 'running') {
+        return send(`<div class="msg error">${esc(projectName)} is not running — start it first.</div>`, 400);
+      }
+    }
+    if (act.toBackups) {
+      // A dump belongs in the workspace's backups folder, never in the home directory or
+      // the project itself.
+      const outDir = path.join(loadWorkspaces()[workspace].backupsDir);
+      try { fs.mkdirSync(outDir, { recursive: true }); } catch (_) { /* reported by ddev */ }
+      const stamp = new Date().toISOString().slice(0, 16).replace(/[:T]/g, '-');
+      args = [...args, '--gzip', '--file', path.join(outDir, `${projectName}--db--${stamp}.sql.gz`)];
+    }
+    // Before anything destructive: a dump into the workspace's backups folder.
+    // `sql:drop` leaves nothing behind, so this is the only copy there will be.
+    // && not ; — nothing is dropped unless the dump actually succeeded.
+    let line = `ddev ${args.join(' ')}`;
+    if (act.backupFirst) {
+      const outDir = path.join(loadWorkspaces()[workspace].backupsDir);
+      try { fs.mkdirSync(outDir, { recursive: true }); } catch (_) { /* the session reports it */ }
+      const stamp = new Date().toISOString().slice(0, 16).replace(/[:T]/g, '-');
+      const dump = path.join(outDir, `${projectName}--before-sql-drop--${stamp}.sql.gz`);
+      line = `echo "Backing the database up first…" && ddev export-db --gzip --file ${JSON.stringify(dump)}`
+        + ` && echo "Saved ${dump}" && ${line}`;
+    }
+    // `ddev restart` recreates the router like start and stop do, so it queues with
+    // them rather than racing. The rest (drush, composer, snapshot, logs) leave the
+    // router alone and stay parallel — serialising those would make the dashboard feel
+    // broken for no reason.
+    if (touchesRouter(args)) line = serialiseRouter(line);
+    // Every DDEV command runs detached in a screen named after the project: no
+    // toast to follow the user around, and the row's SCREENS group lists it.
+    const verb = pathname.replace('/actions/ddev-', '');
+    const started = await startInScreen({ workspace, project: projectName, projectDir, verb, cmdLine: line, label: act.label });
+    return send(screenStartedHtml(started, act.label, projectName), started.ok ? 200 : (started.already ? 409 : 500));
+}
+
+/**
+ * Put a database back into a project.
+ *
+ * The dump is named by BASENAME and looked up in the workspace's own backups folder, so no path from
+ * a browser ever reaches a command line. A snapshot is taken first, in the same line with `&&`:
+ * importing replaces every table, and the database it replaces is often the only copy of an
+ * afternoon's work — the same shape `drush sql:drop` already uses before it drops.
+ */
+async function ddev_import_db({ form, send, workspace }) {
+  const projectName = String(form.projectName || '');
+  if (!NAME_RE.test(projectName)) return send('<div class="msg error">Invalid project name.</div>', 400);
+  const projectDir = path.join(workspaceDir(workspace), projectName);
+  if (!ddevProjectName(projectDir)) return send('<div class="msg error">Not a DDEV project.</div>', 400);
+  if (form.confirm !== 'yes') {
+    return send('<div class="msg error">Importing replaces every table in the database — it needs confirmation.</div>', 400);
+  }
+  const backupsDir = loadWorkspaces()[workspace].backupsDir;
+  const dump = ddevImport.findDump(backupsDir, form.dump);
+  if (!dump) return send('<div class="msg error">No such dump in this workspace\'s backups.</div>', 404);
+  const file = path.join(backupsDir, dump.name);
+  const stamp = new Date().toISOString().slice(0, 16).replace(/[:T]/g, '-');
+  const cmdLine = `echo "Taking a snapshot first…" && ddev snapshot --name before-import-${stamp}`
+    + ` && ddev import-db --file ${JSON.stringify(file)}`
+    + ` && echo "Imported ${dump.name}. The database as it was is the snapshot before-import-${stamp}."`;
+  const started = await startInScreen({
+    workspace, project: projectName, projectDir, verb: 'import-db', cmdLine, label: `ddev import-db ${dump.name}`,
+  });
+  return send(screenStartedHtml(started, `ddev import-db ${dump.name}`, projectName),
+    started.ok ? 200 : (started.already ? 409 : 500));
+}
+
+// One of the project's own `.ddev/commands/<service>/*`. The name is checked against
+// what the project actually ships, so only a real command can be run.
+async function ddev_project_command({ form, send, workspace }) {
+  const projectName = String(form.projectName || '');
+  if (!NAME_RE.test(projectName)) return send('<div class="msg error">Invalid project name.</div>', 400);
+  const projectDir = path.join(workspaceDir(workspace), projectName);
+  if (!ddevProjectName(projectDir)) return send('<div class="msg error">Not a DDEV project.</div>', 400);
+  const cmd = String(form.command || '');
+  if (!projectDdevCommands(projectDir).some((c) => c.name === cmd)) return send('<div class="msg error">This project does not ship that command.</div>', 400);
+  const started = await startInScreen({ workspace, project: projectName, projectDir, verb: cmd, cmdLine: `ddev ${cmd}`, label: `ddev ${cmd}` });
+  return send(screenStartedHtml(started, `ddev ${cmd}`, projectName), started.ok ? 200 : (started.already ? 409 : 500));
+}
+
+module.exports = {
+  '/actions/ddev-project-command': ddev_project_command,
+  '/actions/ddev-import-db': ddev_import_db,
+  '/actions/ddev-restart': ddev_verb,
+  '/actions/ddev-describe': ddev_verb,
+  '/actions/ddev-logs': ddev_verb,
+  '/actions/ddev-drush-cr': ddev_verb,
+  '/actions/ddev-drush-uli': ddev_verb,
+  '/actions/ddev-export-db': ddev_verb,
+  '/actions/ddev-mutagen-sync': ddev_verb,
+  '/actions/ddev-xdebug-on': ddev_verb,
+  '/actions/ddev-xdebug-off': ddev_verb,
+  '/actions/ddev-xdebug-status': ddev_verb,
+  '/actions/ddev-auth-ssh': ddev_verb,
+  '/actions/ddev-share': ddev_verb,
+  '/actions/ddev-diagnose': ddev_verb,
+  '/actions/ddev-tls-diagnose': ddev_verb,
+  '/actions/ddev-port-diagnose': ddev_verb,
+  '/actions/ddev-db-match': ddev_verb,
+  '/actions/ddev-mutagen-status': ddev_verb,
+  '/actions/ddev-mutagen-reset': ddev_verb,
+  '/actions/ddev-drush-sql-drop': ddev_verb,
+  '/actions/ddev-snapshot': ddev_verb,
+  '/actions/ddev-snapshot-restore': ddev_verb,
+  '/actions/ddev-snapshot-delete': ddev_verb,
+  '/actions/ddev-drush-status': ddev_verb,
+  '/actions/ddev-drush-cex': ddev_verb,
+  '/actions/ddev-drush-cim': ddev_verb,
+  '/actions/ddev-drush-updb': ddev_verb,
+  '/actions/ddev-composer-update': ddev_verb,
+  '/actions/ddev-composer-install': ddev_verb,
+  '/actions/ddev-start': ddev_start,
+  '/actions/ddev-stop': ddev_start,
+};
+
+// `ddev config` for a folder DDEV does not manage yet, or one it does. Every value is picked from the lists in
+// ddev-options.js (the DDEV docs), so nothing typed reaches the shell line.
+async function ddev_config({ form, send, workspace }) {
+  const dir = workspaceDir(workspace);
+  const projectName = String(form.projectName || '');
+  if (!NAME_RE.test(projectName) || !listProjects(dir).includes(projectName)) {
+    return send('<div class="msg error">Unknown project.</div>', 400);
+  }
+  const opts = require('../ddev-options');
+  const args = ['config', '--auto=false', `--project-name=${projectName}`, ...opts.configArgs(form)];
+  return screenAction(send, { workspace, project: projectName, projectDir: path.join(dir, projectName),
+    verb: 'config', cmdLine: `ddev ${opts.shellArgs(args)}`, label: 'ddev config' });
+}
+
+module.exports['/actions/ddev-config'] = ddev_config;
+module.exports.CONFIG_CHOICES = require('../ddev-options').CHOICES;

package/actions/folders.js

@@ -0,0 +1,165 @@
+/**
+ * Make an empty folder in a workspace, set it up, and optionally open a terminal or Claude Code in it.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('../html');
+const { isValidWorkspace, loadWorkspaces, loadSettings, workspaceDir } = require('../workspaces');
+const folders = require('../folders');
+const notes = require('../notes');
+const { startInScreen, screenStartedHtml } = require('../jobs');
+const { pluginFolderSetups } = require('../plugin-loader');
+
+/** What the plugins get to decide with: the actions this workspace's type allows. */
+const setupCtx = (ws) => { const m = loadWorkspaces()[ws]; return { allowed: (m && m.typeActions) || new Set() }; };
+
+const shq = (v) => `'${String(v).replace(/'/g, `'\\''`)}'`;
+
+/** Whether this workspace offers New folder: project workspaces whose type allows it. */
+function canMakeFolder(ws) {
+  if (!isValidWorkspace(ws)) return false;
+  const meta = loadWorkspaces()[ws];
+  if (!meta || !(meta.typeActions && meta.typeActions.has('folder'))) return false;
+  // A files workspace shows folders only when it is browsable; elsewhere a new folder would be invisible.
+  return meta.kind !== 'files' || require('../files-browser').BROWSABLE.has(ws);
+}
+
+/** Whether the workspace is a files one, where a folder is made inside the folder being viewed. */
+function isFilesWorkspace(ws) {
+  const meta = loadWorkspaces()[ws];
+  return !!meta && meta.kind === 'files';
+}
+
+const ships = (ws, script) => fs.existsSync(path.join(workspaceDir(ws), script));
+const allows = (ws, action) => { const m = loadWorkspaces()[ws]; return !!(m && m.typeActions && m.typeActions.has(action)); };
+
+/** Whether the workspace ships the testing command the webship-js setup runs. */
+function canTest(ws) { return ships(ws, 'cmd-tools-testing.sh'); }
+
+/** DDEV project types the form offers, the same list Configure DDEV uses. */
+function projectTypes() {
+  return require('../ddev-options').PROJECT_TYPES;
+}
+
+/** The setup shell line: DDEV, then the testing stack, then what the plugins add. Each step needs the one before. */
+function setupLine(ws, name, form) {
+  const steps = [];
+  const wantE2e = form.e2e === '1' && canTest(ws);
+  if (form.ddev === '1' || wantE2e) {
+    const opts = require('../ddev-options');
+    const chosen = { docroot: '', ...form };
+    if (!opts.PROJECT_TYPES.includes(String(chosen.project_type))) chosen.project_type = 'php';
+    const args = ['config', '--auto=false', `--project-name=${name}`, ...opts.configArgs(chosen)];
+    steps.push(`( cd ${shq(name)} && ddev ${opts.shellArgs(args)} )`);
+  }
+  if (wantE2e) steps.push(`bash cmd-tools-testing.sh ${shq(name)}`);
+  for (const s of pluginFolderSetups()) if (s.steps) steps.push(...(s.steps(ws, name, form, setupCtx(ws)) || []));
+  return steps.join(' && ');
+}
+
+/** What the Claude Code session is asked to do: the AI tasks the form chose, then the user's own message. */
+function claudePrompt(ws, name, form) {
+  const parts = [];
+  const what = String(form.note || '').trim();
+  for (const s of pluginFolderSetups()) if (s.prompt) parts.push(...(s.prompt(ws, name, form, setupCtx(ws)) || []));
+  const own = String(form.prompt || '').trim();
+  if (own) parts.push(own);
+  return parts.join('\n\n');
+}
+
+/** Why the form cannot be run as sent, or ''. */
+function formProblem(ws, form) {
+  for (const s of pluginFolderSetups()) if (s.problem) { const why = s.problem(ws, form, setupCtx(ws)); if (why) return why; }
+  return '';
+}
+
+/** A folder in a files workspace: inside the folder being viewed, with its note, and nothing else to set up. */
+function filesFolderNew({ ws, form, send, res }) {
+  const where = require('../files-browser').safeSub(ws, String(form.sub || ''));
+  if (!where.ok) return send('<div class="msg error">That folder is not in this workspace.</div>', 400);
+  const name = String(form.name || '').trim();
+  const made = folders.createFolder(where.abs, name, { files: true });
+  if (!made.ok) return send(`<div class="msg error">${made.error}</div>`, made.status);
+  const note = String(form.note || '').trim();
+  if (note) notes.writeNote(made.dir, { title: '', body: note });
+  const shown = [ws, where.rel, name].filter(Boolean).join('/');
+  try { res.setHeader('HX-Trigger', JSON.stringify({ 'refresh-projects': true })); } catch (_) { /* headers already sent */ }
+  return send(`<div class="msg assistant"><p>Made <strong>${esc(shown)}</strong>.</p></div>`);
+}
+
+async function folder_new({ form, send, res }) {
+  const ws = String(form.workspace || '');
+  if (!canMakeFolder(ws)) return send('<div class="msg error">This workspace does not take new folders.</div>', 400);
+  if (isFilesWorkspace(ws)) return filesFolderNew({ ws, form, send, res });
+  const problem = formProblem(ws, form);
+  if (problem) return send(`<div class="msg error">${esc(problem)}</div>`, 400);
+  const name = String(form.name || '').trim();
+  const made = folders.createFolder(workspaceDir(ws), name);
+  if (!made.ok) return send(`<div class="msg error">${made.error}</div>`, made.status);
+
+  const note = String(form.note || '').trim();
+  if (note) notes.writeNote(made.dir, { title: '', body: note });
+
+  let setup = '';
+  const line = setupLine(ws, name, form);
+  if (line) {
+    const label = 'set up the folder';
+    const started = await startInScreen({ workspace: ws, project: name, projectDir: workspaceDir(ws), ownerDir: made.dir,
+      verb: 'setup', cmdLine: line, label });
+    setup = started.ok
+      ? `<p>Setting it up in <code>${esc(started.session)}</code>: <a href="/screens">watch it on Screens</a>.</p>`
+      : screenStartedHtml(started, label, name);
+  }
+
+  // An AI task needs Claude Code, so it is started even when Then said otherwise.
+  const prompt = claudePrompt(ws, name, form);
+  let then = Object.prototype.hasOwnProperty.call(folders.THEN, form.then) ? String(form.then) : 'none';
+  if (prompt && then !== 'claude') then = 'claude';
+  let started = '';
+  const triggers = { 'refresh-projects': true };
+  if (then !== 'none') {
+    let out = null;
+    await require('./screens')['/actions/screen-new']({
+      form: { target: `p:${ws}:${name}`, kind: then, session: then === 'claude' ? 'claude' : 'shell',
+              command: then === 'claude' ? prompt : '' },
+      send: (html, status = 200) => { out = { html, status }; },
+      res,
+    });
+    const session = `${ws}--${name}--${then === 'claude' ? 'claude' : 'shell'}`;
+    started = out && out.status < 400
+      ? `<p>${then === 'claude' ? 'Claude Code is' : 'A terminal is'} running in it as <code>${esc(session)}</code>.
+          <a class="uk-button uk-button-primary uk-button-small" href="/terminal/${encodeURIComponent(session)}" target="_blank" rel="noopener">Open the terminal</a></p>`
+      : `<div class="msg error">The folder is made, but the session did not start.</div>${out ? out.html : ''}`;
+    triggers['screens-changed'] = { session };
+  }
+  try { res.setHeader('HX-Trigger', JSON.stringify(triggers)); } catch (_) { /* headers already sent */ }
+  return send(`<div class="msg assistant">
+      <p>Made <strong>${esc(ws)}/${esc(name)}</strong>. It is listed with the projects, and its Screens, IDE,
+        GIT and command buttons work on it now.</p>${setup.startsWith('<p>') ? setup : ''}${started}</div>${setup.startsWith('<p>') ? '' : setup}`);
+}
+
+/**
+ * The New folder form for a workspace. A files workspace gets the folder being viewed, read from the page address
+ * htmx sends or the last one browsed; a project workspace gets the full form with its setup options.
+ */
+function folderFormFor(ws, req, { readPageState } = {}) {
+  const meta = loadWorkspaces()[ws];
+  if (isFilesWorkspace(ws)) {
+    let sub = '';
+    try { sub = new URL(String(req.headers['hx-current-url'] || ''), 'http://x').searchParams.get('path') || ''; } catch (_) { /* no page address */ }
+    if (!sub && readPageState) sub = readPageState(req, `${ws}/items`).path || '';
+    const where = require('../files-browser').safeSub(ws, sub);
+    return folders.filesFolderFormHtml(ws, { label: meta.label, sub: where.ok ? where.rel : '',
+      suggestion: folders.suggestName(where.ok ? where.abs : meta.dir, 'new-folder-') });
+  }
+  return folders.folderFormHtml(ws, { label: meta.label, suggestion: folders.suggestName(meta.dir),
+    projectTypes: projectTypes(), canTest: canTest(ws),
+    pluginSetups: pluginFolderSetups().map((s) => (s.html ? s.html(ws, setupCtx(ws)) : '')).filter(Boolean).join('') });
+}
+
+module.exports = {
+  '/actions/folder-new': folder_new,
+  canMakeFolder, isFilesWorkspace, folderFormFor, canTest, projectTypes, setupLine, claudePrompt, formProblem,
+};