@motujs/cli 0.0.0-stage → 0.1.1

package/src/lib/islands.mjs

@@ -0,0 +1,112 @@
+// Island discovery + the generated element registry.
+//
+// Two layouts are supported on purpose (C1: the verbose form stays reachable):
+//   FLAT    src/islands/<kebab>.island.ts      — exports `element`; evidence in <kebab>.evidence.ts
+//   FOLDER  src/islands/<kebab>/element.ts     — the original; the reference ocean still uses it
+//
+// The registry is GENERATED rather than hand-maintained. It cannot be a glob: the barrel that exports
+// it is imported by the host application, and `import.meta.glob` is a Vite feature — Next's bundler
+// does not have it. Generating gives the same "adding an island is not an edit" property with static
+// imports that every bundler understands, and lets verify detect a registry that has drifted from the
+// files on disk.
+import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+/** Every island in the project, whichever layout it uses. */
+export function listIslands(islandsDir) {
+  if (!existsSync(islandsDir)) return [];
+  const out = [];
+  for (const e of readdirSync(islandsDir, { withFileTypes: true })) {
+    if (e.isDirectory()) {
+      if (existsSync(resolve(islandsDir, e.name, 'element.ts')))
+        out.push({ kebab: e.name, layout: 'folder', element: resolve(islandsDir, e.name, 'element.ts') });
+    } else if (e.name.endsWith('.island.ts') || e.name.endsWith('.island.tsx')) {
+      out.push({
+        kebab: e.name.replace(/\.island\.tsx?$/, ''),
+        layout: 'flat',
+        element: resolve(islandsDir, e.name),
+      });
+    }
+  }
+  return out.sort((a, b) => a.kebab.localeCompare(b.kebab));
+}
+
+/** The exported ElementSpec binding in an island's file (`element` in flat form, `<camel>Element` in folder form). */
+export function elementExportName(file) {
+  const m = readFileSync(file, 'utf8').match(/export const (\w+)\s*:\s*ElementSpec/);
+  return m?.[1] ?? 'element';
+}
+
+/** Render the registry from what is on disk. */
+/**
+ * COVERAGE IS NOT HERE ANY MORE, and its absence is the point.
+ *
+ * `configureCoverage({ enabled, regions })` used to be emitted into this file. Nothing about it is
+ * island-shaped — `regions: ["actions"]` names REGIONS — and it lived here only because the island
+ * registry was the one generated module an application is guaranteed to import at startup. That is a
+ * fact about which files happened to exist, not a reason, and it made the island registry responsible
+ * for something outside its own noun. See lib/archipelagos.mjs.
+ */
+export function renderRegistry(islands, islandsDir, isolation) {
+  // NO SILENT DEFAULT. Writing `'shadow'` when the caller passed nothing is how this generator put the
+  // wrong isolation into a project declaring `light` — the value was missing from the `paths` object,
+  // not from the config, and a fallback turned a plumbing bug into a wrong file nobody would question.
+  if (isolation !== 'light' && isolation !== 'shadow') {
+    throw new Error(
+      `motu: renderRegistry needs the project's isolation ('light' or 'shadow'), got ${JSON.stringify(isolation)}. ` +
+        `It comes from motu.config.json via \`paths.isolation\`.`,
+    );
+  }
+  const rows = islands.map((i) => {
+    const name = elementExportName(i.element);
+    // Extensionless. motu's packages declare `moduleResolution: "Bundler"`, and the registry this
+    // writes is compiled by the HOST's bundler — where a '.js' specifier pointing at a '.ts' file is
+    // a mapping each one has to be told about. webpack has `extensionAlias`; Turbopack has nothing,
+    // and an Angular build resolves it only from inside node_modules. Extensionless needs no mapping.
+    const spec = i.layout === 'flat' ? `./${i.kebab}.island` : `./${i.kebab}/element`;
+    // Local alias when the export name would collide across islands (folder form names them uniquely).
+    const local = name === 'element' ? `${i.kebab.replace(/-(\w)/g, (_, c) => c.toUpperCase())}Element` : name;
+    const text = readFileSync(i.element, 'utf8');
+    const tag = (text.match(/\btag:\s*'([^']+)'/) ?? text.match(/\bisland\(\s*'([^']+)'/))?.[1] ?? i.kebab;
+    return { import: `import { ${name}${local !== name ? ` as ${local}` : ''} } from '${spec}';`, local, tag };
+  });
+  return `// GENERATED by \`motu sync\` — do not edit by hand.
+//
+// Static imports, not a glob: this file is re-exported by the project barrel, which the host
+// application imports through its own bundler, and \`import.meta.glob\` is Vite-only.
+import type { ElementSpec } from '@motujs/react';
+import { setDefaultIsolation } from '@motujs/core';
+${rows.map((r) => r.import).join('\n')}
+
+// ISOLATION, from motu.config.json, applied by IMPORTING this file.
+//
+// The lagoon has always had it — its root is scaffolded with \`setDefaultIsolation(__MOTU_ISOLATION__)\`
+// — and a host application had no way to say it at all: \`registerElements\` takes css and a theme and
+// nothing else. So a project declaring \`light\` previewed in light DOM and SHIPPED in shadow, which
+// changes whether the host's own stylesheet reaches the island. Approving a baseline then means
+// approving something the page does not render.
+//
+// Set here rather than as an argument to \`registerElements\` so no host has to repeat the value and
+// no host can disagree with the config: importing the registry is already what a host does, and this
+// file is generated, so a stale copy is caught the same way every other drift in it is.
+setDefaultIsolation('${isolation}');
+export const ELEMENT_REGISTRY: ElementSpec[] = [${rows.map((r) => r.local).join(', ')}];
+
+/**
+ * Tag -> element spec, as a TYPE. Lets an archipelago check its wiring against the islands it names
+ * (\`RegionWiringOk\`) without importing them at runtime — the values above are the registry; this is
+ * the same information in a form the compiler can look up by tag.
+ */
+export interface ElementTypes {
+${rows.map((r) => `  '${r.tag}': typeof ${r.local};`).join('\n')}
+}
+`;
+}
+
+/** Write the registry for a project. Returns the path written. */
+export function syncRegistry(islandsDir, isolation) {
+  const islands = listIslands(islandsDir);
+  const out = resolve(islandsDir, 'registry.ts');
+  writeFileSync(out, renderRegistry(islands, islandsDir, isolation));
+  return { path: out, count: islands.length };
+}

package/src/lib/lagoon-bundle.mjs

@@ -0,0 +1,138 @@
+// A lagoon as CHUNKS: the page, the files it loads, and a manifest naming each file by its content.
+//
+// WHY. A lagoon used to travel as one self-contained file, so a one-line edit in one region re-sent
+// (and the host re-stored) the whole thing: every dependency, the framework, every other region. The
+// build now cuts stable chunks (`chunkOf` in lagoon-vite.mjs), and this module turns that output into
+// something a content-addressed host can take a piece at a time:
+//
+//   manifest  { motu: 'lagoon-manifest/1', html, files: { 'region-members.js': '<sha256>', … } }
+//
+// The host is asked which hashes it lacks, is sent only those, and then the manifest. An edit in one
+// region sends that region's chunk and the manifest; everything else is already there.
+//
+// THE PAGE DOES NOT KNOW WHERE ITS CHUNKS LIVE. Its references read `__MOTU_ASSETS__/<file>`, and
+// whoever serves the page fills that in: the host with `/__motu_assets/<manifest hash>`, the local
+// `lagoon serve` with its own. Chunks find each other relatively, so only the page needs filling.
+//
+// The self-contained single file still exists (`motu lagoon publish` without --remote, `--single`):
+// it is what an Artifact needs, and what opens from disk with nothing behind it.
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { gzipSync } from 'node:zlib';
+
+export const MANIFEST_FORMAT = 'lagoon-manifest/1';
+export const MANIFEST_TYPE = 'application/vnd.motu.lagoon+json';
+/** What the page says where a server must say where its chunks are. */
+export const ASSETS_PLACEHOLDER = '__MOTU_ASSETS__';
+
+export const sha256 = (buf) => createHash('sha256').update(buf).digest('hex');
+
+/**
+ * Read a CHUNKED build's output into `{ html, files }`.
+ *
+ * `html` is the fragment (no doctype/html/head/body, like the single-file artifact) with every
+ * `./assets/x` reference rewritten to the placeholder. `files` maps a flat name to its bytes.
+ */
+export function readChunkedBuild(htmlPath, title) {
+  const distDir = resolve(htmlPath, '..');
+  const assetsDir = resolve(distDir, 'assets');
+  let html = readFileSync(htmlPath, 'utf8');
+  html = html.replace(/(["'])\.?\/assets\//g, `$1${ASSETS_PLACEHOLDER}/`);
+  html = html
+    .replace(/<!doctype html>\s*/i, '')
+    .replace(/<\/?(?:html|head|body)\b[^>]*>\s*/gi, '')
+    .replace(/<title>[\s\S]*?<\/title>/i, `<title>${title}</title>`)
+    .trim() + '\n';
+  const files = new Map();
+  if (existsSync(assetsDir)) {
+    for (const name of readdirSync(assetsDir)) {
+      const file = resolve(assetsDir, name);
+      if (statSync(file).isFile()) files.set(name, readFileSync(file));
+    }
+  }
+  // THE SAME CHECK THE SINGLE FILE MAKES: a page still pointing at /assets/ is one whose chunks the
+  // server will not find, and it renders blank rather than failing.
+  const dangling = html.match(/["'(]\/assets\/[^"')]+/g);
+  if (dangling) throw new Error(`chunked page still references ${[...new Set(dangling)].join(', ')}`);
+  return { html, files };
+}
+
+/** The manifest for a page whose html has already been through whatever the caller injects. */
+export function manifestOf(html, files) {
+  const hashes = {};
+  for (const [name, bytes] of [...files].sort(([a], [b]) => (a < b ? -1 : 1))) hashes[name] = sha256(bytes);
+  const json = JSON.stringify({ motu: MANIFEST_FORMAT, html, files: hashes });
+  return { json, hash: sha256(Buffer.from(json, 'utf8')), hashes };
+}
+
+/** Fill the placeholder: where this server serves the chunks of the manifest it is serving. */
+export function placeAssets(html, base) {
+  return html.split(ASSETS_PLACEHOLDER).join(base.replace(/\/+$/, ''));
+}
+
+const TYPES = {
+  js: 'text/javascript; charset=utf-8',
+  mjs: 'text/javascript; charset=utf-8',
+  css: 'text/css; charset=utf-8',
+  json: 'application/json',
+  svg: 'image/svg+xml',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  avif: 'image/avif',
+  ico: 'image/x-icon',
+  woff: 'font/woff',
+  woff2: 'font/woff2',
+  ttf: 'font/ttf',
+  otf: 'font/otf',
+  wasm: 'application/wasm',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+};
+export const contentTypeOf = (name) => TYPES[String(name).split('.').pop().toLowerCase()] ?? 'application/octet-stream';
+
+/**
+ * Send a host the chunks it does not have yet. Returns what was sent and what was already there.
+ *
+ * Asked first, in one request, so an unchanged chunk costs one hash on the wire. A host older than
+ * this protocol answers 404 to the question, which is reported as such rather than as a failed upload.
+ */
+export async function sendMissingChunks({ base, token, files, hashes }) {
+  const auth = token ? { authorization: `Bearer ${token}` } : {};
+  const all = [...new Set(Object.values(hashes))];
+  const ask = await fetch(`${base}/api/blobs/missing`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', ...auth },
+    body: JSON.stringify({ hashes: all }),
+  });
+  if (ask.status === 404) {
+    throw Object.assign(new Error('this host stores single files only — update it, or publish with --single'), { oldHost: true });
+  }
+  if (!ask.ok) throw new Error(`host refused the chunk check (${ask.status}): ${(await ask.text()).slice(0, 200)}`);
+  const { missing = [] } = await ask.json();
+  const wanted = new Set(missing);
+  let sentBytes = 0;
+  let sent = 0;
+  const byHash = new Map();
+  for (const [name, h] of Object.entries(hashes)) if (!byHash.has(h)) byHash.set(h, files.get(name));
+  // A FEW AT ONCE: one request per chunk, but a cold upload is dozens of them.
+  const queue = [...wanted];
+  const worker = async () => {
+    for (let h = queue.shift(); h; h = queue.shift()) {
+      const gz = gzipSync(byHash.get(h));
+      const res = await fetch(`${base}/api/blobs/${h}`, {
+        method: 'PUT',
+        headers: { 'content-type': 'application/octet-stream', 'content-encoding': 'gzip', ...auth },
+        body: gz,
+      });
+      if (!res.ok) throw new Error(`host refused chunk ${h.slice(0, 12)} (${res.status}): ${(await res.text()).slice(0, 200)}`);
+      sentBytes += gz.length;
+      sent++;
+    }
+  };
+  await Promise.all(Array.from({ length: 6 }, worker));
+  return { sent, reused: all.length - sent, total: all.length, sentBytes };
+}