@motujs/cli 0.0.0-stage → 0.1.1

package/src/lib/live-url.mjs

@@ -0,0 +1,53 @@
+// WHERE A PERSON CAN LOOK AT THIS RIGHT NOW.
+//
+// One file, written by a running dev server and read by every check's verdict line. It exists because
+// a green report describes FILES, while the thing the work is for is a rendered region — and across a
+// whole bench run no agent ever handed one over: each finished on a passing check, and the person who
+// asked for the work had nothing to open.
+//
+// ONE MODULE FOR THE PATH, and that is not tidiness. The first version spelled the directory two ways
+// (`paths.cacheDir`, which does not exist, against the config's `cacheDir`, which does), so the writer
+// silently wrote nothing and the reader silently found nothing — while the dev server printed a
+// perfectly correct "live at:" line. Both halves agreed, both were wrong, and nothing said so.
+import { mkdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { loadMotuConfig } from './config.mjs';
+
+/** The dev server rewrites this every heartbeat; two beats of silence means the process is gone. */
+const STALE_MS = 90_000;
+
+function file() {
+  return resolve(loadMotuConfig().cacheDir, 'lagoon-live.url');
+}
+
+/**
+ * Record the member URL a dev server is currently serving.
+ *
+ * Rewritten on EVERY heartbeat rather than once, so the file's own mtime carries how long ago this
+ * was true. A URL left behind by a killed dev server is worse than no URL at all: it sends whoever
+ * reads it to a page that no longer exists, and it reads exactly like a working one.
+ */
+export function writeLiveUrl(url) {
+  const f = file();
+  mkdirSync(resolve(f, '..'), { recursive: true });
+  writeFileSync(f, `${url}\n`);
+}
+
+export function clearLiveUrl() {
+  try {
+    rmSync(file(), { force: true });
+  } catch {
+    /* nothing to clean up */
+  }
+}
+
+/** The live member URL, or null when there is none or the last heartbeat is too old to believe. */
+export function readLiveUrl() {
+  try {
+    const f = file();
+    if (Date.now() - statSync(f).mtimeMs >= STALE_MS) return null;
+    return readFileSync(f, 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}

package/src/lib/node-aliases.mjs

@@ -0,0 +1,73 @@
+// The lagoon's alias list, serialised for the node loader (RegExp does not survive JSON).
+import { buildLagoonViteConfig, loadLagoonJson } from './lagoon-vite.mjs';
+import { createRequire } from 'node:module';
+import { resolve } from 'node:path';
+import { loadMotuConfig } from './config.mjs';
+
+/**
+ * The browser env the lagoon declares, for the node harness.
+ *
+ * `lagoon.config.json`'s `env` is what the app's modules read at import time — acme's Supabase client
+ * throws without it. Vite hands it to the browser through `define`; nothing handed it to node, so an
+ * island whose graph touches that client died on a missing variable rather than on anything about the
+ * island. One declaration, both paths.
+ */
+export function lagoonEnv() {
+  try {
+    return { ...(loadLagoonJson(loadMotuConfig()).env ?? {}) };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * ONE React, resolved from the project — node's answer to Vite's `dedupe: ['react', 'react-dom']`.
+ *
+ * The framework's packages resolve their own copy and the project resolves its own, so a component
+ * that calls a hook meets a null dispatcher. It is the failure that made `--fast` unusable for any
+ * island with state, and it is not the island's fault: the same island mounts fine in the browser,
+ * where vite dedupes. Pointing both at the project's copy is the same fix in the other module system.
+ */
+function reactDedupe(root) {
+  const out = [];
+  try {
+    const require = createRequire(resolve(root, 'package.json'));
+    for (const [specifier, pattern] of [
+      ['react', '^react$'],
+      ['react/jsx-runtime', '^react/jsx-runtime$'],
+      ['react/jsx-dev-runtime', '^react/jsx-dev-runtime$'],
+      ['react-dom', '^react-dom$'],
+      ['react-dom/client', '^react-dom/client$'],
+    ]) {
+      try {
+        out.push({ source: pattern, flags: '', replacement: require.resolve(specifier) });
+      } catch {
+        // Not installed here — nothing to dedupe to, and inventing a path would be worse.
+      }
+    }
+  } catch {
+    /* no package.json to resolve from */
+  }
+  return out;
+}
+
+export async function nodeAliasEnv() {
+  try {
+    const cfg = loadMotuConfig();
+    const vite = await buildLagoonViteConfig(cfg, process.env);
+    const alias = vite?.resolve?.alias ?? [];
+    // The project's React wins, and it is listed FIRST so nothing else can claim the specifier.
+    return JSON.stringify(
+      [...reactDedupe(cfg.hostRoot), ...reactDedupe(cfg.root)].concat(
+      alias
+        .filter((a) => typeof a?.replacement === 'string')
+        .map((a) =>
+          a.find instanceof RegExp
+            ? { source: a.find.source, flags: a.find.flags, replacement: a.replacement }
+            : { find: String(a.find), replacement: a.replacement },
+        )),
+    );
+  } catch {
+    return '[]';
+  }
+}

package/src/lib/operations.mjs

@@ -0,0 +1,145 @@
+// The BACKEND'S OWN LIST OF OPERATIONS, and how a region's ask resolves to one of them.
+//
+// motu records what a region asked for (`recordOutbound`, `@motujs/core`) and has never been able to
+// say whether the thing it asked for EXISTS. It cannot know on its own: an operation is a fact about
+// the backend, and motu has no view of one. So the list is read from a file the project already
+// maintains, and this module is everything motu knows about it.
+//
+// ## Opaque, on purpose
+//
+// A name and nothing else. The file this is pointed at in practice is assay's
+// `.assay/operations.json`, which also declares the tables each operation reads and writes, whether
+// it runs with RLS bypassed, and prohibitions on how it may be keyed — and none of that is read
+// here, because the moment motu interprets a declaration's CONTENTS it has married one backend tool.
+// A list of names is a shape an OpenAPI document, a tRPC router or a hand-written array can also
+// produce, and every one of them can fill this slot.
+//
+// ## Two kinds of name, because two doors carry an identifier
+//
+// The wire door records `route:<METHOD> <path>` and `fn:<name>` (`reachEntry()` in
+// `@motujs/runtime/postgrest-fetch`). Those are the only asks that can name an operation at all — a
+// contract call is `service.method` and a traced host module is a bare function name, neither of
+// which says which backend thing answered. This module resolves the two that can, and says nothing
+// about the two that cannot.
+
+/** A universe entry that looks like a Next route handler file. */
+const ROUTE_FILE = /(^|\/)route\.(ts|tsx|js|mjs)$/;
+
+/**
+ * The operation names out of whatever the project pointed us at.
+ *
+ * Two accepted shapes and no more: an object whose KEYS are the names (assay's file, whose values
+ * this deliberately ignores), or a plain array of names. Anything else returns an error rather than
+ * an empty list — a universe that parsed to nothing would make every ask unreachable, which is a
+ * wall of red that says the opposite of what happened.
+ */
+export function readOperationNames(text) {
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    return { names: [], error: `is not valid JSON (${String(err.message).split('\n')[0]})` };
+  }
+  if (Array.isArray(parsed)) return { names: parsed.filter((n) => typeof n === 'string') };
+  if (parsed && typeof parsed === 'object') {
+    const source = parsed.operations && typeof parsed.operations === 'object' ? parsed.operations : parsed;
+    const names = Object.keys(source).filter((k) => k !== 'version');
+    return { names };
+  }
+  return { names: [], error: 'is neither an object of operation names nor an array of them' };
+}
+
+/**
+ * A universe split into the two things an ask can name.
+ *
+ * Routes are indexed by SEGMENTS rather than compared as strings, because a route file is a PATTERN
+ * and a request is an instance of it: `app/api/admin/email-previews/[id]/route.ts` answers
+ * `/api/admin/email-previews/9f3c`, and a string compare would report that real, declared,
+ * successfully-answered ask as naming an operation nobody declares.
+ */
+export function indexOperations(names) {
+  const routes = [];
+  const fns = new Set();
+  for (const name of names) {
+    if (ROUTE_FILE.test(name)) routes.push({ name, segments: routeSegments(name) });
+    else fns.add(name);
+  }
+  return { names, routes, fns };
+}
+
+/**
+ * The URL segments a route FILE answers.
+ *
+ * Drops the `app/` (or `src/app/`) prefix and the trailing `route.ts`, and drops route GROUPS —
+ * `app/(dashboard)/api/x/route.ts` answers `/api/x`, because a parenthesised segment organises files
+ * and never appears in a URL. Getting that wrong would silently fail to match a whole directory's
+ * worth of real operations.
+ */
+function routeSegments(name) {
+  return String(name)
+    .replace(/^src\//, '')
+    .replace(/^app\//, '')
+    .replace(ROUTE_FILE, '')
+    .split('/')
+    .filter((s) => s && !/^\(.*\)$/.test(s));
+}
+
+/** The path segments an ask actually requested. */
+function askSegments(path) {
+  return String(path).split('?')[0].split('#')[0].split('/').filter(Boolean);
+}
+
+/**
+ * Does a route file's segment pattern answer this request's segments?
+ *
+ * `[id]` matches exactly one segment; `[...slug]` and `[[...slug]]` match one or more (and the
+ * optional form matches none), which is what a catch-all route does.
+ */
+function segmentsMatch(pattern, actual) {
+  let p = 0;
+  let a = 0;
+  while (p < pattern.length) {
+    const seg = pattern[p];
+    const catchAll = /^\[\[?\.\.\..*\]\]?$/.test(seg);
+    if (catchAll) {
+      // A catch-all is last by construction, so it takes whatever is left. The optional form
+      // `[[...x]]` is allowed to take nothing.
+      const optional = seg.startsWith('[[');
+      return optional ? true : a < actual.length;
+    }
+    if (a >= actual.length) return false;
+    if (!/^\[.*\]$/.test(seg) && seg !== actual[a]) return false;
+    p += 1;
+    a += 1;
+  }
+  return a === actual.length;
+}
+
+/** 'route' | 'fn' for an ask that can name an operation, null for one that cannot. */
+export function askKind(canonical) {
+  const s = String(canonical);
+  if (s.startsWith('route:')) return 'route';
+  if (s.startsWith('fn:')) return 'fn';
+  return null;
+}
+
+/**
+ * The operation a canonical wire entry names, or null when the universe has no such operation.
+ *
+ * Takes the canonical form the runtime records and `reaches`/`effects` declare — the same vocabulary
+ * on both sides, which is the point of `lib/effects.mjs`.
+ */
+export function resolveOperation(canonical, index) {
+  const s = String(canonical);
+  if (s.startsWith('fn:')) {
+    const name = s.slice(3);
+    return index.fns.has(name) ? name : null;
+  }
+  if (!s.startsWith('route:')) return null;
+  // `route:GET /api/x` and `route:/api/x` — the method is not part of the identity here. A route file
+  // exports every verb it answers, so METHOD does not select between operations; assay keys the file.
+  const path = s.slice(6).replace(/^\S+\s+/, '');
+  const actual = askSegments(path);
+  const hit = index.routes.find((r) => segmentsMatch(r.segments, actual));
+  return hit ? hit.name : null;
+}

package/src/lib/provenance-plugin.mjs

@@ -0,0 +1,74 @@
+// PROVENANCE, WITHOUT ANYONE HAVING TO ASK FOR IT.
+//
+// Every entry in lagoon.config.json's "alias" is a host module the lagoon stands DOWN — which is
+// exactly the statement that it is a boundary this screen's data comes across. So each one is loaded
+// through a wrapper that records the calls islands make into it, and the seam lens can say where a
+// rendered row came from.
+//
+// This was per-export (`traced(...)` by hand in the stub) and that is the wrong shape for a fact
+// about the boundary rather than about the function: acme's club stub had opted in, so the club region
+// showed its two fetches while the actions and directory regions — whose stubs nobody had wrapped —
+// reported "traced export(s), none called", which reads as "these islands fetched nothing" and is a
+// different claim entirely. A stub added tomorrow is traced the day it lands.
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const PREFIX = '\0motu-traced:';
+
+/**
+ * The names a module exports at runtime, by reading its source.
+ *
+ * Deliberately regex and deliberately allowed to miss: the wrapper below re-exports the real module
+ * with `export *` FIRST, and ESM lets an explicit export shadow a star. A name missed here is still
+ * exported — unwrapped and unrecorded — rather than missing, so the worst case is a gap in the lens
+ * and never a build that fails on an import.
+ */
+function exportedNames(code) {
+  const out = new Set();
+  for (const m of code.matchAll(/^\s*export\s+(?:async\s+)?(?:function|const|let|var|class)\s+([A-Za-z_$][\w$]*)/gm)) out.add(m[1]);
+  for (const m of code.matchAll(/^\s*export\s*\{([^}]*)\}(?!\s*from)/gm))
+    for (const part of m[1].split(',')) out.add((part.split(/\bas\b/).pop() ?? '').trim());
+  // `export type` / `export interface` are erased before this runs anywhere it matters, and the
+  // patterns above do not match them.
+  return [...out].filter((n) => n && n !== 'default');
+}
+
+/** Wrap every aliased host module so its calls are recorded. Debug builds only. */
+export function motuProvenance(alias, lagoonDir) {
+  // BY RESOLVED FILE, NOT BY SPECIFIER. Vite's own alias plugin runs BEFORE user `pre` plugins, so a
+  // `resolveId` matching '@/lib/services/directory' is never called with it — the specifier is already
+  // the stub's path by then. This cost a whole build to find, because the one region that did record
+  // was the one whose stub had been wrapped by hand: the plugin looked like it worked.
+  const stubs = new Map();
+  for (const [spec, rel] of Object.entries(alias ?? {})) stubs.set(resolve(lagoonDir, rel), spec);
+  return {
+    name: 'motu:provenance',
+    enforce: 'pre',
+    resolveId(source, importer) {
+      // The wrapper's own `import … from '<the stub>'` must reach the real file, or this recurses.
+      if (importer?.startsWith(PREFIX)) return null;
+      if (source.startsWith(PREFIX)) return source;
+      return stubs.has(source) ? PREFIX + source : null;
+    },
+    load(id) {
+      if (!id.startsWith(PREFIX)) return null;
+      const file = id.slice(PREFIX.length);
+      const spec = stubs.get(file);
+      let code = '';
+      try {
+        code = readFileSync(file, 'utf8');
+      } catch {
+        return null; // unreadable: let the normal path take it and fail where it usually would
+      }
+      const path = JSON.stringify(file);
+      return [
+        `import * as __impl from ${path};`,
+        `import { traceModule } from '@motujs/core';`,
+        `export * from ${path};`,
+        `const __traced = traceModule(${JSON.stringify(spec)}, __impl);`,
+        ...exportedNames(code).map((n) => `export const ${n} = __traced[${JSON.stringify(n)}];`),
+        /(^|\n)\s*export\s+default\b/.test(code) ? 'export default __impl.default;' : '',
+      ].join('\n');
+    },
+  };
+}

package/src/lib/region-refs.mjs

@@ -0,0 +1,40 @@
+// REGIONS INSIDE REGIONS — `slots: { prop: { region: '<id>' } }`, read from every archipelago on disk.
+//
+// The graph is the project's, not one region's: whether `base → equipage` is a cycle depends on what
+// `equipage` references, so a single file cannot answer it. The verdict on the graph is
+// `regionRefProblems` from @motujs/core — the same function the lagoon uses to refuse a placeholder — so
+// the check and the preview cannot disagree about which references are broken.
+import { regionRefProblems } from '@motujs/core';
+import { readRegions } from './eject.mjs';
+import { regionRefsDeclared } from './lagoon-declares.mjs';
+
+/**
+ * `{ graph, unreadable }` — every archipelago's root-ness and references, and the ids whose file did
+ * not parse (their references are unknown, which is not the same as none).
+ */
+export function regionRefGraphOnDisk(archipelagosDir) {
+  const graph = {};
+  const unreadable = [];
+  for (const region of readRegions(archipelagosDir)) {
+    const refs = regionRefsDeclared(region.file);
+    if (refs === null) unreadable.push(region.id);
+    graph[region.id] = { root: Boolean(region.root), refs: refs ?? {} };
+  }
+  return { graph, unreadable };
+}
+
+/**
+ * What one region's references look like from the whole graph: the props it fills with another
+ * region, what is wrong with them, and who fills a slot with IT.
+ */
+export function regionRefsOf(id, archipelagosDir) {
+  const { graph, unreadable } = regionRefGraphOnDisk(archipelagosDir);
+  const refs = graph[id]?.refs ?? {};
+  const problems = regionRefProblems(graph).filter((p) => p.region === id);
+  const referencedBy = Object.entries(graph).filter(([other]) => other !== id).flatMap(([other, node]) =>
+    Object.entries(node.refs)
+      .filter(([, ref]) => ref === id)
+      .map(([prop]) => `${other}.${prop}`),
+  );
+  return { refs, problems, referencedBy, unreadable: unreadable.includes(id) };
+}

package/src/lib/remote.mjs

@@ -0,0 +1,171 @@
+// Publishing a lagoon to a host instead of to a file.
+//
+// Two shapes. `uploadManifest` is the default: the lagoon as content-addressed chunks plus a manifest,
+// so a republish sends only what changed (lib/lagoon-bundle.mjs). `uploadLagoon` is the one-file shape
+// (`--single`): the same self-contained fragment `publish` writes for an Artifact, POSTed as is.
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, resolve } from 'node:path';
+import { createHash } from 'node:crypto';
+import { gzipSync } from 'node:zlib';
+import { sendMissingChunks, MANIFEST_TYPE } from './lagoon-bundle.mjs';
+
+/**
+ * ONE host for every agent on this machine.
+ *
+ * The point of a long-running host is that nobody has to be told where it is: an agent runs
+ * `motu lagoon publish --remote` with no argument, in whatever project it happens to be working on,
+ * and lands in the same place as every other agent. So the URL and token have a well-known home,
+ * and the flag and the environment variable stay available to override it.
+ *
+ * Precedence: an explicit flag, then $MOTU_HOST_URL / $MOTU_HOST_TOKEN, then this file.
+ */
+export function loadHostConfig() {
+  const file = resolve(process.env.MOTU_CONFIG_HOME || resolve(homedir(), '.config/motu'), 'host.json');
+  if (!existsSync(file)) return {};
+  try {
+    const cfg = JSON.parse(readFileSync(file, 'utf8'));
+    return { url: typeof cfg.url === 'string' ? cfg.url : undefined, token: typeof cfg.token === 'string' ? cfg.token : undefined, file };
+  } catch {
+    // A malformed file must not stop a publish that also has a flag or an env var.
+    return {};
+  }
+}
+
+/** Run git, quietly. Absence of git, or of a repo, is a normal case here — not an error. */
+function git(cwd, args) {
+  const res = spawnSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+  return res.status === 0 ? res.stdout.trim() : null;
+}
+
+/** Trim a host-safe segment out of a git ref or a directory name. */
+function segment(raw, max = 64) {
+  const s = String(raw ?? '')
+    .replace(/[^A-Za-z0-9._-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, max);
+  return /^[A-Za-z0-9]/.test(s) ? s : null;
+}
+
+/**
+ * WHO IS PUBLISHING? With no accounts yet, the repo id has to come from the repo itself, and the git
+ * remote is the only name that is stable across machines and clones — a directory name is whatever
+ * someone typed when they cloned. Falls back to the directory when there is no remote (or no git),
+ * because a project that has not been pushed anywhere must still be publishable.
+ */
+export function gitIdentity(cwd) {
+  const origin = git(cwd, ['remote', 'get-url', 'origin']);
+  let repo = null;
+  if (origin) {
+    // Both spellings of a remote: git@host:owner/name.git and https://host/owner/name.git
+    const m = origin.replace(/\.git$/, '').match(/[:/]([^/:]+)\/([^/]+)$/);
+    if (m) {
+      const owner = segment(m[1]);
+      const name = segment(m[2]);
+      if (owner && name) repo = `${owner}/${name}`;
+    }
+  }
+  if (!repo) repo = segment(basename(cwd));
+
+  const sha = git(cwd, ['rev-parse', 'HEAD']);
+  const branchRaw = git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']);
+  const dirty = git(cwd, ['status', '--porcelain']);
+  return {
+    repo,
+    // A dirty tree's HEAD sha would be a LIE about what those bytes are: the immutable URL would name
+    // a commit that does not contain what you are looking at. Let the host fall back to the content
+    // hash instead — it is always true, and it is what content addressing is for.
+    sha: sha && !dirty ? sha.slice(0, 12) : null,
+    branch: branchRaw && branchRaw !== 'HEAD' ? segment(branchRaw) : null,
+    dirty: !!dirty,
+  };
+}
+
+/** POST the fragment. Gzipped: ~430 kB of inlined bundle goes over the wire at roughly a quarter. */
+export async function uploadLagoon({ url, token, repo, slug, title, sha, branch, brand, body }) {
+  const base = String(url).replace(/\/+$/, '');
+  const qs = new URLSearchParams({ repo, slug, title });
+  if (sha) qs.set('sha', sha);
+  if (branch) qs.set('branch', branch);
+  // The project's own colour, so tools that list repositories can be the right one. Kept off the
+  // record and on the repo by the host: it describes the project, not this build.
+  if (brand) qs.set('brand', brand);
+
+  const gz = gzipSync(Buffer.from(body, 'utf8'));
+  const res = await fetch(`${base}/api/publish?${qs}`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'text/html; charset=utf-8',
+      'content-encoding': 'gzip',
+      ...(token ? { authorization: `Bearer ${token}` } : {}),
+    },
+    body: gz,
+  });
+
+  const text = await res.text();
+  let payload = null;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    /* a non-JSON body means a proxy answered, not the host — report it verbatim below */
+  }
+  if (!res.ok) {
+    const detail = payload?.error ?? text.slice(0, 200).replace(/\s+/g, ' ').trim();
+    throw new Error(`host refused the upload (${res.status}): ${detail || 'no detail'}`);
+  }
+
+  // DID IT STORE WHAT WE SENT? A 200 with a URL in it is not an answer to that question, and for a
+  // while it was the only one we had: the CLI printed the host's URLs as fact and never checked one.
+  // When a publish then looked wrong, there was nothing to distinguish "the host mis-stored it" from
+  // "you are looking at the wrong thing" — which cost an afternoon of diagnosing a host bug that did
+  // not exist.
+  //
+  // Hashing costs nothing over the wire, which is why it is the check rather than fetching the page
+  // back: both sides hold the bytes, so both can name them. A host that returns no hash is older than
+  // this and is simply unverified — say that, never silently pass.
+  const sentHash = createHash('sha256').update(body, 'utf8').digest('hex');
+  const verified = payload?.hash ? payload.hash === sentHash : null;
+  if (verified === false) {
+    throw new Error(
+      `host stored different bytes than were sent (sent ${sentHash.slice(0, 12)}, host has ${String(payload.hash).slice(0, 12)}) — ` +
+      `the URLs it returned would show someone else's build`,
+    );
+  }
+
+  return { ...payload, base, sentBytes: gz.length, verified };
+}
+
+/**
+ * Publish a CHUNKED lagoon: the chunks the host lacks, then the manifest as the record.
+ *
+ * Verified the same way the single file is: the host names the content it stored, and that must be
+ * the manifest's own hash — which pins every chunk, because the manifest names each one by its hash.
+ */
+export async function uploadManifest({ url, token, repo, slug, title, sha, branch, brand, bundle, manifest }) {
+  const base = String(url).replace(/\/+$/, '');
+  const chunks = await sendMissingChunks({ base, token, files: bundle.files, hashes: manifest.hashes });
+  const qs = new URLSearchParams({ repo, slug, title });
+  if (sha) qs.set('sha', sha);
+  if (branch) qs.set('branch', branch);
+  if (brand) qs.set('brand', brand);
+  const gz = gzipSync(Buffer.from(manifest.json, 'utf8'));
+  const res = await fetch(`${base}/api/publish?${qs}`, {
+    method: 'POST',
+    headers: { 'content-type': MANIFEST_TYPE, 'content-encoding': 'gzip', ...(token ? { authorization: `Bearer ${token}` } : {}) },
+    body: gz,
+  });
+  const text = await res.text();
+  let payload = null;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    /* reported below */
+  }
+  if (!res.ok) throw new Error(`host refused the manifest (${res.status}): ${payload?.error ?? text.slice(0, 200)}`);
+  const verified = payload?.hash ? payload.hash === manifest.hash : null;
+  if (verified === false) {
+    throw new Error(`host stored a different manifest than was sent (sent ${manifest.hash.slice(0, 12)}, host has ${String(payload.hash).slice(0, 12)})`);
+  }
+  return { ...payload, base, chunks, sentBytes: chunks.sentBytes + gz.length, verified };
+}