@xoong/cli 0.0.0-stage → 0.0.34

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Duong Tran Xuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @xoong/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The `xoong` command: turns an OpenAPI document into typed operations, lints your screens, runs the dev server and builds static output that runs under a strict Content-Security-Policy.
+
+## Install
+
+```bash
+npm install @xoong/cli
+```
+
+## Use
+
+```bash
+npx xoong sync openapi.json        # writes .xoong/operations.json and api.d.ts
+npx xoong check index.html         # lint screens against the API
+npx xoong dev                      # static server with an API proxy
+npx xoong build --out dist         # strict-CSP static output
+```
+
+## More
+
+* Documentation and demos: https://github.com/fpt-duongtx/xoong#readme
+* Source: https://github.com/fpt-duongtx/xoong/tree/main/packages/cli
+* All packages share one version number and are released together: https://github.com/fpt-duongtx/xoong/releases
+* xoong is a working prototype (0.0.x): the HTML syntax is still Draft.
+
+MIT licence.

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@xoong/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.34",
+  "description": "The xoong command line: sync (OpenAPI to typed operations), doctor, check (lint screens), dev, build (strict-CSP static output), render and i18n.",
+  "type": "module",
+  "bin": {
+    "xoong": "src/cli.js"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./check": "./src/check.js",
+    "./cli": "./src/cli.js",
+    "./build": "./src/build.js",
+    "./html-data": "./src/html-data.js"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "parse5": "^8.1.0",
+    "yaml": "^2.8.0",
+    "@xoong/server": "0.0.34",
+    "@xoong/core": "0.0.34",
+    "@xoong/i18n": "0.0.34"
+  },
+  "files": [
+    "src"
+  ],
+  "keywords": [
+    "xoong",
+    "web-framework",
+    "openapi",
+    "custom-elements"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "author": "Duong Tran Xuan <duongtx1505@icloud.com>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fpt-duongtx/xoong.git",
+    "directory": "packages/cli"
+  },
+  "bugs": {
+    "url": "https://github.com/fpt-duongtx/xoong/issues"
+  },
+  "homepage": "https://github.com/fpt-duongtx/xoong#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/body-schema.js

@@ -0,0 +1,161 @@
+// @ts-check
+/**
+ * OpenAPI request schema -> the compact node tree that forms use at runtime (`bodySchema` in operations.json; see
+ * packages/data/src/schema.js for the node shapes and docs/decisions/0009-forms-from-the-api-schema.md).
+ */
+
+const refName = (r) => r.slice(r.lastIndexOf('/') + 1);
+const PRIMITIVE = new Set(['string', 'integer', 'number', 'boolean']);
+const MAX_DEPTH = 10;
+/** Where a union of objects could not be told apart, collected by `bodySchemaOf(..., lost)`. */
+let lostUnions;
+
+/**
+ * @param {any} schema the request body schema (maybe a $ref)
+ * @param {Record<string, any>} schemas components.schemas
+ * @param {{ fields?: Record<string, { label?: string, hint?: string, placeholder?: string, widget?: string, order?: number, readOnly?: boolean }> }} [hints]
+ *   `fields`: presentation hints keyed "SchemaName.property" for specs that cannot be edited
+ * @returns {any | undefined} an object node, or undefined when the body is not an object
+ */
+export function bodySchemaOf(schema, schemas, hints, lost) {
+  lostUnions = lost;
+  const n = convert(schema, schemas, hints, 0, undefined);
+  lostUnions = undefined;
+  return n && n.t === 'object' ? n : undefined;
+}
+
+/** Follow $ref chains; returns the schema and the name of the last named schema met. */
+function deref(s, schemas, owner) {
+  let name = owner;
+  for (let i = 0; s?.$ref && i < 20; i++) { name = refName(s.$ref); s = schemas[name]; }
+  return { s, name };
+}
+
+/** allOf: the union of properties and required lists, other keywords from the parts and the schema itself. */
+function flatten(schema, schemas, owner, depth) {
+  const { s, name } = deref(schema, schemas, owner);
+  if (!s?.allOf) return { s, name };
+  const merged = { ...s, properties: { ...(s.properties ?? {}) }, required: [...(s.required ?? [])] };
+  delete merged.allOf;
+  for (const part of s.allOf) {
+    const f = depth < MAX_DEPTH ? flatten(part, schemas, name, depth + 1).s : undefined;
+    if (!f) continue;
+    for (const [k, v] of Object.entries(f)) if (k !== 'properties' && k !== 'required' && merged[k] === undefined) merged[k] = v;
+    merged.properties = { ...(f.properties ?? {}), ...merged.properties };
+    merged.required = [...new Set([...merged.required, ...(f.required ?? [])])];
+  }
+  return { s: merged, name };
+}
+
+function convert(schema, schemas, hints, depth, owner) {
+  if (depth > MAX_DEPTH) return { t: 'any' };
+  let { s, name } = flatten(schema, schemas, owner, depth);
+  if (!s || typeof s !== 'object') return { t: 'any' };
+
+  // oneOf / anyOf: [X, null] is a nullable X; several objects need a tag to be told apart
+  const alternatives = s.oneOf ?? s.anyOf;
+  if (alternatives) {
+    const real = alternatives.filter((a) => deref(a, schemas).s?.type !== 'null');
+    const nullable = real.length !== alternatives.length;
+    if (real.length === 1) return decorate({ ...convert(real[0], schemas, hints, depth + 1, name), ...(nullable ? { nullable: true } : {}) }, s);
+    const union = unionOf(s, real, schemas, hints, depth, name);
+    if (!union && real.some((m) => deref(m, schemas).s?.type === 'object' || deref(m, schemas).s?.properties)) lostUnions?.push(name ?? owner ?? 'the request body');
+    return union ? decorate({ ...union, ...(nullable ? { nullable: true } : {}) }, s) : { t: 'any' };
+  }
+
+  let type = s.type;
+  let nullable = s.nullable === true;
+  if (Array.isArray(type)) { nullable = type.includes('null'); type = type.find((t) => t !== 'null'); }
+  if (!type && s.const !== undefined) { type = typeof s.const === 'number' ? 'number' : typeof s.const === 'boolean' ? 'boolean' : 'string'; s = { ...s, enum: [s.const] }; }
+  if (!type) type = s.properties ? 'object' : s.items ? 'array' : s.enum ? typeof s.enum[0] === 'number' ? 'number' : 'string' : undefined;
+
+  /** @type {any} */ let node;
+  if (type === 'object') {
+    const props = {};
+    for (const [prop, child] of Object.entries(s.properties ?? {})) {
+      const n = convert(child, schemas, hints, depth + 1, name);
+      props[prop] = applyHints(n, name ? hints?.fields?.[`${name}.${prop}`] : undefined);
+    }
+    if (!Object.keys(props).length) return { t: 'any', ...(nullable ? { nullable: true } : {}) }; // a free-form object (additionalProperties only)
+    node = { t: 'object', props, ...(s.required?.length ? { required: [...s.required] } : {}) };
+    if (name && hints?.schemas?.[name]) { // hints for a whole schema: pruneEmpty, emptyAs, and anything else a widget of that schema wants
+      const { id: _id, entity: _entity, ...rest } = hints.schemas[name];
+      node = applyHints(node, rest);
+    }
+  } else if (type === 'array') {
+    node = { t: 'array', items: convert(s.items ?? {}, schemas, hints, depth + 1, name),
+      ...(s.minItems != null ? { minItems: s.minItems } : {}), ...(s.maxItems != null ? { maxItems: s.maxItems } : {}), ...(s.uniqueItems ? { uniqueItems: true } : {}) };
+  } else if (PRIMITIVE.has(type)) {
+    node = { t: type };
+    for (const k of ['format', 'enum', 'minLength', 'maxLength', 'pattern', 'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf']) if (s[k] !== undefined) node[k] = s[k];
+    if (type === 'string' && s.format === 'binary') node.format = 'binary';
+    // OpenAPI 3.0 writes exclusiveMinimum as a boolean next to minimum
+    if (s.exclusiveMinimum === true) { node.exclusiveMinimum = s.minimum; delete node.minimum; }
+    if (s.exclusiveMaximum === true) { node.exclusiveMaximum = s.maximum; delete node.maximum; }
+    if (node.exclusiveMinimum === false) delete node.exclusiveMinimum;
+    if (node.exclusiveMaximum === false) delete node.exclusiveMaximum;
+  } else {
+    return { t: 'any' };
+  }
+  if (nullable) node.nullable = true;
+  return decorate(node, s);
+}
+
+/** Presentation and server-owned flags that any node may carry. */
+function decorate(node, s) {
+  if (s.readOnly) node.readOnly = true;
+  if (s.default !== undefined) node.default = s.default;
+  if (s.title) node.title = s.title;
+  if (s.description) node.description = s.description;
+  if (s['x-xoong-widget']) node.widget = s['x-xoong-widget'];
+  if (s['x-xoong-prune-empty'] !== undefined) node.pruneEmpty = !!s['x-xoong-prune-empty']; // the same as the pruneEmpty hint, written in the spec
+  if (s['x-xoong-empty-as']) node.emptyAs = s['x-xoong-empty-as'];
+  for (const [k, v] of Object.entries(s)) { // any other x-* extension reaches custom widgets untouched, in `schema.hints`
+    if (k.startsWith('x-') && !k.startsWith('x-xoong-') && !['x-nullable', 'x-xoong-id', 'x-xoong-entity'].includes(k)) (node.hints ??= {})[k] = v;
+  }
+  return node;
+}
+
+const KNOWN_HINTS = new Set(['label', 'hint', 'placeholder', 'widget', 'order', 'readOnly', 'hidden', 'group', 'emptyAs', 'pruneEmpty']);
+
+/**
+ * Hints from xoong.hints.json. `label` and `hint` become the node's title and description; the other keys xoong acts on keep their names;
+ * every other key is passed through untouched in `node.hints`, for custom widgets (an open registry, ADR-0009).
+ */
+function applyHints(node, h) {
+  if (!h) return node;
+  const out = { ...node };
+  if (h.label !== undefined) out.title = h.label;
+  if (h.hint !== undefined) out.description = h.hint;
+  for (const k of ['placeholder', 'widget', 'order', 'readOnly', 'hidden', 'group', 'emptyAs', 'pruneEmpty']) if (h[k] !== undefined) out[k] = h[k];
+  const extra = Object.fromEntries(Object.entries(h).filter(([k]) => !KNOWN_HINTS.has(k)));
+  if (Object.keys(extra).length) out.hints = { ...(out.hints ?? {}), ...extra };
+  return out;
+}
+
+/** A union told apart by the discriminator, or by a property every member fixes to one value. */
+function unionOf(s, members, schemas, hints, depth, owner) {
+  const d = s.discriminator;
+  const resolved = members.map((m) => flatten(m, schemas, owner, depth + 1));
+  let key = d?.propertyName;
+  /** @type {(string|number|boolean)[] | undefined} */ let values;
+  if (key) {
+    const single = (p) => (p && 'const' in p ? p.const : p?.enum?.length === 1 ? p.enum[0] : undefined);
+    values = members.map((m, i) => {
+      if (!m.$ref) return single(deref(resolved[i].s?.properties?.[key], schemas).s); // an inline member names itself by the fixed value of the tag
+      const mapped = Object.entries(d.mapping ?? {}).find(([, target]) => target === m.$ref || String(target).endsWith('/' + refName(m.$ref)));
+      return mapped ? mapped[0] : refName(m.$ref);
+    });
+  } else {
+    const single = (p) => (p && 'const' in p ? p.const : p?.enum?.length === 1 ? p.enum[0] : undefined);
+    const keys = Object.keys(resolved[0]?.s?.properties ?? {});
+    for (const k of keys) {
+      const vs = resolved.map((r) => single(deref(r.s?.properties?.[k], schemas).s));
+      if (vs.every((v) => v !== undefined) && new Set(vs).size === vs.length) { key = k; values = vs; break; }
+    }
+  }
+  if (!key || !values || values.some((v) => v === undefined)) return undefined;
+  const map = {};
+  members.forEach((m, i) => { map[String(values[i])] = convert(m, schemas, hints, depth + 1, owner); });
+  return { t: 'union', key, map };
+}

package/src/build.js

@@ -0,0 +1,211 @@
+// @ts-check
+/**
+ * `xoong build`: static output that runs under a strict Content-Security-Policy (no import map, no inline script, no inline style).
+ *
+ *   xoong build [--root .] [--out dist] [--base /admin]
+ *
+ * Starts from every .html page under the root and follows what it references (scripts, stylesheets, images) and what the scripts import
+ * (relative modules, JSON, and bare packages, which are found in node_modules and copied to the same URLs the dev server uses). Then:
+ *   - bare imports ("@xoong/data") are rewritten to URLs, so the page needs no import map;
+ *   - TypeScript is stripped (erasable syntax only) and .ts files are written as .js;
+ *   - `--base` prefixes root-absolute URLs for an app served under a path;
+ *   - nothing is minified or bundled; every file is the one you wrote (readable in the browser's tools).
+ * What cannot be seen (a fetch() of a data file, an image named in JavaScript) is added with `--include <file-or-folder>`.
+ */
+import { readFile, writeFile, mkdir, readdir, stat, copyFile, realpath } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve, extname, posix, sep } from 'node:path';
+import { gzipSync } from 'node:zlib';
+import { parse } from 'parse5';
+import { findPackages, packagePath, stripTypes } from '@xoong/server/node';
+import { loadConfig } from './dev.js';
+import { buildImportMap } from '@xoong/server';
+
+const SCRIPT_EXT = new Set(['.js', '.mjs', '.ts', '.mts']);
+const toJs = (p) => p.replace(/\.m?ts$/, (m) => (m === '.mts' ? '.mjs' : '.js'));
+const isLocal = (u) => !!u && !/^([a-z][a-z0-9+.-]*:|\/\/|#)/i.test(u);
+
+/** The policy this output is meant to run under (and is tested with). */
+export const CSP = "default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; img-src 'self' data:; font-src 'self'; base-uri 'none'; form-action 'self'";
+
+/**
+ * @param {{ root?: string, out?: string, base?: string, include?: string[] }} [options]
+ * @returns {Promise<{ out: string, files: { path: string, bytes: number, gzip: number }[], warnings: string[], csp: string }>}
+ */
+export async function build({ root = '.', out = 'dist', base = '', include = [], packages: extra } = {}) {
+  const rootDir = await realpath(resolve(root)); // real path: packages are found by theirs, so an app inside a symlinked package must compare equal
+  // the output folder may not exist yet: resolve the part that does
+  const realOut = async (p) => { try { return await realpath(p); } catch { const up = dirname(p); return up === p ? p : join(await realOut(up), basename(p)); } };
+  const outDir = await realOut(resolve(out));
+  const basePath = base ? `/${base.replace(/^\/+|\/+$/g, '')}` : '';
+  const packages = await findPackages(rootDir, undefined, extra ?? (await loadConfig(rootDir)).packages ?? []);
+  const importMap = buildImportMap(packages).imports;
+  /** @type {string[]} */ const warnings = [];
+  /** @type {Map<string, string>} output path (relative to out, with a leading slash) -> source file */
+  const sources = new Map();
+  /** @type {Map<string, Buffer | string>} */ const written = new Map();
+  const queue = [];
+
+  /** Source file for a root-absolute URL path: the app root, or an installed package under its prefix. */
+  function fileFor(urlPath) {
+    for (const p of Object.values(packages)) {
+      if (urlPath === p.prefix || urlPath.startsWith(`${p.prefix}/`)) return join(p.dir, urlPath.slice(p.prefix.length));
+    }
+    return join(rootDir, urlPath);
+  }
+  /** An exports subpath used as a URL ("/@rainlet/theme.css") becomes the real file's URL, so relative references inside it keep working. */
+  const canon = (url) => {
+    for (const p of Object.values(packages)) if (url.startsWith(`${p.prefix}/`)) return p.prefix + packagePath(p.exports, url.slice(p.prefix.length));
+    return url;
+  };
+  /**
+   * The URL of a file. The most specific owner wins: an app that lives inside the package it consumes (`"rainlet": "file:.."`, a workspace)
+   * keeps its own pages at the site root, while the package's files are still served under its prefix.
+   */
+  const urlOf = (file) => {
+    const inside = (dir) => file === dir || file.startsWith(dir + sep);
+    const owner = Object.values(packages).filter((p) => inside(p.dir)).sort((a, b) => b.dir.length - a.dir.length)[0];
+    if (owner && !(inside(rootDir) && rootDir.length > owner.dir.length)) return `${owner.prefix}${file.slice(owner.dir.length).split(sep).join('/')}`;
+    return `/${relative(rootDir, file).split(sep).join('/')}`;
+  };
+  const inOut = (f) => f === outDir || f.startsWith(outDir + sep); // the output folder is never an input, even when it sits inside the root
+  const exists = async (f) => !inOut(f) && stat(f).then((s) => s.isFile(), () => false);
+
+  /** Rewrite one specifier or URL found in `fromUrl` (a root-absolute URL path). Returns the new text, and queues the target file. */
+  async function rewrite(spec, fromUrl) {
+    let target;
+    if (importMap[spec]) target = importMap[spec]; // a bare import of an installed package
+    else if (/^[a-z@][^:]*$/i.test(spec) && !spec.startsWith('.') && !spec.startsWith('/')) {
+      const prefix = Object.keys(importMap).filter((k) => k.endsWith('/') && spec.startsWith(k)).sort((a, b) => b.length - a.length)[0];
+      if (!prefix) { warnings.push(`${fromUrl}: cannot resolve "${spec}" (not an installed xoong package); left as it is`); return spec; }
+      target = importMap[prefix] + spec.slice(prefix.length);
+    } else if (spec.startsWith('/')) target = spec.split(/[?#]/)[0];
+    else if (spec.startsWith('.')) target = posix.normalize(posix.join(posix.dirname(fromUrl), spec.split(/[?#]/)[0]));
+    else return spec; // an absolute URL: not ours
+    target = canon(target);
+    const suffix = (spec.match(/[?#].*$/) ?? [''])[0];
+    queue.push(target);
+    return `${basePath}${toJs(target)}${suffix}`;
+  }
+
+  async function transformScript(urlPath, source) {
+    let code = source;
+    if (/\.m?ts$/.test(urlPath)) code = await stripTypes(code, urlPath);
+    const re = /(\bimport\s*(?:[\w*${}\s,]*?\bfrom\s*)?|\bexport\s+(?:\*(?:\s+as\s+\w+)?|\{[^}]*\})\s*from\s*|\bimport\s*\(\s*)(['"])([^'"\n]+)\2/g;
+    const parts = [];
+    let last = 0;
+    for (const m of code.matchAll(re)) {
+      const specStart = (m.index ?? 0) + m[0].length - m[3].length - 1;
+      parts.push(code.slice(last, specStart), await rewrite(m[3], urlPath));
+      last = specStart + m[3].length;
+    }
+    parts.push(code.slice(last));
+    return parts.join('');
+  }
+
+  async function transformCss(urlPath, source) {
+    const parts = [];
+    let last = 0;
+    for (const m of source.matchAll(/url\(\s*(['"]?)([^'")]+)\1\s*\)|@import\s+(['"])([^'"]+)\3/g)) {
+      const spec = m[2] ?? m[4];
+      if (!isLocal(spec) || spec.startsWith('data:')) continue;
+      const at = (m.index ?? 0) + m[0].indexOf(spec);
+      parts.push(source.slice(last, at), await rewrite(relativeUrl(spec), urlPath));
+      last = at + spec.length;
+    }
+    parts.push(source.slice(last));
+    return parts.join('');
+  }
+
+  /** HTML: rewrite references, drop an import map (the imports are rewritten), warn about what a strict policy blocks. */
+  async function transformHtml(urlPath, source) {
+    const doc = parse(source, { sourceCodeLocationInfo: true });
+    const edits = [];
+    const visit = async (node) => {
+      for (const child of node.childNodes ?? []) await visit(child);
+      if (node.nodeName === 'template') for (const child of node.content?.childNodes ?? []) await visit(child);
+      if (!node.tagName) return;
+      const attr = (n) => node.attrs.find((a) => a.name === n);
+      if (node.tagName === 'script') {
+        if (attr('type')?.value === 'importmap') { const l = node.sourceCodeLocation; edits.push([l.startOffset, l.endOffset, '']); return; }
+        if (!attr('src') && (node.childNodes ?? []).some((c) => c.value?.trim())) warnings.push(`${urlPath}:${node.sourceCodeLocation.startLine}: an inline <script> is blocked by script-src 'self'; move it to a file`);
+      }
+      if (attr('style')) warnings.push(`${urlPath}:${node.sourceCodeLocation.startLine}: a style="" attribute is blocked by style-src 'self'; use a class`);
+      if (node.tagName === 'style') warnings.push(`${urlPath}:${node.sourceCodeLocation.startLine}: an inline <style> is blocked by style-src 'self'; move it to a stylesheet`);
+      for (const name of ['src', 'href', 'poster', 'srcset']) {
+        const a = attr(name);
+        if (!a || !isLocal(a.value) || node.tagName === 'a' || (node.tagName === 'link' && attr('rel')?.value && !/stylesheet|icon|preload|modulepreload|manifest/.test(attr('rel')?.value ?? ''))) continue;
+        if (name === 'srcset' || a.value.startsWith('data:')) continue;
+        const loc = node.sourceCodeLocation.attrs?.[name];
+        if (!loc) continue;
+        const raw = source.slice(loc.startOffset, loc.endOffset);
+        edits.push([loc.startOffset, loc.endOffset, raw.replace(a.value, await rewriteHtmlUrl(a.value, urlPath))]);
+      }
+    };
+    await visit(doc);
+    edits.sort((x, y) => y[0] - x[0]);
+    let result = source;
+    for (const [s, e, text] of edits) result = result.slice(0, s) + text + result.slice(e);
+    return result;
+  }
+
+  /** In HTML and CSS a URL without a leading slash or dot is relative to the file (only JavaScript imports have bare package names). */
+  const relativeUrl = (u) => (/^[./?#]/.test(u) ? u : `./${u}`);
+
+  /** Links inside the page to other pages are left; files the page loads are queued and given the base. */
+  async function rewriteHtmlUrl(rawUrl, fromUrl) {
+    const url = relativeUrl(rawUrl); // href="src/app.css" is relative to the page, not a package name
+    const target = url.startsWith('/') ? url.split(/[?#]/)[0] : posix.normalize(posix.join(posix.dirname(fromUrl), url.split(/[?#]/)[0]));
+    if (!(await exists(fileFor(canon(target))))) return url; // not a file we can serve (a route): keep as written
+    return rewrite(url, fromUrl);
+  }
+
+  async function emit(urlPath) {
+    const outPath = toJs(urlPath);
+    if (sources.has(outPath)) return;
+    const file = fileFor(urlPath);
+    if (inOut(file)) { warnings.push(`${urlPath}: points into the output folder, which is not an input`); sources.set(outPath, ''); return; }
+    if (!(await exists(file))) { warnings.push(`${urlPath}: referenced but not found`); sources.set(outPath, ''); return; }
+    sources.set(outPath, file);
+    const ext = extname(file).toLowerCase();
+    if (SCRIPT_EXT.has(ext)) written.set(outPath, await transformScript(urlPath, await readFile(file, 'utf8')));
+    else if (ext === '.css') written.set(outPath, await transformCss(urlPath, await readFile(file, 'utf8')));
+    else if (ext === '.html' || ext === '.htm') written.set(outPath, await transformHtml(urlPath, await readFile(file, 'utf8')));
+    else written.set(outPath, await readFile(file));
+  }
+
+  // pages first, then whatever they pull in
+  const pages = [];
+  const walk = async (dir) => {
+    for (const name of await readdir(dir)) {
+      if (name === 'node_modules' || name.startsWith('.') || resolve(dir, name) === outDir) continue;
+      const p = join(dir, name);
+      if ((await stat(p)).isDirectory()) await walk(p); else if (/\.html?$/i.test(name)) pages.push(urlOf(p));
+    }
+  };
+  await walk(rootDir);
+  if (!pages.length) throw new Error(`xoong build: no .html page found under ${rootDir}`);
+  for (const item of include) {
+    const p = resolve(rootDir, item);
+    const s = await stat(p).catch(() => null);
+    if (!s) { warnings.push(`--include ${item}: not found`); continue; }
+    const files = [];
+    const collect = async (d) => { for (const n of await readdir(d)) { const f = join(d, n); if (inOut(f)) continue; if ((await stat(f)).isDirectory()) await collect(f); else files.push(f); } };
+    if (s.isDirectory()) await collect(p); else files.push(p);
+    for (const f of files) queue.push(urlOf(f));
+  }
+  queue.push(...pages);
+  while (queue.length) await emit(/** @type {string} */ (queue.shift()));
+
+  const report = [];
+  for (const [outPath, content] of written) {
+    const dest = join(outDir, outPath);
+    await mkdir(dirname(dest), { recursive: true });
+    await writeFile(dest, content);
+    const buf = typeof content === 'string' ? Buffer.from(content) : content;
+    report.push({ path: outPath, bytes: buf.length, gzip: gzipSync(buf).length });
+  }
+  report.sort((a, b) => a.path.localeCompare(b.path));
+  await writeFile(join(outDir, 'build-report.json'), JSON.stringify({ csp: CSP, files: report, warnings }, null, 2) + '\n');
+  void copyFile;
+  return { out: outDir, files: report, warnings, csp: CSP };
+}