@tempoxyz/mercator 0.0.265 → 0.0.283

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.
package/dist/index.js CHANGED
@@ -1,6 +1,7 @@
1
- import { Cli, z } from 'incur';
1
+ import { Binary, Cli, z } from 'incur';
2
2
  import packageMetadata from '../package.json' with { type: 'json' };
3
3
  import { installCodexAgents, removeCodexAgents } from './agents.js';
4
+ import { ClaimProvider, claimMach, WalletClaimError } from './claim.js';
4
5
  import { CLIENT_IDS, Client, clientLabel, configurationState, installedClients, mergeConfigFile, removalPlan, removeConfigFile, setupPlan, } from './clients.js';
5
6
  import { inspectCodexPlugin, installCodexPlugin, removeCodexPlugin, } from './codex-plugin.js';
6
7
  import { runInteractiveCommand } from './command.js';
@@ -9,9 +10,10 @@ import { setupNativePayments } from './native-payments.js';
9
10
  import { confirmSetup } from './setup-confirmation.js';
10
11
  import { startTerminalSetupProgress } from './setup-progress.js';
11
12
  import { SubmitError, submitPaidJob } from './submit.js';
12
- import { inspectWallet, openFundingPage, setupWallet, WalletRequiredError, } from './wallet.js';
13
+ import { inspectWallet, listWallets, openFundingPage, setupWallet, useWallet, WalletProvider, WalletRequiredError, } from './wallet.js';
13
14
  const DEFAULT_ENDPOINT = 'https://mercator.tempo.xyz/mcp';
14
15
  const defaultDependencies = {
16
+ claimMach,
15
17
  confirmSetup,
16
18
  configurationState,
17
19
  diagnose,
@@ -19,6 +21,7 @@ const defaultDependencies = {
19
21
  installCodexAgents,
20
22
  installCodexPlugin,
21
23
  inspectWallet,
24
+ listWallets,
22
25
  installedClients,
23
26
  mergeConfigFile,
24
27
  removeCodexAgents,
@@ -30,6 +33,7 @@ const defaultDependencies = {
30
33
  startSetupProgress: startTerminalSetupProgress,
31
34
  submitPaidJob,
32
35
  setupWallet,
36
+ useWallet,
33
37
  };
34
38
  const setupOptions = z.object({
35
39
  agents: z
@@ -50,6 +54,10 @@ const setupOptions = z.object({
50
54
  .boolean()
51
55
  .default(false)
52
56
  .describe('Remove managed Codex guidance without running setup'),
57
+ skill: z
58
+ .boolean()
59
+ .default(true)
60
+ .describe('Include the Mercator skill in the plugin; disable with --no-skill'),
53
61
  url: z.url().default(DEFAULT_ENDPOINT).describe('Mercator MCP endpoint'),
54
62
  yes: z.boolean().default(false).describe('Apply setup without confirmation'),
55
63
  });
@@ -70,15 +78,6 @@ export function createMercatorCli(overrides = {}) {
70
78
  finally {
71
79
  await progress?.stop();
72
80
  }
73
- if (!result.ready) {
74
- return context.error({
75
- code: 'SETUP_INCOMPLETE',
76
- exitCode: 1,
77
- message: context.agent
78
- ? `Mercator setup needs attention: ${JSON.stringify(result)}`
79
- : formatSetupResult(result),
80
- });
81
- }
82
81
  return context.agent ? result : formatSetupResult(result);
83
82
  };
84
83
  const runWalletSetup = async (context, action) => {
@@ -92,17 +91,87 @@ export function createMercatorCli(overrides = {}) {
92
91
  }
93
92
  return { ready: true, report };
94
93
  };
94
+ const runWalletClaim = async (context, provider) => {
95
+ const report = await dependencies.inspectWallet();
96
+ if (!report.address || !report.provider || report.sessionClient !== 'ready') {
97
+ return context.error({
98
+ code: 'WALLET_REQUIRED',
99
+ exitCode: 1,
100
+ message: [
101
+ 'Set up a Mercator wallet first:',
102
+ ' mercator wallet create',
103
+ ' mercator wallet connect',
104
+ '',
105
+ 'Then run:',
106
+ ` mercator wallet claim ${provider}`,
107
+ ].join('\n'),
108
+ });
109
+ }
110
+ try {
111
+ return await dependencies.claimMach({ address: report.address, provider });
112
+ }
113
+ catch (error) {
114
+ if (error instanceof WalletClaimError) {
115
+ return context.error({
116
+ code: error.code,
117
+ exitCode: 1,
118
+ message: error.message,
119
+ });
120
+ }
121
+ throw error;
122
+ }
123
+ };
124
+ const claimCommand = Cli.create('claim', {
125
+ description: 'Claim the one-time MACH grant with GitHub or X',
126
+ })
127
+ .command('github', {
128
+ description: 'Claim MACH with GitHub',
129
+ run: async (context) => runWalletClaim(context, ClaimProvider.GitHub),
130
+ })
131
+ .command('x', {
132
+ description: 'Claim MACH with X',
133
+ run: async (context) => runWalletClaim(context, ClaimProvider.X),
134
+ });
95
135
  const walletCommand = Cli.create('wallet', {
96
136
  description: 'Set up or inspect the payment wallet',
97
137
  run: async (context) => runWalletSetup(context),
98
138
  })
99
139
  .command('connect', {
100
- description: 'Connect an existing wallet in the browser',
140
+ description: 'Connect or replace Tempo Wallet in the browser',
101
141
  run: async (context) => runWalletSetup(context, 'connect'),
102
142
  })
103
143
  .command('create', {
104
- description: 'Create a wallet on this machine',
144
+ description: 'Create or activate the local wallet on this machine',
105
145
  run: async (context) => runWalletSetup(context, 'create'),
146
+ })
147
+ .command('list', {
148
+ description: 'List stored wallets; the active wallet pays for jobs',
149
+ run: async () => dependencies.listWallets(),
150
+ })
151
+ .command('use', {
152
+ aliases: ['switch'],
153
+ args: z.object({
154
+ provider: z
155
+ .enum([WalletProvider.Tempo, WalletProvider.Local])
156
+ .describe('Stored wallet provider to activate'),
157
+ }),
158
+ description: 'Use a stored wallet without browser authorization',
159
+ run: async (context) => {
160
+ try {
161
+ const report = await dependencies.useWallet(context.args.provider);
162
+ return { active: context.args.provider, report };
163
+ }
164
+ catch (error) {
165
+ if (error instanceof WalletRequiredError) {
166
+ return context.error({
167
+ code: error.code,
168
+ exitCode: 1,
169
+ message: error.message,
170
+ });
171
+ }
172
+ throw error;
173
+ }
174
+ },
106
175
  })
107
176
  .command('status', {
108
177
  description: 'Show payment wallet readiness without onboarding',
@@ -149,19 +218,20 @@ export function createMercatorCli(overrides = {}) {
149
218
  url: result.url,
150
219
  };
151
220
  },
152
- });
221
+ })
222
+ .command(claimCommand);
153
223
  return Cli.create('mercator', {
154
224
  description: 'Install, diagnose, and remove Mercator agent integrations',
155
225
  examples: [
156
226
  { description: 'Set up Mercator for Codex', options: { client: [Client.Codex] } },
157
227
  ],
158
228
  options: setupOptions,
159
- update: false,
229
+ update: Binary.github({ repository: 'tempoxyz/mercator' }),
160
230
  version: packageMetadata.version,
161
231
  run: async (context) => runSetup(context, context.options),
162
232
  })
163
233
  .command('setup', {
164
- description: 'Install MCP, optional guidance, and MPP payment integrations',
234
+ description: 'Install MCP, optional skill and guidance, and MPP payments',
165
235
  options: setupOptions,
166
236
  run: async (context) => runSetup(context, context.options),
167
237
  })
@@ -239,8 +309,10 @@ export async function run(argv, overrides = {}) {
239
309
  '--force',
240
310
  '--no-agents',
241
311
  '--no-plugin',
312
+ '--no-skill',
242
313
  '--plugin',
243
314
  '--remove-agents',
315
+ '--skill',
244
316
  '--url',
245
317
  '--yes',
246
318
  ]);
@@ -264,6 +336,7 @@ export async function run(argv, overrides = {}) {
264
336
  }
265
337
  async function setup(options, dependencies, progress) {
266
338
  progress?.report(options.dryRun ? 'Preparing setup preview...' : 'Preparing setup...');
339
+ const warnings = [];
267
340
  if (options.removeAgents && !options.agents) {
268
341
  throw new Error('--remove-agents and --no-agents cannot be used together');
269
342
  }
@@ -273,7 +346,13 @@ async function setup(options, dependencies, progress) {
273
346
  if (options.removeAgents) {
274
347
  progress?.report('Removing managed Codex guidance...');
275
348
  const result = await dependencies.removeCodexAgents({ dryRun: options.dryRun });
276
- return { agents: result, clients: [], dryRun: options.dryRun, ready: true };
349
+ return {
350
+ agents: result,
351
+ clients: [],
352
+ dryRun: options.dryRun,
353
+ ready: true,
354
+ warnings,
355
+ };
277
356
  }
278
357
  let clients;
279
358
  let plugin;
@@ -285,7 +364,13 @@ async function setup(options, dependencies, progress) {
285
364
  }
286
365
  else {
287
366
  progress?.report('Detecting installed clients...');
288
- clients = await dependencies.installedClients();
367
+ try {
368
+ clients = await dependencies.installedClients();
369
+ }
370
+ catch (error) {
371
+ clients = [];
372
+ warnings.push(`Agent CLI detection skipped: ${errorMessage(error)}. Select one later with mercator setup --client <client>.`);
373
+ }
289
374
  if (clients.length === 0) {
290
375
  progress?.report('No agent CLI detected.');
291
376
  }
@@ -294,32 +379,71 @@ async function setup(options, dependencies, progress) {
294
379
  }
295
380
  }
296
381
  if (clients.length === 0 && !options.plugin) {
297
- throw new Error('No supported agent CLI detected and local plugin installation is disabled. Install a supported agent CLI or rerun without --no-plugin.');
382
+ warnings.push('No integration target is available. Install a supported agent CLI and rerun, or rerun without --no-plugin for the Codex/ChatGPT desktop plugin.');
298
383
  }
384
+ const inspectionErrors = new Map();
299
385
  const uncheckedClients = clients.filter((client) => !detectedStates.has(client));
300
386
  if (uncheckedClients.length > 0) {
301
387
  progress?.report('Checking existing MCP registrations...');
302
388
  await Promise.all(uncheckedClients.map(async (client) => {
303
- detectedStates.set(client, await dependencies.configurationState(setupPlan(client, options.url)));
389
+ try {
390
+ detectedStates.set(client, await dependencies.configurationState(setupPlan(client, options.url)));
391
+ }
392
+ catch (error) {
393
+ detectedStates.set(client, 'unknown');
394
+ inspectionErrors.set(client, errorMessage(error));
395
+ }
304
396
  }));
305
397
  }
306
- const conflictingClient = clients.find((client) => detectedStates.get(client) === 'different');
307
- if (conflictingClient && !options.dryRun && !options.force) {
308
- const plan = setupPlan(conflictingClient, options.url);
309
- throw new Error(`${conflictingClient}: Mercator is already configured differently. ${plan.undo}, then run this command again.`);
398
+ if (!options.dryRun) {
399
+ const skippedClients = new Set();
400
+ for (const client of clients) {
401
+ const inspectionError = inspectionErrors.get(client);
402
+ if (inspectionError) {
403
+ clientResults.push({
404
+ action: `Could not inspect the existing configuration: ${inspectionError}. Retry with mercator setup --client ${client}.`,
405
+ client,
406
+ status: 'skipped',
407
+ });
408
+ skippedClients.add(client);
409
+ continue;
410
+ }
411
+ if (detectedStates.get(client) === 'unavailable') {
412
+ const guidance = unavailableClientGuidance(client);
413
+ progress?.report(`${guidance} Continuing with other integrations.`);
414
+ clientResults.push({ action: guidance, client, status: 'skipped' });
415
+ skippedClients.add(client);
416
+ }
417
+ }
418
+ clients = clients.filter((client) => !skippedClients.has(client));
310
419
  }
311
420
  if (!options.dryRun && !options.yes) {
312
- const confirmed = await dependencies.confirmSetup(setupConfirmationActions(clients, options), progress ? { globe: progress.globe } : undefined);
421
+ const configurableClients = options.force
422
+ ? clients
423
+ : clients.filter((client) => detectedStates.get(client) !== 'different');
424
+ const confirmed = await dependencies.confirmSetup(setupConfirmationActions(configurableClients, options), progress ? { globe: progress.globe } : undefined);
313
425
  if (!confirmed) {
314
- return { cancelled: true, clients: [], dryRun: false, ready: true };
426
+ return {
427
+ cancelled: true,
428
+ clients: [],
429
+ dryRun: false,
430
+ ready: true,
431
+ warnings,
432
+ };
315
433
  }
316
434
  }
317
435
  if (options.plugin) {
318
436
  progress?.report('Bootstrapping the local desktop plugin...');
319
- plugin = await dependencies.installCodexPlugin({
320
- dryRun: options.dryRun,
321
- packageVersion: packageMetadata.version,
322
- });
437
+ try {
438
+ plugin = await dependencies.installCodexPlugin({
439
+ dryRun: options.dryRun,
440
+ packageVersion: packageMetadata.version,
441
+ skill: options.skill,
442
+ });
443
+ }
444
+ catch (error) {
445
+ warnings.push(`Codex/ChatGPT plugin skipped: ${errorMessage(error)}. Other integrations continued; rerun mercator setup --plugin to retry.`);
446
+ }
323
447
  }
324
448
  for (const client of clients) {
325
449
  const plan = setupPlan(client, options.url);
@@ -349,45 +473,70 @@ async function setup(options, dependencies, progress) {
349
473
  });
350
474
  continue;
351
475
  }
352
- if (options.force && state !== 'missing') {
353
- progress?.report(`Removing existing ${client} MCP registration...`);
354
- await removeClientConfiguration(client, dependencies);
476
+ try {
477
+ if (options.force && state !== 'missing') {
478
+ progress?.report(`Removing existing ${client} MCP registration...`);
479
+ await removeClientConfiguration(client, dependencies);
480
+ }
481
+ progress?.report(`Configuring ${client} MCP...`);
482
+ if (plan.kind === 'file')
483
+ await dependencies.mergeConfigFile(plan);
484
+ else
485
+ await dependencies.runCommand(plan.command, plan.args);
486
+ clientResults.push({
487
+ client,
488
+ status: options.force && state !== 'missing' ? 'reconfigured' : 'configured',
489
+ });
490
+ }
491
+ catch (error) {
492
+ clientResults.push({
493
+ action: `${errorMessage(error)}. Retry with mercator setup --client ${client}.`,
494
+ client,
495
+ status: 'skipped',
496
+ });
355
497
  }
356
- progress?.report(`Configuring ${client} MCP...`);
357
- if (plan.kind === 'file')
358
- await dependencies.mergeConfigFile(plan);
359
- else
360
- await dependencies.runCommand(plan.command, plan.args);
361
- clientResults.push({
362
- client,
363
- status: options.force && state !== 'missing' ? 'reconfigured' : 'configured',
364
- });
365
498
  }
366
499
  let agents;
367
500
  if (options.agents && (plugin !== undefined || clients.includes(Client.Codex))) {
368
501
  progress?.report('Refreshing managed Codex guidance...');
369
- agents = await dependencies.installCodexAgents({ dryRun: options.dryRun });
502
+ try {
503
+ agents = await dependencies.installCodexAgents({ dryRun: options.dryRun });
504
+ }
505
+ catch (error) {
506
+ warnings.push(`Codex guidance skipped: ${errorMessage(error)}. MCP access is unaffected; rerun mercator setup --agents to retry.`);
507
+ }
370
508
  }
371
509
  progress?.report('Checking native payment integrations...');
372
- const nativePayments = await dependencies.setupNativePayments(clients, {
373
- dryRun: options.dryRun || options.force,
374
- endpoint: options.url,
375
- });
510
+ let nativePayments = [];
511
+ try {
512
+ nativePayments = await dependencies.setupNativePayments(clients, {
513
+ dryRun: options.dryRun || options.force,
514
+ endpoint: options.url,
515
+ });
516
+ }
517
+ catch (error) {
518
+ warnings.push(`Native payment setup skipped: ${errorMessage(error)}. Free operations remain available; rerun mercator setup to retry.`);
519
+ }
376
520
  const hasGenericClient = plugin !== undefined ||
377
521
  clients.some((client) => client !== Client.OpenClaw && client !== Client.Hermes);
378
522
  let walletReport;
379
523
  if (hasGenericClient) {
380
- if (options.force) {
381
- progress?.report('Checking payment wallet...');
382
- walletReport = await dependencies.inspectWallet();
524
+ try {
525
+ if (options.force) {
526
+ progress?.report('Checking payment wallet...');
527
+ walletReport = await dependencies.inspectWallet();
528
+ }
529
+ else {
530
+ progress?.report('Preparing payment wallet...');
531
+ walletReport = await dependencies.setupWallet({
532
+ allowSkip: true,
533
+ dryRun: options.dryRun,
534
+ ...(progress ? { globe: progress.globe } : {}),
535
+ });
536
+ }
383
537
  }
384
- else {
385
- progress?.report('Preparing payment wallet...');
386
- walletReport = await dependencies.setupWallet({
387
- allowSkip: true,
388
- dryRun: options.dryRun,
389
- ...(progress ? { globe: progress.globe } : {}),
390
- });
538
+ catch (error) {
539
+ warnings.push(`Payment wallet setup skipped: ${errorMessage(error)}. Free operations remain available; run mercator wallet later to enable paid jobs.`);
391
540
  }
392
541
  }
393
542
  if (options.dryRun) {
@@ -398,11 +547,32 @@ async function setup(options, dependencies, progress) {
398
547
  nativePayments,
399
548
  ...(plugin ? { plugin } : {}),
400
549
  ready: true,
550
+ warnings,
401
551
  ...(walletReport ? { wallet: withoutBalances(walletReport) } : {}),
402
552
  };
403
553
  }
404
554
  progress?.report('Running Mercator readiness checks...');
405
- const diagnosis = await diagnoseWithoutWallet(options.url, dependencies, progress);
555
+ let diagnosis;
556
+ try {
557
+ diagnosis = await diagnoseWithoutWallet(options.url, dependencies, progress);
558
+ }
559
+ catch (error) {
560
+ const message = errorMessage(error);
561
+ warnings.push(`Readiness check skipped: ${message}. Your completed setup was preserved; run mercator doctor to retry.`);
562
+ diagnosis = {
563
+ ready: false,
564
+ report: {
565
+ discovery: 'failed',
566
+ endpoint: options.url,
567
+ error: message,
568
+ paidExecution: 'not_verified',
569
+ tools: [],
570
+ transport: 'failed',
571
+ },
572
+ };
573
+ }
574
+ const integrationReady = plugin !== undefined ||
575
+ clientResults.some((client) => ['already_configured', 'configured', 'reconfigured'].includes(client.status));
406
576
  return {
407
577
  ...(agents
408
578
  ? {
@@ -417,14 +587,26 @@ async function setup(options, dependencies, progress) {
417
587
  dryRun: false,
418
588
  nativePayments,
419
589
  ...(plugin ? { plugin } : {}),
420
- ready: diagnosis.report.transport === 'ready' && diagnosis.report.discovery === 'ready',
590
+ ready: diagnosis.ready && integrationReady,
591
+ warnings,
421
592
  ...(walletReport ? { wallet: withoutBalances(walletReport) } : {}),
422
593
  };
423
594
  }
595
+ function unavailableClientGuidance(client) {
596
+ if (client === Client.Codex) {
597
+ 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.';
598
+ }
599
+ return `${clientLabel(client)} is not available on PATH. Install its CLI and rerun, or omit --client ${client} to auto-detect available clients.`;
600
+ }
601
+ function errorMessage(error) {
602
+ return error instanceof Error ? error.message : String(error);
603
+ }
424
604
  function setupConfirmationActions(clients, options) {
425
605
  const actions = [];
426
606
  if (options.plugin)
427
607
  actions.push('Install the Codex/ChatGPT desktop plugin');
608
+ if (options.plugin && options.skill)
609
+ actions.push('Install the Mercator skill');
428
610
  if (clients.length > 0) {
429
611
  const labels = clients.map(clientLabel);
430
612
  const formatted = labels.length === 1
@@ -462,16 +644,26 @@ function formatSetupResult(result) {
462
644
  : 'Mercator guidance was not installed.';
463
645
  return [title, '', ...paths.map((path) => `✓ ${path}`)].join('\n');
464
646
  }
647
+ const hasWarnings = result.warnings.length > 0 ||
648
+ result.clients.some((client) => client.status === 'conflict' || client.status === 'skipped');
465
649
  const lines = [
466
650
  result.dryRun
467
651
  ? 'Mercator setup preview — no changes made.'
468
- : result.ready
652
+ : result.ready && !hasWarnings
469
653
  ? 'Mercator setup complete.'
470
- : 'Mercator setup needs attention.',
654
+ : result.ready
655
+ ? 'Mercator setup complete with warnings.'
656
+ : 'Mercator setup needs attention.',
471
657
  '',
472
658
  ];
659
+ for (const warning of result.warnings)
660
+ lines.push(`! ${warning}`);
473
661
  for (const client of result.clients) {
474
- const glyph = client.status === 'planned' ? '→' : client.status === 'conflict' ? '!' : '✓';
662
+ const glyph = client.status === 'planned' || client.status === 'skipped'
663
+ ? '→'
664
+ : client.status === 'conflict'
665
+ ? '!'
666
+ : '✓';
475
667
  const status = client.status === 'planned'
476
668
  ? 'would be configured'
477
669
  : client.status === 'conflict'
@@ -487,6 +679,11 @@ function formatSetupResult(result) {
487
679
  ? 'would be installed'
488
680
  : humanizeStatus(result.plugin.status);
489
681
  lines.push(`${glyph} Codex/ChatGPT plugin — ${status}`, ` ${result.plugin.pluginPath}`);
682
+ lines.push(result.plugin.status === 'planned'
683
+ ? `→ Mercator skill — ${result.plugin.skillInstalled ? 'would be installed' : 'would be omitted'}`
684
+ : result.plugin.skillInstalled
685
+ ? '✓ Mercator skill — installed'
686
+ : '○ Mercator skill — not installed');
490
687
  }
491
688
  if ('agents' in result && result.agents) {
492
689
  const glyph = result.agents.state === 'planned' ? '→' : '✓';
@@ -557,9 +754,14 @@ function formatSetupResult(result) {
557
754
  }
558
755
  if (!paymentsReady) {
559
756
  lines.push('', 'Free operations are ready.');
560
- const walletCommand = walletAction(wallet);
561
- if (walletCommand)
562
- lines.push('', 'Enable paid jobs:', ` ${walletCommand}`);
757
+ if (wallet?.status === 'needs_funding') {
758
+ lines.push('', 'Enable paid jobs:', ' mercator wallet claim github', ' mercator wallet claim x', ' mercator wallet fund');
759
+ }
760
+ else {
761
+ const walletCommand = walletAction(wallet);
762
+ if (walletCommand)
763
+ lines.push('', 'Enable paid jobs:', ` ${walletCommand}`);
764
+ }
563
765
  }
564
766
  const everythingCurrent = result.clients.every((client) => client.status === 'already_configured') &&
565
767
  (!('plugin' in result) || result.plugin?.status === 'already_configured') &&
@@ -614,7 +816,7 @@ async function uninstall(options, dependencies) {
614
816
  continue;
615
817
  }
616
818
  const state = await dependencies.configurationState(setupPlan(client, DEFAULT_ENDPOINT));
617
- if (state === 'missing') {
819
+ if (state === 'missing' || state === 'unavailable') {
618
820
  clientResults.push({ client, status: 'missing' });
619
821
  continue;
620
822
  }
@@ -661,5 +863,5 @@ async function diagnoseWithoutWallet(endpoint, dependencies, progress) {
661
863
  report,
662
864
  };
663
865
  }
664
- export { diagnose, inspectCodexPlugin, inspectWallet, installCodexPlugin, openFundingPage, removeCodexPlugin, setupPlan, setupWallet, };
866
+ export { diagnose, inspectCodexPlugin, inspectWallet, installCodexPlugin, listWallets, openFundingPage, removeCodexPlugin, setupPlan, setupWallet, useWallet, };
665
867
  //# sourceMappingURL=index.js.map