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

package/claude-args.js

@@ -0,0 +1,282 @@
+/**
+ * The Claude Code CLI's own arguments, read from `claude --help`.
+ *
+ * The New screen form used to offer a permission-mode select and one free-text box labelled "more
+ * claude options" — which means knowing the flags by heart, and typing them without a single check
+ * until the screen either starts or dies. The CLI already documents every one of them, so this parses
+ * what it prints rather than keeping a hand-written list that drifts the next time it gains a flag.
+ *
+ * Two things fall out of that:
+ *
+ *   - every option is offered with the control its own shape asks for — a checkbox for a flag, a select
+ *     for one with `(choices: …)`, a field for one that takes a value;
+ *   - a value is checked against that shape before it reaches a shell line, instead of a charset test
+ *     over one long string.
+ *
+ * **Not every flag belongs on a screen.** A screen is an interactive terminal in a directory — that is
+ * the whole point of starting one — so the flags that only work with `--print`, the ones that start the
+ * session somewhere else (the cloud, the background, a remote control), and the ones this form already
+ * asks about itself (the resume row, the prompt field) are held back, each with the reason. Everything
+ * else is offered, including flags that did not exist when this was written.
+ */
+
+const { execFile } = require('child_process');
+
+/* ------------------------------------------------------------------ *
+ * Parsing `claude --help`
+ * ------------------------------------------------------------------ */
+
+/**
+ * One option of the Options: block. The flag line is `  -p, --print`, `  --add-dir <directories...>`,
+ * `  --autocompact <auto|tokens>` or `  --cloud [description|session_id|url]`, and its description runs
+ * on until the next one — wrapped, and sometimes starting on the line below when the flags are long.
+ */
+function parseOptions(help) {
+  const body = help.slice(help.indexOf('\nOptions:'));
+  const end = body.indexOf('\nCommands:');
+  const lines = (end < 0 ? body : body.slice(0, end)).split('\n').slice(1);
+
+  const out = [];
+  let current = null;
+  for (const line of lines) {
+    const start = line.match(/^ {2}(-[^\s].*)$/);
+    if (start) {
+      if (current) out.push(current);
+      // Two columns: the flags, then a run of 2+ spaces, then the description — which wraps, and which
+      // starts on the NEXT line when the flags are too long for the column. Splitting on the first wide
+      // gap is what tells the two apart; without it the description was read as part of the flag name.
+      const both = start[1].match(/^(.*?)(?:\s{2,}(.*))?$/);
+      current = { spec: both[1].trim(), text: (both[2] || '').trim() };
+      continue;
+    }
+    if (!current) continue;
+    const cont = line.match(/^ {4,}(\S.*)$/);
+    if (cont) current.text += `${current.text ? ' ' : ''}${cont[1].trim()}`;
+  }
+  if (current) out.push(current);
+
+  return out.map(shape).filter(Boolean);
+}
+
+/**
+ * A raw entry as something to render and to check. The flags and the value come off the front of the
+ * spec; anything left on it is the first line of a wrapped description.
+ */
+function shape({ spec, text }) {
+  // The value is the LAST bracketed group of the flag part: `--allowedTools, --allowed-tools <tools...>`.
+  const m = spec.match(/^([^<[]+?)(?:\s+([<[][^\])>]*[\])>]))?\s*$/);
+  if (!m) return null;
+  const flagPart = m[1].trim().replace(/,$/, '');
+  const arg = m[2] || '';
+  const flags = flagPart.split(/,\s*/).map((f) => f.trim()).filter((f) => /^--?[A-Za-z]/.test(f));
+  if (!flags.length) return null;
+  const name = flags.filter((f) => f.startsWith('--')).pop() || flags[0];
+
+  const description = text.replace(/\s+/g, ' ').trim();
+  // Only what the CLI calls a CHOICE is one. `<auto|tokens>` in the flag line is a hint at the shape of
+  // the value ("auto, or 100k-1M tokens"), and rendering that as a select would refuse 200k. The
+  // parenthesis also carries `default:` and `preset:` inside the same list, which are not choices.
+  const choices = (description.match(/\(choices: ([^)]*)\)/) || [])[1];
+
+  return {
+    name,
+    flags,
+    // `<x>` needs a value, `[x]` may take one, neither is a plain flag. `...` means it repeats.
+    takes: arg.startsWith('<') ? 'required' : arg.startsWith('[') ? 'optional' : 'none',
+    repeatable: arg.includes('...'),
+    placeholder: arg.replace(/^[<[]|[\])>]$/g, '').replace(/\.\.\.$/, ''),
+    choices: choices
+      ? choices.split(',').map((c) => c.trim()).filter((c) => c && !c.includes(':'))
+        .map((c) => c.replace(/^"|"$/g, ''))
+      // Some options enumerate their values in PROSE rather than in the `(choices: …)` the help
+      // generator emits — `--effort <level>  Effort level for the current session (low, medium, high,
+      // xhigh, max)`. That is a closed list said in a sentence, and reading it is better than leaving
+      // a field where five known answers have to be typed from memory. Bare lowercase words only, and
+      // three or more of them: `(default: sonnet)` and `(e.g. 'fable', 'opus')` do not match, and
+      // neither does the `<auto|tokens>` shape hint the comment above warns about.
+      : (((description.match(/\((([a-z][a-z0-9-]*)(, [a-z][a-z0-9-]*){2,})\)/) || [])[1] || '')
+        .split(',').map((c) => c.trim()).filter(Boolean)),
+    default: (description.match(/\(default: ([^),]*)\)/) || [])[1] || '',
+    // What the help NAMES as examples, which is not the same as the whole set. `--model` says "an alias
+    // for the latest model (e.g. 'fable', 'opus', or 'sonnet') or a model's full name (e.g.
+    // 'claude-fable-5')" — so those are worth offering, and typing another one has to stay possible.
+    // A closed select here would refuse every model released after this help text was read.
+    suggestions: [...description.matchAll(/'([a-z][a-z0-9.-]{1,40})'/g)].map((m) => m[1]),
+    description,
+  };
+}
+
+/**
+ * The agents `--agent` can actually resolve on this machine.
+ *
+ * Read from the files rather than from a list kept here: the CLI dispatches on the frontmatter `name`,
+ * which is what a file may have been cloned and renamed to, so the name in the file wins over the name
+ * of the file. A project's own `.claude/agents` counts too, which is why the directory is a parameter.
+ *
+ * Suggestions, not a closed list: an agent can also come from a plugin or a directory this does not
+ * know about, and refusing a name the CLI would have accepted is worse than offering an incomplete list.
+ */
+function installedAgents(projectDir) {
+  const fs = require('fs');
+  const path = require('path');
+  const homes = [path.join(process.env.HOME || '', '.claude', 'agents')];
+  if (projectDir) homes.push(path.join(projectDir, '.claude', 'agents'));
+  const names = new Set();
+  for (const dir of homes) {
+    let files = [];
+    try { files = fs.readdirSync(dir).filter((f) => f.endsWith('.md')); } catch (_) { continue; }
+    for (const f of files) {
+      let head = '';
+      try { head = fs.readFileSync(path.join(dir, f), 'utf8').slice(0, 800); } catch (_) { continue; }
+      // An agent is a file with FRONTMATTER naming it — that is what the CLI dispatches on, and it is
+      // also what tells an agent apart from the prose that lives in the same folder: RULES.md there is
+      // the standing working rules, not something `--agent RULES` could ever resolve. Blocklisting the
+      // names of the docs would work until somebody added another one.
+      if (!/^---\s*$/m.test(head.split('\n')[0] || '')) continue;
+      const m = head.match(/^name:\s*["']?([a-zA-Z0-9][a-zA-Z0-9_-]{0,60})["']?\s*$/m);
+      if (!m) continue;
+      names.add(m[1]);
+    }
+  }
+  return [...names].sort();
+}
+
+/* ------------------------------------------------------------------ *
+ * What belongs on a screen
+ * ------------------------------------------------------------------ */
+
+/**
+ * Held back, each with the reason it is not offered. Stated rather than filtered by a clever rule: a
+ * person reading this should be able to see why a flag they know is missing, and disagree with it.
+ */
+const WITHHELD = {
+  '--help': 'prints the help and exits',
+  '--version': 'prints the version and exits',
+  '--print': 'a screen IS the interactive session; --print exits as soon as it has answered',
+  '--resume': 'the Resume row above asks this, and checks the id against the sessions that directory has',
+  '--continue': 'takes the most recent session for the directory, which after a day of parallel work is often not the one meant — resume by id instead',
+  '--from-pr': 'opens its own picker over the session this form is starting',
+  '--session-id': 'a new session gets its own id; naming one that exists resumes it, which the Resume row does',
+  '--background': 'returns immediately, so the screen would hold nothing',
+  '--bg': 'returns immediately, so the screen would hold nothing',
+  '--cloud': 'runs the session somewhere else, so a screen on this machine is not where it is',
+  '--environment': 'belongs to a cloud session',
+  '--teleport': 'resumes a teleport session rather than starting one here',
+  '--remote-control': 'a screen is already the way back to this session, through screen -r',
+  '--remote-control-session-name-prefix': 'belongs to Remote Control',
+  '--tmux': 'a tmux inside a screen is two multiplexers over one session',
+  '--ide': 'connects to an IDE on this machine, which a detached session has no window in',
+  '--chrome': 'drives a browser on the desktop, which a detached session cannot show',
+  '--no-chrome': 'the integration is off unless --chrome asks for it',
+  '--file': 'downloads resources by id, which belongs to a hosted session',
+  '--permission-prompts': 'answers prompts for --print; on a screen a person is sitting in front of it',
+  '--json-schema': 'validates structured output, which needs --print to have any output to validate',
+};
+
+/** Only works when the CLI is printing rather than running a session. */
+const PRINT_ONLY = /only works with (--print|--input-format|--output-format)|\(only works with --print\)/i;
+
+function usableOnAScreen(opt) {
+  if (WITHHELD[opt.name]) return false;
+  if (opt.flags.some((f) => WITHHELD[f])) return false;
+  return !PRINT_ONLY.test(opt.description);
+}
+
+/* ------------------------------------------------------------------ *
+ * Reading it, once
+ * ------------------------------------------------------------------ */
+
+// The help text changes only when the CLI is updated, and the form is drawn on every modal open — so it
+// is read once and kept. A failure is kept too, briefly: a machine with no claude on PATH must not shell
+// out on every keystroke to be told so again.
+let memo = { at: 0, options: null, error: '' };
+const TTL = 10 * 60 * 1000;
+const FAIL_TTL = 30 * 1000;
+
+function helpText() {
+  return new Promise((resolve) => {
+    execFile('claude', ['--help'], { timeout: 15000, maxBuffer: 4 * 1024 * 1024 }, (err, stdout, stderr) => {
+      // Commander prints its help on stdout; a version that uses stderr is still the help.
+      const text = `${stdout || ''}${stderr || ''}`;
+      if (text.includes('\nOptions:')) return resolve({ text });
+      resolve({ error: (err && err.message) || 'claude --help printed no options' });
+    });
+  });
+}
+
+/** Every option a screen can be started with, newest help text, cached. */
+async function claudeOptions() {
+  const now = Date.now();
+  const ttl = memo.error ? FAIL_TTL : TTL;
+  if (memo.options && now - memo.at < ttl) return memo;
+  const { text, error } = await helpText();
+  memo = error
+    ? { at: now, options: [], error }
+    : { at: now, options: parseOptions(text).filter(usableOnAScreen), error: '' };
+  return memo;
+}
+
+/** Forget what was read — for a test, and for a machine that has just updated the CLI. */
+function forget() { memo = { at: 0, options: null, error: '' }; }
+
+/* ------------------------------------------------------------------ *
+ * How the form shows them
+ * ------------------------------------------------------------------ */
+
+/**
+ * The handful that are asked about every time, in the order someone reaches for them. Everything else is
+ * behind "All options", so the form opens as four controls rather than fifty.
+ */
+const COMMON = ['--model', '--permission-mode', '--effort', '--agent'];
+
+/** A field name that cannot collide with the form's own: `--add-dir` posts as `arg_add_dir`. */
+const fieldName = (name) => `arg_${name.replace(/^--/, '').replace(/[^A-Za-z0-9]+/g, '_')}`;
+
+/** The option a posted field name belongs to. */
+function optionFor(options, field) {
+  return options.find((o) => fieldName(o.name) === field) || null;
+}
+
+/**
+ * A value on its way to a shell line. The line is handed to an outer shell, so a value may hold no
+ * quote, no backtick, no `$` and no newline — the same rule every command in this dashboard follows.
+ * A value that breaks it is REFUSED by name rather than dropped, because a flag that silently did
+ * nothing is worse than one that says why.
+ */
+const SAFE_VALUE = /^[A-Za-z0-9 @=+.,:/_-]*$/;
+
+/**
+ * The flags one submitted form asks for, as an array of shell words, or an error naming the field.
+ * Every flag has to be one the CLI printed, and every value has to fit the shape that flag documented.
+ */
+function flagsFromForm(options, form) {
+  const words = [];
+  const problems = [];
+  for (const opt of options) {
+    const raw = form[fieldName(opt.name)];
+    if (raw === undefined) continue;
+    const value = String(Array.isArray(raw) ? raw[raw.length - 1] : raw).trim();
+    if (!value) continue;
+    if (opt.takes === 'none') {
+      // A checkbox posts its value only when it is ticked.
+      words.push(opt.name);
+      continue;
+    }
+    if (opt.choices.length && !opt.choices.includes(value)) {
+      problems.push(`${opt.name} does not take “${value}”`);
+      continue;
+    }
+    if (!SAFE_VALUE.test(value)) {
+      problems.push(`${opt.name} may hold only letters, digits and @ = + . , : / _ -`);
+      continue;
+    }
+    words.push(opt.name, ...(opt.repeatable ? value.split(/\s+/) : [value]));
+  }
+  return { words, problems };
+}
+
+module.exports = {
+  installedAgents,
+  parseOptions, shape, usableOnAScreen, WITHHELD, PRINT_ONLY, COMMON,
+  claudeOptions, forget, fieldName, optionFor, flagsFromForm, SAFE_VALUE,
+};

package/claude-sessions.js

@@ -0,0 +1,129 @@
+/**
+ * The Claude Code sessions a directory already has, so one can be RESUMED rather than started over.
+ *
+ * A screen session that dies — the machine reboots, the terminal closes, `screen -wipe` takes a dead
+ * one — does not take the conversation with it: the Claude Code CLI keeps every session's transcript
+ * under `~/.claude/projects/<the directory, slashes turned into dashes>/<session id>.jsonl`. Resuming
+ * by id is `claude --resume <id>` from that same directory.
+ *
+ * By ID, deliberately, and not `--continue`: continue takes the most recent session for the directory,
+ * which after a day of parallel work is often not the one meant. The id is exact.
+ *
+ * What is on disk is two different things, and only one of them can be resumed:
+ *   <id>.jsonl   the transcript. This is what --resume reads, so this is what makes a session resumable.
+ *   <id>/        that session's tool results and subagents. It exists on its own for a session whose
+ *                transcript has not been written — and `claude --resume` on such an id answers
+ *                "No conversation found with session ID", which is exactly what happened when this
+ *                listed them: the screen started and died in the same second.
+ * So `resumable` is the transcript, and a directory-only id is reported rather than offered.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const PROJECTS = path.join(os.homedir(), '.claude', 'projects');
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Is this a session id we would hand to `claude --resume`? */
+const isSessionId = (v) => UUID_RE.test(String(v || ''));
+
+/**
+ * The CLI's own name for a directory: the absolute path with every slash turned into a dash. So
+ * /home/rajab/workspace/dev/ha1x00b1 is -home-rajab-workspace-dev-ha1x00b1.
+ */
+function projectSlug(dir) {
+  return String(path.resolve(dir)).replace(/\//g, '-');
+}
+
+function projectDirFor(dir) {
+  return path.join(PROJECTS, projectSlug(dir));
+}
+
+/**
+ * The first thing the person typed, as the session's title. Read from the head of the file rather than
+ * all of it: a long transcript is tens of megabytes and this runs while a form is being drawn.
+ */
+function titleOf(file) {
+  let head = '';
+  try {
+    const fd = fs.openSync(file, 'r');
+    const buf = Buffer.alloc(256 * 1024);
+    const n = fs.readSync(fd, buf, 0, buf.length, 0);
+    fs.closeSync(fd);
+    head = buf.slice(0, n).toString('utf8');
+  } catch (_) {
+    return '';
+  }
+  for (const line of head.split('\n')) {
+    if (!line.startsWith('{') || !line.includes('"type":"user"')) continue;
+    try {
+      const d = JSON.parse(line);
+      const content = (d.message || {}).content;
+      const text = typeof content === 'string'
+        ? content
+        : Array.isArray(content)
+          ? content.filter((p) => p && p.type === 'text').map((p) => p.text).join(' ')
+          : '';
+      const clean = String(text).replace(/<[^>]+>/g, ' ').replace(/\s+/g, ' ').trim();
+      if (clean) return clean.slice(0, 90);
+    } catch (_) { /* a half-written line at the head is not a title */ }
+  }
+  return '';
+}
+
+/**
+ * Every resumable session for one directory, newest first.
+ *
+ * `at` is when it was last written — which is what "the one I was just in" means — and `title` is the
+ * first thing typed in it, so two sessions in one project can be told apart without opening either.
+ */
+function sessionsFor(dir, { limit = 25, resumableOnly = false } = {}) {
+  const projectDir = projectDirFor(dir);
+  let names = [];
+  try { names = fs.readdirSync(projectDir); } catch (_) { return []; }
+
+  const found = new Map();
+  const note = (id, file, isTranscript) => {
+    let st;
+    try { st = fs.statSync(file); } catch (_) { return; }
+    const prev = found.get(id);
+    const entry = prev || { id, at: 0, size: 0, title: '', transcript: false, resumable: false };
+    entry.at = Math.max(entry.at, st.mtimeMs);
+    if (isTranscript) {
+      entry.size = st.size;
+      entry.transcript = true;
+      // An empty transcript is a session that never got going; --resume finds nothing in it either.
+      entry.resumable = st.size > 0;
+      entry.title = entry.title || titleOf(file);
+    }
+    found.set(id, entry);
+  };
+
+  for (const name of names) {
+    if (name === 'memory') continue;
+    if (name.endsWith('.jsonl')) {
+      const id = name.slice(0, -'.jsonl'.length);
+      if (isSessionId(id)) note(id, path.join(projectDir, name), true);
+    } else if (isSessionId(name)) {
+      // A session whose transcript has not been written yet — still running, or cut off by a reboot.
+      note(name, path.join(projectDir, name), false);
+    }
+  }
+
+  return [...found.values()]
+    .filter((x) => !resumableOnly || x.resumable)
+    .sort((a, b) => b.at - a.at)
+    .slice(0, limit);
+}
+
+/** Does this directory have any session to resume? Cheap enough to ask while drawing a list. */
+function hasSessions(dir) {
+  try {
+    return fs.readdirSync(projectDirFor(dir)).some((n) => isSessionId(n) || (n.endsWith('.jsonl') && isSessionId(n.slice(0, -6))));
+  } catch (_) {
+    return false;
+  }
+}
+
+module.exports = { PROJECTS, isSessionId, projectSlug, projectDirFor, sessionsFor, hasSessions, titleOf };

package/command-author.js

@@ -0,0 +1,117 @@
+/**
+ * What the assistant is told when it writes or changes a `cmd-*.sh`.
+ *
+ * A workspace command is not a free-form script. It has a fixed shape — locate the tooling from its
+ * own path, source the bootstrap, parse the workspace's settings file, declare its arguments through
+ * the argparse heredoc, then call one function — and a set of rules that are not negotiable, because
+ * breaking them breaks the machine rather than the script: DDEV only, no `$databases` block, no
+ * masked failures. An agent that has not been told these writes plausible bash that this workspace
+ * cannot use.
+ *
+ * So the prompt carries the conventions, and it points at the real files rather than describing
+ * them: the surest way to write a command like the others is to read the others. The agent is given
+ * read tools ONLY — it never writes the file itself. Its answer is captured, checked with `bash -n`,
+ * and only then does it become a command.
+ *
+ * One module, two callers: creating a command with a purpose, and asking for a change to one that
+ * exists. They share every rule; only the last paragraph differs.
+ */
+
+const path = require('path');
+
+const { ROOT } = require('./workspaces');
+
+// The conventions, in the order they appear in a real command. Written as instructions rather than
+// as prose about instructions, because this text is read by an agent and not by a person.
+function conventions(workspace) {
+  return `THE SHAPE OF A WORKSPACE COMMAND — follow it exactly:
+
+1. \`#!/usr/bin/env bash\` and, for a builder, a \`# workspace-name: <Human Name>\` header on line 3.
+   The smoke test at core/scripts/tests/cmd-smoke-test.sh enforces the header on cmd-*-project.sh.
+2. The bootstrap, verbatim, so a fresh clone needs no setup and no environment variable:
+     WORKSPACE_SCRIPTS="\${WORKSPACE_SCRIPTS:-$(cd "$(dirname "\${BASH_SOURCE[0]}")/../core/scripts" && pwd)}";
+     source \${WORKSPACE_SCRIPTS}/bootstrap.sh || exit 1 ;
+3. \`eval $(parse_yaml \${WORKSPACE_CONFIG}/workspace.${workspace}.settings.yml);\` — this is where
+   \`doc_name\` comes from, and every function below uses it.
+4. \`ARGPARSE_DESCRIPTION="…"\` then \`source \${WORKSPACE_SCRIPTS}/args/arg-<name>.sh || exit 1 ;\`
+5. \`shift $#;\` then ONE call to the function that does the work.
+
+The logic goes in \`core/scripts/functions/fun-<name>.sh\`, sourced from
+core/scripts/bootstrap-functions.sh. A cmd-*.sh that contains its own logic is the wrong shape: the
+command is the entry point, the function is the program.
+
+ARGUMENTS are declared in an argparse heredoc in core/scripts/args/arg-<name>.sh. Optional string
+flags default to the string \`_none_\` and are tested \`[ ! "\${FLAG}" == '_none_' ]\`. Booleans use
+\`action='store_true'\` and arrive as \`yes\` or empty. Do NOT use \`nargs='+'\`: this argparse hands
+arrays back as a scalar and the extra values are lost silently.
+
+HARD RULES — these are not style:
+  * DDEV only. \`ddev composer\`, \`ddev drush\`, \`ddev exec\`, \`ddev export-db\`. Never raw composer,
+    drush, npm or mysql on the host.
+  * Never write a \`$databases\` block into settings.php — DDEV's settings.ddev.php owns it.
+  * \`ddev start\` accepts \`-y\`; \`ddev stop\` does NOT.
+  * Never mask a failure with \`|| true\` on a command whose result matters, and never \`rm -rf\` a
+    path built from an unvalidated argument.
+  * Anything the dashboard runs has no one to answer a prompt, so never wait for input.
+  * A command that CREATES something for its own checking removes it again, or reports it and stops —
+    never leaves a scratch project behind. Remove one with cmd-tools-remove.sh <project>, or
+    ddev delete -y -O inside it; never rm -rf. The folder is not the project: deleting it alone
+    strands the DDEV registry entry, the database volume, the snapshots volume and the built images.
+
+READ THESE FIRST with your tools — they are the pattern, and copying it is the point:
+  ${path.join(ROOT, workspace)}/cmd-*.sh                    (the commands this workspace already has)
+  ${path.join(ROOT, 'core', 'scripts', 'functions')}/       (every fun-*.sh — the functions that already exist)
+  ${path.join(ROOT, 'core', 'scripts', 'args')}/            (every arg-*.sh — the argparse blocks that already exist)
+  ${path.join(ROOT, 'core', 'scripts', 'bootstrap.sh')}               (what is exported for you)
+
+REUSE BEFORE INVENTING. List both directories and read what is close to the task: the best command
+is usually ONE call to a function somebody already wrote, behind an arg file that already fits
+(arg-distribution, arg-webship-site-template, arg-checks, arg-testing …). Write new logic inline
+only when no existing function covers it — and then still declare the arguments through an existing
+arg file when one matches, so the same flags mean the same things across the workspace.`;
+}
+
+/** Writing a new command's body into the scaffold that already exists. */
+function commandAuthorPrompt({ workspace, file, purpose, scaffoldPath }) {
+  return `You are writing a command for the Webship Workspace, a DDEV-only harness rooted at ${ROOT}.
+
+The file ${scaffoldPath} has just been scaffolded and already carries the correct bootstrap chain.
+Read it first. Rewrite it so it does what is asked below, keeping every line of the bootstrap exactly
+as it is.
+
+WHAT IT SHOULD DO:
+${purpose}
+
+${conventions(workspace)}
+
+Also state, in a comment block at the top of the file, what this command is for and what it will NOT
+do — the destructive edges it deliberately leaves alone. That comment is the first thing the next
+person reads.
+
+If the work needs a new function file or a new arg file, say so in a comment at the point it would be
+called, naming the exact path — you cannot create it, and a command that calls a function nobody
+wrote fails loudly on the first run, which is better than a command that silently does half of it.
+
+Output ONLY the complete contents of ${file}. No commentary, no code fences, no explanation.`;
+}
+
+/** Changing a command that already exists, to an instruction. */
+function commandEditPrompt({ workspace, file, instruction, fullPath }) {
+  return `You are changing a command in the Webship Workspace, a DDEV-only harness rooted at ${ROOT}.
+
+The command is ${fullPath}. Read it first, and read the commands beside it.
+
+WHAT TO CHANGE:
+${instruction}
+
+Change only what that asks for. Everything else — the bootstrap chain, the argparse source line, the
+comments explaining decisions somebody already made — stays exactly as it is. If the instruction
+cannot be carried out without breaking one of the rules below, do not carry it out: leave the file as
+it is and put a single comment at the top saying which rule stopped you.
+
+${conventions(workspace)}
+
+Output ONLY the complete new contents of ${file}. No commentary, no code fences, no explanation.`;
+}
+
+module.exports = { commandAuthorPrompt, commandEditPrompt, conventions };

package/command-block.js

@@ -0,0 +1,20 @@
+/**
+ * A command the dashboard shows rather than runs, with a copy button on each line.
+ *
+ * `claude mcp add` writes ~/.claude.json — the CLI configuration of the person at the keyboard, not
+ * of this web request. The Upsun pulls need cloud credentials this container does not have, and
+ * they replace local data. Both are worth reading before they happen.
+ */
+
+const { esc } = require('./html');
+
+const commandBlock = (title, lines, note) => `<div class="msg assistant">
+    <strong>${esc(title)}</strong>
+    ${lines.map((l) => `<div class="uk-margin-small-top uk-flex uk-flex-middle" style="gap:.5rem">
+      <code style="flex:1;overflow-x:auto;white-space:pre">${esc(l)}</code>
+      <button class="uk-button uk-button-default uk-button-small copy-cmd" data-copy="${esc(l)}"><span uk-icon="icon: copy; ratio: .7"></span> Copy</button>
+    </div>`).join('')}
+    <p class="uk-text-meta uk-margin-small-top">${note}</p>
+  </div>`;
+
+module.exports = { commandBlock };