zoodealio 0.1.0 → 0.2.0

package/README.md

@@ -10,22 +10,38 @@ It has no runtime dependencies and needs Node 22 or newer.
 
 ## Install
 
-Run it without installing:
-
 ```sh
-npx zoodealio whoami
+npm install -g zoodealio
+zoodealio login
+zoodealio whoami
 ```
 
-or install it globally:
+or run it without installing: `npx zoodealio whoami` (after a `zoodealio login` elsewhere, or with
+`ZOODEALIO_API_KEY` set). From a checkout of this repo, `node integrations/cli/bin/zoodealio.js`
+runs the working copy.
+
+## Authenticate
+
+### Sign in (the default)
 
 ```sh
-npm install -g zoodealio
-zoodealio whoami
+zoodealio login            # opens your browser; approve "Sign in Zoodealio CLI on <device>"
+zoodealio login --no-browser   # print the URL to stderr instead (SSH, containers)
+zoodealio login --name work-laptop   # device name shown at sign-in (default: this host)
+zoodealio logout           # revokes this machine's key and forgets it
 ```
 
-From a checkout of this repo, `node integrations/cli/bin/zoodealio.js` runs the working copy.
+`login` binds a loopback port, sends you to Zoodealio AI to approve, and exchanges the one-time
+code (with PKCE) for a personal API key named `CLI – <device>`. It waits up to 5 minutes. It prints
+`{ok, email, name, keyPrefix, origin}` and never the key.
 
-## Authenticate
+The key is stored per API origin in `$XDG_CONFIG_HOME/zoodealio/credentials.json`
+(default `~/.config/zoodealio/credentials.json`; `%APPDATA%\zoodealio\credentials.json` on Windows),
+written atomically with mode `0600` in a `0700` directory. Keys are per environment:
+`zoodealio login --env dev` stores a separate login. `ZOODEALIO_WEB_URL` overrides the sign-in
+page origin the way `ZOODEALIO_API_URL` overrides the API origin.
+
+### API key for CI and servers
 
 Copy a personal API key from **Settings → API** in Zoodealio AI and export it:
 
@@ -33,12 +49,46 @@ Copy a personal API key from **Settings → API** in Zoodealio AI and export it:
 export ZOODEALIO_API_KEY=zoo_...
 ```
 
-The key is read only from this variable and sent only as the `ApiKey` header. It is never
-printed: errors, `--dry-run` output and `whoami` show it as `zoo_…<last4>`. Redirects are
-refused so the header cannot be forwarded. A missing key is a usage error (exit 2) and no
-request is sent. The key keeps its owner's workspace and property scope.
+`ZOODEALIO_API_KEY` wins over a stored login. If neither is present the CLI exits 3 with
+`Not signed in. Run zoodealio login, or set ZOODEALIO_API_KEY.` and sends nothing.
+A 401 on a stored login means it was revoked or expired; run `zoodealio login` again.
+
+The key is sent only as the `ApiKey` header. It is never printed: errors, `--dry-run` output and
+`whoami` show it as `zoo_…<last4>` (the one exception is `keys create`, whose purpose is to show a
+new key once). Redirects are refused so the header cannot be forwarded. The key keeps its owner's
+workspace and property scope. Every request sends `User-Agent: zoodealio-cli/<version>`.
+
+`zoodealio whoami` confirms the key works and shows the target origin, `source` (`login` or
+`env`) and, for a login, the `email`.
+
+### Keys
+
+```sh
+zoodealio keys list                 # your keys; "current" marks the one in use
+zoodealio keys create --name ci     # prints the raw key once
+zoodealio keys revoke <id> --yes
+```
+
+Key management needs a key created by `zoodealio login`; keys made with `keys create` or in the web
+app cannot manage keys.
+
+### MCP
+
+`zoodealio mcp` is a stdio MCP server that forwards each JSON-RPC message to the hosted
+`/openapi/mcp` endpoint with your key, so MCP clients need no HTTP or header setup.
+
+```sh
+claude mcp add zoodealio -- zoodealio mcp
+```
+
+Cursor (`.cursor/mcp.json`) or VS Code (`.vscode/mcp.json`, under `servers`):
+
+```json
+{ "mcpServers": { "zoodealio": { "command": "zoodealio", "args": ["mcp"] } } }
+```
 
-`zoodealio whoami` confirms the key works and shows the target origin.
+Run `zoodealio login` first (or put `ZOODEALIO_API_KEY` in the client's `env`). Stdout carries only
+JSON-RPC; logs go to stderr.
 
 ## Environments
 
@@ -69,9 +119,9 @@ for usage and network errors. A 429 adds `retryAfter` in seconds.
 | Exit | Meaning | `code` |
 | --- | --- | --- |
 | 0 | Success | |
-| 1 | Other API or network error | `http_error`, `network_error` |
-| 2 | Usage: unknown command or flag, missing argument, bad ID or JSON, missing `--yes`, missing key, or HTTP 400 | `usage`, `bad_request` |
-| 3 | Not authenticated or not allowed (401, 403) | `unauthorized`, `forbidden` |
+| 1 | Other API or network error; login cancelled or timed out | `http_error`, `network_error`, `login_cancelled`, `login_timeout` |
+| 2 | Usage: unknown command or flag, missing argument, bad ID or JSON, missing `--yes`, or HTTP 400 | `usage`, `bad_request` |
+| 3 | Not signed in, or not authenticated or allowed (401, 403) | `unauthorized`, `forbidden` |
 | 4 | Not found (404) | `not_found` |
 | 5 | Conflict, precondition or validation failure (409, 412, 422) | `conflict`, `precondition_failed`, `validation_failed` |
 | 6 | Rate limited (429) | `rate_limited` |
@@ -120,12 +170,15 @@ concurrency on `properties update`, `offers accept` and `offers request-details`
 | `webhooks create` | POST Webhooks | `--url` and `--event` (repeatable) or `--body` |
 | `webhooks update <id>` | PUT Webhooks/{id} | `--body` (`endpointUrl`, `eventTypes`, `isActive`) |
 | `webhooks rotate <id>`, `webhooks delete <id>` | POST, DELETE | `--yes` required |
-| `whoami` | | Key check; prints `{ok, origin, key}` |
+| `login`, `logout` | | Browser sign-in and sign-out; `login` takes `--no-browser`, `--name` |
+| `keys list\|create\|revoke` | GET, POST, DELETE Keys | `create`: `--name`; `revoke <id>` needs `--yes`; needs a `login` key |
+| `mcp` | POST `/openapi/mcp` | stdio MCP bridge |
+| `whoami` | | Key check; prints `{ok, origin, key, source, email?}` |
 | `openapi` | GET `/_openapi/partner.json` | Partner OpenAPI document; no key needed |
 | `api <METHOD> <path>` | any `/openapi/...` | `--query k=v` (repeatable), `--body`; `DELETE` needs `--yes` |
 | `commands` | | Command catalogue as JSON |
 
-Destructive commands (`offers accept`, `team remove`, `properties photos delete`,
+Destructive commands (`keys revoke`, `offers accept`, `team remove`, `properties photos delete`,
 `properties documents delete`, `webhooks rotate`, `webhooks delete`, and `api ... DELETE`)
 refuse to run without `--yes`, exit 2, and send nothing. `--dry-run` previews them
 without `--yes`, since it sends nothing either.
@@ -179,8 +232,8 @@ zoodealio api GET Properties --query pageSize=5
 
 - No multipart uploads of local files. Photos and documents are imported from URLs only
   (`photos add --url`); `api` cannot send multipart either.
-- No config file, keychain or interactive prompts; the environment variable is the only
-  credential source.
+- No keychain or interactive prompts. Credentials are `ZOODEALIO_API_KEY` or the
+  `credentials.json` written by `zoodealio login`.
 
 ## Development
 
@@ -192,13 +245,15 @@ npm run check   # eslint, tsc --noEmit (checkJs), node --test
 
 ## Releasing
 
-Maintainers publish from their machine with a granular npm token kept outside the repo:
+npm no longer lets a token that bypasses 2FA publish directly, so releases are staged and then
+approved by a maintainer with 2FA:
 
 ```sh
 cd integrations/cli
 npm version <patch|minor|major> --no-git-tag-version   # in a PR, then merge
 npm run check
-npm publish --userconfig ~/.config/zoodealio/npm-publish.npmrc
+npm stage publish --userconfig ~/.config/zoodealio/npm-publish.npmrc
 ```
 
-A version with a `-` suffix (`0.2.0-beta.1`) goes out with `--tag next` so `latest` stays stable.
+Then approve it on npmjs.com (avatar → Staged Packages → Approve). A version with a `-` suffix
+(`0.2.0-beta.1`) is staged with `--tag next` so `latest` stays stable.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zoodealio",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Zoodealio command line tool: the partner API as JSON, built for people, scripts and AI agents",
   "license": "UNLICENSED",
   "repository": {

package/src/cli.js

@@ -2,12 +2,15 @@ const { CliError, usage } = require('./errors');
 const { parse, normalizeApiPath, METHODS } = require('./args');
 const { catalogue } = require('./commands');
 const { resolveBody } = require('./input');
-const { redactKey, resolveOrigin, buildUrl, send } = require('./http');
-const pkg = require('../package.json');
+const { USER_AGENT, redactKey, scrubKeys, resolveOrigin, buildUrl, send } = require('./http');
+const { readCredential, saveCredential, removeCredential } = require('./credentials');
+const { browserLogin, resolveWebOrigin, defaultDevice } = require('./login');
+const { bridge } = require('./mcp');
 
 /**
  * @typedef {{env: Record<string, string | undefined>, stdout: {write(s: string): unknown, isTTY?: boolean},
- *   stderr: {write(s: string): unknown}, stdin: AsyncIterable<string | Buffer>, fetch?: typeof fetch}} Io
+ *   stderr: {write(s: string): unknown}, stdin: AsyncIterable<string | Buffer>, fetch?: typeof fetch,
+ *   openBrowser?: (url: string) => Promise<void>, loginTimeoutMs?: number}} Io
  */
 
 /**
@@ -17,20 +20,18 @@ const pkg = require('../package.json');
  * @returns {Promise<number>} exit code
  */
 async function run(argv, io) {
-    const key = (io.env.ZOODEALIO_API_KEY || '').trim();
+    const envKey = (io.env.ZOODEALIO_API_KEY || '').trim();
+    /** Every key seen this run; none may appear in output. */
+    const secrets = new Set(envKey ? [envKey] : []);
     try {
-        await execute(argv, io, key);
+        await execute(argv, io, envKey, secrets);
         return 0;
     } catch (err) {
         const error = err instanceof CliError
             ? err
             : new CliError({ exit: 1, code: 'internal', title: 'Unexpected error', detail: /** @type {Error} */ (err).message });
-        let text = JSON.stringify(error.toJSON());
-        if (key) {
-            // The key can appear JSON-escaped (newline, quote, backslash) inside the serialized error.
-            for (const form of [key, JSON.stringify(key).slice(1, -1)]) text = text.split(form).join(redactKey(key));
-        }
-        io.stderr.write(`${text}\n`);
+        // A key can appear JSON-escaped (newline, quote, backslash) inside the serialized error.
+        io.stderr.write(`${scrubKeys(JSON.stringify(error.toJSON()), secrets)}\n`);
         return error.exit;
     }
 }
@@ -38,9 +39,10 @@ async function run(argv, io) {
 /**
  * @param {string[]} argv
  * @param {Io} io
- * @param {string} key
+ * @param {string} envKey
+ * @param {Set<string>} secrets
  */
-async function execute(argv, io, key) {
+async function execute(argv, io, envKey, secrets) {
     const parsed = parse(argv);
     if ('help' in parsed) {
         io.stdout.write(parsed.help);
@@ -53,6 +55,46 @@ async function execute(argv, io, key) {
 
     if (command.name === 'commands') return emit(catalogue());
 
+    const origin = resolveOrigin(io.env, flags.env);
+    const stored = readCredential(io.env, origin);
+    if (stored) secrets.add(stored.key);
+    const source = envKey ? 'env' : stored ? 'login' : undefined;
+    const key = envKey || stored?.key || '';
+
+    if (['login', 'logout', 'mcp'].includes(command.name)) {
+        if (flags['dry-run']) throw usage(`--dry-run is not supported for \`${command.name}\``);
+        if (command.name === 'login') {
+            const result = await browserLogin({
+                apiOrigin: origin, webOrigin: resolveWebOrigin(io.env, flags.env), device: (flags.name?.trim() || defaultDevice()).slice(0, 64),
+                noBrowser: !!flags['no-browser'], openBrowser: io.openBrowser, timeoutMs: io.loginTimeoutMs, stderr: io.stderr, fetch: io.fetch,
+            });
+            secrets.add(result.key);
+            saveCredential(io.env, origin, { key: result.key, keyId: result.keyId, email: result.email, name: result.name });
+            return emit({ ok: true, email: result.email, name: result.name, keyPrefix: result.keyPrefix, origin });
+        }
+        if (command.name === 'logout') {
+            if (!stored) {
+                return emit({
+                    ok: true, loggedOut: false,
+                    detail: envKey ? 'Signed in only through ZOODEALIO_API_KEY; nothing to sign out of.' : 'Not signed in.',
+                });
+            }
+            try {
+                await send(io.fetch || fetch, {
+                    method: 'DELETE', url: buildUrl(origin, `/openapi/Keys/${encodeURIComponent(stored.keyId)}`, []),
+                    headers: { Accept: 'application/json', 'User-Agent': USER_AGENT, ApiKey: stored.key },
+                });
+            } catch (err) {
+                // 401/404 mean the key is already gone; anything else keeps the login so it can be retried.
+                if (!(err instanceof CliError) || (err.status !== 401 && err.status !== 404)) throw err;
+            }
+            removeCredential(io.env, origin);
+            return emit({ ok: true, loggedOut: true, email: stored.email, origin });
+        }
+        if (!key) throw notSignedIn();
+        return bridge({ url: origin, key, stdin: io.stdin, stdout: io.stdout, stderr: io.stderr, fetch: io.fetch, scrub: (s) => scrubKeys(s, secrets), storedLogin: source === 'login' });
+    }
+
     /** @type {string} */
     let method;
     /** @type {string} */
@@ -90,14 +132,13 @@ async function execute(argv, io, key) {
     }
 
     const needsKey = command.auth !== false;
-    if (needsKey && !key && !flags['dry-run']) throw usage('ZOODEALIO_API_KEY is not set');
+    if (needsKey && !key && !flags['dry-run']) throw notSignedIn();
 
-    const origin = resolveOrigin(io.env, flags.env);
     const url = buildUrl(origin, path, query);
     /** @param {string} apiKey */
     const headers = (apiKey) => ({
         Accept: 'application/json',
-        'User-Agent': `zoodealio-cli/${pkg.version}`,
+        'User-Agent': USER_AGENT,
         ...(needsKey ? { ApiKey: apiKey } : {}),
         ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
         ...(flags['if-match'] === undefined ? {} : { 'If-Match': flags['if-match'] }),
@@ -105,9 +146,23 @@ async function execute(argv, io, key) {
 
     if (flags['dry-run']) return emit({ method, url, headers: headers(redactKey(key)), body: body ?? null });
 
-    const result = await send(io.fetch || fetch, { method, url, headers: headers(key), body });
-    if (command.name === 'whoami') return emit({ ok: true, origin, key: redactKey(key) });
+    /** @type {unknown} */
+    let result;
+    try {
+        result = await send(io.fetch || fetch, { method, url, headers: headers(key), body });
+    } catch (err) {
+        if (source === 'login' && err instanceof CliError && err.status === 401) {
+            throw new CliError({ exit: 3, status: 401, code: 'unauthorized', title: 'Login revoked or expired', detail: 'The stored login was revoked or expired. Run zoodealio login again.' });
+        }
+        throw err;
+    }
+    if (command.name === 'keys revoke' && source === 'login' && stored && args.id === stored.keyId) removeCredential(io.env, origin);
+    if (command.name === 'whoami') return emit({ ok: true, origin, key: redactKey(key), source, ...(source === 'login' && stored ? { email: stored.email } : {}) });
     return emit(result);
 }
 
+function notSignedIn() {
+    return new CliError({ exit: 3, code: 'unauthorized', title: 'Not signed in', detail: 'Not signed in. Run zoodealio login, or set ZOODEALIO_API_KEY.' });
+}
+
 module.exports = { run };

package/src/commands.js

@@ -135,6 +135,21 @@ const COMMANDS = [
     cmd('webhooks deliveries', 'List webhook deliveries', 'GET', '/openapi/Webhooks/deliveries', {
         flags: [str('subscription', 'Subscription id', { query: 'subscriptionId' }), str('status', 'Delivery status', { query: 'status' }), ...PAGING],
     }),
+    cmd('login', 'Sign in through the browser and store a CLI key', null, null, {
+        auth: false,
+        flags: [
+            { name: 'no-browser', type: 'boolean', description: 'Print the sign-in URL to stderr instead of opening a browser' },
+            str('name', 'Device name shown at sign-in (default: this host)'),
+        ],
+    }),
+    cmd('logout', 'Revoke the stored CLI key and forget it', 'DELETE', '/openapi/Keys/{keyId}'),
+    cmd('keys list', 'List your API keys (needs a zoodealio login)', 'GET', '/openapi/Keys'),
+    cmd('keys create', 'Create an API key; the raw key is shown once', 'POST', '/openapi/Keys', {
+        flags: [str('name', 'Key name', { required: true })],
+        build: (f) => ({ name: f.name }),
+    }),
+    cmd('keys revoke', 'Revoke an API key', 'DELETE', '/openapi/Keys/{id}', { args: [id('id', 'Key id')], destructive: true }),
+    cmd('mcp', 'Run a stdio MCP server bridged to /openapi/mcp', 'POST', '/openapi/mcp'),
     cmd('whoami', 'Check the API key and show the target origin', 'GET', '/openapi/Webhooks/event-types'),
     cmd('openapi', 'Print the partner OpenAPI document (no key needed)', 'GET', '/_openapi/partner.json', { auth: false }),
     cmd('api', 'Call any /openapi endpoint directly (DELETE needs --yes)', null, null, {
@@ -194,7 +209,7 @@ function helpText(prefix) {
         for (const a of exact.args) lines.push(`  <${a.name}>  ${a.description}`);
         for (const f of exact.flags) lines.push(`  --${f.name}  ${f.description}${f.required ? ' (required)' : ''}`);
     } else {
-        lines.push('zoodealio <command> [args] [flags]', '', 'JSON on stdout; errors as JSON on stderr. Key: ZOODEALIO_API_KEY.', '');
+        lines.push('zoodealio <command> [args] [flags]', '', 'JSON on stdout; errors as JSON on stderr. Sign in with `zoodealio login` or set ZOODEALIO_API_KEY.', '');
         for (const c of matches) lines.push(`  ${c.name.padEnd(28)}${c.summary}`);
         lines.push('', 'Global flags:');
         for (const f of GLOBAL_FLAGS) lines.push(`  --${f.name.padEnd(10)}${f.description}`);

package/src/credentials.js

@@ -0,0 +1,87 @@
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { CliError } = require('./errors');
+
+/**
+ * @typedef {{key: string, keyId: string, email: string, name: string}} Credential
+ */
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @returns {string} directory holding credentials.json
+ */
+function configDir(env) {
+    if (env.XDG_CONFIG_HOME) return path.join(env.XDG_CONFIG_HOME, 'zoodealio');
+    if (process.platform === 'win32' && env.APPDATA) return path.join(env.APPDATA, 'zoodealio');
+    return path.join(env.HOME || os.homedir(), '.config', 'zoodealio');
+}
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @param {boolean} [strict] throw instead of returning empty when the file exists but is unreadable, so a rewrite cannot wipe it
+ * @returns {Record<string, Credential>} stored logins keyed by API origin; empty when missing (or unreadable, unless strict)
+ */
+function readAll(env, strict = false) {
+    const file = path.join(configDir(env), 'credentials.json');
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
+    } catch (err) {
+        if (/** @type {NodeJS.ErrnoException} */ (err).code === 'ENOENT') return {};
+    }
+    if (strict) {
+        throw new CliError({ exit: 1, code: 'credentials_unreadable', title: 'Credentials file is unreadable', detail: `${file} is not valid JSON. Fix or delete it, then run zoodealio login again.` });
+    }
+    return {};
+}
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @param {string} origin
+ * @returns {Credential | undefined}
+ */
+function readCredential(env, origin) {
+    const all = readAll(env);
+    const entry = Object.hasOwn(all, origin) ? all[origin] : undefined;
+    return entry && typeof entry.key === 'string' && entry.key ? entry : undefined;
+}
+
+/**
+ * Writes atomically (temp file, then rename) with owner-only permissions.
+ * @param {Record<string, string | undefined>} env
+ * @param {Record<string, Credential>} all
+ */
+function writeAll(env, all) {
+    const dir = configDir(env);
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const temp = path.join(dir, `credentials.json.${process.pid}.tmp`);
+    try {
+        fs.writeFileSync(temp, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600, flag: 'w' });
+        fs.renameSync(temp, path.join(dir, 'credentials.json'));
+    } catch (err) {
+        fs.rmSync(temp, { force: true });
+        throw err;
+    }
+}
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @param {string} origin
+ * @param {Credential} credential
+ */
+function saveCredential(env, origin, credential) {
+    writeAll(env, { ...readAll(env, true), [origin]: credential });
+}
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @param {string} origin
+ */
+function removeCredential(env, origin) {
+    const all = readAll(env, true);
+    delete all[origin];
+    writeAll(env, all);
+}
+
+module.exports = { configDir, readCredential, saveCredential, removeCredential };

package/src/http.js

@@ -1,5 +1,7 @@
 const { CliError, usage } = require('./errors');
+const pkg = require('../package.json');
 
+const USER_AGENT = `zoodealio-cli/${pkg.version}`;
 const ENVS = { prod: 'https://api.zoodealio.ai', dev: 'https://dev.api.zoodealio.ai' };
 
 /** @type {Record<number, [number, string]>} status -> [exit code, error code slug] */
@@ -23,6 +25,20 @@ function redactKey(key) {
     return key.length >= 12 ? `zoo_…${key.slice(-4)}` : 'zoo_…';
 }
 
+/**
+ * Replaces every known key in text, raw or JSON-escaped, with its redacted form.
+ * @param {string} text
+ * @param {Iterable<string>} keys
+ * @returns {string}
+ */
+function scrubKeys(text, keys) {
+    let out = text;
+    for (const key of keys) {
+        for (const form of [key, JSON.stringify(key).slice(1, -1)]) out = out.split(form).join(redactKey(key));
+    }
+    return out;
+}
+
 /**
  * @param {Record<string, string | undefined>} env
  * @param {string | undefined} envName
@@ -107,4 +123,4 @@ async function send(doFetch, req) {
     }
 }
 
-module.exports = { ENVS, redactKey, resolveOrigin, buildUrl, send };
+module.exports = { ENVS, USER_AGENT, redactKey, scrubKeys, resolveOrigin, buildUrl, send };

package/src/login.js

@@ -0,0 +1,136 @@
+const crypto = require('node:crypto');
+const http = require('node:http');
+const os = require('node:os');
+const { spawn } = require('node:child_process');
+const { CliError } = require('./errors');
+const { USER_AGENT, send } = require('./http');
+
+const WEB_ENVS = { prod: 'https://zoodealio.ai', dev: 'https://dev.zoodealio.ai' };
+const LOGIN_TIMEOUT_MS = 5 * 60 * 1000;
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @param {string | undefined} envName
+ * @returns {string} web origin without trailing slash
+ */
+function resolveWebOrigin(env, envName) {
+    if (env.ZOODEALIO_WEB_URL) return env.ZOODEALIO_WEB_URL.replace(/\/+$/, '');
+    return WEB_ENVS[/** @type {'prod'|'dev'} */ (envName === 'dev' ? 'dev' : 'prod')];
+}
+
+/**
+ * Opens a URL in the default browser. Rejects when no opener could be started.
+ * @param {string} url
+ * @returns {Promise<void>}
+ */
+function openBrowser(url) {
+    const [command, args, options] = process.platform === 'win32'
+        ? ['cmd', ['/d', '/s', '/c', `start "" "${url}"`], { windowsVerbatimArguments: true }]
+        : [process.platform === 'darwin' ? 'open' : 'xdg-open', [url], {}];
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: 'ignore', detached: true, ...options });
+        child.once('error', reject);
+        child.once('spawn', () => {
+            child.unref();
+            resolve();
+        });
+    });
+}
+
+const PAGE = (/** @type {string} */ message) => `<!doctype html><meta charset="utf-8"><title>Zoodealio CLI</title><body style="font-family:system-ui;text-align:center;margin-top:4rem"><h1>${message}</h1><p>You can close this tab and return to your terminal.</p>`;
+
+/**
+ * Listens on a loopback port for the browser's one redirect back to /callback.
+ * @param {string} state
+ * @param {number} timeoutMs
+ * @returns {Promise<{port: number, result: Promise<{code?: string, error?: string}>, close: () => void}>}
+ */
+async function listenForCallback(state, timeoutMs) {
+    /** @type {(r: {code?: string, error?: string}) => void} */
+    let finish = () => {};
+    /** @type {(e: Error) => void} */
+    let fail = () => {};
+    const result = new Promise((resolve, reject) => { finish = resolve; fail = reject; });
+    const stateBuffer = Buffer.from(state);
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url || '/', 'http://127.0.0.1');
+        const got = Buffer.from(url.searchParams.get('state') || '');
+        res.setHeader('Connection', 'close');
+        if (req.method !== 'GET' || url.pathname !== '/callback') {
+            res.writeHead(404).end();
+        } else if (got.length !== stateBuffer.length || !crypto.timingSafeEqual(got, stateBuffer)) {
+            // A stray or forged request must not be able to abort the real login.
+            res.writeHead(400, { 'content-type': 'text/html; charset=utf-8' }).end(PAGE('Sign-in link did not match'));
+        } else if (url.searchParams.get('error')) {
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }).end(PAGE('Sign-in cancelled'));
+            finish({ error: /** @type {string} */ (url.searchParams.get('error')) });
+        } else if (url.searchParams.get('code')) {
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }).end(PAGE('Signed in to the Zoodealio CLI'));
+            finish({ code: /** @type {string} */ (url.searchParams.get('code')) });
+        } else {
+            res.writeHead(400).end();
+        }
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => resolve(undefined));
+    });
+    const timer = setTimeout(() => fail(new CliError({ exit: 1, code: 'login_timeout', title: 'Login timed out', detail: 'No sign-in came back from the browser. Run zoodealio login again.' })), timeoutMs);
+    return {
+        port: /** @type {import('node:net').AddressInfo} */ (server.address()).port,
+        result,
+        close: () => {
+            clearTimeout(timer);
+            server.close();
+            server.closeIdleConnections();
+        },
+    };
+}
+
+/**
+ * Browser sign-in (authorization code + PKCE). Returns the exchange response; the caller stores it.
+ * @param {{apiOrigin: string, webOrigin: string, device: string, noBrowser: boolean,
+ *   openBrowser?: (url: string) => Promise<void>, timeoutMs?: number, stderr: {write(s: string): unknown}, fetch?: typeof fetch}} opts
+ * @returns {Promise<{key: string, keyId: string, keyPrefix: string, name: string, email: string}>}
+ */
+async function browserLogin(opts) {
+    const state = crypto.randomBytes(32).toString('base64url');
+    const verifier = crypto.randomBytes(32).toString('base64url');
+    const challenge = crypto.createHash('sha256').update(verifier).digest('base64url');
+    const listener = await listenForCallback(state, opts.timeoutMs ?? LOGIN_TIMEOUT_MS);
+    try {
+        const url = `${opts.webOrigin}/cli/login?${new URLSearchParams({ port: String(listener.port), state, challenge, device: opts.device })}`;
+        let opened = false;
+        if (!opts.noBrowser) {
+            try {
+                await (opts.openBrowser || openBrowser)(url);
+                opened = true;
+            } catch {
+                // fall through to printing the URL
+            }
+        }
+        if (!opened) opts.stderr.write(`Open this URL in a browser to sign in:\n${url}\n`);
+
+        const { code, error } = await listener.result;
+        if (!code) {
+            throw new CliError({
+                exit: 1, code: error === 'cancelled' ? 'login_cancelled' : 'login_failed',
+                title: error === 'cancelled' ? 'Login cancelled' : 'Login failed',
+                detail: error === 'cancelled' ? 'Sign-in was cancelled in the browser.' : `The browser reported: ${error}`,
+            });
+        }
+        return /** @type {any} */ (await send(opts.fetch || fetch, {
+            method: 'POST',
+            url: `${opts.apiOrigin}/openapi/cli-logins/exchange`,
+            headers: { Accept: 'application/json', 'Content-Type': 'application/json', 'User-Agent': USER_AGENT },
+            body: { code, verifier },
+        }));
+    } finally {
+        listener.close();
+    }
+}
+
+/** @returns {string} */
+const defaultDevice = () => os.hostname().slice(0, 64) || 'cli';
+
+module.exports = { browserLogin, resolveWebOrigin, defaultDevice };

package/src/mcp.js

@@ -0,0 +1,107 @@
+const { StringDecoder } = require('node:string_decoder');
+const { USER_AGENT } = require('./http');
+
+/** @typedef {{write(s: string): unknown}} Sink */
+
+/** @param {string} text @returns {unknown[]} the JSON payload of each data event */
+function sseMessages(text) {
+    const messages = [];
+    for (const event of text.split(/\r?\n\r?\n/)) {
+        const data = event.split(/\r?\n/).filter((l) => l.startsWith('data:')).map((l) => l.slice(5).replace(/^ /, '')).join('\n');
+        if (!data) continue;
+        try {
+            messages.push(JSON.parse(data));
+        } catch {
+            // not JSON (keep-alive or comment)
+        }
+    }
+    return messages;
+}
+
+/**
+ * Bridges newline-delimited JSON-RPC on stdin to the remote MCP endpoint, one POST per message.
+ * Stdout carries only JSON-RPC responses; logs go to stderr.
+ * @param {{url: string, key: string, stdin: AsyncIterable<string | Buffer>, stdout: Sink, stderr: Sink,
+ *   fetch?: typeof fetch, scrub?: (s: string) => string, storedLogin?: boolean}} opts
+ */
+async function bridge(opts) {
+    const doFetch = opts.fetch || fetch;
+    const scrub = opts.scrub || ((/** @type {string} */ s) => s);
+    /** @type {string | undefined} */
+    let sessionId;
+    /** @type {Set<Promise<void>>} */
+    const pending = new Set();
+
+    /** @param {unknown} message */
+    const emit = (message) => opts.stdout.write(`${JSON.stringify(message)}\n`);
+    /** @param {unknown} id @param {number} code @param {string} message */
+    const fail = (id, code, message) => {
+        const text = scrub(message);
+        opts.stderr.write(`zoodealio mcp: ${text}\n`);
+        if (id !== undefined) emit({ jsonrpc: '2.0', id, error: { code, message: text } });
+    };
+
+    /** @param {string} line */
+    async function forward(line) {
+        let message;
+        try {
+            message = JSON.parse(line);
+        } catch {
+            return fail(null, -32700, 'Parse error: input line is not valid JSON');
+        }
+        const id = message && typeof message === 'object' && 'id' in message ? message.id : undefined;
+        try {
+            const res = await doFetch(`${opts.url}/openapi/mcp`, {
+                method: 'POST',
+                headers: {
+                    ApiKey: opts.key,
+                    Accept: 'application/json, text/event-stream',
+                    'Content-Type': 'application/json',
+                    'User-Agent': USER_AGENT,
+                    ...(sessionId ? { 'Mcp-Session-Id': sessionId } : {}),
+                },
+                body: line,
+                redirect: 'error',
+                signal: AbortSignal.timeout(300000),
+            });
+            const text = await res.text();
+            sessionId ??= res.headers.get('mcp-session-id') || undefined;
+            if (!res.ok) {
+                let detail = '';
+                try {
+                    const problem = JSON.parse(text);
+                    detail = problem.detail || problem.title || '';
+                } catch {
+                    // non-JSON error body
+                }
+                const hint = res.status === 401 && opts.storedLogin ? '. The stored login was revoked or expired; run zoodealio login again' : '';
+                return fail(id, -32000, `HTTP ${res.status}${detail ? `: ${detail}` : ''}${hint}`);
+            }
+            if (!text.trim()) return;
+            const payloads = (res.headers.get('content-type') || '').includes('text/event-stream') ? sseMessages(text) : [JSON.parse(text)];
+            for (const payload of payloads.flat()) emit(payload);
+        } catch (err) {
+            const e = /** @type {{message?: string, cause?: {message?: string}}} */ (err);
+            fail(id, -32000, e.cause?.message || e.message || 'request failed');
+        }
+    }
+
+    const decoder = new StringDecoder('utf8');
+    let buffer = '';
+    /** @param {string} line */
+    const dispatch = (line) => {
+        if (!line.trim()) return;
+        const p = forward(line).finally(() => pending.delete(p));
+        pending.add(p);
+    };
+    for await (const chunk of opts.stdin) {
+        buffer += typeof chunk === 'string' ? chunk : decoder.write(chunk);
+        const lines = buffer.split('\n');
+        buffer = /** @type {string} */ (lines.pop());
+        lines.forEach(dispatch);
+    }
+    dispatch(buffer + decoder.end());
+    await Promise.all(pending);
+}
+
+module.exports = { bridge };