@junoflow/cli 0.6.0 → 0.9.0

package/app-client.js

@@ -0,0 +1,306 @@
+/*
+ * The Juno app client, served at /<id>/_juno/app.js.
+ *
+ * The apps listener prepends one line before this file:
+ *
+ *   window.__JUNO_APP__={"id":"echo","version":3,"base":"/echo/"};
+ *
+ * naming the version that served the page. Everything here is plain ES2020
+ * with no imports and no build step: it is embedded into the Go binary as is
+ * (sdkembed.go) and tested by sdk/test/app-client.test.js.
+ *
+ * window.juno.handlers.<name>(input) → Promise<output>
+ *   POSTs input as JSON to the handler and resolves with its result, or
+ *   rejects with an Error whose message is the handler's (or the host's).
+ *
+ * window.juno.values
+ *   The app's bound states and controls, by binding name:
+ *   {states: {<b>: value}, controls: {<b>: {value, active, expires_at}}}, or
+ *   null until the first snapshot has arrived.
+ *
+ * window.juno.watch(cb) → unwatch()
+ *   Calls cb(values, changed) on every snapshot and update, where changed
+ *   lists the keys that moved ("states.<b>", "controls.<b>"; every key on a
+ *   snapshot). Registered after a snapshot, cb is called at once with every
+ *   key.
+ *
+ * window.juno.controls.<binding>.onPress(cb) → unwatch()
+ *   Calls cb(at) on every press of that bound button control, at an RFC 3339
+ *   timestamp.
+ *
+ * handlers and controls are proxies, not maps of what the manifest declares:
+ * the client is never told the names, so any name reaches the server, and an
+ * unknown handler is a rejected call carrying the host's 404 — the same answer
+ * a hand-typed name got before. A name some JavaScript protocol looks up on
+ * every object (then, toJSON, toString, …) answers undefined instead, so
+ * `await juno.handlers` or JSON.stringify(juno) never fires a call;
+ * manifest.ValidateApp refuses those names for a handler or a control binding.
+ *
+ * The values arrive over one EventSource on _juno/stream, opened by the first
+ * watch or onPress and never on page load: a page that does not watch holds no
+ * connection. Every connect starts with a fresh snapshot, which replaces the
+ * values outright, so a dropped connection costs nothing; when the page becomes
+ * visible with its source closed (mobile browsers drop background
+ * connections), the client opens a new one.
+ *
+ * Version skew: every response names the version that answered it, and the
+ * stream sends `stale` when the page's version is no longer what its path
+ * serves. Either way the client dispatches a cancelable `juno:stale` event on
+ * window, once per page load; a stale stream is closed and never reopened.
+ * Unless a listener calls preventDefault(), the client shows a small
+ * "Updated — tap to reload" bar. Tapping it reloads, except on a ~draft/ page
+ * whose own version became the active one: that draft is gone, so the bar goes
+ * to the app's base instead.
+ */
+(function () {
+  'use strict';
+
+  var app = window.__JUNO_APP__ || {};
+  var base = app.base || '/';
+  var version = app.version;
+  var draftSuffix = '~draft/';
+  var staleSeen = false;
+
+  function checkVersion(res) {
+    var answered = res.headers && res.headers.get('X-Juno-App-Version');
+    if (!answered || Number(answered) === version) return;
+    reportStale(Number(answered));
+  }
+
+  // reportStale dispatches juno:stale, once per page load, whether the call
+  // path or the stream noticed first.
+  function reportStale(current) {
+    if (staleSeen) return;
+    staleSeen = true;
+    var event = new CustomEvent('juno:stale', {
+      cancelable: true,
+      detail: { version: version, current: current },
+    });
+    if (!window.dispatchEvent(event)) return;
+    // A ~draft/ page told that its own version is now current was activated:
+    // ~draft/ no longer serves it, and reloading would show a 404.
+    var activated =
+      current === version && base.slice(-draftSuffix.length) === draftSuffix;
+    showReloadBar(
+      activated ? base.slice(0, base.length - draftSuffix.length) : null
+    );
+  }
+
+  function showReloadBar(href) {
+    var bar = document.createElement('div');
+    bar.setAttribute('role', 'button');
+    bar.textContent = 'Updated — tap to reload';
+    bar.style.cssText =
+      'position:fixed;left:0;right:0;bottom:0;z-index:2147483647;padding:12px 16px;' +
+      'background:#1f2937;color:#fff;font:14px/1.4 system-ui,sans-serif;' +
+      'text-align:center;cursor:pointer';
+    bar.addEventListener('click', function () {
+      if (href) window.location.assign(href);
+      else window.location.reload();
+    });
+    document.body.appendChild(bar);
+  }
+
+  // namespace answers every name with make(name), made once, except the
+  // protocol names in the header comment. Keep the list in step with
+  // manifest.appReservedNames.
+  function namespace(make) {
+    var made = Object.create(null);
+    return new Proxy(Object.create(null), {
+      get: function (target, name) {
+        if (typeof name !== 'string' || reserved(name)) return undefined;
+        return made[name] || (made[name] = make(name));
+      },
+      set: function () {
+        return false;
+      },
+    });
+  }
+
+  function reserved(name) {
+    return name === 'then' || name === 'toJSON' || name in Object.prototype;
+  }
+
+  async function call(name, input) {
+    var res = await fetch(base + '_juno/call/' + encodeURIComponent(name), {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-Juno-App-Version': String(version),
+      },
+      body: JSON.stringify(input === undefined ? {} : input),
+    });
+    checkVersion(res);
+    var body;
+    try {
+      body = await res.json();
+    } catch (e) {
+      throw new Error('HTTP ' + res.status);
+    }
+    if (!res.ok) {
+      throw new Error(
+        body && typeof body.error === 'string'
+          ? body.error
+          : 'HTTP ' + res.status
+      );
+    }
+    return body.result;
+  }
+
+  // Live values. The stream is opened lazily and at most one is open.
+  var values = null;
+  var watchers = [];
+  var pressHandlers = Object.create(null);
+  var source = null;
+  var streamStale = false;
+  var visibilityHooked = false;
+
+  function openStream() {
+    if (streamStale || (source && source.readyState !== EventSource.CLOSED)) {
+      return;
+    }
+    source = new EventSource(base + '_juno/stream?v=' + version);
+    source.addEventListener('snapshot', onSnapshot);
+    source.addEventListener('update', onUpdate);
+    source.addEventListener('pressed', onPressed);
+    source.addEventListener('stale', onStale);
+    if (!visibilityHooked) {
+      visibilityHooked = true;
+      document.addEventListener('visibilitychange', function () {
+        // A source the browser gave up on stays closed; one it is still
+        // retrying is left to its own reconnect.
+        if (document.visibilityState === 'visible') openStream();
+      });
+    }
+  }
+
+  function parse(ev) {
+    try {
+      return JSON.parse(ev.data);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  function keys(vals) {
+    var out = [];
+    Object.keys(vals.states || {}).forEach(function (b) {
+      out.push('states.' + b);
+    });
+    Object.keys(vals.controls || {}).forEach(function (b) {
+      out.push('controls.' + b);
+    });
+    return out;
+  }
+
+  function notify(cb, changed) {
+    try {
+      cb(values, changed);
+    } catch (e) {
+      console.error(e);
+    }
+  }
+
+  function onSnapshot(ev) {
+    var data = parse(ev);
+    if (!data || !data.values) return;
+    values = {
+      states: data.values.states || {},
+      controls: data.values.controls || {},
+    };
+    var changed = keys(values);
+    watchers.slice().forEach(function (cb) {
+      notify(cb, changed);
+    });
+  }
+
+  // onUpdate merges per binding. An update carries both maps, the one that did
+  // not move empty, so the changed keys are exactly the bindings present.
+  function onUpdate(ev) {
+    var data = parse(ev);
+    if (!data || !data.values || !values) return;
+    var moved = {
+      states: data.values.states || {},
+      controls: data.values.controls || {},
+    };
+    values = {
+      states: Object.assign({}, values.states, moved.states),
+      controls: Object.assign({}, values.controls, moved.controls),
+    };
+    var changed = keys(moved);
+    if (!changed.length) return;
+    watchers.slice().forEach(function (cb) {
+      notify(cb, changed);
+    });
+  }
+
+  function onPressed(ev) {
+    var data = parse(ev);
+    if (!data) return;
+    (pressHandlers[data.binding] || []).slice().forEach(function (cb) {
+      try {
+        cb(data.at);
+      } catch (e) {
+        console.error(e);
+      }
+    });
+  }
+
+  // onStale closes the source before anything else: the server ends the
+  // response, and an EventSource left open would reconnect into another stale.
+  function onStale(ev) {
+    streamStale = true;
+    source.close();
+    var data = parse(ev);
+    reportStale(data && typeof data.version === 'number' ? data.version : NaN);
+  }
+
+  function remover(list, cb) {
+    return function () {
+      var i = list.indexOf(cb);
+      if (i >= 0) list.splice(i, 1);
+    };
+  }
+
+  function watch(cb) {
+    if (typeof cb !== 'function') {
+      throw new TypeError('juno.watch: callback must be a function');
+    }
+    watchers.push(cb);
+    openStream();
+    if (values) notify(cb, keys(values));
+    return remover(watchers, cb);
+  }
+
+  function onPress(binding, cb) {
+    if (typeof cb !== 'function') {
+      throw new TypeError(
+        'juno.controls.' + binding + '.onPress: callback must be a function'
+      );
+    }
+    var list = pressHandlers[binding] || (pressHandlers[binding] = []);
+    list.push(cb);
+    openStream();
+    return remover(list, cb);
+  }
+
+  window.juno = Object.freeze({
+    app: Object.freeze({ id: app.id, version: version, base: base }),
+    handlers: namespace(function (name) {
+      return function (input) {
+        return call(name, input);
+      };
+    }),
+    controls: namespace(function (binding) {
+      return Object.freeze({
+        onPress: function (cb) {
+          return onPress(binding, cb);
+        },
+      });
+    }),
+    get values() {
+      return values;
+    },
+    watch: watch,
+  });
+})();

package/eslint.app.config.js

@@ -0,0 +1,34 @@
+import tsParser from '@typescript-eslint/parser';
+import juno from '@junoflow/eslint-plugin';
+
+/**
+ * The lint preset for an app working copy (`juno app init`).
+ *
+ * The rules come from the plugin's `rulesets.json`, `configs.app` — the set
+ * Juno's verify step lints an app's src/ with — so the author runs the rules
+ * the server runs, by construction rather than by two lists.
+ *
+ * Only the handlers are linted. page/ is not: the `app` ruleset is written
+ * for handlers (a page's clock and module state are not a handler's), and
+ * verify does not lint page/ either, so a local lint matches the server's.
+ * The generated `.d.ts` files are not linted: verify lints the author's
+ * source and nothing else, and app-env.d.ts carries an `eslint-disable`
+ * comment naming a rule this config does not load, which eslint would report
+ * as unknown. Neither is test/: the app rules are written for handler code,
+ * and a test calling `Date.now()` is not a defect.
+ */
+export default [
+  {
+    ignores: ['node_modules/**', 'dist/**', '**/*.d.ts', 'page/**', 'test/**'],
+  },
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parser: tsParser,
+      ecmaVersion: 2022,
+      sourceType: 'module',
+    },
+    plugins: { juno },
+    rules: { ...juno.configs.app },
+  },
+];

package/eslint.flow.config.js

@@ -5,7 +5,7 @@ import juno from '@junoflow/eslint-plugin';
  * The lint preset for a flow working copy (`juno flow init`).
  *
  * The rules come from the plugin's `rulesets.json`, `configs.flow` — the set
- * Juno's verify step lints a flow's `flow.ts` with — so the author runs the
+ * Juno's verify step lints a flow's `src/` with — so the author runs the
  * rules the server runs, by construction rather than by two lists.
  *
  * One rule reports nothing here: `juno/prefer-claim-over-set` needs to know
@@ -15,10 +15,12 @@ import juno from '@junoflow/eslint-plugin';
  *
  * The generated `.d.ts` files are not linted: verify lints the author's source
  * and nothing else, and the flow rules are about handlers they do not contain.
+ * Neither is test/: the flow rules are written for handler code, and a test
+ * calling `Date.now()` is not a defect.
  */
 export default [
   {
-    ignores: ['node_modules/**', 'dist/**', '**/*.d.ts'],
+    ignores: ['node_modules/**', 'dist/**', '**/*.d.ts', 'test/**'],
   },
   {
     files: ['**/*.ts'],

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@junoflow/cli",
-  "version": "0.6.0",
-  "description": "Develop Juno integrations and operate a Juno instance from the command line",
+  "version": "0.9.0",
+  "description": "Develop Juno flows, integrations and apps, and operate a Juno instance from the command line",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -16,16 +16,21 @@
     ".": "./src/index.js",
     "./package.json": "./package.json",
     "./tsconfig.base.json": "./tsconfig.base.json",
+    "./tsconfig.page.json": "./tsconfig.page.json",
     "./eslint.config.js": "./eslint.config.js",
-    "./eslint.flow.config.js": "./eslint.flow.config.js"
+    "./eslint.flow.config.js": "./eslint.flow.config.js",
+    "./eslint.app.config.js": "./eslint.app.config.js"
   },
   "files": [
     "bin",
     "src",
     "tsconfig.base.json",
+    "tsconfig.page.json",
     "eslint.config.js",
     "eslint.flow.config.js",
+    "eslint.app.config.js",
     "verbs.json",
+    "app-client.js",
     "README.md"
   ],
   "scripts": {
@@ -35,7 +40,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@junoflow/eslint-plugin": "0.6.0",
+    "@junoflow/eslint-plugin": "0.9.0",
     "@typescript-eslint/parser": "^8.0.0"
   },
   "devDependencies": {