@tempoxyz/mercator 0.0.887 → 0.0.924

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,7 @@
1
+ import { describeExecutable } from './client-binary.js';
1
2
  import { clientLabel } from './clients.js';
2
3
  import { formatConnectionSummary } from './connection-summary.js';
4
+ import { isAuthorizationPending } from './setup.js';
3
5
  import { FALLBACK_SUGGESTED_QUERIES } from './suggested-queries.js';
4
6
  import { styleText } from './terminal-style.js';
5
7
  /** Maximum serialized setup result included in verbose terminal output. */
@@ -35,13 +37,17 @@ export function formatSetupResult(result, color = false, debug, suggestedQueries
35
37
  result.clients.some((client) => client.status === 'conflict' || client.status === 'skipped') ||
36
38
  ('marketplacePlugins' in result &&
37
39
  Boolean(result.marketplacePlugins?.some((plugin) => plugin.status === 'skipped')));
40
+ // Client OAuth is completed in each client; an unauthorized CLI alone is not a failure.
41
+ const authorizationPending = isAuthorizationPending(result);
38
42
  const title = result.dryRun
39
43
  ? 'Mercator setup preview — no changes made.'
40
44
  : result.ready && !hasWarnings
41
45
  ? 'Mercator setup complete.'
42
46
  : result.ready
43
47
  ? 'Mercator setup complete with warnings.'
44
- : 'Mercator setup needs attention.';
48
+ : authorizationPending && !hasWarnings
49
+ ? 'Mercator setup complete — authorization pending.'
50
+ : 'Mercator setup needs attention.';
45
51
  const lines = [styleText(title, 'bold', color)];
46
52
  const integrations = [];
47
53
  for (const client of result.clients) {
@@ -60,7 +66,10 @@ export function formatSetupResult(result, color = false, debug, suggestedQueries
60
66
  ? 'updated'
61
67
  : humanizeStatus(client.status);
62
68
  integrations.push(formatSetupRow(glyph, `${clientLabel(client.client)} MCP`, status, color));
63
- if (client.action)
69
+ if (client.executable)
70
+ integrations.push(` Using ${describeExecutable(client.executable)}`);
71
+ // Authorization guidance for written registrations is listed under Client readiness.
72
+ if (client.action && !client.readiness)
64
73
  integrations.push(` ${client.action}`);
65
74
  }
66
75
  if ('plugin' in result && result.plugin) {
@@ -116,6 +125,19 @@ export function formatSetupResult(result, color = false, debug, suggestedQueries
116
125
  if (integrations.length > 0) {
117
126
  lines.push('', styleText('Integrations', 'bold', color), ...integrations);
118
127
  }
128
+ const clientReadiness = result.clients.flatMap((client) => {
129
+ if (!client.readiness)
130
+ return [];
131
+ const pending = client.readiness === 'authorization_pending';
132
+ return [
133
+ formatSetupRow(pending ? '○' : '✓', clientLabel(client.client), pending ? 'registration written; authorization pending' : 'registration written', color),
134
+ ...(client.activation ? [` Activate: ${client.activation}`] : []),
135
+ ...(pending && client.action ? [` Authorize: ${client.action}`] : []),
136
+ ];
137
+ });
138
+ if (clientReadiness.length > 0) {
139
+ lines.push('', styleText('Client readiness', 'bold', color), ...clientReadiness);
140
+ }
119
141
  const readiness = [];
120
142
  const clientOnly = 'clientOnly' in result && result.clientOnly;
121
143
  if ('nativePayments' in result) {
@@ -207,23 +229,22 @@ export function formatSetupResult(result, color = false, debug, suggestedQueries
207
229
  ? 'Resolve AGENTS.override.md shadowing before starting a new Codex session to load the updated AGENTS.md guidance.'
208
230
  : 'Start a new Codex session to load the updated AGENTS.md guidance.');
209
231
  }
210
- for (const client of result.clients) {
211
- if ((client.client === 'claude' || client.client === 'codex') &&
212
- (client.status === 'configured' || client.status === 'reconfigured')) {
213
- lines.push(`If the updated MCP registration is missing in ${clientLabel(client.client)}, restart that client (fully quit and reopen the desktop app), then authorize Mercator. Plugin reload alone may not load standalone MCP configuration.`);
214
- }
215
- }
216
232
  if (!result.ready) {
217
233
  lines.push('', 'Your completed setup was preserved.', '', ...(clientOnly
218
234
  ? [
219
235
  'Verify the connection in the selected client with search_services and get_connection_status.',
220
236
  ]
221
- : 'diagnosis' in result && result.diagnosis.authorization === 'required'
237
+ : authorizationPending
222
238
  ? [
223
- 'Retry CLI login and readiness checks in an interactive terminal:',
224
- ' mercator setup',
239
+ 'Authorize Mercator in each configured client or plugin, then call get_connection_status there.',
240
+ 'To also use the Mercator CLI, run mercator login. It creates a separate access key that can spend.',
225
241
  ]
226
- : ['Retry readiness checks:', ' mercator doctor']));
242
+ : 'diagnosis' in result && result.diagnosis.authorization === 'required'
243
+ ? [
244
+ 'Retry CLI login and readiness checks in an interactive terminal:',
245
+ ' mercator setup --login',
246
+ ]
247
+ : ['Retry readiness checks:', ' mercator doctor']));
227
248
  return appendDebugContext(lines.join('\n'), result, debug, color);
228
249
  }
229
250
  const everythingCurrent = !claudeSkillsReload &&
@@ -19,8 +19,9 @@ export function setupArguments(options) {
19
19
  'setup',
20
20
  ...(options.update === false ? ['--no-update'] : []),
21
21
  ...options.client.flatMap((client) => ['--client', client]),
22
+ ...(options.codexPath ? ['--codex-path', options.codexPath] : []),
22
23
  ...['agents', 'plugin', 'skill', 'color'].map((key) => options[key] ? `--${key}` : `--no-${key}`),
23
- ...['dryRun', 'force', 'manual', 'removeAgents', 'verbose', 'yes']
24
+ ...['dryRun', 'force', 'login', 'manual', 'removeAgents', 'verbose', 'yes']
24
25
  .filter((key) => options[key])
25
26
  .map((key) => `--${key.replace(/[A-Z]/g, (value) => `-${value.toLowerCase()}`)}`),
26
27
  '--url',
package/dist/setup.d.ts CHANGED
@@ -1,6 +1,7 @@
1
1
  import type { installCodexAgents, removeCodexAgents } from './agents.js';
2
2
  import type { inspectClaudeRegistrations } from './claude-registrations.js';
3
3
  import type { ClaudeSkills, installClaudeSkills } from './claude-skills.js';
4
+ import { type ClientExecutable, type resolveClientExecutable } from './client-binary.js';
4
5
  import type { prepareSetupPlan } from './client-capabilities.js';
5
6
  import type { selectSetupClients } from './client-selection.js';
6
7
  import { type ClientId, type configurationState, type installedClients, type mergeConfigFile, type removeConfigFile } from './clients.js';
@@ -37,6 +38,8 @@ export type SetupDependencies = {
37
38
  diagnose: typeof diagnose;
38
39
  loginMcp: typeof loginMcp;
39
40
  mcpFetch: typeof mcpFetch;
41
+ /** Selects client executables; omitted, setup runs each client command from PATH. */
42
+ resolveClientExecutable?: typeof resolveClientExecutable | undefined;
40
43
  };
41
44
  /** Validated controls passed from CLI parsing into setup orchestration. */
42
45
  export type SetupOptions = {
@@ -45,9 +48,16 @@ export type SetupOptions = {
45
48
  refresh?: boolean;
46
49
  agents: boolean;
47
50
  client: ClientId[];
51
+ /** Absolute Codex executable that overrides discovery for this invocation. */
52
+ codexPath?: string | undefined;
48
53
  color: boolean;
49
54
  dryRun: boolean;
50
55
  force: boolean;
56
+ /**
57
+ * Also authorize the Mercator CLI during readiness checks. Off by default: CLI login mints a
58
+ * separate spending access key, and agent clients authorize independently.
59
+ */
60
+ login?: boolean;
51
61
  manual?: boolean;
52
62
  plugin: boolean;
53
63
  removeAgents: boolean;
@@ -96,6 +106,12 @@ export declare function setup(options: SetupOptions, dependencies: SetupDependen
96
106
  agents?: import("./agents.js").CodexAgentsInstallResult;
97
107
  clients: {
98
108
  action?: string;
109
+ /** Steps that load a newly written registration. */
110
+ activation?: string;
111
+ /** Selected client executable, when setup runs that client's CLI. */
112
+ executable?: ClientExecutable;
113
+ /** Whether the client still needs its own OAuth before use. */
114
+ readiness?: 'authorization_pending' | 'registration_written';
99
115
  client: ClientId;
100
116
  status: 'already_configured' | 'configured' | 'conflict' | 'planned' | 'reconfigured' | 'skipped';
101
117
  }[];
@@ -111,6 +127,7 @@ export declare function setup(options: SetupOptions, dependencies: SetupDependen
111
127
  } | {
112
128
  manual?: never;
113
129
  cancelled?: never;
130
+ authorizationPending?: true;
114
131
  agents?: {
115
132
  path: string;
116
133
  shadowed: boolean;
@@ -119,6 +136,12 @@ export declare function setup(options: SetupOptions, dependencies: SetupDependen
119
136
  };
120
137
  clients: {
121
138
  action?: string;
139
+ /** Steps that load a newly written registration. */
140
+ activation?: string;
141
+ /** Selected client executable, when setup runs that client's CLI. */
142
+ executable?: ClientExecutable;
143
+ /** Whether the client still needs its own OAuth before use. */
144
+ readiness?: 'authorization_pending' | 'registration_written';
122
145
  client: ClientId;
123
146
  status: 'already_configured' | 'configured' | 'conflict' | 'planned' | 'reconfigured' | 'skipped';
124
147
  }[];
@@ -134,5 +157,10 @@ export declare function setup(options: SetupOptions, dependencies: SetupDependen
134
157
  ready: boolean;
135
158
  warnings: string[];
136
159
  }>;
160
+ /**
161
+ * True when setup finished and only OAuth remains: the endpoint answered with an authorization
162
+ * challenge that setup was not asked to complete (no `--login`). Each client authorizes itself.
163
+ */
164
+ export declare function isAuthorizationPending(result: SetupResult): boolean;
137
165
  /** Records the structured result independently of terminal presentation. */
138
166
  export declare function recordSetupResult(telemetry: SetupTelemetry, result: SetupResult): void;
package/dist/setup.js CHANGED
@@ -1,5 +1,6 @@
1
1
  import packageMetadata from '../package.json' with { type: 'json' };
2
- import { clientAuthorizationGuidance } from './client-authorization.js';
2
+ import { clientActivationGuidance, clientAuthorizationGuidance, clientReadiness, shellCommand, } from './client-authorization.js';
3
+ import { describeExecutable, executableOverrideVariable, guidanceExecutable, } from './client-binary.js';
3
4
  import { clientEndpoint, isProtectedMcpEndpoint } from './client-endpoint.js';
4
5
  import { Client, clientIntegrationLabel, clientLabel, removalPlan, setupPlan, } from './clients.js';
5
6
  import { SetupTelemetryEvent } from './setup-telemetry.js';
@@ -119,6 +120,55 @@ export async function setup(options, dependencies, progress, telemetry, diagnost
119
120
  if (clients.length === 0 && !options.plugin && !(options.refresh && options.agents)) {
120
121
  warnings.push('No integration target is available. Run mercator setup --manual for generic MCP/OAuth instructions, install a supported client and rerun, or rerun without --no-plugin for the Codex/ChatGPT desktop plugin.');
121
122
  }
123
+ const executables = new Map();
124
+ const resolutionFailures = new Map();
125
+ const resolveExecutable = dependencies.resolveClientExecutable;
126
+ if (resolveExecutable) {
127
+ await Promise.all(clients.map(async (client) => {
128
+ if (setupPlan(client, clientEndpoint(client, options.url)).kind !== 'command')
129
+ return;
130
+ const resolution = await resolveExecutable(client, client === Client.Codex && options.codexPath
131
+ ? { flagPath: options.codexPath }
132
+ : {});
133
+ if (resolution.status === 'missing') {
134
+ detectedStates.set(client, 'unavailable');
135
+ return;
136
+ }
137
+ if (resolution.status === 'invalid_override') {
138
+ resolutionFailures.set(client, `${resolution.path} is not an absolute path to an executable. Fix ${client === Client.Codex ? '--codex-path or ' : ''}${executableOverrideVariable(client)} and rerun mercator setup --client ${client}.`);
139
+ return;
140
+ }
141
+ if (resolution.status === 'incompatible') {
142
+ const found = resolution.candidates
143
+ .map((candidate) => candidate.version
144
+ ? describeExecutable(candidate)
145
+ : `${candidate.path} (version unknown)`)
146
+ .join(', ');
147
+ resolutionFailures.set(client, `${clientLabel(client)} ${resolution.minimumVersion} or newer is required for Mercator OAuth; found ${found}. Update ${clientLabel(client)}, or ${client === Client.Codex ? 'pass --codex-path <path> or ' : ''}set ${executableOverrideVariable(client)} to a newer executable, then rerun mercator setup --client ${client}.`);
148
+ return;
149
+ }
150
+ executables.set(client, resolution.executable);
151
+ progress?.report(`Using ${clientLabel(client)} at ${describeExecutable(resolution.executable)}.`);
152
+ // A rejected PATH binary still answers the bare command in the user's shell.
153
+ for (const rejected of resolution.rejected ?? [])
154
+ warnings.push(`${clientLabel(client)} at ${describeExecutable(rejected)} is older than ${resolution.minimumVersion} and fails Mercator OAuth. Setup used ${resolution.executable.path}; run authorization with that path or update the older install.`);
155
+ if (resolution.belowMinimum)
156
+ warnings.push(`${clientLabel(client)} override ${describeExecutable(resolution.executable)} is older than ${resolution.minimumVersion}; OAuth may fail. Using it because it was selected explicitly.`);
157
+ }));
158
+ }
159
+ const inspectClaude = (endpoint) => {
160
+ const path = executables.get(Client.Claude)?.path;
161
+ return path
162
+ ? dependencies.inspectClaudeRegistrations(endpoint, undefined, path)
163
+ : dependencies.inspectClaudeRegistrations(endpoint);
164
+ };
165
+ const planFor = (client) => {
166
+ const executable = executables.get(client);
167
+ return setupPlan(client, clientEndpoint(client, options.url), executable ? { executable: executable.path } : {});
168
+ };
169
+ for (const [client, action] of resolutionFailures)
170
+ clientResults.push({ action, client, status: 'skipped' });
171
+ clients = clients.filter((client) => !resolutionFailures.has(client));
122
172
  const inspectionErrors = new Map();
123
173
  const uncheckedClients = clients.filter((client) => !detectedStates.has(client));
124
174
  if (uncheckedClients.length > 0) {
@@ -129,7 +179,7 @@ export async function setup(options, dependencies, progress, telemetry, diagnost
129
179
  reportPending();
130
180
  await Promise.all(uncheckedClients.map(async (client) => {
131
181
  try {
132
- const plan = setupPlan(client, clientEndpoint(client, options.url));
182
+ const plan = planFor(client);
133
183
  const state = await runDiagnostic(diagnostics, diagnosticOperation('client-inspection', client, plan), () => dependencies.configurationState(plan));
134
184
  detectedStates.set(client, state);
135
185
  diagnostics?.info({ client, phase: 'client-state', state });
@@ -180,8 +230,8 @@ export async function setup(options, dependencies, progress, telemetry, diagnost
180
230
  try {
181
231
  registration =
182
232
  client === Client.Claude
183
- ? await dependencies.inspectClaudeRegistrations(clientEndpoint(client, options.url))
184
- : await dependencies.inspectCodexRegistrations();
233
+ ? await inspectClaude(clientEndpoint(client, options.url))
234
+ : await dependencies.inspectCodexRegistrations(undefined, undefined, executables.get(Client.Codex)?.path);
185
235
  }
186
236
  catch {
187
237
  registration = {
@@ -306,14 +356,17 @@ export async function setup(options, dependencies, progress, telemetry, diagnost
306
356
  }
307
357
  for (const client of clients) {
308
358
  const endpoint = clientEndpoint(client, options.url);
309
- let plan = setupPlan(client, endpoint);
359
+ let plan = planFor(client);
310
360
  const state = detectedStates.get(client);
311
- const authorizationAction = clientAuthorizationGuidance(client, endpoint);
361
+ const executable = executables.get(client);
362
+ const authorizationAction = clientAuthorizationGuidance(client, endpoint, guidanceExecutable(executable));
363
+ const selected = executable ? { executable } : {};
364
+ const readiness = { readiness: clientReadiness(client, endpoint) };
312
365
  if (state === undefined)
313
366
  throw new Error(`${client}: MCP state was not inspected.`);
314
367
  if (client === Client.Claude && !(options.dryRun && state === 'unavailable')) {
315
368
  try {
316
- const registration = await dependencies.inspectClaudeRegistrations(endpoint);
369
+ const registration = await inspectClaude(endpoint);
317
370
  if (registration.kind === 'conflict') {
318
371
  clientResults.push({ client, status: 'conflict', action: registration.action });
319
372
  continue;
@@ -340,6 +393,8 @@ export async function setup(options, dependencies, progress, telemetry, diagnost
340
393
  if (state === 'current' && !options.force) {
341
394
  clientResults.push({
342
395
  ...(authorizationAction ? { action: authorizationAction } : {}),
396
+ ...selected,
397
+ ...readiness,
343
398
  client,
344
399
  status: 'already_configured',
345
400
  });
@@ -367,6 +422,7 @@ export async function setup(options, dependencies, progress, telemetry, diagnost
367
422
  action: options.force || state === 'legacy'
368
423
  ? `Recreate the Mercator MCP registration, then run: ${describeSetupPlan(plan)}`
369
424
  : describeSetupPlan(plan),
425
+ ...selected,
370
426
  client,
371
427
  status: 'planned',
372
428
  });
@@ -376,7 +432,7 @@ export async function setup(options, dependencies, progress, telemetry, diagnost
376
432
  await runDiagnostic(diagnostics, diagnosticOperation('client-configuration', client, plan), async () => {
377
433
  if (replaceExisting && state !== 'missing') {
378
434
  progress?.report(`Removing existing ${client} MCP registration...`);
379
- await removeClientConfiguration(client, dependencies, diagnostics);
435
+ await removeClientConfiguration(client, dependencies, diagnostics, executable?.path);
380
436
  }
381
437
  progress?.report(`Configuring ${client} MCP...`);
382
438
  if (plan.kind === 'file')
@@ -395,6 +451,9 @@ export async function setup(options, dependencies, progress, telemetry, diagnost
395
451
  });
396
452
  clientResults.push({
397
453
  ...(authorizationAction ? { action: authorizationAction } : {}),
454
+ activation: clientActivationGuidance(client),
455
+ ...selected,
456
+ ...readiness,
398
457
  client,
399
458
  status: replaceExisting && state !== 'missing' ? 'reconfigured' : 'configured',
400
459
  });
@@ -406,12 +465,12 @@ export async function setup(options, dependencies, progress, telemetry, diagnost
406
465
  !options.refresh) {
407
466
  try {
408
467
  progress?.report('Authorize OpenClaw in Tempo Wallet...');
409
- await dependencies.runCommand('openclaw', ['mcp', 'login', 'mercator'], {
468
+ await dependencies.runCommand(executable?.path ?? 'openclaw', ['mcp', 'login', 'mercator'], {
410
469
  timeoutMs: 10 * 60_000,
411
470
  });
412
471
  }
413
472
  catch {
414
- warnings.push('OpenClaw configuration was saved, but OAuth login did not complete. Run openclaw mcp login mercator to retry.');
473
+ warnings.push(`OpenClaw configuration was saved, but OAuth login did not complete. Run ${shellCommand(guidanceExecutable(executable) ?? 'openclaw')} mcp login mercator to retry.`);
415
474
  }
416
475
  }
417
476
  }
@@ -469,7 +528,7 @@ export async function setup(options, dependencies, progress, telemetry, diagnost
469
528
  try {
470
529
  const diagnosticEndpoints = new Set(clients.map((client) => clientEndpoint(client, options.url)));
471
530
  const diagnosticEndpoint = diagnosticEndpoints.size === 1 ? [...diagnosticEndpoints][0] : options.url;
472
- diagnosis = await runDiagnostic(diagnostics, { phase: 'readiness' }, () => diagnoseWithoutWallet(diagnosticEndpoint ?? options.url, dependencies, progress, diagnostics, Boolean(options.interactive && !options.yes && !options.refresh), !clientOnly));
531
+ diagnosis = await runDiagnostic(diagnostics, { phase: 'readiness' }, () => diagnoseWithoutWallet(diagnosticEndpoint ?? options.url, dependencies, progress, diagnostics, Boolean(options.login && options.interactive && !options.yes && !options.refresh), !clientOnly || Boolean(options.login), Boolean(options.login)));
473
532
  diagnostics?.info({
474
533
  phase: 'readiness-result',
475
534
  state: diagnosis.ready ? 'ready' : 'failed',
@@ -493,7 +552,18 @@ export async function setup(options, dependencies, progress, telemetry, diagnost
493
552
  const integrationReady = (agents !== undefined && agents.state !== 'planned' && !agents.shadowed) ||
494
553
  plugin !== undefined ||
495
554
  clientResults.some((client) => ['already_configured', 'configured', 'reconfigured'].includes(client.status));
555
+ const otherwiseReady = (!(options.plugin && options.skill && clients.includes(Client.Claude)) ||
556
+ claudeSkills?.skillInstalled === true) &&
557
+ nativePaymentClients.length === 0 &&
558
+ (integrationReady || marketplacePlugins.some(({ status }) => status === 'configured'));
559
+ // Only client OAuth remains: the endpoint challenged, no CLI login was requested, and every
560
+ // other readiness condition (skills, native payments, an integration) holds.
561
+ const authorizationPending = otherwiseReady &&
562
+ diagnosis.report.transport === 'ready' &&
563
+ diagnosis.report.authorization === 'required' &&
564
+ diagnosis.report.error === undefined;
496
565
  return {
566
+ ...(authorizationPending ? { authorizationPending: true } : {}),
497
567
  ...(agents
498
568
  ? {
499
569
  agents: {
@@ -510,15 +580,17 @@ export async function setup(options, dependencies, progress, telemetry, diagnost
510
580
  ...(plugin ? { plugin } : {}),
511
581
  ...(marketplacePlugins.length > 0 ? { marketplacePlugins } : {}),
512
582
  ...(claudeSkills ? { claudeSkills } : {}),
513
- ready: diagnosis.ready &&
514
- (!(options.plugin && options.skill && clients.includes(Client.Claude)) ||
515
- claudeSkills?.skillInstalled === true) &&
516
- nativePaymentClients.length === 0 &&
517
- (integrationReady ||
518
- marketplacePlugins.some(({ status }) => status === 'configured')),
583
+ ready: diagnosis.ready && otherwiseReady,
519
584
  warnings,
520
585
  };
521
586
  }
587
+ /**
588
+ * True when setup finished and only OAuth remains: the endpoint answered with an authorization
589
+ * challenge that setup was not asked to complete (no `--login`). Each client authorizes itself.
590
+ */
591
+ export function isAuthorizationPending(result) {
592
+ return 'authorizationPending' in result && result.authorizationPending === true;
593
+ }
522
594
  /** Records the structured result independently of terminal presentation. */
523
595
  export function recordSetupResult(telemetry, result) {
524
596
  if ('manual' in result && result.manual) {
@@ -529,6 +601,8 @@ export function recordSetupResult(telemetry, result) {
529
601
  telemetry.record({ event: SetupTelemetryEvent.ReadinessChecked, outcome: 'skipped' }, { event: SetupTelemetryEvent.SetupFinished, outcome: 'cancelled' });
530
602
  return;
531
603
  }
604
+ // Client OAuth happens after setup; an unauthorized CLI is not a failed setup.
605
+ const pending = isAuthorizationPending(result);
532
606
  const incomplete = result.warnings.length > 0 ||
533
607
  result.clients.some(({ status }) => ['conflict', 'skipped'].includes(status)) ||
534
608
  ('marketplacePlugins' in result &&
@@ -539,12 +613,12 @@ export function recordSetupResult(telemetry, result) {
539
613
  outcome,
540
614
  })), {
541
615
  event: SetupTelemetryEvent.ReadinessChecked,
542
- outcome: result.dryRun ? 'skipped' : result.ready ? 'ready' : 'failed',
616
+ outcome: result.dryRun || pending ? 'skipped' : result.ready ? 'ready' : 'failed',
543
617
  }, {
544
618
  event: SetupTelemetryEvent.SetupFinished,
545
619
  outcome: result.dryRun
546
620
  ? 'planned'
547
- : result.ready && !incomplete
621
+ : (result.ready || pending) && !incomplete
548
622
  ? 'succeeded'
549
623
  : 'partial',
550
624
  });
@@ -552,9 +626,9 @@ export function recordSetupResult(telemetry, result) {
552
626
  /** Native hosts own credentials; setup never claims their grants were verified. */
553
627
  function unavailableClientGuidance(client) {
554
628
  if (client === Client.Codex) {
555
- return 'Codex CLI is not available on PATH. Install it, then rerun mercator setup --client codex; the desktop plugin can still be installed without it.';
629
+ return 'Codex CLI was not found on PATH or in the ChatGPT/Codex app bundle. Install it or pass --codex-path, then rerun mercator setup --client codex; the desktop plugin can still be installed without it.';
556
630
  }
557
- return `${clientLabel(client)} is not available on PATH. Install its CLI and rerun, or omit --client ${client} to auto-detect available clients.`;
631
+ return `${clientLabel(client)} is not available on PATH. Install its CLI and rerun, set ${executableOverrideVariable(client)} to its executable, or omit --client ${client} to auto-detect available clients.`;
558
632
  }
559
633
  function errorMessage(error) {
560
634
  return error instanceof Error ? error.message : String(error);
@@ -581,8 +655,8 @@ function setupConfirmationActions(clients, options) {
581
655
  }
582
656
  return actions;
583
657
  }
584
- async function removeClientConfiguration(client, dependencies, diagnostics) {
585
- const removal = removalPlan(client);
658
+ async function removeClientConfiguration(client, dependencies, diagnostics, executable) {
659
+ const removal = removalPlan(client, executable ? { executable } : {});
586
660
  if (removal.kind === 'manual') {
587
661
  throw new Error(`${client}: Cannot force setup automatically. ${removal.instructions}`);
588
662
  }
@@ -604,7 +678,7 @@ function describeSetupPlan(plan) {
604
678
  : `Update ${plan.path}`;
605
679
  }
606
680
  /** Checks remote MCP readiness without requiring a local payment wallet. */
607
- async function diagnoseWithoutWallet(endpoint, dependencies, progress, diagnostics, interactive = false, useCliSession = true) {
681
+ async function diagnoseWithoutWallet(endpoint, dependencies, progress, diagnostics, interactive = false, useCliSession = true, loginRequested = false) {
608
682
  const protectedEndpoint = isProtectedMcpEndpoint(endpoint);
609
683
  let fetcher;
610
684
  if (protectedEndpoint && useCliSession) {
@@ -643,6 +717,28 @@ async function diagnoseWithoutWallet(endpoint, dependencies, progress, diagnosti
643
717
  progress?.resumeAfterPrompt?.();
644
718
  }
645
719
  diagnosed = await diagnose();
720
+ // An explicitly requested CLI login that still leaves the endpoint unauthorized failed.
721
+ if (diagnosed.authorization === 'required')
722
+ return {
723
+ ready: false,
724
+ report: { ...diagnosed, error: 'CLI login did not authorize this endpoint.' },
725
+ };
726
+ }
727
+ if (protectedEndpoint && diagnosed.authorization === 'required' && loginRequested)
728
+ // --login was requested but --yes, refresh, or a missing terminal prevented it.
729
+ return {
730
+ ready: false,
731
+ report: {
732
+ ...diagnosed,
733
+ error: 'CLI login needs an interactive terminal; rerun mercator setup --login without --yes.',
734
+ },
735
+ };
736
+ if (protectedEndpoint && diagnosed.authorization === 'required') {
737
+ // Without --login an OAuth challenge is the expected state, not a failure: doctor's
738
+ // "run mercator login" error would push users to mint a separate spending key.
739
+ const pending = { ...diagnosed };
740
+ delete pending.error;
741
+ return { ready: false, report: pending };
646
742
  }
647
743
  const remoteReady = diagnosed.transport === 'ready' &&
648
744
  diagnosed.discovery === 'ready' &&
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tempoxyz/mercator",
3
- "version": "0.0.887",
3
+ "version": "0.0.924",
4
4
  "description": "Connect agent clients to the Mercator remote MCP server",
5
5
  "type": "module",
6
6
  "bin": {