@streamorchard/grapevine 0.5.0 → 0.6.0

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'),
@@ -177,7 +184,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.0",
+  "version": "0.6.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

@@ -99,7 +99,14 @@ class Link extends EventEmitter {
       const server = net.createServer((socket) => this.accept(socket));
       const go = () =>
         server.listen(this.socketPath, () => {
-          if (platform !== 'win32') fs.chmodSync(this.socketPath, 0o600);
+          // The socket can vanish before this runs (its folder removed): start() fails, rather than
+          // an exception the app can't catch.
+          try {
+            if (platform !== 'win32') fs.chmodSync(this.socketPath, 0o600);
+          } catch (err) {
+            server.close();
+            return reject(err);
+          }
           this.server = server;
           resolve();
         });