@anyslate/cli 0.2.0 → 0.3.0

package/src/oauth.mjs

@@ -0,0 +1,633 @@
+// OAuth 2.1 authorization-code + PKCE + Dynamic Client Registration for
+// `anyslate login`.
+//
+// WHY THIS EXISTS. `anyslate login --token as_mcp_…` required the user to open
+// the desktop app, mint a token, and paste it into a terminal. That is four
+// context switches for a first-run experience, and the pasted token never
+// expires, so it is also the worst credential to leave lying in a shell
+// history. The browser flow replaces it for humans; `--token` stays for CI.
+//
+// EVERY ENDPOINT IS DISCOVERED, NOTHING IS GUESSED.
+//   GET {root}/.well-known/oauth-authorization-server → issuer,
+//       authorization_endpoint, token_endpoint, registration_endpoint,
+//       code_challenge_methods_supported, grant_types_supported
+//   GET {root}/.well-known/oauth-protected-resource   → resource
+//
+// The `resource` value is REQUIRED on /oauth/authorize and accepted on
+// /oauth/token. It is read from the protected-resource document for the root
+// being logged into — never hardcoded — because dev, prod and a local wrangler
+// instance each publish a different one, and a wrong `resource` is rejected at
+// the authorize step with no useful diagnostic.
+//
+// LOOPBACK PORTS AND THE REGISTERED REDIRECT URI. RFC 8252 §7.3 says a native
+// app must be able to bind an ephemeral loopback port, so the server's
+// redirect-URI comparison ignores the port for loopback URIs (it compares
+// protocol + hostname + pathname). We therefore register ONE canonical
+// `http://127.0.0.1/callback` and send the actual `http://127.0.0.1:<port>/callback`
+// at authorize/exchange time. Registering the live port instead would burn a
+// Dynamic Client Registration on every login — and DCR is rate limited to 10
+// per hour, so that would lock a user out after ten logins.
+
+import { createHash, randomBytes } from 'node:crypto';
+import { createServer } from 'node:http';
+import { spawn } from 'node:child_process';
+import { USER_AGENT } from './version.mjs';
+import { classifyNetworkError } from './mcp-client.mjs';
+
+export const AS_METADATA_PATH = '/.well-known/oauth-authorization-server';
+export const RESOURCE_METADATA_PATH = '/.well-known/oauth-protected-resource';
+
+export const LOOPBACK_HOST = '127.0.0.1';
+export const CALLBACK_PATH = '/callback';
+
+/** The URI we register once and reuse forever. The port is deliberately absent. */
+export const REGISTERED_REDIRECT_URI = `http://${LOOPBACK_HOST}${CALLBACK_PATH}`;
+
+export const CLIENT_NAME = 'AnySlate CLI';
+
+/** How long `login` waits on the loopback listener, in seconds. */
+export const DEFAULT_CALLBACK_TIMEOUT_S = 180;
+
+/** Access tokens live 3600s. Refresh this far ahead of expiry. */
+export const REFRESH_SKEW_MS = 5 * 60 * 1000;
+
+/** Fallback when the token response omits `expires_in` (server sends 3600). */
+export const DEFAULT_EXPIRES_IN_S = 3600;
+
+// ---------------------------------------------------------------------------
+// PKCE
+// ---------------------------------------------------------------------------
+
+/** @param {Buffer|Uint8Array|string} input */
+export function base64url(input) {
+  return Buffer.from(input)
+    .toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/, '');
+}
+
+/**
+ * S256: challenge = base64url(sha256(ASCII(verifier))).
+ *
+ * The hash is taken over the verifier's ASCII characters, NOT over the random
+ * bytes it was derived from. Hashing the raw bytes produces a challenge the
+ * server can never reproduce, and the failure surfaces only at the token
+ * endpoint as an opaque `invalid_grant`.
+ *
+ * @param {string} verifier
+ * @returns {string}
+ */
+export function deriveCodeChallenge(verifier) {
+  return base64url(createHash('sha256').update(verifier, 'ascii').digest());
+}
+
+/**
+ * 64 random bytes → 86 base64url chars, inside RFC 7636's 43–128 range.
+ * @param {number} [bytes]
+ * @returns {{verifier: string, challenge: string, method: 'S256'}}
+ */
+export function generatePkce(bytes = 64) {
+  const verifier = base64url(randomBytes(bytes));
+  return { verifier, challenge: deriveCodeChallenge(verifier), method: 'S256' };
+}
+
+export function generateState() {
+  return base64url(randomBytes(32));
+}
+
+// ---------------------------------------------------------------------------
+// HTTP helpers
+// ---------------------------------------------------------------------------
+
+function hostOf(url) {
+  try {
+    return new URL(url).host;
+  } catch {
+    return String(url);
+  }
+}
+
+async function requestJson(url, { method = 'GET', body, headers = {}, fetchImpl = fetch, timeoutMs = 15_000 }) {
+  const ac = new AbortController();
+  const timer = setTimeout(() => ac.abort(), timeoutMs);
+  let res;
+  try {
+    res = await fetchImpl(url, {
+      method,
+      headers: { accept: 'application/json', 'user-agent': USER_AGENT, ...headers },
+      body,
+      signal: ac.signal,
+    });
+  } catch (e) {
+    return { ok: false, networkError: true, detail: classifyNetworkError(e, hostOf(url), timeoutMs) };
+  } finally {
+    clearTimeout(timer);
+  }
+
+  let parsed = null;
+  let text = '';
+  try {
+    text = await res.text();
+    parsed = text ? JSON.parse(text) : null;
+  } catch {
+    parsed = null;
+  }
+  return { ok: res.ok, status: res.status, body: parsed, text, res };
+}
+
+/** `{error, error_description}` rendered for a human, without losing either half. */
+export function oauthErrorText(body, fallback) {
+  if (body && typeof body === 'object') {
+    const err = typeof body.error === 'string' ? body.error : null;
+    const desc = typeof body.error_description === 'string' ? body.error_description : null;
+    if (err && desc) return `${err}: ${desc}`;
+    if (err) return err;
+    if (desc) return desc;
+  }
+  return fallback;
+}
+
+// ---------------------------------------------------------------------------
+// Discovery
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch BOTH well-known documents. Either one missing is a hard failure —
+ * falling back to guessed paths (`/oauth/authorize`, `/oauth/token`) would turn
+ * "this host does not speak OAuth" into a confusing 404 three steps later.
+ *
+ * @param {{root: string, fetchImpl?: typeof fetch, timeoutMs?: number}} opts
+ * @returns {Promise<{ok: true, issuer: string|null, authorizationEndpoint: string,
+ *   tokenEndpoint: string, registrationEndpoint: string, revocationEndpoint: string|null,
+ *   resource: string, codeChallengeMethods: string[], grantTypes: string[], root: string}
+ *   | {ok: false, code: string, message: string}>}
+ */
+export async function discover({ root, fetchImpl = fetch, timeoutMs = 15_000 }) {
+  const host = hostOf(root);
+
+  const meta = await requestJson(`${root}${AS_METADATA_PATH}`, { fetchImpl, timeoutMs });
+  if (meta.networkError) {
+    return {
+      ok: false,
+      code: 'discovery_unreachable',
+      message: `anyslate: cannot reach ${host} for OAuth discovery — ${meta.detail}. Check --api-url and your network.`,
+    };
+  }
+  if (!meta.ok || !meta.body || typeof meta.body !== 'object') {
+    return {
+      ok: false,
+      code: 'discovery_failed',
+      message:
+        `anyslate: OAuth discovery failed at ${host} — GET ${AS_METADATA_PATH} returned HTTP ${meta.status}. ` +
+        `That host does not advertise an OAuth authorization server. Check --api-url, or sign in with \`anyslate login --token <BEARER>\`.`,
+    };
+  }
+
+  const authorizationEndpoint = str(meta.body.authorization_endpoint);
+  const tokenEndpoint = str(meta.body.token_endpoint);
+  const registrationEndpoint = str(meta.body.registration_endpoint);
+  const missing = [
+    !authorizationEndpoint && 'authorization_endpoint',
+    !tokenEndpoint && 'token_endpoint',
+    !registrationEndpoint && 'registration_endpoint',
+  ].filter(Boolean);
+  if (missing.length) {
+    return {
+      ok: false,
+      code: 'discovery_incomplete',
+      message: `anyslate: OAuth discovery at ${host} is missing ${missing.join(', ')}. The CLI will not guess endpoint paths.`,
+    };
+  }
+
+  const codeChallengeMethods = Array.isArray(meta.body.code_challenge_methods_supported)
+    ? meta.body.code_challenge_methods_supported.map(String)
+    : [];
+  if (codeChallengeMethods.length && !codeChallengeMethods.includes('S256')) {
+    return {
+      ok: false,
+      code: 'pkce_unsupported',
+      message: `anyslate: ${host} does not advertise PKCE S256 (got [${codeChallengeMethods.join(',')}]). The CLI will not fall back to a weaker method.`,
+    };
+  }
+
+  const resourceDoc = await requestJson(`${root}${RESOURCE_METADATA_PATH}`, { fetchImpl, timeoutMs });
+  if (resourceDoc.networkError) {
+    return {
+      ok: false,
+      code: 'discovery_unreachable',
+      message: `anyslate: cannot reach ${host} for OAuth discovery — ${resourceDoc.detail}. Check --api-url and your network.`,
+    };
+  }
+  const resource = str(resourceDoc.body?.resource);
+  if (!resourceDoc.ok || !resource) {
+    return {
+      ok: false,
+      code: 'resource_missing',
+      message:
+        `anyslate: OAuth discovery failed at ${host} — GET ${RESOURCE_METADATA_PATH} returned HTTP ${resourceDoc.status} with no \`resource\`. ` +
+        `That value is required on /oauth/authorize and the CLI reads it from this document rather than assuming one.`,
+    };
+  }
+
+  return {
+    ok: true,
+    root,
+    issuer: str(meta.body.issuer) || null,
+    authorizationEndpoint,
+    tokenEndpoint,
+    registrationEndpoint,
+    revocationEndpoint: str(meta.body.revocation_endpoint) || null,
+    resource,
+    codeChallengeMethods,
+    grantTypes: Array.isArray(meta.body.grant_types_supported) ? meta.body.grant_types_supported.map(String) : [],
+  };
+}
+
+function str(v) {
+  return typeof v === 'string' && v.trim() ? v.trim() : '';
+}
+
+// ---------------------------------------------------------------------------
+// Dynamic Client Registration
+// ---------------------------------------------------------------------------
+
+/**
+ * DCR is rate limited to 10/hour. The caller MUST cache the returned client_id
+ * per root and reuse it; this function does no caching of its own.
+ *
+ * @param {{registrationEndpoint: string, redirectUri?: string, clientName?: string,
+ *          fetchImpl?: typeof fetch, timeoutMs?: number}} opts
+ * @returns {Promise<{ok: true, clientId: string, raw: unknown} | {ok: false, code: string, message: string}>}
+ */
+export async function registerClient({
+  registrationEndpoint,
+  redirectUri = REGISTERED_REDIRECT_URI,
+  clientName = CLIENT_NAME,
+  fetchImpl = fetch,
+  timeoutMs = 15_000,
+}) {
+  const host = hostOf(registrationEndpoint);
+  const res = await requestJson(registrationEndpoint, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({
+      client_name: clientName,
+      redirect_uris: [redirectUri],
+      grant_types: ['authorization_code', 'refresh_token'],
+    }),
+    fetchImpl,
+    timeoutMs,
+  });
+
+  if (res.networkError) {
+    return { ok: false, code: 'unreachable', message: `anyslate: cannot reach ${host} to register the CLI — ${res.detail}.` };
+  }
+  if (res.status === 429) {
+    return {
+      ok: false,
+      code: 'registration_rate_limited',
+      message:
+        `anyslate: ${host} rate limited client registration (10 per hour). ` +
+        `Wait an hour, or sign in with \`anyslate login --token <BEARER>\`.`,
+    };
+  }
+  const clientId = str(res.body?.client_id);
+  if (!res.ok || !clientId) {
+    return {
+      ok: false,
+      code: 'registration_failed',
+      message: `anyslate: client registration at ${host} failed (HTTP ${res.status}) — ${oauthErrorText(res.body, 'no client_id in the response')}.`,
+    };
+  }
+  return { ok: true, clientId, raw: res.body };
+}
+
+// ---------------------------------------------------------------------------
+// Authorize
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{authorizationEndpoint: string, clientId: string, redirectUri: string,
+ *          codeChallenge: string, state: string, resource: string, scope?: string}} opts
+ * @returns {string}
+ */
+export function buildAuthorizeUrl({ authorizationEndpoint, clientId, redirectUri, codeChallenge, state, resource, scope }) {
+  const url = new URL(authorizationEndpoint);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('client_id', clientId);
+  url.searchParams.set('redirect_uri', redirectUri);
+  url.searchParams.set('code_challenge', codeChallenge);
+  url.searchParams.set('code_challenge_method', 'S256');
+  url.searchParams.set('state', state);
+  url.searchParams.set('resource', resource);
+  if (scope) url.searchParams.set('scope', scope);
+  return url.toString();
+}
+
+// ---------------------------------------------------------------------------
+// Loopback listener
+// ---------------------------------------------------------------------------
+
+function callbackPage({ title, body, tone }) {
+  const accent = tone === 'error' ? '#c0392b' : '#2f7d4f';
+  return `<!doctype html><html lang="en"><head><meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${title} · AnySlate</title>
+<style>
+:root{color-scheme:light dark}
+body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;
+font:16px/1.55 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;
+background:#f6f7f9;color:#1c1f23}
+@media (prefers-color-scheme:dark){body{background:#101214;color:#e6e8ea}
+.card{background:#191c1f!important;box-shadow:none!important;border:1px solid #2a2f34}}
+.card{background:#fff;border-radius:14px;padding:40px 44px;max-width:26rem;text-align:center;
+box-shadow:0 1px 3px rgba(0,0,0,.08),0 8px 28px rgba(0,0,0,.06)}
+h1{margin:0 0 .5rem;font-size:1.25rem;color:${accent}}
+p{margin:0;opacity:.8;font-size:.95rem}
+</style></head><body><div class="card"><h1>${title}</h1><p>${body}</p></div></body></html>`;
+}
+
+/**
+ * Bind an ephemeral loopback port and wait for exactly one authorization
+ * callback.
+ *
+ * @param {{state: string, timeoutMs?: number, path?: string, host?: string}} opts
+ * @returns {Promise<{port: number, redirectUri: string,
+ *   waitForResult: () => Promise<{ok: true, code: string} | {ok: false, code: string, message: string}>,
+ *   close: () => Promise<void>}>}
+ */
+export async function startCallbackServer({
+  state,
+  timeoutMs = DEFAULT_CALLBACK_TIMEOUT_S * 1000,
+  path = CALLBACK_PATH,
+  host = LOOPBACK_HOST,
+}) {
+  /** @type {(r: object) => void} */
+  let settle = () => {};
+  let settled = false;
+  const result = new Promise((resolve) => {
+    settle = (r) => {
+      if (settled) return;
+      settled = true;
+      resolve(r);
+    };
+  });
+
+  const server = createServer((req, res) => {
+    let url;
+    try {
+      url = new URL(req.url, `http://${host}`);
+    } catch {
+      res.writeHead(400).end();
+      return;
+    }
+
+    if (url.pathname === '/favicon.ico') {
+      res.writeHead(204).end();
+      return;
+    }
+    if (url.pathname !== path) {
+      res.writeHead(404, { 'content-type': 'text/plain' }).end('not found');
+      return;
+    }
+
+    const send = (status, page) => {
+      res.writeHead(status, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store' });
+      res.end(page);
+    };
+
+    const err = url.searchParams.get('error');
+    if (err) {
+      const desc = url.searchParams.get('error_description') || '';
+      send(400, callbackPage({ title: 'Sign-in failed', body: 'You can close this tab and return to your terminal.', tone: 'error' }));
+      settle({
+        ok: false,
+        code: 'authorize_error',
+        message: `anyslate: the authorization server returned "${err}"${desc ? ` — ${desc}` : ''}.`,
+      });
+      return;
+    }
+
+    // State is checked BEFORE the code is touched. A callback whose state does
+    // not match ours is either a stale tab from a previous attempt or a
+    // cross-site request; either way the `code` in it is not ours to redeem.
+    const got = url.searchParams.get('state') || '';
+    if (got !== state) {
+      send(400, callbackPage({ title: 'Sign-in failed', body: 'This sign-in link did not match the one this terminal started.', tone: 'error' }));
+      settle({
+        ok: false,
+        code: 'state_mismatch',
+        message: 'anyslate: the callback `state` did not match the one this login started with — discarding it. Run `anyslate login` again.',
+      });
+      return;
+    }
+
+    const code = url.searchParams.get('code') || '';
+    if (!code) {
+      send(400, callbackPage({ title: 'Sign-in failed', body: 'The callback carried no authorization code.', tone: 'error' }));
+      settle({ ok: false, code: 'no_code', message: 'anyslate: the callback carried no authorization code.' });
+      return;
+    }
+
+    send(200, callbackPage({ title: 'Signed in to AnySlate', body: 'You can close this tab and return to your terminal.', tone: 'ok' }));
+    settle({ ok: true, code });
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, host, resolve);
+  });
+  const { port } = server.address();
+
+  const timer = setTimeout(() => {
+    settle({
+      ok: false,
+      code: 'timeout',
+      message: `anyslate: timed out after ${Math.round(timeoutMs / 1000)}s waiting for the browser callback. Re-run \`anyslate login\`, or use --timeout <seconds>.`,
+    });
+  }, timeoutMs);
+  if (typeof timer.unref === 'function') timer.unref();
+
+  const close = () =>
+    new Promise((resolve) => {
+      clearTimeout(timer);
+      server.close(() => resolve());
+      server.closeAllConnections?.();
+    });
+
+  return {
+    port,
+    redirectUri: `http://${host}:${port}${path}`,
+    waitForResult: () => result,
+    close,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Token endpoint
+// ---------------------------------------------------------------------------
+
+/**
+ * Turn a token response into the shape we persist. `expires_at` is absolute so
+ * a config file read an hour later is still interpretable.
+ *
+ * @param {unknown} body
+ * @param {number} [now]
+ */
+export function normalizeTokenResponse(body, now = Date.now()) {
+  const b = body && typeof body === 'object' ? body : {};
+  const expiresIn = Number.isFinite(Number(b.expires_in)) ? Number(b.expires_in) : DEFAULT_EXPIRES_IN_S;
+  return {
+    access_token: str(b.access_token),
+    refresh_token: str(b.refresh_token) || null,
+    token_type: str(b.token_type) || 'Bearer',
+    scope: str(b.scope) || null,
+    expires_in: expiresIn,
+    expires_at: new Date(now + expiresIn * 1000).toISOString(),
+  };
+}
+
+async function postToken({ tokenEndpoint, params, fetchImpl, timeoutMs, now }) {
+  const host = hostOf(tokenEndpoint);
+  const form = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v != null && v !== '') form.set(k, String(v));
+  }
+
+  const res = await requestJson(tokenEndpoint, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: form.toString(),
+    fetchImpl,
+    timeoutMs,
+  });
+
+  if (res.networkError) {
+    return { ok: false, code: 'unreachable', message: `anyslate: cannot reach ${host} to exchange tokens — ${res.detail}.` };
+  }
+  if (!res.ok) {
+    return {
+      ok: false,
+      code: str(res.body?.error) || 'token_request_failed',
+      status: res.status,
+      message: `anyslate: ${host} rejected the token request (HTTP ${res.status}) — ${oauthErrorText(res.body, res.text?.slice(0, 200) || 'no detail')}.`,
+    };
+  }
+  const tokens = normalizeTokenResponse(res.body, now);
+  if (!tokens.access_token) {
+    return { ok: false, code: 'no_access_token', message: `anyslate: ${host} returned no access_token.` };
+  }
+  return { ok: true, tokens, raw: res.body };
+}
+
+/**
+ * @param {{tokenEndpoint: string, code: string, redirectUri: string, codeVerifier: string,
+ *          clientId: string, resource: string, fetchImpl?: typeof fetch, timeoutMs?: number, now?: number}} opts
+ */
+export function exchangeCode({ tokenEndpoint, code, redirectUri, codeVerifier, clientId, resource, fetchImpl = fetch, timeoutMs = 15_000, now }) {
+  return postToken({
+    tokenEndpoint,
+    params: {
+      grant_type: 'authorization_code',
+      code,
+      redirect_uri: redirectUri,
+      code_verifier: codeVerifier,
+      client_id: clientId,
+      resource,
+    },
+    fetchImpl,
+    timeoutMs,
+    now,
+  });
+}
+
+/**
+ * Refresh rotation IS enabled server-side (oauth_refresh_tokens.replaced_by_id),
+ * so the caller MUST persist `tokens.refresh_token` immediately — the old one is
+ * dead the moment this resolves.
+ *
+ * @param {{tokenEndpoint: string, refreshToken: string, clientId: string, resource: string,
+ *          fetchImpl?: typeof fetch, timeoutMs?: number, now?: number}} opts
+ */
+export function refreshAccessToken({ tokenEndpoint, refreshToken, clientId, resource, fetchImpl = fetch, timeoutMs = 15_000, now }) {
+  return postToken({
+    tokenEndpoint,
+    params: {
+      grant_type: 'refresh_token',
+      refresh_token: refreshToken,
+      client_id: clientId,
+      resource,
+    },
+    fetchImpl,
+    timeoutMs,
+    now,
+  });
+}
+
+/**
+ * Best effort — a revocation that fails must never stop `logout` from deleting
+ * the local credential, or the user is stuck with a file they cannot clear.
+ *
+ * @param {{revocationEndpoint: string, token: string, clientId?: string,
+ *          tokenTypeHint?: string, fetchImpl?: typeof fetch, timeoutMs?: number}} opts
+ * @returns {Promise<{ok: boolean, status?: number, detail?: string}>}
+ */
+export async function revokeToken({ revocationEndpoint, token, clientId, tokenTypeHint, fetchImpl = fetch, timeoutMs = 8_000 }) {
+  const form = new URLSearchParams();
+  form.set('token', token);
+  if (clientId) form.set('client_id', clientId);
+  if (tokenTypeHint) form.set('token_type_hint', tokenTypeHint);
+
+  const res = await requestJson(revocationEndpoint, {
+    method: 'POST',
+    headers: { 'content-type': 'application/x-www-form-urlencoded' },
+    body: form.toString(),
+    fetchImpl,
+    timeoutMs,
+  });
+  if (res.networkError) return { ok: false, detail: res.detail };
+  return { ok: !!res.ok, status: res.status, detail: res.ok ? undefined : oauthErrorText(res.body, `HTTP ${res.status}`) };
+}
+
+/** The conventional path when discovery does not advertise `revocation_endpoint`. */
+export function revocationEndpointFor(discovery, root) {
+  return discovery?.revocationEndpoint || `${String(root).replace(/\/+$/, '')}/oauth/revoke`;
+}
+
+// ---------------------------------------------------------------------------
+// Browser
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string} url
+ * @param {{platform?: string, spawnImpl?: typeof spawn}} [deps]
+ * @returns {{ok: boolean, command?: string, error?: string}}
+ */
+export function openBrowser(url, deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  const spawnImpl = deps.spawnImpl ?? spawn;
+
+  let cmd;
+  let args;
+  if (platform === 'darwin') {
+    cmd = 'open';
+    args = [url];
+  } else if (platform === 'win32') {
+    // The empty "" is the window title `start` otherwise steals from the URL.
+    cmd = 'cmd';
+    args = ['/c', 'start', '', url];
+  } else {
+    cmd = 'xdg-open';
+    args = [url];
+  }
+
+  try {
+    const child = spawnImpl(cmd, args, { stdio: 'ignore', detached: true });
+    child?.unref?.();
+    child?.on?.('error', () => {});
+    return { ok: true, command: cmd };
+  } catch (e) {
+    return { ok: false, command: cmd, error: String(e?.message ?? e) };
+  }
+}