@remits/remits-cli 0.1.99 → 0.1.100

package/README.md

@@ -34,6 +34,8 @@ 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 --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}'
 remits-cli data-mode
 remits-cli data-mode set prod
 remits-cli sessions list

package/index.js

@@ -278,9 +278,29 @@ 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.
+// Tools/actions whose names signal they mutate state rather than only reading it. Used solely to make
+// data-lane banners precise — 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;
+const MUTATING_TOOL_ACTION_PATTERN = /(^|_)(patch|edit|create|commit|update|delete|remove|write|set|assign|run|execute|send|pause|unpause|interrupt|restore|repair|migrate|sync|add|upsert|reparent|structure|accept|complete|release|record|clear|retire|subscribe|unsubscribe|stop|cancel|kill)(_|$)/i;
+
+function toolInputAction(input) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const value = input.action || input.controlAction || input.command || input.mode;
+  if (value === undefined || value === null || value === true) return null;
+  const normalized = String(value).trim();
+  return normalized || null;
+}
+
+function isMutatingToolCall(toolName, input) {
+  if (MUTATING_TOOL_PATTERN.test(String(toolName || ''))) return true;
+  const action = toolInputAction(input);
+  return action ? MUTATING_TOOL_ACTION_PATTERN.test(action) : false;
+}
+
+function toolOperationLabel(toolName, input) {
+  const action = toolInputAction(input);
+  return 'tool ' + String(toolName) + (action ? ' action ' + action : '');
+}
 
 function looksLikeDryRun(input) {
   if (!input || typeof input !== 'object') return false;
@@ -294,25 +314,29 @@ function isLocalBaseUrl(baseUrl) {
 }
 
 /**
- * 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.
+ * One consistent banner across risky data-lane surfaces. Agents have repeatedly crossed prod/test
+ * boundaries by assumption, so the banner is loud, states the account it resolved, and distinguishes
+ * live production writes from isolated test-data writes.
  */
 function printProdDataBanner({ dataMode, accountId, baseUrl, operation, mutating = false, dryRun = false }) {
   const normalizedDataMode = String(dataMode || '').toLowerCase();
   const prodData = normalizedDataMode === 'prod';
   const prodHost = baseUrl && !isLocalBaseUrl(baseUrl);
-  if (!prodData && !prodHost) return;
+  if (!prodData && !prodHost && !mutating) return;
   const bar = '='.repeat(72);
   let headline;
   if (prodData) {
     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');
-  } else {
+  } else if (prodHost) {
     headline = dryRun
       ? 'PROD HOST / TEST DATA — DRY RUN'
       : (mutating ? 'PROD HOST / TEST DATA WRITE — deployed app, isolated test data' : 'PROD HOST / TEST DATA READ — deployed app, isolated test data');
+  } else {
+    headline = dryRun
+      ? 'TEST DATA — DRY RUN (no write will be attempted)'
+      : 'TEST DATA WRITE — isolated test data';
   }
   console.log(bar);
   console.log('  ' + headline);
@@ -421,6 +445,17 @@ function sessionJsonlFile(cwd) {
 }
 
 const CONTENT_FIELDS = new Set(['source', 'html', 'javascript', 'css', 'schema', 'inputSchema', 'previewData', 'messages']);
+const SECRET_LOG_FIELDS = new Set([
+  'token',
+  'tokeninput',
+  'tokenkey',
+  'authtoken',
+  'xauthtoken',
+  'x-auth-token',
+  'remitstoken',
+  'x-remits-token',
+  'authorization'
+]);
 
 function sanitizeForLog(value) {
   if (value === null || value === undefined) {
@@ -434,7 +469,7 @@ function sanitizeForLog(value) {
   }
   const out = {};
   for (const [k, v] of Object.entries(value)) {
-    if (k.toLowerCase() === 'token') {
+    if (SECRET_LOG_FIELDS.has(k.toLowerCase())) {
       out[k] = '[redacted]';
     } else if (CONTENT_FIELDS.has(k) && typeof v === 'string') {
       out[k] = '[' + v.length + ' chars]';
@@ -2777,6 +2812,12 @@ async function testCommand(flags) {
 }
 
 async function tokenCommand(flags) {
+  const subcommand = flags._ && flags._[1];
+  if (subcommand === 'inspect' || subcommand === 'details' || subcommand === 'decode') {
+    await tokenInspectCommand(flags);
+    return;
+  }
+
   const cwd = process.cwd();
   ensureLocalState(cwd);
   const sessionContext = resolveSessionContext(cwd, flags);
@@ -2829,6 +2870,35 @@ async function tokenCommand(flags) {
   console.log(JSON.stringify(output, null, 2));
 }
 
+async function tokenInspectCommand(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 positional = flags._ && flags._[2];
+  const tokenInput = flags.token || flags['token-key'] || flags.tokenKey || flags.value || flags.url || positional;
+
+  if (!tokenInput || tokenInput === true) {
+    throw new Error('Token inspection requires --token <token|tokenKey|URL>, --token-key <key>, --url <URL>, or a positional value.');
+  }
+
+  const api = buildAxios(baseUrl, session.token);
+  const data = await loggedPost(api, cwd, '/cli/tokenInspect', {
+    token: session.token,
+    accountId,
+    tokenInput
+  }).then((r) => r.data);
+
+  if (!data.success) {
+    throw new Error(data.message || 'Failed to inspect token');
+  }
+
+  printSessionResolutionWarning(sessionContext);
+  printResolvedBaseUrl(baseUrl);
+  console.log(JSON.stringify(data, null, 2));
+}
+
 async function toolsCommand(flags) {
   const cwd = process.cwd();
   ensureLocalState(cwd);
@@ -2957,8 +3027,8 @@ async function toolCommand(flags) {
     dataMode,
     accountId,
     baseUrl,
-    operation: 'tool ' + String(toolName),
-    mutating: MUTATING_TOOL_PATTERN.test(String(toolName)),
+    operation: toolOperationLabel(toolName, input),
+    mutating: isMutatingToolCall(toolName, input),
     dryRun: looksLikeDryRun(input)
   });
 
@@ -5524,8 +5594,10 @@ function printToolsHelp() {
 
 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('Inspect decodes a persisted Remits token and prints token metadata, recognized routing fields, safety/dataMode evidence, and full context.');
 }
 
 async function main() {
@@ -5594,6 +5666,7 @@ async function main() {
     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('  remits-cli token inspect --token <token|tokenKey|URL> [--base-url URL] [--account-id ID]');
     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.');

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -166,6 +166,31 @@ For access questions — "who can see this client account?", "why does this user
 `mcp_sql_query` only when you need raw join-table investigation. Remember a user's custom fields are stored
 **per bound account**, so the same person can differ per account.
 
+**Test-data flags are first-class safety evidence.** `Account.testAccount` and `User.testUser` are set for
+accounts/users created while the execution data lane is `test` (including `mcp_account_user_admin`
+creation paths); prod-data creates leave them false. Updating an existing real account/user in test mode
+does not convert it into test data, but its Firestore extension-field writes still go to the test lane.
+`Object.testMode` / `Event.testMode` / `Alert.testMode` identify lifecycle rows in the test data lane.
+Agent-facing surfaces expose these fields:
+
+- `account-info.json`, `account-hierarchy.json`, and `mcp_account_view`: `resolution.testAccount` for the
+  described account, and `testAccount` on returned hierarchy nodes.
+- `mcp_account_user_admin`: `testAccount` on `hierarchy`, `account`, and `account_create` results;
+  `testUser` on `users` / `user` results.
+- `mcp_record_listing` / `mcp_record_view`: `testMode` on `object`, `event`, and `alert` records.
+- `mcp_object_activity`: top-level `dataMode`, `object.testMode`, and `testMode` on Event/Alert
+  timeline entries.
+- `mcp_event_diagnostics`: top-level `dataMode` and `result.event.testMode`.
+- `remits-cli token inspect`: owner `account.testAccount` and `user.testUser`, plus token `dataMode`.
+
+Persisted AI session rows currently do **not** store durable per-grouping `testMode` / `dataMode`; use
+`mcp_ai_session_search.dataMode` only as the current tool execution lane, not as proof of the historical
+grouping's data lane.
+
+If any of those fields contradict the lane you intended, stop and rerun the command with an explicit
+`--data-mode test` or `--data-mode prod`. Never infer prod/test from an account name, URL, branch name, or
+the mere existence of a created account.
+
 Use `remits-cli` for everything else: staging changes, running tests, generating embeddable tokens,
 committing work, and diagnosing production issues.
 
@@ -400,6 +425,7 @@ Use `mcp_support_ticket` to manage lifecycle:
 - `complete` — resolve the ticket with a summary of what was done
 - `release` — unassign if you cannot continue
 - **Pulling a ticket by number is enough — you do NOT need to know its account first.** The `ticketId` IS the ticket's globally-unique anchor id, and `mcp_support_ticket` resolves the owning account from it for every action that operates on an existing ticket (`read`, `accept`, `update_status`, `complete`, `release`, `record_progress`, `add_artifact`, `get_attachment`). So when a user says "pull ticket 19463", just call `read` with `{ "action": "read", "ticketId": "19463" }` from any authenticated **prod** session (the ticket lives in prod data) — omit `accountId` entirely. The response returns the resolved `accountId`/`accountName` (and `implementationAccountId` when set); use those for any follow-up work. **Only `create` requires an explicit `accountId`** (a brand-new ticket has no anchor to resolve from). If a bare `ticketId` returns "Support ticket not found", double-check you are in `--data-mode prod`, then fall back to passing an explicit `accountId`.
+- `read` can return `documentState:'missing_or_empty'` with `ticket.mirrorOnly:true` and `ticket.canMutate:false`. That means the support-ticket anchor exists and the queue row is real, but the backing Firestore `support_tickets/{ticketId}` document is missing or metadata-only. Treat this as a degraded ticket, not as "ticket not found"; run or request the System Account action `Restore Support Ticket Documents From Anchor Mirrors` for the owning account before lifecycle mutations. The restore recovers mirrored scalar fields, but document-only arrays such as alert snapshots, email threads, attachments, worklog entries, and artifacts may be lost.
 - If a ticket is part of the request, manage the lifecycle proactively. Do not wait for the human user to remind you to read, accept, update, complete, or release it.
 
 Ticket-routing context:
@@ -1602,15 +1628,16 @@ account).
 
 - `action: 'hierarchy'` (default) — the descendant tree trimmed to `depth` (1-10, default 2; nodes cut off
   are marked `truncated` and still report their child count) and/or the anchored ancestor chain plus every
-  edge (`direction: 'down'|'up'|'both'`). **This is how you get the deep tree account-info.json omits.**
-- `action: 'account'` — one account's `resolution` block plus masked configuration fields, without paying
-  for the component inventory.
+  edge (`direction: 'down'|'up'|'both'`). Nodes include `testAccount`. **This is how you get the deep tree
+  account-info.json omits.**
+- `action: 'account'` — one account's `resolution` block, including `testAccount`, plus masked
+  configuration fields, without paying for the component inventory.
 - `action: 'users'` — an account's users at a hierarchy `scope` (`self`/`children`/`parents`/`hierarchy`),
-  optional `email` substring filter. Extension fields are omitted here on purpose: they are stored **per
-  account** and these users are bound to their own.
+  optional `email` substring filter. Rows include `testUser`. Extension fields are omitted here on purpose:
+  they are stored **per account** and these users are bound to their own.
 - `action: 'user'` — one user (`userId` or `email`) with roles, account memberships, and extension fields
-  **correctly scoped to the requested account**. It never grants membership as a side effect of a read, and
-  tells you when the fields shown belong to a different account.
+  **correctly scoped to the requested account**, plus `testUser`. It never grants membership as a side
+  effect of a read, and tells you when the fields shown belong to a different account.
 - `action: 'account_update'` — write Account-schema configuration `fields`, and/or `name`/`status`
   (`ACTIVE`/`ON_HOLD`/`PENDING`).
 - `action: 'user_update'` — write User-schema `fields` under the named account, plus `name`/`enabled` and
@@ -1621,12 +1648,35 @@ account).
 **Building an account hierarchy** (the structural writes — this is how a coding agent provisions accounts
 without a browser):
 
+**Data-lane rule for provisioning:** `remits-cli tool` defaults to `--data-mode test`. That is correct for
+fixtures and rehearsals, but it means `mcp_account_user_admin` `action:'account_create'` creates test-lane
+accounts unless the command explicitly passes `--data-mode prod`. For real platform/product/customer
+provisioning, always dry-run in prod first, check the response's `dataMode`, then run the write in prod:
+
+```bash
+remits-cli tool --name mcp_account_user_admin --data-mode prod --input '{"action":"account_create","parentAccountId":4,"name":"Freto","type":"PRODUCT","dryRun":true}'
+```
+
+After the real write, verify the response (or re-read `action:'account'`) shows the command `dataMode` you
+intended and `testAccount:false` for real provisioning. `testAccount:true` means you created a test-data
+account, even if the name and structure look correct.
+
+For a test rehearsal, make the opposite assertion explicit: the response should show `dataMode:'test'` and
+`testAccount:true` for created accounts (or `testUser:true` for created users). A false test flag in a
+test rehearsal means the data lane or the returned entity is not the one you intended.
+
+Account/User schema `fields` are Firestore-backed extension fields. Their physical storage follows the
+same data lane as the tool call: `--data-mode test` writes under `testing/<resolvedDatabaseName>/...`, while
+`--data-mode prod` writes under `accounts/<resolvedDatabaseName>/...` (for modern segmented accounts). If a
+test-lane rehearsal should become real provisioning, rerun the create/update in prod mode; do not assume the
+test-lane Firestore fields moved.
+
 - `action: 'account_create'` — create a child under `parentAccountId`, with its **primary relationship edge**,
   applying `type` / `databaseName` / `domainName` / `authPath` / `targetPath` / `code` /
   `repositoryNameOverride` / `branchName` / `editMode` / … **at birth**. That ordering matters: the storage
   namespace is resolved from those properties, and the parent's cascaded schema fields are written into it
   during creation. Idempotent — an existing same-name account under that parent comes back with
-  `reusedExisting: true`, unchanged.
+  `reusedExisting: true`, unchanged. The response includes `testAccount`.
 - `action: 'account_structure'` — change those properties on an existing account, including account-level
   custom host, login path, and landing path.
 - `action: 'edge_add'` / `'edge_update'` / `'edge_remove'` — manage a membership `AccountRelationship` edge to
@@ -1752,8 +1802,11 @@ Object lifecycle timeline — metadata + recent activity.
 |-----------|----------|-------------|
 | `accountId` | yes | Account ID |
 | `objectId` | yes | Object ID (from `object_id` in documents) |
+| `dataMode` | no | Explicit lane: `prod` or `test`. Response echoes `dataMode`. |
 | `activityOptions` | no | `{limit, offset, types, start, end, order}`. Default: limit=5, order=desc. Types: `OBJECT_LOG`, `EVENT`, `ALERT`. |
 
+Response fields include `dataMode`, `object.testMode`, and `testMode` on Event/Alert timeline entries.
+
 ### `mcp_record_listing`
 List and search lifecycle records when you do not already know the record ID.
 
@@ -1807,6 +1860,7 @@ Front-stage references:
 | Parameter | Required | Description |
 |-----------|----------|-------------|
 | `action` | no | `search` (default), `detail`, or session control `pause`/`unpause`/`interrupt` |
+| `dataMode` | no | Explicit execution lane: `prod` or `test`. Response echoes `dataMode`, but persisted groupings do not have durable per-row lane flags. |
 | `search` | no | Broad text match against session IDs and grouping IDs |
 | `sessionId` | no | Session ID filter in search mode, or grouping/session key in detail mode |
 | `groupingId` | no | Grouping ID filter in search mode, or grouping key in detail mode |
@@ -2191,6 +2245,7 @@ This keeps file retrieval self-contained — no separate download endpoint is ne
 
 **Recommended flow** — `accountId` is optional throughout; `ticketId` resolves the owning account:
 1. `read` — check ticket state and any attachments
+   - If `read` returns `ticket.mirrorOnly:true`, use the mirrored fields for triage context, restore the backing document first, then claim/update/complete it.
 2. **`accept`** (with `assignee`) — this is a **hard precondition for `update_status`**, not just etiquette
 3. `get_attachment` if attachments are present and relevant to the investigation
 4. `update_status` — `in_progress` while working, `pending_review` when the fix is done but not yet deployed
@@ -2356,6 +2411,10 @@ optional class-histogram sampling, **no heap dump and no JFR**.
 List and filter tickets **across an account and its descendants** so you can choose what to work on. Lifecycle
 actions stay on `mcp_support_ticket`.
 
+Queue rows are built from support-ticket anchor mirrors by default. A row in this list means a
+support-ticket anchor exists; it does not guarantee the full Firestore document is healthy. Open the
+ticket with `mcp_support_ticket read` before lifecycle work and honor `mirrorOnly` / `documentState` if present.
+
 | Parameter | Required | Description |
 |-----------|----------|-------------|
 | `action` | no | `list` (default) |
@@ -2544,6 +2603,7 @@ remits-cli components branch <name> --unsubscribe <accountId>
 remits-cli components branch <name> --retire [--force]                                 # delete the branch's overlays
 remits-cli test run --test <id|name> [--names "a,b"] [--watch true|false] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
 remits-cli token [--path <embeddablePathOrId>] [--data-mode test|prod] [--as-account <ID>] [--variant-branch <name|none>]
+remits-cli token inspect --token <token|tokenKey|URL>                  # inspect token metadata, safety/dataMode evidence, and full context
 remits-cli tools [--branch <name>] [--data-mode test|prod] [--variant-branch <name|none>]
 remits-cli tool --name <toolName> [--branch <name>] [--input "{...}"] [--data-mode test|prod] [--variant-branch <name|none>] [--timeout-ms 60000] [--async true --wait true]
 remits-cli tool status --call-id <callId> [--data-mode test|prod]
@@ -2584,7 +2644,10 @@ For tests specifically:
 
 - Every command that can touch production (`tool`, `test run`, `components sync`) prints a `PROD DATA`
   banner naming the operation, the resolved account, and the host — and distinguishes a live **WRITE**
-  from a live **READ** and from a **DRY RUN**. If you see a WRITE banner you did not intend, stop.
+  from a live **READ** and from a **DRY RUN**. `remits-cli tool` also prints an explicit **TEST DATA WRITE**
+  banner for mutating tool calls in the test lane, including multi-action tools such as
+  `mcp_account_user_admin` where the write is signaled by `input.action` (`account_create`, `user_update`,
+  `edge_update`, etc.). If you see a WRITE banner you did not intend, stop.
 - A tool call that fails **in the platform runtime** rather than in the tool (Groovy reflective dispatch
   of a runtime-compiled component, an empty connection pool, a Redis reconnect, a lock-wait timeout)
   now comes back as HTTP `503` with `failureClass: "transient_infrastructure"` and `retryable: true`,
@@ -2612,6 +2675,7 @@ For tests specifically:
 | Staged change has no effect in a live (non-CLI) run | Staged overrides resolve only under a CLI TestMode (`branchName`+`cliUserId`). Live webhooks and other non-CLI runtime paths still use the DB (trunk, or the account's subscribed variant). `commit` to make it durable. See "Component Resolution". |
 | Need to know an account's shape (role, type, parents, namespace, branch, host/login routes) | Read `resolution` — from the repo's `account-info.json`, or `mcp_account_user_admin` `action:'account'` (cheap), or `mcp_account_view` (full inventory): `role`/`summary`, `type`, `resolvedDatabaseName`, `domainName`/`resolvedDomainName`, `authPath`/`targetPath`, `relationships`, `componentBranch`, plus top-level `componentBranches`. Never infer structure from the account's name. |
 | Need the account tree below an account, or its users | In a local repo, read `account-hierarchy.json` for the generated tree. For live data, use `mcp_account_user_admin` (`action:'hierarchy'` with a `depth`, or `action:'users'`). `account-info.json` deliberately omits the tree. |
+| Need to prove whether an account/user/record is test data | Check explicit flags: `resolution.testAccount` / hierarchy `testAccount`, `mcp_account_user_admin` `testAccount` / `testUser`, token inspect owner flags, and `mcp_record_listing` / `mcp_record_view` `testMode` for object/event/alert rows. Do not infer from names or branch labels. |
 | Need account configuration values | In a local repo, read `account-configurations.json`. For live data, use `mcp_account_user_admin` (`action:'account'`) or `mcp_account_view`. `account-info.json` deliberately omits configurations. |
 | An account has two parents and you don't know which one a run used | `resolution.relationships` lists every link with its own `branchName`/`databaseName`/`domainName`. A membership-only account with SEVERAL edges resolves **trunk and inherits nothing** until a path is named (`--as-account`, `--variant-branch`, or an edge host) — that is by design, not a bug. With exactly ONE membership edge it inherits normally, descendants included. |
 | Documents missing / written to the wrong place | Compare `resolution.databaseName` (the account's own override) with `resolution.resolvedDatabaseName` (what is actually in effect), and check for a `databaseName` on one of the `relationships` edges. Data does not inherit; components do. |