@remits/remits-cli 0.1.77 → 0.1.80

package/README.md

@@ -55,7 +55,8 @@ remits-cli install --skills --overwrite true
 
 - `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.
 - `components status` shows the branch/user staging entries that can shadow DB components during CLI-scoped test-mode execution.
-- `components clear` clears the branch/user staging scope. Use `--component-type` + `--component-id` to clear one component; omit them to clear all staged entries for the current branch.
+- `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 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.

package/index.js

@@ -92,6 +92,10 @@ function parseArgs(argv) {
   return out;
 }
 
+function flagEnabled(value) {
+  return value === true || value === 'true' || value === '1' || value === 'yes';
+}
+
 function ensureSessionDir() {
   if (!fs.existsSync(SESSION_DIR)) {
     fs.mkdirSync(SESSION_DIR, { recursive: true });
@@ -1635,11 +1639,80 @@ async function pushComponentsCommand(flags) {
     components
   }).then((r) => r.data);
 
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(response, null, 2));
+    return response;
+  }
+
   printSessionResolutionWarning(sessionContext);
   printResolvedBaseUrl(baseUrl);
   console.log('Data mode:', response.dataMode || dataMode);
   console.log('Mode:', response.mode || mode);
-  console.log('Components sync:', JSON.stringify(response, null, 2));
+  printStageSummary(response, flags);
+}
+
+function shouldPrintFullComponentResponse(flags) {
+  return flagEnabled(flags.verbose);
+}
+
+function printFullResponseHint() {
+  console.log('Full response: use --json or --verbose');
+}
+
+function componentTypeCounts(entries) {
+  const counts = {};
+  for (const entry of entries || []) {
+    const type = entry.componentType || entry.type || 'Unknown';
+    counts[type] = (counts[type] || 0) + 1;
+  }
+  return counts;
+}
+
+function printComponentTypeCounts(entries) {
+  const counts = componentTypeCounts(entries);
+  const summary = Object.keys(counts)
+    .sort()
+    .map((type) => type + ':' + counts[type])
+    .join(', ');
+  if (summary) {
+    console.log('By type:', summary);
+  }
+}
+
+function printComponentCommandResponse(label, response, flags) {
+  if (shouldPrintFullComponentResponse(flags)) {
+    console.log(label + ':', JSON.stringify(response, null, 2));
+    return;
+  }
+  printFullResponseHint();
+}
+
+function printStageSummary(response, flags) {
+  console.log('Updated:', response.updated || 0);
+  console.log('Unchanged:', response.unchanged || 0);
+  console.log('Skipped:', Array.isArray(response.skipped) ? response.skipped.length : 0);
+  if (response.reconcile) {
+    console.log('Reconciled stale keys:', response.reconcile.removedCount || 0);
+  }
+  if (response.staging) {
+    console.log('Remaining staged count:', response.staging.remainingCount || 0);
+  }
+  printComponentCommandResponse('Components stage', response, flags);
+}
+
+function printStatusSummary(response, flags) {
+  console.log('Staged count:', response.stagedCount || 0);
+  printComponentTypeCounts(response.entries || []);
+  printComponentCommandResponse('Components staging', response, flags);
+}
+
+function printClearSummary(response, flags) {
+  console.log('Cleared keys:', response.clearedCount || 0);
+  console.log('Remaining staged count:', response.remainingCount || 0);
+  if (Array.isArray(response.clearedKeys) && response.clearedKeys.length && response.clearedKeys.length <= 10) {
+    console.log('Cleared:', response.clearedKeys.join(', '));
+  }
+  printComponentCommandResponse('Components clear', response, flags);
 }
 
 async function statusComponentsCommand(flags) {
@@ -1666,12 +1739,16 @@ async function statusComponentsCommand(flags) {
     throw new Error(response.message || 'Staging status failed');
   }
 
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(response, null, 2));
+    return response;
+  }
+
   printSessionResolutionWarning(sessionContext);
   printResolvedBaseUrl(baseUrl);
   console.log('Data mode:', response.dataMode || dataMode);
   console.log('Mode:', response.mode || 'status');
-  console.log('Staged count:', response.stagedCount || 0);
-  console.log('Components staging:', JSON.stringify(response, null, 2));
+  printStatusSummary(response, flags);
   return response;
 }
 
@@ -1687,13 +1764,23 @@ async function clearComponentsCommand(flags) {
   const componentType = flags['component-type'] || flags.type;
   const componentId = flags['component-id'] || flags.id;
 
+  // A clear is SCOPED when a type and/or id is given. Component ids are type-local, so an id alone can
+  // match more than one family; the server clears it only when unambiguous and otherwise returns an
+  // ambiguity error asking for --component-type (pass the type to target exactly one). Only escalate to
+  // clearAll (the whole branch/user scope) when NO filter is supplied — never because a filter was
+  // partial. Passing `--all` forces the full-scope wipe.
+  const hasType = Boolean(componentType && String(componentType).trim());
+  const hasId = componentId !== undefined && componentId !== null && String(componentId).trim() !== '';
+  const scoped = hasType || hasId;
+  const clearAll = flagEnabled(flags.all) || flagEnabled(flags['clear-all']) || !scoped;
+
   const response = await loggedPost(api, cwd, '/cli/components', {
     token: session.token,
     accountId,
     branchName,
     dataMode,
     mode: 'clear',
-    clearAll: !(componentType && componentId),
+    clearAll,
     componentType,
     componentId
   }).then((r) => r.data);
@@ -1702,13 +1789,16 @@ async function clearComponentsCommand(flags) {
     throw new Error(response.message || 'Staging clear failed');
   }
 
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(response, null, 2));
+    return response;
+  }
+
   printSessionResolutionWarning(sessionContext);
   printResolvedBaseUrl(baseUrl);
   console.log('Data mode:', response.dataMode || dataMode);
   console.log('Mode:', response.mode || 'clear');
-  console.log('Cleared count:', response.clearedCount || 0);
-  console.log('Remaining staged count:', response.remainingCount || 0);
-  console.log('Components staging:', JSON.stringify(response, null, 2));
+  printClearSummary(response, flags);
   return response;
 }
 
@@ -1735,6 +1825,11 @@ async function syncComponentsCommand(flags) {
     throw new Error(response.message || 'Server sync failed');
   }
 
+  if (flagEnabled(flags.json)) {
+    console.log(JSON.stringify(response, null, 2));
+    return response;
+  }
+
   printSessionResolutionWarning(sessionContext);
   printResolvedBaseUrl(baseUrl);
   console.log('Data mode:', response.dataMode || dataMode);
@@ -4338,6 +4433,7 @@ function releaseAutoUpdateLock() {
 function shouldAutoUpdate(command, flags) {
   if (!command || command === 'help' || command === '--help') return false;
   if (flags && flags['no-auto-update']) return false;
+  if (flags && flagEnabled(flags.json)) return false;
   if (process.env.REMITS_CLI_AUTO_UPDATE && AUTO_UPDATE_DISABLED_VALUES.has(String(process.env.REMITS_CLI_AUTO_UPDATE).toLowerCase())) {
     return false;
   }
@@ -4408,6 +4504,7 @@ async function main() {
   const args = parseArgs(originalArgv);
   const [command, subcommand] = args._;
   const wantsHelp = args.help === true || subcommand === 'help' || subcommand === '--help' || args._.includes('--help');
+  const wantsJson = flagEnabled(args.json);
 
   if (shouldAutoUpdate(command, args)) {
     const requireSuccessfulAutoUpdate = command === 'start';
@@ -4421,7 +4518,7 @@ async function main() {
   // Skip for lifecycle subcommands and help.
   const isLifecycleCmd = command === 'listen' || command === 'start' || command === 'stop' || command === 'status';
   const isHelpCmd = !command || command === 'help' || command === '--help' || wantsHelp;
-  if (!isHelpCmd && !isLifecycleCmd && !isListenerRunning()) {
+  if (!wantsJson && !isHelpCmd && !isLifecycleCmd && !isListenerRunning()) {
     try {
       const dashboardUrl = await autoStartServiceIfNeeded();
       if (dashboardUrl) {
@@ -4436,7 +4533,7 @@ async function main() {
   // only platform-authenticated users ever receive them. `auth` syncs its own
   // guides, so it is excluded here.
   const GUIDE_SYNC_COMMANDS = new Set(['components', 'test', 'token', 'tools', 'tool']);
-  if (!isHelpCmd && GUIDE_SYNC_COMMANDS.has(command)) {
+  if (!wantsJson && !isHelpCmd && GUIDE_SYNC_COMMANDS.has(command)) {
     try { await ensureGuidesSynced(process.cwd(), args); } catch (_) { /* best-effort */ }
   }
 
@@ -4454,9 +4551,9 @@ async function main() {
     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]');
-    console.log('  remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod]');
-    console.log('  remits-cli components status [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID]');
-    console.log('  remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID]');
+    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]');
@@ -4466,9 +4563,9 @@ async function main() {
 
   if (command === 'components' && wantsHelp) {
     console.log('Usage: remits-cli components <stage|status|clear|sync|commit>');
-    console.log('  remits-cli components stage [--base-url URL] [--account-id ID] [--branch BRANCH] [--data-mode test|prod]');
-    console.log('  remits-cli components status [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID]');
-    console.log('  remits-cli components clear [--base-url URL] [--account-id ID] [--branch BRANCH] [--component-type TYPE --component-id ID]');
+    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]');
     process.exit(0);

package/package.json

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

package/skills/remits-cli/SKILL.md

@@ -217,7 +217,7 @@ Use `mcp_support_ticket` to manage lifecycle:
 - `update_status` — move to `in_progress` or `pending_review`
 - `complete` — resolve the ticket with a summary of what was done
 - `release` — unassign if you cannot continue
-- Always call `mcp_support_ticket` with the ticket's owning `accountId`.
+- **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`.
 - 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:
@@ -811,8 +811,9 @@ TestMode still uses the committed DB source. Staging remains a dev/verification
 - **Confirm the DB version:** `mcp_component_view` reads the live DB source directly (no staging, no compile
   cache), so it is the source of truth for "what was committed."
 - **Ask the CLI what is staged:** `remits-cli components status` lists the current branch/user staged entries,
-  including `componentSource`, staged fields, aliases, hashes, and TTLs. `remits-cli components clear` removes
-  those entries when you intentionally want to fall back to DB source.
+  including staged fields, aliases, hashes, and TTLs. The default terminal output is concise; pass `--json` or
+  `--verbose` when you need the full staged-entry payload. `remits-cli components clear` removes those entries
+  when you intentionally want to fall back to DB source.
 
 ### Stage / commit / clear with the MCP tools
 
@@ -1108,9 +1109,9 @@ Create and manage the full lifecycle of account-relative `support_tickets`.
 
 | Parameter | Required | Description |
 |-----------|----------|-------------|
-| `accountId` | yes | The account that owns the support ticket |
+| `accountId` | conditional | The account that owns the support ticket. **Required only for `create`.** For every other action it is optional — the tool resolves the owning account from `ticketId` (the ticket's anchor id) and returns it. Pass it only to override/disambiguate. |
 | `action` | yes | `create`, `read`, `accept`, `update_status`, `complete`, `release`, `record_progress`, `add_artifact`, or `get_attachment` |
-| `ticketId` | conditional | Required for every action **except** `create` (which returns the new ticket ID) |
+| `ticketId` | conditional | Required for every action **except** `create` (which returns the new ticket ID). Alone it is sufficient to resolve the ticket and its owning account. |
 | `subject` | conditional | Short title. Required for `create`. |
 | `type` | conditional | Required for `create`: `enhancement`, `defect`, `question`, `task`, or `incident` |
 | `priority` | no | `low`/`medium`/`high`/`critical` for `create` (default `medium`) |
@@ -1371,9 +1372,9 @@ remits-cli stop
 remits-cli status
 remits-cli listen [stop|status] [--foreground true]   # compatibility alias
 remits-cli data-mode [set test|prod]
-remits-cli components stage [--branch <name>] [--data-mode test|prod]
-remits-cli components status [--branch <name>] [--component-type <type>] [--component-id <id>]
-remits-cli components clear [--branch <name>] [--component-type <type>] [--component-id <id>]
+remits-cli components stage [--branch <name>] [--data-mode test|prod] [--json|--verbose]
+remits-cli components status [--branch <name>] [--component-type <type>] [--component-id <id>] [--json|--verbose]
+remits-cli components clear [--branch <name>] [--component-type <type>] [--component-id <id>] [--all] [--json|--verbose]   # id alone scopes to one component when unambiguous (ids are type-local; add --component-type if the same id is staged in multiple families); no filter clears the whole branch scope; --all forces the full wipe
 remits-cli components sync [--branch <name>] [--data-mode test|prod]   # gated durable repo->DB reconciliation only
 remits-cli components commit [--message "msg"] [--data-mode test|prod]
 remits-cli test run --test <id|name> [--names "a,b"] [--watch true|false] [--data-mode test|prod]
@@ -1402,7 +1403,7 @@ For tests specifically:
 | Tool parameters rejected | Tool schemas may be cached. Run `remits-cli tools` to refresh `.remits-cli/tools/tools.json` with latest schemas. |
 | Tool response missing | Check `./.remits-cli/tool-responses/` |
 | 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. `commit` to make it durable. See "Component Resolution". |
-| New source shown by `mcp_component_view` but old behavior persists after sync/commit | In-memory compile cache (`CLOSURE_CACHE`, version-keyed, per instance) still holds the prior closure. Environmental; the platform owner recycles the instance. |
+| New source shown by `mcp_component_view` but old behavior persists after sync/commit | The compile cache (`CLOSURE_CACHE`) is keyed by `version:<N>:<sourceHash12>`, so a source change on the same version now invalidates it automatically — a run right after sync/commit picks up the new source. If old behavior still persists, confirm the run actually hit the synced instance and that no staged override is still shadowing DB (`remits-cli components status`). |
 | Staged Reader test run throws `No enum constant ObjectType.<family>` | The staged entry has the component family in `type` (should be `kind`). Clear + re-stage; if it persists, the `mcp_component_edit` tool on that instance is on an old/cached version. Inspect with `mcp_cache`. |
 | Unsure whether a run used staged vs DB source | Query `mcp_system_logs` for `Using Cached BCD` — `Signature: cli:<hash>` = staged, `version:<N>:<sourceHash12>` = DB. CLI/MCP tool results also report `componentSource` and `componentSignature` when available. |
 | Service already running | Run `remits-cli status` to get the dashboard URL, or `remits-cli stop` before restarting. |