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

package/actions/images.js

@@ -0,0 +1,145 @@
+/**
+ * Renaming and deleting an image in the images workspace. Images shown from other workspaces are
+ * read-only here, so both refuse any source but images/.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('../html');
+const { workspaceDir, isValidWorkspace } = require('../workspaces');
+const images = require('../images');
+
+function ownImage(form) {
+  if (!isValidWorkspace('images')) return null;
+  const where = images.safeIn(workspaceDir('images'), String(form.file || ''));
+  if (!where || !images.IMAGE_RE.test(where.abs)) return null;
+  try { if (!fs.statSync(where.abs).isFile()) return null; } catch (_) { return null; }
+  return where;
+}
+
+function refreshed(res) {
+  images.forgetScan();
+  try { res.setHeader('HX-Trigger', 'refresh-projects'); } catch (_) { /* headers already sent */ }
+}
+
+async function image_rename({ form, send, res }) {
+  const where = ownImage(form);
+  if (!where) return send('<div class="msg error">That image is not in the images workspace.</div>', 404);
+  const ext = path.extname(where.abs).toLowerCase();
+  let name = images.safeName(form.name);
+  if (!name) return send('<div class="msg error">Give it a name: letters, digits, dot, dash and underscore.</div>', 400);
+  // The extension is the file's own; a rename never changes what kind of image it is.
+  if (path.extname(name).toLowerCase() !== ext) name = `${name.replace(/\.[^.]*$/, '')}${ext}`;
+  const dest = path.join(path.dirname(where.abs), name);
+  if (dest === where.abs) return send('<div class="msg assistant">The name is unchanged.</div>');
+  if (fs.existsSync(dest)) return send(`<div class="msg error"><code>${esc(name)}</code> already exists in that folder.</div>`, 409);
+  fs.renameSync(where.abs, dest);
+  // A sidecar travels with its image.
+  if (fs.existsSync(`${where.abs}.json`)) fs.renameSync(`${where.abs}.json`, `${dest}.json`);
+  refreshed(res);
+  const rel = path.relative(fs.realpathSync(workspaceDir('images')), dest).split(path.sep).join('/');
+  return send(`<div class="msg assistant">Renamed to <strong>${esc(name)}</strong>.</div>${
+    require('../images-page').viewerHtml({ q: '', sort: 'newest', kind: '', scope: 'here' }, path.posix.dirname(rel) === '.' ? '' : path.posix.dirname(rel), 'images', rel) || ''}`);
+}
+
+async function image_delete({ form, send, res }) {
+  if (form.confirm !== 'yes') return send('<div class="msg error">Deleting needs confirmation.</div>', 400);
+  const where = ownImage(form);
+  if (!where) return send('<div class="msg error">That image is not in the images workspace.</div>', 404);
+  fs.unlinkSync(where.abs);
+  try { fs.unlinkSync(`${where.abs}.json`); } catch (_) { /* no sidecar */ }
+  refreshed(res);
+  return send(`<div class="msg assistant">Deleted <strong>${esc(where.rel)}</strong>.</div>`);
+}
+
+const viewerOf = (rel) => require('../images-page').viewerHtml({ q: '', sort: 'newest', kind: '', scope: 'here' },
+  path.posix.dirname(rel) === '.' ? '' : path.posix.dirname(rel), 'images', rel) || '';
+
+async function image_screenshot({ form, send, res }) {
+  const r = await require('../images-create').screenshot(form);
+  if (!r.ok) return send(`<div class="msg error">${esc(r.error)}</div>`, r.status);
+  refreshed(res);
+  return send(`<div class="msg assistant">Saved <strong>${esc(r.rel)}</strong>.</div>${viewerOf(r.rel)}`);
+}
+
+async function image_edit({ form, send, res }) {
+  const r = await require('../images-create').edit(form);
+  if (!r.ok) return send(`<div class="msg error">${esc(r.error)}</div>`, r.status);
+  refreshed(res);
+  return send(`<div class="msg assistant">Saved as <strong>${esc(r.name)}</strong>; the original is unchanged.</div>${viewerOf(r.rel)}`);
+}
+
+/** Why a provider cannot run here, as HTML, or '' when it can. */
+function notReady(id) {
+  const prov = require('../images-providers').get(id);
+  if (!prov) return 'Unknown provider.';
+  const a = prov.available();
+  if (a.ok) return '';
+  return prov.keyName ? `Set <code>ai_providers.${esc(prov.keyName)}.api_key</code> in <code>core/config/settings.yml</code> first.` : `${esc(prov.label)}: ${esc(a.why)}.`;
+}
+
+/** A Claude Code session has started: where to watch it and where the result lands. */
+function startedHtml(session, where) {
+  return `<div class="msg assistant">Claude Code is drawing it in the screen session <strong>${esc(session)}</strong>: <a href="/screens">watch it on Screens</a>. The SVG, its PNG and the records appear in <strong>${where}</strong> when it is done.</div>`;
+}
+
+// Without confirm=yes this only answers with the plan; the paid request needs the confirm dialog's Yes.
+async function image_generate({ form, send, res }) {
+  const ai = require('../images-ai');
+  if (form.confirm !== 'yes') {
+    const p = ai.plan(form);
+    if (!p.ok) return send(`<div class="msg error">${esc(p.error)}</div>${ai.formHtml()}`, 400);
+    const why = notReady(p.provider);
+    if (why) return send(`<div class="msg error">${why}</div>`, 503);
+    return send(ai.planHtml(p));
+  }
+  const r = await ai.generate(form);
+  if (!r.ok) return send(`<div class="msg error">${esc(r.error)}</div>`, r.status);
+  if (r.async) return send(startedHtml(r.session, 'images/generated/'));
+  refreshed(res);
+  const page = require('../images-page');
+  const thumbs = r.made.map((rel) => `<button type="button" class="img-thumb img-made-thumb"
+      hx-get="/fragments/images/view?src=images&file=${encodeURIComponent(rel)}&path=generated" hx-target="#editor-modal-body" hx-swap="innerHTML">
+      <img src="${esc(page.fileUrl('images', rel))}" alt="${esc(rel)}"></button>`).join('');
+  const missing = (r.undescribed || []).length
+    ? `<div class="msg error">The description was not written for ${r.undescribed.map((n) => `<code>${esc(n)}</code>`).join(', ')}; open it and use <strong>Describe it</strong>.</div>` : '';
+  return send(`<div class="msg assistant">Made ${r.made.length} image${r.made.length === 1 ? '' : 's'} in <strong>images/generated/</strong>, each with its prompt, a description and an alt text${
+    r.cost === null ? '' : `, for about $${r.cost.toFixed(4)} in all`}. Open one to see it full size.</div>${missing}<div class="img-made-grid">${thumbs}</div>`);
+}
+
+// Edit with AI: a plan first, and the paid request only with the confirm dialog's Yes.
+async function image_ai_edit({ form, send, res }) {
+  const ai = require('../images-ai');
+  if (form.confirm !== 'yes') {
+    const p = ai.editPlan(form);
+    if (!p.ok) return send(`<div class="msg error">${esc(p.error)}</div>`, 400);
+    const why = notReady(p.provider);
+    if (why) return send(`<div class="msg error">${why}</div>`, 503);
+    return send(ai.editPlanHtml(p));
+  }
+  const r = await ai.editImage(form);
+  if (!r.ok) return send(`<div class="msg error">${esc(r.error)}</div>`, r.status);
+  if (r.async) return send(startedHtml(r.session, `the source's folder as ${esc(r.name)}`));
+  refreshed(res);
+  return send(`<div class="msg assistant">Saved as <strong>images/${esc(r.rel)}</strong>; the source is unchanged${
+    r.cost === null ? '' : `. It cost about $${r.cost.toFixed(4)}`}.${r.described ? '' : ' The description was not written: use <strong>Describe it</strong>.'}</div>${viewerOf(r.rel)}`);
+}
+
+// Describe an image: a small paid call, so only with the confirm dialog's Yes.
+async function image_describe({ form, send, res }) {
+  const r = await require('../images-ai').describeExisting(form);
+  if (!r.ok) return send(`<div class="msg error">${esc(r.error)}</div>`, r.status);
+  refreshed(res);
+  return send(`<div class="msg assistant">Described, for about $${r.cost.toFixed(4)}.</div>${viewerOf(r.rel)}`);
+}
+
+module.exports = {
+  '/actions/image-generate': image_generate,
+  '/actions/image-ai-edit': image_ai_edit,
+  '/actions/image-describe': image_describe,
+  '/actions/image-screenshot': image_screenshot,
+  '/actions/image-edit': image_edit,
+  '/actions/image-rename': image_rename,
+  '/actions/image-delete': image_delete,
+};

package/actions/navigation.js

@@ -0,0 +1,190 @@
+/**
+ * Writing the rail's layout: what is hidden, in what order, and the entries someone added.
+ *
+ * One form carries the whole arrangement (`#nav-form`), so a drag that has not been saved is posted with
+ * anything else that is done meanwhile — adding an entry never loses a reorder. Every write carries the
+ * file's mtime and is refused with 409 when it changed since, the way every other writer here works.
+ */
+
+const rail = require('../navigation');
+const navPage = require('../navigation-page');
+const cc = require('../commands');
+const { startJob, jobFragment } = require('../jobs');
+
+const ok = (msg) => `<div class="msg assistant">✅ ${msg}</div>`;
+const bad = (msg) => `<div class="msg error">${msg}</div>`;
+
+const asArray = (v) => (v === undefined ? [] : (Array.isArray(v) ? v : [v]));
+
+/** The arrangement as posted: group order, and each entry under the group it was dropped in. */
+function arranged(form) {
+  // Deduplicated, and the reserved lists are not sidebar groups: the group order is a set, and a stray
+  // repeat would make the same group render twice.
+  const groups = [...new Set(asArray(form.group).map(String).filter(rail.isId))]
+    .filter((g) => !rail.RESERVED.has(g));
+  const order = {};
+  const hidden = [];
+  const topbar = rail.emptyTopbar();
+  // How much of each entry is shown: `<id>:icon`, `<id>:text`, or `<id>:both`. Both is the default and
+  // is not written down, which is what keeps the file a record of what somebody changed — and posting
+  // it explicitly is what makes going back to both work.
+  const ships = shippedShow(scopeOf(form));
+  const show = {};
+  for (const raw of asArray(form.show).map(String)) {
+    const at = raw.lastIndexOf(':');
+    if (at < 0) continue;
+    const id = raw.slice(0, at);
+    const how = raw.slice(at + 1);
+    if (!rail.isId(id)) continue;
+    if (how === 'icon' || how === 'text') { show[id] = how; continue; }
+    // Both is what an entry is unless somebody says otherwise, so it is not written down — EXCEPT when
+    // it is overriding an entry the dashboard ships one way. Without that there would be no way to put
+    // the assistant's label back: leaving the key out would just let its own default win again.
+    if (how === 'both' && ships[id]) show[id] = 'both';
+  }
+  for (const raw of asArray(form.item).map(String)) {
+    const at = raw.indexOf(':');
+    if (at < 0) continue;
+    const group = raw.slice(0, at);
+    const id = raw.slice(at + 1);
+    if (!rail.isId(id)) continue;
+    if (group === 'hidden') { hidden.push(id); continue; }
+    const region = rail.regionOf(group);
+    if (region) { topbar[region].push(id); continue; }
+    if (!rail.isId(group)) continue;
+    (order[group] || (order[group] = [])).push(id);
+  }
+  return { groups, order, hidden, topbar, show };
+}
+
+/** How each entry SHIPS, from what the navigation has drawn — a default an explicit answer overrides. */
+function shippedShow(scope) {
+  const out = {};
+  for (const g of Object.values(rail.seenFor(scope))) {
+    for (const [id, was] of Object.entries((g || {}).items || {})) {
+      const how = rail.seenShips(was);
+      if (how) out[id] = how;
+    }
+  }
+  return out;
+}
+
+function scopeOf(form) {
+  const scope = String(form.scope || 'global');
+  return scope === 'global' || rail.isId(scope) ? scope : 'global';
+}
+
+/** Save one scope, keeping the entries it already had — they are edited by their own actions. */
+function write(form, change) {
+  const { raw, mtime } = rail.rawLayout();
+  if (String(form.mtime || '') !== String(mtime)) {
+    return { conflict: true };
+  }
+  const scope = scopeOf(form);
+  const current = rail.scopeLayout(raw, scope);
+  const next = change({ ...current });
+  const out = rail.withScope(raw, scope, next);
+  return { mtime: rail.saveLayout(out) };
+}
+
+const editor = (send, form, message, status = 200) =>
+  send(navPage.navEditorHtml(scopeOf(form), message), status);
+
+async function nav_save({ form, send }) {
+  const { groups, order, hidden, topbar, show } = arranged(form);
+  const res = write(form, (current) => ({ ...current, groups, order, hidden, topbar, show }));
+  if (res.conflict) {
+    return editor(send, form, bad('The navigation changed somewhere else while this was open — nothing was written. This is how it is now.'), 409);
+  }
+  return editor(send, form, ok('Navigation saved. It applies on the next page you open.'));
+}
+
+async function nav_add({ form, send }) {
+  const label = String(form.new_label || '').trim().slice(0, 40);
+  if (!label) return editor(send, form, bad('An entry needs a label.'), 400);
+  const href = String(form.new_href || '').trim();
+  const use = String(form.new_use || '').trim();
+  if (!href && !use) return editor(send, form, bad('An entry needs somewhere to go, or a command to run.'), 400);
+  if (href && use) return editor(send, form, bad('An entry is a link or a command, not both.'), 400);
+  if (use && !cc.loadCatalog().commands.some((c) => c.id === use)) {
+    return editor(send, form, bad('No such command.'), 400);
+  }
+  // A link goes in an href attribute and is followed by a click: only http(s) and a path of this
+  // dashboard, so nothing can put javascript: or data: into the rail.
+  if (href && !/^(https?:\/\/|\/)[^\s"'<>]*$/i.test(href)) {
+    return editor(send, form, bad('A link is an https:// address or a path of this dashboard.'), 400);
+  }
+
+  const base = rail.slugId(label);
+  const { raw } = rail.rawLayout();
+  const taken = new Set(rail.scopeLayout(raw, scopeOf(form)).items.map((i) => i.id));
+  let id = base;
+  for (let n = 2; taken.has(id); n += 1) id = `${base}-${n}`.slice(0, 48);
+
+  const item = { id, label };
+  const iconValue = String(form.new_icon || '').trim();
+  if (iconValue) item.icon = iconValue.slice(0, 40);
+  const group = String(form.new_group || '').trim();
+  // A region of the top bar is a legal destination, and slugId leaves it alone (it is already a slug).
+  if (group) item.group = rail.slugId(group);
+  if (href) item.href = href; else item.use = use;
+  if (form.new_confirm) item.confirm = true;
+
+  const { groups, order, hidden, topbar, show } = arranged(form);
+  const res = write(form, (current) => ({ ...current, groups, order, hidden, topbar, show, items: [...current.items, item] }));
+  if (res.conflict) {
+    return editor(send, form, bad('The navigation changed somewhere else while this was open — nothing was written.'), 409);
+  }
+  return editor(send, form, ok(`Added <strong>${label}</strong> to the navigation.`));
+}
+
+async function nav_remove({ form, send }) {
+  const id = String(form.id || '');
+  const { groups, order, hidden, topbar, show } = arranged(form);
+  const res = write(form, (current) => ({
+    ...current,
+    groups,
+    show: Object.fromEntries(Object.entries(show).filter(([x]) => x !== id)),
+    order: Object.fromEntries(Object.entries(order).map(([g, ids]) => [g, ids.filter((x) => x !== id)])),
+    hidden: hidden.filter((x) => x !== id),
+    topbar: Object.fromEntries(Object.entries(topbar).map(([r, ids]) => [r, ids.filter((x) => x !== id)])),
+    items: current.items.filter((it) => it.id !== id),
+  }));
+  if (res.conflict) return editor(send, form, bad('The navigation changed somewhere else while this was open.'), 409);
+  return editor(send, form, ok('Removed.'));
+}
+
+async function nav_reset({ form, send }) {
+  const { raw, mtime } = rail.rawLayout();
+  if (String(form.mtime || '') !== String(mtime)) {
+    return editor(send, form, bad('The navigation changed somewhere else while this was open.'), 409);
+  }
+  rail.saveLayout(rail.withScope(raw, scopeOf(form), {}));
+  return editor(send, form, ok('Back to the navigation this scope ships with.'));
+}
+
+/**
+ * Run a command an entry carries. The same runner a row action uses, so there is one history and one
+ * screen session per run rather than a second way of doing it.
+ */
+async function nav_run({ form, send }) {
+  const use = String(form.use || '');
+  const command = cc.loadCatalog().commands.find((c) => c.id === use);
+  if (!command) return send(bad('No such command.'), 400);
+  let line;
+  try {
+    line = cc.commandLine(command, { workspace: command.workspace });
+  } catch (err) {
+    return send(bad(`That command cannot run from the rail: ${err.message}`), 400);
+  }
+  const id = startJob(`rail:${use}`, line, { cwd: command.dir });
+  return send(jobFragment(id).html);
+}
+
+module.exports = {
+  '/actions/nav-save': nav_save,
+  '/actions/nav-add': nav_add,
+  '/actions/nav-remove': nav_remove,
+  '/actions/nav-reset': nav_reset,
+  '/actions/nav-run': nav_run,
+};

package/actions/node.js

@@ -0,0 +1,222 @@
+/**
+ * The NODE menu on a project row: npm and yarn for any folder with a package.json.
+ *
+ * It follows the COMPOSER menu (actions/composer.js) and reuses its machinery: every command runs in
+ * a SCREEN SESSION that stays open to be read, the page shows only the toast at the top, and a second
+ * click replaces a session only once its command has finished — a run still going is left alone.
+ * Unlike COMPOSER there is no manifest mode: every workspace gets the whole menu.
+ *
+ * DDEV only, as with composer:
+ *
+ *   - A DDEV project runs `ddev npm` / `ddev yarn`, in its own web container (the site projects all
+ *     carry `corepack_enable: true`, so a pinned Yarn 4 is what runs).
+ *   - Any other folder runs in the DASHBOARD's DDEV container: `ddev exec -d <folder> npm …`. When the
+ *     project pins yarn in `packageManager`, it runs `corepack yarn`, so the pinned version runs rather
+ *     than the container's Yarn 1.
+ *
+ * Which manager: the menu offers both, as a yarn and an npm tab, each saying whether its lock file is
+ * there. The tab that opens is the one the project uses — its `packageManager` pin, else its lock file.
+ * Yarn 1 (classic) and Yarn 2+ (berry) differ in several commands, so every entry carries three forms;
+ * which Yarn a folder has is read from the folder (`packageManager`, `.yarnrc.yml`), never from the request.
+ *
+ * The handler runs only what these tables name for that manager, a package that looks like an npm
+ * package name (never a git URL, a tarball or a file: path), and a script package.json declares.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('../html');
+const { workspaceDir } = require('../workspaces');
+const { screenStartedHtml } = require('../jobs');
+const { NAME_RE } = require('../validate');
+const { lingerTail } = require('../linger');
+const { startUnlessRunning, terminalLink, isDdevProject, dashboardDir, sq, SAFE_PATH_RE } = require('./composer');
+
+// The order of the tabs. yarn first: every site project in this tree uses it.
+const MANAGERS = ['yarn', 'npm'];
+const NODE_GROUPS = ['Daily', 'Inspect', 'Maintenance'];
+
+// Each command in its three forms: npm, Yarn 1 (yarn1) and Yarn 2+ (yarn). null = that manager has no
+// such command, and the entry is not offered. In the order people reach for them.
+const NODE_RUN_ACTIONS = {
+  '/actions/node-install':  { group: 'Daily',       npm: ['install'],          yarn1: ['install'],                     yarn: ['install'] },
+  '/actions/node-ci':       { group: 'Daily',       npm: ['ci'],               yarn1: ['install', '--frozen-lockfile'], yarn: ['install', '--immutable'],
+    needsLock: true, title: 'Install exactly what the lock file says, and fail if package.json disagrees with it' },
+  '/actions/node-outdated': { group: 'Daily',       npm: ['outdated'],         yarn1: ['outdated'],                    yarn: ['upgrade-interactive'] },
+  '/actions/node-audit':    { group: 'Daily',       npm: ['audit'],            yarn1: ['audit'],                       yarn: ['npm', 'audit'] },
+  '/actions/node-list':     { group: 'Inspect',     npm: ['ls', '--depth=0'],  yarn1: ['list', '--depth=0'],           yarn: ['info', '--name-only'] },
+  '/actions/node-version':  { group: 'Inspect',     npm: ['--version'],        yarn1: ['--version'],                   yarn: ['--version'] },
+  '/actions/node-update':   { group: 'Maintenance', npm: ['update'],           yarn1: ['upgrade'],                     yarn: null },
+  '/actions/node-dedupe':   { group: 'Maintenance', npm: ['dedupe'],           yarn1: null,                            yarn: ['dedupe'] },
+  '/actions/node-cache':    { group: 'Maintenance', npm: ['cache', 'verify'],  yarn1: ['cache', 'clean'],              yarn: ['cache', 'clean'] },
+};
+
+// Take a package from the field. Only add accepts a version after the name.
+const NODE_PACKAGE_ACTIONS = {
+  '/actions/node-add':      { button: 'add',       npm: ['install'],               yarn1: ['add'],          yarn: ['add'],          version: true },
+  '/actions/node-upgrade':  { button: 'upgrade',   npm: ['update'],                yarn1: ['upgrade'],      yarn: ['up'] },
+  '/actions/node-remove':   { button: 'remove',    npm: ['uninstall'],             yarn1: ['remove'],       yarn: ['remove'] },
+  '/actions/node-add-dev':  { button: 'add --dev', npm: ['install', '--save-dev'], yarn1: ['add', '--dev'], yarn: ['add', '--dev'], version: true },
+  '/actions/node-why':      { button: 'why',       npm: ['explain'],               yarn1: ['why'],          yarn: ['why'] },
+};
+
+const NODE_SCRIPT_ROUTE = '/actions/node-script';
+
+// npm's own package-name shape, optionally scoped. A version is range characters only: no quote, $,
+// backtick, backslash or colon, so a git URL, a tarball or a file: path can never pass.
+const NPM_NAME_RE = /^(@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
+const NPM_VERSION_RE = /^[A-Za-z0-9.^~*|<>=_ -]{1,60}$/;
+const SCRIPT_NAME_RE = /^[A-Za-z0-9_][A-Za-z0-9_:.@/-]{0,80}$/;
+// Run by npm and yarn themselves around install, publish and version — not something to run by hand.
+const LIFECYCLE = new Set(['install', 'preinstall', 'postinstall', 'prepare', 'prepublish', 'prepublishOnly',
+  'prepack', 'postpack', 'publish', 'postpublish', 'preversion', 'version', 'postversion', 'dependencies',
+  'preuninstall', 'uninstall', 'postuninstall']);
+
+function hasPackageJson(dir) {
+  try { return fs.statSync(path.join(dir, 'package.json')).isFile(); } catch (_) { return false; }
+}
+
+/** What the folder says about itself: the manifest, the pin, the lock files, and which Yarn. */
+function nodeInfo(dir) {
+  let pkg = null;
+  try { pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')); } catch (_) { /* valid: false */ }
+  if (!pkg || typeof pkg !== 'object') pkg = null;
+  const has = (f) => { try { return fs.existsSync(path.join(dir, f)); } catch (_) { return false; } };
+  const m = pkg && typeof pkg.packageManager === 'string' ? /^(npm|yarn|pnpm)@(\d+)[^+\s]*/.exec(pkg.packageManager) : null;
+  const pinned = m ? { name: m[1], major: Number(m[2]), spec: m[0] } : null;
+  const locks = { yarn: has('yarn.lock'), npm: has('package-lock.json') };
+  const yarnBerry = (pinned && pinned.name === 'yarn' && pinned.major >= 2) || has('.yarnrc.yml');
+  const preferred = (pinned && MANAGERS.includes(pinned.name)) ? pinned.name
+    : (locks.yarn ? 'yarn' : (locks.npm ? 'npm' : 'npm'));
+  return { valid: !!pkg, pkg, pinned, locks, yarnBerry, preferred, nodeModules: has('node_modules') };
+}
+
+/** The arguments an entry runs with for this manager in this folder, or null when it has none. */
+function nodeArgsFor(action, manager, info) {
+  if (manager === 'npm') return action.npm || null;
+  return ((info && info.yarnBerry) ? action.yarn : action.yarn1) || null;
+}
+
+/** Why this package value must not run, or '' when it may. */
+function nodePackageRefusal(value, { version = false } = {}) {
+  const v = String(value || '').trim();
+  if (!v) return 'type a package first, as name or @scope/name';
+  const at = v.indexOf('@', 1);
+  const name = at > 0 ? v.slice(0, at) : v;
+  if (!NPM_NAME_RE.test(name)) return 'that is not a package name (name or @scope/name, lower case)';
+  if (at < 0) return '';
+  if (!version) return 'a version only goes with add';
+  return NPM_VERSION_RE.test(v.slice(at + 1)) ? '' : 'that is not a version or range';
+}
+
+/**
+ * The folder's own scripts. Lifecycle hooks — install, prepare… and the pre/post twin of another
+ * script — run by themselves, so they are not offered; `prettier` or `postcss` are ordinary scripts.
+ */
+function nodeScripts(pkg) {
+  const scripts = (pkg && typeof pkg.scripts === 'object' && pkg.scripts) || {};
+  const names = Object.keys(scripts);
+  const isHook = (n) => LIFECYCLE.has(n)
+    || names.some((o) => o !== n && (n === `pre${o}` || n === `post${o}`));
+  return names
+    .filter((n) => !isHook(n) && SCRIPT_NAME_RE.test(n))
+    .map((n) => ({ name: n, command: typeof scripts[n] === 'string' ? scripts[n] : '' }));
+}
+
+/**
+ * The line a node session runs. No `$` anywhere: the runner hands it to an outer `bash -lc "…"`.
+ * Paths are checked against SAFE_PATH_RE and single-quoted.
+ */
+function nodeScreenCommand(label, manager, args, { isDdev, projectDir, pinned }) {
+  let line;
+  if (isDdev) {
+    line = `ddev ${manager} ${args.join(' ')}`;
+  } else {
+    // Corepack would stop to ask before downloading the pinned Yarn; `env` sets that off without a `$`.
+    const bin = (manager === 'yarn' && pinned && pinned.name === 'yarn')
+      ? 'env COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack yarn' : manager;
+    line = `cd ${sq(dashboardDir())} && ddev exec -d ${sq(projectDir)} ${bin} ${args.join(' ')}`;
+  }
+  return `${line}; ${lingerTail(label)}`;
+}
+
+async function node_run({ form, send, workspace, pathname }) {
+  const isScript = pathname === NODE_SCRIPT_ROUTE;
+  const act = NODE_RUN_ACTIONS[pathname] || NODE_PACKAGE_ACTIONS[pathname];
+  if (!act && !isScript) return send('<div class="msg error">Unknown node command.</div>', 404);
+  const projectName = String(form.projectName || '');
+  if (!NAME_RE.test(projectName)) return send('<div class="msg error">Invalid project name.</div>', 400);
+  const manager = String(form.manager || '');
+  if (!MANAGERS.includes(manager)) return send('<div class="msg error">Pick npm or yarn.</div>', 400);
+
+  // What the request carries is checked before anything on disk is looked at.
+  const isPackage = !!NODE_PACKAGE_ACTIONS[pathname];
+  if (isPackage) {
+    const why = nodePackageRefusal(form.package, act);
+    if (why) return send(`<div class="msg error">Not running ${esc(manager)} ${esc(act.button)}: ${esc(why)}.</div>`, 400);
+  }
+  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 (!hasPackageJson(projectDir)) {
+    return send(`<div class="msg error">${esc(projectName)} has no package.json.</div>`, 400);
+  }
+  if (!SAFE_PATH_RE.test(projectDir)) {
+    return send('<div class="msg error">Not running it: the folder path has characters a shell line cannot carry safely.</div>', 400);
+  }
+  const info = nodeInfo(projectDir);
+
+  let args;
+  let verb;
+  if (isScript) {
+    if (!nodeScripts(info.pkg).some((s) => s.name === script)) {
+      return send(`<div class="msg error">${esc(projectName)}'s package.json has no script called ${esc(script)}.</div>`, 400);
+    }
+    args = ['run', script];
+    verb = `${manager}-run-${script.replace(/[^\w-]/g, '-')}`;
+  } else {
+    const base = nodeArgsFor(act, manager, info);
+    if (!base) return send(`<div class="msg error">${esc(manager)} has no such command in ${esc(projectName)}.</div>`, 400);
+    if (act.needsLock && !info.locks[manager]) {
+      return send(`<div class="msg error">${esc(projectName)} has no ${manager === 'npm' ? 'package-lock.json' : 'yarn.lock'} to install from.</div>`, 400);
+    }
+    args = [...base];
+    verb = `${manager}-${pathname.replace('/actions/node-', '')}`;
+  }
+  // The label goes into the session's closing echo: the manager and the command, never the typed package.
+  const label = `${manager} ${args.join(' ')}`;
+  if (isPackage) args.push(sq(String(form.package).trim()));
+
+  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 it in.</div>', 500);
+  }
+
+  const started = await startUnlessRunning({ workspace, project: projectName, projectDir, verb,
+    cmdLine: nodeScreenCommand(label, manager, args, { isDdev, projectDir, pinned: info.pinned }), 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);
+  // These change node_modules or a lock file: reload as the toast leaves, so the caption is current.
+  const reload = !isScript && /^(install|ci|add|remove|uninstall|update|upgrade|up|dedupe)$/.test(args[0]);
+  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 = {
+  MANAGERS,
+  NODE_GROUPS,
+  NODE_RUN_ACTIONS,
+  NODE_PACKAGE_ACTIONS,
+  NODE_SCRIPT_ROUTE,
+  hasPackageJson,
+  nodeInfo,
+  nodeArgsFor,
+  nodePackageRefusal,
+  nodeScripts,
+  nodeScreenCommand,
+  ...Object.fromEntries([...Object.keys(NODE_RUN_ACTIONS), ...Object.keys(NODE_PACKAGE_ACTIONS), NODE_SCRIPT_ROUTE]
+    .map((route) => [route, node_run])),
+};

package/actions/notes.js

@@ -0,0 +1,55 @@
+/**
+ * Writing the note on a folder or a project.
+ *
+ * The note is a file INSIDE the folder it is about, so the only thing this has to be careful about is
+ * which folder: the workspace and the project name come from the browser, and a path built from them
+ * without checking would write `.workspace-note` anywhere on the machine that `..` can reach.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('../html');
+const { isValidWorkspace, workspaceDir } = require('../workspaces');
+const notes = require('../notes');
+
+/**
+ * The folder a request names, or null.
+ *
+ * Three checks, and each one is the one that matters: the workspace has to be a workspace this
+ * dashboard knows, the project name has to be a plain name rather than a path, and the resolved
+ * directory has to still be inside the workspace — the same containment check the command editor makes
+ * before it writes a script.
+ */
+function folderOf(form) {
+  const ws = String(form.workspace || '');
+  const project = String(form.projectName || '');
+  if (!isValidWorkspace(ws)) return null;
+  const root = workspaceDir(ws);
+  if (project && !/^[a-zA-Z0-9_-]+$/.test(project)) return null;
+  const dir = project ? path.join(root, project) : root;
+  const resolved = fs.realpathSync.native ? safeReal(dir) : dir;
+  if (!resolved || !(resolved === safeReal(root) || resolved.startsWith(`${safeReal(root)}${path.sep}`))) return null;
+  return fs.existsSync(resolved) ? resolved : null;
+}
+
+function safeReal(p) {
+  try { return fs.realpathSync(p); } catch (_) { return ''; }
+}
+
+async function note_save({ form, send, res }) {
+  const dir = folderOf(form);
+  if (!dir) return send('<div class="msg error">No such folder.</div>', 400);
+  const r = notes.writeNote(dir, { title: form.title, body: form.body });
+  if (!r.ok) return send(`<div class="msg error">The note could not be written: ${esc(r.error)}</div>`, 500);
+  const what = form.projectName ? `${form.workspace}/${form.projectName}` : `${form.workspace}/`;
+  // The rows carry the note as their tooltip and their heading, so the page behind this has to redraw
+  // — otherwise the note is saved and nothing on screen says so until the next navigation. Set the way
+  // every other action here asks for a refresh, on the response rather than through send().
+  try { res.setHeader('HX-Trigger', 'refresh-projects'); } catch (_) { /* headers already sent */ }
+  return send(`<div class="msg assistant">${r.title || r.body
+    ? `Noted on <strong>${esc(what)}</strong>${r.title ? ` — it is called <strong>${esc(r.title)}</strong> here now.` : '.'}`
+    : `The note on <strong>${esc(what)}</strong> was removed.`}</div>`);
+}
+
+module.exports = { '/actions/note-save': note_save, folderOf };

package/actions/plugins.js

@@ -0,0 +1,36 @@
+/**
+ * The Plugins page's buttons: each one is core/scripts/plugins.sh with a verb, run as a job so the
+ * output streams to the page and the record of what happened is the same as on the command line.
+ */
+
+const path = require('path');
+
+const { esc } = require('../html');
+const { ROOT } = require('../workspaces');
+const { jobFragment, runningJobKey, startJob } = require('../jobs');
+const { pluginByName } = require('../plugin-manifest');
+
+const VERBS = new Set(['require', 'activate', 'install', 'configure', 'deactivate', 'uninstall']);
+const NAME_RE = /^[a-z0-9-]+$/;
+// An npm spec: a package name, github:owner/repo[#ref], a git+https url, a tarball or a path. Nothing a shell could read as more than one word.
+const SPEC_RE = /^[A-Za-z0-9@:/._#+~-]+$/;
+
+module.exports = {
+  '/actions/plugins': async ({ form, send }) => {
+    const verb = String(form.verb || '');
+    if (!VERBS.has(verb)) return send('<div class="msg error">Unknown plugin action.</div>', 400);
+    let arg = '';
+    if (verb === 'require') {
+      arg = String(form.spec || '').trim();
+      if (!SPEC_RE.test(arg)) return send('<div class="msg error">That is not a package spec: a name, github:owner/repo, a git url, a tarball or a path.</div>', 400);
+    } else {
+      arg = String(form.name || '');
+      if (!NAME_RE.test(arg) || !pluginByName(arg)) return send('<div class="msg error">Unknown plugin.</div>', 400);
+    }
+    const key = `plugins:${verb}:${arg}`;
+    if (runningJobKey(key)) return send('<div class="msg error">That is already running.</div>', 409);
+    const id = startJob(`🧩 Plugin <strong>${esc(verb)}</strong> ${esc(arg)}`, 'bash', ['core/scripts/plugins.sh', `--${verb}`, arg], ROOT,
+      { timeoutMs: 10 * 60 * 1000, echoLine: `bash core/scripts/plugins.sh --${verb} ${arg}`, key });
+    return send(jobFragment(id).html);
+  },
+};