Audit cleanup: concurrency, error handling, DRY pass (#407)

* Audit cleanup: concurrency, error handling, DRY pass

Cross-package code-review pass addressing high- and medium-severity
findings across the SDK, CLI, MCP server, VS extension, and mrt-utilities.

Concurrency / correctness:
- SDK: atomic write for the stateful auth-session file (temp + rename).
- SDK: single-flight refresh in OAuthStrategy.getAccessToken so concurrent
  callers coalesce instead of stampeding the AM token endpoint.
- SDK: clean up debug-session keepalive/poll timers when connect()
  fails after starting them.
- SDK: try/finally around progress timers in code download/deploy so
  aborted requests can no longer leak intervals.
- CLI: long-running commands (code:watch, logs:tail, mrt:tail-logs)
  deregister their SIGINT/SIGTERM handlers when finished.
- VS ext: guard webview postMessage against panel disposal in the
  Swagger API Browser; drain pending uploads before tearing down code-
  sync watchers; prevent sandbox-tree polling stop-checks from stacking
  when the polling interval is shorter than the stabilization window.
- mrt-utilities: pipeToDestination now destroys the destination on
  pipeline error so consumers fail fast instead of hanging.
- MCP: registerToolsets() throws clearly if invoked twice for the
  same server; telemetry send failures are logged at debug.

Error handling:
- Replaced silent catch {} blocks in stateful-store unlinkSync,
  job:run afterOperation hooks, logs:tail signal handler, and MCP
  telemetry with debug-level logging.
- CIP commands now stream output through ux.stdout instead of
  process.stdout, restoring --json and test capture; CIP tests use
  runSilent.

DRY / dead code:
- New @salesforce/b2c-tooling-sdk/ux export hosts the canonical
  confirm() prompt; CLI's prompts.ts is now a thin re-export.
- New auth/jwt-utils consolidates JWT exp/scope decoding previously
  duplicated across three auth strategies.
- AM list commands share an amPageSizeFlag definition.
- formatApiError SLAS/SCAPI variants now alias the SDK's
  getApiErrorMessage; ECDN gets a single requireScapiCoordinates
  helper.
- Removed deprecated LocalSourceResult re-export.

Lint, typecheck, and the full test suite (4,075 tests) pass.

* Test-quality cleanup: tighten assertions, add expectError helper

Companion to the audit cleanup. Addresses every High and the highest-
leverage Medium items from TEST_AUDIT_PLAN.md so the test suite catches
real regressions instead of just confirming functions ran.

CLI:
- expectError(fn, match?) helper added to test/helpers/test-setup.ts;
  replaces the verbose try { await x; expect.fail(...) } catch {}
  pattern that could swallow the wrong error type.
- code/deploy: tighten .calledOnce checks to verify args (instance,
  cartridges, code version) and afterOperation hook payload.
- code/activate: assert PATCH path/body and reload toggle order
  (active → alternate → active) instead of just call counts.
- auth/token: assert returned JSON shape and that ux.stdout was called
  with exactly the access token, not just .calledOnce.
- mrt/env/var/push: positively assert that listEnvVars ran when
  asserting setBatchStub was *not* called.
- cip/query: drop echo tautologies (result.sql === input); assert that
  the resolved SQL was passed to mockClient.query.
- Promote sinon.stub(odsClient) and makeCommandThrowOnError out of 12
  duplicated copies in sandbox tests into the canonical helpers.
- Switch .to.equal(true|false) → .to.be.true|false where present.

SDK:
- logger.test.ts: drop 18 redundant `expect(logger).to.exist` lines
  (the followup `.to.be.a('function')` was the real check).

MCP:
- registry: new smoke test invokes a registered handler
  (sfnext_get_guidelines) end-to-end; previously only tool names were
  asserted.
- theming-store: 25 weak `expect(guidance).to.exist` calls upgraded to
  `expect(guidance, '...').to.not.be.undefined` so failures point at
  the missing key.
- figma generate-component: replace 7 `array.some(d => …).to.equal(true)`
  chains with `array.find(...)` + concrete property assertions so
  failures show what actually went wrong.

mrt-utilities:
- create-lambda-adapter-compression.test.ts: replace 39 fixed
  `setTimeout(50ms)` waits with the existing event-driven
  `stream.waitForEnd()`. Suite runtime drops from ~3s to ~1s.

All 4,076 tests pass (+1 from the new MCP smoke test). Lint and
typecheck clean.

Author: clavery

.changeset/audit-cleanup-cli.md

@@ -0,0 +1,11 @@
+---
+'@salesforce/b2c-cli': patch
+---
+
+CLI cleanup and correctness fixes:
+
+- `b2c cip query`, `cip describe`, `cip tables`, and `cip report *` now stream output through oclif's `ux.stdout` instead of writing directly to `process.stdout`. This restores the `--json` flag and makes output capturable by tests and CI.
+- Long-running commands (`code:watch`, `logs:tail`, `mrt:tail-logs`) now deregister their SIGINT/SIGTERM handlers when finished, so re-invocations no longer stack handlers on the same process.
+- Hook and signal-handler errors that were previously swallowed (`job:run` afterOperation hooks, `logs:tail` stop, `setup:ide:prophet` console fallbacks) now log at debug instead of disappearing.
+- AM list commands (`am clients|roles|users list`) share a single `amPageSizeFlag` definition.
+- Removed deprecated `LocalSourceResult` re-export.

.changeset/audit-cleanup-mcp.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/b2c-dx-mcp': patch
+---
+
+- Telemetry send failures are no longer silently swallowed; they now log at debug level so deployment-monitoring drift is visible behind the `--debug` flag.
+- `registerToolsets()` throws a clear error if invoked more than once for the same server instance (instead of producing a cryptic duplicate-tool error from the SDK).

.changeset/audit-cleanup-mrt.md

@@ -0,0 +1,6 @@
+---
+'@salesforce/mrt-utilities': patch
+---
+
+- The Lambda response adapter's `pipeToDestination` now destroys the destination stream when the underlying pipeline rejects, so consumers fail fast instead of hanging.
+- `pipedDestinations` cleanup is unified between the success and error paths.

.changeset/audit-cleanup-sdk.md

@@ -0,0 +1,13 @@
+---
+'@salesforce/b2c-tooling-sdk': patch
+---
+
+Hardened auth and long-running operation paths:
+
+- Token store now writes atomically (temp file + rename) so concurrent CLI invocations cannot corrupt `auth-session.json`.
+- `OAuthStrategy.getAccessToken()` coalesces concurrent refreshes onto a single in-flight request, preventing token-endpoint stampedes.
+- Debug session cleans up its keepalive/poll timers if `connect()` fails after starting them.
+- `downloadCartridges` and `deployCartridges` use try/finally around progress timers so an aborted or failing request can no longer leak intervals.
+- New `@salesforce/b2c-tooling-sdk/ux` export surfaces the canonical `confirm()` prompt; CLI re-exports from here.
+- New `auth/jwt-utils` consolidates JWT `exp`/`scope` decoding previously duplicated across three auth strategies.
+- Better error message when the implicit-OAuth port is already in use (suggests `SFCC_OAUTH_LOCAL_PORT`).

.changeset/audit-cleanup-vsx.md

@@ -0,0 +1,9 @@
+---
+'b2c-vs-extension': patch
+---
+
+VS Code extension reliability fixes:
+
+- Swagger API Browser webview no longer attempts `postMessage` after the panel has been disposed (previously could throw on token refresh or proxy responses arriving after close).
+- Sandbox tree polling no longer stacks "stop-check" timers when the configured polling interval is shorter than the 3-second stabilization window.
+- Code Sync now drains pending uploads/deletes before tearing down its file watchers, so saves immediately preceding a stop are no longer dropped.

packages/b2c-cli/src/commands/am/clients/list.ts

@@ -7,6 +7,7 @@ import {Flags, Errors} from '@oclif/core';
 import {AmCommand, TableRenderer, type ColumnDef} from '@salesforce/b2c-tooling-sdk/cli';
 import type {AccountManagerApiClient, APIClientCollection} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../../i18n/index.js';
+import {amPageSizeFlag} from '../../../utils/am/flags.js';
 
 /** Format date as MM/DD/YYYY HH:MM:SS with zero-padding for equal column width. */
 function formatDateEqualLength(value: Date | number | string): string {
@@ -75,10 +76,7 @@ export default class ClientList extends AmCommand<typeof ClientList> {
   ];
 
   static flags = {
-    size: Flags.integer({
-      char: 's',
-      description: 'Page size (default: 20, min: 1, max: 4000)',
-    }),
+    size: amPageSizeFlag,
     page: Flags.integer({
       description: 'Page number (zero-based index, default: 0, min: 0)',
     }),

packages/b2c-cli/src/commands/am/roles/list.ts

@@ -7,6 +7,7 @@ import {Flags, Errors} from '@oclif/core';
 import {AmCommand, TableRenderer, type ColumnDef} from '@salesforce/b2c-tooling-sdk/cli';
 import type {AccountManagerRole, RoleCollection} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../../i18n/index.js';
+import {amPageSizeFlag} from '../../../utils/am/flags.js';
 
 const COLUMNS: Record<string, ColumnDef<AccountManagerRole>> = {
   id: {
@@ -64,10 +65,7 @@ export default class RoleList extends AmCommand<typeof RoleList> {
   ];
 
   static flags = {
-    size: Flags.integer({
-      char: 's',
-      description: 'Page size (default: 20, min: 1, max: 4000)',
-    }),
+    size: amPageSizeFlag,
     page: Flags.integer({
       description: 'Page number (zero-based index, default: 0, min: 0)',
     }),

packages/b2c-cli/src/commands/am/users/list.ts

@@ -7,6 +7,7 @@ import {Flags, Errors} from '@oclif/core';
 import {AmCommand, TableRenderer, type ColumnDef} from '@salesforce/b2c-tooling-sdk/cli';
 import type {AccountManagerUser, UserCollection} from '@salesforce/b2c-tooling-sdk';
 import {t} from '../../../i18n/index.js';
+import {amPageSizeFlag} from '../../../utils/am/flags.js';
 
 const COLUMNS: Record<string, ColumnDef<AccountManagerUser>> = {
   mail: {
@@ -89,10 +90,7 @@ export default class UserList extends AmCommand<typeof UserList> {
   ];
 
   static flags = {
-    size: Flags.integer({
-      char: 's',
-      description: 'Page size (default: 20, min: 1, max: 4000)',
-    }),
+    size: amPageSizeFlag,
     page: Flags.integer({
       description: 'Page number (zero-based index, default: 0, min: 0)',
     }),

packages/b2c-cli/src/commands/cip/describe.ts

@@ -8,7 +8,7 @@ import {Args, Flags} from '@oclif/core';
 import {describeCipTable} from '@salesforce/b2c-tooling-sdk';
 import {withDocs} from '../../i18n/index.js';
 import {CipCommand} from '../../utils/cip/command.js';
-import {renderTable, toCsv, type CipOutputFormat} from '../../utils/cip/format.js';
+import {renderTable, writeCsv, writeJson, type CipOutputFormat} from '../../utils/cip/format.js';
 
 const {from: _unusedFrom, to: _unusedTo, ...cipMetadataFlags} = CipCommand.baseFlags;
 
@@ -77,7 +77,7 @@ export default class CipDescribe extends CipCommand<typeof CipDescribe> {
     }
 
     if (this.flags.format === 'json') {
-      process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+      writeJson(output);
       return output;
     }
 
@@ -88,7 +88,7 @@ export default class CipDescribe extends CipCommand<typeof CipDescribe> {
   private renderRows(rows: CipDescribeCommandResult['columns'], format: CipOutputFormat): void {
     const columns = ['column', 'dataType', 'isNullable'];
     if (format === 'csv') {
-      process.stdout.write(`${toCsv(columns, rows)}\n`);
+      writeCsv(columns, rows);
       return;
     }
 

packages/b2c-cli/src/commands/cip/query.ts

@@ -8,7 +8,7 @@ import fs from 'node:fs';
 import {Args, Flags} from '@oclif/core';
 import {withDocs} from '../../i18n/index.js';
 import {CipCommand} from '../../utils/cip/command.js';
-import {renderTable, toCsv, type CipOutputFormat} from '../../utils/cip/format.js';
+import {renderTable, writeCsv, writeJson, type CipOutputFormat} from '../../utils/cip/format.js';
 
 interface CipQueryCommandResult {
   columns: string[];
@@ -56,7 +56,7 @@ export default class CipQuery extends CipCommand<typeof CipQuery> {
     }
 
     if (this.flags.format === 'json') {
-      process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+      writeJson(output);
       return output;
     }
 
@@ -66,7 +66,7 @@ export default class CipQuery extends CipCommand<typeof CipQuery> {
 
   private renderRows(columns: string[], rows: Array<Record<string, unknown>>, format: CipOutputFormat): void {
     if (format === 'csv') {
-      process.stdout.write(`${toCsv(columns, rows)}\n`);
+      writeCsv(columns, rows);
       return;
     }