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

package/WORKSPACES.md

@@ -0,0 +1,69 @@
+# Workspace folders: kinds, types and their settings
+
+Every folder listed in `settings.yml`'s `workspaces:` is a workspace. What its page looks like and
+what its rows can do come from two ideas that answer different questions:
+
+- **kind** — how the page is laid out. `projects` (a table of project folders) or `files` (a list
+  of markdown/media items). Presentation, set in the folder's `presentation:` block.
+- **type** — what the projects ARE, and therefore which actions their rows offer. Policy, set with
+  the `type:` key, editable from the Settings page.
+
+A control appears only when **both** layers say yes: the folder must ship the script
+(`cmd-tools-backup-*.sh`, `cmd-tools-upsun.sh`, …) and the type must want the action. Copying a
+stray `cmd` file into a folder no longer grows its interface.
+
+## The types
+
+| Type | For | Project-row actions |
+| --- | --- | --- |
+| `sites` | Built Drupal sites (dev, test, demos, sandboxes, projects, products, profiles, site-templates, rag, designs) | Build, DDEV menu (+Launch), Upsun menu, Backup, Remove, Graph, RAG, Tests, Checks, Users |
+| `code` | Packages and repositories (modules, themes, libraries, recipes, components, forked, graphs) | Build, Backup, Remove, Graph, RAG, Checks |
+| `files` | Documents and drafts (docs, worklogs, specs) | none — the page is an item list |
+| `media` | Images, recordings and sounds (images, videos, audio) | none — the page is an item list |
+| `ai-items` | Claude Code items (agents, skills, prompts) | none — these pages carry their own install/fetch/propose surface |
+
+Defaults live in `core/workspace-app/workspace-types.js`; an unset `type:` resolves to the shipped
+default for that folder, so nothing changes until somebody chooses differently. A brand-new
+workspace folder defaults by its kind: `projects` → `sites`, `files` → `files`.
+
+## A workspace's settings file
+
+`core/config/workspace.<name>.settings.yml`, all keys optional beyond `doc.name`:
+
+```yaml
+doc:
+  name: dev                    # the folder under the workspace root
+  # path: /elsewhere/dev       # override the location entirely
+
+# What this folder's projects are, and which actions their rows offer.
+type: sites                    # sites | code | files | media | ai-items
+
+# What the COMPOSER menu may do on a folder with a composer.json.
+composer: full                 # full = install, update, scripts… (dev, test, demos, sandboxes, projects)
+                               # manifest (the default) = only add to composer.json, never install
+
+presentation:                  # the card and rail — icon, words, layout
+  icon: tabler:code
+  label: Dev
+  subtitle: Development Projects
+  noun: project                # what one item is called
+  plural: projects
+  kind: projects               # projects | files — the page layout
+  also_files: false            # true = project table AND file list (designs)
+```
+
+Everything is read live (2s memo): edit the file or use the Settings page, reload, done.
+
+## Adding a new workspace folder
+
+1. Add its name to `workspaces:` in `settings.yml` (or drag-create from the dashboard).
+2. Create `core/config/workspace.<name>.settings.yml` with `doc.name` and pick a `type:`.
+3. Drop the `cmd-*.sh` scripts it should serve — copy them from a folder of the same type; each
+   one self-locates the tooling, so they work wherever they land.
+4. Optional: a `presentation:` block for the icon and words, an `AGENTS.md` for sessions.
+
+## Extending a workspace
+
+Per-workspace features beyond the type's action set are plugins — `settings.yml plugins:` decides
+which load and which workspaces they apply to, and a plugin can add rail buttons, per-project-row
+buttons, fragments and actions without touching core code. See `PLUGINS.md`.

package/actions/ai-items.js

@@ -0,0 +1,293 @@
+/**
+ * The AI-items actions: everything a row or the rail can do to an agent, a
+ * skill or a prompt — sync, fetch, add from any repo, update, install, save,
+ * delete, propose, clone, generate. One module per area of the dashboard;
+ * server.js merges the maps and dispatches. The shared primitives live in
+ * ../ai-items, which the rendering imports too, so a button and its badge can
+ * never disagree.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('../html');
+const { VIDEO_RE, DOC_ARTIFACT_RE } = require('../format');
+const { ROOT, loadWorkspaces, workspaceDir, isValidWorkspace } = require('../workspaces');
+const filesBrowser = require('../files-browser');
+const { screenAction } = require('../jobs');
+const { NAME_RE, ITEM_NAME_RE } = require('../validate');
+const {
+  INSTALL_TARGETS, NO_CLAUDE_SYNC, AI_ITEMS_REPO, AI_ITEMS_REPO_PATHS, AI_ITEMS_PROJECT_PATHS,
+  itemFile, invalidateRepoCaches,
+} = require('../ai-items');
+
+async function save_item({ form, res, send, workspace, pathname }) {
+    const meta = loadWorkspaces()[workspace];
+    if (meta.kind !== 'files') return send('<div class="msg error">Not an editable workspace.</div>', 400);
+    const name = String(form.name || '');
+    if (!ITEM_NAME_RE.test(name)) return send('<div class="msg error">A name starts with a letter or digit and holds letters, digits, dots, dashes and underscores.</div>', 400);
+    const content = String(form.content || '').replace(/\r\n/g, '\n');
+    if (content.length > 500000) return send('<div class="msg error">Content too large.</div>', 400);
+    const file = itemFile(workspace, name);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content);
+    res.setHeader('HX-Trigger', 'refresh-projects');
+    return send(`<div class="msg assistant">✅ Saved <strong>${esc(name)}</strong> (${esc(path.relative(ROOT, file))}).</div>`);
+  }
+
+async function sync_items({ form, res, send, workspace, pathname }) {
+    const key = workspace;
+    const dir = workspaceDir(key);
+    const script = 'cmd-tools-ai-items.sh';
+    if (!AI_ITEMS_REPO_PATHS[key] || !fs.existsSync(path.join(dir, script))) {
+      return send('<div class="msg error">No sync script in this workspace.</div>', 400);
+    }
+    // Only the directions the script understands. Reading ~/.claude keeps
+    // the script's own name filter, so client and third-party items stay out of
+    // a folder that may end up in a shared repository.
+    const source = ['claude', 'install', 'check', 'update'].includes(form.source) ? form.source : 'repo';
+    if (NO_CLAUDE_SYNC.has(key) && ['install', 'check', 'update', 'claude'].includes(source)) {
+      return send('<div class="msg error">Prompts are launch templates for a new screen, not slash commands — pull from the shared repo instead.</div>', 400);
+    }
+    const flags = source === 'install' ? ['--install']
+      : source === 'claude' ? ['--pull', '--source', 'claude']
+      : source === 'check' ? ['--check']
+      : source === 'update' ? ['--update']
+      : ['--pull'];
+    invalidateRepoCaches(key);
+    return screenAction(send, { workspace: key, project: source, projectDir: dir, verb: 'sync',
+      cmdLine: `bash ${script} ${flags.join(' ')}`, label: `${source} ${key}` });
+  }
+
+async function fetch_item({ form, res, send, workspace, pathname }) {
+    const key = workspace;
+    const name = String(form.name || '');
+    if (!AI_ITEMS_REPO_PATHS[key]) return send('<div class="msg error">Not a fetchable workspace.</div>', 400);
+    if (!ITEM_NAME_RE.test(name)) return send('<div class="msg error">Invalid name.</div>', 400);
+    const dir = workspaceDir(key);
+    const script = 'cmd-tools-ai-items.sh';
+    if (!fs.existsSync(path.join(dir, script))) {
+      return send('<div class="msg error">This workspace has no cmd-tools-ai-items.sh.</div>', 400);
+    }
+    const toClaude = pathname === '/actions/fetch-item';
+    if (toClaude && NO_CLAUDE_SYNC.has(key)) {
+      return send('<div class="msg error">Prompts stay in this workspace folder — use “Copy here to edit” instead.</div>', 400);
+    }
+    const flag = toClaude ? '--fetch' : '--pull';
+    invalidateRepoCaches(key);
+    return screenAction(send, { workspace: key, project: name, projectDir: dir,
+      verb: toClaude ? 'fetch' : 'copy',
+      cmdLine: `bash ${script} ${JSON.stringify(name)} ${flag}`,
+      label: toClaude ? `fetch ${name} into ~/.claude` : `copy ${name} into ${key}/` });
+  }
+
+async function add_item({ form, res, send, workspace, pathname }) {
+    const key = workspace;
+    if (!AI_ITEMS_REPO_PATHS[key] || NO_CLAUDE_SYNC.has(key)) return send('<div class="msg error">Not an installable workspace.</div>', 400);
+    const dir = workspaceDir(key);
+    const script = 'cmd-tools-ai-items.sh';
+    if (!fs.existsSync(path.join(dir, script))) {
+      return send('<div class="msg error">This workspace has no cmd-tools-ai-items.sh.</div>', 400);
+    }
+    // The script re-validates the source; this only keeps junk out of the job line.
+    const source = String(form.source || '').trim();
+    if (!/^(https:\/\/github\.com\/[\w./@-]+|[\w.-]+\/[\w.-]+(@[\w./-]+)?)$/.test(source) || source.includes('..')) {
+      return send('<div class="msg error">Use owner/repo, owner/repo@branch, or a github.com URL.</div>', 400);
+    }
+    const name = String(form.name || '').trim();
+    if (name && !ITEM_NAME_RE.test(name)) return send('<div class="msg error">Invalid name.</div>', 400);
+    const toWorkspace = String(form.toWorkspace || '').trim();
+    const toProject = String(form.toProject || '').trim();
+    const args = [script, ...(name ? [name] : []), '--add', source];
+    let where = '~/.claude';
+    if (toWorkspace) {
+      if (!isValidWorkspace(toWorkspace)) return send('<div class="msg error">Unknown target workspace.</div>', 400);
+      if (!toProject || !NAME_RE.test(toProject)) return send('<div class="msg error">Name the project to install into.</div>', 400);
+      if (!fs.existsSync(path.join(workspaceDir(toWorkspace), toProject))) {
+        return send(`<div class="msg error">No ${esc(toWorkspace)}/${esc(toProject)}.</div>`, 404);
+      }
+      args.push('--to', `${toWorkspace}/${toProject}`);
+      where = `${toWorkspace}/${toProject}`;
+    }
+    invalidateRepoCaches(key);
+    return screenAction(send, { workspace: key, project: name || `all-${key}`, projectDir: dir, verb: 'add',
+      cmdLine: `bash ${args.map((a) => JSON.stringify(a)).join(' ')}`,
+      label: `add ${name || `all ${key}`} → ${where}` });
+  }
+
+async function update_one_item({ form, res, send, workspace, pathname }) {
+    const key = workspace;
+    const name = String(form.name || '');
+    if (!AI_ITEMS_REPO_PATHS[key]) return send('<div class="msg error">Not a shared-items workspace.</div>', 400);
+    if (!ITEM_NAME_RE.test(name)) return send('<div class="msg error">Invalid name.</div>', 400);
+    const dir = workspaceDir(key);
+    const script = 'cmd-tools-ai-items.sh';
+    if (!fs.existsSync(path.join(dir, script))) {
+      return send('<div class="msg error">This workspace has no cmd-tools-ai-items.sh.</div>', 400);
+    }
+    // Take the repo's version of this one item into THIS FOLDER only. These folders are
+    // the staging area where items get worked on; reaching ~/.claude or a project is a
+    // separate, explicit Install.
+    const shellLine = `bash ${script} ${JSON.stringify(name)} --pull`;
+    invalidateRepoCaches(key);
+    return screenAction(send, { workspace: key, project: name, projectDir: dir, verb: 'update',
+      cmdLine: shellLine, label: `update ${name}` });
+  }
+
+async function install_item({ form, res, send, workspace, pathname }) {
+    const meta = loadWorkspaces()[workspace];
+    if (!INSTALL_TARGETS[workspace] || meta.kind !== 'files') return send('<div class="msg error">This workspace has no install target.</div>', 400);
+    if (NO_CLAUDE_SYNC.has(workspace)) return send('<div class="msg error">Prompts run a new screen session — they do not install into ~/.claude or a project.</div>', 400);
+    const name = String(form.name || '');
+    if (!ITEM_NAME_RE.test(name)) return send('<div class="msg error">Invalid name.</div>', 400);
+    const src = itemFile(workspace, name);
+    if (!fs.existsSync(src)) return send('<div class="msg error">Item not found.</div>', 404);
+
+    // Global by default; a chosen workspace + project puts it in that project's own .claude/
+    // instead, reaching only sessions started under it — same mechanism cmd-tools-ai-items.sh
+    // --to uses, so a --to install and this button never disagree about where things land.
+    const toWorkspace = String(form.toWorkspace || '').trim();
+    const toProject = String(form.toProject || '').trim();
+    let target = INSTALL_TARGETS[workspace];
+    let where = '~/.claude';
+    if (toWorkspace) {
+      if (!isValidWorkspace(toWorkspace)) return send('<div class="msg error">Unknown target workspace.</div>', 400);
+      if (!toProject || !NAME_RE.test(toProject)) return send('<div class="msg error">Name the project to install into.</div>', 400);
+      const projectDir = path.join(workspaceDir(toWorkspace), toProject);
+      if (!fs.existsSync(projectDir)) return send(`<div class="msg error">No ${esc(toWorkspace)}/${esc(toProject)}.</div>`, 404);
+      target = path.join(projectDir, AI_ITEMS_PROJECT_PATHS[workspace]);
+      where = `${toWorkspace}/${toProject}/${AI_ITEMS_PROJECT_PATHS[workspace]}`;
+    }
+
+    fs.mkdirSync(target, { recursive: true });
+    let dest;
+    if (workspace === 'ai-skills') {
+      dest = path.join(target, name, 'SKILL.md');
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+    } else {
+      dest = path.join(target, `${name}.md`);
+    }
+    fs.copyFileSync(src, dest);
+    const usage = workspace === 'ai-prompts' && !toWorkspace ? ` — available in Claude Code as <code>/${esc(name)}</code>` : '';
+    const reach = toWorkspace ? `sessions started under ${esc(toWorkspace)}/${esc(toProject)}` : 'Claude Code sessions';
+    return send(`<div class="msg assistant">✅ Installed <strong>${esc(name)}</strong> to <code>${esc(where)}</code>${usage}. Restart ${reach} to pick it up.</div>`);
+  }
+
+async function delete_item({ form, res, send, workspace, pathname }) {
+    const meta = loadWorkspaces()[workspace];
+    if (meta.kind !== 'files') return send('<div class="msg error">Not an editable workspace.</div>', 400);
+    if (form.confirm !== 'yes') return send('<div class="msg error">Deleting requires confirmation.</div>', 400);
+    // `names` deletes every format of one document or recording, which is what a grouped
+    // row offers; `name` stays for a single markdown item or skill.
+    const targets = String(form.names || form.name || '').split(',').map((n) => n.trim()).filter(Boolean);
+    if (!targets.length) return send('<div class="msg error">Nothing named to delete.</div>', 400);
+    for (const t of targets) {
+      if (!/^[a-zA-Z0-9_.-]+$/.test(t) || t.includes('..')) return send('<div class="msg error">Invalid name.</div>', 400);
+    }
+    // Which folder the row was in. A name is still a plain name — the subfolder is separate and
+    // resolved by the same check the listing uses (segments, then realpath), so a delete can reach
+    // into a folder you are browsing and nowhere else.
+    const where = filesBrowser.safeSub(workspace, form.dir || '');
+    if (!where.ok) return send('<div class="msg error">No such folder.</div>', 400);
+    const base = where.abs;
+    const inSub = !!where.rel;
+    const removed = [];
+    for (const name of targets) {
+      // Match on what the workspace actually lists. This used to test /\.(pdf|html)$/
+      // only, so once docs listed Office files and videos listed recordings, deleting
+      // either fell through to the markdown branch, looked for "<name>.mp4.md", found
+      // nothing and reported "(nothing found)" while leaving the file in place.
+      if (inSub || DOC_ARTIFACT_RE.test(name) || VIDEO_RE.test(name)) {
+        // Inside a folder every row is a file, whatever its extension: the browsable workspaces list
+        // what is there rather than a curated set, so the delete has to cover the same ground or a
+        // row offers a button that reports "(nothing found)".
+        const f = path.join(base, name);
+        if (fs.existsSync(f) && fs.statSync(f).isFile()) { fs.unlinkSync(f); removed.push(where.rel ? `${where.rel}/${name}` : name); }
+      } else if (workspace === 'ai-skills') {
+        const d = path.join(meta.dir, name);
+        if (fs.existsSync(path.join(d, 'SKILL.md'))) { fs.rmSync(d, { recursive: true }); removed.push(name); }
+      } else {
+        const f = itemFile(workspace, name);
+        if (fs.existsSync(f)) { fs.unlinkSync(f); removed.push(`${name}.md`); }
+      }
+    }
+    res.setHeader('HX-Trigger', 'refresh-projects');
+    return send(`<div class="msg assistant">🗑️ Deleted: ${esc(removed.join(', ') || '(nothing found)')}</div>`);
+  }
+
+async function propose_item({ form, res, send, workspace, pathname }) {
+    const meta = loadWorkspaces()[workspace];
+    if (!AI_ITEMS_REPO_PATHS[workspace] || meta.kind !== 'files') return send('<div class="msg error">Proposing is for agents, skills, and prompts.</div>', 400);
+    const name = String(form.name || '');
+    if (!ITEM_NAME_RE.test(name)) return send('<div class="msg error">Invalid name.</div>', 400);
+    const summary = String(form.summary || '').slice(0, 2000).trim();
+    const confirmed = String(form.confirm || '') === 'yes';
+    if (confirmed && !summary) return send('<div class="msg error">Say what it is for — it goes into the issue and the PR.</div>', 400);
+    const script = 'cmd-tools-ai-items.sh';
+    if (!fs.existsSync(path.join(meta.dir, script))) {
+      return send('<div class="msg error">This workspace has no cmd-tools-ai-items.sh.</div>', 400);
+    }
+    const args = [script, name, '--propose', '--summary', summary || '(no summary given)'];
+    if (confirmed) args.push('--confirm');
+    return screenAction(send, { workspace, project: name, projectDir: meta.dir,
+      verb: confirmed ? 'propose' : 'propose-dry-run',
+      cmdLine: `bash ${args.map((a) => JSON.stringify(a)).join(' ')}`,
+      label: confirmed ? `propose ${name} upstream` : `what proposing ${name} would do` });
+  }
+
+async function clone_item({ form, res, send, workspace, pathname }) {
+    const meta = loadWorkspaces()[workspace];
+    if (!INSTALL_TARGETS[workspace] || meta.kind !== 'files') return send('<div class="msg error">Cloning is for agents, skills, and prompts.</div>', 400);
+    const name = String(form.name || '');
+    const cloneTo = String(form.cloneTo || '');
+    const purpose = String(form.purpose || '').slice(0, 2000).trim();
+    if (!NAME_RE.test(name) || !NAME_RE.test(cloneTo)) return send('<div class="msg error">Invalid name.</div>', 400);
+    if (name === cloneTo) return send('<div class="msg error">Give the copy a different name.</div>', 400);
+
+    // The CLI owns the copy, the identity rewrite and the AI pass, so the button
+    // and `bash cmd-tools-ai-items.sh` cannot drift apart. A purpose means a
+    // claude run, which is slow — hence a job with the AI timeout, not an
+    // inline response.
+    const args = [`${name}`, '--clone-to', cloneTo];
+    if (purpose) args.push('--purpose', purpose);
+    const shellLine = `bash cmd-tools-ai-items.sh ${args.map((a) => JSON.stringify(a)).join(' ')}`;
+    res.setHeader('HX-Trigger', 'refresh-projects');
+    return screenAction(send, { workspace, project: cloneTo, projectDir: meta.dir, verb: 'clone',
+      cmdLine: shellLine, label: `clone ${name} to ${cloneTo}` });
+  }
+
+async function generate_item({ form, res, send, workspace, pathname }) {
+    const target = INSTALL_TARGETS[workspace];
+    const meta = loadWorkspaces()[workspace];
+    if (!target || meta.kind !== 'files') return send('<div class="msg error">AI generation is for agents, skills, and prompts.</div>', 400);
+    const name = String(form.name || '');
+    const description = String(form.description || '').slice(0, 2000);
+    if (!ITEM_NAME_RE.test(name)) return send('<div class="msg error">Invalid name.</div>', 400);
+    if (!description.trim()) return send('<div class="msg error">Describe what it should do.</div>', 400);
+
+    const SPECS = {
+      agents: `a Claude Code CLI subagent definition markdown file. It MUST start with YAML frontmatter delimited by --- lines containing: name: ${name}, a one-paragraph description: telling Claude when to invoke this agent (starting "Use this agent to"), and a tools: list (only the tools it truly needs from Bash, Read, Write, Edit, Glob, Grep, WebFetch). After the frontmatter: a # ${name} heading, a role statement, and concrete ## Instructions the agent follows. Study ${ROOT} with your tools first if the description references this workspace.`,
+      skills: `a Claude Code CLI skill (SKILL.md) markdown file. It MUST start with YAML frontmatter delimited by --- lines containing: name: ${name} and a one-line description: saying what the skill does and when to use it. After the frontmatter: a # ${name} heading and precise step-by-step ## Instructions. Study ${ROOT} with your tools first if the description references this workspace.`,
+      prompts: `a reusable prompt file kept in this workspace's prompts folder (nothing installs into ~/.claude). Plain markdown, no frontmatter: just the complete, well-structured prompt text a user would paste or run repeatedly. Make it specific and actionable.`,
+    };
+    const file = itemFile(workspace, name);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    const genPrompt = `Write ${SPECS[workspace]}\n\nWhat it should do: ${description}\n\nOutput ONLY the raw file content — no surrounding commentary, no code fences.`;
+    const shellLine = `set -e; echo "Generating ${meta.noun} '${name}' with AI…"; claude -p ${JSON.stringify(genPrompt)} --allowedTools Read Glob Grep --disallowedTools Write Edit Bash --no-session-persistence > ${JSON.stringify(file)}; echo "Written: ${path.relative(ROOT, file)}"; head -20 ${JSON.stringify(file)}`;
+    return screenAction(send, { workspace, project: name, projectDir: meta.dir, verb: 'generate',
+      cmdLine: shellLine, label: `generate the ${meta.noun} ${name}` });
+  }
+
+module.exports = {
+  '/actions/save-item': save_item,
+  '/actions/sync-items': sync_items,
+  '/actions/fetch-item': fetch_item,
+  '/actions/pull-item': fetch_item,
+  '/actions/add-item': add_item,
+  '/actions/update-one-item': update_one_item,
+  '/actions/install-item': install_item,
+  '/actions/delete-item': delete_item,
+  '/actions/propose-item': propose_item,
+  '/actions/clone-item': clone_item,
+  '/actions/generate-item': generate_item,
+};

package/actions/audio.js

@@ -0,0 +1,48 @@
+/**
+ * The audio actions: generate a voice from text with Piper or ElevenLabs.
+ *
+ * The form is `audio-voice.js`; the work is `audio/cmd-tools-voice.sh`, run on the host in a screen
+ * session like every other long action. Anything that spends credits needs `confirm=yes`, which only
+ * the confirm dialog's button sends, and the command refuses to spend without its own `--confirm`.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('../html');
+const { workspaceDir } = require('../workspaces');
+const { startInScreen, screenStartedHtml } = require('../jobs');
+const voice = require('../audio-voice');
+
+async function generate_voice({ form, res, send, workspace }) {
+  if (workspace !== 'audio') return send('<div class="msg error">Voices are generated in the audio workspace.</div>', 400);
+  const found = await voice.loadEngines();
+  const p = voice.plan(form, found.engines);
+  if (p.error) return send(`<div class="msg error">${esc(p.error)}</div>`, 400);
+  if (p.engine === 'elevenlabs' && form.confirm !== 'yes') {
+    return send('<div class="msg error">ElevenLabs spends credits, so it needs your confirmation.</div>', 400);
+  }
+  // A script chosen from docs/ is read where it is; pasted text goes through a private temporary file.
+  const textFile = p.scriptPath ? null : voice.writeText(p.kind === 'video' ? p.script : p.text);
+  const opts = { workspace, project: path.basename(p.file, `.${p.ext}`), projectDir: workspaceDir('audio'),
+    verb: 'voice', cmdLine: voice.commandLine(p, textFile, true), label: `${p.engine} ${p.kind === 'video' ? 'voiceover' : 'voice'} ${p.file}` };
+  const started = await startInScreen(opts);
+  // The command removes the text itself once it has run; when nothing started, nothing will.
+  if (!started.ok) {
+    if (textFile) fs.rmSync(path.dirname(textFile), { recursive: true, force: true });
+    return send(screenStartedHtml(started, opts.label, opts.project), started.already ? 409 : 500);
+  }
+  // The modal stays open and says it is working; it asks again until the file is there.
+  return send(voice.progressHtml({ kind: p.kind, file: p.file, session: started.session, t0: Date.now(), engine: p.engine }, null));
+}
+
+/** The plan for a video voiceover: nothing runs, and nothing is spent. */
+async function voiceover_plan({ form, send, workspace }) {
+  if (workspace !== 'audio') return send('<div class="msg error">Voices are generated in the audio workspace.</div>', 400);
+  const found = await voice.loadEngines();
+  const p = voice.plan({ ...form, kind: 'video' }, found.engines);
+  if (p.error) return send(`<div class="msg error">${esc(p.error)}</div>`, 400);
+  return send(voice.planHtml(p, found));
+}
+
+module.exports = { '/actions/generate-voice': generate_voice, '/actions/voiceover-plan': voiceover_plan };

package/actions/build-order.js

@@ -0,0 +1,79 @@
+/**
+ * Writing the order of the builders in Build a new project.
+ *
+ * One form carries the whole arrangement, and every write carries the file's mtime and is refused with
+ * 409 when it changed since — the same rule as every other writer here, and it matters more than usual
+ * on this one: two people arranging the same list would otherwise silently keep whichever saved last.
+ *
+ * **Only what was moved is written.** The form posts every row, but a list that recorded all of them
+ * would freeze the order of commands nobody has an opinion about: one added next month would then land
+ * at the bottom rather than in its shipped place, and the file would assert decisions nobody made. So
+ * what is written is the SHORTEST list that reproduces what you see — see `minimalOrder`.
+ */
+
+const order = require('../build-order');
+const page = require('../build-order-page');
+const { loadWorkspaces } = require('../workspaces');
+
+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]));
+
+/** 'global', or a workspace that really exists; anything else is refused rather than written. */
+function scopeOf(form) {
+  const want = String(form.scope || 'global');
+  if (want === 'global') return 'global';
+  return loadWorkspaces()[want] ? want : null;
+}
+
+function editor(send, form, message, status = 200) {
+  const scope = scopeOf(form) || 'global';
+  return send(page.editorHtml(scope, message), status);
+}
+
+async function build_order_save({ form, send }) {
+  const scope = scopeOf(form);
+  if (!scope) return send(bad('No such workspace.'), 400);
+
+  // One form, two lists. A kind that was not posted is left ALONE rather than emptied: a page that
+  // showed no tools must not be able to erase the tool order somebody set on another tab.
+  const posted = {
+    builders: [...new Set(asArray(form.builder).map(String).filter(order.isBuilder))],
+    tools: [...new Set(asArray(form.tool).map(String).filter(order.isTool))],
+  };
+  if (!posted.builders.length && !posted.tools.length) {
+    return editor(send, form, bad('Nothing to save: no commands were posted.'), 400);
+  }
+
+  const { raw, mtime } = order.rawOrder();
+  if (String(form.mtime || '') !== String(mtime)) {
+    return editor(send, form,
+      bad('The command order changed somewhere else while this was open — nothing was written. This is how it is now.'), 409);
+  }
+
+  const kept = {};
+  let placed = 0;
+  for (const kind of order.KINDS) {
+    if (!posted[kind].length) continue;            // not posted: withScope keeps what is on disk
+    kept[kind] = order.minimalOrder(posted[kind], scope, kind);
+    placed += kept[kind].length;
+  }
+  order.saveOrder(order.withScope(raw, scope, kept));
+  return editor(send, form, ok(placed
+    ? `Command order saved — ${placed} placed by this list, the rest left where they were. It applies on the next page you open.`
+    : 'Command order saved. Nothing here differs from the shipped order, so this scope names nothing — which is what makes a command added later still arrive in the right place.'));
+}
+
+async function build_order_reset({ form, send }) {
+  const scope = scopeOf(form);
+  if (!scope) return send(bad('No such workspace.'), 400);
+  const { raw } = order.rawOrder();
+  order.saveOrder(order.withScope(raw, scope, Object.fromEntries(order.KINDS.map((k) => [k, []]))));
+  return editor(send, form, ok('Back to the shipped order.'));
+}
+
+module.exports = {
+  '/actions/build-order-save': build_order_save,
+  '/actions/build-order-reset': build_order_reset,
+};

package/actions/checks.js

@@ -0,0 +1,95 @@
+/**
+ * Running the checks a project already declares, from the dashboard.
+ *
+ * Two handlers. `/actions/checks-plan` answers instantly and starts nothing — it is the same
+ * `--list` the command prints, so you can see what a package covers before deciding to run it.
+ * `/actions/checks` starts the real thing as a job, because a full set on a large package is
+ * minutes of work and belongs in a toast rather than in a request.
+ *
+ * Neither ever passes a writing flag. The command has one (`--fix`); the dashboard does not send it,
+ * because a button that rewrites source files on a click is not a button anybody should press by
+ * accident.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { esc } = require('../html');
+const { workspaceDir } = require('../workspaces');
+const { jobFragment, runningJobKey, startJob, listProjects , startInScreen, screenStartedHtml } = require('../jobs');
+const { NAME_RE } = require('../validate');
+const { checksDeclaredOf } = require('../checks');
+
+const SCRIPT = 'cmd-tools-checks.sh';
+
+// The guards every handler here repeats: a real workspace folder that ships the command, a project
+// name that is a name, and a project that is actually in that folder.
+function target(form, workspace) {
+  const dir = workspaceDir(workspace);
+  const projectName = String(form.projectName || '');
+  if (!fs.existsSync(path.join(dir, SCRIPT))) return { error: 'This workspace has no checks command.' };
+  if (!NAME_RE.test(projectName) || !listProjects(dir).includes(projectName)) return { error: 'Unknown project.' };
+  return { dir, projectName };
+}
+
+// The plan, rendered as the table the command prints. No job: this is filesystem work.
+async function checks_plan({ form, send, workspace }) {
+  const t = target(form, workspace);
+  if (t.error) return send(`<div class="msg error">${esc(t.error)}</div>`, 400);
+
+  const { resolvePlan } = require(path.join(require('../workspaces').ROOT, 'core', 'scripts', 'libs', 'checks_plan'));
+  let plan;
+  try {
+    plan = resolvePlan(path.join(t.dir, t.projectName));
+  } catch (e) {
+    return send(`<div class="msg error">Could not read that package: ${esc(e.message)}</div>`, 500);
+  }
+
+  const symbol = { ready: '✅', masked: '⛔', refused: '🚫', skipped: '⏭', 'deps-missing': '⏭', 'unresolved-runner': '⏭', none: '➖' };
+  const rows = plan.rows.map((r) => `
+      <tr class="checks-row is-${esc(r.status)}">
+        <td>${symbol[r.status] || '➖'}</td>
+        <td><code>${esc(r.id)}</code></td>
+        <td>${r.script ? `<code>${esc(r.script)}</code>` : '<span class="uk-text-meta">—</span>'}</td>
+        <td class="uk-text-meta">${esc(r.status === 'ready' ? r.command : r.reason)}</td>
+      </tr>`).join('');
+
+  return send(`
+    <div class="checks-plan">
+      <p class="uk-text-meta uk-margin-remove-bottom">
+        ${plan.hasPackageJson
+          ? `${esc(plan.runner || 'no package manager')} · ${esc(plan.runnerReason)} · dependencies ${plan.deps.installed ? 'installed' : `<strong>not installed</strong> (${esc(plan.deps.evidence)})`}`
+          : 'This project has no package.json — only the checks a DDEV add-on provides can apply.'}
+      </p>
+      <table class="uk-table uk-table-small uk-table-divider checks-table"><tbody>${rows}</tbody></table>
+      <p class="uk-text-meta">Every check this project declares, and the script behind it. Nothing has been run.</p>
+    </div>`);
+}
+
+// The real run, as a job.
+async function checks_run({ form, send, workspace }) {
+  const t = target(form, workspace);
+  if (t.error) return send(`<div class="msg error">${esc(t.error)}</div>`, 400);
+
+  const declared = checksDeclaredOf(t.dir, t.projectName);
+  if (!declared.declared) {
+    return send('<div class="msg error">This project declares no check this command can run — open the plan to see why.</div>', 409);
+  }
+
+  const jobKey = `checks:${workspace}/${t.projectName}`;
+  if (runningJobKey(jobKey)) {
+    return send('<div class="msg error">The checks are already running for this project.</div>', 409);
+  }
+
+  // --only rides through when the row asked for one check; otherwise the whole declared set runs.
+  const only = String(form.only || '').trim();
+  const args = [SCRIPT, t.projectName, ...(only && /^[a-z,]+$/.test(only) ? ['--only', only] : [])];
+  const started = await startInScreen({ workspace, project: t.projectName, projectDir: t.dir, verb: 'checks',
+    cmdLine: `bash ${args.map((a) => JSON.stringify(a)).join(' ')}`, label: 'checks' });
+  return send(screenStartedHtml(started, 'checks', t.projectName), started.ok ? 200 : (started.already ? 409 : 500));
+}
+
+module.exports = {
+  '/actions/checks': checks_run,
+  '/actions/checks-plan': checks_plan,
+};