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

package/actions/claude-session.js

@@ -0,0 +1,104 @@
+/**
+ * Claude Code in a screen session: end it the way a person would, with /exit, and pick the conversation up again
+ * with `claude --resume <id>` in the same folder.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('../html');
+const { hostRunnerUp, hostRunnerRequest } = require('../jobs');
+const { ROOT, isValidWorkspace, workspaceDir } = require('../workspaces');
+const claudeSessions = require('../claude-sessions');
+
+const SESSION_RE = /^[a-z0-9][a-zA-Z0-9_.-]*$/;
+const NAME_RE = /^[a-zA-Z0-9_-]+$/;
+
+/** The folder a session runs in, from the record the runner keeps beside its log. */
+function sessionDir(session) {
+  try {
+    const dir = fs.readFileSync(path.join(ROOT, '.screens', `${session}.cwd`), 'utf8').trim();
+    return dir && dir.startsWith(ROOT) && fs.existsSync(dir) ? dir : '';
+  } catch (_) { return ''; }
+}
+
+/** The newest conversation in a folder that `--resume` can open, or null. */
+function lastConversation(dir) {
+  return claudeSessions.sessionsFor(dir, { limit: 1, resumableOnly: true })[0] || null;
+}
+
+/** Whether a live session is running Claude Code. */
+async function isClaudeSession(session) {
+  const screens = require('../screens');
+  const live = (await screens.listScreens()).filter((s) => s.session === session && !/dead/i.test(s.state || ''));
+  return live.length > 0 && screens.agentSessions(live).has(session);
+}
+
+const resumeButton = (attrs, label = 'Resume it') => `<button type="button" class="uk-button uk-button-primary uk-button-small"
+  hx-post="/actions/claude-resume" hx-vals='${JSON.stringify(attrs)}' hx-target="#webship-workspace-output" hx-swap="innerHTML">${esc(label)}</button>`;
+
+async function claude_exit({ form, send, res }) {
+  const session = String(form.session || '');
+  if (!SESSION_RE.test(session)) return send('<div class="msg error">Not a screen session name.</div>', 400);
+  if (form.confirm !== 'yes') return send('<div class="msg error">Exiting needs confirmation.</div>', 400);
+  if (!(await isClaudeSession(session))) return send(`<div class="msg error">Claude Code is not running in <strong>${esc(session)}</strong>.</div>`, 409);
+  // Typed the way a person types it. Escape first closes a question or menu that is open (the trust prompt of a new
+  // folder, a permission ask), then the command, then Enter on its own, so the prompt does not take it as a paste.
+  const { onHostScreen } = require('./screens');
+  const pause = (ms) => new Promise((r) => setTimeout(r, ms));
+  await onHostScreen(session, ['-S', session, '-X', 'stuff', '\x1b']);
+  await pause(500);
+  const typed = await onHostScreen(session, ['-S', session, '-X', 'stuff', '/exit']);
+  if (typed.ok) await pause(300);
+  const entered = typed.ok ? await onHostScreen(session, ['-S', session, '-X', 'stuff', '\r']) : typed;
+  if (!entered.ok) return send(`<div class="msg error">Could not reach ${esc(session)}: ${esc(String(entered.stderr || entered.stdout).slice(-200))}</div>`, 500);
+  try { res.setHeader('HX-Trigger', JSON.stringify({ 'screens-changed': { session } })); } catch (_) { /* headers already sent */ }
+  return send(`<div class="msg assistant"><p>Sent <code>/exit</code> to Claude Code in <strong>${esc(session)}</strong>. The conversation is kept.</p>
+    <p>${resumeButton({ session })}</p></div>`);
+}
+
+async function claude_resume({ form, send, res }) {
+  let session = String(form.session || '');
+  let dir = '';
+  if (session) {
+    if (!SESSION_RE.test(session)) return send('<div class="msg error">Not a screen session name.</div>', 400);
+    dir = sessionDir(session);
+  } else {
+    const ws = String(form.workspace || '');
+    const project = String(form.project || '');
+    if (!isValidWorkspace(ws) || !NAME_RE.test(project)) return send('<div class="msg error">Unknown project.</div>', 400);
+    dir = path.join(workspaceDir(ws), project);
+    if (!fs.existsSync(dir)) return send('<div class="msg error">No such folder.</div>', 404);
+    session = `${ws}--${project}--claude`.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').slice(0, 60);
+  }
+  if (!dir) return send(`<div class="msg error">The folder of <strong>${esc(session)}</strong> is not known, so there is nothing to resume there.</div>`, 404);
+  const last = lastConversation(dir);
+  if (!last || !claudeSessions.isSessionId(last.id)) return send('<div class="msg error">No Claude Code conversation in this folder to resume.</div>', 404);
+  if (!(await hostRunnerUp())) return send('<div class="msg error">The screen runner on this machine is not up.</div>', 503);
+  const answer = await hostRunnerRequest('start', { session, dir, owner: dir, cmd: `exec claude --resume ${last.id}` });
+  if (!answer) return send('<div class="msg error">The screen runner on this machine is not up.</div>', 503);
+  if (answer.already) return send(`<div class="msg error"><strong>${esc(session)}</strong> is still running. Exit it first, or open it from Screens.</div>`, 409);
+  if (!answer.ok) return send(`<div class="msg error">Could not resume it: ${esc(String(answer.error || '').slice(-200))}</div>`, 500);
+  try { res.setHeader('HX-Trigger', JSON.stringify({ 'screens-changed': { session } })); } catch (_) { /* headers already sent */ }
+  return send(`<div class="msg assistant"><p>Resumed${last.title ? ` <em>${esc(last.title.slice(0, 80))}</em>` : ''} in <strong>${esc(session)}</strong>.</p>
+    <p><a class="uk-button uk-button-primary uk-button-small" href="/terminal/${encodeURIComponent(session)}" target="_blank" rel="noopener">Open the terminal</a></p></div>`);
+}
+
+/** The menu entries for a project's SCREENS menu: exit for each live Claude session, resume when none runs. */
+function menuItems({ ws, project, sessions, agents, dir }) {
+  const live = sessions.filter((s) => agents.has(s.session) && !/dead/i.test(s.state || ''));
+  const exits = live.map((s) => `
+    <li><a href class="arm-step" title="Exit Claude Code in ${esc(s.session)} (/exit)"
+      hx-post="/actions/claude-exit" hx-vals='${JSON.stringify({ session: s.session, confirm: 'yes' })}'
+      hx-trigger="confirmed-remove" hx-target="#webship-workspace-output" hx-swap="innerHTML"><span uk-icon="icon: sign-out; ratio: .7"></span> Exit Claude Code (/exit)</a></li>`);
+  const resume = !live.length && dir && lastConversation(dir) ? `
+    <li><a href title="Resume the last Claude Code conversation in this folder" hx-post="/actions/claude-resume" hx-vals='${JSON.stringify({ workspace: ws, project })}'
+      hx-target="#webship-workspace-output" hx-swap="innerHTML"><span uk-icon="icon: history; ratio: .7"></span> Resume Claude Code</a></li>` : '';
+  return exits.join('') + resume;
+}
+
+module.exports = {
+  '/actions/claude-exit': claude_exit,
+  '/actions/claude-resume': claude_resume,
+  sessionDir, lastConversation, menuItems,
+};

package/actions/commands-center.js

@@ -0,0 +1,258 @@
+/**
+ * The Commands page's writes, and running a command on what it runs on.
+ *
+ * Each form carries the mtime of core/config/commands.yml from when it was drawn, and a write refuses with 409 when
+ * the file changed since, rather than silently writing over another tab or a hand edit. A refused save answers
+ * with the same form holding what was typed, so nothing has to be typed again.
+ *
+ * A command is run by id only: its line comes from the catalog, never from the request. The only things a request
+ * carries into a run are the target it picked — resolved and kept inside its workspace or project — and option
+ * values, each checked against its option. Every value is single-quoted.
+ */
+
+const fs = require('fs');
+
+const { esc } = require('../html');
+const { isValidWorkspace, workspaceDir } = require('../workspaces');
+const { screenStartedHtml, screenSessionName } = require('../jobs');
+const { lingerTail } = require('../linger');
+const { hasOwnGit } = require('../git-info');
+const { startUnlessRunning, terminalLink, isDdevProject, hasComposerJson } = require('./composer');
+const { hasPackageJson } = require('./node');
+const rl = require('../row-layout');
+const cc = require('../commands');
+const cp = require('../commands-page');
+
+const ok = (text) => `<div class="msg assistant">✅ ${text}</div>`;
+const bad = (text) => `<div class="msg error">${text}</div>`;
+const saveError = (err) => (err && err.code === 'CHANGED'
+  ? { code: 409, html: bad('Your commands changed since this page was loaded (another tab, or a hand edit), so nothing was saved. Reload to see them.') }
+  : { code: 500, html: bad(`Could not save: ${esc(String((err && err.message) || err))}`) });
+
+/** A command from the add or edit form. Editing keeps the id and the options (those are changed in Definition). */
+function fromForm(form, old) {
+  const f = (n) => (form[`cc_${n}`] === undefined ? '' : String(form[`cc_${n}`]));
+  const kind = f('kind') === 'script' ? 'script' : 'run';
+  return cc.cleanCommand({
+    id: old ? old.id : f('id').trim(),
+    label: f('label'),
+    group: f('group'),
+    description: f('description'),
+    on: f('on'),
+    when: f('when').trim().split(/\s+/).filter(Boolean),
+    run: kind === 'run' ? f('run') : '',
+    script: kind === 'script' ? f('script') : '',
+    args: kind === 'script' ? f('args') : '',
+    options: old ? old.options : [],
+    confirm: f('confirm') === '1',
+    open: f('open'),
+    tags: f('tags').split(/[\s,]+/).filter(Boolean),
+  }, 'yours');
+}
+
+async function cc_save({ form, send, res }) {
+  const cat = cc.loadCatalog();
+  const scripts = cc.listScripts();
+  const editing = String(form.id || '');
+  const old = editing ? cat.commands.find((c) => c.id === editing) : null;
+  if (editing && !old) return send(`<div id="cc-command">${bad('No such command — it may have been deleted.')} <a href="/commands">Back to the commands</a></div>`, 404);
+  const again = (message, draft, code) => send(old
+    ? cp.commandPageBody(old, { message, draft, scripts })
+    : cp.newPageBody({ scripts, draft, message }), code);
+
+  const e = fromForm(form, old);
+  if (!old) {
+    if (!e.id) {
+      const base = rl.slug(e.label);
+      let id = base;
+      for (let n = 2; cat.commands.some((c) => c.id === id); n += 1) id = `${base}-${n}`;
+      e.id = id;
+    } else if (cat.commands.some((c) => c.id === e.id)) {
+      return again(bad(`There is already a command with the id ${esc(e.id)} — pick another, or edit that one.`), e, 409);
+    }
+  }
+  const why = cc.commandRefusal(e);
+  if (why) return again(bad(`Not saved: ${esc(why)}.`), e, 400);
+
+  const list = cat.yours.slice();
+  const at = list.findIndex((c) => c.id === e.id);
+  if (at >= 0) list[at] = e; else list.push(e);
+  try { cc.saveYourCommands(list, form.mtime); } catch (err) {
+    const { code, html } = saveError(err);
+    return again(html, e, code);
+  }
+  if (res) res.setHeader('HX-Trigger', 'refresh-projects');
+  const saved = cc.findCommand(e.id);
+  const changedBuiltin = cat.builtin.some((c) => c.id === e.id);
+  return send(cp.commandPageBody(saved, { scripts,
+    message: ok(`${old ? 'Saved' : 'Added'} <strong>${esc(saved.label)}</strong>${changedBuiltin ? ' — your version of a built-in command' : ''}.`
+      + `${old ? '' : ` Its page is <a href="/commands/c/${encodeURIComponent(saved.id)}">/commands/c/${esc(saved.id)}</a>.`}`) }));
+}
+
+async function cc_copy({ form, send, res }) {
+  const fromPage = form.from === 'page';
+  const cat = cc.loadCatalog();
+  const src = cat.commands.find((c) => c.id === String(form.id || ''));
+  if (!src) return send(fromPage ? `<div id="cc-command">${bad('No such command.')} <a href="/commands">Back to the commands</a></div>` : bad('No such command.'), 404);
+  const base = `${src.id.slice(0, 38)}-copy`;
+  let id = base;
+  for (let n = 2; cat.commands.some((c) => c.id === id); n += 1) id = `${base}-${n}`;
+  const copy = { ...src, id, label: `${src.label.slice(0, 55)} copy`, source: 'yours', overrides: undefined };
+  const why = cc.commandRefusal(copy);
+  if (why) return send(bad(`Not copied: ${esc(why)}.`), 400);
+  try { cc.saveYourCommands([...cat.yours, copy], form.mtime); } catch (err) {
+    const { code, html } = saveError(err);
+    return send(fromPage ? cp.commandPageBody(src, { message: html, scripts: cc.listScripts() }) : html, code);
+  }
+  if (res) res.setHeader('HX-Trigger', 'refresh-projects');
+  const saved = cc.findCommand(id);
+  if (fromPage) return send(cp.commandPageBody(saved, { scripts: cc.listScripts(), message: ok(`This is the copy, <strong>${esc(saved.label)}</strong> — change it below.`) }));
+  return send(ok(`Copied to <strong>${esc(saved.label)}</strong>. <a href="/commands/c/${encodeURIComponent(id)}">Open the copy</a> to change it.`));
+}
+
+async function cc_remove({ form, send, res }) {
+  const fromPage = form.from === 'page';
+  const cat = cc.loadCatalog();
+  const id = String(form.id || '');
+  const fail = (html, code) => send(fromPage ? `<div id="cc-command">${html} <a href="/commands">Back to the commands</a></div>` : html, code);
+  if (!cat.yours.some((c) => c.id === id)) {
+    return fail(bad(cat.builtin.some((c) => c.id === id)
+      ? 'A built-in command cannot be deleted. Copy it and change the copy, or hide it from its button in Buttons.'
+      : 'No such command of yours — it may have been deleted already.'), 404);
+  }
+  // Deleting yours of a built-in id leaves the built-in one, so only a command of yours alone is refused while a button uses it.
+  const by = cat.builtin.some((c) => c.id === id) ? [] : cc.usedBy(id);
+  if (by.length) {
+    return fail(bad(`${esc(cat.yours.find((c) => c.id === id).label)} is on ${by.length === 1 ? 'a button' : `${by.length} buttons`}: `
+      + `${esc(cc.describeUses(by))}. Take it off in Buttons first, then delete it.`), 409);
+  }
+  try { cc.saveYourCommands(cat.yours.filter((c) => c.id !== id), form.mtime); } catch (err) {
+    const { code, html } = saveError(err);
+    return fail(html, code);
+  }
+  if (res) res.setHeader('HX-Trigger', 'refresh-projects');
+  const builtin = cc.findCommand(id);
+  if (fromPage) {
+    return send(builtin
+      ? cp.commandPageBody(builtin, { scripts: cc.listScripts(), message: ok('Yours is deleted: this is the built-in command again.') })
+      : `<div id="cc-command">${ok('Command deleted.')} <a href="/commands">Back to the commands</a></div>`);
+  }
+  return send(ok(builtin ? `Yours is deleted: <strong>${esc(builtin.label)}</strong> is the built-in command again.` : 'Command deleted.'));
+}
+
+async function cc_run({ form, send }) {
+  const e = cc.findCommand(form.id);
+  if (!e) return send(bad('No such command — it may have been deleted.'), 404);
+  const why = cc.commandRefusal(e);
+  if (why) return send(bad(`Not running ${esc(e.label)}: ${esc(why)}.`), 400);
+  const t = cc.resolveTarget(e, form);
+  if (t.error) return send(bad(`Not running ${esc(e.label)}: ${esc(t.error)}`), 400);
+  const ctx = { key: t.ws, isDdev: isDdevProject(t.base), hasComposer: hasComposerJson(t.base), hasNode: hasPackageJson(t.base), hasGit: hasOwnGit(t.base) };
+  if (!rl.whenMatches(e.when, ctx)) return send(bad(`${esc(e.label)} is only for ${esc(rl.describeWhen(e.when))}, and ${esc(t.name)} is not.`), 400);
+
+  let cwd = t.cwd;
+  if (e.script) {
+    const m = cc.SCRIPT_REF_RE.exec(e.script);
+    if (m[1] !== 'commands' && !isValidWorkspace(m[1])) return send(bad(`Not running ${esc(e.label)}: there is no ${esc(m[1])} workspace.`), 400);
+    const file = cc.scriptPath(e);
+    if (!fs.existsSync(file)) return send(bad(`Not running ${esc(e.label)}: ${esc(e.script)} does not exist.`), 404);
+    // A script runs from its own folder, the way it runs from a terminal; the target reaches it through its arguments.
+    cwd = m[1] === 'commands' ? require('path').dirname(file) : workspaceDir(m[1]);
+  }
+  if (e.options.length && form.submitted !== '1') {
+    return send(bad(`${esc(e.label)} asks for ${e.options.length === 1 ? 'an option' : 'options'} — run it from its form.`), 400);
+  }
+  const { values, error } = rl.resolveOptions(e, form);
+  if (error) return send(bad(`Not running ${esc(e.label)}: ${esc(error)}.`), 400);
+
+  const verb = `cmd-${e.id}`;
+  const project = t.project || t.ws;
+  // The last run of this command here is about to have its log truncated: write down how it ended first.
+  rl.settleRun(screenSessionName(project, verb, t.ws));
+  const started = await startUnlessRunning({ workspace: t.ws, project, projectDir: cwd, ownerDir: t.base, verb,
+    cmdLine: `${cc.commandLine(e, t.vars, values)}; ${lingerTail(e.label)}`, label: e.label });
+  if (started.stillRunning) {
+    return send(bad(`<code>${esc(e.label)}</code> is still running on <strong>${esc(t.name)}</strong> — ${terminalLink(started.session, 'open it')}. Left alone.`), 409);
+  }
+  if (!started.ok) return send(screenStartedHtml(started, e.label, t.name), started.already ? 409 : 500);
+  rl.recordRun({ at: new Date().toISOString(), id: `command:${e.id}`, label: e.label, workspace: t.ws, project: t.where || '.', session: started.session });
+
+  if (e.open === 'screen') {
+    return send(`<div hidden hx-get="/fragments/screen-term/${encodeURIComponent(started.session)}" hx-trigger="load" hx-target="#editor-modal-body" hx-swap="innerHTML"
+      hx-on::after:request="UIkit.modal('#editor-modal').show()"></div>`);
+  }
+  return send(`<div class="msg assistant flash-now"><code>${esc(e.label)}</code> on <strong>${esc(t.name)}</strong> — ${terminalLink(started.session, 'open the output')}</div>`);
+}
+
+/** Put a command on a button: an action there whose one step uses it, with the command's node filter. */
+async function cc_add_to_button({ form, send }) {
+  const cmd = cc.findCommand(form.id);
+  if (!cmd) return send(`<div id="cc-command">${bad('No such command — it may have been deleted.')} <a href="/commands">Back to the commands</a></div>`, 404);
+  const scripts = cc.listScripts();
+  const again = (message, code) => send(cp.commandPageBody(cmd, { message, scripts }), code);
+  const layout = rl.loadRowLayoutFresh();
+  const label = String(form.label || '').trim() || cmd.label;
+  const taken = new Set(layout.custom.map((c) => c.id));
+  const base = rl.slug(label);
+  let id = base;
+  for (let n = 2; taken.has(id); n += 1) id = `${base}-${n}`;
+  const entry = rl.cleanCustom({ id, label, button: String(form.button || ''), group: String(form.group || '').trim() || cmd.group,
+    description: cmd.description, when: cmd.when, confirm: cmd.confirm, open: cmd.open, steps: [{ use: cmd.id }] });
+  const why = rl.customRefusal(entry) || rl.useRefusal(entry);
+  if (why) return again(bad(`Not added: ${esc(why)}.`), 400);
+  const doc = rl.toDoc(layout);
+  doc.custom.push(rl.customToDoc(entry));
+  try { rl.saveRowLayout(rl.normalizeLayout(doc), form.mtime); } catch (err) {
+    return again(bad(err && err.code === 'CHANGED'
+      ? 'The buttons changed since this page was loaded (another tab, or a hand edit), so nothing was added. Reload to see them.'
+      : `Could not save: ${esc(String((err && err.message) || err))}`), err && err.code === 'CHANGED' ? 409 : 500);
+  }
+  return again(ok(`Added to ${esc(rl.buttonLabel(entry.button))} → ${esc(entry.group)} as <strong>${esc(label)}</strong>. Reload a workspace page to see it.`));
+}
+
+function reportHtml(report) {
+  return `${report.errors.map((x) => bad(esc(x))).join('')}${report.notes.length
+    ? `<div class="msg assistant">${report.errors.length ? '' : '✅ '}${report.notes.map(esc).join(' ')}</div>` : ''}`;
+}
+
+async function cc_definition_check({ form, send }) {
+  const report = cc.checkDefinition(form.definition);
+  if (!report.errors.length) report.notes.unshift('It loads cleanly.');
+  return send(reportHtml(report), report.errors.length ? 400 : 200);
+}
+
+async function cc_definition_save({ form, send }) {
+  const report = cc.checkDefinition(form.definition);
+  if (report.errors.length) {
+    return send(cp.definitionBody({ message: `${bad('Nothing was saved:')}${reportHtml(report)}`, draft: String(form.definition || '') }), 400);
+  }
+  try { cc.saveYourCommands(report.next, form.mtime); } catch (err) {
+    const { code, html } = saveError(err);
+    return send(cp.definitionBody({ message: html, draft: String(form.definition || '') }), code);
+  }
+  return send(cp.definitionBody({ message: ok(`Saved. ${report.notes.map(esc).join(' ')}`) }));
+}
+
+async function cc_reset({ form, send }) {
+  const cat = cc.loadCatalog();
+  const used = cat.yours.filter((c) => !cat.builtin.some((b) => b.id === c.id)).map((c) => ({ c, by: cc.usedBy(c.id) })).filter((x) => x.by.length);
+  if (used.length) {
+    return send(cp.definitionBody({ message: bad(`Nothing was removed: ${used.map((x) => `${esc(x.c.id)} is used by ${esc(cc.describeUses(x.by))}`).join('; ')}. Take those off their buttons first.`) }), 409);
+  }
+  try { cc.saveYourCommands([], form.mtime); } catch (err) {
+    const { code, html } = saveError(err);
+    return send(cp.definitionBody({ message: html }), code);
+  }
+  return send(cp.definitionBody({ message: ok('Every command of yours is removed; the built-in commands are as shipped.') }));
+}
+
+module.exports = {
+  '/actions/cc-save': cc_save,
+  '/actions/cc-copy': cc_copy,
+  '/actions/cc-remove': cc_remove,
+  '/actions/cc-run': cc_run,
+  '/actions/cc-definition-check': cc_definition_check,
+  '/actions/cc-definition-save': cc_definition_save,
+  '/actions/cc-reset': cc_reset,
+  '/actions/cc-add-to-button': cc_add_to_button,
+};

package/actions/composer.js

@@ -0,0 +1,267 @@
+/**
+ * The COMPOSER menu on a project row: composer commands for any folder with a composer.json.
+ *
+ * Every command runs in a SCREEN SESSION, like the DDEV menu's "Composer update", and the page
+ * shows only the toast at the top that links to it. The session stays open after the output,
+ * waiting for Enter, and closes by itself after 15 minutes — `composer validate` is over before
+ * anyone could open it otherwise.
+ *
+ * DDEV only, and there are two ways to be inside DDEV:
+ *
+ *   - A DDEV project runs `ddev composer`, in that project's own web container.
+ *   - A folder that is not a DDEV project (a library, a module clone in products/) runs composer in
+ *     the DASHBOARD's DDEV container, which bind-mounts ~/workspace at the same path: `ddev exec -d
+ *     <folder> composer`. There is no host composer to fall back on, and there must not be.
+ *
+ * Four kinds of entry: inspect (read-only), change (install, update…), one package (require,
+ * remove, why…, from a field) and the project's OWN scripts from composer.json, with their aliases.
+ * The handler runs only what these tables name, a package that looks like a package, and a script
+ * the folder's composer.json actually declares — so a hand-built request cannot run anything else.
+ *
+ * The full menu is only for the SITE workspaces — dev, test, demos, sandboxes, projects — which set
+ * `composer: full` in their own settings file. Everywhere else (products, modules, themes, recipes,
+ * profiles, and any workspace that says nothing) the mode is `manifest`: the menu only ADDS to
+ * composer.json without running an install — require / require --dev / remove with --no-update, which
+ * write composer.json and nothing else — plus validate. No install, no update, and scripts only in a DDEV
+ * folder that has a composer.lock (the DDEV menu lists them). Manifest is
+ * the default so that a new workspace never installs by accident, and the handler enforces the same
+ * list, so a hand-built request cannot install there either.
+ *
+ * A second click on a command whose session is still open replaces it only when that session has
+ * FINISHED (its log ends with the "Press Enter" line). One still running is left alone and the
+ * toast links to it: a `composer update` is minutes of work, and a click must never kill it.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('../html');
+const { ROOT, workspaceDir, loadWorkspaces } = require('../workspaces');
+const { startInScreen, screenStartedHtml, hostRunnerRequest } = require('../jobs');
+const { NAME_RE } = require('../validate');
+const { lingerTail, LINGER_MARK } = require('../linger');
+
+// In the order people reach for them: what is run every day first, then looking around, then the rare ones.
+const COMPOSER_RUN_ACTIONS = {
+  '/actions/composer-install':        { group: 'Daily',       label: 'composer install',             args: ['install'] },
+  '/actions/composer-update':         { group: 'Daily',       label: 'composer update',              args: ['update'] },
+  '/actions/composer-outdated':       { group: 'Daily',       label: 'composer outdated --direct',   args: ['outdated', '--direct'] },
+  '/actions/composer-validate':       { group: 'Daily',       label: 'composer validate',            args: ['validate', '--no-check-publish'], manifest: true },
+  '/actions/composer-update-dry-run': { group: 'Inspect',     label: 'composer update --dry-run',    args: ['update', '--dry-run'] },
+  '/actions/composer-show':           { group: 'Inspect',     label: 'composer show --direct',       args: ['show', '--direct'] },
+  '/actions/composer-show-tree':      { group: 'Inspect',     label: 'composer show --tree',         args: ['show', '--tree'] },
+  '/actions/composer-audit':          { group: 'Inspect',     label: 'composer audit',               args: ['audit'] },
+  '/actions/composer-platform':       { group: 'Inspect',     label: 'composer check-platform-reqs', args: ['check-platform-reqs'] },
+  '/actions/composer-licenses':       { group: 'Inspect',     label: 'composer licenses',            args: ['licenses'] },
+  '/actions/composer-update-lock':    { group: 'Maintenance', label: 'composer update --lock',       args: ['update', '--lock'] },
+  '/actions/composer-dump-autoload':  { group: 'Maintenance', label: 'composer dump-autoload -o',    args: ['dump-autoload', '--optimize'] },
+};
+
+// The order the groups are shown in.
+const COMPOSER_GROUPS = ['Daily', 'Inspect', 'Maintenance'];
+
+// Take a package from the field. Only require accepts a version constraint after the name.
+const COMPOSER_PACKAGE_ACTIONS = {
+  '/actions/composer-require':        { label: 'composer require',       args: ['require'],                              button: 'require',   constraint: true, manifestArgs: ['require', '--no-update'] },
+  '/actions/composer-update-package': { label: 'composer update -W',     args: ['update', '--with-all-dependencies'],    button: 'update -W' },
+  '/actions/composer-remove':         { label: 'composer remove',        args: ['remove'],                               button: 'remove', manifestArgs: ['remove', '--no-update'] },
+  '/actions/composer-require-dev':    { label: 'composer require --dev', args: ['require', '--dev'],                     button: 'require --dev', constraint: true, manifestArgs: ['require', '--dev', '--no-update'] },
+  '/actions/composer-why':            { label: 'composer why',           args: ['why'],                                  button: 'why' },
+};
+
+const SCRIPT_ROUTE = '/actions/composer-script';
+
+/** What the menu offers, and the handler runs, in a workspace of this mode. */
+function composerActionsFor(mode) {
+  if (mode === 'full') return { run: COMPOSER_RUN_ACTIONS, packages: COMPOSER_PACKAGE_ACTIONS, scripts: true };
+  const run = Object.fromEntries(Object.entries(COMPOSER_RUN_ACTIONS).filter(([, a]) => a.manifest));
+  const packages = Object.fromEntries(Object.entries(COMPOSER_PACKAGE_ACTIONS).filter(([, a]) => a.manifestArgs)
+    .map(([route, a]) => [route, { ...a, args: a.manifestArgs, label: `${a.label} --no-update` }]));
+  return { run, packages, scripts: false };
+}
+
+function composerModeOf(workspace) {
+  try { return (loadWorkspaces()[workspace] || {}).composerMode === 'full' ? 'full' : 'manifest'; } catch (_) { return 'manifest'; }
+}
+
+// vendor/name as Composer itself defines it, then an optional `:constraint` of version characters
+// only. No quote, $, backtick or backslash can pass: the value is single-quoted into a shell line.
+const PACKAGE_RE = /^[a-z0-9]([_.-]?[a-z0-9]+)*\/[a-z0-9](([_.]|-{1,2})?[a-z0-9]+)*$/;
+const CONSTRAINT_RE = /^[A-Za-z0-9.^~*|,<>=@ -]{1,60}$/;
+const SCRIPT_NAME_RE = /^[A-Za-z0-9_][A-Za-z0-9_:.-]{0,80}$/;
+const SAFE_PATH_RE = /^[\w/.@+~-]+$/;
+
+/** The dashboard's own DDEV project, whose container runs composer for non-DDEV folders. */
+function dashboardDir() { return path.join(ROOT, 'core', 'workspace-app'); }
+
+function hasComposerJson(dir) {
+  try { return fs.statSync(path.join(dir, 'composer.json')).isFile(); } catch (_) { return false; }
+}
+
+function isDdevProject(dir) {
+  try { return fs.existsSync(path.join(dir, '.ddev', 'config.yaml')); } catch (_) { return false; }
+}
+
+/** Why this package value must not run, or '' when it may. */
+function packageRefusal(value, { constraint = false } = {}) {
+  const v = String(value || '').trim();
+  if (!v) return 'type a package first, as vendor/name';
+  const [name, ...rest] = v.split(':');
+  if (!PACKAGE_RE.test(name)) return 'that is not a package name (vendor/name, lower case)';
+  if (!rest.length) return '';
+  if (!constraint) return 'a version constraint only goes with require';
+  return CONSTRAINT_RE.test(rest.join(':')) ? '' : 'that is not a version constraint';
+}
+
+/**
+ * The folder's own scripts, which is what "custom commands" are in Composer. Event hooks
+ * (pre-/post-…) run by themselves during install and update, so they are not offered by hand.
+ * A script whose name could not be passed safely to a shell is left out rather than escaped.
+ */
+function composerScripts(dir) {
+  let pkg;
+  try { pkg = JSON.parse(fs.readFileSync(path.join(dir, 'composer.json'), 'utf8')); } catch (_) { return []; }
+  const scripts = (pkg && typeof pkg.scripts === 'object' && pkg.scripts) || {};
+  const aliases = (pkg && typeof pkg['scripts-aliases'] === 'object' && pkg['scripts-aliases']) || {};
+  const descriptions = (pkg && typeof pkg['scripts-descriptions'] === 'object' && pkg['scripts-descriptions']) || {};
+  return Object.keys(scripts)
+    .filter((name) => !/^(pre|post)-/.test(name) && !['init', 'command'].includes(name) && SCRIPT_NAME_RE.test(name))
+    .map((name) => ({
+      name,
+      aliases: (Array.isArray(aliases[name]) ? aliases[name] : []).filter((a) => typeof a === 'string' && SCRIPT_NAME_RE.test(a)),
+      description: typeof descriptions[name] === 'string' ? descriptions[name] : '',
+    }));
+}
+
+const sq = (s) => `'${s}'`;
+
+/**
+ * The line a composer session runs. No `$` anywhere: the runner hands it to an outer `bash -lc "…"`,
+ * which would expand it too early. Paths are checked against SAFE_PATH_RE and single-quoted.
+ */
+function composerScreenCommand(label, args, { isDdev, projectDir }) {
+  const composer = isDdev
+    ? `ddev composer --no-interaction --ansi ${args.join(' ')}`
+    : `cd ${sq(dashboardDir())} && ddev exec -d ${sq(projectDir)} composer --no-interaction --ansi ${args.join(' ')}`;
+  return `${composer}; ${lingerTail(label)}`;
+}
+
+/** Has this session's command finished, so that it is only waiting to be read? */
+function sessionFinished(logText) {
+  const lines = String(logText || '').split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+  return lines.length > 0 && lines[lines.length - 1].includes(LINGER_MARK);
+}
+
+function sessionLogTail(session) {
+  try {
+    const file = path.join(ROOT, '.screens', `${session}.log`);
+    const size = fs.statSync(file).size;
+    const fd = fs.openSync(file, 'r');
+    try {
+      const len = Math.min(size, 4096);
+      const buf = Buffer.alloc(len);
+      fs.readSync(fd, buf, 0, len, size - len);
+      return buf.toString('utf8');
+    } finally { fs.closeSync(fd); }
+  } catch (_) { return ''; }
+}
+
+/** Start the session; replace one still open from last time only if its command has finished. */
+async function startUnlessRunning(opts) {
+  let started = await startInScreen(opts);
+  for (let i = 0; started.already && i < 3; i += 1) {
+    if (!sessionFinished(sessionLogTail(started.session))) return { ...started, stillRunning: true };
+    await hostRunnerRequest('stop', { session: started.session });
+    await new Promise((resolve) => setTimeout(resolve, 400));
+    started = await startInScreen(opts);
+  }
+  return started;
+}
+
+function terminalLink(session, text) {
+  return `<a href="/terminal/${encodeURIComponent(session)}" target="_blank" rel="noopener">${esc(text)}</a>`;
+}
+
+async function composer_run({ form, send, workspace, pathname }) {
+  const isScript = pathname === SCRIPT_ROUTE;
+  const act = COMPOSER_RUN_ACTIONS[pathname] || COMPOSER_PACKAGE_ACTIONS[pathname];
+  if (!act && !isScript) return send('<div class="msg error">Unknown composer command.</div>', 404);
+  const projectName = String(form.projectName || '');
+  if (!NAME_RE.test(projectName)) return send('<div class="msg error">Invalid project name.</div>', 400);
+
+  // The workspace's mode decides before anything else: a package clone never installs.
+  const allowed = composerActionsFor(composerModeOf(workspace));
+  const use = isScript ? null : (allowed.run[pathname] || allowed.packages[pathname]);
+  // A DDEV folder that is installed (composer.lock) runs its own scripts in any workspace: they are its commands.
+  const installedDdev = (dir) => isDdevProject(dir) && fs.existsSync(path.join(dir, 'composer.lock'));
+  const scriptsHere = allowed.scripts || (NAME_RE.test(String(form.projectName || ''))
+    && installedDdev(path.join(workspaceDir(workspace), String(form.projectName))));
+  if (isScript ? !scriptsHere : !use) {
+    return send(`<div class="msg error">Not run in ${esc(workspace)}: this workspace only edits composer.json — validate, and require or remove with --no-update.</div>`, 403);
+  }
+
+  // What the request carries is checked before anything on disk is looked at.
+  let args = use ? [...use.args] : [];
+  let label = use ? use.label : '';
+  let verb = pathname.replace('/actions/', '');
+  if (COMPOSER_PACKAGE_ACTIONS[pathname]) {
+    const why = packageRefusal(form.package, use);
+    if (why) return send(`<div class="msg error">Not running ${esc(use.label)}: ${esc(why)}.</div>`, 400);
+    args.push(sq(String(form.package).trim()));
+  }
+  const script = String(form.script || '');
+  if (isScript && !SCRIPT_NAME_RE.test(script)) return send('<div class="msg error">Invalid script name.</div>', 400);
+
+  const projectDir = path.join(workspaceDir(workspace), projectName);
+  if (!hasComposerJson(projectDir)) {
+    return send(`<div class="msg error">${esc(projectName)} has no composer.json.</div>`, 400);
+  }
+  if (!SAFE_PATH_RE.test(projectDir)) {
+    return send(`<div class="msg error">Not running composer: the folder path has characters a shell line cannot carry safely.</div>`, 400);
+  }
+  if (isScript) {
+    if (!composerScripts(projectDir).some((s) => s.name === script)) {
+      return send(`<div class="msg error">${esc(projectName)}'s composer.json has no script called ${esc(script)}.</div>`, 400);
+    }
+    args = ['run-script', script];
+    label = `composer run-script ${script}`;
+    verb = `composer-script-${script.replace(/[^\w-]/g, '-')}`;
+  }
+  const isDdev = isDdevProject(projectDir);
+  if (!isDdev && !isDdevProject(dashboardDir())) {
+    return send('<div class="msg error">This folder is not a DDEV project, and the dashboard\'s own DDEV project was not found to run composer in.</div>', 500);
+  }
+
+  const started = await startUnlessRunning({ workspace, project: projectName, projectDir, verb,
+    cmdLine: composerScreenCommand(label, args, { isDdev, projectDir }), label });
+  if (started.stillRunning) {
+    return send(`<div class="msg error"><code>${esc(label)}</code> is still running on <strong>${esc(projectName)}</strong> — ${terminalLink(started.session, 'open it')}. Left alone.</div>`, 409);
+  }
+  if (!started.ok) return send(screenStartedHtml(started, label, projectName), started.already ? 409 : 500);
+  // install, update, require and remove change composer.lock: reload as the toast leaves, so the caption is current.
+  const reload = /^(install|update|require|remove)$/.test(args[0]) && !args.includes('--dry-run');
+  return send(`<div class="msg assistant flash-now"${reload ? ' data-reload-on-close="1"' : ''}><code>${esc(label)}</code> on <strong>${esc(projectName)}</strong> — ${terminalLink(started.session, 'open the output')}</div>`);
+}
+
+module.exports = {
+  COMPOSER_RUN_ACTIONS,
+  COMPOSER_PACKAGE_ACTIONS,
+  COMPOSER_GROUPS,
+  SCRIPT_ROUTE,
+  composerActionsFor,
+  composerModeOf,
+  hasComposerJson,
+  isDdevProject,
+  packageRefusal,
+  composerScripts,
+  composerScreenCommand,
+  sessionFinished,
+  // Shared with the NODE menu (actions/node.js), which runs npm and yarn the same way.
+  sq,
+  SAFE_PATH_RE,
+  dashboardDir,
+  startUnlessRunning,
+  terminalLink,
+  ...Object.fromEntries([...Object.keys(COMPOSER_RUN_ACTIONS), ...Object.keys(COMPOSER_PACKAGE_ACTIONS), SCRIPT_ROUTE]
+    .map((route) => [route, composer_run])),
+};