@junoflow/cli 0.6.0 → 0.9.0

package/src/app-dev/server.js

@@ -0,0 +1,347 @@
+import { readFile, stat } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { extname, join, posix } from 'node:path';
+
+/**
+ * The URL segment the instance answers itself under /<id>/
+ * (internal/appserve's reservedSegment); ingest refuses an asset under it, so
+ * it never shadows a file here either.
+ */
+const RESERVED = '_juno';
+
+/**
+ * The version every response names. The dev server has one build of the app
+ * and never a second, so the client's skew check (`X-Juno-App-Version`
+ * against the stamp) never fires.
+ */
+export const DEV_VERSION = 1;
+
+/** The client the instance serves, byte for byte (TestAppClientCLICopy). */
+const CLIENT = readFile(new URL('../../app-client.js', import.meta.url));
+
+/**
+ * Content types by extension, for public/. The instance uses Go's
+ * mime.TypeByExtension; Node has no table of its own, so this is the part of
+ * it a page plausibly serves. Anything else is application/octet-stream.
+ */
+const CONTENT_TYPES = {
+  '.avif': 'image/avif',
+  '.css': 'text/css; charset=utf-8',
+  '.gif': 'image/gif',
+  '.htm': 'text/html; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.ico': 'image/vnd.microsoft.icon',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json',
+  '.map': 'application/json',
+  '.mjs': 'text/javascript; charset=utf-8',
+  '.mp3': 'audio/mpeg',
+  '.mp4': 'video/mp4',
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.svg': 'image/svg+xml',
+  '.txt': 'text/plain; charset=utf-8',
+  '.wasm': 'application/wasm',
+  '.webm': 'video/webm',
+  '.webmanifest': 'application/manifest+json',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.xml': 'text/xml; charset=utf-8',
+};
+
+/**
+ * createDevServer is `juno app dev`'s HTTP server: the instance's apps
+ * listener (internal/appserve) for one app, answered from the working copy
+ * instead of a stored version.
+ *
+ * | Request                       | Answer                                       |
+ * | ----------------------------- | -------------------------------------------- |
+ * | `GET /`                       | `routes.shell`: the page in a frame          |
+ * | `/_dev/<rest>`                | `routes.dev`                                 |
+ * | `GET /<id>`                   | 301 → `/<id>/`                               |
+ * | `GET /<id>/`, `/<id>/<entry>` | `page/<entry>` as written                    |
+ * | `GET /<id>/<path>.ts`         | that page/ module, bundled for the browser   |
+ * | `GET /<id>/<path>`            | `public/<path>`                              |
+ * | `GET /<id>/_juno/app.js`      | the stamp line and the client                |
+ * | `POST /<id>/_juno/call/<h>`   | the harness's answer, as the invoker maps it |
+ * | `GET /<id>/_juno/stream`      | `routes.stream`                              |
+ *
+ * `routes` is the extension point: each member is `(req, res, url)` and owns
+ * the response. Left out, `shell` frames the page and `dev` and `stream` are
+ * 404s. They are copied onto the returned object's `routes`, which is what
+ * the server reads per request, so a member set there later takes effect.
+ *
+ * dev is the harness (createDevHarness), builder the esbuild wrapper
+ * (createBuilder); log receives one line per failed call.
+ */
+export function createDevServer({
+  cwd,
+  dev,
+  builder,
+  routes = {},
+  log = () => {},
+}) {
+  const srv = {
+    routes: Object.assign({ shell: serveShell }, routes),
+    server: createServer((req, res) => {
+      handle(req, res).catch((err) => {
+        log(`${req.method} ${req.url}: ${err.message}`);
+        if (!res.headersSent) sendText(res, 500, 'internal error');
+        else res.destroy();
+      });
+    }),
+
+    /** Listens on 127.0.0.1 only and resolves to the port. */
+    listen(port) {
+      return new Promise((resolve, reject) => {
+        srv.server.once('error', reject);
+        srv.server.listen(port, '127.0.0.1', () => {
+          srv.server.off('error', reject);
+          resolve(srv.server.address().port);
+        });
+      });
+    },
+
+    /** Stops listening and drops every open connection (a stream included). */
+    close() {
+      return new Promise((resolve) => {
+        srv.server.close(() => resolve());
+        srv.server.closeAllConnections();
+      });
+    },
+  };
+
+  async function handle(req, res) {
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('Cache-Control', 'no-store');
+    const url = new URL(req.url, 'http://localhost');
+    const id = dev.manifest.id;
+
+    if (url.pathname === '/') {
+      if (!allowGet(req, res)) return;
+      return srv.routes.shell(req, res, url);
+    }
+    if (url.pathname.startsWith('/_dev/')) {
+      return route(srv.routes.dev, req, res, url);
+    }
+    if (url.pathname === `/${id}`) {
+      res.writeHead(301, { Location: `/${id}/${url.search}` });
+      return res.end();
+    }
+    if (!url.pathname.startsWith(`/${id}/`)) {
+      return sendHTML(res, 404, 'This app is not available');
+    }
+
+    // Only the app's own frame, the shell's, may embed it.
+    res.setHeader('Content-Security-Policy', "frame-ancestors 'self'");
+    const rest = safePath(url.pathname.slice(id.length + 2));
+    if (rest === null) return sendText(res, 404, 'not found');
+
+    if (rest.startsWith(`${RESERVED}/`)) {
+      const after = rest.slice(RESERVED.length + 1);
+      if (after === 'app.js') return serveClient(req, res, id);
+      if (after === 'stream') return route(srv.routes.stream, req, res, url);
+      if (after.startsWith('call/')) {
+        return serveCall(req, res, id, after.slice('call/'.length));
+      }
+      return sendText(res, 404, 'not found');
+    }
+    if (!allowGet(req, res)) return;
+    const entry = dev.manifest.entry || 'index.html';
+    if (rest === '' || rest === entry) {
+      return serveFile(
+        req,
+        res,
+        join(cwd, 'page', entry),
+        CONTENT_TYPES['.html']
+      );
+    }
+    if (rest.endsWith('.ts')) return servePageModule(req, res, rest);
+    return serveFile(req, res, join(cwd, 'public', rest), contentType(rest));
+  }
+
+  /** The default `/`: the page in a full-window frame, so it runs at /<id>/. */
+  function serveShell(_req, res) {
+    const id = escapeHTML(dev.manifest.id);
+    sendHTML(
+      res,
+      200,
+      `<!doctype html>\n<meta charset="utf-8">\n<title>${id} — juno app dev</title>\n` +
+        '<style>html,body{margin:0;height:100%}iframe{border:0;width:100%;height:100%}</style>\n' +
+        `<iframe src="/${id}/"></iframe>\n`
+    );
+  }
+
+  async function serveClient(req, res, id) {
+    if (!allowGet(req, res)) return;
+    const stamp = JSON.stringify({
+      id,
+      version: DEV_VERSION,
+      base: `/${id}/`,
+    });
+    const body = Buffer.concat([
+      Buffer.from(`window.__JUNO_APP__=${stamp};\n`),
+      await CLIENT,
+    ]);
+    send(req, res, 200, CONTENT_TYPES['.js'], body);
+  }
+
+  /**
+   * A page/ module, built on this request. A `<script type="module">` runs
+   * whatever arrives with a JavaScript content type, whatever the URL's
+   * extension, so the page needs no rewriting (decision 3). A build failure
+   * is a 500 carrying esbuild's message.
+   */
+  async function servePageModule(req, res, rest) {
+    const abs = join(cwd, 'page', rest);
+    if (!(await isFile(abs))) return sendText(res, 404, 'not found');
+    let js;
+    try {
+      js = await builder.page(abs);
+    } catch (err) {
+      log(`build page/${rest}: ${err.message}`);
+      return sendText(res, 500, err.message);
+    }
+    send(req, res, 200, CONTENT_TYPES['.js'], Buffer.from(js));
+  }
+
+  async function serveFile(req, res, abs, type) {
+    if (!(await isFile(abs))) return sendText(res, 404, 'not found');
+    send(req, res, 200, type, await readFile(abs));
+  }
+
+  /**
+   * One handler call, in the order internal/apps/invoker.go decides it: the
+   * handler (404), then the body (400; an empty one is {}), then the call. A
+   * throw, a harness refusal and a build failure are all 500s carrying the
+   * message. Not simulated: the timeout, the in-flight cap, the body cap.
+   */
+  async function serveCall(req, res, id, handler) {
+    if (req.method !== 'POST') {
+      res.setHeader('Allow', 'POST');
+      return sendCall(res, 405, { error: 'handlers are called with POST' });
+    }
+    const raw = await readBody(req);
+    const handlers = dev.manifest.handlers ?? {};
+    if (!Object.hasOwn(handlers, handler)) {
+      const have = Object.keys(handlers).sort().join(', ');
+      return sendCall(res, 404, {
+        error: `app ${JSON.stringify(id)} has no handler ${JSON.stringify(handler)} (have: ${have})`,
+      });
+    }
+    let input;
+    try {
+      input = raw.trim() === '' ? {} : JSON.parse(raw);
+    } catch (err) {
+      return sendCall(res, 400, {
+        error: `body is not valid JSON: ${err.message}`,
+      });
+    }
+    let result;
+    try {
+      result = await dev.call(handler, input);
+    } catch (err) {
+      log(`${handler}: ${err.message}`);
+      return sendCall(res, 500, { error: err.message });
+    }
+    sendCall(res, 200, { result });
+  }
+
+  return srv;
+}
+
+/** Hands the request to an optional route, or answers 404 without one. */
+function route(fn, req, res, url) {
+  if (typeof fn === 'function') return fn(req, res, url);
+  return sendText(res, 404, 'not found');
+}
+
+/**
+ * The path under /<id>/, decoded and normalised, or null for one that
+ * escapes it. A trailing slash is kept, so `dir/` names no file.
+ */
+function safePath(encoded) {
+  let rel;
+  try {
+    rel = decodeURIComponent(encoded);
+  } catch {
+    return null;
+  }
+  if (rel.includes('\0') || rel.includes('\\')) return null;
+  if (rel === '') return '';
+  const norm = posix.normalize(rel);
+  if (norm === '..' || norm.startsWith('../') || norm.startsWith('/')) {
+    return null;
+  }
+  return norm;
+}
+
+function contentType(rel) {
+  return (
+    CONTENT_TYPES[extname(rel).toLowerCase()] ?? 'application/octet-stream'
+  );
+}
+
+async function isFile(abs) {
+  try {
+    return (await stat(abs)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function allowGet(req, res) {
+  if (req.method === 'GET' || req.method === 'HEAD') return true;
+  res.setHeader('Allow', 'GET, HEAD');
+  sendText(res, 405, 'method not allowed');
+  return false;
+}
+
+function readBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', reject);
+  });
+}
+
+/** A body for GET, headers only for HEAD. */
+function send(req, res, status, type, body) {
+  res.writeHead(status, {
+    'Content-Type': type,
+    'Content-Length': body.length,
+  });
+  res.end(req.method === 'HEAD' ? undefined : body);
+}
+
+function sendCall(res, status, body) {
+  res.writeHead(status, {
+    'Content-Type': 'application/json',
+    'X-Juno-App-Version': String(DEV_VERSION),
+  });
+  res.end(JSON.stringify(body));
+}
+
+function sendText(res, status, text) {
+  res.writeHead(status, { 'Content-Type': 'text/plain; charset=utf-8' });
+  res.end(text);
+}
+
+function sendHTML(res, status, html) {
+  res.writeHead(status, { 'Content-Type': 'text/html; charset=utf-8' });
+  res.end(html);
+}
+
+function escapeHTML(s) {
+  return String(s).replace(
+    /[&<>"']/g,
+    (c) =>
+      ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[
+        c
+      ]
+  );
+}

package/src/app-dev/stream.js

@@ -0,0 +1,224 @@
+/** How often an open stream sends a `: ping` comment, as the instance does. */
+export const PING_MS = 20_000;
+
+/**
+ * How a control stands with nothing said about it: the instance's answer for
+ * a button and for an idle control (appserve.ControlValue, `null`s sent).
+ */
+const IDLE = Object.freeze({ value: null, active: false, expires_at: null });
+
+/**
+ * createLive is the dev server's `_juno/stream` (plan-local-dev-6 decision
+ * 6), in the instance's wire shape (internal/appserve, `.claude/rules/
+ * apps.md` "Live values"):
+ *
+ * | Event      | Data                             | When                         |
+ * | ---------- | -------------------------------- | ---------------------------- |
+ * | `snapshot` | `{"values": {states, controls}}` | on connect, and on `reset()` |
+ * | `update`   | `{"values": {states, controls}}` | `set()`, one per moved map   |
+ * | `pressed`  | `{"binding", "at"}`              | `press()`                    |
+ * | (comment)  | `: ping`                         | every `pingMs`               |
+ *
+ * Values are keyed by binding, as the instance keys them: every declared
+ * state binding under `states` (the scenario's value, else null) and every
+ * control binding under `controls` (idle). The panel's overrides sit on top.
+ * A read or read_write binding's override is also seeded into the harness,
+ * so a handler reads what the page is shown; a slot or signal binding holds
+ * no value a handler can read, so its override reaches the page only.
+ *
+ * `stale` is never sent: the dev server serves one version, whatever `?v=`
+ * the client names. A handler's claim or set moves no value here, because
+ * the layer stack is the instance's, as it is in the harness.
+ *
+ * dev is the harness (createDevHarness). Telling the panel the values moved
+ * is the caller's (createPanel).
+ */
+export function createLive({ dev, pingMs = PING_MS }) {
+  const streams = new Set();
+  // The panel's overrides, by binding. Cleared by a scenario switch.
+  let overrides = { states: {}, controls: {} };
+
+  const live = {
+    /** The values a snapshot would carry now. */
+    values() {
+      const states = {};
+      for (const name of Object.keys(dev.manifest.states ?? {})) {
+        states[name] = Object.hasOwn(overrides.states, name)
+          ? overrides.states[name]
+          : (dev.scenario?.value?.states?.[name] ?? null);
+      }
+      const controls = {};
+      for (const name of Object.keys(dev.manifest.controls ?? {})) {
+        controls[name] = overrides.controls[name] ?? { ...IDLE };
+      }
+      return { states, controls };
+    },
+
+    /**
+     * Moves values, `{states?, controls?}` by binding, and sends one
+     * `update` per map that moved, the other map `{}` — as the instance
+     * sends a settle generation and a control change separately. A binding
+     * the manifest does not declare, or a control value that is not an
+     * object, throws before anything moves.
+     */
+    set({ states = {}, controls = {} } = {}) {
+      const declared = {
+        states: dev.manifest.states ?? {},
+        controls: dev.manifest.controls ?? {},
+      };
+      for (const [section, map] of Object.entries({ states, controls })) {
+        if (map === null || typeof map !== 'object' || Array.isArray(map)) {
+          throw new Error(`"${section}" maps bindings to values`);
+        }
+        for (const name of Object.keys(map)) {
+          if (!Object.hasOwn(declared[section], name)) {
+            throw new Error(
+              `"${name}" is not declared in manifest.json ${section} (have: ${Object.keys(declared[section]).sort().join(', ') || '(none)'})`
+            );
+          }
+        }
+      }
+      const movedControls = {};
+      for (const [name, v] of Object.entries(controls)) {
+        movedControls[name] = controlValue(name, v);
+      }
+      const seeded = {};
+      for (const [name, v] of Object.entries(states)) {
+        if (holdsValue(declared.states[name])) seeded[name] = v;
+      }
+      dev.h.states(seeded);
+
+      Object.assign(overrides.states, states);
+      Object.assign(overrides.controls, movedControls);
+      if (Object.keys(states).length) {
+        broadcast('update', { values: { states, controls: {} } });
+      }
+      if (Object.keys(movedControls).length) {
+        broadcast('update', {
+          values: { states: {}, controls: movedControls },
+        });
+      }
+    },
+
+    /** Sends `pressed` for a declared control binding, at now. */
+    press(binding) {
+      const controls = dev.manifest.controls ?? {};
+      if (typeof binding !== 'string' || !Object.hasOwn(controls, binding)) {
+        throw new Error(
+          `"${binding}" is not declared in manifest.json controls (have: ${Object.keys(controls).sort().join(', ') || '(none)'})`
+        );
+      }
+      const data = { binding, at: new Date().toISOString() };
+      broadcast('pressed', data);
+      return data;
+    },
+
+    /**
+     * After the harness was rebuilt (a scenario switch, a manifest save):
+     * drops the overrides with `clear`, or keeps those whose binding is still
+     * declared and seeds them into the fresh harness, then sends every open
+     * stream a new snapshot.
+     */
+    reset({ clear }) {
+      if (clear) {
+        overrides = { states: {}, controls: {} };
+      } else {
+        const states = dev.manifest.states ?? {};
+        const controls = dev.manifest.controls ?? {};
+        overrides = {
+          states: pick(overrides.states, states),
+          controls: pick(overrides.controls, controls),
+        };
+        const seeded = {};
+        for (const [name, v] of Object.entries(overrides.states)) {
+          if (holdsValue(states[name])) seeded[name] = v;
+        }
+        dev.h.states(seeded);
+      }
+      broadcast('snapshot', { values: live.values() });
+    },
+
+    /** The `_juno/stream` route. */
+    serve(req, res) {
+      if (req.method !== 'GET') {
+        res.writeHead(405, {
+          Allow: 'GET',
+          'Content-Type': 'text/plain; charset=utf-8',
+        });
+        return res.end('method not allowed');
+      }
+      const stream = openStream(res, pingMs, () => streams.delete(stream));
+      streams.add(stream);
+      stream.send('snapshot', { values: live.values() });
+    },
+
+    /** Ends every open stream. */
+    close() {
+      for (const s of streams) s.end();
+    },
+  };
+
+  function broadcast(event, data) {
+    for (const s of streams) s.send(event, data);
+  }
+
+  return live;
+}
+
+/**
+ * openStream starts a server-sent event response with the instance's
+ * headers, and a `: ping` comment every pingMs so an idle connection is kept.
+ * The timer stops when the response closes, by either side. Returns
+ * `{send(event, data), end()}`.
+ */
+export function openStream(res, pingMs, onClose = () => {}) {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache',
+    'X-Accel-Buffering': 'no',
+  });
+  res.flushHeaders();
+  const ping = setInterval(() => res.write(': ping\n\n'), pingMs);
+  res.on('close', () => {
+    clearInterval(ping);
+    onClose();
+  });
+  return {
+    // One line of JSON, which never contains a raw newline.
+    send(event, data) {
+      res.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
+    },
+    end() {
+      clearInterval(ping);
+      res.end();
+    },
+  };
+}
+
+/** A read or read_write binding: what h.states seeds and a handler reads. */
+function holdsValue(binding) {
+  return !binding?.slot && !binding?.signal;
+}
+
+/** A control's value as the instance sends it: the three fields, nulls kept. */
+function controlValue(name, v) {
+  if (v === null || typeof v !== 'object' || Array.isArray(v)) {
+    throw new Error(
+      `controls "${name}" — expected {value, active, expires_at}, got ${JSON.stringify(v)}`
+    );
+  }
+  if (v.expires_at != null && typeof v.expires_at !== 'string') {
+    throw new Error(`controls "${name}" — expires_at must be a string or null`);
+  }
+  return {
+    value: v.value ?? null,
+    active: v.active === true,
+    expires_at: v.expires_at ?? null,
+  };
+}
+
+function pick(map, declared) {
+  return Object.fromEntries(
+    Object.entries(map).filter(([name]) => Object.hasOwn(declared, name))
+  );
+}

package/src/app-dev/watch.js

@@ -0,0 +1,47 @@
+import { join } from 'node:path';
+
+import { watchPaths } from '../watch.js';
+
+/**
+ * watchApp is `juno app dev`'s rebuild on save (plan-local-dev-6 decision 9):
+ * one debounced watch per part of the working copy, so a save reaches the
+ * one handler that knows what to rebuild.
+ *
+ * | Handler    | Watches                                  |
+ * | ---------- | ---------------------------------------- |
+ * | `manifest` | `manifest.json`                          |
+ * | `src`      | `src/`, recursively                      |
+ * | `page`     | `page/` and `public/`, recursively       |
+ * | `fixtures` | `test/fixtures/`, recursively            |
+ *
+ * manifest.json is watched through its directory, filtered by name, because
+ * a watch on the file itself is lost the first time an editor saves by
+ * renaming over it. A directory absent at start is not watched. Returns
+ * `{close()}`.
+ */
+export function watchApp(cwd, on, { debounceMs } = {}) {
+  const groups = {
+    manifest: [
+      {
+        path: cwd,
+        filter: (name) => name === null || name === 'manifest.json',
+      },
+    ],
+    src: [{ path: join(cwd, 'src'), recursive: true }],
+    page: [
+      { path: join(cwd, 'page'), recursive: true },
+      { path: join(cwd, 'public'), recursive: true },
+    ],
+    fixtures: [{ path: join(cwd, 'test', 'fixtures'), recursive: true }],
+  };
+  const watchers = [];
+  for (const [group, paths] of Object.entries(groups)) {
+    if (typeof on[group] !== 'function') continue;
+    watchers.push(watchPaths(paths, on[group], { debounceMs }));
+  }
+  return {
+    close() {
+      for (const w of watchers) w.close();
+    },
+  };
+}