@chrischall/mcp-host-cli 0.0.0-stage → 2.33.1

package/src/wizard.mjs

@@ -0,0 +1,416 @@
+// The interactive register wizard: `mcp-host wizard`, or `mcp-host register`
+// with no flags on a terminal.
+//
+// A conversation over the SAME control API the flags use — `api` is passed
+// in (the (method, path, body) function index.mjs owns) so a test can
+// record every call, and the prompter is passed in so a test can script the
+// answers. Nothing here resolves a source or validates a slug beyond what it
+// needs to ask the next question: the preview endpoint is the resolver and
+// the create is the validator, and a copy of either rule would drift.
+//
+// Every line it prints goes to `stderr`, like the prompts: stdout stays the
+// JSON of the registration that was created, exactly as `register` prints.
+
+import { DEP_GRAMMAR, bundleSummaryLines, parseGithubSpec, parseMcpbSpec, parseNpmSpec, suggestSlug } from './lib.mjs';
+import { storeSecretSealed } from './secrets.mjs';
+
+/** Secret values never pass through this string; env values and names do. */
+function shellQuote(value) {
+  return /^[A-Za-z0-9_@%+=:,.#/-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+/**
+ * A source back to the `--npm`/`--github`/`--mcpb` spelling `register`
+ * accepts. An mcpb source in the BODY is already by hash or by URL — a path
+ * was uploaded before the body existed — so the flag it re-spells names the
+ * hash, which is the form that works from any machine.
+ */
+function sourceSpec(source) {
+  if (source.type === 'npm') return `${source.pkg}${source.version ? `@${source.version}` : ''}`;
+  if (source.type === 'mcpb') return source.url ?? `sha256:${source.sha256}`;
+  return `${source.repo}${source.ref ? `#${source.ref}` : source.commit ? `#${source.commit}` : ''}`;
+}
+
+/** A dependency input back to the one-line `--dep` grammar. */
+function depSpec(dep) {
+  if (dep.kind === 'npm') return `npm:${dep.pkg}${dep.version ? `@${dep.version}` : ''}`;
+  return `github:${dep.repo}@${dep.tag}:${dep.asset}#${dep.bin.join(',')}`;
+}
+
+/**
+ * The flags that would have produced this body, for the epilogue. Teaching
+ * the flags is the point: the wizard is for the first registration, and the
+ * second one is usually a script. Secret VALUES cannot appear — the body
+ * carries references by name, and the value was sent on its own PUT.
+ */
+export function equivalentCommand(body) {
+  const parts = ['mcp-host register', '--slug', shellQuote(body.slug)];
+  if (body.account !== undefined) parts.push('--account', shellQuote(body.account));
+  if (body.source.type === 'npm') parts.push('--npm', shellQuote(sourceSpec(body.source)));
+  else if (body.source.type === 'mcpb') parts.push('--mcpb', shellQuote(sourceSpec(body.source)));
+  else {
+    parts.push('--github', shellQuote(sourceSpec(body.source)));
+    if (body.source.subdir) parts.push('--subdir', shellQuote(body.source.subdir));
+    if (body.source.build) parts.push('--build', shellQuote(body.source.build));
+  }
+  if (body.displayName) parts.push('--name', shellQuote(body.displayName));
+  if (body.command?.bin) parts.push('--bin', shellQuote(body.command.bin));
+  for (const [name, value] of Object.entries(body.env ?? {})) {
+    if (typeof value === 'string') parts.push('--env', shellQuote(`${name}=${value}`));
+    else parts.push('--secret-env', shellQuote(`${name}=${value.secret}`));
+  }
+  for (const dep of body.dependencies ?? []) {
+    parts.push('--dep', shellQuote(depSpec(dep)));
+    if (dep.sha256) parts.push('--dep-sha256', shellQuote(`${dep.asset}=${dep.sha256}`));
+  }
+  if (body.updatePolicy === 'follow') parts.push('--follow');
+  if (body.dataDir === false) parts.push('--no-data-dir');
+  if (body.perUserChild) parts.push('--per-user-child');
+  if (body.bridge) parts.push('--bridge');
+  return parts.join(' ');
+}
+
+function describeSource(source) {
+  if (source.type === 'npm') return `${source.pkg}@${source.version}`;
+  if (source.type === 'mcpb') return `${source.name}@${source.version} (mcpb ${source.serverType}, sha256 ${source.sha256})`;
+  return `${source.repo}@${source.commit}${source.subdir ? ` (${source.subdir})` : ''}`;
+}
+
+/**
+ * @param {import('./prompt.mjs').Prompter} prompter
+ * @param {(method: string, path: string, body?: unknown) => Promise<any>} api
+ * @param {{ stderr?: { write(s: string): unknown }, uploadBundle?: (file: string) => Promise<any> }} [opts]
+ *   `uploadBundle` is index.mjs's raw `PUT /api/v1/bundles` (the one non-JSON
+ *   request), passed in like `api` so a test can hand over a recorder.
+ * @returns {Promise<{ registration: any, body: object, secretsStored: string[] }>}
+ */
+export async function runWizard(prompter, api, { stderr = process.stderr, uploadBundle } = {}) {
+  const say = (s = '') => stderr.write(`${s}\n`);
+
+  // --- source, previewed before anything else is asked -------------------
+  // The preview is the first call because everything after it (the slug
+  // suggestion, the env rows, the bins) is read off its answer, and a source
+  // that does not resolve should fail here, before a single other question.
+  let source;
+  let preview;
+  for (;;) {
+    // APPENDED, never inserted: the menu is answered by position in every
+    // scripted run (wizard.test.ts), and by habit at a terminal.
+    const kind = await prompter.choose('Where does the MCP come from?', [
+      { value: 'npm', label: 'an npm package' },
+      { value: 'github', label: 'a GitHub repository' },
+      { value: 'mcpb', label: 'an MCPB bundle (.mcpb file or URL)' },
+    ]);
+    try {
+      if (kind === 'npm') {
+        source = parseNpmSpec(await prompter.ask('Package (name[@version|dist-tag])'));
+      } else if (kind === 'mcpb') {
+        // A path is uploaded NOW, before the preview, because the preview
+        // can only name a bundle the gateway holds; the summary it answers
+        // (type, signature presence, the config this host cannot deliver) is
+        // printed before anything else is asked. A refused upload re-asks
+        // the source like a refused preview does. The body then names the
+        // HASH — the URL form stays a URL, the gateway fetches it.
+        const spec = parseMcpbSpec(await prompter.ask('Bundle (.mcpb path, https URL, or sha256:<hex> of one already uploaded)'));
+        if (spec.kind === 'url') source = { type: 'mcpb', url: spec.url };
+        else if (spec.kind === 'sha256') source = { type: 'mcpb', sha256: spec.sha256 };
+        else {
+          if (!uploadBundle) throw new Error('this wizard was started without an uploader; pass --mcpb to `register` instead');
+          say('Uploading…');
+          const view = await uploadBundle(spec.path);
+          for (const line of bundleSummaryLines(view)) say(line);
+          source = { type: 'mcpb', sha256: view.sha256 };
+        }
+      } else {
+        source = parseGithubSpec(await prompter.ask('Repository (owner/repo[#ref])'));
+        const subdir = await prompter.ask('Subdirectory (monorepos; blank for the root)', { default: '' });
+        const build = await prompter.ask('Build command (blank for none; installs never run scripts)', { default: '' });
+        if (subdir) source.subdir = subdir;
+        if (build) source.build = build;
+      }
+      say('Resolving…');
+      preview = await api('POST', '/api/v1/registrations/preview', { source });
+      break;
+    } catch (error) {
+      say(`  ${error.message}`);
+      say('  Try again.');
+    }
+  }
+  printPreview(say, preview);
+
+  // --- identity -----------------------------------------------------------
+  // A bundle's input names no package; the manifest's name is on the pin.
+  const sourceName = source.type === 'npm' ? source.pkg : source.type === 'mcpb' ? preview.source.name : source.repo;
+  let slug;
+  for (;;) {
+    slug = await prompter.ask('Slug (the URL path: /c/<account>/<slug>/mcp)', { default: suggestSlug(sourceName) });
+    if (slug) break;
+    say('  a slug is required');
+  }
+  const displayName = await prompter.ask('Display name', { default: preview.package?.name ?? slug });
+
+  // --- env ----------------------------------------------------------------
+  /** @type {Record<string, string | {secret: string}>} */
+  const env = {};
+  /** @type {string[]} */
+  const secretsStored = [];
+  /** @type {string[] | null} — fetched once, the first time a row asks */
+  let existingSecrets = null;
+  const secretNames = async () => {
+    if (existingSecrets === null) {
+      const listed = await api('GET', '/api/v1/secrets');
+      existingSecrets = listed.secrets.map((s) => s.name);
+    }
+    return existingSecrets;
+  };
+
+  /**
+   * One env row. Returns when the row is settled: bound, or skipped when
+   * that is allowed. A required row re-asks, because the preview said the
+   * MCP will not start without it and a create that omits it is a
+   * registration that fails at its first spawn.
+   */
+  async function envRow(name, { required, secret: secretShaped, help }) {
+    const tag = required ? 'required' : 'optional';
+    for (;;) {
+      say();
+      say(`${name} (${tag}${secretShaped ? ', a secret' : ''})${help ? ` — ${help}` : ''}`);
+      const how = await prompter.choose(`How should ${name} be set?`, [
+        { value: 'literal', label: 'a literal value (stored in plaintext, shown on every GET)' },
+        { value: 'secret', label: 'an existing secret' },
+        { value: 'new', label: 'a new secret (entered now, without echo)' },
+        { value: 'skip', label: required ? 'skip (not allowed: required)' : 'skip' },
+      ]);
+      if (how === 'skip') {
+        if (!required) return;
+        say(`  ${name} is required`);
+        continue;
+      }
+      if (how === 'literal') {
+        const value = await prompter.ask(`Value for ${name}`);
+        if (value === '' && required) {
+          say(`  ${name} is required`);
+          continue;
+        }
+        if (secretShaped) say('  note: the metadata marks this a secret; a literal is stored in plaintext');
+        env[name] = value;
+        return;
+      }
+      if (how === 'secret') {
+        const names = await secretNames();
+        if (names.length === 0) {
+          say('  no secrets stored yet — choose "a new secret"');
+          continue;
+        }
+        const picked = await prompter.choose('Which secret?', names.map((n) => ({ value: n })));
+        env[name] = { secret: picked };
+        return;
+      }
+      // 'new': stored IMMEDIATELY, before the create, so the reference the
+      // body carries names a secret that exists. The value goes on its own
+      // PUT and nowhere else — not the body, not the epilogue.
+      const secretName = await prompter.ask('Secret name', { default: name });
+      const value = await prompter.secret(`Value for ${secretName}`);
+      if (value === '') {
+        say('  an empty secret is not stored');
+        continue;
+      }
+      // Sealed to the account key on the way out — the SAME path `secret
+      // set` takes (secrets.mjs), so the wizard cannot store a value the
+      // gateway can read. A refused PUT re-asks the row rather than ending
+      // the wizard: the value never reached the store, so nothing is
+      // half-done, and the person can pick another way (an existing secret,
+      // a literal, skip).
+      try {
+        await storeSecretSealed(api, secretName, value, { stderr });
+      } catch (error) {
+        say(`  ${error.message}`);
+        say(`  ${secretName} was not stored.`);
+        continue;
+      }
+      secretsStored.push(secretName);
+      if (existingSecrets && !existingSecrets.includes(secretName)) existingSecrets.push(secretName);
+      env[name] = { secret: secretName };
+      return;
+    }
+  }
+
+  if (preview.env.length > 0) {
+    say();
+    say(`Environment proposed by the package's ${preview.envSource ?? 'metadata'}:`);
+  }
+  for (const row of preview.env) await envRow(row.name, row);
+  while (await prompter.confirm('Add another environment variable?', false)) {
+    const name = await prompter.ask('Variable name');
+    if (!name) continue;
+    await envRow(name, { required: false, secret: false });
+  }
+
+  // --- dependencies -------------------------------------------------------
+  // Not asked for a bundle: the API refuses dependencies on one ("ships its
+  // own tree"), and asking a question whose every answer is refused is
+  // worse than saying so once.
+  const dependencies = [];
+  const isBundle = source.type === 'mcpb';
+  say();
+  if (isBundle) say('A bundle ships its own tree: no dependencies, and no version channel to follow.');
+  else {
+    say('Dependencies are tools the MCP shells out to that are not in its npm tree');
+    say(`(the flag form: ${DEP_GRAMMAR}).`);
+  }
+  while (!isBundle && (await prompter.confirm('Add a dependency?', false))) {
+    const kind = await prompter.choose('Dependency kind', [
+      { value: 'github-release', label: 'a GitHub release asset (a binary on the PATH)' },
+      { value: 'npm', label: 'an npm package (its bins on the PATH)' },
+    ]);
+    if (kind === 'npm') {
+      const { pkg, version } = parseNpmSpec(await prompter.ask('Package (name[@version|dist-tag])'));
+      dependencies.push({ kind: 'npm', pkg, ...(version ? { version } : {}) });
+    } else {
+      const repo = await prompter.ask('Repository (owner/repo)');
+      const tag = await prompter.ask('Release tag', { default: 'latest' });
+      const asset = await prompter.ask('Asset name (exact, or a glob with * matching exactly one)');
+      const bins = (await prompter.ask('Executables to extract (comma-separated)'))
+        .split(',')
+        .map((b) => b.trim())
+        .filter(Boolean);
+      const sha256 = await prompter.ask('sha256 of the asset (only when GitHub reports no digest; blank otherwise)', {
+        default: '',
+      });
+      dependencies.push({ kind: 'github-release', repo, tag, asset, bin: bins, ...(sha256 ? { sha256 } : {}) });
+    }
+  }
+  if (dependencies.length > 0 && (await prompter.confirm('Re-resolve the preview with these dependencies?', false))) {
+    try {
+      preview = await api('POST', '/api/v1/registrations/preview', { source, dependencies });
+      printPreview(say, preview);
+    } catch (error) {
+      say(`  ${error.message}`);
+    }
+  }
+
+  // --- options ------------------------------------------------------------
+  // No runtime question: there is one tier since the isolated one was retired
+  // (2026-09-11), and no egress question either — `requireEgressPolicy` asks
+  // it of a TENANT, and this CLI authenticates with MCP_HOST_ADMIN_TOKEN, so
+  // its caller is always the operator (index.mjs `buildRegisterBody` says the
+  // whole of it). The portal is where a tenant is asked.
+  //
+  // Same for `follow`: the API refuses it on a bundle (no channel to follow).
+  const follow = isBundle ? false : await prompter.confirm('Follow the latest version (the daily cron moves the pin)?', false);
+  // Default YES, because the server's default is yes: since
+  // docs/GLOBAL-REGISTRATIONS.md §5 a registration that says nothing GETS a
+  // persistent HOME, and a question whose default contradicted the server's
+  // would hand somebody the opposite of what they read. The ANSWER is sent
+  // only when it is "no" — see the body below.
+  const dataDir = await prompter.confirm('Persistent data directory (HOME on the runner volume)?', true);
+  const perUserChild = await prompter.confirm('One child per connected user (per-user credentials)?', false);
+  // Asked AFTER dataDir on purpose: a bridged MCP's fetchproxy identity lives
+  // under its HOME, so without persistence the pair code changes on every cold
+  // start and the extension has to be re-paired each time
+  // (docs/BROWSER-BRIDGE.md). The prompt says so rather than letting someone
+  // discover it later, and the default follows what was just answered.
+  const bridge = await prompter.confirm(
+    dataDir
+      ? 'Route this MCP\'s fetches through your browser (the fetchproxy bridge)?'
+      : 'Route this MCP\'s fetches through your browser (the fetchproxy bridge)? Without a persistent data directory its pair code changes on every cold start',
+    false,
+  );
+
+  // The body `register` would have built from the equivalent flags: defaults
+  // omitted, `dependencies` only when there are any. No `account` either — the
+  // wizard never asks for one, and an absent account is the caller's own.
+  const body = {
+    slug,
+    displayName,
+    source,
+    env,
+    enabledTools: null,
+    ...(follow ? { updatePolicy: 'follow' } : {}),
+    // Sent only when DECLINED. Omitted means "the server decides", and it
+    // decides yes; a `false` is the one answer the body has to carry, or the
+    // question would be decorative.
+    ...(dataDir ? {} : { dataDir: false }),
+    ...(perUserChild ? { perUserChild: true } : {}),
+    ...(bridge ? { bridge: true } : {}),
+    ...(dependencies.length > 0 ? { dependencies } : {}),
+  };
+  if (preview.package && preview.package.bins.length > 1) {
+    const bin = await prompter.choose('The package has several bins; which one is the MCP?', preview.package.bins.map((b) => ({ value: b })));
+    body.command = { bin };
+  }
+
+  // --- summary + confirm --------------------------------------------------
+  say();
+  say('Summary');
+  say(`  slug:     ${slug}`);
+  say(`  name:     ${displayName}`);
+  say(`  source:   ${describeSource(preview.source)}`);
+  for (const [name, value] of Object.entries(env)) {
+    say(`  env:      ${name} = ${typeof value === 'string' ? value : `{secret ${value.secret}}`}`);
+  }
+  for (const dep of dependencies) say(`  dep:      ${depSpec(dep)}`);
+  if (follow) say('  follow latest: yes');
+  say(`  data dir: ${dataDir ? 'yes' : 'no'}`);
+  if (perUserChild) say('  per-user child: yes');
+  if (bridge) say(`  browser bridge: yes${dataDir ? '' : ' (no data dir — the pair code changes on every cold start)'}`);
+  say();
+  say('Equivalent command:');
+  say(`  ${equivalentCommand(body)}`);
+  say();
+
+  // Said on every exit that is not a created registration — a declined
+  // confirm AND a refused create — because the secrets were stored when they
+  // were entered, and a person who was never told would not know to `rm`.
+  const sayStoredSecrets = () => {
+    if (secretsStored.length === 0) return;
+    say(`The secret${secretsStored.length > 1 ? 's' : ''} already stored stay stored: ${secretsStored.join(', ')}`);
+    say('(remove with `mcp-host secret rm <NAME>`).');
+  };
+
+  if (!(await prompter.confirm('Register it?', true))) {
+    say('Not registered.');
+    sayStoredSecrets();
+    return { registration: null, body, secretsStored };
+  }
+
+  let registration;
+  try {
+    registration = await api('POST', '/api/v1/registrations', body);
+  } catch (error) {
+    // Not retried: a refused create is usually the slug or the source, and
+    // the answers that led here are the equivalent command printed above —
+    // edit it and run that. Rethrown so the CLI exits 1 as `register` would.
+    say(`  ${error.message}`);
+    say('Not registered.');
+    sayStoredSecrets();
+    throw error;
+  }
+  say();
+  say('Add to claude.ai: Settings -> Connectors -> Add custom connector ->');
+  say(`  URL: ${registration.shortConnectUrl ?? registration.connectUrl}`);
+  say('  Sign in there and approve the connection — no key to paste.');
+  say();
+  say('Next time, the same registration without the questions:');
+  say(`  ${equivalentCommand(body)}`);
+  return { registration, body, secretsStored };
+}
+
+function printPreview(say, preview) {
+  say();
+  say(`Pinned: ${describeSource(preview.source)}`);
+  if (preview.source.type === 'npm') say(`  integrity: ${preview.source.integrity ?? '(none recorded — installs unverified)'}`);
+  if (preview.package) {
+    if (preview.package.description) say(`  ${preview.package.description}`);
+    say(`  bins: ${preview.package.bins.length > 0 ? preview.package.bins.join(', ') : '(none)'}`);
+  }
+  for (const dep of preview.dependencies ?? []) {
+    say(
+      dep.kind === 'npm'
+        ? `  dependency: npm ${dep.pkg}@${dep.version}`
+        : `  dependency: ${dep.repo}@${dep.tag} ${dep.asset}${dep.sha256 ? ` sha256 ${dep.sha256}` : ''}`,
+    );
+  }
+  for (const note of preview.notes ?? []) say(`  note: ${note}`);
+  for (const skipped of preview.skipped ?? []) say(`  skipped ${skipped.name}: ${skipped.reason}`);
+}