@tempoxyz/mercator 0.0.912 → 0.0.928

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/clients.js CHANGED
@@ -13,22 +13,28 @@ export const CLIENT_DEFINITIONS = {
13
13
  ...CLIENT_METADATA.claude,
14
14
  command: 'claude',
15
15
  remove: () => commandRemoval('claude', ['mcp', 'remove', '--scope', 'user', 'mercator']),
16
- setup: ({ url }) => commandPlan('claude', ['mcp', 'add', '--scope', 'user', '--transport', 'http', 'mercator', url], { args: ['mcp', 'get', 'mercator'], command: 'claude', url }),
16
+ setup: ({ url }) => commandPlan('claude', ['mcp', 'add', '--scope', 'user', '--transport', 'http', 'mercator', url], { args: ['mcp', 'get', 'mercator'], client: 'claude', command: 'claude', url }),
17
17
  },
18
18
  cline: {
19
19
  ...CLIENT_METADATA.cline,
20
20
  command: 'cline',
21
- configFootprints: ({ cwd }) => [join(cwd, '.cline')],
22
- remove: ({ cwd }) => fileRemoval(join(cwd, '.cline', 'mcp.json'), 'mcpServers', cwd),
23
- setup: ({ cwd, url }) => filePlan(join(cwd, '.cline', 'mcp.json'), 'mcpServers', {
21
+ configFootprints: ({ home }) => [join(home, '.cline')],
22
+ remove: ({ env, home }) => fileRemoval(clineSettingsPath(home, env), 'mcpServers'),
23
+ setup: ({ env, home, url }) => filePlan(clineSettingsPath(home, env), 'mcpServers', {
24
24
  mcpServers: { mercator: { type: 'streamableHttp', url } },
25
- }, cwd),
25
+ }),
26
26
  },
27
27
  codex: {
28
28
  ...CLIENT_METADATA.codex,
29
+ bundle: {
30
+ macos: [
31
+ 'ChatGPT.app/Contents/Resources/codex',
32
+ 'Codex.app/Contents/Resources/codex',
33
+ ],
34
+ },
29
35
  command: 'codex',
30
36
  remove: () => commandRemoval('codex', ['mcp', 'remove', 'mercator']),
31
- setup: ({ url }) => commandPlan('codex', ['mcp', 'add', 'mercator', '--url', url, '--oauth-client-registration', 'dcr'], { args: ['mcp', 'get', 'mercator'], command: 'codex', url }),
37
+ setup: ({ url }) => commandPlan('codex', ['mcp', 'add', 'mercator', '--url', url, '--oauth-client-registration', 'dcr'], { args: ['mcp', 'get', 'mercator'], client: 'codex', command: 'codex', url }),
32
38
  },
33
39
  continue: {
34
40
  ...CLIENT_METADATA.continue,
@@ -52,7 +58,13 @@ export const CLIENT_DEFINITIONS = {
52
58
  ...CLIENT_METADATA.gemini,
53
59
  command: 'gemini',
54
60
  remove: () => commandRemoval('gemini', ['mcp', 'remove', 'mercator']),
55
- setup: ({ url }) => commandPlan('gemini', ['mcp', 'add', 'mercator', url, '--transport', 'http', '--scope', 'user'], { args: ['mcp', 'list'], command: 'gemini', serverName: 'mercator', url }),
61
+ setup: ({ url }) => commandPlan('gemini', ['mcp', 'add', 'mercator', url, '--transport', 'http', '--scope', 'user'], {
62
+ args: ['mcp', 'list'],
63
+ client: 'gemini',
64
+ command: 'gemini',
65
+ serverName: 'mercator',
66
+ url,
67
+ }),
56
68
  },
57
69
  grok: {
58
70
  ...CLIENT_METADATA.grok,
@@ -60,6 +72,7 @@ export const CLIENT_DEFINITIONS = {
60
72
  remove: () => commandRemoval('grok', ['mcp', 'remove', '--scope', 'user', 'mercator']),
61
73
  setup: ({ url }) => commandPlan('grok', ['mcp', 'add', '--scope', 'user', '--transport', 'http', 'mercator', url], {
62
74
  args: ['mcp', 'list', '--json'],
75
+ client: 'grok',
63
76
  command: 'grok',
64
77
  serverName: 'mercator',
65
78
  url,
@@ -71,6 +84,7 @@ export const CLIENT_DEFINITIONS = {
71
84
  remove: () => commandRemoval('hermes', ['mcp', 'remove', 'mercator']),
72
85
  setup: ({ url }) => commandPlan('hermes', ['mcp', 'add', 'mercator', '--url', url], {
73
86
  args: ['mcp', 'list'],
87
+ client: 'hermes',
74
88
  command: 'hermes',
75
89
  serverName: 'mercator',
76
90
  url,
@@ -128,6 +142,7 @@ export const CLIENT_DEFINITIONS = {
128
142
  }),
129
143
  ], {
130
144
  args: ['mcp', 'show', 'mercator', '--json'],
145
+ client: 'openclaw',
131
146
  command: 'openclaw',
132
147
  ...(isProtectedMcpEndpoint(url) ? { requireOAuth: true } : {}),
133
148
  url,
@@ -135,15 +150,29 @@ export const CLIENT_DEFINITIONS = {
135
150
  },
136
151
  vscode: {
137
152
  ...CLIENT_METADATA.vscode,
153
+ bundle: { macos: ['Visual Studio Code.app/Contents/Resources/app/bin/code'] },
138
154
  command: 'code',
139
155
  desktop: { macos: 'Visual Studio Code', windows: 'Microsoft VS Code' },
140
156
  remove: ({ home, platform }) => vscodeRemovalPlan(home, platform),
141
- setup: ({ url }) => ({
142
- args: ['--add-mcp', JSON.stringify({ name: 'mercator', type: 'http', url })],
143
- command: 'code',
144
- kind: 'command',
145
- undo: 'Remove Mercator from the MCP: Open User Configuration command.',
146
- }),
157
+ setup: ({ home, platform, url }) => {
158
+ const userFile = vscodeRemovalPlan(home, platform);
159
+ return {
160
+ args: ['--add-mcp', JSON.stringify({ name: 'mercator', type: 'http', url })],
161
+ command: 'code',
162
+ kind: 'command',
163
+ // `code --add-mcp` writes the user mcp.json; read it rather than launching Electron.
164
+ ...(userFile.kind === 'file'
165
+ ? {
166
+ state: {
167
+ config: { servers: { mercator: { type: 'http', url } } },
168
+ path: userFile.path,
169
+ serverContainer: 'servers',
170
+ },
171
+ }
172
+ : {}),
173
+ undo: 'Remove Mercator from the MCP: Open User Configuration command.',
174
+ };
175
+ },
147
176
  },
148
177
  windsurf: {
149
178
  ...CLIENT_METADATA.windsurf,
@@ -169,26 +198,38 @@ export const CLIENT_DEFINITIONS = {
169
198
  },
170
199
  };
171
200
  export function setupPlan(client, url, options = {}) {
172
- return CLIENT_DEFINITIONS[client].setup({
201
+ const plan = CLIENT_DEFINITIONS[client].setup({
173
202
  cwd: options.cwd ?? process.cwd(),
174
203
  env: options.env ?? process.env,
175
204
  home: options.home ?? homedir(),
176
205
  platform: options.platform ?? process.platform,
177
206
  url,
178
207
  });
208
+ if (plan.kind !== 'command' || !options.executable)
209
+ return plan;
210
+ return {
211
+ ...plan,
212
+ command: options.executable,
213
+ ...(plan.check ? { check: { ...plan.check, command: options.executable } } : {}),
214
+ };
179
215
  }
180
216
  /** Builds a conservative removal plan that never includes wallet state. */
181
217
  export function removalPlan(client, options = {}) {
182
- return CLIENT_DEFINITIONS[client].remove({
218
+ const plan = CLIENT_DEFINITIONS[client].remove({
183
219
  cwd: options.cwd ?? process.cwd(),
184
220
  env: options.env ?? process.env,
185
221
  home: options.home ?? homedir(),
186
222
  platform: options.platform ?? process.platform,
187
223
  });
224
+ return plan.kind === 'command' && options.executable
225
+ ? { ...plan, command: options.executable }
226
+ : plan;
188
227
  }
189
228
  export async function configurationState(plan, runCheck = runCommandCheck) {
190
229
  if (plan.kind === 'file')
191
230
  return fileConfigurationState(plan);
231
+ if (plan.state)
232
+ return fileConfigurationState({ ...plan.state, kind: 'file', undo: plan.undo });
192
233
  if (!plan.check)
193
234
  return 'unknown';
194
235
  const result = await runCheck(plan.check);
@@ -198,18 +239,42 @@ export async function configurationState(plan, runCheck = runCommandCheck) {
198
239
  return 'unknown';
199
240
  if (result.code !== 0)
200
241
  return 'missing';
201
- if (plan.check.command === 'grok')
242
+ if (plan.check.client === 'grok')
202
243
  return grokConfigurationState(result.output, plan.check.url);
203
- if (plan.check.serverName && !result.output.includes(plan.check.serverName))
244
+ // List output covers every server; consider only lines naming Mercator exactly.
245
+ const relevant = plan.check.serverName
246
+ ? serverLines(result.output, plan.check.serverName)
247
+ : result.output;
248
+ if (plan.check.serverName && relevant === '')
204
249
  return 'missing';
205
- if (!result.output.includes(plan.check.url)) {
250
+ const urls = outputUrls(relevant);
251
+ if (!urls.has(normalizeUrl(plan.check.url))) {
206
252
  const legacyUrl = legacyMcpEndpoint(plan.check.url);
207
- return legacyUrl && result.output.includes(legacyUrl) ? 'legacy' : 'different';
253
+ return legacyUrl && urls.has(normalizeUrl(legacyUrl)) ? 'legacy' : 'different';
208
254
  }
209
255
  return plan.check.requireOAuth && !/"auth"\s*:\s*"oauth"/.test(result.output)
210
256
  ? 'legacy'
211
257
  : 'current';
212
258
  }
259
+ /** Lines naming `name` as a whole server name, so `mercator-old` never matches `mercator`. */
260
+ function serverLines(output, name) {
261
+ const escaped = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
262
+ const pattern = new RegExp(`(?:^|[^\\w.-])${escaped}(?![\\w.-])`);
263
+ return output
264
+ .split(/\r?\n/)
265
+ .filter((line) => pattern.test(line))
266
+ .join('\n');
267
+ }
268
+ /** Whole URLs in CLI output; substring checks would let `/mcp` match `/mcp/auth`. */
269
+ function outputUrls(output) {
270
+ return new Set([
271
+ // Bracketed IPv6 hosts are allowed only immediately after the scheme.
272
+ ...output.matchAll(/https?:\/\/(?:\[[0-9A-Fa-f:.]+\])?[^\s"'`<>()[\]{},│|]*/g),
273
+ ].map(([url]) => normalizeUrl(url.replace(/[.;:]+$/, ''))));
274
+ }
275
+ function normalizeUrl(url) {
276
+ return url.replace(/\/+$/, '');
277
+ }
213
278
  // Grok list is configuration-only. Select the actual server before examining auth;
214
279
  // another entry's URL or credentials must not determine Mercator's migration.
215
280
  function grokConfigurationState(output, endpoint) {
@@ -260,6 +325,7 @@ export async function installedClients(options = {}) {
260
325
  ...(CLIENT_DEFINITIONS[client].configFootprints?.({ cwd, env, home, platform }) ??
261
326
  []),
262
327
  ...desktopClientPaths(CLIENT_DEFINITIONS[client], home, platform, env),
328
+ ...bundlePaths(CLIENT_DEFINITIONS[client], home, platform),
263
329
  ];
264
330
  if ((await Promise.all(paths.map(isPathAvailable))).some(Boolean)) {
265
331
  detected.add(client);
@@ -552,6 +618,20 @@ function zedSettingsPath(home, platform, env) {
552
618
  }
553
619
  return join(env.XDG_CONFIG_HOME ?? join(home, '.config'), 'zed', 'settings.json');
554
620
  }
621
+ /** App-bundled client executables on macOS, under system and user Applications folders. */
622
+ export function bundlePaths(definition, home, platform) {
623
+ if (!definition.bundle || platform !== 'darwin')
624
+ return [];
625
+ return definition.bundle.macos.flatMap((relative) => [
626
+ join('/Applications', relative),
627
+ join(home, 'Applications', relative),
628
+ ]);
629
+ }
630
+ /** Cline CLI settings; the IDE extension keeps its own extension-managed file. */
631
+ function clineSettingsPath(home, env) {
632
+ return (env.CLINE_MCP_SETTINGS_PATH ||
633
+ join(home, '.cline', 'data', 'settings', 'cline_mcp_settings.json'));
634
+ }
555
635
  function desktopClientPaths(definition, home, platform, env) {
556
636
  if (!definition.desktop)
557
637
  return [];
@@ -1,4 +1,6 @@
1
1
  import type { ClaudeRegistration } from './claude-registrations.js';
2
2
  import { commandAvailable, runCapturedCommand } from './command.js';
3
3
  /** Preserve native plugins; their credentials and health belong to the host client. */
4
- export declare function inspectCodexRegistrations(run?: typeof runCapturedCommand, available?: typeof commandAvailable): Promise<ClaudeRegistration>;
4
+ export declare function inspectCodexRegistrations(run?: typeof runCapturedCommand, available?: typeof commandAvailable,
5
+ /** Executable chosen by the client resolver; defaults to `codex` on PATH. */
6
+ command?: string): Promise<ClaudeRegistration>;
@@ -8,15 +8,17 @@ const pluginList = z.object({
8
8
  })),
9
9
  });
10
10
  /** Preserve native plugins; their credentials and health belong to the host client. */
11
- export async function inspectCodexRegistrations(run = runCapturedCommand, available = commandAvailable) {
12
- if (!(await available('codex')))
11
+ export async function inspectCodexRegistrations(run = runCapturedCommand, available = commandAvailable,
12
+ /** Executable chosen by the client resolver; defaults to `codex` on PATH. */
13
+ command = 'codex') {
14
+ if (!(await available(command)))
13
15
  return { kind: 'standalone', action: 'Codex CLI is not installed.' };
14
16
  const conflict = {
15
17
  kind: 'conflict',
16
18
  action: 'Codex plugin registrations could not be verified. Run codex plugin list --json and use native plugin controls to resolve the installation; existing entries were preserved.',
17
19
  };
18
20
  try {
19
- const result = await run('codex', ['plugin', 'list', '--json'], {
21
+ const result = await run(command, ['plugin', 'list', '--json'], {
20
22
  maxOutputBytes: 128 * 1024,
21
23
  timeoutMs: 10_000,
22
24
  });
package/dist/command.d.ts CHANGED
@@ -30,6 +30,8 @@ export declare class CommandTimeoutError extends CommandExecutionError {
30
30
  }
31
31
  /** Restricts nested installer utilities to absolute PATH entries, preserving other environment values. */
32
32
  export declare function commandEnvironment(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
33
+ /** Lists every executable match in PATH order without implicitly searching the working directory. */
34
+ export declare function findExecutables(command: string, env?: NodeJS.ProcessEnv): string[];
33
35
  /** Returns whether an executable is available on the current process PATH. */
34
36
  export declare function commandAvailable(command: string): Promise<boolean>;
35
37
  /** Resolves a command to an absolute executable path or fails without OS search fallback. */
package/dist/command.js CHANGED
@@ -46,8 +46,8 @@ export function commandEnvironment(env) {
46
46
  PATH: entries.join(process.platform === 'win32' ? win32.delimiter : posix.delimiter),
47
47
  };
48
48
  }
49
- /** Resolves executables without implicitly searching the working directory. */
50
- function findCommand(command, env = process.env) {
49
+ /** Lists every executable match in PATH order without implicitly searching the working directory. */
50
+ export function findExecutables(command, env = process.env) {
51
51
  const windows = process.platform === 'win32';
52
52
  const path = windows ? win32 : posix;
53
53
  const isAbsolute = (value) => path.isAbsolute(value) && (!windows || path.parse(value).root.length > 1);
@@ -61,17 +61,19 @@ function findCommand(command, env = process.env) {
61
61
  !command.includes('\\')
62
62
  ? directories.flatMap((directory) => names.map((name) => path.join(directory, name)))
63
63
  : [];
64
- for (const candidate of candidates) {
64
+ return [...new Set(candidates)].filter((candidate) => {
65
65
  try {
66
66
  accessSync(candidate, constants.X_OK);
67
- if (statSync(candidate).isFile())
68
- return candidate;
67
+ return statSync(candidate).isFile();
69
68
  }
70
69
  catch {
71
- // Continue searching PATH.
70
+ return false;
72
71
  }
73
- }
74
- return undefined;
72
+ });
73
+ }
74
+ /** Resolves executables without implicitly searching the working directory. */
75
+ function findCommand(command, env = process.env) {
76
+ return findExecutables(command, env)[0];
75
77
  }
76
78
  /** Returns whether an executable is available on the current process PATH. */
77
79
  export async function commandAvailable(command) {
package/dist/index.d.ts CHANGED
@@ -52,9 +52,11 @@ export declare function createMercatorCli(overrides?: Partial<CliDependencies>,
52
52
  options: {
53
53
  agents: boolean;
54
54
  client: ("claude" | "cline" | "codex" | "continue" | "cursor" | "gemini" | "grok" | "hermes" | "kiro" | "lmstudio" | "muse" | "openclaw" | "vscode" | "windsurf" | "zed")[];
55
+ codexPath?: string | undefined;
55
56
  color: boolean;
56
57
  dryRun: boolean;
57
58
  force: boolean;
59
+ login: boolean;
58
60
  manual: boolean;
59
61
  plugin: boolean;
60
62
  removeAgents: boolean;
package/dist/index.js CHANGED
@@ -5,6 +5,7 @@ import { openBrowserUrl } from './browser.js';
5
5
  import { inspectClaudeRegistrations } from './claude-registrations.js';
6
6
  import { inspectClaudeSkills, installClaudeSkills, removeClaudeSkills, } from './claude-skills.js';
7
7
  import { clientAuthorizationGuidance } from './client-authorization.js';
8
+ import { guidanceExecutable, resolveClientExecutable, resolvedExecutable, resolvedExecutablePath, } from './client-binary.js';
8
9
  import { prepareSetupPlan } from './client-capabilities.js';
9
10
  import { clientEndpoint } from './client-endpoint.js';
10
11
  import { selectSetupClients } from './client-selection.js';
@@ -114,6 +115,7 @@ const defaultDependencies = {
114
115
  openBrowserUrl,
115
116
  runCommand: (command, args, options) => runInteractiveCommand(command, args, { timeoutMs: 60_000, ...options }),
116
117
  setupNativePayments,
118
+ resolveClientExecutable,
117
119
  selectSetupClients,
118
120
  startSetupProgress: startTerminalSetupProgress,
119
121
  submitPaidJob,
@@ -126,12 +128,20 @@ const setupOptions = z.object({
126
128
  .default(true)
127
129
  .describe('Install Codex AGENTS.md guidance; disable with --no-agents'),
128
130
  client: z.array(z.enum(CLIENT_IDS)).default([]).describe('Target a client; repeatable'),
131
+ codexPath: z
132
+ .string()
133
+ .optional()
134
+ .describe('Absolute path to the Codex executable; overrides MERCATOR_CODEX_BIN and discovery'),
129
135
  color: z.boolean().default(true).describe('Use color in interactive output'),
130
136
  dryRun: z.boolean().default(false).describe('Show changes without writing them'),
131
137
  force: z
132
138
  .boolean()
133
139
  .default(false)
134
140
  .describe('Recreate Mercator MCP without changing wallet or key state'),
141
+ login: z
142
+ .boolean()
143
+ .default(false)
144
+ .describe('Also authorize the Mercator CLI; creates a separate spending access key'),
135
145
  manual: z
136
146
  .boolean()
137
147
  .default(false)
@@ -186,10 +196,12 @@ export function createMercatorCli(overrides = {}, argv = [], onDoctorResult = ()
186
196
  return freshness.deferred
187
197
  ? 'Update scheduled; setup will resume after this process exits.'
188
198
  : undefined;
189
- if (!options.manual &&
190
- !options.removeAgents &&
191
- freshness.release.status === 'unavailable')
192
- console.error('Release freshness unavailable; setup is using its bundled guidance.');
199
+ if (!options.manual && !options.removeAgents) {
200
+ if (freshness.release.status === 'unavailable')
201
+ console.error(`Release freshness unavailable (${freshness.release.failure === 'http' ? 'release server error' : 'network'}); setup is using its bundled guidance.`);
202
+ if (freshness.release.status === 'invalid')
203
+ console.error('Published release metadata is invalid; setup is using its bundled guidance. Report this with mercator doctor output if it persists.');
204
+ }
193
205
  if (options.dryRun &&
194
206
  options.update !== false &&
195
207
  freshness.release.manifest &&
@@ -605,7 +617,9 @@ async function uninstall(options, dependencies) {
605
617
  const clients = options.client.length > 0 ? [...new Set(options.client)] : CLIENT_IDS;
606
618
  const clientResults = [];
607
619
  for (const client of clients) {
608
- const removal = removalPlan(client);
620
+ const resolved = await resolvedExecutablePath(client, dependencies.resolveClientExecutable);
621
+ const executable = resolved ? { executable: resolved } : {};
622
+ const removal = removalPlan(client, executable);
609
623
  if (removal.kind === 'manual') {
610
624
  clientResults.push({ client, instructions: removal.instructions, status: 'manual' });
611
625
  continue;
@@ -617,7 +631,7 @@ async function uninstall(options, dependencies) {
617
631
  clientResults.push({ client, status: state });
618
632
  continue;
619
633
  }
620
- const state = await dependencies.configurationState(setupPlan(client, DEFAULT_ENDPOINT));
634
+ const state = await dependencies.configurationState(setupPlan(client, DEFAULT_ENDPOINT, executable));
621
635
  if (state === 'missing' || state === 'unavailable') {
622
636
  clientResults.push({ client, status: 'missing' });
623
637
  continue;
@@ -649,12 +663,16 @@ async function clientStatus(endpoint, dependencies) {
649
663
  const installed = await dependencies.installedClients();
650
664
  const clients = await Promise.all(installed.map(async (client) => {
651
665
  const clientUrl = clientEndpoint(client, endpoint);
666
+ const selected = await resolvedExecutable(client, dependencies.resolveClientExecutable);
667
+ const resolved = selected?.path;
652
668
  const skills = client === Client.Claude
653
669
  ? await dependencies.inspectClaudeSkills().catch(() => undefined)
654
670
  : undefined;
655
671
  try {
656
672
  if (client === Client.Claude) {
657
- const registration = await dependencies.inspectClaudeRegistrations(clientUrl);
673
+ const registration = resolved
674
+ ? await dependencies.inspectClaudeRegistrations(clientUrl, undefined, resolved)
675
+ : await dependencies.inspectClaudeRegistrations(clientUrl);
658
676
  if (registration.kind !== 'standalone')
659
677
  return {
660
678
  client,
@@ -667,11 +685,11 @@ async function clientStatus(endpoint, dependencies) {
667
685
  error: registration.action,
668
686
  };
669
687
  }
670
- const state = await dependencies.configurationState(setupPlan(client, clientUrl));
688
+ const state = await dependencies.configurationState(setupPlan(client, clientUrl, resolved ? { executable: resolved } : {}));
671
689
  const action = state === 'legacy'
672
690
  ? `Run mercator setup --client ${client} to migrate the registration before authorizing.`
673
691
  : state === 'current'
674
- ? clientAuthorizationGuidance(client, clientUrl)
692
+ ? clientAuthorizationGuidance(client, clientUrl, guidanceExecutable(selected))
675
693
  : undefined;
676
694
  return {
677
695
  client,
@@ -40,8 +40,8 @@ If tools are unavailable, use `mercator-setup` or the host's native MCP connecti
40
40
 
41
41
  - When an unexpected failure persists after one safe recovery attempt, proactively draft a report
42
42
  for `send_product_feedback`.
43
- - Include the tool or command, safe error code, reproduction steps, and expected versus actual
44
- behavior. Follow live tool schemas.
43
+ - Include the tool or command, safe error code, any `error_id` and `request_id`, reproduction
44
+ steps, and expected versus actual behavior. Follow live tool schemas.
45
45
  - Exclude secrets, credentials, payment material, personal data, and raw inputs or outputs. Include
46
46
  a known job ID only when authorized; sharing it gives maintainers access to job results.
47
47
  - Show the draft and ask before sending unless the user already authorized reporting this issue.
package/dist/refresh.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import { type resolveClientExecutable } from './client-binary.js';
1
2
  import { type configurationState, type installedClients } from './clients.js';
2
3
  import type { inspectCodexPlugin } from './codex-plugin.js';
3
4
  import type { SetupOptions } from './setup.js';
@@ -9,6 +10,8 @@ type RefreshDependencies = {
9
10
  configurationState: typeof configurationState;
10
11
  inspectCodexPlugin: typeof inspectCodexPlugin;
11
12
  hasManagedAgents: typeof hasManagedAgents;
13
+ /** Same executable selection setup uses, so bundled or overridden clients are inspected. */
14
+ resolveClientExecutable?: typeof resolveClientExecutable | undefined;
12
15
  };
13
16
  /** Detects only installer-owned activation guidance, preserving user-authored instructions. */
14
17
  export declare function hasManagedAgents(codexHome?: string): Promise<boolean>;
package/dist/refresh.js CHANGED
@@ -2,6 +2,7 @@ import { readFile } from 'node:fs/promises';
2
2
  import { homedir } from 'node:os';
3
3
  import { join } from 'node:path';
4
4
  import { MERCATOR_AGENTS_BEGIN } from './agents.js';
5
+ import { resolvedExecutablePath } from './client-binary.js';
5
6
  import { clientEndpoint } from './client-endpoint.js';
6
7
  import { setupPlan } from './clients.js';
7
8
  /** Detects only installer-owned activation guidance, preserving user-authored instructions. */
@@ -30,10 +31,13 @@ export async function refreshOptions(controls, dependencies) {
30
31
  ]);
31
32
  if (plugin.status === 'conflict')
32
33
  throw new Error('Existing plugin is not CLI-managed. Refresh it through its marketplace, or run targeted setup.');
33
- const states = await Promise.all(installed.map(async (client) => ({
34
- client,
35
- state: await dependencies.configurationState(setupPlan(client, clientEndpoint(client, url))),
36
- })));
34
+ const states = await Promise.all(installed.map(async (client) => {
35
+ const executable = await resolvedExecutablePath(client, dependencies.resolveClientExecutable);
36
+ return {
37
+ client,
38
+ state: await dependencies.configurationState(setupPlan(client, clientEndpoint(client, url), executable ? { executable } : {})),
39
+ };
40
+ }));
37
41
  if (states.some(({ state }) => ['different', 'unknown'].includes(state)))
38
42
  throw new Error('An existing registration needs explicit setup choices. Run mercator setup --client <client> with its intended endpoint before refreshing.');
39
43
  preferences = {
package/dist/release.d.ts CHANGED
@@ -8,11 +8,19 @@ export declare const ReleaseManifestSchema: z.ZodObject<{
8
8
  }, z.core.$strip>;
9
9
  /** Validated public release metadata. */
10
10
  type ReleaseManifest = z.infer<typeof ReleaseManifestSchema>;
11
+ /**
12
+ * Why freshness could not be determined. `network` covers transport failures and timeouts;
13
+ * `http` is a non-success response; `invalid` is a reachable but malformed, oversized, or
14
+ * inconsistent policy, which indicates a publishing defect rather than a transient outage.
15
+ */
16
+ type ReleaseFailure = 'http' | 'invalid' | 'network';
11
17
  /** Published freshness is independent of MCP connection readiness. */
12
18
  export type ReleaseStatus = {
13
19
  currentVersion: string;
14
- status: 'current' | 'outdated' | 'unsupported' | 'unavailable' | 'development';
20
+ status: 'current' | 'outdated' | 'unsupported' | 'unavailable' | 'invalid' | 'development';
15
21
  manifest?: ReleaseManifest;
22
+ /** Present when status is `unavailable` or `invalid`. */
23
+ failure?: ReleaseFailure;
16
24
  };
17
25
  /** Compares the stable numeric release components without floating-point truncation. */
18
26
  export declare function compareReleaseVersions(left: string, right: string): number;
package/dist/release.js CHANGED
@@ -26,41 +26,60 @@ export function compareReleaseVersions(left, right) {
26
26
  export async function inspectRelease(currentVersion, fetcher = fetch) {
27
27
  if (currentVersion === '0.0.0')
28
28
  return { currentVersion, status: 'development' };
29
+ const failed = (failure) => ({
30
+ currentVersion,
31
+ failure,
32
+ status: failure === 'invalid' ? 'invalid' : 'unavailable',
33
+ });
34
+ let response;
29
35
  try {
30
- const response = await fetcher('https://mercator.sh/downloads/latest/release.json', {
36
+ response = await fetcher('https://mercator.sh/downloads/latest/release.json', {
31
37
  cache: 'no-store',
32
38
  redirect: 'error',
33
39
  signal: AbortSignal.timeout(5_000),
34
40
  });
35
- if (!response.ok || !response.body)
36
- throw new Error('Release unavailable');
37
- const reader = response.body.getReader();
38
- const chunks = [];
39
- let size = 0;
40
- try {
41
- while (true) {
42
- const { done, value } = await reader.read();
43
- if (done)
44
- break;
45
- size += value.byteLength;
46
- if (size > 4_096)
47
- throw new Error('Release metadata too large');
48
- chunks.push(value);
49
- }
50
- }
51
- finally {
52
- await reader.cancel().catch(() => undefined);
41
+ }
42
+ catch {
43
+ return failed('network');
44
+ }
45
+ if (!response.ok || !response.body) {
46
+ await response.body?.cancel().catch(() => undefined);
47
+ return failed('http');
48
+ }
49
+ const reader = response.body.getReader();
50
+ const chunks = [];
51
+ let size = 0;
52
+ try {
53
+ while (true) {
54
+ const { done, value } = await reader.read();
55
+ if (done)
56
+ break;
57
+ size += value.byteLength;
58
+ if (size > 4_096)
59
+ return failed('invalid');
60
+ chunks.push(value);
53
61
  }
54
- const manifest = ReleaseManifestSchema.parse(JSON.parse(Buffer.concat(chunks).toString('utf8')));
55
- ReleaseVersion.parse(currentVersion);
56
- const status = compareReleaseVersions(currentVersion, manifest.minimumSetupVersion) < 0
57
- ? 'unsupported'
58
- : compareReleaseVersions(currentVersion, manifest.latestVersion) < 0
59
- ? 'outdated'
60
- : 'current';
61
- return { currentVersion, manifest, status };
62
62
  }
63
63
  catch {
64
- return { currentVersion, status: 'unavailable' };
64
+ return failed('network');
65
+ }
66
+ finally {
67
+ await reader.cancel().catch(() => undefined);
68
+ }
69
+ let manifest;
70
+ try {
71
+ manifest = ReleaseManifestSchema.parse(JSON.parse(Buffer.concat(chunks).toString('utf8')));
72
+ }
73
+ catch {
74
+ return failed('invalid');
65
75
  }
76
+ // A malformed local version is a packaging defect, not a policy or network failure.
77
+ if (!ReleaseVersion.safeParse(currentVersion).success)
78
+ return failed('invalid');
79
+ const status = compareReleaseVersions(currentVersion, manifest.minimumSetupVersion) < 0
80
+ ? 'unsupported'
81
+ : compareReleaseVersions(currentVersion, manifest.latestVersion) < 0
82
+ ? 'outdated'
83
+ : 'current';
84
+ return { currentVersion, manifest, status };
66
85
  }
@@ -1,4 +1,4 @@
1
- import type { SetupResult } from './setup.js';
1
+ import { type SetupResult } from './setup.js';
2
2
  import type { SetupDiagnosticReport } from './setup-diagnostics.js';
3
3
  /** Safe runtime metadata included with verbose setup results. */
4
4
  export type SetupDebugContext = SetupDiagnosticReport & {