@junoflow/cli 0.3.0 → 0.9.0

package/src/app-dev/build.js

@@ -0,0 +1,134 @@
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import { UserError } from '../errors.js';
+
+/**
+ * loadFromWorkingCopy imports `name` as the working copy's own code would:
+ * resolved from its package.json, so out of its node_modules. The CLI has no
+ * runtime dependencies (`.claude/rules/cli.md`, "A thin client"), and the dev
+ * server must run the esbuild and testkit the project's own build and tests
+ * run, not a second copy of either.
+ */
+export async function loadFromWorkingCopy(cwd, name) {
+  let resolved;
+  try {
+    resolved = createRequire(join(cwd, 'package.json')).resolve(name);
+  } catch {
+    throw new UserError(
+      `${name} is not installed in this working copy — run npm install`
+    );
+  }
+  return import(pathToFileURL(resolved).href);
+}
+
+/**
+ * createBuilder wraps the working copy's esbuild with the two builds the dev
+ * server makes: a page/ module for the browser, as ingest bundles it
+ * (internal/verify/page.go's bundlePage), and src/app.ts for Node, imported
+ * in process for the harness.
+ *
+ * A page module is built on every request, so a save needs no watcher to show
+ * up. The handlers are built once and kept: `invalidate()` marks them for a
+ * rebuild on the next `handlers()`, and a rebuild that fails keeps the last
+ * good module serving, with the failure in `error` — a syntax error mid-edit
+ * must not take the page's working calls down with it. `generation` counts
+ * the handler builds that succeeded, so a caller holding something built from
+ * one module can tell when it is out of date.
+ */
+export async function createBuilder(cwd) {
+  const mod = await loadFromWorkingCopy(cwd, 'esbuild');
+  const esbuild = typeof mod.build === 'function' ? mod : mod.default;
+  const tmp = await mkdtemp(join(tmpdir(), 'juno-app-dev-'));
+
+  let generation = 0;
+  let good = null; // the last module that built and imported
+  let dirty = true;
+  let error = null; // the last rebuild's failure, null after a success
+
+  const builder = {
+    /** The page/ module at abs, bundled for the browser, as JavaScript text. */
+    async page(abs) {
+      const out = await esbuild.build({
+        entryPoints: [abs],
+        absWorkingDir: cwd,
+        bundle: true,
+        format: 'esm',
+        platform: 'browser',
+        target: 'es2020',
+        write: false,
+        logLevel: 'silent',
+      });
+      return out.outputFiles[0].text;
+    },
+
+    /**
+     * The handlers module's default export, rebuilt first when invalidated.
+     * Throws only when nothing has ever built.
+     */
+    async handlers() {
+      if (dirty) {
+        dirty = false;
+        try {
+          good = await buildHandlers();
+          error = null;
+        } catch (err) {
+          // Retried on the next call too, so a fix is picked up even before
+          // anything invalidates.
+          error = err;
+          dirty = true;
+        }
+      }
+      if (!good) throw error;
+      return good;
+    },
+
+    /** Marks src/ as changed: the next handlers() rebuilds. */
+    invalidate() {
+      dirty = true;
+    },
+
+    /** The last handlers rebuild's failure, or null. */
+    get error() {
+      return error;
+    },
+
+    /** How many handler builds have succeeded. */
+    get generation() {
+      return generation;
+    },
+
+    /** Removes the temp directory the handler builds are written to. */
+    close() {
+      return rm(tmp, { recursive: true, force: true });
+    },
+  };
+
+  /**
+   * One Node build of src/app.ts, written under tmp and imported with a
+   * cache-busting query: Node caches a module by URL, and the same URL would
+   * answer the first build forever.
+   */
+  async function buildHandlers() {
+    const out = await esbuild.build({
+      entryPoints: [join(cwd, 'src', 'app.ts')],
+      absWorkingDir: cwd,
+      bundle: true,
+      format: 'esm',
+      platform: 'node',
+      target: 'node20',
+      write: false,
+      logLevel: 'silent',
+    });
+    const file = join(tmp, 'app.mjs');
+    await writeFile(file, out.outputFiles[0].text, 'utf8');
+    generation += 1;
+    const mod = await import(`${pathToFileURL(file).href}?v=${generation}`);
+    return mod.default;
+  }
+
+  return builder;
+}

package/src/app-dev/harness.js

@@ -0,0 +1,108 @@
+import { readFile } from 'node:fs/promises';
+import { isAbsolute, relative, resolve } from 'node:path';
+
+import { UserError } from '../errors.js';
+import { loadFromWorkingCopy } from './build.js';
+
+/**
+ * createDevHarness runs the app's handlers the way `npm test` does: through
+ * the working copy's own @junoflow/testkit appHarness, so the dev server is
+ * exactly as strict as the project's tests — an unanswered target is a
+ * refusal naming `binding.method`, not a silent `undefined`.
+ *
+ * The world comes from a scenario file, the shape `h.scenario` takes
+ * (plan-local-dev-6 decision 7). With none, the world is empty, and every
+ * call that asks it something fails visibly.
+ *
+ * One harness lives until the scenario or the manifest changes; then a fresh
+ * one is built and the scenario re-applied to it. A handlers rebuild keeps
+ * the harness: its `app` reads the builder's latest module on every call.
+ */
+export async function createDevHarness({ cwd, manifest, builder }) {
+  const { appHarness } = await loadFromWorkingCopy(cwd, '@junoflow/testkit');
+  if (typeof appHarness !== 'function') {
+    throw new UserError(
+      '@junoflow/testkit in this working copy has no appHarness — run npm install @junoflow/testkit@latest'
+    );
+  }
+
+  let latest = { handlers: {} };
+  const app = {
+    get handlers() {
+      return latest.handlers;
+    },
+  };
+
+  const dev = {
+    manifest,
+    /** The scenario in use, `{path, value}` (path relative to cwd), or null. */
+    scenario: null,
+    /** The testkit harness calls go through; replaced by a reset. */
+    h: null,
+
+    /**
+     * Reads and applies the scenario at path (relative to cwd), or the empty
+     * world for null. A file that is not a scenario fails here, naming it,
+     * and the scenario in use stays.
+     */
+    async useScenario(path) {
+      if (path == null) {
+        dev.scenario = null;
+      } else {
+        const abs = isAbsolute(path) ? path : resolve(cwd, path);
+        const rel = relative(cwd, abs);
+        const value = await readScenario(abs, rel);
+        // Applied to a throwaway harness first, so a bad key is refused with
+        // the testkit's message before anything is replaced.
+        try {
+          appHarness({ manifest: dev.manifest, app }).scenario(value);
+        } catch (err) {
+          throw new UserError(`${rel}: ${err.message}`);
+        }
+        dev.scenario = { path: rel, value };
+      }
+      reset();
+      return dev;
+    },
+
+    /** Replaces the manifest (manifest.json was saved) and resets. */
+    setManifest(m) {
+      dev.manifest = m;
+      reset();
+      return dev;
+    },
+
+    /**
+     * Calls handler name with input, after picking up the latest handlers
+     * build. Resolves to the result after the JSON round trip; throws what
+     * the handler threw, the harness's refusal, or the build's failure.
+     */
+    async call(name, input) {
+      // A module with no default export reaches the harness's own refusal.
+      latest = (await builder.handlers()) ?? {};
+      return dev.h.call(name, input);
+    },
+  };
+
+  function reset() {
+    dev.h = appHarness({ manifest: dev.manifest, app });
+    if (dev.scenario) dev.h.scenario(dev.scenario.value);
+  }
+
+  reset();
+  return dev;
+}
+
+async function readScenario(abs, rel) {
+  let text;
+  try {
+    text = await readFile(abs, 'utf8');
+  } catch (err) {
+    throw new UserError(`cannot read scenario ${rel}: ${err.message}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw new UserError(`scenario ${rel} is not valid JSON: ${err.message}`);
+  }
+}

package/src/app-dev/panel.html

@@ -0,0 +1,336 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>juno app dev</title>
+    <style>
+      :root {
+        color-scheme: light dark;
+        --bg: #f6f6f4;
+        --fg: #1d1d1b;
+        --muted: #6b6b66;
+        --line: #d9d9d4;
+        --field: #ffffff;
+        --error-bg: #fbe9e7;
+        --error-fg: #8a1c0c;
+      }
+      @media (prefers-color-scheme: dark) {
+        :root {
+          --bg: #1c1c1a;
+          --fg: #e8e8e4;
+          --muted: #9a9a94;
+          --line: #3a3a36;
+          --field: #262624;
+          --error-bg: #3b1a14;
+          --error-fg: #ffb4a6;
+        }
+      }
+      * {
+        box-sizing: border-box;
+      }
+      html,
+      body {
+        margin: 0;
+        height: 100%;
+      }
+      body {
+        display: flex;
+        background: var(--bg);
+        color: var(--fg);
+        font:
+          13px/1.4 system-ui,
+          sans-serif;
+      }
+      aside {
+        width: 320px;
+        flex: none;
+        overflow-y: auto;
+        padding: 12px;
+        border-right: 1px solid var(--line);
+      }
+      main {
+        flex: 1;
+        min-width: 0;
+      }
+      iframe {
+        border: 0;
+        width: 100%;
+        height: 100%;
+        background: #fff;
+      }
+      h1 {
+        font-size: 14px;
+        margin: 0 0 4px;
+      }
+      h2 {
+        font-size: 11px;
+        text-transform: uppercase;
+        letter-spacing: 0.05em;
+        color: var(--muted);
+        margin: 16px 0 6px;
+      }
+      #status {
+        color: var(--muted);
+      }
+      #errors {
+        background: var(--error-bg);
+        color: var(--error-fg);
+        padding: 8px;
+        margin: 8px 0 0;
+        border-radius: 4px;
+        white-space: pre-wrap;
+        font:
+          12px/1.4 ui-monospace,
+          monospace;
+      }
+      #errors:empty {
+        display: none;
+      }
+      select,
+      input,
+      button {
+        font: inherit;
+        color: inherit;
+      }
+      select,
+      input {
+        background: var(--field);
+        border: 1px solid var(--line);
+        border-radius: 4px;
+        padding: 3px 6px;
+      }
+      select {
+        width: 100%;
+      }
+      button {
+        background: var(--field);
+        border: 1px solid var(--line);
+        border-radius: 4px;
+        padding: 3px 8px;
+        cursor: pointer;
+      }
+      .binding {
+        border-top: 1px solid var(--line);
+        padding: 6px 0;
+      }
+      .binding .name {
+        font-weight: 600;
+      }
+      .binding .kind {
+        color: var(--muted);
+        font-size: 11px;
+        margin-left: 4px;
+      }
+      .binding code {
+        display: block;
+        font:
+          12px/1.4 ui-monospace,
+          monospace;
+        color: var(--muted);
+        overflow-wrap: anywhere;
+        margin: 2px 0 4px;
+      }
+      .binding form {
+        display: flex;
+        gap: 4px;
+      }
+      .binding input {
+        flex: 1;
+        min-width: 0;
+      }
+      .empty,
+      .hint {
+        color: var(--muted);
+      }
+      .hint {
+        font-size: 11px;
+        margin-top: 4px;
+      }
+    </style>
+  </head>
+  <body>
+    <aside>
+      <h1 id="title">juno app dev</h1>
+      <div id="status">connecting…</div>
+      <pre id="errors"></pre>
+
+      <h2>Scenario</h2>
+      <select id="scenario"></select>
+
+      <h2>States</h2>
+      <div id="states"></div>
+      <div class="hint">
+        A value is JSON; anything else is sent as a string.
+      </div>
+
+      <h2>Controls</h2>
+      <div id="controls"></div>
+      <div class="hint">
+        A value is <code>{"value", "active", "expires_at"}</code>. Press sends a
+        button press.
+      </div>
+    </aside>
+    <main><iframe id="page" title="the app"></iframe></main>
+
+    <script>
+      // The panel for `juno app dev` (tools/npm/cli/src/app-dev/panel.js):
+      // it draws the server's `state` events and posts what the author does.
+      // It never touches the page in the frame beyond reloading it.
+      'use strict';
+
+      var $ = function (id) {
+        return document.getElementById(id);
+      };
+      var frame = $('page');
+      var shape = null; // the bindings drawn, as JSON
+
+      function post(path, body) {
+        return fetch('/_dev/' + path, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(body),
+        })
+          .then(function (res) {
+            return res.json().then(function (data) {
+              if (!res.ok) throw new Error(data.error || res.statusText);
+              return data;
+            });
+          })
+          .catch(function (err) {
+            alert(err.message);
+          });
+      }
+
+      // Typed text is JSON when it parses, and a string when it does not, so
+      // `on` needs no quotes.
+      function parse(text) {
+        try {
+          return JSON.parse(text);
+        } catch (e) {
+          return text;
+        }
+      }
+
+      function el(tag, cls, text) {
+        var n = document.createElement(tag);
+        if (cls) n.className = cls;
+        if (text != null) n.textContent = text;
+        return n;
+      }
+
+      function row(section, name, kind) {
+        var div = el('div', 'binding');
+        div.dataset.name = name;
+        var head = el('div');
+        head.appendChild(el('span', 'name', name));
+        if (kind) head.appendChild(el('span', 'kind', kind));
+        div.appendChild(head);
+        div.appendChild(el('code', 'value'));
+        var form = el('form');
+        var input = el('input');
+        input.placeholder = 'new value';
+        form.appendChild(input);
+        form.appendChild(el('button', null, 'set'));
+        if (section === 'controls') {
+          var press = el('button', null, 'press');
+          press.type = 'button';
+          press.onclick = function () {
+            post('press', { binding: name });
+          };
+          form.appendChild(press);
+        }
+        form.onsubmit = function (e) {
+          e.preventDefault();
+          var body = {};
+          body[section] = {};
+          body[section][name] = parse(input.value);
+          post('set', body).then(function (ok) {
+            if (ok) input.value = '';
+          });
+        };
+        div.appendChild(form);
+        return div;
+      }
+
+      function drawBindings(s) {
+        var next = JSON.stringify(s.bindings);
+        if (next === shape) return;
+        shape = next;
+        var states = $('states');
+        var controls = $('controls');
+        states.textContent = '';
+        controls.textContent = '';
+        s.bindings.states.forEach(function (b) {
+          states.appendChild(row('states', b.name, b.kind));
+        });
+        s.bindings.controls.forEach(function (name) {
+          controls.appendChild(row('controls', name));
+        });
+        if (!s.bindings.states.length) {
+          states.appendChild(el('div', 'empty', 'none declared'));
+        }
+        if (!s.bindings.controls.length) {
+          controls.appendChild(el('div', 'empty', 'none declared'));
+        }
+      }
+
+      function drawValues(values) {
+        ['states', 'controls'].forEach(function (section) {
+          $(section)
+            .querySelectorAll('.binding')
+            .forEach(function (div) {
+              var v = values[section][div.dataset.name];
+              div.querySelector('.value').textContent = JSON.stringify(v);
+            });
+        });
+      }
+
+      function drawScenarios(s) {
+        var sel = $('scenario');
+        sel.textContent = '';
+        var none = el('option', null, '(none: an empty world)');
+        none.value = '';
+        sel.appendChild(none);
+        var paths = s.scenarios.slice();
+        // A --scenario outside test/fixtures/ is still the one in use.
+        if (s.scenario && paths.indexOf(s.scenario) < 0) paths.push(s.scenario);
+        paths.forEach(function (p) {
+          var o = el('option', null, p);
+          o.value = p;
+          if (s.scenarios.indexOf(p) < 0) o.disabled = true;
+          sel.appendChild(o);
+        });
+        sel.value = s.scenario || '';
+      }
+
+      $('scenario').onchange = function (e) {
+        post('scenario', { path: e.target.value || null });
+      };
+
+      function draw(s) {
+        document.title = s.id + ' — juno app dev';
+        $('title').textContent = s.id;
+        if (!frame.getAttribute('src')) frame.src = '/' + s.id + '/';
+        $('errors').textContent = s.errors.join('\n\n');
+        drawScenarios(s);
+        drawBindings(s);
+        drawValues(s.values);
+      }
+
+      var events = new EventSource('/_dev/events');
+      events.addEventListener('open', function () {
+        $('status').textContent = 'connected';
+      });
+      events.addEventListener('error', function () {
+        $('status').textContent = 'disconnected: is juno app dev running?';
+      });
+      events.addEventListener('state', function (e) {
+        draw(JSON.parse(e.data));
+      });
+      events.addEventListener('reload', function () {
+        frame.contentWindow.location.reload();
+      });
+    </script>
+  </body>
+</html>