@streamorchard/grapevine 0.4.0 → 0.5.0

package/PROTOCOL.md

@@ -197,6 +197,8 @@ A capability is a named feature one app provides and others use, defined by a JS
 
 What a drops app is farming, with enough for another app to show it, in a top-bar widget say. Provided by Pear Drops.
 
+Event `drops.farming.changed`, and `drops.farming.get` answers with the same: the whole state, below. `drops.farming.show` is further down.
+
 | Field          |                                                                                                                                                                                                                                                                                                                                 |
 | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `state`        | `farming` (its player is watching a stream for drop credit), `waiting`, `paused`, `done`, `signed-out`, or one added later                                                                                                                                                                                                      |
@@ -216,6 +218,8 @@ What a drops app is farming, with enough for another app to show it, in a top-ba
 
 An app's stream players, by site. Provided by Stream Multiview.
 
+Event `players.changed`, and `players.get` answers with the same: the whole state, below.
+
 | Field       |                                                                                                                 |
 | ----------- | --------------------------------------------------------------------------------------------------------------- |
 | `platforms` | An object keyed by `Platform`. Each site has `{ signedIn, mode, account, open }`                                |
@@ -259,7 +263,7 @@ After the hello, each app tells its user one of:
 | **Works, with a feature missing** | A capability one app wants has no major in common. It names the app with the older versions and, if known, the release to update to: "update Pear Drops to 0.1.7 or later" |
 | **Can't connect**                 | No protocol version in common. Again, it names the app to update                                                                                                           |
 
-The releases come from the known-apps list (`src/known-apps.js`): `firstRelease` maps `"<capability>@<major>.<minor>"` and `"protocol@<n>"` to the first release of that app that had it.
+The releases come from `schemas/released.json`, recorded as each app ships (`npm run released`), through the known-apps list's `firstRelease`: `"<capability>@<major>.<minor>"` and `"protocol@<n>"` mapped to the first release of that app that had them.
 
 ## Renaming an app
 

package/README.md

@@ -111,17 +111,18 @@ Editors suggest every event's fields and underline mistakes, in plain JavaScript
 
 `link.peers()` lists every known app with what its card needs, and `link.on('change', …)` says when to draw it again.
 
-| Field                                 |                                                                                                            |
-| ------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
-| `name`, `summary`, `icon`, `download` | The app's logo (bundled, so it shows even when it isn't installed), one line about it, and where to get it |
-| `installed`                           | Whether its data folder exists (with `appDataDir`)                                                         |
-| `enabled`                             | Your switch for it                                                                                         |
-| `status`                              | `off`, `waiting`, `connected`, `pair-again` or `incompatible`                                              |
-| `reason`                              | Why it's waiting: `switched-off` (its own switch is off), `disconnected-there`                             |
-| `keyHeldBy`                           | For `pair-again`: `us` means show **Pair again** here, `them` means it's pressed in the other app          |
-| `version`, `report.text`              | While connected: its version, and "Works" or what's missing ("update Pear Drops to 0.1.7 or later")        |
-| `pairedAt`, `keysEncrypted`           | When they paired, and whether keys are stored encrypted                                                    |
-| `formerIds`                           | Ids the app had before a rename                                                                            |
+| Field                                 |                                                                                                              |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `name`, `summary`, `icon`, `download` | The app's logo (bundled, so it shows even when it isn't installed), one line about it, and where to get it   |
+| `installed`                           | Whether its data folder exists (with `appDataDir`)                                                           |
+| `enabled`                             | Your switch for it                                                                                           |
+| `status`                              | `off`, `waiting`, `connected`, `pair-again` or `incompatible`                                                |
+| `reason`                              | Why it's waiting: `switched-off` (its own switch is off), `disconnected-there`                               |
+| `keyHeldBy`                           | For `pair-again`: `us` means show **Pair again** here, `them` means it's pressed in the other app            |
+| `version`, `report.text`              | While connected: its version, and "Works" or what's missing ("update Pear Drops to 0.1.7 or later")          |
+| `pairedAt`, `keysEncrypted`           | When they paired, and whether keys are stored encrypted                                                      |
+| `formerIds`                           | Ids the app had before a rename                                                                              |
+| `shares`                              | What the two apps share: `{ out, in }`, capabilities this app provides that it uses, and the other way round |
 
 Two calls go with buttons on the card:
 
@@ -166,7 +167,17 @@ To change one, follow [the version rules](PROTOCOL.md#versions): additions are a
 
 ## Adding an app
 
-Add it to `src/known-apps.js`, with its id, slug, summary, a 256×256 logo in `assets/apps/`, its download page and its data folder's name. Every app that updates Grapevine then shows it on its Connected apps page.
+Add it to `src/known-apps.js` with:
+
+- its id and slug
+- a one-line summary
+- a 256×256 logo in `assets/apps/`
+- its download page and its data folder's name
+- the capabilities it `provides` and `uses`
+
+Every app that updates Grapevine then shows it on its Connected apps page, with what the two would share. `link.peers()` gives that as `shares`, from this list until they meet and from the hello after.
+
+When it ships a release that uses Grapevine, record it: `npm run released -- <its id> <its version>`. That fixes the capability versions it uses (they can't change in place after that) and tells other apps which release to ask for.
 
 ## Renaming an app
 
@@ -183,6 +194,7 @@ npm run lint           # ESLint and Prettier
 npm run format         # fix what lint can
 npm run types          # types/capabilities.d.ts from the schemas
 npm run check          # the types are up to date, and tsc finds no type errors
+npm run released -- <app id> <version>   # an app shipped a release using Grapevine (see Adding an app)
 ```
 
 CI runs the tests on Windows, macOS and Linux, and lint, types and coverage on Linux.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@streamorchard/grapevine",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Lets desktop apps on the same computer find each other and talk, privately: local sockets, JSON-RPC, pairing and versioned capabilities.",
   "license": "GPL-3.0-only",
   "author": "StreamOrchard",
@@ -52,7 +52,8 @@
     "lint": "eslint . && prettier --check .",
     "format": "prettier --write . && eslint --fix .",
     "types": "node scripts/types.js",
-    "check": "node scripts/types.js --check && tsc -p jsconfig.json"
+    "check": "node scripts/types.js --check && tsc -p jsconfig.json",
+    "released": "node scripts/released.js"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",

package/schemas/released.json

@@ -0,0 +1,5 @@
+{
+  "description": "Capability versions that have shipped in an app's release, and which release of each app first had them. Written by `npm run released -- <app id> <version>`; never by hand. A version recorded here can't change in place: test/released.test.js fails until the change goes in a new minor.",
+  "schemas": {},
+  "firstRelease": {}
+}

package/src/index.js

@@ -415,6 +415,20 @@ class Link extends EventEmitter {
     return this.conns.has(this.currentId(appId));
   }
 
+  /**
+   * What this app and another share: `out`, capabilities this app provides that it uses; `in`,
+   * ones it provides that this app uses. Agreed in the hello while connected; from the known-apps
+   * list otherwise, so a card can say what linking would do before the two have met.
+   */
+  sharesWith(app, conn) {
+    if (conn) return { out: [...conn.agreed.outgoing.keys()].sort(), in: [...conn.agreed.incoming.keys()].sort() };
+    const mine = (list) => (cap) => cap in list;
+    return {
+      out: (app.uses ?? []).filter(mine(this.mine.provides)).sort(),
+      in: (app.provides ?? []).filter(mine(this.mine.uses)).sort(),
+    };
+  }
+
   /**
    * Every known app, for the Connected apps page:
    * status 'off' (its switch is off) | 'waiting' | 'connected' | 'pair-again' | 'incompatible'.
@@ -445,6 +459,7 @@ class Link extends EventEmitter {
         keyHeldBy: status === 'pair-again' ? (why?.keyHeldBy ?? null) : null,
         version: conn?.peer.version ?? null,
         report,
+        shares: this.sharesWith(app, conn),
         pairedAt: paired?.pairedAt ?? null,
         keysEncrypted: !!this.keys.encrypted,
       };

package/src/known-apps.js

@@ -7,6 +7,8 @@ const fs = require('fs');
 const path = require('path');
 
 const ICONS = path.join(__dirname, '..', 'assets', 'apps');
+// Which release of each app first had each capability version: written by `npm run released`.
+const RELEASED = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'schemas', 'released.json'), 'utf8')).firstRelease;
 
 /**
  * @typedef {object} KnownApp
@@ -19,6 +21,8 @@ const ICONS = path.join(__dirname, '..', 'assets', 'apps');
  * @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 {string[]} provides the capabilities it provides (their names), so another app can say what the two share before they've met
+ * @property {string[]} uses the capabilities it uses
  * @property {Record<string, string>} firstRelease "capability@major.minor" (or "protocol@N") -> the app version that first had it
  */
 
@@ -34,7 +38,9 @@ const KNOWN_APPS = [
     homepage: 'https://github.com/Stream-Orchard/pear-drops',
     download: 'https://github.com/Stream-Orchard/pear-drops/releases/latest',
     dataFolder: 'Pear Drops',
-    firstRelease: {},
+    provides: ['drops.farming'],
+    uses: ['players'],
+    firstRelease: { ...RELEASED['com.streamorchard.peardrops'] },
   },
   {
     id: 'com.glowingpear.streammultiview',
@@ -46,7 +52,9 @@ const KNOWN_APPS = [
     homepage: 'https://github.com/GlowingPear/stream-window-multiview',
     download: 'https://github.com/GlowingPear/stream-window-multiview/releases/latest',
     dataFolder: 'Stream Multiview',
-    firstRelease: {},
+    provides: ['players'],
+    uses: ['drops.farming'],
+    firstRelease: { ...RELEASED['com.glowingpear.streammultiview'] },
   },
 ];
 

package/types/index.d.ts

@@ -64,6 +64,9 @@ export interface KnownApp {
   download: string;
   /** Its folder in the OS's app data folder */
   dataFolder: string;
+  /** The capabilities it provides and uses (names), so a card can say what linking would do */
+  provides: string[];
+  uses: string[];
   /** "capability@major.minor" (or "protocol@N") -> the app version that first had it */
   firstRelease: Record<string, string>;
 }
@@ -119,6 +122,8 @@ export interface Peer {
   /** Its version, while connected */
   version: string | null;
   report: Report | null;
+  /** What the two apps share: `out`, capabilities this app provides that it uses; `in`, ones it provides that this app uses */
+  shares: { out: string[]; in: string[] };
   pairedAt: string | null;
   keysEncrypted: boolean;
 }