@junoflow/cli 0.3.0 → 0.9.0

package/src/app-dev/panel.js

@@ -0,0 +1,290 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { readManifestFile } from '../working-copy.js';
+import { openStream, PING_MS } from './stream.js';
+
+/** The panel page, served as written (one static file, no framework). */
+const PANEL = readFile(new URL('./panel.html', import.meta.url));
+
+/** Where the panel's scenario picker looks. */
+const FIXTURES = 'test/fixtures';
+
+/**
+ * createPanel is the dev panel's side of `juno app dev` (plan-local-dev-6
+ * decisions 7–9): the shell page at `/`, its channel under `/_dev/`, and
+ * what a save does.
+ *
+ * | Request               | Body                         | Answer                  |
+ * | --------------------- | ---------------------------- | ----------------------- |
+ * | `GET /`               |                              | panel.html              |
+ * | `GET /_dev/events`    |                              | SSE: `state`, `reload`  |
+ * | `POST /_dev/set`      | `{states?, controls?}`       | 200 `{values}`          |
+ * | `POST /_dev/press`    | `{binding}`                  | 200 `{binding, at}`     |
+ * | `POST /_dev/scenario` | `{path}`: a listed one, null | 200 the `state` data    |
+ *
+ * A POST must say `Content-Type: application/json`, which no page on another
+ * origin can send without a preflight this server never answers; a body the
+ * panel could not have sent is a 400 `{error}`.
+ *
+ * `state` carries everything the panel draws — `{id, scenario, scenarios,
+ * bindings, values, errors}` — and is sent on connect and after anything in
+ * it moves. `reload` tells the panel to reload the page's frame.
+ *
+ * Saves (watchApp's handlers): `src/` rebuilds the handlers at once, so a
+ * build error reaches the panel without a call, and reloads only after a
+ * good build — the last good one keeps serving. `page/` and `public/`
+ * reload. `manifest.json`, when its text changed, rebuilds the harness,
+ * keeps the overrides still declared, and reloads. A save under
+ * `test/fixtures/` relists the scenarios, and re-applies the one in use,
+ * from scratch, when its file is among them.
+ */
+export function createPanel({
+  cwd,
+  dev,
+  builder,
+  live,
+  pingMs = PING_MS,
+  log = () => {},
+}) {
+  const clients = new Set();
+  // What failed: the handlers build is builder.error; these are the others.
+  const problems = { manifest: null, scenario: null };
+  let manifestRaw = JSON.stringify(dev.manifest);
+  let scenarioRaw = null;
+  // Saves are applied one at a time, in order.
+  let queue = Promise.resolve();
+
+  const panel = {
+    /** The shell: the panel and the page's frame. */
+    async shell(req, res) {
+      const body = await PANEL;
+      res.writeHead(200, {
+        'Content-Type': 'text/html; charset=utf-8',
+        'Content-Length': body.length,
+      });
+      res.end(req.method === 'HEAD' ? undefined : body);
+    },
+
+    /** Everything under /_dev/. */
+    async route(req, res, url) {
+      const name = url.pathname.slice('/_dev/'.length);
+      if (name === 'events') {
+        if (req.method !== 'GET') return methodNotAllowed(res, 'GET');
+        const client = openStream(res, pingMs, () => clients.delete(client));
+        clients.add(client);
+        client.send('state', await state());
+        return;
+      }
+      const action = Object.hasOwn(ACTIONS, name) ? ACTIONS[name] : null;
+      if (!action) return sendJSON(res, 404, { error: 'not found' });
+      if (req.method !== 'POST') return methodNotAllowed(res, 'POST');
+      if (!/^application\/json\b/i.test(req.headers['content-type'] ?? '')) {
+        return sendJSON(res, 415, {
+          error: 'the panel posts Content-Type: application/json',
+        });
+      }
+      let body;
+      try {
+        body = JSON.parse((await readBody(req)) || '{}');
+      } catch (err) {
+        return sendJSON(res, 400, {
+          error: `body is not valid JSON: ${err.message}`,
+        });
+      }
+      if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+        return sendJSON(res, 400, { error: 'body must be a JSON object' });
+      }
+      let answer;
+      try {
+        answer = await action(body);
+      } catch (err) {
+        return sendJSON(res, 400, { error: err.message });
+      }
+      sendJSON(res, 200, answer);
+    },
+
+    /** Sends every panel the current state. */
+    async changed() {
+      if (clients.size === 0) return;
+      broadcast('state', await state());
+    },
+
+    /** watchApp's handlers. */
+    watch: {
+      src: () => serially(onSource),
+      page: () => serially(async () => broadcast('reload', {})),
+      manifest: () => serially(onManifest),
+      fixtures: () => serially(onFixtures),
+    },
+
+    /** Resolves once every save so far has been applied. */
+    settled() {
+      return queue;
+    },
+
+    /** Records the scenario file in use, so an unchanged save is ignored. */
+    async noteScenario() {
+      scenarioRaw = dev.scenario
+        ? await readFile(join(cwd, dev.scenario.path), 'utf8').catch(() => null)
+        : null;
+    },
+
+    /** Ends every panel connection. */
+    close() {
+      for (const c of clients) c.end();
+    },
+  };
+
+  const ACTIONS = {
+    async set(body) {
+      live.set({ states: body.states, controls: body.controls });
+      await panel.changed();
+      return { values: live.values() };
+    },
+    async press(body) {
+      return live.press(body.binding);
+    },
+    async scenario(body) {
+      const path = body.path ?? null;
+      if (path !== null && !(await listScenarios()).includes(path)) {
+        throw new Error(
+          `${JSON.stringify(path)} is not a scenario under ${FIXTURES}/`
+        );
+      }
+      await switchScenario(path);
+      return state();
+    },
+  };
+
+  /** Applies the scenario at path to a fresh harness; drops the overrides. */
+  async function switchScenario(path) {
+    await dev.useScenario(path);
+    problems.scenario = null;
+    await panel.noteScenario();
+    live.reset({ clear: true });
+    await panel.changed();
+  }
+
+  async function onSource() {
+    builder.invalidate();
+    try {
+      await builder.handlers();
+    } catch {
+      // Nothing has built yet: builder.error says why.
+    }
+    if (builder.error) {
+      log(`build src/app.ts: ${builder.error.message}`);
+      return panel.changed();
+    }
+    await panel.changed();
+    broadcast('reload', {});
+  }
+
+  async function onManifest() {
+    let read;
+    try {
+      read = await readManifestFile(cwd);
+    } catch (err) {
+      problems.manifest = err.message;
+      return panel.changed();
+    }
+    problems.manifest = null;
+    const raw = JSON.stringify(read.manifest);
+    if (raw === manifestRaw) return panel.changed();
+    manifestRaw = raw;
+    dev.setManifest(read.manifest);
+    live.reset({ clear: false });
+    await panel.changed();
+    broadcast('reload', {});
+  }
+
+  async function onFixtures() {
+    const path = dev.scenario?.path;
+    if (path && (await listScenarios()).includes(path)) {
+      const raw = await readFile(join(cwd, path), 'utf8').catch(() => null);
+      if (raw !== scenarioRaw) {
+        try {
+          await switchScenario(path);
+          return;
+        } catch (err) {
+          // The scenario in use stays, and says why on the panel.
+          problems.scenario = err.message;
+          scenarioRaw = raw;
+        }
+      }
+    }
+    await panel.changed();
+  }
+
+  function serially(fn) {
+    queue = queue.then(fn).catch((err) => log(`app dev: ${err.message}`));
+    return queue;
+  }
+
+  async function listScenarios() {
+    let names;
+    try {
+      names = await readdir(join(cwd, FIXTURES));
+    } catch {
+      return [];
+    }
+    return names
+      .filter((n) => n.endsWith('.json'))
+      .sort()
+      .map((n) => `${FIXTURES}/${n}`);
+  }
+
+  async function state() {
+    const states = dev.manifest.states ?? {};
+    return {
+      id: dev.manifest.id,
+      scenario: dev.scenario?.path ?? null,
+      scenarios: await listScenarios(),
+      bindings: {
+        states: Object.keys(states)
+          .sort()
+          .map((name) => ({ name, kind: bindingKind(states[name]) })),
+        controls: Object.keys(dev.manifest.controls ?? {}).sort(),
+      },
+      values: live.values(),
+      errors: [
+        builder.error && `src/app.ts: ${builder.error.message}`,
+        problems.manifest,
+        problems.scenario,
+      ].filter(Boolean),
+    };
+  }
+
+  function broadcast(event, data) {
+    for (const c of clients) c.send(event, data);
+  }
+
+  return panel;
+}
+
+/** A state binding's kind, as the harness names it. */
+function bindingKind(b) {
+  if (b?.slot) return 'slot';
+  if (b?.signal) return 'signal';
+  return b?.access === 'read_write' ? 'read_write' : 'read';
+}
+
+function methodNotAllowed(res, allow) {
+  res.setHeader('Allow', allow);
+  sendJSON(res, 405, { error: 'method not allowed' });
+}
+
+function sendJSON(res, status, body) {
+  res.writeHead(status, { 'Content-Type': 'application/json' });
+  res.end(JSON.stringify(body));
+}
+
+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);
+  });
+}

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
+      ]
+  );
+}