@remits/remits-cli 0.1.90 → 0.1.92

package/index.js

@@ -72,6 +72,10 @@ const ACCOUNT_SCAN_EXCLUDE_DIRS = new Set([
   'tmp'
 ]);
 
+// Flags that are legitimately repeatable accumulate into an array instead of last-wins. Every other
+// flag keeps last-wins so existing callers are unaffected.
+const REPEATABLE_FLAGS = new Set(['expected-removed', 'expectedRemoved']);
+
 function parseArgs(argv) {
   const out = { _: [] };
   for (let i = 0; i < argv.length; i++) {
@@ -82,12 +86,18 @@ function parseArgs(argv) {
     }
     const key = arg.slice(2);
     const next = argv[i + 1];
+    let value;
     if (!next || next.startsWith('--')) {
-      out[key] = true;
+      value = true;
     } else {
-      out[key] = next;
+      value = next;
       i += 1;
     }
+    if (REPEATABLE_FLAGS.has(key) && Object.prototype.hasOwnProperty.call(out, key)) {
+      out[key] = (Array.isArray(out[key]) ? out[key] : [out[key]]).concat(value);
+    } else {
+      out[key] = value;
+    }
   }
   return out;
 }
@@ -268,6 +278,35 @@ function printResolvedBaseUrl(baseUrl) {
   console.log('Base URL:', normalizeBaseUrl(baseUrl || DEFAULT_BASE_URL));
 }
 
+// Tools whose name signals they mutate state rather than only reading it. Used solely to escalate the
+// prod banner from "reading live data" to "WRITING live data" — never to block or permit anything.
+const MUTATING_TOOL_PATTERN = /(^|_)(patch|edit|create|commit|update|delete|remove|write|set|assign|run|execute|send|pause|unpause|interrupt|restore|repair|migrate|sync)(_|$)/i;
+
+function looksLikeDryRun(input) {
+  if (!input || typeof input !== 'object') return false;
+  const value = input.dryRun !== undefined ? input.dryRun : input.dry_run;
+  return value === true || value === 'true';
+}
+
+/**
+ * One consistent banner across every surface that can touch production. Agents have repeatedly run a
+ * prod write believing they were in test mode, so the banner is loud, states the account it resolved,
+ * and distinguishes a live WRITE from a live read.
+ */
+function printProdDataBanner({ dataMode, accountId, baseUrl, operation, mutating = false, dryRun = false }) {
+  if (String(dataMode || '').toLowerCase() !== 'prod') return;
+  const bar = '='.repeat(72);
+  const headline = dryRun
+    ? 'PROD DATA — DRY RUN (no write will be attempted)'
+    : (mutating ? 'PROD DATA WRITE — this runs against LIVE production data' : 'PROD DATA READ — this reads LIVE production data');
+  console.log(bar);
+  console.log('  ' + headline);
+  console.log('  operation: ' + (operation || 'unknown'));
+  if (accountId != null) console.log('  account:   ' + accountId);
+  if (baseUrl) console.log('  host:      ' + normalizeBaseUrl(baseUrl));
+  console.log(bar);
+}
+
 // A tool's OWN verdict, which is separate from whether the call was dispatched. Only an explicit
 // failure signal counts: tools legitimately return strings, arrays, and maps with no `success` key.
 // Used as a fallback when the platform build predates the envelope's `toolSuccess`.
@@ -1242,6 +1281,124 @@ function collectComponents(cwd) {
   return components;
 }
 
+function componentPathInfo(cwd, filePath) {
+  const mapping = {
+    schemas: 'schema',
+    readers: 'reader',
+    actions: 'action',
+    embeddables: 'embeddable',
+    i18n: 'i18n',
+    rules: 'rule',
+    templates: 'htmltemplate',
+    agents: 'utility',
+    tools: 'tool',
+    prompts: 'prompt',
+    tests: 'test'
+  };
+  const relative = String(filePath || '').replace(/\\/g, '/').replace(/^"|"$/g, '');
+  const parts = relative.split('/');
+  if (parts.length < 3 || parts[0] !== 'components') {
+    return null;
+  }
+  const type = mapping[parts[1]];
+  if (!type) {
+    return null;
+  }
+  const fileName = parts.slice(2).join('/');
+  if (fileName.includes('/')) {
+    return null;
+  }
+  const metaMatch = fileName.match(/^(.+?)_(.+)\.meta\.ya?ml$/i);
+  const match = metaMatch || fileName.match(/^(.+?)_(.+)\.([^.]+)$/);
+  if (!match) {
+    return null;
+  }
+  const prefix = match[1];
+  const rawName = match[2];
+  const ext = metaMatch ? 'meta' : match[3].toLowerCase();
+  const id = /^\d+$/.test(prefix) ? Number(prefix) : null;
+  const name = normalizeName(rawName);
+  const key = type + ':' + (id ? 'id:' + id : 'name:' + name.toLowerCase());
+  let field = ext;
+  if (ext === 'meta') field = 'metadata';
+  else if ((type === 'utility' || type === 'prompt') && ext === 'md') field = 'prompt';
+  else if (ext === 'groovy' || ext === 'md') field = 'source';
+  else if (type === 'embeddable' && ext === 'html') field = 'html';
+  else if (type === 'embeddable' && ext === 'js') field = 'javascript';
+  else if (type === 'htmltemplate' && ext === 'html') field = 'html';
+  else if (type === 'htmltemplate' && ext === 'json') field = 'previewData';
+  else if (type === 'tool' && ext === 'json') field = 'inputSchema';
+  else if (type === 'i18n' && ext === 'json') field = 'messages';
+  else if (type === 'schema' && ext === 'json') field = 'schema';
+
+  return { key, type, id, name, field, path: relative };
+}
+
+// Returns null (not []) when git cannot answer — e.g. this checkout is not a git repo. The caller
+// must not render "0 components edited" in that case, because it is a missing answer, not a zero.
+function changedComponentsFromWorkingTree(cwd) {
+  let porcelain = '';
+  try {
+    // NOT runGit(): it trims the whole output, which eats the leading space of porcelain's 2-char
+    // status field on the FIRST line (` M path` -> `M path`). Any fixed-offset slice then reads the
+    // path one character short and silently drops that entry — so a single modified component
+    // reported as zero, while an untracked one ("?? path", no leading space) reported fine.
+    porcelain = execSync('git status --porcelain -- components', {
+      cwd,
+      stdio: ['ignore', 'pipe', 'pipe']
+    }).toString();
+  } catch (_) {
+    return null;
+  }
+  if (!porcelain.trim()) {
+    return [];
+  }
+  const byKey = new Map();
+  for (const rawLine of porcelain.split(/\r?\n/)) {
+    // Status is exactly 2 columns, then a space, then the path. Match it rather than slicing, so a
+    // status whose first column is a space (unstaged change) parses identically to a staged one.
+    const parsed = /^(..) (.*)$/.exec(rawLine.replace(/\s+$/, ''));
+    if (!parsed) continue;
+    const status = parsed[1].trim() || parsed[1];
+    let filePath = parsed[2].trim();
+    // Renames render as "old -> new"; the new path is the one that exists on disk.
+    if (filePath.includes(' -> ')) {
+      filePath = filePath.split(' -> ').pop().trim();
+    }
+    // Quoted paths (non-ASCII / spaces) come back wrapped in double quotes.
+    if (filePath.startsWith('"') && filePath.endsWith('"')) {
+      filePath = filePath.slice(1, -1);
+    }
+    const info = componentPathInfo(cwd, filePath);
+    if (!info) {
+      continue;
+    }
+    if (!byKey.has(info.key)) {
+      byKey.set(info.key, {
+        type: info.type,
+        id: info.id,
+        name: info.name,
+        fields: [],
+        statuses: [],
+        paths: []
+      });
+    }
+    const entry = byKey.get(info.key);
+    if (!entry.fields.includes(info.field)) entry.fields.push(info.field);
+    if (!entry.statuses.includes(status)) entry.statuses.push(status);
+    if (!entry.paths.includes(info.path)) entry.paths.push(info.path);
+  }
+  return Array.from(byKey.values()).map((entry) => ({
+    ...entry,
+    fields: entry.fields.sort(),
+    paths: entry.paths.sort()
+  })).sort((a, b) => {
+    const typeCmp = String(a.type).localeCompare(String(b.type));
+    if (typeCmp !== 0) return typeCmp;
+    return String(a.id || a.name || '').localeCompare(String(b.id || b.name || ''));
+  });
+}
+
 function parsePositiveInt(value, fallback) {
   const parsed = Number(value);
   return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
@@ -1259,6 +1416,14 @@ function describeError(err) {
   const parts = [];
   if (err.response && err.response.data) {
     const responseData = err.response.data;
+    // The server distinguishes a failure in the RUNTIME (Groovy reflective dispatch, empty connection
+    // pool, Redis reconnect, lock-wait timeout) from a tool that ran and genuinely failed. Surface that
+    // verdict, or the caller cannot tell "retry this" from "this is broken".
+    if (responseData.failureClass === 'transient_infrastructure') {
+      parts.push('TRANSIENT INFRASTRUCTURE FAILURE (retryable)');
+      if (responseData.failureReason) parts.push('signal: ' + responseData.failureReason);
+      if (responseData.hint) parts.push(responseData.hint);
+    }
     if (responseData.message) {
       parts.push(String(responseData.message));
     } else if (typeof responseData === 'string') {
@@ -1679,6 +1844,7 @@ async function pushComponentsCommand(flags) {
   const requestedMode = String(flags.mode || 'stage').toLowerCase();
   const mode = requestedMode === 'push' ? 'stage' : requestedMode;
   const components = collectComponents(cwd);
+  const changedFromWorkingTree = changedComponentsFromWorkingTree(cwd);
 
   if (requestedMode === 'push') {
     console.log('Warning: `components push` is deprecated and currently behaves the same as `components stage`.');
@@ -1694,6 +1860,8 @@ async function pushComponentsCommand(flags) {
     replace: true,
     components
   }).then((r) => r.data);
+  response.changedFromWorkingTree = changedFromWorkingTree || [];
+  response.changedFromWorkingTreeAvailable = changedFromWorkingTree !== null;
 
   if (flagEnabled(flags.json)) {
     console.log(JSON.stringify(response, null, 2));
@@ -1744,14 +1912,35 @@ function printComponentCommandResponse(label, response, flags) {
 }
 
 function printStageSummary(response, flags) {
-  console.log('Updated:', response.updated || 0);
-  console.log('Unchanged:', response.unchanged || 0);
+  // `stage` always uploads EVERY component in the repo, so the server's Updated/Unchanged counts
+  // describe the whole staging overlay, not what this checkout edited. That is what made "Updated: 75"
+  // read as "I changed 75 components". Lead with the working-tree delta, which is the number an agent
+  // is actually asking about, and label the server counts as the overlay they describe.
+  const changed = Array.isArray(response.changedFromWorkingTree) ? response.changedFromWorkingTree : [];
+  const tracked = response.changedFromWorkingTreeAvailable !== false;
+  if (tracked) {
+    console.log('Components edited in this working tree:', changed.length);
+    changed.slice(0, 20).forEach((entry) => {
+      const label = (entry.type || 'component') + ' ' + (entry.id || entry.name || '(unknown)');
+      const name = entry.name && entry.id ? ' ' + entry.name : '';
+      const fields = Array.isArray(entry.fields) && entry.fields.length ? ': ' + entry.fields.join(', ') : '';
+      console.log('  ' + label + name + fields);
+    });
+    if (changed.length > 20) {
+      console.log('  ...' + (changed.length - 20) + ' more');
+    }
+    if (!changed.length) {
+      console.log('  (no uncommitted component edits — already-committed edits are staged but not listed here)');
+    }
+  }
+  console.log('Staging overlay — newly written:', response.updated || 0);
+  console.log('Staging overlay — already current:', response.unchanged || 0);
   console.log('Skipped:', Array.isArray(response.skipped) ? response.skipped.length : 0);
   if (response.reconcile) {
     console.log('Reconciled stale keys:', response.reconcile.removedCount || 0);
   }
   if (response.staging) {
-    console.log('Remaining staged count:', response.staging.remainingCount || 0);
+    console.log('Total staged entries for this branch/user:', response.staging.remainingCount || 0);
   }
   printComponentCommandResponse('Components stage', response, flags);
 }
@@ -1901,6 +2090,15 @@ async function syncComponentsCommand(flags) {
   const dryRun = flagEnabled(flags['dry-run']) || flagEnabled(flags.dryRun);
   const api = buildAxios(baseUrl, session.token);
 
+  printProdDataBanner({
+    dataMode,
+    accountId,
+    baseUrl,
+    operation: 'components sync (branch ' + branchName + ')',
+    mutating: true,
+    dryRun
+  });
+
   const response = await loggedPost(api, cwd, '/cli/components', {
     token: session.token,
     accountId,
@@ -1916,8 +2114,13 @@ async function syncComponentsCommand(flags) {
     throw new Error(response.message || 'Server sync failed');
   }
 
+  const summary = buildSyncSummary(response);
+  const gate = evaluateSyncGates(response, flags, changedComponentsFromWorkingTree(cwd));
+  summary.gates = gate.checks;
+
   if (flagEnabled(flags.json)) {
-    console.log(JSON.stringify(response, null, 2));
+    console.log(JSON.stringify(flagEnabled(flags.summary) ? summary : response, null, 2));
+    failOnSyncGate(gate);
     return response;
   }
 
@@ -1928,10 +2131,169 @@ async function syncComponentsCommand(flags) {
   if (response.sync && response.sync.dryRun) {
     console.log('Dry run: no variants were written and staging was not cleared.');
   }
+  if (flagEnabled(flags['names-only']) || flagEnabled(flags.namesOnly)) {
+    printSyncNames(response);
+    failOnSyncGate(gate);
+    return response;
+  }
+  if (flagEnabled(flags.summary)) {
+    console.log('Components sync summary:', JSON.stringify(summary, null, 2));
+    failOnSyncGate(gate);
+    return response;
+  }
   console.log('Components sync:', JSON.stringify(response, null, 2));
+  failOnSyncGate(gate);
   return response;
 }
 
+// One "type:id" / "type:name" token per planned write, so an agent can eyeball or diff the plan
+// without paging through the full server response.
+function syncPlanEntries(response) {
+  const results = ((response && response.sync) || {}).syncResults || {};
+  const entries = [];
+  ['overridden', 'added', 'removed', 'errors'].forEach((bucket) => {
+    (Array.isArray(results[bucket]) ? results[bucket] : []).forEach((entry) => {
+      entries.push({
+        bucket,
+        type: String(entry.type || entry.kind || 'component').toLowerCase(),
+        id: entry.id == null ? null : String(entry.id),
+        name: entry.name || null
+      });
+    });
+  });
+  return entries;
+}
+
+function syncEntryToken(entry) {
+  return entry.type + ':' + (entry.id != null ? entry.id : (entry.name || '?'));
+}
+
+function printSyncNames(response) {
+  const entries = syncPlanEntries(response);
+  if (!entries.length) {
+    console.log('No planned component writes.');
+    return;
+  }
+  entries.forEach((entry) => {
+    console.log(entry.bucket.toUpperCase().padEnd(10), syncEntryToken(entry), entry.name || '');
+  });
+}
+
+function parseExpectedRemoved(flags) {
+  const raw = flags['expected-removed'] != null ? flags['expected-removed'] : flags.expectedRemoved;
+  if (raw == null) return null;
+  // A bare `--expected-removed` with no value means "I expect none" — fail closed on any removal.
+  const values = raw === true ? [] : (Array.isArray(raw) ? raw : [raw]);
+  const tokens = new Set();
+  values.forEach((value) => {
+    String(value).split(',').forEach((token) => {
+      const trimmed = token.trim().toLowerCase();
+      if (trimmed) tokens.add(trimmed);
+    });
+  });
+  return tokens;
+}
+
+// Fail-closed gates. Each returns a violation string or null; the command exits non-zero if any fire.
+function evaluateSyncGates(response, flags, changedFromWorkingTree) {
+  const entries = syncPlanEntries(response);
+  const results = ((response && response.sync) || {}).syncResults || {};
+  const removed = entries.filter((e) => e.bucket === 'removed');
+  const errors = Array.isArray(results.errors) ? results.errors : [];
+  const expectedRemoved = parseExpectedRemoved(flags);
+  const violations = [];
+  const checks = {};
+
+  if (flagEnabled(flags['fail-on-errors']) || flagEnabled(flags.failOnErrors)) {
+    checks.failOnErrors = errors.length === 0;
+    if (errors.length) {
+      violations.push('--fail-on-errors: server reported ' + errors.length + ' component sync error(s): ' +
+        errors.map((e) => (e.type || 'component') + ':' + (e.id != null ? e.id : e.name)).join(', '));
+    }
+  }
+
+  // --expected-removed implies --fail-on-removed: you named the removals you accept, so any other
+  // removal is by definition unexpected.
+  const failOnRemoved = flagEnabled(flags['fail-on-removed']) || flagEnabled(flags.failOnRemoved) || expectedRemoved !== null;
+  if (failOnRemoved) {
+    const unexpected = removed.filter((entry) => !expectedRemoved || !expectedRemoved.has(syncEntryToken(entry)));
+    checks.failOnRemoved = unexpected.length === 0;
+    if (unexpected.length) {
+      violations.push((expectedRemoved ? '--expected-removed' : '--fail-on-removed') +
+        ': plan removes/tombstones ' + unexpected.length + ' unlisted component(s): ' +
+        unexpected.map(syncEntryToken).join(', '));
+    }
+  }
+
+  if (flagEnabled(flags['changed-only']) || flagEnabled(flags.changedOnly)) {
+    if (changedFromWorkingTree === null) {
+      violations.push('--changed-only: this checkout is not a git working tree, so the changed set cannot be established.');
+      checks.changedOnly = false;
+    } else {
+      // A component the checkout edited is identified by type + id, or type + name for `new_` files.
+      const allowedIds = new Set(changedFromWorkingTree.filter((c) => c.id != null).map((c) => c.type + ':' + c.id));
+      const allowedNames = new Set(changedFromWorkingTree.filter((c) => c.name).map((c) => c.type + ':' + String(c.name).toLowerCase()));
+      const unexpected = entries.filter((entry) => {
+        if (entry.id != null && allowedIds.has(entry.type + ':' + entry.id)) return false;
+        if (entry.name && allowedNames.has(entry.type + ':' + String(entry.name).toLowerCase())) return false;
+        return true;
+      });
+      checks.changedOnly = unexpected.length === 0;
+      if (unexpected.length) {
+        violations.push('--changed-only: plan touches ' + unexpected.length + ' component(s) this working tree did not edit: ' +
+          unexpected.slice(0, 20).map(syncEntryToken).join(', ') + (unexpected.length > 20 ? ', ...' : ''));
+      }
+    }
+  }
+
+  return { violations, checks };
+}
+
+function failOnSyncGate(gate) {
+  if (gate && gate.violations && gate.violations.length) {
+    throw new Error('components sync safety gate failed:\n  ' + gate.violations.join('\n  '));
+  }
+}
+
+function buildSyncSummary(response) {
+  const sync = (response && response.sync) || {};
+  const results = sync.syncResults || {};
+  const removed = Array.isArray(results.removed) ? results.removed : [];
+  const errors = Array.isArray(results.errors) ? results.errors : [];
+  const skipped = Array.isArray(results.skipped) ? results.skipped : [];
+  const added = Array.isArray(results.added) ? results.added : [];
+  const overridden = Array.isArray(results.overridden) ? results.overridden : [];
+  const unchanged = Array.isArray(results.unchanged) ? results.unchanged : [];
+  const warnings = [];
+  if (removed.length) warnings.push(String(removed.length) + ' removed/tombstone entr' + (removed.length === 1 ? 'y' : 'ies') + ' present');
+  if (errors.length) warnings.push(String(errors.length) + ' sync error' + (errors.length === 1 ? '' : 's') + ' present');
+  return {
+    success: response && response.success === true,
+    accountId: response && response.accountId,
+    branchName: sync.branchName || (response && response.branchName),
+    mode: sync.mode || 'trunk',
+    dryRun: Boolean(sync.dryRun),
+    overridden: overridden.length,
+    added: added.length,
+    removed: removed.map((entry) => ({
+      type: entry.type,
+      kind: entry.kind,
+      name: entry.name,
+      id: entry.id,
+      variantId: entry.variantId
+    })),
+    unchanged: unchanged.length,
+    skipped: skipped.length,
+    errors: errors.length,
+    errorDetails: errors.map((entry) => ({
+      type: entry.type,
+      id: entry.id,
+      error: entry.error
+    })),
+    warnings
+  };
+}
+
 // Inspect committed branch variants: durable, branch-scoped overlays of this account's components.
 // Unlike `components status` (which shows the ephemeral Redis staging cache), these are what
 // subscribing accounts actually resolve in production.
@@ -2285,6 +2647,15 @@ async function testCommand(flags) {
   // --variant-branch explicitly probes a committed variant branch. Normally omitted: variants resolve
   // from the account's subscription edge, which is what production does.
   const variantBranch = flags['variant-branch'];
+
+  printProdDataBanner({
+    dataMode,
+    accountId: asAccountId || accountId,
+    baseUrl,
+    operation: 'test run ' + String(testRef),
+    mutating: true
+  });
+
   const start = await loggedPost(api, cwd, '/cli/test', {
     token: session.token,
     accountId,
@@ -2507,6 +2878,15 @@ async function toolCommand(flags) {
     return;
   }
 
+  printProdDataBanner({
+    dataMode,
+    accountId,
+    baseUrl,
+    operation: 'tool ' + String(toolName),
+    mutating: MUTATING_TOOL_PATTERN.test(String(toolName)),
+    dryRun: looksLikeDryRun(input)
+  });
+
   const response = await loggedPost(api, cwd, '/cli/tool', {
     token: session.token,
     accountId,
@@ -4965,6 +5345,113 @@ function autoUpdateIfNeeded(originalArgv, options = {}) {
   }
 }
 
+function printComponentsHelp(subcommand) {
+  if (subcommand === 'sync') {
+    console.log('Usage: remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary] [--json]');
+    console.log('');
+    console.log('On trunk this reconciles the pushed repository into live component rows.');
+    console.log('On a variant branch this writes ComponentVariant overlays only.');
+    console.log('--dry-run is only supported on variant branches and writes nothing.');
+    console.log('--summary prints compact counts, removals/tombstones, errors, skipped items, and warnings.');
+    console.log('');
+    console.log('Agent safety gates (each exits non-zero instead of printing a wall of JSON):');
+    console.log('  --changed-only            fail unless every planned write is a component this checkout changed');
+    console.log('  --names-only              print only "type id name" lines for the planned writes');
+    console.log('  --fail-on-removed         fail if the plan removes/tombstones anything');
+    console.log('  --fail-on-errors          fail if the server reported any per-component sync error');
+    console.log('  --expected-removed t:id   whitelist an intended removal; repeatable/comma-delimited.');
+    console.log('                            Implies --fail-on-removed, so any OTHER removal fails.');
+    return;
+  }
+  if (subcommand === 'stage' || subcommand === 'push') {
+    console.log('Usage: remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--json|--verbose]');
+    console.log('');
+    console.log('Stages local component files into the Redis staging cache. It never writes the database or git.');
+    console.log('Terminal output separates local working-tree component deltas from the full materialized staging cache count.');
+    return;
+  }
+  if (subcommand === 'status') {
+    console.log('Usage: remits-cli components status [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID] [--json|--verbose]');
+    console.log('');
+    console.log('Shows staged entries and whether this checkout resolves/writes trunk or a variant branch.');
+    return;
+  }
+  if (subcommand === 'clear') {
+    console.log('Usage: remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE] [--component-id ID] [--all] [--json|--verbose]');
+    console.log('');
+    console.log('Clears staged Redis entries without touching the database or git.');
+    console.log('Use --component-type with --component-id when the id could exist in multiple component families.');
+    console.log('Use --all for the temporary-experiment cleanup flow.');
+    return;
+  }
+  if (subcommand === 'commit') {
+    console.log('Usage: remits-cli components commit [--message "msg"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones]');
+    console.log('');
+    console.log('Runs local git add/commit/push, then server sync. Prefer explicit git + components sync when you need inspectable phases.');
+    console.log('components commit does not support --dry-run.');
+    return;
+  }
+  console.log('Usage: remits-cli components <stage|status|clear|sync|commit|branches|branch>');
+  console.log('  remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--json|--verbose]');
+  console.log('  remits-cli components status [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID] [--json|--verbose]');
+  console.log('  remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE] [--component-id ID] [--all] [--json|--verbose]');
+  console.log('  remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary]');
+  console.log('  remits-cli components commit [--message "msg"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones]');
+  console.log('');
+  console.log('  --force-tombstones applies only on non-trunk variant syncs, when a missing trunk');
+  console.log('  component file is intentionally being recorded as a tombstone override.');
+  console.log('  --dry-run reports the variant override/add/remove plan without writing variants,');
+  console.log('  updating sync SHA cache, or clearing staged CLI entries.');
+  console.log('  --summary, --changed-only, --names-only, --fail-on-removed, --fail-on-errors, and');
+  console.log('  --expected-removed keep sync output small and fail closed. See `components sync --help`.');
+  console.log('');
+  console.log('Committed branch variants (durable overlays subscribing accounts resolve in production):');
+  console.log('  remits-cli components branches [--json]');
+  console.log('  remits-cli components branch <name> [--json]                       # overridden/added/removed + drift');
+  console.log('  remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]');
+  console.log('  remits-cli components branch <name> --subscribers [--json]');
+  console.log('  remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>]');
+  console.log('  remits-cli components branch <name> --unsubscribe <accountId>');
+  console.log('  remits-cli components branch <name> --retire [--force]');
+}
+
+function printTestHelp() {
+  console.log('Usage: remits-cli test run --test <id|name> [--base-url URL] [--names name1,name2] [--watch true|false] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none]');
+  console.log('');
+  console.log('Runs a Test component against the staged/variant world for this checkout.');
+  console.log('Examples:');
+  console.log('  remits-cli test run --test 11');
+  console.log('  remits-cli test run --test "Merchant Statements" --names "managed account case"');
+  console.log('');
+  console.log('Notes:');
+  console.log('  --names is comma-delimited, so avoid commas in individual test case names.');
+  console.log('  --as-account changes the execution account so subscriber branch edges apply.');
+  console.log('  --data-mode prod intentionally targets live production data.');
+}
+
+function printToolHelp() {
+  console.log('Usage: remits-cli tool --name <toolName> [--base-url URL] [--account-id ID] [--branch BRANCH] [--input "{...}"|--input-file file.json] [--data-mode test|prod] [--variant-branch NAME|none] [--timeout-ms 60000] [--async true --wait true]');
+  console.log('       remits-cli tool status --call-id <callId> [--base-url URL] [--account-id ID] [--data-mode test|prod]');
+  console.log('');
+  console.log('Examples:');
+  console.log('  remits-cli tool --name mcp_firestore_search --input-file query.json --data-mode prod');
+  console.log('  remits-cli tool --name mcp_run_action --input \'{"accountId":49,"actionId":200,"executionMode":"async"}\' --data-mode prod');
+  console.log('');
+  console.log('For mcp_run_action and mcp_run_agent, prefer the tool\'s own executionMode:"async" and poll with that tool\'s controlAction:"status".');
+}
+
+function printToolsHelp() {
+  console.log('Usage: remits-cli tools [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--variant-branch NAME|none]');
+  console.log('');
+  console.log('Refreshes .remits-cli/tools/tools.json for the current account/branch/data-mode context.');
+}
+
+function printTokenHelp() {
+  console.log('Usage: remits-cli token [--base-url URL] [--branch BRANCH] [--path embeddable/path] [--data-mode test|prod] [--as-account ID] [--variant-branch NAME|none]');
+  console.log('');
+  console.log('Mints a branch-aware browser URL for embeddable verification.');
+}
+
 async function main() {
   migrateSessionIfNeeded();
   const originalArgv = process.argv.slice(2);
@@ -5022,7 +5509,7 @@ async function main() {
     console.log('  remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--json|--verbose]');
     console.log('  remits-cli components status [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID] [--json|--verbose]');
     console.log('  remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE] [--component-id ID] [--all] [--json|--verbose]');
-    console.log('  remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run]');
+    console.log('  remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run] [--summary]');
     console.log('  remits-cli components commit [--message \"msg\"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones]');
     console.log('  remits-cli components branches [--json]                     # committed branch variants for this account');
     console.log('  remits-cli components branch <name> [--diff <componentId> --component-type <kind>] [--subscribers] [--json]');
@@ -5039,27 +5526,28 @@ async function main() {
     process.exit(0);
   }
 
-  if (command === 'components' && wantsHelp) {
-    console.log('Usage: remits-cli components <stage|status|clear|sync|commit|branches|branch>');
-    console.log('  remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--json|--verbose]');
-    console.log('  remits-cli components status [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID] [--json|--verbose]');
-    console.log('  remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE] [--component-id ID] [--all] [--json|--verbose]');
-    console.log('  remits-cli components sync [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones] [--dry-run]');
-    console.log('  remits-cli components commit [--message \"msg\"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod] [--force-tombstones]');
-    console.log('');
-    console.log('  --force-tombstones applies only on non-trunk variant syncs, when a missing trunk');
-    console.log('  component file is intentionally being recorded as a tombstone override.');
-    console.log('  --dry-run reports the variant override/add/remove plan without writing variants,');
-    console.log('  updating sync SHA cache, or clearing staged CLI entries.');
-    console.log('');
-    console.log('Committed branch variants (durable overlays subscribing accounts resolve in production):');
-    console.log('  remits-cli components branches [--json]');
-    console.log('  remits-cli components branch <name> [--json]                       # overridden/added/removed + drift');
-    console.log('  remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]');
-    console.log('  remits-cli components branch <name> --subscribers [--json]');
-    console.log('  remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>]');
-    console.log('  remits-cli components branch <name> --unsubscribe <accountId>');
-    console.log('  remits-cli components branch <name> --retire [--force]');
+  if (wantsHelp && command === 'test') {
+    printTestHelp();
+    process.exit(0);
+  }
+
+  if (wantsHelp && command === 'tool') {
+    printToolHelp();
+    process.exit(0);
+  }
+
+  if (wantsHelp && command === 'tools') {
+    printToolsHelp();
+    process.exit(0);
+  }
+
+  if (wantsHelp && command === 'token') {
+    printTokenHelp();
+    process.exit(0);
+  }
+
+  if (wantsHelp && command === 'components') {
+    printComponentsHelp(subcommand);
     process.exit(0);
   }