@empirical-gauzza/cli 1.0.38 → 1.0.40

package/lib/memoryResolve.js

@@ -1,112 +1,112 @@
-'use strict';
-
-// Resolving "which memory did the user mean" from a --match query, shared by every memory
-// subcommand that accepts --match. It lives in its own module so attachmentCommands.js can use
-// it without a require cycle back through memoryCommands.js; memoryCommands.js re-exports the
-// three names so existing importers and tests are unaffected.
-
-const { warn } = require('./ui');
-const { httpJson } = require('./http');
-const { parseOption } = require('./env');
-const { buildApiAuthHeaders } = require('./auth');
-
-async function resolveMemoryByQuery(match, minScore, accessToken, baseUrl, filters) {
-  const queryUrl = new URL('/api/v1/memories/query', baseUrl).toString();
-  const body = { query: match, topK: 5 };
-  if (filters && Object.keys(filters).length) body.filters = filters;
-  let response;
-  try {
-    response = await httpJson(queryUrl, 'POST', body, buildApiAuthHeaders(accessToken));
-  } catch (error) {
-    return { found: false, reason: 'error', message: error.message };
-  }
-
-  const results = (response && response.data && Array.isArray(response.data.results))
-    ? response.data.results
-    : (Array.isArray(response) ? response : []);
-
-  if (!results.length) {
-    return { found: false, reason: 'no_results' };
-  }
-
-  const scored = results.map((r) => ({
-    id: r.id,
-    summary: r.summary,
-    score: r.rankScore != null ? r.rankScore : (r.similarityScore != null ? r.similarityScore : 0)
-  }));
-
-  scored.sort((a, b) => b.score - a.score);
-
-  // A caller-supplied filter (e.g. --tags) that narrows the server-side result set to exactly
-  // one memory is already a stronger disambiguation signal than the semantic score - trust it
-  // outright rather than falling through to the score check below. This matters because Atlas
-  // vector search has a real async indexing lag: a memory created moments ago can come back
-  // with score 0 (unindexed, not "not this one") even when a tag filter already proves it is
-  // the only candidate. Fixes a real bug found 2026-08-25 where delete --match failed on a
-  // memory `query` found instantly, because delete had no way to trust a filtered, unambiguous
-  // result over a stale/zero semantic score.
-  if (filters && Object.keys(filters).length && results.length === 1) {
-    const only = scored[0];
-    return { found: true, memory: { id: only.id, summary: only.summary, score: only.score } };
-  }
-
-  const top = scored[0];
-  const second = scored[1];
-
-  if (top.score < minScore) {
-    return { found: false, reason: 'low_score', candidates: scored.slice(0, 3) };
-  }
-
-  if (second && (top.score - second.score) <= 0.05) {
-    return { found: false, reason: 'ambiguous', candidates: scored.slice(0, 3) };
-  }
-
-  return { found: true, memory: { id: top.id, summary: top.summary, score: top.score } };
-}
-
-// --match resolution depends on Atlas vector search, which has a real async indexing lag:
-// a memory created moments ago can be invisible to $vectorSearch even though it is already
-// findable by tag. Letting --match commands pass --tags narrows the candidate pool directly
-// instead of hoping semantic ranking surfaces the right one - the fix for a real bug found
-// 2026-08-25 where delete --match returned unrelated score-0 candidates for a memory that
-// `query` found instantly. Deliberately --tags (plural) only, not --category: `delete` already
-// uses singular --tag/--category to mean "bulk delete everything in this category", so adding
-// --category here would silently reroute a --match delete into a bulk delete instead of
-// narrowing it - --tags never collides with that bulk-mode gate.
-function parseMatchFilters(args) {
-  const tagsRaw = parseOption(args, '--tags', '');
-  const tags = tagsRaw ? tagsRaw.split(',').map((t) => t.trim()).filter(Boolean) : [];
-  const filters = {};
-  if (tags.length) filters.tags = tags;
-  return filters;
-}
-
-function printMemoryResolveError(result) {
-  if (result.reason === 'no_results') {
-    warn(JSON.stringify({ error: true, code: 'no_results', message: 'No memories matched the query.' }));
-  } else if (result.reason === 'low_score') {
-    warn(JSON.stringify({
-      error: true,
-      code: 'low_score',
-      message: 'Top result score was below --min-score threshold.',
-      candidates: result.candidates
-    }));
-  } else if (result.reason === 'ambiguous') {
-    warn(JSON.stringify({
-      error: true,
-      code: 'ambiguous',
-      message: 'Multiple memories matched with similar scores. Use --memory-id to target one directly.',
-      candidates: result.candidates
-    }));
-  } else if (result.reason === 'error') {
-    warn(JSON.stringify({ error: true, code: 'query_error', message: result.message }));
-  } else {
-    warn(JSON.stringify({ error: true, code: 'resolve_failed', message: 'Could not resolve memory.' }));
-  }
-}
-
-module.exports = {
-  resolveMemoryByQuery,
-  parseMatchFilters,
-  printMemoryResolveError
-};
+'use strict';
+
+// Resolving "which memory did the user mean" from a --match query, shared by every memory
+// subcommand that accepts --match. It lives in its own module so attachmentCommands.js can use
+// it without a require cycle back through memoryCommands.js; memoryCommands.js re-exports the
+// three names so existing importers and tests are unaffected.
+
+const { warn } = require('./ui');
+const { httpJson } = require('./http');
+const { parseOption } = require('./env');
+const { buildApiAuthHeaders } = require('./auth');
+
+async function resolveMemoryByQuery(match, minScore, accessToken, baseUrl, filters) {
+  const queryUrl = new URL('/api/v1/memories/query', baseUrl).toString();
+  const body = { query: match, topK: 5 };
+  if (filters && Object.keys(filters).length) body.filters = filters;
+  let response;
+  try {
+    response = await httpJson(queryUrl, 'POST', body, buildApiAuthHeaders(accessToken));
+  } catch (error) {
+    return { found: false, reason: 'error', message: error.message };
+  }
+
+  const results = (response && response.data && Array.isArray(response.data.results))
+    ? response.data.results
+    : (Array.isArray(response) ? response : []);
+
+  if (!results.length) {
+    return { found: false, reason: 'no_results' };
+  }
+
+  const scored = results.map((r) => ({
+    id: r.id,
+    summary: r.summary,
+    score: r.rankScore != null ? r.rankScore : (r.similarityScore != null ? r.similarityScore : 0)
+  }));
+
+  scored.sort((a, b) => b.score - a.score);
+
+  // A caller-supplied filter (e.g. --tags) that narrows the server-side result set to exactly
+  // one memory is already a stronger disambiguation signal than the semantic score - trust it
+  // outright rather than falling through to the score check below. This matters because Atlas
+  // vector search has a real async indexing lag: a memory created moments ago can come back
+  // with score 0 (unindexed, not "not this one") even when a tag filter already proves it is
+  // the only candidate. Fixes a real bug found 2026-08-25 where delete --match failed on a
+  // memory `query` found instantly, because delete had no way to trust a filtered, unambiguous
+  // result over a stale/zero semantic score.
+  if (filters && Object.keys(filters).length && results.length === 1) {
+    const only = scored[0];
+    return { found: true, memory: { id: only.id, summary: only.summary, score: only.score } };
+  }
+
+  const top = scored[0];
+  const second = scored[1];
+
+  if (top.score < minScore) {
+    return { found: false, reason: 'low_score', candidates: scored.slice(0, 3) };
+  }
+
+  if (second && (top.score - second.score) <= 0.05) {
+    return { found: false, reason: 'ambiguous', candidates: scored.slice(0, 3) };
+  }
+
+  return { found: true, memory: { id: top.id, summary: top.summary, score: top.score } };
+}
+
+// --match resolution depends on Atlas vector search, which has a real async indexing lag:
+// a memory created moments ago can be invisible to $vectorSearch even though it is already
+// findable by tag. Letting --match commands pass --tags narrows the candidate pool directly
+// instead of hoping semantic ranking surfaces the right one - the fix for a real bug found
+// 2026-08-25 where delete --match returned unrelated score-0 candidates for a memory that
+// `query` found instantly. Deliberately --tags (plural) only, not --category: `delete` already
+// uses singular --tag/--category to mean "bulk delete everything in this category", so adding
+// --category here would silently reroute a --match delete into a bulk delete instead of
+// narrowing it - --tags never collides with that bulk-mode gate.
+function parseMatchFilters(args) {
+  const tagsRaw = parseOption(args, '--tags', '');
+  const tags = tagsRaw ? tagsRaw.split(',').map((t) => t.trim()).filter(Boolean) : [];
+  const filters = {};
+  if (tags.length) filters.tags = tags;
+  return filters;
+}
+
+function printMemoryResolveError(result) {
+  if (result.reason === 'no_results') {
+    warn(JSON.stringify({ error: true, code: 'no_results', message: 'No memories matched the query.' }));
+  } else if (result.reason === 'low_score') {
+    warn(JSON.stringify({
+      error: true,
+      code: 'low_score',
+      message: 'Top result score was below --min-score threshold.',
+      candidates: result.candidates
+    }));
+  } else if (result.reason === 'ambiguous') {
+    warn(JSON.stringify({
+      error: true,
+      code: 'ambiguous',
+      message: 'Multiple memories matched with similar scores. Use --memory-id to target one directly.',
+      candidates: result.candidates
+    }));
+  } else if (result.reason === 'error') {
+    warn(JSON.stringify({ error: true, code: 'query_error', message: result.message }));
+  } else {
+    warn(JSON.stringify({ error: true, code: 'resolve_failed', message: 'Could not resolve memory.' }));
+  }
+}
+
+module.exports = {
+  resolveMemoryByQuery,
+  parseMatchFilters,
+  printMemoryResolveError
+};

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