@stage-labs/metro 0.1.0-beta.15 → 0.1.0-beta.16

package/dist/api.js

@@ -0,0 +1,58 @@
+import { metroUrl, readToken } from './store.js';
+export class NotSignedIn extends Error {
+}
+const TIMEOUT_MS = 20_000;
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+export function carriesSecretsSafely(base) {
+    let url;
+    try {
+        url = new URL(base);
+    }
+    catch {
+        return false;
+    }
+    if (url.protocol === 'https:')
+        return true;
+    return url.protocol === 'http:' && LOOPBACK.has(url.hostname);
+}
+function tokenOrThrow() {
+    if (!carriesSecretsSafely(metroUrl()))
+        throw new Error(`refusing to send your session to ${metroUrl()} in the clear — use https, or a loopback address`);
+    const token = readToken();
+    if (token === null)
+        throw new NotSignedIn('not signed in — run `metro login` first');
+    return token;
+}
+async function get(path, presented) {
+    const auth = presented ?? tokenOrThrow();
+    let res;
+    try {
+        res = await fetch(`${metroUrl()}${path}`, {
+            headers: { authorization: `Bearer ${auth}` },
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+    }
+    catch {
+        throw new Error(`could not reach ${metroUrl()}`);
+    }
+    if (res.status === 401)
+        throw new NotSignedIn('that sign-in has expired — run `metro login` again');
+    if (!res.ok)
+        throw new Error(`metro answered ${String(res.status)}`);
+    return res.json();
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export async function mcpServers() {
+    const body = await get('/api/connectors');
+    if (!isRecord(body) || typeof body.json !== 'string')
+        throw new Error('metro returned an unexpected response');
+    return body.json;
+}
+export async function sessionEmail(presented) {
+    const body = await get('/api/session', presented);
+    if (!isRecord(body) || typeof body.email !== 'string')
+        throw new Error('metro returned an unexpected response');
+    return body.email;
+}

package/dist/cli.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+import { mcpServers, NotSignedIn, sessionEmail } from './api.js';
+import { signIn } from './login.js';
+import { clearToken, credentialsPath, metroUrl, writeToken } from './store.js';
+import { update } from './update.js';
+import { currentVersion } from './version.js';
+const USAGE = `metro — the command line for your MCP connectors
+
+  metro login     sign in to metro in your browser
+  metro logout    forget this machine's sign-in
+  metro whoami    print the account this machine is signed in as
+  metro mcp       print an mcpServers block for every connector
+  metro update    update to the newest published version
+  metro version   print this CLI's version
+
+Start Claude Code with all of them, without writing them to disk:
+
+  claude --mcp-config <(metro mcp)
+
+  METRO_URL     the metro to talk to (default https://mcp.metro.box)
+  METRO_TOKEN   use this session instead of the stored one
+`;
+async function login() {
+    const token = await signIn();
+    const email = await sessionEmail(token).catch(() => '');
+    writeToken(token);
+    process.stderr.write(`Signed in${email === '' ? '' : ` as ${email}`}. Stored in ${credentialsPath()}\n`);
+}
+async function whoami() {
+    process.stdout.write(`${await sessionEmail()} on ${metroUrl()}\n`);
+}
+const HELP = new Set([undefined, 'help', '--help', '-h']);
+const COMMANDS = {
+    login: async () => {
+        await login();
+        return 0;
+    },
+    logout: async () => {
+        clearToken();
+        process.stderr.write('Signed out.\n');
+        return Promise.resolve(0);
+    },
+    whoami: async () => {
+        await whoami();
+        return 0;
+    },
+    mcp: async () => {
+        process.stdout.write(`${await mcpServers()}\n`);
+        return 0;
+    },
+    update,
+    version: async () => {
+        process.stdout.write(`${currentVersion()}\n`);
+        return Promise.resolve(0);
+    },
+};
+async function run(command) {
+    const handler = command === undefined ? undefined : COMMANDS[command];
+    if (handler !== undefined)
+        return handler();
+    process.stderr.write(USAGE);
+    return Promise.resolve(HELP.has(command) ? 0 : 1);
+}
+const code = await run(process.argv[2]).catch((err) => {
+    const message = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`metro: ${message}\n`);
+    return err instanceof NotSignedIn ? 2 : 1;
+});
+process.exit(code);

package/dist/login.js

@@ -0,0 +1,102 @@
+import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { metroUrl } from './store.js';
+const TIMEOUT_MS = 5 * 60_000;
+const MAX_BODY = 16 * 1024;
+const PAGE = `<!doctype html><meta charset="utf-8"><title>Metro</title>
+<body style="font:16px system-ui;padding:3rem;color:#222">
+<p id="m">Finishing sign-in…</p>
+<script>
+const nonce = new URLSearchParams(location.search).get('s') || '';
+const body = new URLSearchParams(location.hash.replace(/^#/, ''));
+body.set('s', nonce);
+fetch('/token', { method: 'POST', body }).then(
+  () => { document.getElementById('m').textContent = 'Signed in. You can close this tab.'; },
+  () => { document.getElementById('m').textContent = 'Could not reach the metro CLI.'; },
+);
+</script>`;
+function browserCommand(url) {
+    if (process.platform === 'darwin')
+        return { cmd: 'open', args: [url] };
+    if (process.platform === 'win32')
+        return { cmd: 'cmd', args: ['/c', 'start', '', url] };
+    return { cmd: 'xdg-open', args: [url] };
+}
+function openBrowser(url) {
+    if (process.env.METRO_NO_BROWSER === '1')
+        return;
+    const { cmd, args } = browserCommand(url);
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+    child.on('error', () => undefined);
+    child.unref();
+}
+async function readBody(req) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buf = chunk;
+        size += buf.length;
+        if (size > MAX_BODY)
+            throw new Error('sign-in body too large');
+        chunks.push(buf);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+export function sessionFrom(body, nonce) {
+    const params = new URLSearchParams(body);
+    if (params.get('s') !== nonce)
+        return '';
+    return params.get('session') ?? '';
+}
+export function signIn() {
+    const nonce = randomBytes(16).toString('base64url');
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = (err, token) => {
+            if (settled)
+                return;
+            settled = true;
+            server.close();
+            clearTimeout(timer);
+            if (err !== null)
+                reject(err);
+            else
+                resolve(token ?? '');
+        };
+        const accept = (res, body) => {
+            const session = sessionFrom(body, nonce);
+            if (session === '') {
+                res.writeHead(400).end();
+                return;
+            }
+            res.writeHead(204).end();
+            finish(null, session);
+        };
+        const server = createServer((req, res) => {
+            if (req.method !== 'POST' || !(req.url ?? '').startsWith('/token')) {
+                res.writeHead(200, { 'content-type': 'text/html; charset=utf-8' }).end(PAGE);
+                return;
+            }
+            readBody(req).then((body) => {
+                accept(res, body);
+            }, () => {
+                res.writeHead(400).end();
+            });
+        });
+        const timer = setTimeout(() => {
+            finish(new Error('sign-in timed out'));
+        }, TIMEOUT_MS);
+        timer.unref();
+        server.on('error', (err) => {
+            finish(err);
+        });
+        server.listen(0, '127.0.0.1', () => {
+            const { port } = server.address();
+            const returnTo = `http://127.0.0.1:${String(port)}/callback?s=${nonce}`;
+            const url = `${metroUrl()}/auth/google/start?return_to=${encodeURIComponent(returnTo)}`;
+            process.stderr.write(`Opening ${url}\n`);
+            openBrowser(url);
+        });
+    });
+}

package/dist/store.js

@@ -0,0 +1,63 @@
+import { chmodSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+const DEFAULT_BASE = 'https://mcp.metro.box';
+export function metroUrl() {
+    const raw = process.env.METRO_URL?.trim();
+    return raw === undefined || raw === '' ? DEFAULT_BASE : raw.replace(/\/+$/, '');
+}
+function configDir() {
+    const xdg = process.env.XDG_CONFIG_HOME?.trim();
+    const base = xdg === undefined || xdg === '' ? join(homedir(), '.config') : xdg;
+    return join(base, 'metro');
+}
+export function credentialsPath() {
+    return join(configDir(), 'credentials.json');
+}
+function readStored() {
+    let raw;
+    try {
+        raw = readFileSync(credentialsPath(), 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return null;
+    const { token, url } = parsed;
+    if (typeof token !== 'string' || token === '')
+        return null;
+    return { token, url: typeof url === 'string' ? url : DEFAULT_BASE };
+}
+export function readToken() {
+    const fromEnv = process.env.METRO_TOKEN?.trim();
+    if (fromEnv !== undefined && fromEnv !== '')
+        return fromEnv;
+    const stored = readStored();
+    if (stored === null)
+        return null;
+    return stored.url === metroUrl() ? stored.token : null;
+}
+export function writeToken(token) {
+    const path = credentialsPath();
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    writeFileSync(path, `${JSON.stringify({ token, url: metroUrl() })}\n`, {
+        mode: 0o600,
+    });
+    chmodSync(path, 0o600);
+}
+export function clearToken() {
+    try {
+        rmSync(credentialsPath());
+    }
+    catch {
+        return;
+    }
+}

package/dist/update.js

@@ -0,0 +1,33 @@
+import { spawnSync } from 'node:child_process';
+import { currentVersion, isNewer, PACKAGE_NAME, publishedVersion, } from './version.js';
+export function managerFor(location) {
+    return location.includes('/.bun/') ? 'bun' : 'npm';
+}
+export function installArgs(manager, version) {
+    const spec = `${PACKAGE_NAME}@${version}`;
+    return manager === 'bun'
+        ? ['add', '--global', spec]
+        : ['install', '--global', spec];
+}
+export async function update() {
+    const current = currentVersion();
+    const newest = await publishedVersion();
+    if (newest === '') {
+        process.stderr.write('npm published no version this CLI understands\n');
+        return 1;
+    }
+    if (!isNewer(newest, current)) {
+        process.stderr.write(`metro ${current} is the newest published version\n`);
+        return 0;
+    }
+    const manager = managerFor(import.meta.url);
+    const args = installArgs(manager, newest);
+    process.stderr.write(`Updating metro ${current} to ${newest} with ${manager}\n`);
+    const run = spawnSync(manager, args, { stdio: 'inherit' });
+    if (run.error !== undefined || run.status !== 0) {
+        process.stderr.write(`That did not work. Run it yourself:\n  ${manager} ${args.join(' ')}\n`);
+        return 1;
+    }
+    process.stderr.write(`metro is now ${newest}\n`);
+    return 0;
+}

package/dist/version.js

@@ -0,0 +1,97 @@
+import { readFileSync } from 'node:fs';
+export const PACKAGE_NAME = '@stage-labs/metro';
+const REGISTRY = 'https://registry.npmjs.org';
+const TIMEOUT_MS = 15_000;
+export function parseVersion(raw) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/.exec(raw.trim());
+    if (match === null)
+        return null;
+    const core = [match[1], match[2], match[3]].map((n) => Number(n));
+    const pre = match[4] === undefined
+        ? []
+        : match[4]
+            .split('.')
+            .map((part) => (/^\d+$/.test(part) ? Number(part) : part));
+    return { core, pre };
+}
+function comparePart(left, right) {
+    if (left === undefined)
+        return -1;
+    if (right === undefined)
+        return 1;
+    if (left === right)
+        return 0;
+    if (typeof left === 'number' && typeof right === 'number')
+        return left < right ? -1 : 1;
+    if (typeof left === 'number')
+        return -1;
+    if (typeof right === 'number')
+        return 1;
+    return left < right ? -1 : 1;
+}
+function comparePre(a, b) {
+    if (a.length === 0 && b.length === 0)
+        return 0;
+    if (a.length === 0)
+        return 1;
+    if (b.length === 0)
+        return -1;
+    for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+        const cmp = comparePart(a[i], b[i]);
+        if (cmp !== 0)
+            return cmp;
+    }
+    return 0;
+}
+export function compareVersions(a, b) {
+    const left = parseVersion(a);
+    const right = parseVersion(b);
+    if (left === null || right === null)
+        return 0;
+    for (let i = 0; i < 3; i += 1) {
+        const l = left.core[i] ?? 0;
+        const r = right.core[i] ?? 0;
+        if (l !== r)
+            return l < r ? -1 : 1;
+    }
+    return comparePre(left.pre, right.pre);
+}
+export function isNewer(candidate, current) {
+    return compareVersions(candidate, current) > 0;
+}
+export function currentVersion() {
+    const path = new URL('../package.json', import.meta.url);
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    return typeof raw.version === 'string' ? raw.version : '0.0.0';
+}
+export function newestOf(tags) {
+    let best = '';
+    for (const value of Object.values(tags)) {
+        if (typeof value !== 'string' || parseVersion(value) === null)
+            continue;
+        if (best === '' || isNewer(value, best))
+            best = value;
+    }
+    return best;
+}
+export async function publishedVersion() {
+    let res;
+    try {
+        res = await fetch(`${REGISTRY}/${PACKAGE_NAME.replace('/', '%2F')}`, {
+            headers: { accept: 'application/json' },
+            signal: AbortSignal.timeout(TIMEOUT_MS),
+        });
+    }
+    catch {
+        throw new Error('could not reach the npm registry');
+    }
+    if (!res.ok)
+        throw new Error(`npm answered ${String(res.status)}`);
+    const body = await res.json();
+    if (typeof body !== 'object' || body === null)
+        throw new Error('npm returned an unexpected response');
+    const tags = body['dist-tags'];
+    if (typeof tags !== 'object' || tags === null)
+        throw new Error('npm returned no dist-tags');
+    return newestOf(tags);
+}

package/package.json

@@ -1,8 +1,7 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.15",
-  "private": false,
-  "description": "Event-interception wire. Supervises train subprocesses in ~/.metro/trains/, multiplexes their JSON event stream onto stdout, and routes outbound action calls back via stdin. Per-platform code is written by the agent (or user) as train scripts — metro core is pure transport.",
+  "version": "0.1.0-beta.16",
+  "description": "The metro command line. Sign in once per machine, then hand your MCP connector list to Claude Code without the credentials touching disk, argv or shell history.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -15,39 +14,25 @@
     "node": ">=22"
   },
   "bin": {
-    "metro": "./dist/cli/index.js"
+    "metro": "dist/cli.js"
   },
   "files": [
-    "dist",
-    "docs",
-    "examples",
-    "skills",
-    "README.md",
-    "LICENSE"
+    "dist"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "tag": "beta"
   },
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "tsc",
-    "lint": "eslint src/ examples/",
-    "lint:fix": "eslint src/ examples/ --fix",
-    "typecheck": "tsc --noEmit",
-    "test": "METRO_STATE_DIR=\"$(mktemp -d /tmp/metro-test.XXXXXX)\" bun test test/"
-  },
-  "dependencies": {
-    "pino": "^9.5.0",
-    "pino-pretty": "^13.1.3",
-    "ws": "^8.20.0"
+    "test": "tsc --noEmit && bun test test/"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.0",
-    "@types/node": "^22.10.0",
-    "@types/ws": "^8.18.1",
+    "@stage-labs/config": "0.1.0-beta.2",
     "eslint": "^10.3.0",
-    "typescript": "^5",
-    "typescript-eslint": "^8.59.2"
-  },
-  "packageManager": "bun@1.3.9"
+    "knip": "^6.15.0",
+    "madge": "^8.0.0",
+    "typescript": "^5"
+  }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 Stage Labs
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/README.md

@@ -1,139 +0,0 @@
-# Metro
-
-[![npm](https://img.shields.io/npm/v/@stage-labs/metro/beta?label=npm&color=cb3837)](https://www.npmjs.com/package/@stage-labs/metro)
-[![lines of code](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.codetabs.com%2Fv1%2Floc%2F%3Fgithub%3Dbonustrack%2Fmetro%26ignored%3Dapps%2Ctest&query=%24%5B0%5D.linesOfCode&label=lines%20of%20TypeScript&color=blue)](https://github.com/bonustrack/metro)
-
-> **Event-interception wire. Supervises train subprocesses, multiplexes their stdout into one
-> JSON event stream, routes outbound action calls back via stdin. Per-platform code lives in
-> train scripts under `~/.metro/trains/` — outside this repo — written by the user (or agent)
-> on demand.**
-
-Metro is not a framework with platform connectors. Metro is the wire.
-
-```
-[Claude Code session]
-
-$ metro &                              # backgrounded
-$ Monitor( … metro's stdout … )
-
->>> {"kind":"inbound","station":"discord","line":"metro://discord/123…","message_id":"9876",
-     "text":"@metro 5xx spike on /v1/sync — look?",
-     "payload":{"channelId":"123…","guildId":"456…","content":"<@…> 5xx spike…",
-                "mentions":{"users":["<bot-id>"],"roles":[],"everyone":false},…}}
-
-  [I'd grep services/sync.ts, then…]
-  Bash: metro call discord send '{"line":"metro://discord/123…","text":"three deploys in the last 24h…","replyTo":"9876"}'
-```
-
-You own streaming, tool calls, and reply timing. Metro is the wire.
-
----
-
-## Quickstart
-
-```bash
-npm install -g @stage-labs/metro@beta    # or: bun add -g @stage-labs/metro@beta
-
-# One-time train setup (Telegram — no npm deps needed; uses native fetch)
-mkdir -p ~/.metro && cd ~/.metro && bun init -y
-cp $(npm root -g)/@stage-labs/metro/examples/telegram.ts ~/.metro/trains/
-echo 'TELEGRAM_BOT_TOKEN=your-token' >> ~/.metro/.env
-
-metro doctor                                # verify
-metro                                       # run the daemon
-```
-
-For Discord, copy the same `telegram.ts` and port it — swap the API base for
-`https://discord.com/api/v10` with `Authorization: Bot $TOKEN`, install
-`discord.js` for the gateway (`cd ~/.metro && bun add discord.js`), and keep
-the same envelope + `op:"call"` ↔ `op:"response"` protocol. See
-[`examples/README.md`](./examples/README.md) for the wire-format reference.
-
-Requires **Bun ≥ 1.3** (trains run under `bun run`). Metro core itself works under Node ≥ 22.
-
----
-
-## Architecture
-
-```
-~/.metro/trains/discord.ts ──> stdout JSON ──┐
-~/.metro/trains/telegram.ts ─> stdout JSON ──┤
-~/.metro/trains/<anything>.ts ─> stdout ─────┼──>  metro daemon ──>  stdout (Monitor / Codex push)
-                                             │                       history.jsonl
-HTTP /wh/<id>  (builtin webhook receiver) ───┤
-IPC `notify`   (builtin cross-user channel) ─┘
-
-metro call discord send {…}  ──>  IPC ──>  daemon  ──>  train stdin  ──>  response  ──> CLI stdout
-```
-
-Every event metro emits is a `HistoryEntry`. Trains produce the full envelope; metro
-enriches `id`/`display` and appends to `history.jsonl`. Outbound action calls are
-train-defined — metro core knows the protocol (`{op:"call", id, action, args}` → `{op:"response", id, result|error}`),
-not what any specific action does.
-
----
-
-## Train protocol
-
-**Inbound (train → metro stdout)** — one JSON line per event (wire fields are `snake_case`):
-
-```json
-{"kind":"inbound","station":"discord","line":"metro://discord/123","from":"metro://discord/user/456","from_name":"alice","message_id":"789","text":"hi","is_private":false,"ts":"2026-05-17T18:00:00Z","payload":{...}}
-```
-
-**Outbound (metro → train stdin)** — one JSON line per action call:
-
-```json
-{"op":"call","id":"req_abc","action":"send","args":{"line":"metro://discord/123","text":"hi"}}
-```
-
-Train responds on stdout:
-
-```json
-{"op":"response","id":"req_abc","result":{"messageId":"999"}}
-```
-
-See [`examples/telegram.ts`](./examples/telegram.ts) (a self-contained ~110 LOC reference train) and [`examples/README.md`](./examples/README.md) for the full protocol + Discord port notes.
-
----
-
-## CLI
-
-```
-metro                                    # start the daemon (foreground)
-metro trains list                        # supervised trains + state
-metro trains new <name>                  # scaffold ~/.metro/trains/<name>.ts from the example
-metro trains restart <name>              # kill + respawn a train (resets backoff)
-metro call <train> <action> <args>       # forward an action call; args = JSON / @file / - / string
-metro tail [--as=<user-uri>] [--follow]  # subscribe to the event log; claim-aware
-metro history [--limit=50] [--line=…]    # recent history (newest first), filterable
-metro lines                              # recently-seen conversations
-metro claim <line>                       # take exclusive ownership of a line
-metro release <line>                     # release
-metro claims                             # print the claims map
-metro webhook add <label> [--secret=…]   # add an HTTP receive endpoint
-metro webhook list | remove <id>         # manage endpoints
-metro tunnel setup <name> <hostname>     # configure a Cloudflare named tunnel
-metro tunnel status                      # show current tunnel config
-metro setup [skill [clear]]              # status; or install/remove the skill into ~/.claude / ~/.codex
-metro doctor                             # health check (trains, deps, tunnel, webhooks, env vars)
-metro update                             # upgrade in place
-```
-
-No more `metro send / reply / edit / react / download / fetch` — outbound is always
-`metro call <train> <action> <args>`, with action names defined by the train.
-
----
-
-## State
-
-- `~/.metro/trains/` — your train scripts
-- `~/.metro/.env` — your credentials (trains read these)
-- `~/.metro/package.json` — `bun add` here for train deps
-- `$METRO_STATE_DIR` (default `~/.cache/metro/`) — history, claims, cursors, monitor data
-
----
-
-## License
-
-MIT