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

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/obsidian.js

@@ -0,0 +1,59 @@
+/**
+ * Building and removing a project's Obsidian vault.
+ *
+ * Both shell out to `cmd-tools-obsidian.sh` in the project's own workspace rather than
+ * reimplementing the conversion, for the same reason every other action here does: the button and
+ * the command line cannot then drift apart.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { listProjects, workspaceDir } = require('../workspaces');
+const { esc } = require('../html');
+const { jobFragment, runningJobKey, startJob } = require('../jobs');
+const { NAME_RE } = require('../validate');
+const { graphStoreDir } = require('../graphs');
+const { vaultDir } = require('../obsidian');
+
+module.exports = {
+  '/actions/obsidian': async ({ form, res, send, workspace, req }) => {
+    const dir = workspaceDir(workspace);
+    const script = 'cmd-tools-obsidian.sh';
+    const projectName = String(form.projectName || '');
+    if (!fs.existsSync(path.join(dir, script))) return send('<div class="msg error">This workspace has no Obsidian script.</div>', 400);
+    if (!NAME_RE.test(projectName) || !listProjects(dir).includes(projectName)) {
+      return send('<div class="msg error">Unknown project.</div>', 400);
+    }
+    // Said here rather than left to the script, because the menu is reached from a row that may
+    // have had its graph deleted since the page was drawn.
+    if (!fs.existsSync(path.join(graphStoreDir(workspace, projectName), 'graph.json'))) {
+      return send('<div class="msg error">No graph to convert yet — build the graph first, from the same menu.</div>', 409);
+    }
+    // One writer per vault: the build writes to a sibling directory and swaps it in, so two runs
+    // would race on that swap and the loser's vault would vanish under it.
+    const jobKey = `obsidian:${workspace}/${projectName}`;
+    if (runningJobKey(jobKey)) {
+      return send('<div class="msg error">A vault is already being built for this project.</div>', 409);
+    }
+    const id = startJob(`🗂️ Obsidian <strong>${esc(projectName)}</strong>`, 'bash', [script, projectName], dir,
+      { timeoutMs: 10 * 60 * 1000, echoLine: `bash ${script} ${projectName}`, key: jobKey });
+    return send(jobFragment(id).html);
+  },
+
+  '/actions/obsidian-remove': async ({ form, res, send, workspace }) => {
+    if (form.confirm !== 'yes') return send('<div class="msg error">Deleting requires confirmation.</div>', 400);
+    const projectName = String(form.projectName || '');
+    // The project may be long gone — a vault outlives it, and that is exactly a vault worth
+    // throwing away. So the name is validated but not looked up.
+    if (!NAME_RE.test(projectName)) return send('<div class="msg error">Unknown project.</div>', 400);
+    const dir = vaultDir(workspace, projectName);
+    if (!fs.existsSync(dir)) return send('<div class="msg">There was no vault to delete.</div>');
+    try {
+      fs.rmSync(dir, { recursive: true, force: true });
+    } catch (e) {
+      return send(`<div class="msg error">Could not delete the vault: ${esc(e.message)}</div>`, 500);
+    }
+    return send('<div class="msg">Vault deleted. The graph it was made from is untouched.</div>');
+  },
+};

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);
+  },
+};

package/actions/project-make.js

@@ -0,0 +1,28 @@
+/**
+ * Make a video or an audio recording about a project: the form of the row's More menu posts here.
+ * It starts a Claude Code session in the project through the same handler New screen uses, briefed by
+ * `project-make.js`, so it shows on Screens like every other session.
+ */
+
+const { esc } = require('../html');
+const make = require('../project-make');
+
+async function project_make({ form, send, res }) {
+  const brief = make.brief(form);
+  if (brief.error) return send(`<div class="msg error">${esc(brief.error)}</div>`, 400);
+  let out = null;
+  await require('./screens')['/actions/screen-new']({
+    form: { target: brief.target, kind: 'claude', session: brief.session, command: brief.prompt },
+    send: (html, status = 200) => { out = { html, status }; },
+    res,
+  });
+  if (!out || out.status >= 400) return send((out && out.html) || '<div class="msg error">The session did not start.</div>', (out && out.status) || 500);
+  const name = `${brief.project ? `${brief.ws}--${brief.project}` : brief.ws}--${brief.session}`.toLowerCase();
+  const dest = make.KIND[brief.kind].dest;
+  return send(`<div class="msg assistant">
+      <p>The AI (Claude Code) is working${brief.project ? ` in <strong>${esc(brief.ws)}/${esc(brief.project)}</strong>` : ''}, in the session <code>${esc(name)}</code>.</p>
+      <p class="uk-text-meta">It writes the words first and waits for your yes. Watch and answer it on <a href="/screens">Screens</a>, or
+        <code>screen -r ${esc(name)}</code> in your terminal. The result lands in <a href="https://${esc(dest)}.${esc(require('../workspaces').hubDomain())}">${esc(dest)}</a>.</p></div>`);
+}
+
+module.exports = { '/actions/project-make': project_make };

package/actions/rag.js

@@ -0,0 +1,202 @@
+/**
+ * Indexing a project into Milvus, searching it, and choosing which server holds it.
+ *
+ * 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 } = require('../ddev');
+
+async function rag_mcp_command({ form, res, send, workspace, pathname }) {
+    const projectName = String(form.projectName || '');
+    if (!NAME_RE.test(projectName)) return send('<div class="msg error">Unknown project.</div>', 400);
+    const instance = ragInstanceFor(workspace, projectName);
+    const collection = ragCollectionName(workspace, projectName);
+    return send(commandBlock(
+      `Serve the ${instance} RAG server to the Claude Code CLI`,
+      [`cd ${ROOT}/rag && bash cmd-milvus-mcp.sh ${instance} -a register`,
+        `claude mcp add --scope user rag-${instance} -- uvx --from mcp-server-milvus==0.1.1.dev9 --with "mcp<2" mcp-server-milvus --milvus-uri http://127.0.0.1:19530`],
+      `Run either one <strong>on the host</strong>, in a terminal. One registration covers the whole `
+      + `server, so every collection on it — including <code>${esc(collection)}</code> — is searchable `
+      + `from the same 13 tools, and a new index needs no new registration. The workspace command is `
+      + `the safer of the two: it resolves the published port for you and proves the server starts `
+      + `before registering it.`));
+}
+
+  // Bind a project to a RAG server, or unbind it back to the shared default.
+async function rag_bind({ form, res, send, workspace, pathname }) {
+    const projectName = String(form.projectName || '');
+    const instance = String(form.instance || '');
+    if (!NAME_RE.test(projectName)) return send('<div class="msg error">Unknown project.</div>', 400);
+    if (instance && !ragInstances().includes(instance)) {
+      return send('<div class="msg error">No such RAG server in the rag workspace.</div>', 400);
+    }
+    ragWriteBinding(workspace, projectName, instance);
+    ragInvalidate();
+    res.setHeader('HX-Trigger', 'refresh-projects');
+    const where = instance || `${milvusProjectName()} (the shared default)`;
+    return send(`<div class="msg assistant">🔗 <strong>${esc(projectName)}</strong> now indexes into <strong>${esc(where)}</strong>.
+      Re-index it to fill that server — the old collection stays where it was, so drop it first if it is stale.</div>`);
+}
+
+  // Build a new RAG server, and bind this project to it. Two steps deliberately kept in one
+  // action: a server built and then not bound is a 2 GB stack nothing uses.
+async function rag_server_new({ form, res, send, workspace, pathname }) {
+    const projectName = String(form.projectName || '');
+    const name = String(form.name || '').trim();
+    if (!NAME_RE.test(projectName)) return send('<div class="msg error">Unknown project.</div>', 400);
+    if (!NAME_RE.test(name)) return send('<div class="msg error">A server name is letters, digits, dashes and underscores.</div>', 400);
+    if (ragInstances().includes(name)) return send(`<div class="msg error">A RAG server called ${esc(name)} already exists — pick it from the list instead.</div>`, 409);
+    const ragDir = workspaceDir('rag');
+    const script = 'cmd-milvus-project.sh';
+    if (!fs.existsSync(path.join(ragDir, script))) return send('<div class="msg error">No Milvus builder in the rag workspace.</div>', 400);
+    const jobKey = `milvus-build:${name}`;
+    if (runningJobKey(jobKey)) return send('<div class="msg error">That server is already being built.</div>', 409);
+    // Bound first: the build takes minutes, and the binding is what makes the row point at the new
+    // server the moment it answers.
+    ragWriteBinding(workspace, projectName, name);
+    ragInvalidate();
+    return screenAction(send, { workspace: 'rag', project: name, projectDir: ragDir, verb: 'milvus-build',
+      cmdLine: `bash ${JSON.stringify(script)} ${JSON.stringify(name)}`, label: `build the RAG server ${name}` });
+}
+
+  // Build or rebuild a project's RAG index. The script does the work — this only guards the
+  // arguments and keeps two runs off one collection, since a re-index drops and recreates it and
+  // two of those racing would leave half of each.
+async function ragify({ form, res, send, workspace, pathname }) {
+    const dir = workspaceDir(workspace);
+    const script = findRagifyScript(dir);
+    const projectName = String(form.projectName || '');
+    if (!script) return send('<div class="msg error">No ragify script in this workspace.</div>', 400);
+    if (!NAME_RE.test(projectName) || !listProjects(dir).includes(projectName)) {
+      return send('<div class="msg error">Unknown project.</div>', 400);
+    }
+    const instance = ragInstanceFor(workspace, projectName);
+    const { up } = await ragCollections(instance);
+    if (!up) {
+      return send(`<div class="msg error">The ${esc(instance)} RAG server is not running — start it from the <a href="${wsUrl('rag')}">RAG workspace</a> first.</div>`, 409);
+    }
+    const jobKey = `ragify:${workspace}/${projectName}`;
+    if (runningJobKey(jobKey)) {
+      return send('<div class="msg error">This project is already being indexed.</div>', 409);
+    }
+    // BM25 inside the database: no embedding model, no API key, nothing leaves the machine. Long
+    // timeout because a large tree is thousands of chunks.
+    const started = await startInScreen({ workspace, project: projectName, projectDir: dir, ownerDir: path.join(dir, projectName), verb: 'ragify',
+      cmdLine: `bash ${JSON.stringify(script)} ${JSON.stringify(projectName)}`, label: 'ragify' });
+    return send(screenStartedHtml(started, 'ragify', projectName), started.ok ? 200 : (started.already ? 409 : 500));
+}
+
+async function rag_info({ form, res, send, workspace, pathname }) {
+    const projectName = String(form.projectName || '');
+    if (!NAME_RE.test(projectName)) return send('<div class="msg error">Unknown project.</div>', 400);
+    const collection = ragCollectionName(workspace, projectName);
+    const instance = ragInstanceFor(workspace, projectName);
+    const described = await milvusPost('/v2/vectordb/collections/describe', { collectionName: collection }, 4000, instance);
+    const stats = await milvusPost('/v2/vectordb/collections/get_stats', { collectionName: collection }, 4000, instance);
+    if (!described || described.code !== 0) {
+      return send('<div class="msg error">Milvus did not answer for this collection — is the instance running?</div>', 409);
+    }
+    const fields = (described.data.fields || []).map((f) => f.name);
+    const functions = (described.data.functions || []).map((f) => `${f.name} (${f.type || 'function'})`);
+    const rows = stats && stats.code === 0 ? stats.data.rowCount : '?';
+    return send(`<div class="msg assistant">
+      <strong>${esc(collection)}</strong><br>
+      Chunks: <strong>${esc(String(rows))}</strong><br>
+      Fields: <code>${esc(fields.join(', '))}</code><br>
+      Functions: <code>${esc(functions.join(', ') || '—')}</code><br>
+      <span class="uk-text-meta">Retrieval is BM25, built inside Milvus — no embedding model and no API key.</span>
+    </div>`);
+}
+
+  // Search one index. Straight over Milvus's REST API rather than through the Python worker: the
+  // dashboard container has no pymilvus, and full-text search on a BM25 function field takes the
+  // query as plain text in `data`.
+async function rag_search({ form, res, send, workspace, pathname }) {
+    const projectName = String(form.projectName || '');
+    const query = String(form.query || '').trim();
+    if (!NAME_RE.test(projectName)) return send('<div class="msg error">Unknown project.</div>', 400);
+    if (!query) return send('<p class="uk-text-meta">Type a question first.</p>');
+    const collection = ragCollectionName(workspace, projectName);
+    const body = await milvusPost('/v2/vectordb/entities/search', {
+      collectionName: collection,
+      data: [query],
+      annsField: 'sparse',
+      limit: 8,
+      outputFields: ['path', 'start_line', 'end_line', 'text'],
+    }, 20000, ragInstanceFor(workspace, projectName));
+    if (!body || body.code !== 0) {
+      return send(`<div class="msg error">Milvus refused the search${body && body.message ? `: ${esc(body.message)}` : ''}.</div>`);
+    }
+    const hits = body.data || [];
+    if (!hits.length) return send(`<p class="uk-text-meta">No passage in <code>${esc(collection)}</code> matches ${esc(query)}.</p>`);
+    const cards = hits.map((h) => {
+      // The path is indexed as the first line of the chunk (so a filename matches even when the
+      // words are not in the file) — show the body, not that duplicate.
+      const text = String(h.text || '');
+      const nl = text.indexOf('\n');
+      const bodyText = nl === -1 ? text : text.slice(nl + 1);
+      return `<div class="uk-card uk-card-default uk-card-small uk-card-body uk-margin-small">
+        <div class="uk-text-bold">${esc(h.path)}<span class="uk-text-meta">:${esc(String(h.start_line))}-${esc(String(h.end_line))}</span>
+          <span class="uk-label">score ${esc(String(Math.round((h.distance || 0) * 100) / 100))}</span></div>
+        <pre class="uk-margin-small-top" style="max-height:16rem;overflow:auto"><code>${esc(bodyText.split('\n').slice(0, 24).join('\n'))}</code></pre>
+      </div>`;
+    }).join('');
+    return send(`<p class="uk-text-meta">${hits.length} passages for ${esc(query)} in <code>${esc(collection)}</code>, best first.</p>${cards}`);
+}
+
+  // Drop one index. Regenerable by definition — a re-index rebuilds it from the tree — and the
+  // project itself is never touched: nothing of the index lives in it.
+async function rag_remove({ form, res, send, workspace, pathname }) {
+    if (form.confirm !== 'yes') return send('<div class="msg error">Deleting requires confirmation.</div>', 400);
+    const projectName = String(form.projectName || '');
+    if (!NAME_RE.test(projectName)) return send('<div class="msg error">Unknown project.</div>', 400);
+    if (runningJobKey(`ragify:${workspace}/${projectName}`)) {
+      return send('<div class="msg error">An index run is in progress for this project — wait for it to finish.</div>', 409);
+    }
+    const collection = ragCollectionName(workspace, projectName);
+    const body = await milvusPost('/v2/vectordb/collections/drop', { collectionName: collection }, 4000,
+      ragInstanceFor(workspace, projectName));
+    if (!body || body.code !== 0) {
+      return send('<div class="msg error">Milvus did not drop the collection — is the instance running?</div>', 409);
+    }
+    ragInvalidate();
+    res.setHeader('HX-Trigger', 'refresh-projects');
+    return send(`<div class="msg assistant">🗑️ Deleted the index <strong>${esc(collection)}</strong>. Rebuild it any time from the RAG menu.</div>`);
+}
+
+module.exports = {
+  '/actions/rag-mcp-command': rag_mcp_command,
+  '/actions/rag-bind': rag_bind,
+  '/actions/rag-server-new': rag_server_new,
+  '/actions/ragify': ragify,
+  '/actions/rag-info': rag_info,
+  '/actions/rag-search': rag_search,
+  '/actions/rag-remove': rag_remove,
+};