@empirical-gauzza/cli 1.0.37 → 1.0.39

package/lib/setupCommands.js

@@ -55,9 +55,20 @@ function recoveryHints(error, sessionId, step = '') {
   switch (error && error.code) {
     case 'GUIDED_SETUP_VOICE_NOT_WAITING':
     case 'GUIDED_SETUP_VOICE_STALE':
+    case 'GUIDED_SETUP_WORKSPACE_NOT_WAITING':
       return [`See the current question and its key with: ${resume}`];
     case 'GUIDED_SETUP_VOICE_BUSY':
+    case 'GUIDED_SETUP_WORKSPACE_BUSY':
       return [`Wait a moment, then pick it up with: ${resume}`];
+    // The workspace interview's own refusals. The server's message already carries the price of a new
+    // interview (it is the effective one), so these lines name no number. An abandoned interview is
+    // not refunded, which is said before the person is pointed at starting again.
+    case 'GUIDED_SETUP_WORKSPACE_SESSION_LIMIT':
+      return [`If a draft was already shown, you can read it with ${resume} and confirm it; the limit can be reached before there is one. Starting a new interview is charged again, and stopping this one with empirical setup abandon ${sid} does not return what it cost.`];
+    case 'GUIDED_SETUP_WORKSPACE_GENERATION_FAILED':
+      return [`Your answers are saved. Run ${resume} to see where the setup is, then answer again.`];
+    case 'GUIDED_SETUP_WORKSPACE_UNAVAILABLE':
+      return ['Nothing was started or charged. Run the command again in a few minutes.'];
     case 'EMPIRICAL_TOKENS_ATTEMPT_CLOSED':
       return ['This attempt is already closed, so it cannot be continued. Start a new one with: empirical setup run <setupId>'];
     case 'EMPIRICAL_TOKEN_KEY_OWNER_MISMATCH':
@@ -120,7 +131,23 @@ function refundLine(error) {
   return null;
 }
 
+// The server words its errors for every client, and one clause tells an AGENT to call a tool. At a terminal the
+// same step is a command, so that clause (and only that clause) becomes the real command.
+function cliConfirmWording(text, sessionId) {
+  return String(text === undefined || text === null ? '' : text).replace(
+    /\b([Cc])all confirm_guided_setup with this session's sessionId and the draftHash shown with the draft/g,
+    (_m, c) => `${c === 'C' ? 'Run' : 'run'} empirical setup confirm ${sessionId || '<sessionId>'} <draftHash>`
+  );
+}
+function forTerminal(error, sessionId) {
+  if (!error) return error;
+  if (typeof error.message === 'string') error.message = cliConfirmWording(error.message, sessionId);
+  if (typeof error.serverMessage === 'string') error.serverMessage = cliConfirmWording(error.serverMessage, sessionId);
+  return error;
+}
+
 function failWith(error, pathSuffix, body) {
+  forTerminal(error, sessionIdFromPath(pathSuffix));
   printApiError(error);
   for (const line of recoveryHints(error, sessionIdFromPath(pathSuffix), stepOf(pathSuffix, body))) warn(line);
   const refund = refundLine(error);
@@ -219,7 +246,9 @@ function formatQuestionLines(question, progress = {}) {
     // records whatever is typed, so the end-early hint belongs to the follow-up loop alone.
     if (p.meterLine && question.kind === 'text' && /^g\d+$/.test(key) && !question.focus) lines.push(loopHint(question, p));
   }
-  if (question.kind === 'pick_and_edit') lines.push('Reply with the numbers that fit, like 2,5, and optionally a | and your own changes.');
+  // The workspace interview words its own examples (built from the options on offer, and in the 'add Name'
+  // form its parser reads); this Writing Voice line would show "2,5" for a list that may have two options.
+  if (question.kind === 'pick_and_edit' && !isWorkspaceQuestion(question)) lines.push('Reply with the numbers that fit, like 2,5, and optionally a | and your own changes.');
   if (question.kind === 'pick_one') lines.push('Reply with one number.');
   if (question.kind === 'yes_no') lines.push('Reply yes or no.');
   if (staleTopic) {
@@ -238,7 +267,46 @@ function workspacePlace(name) {
   return /\bworkspace$/i.test(n) ? n : `${n} workspace`;
 }
 
+// A workspace draft is a list of plain sentences (no hub or rules), the people to be invited, and
+// anything that stops it being confirmed. The Writing Voice branch below would print "Hub: undefined".
+function isWorkspaceDraft(question) {
+  return Boolean(question && question.draft && Array.isArray(question.draft.lines));
+}
+
+function formatWorkspaceDraftLines(question) {
+  const t = sanitizeForTerminal;
+  const confirm = question.confirm || {};
+  const lines = [];
+  for (const l of [...question.draft.lines, ...(Array.isArray(question.draft.statusSummary) ? question.draft.statusSummary : [])]) lines.push(`- ${t(l)}`);
+  if (Array.isArray(confirm.invites)) {
+    lines.push(confirm.invites.length
+      ? `Invites: ${confirm.invites.map((i) => `${t(i.email)} (${t(i.role)})`).join(', ')}`
+      : 'Invites: nobody yet.');
+  }
+  if (confirm.inviteNote) lines.push(t(confirm.inviteNote));
+  if (confirm.canConfirm === false) {
+    lines.push('This draft cannot be confirmed as it is:');
+    for (const b of Array.isArray(confirm.blockers) ? confirm.blockers : []) lines.push(`- ${t(b)}`);
+    lines.push('Type a change to fix it. Nothing has been created or changed.');
+  } else if (question.prompt) {
+    // The server's own review wording: what the person can do next (next, confirm, a change, a rename).
+    lines.push(workspaceReviewPrompt(question.prompt));
+  }
+  return lines;
+}
+
+// The server words the review for every client, and its one tool-call clause (how an AGENT confirms) means
+// nothing at a terminal, where the person types the word that is asked for below. Everything else is the
+// server's own text, unchanged, so every example in it works as typed.
+function workspaceReviewPrompt(prompt) {
+  return sanitizeForTerminal(prompt)
+    .replace(/\s*\(call confirm_guided_setup[^)]*\)/, '')
+    .replace(/To (?:create the workspace|save these changes), call confirm_guided_setup[^.]*\.\s*/, '')
+    .trim();
+}
+
 function formatDraftLines(question, progress = {}) {
+  if (isWorkspaceDraft(question)) return formatWorkspaceDraftLines(question);
   const t = sanitizeForTerminal;
   const draft = question.draft || {};
   const confirm = question.confirm || {};
@@ -302,6 +370,10 @@ function printCurrentQuestion(result) {
   }
   printDraft(question, result.progress);
   const confirm = question.confirm || {};
+  if (isWorkspaceDraft(question) && confirm.canConfirm === false) {
+    warn(`Ask for a change with: empirical setup answer ${sid} ${key} <the change you want>`);
+    return;
+  }
   if (confirm.stale) {
     warn(`Rebuild it with: empirical setup answer ${sid} ${key} rebuild`);
   } else if (confirm.draftHash) {
@@ -378,6 +450,14 @@ async function offerVoicePluginInstall({ prompter, env = process.env, install =
 // offer: { prompter } when a person at a terminal ran the interview; absent for scripted runs.
 async function reportConfirmed(result, offer) {
   if (result && result.message) log(sanitizeForTerminal(result.message));
+  // A confirmed workspace interview has no install job: it names the workspace and what to do next.
+  if (result && result.workspaceId && !(result && result.installId)) {
+    const id = sanitizeForTerminal(result.workspaceId);
+    log(`Workspace id: ${id}`);
+    log(`Switch to it with: ${WORKSPACE_USE_LINE(id)}`);
+    log(`Change its shape later with: ${WORKSPACE_SHAPE_LINE(id)}`);
+    return;
+  }
   const installId = result && result.installId;
   if (!installId) return;
   const status = await fetchInstallStatus(installId);
@@ -419,11 +499,26 @@ async function reportConfirmed(result, offer) {
 // Spec 7.3: a priced setup returns a cost preview first. Acceptance is sent only from the explicit
 // --accept-cost flag; a first call without it stops at the cost and starts nothing. A person at a
 // terminal is asked instead, and a non-interactive run stops.
-async function startWithCost(setupId, { acceptCost, prompter }) {
-  const first = await callApi('POST', '/start', acceptCost ? { setupId, acceptEmpiricalTokenCost: true } : { setupId });
+//
+// start carries any extra start fields. For the workspace interview that is targetWorkspaceId, the one
+// explicit way to ask for a re-shape (no field means a new workspace). Its start is also where a setup
+// that is switched off for the person answers 404, which is explained instead of left as a bare error.
+async function startWithCost(setupId, { acceptCost, prompter, start = {} }) {
+  const first = await startCall({ setupId, ...start, ...(acceptCost ? { acceptEmpiricalTokenCost: true } : {}) });
   if (!isCostPreview(first)) return reportTokensUsed(first);
   await confirmCostOrExit(first, { prompter, warn, sanitize: sanitizeForTerminal });
-  return reportTokensUsed(await callApi('POST', '/start', { setupId, acceptEmpiricalTokenCost: true }));
+  return reportTokensUsed(await startCall({ setupId, ...start, acceptEmpiricalTokenCost: true }));
+}
+
+async function startCall(body) {
+  const { data, error } = await tryApi('POST', '/start', body);
+  if (!error) return data;
+  if (body.setupId === WORKSPACE_SETUP_ID && error.statusCode === 404) {
+    printApiError(error);
+    warn('The workspace interview is not switched on for your account, so nothing was started or charged.');
+    process.exit(1);
+  }
+  return failWith(error, '/start', body);
 }
 
 // After a paid start, say what it cost, but only when the response carries the amount. stderr, so
@@ -434,20 +529,35 @@ function reportTokensUsed(result) {
   return result;
 }
 
-async function runNonInteractive(setupId, answersFilePath, acceptCost) {
+async function runNonInteractive(setupId, answersFilePath, acceptCost, start) {
   const raw = fs.readFileSync(path.resolve(answersFilePath), 'utf8');
   const answersByQuestionKey = JSON.parse(raw);
 
-  let current = await startWithCost(setupId, { acceptCost, prompter: null });
+  let current = await startWithCost(setupId, { acceptCost, prompter: null, start });
+  hintAbandon(current);
   let confirmed = false;
+  const reviewTurns = {};
 
   while (current.question && current.status !== 'completed' && current.status !== 'finished_early') {
     const question = current.question;
     const questionKey = question.questionKey;
+    if (question.kind === 'confirm' && isFirstWorkspaceReview(question) && Object.prototype.hasOwnProperty.call(answersByQuestionKey, questionKey) && answersByQuestionKey[questionKey] !== 'confirm') {
+      // The first review of a workspace: the file's value is the answer, so a script can reach the invites.
+      // A list is taken in order (a rename, then next); a single string is sent once.
+      const wanted = answersByQuestionKey[questionKey];
+      const queue = Array.isArray(wanted) ? wanted : [wanted];
+      const turn = (reviewTurns[questionKey] = (reviewTurns[questionKey] || 0) + 1) - 1;
+      if (turn < queue.length) {
+        current = await callApi('POST', `/${current.sessionId}/continue`, answerBody(question, queue[turn]));
+        continue;
+      }
+    }
     if (question.kind === 'confirm') {
       // Confirming is its own step: only an explicit "confirm" for q5_confirm installs, never a stale draft.
       const stale = Boolean(question.confirm && question.confirm.stale);
-      if (answersByQuestionKey[questionKey] === 'confirm' && !stale) {
+      // A workspace draft with blockers has no hash to confirm; the file's "confirm" is not sent for it.
+      const confirmable = !(question.confirm && question.confirm.canConfirm === false);
+      if (answersByQuestionKey[questionKey] === 'confirm' && !stale && confirmable) {
         current = await callApi('POST', `/${current.sessionId}/confirm`, { draftHash: question.confirm.draftHash });
         confirmed = true;
       } else if (stale) {
@@ -517,34 +627,44 @@ async function sendInteractiveAnswer(current, answer) {
   if (!error) return data;
   if (error.statusCode !== 400 && error.statusCode !== 409) failWith(error, pathSuffix, body);
   if (error.code === 'GUIDED_SETUP_CONFIRM_REQUIRED') warn('To install this draft, type yes.');
-  else warn(sanitizeForTerminal(error.serverMessage || error.message));
+  else warn(sanitizeForTerminal(cliConfirmWording(error.serverMessage || error.message, current.sessionId)));
   return callApi('POST', pathSuffix, {});
 }
 
-async function runInteractive(setupId, acceptCost) {
+async function runInteractive(setupId, acceptCost, start) {
   const prompter = createPrompter(process.stderr);
   let abortMessage = null;
   let finalResult = null;
   let confirmed = false;
   try {
-    let current = await startWithCost(setupId, { acceptCost, prompter });
+    let current = await startWithCost(setupId, { acceptCost, prompter, start });
     if (!current) return;
+    hintAbandon(current);
     let emptyReplies = 0;
     while (current.question && current.status !== 'completed' && current.status !== 'finished_early') {
       const question = current.question;
       if (question.kind === 'confirm') {
         printDraft(question, current.progress);
-        const reply = (await prompter.askText('Install this? (type yes to install, or type a change you want)')).trim();
+        const reply = (await prompter.askText(confirmPromptFor(question))).trim();
         if (!reply) {
           const sessionId = current.sessionId;
           abortMessage = () => printNothingInstalled(sessionId, question.confirm && question.confirm.draftHash);
           break;
         }
-        if (/^(y|yes)$/i.test(reply)) {
+        const firstReview = isFirstWorkspaceReview(question);
+        if (firstReview && /^(y|yes)$/i.test(reply)) {
+          warn('Yes is not one of the choices here. Type next to choose who to invite, or confirm to finish without inviting anyone.');
+          continue;
+        }
+        if (firstReview ? /^confirm$/i.test(reply) : /^(y|yes|confirm)$/i.test(reply)) {
           if (question.confirm && question.confirm.stale) {
             warn('This draft is out of date. Type rebuild to write a new one first.');
             continue;
           }
+          if (isWorkspaceDraft(question) && (question.confirm.canConfirm === false || !question.confirm.draftHash)) {
+            warn('This draft cannot be confirmed as it is. Type a change to fix what is listed above.');
+            continue;
+          }
           current = await callApi('POST', `/${current.sessionId}/confirm`, { draftHash: question.confirm.draftHash });
           confirmed = true;
           break;
@@ -589,6 +709,50 @@ async function runInteractive(setupId, acceptCost) {
   printJson(finalResult);
 }
 
+const WORKSPACE_SETUP_ID = 'setup_workspace';
+// The commands printed after a workspace is made, built from the real id so they work as typed.
+const WORKSPACE_USE_LINE = (id) => `empirical workspace use ${id}`;
+const WORKSPACE_SHAPE_LINE = (id) => `empirical workspace shape --workspace-id ${id}`;
+
+// The question at the review step. The workspace interview creates or changes a workspace, not an install.
+// The first review (questionKey draft) is BEFORE the invitations, so a bare yes is not a choice there: the
+// person picks next (to choose who to invite) or confirm (finish with nobody invited). The final review
+// (after the invitations) is the one a yes confirms.
+function isFirstWorkspaceReview(question) {
+  return isWorkspaceDraft(question) && question.questionKey === 'draft';
+}
+function confirmPromptFor(question) {
+  if (!isWorkspaceDraft(question)) return 'Install this? (type yes to install, or type a change you want)';
+  const reshape = question.confirm && question.confirm.mode === 'reshape';
+  if (question.confirm && question.confirm.canConfirm === false) return 'What next? (type a change you want)';
+  if (isFirstWorkspaceReview(question)) return `What next? (type next to choose who to invite, confirm to ${reshape ? 'save these changes' : 'create the workspace'} without inviting anyone, or type a change you want)`;
+  return `${reshape ? 'Apply this to the workspace?' : 'Create this workspace?'} (type yes to confirm, or type a change you want)`;
+}
+
+// Printed once after a workspace interview starts. An abandoned interview is NOT refunded, and the
+// line says so, so nobody stops one expecting their Empirical Tokens back.
+function hintAbandon(result) {
+  if (!result || !result.sessionId || !result.question) return;
+  if (!isWorkspaceQuestion(result.question)) return;
+  const sid = sanitizeForTerminal(result.sessionId);
+  warn(`If you want to stop this interview, run: empirical setup abandon ${sid} (what it cost is not returned).`);
+}
+
+// Workspace questions are the only ones with these keys; the Writing Voice engine has none of them.
+function isWorkspaceQuestion(question) {
+  const key = String((question && question.questionKey) || '');
+  return key === 'purpose' || key === 'types' || key === 'nesting' || key === 'policy' || key === 'invites'
+    || key === 'draft' || /^(statuses|fields):/.test(key);
+}
+
+// The workspace interview from the workspace commands. targetWorkspaceId present means re-shape that
+// workspace, absent means create a new one; nothing else decides it.
+async function runWorkspaceInterview({ targetWorkspaceId, answersFile = '', acceptCost = false } = {}) {
+  const start = targetWorkspaceId ? { targetWorkspaceId } : {};
+  if (answersFile) return runNonInteractive(WORKSPACE_SETUP_ID, answersFile, acceptCost, start);
+  return runInteractive(WORKSPACE_SETUP_ID, acceptCost, start);
+}
+
 async function runRun(args) {
   const setupId = args[0] && !args[0].startsWith('--') ? args[0] : '';
   if (!setupId) {
@@ -627,6 +791,18 @@ async function runFinish(args) {
   printJson(result);
 }
 
+async function runAbandon(args) {
+  const [sessionId] = args;
+  if (!sessionId) {
+    warn('Usage: empirical setup abandon <sessionId>');
+    process.exit(1);
+  }
+  const result = await callApi('POST', `/${encodeURIComponent(sessionId)}/abandon`, {});
+  log(result && result.status === 'abandoned'
+    ? 'The interview was stopped. Nothing was created or changed, and what it cost was not returned.'
+    : 'That interview was already finished or stopped. Nothing was changed, and no Empirical Tokens were returned.');
+}
+
 async function runResume(args) {
   const [sessionId] = args;
   if (!sessionId) {
@@ -656,11 +832,12 @@ async function runSetupCommand(args) {
   if (sub === 'finish') return runFinish(rest);
   if (sub === 'resume') return runResume(rest);
   if (sub === 'confirm') return runConfirm(rest);
-  warn('Usage: empirical setup <list|run|answer|finish|resume|confirm> ...');
+  if (sub === 'abandon') return runAbandon(rest);
+  warn('Usage: empirical setup <list|run|answer|finish|resume|confirm|abandon> ...');
   process.exit(1);
 }
 
 module.exports = {
-  refundLine, runSetupCommand, formatQuestionLines, formatDraftLines, sanitizeForTerminal,
+  refundLine, cliConfirmWording, runSetupCommand, runWorkspaceInterview, WORKSPACE_SETUP_ID, recoveryHints, formatQuestionLines, formatDraftLines, sanitizeForTerminal,
   offerVoicePluginInstall, VOICE_PLUGIN_COMMANDS, VOICE_STANDING_INSTRUCTION
 };

package/lib/shapeCommands.js

@@ -0,0 +1,313 @@
+'use strict';
+
+// Editing a workspace's shape by hand, without the interview.
+//
+//   empirical workspace shape show      --workspace-id <id>
+//   empirical workspace shape set       --workspace-id <id> --file <shape.json> [--apply]
+//   empirical workspace shape edit      --workspace-id <id> --file <edit.json>  [--apply]
+//   empirical workspace shape add-type  --workspace-id <id> <label> [--statuses "A,B,C (done)"] ...
+//   empirical workspace shape add-status --workspace-id <id> <type-key> <label> [--done]
+//   empirical workspace shape add-field  --workspace-id <id> <type-key> <label> --kind <kind> ...
+//
+// The interview is charged (100 Empirical Tokens, plus 25 per change to a draft) and takes nine
+// questions, so adding a single status cost more than the status was worth. The server has had the
+// door for this since POST/PATCH /api/v1/team-brains/:id/shape and /shape/preview; this file is the
+// CLI side of it.
+//
+// Every change is a DRY RUN until --apply. A change goes to /shape/preview first, which validates it
+// against the active shape and returns a confirmDigest; --apply sends that digest back, so an edit
+// is only ever applied to the shape that was shown. The commands here only ADD (a type, a status, a
+// field); removing needs a mapping for the stored values, which `edit --mapping-file` accepts.
+
+const fs = require('fs');
+const { log, warn } = require('./ui');
+const { httpJson } = require('./http');
+const { parseOption, parseFlag } = require('./env');
+
+const SHAPE_ACTIONS = ['show', 'set', 'edit', 'add-type', 'add-status', 'add-field'];
+const FIELD_KINDS = ['text', 'longText', 'number', 'date', 'select', 'multiSelect', 'person', 'link', 'url'];
+const VALUE_OPTIONS = new Set([
+  '--workspace-id', '--file', '--mapping-file', '--purpose', '--plural', '--category', '--node-type',
+  '--icon', '--color', '--statuses', '--fields', '--nest-under', '--kind', '--options'
+]);
+
+const SHAPE_USAGE = [
+  'Usage: empirical workspace shape <show|set|edit|add-type|add-status|add-field> --workspace-id <id> ...',
+  '  show                                          print the workspace\'s item types, statuses and fields',
+  '  set --file <shape.json> [--apply]             give a workspace with no shape its first shape',
+  '  edit --file <edit.json> [--mapping-file <m.json>] [--apply]',
+  '                                                add, update or remove entries (see `empirical doc workspace`)',
+  '  add-type <label> [--statuses "A,B,C (done)"] [--fields "Email:text:required;Wave:number"]',
+  '           [--plural <label>] [--category <cat>] [--node-type <type>] [--icon <i>] [--color <c>]',
+  '           [--nest-under <type-key,...>] [--purpose <text>]   (--purpose only when the workspace has no shape yet)',
+  '  add-status <type-key> <label> [--done]',
+  '  add-field <type-key> <label> [--kind text|longText|number|date|select|multiSelect|person|link|url]',
+  '            [--required] [--options "Yes|No|Not asked"]',
+  'Changes are a dry run until you add --apply. Running the interview instead: `empirical workspace shape` with no action.'
+].join('\n');
+
+function isManualShapeAction(args) {
+  return SHAPE_ACTIONS.includes(args[2]);
+}
+
+// Words after the action that are not options or option values, in order.
+function positionals(args, startIndex = 3) {
+  const out = [];
+  for (let i = startIndex; i < args.length; i += 1) {
+    if (VALUE_OPTIONS.has(args[i])) i += 1;
+    else if (!String(args[i]).startsWith('--')) out.push(args[i]);
+  }
+  return out;
+}
+
+// "Not Yet Invited, Invited, Call Completed (done)" -> statuses in order; "(done)" marks the finished one.
+function parseStatusList(text) {
+  return String(text || '')
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => {
+      const done = /\(\s*done\s*\)\s*$/i.test(part);
+      const label = part.replace(/\(\s*done\s*\)\s*$/i, '').trim();
+      return done ? { label, isDone: true } : { label };
+    });
+}
+
+// "Email:text:required; Open to a call:select:Yes|No|Not asked; Wave:number"
+// label[:kind][:required][:option|option...] separated by semicolons (options may contain commas).
+function parseFieldList(text) {
+  return String(text || '')
+    .split(';')
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => {
+      const [label, kindRaw, ...rest] = part.split(':').map((s) => s.trim());
+      const kind = kindRaw || 'text';
+      if (!FIELD_KINDS.includes(kind)) {
+        throw new Error(`Field "${label}" has kind "${kind}". Use one of: ${FIELD_KINDS.join(', ')}.`);
+      }
+      const field = { label, kind };
+      for (const piece of rest) {
+        if (/^required$/i.test(piece)) field.required = true;
+        else if (piece) field.options = piece.split('|').map((o) => o.trim()).filter(Boolean);
+      }
+      return field;
+    });
+}
+
+function buildTypeFromFlags(args, label) {
+  const type = {
+    label,
+    baseCategory: parseOption(args, '--category', 'project'),
+    baseNodeType: parseOption(args, '--node-type', 'entity')
+  };
+  const plural = parseOption(args, '--plural', '');
+  if (plural) type.labelPlural = plural;
+  for (const [flag, key] of [['--icon', 'icon'], ['--color', 'color']]) {
+    const value = parseOption(args, flag, '');
+    if (value) type[key] = value;
+  }
+  const nest = parseOption(args, '--nest-under', '');
+  if (nest) type.canNestUnder = nest.split(',').map((s) => s.trim()).filter(Boolean);
+  const statuses = parseStatusList(parseOption(args, '--statuses', ''));
+  if (statuses.length) type.statuses = statuses;
+  const fields = parseFieldList(parseOption(args, '--fields', ''));
+  if (fields.length) type.fields = fields;
+  return type;
+}
+
+function buildAddStatusEdit(typeKey, label, isDone) {
+  return { itemTypes: { update: [{ key: typeKey, statuses: { add: [isDone ? { label, isDone: true } : { label }] } }] } };
+}
+
+function buildAddFieldEdit(typeKey, field) {
+  return { itemTypes: { update: [{ key: typeKey, fields: { add: [field] } }] } };
+}
+
+function readJsonFile(path, what) {
+  let raw;
+  try {
+    raw = fs.readFileSync(path, 'utf8');
+  } catch (error) {
+    throw new Error(`Could not read ${what} ${path}: ${error.message}`);
+  }
+  try {
+    return JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`${what} ${path} is not valid JSON: ${error.message}`);
+  }
+}
+
+// One readable block per item type. Statuses in order, (done) on the finished ones.
+function formatShape(shape) {
+  if (!shape) return ['This workspace has no shape yet.'];
+  const lines = [];
+  if (shape.purpose) lines.push(`Purpose: ${shape.purpose}`);
+  if (shape.version !== undefined) lines.push(`Version ${shape.version}${shape.source ? ` (${shape.source})` : ''}`);
+  for (const type of shape.itemTypes || []) {
+    lines.push('');
+    lines.push(`${type.label} [${type.key}] saved as ${type.baseCategory}/${type.baseNodeType}`);
+    const statuses = (type.statuses || []).map((s) => `${s.label} [${s.key}]${s.isDone ? ' (done)' : ''}`);
+    lines.push(`  statuses: ${statuses.length ? statuses.join(' > ') : 'none'}`);
+    for (const f of type.fields || []) {
+      const extra = [f.kind, f.required ? 'required' : null, f.options && f.options.length ? f.options.join('|') : null].filter(Boolean);
+      lines.push(`  field ${f.label} [${f.key}]: ${extra.join(', ')}`);
+    }
+    if (type.canNestUnder && type.canNestUnder.length) lines.push(`  nests under: ${type.canNestUnder.join(', ')}`);
+  }
+  if ((shape.policy || []).length) {
+    lines.push('');
+    lines.push('Rules:');
+    for (const p of shape.policy) lines.push(`  ${p.mode || ''} ${p.key || ''}: ${p.text || ''}`.replace(/\s+/g, ' ').replace(/^ /, '  '));
+  }
+  return lines;
+}
+
+function shapeUrl(baseUrl, workspaceId, suffix = '') {
+  return new URL(`/api/v1/team-brains/${encodeURIComponent(workspaceId)}/shape${suffix}`, baseUrl).toString();
+}
+
+// An edit goes to /shape/preview, is shown, and only with --apply is sent to PATCH /shape with the
+// digest the preview returned. Returns what happened so a script can act on it.
+async function previewAndMaybeApply({ baseUrl, workspaceId, authHeaders, edit, mapping, apply, asJson }) {
+  const preview = (await httpJson(shapeUrl(baseUrl, workspaceId, '/preview'), 'POST', { edit, ...(mapping ? { mapping } : {}) }, authHeaders)).preview;
+  if (asJson && !apply) {
+    log(JSON.stringify({ applied: false, preview }));
+  } else if (!asJson) {
+    for (const line of preview.summary || []) log(line);
+    for (const line of preview.mappingSummary || []) log(line);
+  }
+
+  if ((preview.mappingProblems || []).length) {
+    for (const problem of preview.mappingProblems) warn(`Needs a decision: ${problem}`);
+    throw new Error('This change removes or renames something that has stored values. Say where they go with --mapping-file (see `empirical doc workspace`).');
+  }
+  if (!apply) {
+    if (!asJson) log('Dry run: nothing was changed. Add --apply to save this.');
+    return { applied: false, preview };
+  }
+
+  const saved = await httpJson(shapeUrl(baseUrl, workspaceId), 'PATCH', {
+    edit,
+    confirmDigest: preview.confirmDigest,
+    ...(mapping ? { mapping } : {})
+  }, authHeaders);
+  if (asJson) log(JSON.stringify({ applied: true, shape: saved.shape }));
+  else log(`Saved: the shape of ${workspaceId} is now version ${saved.shape && saved.shape.version}.`);
+  return { applied: true, preview, saved };
+}
+
+// Gives a workspace with no shape its first one. The server refuses if it already has one.
+async function createShape({ baseUrl, workspaceId, authHeaders, shape, apply, asJson }) {
+  if (!apply) {
+    if (asJson) log(JSON.stringify({ applied: false, shape }));
+    else {
+      log(`Purpose: ${shape.purpose}`);
+      for (const t of shape.itemTypes || []) {
+        log(`${t.label} saved as ${t.baseCategory}/${t.baseNodeType}`);
+        log(`  statuses: ${(t.statuses || []).map((st) => st.label + (st.isDone ? ' (done)' : '')).join(' > ') || 'none'}`);
+        for (const f of t.fields || []) log(`  field ${f.label}: ${[f.kind, f.required ? 'required' : null, (f.options || []).join('|') || null].filter(Boolean).join(', ')}`);
+      }
+      log('');
+      log('Dry run: nothing was created. Add --apply to give this workspace that shape.');
+    }
+    return { applied: false };
+  }
+  const created = await httpJson(shapeUrl(baseUrl, workspaceId), 'POST', { shape }, authHeaders);
+  if (asJson) log(JSON.stringify({ applied: true, shape: created.shape }));
+  else log(`Created: ${workspaceId} now has a shape (version ${created.shape && created.shape.version}).`);
+  return { applied: true, created };
+}
+
+function requireWorkspaceId(args, { needsExplicit }) {
+  const id = parseOption(args, '--workspace-id', '').trim();
+  if (!id && needsExplicit) {
+    throw new Error('Saving a shape change needs --workspace-id <id>, so a stale directory binding cannot aim it at the wrong workspace.');
+  }
+  return id;
+}
+
+// The entry point. `resolveBound` returns the bound workspace id (or '') for read-only and dry-run use.
+async function runManualShapeCommand({ args, baseUrl, authHeaders, resolveBound = () => '' }) {
+  const action = args[2];
+  const apply = parseFlag(args, '--apply');
+  const asJson = parseFlag(args, '--json');
+  const workspaceId = requireWorkspaceId(args, { needsExplicit: apply }) || resolveBound();
+  if (!workspaceId) throw new Error(`${SHAPE_USAGE}\n\nNo workspace: pass --workspace-id <id>.`);
+  if (!apply && !parseOption(args, '--workspace-id', '')) warn(`Using the workspace bound to this directory: ${workspaceId}`);
+
+  const current = (await httpJson(shapeUrl(baseUrl, workspaceId), 'GET', null, authHeaders)).shape || null;
+
+  if (action === 'show') {
+    if (asJson) log(JSON.stringify({ shape: current }));
+    else for (const line of formatShape(current)) log(line);
+    return { shape: current };
+  }
+
+  if (action === 'set') {
+    const file = parseOption(args, '--file', '');
+    if (!file) throw new Error('Usage: empirical workspace shape set --workspace-id <id> --file <shape.json> [--apply]');
+    if (current) throw new Error('This workspace already has a shape. Change it with `shape edit`, `add-type`, `add-status` or `add-field`.');
+    const body = readJsonFile(file, 'the shape file');
+    return createShape({ baseUrl, workspaceId, authHeaders, shape: body.shape || body, apply, asJson });
+  }
+
+  const mappingFile = parseOption(args, '--mapping-file', '');
+  const mapping = mappingFile ? readJsonFile(mappingFile, 'the mapping file') : undefined;
+
+  if (action === 'edit') {
+    const file = parseOption(args, '--file', '');
+    if (!file) throw new Error('Usage: empirical workspace shape edit --workspace-id <id> --file <edit.json> [--mapping-file <m.json>] [--apply]');
+    if (!current) throw new Error('This workspace has no shape to edit. Give it one first with `shape set` or `shape add-type --purpose "..."`.');
+    return previewAndMaybeApply({ baseUrl, workspaceId, authHeaders, edit: readJsonFile(file, 'the edit file'), mapping, apply, asJson });
+  }
+
+  if (action === 'add-type') {
+    const [label] = positionals(args);
+    if (!label) throw new Error('Usage: empirical workspace shape add-type <label> [--statuses "A,B,C (done)"] [--fields "Email:text:required"] [--purpose <text>] --workspace-id <id>');
+    const type = buildTypeFromFlags(args, label);
+    if (!current) {
+      const purpose = parseOption(args, '--purpose', '');
+      if (!purpose) throw new Error('This workspace has no shape yet, so add-type also needs --purpose "what this workspace is for".');
+      return createShape({ baseUrl, workspaceId, authHeaders, shape: { purpose, itemTypes: [type], policy: [] }, apply, asJson });
+    }
+    return previewAndMaybeApply({ baseUrl, workspaceId, authHeaders, edit: { itemTypes: { add: [type] } }, mapping, apply, asJson });
+  }
+
+  if (!current) throw new Error('This workspace has no shape yet. Start with `shape add-type <label> --purpose "..."`.');
+
+  if (action === 'add-status') {
+    const [typeKey, label] = positionals(args);
+    if (!typeKey || !label) throw new Error('Usage: empirical workspace shape add-status <type-key> <label> [--done] --workspace-id <id> [--apply]');
+    return previewAndMaybeApply({ baseUrl, workspaceId, authHeaders, edit: buildAddStatusEdit(typeKey, label, parseFlag(args, '--done')), mapping, apply, asJson });
+  }
+
+  if (action === 'add-field') {
+    const [typeKey, label] = positionals(args);
+    if (!typeKey || !label) throw new Error('Usage: empirical workspace shape add-field <type-key> <label> [--kind text] [--required] [--options "A|B"] --workspace-id <id> [--apply]');
+    const kind = parseOption(args, '--kind', 'text');
+    if (!FIELD_KINDS.includes(kind)) throw new Error(`--kind must be one of: ${FIELD_KINDS.join(', ')}.`);
+    const field = { label, kind };
+    if (parseFlag(args, '--required')) field.required = true;
+    const options = parseOption(args, '--options', '');
+    if (options) field.options = options.split('|').map((o) => o.trim()).filter(Boolean);
+    return previewAndMaybeApply({ baseUrl, workspaceId, authHeaders, edit: buildAddFieldEdit(typeKey, field), mapping, apply, asJson });
+  }
+
+  throw new Error(SHAPE_USAGE);
+}
+
+module.exports = {
+  SHAPE_ACTIONS,
+  SHAPE_USAGE,
+  FIELD_KINDS,
+  isManualShapeAction,
+  positionals,
+  parseStatusList,
+  parseFieldList,
+  buildTypeFromFlags,
+  buildAddStatusEdit,
+  buildAddFieldEdit,
+  formatShape,
+  runManualShapeCommand
+};