@remits/remits-cli 0.1.103 → 0.1.104

package/README.md

@@ -33,7 +33,7 @@ remits-cli components sync
 remits-cli components sync --branch feature_branch --dry-run
 remits-cli components sync --branch feature_branch --dry-run --summary
 remits-cli components sync --branch feature_branch --force-tombstones
-remits-cli token --path page/my-embeddable
+remits-cli token --path page/my-embeddable    # returns tokenKey/embeddableUrl, plus embedTokenKey/embedSnippet for host embeds
 remits-cli token --path page/my-embeddable --variant-branch feature_branch
 remits-cli token inspect --token https://example.test/s/<tokenKey>/page/my-embeddable
 remits-cli tool --name mcp_account_user_admin --data-mode prod --input '{"action":"account_create","parentAccountId":4,"name":"Freto","type":"PRODUCT","dryRun":true}'

package/index.js

@@ -1386,7 +1386,15 @@ function collectComponents(cwd) {
       const key = type + ':' + (id ? 'id:' + id : 'name:' + name.toLowerCase());
 
       if (!byKey.has(key)) {
-        byKey.set(key, { type, id, name });
+        // `metadataAuthoritative` tells the server this payload was assembled from the repo, so the
+        // .meta.yml it carries is the COMPLETE metadata for the component. The server then removes
+        // staged metadata keys the sidecar no longer declares, instead of carrying them forever —
+        // without it, deleting a key from a sidecar and re-staging left the old value staged, so
+        // "restore the file and re-stage" did not restore the staged state.
+        //
+        // A partial stage (mcp_component_edit writing one field) deliberately does NOT set this and
+        // keeps the merge semantics it needs.
+        byKey.set(key, { type, id, name, metadataAuthoritative: true });
       }
       const component = byKey.get(key);
       const filePath = path.join(dir, fileName);
@@ -2342,19 +2350,97 @@ async function syncComponentsCommand(flags) {
   }
   if (namesOnly) {
     printSyncNames(response);
+    printPromotionSignals(response);
     failOnSyncGate(gate);
     return response;
   }
   if (flagEnabled(flags.summary)) {
     console.log('Components sync summary:', JSON.stringify(summary, null, 2));
+    printPromotionSignals(response);
     failOnSyncGate(gate);
     return response;
   }
   console.log('Components sync:', JSON.stringify(response, null, 2));
+  printPromotionSignals(response);
   failOnSyncGate(gate);
   return response;
 }
 
+// A sync is a step in a longer loop, and the steps after it are the ones that get skipped — so print what
+// the server just observed about this branch's relationship to trunk, not only what it wrote.
+function printPromotionSignals(response) {
+  const sync = (response && response.sync) || {};
+
+  const cmp = sync.branchComparison;
+  if (cmp && cmp.comparable) {
+    console.log('');
+    console.log('Branch vs trunk "' + cmp.trunkBranch + '": ' + cmp.aheadBy + ' ahead, ' + cmp.behindBy +
+      ' behind  [phase ' + cmp.phase + ']');
+    if (cmp.phase === 'diverged') {
+      console.log('  This branch has not merged trunk in. Its overlays assert its OLD copy of everything');
+      console.log('  trunk has changed since, and its subscribers are running that copy right now.');
+      console.log('  Fix: git merge ' + cmp.trunkBranch + ' into this branch, push, then sync again.');
+    } else if (cmp.phase === 'awaiting-merge-back') {
+      console.log('  Every commit here is already in trunk and trunk has moved on — a promotion merge-back');
+      console.log('  is outstanding. Until it happens the subscribers stay pinned to the pre-promotion copy.');
+      console.log('  Fix: git merge ' + cmp.trunkBranch + ' into this branch, push, then sync again.');
+    }
+    if (cmp.deletionEvidence !== 'complete') {
+      console.log('  NOTE: deletion evidence is ' + cmp.deletionEvidence + ', so removals fall back to the');
+      console.log('  conservative ratio guard rather than git\'s own answer.');
+    }
+  } else if (cmp) {
+    console.log('');
+    console.log('Branch vs trunk: UNAVAILABLE' + (cmp.message ? ' (' + cmp.message + ')' : ''));
+  }
+
+  const promotion = sync.promotion;
+  if (promotion) {
+    (promotion.tags || []).forEach((t) => {
+      console.log('');
+      console.log('Tagged promotion: ' + t.tag + ' -> ' + short(t.sha) + ' (' + t.ref + ')');
+    });
+    // Older servers sent bare branch names; newer ones send {branch, overlayCount}. Normalize, because the
+    // count decides whether this is an alarm or a tidy-up and the difference must not be guessed.
+    const pending = (promotion.pendingMergeBack || []).map((entry) =>
+      (typeof entry === 'string' ? { branch: entry, overlayCount: -1 } : entry));
+    if (pending.length) {
+      const shadowing = pending.filter((p) => p.overlayCount > 0);
+      const unknown = pending.filter((p) => !(p.overlayCount >= 0));
+      console.log('');
+      if (shadowing.length) {
+        console.log('THE PROMOTION IS NOT FINISHED. Trunk is synced, but ' + shadowing.length +
+          ' variant branch(es) still SHADOW it — their subscribers resolve the PRE-promotion code:');
+      } else if (unknown.length) {
+        // The overlay count could not be read, so say nothing about what is shadowed. "Nothing is
+        // shadowed" would be a claim, and an unverifiable one is the failure this whole change is about.
+        console.log('THE PROMOTION IS NOT FINISHED. Trunk is synced, but ' + pending.length +
+          ' variant branch(es) are behind it and owe a merge-back:');
+      } else {
+        console.log('Merge-back outstanding on ' + pending.length + ' variant branch(es). Nothing is shadowed' +
+          ' (no overlays stored), but the branch is behind trunk until you merge it back:');
+      }
+      pending.forEach((p) => {
+        const detail = p.overlayCount > 0 ? '  (' + p.overlayCount + ' overlay(s) shadowing trunk)'
+          : p.overlayCount === 0 ? '  (0 overlays — converged, just behind)' : '';
+        console.log('  ' + p.branch + ':' + detail);
+        console.log('    git checkout ' + p.branch + ' && git merge ' + (sync.branchName || 'main') + ' && git push');
+        console.log('    remits-cli components sync --branch ' + p.branch);
+      });
+      console.log('  Verify with: remits-cli components promotion --branch <name>');
+    }
+  }
+
+  (sync.advisories || []).forEach((advisory) => {
+    console.log('');
+    console.log('ADVISORY [' + advisory.code + ']: ' + advisory.message);
+    (advisory.findings || []).slice(0, 15).forEach((f) => {
+      console.log('  ' + f.path + ':' + f.line + '  ' + f.call);
+    });
+    if (advisory.truncated) console.log('  ... (list truncated; re-run with --json for the rest)');
+  });
+}
+
 function syncPreflightRequested(flags) {
   return Boolean(
     flagEnabled(flags['names-only']) ||
@@ -2482,9 +2568,41 @@ function failOnSyncGate(gate) {
 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 : [];
+
+  // A TRUNK sync and a VARIANT sync report in different vocabularies, and this summary only ever spoke
+  // variant. So the single most consequential line of a promotion — "component X was CREATED on trunk as
+  // id N" — printed as `added: 0`, and the runbook's definition of done ("components created, with their
+  // new ids") could not be satisfied from the summary it tells you to read.
+  if ((sync.mode || 'trunk') === 'trunk') {
+    const created = Array.isArray(results.created) ? results.created : [];
+    const updated = Array.isArray(results.updated) ? results.updated : [];
+    const renamed = Array.isArray(results.renamed) ? results.renamed : [];
+    const deleted = Array.isArray(results.deleted) ? results.deleted : [];
+    const trunkWarnings = [];
+    if (deleted.length) trunkWarnings.push(String(deleted.length) + ' live component(s) DELETED');
+    if (errors.length) trunkWarnings.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: 'trunk',
+      dryRun: false,
+      // Ids are the part that cannot be recovered later: a promotion mints them once, and anything that
+      // recorded the old identity will not line up if they are re-minted.
+      created: created.map((e) => ({ type: e.type, name: e.name, id: e.newId != null ? e.newId : e.id })),
+      updated: updated.length,
+      renamed: renamed.length,
+      deleted: deleted.map((e) => ({ type: e.type, name: e.name, id: e.id })),
+      skipped: skipped.length,
+      errors: errors.length,
+      errorDetails: errors.map((entry) => ({ type: entry.type, id: entry.id, error: entry.error })),
+      warnings: trunkWarnings
+    };
+  }
+
+  const removed = Array.isArray(results.removed) ? results.removed : [];
   const added = Array.isArray(results.added) ? results.added : [];
   const overridden = Array.isArray(results.overridden) ? results.overridden : [];
   const unchanged = Array.isArray(results.unchanged) ? results.unchanged : [];
@@ -2573,6 +2691,8 @@ async function branchesComponentsCommand(flags) {
     // 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'],
+    dryRun: flagEnabled(flags['dry-run']) || flagEnabled(flags.dryRun),
+    confirmPrimaryEdge: flagEnabled(flags['confirm-primary-edge']) || flagEnabled(flags.confirmPrimaryEdge),
     force: flagEnabled(flags.force)
   }).then((r) => r.data);
 
@@ -2606,9 +2726,13 @@ function printBranchesSummary(response) {
       console.log('  ' + b.branch +
         '  (overridden ' + b.overridden + ', added ' + b.added + ', removed ' + b.removed +
         ', subscribers ' + b.subscribers + ')' + drift);
+      // Name the commit these counts describe. Without it a three-day-old inventory reads exactly like a
+      // current one, which is how a promotion gets reviewed against the wrong tree.
+      console.log('      computed from ' + short(b.syncedSha) + (b.updated ? ' at ' + b.updated : ''));
     });
     console.log('');
-    console.log('Detail: remits-cli components branch <name>');
+    console.log('Detail:    remits-cli components branch <name>');
+    console.log('Promotion: remits-cli components promotion --branch <name>   # is that commit still the branch HEAD?');
     return;
   }
 
@@ -2666,6 +2790,12 @@ function printBranchesSummary(response) {
 
   if (response.mode === 'subscribe' || response.mode === 'unsubscribe' || response.mode === 'retire') {
     console.log(response.message);
+    if (response.requiresConfirmation) {
+      console.log('Confirmation required: re-run with --confirm-primary-edge if that structural edge should subscribe.');
+    }
+    if (response.edge) {
+      console.log('Edge: ' + response.edge.edgeType + ' -> parent ' + response.edge.parentAccountId);
+    }
     return;
   }
 
@@ -2679,6 +2809,167 @@ function printBranchesSummary(response) {
   });
 }
 
+// The promotion "lay of the land": where this branch sits relative to trunk, whether the platform's
+// stored overlays actually describe the branch's current HEAD, who is affected, and the ordered commands
+// for the next step. Every fact here was already obtainable one command at a time; the point is that a
+// promotion goes wrong by assembling a wrong picture out of individually true answers, so this assembles
+// the picture once, server-side, from the REMOTE (which is what the platform syncs from — not your
+// working tree).
+async function promotionComponentsCommand(flags) {
+  const cwd = process.cwd();
+  ensureLocalState(cwd);
+  const sessionContext = resolvePromotionSessionContext(cwd, flags);
+  const { session, accountId } = sessionContext;
+  const baseUrl = flags['base-url'] || session.baseUrl || DEFAULT_BASE_URL;
+  const api = buildAxios(baseUrl, session.token);
+
+  const positional = flags._ && flags._[2];
+  const branchName = flags.branch || positional || currentBranch(cwd);
+
+  const response = await loggedPost(api, cwd, '/cli/branches', {
+    token: session.token,
+    accountId,
+    mode: 'promotion',
+    branchName
+  }).then((r) => r.data);
+
+  if (!response.success) {
+    throw new Error(response.message || 'Promotion status failed');
+  }
+
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(response, null, 2));
+  } else {
+    printSessionResolutionWarning(sessionContext);
+    printResolvedBaseUrl(baseUrl);
+    // Say this out loud: the command is named for the operation it reports on, and an agent that reads
+    // "promotion" as "promoted" would skip the git steps this output is telling it to run.
+    console.log('This REPORTS promotion readiness. It performs no git operation and writes nothing.');
+    if (Array.isArray(response.branches)) {
+      response.branches.forEach((entry) => printPromotionStatus(entry, response));
+    } else {
+      printPromotionStatus(response, response);
+    }
+  }
+
+  // Fail closed by default. This command exists to be the gate an agent runs BEFORE touching git, and a
+  // gate that always exits 0 is a suggestion. `--no-fail` is for a human who only wants to look.
+  const blockers = collectPromotionBlockers(response);
+  if (blockers.length && !flagEnabled(flags['no-fail'])) {
+    throw new Error('promotion is blocked (' + blockers.length + '):\n  ' +
+      blockers.map((b) => b.code + ': ' + b.message).join('\n  ') +
+      '\nRe-run with --no-fail to inspect without failing.');
+  }
+  return response;
+}
+
+// A promotion is normally driven from the BRANCH's checkout, and on a single-subscriber branch that
+// checkout's account-info.json describes the SUBSCRIBER — so the CLI resolves the subscriber's account id
+// and demands a session for it, which an owner-side agent has no reason to hold. Every other branch
+// command has the same shape and tells you to pass `--account-id <ownerId>`; this one should not need to
+// be told, because it is READ-ONLY and the server already resolves the branch owner itself.
+//
+// So: if there is no session for the local account, and the checkout names its component owner, retry as
+// the owner. Deliberately scoped to this command — `sync`/`commit` mutate, and there the account the CLI
+// acts as is a decision, not a detail.
+function resolvePromotionSessionContext(cwd, flags) {
+  try {
+    return resolveSessionContext(cwd, flags);
+  } catch (err) {
+    if (flags && flags['account-id']) throw err;
+    let ownerId = null;
+    try {
+      const info = JSON.parse(fs.readFileSync(path.join(cwd, 'account-info.json'), 'utf8'));
+      const resolution = (info && info.resolution) || {};
+      const localId = Number(accountIdFromAccountInfo(info));
+      const candidate = Number(resolution.componentOwnerAccountId);
+      if (Number.isFinite(candidate) && candidate > 0 && candidate !== localId) ownerId = candidate;
+    } catch (_) { /* not an account repo, or no owner recorded */ }
+    if (!ownerId) throw err;
+
+    const ownerContext = resolveSessionContext(cwd, Object.assign({}, flags, { 'account-id': ownerId }));
+    console.log('Note: no session for this checkout\'s account; reporting as its component OWNER, account ' +
+      ownerId + '. Branch overlays belong to the owner, so this is the account that can answer.');
+    return ownerContext;
+  }
+}
+
+function collectPromotionBlockers(response) {
+  if (Array.isArray(response.branches)) {
+    return response.branches.reduce((all, entry) => all.concat(entry.blockers || []), []);
+  }
+  return response.blockers || [];
+}
+
+function printPromotionStatus(entry, envelope) {
+  const git = entry.git || {};
+  const platform = entry.platform || {};
+  console.log('');
+  console.log('Branch:      ' + entry.branch + '   (trunk "' + (entry.trunkBranch || envelope.trunk) + '")');
+  console.log('Owner:       account ' + entry.ownerAccountId + (entry.ownerAccountName ? ' (' + entry.ownerAccountName + ')' : '') +
+    '   repo ' + (entry.repository || '?'));
+  console.log('Phase:       ' + String(entry.phase || 'unknown').toUpperCase());
+  if (entry.summary) console.log('             ' + entry.summary);
+
+  console.log('');
+  console.log('  git (remote):');
+  if (git.comparable) {
+    console.log('    ahead of trunk:  ' + git.aheadBy + ' commit(s)   [work not yet promoted]');
+    console.log('    behind trunk:    ' + git.behindBy + ' commit(s)   [trunk this branch has not merged in]');
+    console.log('    merge base:      ' + short(git.mergeBaseSha));
+    console.log('    branch HEAD:     ' + short(git.branchHeadSha));
+    console.log('    trunk HEAD:      ' + short(git.trunkHeadSha));
+    const deletions = git.deliberateDeletions || [];
+    console.log('    deliberate component deletions on this branch: ' + deletions.length +
+      (git.deletionEvidence === 'complete' ? '' : '   (evidence ' + git.deletionEvidence + ')'));
+    deletions.slice(0, 20).forEach((p) => console.log('      D ' + p));
+  } else {
+    console.log('    UNAVAILABLE' + (git.message ? ': ' + git.message : ''));
+  }
+
+  console.log('');
+  console.log('  platform (what subscribers resolve right now):');
+  console.log('    overridden ' + platform.overridden + ', branch-only ' + platform.added +
+    ', tombstoned ' + platform.removed + ', drifted ' + platform.drifted);
+  // Freshness is decided server-side (BranchPromotion.freshnessOf) because sparseness compares BOTH sides
+  // and there are two independent ways to go stale. Re-deriving that here from separate booleans would be
+  // a second copy of one rule.
+  const FRESHNESS_LABELS = {
+    'current': '   [current]',
+    'stale-branch-moved': '   [STALE — does not match the branch HEAD]',
+    'stale-trunk-moved': '   [STALE — matches the branch HEAD, but trunk has moved since]'
+  };
+  console.log('    overlays computed from: ' + short(platform.syncedSha) +
+    (FRESHNESS_LABELS[platform.freshness] || '   [unknown]'));
+  (platform.subscribers || []).forEach((s) => {
+    console.log('    subscriber: account ' + s.accountId + (s.accountName ? ' (' + s.accountName + ')' : '') +
+      (s.domainName ? '  [host ' + s.domainName + ']' : ''));
+  });
+
+  const blockers = entry.blockers || [];
+  if (blockers.length) {
+    console.log('');
+    console.log('  BLOCKERS (' + blockers.length + '):');
+    blockers.forEach((b) => {
+      console.log('    * ' + b.code);
+      console.log('      ' + b.message);
+      console.log('      fix: ' + b.fix);
+    });
+  }
+
+  const steps = entry.nextSteps || [];
+  if (steps.length) {
+    console.log('');
+    console.log('  NEXT, IN ORDER:');
+    steps.forEach((s, i) => console.log('    ' + (i + 1) + '. ' + s));
+  }
+  console.log('');
+}
+
+function short(sha) {
+  return sha ? String(sha).slice(0, 8) : 'unknown';
+}
+
 async function commitComponentsCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
@@ -2945,13 +3236,18 @@ async function tokenCommand(flags) {
   // 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'];
+  // Send the path so the server can also mint the EMBEDDABLE-SCOPED token key. `tokenKey` opens a
+  // tokenized URL in a browser; `embedTokenKey` lets the `<script>` embed loader resolve the component
+  // from persisted token context because the loader request sends no path.
+  const requestedPath = flags.path || flags['embeddable-path'];
   const data = await loggedPost(api, cwd, '/cli/token', {
     token: session.token,
     accountId,
     asAccountId: flags['as-account'] || flags['as-account-id'],
     variantBranch,
     branchName,
-    dataMode
+    dataMode,
+    path: requestedPath
   }).then((r) => r.data);
 
   if (!data.success) {
@@ -2959,7 +3255,7 @@ async function tokenCommand(flags) {
   }
 
   const base = baseUrl.replace(/\/$/, '');
-  const embeddablePath = flags.path || flags['embeddable-path'];
+  const embeddablePath = requestedPath;
   let embeddableUrl = embeddablePath
     ? (base + '/s/' + data.tokenKey + '/' + String(embeddablePath).replace(/^\/+/, ''))
     : null;
@@ -2980,6 +3276,26 @@ async function tokenCommand(flags) {
     embeddableUrl
   };
 
+  // What the token will RESOLVE AS. `accountId` says which account it executes as; on a hierarchy the
+  // decisive facts are which component branch applies, whose components those are, and which storage
+  // namespace the page reads — none of which are inferable from the id. Present only when the server
+  // could resolve it.
+  if (data.resolution) {
+    output.resolution = data.resolution;
+  }
+
+  // Present only when the path resolved to an Embeddable. `embedTokenKey` is what a host site pastes
+  // into the loader snippet; the render shape is echoed because it decides what that host receives.
+  if (data.embedTokenKey) {
+    output.embeddableId = data.embeddableId;
+    output.embeddableName = data.embeddableName;
+    output.injectionType = data.injectionType;
+    output.renderMode = data.renderMode;
+    output.headMode = data.headMode;
+    output.embedTokenKey = data.embedTokenKey;
+    output.embedSnippet = data.embedSnippet;
+  }
+
   printSessionResolutionWarning(sessionContext);
   console.log(JSON.stringify(output, null, 2));
 }
@@ -5634,6 +5950,23 @@ function autoUpdateIfNeeded(originalArgv, options = {}) {
 }
 
 function printComponentsHelp(subcommand) {
+  if (subcommand === 'promotion' || subcommand === 'promote') {
+    console.log('Usage: remits-cli components promotion [<branch>] [--branch NAME] [--json] [--no-fail]');
+    console.log('');
+    console.log('Reports where a variant branch sits in the promotion loop and what to do next. It performs');
+    console.log('no git operation and writes nothing. Run it from either checkout — it resolves the branch');
+    console.log('OWNER, and it reads the REMOTE, which is what the platform actually syncs from.');
+    console.log('');
+    console.log('Phases:');
+    console.log('  converged            branch == trunk. Nothing to promote.');
+    console.log('  ready                branch is ahead of trunk and current with it -> promote.');
+    console.log('  diverged             branch is behind trunk. Merge trunk IN before reading any plan.');
+    console.log('  awaiting-merge-back  trunk absorbed this branch and moved on. Steps 4-5 are owed, and');
+    console.log('                       until they run the subscribers resolve the PRE-promotion code.');
+    console.log('');
+    console.log('Exits non-zero when there are blockers, so it can gate a runbook. --no-fail just looks.');
+    return;
+  }
   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('');
@@ -5679,7 +6012,7 @@ function printComponentsHelp(subcommand) {
     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('Usage: remits-cli components <stage|status|clear|sync|commit|promotion|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]');
@@ -5698,7 +6031,7 @@ function printComponentsHelp(subcommand) {
   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> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]');
   console.log('  remits-cli components branch <name> --unsubscribe <accountId>');
   console.log('  remits-cli components branch <name> --retire [--force]');
 }
@@ -5742,7 +6075,8 @@ 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('       remits-cli token inspect --token <token|tokenKey|URL> [--base-url URL] [--account-id ID]');
   console.log('');
-  console.log('Mints a branch-aware browser URL for embeddable verification.');
+  console.log('Mints a branch-aware tokenKey and browser URL for embeddable verification.');
+  console.log('When --path resolves to an Embeddable, output also includes embedTokenKey and embedSnippet for host-site embeds.');
   console.log('Inspect decodes a persisted Remits token and prints token metadata, recognized routing fields, safety/dataMode evidence, and full context.');
 }
 
@@ -5806,15 +6140,17 @@ async function main() {
     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('  remits-cli components promotion [<branch>] [--json] [--no-fail]  # promotion readiness + ordered next steps');
     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> --subscribe <accountId> [--dry-run] [--confirm-primary-edge]');
     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] [--branch stagingScope] [--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('  remits-cli token inspect --token <token|tokenKey|URL> [--base-url URL] [--account-id ID]');
     console.log('');
+    console.log('  token output uses tokenKey for browser URLs and embedTokenKey/embedSnippet for host-site embeds.');
     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');
@@ -5880,6 +6216,11 @@ async function main() {
     return;
   }
 
+  if (command === 'components' && (subcommand === 'promotion' || subcommand === 'promote')) {
+    await promotionComponentsCommand(args);
+    return;
+  }
+
   if (command === 'components' && (subcommand === 'branches' || subcommand === 'branch')) {
     await branchesComponentsCommand(args);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remits/remits-cli",
-  "version": "0.1.103",
+  "version": "0.1.104",
   "description": "Local CLI for auth, component sync, and live test execution against Remits",
   "license": "MIT",
   "private": false,

package/skills/remits-cli/SKILL.md

@@ -168,11 +168,10 @@ For access questions — "who can see this client account?", "why does this user
 
 **Test-data flags are first-class safety evidence.** `Account.testAccount` and `User.testUser` are set by
 the `account(...)` / `user(...)` factories when the execution data lane is `test` (which is how
-`mcp_account_user_admin` creates); prod-data creates leave them false. Two limits worth knowing: a record
-built some other way (`new Account(...).save()` inside a component) is only flagged during an **automated
-Test** in the test lane, so `testAccount:false` on something you created in test mode means it is a real
-account; and updating an existing real account/user in test mode does not convert it into test data,
-though its Firestore extension-field writes still go to the test lane. `Object.testMode` /
+`mcp_account_user_admin` creates); direct inserts such as `new Account(...).save()` are also flagged by the
+domain `beforeInsert` hook in the test lane. Prod-data creates leave them false. Updating an existing real
+account/user in test mode does not convert it into test data, though its Firestore extension-field writes
+still go to the test lane. `Object.testMode` /
 `Event.testMode` / `Alert.testMode` (and `testMode` inside test-lane Audit documents) identify lifecycle
 rows in the test data lane. Agent-facing surfaces expose these fields:
 
@@ -930,6 +929,25 @@ playwright-cli eval "() => document.querySelector('.total-amount').textContent"
 
 The `testMode` metadata confirms you're testing against staged changes, not production.
 
+**Two different token keys come back, for two different jobs.** When `--path` resolves to an
+Embeddable, the response carries an `embedTokenKey` and a paste-ready `embedSnippet` alongside the usual
+`tokenKey` / `embeddableUrl`:
+
+| Field | Use it for |
+|---|---|
+| `tokenKey` / `embeddableUrl` | Opening the page in a browser (Playwright, or clicking the link) |
+| `embedTokenKey` / `embedSnippet` | The `<script>` embed loader — verifying the page as a HOST SITE embeds it |
+
+They are not interchangeable. The loader's request carries **no path**, so it resolves the component
+purely from the embeddable-scoped token key's persisted context. The browser `tokenKey` names the account
+preview URL; `embedTokenKey` names the host-loader credential. The response also echoes `injectionType` /
+`renderMode` / `headMode`, which decide what a host actually receives
+(`guides/components/embeddable-components.md`).
+
+**This works for a `new_` component that has never been synced.** The embed token key carries the
+component NAME as well as its id, so a staged, id-less Embeddable is loader-addressable — you do not
+have to sync it, or borrow another component's id, just to verify a host embed.
+
 **Option C — Use investigation tools** (for backend/data changes):
 
 For changes to Readers, Actions, or Rules that process data rather than display UI, verify by examining the data they produce:
@@ -1179,6 +1197,12 @@ TestMode still uses the committed DB source. Staging remains a dev/verification
   branch/user scope. This is the normal edit/test loop.
 - `remits-cli components status` shows which branch/variant world the checkout resolves, plus staged entries,
   staged fields, aliases, hashes, and TTLs. Use `--json` or `--verbose` for the full staged-entry payload.
+- **A full `stage` makes the `.meta.yml` AUTHORITATIVE.** Staging layers a payload over what is already
+  staged, which is what lets `mcp_component_edit` write a single field without blanking the others. But a
+  `remits-cli components stage` sends the whole sidecar, so a key you DELETE from a sidecar is removed from
+  the staged entry rather than lingering — "restore the file and re-stage" restores the staged state, which
+  is the only mental model that is safe to have. Content fields still layer (they come from separate files),
+  so a partial stage is unaffected.
 - `remits-cli components clear` drops staged entries when you intentionally want to fall back to committed DB
   source. An empty staging scope is clean state, not a failure.
 - `remits-cli components sync` syncs the DB from the pushed git remote and then clears staged entries for the
@@ -1352,6 +1376,63 @@ remits-cli token --path embeddable/index/50 --as-account 101   # subscriber -> v
 remits-cli token --path embeddable/index/50                    # owner      -> trunk
 ```
 
+Each answer carries a **`resolution`** block for the account the token executes as — `role`,
+`componentBranch` and its owner, `resolvedDatabaseName`, `resolvedDomainName`, `scopeAccountId`, and a
+one-sentence `summary`. Read it before opening the URL: `accountId` alone does not say whether a branch
+overlay applies or which storage namespace the page will read, and those are exactly what
+`--as-account` is being used to change.
+
+Separate branch fields, because these questions answer differently and can disagree:
+
+| Field | Answers |
+|---|---|
+| `componentBranch` | what **this token** will resolve |
+| `componentBranchSource` | `probe` (an explicit `--variant-branch`), `subscription` (the account's edge), or `trunk` |
+| `subscribedComponentBranch` | what the **account graph** says, independent of this token |
+| `componentBranchAnchored` | whether **this resolution actually reached** that subscription |
+
+A single `componentBranch` field would have reported `trunk` under `--variant-branch X`, for a token that
+resolves `X`.
+
+**Subscribing to a branch and resolving through it are different facts.** An account subscribes on an
+edge; a *request* resolves through that edge only when something named the path (`--as-account`, the
+edge's own host, an explicit `--variant-branch`). An account with no `parentId` and several upward links
+resolves trunk by design — the resolver refuses to guess a path. So this is a normal, explainable state:
+
+```
+"componentBranch": null,              // this token resolves TRUNK
+"componentBranchSource": "trunk",
+"subscribedComponentBranch": "forked", // ...but the account does subscribe
+"componentBranchAnchored": false       // ...and nothing anchored this request to it
+```
+
+Reading `componentBranch` alone there tells you the account is on trunk, which is true — and leads you to
+conclude it has no branch, which is false. If several edges carry branches, none is picked for you:
+`subscribedComponentBranch` is `null` and `subscribedComponentBranches` lists them.
+
+Under a probe, `componentOwnerAccountId` is the **nearest account on the token's resolution path that owns
+variant rows for X** — not an edge lookup, which answers `null` for the ordinary case of a variant
+committed before anything subscribes to it. `null` means no account on that path owns rows for X, and what
+that implies depends on the account, so read `summary`:
+
+- **on trunk** — the page resolves what it would without the probe; the branch is not committed yet.
+- **resolving through a subscription** — the probe **suppresses** it. `variantBranch` outranks the
+  subscription before it is consulted, so the page resolves **trunk**, not the overlays that account
+  normally gets. Drop `--variant-branch` to see the subscription.
+- **subscribed but not anchored** — it was already resolving trunk before you probed. Dropping
+  `--variant-branch` will *not* by itself show you the branch; name the path as well.
+
+The page itself then states the same facts. Its hidden `remits-session-info` line — which appears in an
+accessibility snapshot with no script — carries `Account` (what it runs as), `Addressed Account` (what
+the URL/token named), `Data Lane`, `Component Branch`, `Variant Applied`, and `Scope Account`.
+
+**`Component Branch` is the branch SELECTED; `Variant Applied` is what actually overlaid.** They are two
+fields because a branch can be selected and overlay nothing: `--variant-branch missing_branch` reports
+`Component Branch: missing_branch` while the page renders trunk components. So read `Variant Applied` —
+the `ComponentVariant` row id this page's component resolved through, or `none` — when the question is
+"did my variant apply?". That is a far sharper signal than inspecting the rendered markup for a style you
+expected.
+
 If `components status` shows staged entries that you cannot safely clear, isolate verification in an
 unused staging namespace instead of deleting someone else's cache:
 
@@ -1383,10 +1464,41 @@ for you, and merging a branch promotes its **deletions** as hard deletes. Do not
 `remits-cli components sync --summary --timeout-ms 300000`; the platform may need longer than the default
 60 seconds to create rows, push rename/meta commits, and regenerate account metadata.
 
+### Where am I in the promotion loop?
+
+```bash
+remits-cli components promotion            # the branch you are standing on
+remits-cli components promotion --branch forked --json
+```
+
+**Run this before every promotion step and after every one.** It reports only — no git, no writes — and it
+reads the remote (which is what the platform syncs from, not your working tree). It works from either
+checkout, because it resolves the branch's owner itself. It exits non-zero while blockers remain, so treat
+that as "do not proceed".
+
+| Phase | Meaning | Next |
+|---|---|---|
+| `converged` | branch == trunk | nothing to do; this is also what a **finished** promotion looks like |
+| `ready` | ahead of trunk, current with it | promote |
+| `diverged` | behind trunk | `git merge <trunk>` into the branch, re-sync, re-read the plan |
+| `awaiting-merge-back` | fully contained in trunk, trunk has moved on | **steps 4–5 are owed** — merge trunk back and re-sync |
+
+Two things it tells you that nothing else does:
+
+- **Which commit the stored counts describe, on BOTH axes.** An overlay is stored only while a file
+  differs from trunk, so the stored set is a statement about a (branch, trunk) pair and either side moving
+  makes it stale: `[STALE — does not match the branch HEAD]` (the branch was pushed since) or
+  `[STALE — matches the branch HEAD, but trunk has moved since]`. The second is the easy one to miss —
+  measured live, a branch at its own synced HEAD reported 2 stored overlays against a real plan of 21.
+- **That a promotion is unfinished.** `awaiting-merge-back` is what a promotion that *looked* successful
+  leaves behind: trunk is correct and its tests pass, while the subscriber silently keeps resolving its
+  pre-promotion overlays — including for any fix made afterwards. **A trunk sync succeeding is step 2 of 5,
+  not completion.**
+
 ### Subscribing, unsubscribing, retiring
 
 ```bash
-remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>]
+remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]
 remits-cli components branch <name> --unsubscribe <accountId>
 remits-cli components branch <name> --retire [--force]
 ```
@@ -1406,6 +1518,11 @@ Branch administration commands act **as the account you are running from**, whic
   Without it the CLI picks the edge to the owner whose branch you are managing, then falls back to the
   account's primary edge — which may not be the one you intended. `--subscribers` prints
   `via primary|membership edge -> parent N` so you can confirm.
+- **Primary-edge subscriptions are structural.** If the selected edge is the account's `parentId` edge,
+  subscribing it makes that account and descendants resolve the branch by default even though `parentId`
+  still points at the same parent. The server refuses this write unless you pass
+  `--confirm-primary-edge`; run `--dry-run` first and prefer a membership edge for fork/pilot
+  subscriptions.
 - **Retiring is explicit.** Deleting the *git* branch does **not** remove its overlays; subscribers would
   keep resolving a branch that no longer exists. `--retire` refuses while subscribers remain unless you
   pass `--force`.
@@ -1438,7 +1555,13 @@ The analogous hazard is different, and you must still respect it:
 - **Deleting a file means "remove the component", not "stop overriding it."** To withdraw an override,
   make the file identical to trunk again — the sync then removes the variant row.
 - **Keep the branch rebased.** A branch physically carries every file, so anything trunk added *after* the
-  branch was cut looks like a deliberate deletion. A small stale gap tombstones silently.
+  branch was cut is absent from it. The sync now asks git which of those absences are real deletions
+  (comparing against the merge base) and refuses to tombstone the rest, reporting them as
+  `skipped: absent from the branch but never deleted on it`. Treat any such entry as "merge trunk in" —
+  if an older sync already stored one of those absences as a tombstone, a non-dry-run sync prunes it and a
+  dry run reports `wouldPrune: true`. The classification falls back to a conservative ratio guard when
+  GitHub's compare is unavailable or its file list comes back truncated, which the sync output says
+  explicitly.
 - **Use `components sync --dry-run` before risky variant syncs.** It reports `overridden`, `added`,
   `removed`, `unchanged`, `skipped`, and `errors` without writing rows, caching the sync SHA, or clearing
   staging. Existing overlay ids appear as `variantId`; an `unchanged` row with `pruned:true` means the
@@ -2687,7 +2810,7 @@ remits-cli components branches [--json]                                # branche
 remits-cli components branch <name> [--json]                           # one branch: overridden / added / removed, drift flags, subscribers
 remits-cli components branch <name> --diff <componentId> --component-type <kind> [--json]
 remits-cli components branch <name> --subscribers [--json]
-remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>]   # make an account resolve this branch
+remits-cli components branch <name> --subscribe <accountId> [--parent-account <id>] [--domain <host>] [--dry-run] [--confirm-primary-edge]   # make an account resolve this branch
 remits-cli components branch <name> --unsubscribe <accountId>                          # return that account to trunk
 remits-cli components branch <name> --retire [--force]                                 # delete the branch's overlays
 remits-cli test run --test <id|name> [--branch <stagingScope>] [--names "a,b"] [--watch true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]