@streamorchard/grapevine 0.5.1 → 0.7.0

package/PROTOCOL.md

@@ -32,7 +32,7 @@ Every app has a **slug** (`a-z`, `0-9` and `-`, up to 40 characters, starting wi
 - A socket left by a crash answers nothing (`ECONNREFUSED`): its app deletes it and listens again when it starts. If something does answer, another copy of the app is running, and the new copy doesn't start its link.
 - An app only listens, and only looks for others, while at least one of its Connected apps switches is on.
 
-**Who connects.** Of two apps, the one whose slug sorts first (plain string order) connects; the other waits for it. So a pair never opens two connections. If they ever do, both keep the connection opened by the app whose slug sorts first and close the other with `link.bye { reason: "duplicate" }`. It's the slug, not the id, because an app's id can change (see [Renaming an app](#renaming-an-app)) and its socket's name doesn't.
+**Who connects.** Of two apps, the one whose slug sorts first (plain string order) connects; the other waits for it, so a pair normally opens one connection. An app may still connect the other way to check the link on its user's request (a Test button). If they ever do have two, both keep the connection opened by the app whose slug sorts first and close the other with `link.bye { reason: "duplicate" }`. It's the slug, not the id, because an app's id can change (see [Renaming an app](#renaming-an-app)) and its socket's name doesn't.
 
 ## Messages
 

package/README.md

@@ -28,10 +28,17 @@ npm install @streamorchard/grapevine
 
 ## Use it
 
+Say what your app speaks in its `package.json`. It's the one place it's written, and every release tag keeps it, which is how `grapevine-check` knows what each release shipped (see [Recording releases](#recording-releases)):
+
+```json
+"grapevine": { "app": "com.streamorchard.peardrops", "provides": { "drops.farming": "1.0" }, "uses": { "players": "1.0" } }
+```
+
 ```js
 const { app, safeStorage } = require('electron');
 const path = require('path');
 const { createLink, fileKeyStore } = require('@streamorchard/grapevine');
+const { grapevine } = require('./package.json');
 
 const link = createLink({
   app: {
@@ -41,8 +48,8 @@ const link = createLink({
     version: app.getVersion(),
     icon: path.join(__dirname, 'icon.png'),
   },
-  provides: { 'drops.farming': '1.0' }, // what it tells other apps
-  uses: { players: '1.0' }, // what it listens to
+  provides: grapevine.provides, // what it tells other apps
+  uses: grapevine.uses, // what it listens to
   allowed: (appId) => settings.connectedApps[appId]?.enabled === true, // your Connected apps switches
   keys: fileKeyStore(path.join(app.getPath('userData'), 'grapevine.json'), {
     encrypt: (t) => safeStorage.encryptString(t).toString('base64'),
@@ -124,8 +131,15 @@ Editors suggest every event's fields and underline mistakes, in plain JavaScript
 | `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:
+Three calls go with buttons on the card:
 
+- **Test:** `await link.test(appId)`. Connected, it's a round trip, `{ ok: true, ms, version, text }`, with `text` like "Stream Multiview 0.4.0 answered in 3 ms". Otherwise it tries straight away, from this side too, and says why it couldn't: `{ ok: false, reason, text }`. `reason` is one of:
+  - `not-running`: "Stream Multiview isn't open"
+  - `switched-off`: its Connect switch is off
+  - `off`: this app's is
+  - `pair-again`: with where to press it
+  - `incompatible`: which app to update
+  - `no-answer`, `not-started`, `unknown`
 - **Disconnect:** `link.disconnect(appId)`. Turn your own switch for that app off too.
 - **Pair again:** `link.pairAgain(appId)`.
 
@@ -177,7 +191,22 @@ Add it to `src/known-apps.js` with:
 
 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.
+When it ships a release that uses Grapevine, record it (next section).
+
+## Recording releases
+
+Once an app ships a capability version, Grapevine records it. From then on that version can't change in place, and other apps can say which release to update to.
+
+In the app's repo, at the start of every change:
+
+```sh
+npx grapevine-check
+```
+
+- **It reads** the `grapevine` field from each of the app's release tags (`v*`), and Grapevine's record from GitHub (the installed copy if it's offline, or with `--offline`).
+- **It lists** any capability version a release shipped that isn't recorded yet, with the command to record it, e.g. `npm run released -- com.streamorchard.peardrops 0.1.6 drops.farming@1.0 players@1.0`.
+- **That command runs in a Grapevine checkout** (its `app-shipped` skill), followed by a pull request and a patch release.
+- **`--strict`** exits 1 while something is unrecorded, for CI.
 
 ## Renaming an app
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@streamorchard/grapevine",
-  "version": "0.5.1",
+  "version": "0.7.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",
@@ -32,7 +32,8 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "grapevine-stand-in": "stand-in-peer.js"
+    "grapevine-stand-in": "stand-in-peer.js",
+    "grapevine-check": "scripts/check-shipped.js"
   },
   "files": [
     "src",
@@ -41,7 +42,8 @@
     "fixtures",
     "assets/apps",
     "stand-in-peer.js",
-    "PROTOCOL.md"
+    "PROTOCOL.md",
+    "scripts/check-shipped.js"
   ],
   "engines": {
     "node": ">=22"

package/scripts/check-shipped.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+// Run in an app's repo (npx grapevine-check): lists the capability versions the app's releases
+// have shipped that Grapevine hasn't recorded yet, with the command that records them (Grapevine's
+// app-shipped skill). Until they're recorded, those versions can still be changed in place, and
+// other apps can't say which release to update to.
+//
+// The app says what it speaks in its package.json, so every release tag has it:
+//   "grapevine": { "app": "com.streamorchard.peardrops", "provides": { "drops.farming": "1.0" }, "uses": { "players": "1.0" } }
+//
+//   npx grapevine-check            prints what needs recording (exit 0)
+//   npx grapevine-check --strict   exits 1 when something does
+//   npx grapevine-check --offline  uses the record in the installed package, not GitHub's
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const RECORD_URL = 'https://raw.githubusercontent.com/Stream-Orchard/grapevine/main/schemas/released.json';
+const INSTALLED = path.join(__dirname, '..', 'schemas', 'released.json');
+const VERSION = /^v?(\d+)\.(\d+)\.(\d+)$/;
+
+/** "capability@major.minor" for each capability a package.json's grapevine field provides or uses. */
+function declaredBy(grapevine) {
+  const out = new Set();
+  for (const list of [grapevine?.provides, grapevine?.uses]) {
+    for (const [cap, versions] of Object.entries(list ?? {})) for (const v of [].concat(versions)) out.add(`${cap}@${v}`);
+  }
+  return [...out].sort();
+}
+
+const byVersion = (a, b) => {
+  const [x, y] = [VERSION.exec(a.version), VERSION.exec(b.version)];
+  for (let i = 1; i <= 3; i++) if (Number(x[i]) !== Number(y[i])) return Number(x[i]) - Number(y[i]);
+  return 0;
+};
+
+/**
+ * What hasn't been recorded: for each capability version any release declared, the first release
+ * that did, unless the record already has it.
+ * @param {{version: string, grapevine: any}[]} releases every release tag, with its package.json's grapevine field (or none)
+ * @param {{firstRelease: Record<string, Record<string, string>>}} released Grapevine's record
+ * @returns {{app: string, version: string, capabilities: string[], command: string}[]} one per release to record, oldest first
+ */
+function findUnrecorded(releases, released) {
+  const first = new Map(); // "app capability@version" -> the first release with it
+  for (const r of [...releases].filter((x) => VERSION.test(x.version)).sort(byVersion)) {
+    if (!r.grapevine?.app) continue;
+    for (const cap of declaredBy(r.grapevine)) {
+      const key = `${r.grapevine.app} ${cap}`;
+      if (!first.has(key)) first.set(key, { app: r.grapevine.app, version: r.version.replace(/^v/, ''), cap });
+    }
+  }
+  const todo = new Map(); // "app version" -> capabilities
+  for (const { app, version, cap } of first.values()) {
+    if (released?.firstRelease?.[app]?.[cap]) continue;
+    const key = `${app} ${version}`;
+    todo.set(key, { app, version, capabilities: [...(todo.get(key)?.capabilities ?? []), cap] });
+  }
+  return [...todo.values()]
+    .sort((a, b) => byVersion(a, b))
+    .map((t) => ({ ...t, command: `npm run released -- ${t.app} ${t.version} ${t.capabilities.join(' ')}` }));
+}
+
+const git = (cwd, args) => execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+
+/** Every v* tag in the repo, with its package.json's grapevine field. */
+function releasesIn(cwd) {
+  const tags = git(cwd, ['tag', '-l', 'v*'])
+    .split('\n')
+    .map((t) => t.trim())
+    .filter((t) => VERSION.test(t));
+  return tags.map((tag) => {
+    let grapevine = null;
+    try {
+      grapevine = JSON.parse(git(cwd, ['show', `${tag}:package.json`])).grapevine ?? null;
+    } catch {}
+    return { version: tag, grapevine };
+  });
+}
+
+/** Grapevine's record: GitHub's copy (the newest), or the installed package's when offline or it can't be fetched. */
+async function loadRecord({ offline = false, fetchImpl = globalThis.fetch, installed = INSTALLED } = {}) {
+  if (!offline && fetchImpl) {
+    try {
+      const res = await fetchImpl(RECORD_URL, { signal: AbortSignal.timeout(5000) });
+      if (res.ok) return { record: await res.json(), source: 'GitHub' };
+    } catch {}
+  }
+  return { record: JSON.parse(fs.readFileSync(installed, 'utf8')), source: 'the installed package (it may be behind GitHub)' };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {{cwd?: string, out?: (text: string) => void, fetchImpl?: typeof fetch}} [opts]
+ */
+async function main(argv, { cwd = process.cwd(), out = (t) => void process.stdout.write(t), fetchImpl = globalThis.fetch } = {}) {
+  const strict = argv.includes('--strict');
+  const offline = argv.includes('--offline');
+  try {
+    if (!offline) git(cwd, ['fetch', '--tags', '--quiet']);
+  } catch {} // no remote, or offline: the tags already here
+  const releases = releasesIn(cwd);
+  if (!releases.some((r) => r.grapevine?.app)) {
+    out('No release of this app declares Grapevine capabilities yet (package.json "grapevine"). Nothing to record.\n');
+    return 0;
+  }
+  const { record, source } = await loadRecord({ offline, fetchImpl });
+  const todo = findUnrecorded(releases, record);
+  if (!todo.length) {
+    out(`Every capability version this app has released is recorded in Grapevine (checked against ${source}).\n`);
+    return 0;
+  }
+  out(`Grapevine hasn't recorded what these releases shipped (checked against ${source}):\n`);
+  for (const t of todo) out(`  ${t.version}: ${t.capabilities.join(', ')}\n`);
+  out(`Record them in a Grapevine checkout (its app-shipped skill), then a pull request and a patch release:\n`);
+  for (const t of todo) out(`  ${t.command}\n`);
+  return strict ? 1 : 0;
+}
+
+if (require.main === module) {
+  main(process.argv.slice(2)).then(
+    (code) => process.exit(code),
+    (err) => {
+      process.stderr.write(`grapevine-check: ${err.message}\n`);
+      process.exit(2);
+    },
+  );
+}
+
+module.exports = { declaredBy, findUnrecorded, releasesIn, loadRecord, main, RECORD_URL };

package/src/index.js

@@ -418,6 +418,59 @@ class Link extends EventEmitter {
     this.changed();
   }
 
+  /**
+   * Test on a card: checks the link to that app now, and says how it went in words. Connected, a
+   * round trip and back; otherwise it tries straight away (from this side too, whichever app
+   * normally connects) and says why it couldn't.
+   * @returns {Promise<{ok: true, ms: number, version: string, text: string} | {ok: false, reason: string, text: string}>}
+   *   reason: 'unknown' | 'off' | 'not-started' | 'not-running' | 'switched-off' | 'pair-again' | 'incompatible' | 'no-answer'
+   */
+  async test(appId, { timeout = 4000 } = {}) {
+    const id = this.currentId(appId);
+    const app = this.knownApps.find((a) => a.id === id);
+    if (!app) return { ok: false, reason: 'unknown', text: `${appId} isn't an app Grapevine knows` };
+    if (!this.allowedAny(this.idsOf(id))) return { ok: false, reason: 'off', text: `Switched off here: switch on Connect with ${app.name} first` };
+    if (!this.running) return { ok: false, reason: 'not-started', text: `${this.self.name} isn't listening for other apps yet` };
+    if (!this.conns.has(id)) {
+      if (!paths.listSlugs(this.place).includes(app.slug)) return { ok: false, reason: 'not-running', text: `${app.name} isn't open` };
+      this.retry.delete(id);
+      this.why.delete(id);
+      const trying = () => [...this.opening].some((c) => (c.expectedId ?? c.peerId) === id);
+      if (!trying()) this.connect(app);
+      await new Promise((resolve) => {
+        const done = () => {
+          clearTimeout(timer);
+          this.off('change', check);
+          resolve();
+        };
+        const check = () => (this.conns.has(id) || this.why.has(id) || !trying()) && done();
+        const timer = setTimeout(done, timeout);
+        this.on('change', check);
+        check();
+      });
+    }
+    const conn = this.conns.get(id);
+    if (!conn) {
+      const why = this.why.get(id);
+      if (why?.status === 'pair-again') {
+        return { ok: false, reason: 'pair-again', text: `The pairing doesn't match: press Pair again ${why.keyHeldBy === 'them' ? `in ${app.name}` : 'here'}` };
+      }
+      if (why?.status === 'incompatible') {
+        return { ok: false, reason: 'incompatible', text: incompatible(this.self, why.theirApp ?? app, hs.PROTOCOL, why.theirProtocol ?? hs.PROTOCOL).text };
+      }
+      if (why?.reason === 'switched-off') return { ok: false, reason: 'switched-off', text: `${app.name} is open, but its Connect switch is off` };
+      return { ok: false, reason: 'no-answer', text: `${app.name} is open, but didn't answer` };
+    }
+    const started = performance.now();
+    try {
+      await conn.rpc.request('link.ping', {}, { timeout });
+    } catch {
+      return { ok: false, reason: 'no-answer', text: `${app.name} didn't answer` };
+    }
+    const ms = Math.max(1, Math.round(performance.now() - started));
+    return { ok: true, ms, version: conn.peer.version, text: `${app.name} ${conn.peer.version} answered in ${ms} ms` };
+  }
+
   isConnected(appId) {
     return this.conns.has(this.currentId(appId));
   }

package/types/index.d.ts

@@ -128,6 +128,15 @@ export interface Peer {
   keysEncrypted: boolean;
 }
 
+export type TestResult =
+  | { ok: true; ms: number; version: string; text: string }
+  | {
+      ok: false;
+      reason: 'unknown' | 'off' | 'not-started' | 'not-running' | 'switched-off' | 'pair-again' | 'incompatible' | 'no-answer';
+      /** In words, for the card: "Stream Multiview isn't open" */
+      text: string;
+    };
+
 export interface CallContext {
   appId: string;
   app: AppInfo;
@@ -156,6 +165,8 @@ export declare class Link extends EventEmitter {
   /** Pair again on a card: forgets this app's old key. */
   pairAgain(appId: string): void;
   isConnected(appId: string): boolean;
+  /** Test on a card: checks the link now, and says how it went. Tries straight away when not connected. */
+  test(appId: string, opts?: { timeout?: number }): Promise<TestResult>;
   /** Its current id, given any id it has had: for moving your own settings across after another app is renamed. */
   currentId(appId: string): string;
   /** Every known app, for the Connected apps page. */