@streamorchard/grapevine 0.0.0-stage → 0.1.1

package/src/known-apps.js

@@ -0,0 +1,63 @@
+// The apps that speak Grapevine, so each one can show the others on its Connected apps page,
+// even when they aren't installed: name, summary, logo, where to get it, and which release first
+// supported each capability version (to say "Update Pear Drops to 0.1.7"). Add a new app here.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ICONS = path.join(__dirname, '..', 'assets', 'apps');
+
+/**
+ * @typedef {object} KnownApp
+ * @property {string} id the app's install id (the hello's app.id)
+ * @property {string} slug its socket name
+ * @property {string} name
+ * @property {string} summary one sentence, for its card
+ * @property {string} icon a bundled 256×256 PNG
+ * @property {string} homepage
+ * @property {string} download its latest release
+ * @property {string} dataFolder its folder in the OS's app data folder: no folder means not installed
+ * @property {Record<string, string>} firstRelease "capability@major.minor" (or "protocol@N") -> the app version that first had it
+ */
+
+/** @type {KnownApp[]} */
+const KNOWN_APPS = [
+  {
+    id: 'com.streamorchard.peardrops',
+    slug: 'pear-drops',
+    name: 'Pear Drops',
+    summary: "Collects your Kick emote and badge drops for you, watching with Kick's own player.",
+    icon: path.join(ICONS, 'pear-drops.png'),
+    homepage: 'https://github.com/Stream-Orchard/pear-drops',
+    download: 'https://github.com/Stream-Orchard/pear-drops/releases/latest',
+    dataFolder: 'Pear Drops',
+    firstRelease: {},
+  },
+  {
+    id: 'com.glowingpear.streammultiview',
+    slug: 'stream-multiview',
+    name: 'Stream Multiview',
+    summary: 'Watch Kick, Twitch and YouTube streams and chats side by side, with custom layouts, live alerts and color themes.',
+    icon: path.join(ICONS, 'stream-multiview.png'),
+    homepage: 'https://github.com/GlowingPear/stream-window-multiview',
+    download: 'https://github.com/GlowingPear/stream-window-multiview/releases/latest',
+    dataFolder: 'Stream Multiview',
+    firstRelease: {},
+  },
+];
+
+const byId = (id) => KNOWN_APPS.find((a) => a.id === id) ?? null;
+const bySlug = (slug) => KNOWN_APPS.find((a) => a.slug === slug) ?? null;
+
+/** Whether an app looks installed: its data folder exists (it's made the first time the app runs). */
+function isInstalled(app, appDataDir, fsImpl = fs) {
+  return fsImpl.existsSync(path.join(appDataDir, app.dataFolder));
+}
+
+/** An app's logo as a data URL, for a hello or an <img>. */
+function iconDataUrl(file) {
+  return `data:image/png;base64,${fs.readFileSync(file).toString('base64')}`;
+}
+
+module.exports = { KNOWN_APPS, byId, bySlug, isInstalled, iconDataUrl };

package/src/paths.js

@@ -0,0 +1,85 @@
+// Where each app's socket lives. One shared, private folder per user (a named pipe prefix on
+// Windows), so apps find each other by listing it. PROTOCOL.md, "Finding apps".
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,39}$/;
+const MAX_SOCKET_PATH = 100; // macOS allows 104 bytes for a socket path, Linux 108
+
+/**
+ * @typedef {object} Place
+ * @property {NodeJS.Platform} [platform]
+ * @property {NodeJS.ProcessEnv} [env]
+ * @property {string} [home]
+ * @property {number} [uid]
+ */
+
+/** The shared folder: GRAPEVINE_DIR if set (tests, dev copies), else the OS's per-user place. */
+function linkDir({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  if (env.GRAPEVINE_DIR) return env.GRAPEVINE_DIR;
+  if (platform === 'darwin') return path.join(home, 'Library', 'Application Support', 'Grapevine');
+  if (platform === 'win32') return path.join(env.APPDATA || path.join(home, 'AppData', 'Roaming'), 'Grapevine');
+  return env.XDG_RUNTIME_DIR ? path.join(env.XDG_RUNTIME_DIR, 'grapevine') : path.join(home, '.local', 'state', 'grapevine');
+}
+
+/** A short tag for the folder, so pipes of different users (or test folders) never mix on Windows. */
+function tagOf(dir) {
+  return crypto.createHash('sha256').update(dir.toLowerCase()).digest('hex').slice(0, 8);
+}
+
+/** The folder the sockets are actually in: the shared folder, or a short one in /tmp if its paths would be too long. */
+function socketDir(place = {}) {
+  const dir = linkDir(place);
+  const { platform = process.platform, uid = process.getuid?.() ?? 0 } = place;
+  if (platform === 'win32') return dir;
+  const longest = path.join(dir, `${'x'.repeat(40)}.sock`);
+  return Buffer.byteLength(longest) > MAX_SOCKET_PATH ? path.join('/tmp', `grapevine-${uid}-${tagOf(dir)}`) : dir;
+}
+
+/** The socket (or pipe) an app listens on. */
+function socketPath(slug, place = {}) {
+  if (!SLUG_RE.test(slug)) throw new Error(`"${slug}" isn't a valid app slug (a-z, 0-9 and -, up to 40)`);
+  const { platform = process.platform } = place;
+  if (platform === 'win32') return `\\\\.\\pipe\\grapevine-${tagOf(linkDir(place))}-${slug}`;
+  return path.join(socketDir(place), `${slug}.sock`);
+}
+
+/** The slugs of every app with a socket in the folder right now (running, or left behind by a crash). */
+function listSlugs(place = {}, fsImpl = fs) {
+  const { platform = process.platform } = place;
+  try {
+    if (platform === 'win32') {
+      const prefix = `grapevine-${tagOf(linkDir(place))}-`;
+      return fsImpl
+        .readdirSync('\\\\.\\pipe\\')
+        .filter((n) => n.startsWith(prefix))
+        .map((n) => n.slice(prefix.length))
+        .filter((s) => SLUG_RE.test(s));
+    }
+    return fsImpl
+      .readdirSync(socketDir(place))
+      .filter((n) => n.endsWith('.sock'))
+      .map((n) => n.slice(0, -5))
+      .filter((s) => SLUG_RE.test(s));
+  } catch {
+    return [];
+  }
+}
+
+/** Creates the socket folder, private to this user. Refuses one owned by someone else. */
+function ensureDir(place = {}, fsImpl = fs) {
+  const { platform = process.platform } = place;
+  if (platform === 'win32') return; // pipes don't live in a folder
+  const dir = socketDir(place);
+  fsImpl.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const uid = place.uid ?? process.getuid?.();
+  const st = fsImpl.statSync(dir);
+  if (uid !== undefined && st.uid !== uid) throw new Error(`${dir} belongs to another user`);
+  if ((st.mode & 0o077) !== 0) fsImpl.chmodSync(dir, 0o700);
+}
+
+module.exports = { SLUG_RE, MAX_SOCKET_PATH, linkDir, tagOf, socketDir, socketPath, listSlugs, ensureDir };

package/src/report.js

@@ -0,0 +1,49 @@
+// The compatibility report for a Connected apps card: works, works with something missing, or
+// can't connect, and which app to update to which release. PROTOCOL.md, "Compatibility".
+'use strict';
+
+const { byId } = require('./known-apps');
+
+/**
+ * Which app needs updating so that both have `major` of `capability` (or protocol `major`).
+ * @param {{id: string, name: string}} self
+ * @param {{id: string, name: string}} peer
+ * @param {number[]} mine majors this app has
+ * @param {number[]} theirs majors the other app has
+ * @param {string} feature "capability@" or "protocol@"
+ */
+function whoUpdates(self, peer, mine, theirs, feature) {
+  const myTop = Math.max(0, ...mine);
+  const theirTop = Math.max(0, ...theirs);
+  // The app with the older versions is the one to update, to the newest the other one has.
+  const [app, major] = theirTop < myTop ? [peer, myTop] : [self, theirTop];
+  const version = byId(app.id)?.firstRelease?.[`${feature}${major}${feature === 'protocol@' ? '' : '.0'}`] ?? null;
+  return { app: app.name, appId: app.id, version };
+}
+
+/**
+ * @param {{id: string, name: string}} self
+ * @param {{id: string, name: string}} peer
+ * @param {{missing: {capability: string, direction: string, mine: number[], theirs: number[]}[]}} agreed
+ * @returns {{state: 'works' | 'limited', missing: {capability: string, update: {app: string, appId: string, version: string | null}}[], text: string}}
+ */
+function compatibility(self, peer, agreed) {
+  const missing = agreed.missing.map((m) => ({ capability: m.capability, update: whoUpdates(self, peer, m.mine, m.theirs, `${m.capability}@`) }));
+  if (!missing.length) return { state: 'works', missing, text: 'Works' };
+  const first = missing[0].update;
+  const more = missing.length > 1 ? ` (and ${missing.length - 1} more)` : '';
+  return {
+    state: 'limited',
+    missing,
+    text: `Works, with a feature missing: update ${first.app}${first.version ? ` to ${first.version} or later` : ''}${more}`,
+  };
+}
+
+/** The report when no protocol version is in common. */
+function incompatible(self, peer, myProtocol, theirProtocol) {
+  const span = (p) => Array.from({ length: p.max - p.min + 1 }, (_, i) => p.min + i);
+  const update = whoUpdates(self, peer, span(myProtocol), span(theirProtocol), 'protocol@');
+  return { state: 'incompatible', missing: [], update, text: `Can't connect: update ${update.app}${update.version ? ` to ${update.version} or later` : ''}` };
+}
+
+module.exports = { compatibility, incompatible, whoUpdates };

package/src/rpc.js

@@ -0,0 +1,92 @@
+// JSON-RPC 2.0 bookkeeping for one connection: numbered requests waiting for their replies, and
+// sorting what comes in into replies, requests and notifications (events).
+'use strict';
+
+const { CODES, GrapevineError } = require('./errors');
+
+const REQUEST_TIMEOUT_MS = 10_000;
+
+const isId = (id) => (typeof id === 'number' && Number.isFinite(id)) || typeof id === 'string';
+
+class Rpc {
+  /**
+   * @param {(message: object) => void} send
+   * @param {{ onRequest: (msg: {id: string | number, method: string, params: any}) => void, onNotification: (msg: {method: string, params: any}) => void }} handlers
+   */
+  constructor(send, { onRequest, onNotification }) {
+    this.send = send;
+    this.onRequest = onRequest;
+    this.onNotification = onNotification;
+    this.nextId = 1;
+    /** @type {Map<string | number, {resolve: (v: any) => void, reject: (e: Error) => void, timer: NodeJS.Timeout}>} */
+    this.pending = new Map();
+    this.closed = false;
+  }
+
+  /** Sends a request; resolves with its result, or rejects with a GrapevineError. */
+  request(method, params = {}, { timeout = REQUEST_TIMEOUT_MS } = {}) {
+    if (this.closed) return Promise.reject(new GrapevineError(CODES.CLOSED, 'The connection is closed'));
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new GrapevineError(CODES.TIMEOUT, `No reply to ${method} in ${timeout} ms`));
+      }, timeout);
+      timer.unref?.();
+      this.pending.set(id, { resolve, reject, timer });
+      this.send({ jsonrpc: '2.0', id, method, params });
+    });
+  }
+
+  /** Sends a notification: an event, with no reply. */
+  notify(method, params = {}) {
+    if (!this.closed) this.send({ jsonrpc: '2.0', method, params });
+  }
+
+  reply(id, result) {
+    if (!this.closed) this.send({ jsonrpc: '2.0', id, result: result ?? {} });
+  }
+
+  /** @param {string | number | null} id @param {GrapevineError} err */
+  fail(id, err) {
+    if (!this.closed) this.send({ jsonrpc: '2.0', id, error: err.toJSON() });
+  }
+
+  /** Sorts one incoming message. */
+  handle(msg) {
+    if (msg.jsonrpc !== '2.0') return this.fail(isId(msg.id) ? msg.id : null, new GrapevineError(CODES.INVALID_REQUEST, 'Not JSON-RPC 2.0'));
+    if ('result' in msg || 'error' in msg) return this.settle(msg);
+    if (typeof msg.method !== 'string' || !msg.method) return this.fail(isId(msg.id) ? msg.id : null, new GrapevineError(CODES.INVALID_REQUEST, 'No method'));
+    const params = msg.params ?? {};
+    if (typeof params !== 'object' || Array.isArray(params))
+      return isId(msg.id) ? this.fail(msg.id, new GrapevineError(CODES.INVALID_PARAMS, 'params must be an object')) : undefined;
+    if ('id' in msg) {
+      if (!isId(msg.id)) return this.fail(null, new GrapevineError(CODES.INVALID_REQUEST, 'Bad id'));
+      return this.onRequest({ id: msg.id, method: msg.method, params });
+    }
+    this.onNotification({ method: msg.method, params });
+  }
+
+  settle(msg) {
+    const waiting = this.pending.get(msg.id);
+    if (!waiting) return; // a reply to nothing (late, after a timeout): ignored
+    this.pending.delete(msg.id);
+    clearTimeout(waiting.timer);
+    if ('error' in msg) {
+      const e = msg.error ?? {};
+      waiting.reject(new GrapevineError(Number.isInteger(e.code) ? e.code : CODES.INTERNAL_ERROR, String(e.message ?? 'Error'), e.data));
+    } else waiting.resolve(msg.result);
+  }
+
+  /** Rejects everything still waiting. */
+  close() {
+    this.closed = true;
+    for (const [, waiting] of this.pending) {
+      clearTimeout(waiting.timer);
+      waiting.reject(new GrapevineError(CODES.CLOSED, 'The connection closed'));
+    }
+    this.pending.clear();
+  }
+}
+
+module.exports = { Rpc, REQUEST_TIMEOUT_MS };

package/src/schema.js

@@ -0,0 +1,125 @@
+// A small JSON Schema checker for the subset the capability schemas use, so the package needs no
+// dependencies. Unknown properties are always allowed: a newer minor version may add fields, and
+// apps must ignore what they don't know (PROTOCOL.md, "Versions").
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SCHEMA_DIR = path.join(__dirname, '..', 'schemas');
+const DATE_TIME = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+
+const typeOf = (v) => (v === null ? 'null' : Array.isArray(v) ? 'array' : Number.isInteger(v) ? 'integer' : typeof v);
+const fits = (actual, wanted) => actual === wanted || (wanted === 'number' && actual === 'integer');
+
+/**
+ * Checks `value` against `schema`. Returns a list of problems ("drop.progress.done: expected integer"),
+ * empty when it's valid.
+ * @param {any} value
+ * @param {any} schema
+ * @param {(ref: string) => any} resolve looks up a "$ref"
+ */
+function check(value, schema, resolve, at = '') {
+  if (schema.$ref) return check(value, resolve(schema.$ref), resolve, at);
+  const where = at || '(message)';
+  const problems = [];
+  if (schema.type) {
+    const types = [].concat(schema.type);
+    if (!types.some((t) => fits(typeOf(value), t))) return [`${where}: expected ${types.join(' or ')}, got ${typeOf(value)}`];
+  }
+  if (schema.anyOf && !schema.anyOf.some((s) => check(value, s, resolve, at).length === 0)) problems.push(`${where}: matches none of the allowed shapes`);
+  if (schema.enum && !schema.enum.includes(value)) problems.push(`${where}: must be one of ${schema.enum.join(', ')}`);
+  if (typeof value === 'string') {
+    if (schema.minLength !== undefined && value.length < schema.minLength) problems.push(`${where}: shorter than ${schema.minLength}`);
+    if (schema.maxLength !== undefined && value.length > schema.maxLength) problems.push(`${where}: longer than ${schema.maxLength}`);
+    if (schema.pattern && !new RegExp(schema.pattern).test(value)) problems.push(`${where}: doesn't match ${schema.pattern}`);
+    if (schema.format === 'date-time' && !DATE_TIME.test(value)) problems.push(`${where}: not an ISO 8601 time`);
+  }
+  if (typeof value === 'number') {
+    if (schema.minimum !== undefined && value < schema.minimum) problems.push(`${where}: below ${schema.minimum}`);
+    if (schema.maximum !== undefined && value > schema.maximum) problems.push(`${where}: above ${schema.maximum}`);
+  }
+  if (Array.isArray(value)) {
+    if (schema.maxItems !== undefined && value.length > schema.maxItems) problems.push(`${where}: more than ${schema.maxItems} items`);
+    if (schema.items) value.forEach((item, i) => problems.push(...check(item, schema.items, resolve, `${at}[${i}]`)));
+  }
+  if (value && typeof value === 'object' && !Array.isArray(value)) {
+    for (const key of schema.required ?? []) if (!(key in value)) problems.push(`${at ? `${at}.` : ''}${key}: missing`);
+    for (const [key, sub] of Object.entries(schema.properties ?? {})) {
+      if (key in value) problems.push(...check(value[key], sub, resolve, at ? `${at}.${key}` : key));
+    }
+    if (schema.additionalProperties && typeof schema.additionalProperties === 'object') {
+      for (const [key, v] of Object.entries(value)) {
+        if (!(key in (schema.properties ?? {}))) problems.push(...check(v, schema.additionalProperties, resolve, at ? `${at}.${key}` : key));
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * A capability's schemas, one file per major version: { capability, major, minor, events, methods, defs }.
+ * "$ref" is "#Name" for the file's own defs and "common:Name" for the shared types.
+ */
+class Schemas {
+  constructor() {
+    this.common = JSON.parse(fs.readFileSync(path.join(SCHEMA_DIR, 'common.json'), 'utf8')).defs;
+    /** @type {Map<string, any>} "capability@major" -> schema file */
+    this.byKey = new Map();
+  }
+
+  /** Loads every schema in the package, plus any extra folders (for apps adding their own capabilities). */
+  static load(extraDirs = []) {
+    const s = new Schemas();
+    for (const dir of [SCHEMA_DIR, ...extraDirs]) {
+      for (const name of fs.readdirSync(dir)) {
+        const full = path.join(dir, name);
+        if (!fs.statSync(full).isDirectory()) continue;
+        for (const file of fs.readdirSync(full).filter((f) => /^\d+\.json$/.test(f))) s.add(JSON.parse(fs.readFileSync(path.join(full, file), 'utf8')));
+      }
+    }
+    return s;
+  }
+
+  add(schema) {
+    if (!schema.capability || !Number.isInteger(schema.major) || !Number.isInteger(schema.minor)) throw new Error('A schema needs capability, major and minor');
+    this.byKey.set(`${schema.capability}@${schema.major}`, schema);
+  }
+
+  get(capability, major) {
+    return this.byKey.get(`${capability}@${major}`) ?? null;
+  }
+
+  /** "drops.farming.changed" -> "drops.farming": the capability a method or event belongs to. */
+  capabilityOf(name) {
+    let best = null;
+    for (const key of this.byKey.keys()) {
+      const cap = key.slice(0, key.lastIndexOf('@'));
+      if (name.startsWith(`${cap}.`) && (!best || cap.length > best.length)) best = cap;
+    }
+    return best;
+  }
+
+  resolver(file) {
+    return (ref) => {
+      const found = ref.startsWith('common:') ? this.common[ref.slice(7)] : ref.startsWith('#') ? file.defs?.[ref.slice(1)] : undefined;
+      if (!found) throw new Error(`Unknown schema reference ${ref}`);
+      return found;
+    };
+  }
+
+  /**
+   * Checks an event's params, or a method's params or result, for one major version.
+   * @param {'event' | 'params' | 'result'} kind
+   * @returns {string[]} problems; empty when valid
+   */
+  validate(capability, major, kind, name, value) {
+    const file = this.get(capability, major);
+    if (!file) return [`no schema for ${capability}@${major}`];
+    const schema = kind === 'event' ? file.events?.[name] : file.methods?.[name]?.[kind];
+    if (!schema) return [`${name} isn't part of ${capability}@${major}`];
+    return check(value, schema, this.resolver(file));
+  }
+}
+
+module.exports = { check, Schemas, SCHEMA_DIR };

package/stand-in-peer.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// A stand-in for another app, for an app's own tests: it speaks Grapevine as that app (any version,
+// any capabilities) without the real app installed.
+//
+// In a test:
+//   const { standInPeer } = require('@streamorchard/grapevine/stand-in-peer');
+//   const peer = await standInPeer({ as: 'com.glowingpear.streammultiview', dir, uses: { 'drops.farming': '1.0' } });
+//   peer.link.on('event', (from, name, params) => …);   peer.link.publish('players.changed', {…});
+//
+// From the command line (a launch test can spawn it): it prints one JSON line per thing that
+// happens ({"type":"connected"|"event"|"disconnected", …}) and reads lines on stdin:
+//   {"publish":"players.changed","data":{…}}   {"request":"drops.farming.get","params":{},"to":"<app id>"}
+//   node stand-in-peer.js --as com.glowingpear.streammultiview --dir /tmp/x --uses drops.farming@1.0 --provides players@1.0
+'use strict';
+
+const readline = require('readline');
+const { createLink, KNOWN_APPS, memoryKeyStore } = require('./src');
+
+/**
+ * @param {object} o
+ * @param {string} o.as the known app to pretend to be (its id)
+ * @param {string} o.dir a GRAPEVINE_DIR shared with the app under test
+ * @param {string} [o.version] its version (default 99.0.0)
+ * @param {Record<string, string | string[]>} [o.provides]
+ * @param {Record<string, string | string[]>} [o.uses]
+ * @param {(appId: string) => boolean} [o.allowed] its switch (default: on for every app)
+ * @param {object} [o.timing]
+ * @param {import('./src/keys').KeyStore} [o.keys]
+ */
+async function standInPeer({ as, dir, version = '99.0.0', provides = {}, uses = {}, allowed = () => true, timing, keys = memoryKeyStore() }) {
+  const known = KNOWN_APPS.find((a) => a.id === as);
+  if (!known) throw new Error(`stand-in-peer: ${as} isn't a known app`);
+  const link = createLink({
+    app: {
+      id: known.id,
+      slug: known.slug,
+      name: `${known.name} (stand-in)`,
+      version,
+      summary: known.summary,
+      homepage: known.homepage,
+      download: known.download,
+    },
+    provides,
+    uses,
+    allowed,
+    keys,
+    place: { env: { ...process.env, GRAPEVINE_DIR: dir } },
+    timing,
+    strict: false,
+  });
+  await link.start();
+  return { link, stop: () => link.stop() };
+}
+
+/** "drops.farming@1.0,players@1.0" -> { 'drops.farming': '1.0', players: '1.0' } */
+function parseCaps(text) {
+  /** @type {Record<string, string[]>} */
+  const out = {};
+  for (const part of String(text ?? '')
+    .split(',')
+    .filter(Boolean)) {
+    const [cap, v] = part.split('@');
+    (out[cap] ??= []).push(v || '1.0');
+  }
+  return out;
+}
+
+async function main(argv) {
+  const arg = (name) => {
+    const i = argv.indexOf(`--${name}`);
+    return i === -1 ? undefined : argv[i + 1];
+  };
+  const out = (o) => process.stdout.write(`${JSON.stringify(o)}\n`);
+  const { link } = await standInPeer({
+    as: arg('as'),
+    dir: arg('dir') ?? process.env.GRAPEVINE_DIR,
+    version: arg('version'),
+    provides: parseCaps(arg('provides')),
+    uses: parseCaps(arg('uses')),
+  });
+  link.on('connected', (id) => out({ type: 'connected', app: id }));
+  link.on('disconnected', (id, reason) => out({ type: 'disconnected', app: id, reason }));
+  link.on('event', (from, name, params) => out({ type: 'event', from, name, params }));
+  out({ type: 'started' });
+  readline.createInterface({ input: process.stdin }).on('line', async (line) => {
+    try {
+      const cmd = JSON.parse(line);
+      if (cmd.publish) out({ type: 'published', params: link.publish(cmd.publish, cmd.data ?? {}) });
+      if (cmd.request) out({ type: 'result', method: cmd.request, result: await link.request(cmd.to, cmd.request, cmd.params ?? {}) });
+      if (cmd.quit) {
+        await link.stop();
+        process.exit(0);
+      }
+    } catch (err) {
+      out({ type: 'error', message: err.message, code: err.code });
+    }
+  });
+  const quit = () => link.stop().then(() => process.exit(0));
+  process.on('SIGTERM', quit);
+  process.on('SIGINT', quit);
+}
+
+if (require.main === module)
+  main(process.argv.slice(2)).catch((err) => {
+    process.stderr.write(`${err.stack}\n`);
+    process.exit(1);
+  });
+
+module.exports = { standInPeer, parseCaps };

package/types/capabilities.d.ts

@@ -0,0 +1,77 @@
+// Generated from schemas/ by scripts/types.js. Don't edit it: change a schema and run `npm run types`.
+
+/** ISO 8601, in UTC */
+export type Timestamp = string;
+
+/** A streaming site */
+export type Platform = "kick" | "twitch" | "youtube" | (string & {});
+
+export type Channel = {
+  platform: Platform;
+  /** As in the channel's address */
+  slug: string;
+  /** As shown on the site */
+  name?: string;
+};
+
+/** Who an app is signed in as: the username only, never a token or cookie */
+export type Account = {
+  platform: Platform;
+  user: string;
+};
+
+export type Progress = {
+  done: number;
+  total: number;
+  unit: "minutes" | (string & {});
+};
+
+export type Empty = Record<string, unknown>;
+
+// drops.farming 1.0: What a drops app is farming. Provided by Pear Drops.
+export type DropsFarmingV1State = {
+  /** Counts up with each change; 0 for a reply to drops.farming.get */
+  seq: number;
+  at: Timestamp;
+  /** farming: its player is watching a stream for drop credit. Any other value, known or not, means it isn't. */
+  state: "farming" | "waiting" | "paused" | "done" | "signed-out" | (string & {});
+  account: Account | null;
+  /** The stream being watched, while farming */
+  channel: Channel | null;
+  drop: {
+    campaign: string;
+    category: string;
+    progress: Progress;
+  } | null;
+};
+
+// players 1.0: An app's stream players, by site: whether they're signed in, and which channels are open. Provided by Stream Multiview.
+export type PlayersV1State = {
+  seq: number;
+  at: Timestamp;
+  /** Keyed by Platform; a site with no players open may be left out */
+  platforms: {
+    [key: string]: PlayersV1Site;
+  };
+};
+
+export type PlayersV1Site = {
+  /** Whether the players play as the account right now */
+  signedIn: boolean;
+  /** auto: signed in, except while a connected drops app is farming */
+  mode: "signed-in" | "signed-out" | "auto" | (string & {});
+  account: Account | null;
+  open: Array<Channel>;
+};
+
+/** Every event, by name: its params. */
+export interface Events {
+  "drops.farming.changed": DropsFarmingV1State;
+  "players.changed": PlayersV1State;
+}
+
+/** Every method, by name: its params and result. */
+export interface Methods {
+  "drops.farming.get": { params: Empty; result: DropsFarmingV1State };
+  "players.get": { params: Empty; result: PlayersV1State };
+}