@luckydraw/cumulus 1.0.0 → 1.0.1

package/examples/web-app-agent/public/index.html

@@ -98,6 +98,20 @@
   <ul class="notes" id="note-list" data-testid="note-list" data-loading="false"></ul>
 </main>
 
+<!-- Asset versions. server.js rewrites the empty map at serve time (stampHtml),
+     and stamps the src/href attributes below with the same hashes. The map
+     exists for assets that are loaded from inside JavaScript — panel.css and
+     the blex pair — because an HTML-level stamp cannot see a URL that only
+     appears in a script. Left as {} by a server that does not do the rewrite,
+     in which case agentAsset() returns URLs unchanged. -->
+<script>
+  window.__AGENT_ASSET_V = {};
+  window.agentAsset = function (url) {
+    var v = window.__AGENT_ASSET_V[url];
+    return v ? url + '?v=' + v : url;
+  };
+</script>
+
 <!-- Load order matters: the registry and its dependencies must exist before
      bridge-mount runs. bridge-mount is a module (it imports the cumulus
      BridgeClient), so it is deferred automatically. -->
@@ -105,6 +119,7 @@
 <script src="/agent/device-thread.js"></script>
 <script src="/agent/commands.js"></script>
 <script src="/agent/chat-client.js"></script>
+<script src="/agent/blex-mount.js"></script>
 <script src="/agent/panel.js"></script>
 <script type="module" src="/agent/bridge-mount.js"></script>
 </body>

package/examples/web-app-agent/server.js

@@ -101,6 +101,114 @@ function resolveBridgeDir() {
 }
 const BRIDGE_DIR = resolveBridgeDir();
 
+/* ---- where the browser's blex renderer comes from -------------------------
+   Same rule as the bridge client above, and for a sharper reason than symmetry.
+   The obvious alternative — point a <script> at GATEWAY_ORIGIN + '/blex.min.js'
+   — is only correct for an app on a DIFFERENT origin from the gateway. The
+   common production shape is the opposite: GATEWAY_ORIGIN is your own hostname
+   and an edge (Caddy/Cloudflare) routes just `/bridge*` and `/api/thread/*` to
+   the gateway. There is no `/blex.min.js` on your hostname, so the cross-origin
+   recipe 404s and blex silently degrades to plain text — a failure that reads
+   like "my route is broken" rather than "my asset is missing". Serving the
+   assets ourselves is origin-agnostic and still not a vendored copy.
+   (Measured by @cdda, which hit exactly this.) */
+function resolveStaticDir() {
+  const inRepo = path.join(ROOT, '..', '..', 'dist', 'gateway', 'static');
+  if (fs.existsSync(path.join(inRepo, 'blex-render.js'))) return inRepo;
+  try {
+    const require = createRequire(import.meta.url);
+    return path.dirname(require.resolve('@luckydraw/cumulus/dist/gateway/static/blex-render.js'));
+  } catch {
+    return null;
+  }
+}
+const STATIC_DIR = resolveStaticDir();
+
+/* ---- asset versioning -----------------------------------------------------
+   Without this, a CDN in front of your app decides how long your agent surface
+   stays stale. Measured at a real Cloudflare edge: it overrides an origin's
+   `no-cache` with `max-age=14400`, so an edit to commands.js — the file you
+   change most — can take four hours to reach a browser, and the panel's files
+   expire on independent clocks, so a visitor can hold two files from DIFFERENT
+   deploys. `?v=<content hash>` makes the URL change when the bytes change,
+   which no cache policy can override.
+
+   Computed at SERVE time, not build time: this kit has no build step, and its
+   blex/bridge assets come out of the installed cumulus package, so a build-time
+   hash would describe the wrong bytes after `npm i`. */
+const assetStampCache = new Map();
+
+/** First 8 hex of sha1, cached and invalidated on mtime+size — so an edit is
+    picked up with no restart. undefined if the file cannot be read. */
+function assetVersion(file) {
+  if (!file) return undefined;
+  try {
+    const stat = fs.statSync(file);
+    const hit = assetStampCache.get(file);
+    if (hit && hit.mtimeMs === stat.mtimeMs && hit.size === stat.size) return hit.hash;
+    const hash = crypto.createHash('sha1').update(fs.readFileSync(file)).digest('hex').slice(0, 8);
+    assetStampCache.set(file, { hash, mtimeMs: stat.mtimeMs, size: stat.size });
+    return hash;
+  } catch {
+    return undefined;
+  }
+}
+
+/** URL path -> file on disk, or null if it is not an asset we serve. ONE owner
+    for this mapping: the routes below and the stamp both go through it, so a
+    URL can never be versioned as one file and served as another. The basename
+    allowlists are the whole traversal defence for the two directories outside
+    PUBLIC — do not loosen them to a prefix match. */
+function assetUrlToFile(pathname) {
+  if (pathname.startsWith('/agent/bridge-client/')) {
+    const name = path.basename(pathname);
+    if (!BRIDGE_DIR || !/^(client|protocol)\.js$/.test(name)) return null;
+    return path.join(BRIDGE_DIR, name);
+  }
+  // blex-chart.min.js is an OPT-IN companion global (blex.min.js inlines Chart.js
+  // and never fetches it). Nothing requests it today; it is allowlisted so an
+  // adopter who wants it can add one script tag instead of editing this server.
+  if (pathname.startsWith('/agent/blex/')) {
+    const name = path.basename(pathname);
+    if (!STATIC_DIR || !/^(blex\.min|blex-render|blex-chart\.min)\.js$/.test(name)) return null;
+    return path.join(STATIC_DIR, name);
+  }
+  const rel = pathname === '/' ? 'index.html' : pathname.replace(/^\/+/, '');
+  const file = path.join(PUBLIC, rel);
+  return file === PUBLIC || file.startsWith(PUBLIC + path.sep) ? file : null;
+}
+
+/* Assets loaded from INSIDE JavaScript — a <link> built at runtime, a script
+   element appended by blex-mount. An HTML-level stamp cannot see a URL that
+   only exists in JS, so these get their hashes through the map below instead.
+   (This is the "a loader that fetches its own dependencies must propagate the
+   version token" case, applied where it is actually true.) */
+const RUNTIME_LOADED = [
+  '/agent/panel.css',
+  '/agent/blex/blex.min.js',
+  '/agent/blex/blex-render.js',
+];
+
+const ASSET_MAP_MARKER = 'window.__AGENT_ASSET_V = {};';
+
+/** Stamp served HTML: `?v=` on every same-origin .js/.css src/href, plus the
+    version map for the runtime-loaded set. */
+function stampHtml(html) {
+  const stamped = html.replace(
+    /(\s(?:src|href)=")(\/[^"?#]+\.(?:js|css))(")/g,
+    (m, pre, url, post) => {
+      const v = assetVersion(assetUrlToFile(url));
+      return v ? `${pre}${url}?v=${v}${post}` : m;
+    }
+  );
+  const map = {};
+  for (const url of RUNTIME_LOADED) {
+    const v = assetVersion(assetUrlToFile(url));
+    if (v) map[url] = v;
+  }
+  return stamped.replace(ASSET_MAP_MARKER, `window.__AGENT_ASSET_V = ${JSON.stringify(map)};`);
+}
+
 /* ---- sessions (in-memory; your app has real ones) ------------------------ */
 const sessions = new Set();
 
@@ -141,14 +249,27 @@ function readBody(req) {
   });
 }
 
-function sendFile(res, file) {
+function sendFile(res, file, requestedVersion) {
   fs.readFile(file, (err, buf) => {
     if (err) {
       res.writeHead(404);
       return res.end('not found');
     }
-    res.writeHead(200, { 'content-type': MIME[path.extname(file)] || 'application/octet-stream' });
-    res.end(buf);
+    const ext = path.extname(file);
+    const body = ext === '.html' ? Buffer.from(stampHtml(buf.toString('utf8')), 'utf8') : buf;
+    // A ?v= that matches the CURRENT hash is content-addressed, so it is safe to
+    // cache forever. A stale or forged one must NOT be — that would pin today's
+    // bytes under a key that no longer describes them. HTML is never immutable:
+    // it is what carries the stamps.
+    const contentAddressed =
+      ext !== '.html' && requestedVersion !== undefined && requestedVersion === assetVersion(file);
+    res.writeHead(200, {
+      'content-type': MIME[ext] || 'application/octet-stream',
+      'cache-control': contentAddressed
+        ? 'public, max-age=31536000, immutable'
+        : 'no-cache, must-revalidate',
+    });
+    res.end(body);
   });
 }
 
@@ -205,24 +326,38 @@ const server = http.createServer(async (req, res) => {
     });
   }
 
+  // Static assets. assetUrlToFile owns the URL -> disk mapping (and the
+  // allowlists for the two directories outside PUBLIC); the routes below only
+  // pick the right 404 message when it declines.
+  const version = url.searchParams.get('v') ?? undefined;
+
   // Bridge client, served from the cumulus package rather than a local copy.
   if (p.startsWith('/agent/bridge-client/')) {
-    const name = path.basename(p);
-    if (!BRIDGE_DIR || !/^(client|protocol)\.js$/.test(name)) {
+    const file = assetUrlToFile(p);
+    if (!file) {
       res.writeHead(404);
       return res.end('bridge client unavailable — build cumulus or npm i @luckydraw/cumulus');
     }
-    return sendFile(res, path.join(BRIDGE_DIR, name));
+    return sendFile(res, file, version);
+  }
+
+  // Blex renderer + library, likewise served from the package.
+  if (p.startsWith('/agent/blex/')) {
+    const file = assetUrlToFile(p);
+    if (!file) {
+      res.writeHead(404);
+      return res.end('blex unavailable — build cumulus or npm i @luckydraw/cumulus');
+    }
+    return sendFile(res, file, version);
   }
 
   if (req.method === 'GET') {
-    const rel = p === '/' ? 'index.html' : p.replace(/^\/+/, '');
-    const file = path.join(PUBLIC, rel);
-    if (!file.startsWith(PUBLIC)) {
+    const file = assetUrlToFile(p);
+    if (!file) {
       res.writeHead(403);
       return res.end('forbidden');
     }
-    return sendFile(res, file);
+    return sendFile(res, file, version);
   }
 
   res.writeHead(404);
@@ -230,7 +365,9 @@ const server = http.createServer(async (req, res) => {
 });
 
 server.listen(PORT, '127.0.0.1', () => {
-  console.log(`demo app: http://127.0.0.1:${PORT}  (password: ${PASSWORD})`);
+  // The bound port, not the requested one — PORT=0 means "pick one for me".
+  const bound = server.address().port;
+  console.log(`demo app: http://127.0.0.1:${bound}  (password: ${PASSWORD})`);
   console.log(
     `bridge client: ${BRIDGE_DIR ?? 'NOT FOUND — run `npm run build` in the cumulus repo'}`
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@luckydraw/cumulus",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "RLM-based CLI chat wrapper for Claude with external history context management",
   "type": "module",
   "main": "dist/index.js",