@remits/remits-cli 0.1.85 → 0.1.87

package/README.md

@@ -29,7 +29,10 @@ git add -A
 git commit -m "sync passing changes"
 git push
 remits-cli components sync
+remits-cli components sync --branch feature_forked --dry-run
+remits-cli components sync --branch feature_forked --force-tombstones
 remits-cli token --path page/my-embeddable
+remits-cli token --path page/my-embeddable --variant-branch feature_forked
 remits-cli data-mode
 remits-cli data-mode set prod
 remits-cli sessions list
@@ -54,10 +57,12 @@ remits-cli install --skills --overwrite true
 ## How It Works
 
 - `components stage` uploads the current working tree into the staging cache used by test-mode execution. It replaces the branch/user staging scope with the current manifest, so stale aliases from prior stages are removed.
+- Schema `.meta.yml` sidecars can stage/sync the schema flags: `enableTrigger`, `enableFullText`, `enableRAG`, `enableRevisions`, `enableBigQuerySync`, `enableRules`, `anchor`, and `auxiliary`.
 - `components status` shows the branch/user staging entries that can shadow DB components during CLI-scoped test-mode execution.
 - `components clear` clears staged entries. Scope it with `--component-type` and/or `--component-id`. Component ids are type-local, so an id alone clears that one component when the id is staged in only one family; if the same id is staged across multiple families it returns an ambiguity error asking you to add `--component-type`. With no filter it clears every staged entry for the current branch; pass `--all` to force the full-branch wipe explicitly.
 - `components stage`, `components status`, and `components clear` print concise summaries by default. Add `--json` or `--verbose` to print the full server response.
-- `components sync` performs a server-side sync from the git remote into the Remits platform for the selected branch. It does not run local git commands. After a successful sync, the platform clears the branch/user staging scope so staged aliases cannot keep shadowing the newly synced DB rows.
+- `components sync` performs a server-side sync from the git remote into the Remits platform for the selected branch. It does not run local git commands. After a successful non-dry-run sync, the platform clears the branch/user staging scope so staged aliases cannot keep shadowing the newly synced DB rows.
+- On trunk, `components sync` performs the full repo-to-DB reconcile. On a non-trunk branch, it writes `ComponentVariant` overlays only and may refresh branch-local `account-info.json` for the subscribing account that initiated the sync. `--dry-run` is accepted only for non-trunk variant syncs and reports overrides/additions/tombstones without writing variants, caching the sync SHA, updating metadata, or clearing staging. `--force-tombstones` is accepted only for non-trunk variant syncs and should be used only when missing trunk component files are intentional tombstone overrides.
 - `components commit` is a convenience wrapper that performs local git commit/push, then `components sync`, then local `git fetch`/`git pull --ff-only`.
 - `components sync` returns the post-sync branch SHA produced by the platform. `components commit` verifies that `origin/<branch>` and local `HEAD` both match that exact SHA after the final pull.
 - `components push` is deprecated and currently behaves the same as `components stage`.
@@ -76,6 +81,7 @@ remits-cli install --skills --overwrite true
 - Avoid commas in individual test names. The `--names` filter is comma-delimited, so a single test case whose name contains commas cannot be targeted cleanly through `remits-cli test run --names ...`.
 - Test activity is streamed from websocket `TestSuite` events while final status is also polled from `/cli/test`.
 - Tool execution writes the full response to a separate file so large payloads do not bloat the session log.
+- `--variant-branch <name|none>` is available on `test run`, `token`, `tools`, and `tool`. Use it to probe a committed branch variant from any checkout; omit it to resolve the execution account's normal subscription, or pass `none`/`trunk` to force subscription semantics from a variant checkout.
 
 ## Service, Dashboard, WebSocket, and Tmux Lifecycle
 

package/index.js

@@ -352,7 +352,7 @@ function sessionJsonlFile(cwd) {
   return path.join(paths.sessionsDir, currentLocalSessionName(cwd) + '.jsonl');
 }
 
-const CONTENT_FIELDS = new Set(['source', 'html', 'javascript', 'css', 'schema', 'inputSchema', 'previewData']);
+const CONTENT_FIELDS = new Set(['source', 'html', 'javascript', 'css', 'schema', 'inputSchema', 'previewData', 'messages']);
 
 function sanitizeForLog(value) {
   if (value === null || value === undefined) {
@@ -1113,6 +1113,7 @@ function collectComponents(cwd) {
     readers: 'reader',
     actions: 'action',
     embeddables: 'embeddable',
+    i18n: 'i18n',
     rules: 'rule',
     templates: 'htmltemplate',
     agents: 'utility',
@@ -1182,6 +1183,8 @@ function collectComponents(cwd) {
         component.previewData = content;
       } else if (type === 'tool' && ext === 'json') {
         component.inputSchema = content;
+      } else if (type === 'i18n' && ext === 'json') {
+        component.messages = content;
       } else if (type === 'schema' && ext === 'json') {
         component.schema = content;
       }
@@ -1718,11 +1721,42 @@ function printStageSummary(response, flags) {
 }
 
 function printStatusSummary(response, flags) {
+  printBranchContext(response);
   console.log('Staged count:', response.stagedCount || 0);
   printComponentTypeCounts(response.entries || []);
   printComponentCommandResponse('Components staging', response, flags);
 }
 
+// Make the working tree's meaning explicit. An agent may be standing in a TRUNK checkout or in a
+// VARIANT branch's checkout, and the two differ on BOTH ends of the loop: what a run resolves, and
+// what a commit writes. Inferring that from the branch name alone is exactly the kind of ambiguity
+// that leads to editing the wrong world.
+function printBranchContext(response) {
+  const ctx = response && response.branchContext;
+  if (!ctx) return;
+
+  console.log('');
+  if (ctx.onTrunk) {
+    console.log('Working tree: TRUNK (' + response.branchName + ')');
+  } else {
+    console.log('Working tree: VARIANT BRANCH "' + response.branchName + '"  (trunk is "' + ctx.trunkBranch + '")');
+  }
+  console.log('  runs resolve:   ' + ctx.resolves);
+  console.log('  commit writes:  ' + ctx.commitWrites);
+
+  if (!ctx.onTrunk) {
+    console.log('  variants stored on this branch: ' + (ctx.variantCount || 0));
+    const subs = ctx.subscribers || [];
+    if (subs.length) {
+      console.log('  subscribing accounts: ' + subs.map((s) =>
+        s.accountId + (s.accountName ? ' (' + s.accountName + ')' : '')).join(', '));
+    } else {
+      console.log('  subscribing accounts: none yet — subscribe an account\'s relationship edge to this branch');
+    }
+  }
+  console.log('');
+}
+
 function printClearSummary(response, flags) {
   console.log('Cleared keys:', response.clearedCount || 0);
   console.log('Remaining staged count:', response.remainingCount || 0);
@@ -1827,6 +1861,8 @@ async function syncComponentsCommand(flags) {
   const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
   const branchName = flags.branch || currentBranch(cwd);
   const dataMode = resolveDataMode(flags, session);
+  const forceTombstones = flagEnabled(flags['force-tombstones']) || flagEnabled(flags.forceTombstones);
+  const dryRun = flagEnabled(flags['dry-run']) || flagEnabled(flags.dryRun);
   const api = buildAxios(baseUrl, session.token);
 
   const response = await loggedPost(api, cwd, '/cli/components', {
@@ -1834,6 +1870,8 @@ async function syncComponentsCommand(flags) {
     accountId,
     branchName,
     dataMode,
+    forceTombstones,
+    dryRun,
     mode: 'sync',
     components: []
   }).then((r) => r.data);
@@ -1851,10 +1889,174 @@ async function syncComponentsCommand(flags) {
   printResolvedBaseUrl(baseUrl);
   console.log('Data mode:', response.dataMode || dataMode);
   console.log('Mode:', response.mode || 'sync');
+  if (response.sync && response.sync.dryRun) {
+    console.log('Dry run: no variants were written and staging was not cleared.');
+  }
   console.log('Components sync:', JSON.stringify(response, null, 2));
   return response;
 }
 
+// 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.
+async function branchesComponentsCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const sessionContext = resolveSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const api = buildAxios(baseUrl, session.token);
+
+  // `components branch <name>` and `components branches` share this handler; the positional argument
+  // after the subcommand is the branch name when present.
+  const positional = flags._ && flags._[2];
+  const branchName = flags.branch || positional;
+
+  // Without a branch there is nothing to detail, so always list. With one, the mutating flags
+  // (--subscribe/--unsubscribe/--retire) win, then the narrower read views, and the default is the
+  // branch's full status.
+  let mode = 'list';
+  if (branchName || flags.unsubscribe !== undefined) {
+    if (flags.subscribe !== undefined) mode = 'subscribe';
+    else if (flags.unsubscribe !== undefined) mode = 'unsubscribe';
+    else if (flagEnabled(flags.retire)) mode = 'retire';
+    else if (flags.diff !== undefined) mode = 'diff';
+    else if (flagEnabled(flags.subscribers)) mode = 'subscribers';
+    else mode = 'status';
+  }
+
+  // `--diff 42` carries the component id inline; a bare `--diff` falls back to --component-id/--name.
+  const componentId = mode === 'diff'
+    ? (flags.diff === true ? (flags['component-id'] || flags.id) : flags.diff)
+    : undefined;
+
+  // `--subscribe 101` / `--unsubscribe 101` name the account whose relationship edge carries (or drops)
+  // the branch subscription. Subscribing is what makes a branch actually reachable in production.
+  const subscribeAccountId = (mode === 'subscribe' || mode === 'unsubscribe')
+    ? ((mode === 'subscribe' ? flags.subscribe : flags.unsubscribe) === true
+        ? (flags['subscribe-account'] || flags['account-id'])
+        : (mode === 'subscribe' ? flags.subscribe : flags.unsubscribe))
+    : undefined;
+
+  const response = await loggedPost(api, cwd, '/cli/branches', {
+    token: session.token,
+    accountId,
+    mode,
+    branchName,
+    componentType: flags['component-type'] || flags.type,
+    componentId,
+    componentName: flags['component-name'] || flags.name,
+    subscribeAccountId,
+    parentAccountId: flags['parent-account'],
+    // Optional branch-scoped custom host set on the same edge as the subscription.
+    // `--domain none` clears it; omitting the flag leaves any existing host untouched.
+    domainName: flags.domain || flags['domain-name'],
+    force: flagEnabled(flags.force)
+  }).then((r) => r.data);
+
+  if (!response.success) {
+    throw new Error(response.message || 'Branch lookup failed');
+  }
+
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(response, null, 2));
+    return response;
+  }
+
+  printSessionResolutionWarning(sessionContext);
+  printResolvedBaseUrl(baseUrl);
+  printBranchesSummary(response);
+  return response;
+}
+
+function printBranchesSummary(response) {
+  console.log('Trunk branch:', response.trunk || 'main');
+
+  if (response.mode === 'list') {
+    const branches = response.branches || [];
+    if (!branches.length) {
+      console.log('No component variant branches for this account.');
+      return;
+    }
+    console.log('');
+    branches.forEach((b) => {
+      const drift = b.drifted ? '  DRIFTED: ' + b.drifted : '';
+      console.log('  ' + b.branch +
+        '  (overridden ' + b.overridden + ', added ' + b.added + ', removed ' + b.removed +
+        ', subscribers ' + b.subscribers + ')' + drift);
+    });
+    console.log('');
+    console.log('Detail: remits-cli components branch <name>');
+    return;
+  }
+
+  if (response.mode === 'status') {
+    console.log('Branch:', response.branch);
+    const show = (label, rows) => {
+      if (!rows || !rows.length) return;
+      console.log('');
+      console.log(label + ' (' + rows.length + '):');
+      rows.forEach((r) => {
+        const drift = r.drifted ? '   <- DRIFTED (origin changed since this variant was cut)' : '';
+        console.log('  ' + r.kind + ' ' + (r.id != null ? r.id : 'new') + ' ' + r.name + drift);
+      });
+    };
+    show('Overridden', response.overridden);
+    show('Added', response.added);
+    show('Removed', response.removed);
+
+    if (response.driftedCount) {
+      console.log('');
+      console.log(response.driftedCount + ' variant(s) drifted. Compare with: remits-cli components branch ' +
+        response.branch + ' --diff <componentId> --component-type <kind>');
+    }
+    const subs = response.subscribers || [];
+    console.log('');
+    console.log('Subscribers (' + subs.length + '):');
+    subs.forEach((s) => {
+      console.log('  account ' + s.accountId + (s.accountName ? ' (' + s.accountName + ')' : '') +
+        ' via ' + (s.viaPrimaryEdge ? 'primary' : 'membership') + ' edge -> parent ' + s.parentAccountId +
+        (s.domainName ? '  [host ' + s.domainName + ']' : ''));
+    });
+    return;
+  }
+
+  if (response.mode === 'diff') {
+    console.log('Branch:', response.branch);
+    console.log(response.kind + ' ' + (response.componentId != null ? response.componentId : 'new') + ' ' + response.componentName);
+    if (response.branchOnly) console.log('(branch-only component: no trunk row)');
+    if (response.tombstone) console.log('(tombstone: this branch REMOVES the component)');
+    if (response.drifted) console.log('DRIFTED: the origin component changed after this variant was cut.');
+    const fields = response.fields || {};
+    Object.keys(fields).forEach((key) => {
+      const f = fields[key];
+      console.log('');
+      console.log('--- ' + key + (f.changed ? ' (changed)' : ' (same as trunk)') + ' ---');
+      if (f.changed) {
+        console.log('  variant length: ' + (f.variant ? f.variant.length : 0) +
+          ', trunk length: ' + (f.trunk ? f.trunk.length : 0));
+      }
+    });
+    console.log('');
+    console.log('Full content: re-run with --json');
+    return;
+  }
+
+  if (response.mode === 'subscribe' || response.mode === 'unsubscribe' || response.mode === 'retire') {
+    console.log(response.message);
+    return;
+  }
+
+  console.log('Branch:', response.branch);
+  const subs = response.subscribers || [];
+  console.log('Subscribers (' + subs.length + '):');
+  subs.forEach((s) => {
+    console.log('  account ' + s.accountId + (s.accountName ? ' (' + s.accountName + ')' : '') +
+      ' via ' + (s.viaPrimaryEdge ? 'primary' : 'membership') + ' edge -> parent ' + s.parentAccountId +
+      (s.domainName ? '  [host ' + s.domainName + ']' : ''));
+  });
+}
+
 async function commitComponentsCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
@@ -1863,6 +2065,9 @@ async function commitComponentsCommand(flags) {
   const commitMessage = String(flags.message || ('remits-cli commit sync ' + new Date().toISOString()));
   const allowEmpty = flags['allow-empty'] === true || flags['allow-empty'] === 'true';
   const skipGit = flags['skip-git'] === true || flags['skip-git'] === 'true';
+  if (flagEnabled(flags['dry-run']) || flagEnabled(flags.dryRun)) {
+    throw new Error('components commit does not support --dry-run because it performs local git writes. Use `remits-cli components sync --dry-run`.');
+  }
 
   if (!skipGit) {
     console.log('Phase 1/3: local git commit/push');
@@ -2038,9 +2243,17 @@ async function testCommand(flags) {
   const names = flags.names ? String(flags.names).split(',').map((s) => s.trim()).filter(Boolean) : [];
 
   const api = buildAxios(baseUrl, session.token);
+  // --as-account runs the Test AS a (descendant) subscriber account, so that account's relationship
+  // edge selects the component branch and the run resolves what production will.
+  const asAccountId = flags['as-account'] || flags['as-account-id'];
+  // --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'];
   const start = await loggedPost(api, cwd, '/cli/test', {
     token: session.token,
     accountId,
+    asAccountId,
+    variantBranch,
     branchName,
     dataMode,
     testId: /^\d+$/.test(String(testRef)) ? Number(testRef) : undefined,
@@ -2091,9 +2304,15 @@ async function tokenCommand(flags) {
   const dataMode = resolveDataMode(flags, session);
 
   const api = buildAxios(baseUrl, session.token);
+  // --as-account mints the token for a (descendant) subscriber so browser verification of an
+  // Embeddable resolves that account's branch variants rather than the owner's trunk.
+  // --variant-branch explicitly probes a committed variant branch before any edge subscribes.
+  const variantBranch = flags['variant-branch'];
   const data = await loggedPost(api, cwd, '/cli/token', {
     token: session.token,
     accountId,
+    asAccountId: flags['as-account'] || flags['as-account-id'],
+    variantBranch,
     branchName,
     dataMode
   }).then((r) => r.data);
@@ -2104,9 +2323,13 @@ async function tokenCommand(flags) {
 
   const base = baseUrl.replace(/\/$/, '');
   const embeddablePath = flags.path || flags['embeddable-path'];
-  const embeddableUrl = embeddablePath
+  let embeddableUrl = embeddablePath
     ? (base + '/s/' + data.tokenKey + '/' + String(embeddablePath).replace(/^\/+/, ''))
     : null;
+  if (embeddableUrl && data.variantBranch) {
+    const separator = embeddableUrl.includes('?') ? '&' : '?';
+    embeddableUrl += separator + 'variantBranch=' + encodeURIComponent(data.variantBranch);
+  }
 
   const output = {
     success: true,
@@ -2114,6 +2337,7 @@ async function tokenCommand(flags) {
     tokenKey: data.tokenKey,
     accountId: data.accountId,
     branchName: data.branchName,
+    variantBranch: data.variantBranch,
     dataMode: data.dataMode || dataMode,
     shortBasePath: data.shortBasePath,
     embeddableUrl
@@ -2131,11 +2355,13 @@ async function toolsCommand(flags) {
   const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
   const branchName = flags.branch || currentBranch(cwd);
   const dataMode = resolveDataMode(flags, session);
+  const variantBranch = flags['variant-branch'];
   const api = buildAxios(baseUrl, session.token);
 
   const data = await loggedPost(api, cwd, '/cli/tools', {
     token: session.token,
     accountId,
+    variantBranch,
     branchName,
     dataMode
   }).then((r) => r.data);
@@ -2148,6 +2374,7 @@ async function toolsCommand(flags) {
     accountId,
     baseUrl: normalizeBaseUrl(baseUrl),
     branchName,
+    variantBranch: data.variantBranch || variantBranch,
     dataMode: data.dataMode || dataMode,
     fetchedAt: new Date().toISOString(),
     tools: data.tools || []
@@ -2157,6 +2384,7 @@ async function toolsCommand(flags) {
   printResolvedBaseUrl(baseUrl);
   console.log('Tools refreshed.');
   console.log('Data mode:', data.dataMode || dataMode);
+  if (data.variantBranch || variantBranch) console.log('Variant branch:', data.variantBranch || variantBranch);
   console.log('Tools file:', toolsFile);
   console.log('Tool count:', (data.tools || []).length);
 }
@@ -2194,6 +2422,7 @@ async function toolCommand(flags) {
   const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
   const branchName = flags.branch || currentBranch(cwd);
   const dataMode = resolveDataMode(flags, session);
+  const variantBranch = flags['variant-branch'];
   const timeoutMs = parsePositiveInt(flags['timeout-ms'] || flags.timeoutMs, 60000);
   const callId = String(flags['call-id'] || flags.callId || crypto.randomUUID());
   const asyncMode = flagEnabled(flags.async) || flagEnabled(input.async);
@@ -2243,6 +2472,7 @@ async function toolCommand(flags) {
     accountIdExplicit,
     branchName,
     dataMode,
+    variantBranch,
     name: String(toolName),
     input,
     callId,
@@ -2259,6 +2489,7 @@ async function toolCommand(flags) {
   console.log(asyncMode ? 'Tool call started.' : 'Tool call succeeded.');
   console.log('Call ID:', callId);
   console.log('Data mode:', data.dataMode || dataMode);
+  if (data.variantBranch || variantBranch) console.log('Variant branch:', data.variantBranch || variantBranch);
   if (data.status) console.log('Status:', data.status);
   if (data.threadGroupingId) console.log('Thread grouping ID:', data.threadGroupingId);
   // Make the resolved component version explicit so callers never assume staged vs DB.
@@ -4731,26 +4962,50 @@ async function main() {
     console.log('  remits-cli listen [stop|status] [--foreground true]  # compatibility alias');
     console.log('  remits-cli data-mode [set test|prod]');
     console.log('  remits-cli install --skills [--target codex|claude|gemini|all] [--overwrite true]');
-    console.log('  remits-cli tools [--base-url URL] [--account-id ID] [--data-mode test|prod]');
-    console.log('  remits-cli tool --name <toolName> [--base-url URL] [--input \"{...}\"|--input-file file.json] [--data-mode test|prod] [--timeout-ms 60000] [--async true --wait true]');
+    console.log('  remits-cli tools [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod] [--variant-branch NAME|none]');
+    console.log('  remits-cli tool --name <toolName> [--base-url URL] [--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('  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]');
-    console.log('  remits-cli components commit [--message \"msg\"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod]');
-    console.log('  remits-cli test run --test <id|name> [--base-url URL] [--names name1,name2] [--watch true|false] [--data-mode test|prod]');
-    console.log('  remits-cli token [--base-url URL] [--branch BRANCH] [--path embeddable/path] [--data-mode test|prod]');
+    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('  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]');
+    console.log('  remits-cli components branch <name> --subscribe <accountId>      # make an account resolve this branch');
+    console.log('  remits-cli components branch <name> --unsubscribe <accountId>    # return that account to trunk');
+    console.log('  remits-cli components branch <name> --retire [--force]           # delete the branch\'s overlays');
+    console.log('  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]');
+    console.log('  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('  --as-account <ID> verifies AS a descendant subscriber account, so its relationship edge');
+    console.log('  selects the component branch and the run resolves exactly what production will.');
+    console.log('  --variant-branch <NAME> explicitly probes a committed variant branch (e.g. before any');
+    console.log('  edge subscribes to it). Omit it to resolve what the account actually subscribes to.');
     process.exit(0);
   }
 
   if (command === 'components' && wantsHelp) {
-    console.log('Usage: remits-cli components <stage|status|clear|sync|commit>');
+    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]');
-    console.log('  remits-cli components commit [--message \"msg\"] [--allow-empty true|false] [--skip-git true|false] [--branch BRANCH] [--data-mode test|prod]');
+    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]');
     process.exit(0);
   }
 
@@ -4787,6 +5042,11 @@ async function main() {
     return;
   }
 
+  if (command === 'components' && (subcommand === 'branches' || subcommand === 'branch')) {
+    await branchesComponentsCommand(args);
+    return;
+  }
+
   if (command === 'data-mode' || command === 'datamode' || command === 'data-model' || command === 'datamodel') {
     await dataModeCommand(args, subcommand);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.85",
+  "version": "0.1.87",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,
@@ -28,7 +28,8 @@
     "automation"
   ],
   "scripts": {
-    "start": "node index.js"
+    "start": "node index.js",
+    "test": "node --test test/*.test.js"
   },
   "dependencies": {
     "@stomp/stompjs": "^7.2.0",