@aletheia-ios/tools 0.1.0 → 0.2.1

package/README.md

@@ -15,6 +15,7 @@ usage: aletheia <command> [options]
   check [--only <slug>]     typecheck, build, verify exports and run fixtures under JavaScriptCore
   pack  [--only <slug>]     build, rasterise the icon and zip to dist/packages/<slug>-v<version>.althsource
   index                     write dist/<target>/index.json for every list in lists/
+  site                      write dist/<target>/site/ - the page a reader adds the list from
   serve [--port <n>]        pack, index, serve dist/ on the lan and rebuild on change
   new <slug> [--name <n>]   scaffold packages/<slug> from the template
   live <slug> <series|-> [query]
@@ -33,6 +34,10 @@ my-sources/
   dist/              generated
 ```
 
+A list may also carry `"url"`, where that target's `index.json` will be served once deployed,
+and `"adult": true`. Only `site` reads them: the first is what the deep link and QR point at,
+the second puts an age gate in front of the page.
+
 `aletheia` finds the nearest `packages/` above the working directory. Every package folder
 name is its slug and must match `source.json`.
 
@@ -58,6 +63,14 @@ as one package because of this.
 size, the package folder's last commit date) plus `dist/<target>/manifest.json` naming the
 package and icon files that target's deploy has to upload.
 
+**site** - for every list that declares a `url`, writes `dist/<target>/site/`: a static page
+with an `aletheia://add-list` deep link, the URL, and a QR inlined as SVG at build time, then
+a card per source carrying its icon, version, languages and rating. Each source's `icon.png`
+and `source.json` are copied in beside the page, so the folder deploys as-is and every card
+can link to the manifest that says what that source contacts. Generated from the same data as
+the index, so the two cannot disagree. A list marked `"adult": true` gets an age gate that
+fails closed without script.
+
 **serve** - runs pack and index, serves `dist/` on the LAN with `cache-control: no-store`, and
 reruns both when anything under `packages/` or `lists/` changes. Point the app's developer list
 at the printed URL.

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import process from "node:process";
 import { parseArgs } from "node:util";
-import { cp, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { copyFile, cp, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join, normalize, relative, resolve } from "node:path";
 import { build } from "esbuild";
-import { createReadStream, existsSync, mkdtempSync, watch, writeFileSync } from "node:fs";
+import { createReadStream, existsSync, mkdtempSync, readFileSync, watch, writeFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { AuthSpec, Filters, Index, SourceManifest } from "@aletheia-ios/sdk/schemas";
 import { spawnSync } from "node:child_process";
@@ -15,6 +15,7 @@ import { z } from "zod";
 import vm from "node:vm";
 import { zipSync } from "fflate";
 import { createServer } from "node:http";
+import qrcode from "qrcode-generator";
 //#region src/lib/log.ts
 /** Bytes per kilobyte as the size lines report it. */
 const KB = 1024;
@@ -75,6 +76,16 @@ function ownRoot() {
 /** The folder this cli is installed in, holding `template/` and its own `node_modules/`. */
 const OWN_ROOT = ownRoot();
 /**
+* This cli's own `name@version`, recorded in each index entry.
+*
+* A bundler upgrade can change `main.js` for unchanged source, so two lists can hold the same
+* package at different shas without anyone tampering. This is what tells them apart.
+*/
+const BUILT_WITH = (() => {
+	const own = JSON.parse(readFileSync(join(OWN_ROOT, "package.json"), "utf8"));
+	return `${own.name}@${own.version}`;
+})();
+/**
 * Locates the repository from a working directory: the nearest ancestor holding `packages/`.
 *
 * @throws `CliError` when no ancestor has one.
@@ -106,6 +117,16 @@ async function readJSON(path) {
 		throw new CliError([`${path}: ${error instanceof Error ? error.message : String(error)}`], { cause: error });
 	}
 }
+/**
+* Whether a manifest slug belongs in a folder of this name.
+*
+* Slugs are reverse-DNS, so `packages/mangadex` holding `com.example.mangadex` keeps the
+* folder list readable. The full slug is accepted too, which is the way out when two
+* publishers' packages in one repository end in the same segment.
+*/
+function namesFolder(slug, folder) {
+	return slug === folder || slug.slice(slug.lastIndexOf(".") + 1) === folder;
+}
 /** Turns a failed parse into `file path: message` lines; empty for a successful one. */
 function issues(file, result) {
 	if (result.success) return [];
@@ -120,12 +141,13 @@ function issues(file, result) {
 *
 * @throws `CliError` listing every problem found.
 */
-async function loadPackage(repo, slug) {
-	const dir = join(repo.packages, slug);
+async function loadPackage(repo, folder) {
+	const dir = join(repo.packages, folder);
+	const slug = folder;
 	const problems = [];
 	const manifestResult = SourceManifest.safeParse(await readJSON(join(dir, "source.json")));
 	problems.push(...issues(`${slug}/source.json`, manifestResult));
-	if (manifestResult.success && manifestResult.data.slug !== slug) problems.push(`${slug}/source.json slug: "${manifestResult.data.slug}" must match the folder name`);
+	if (manifestResult.success && !namesFolder(manifestResult.data.slug, slug)) problems.push(`${slug}/source.json slug: "${manifestResult.data.slug}" must match the folder name or end with it`);
 	const filtersResult = Filters.safeParse(await readJSON(join(dir, "filters.json")));
 	problems.push(...issues(`${slug}/filters.json`, filtersResult));
 	let auth = null;
@@ -137,7 +159,8 @@ async function loadPackage(repo, slug) {
 	if (!existsSync(join(dir, "src", "index.ts"))) problems.push(`${slug}/src/index.ts is missing`);
 	if (problems.length > 0 || !manifestResult.success || !filtersResult.success) throw new CliError(problems);
 	return {
-		slug,
+		slug: manifestResult.data.slug,
+		folder,
 		dir,
 		manifest: manifestResult.data,
 		filters: filtersResult.data,
@@ -204,7 +227,7 @@ const ZOD_INPUT = /node_modules\/(\.pnpm\/)?zod[/@]/;
 *   `@aletheia-ios/sdk/schemas` and would ship a validator to every phone.
 */
 async function buildOne(repo, pkg) {
-	const outfile = bundlePath(repo, pkg.slug);
+	const outfile = bundlePath(repo, pkg.folder);
 	await mkdir(dirname(outfile), { recursive: true });
 	const result = await build({
 		entryPoints: [join(pkg.dir, "src", "index.ts")],
@@ -220,7 +243,7 @@ async function buildOne(repo, pkg) {
 		logLevel: "warning",
 		metafile: true
 	});
-	if (Object.keys(result.metafile.inputs).some((input) => ZOD_INPUT.test(input))) throw new CliError([`${pkg.slug}: main.js bundles zod - a source must not import @aletheia-ios/sdk/schemas`]);
+	if (Object.keys(result.metafile.inputs).some((input) => ZOD_INPUT.test(input))) throw new CliError([`${pkg.folder}: main.js bundles zod - a source must not import @aletheia-ios/sdk/schemas`]);
 	return {
 		pkg,
 		path: outfile,
@@ -232,7 +255,7 @@ async function build$1(repo, packages) {
 	const built = [];
 	for (const pkg of packages) {
 		const one = await buildOne(repo, pkg);
-		info(`${pkg.slug}: main.js ${kb(one.bytes)}`);
+		info(`${pkg.folder}: main.js ${kb(one.bytes)}`);
 		built.push(one);
 	}
 	return built;
@@ -409,7 +432,7 @@ const OPTIONAL = [
 function typecheck(repo, pkg) {
 	const tsc = join(repo.root, "node_modules", ".bin", "tsc");
 	if (!existsSync(tsc)) {
-		warn(`${pkg.slug}: typescript is not installed in this repository, skipping typecheck`);
+		warn(`${pkg.folder}: typescript is not installed in this repository, skipping typecheck`);
 		return [];
 	}
 	const child = spawnSync(tsc, [
@@ -423,7 +446,7 @@ function typecheck(repo, pkg) {
 /** The icon problems for a package as lines, empty when it has exactly one icon. */
 function icon(pkg) {
 	try {
-		findIcon(pkg.dir, pkg.slug);
+		findIcon(pkg.dir, pkg.folder);
 		return [];
 	} catch (error) {
 		if (error instanceof CliError) return error.lines;
@@ -440,20 +463,20 @@ function icon(pkg) {
 async function evaluate$1(pkg, path) {
 	const bundle = await readFile(path, "utf8");
 	const exported = exportsOf(bundle);
-	if (!exported.ok || exported.result === null) return [`${pkg.slug}: main.js failed to evaluate in JavaScriptCore\n${exported.output}`];
+	if (!exported.ok || exported.result === null) return [`${pkg.folder}: main.js failed to evaluate in JavaScriptCore\n${exported.output}`];
 	const missing = REQUIRED.filter((name) => exported.result?.[name] !== "function");
-	if (missing.length > 0) return missing.map((name) => `${pkg.slug}: missing export ${name}()`);
+	if (missing.length > 0) return missing.map((name) => `${pkg.folder}: missing export ${name}()`);
 	const capabilities = OPTIONAL.filter((name) => exported.result?.[name] === "function");
 	if (pkg.auth !== null) capabilities.push("auth");
-	const label = `${pkg.slug}: ok [${capabilities.join(", ") || "base"}]`;
+	const label = `${pkg.folder}: ok [${capabilities.join(", ") || "base"}]`;
 	const fixturesPath = join(pkg.dir, "fixtures", "smoke.json");
 	if (!existsSync(fixturesPath)) {
-		warn(`${pkg.slug}: no fixtures/smoke.json - exports verified, calls not exercised`);
+		warn(`${pkg.folder}: no fixtures/smoke.json - exports verified, calls not exercised`);
 		info(label);
 		return [];
 	}
 	const result = smoke(bundle, JSON.parse(await readFile(fixturesPath, "utf8")));
-	if (!result.ok || result.result === null) return [`${pkg.slug}: smoke failed in JavaScriptCore\n${result.output}`];
+	if (!result.ok || result.result === null) return [`${pkg.folder}: smoke failed in JavaScriptCore\n${result.output}`];
 	const out = result.result;
 	info(`${label} - "${out.details.title}", ${out.search.items.length} results, ${out.chapters.length} chapters, ${out.content.length} pages`);
 	return [];
@@ -485,10 +508,16 @@ async function check(repo, packages) {
 /**
 * Validates one `lists/<name>.json`: the list's display name, the `dist/<target>` folder
 * it publishes to, and the package slugs it includes.
+*
+* `url` is where that target's `index.json` will be served once deployed. Only `site` needs
+* it, to build the deep link and QR a reader adds the list with, so it stays optional until
+* the zone exists. `adult` puts an age gate in front of the generated page.
 */
 const List = z.strictObject({
 	name: z.string().min(1),
 	target: z.string().regex(/^[a-z0-9-]+$/),
+	url: z.url().optional(),
+	adult: z.boolean().optional(),
 	sources: z.array(z.string().min(1)).min(1)
 });
 /**
@@ -538,11 +567,12 @@ function updatedDate(pkg) {
 */
 async function entry(repo, pkg, target) {
 	const path = packagePath(repo, pkg);
-	if (!existsSync(path)) throw new CliError([`${pkg.slug}: not packed - run pack first`]);
+	if (!existsSync(path)) throw new CliError([`${pkg.folder}: not packed - run pack first`]);
 	const bytes = await readFile(path);
 	const base = join(repo.dist, target);
 	return {
 		slug: pkg.slug,
+		...pkg.manifest.replaces === void 0 ? {} : { replaces: pkg.manifest.replaces },
 		name: pkg.manifest.name,
 		version: pkg.manifest.version,
 		minAppVersion: pkg.manifest.minAppVersion,
@@ -553,7 +583,8 @@ async function entry(repo, pkg, target) {
 		sha256: createHash("sha256").update(bytes).digest("hex"),
 		updatedDate: updatedDate(pkg),
 		downloadURL: relative(base, path),
-		iconURL: relative(base, iconPath(repo, pkg.slug))
+		iconURL: relative(base, iconPath(repo, pkg.slug)),
+		builtWith: BUILT_WITH
 	};
 }
 /**
@@ -605,7 +636,7 @@ function evaluate(bundle, hosts) {
 		__host: {
 			async fetch(request) {
 				const { host } = new URL(request.url);
-				if (!hosts.includes(host)) throw new Error(`host not allowed by source.json: ${host}`);
+				if (!hosts.some((name) => host === name || host.endsWith(`.${name}`))) throw new Error(`host not allowed by source.json: ${host}`);
 				const response = await fetch(request.url, {
 					method: request.method ?? "GET",
 					headers: {
@@ -680,8 +711,8 @@ const TEXT = /* @__PURE__ */ new Set([
 	".ts",
 	".md"
 ]);
-/** A valid package slug: lowercase letters, digits and hyphens. */
-const SLUG = /^[a-z0-9-]+$/;
+/** A valid package slug: reverse-DNS, matching the sdk's `slug` scalar. */
+const SLUG = /^[a-z0-9]+(-[a-z0-9]+)*(\.[a-z0-9]+(-[a-z0-9]+)*)+$/;
 /** Rewrites every text file under `dir`, replacing each placeholder wherever it appears. */
 async function substitute(dir, values) {
 	for (const entry of await readdir(dir, { withFileTypes: true })) {
@@ -707,12 +738,13 @@ async function substitute(dir, values) {
 *   already exists.
 */
 async function create(repo, slug, name) {
-	if (!SLUG.test(slug)) throw new CliError([`"${slug}" is not a slug - lowercase letters, digits and hyphens only`]);
-	const dir = join(repo.packages, slug);
-	if (existsSync(dir)) throw new CliError([`packages/${slug} already exists`]);
+	if (!SLUG.test(slug)) throw new CliError([`"${slug}" is not a slug - reverse-dns, such as com.example.mysite`]);
+	const folder = slug.slice(slug.lastIndexOf(".") + 1);
+	const dir = join(repo.packages, folder);
+	if (existsSync(dir)) throw new CliError([`packages/${folder} already exists`]);
 	await cp(TEMPLATE, dir, { recursive: true });
 	await substitute(dir, [["__SLUG__", slug], ["__NAME__", name]]);
-	info(`created packages/${slug} - it passes \`aletheia check\` as an offline source; replace src/ with the real one`);
+	info(`created packages/${folder} - it passes \`aletheia check\` as an offline source; replace src/ with the real one`);
 }
 //#endregion
 //#region src/lib/zip.ts
@@ -754,7 +786,7 @@ async function pack(repo, packages) {
 	const built = await build$1(repo, packages);
 	const packed = [];
 	for (const { pkg, path } of built) {
-		const icon = await rasterise(findIcon(pkg.dir, pkg.slug), pkg.slug);
+		const icon = await rasterise(findIcon(pkg.dir, pkg.folder), pkg.folder);
 		const files = {
 			"source.json": await readFile(join(pkg.dir, "source.json")),
 			"filters.json": await readFile(join(pkg.dir, "filters.json")),
@@ -770,7 +802,7 @@ async function pack(repo, packages) {
 		await writeFile(out, zip);
 		await writeFile(iconOut, icon);
 		const sha256 = createHash("sha256").update(zip).digest("hex");
-		info(`${pkg.slug}: ${out.slice(repo.root.length + 1)} ${kb(zip.byteLength)} ${sha256.slice(0, SHORT_HASH)}`);
+		info(`${pkg.folder}: ${out.slice(repo.root.length + 1)} ${kb(zip.byteLength)} ${sha256.slice(0, SHORT_HASH)}`);
 		packed.push({
 			pkg,
 			path: out,
@@ -782,13 +814,247 @@ async function pack(repo, packages) {
 	return packed;
 }
 //#endregion
+//#region src/lib/html.ts
+/** Error correction level; M survives a phone camera at an angle without doubling the size. */
+const QR_CORRECTION = "M";
+/** Auto-select the smallest QR version that fits the data. */
+const QR_AUTO_VERSION = 0;
+/** Module size in the generated SVG; the viewBox scales it, so this only sets the aspect grid. */
+const QR_CELL = 4;
+/**
+* Escapes text for use in HTML markup or a double-quoted attribute.
+*
+* Everything interpolated into a page comes from a package's own json, so it is author-supplied
+* rather than trusted.
+*/
+function escapeHTML(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&#39;");
+}
+/**
+* Renders a QR code for a URL as a standalone, scalable `<svg>` element.
+*
+* Generated at build time so the page needs no script and no network to draw it.
+*/
+function qrSVG(url) {
+	const code = qrcode(QR_AUTO_VERSION, QR_CORRECTION);
+	code.addData(url);
+	code.make();
+	return code.createSvgTag({
+		cellSize: QR_CELL,
+		margin: 0,
+		scalable: true
+	});
+}
+//#endregion
+//#region src/commands/site.ts
+/** Where a target's generated page and its assets are written. */
+function sitePath(repo, target) {
+	return join(repo.dist, target, "site");
+}
+const STYLE = `
+:root {
+  --bg: #fbfbfd; --fg: #16161a; --muted: #6b6b76; --line: #e4e4ea;
+  --card: #ffffff; --accent: #4c5cff; --accent-fg: #ffffff;
+}
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #0f0f12; --fg: #f2f2f5; --muted: #9a9aa5; --line: #26262e;
+    --card: #17171c; --accent: #7c88ff; --accent-fg: #0f0f12;
+  }
+}
+* { box-sizing: border-box; }
+body {
+  margin: 0; padding: 3rem 1.25rem 5rem; background: var(--bg); color: var(--fg);
+  font: 16px/1.55 ui-sans-serif, -apple-system, "Segoe UI", system-ui, sans-serif;
+}
+main { max-width: 46rem; margin: 0 auto; }
+h1 { font-size: 1.9rem; margin: 0 0 .35rem; letter-spacing: -.02em; }
+.lede { color: var(--muted); margin: 0 0 2rem; }
+.add { display: flex; align-items: flex-start; gap: 1.75rem; flex-wrap: wrap; margin-bottom: 2.75rem; }
+.add-main { flex: 1 1 20rem; min-width: 0; }
+.actions { display: flex; flex-wrap: wrap; gap: .75rem; margin-bottom: 1rem; }
+.button {
+  display: inline-block; padding: .7rem 1.15rem; border-radius: .6rem; border: 1px solid var(--line);
+  background: var(--card); color: var(--fg); font: inherit; font-weight: 600; cursor: pointer;
+  text-decoration: none; line-height: 1.2;
+}
+.button.primary { background: var(--accent); color: var(--accent-fg); border-color: transparent; }
+.url {
+  font: .8rem/1.6 ui-monospace, SFMono-Regular, Menlo, monospace; color: var(--muted);
+  word-break: break-all; margin: 0;
+}
+.qr { width: 7.25rem; height: 7.25rem; padding: .45rem; background: #fff; border-radius: .6rem; flex: none; }
+.qr svg { display: block; width: 100%; height: 100%; }
+.qr rect:first-of-type { fill: #fff; }
+h2 { font-size: .8rem; text-transform: uppercase; letter-spacing: .08em; color: var(--muted); margin: 0 0 .85rem; }
+.source {
+  display: flex; align-items: flex-start; gap: 1rem; padding: 1rem; margin-bottom: .75rem;
+  background: var(--card); border: 1px solid var(--line); border-radius: .75rem;
+}
+.source img { width: 3rem; height: 3rem; border-radius: .55rem; flex: none; }
+.source div { min-width: 0; }
+.source h3 { margin: 0 0 .3rem; font-size: 1rem; line-height: 1.3; }
+.source p { margin: 0 0 .7rem; color: var(--muted); font-size: .9rem; }
+.meta { display: flex; flex-wrap: wrap; align-items: center; gap: .45rem; font-size: .75rem; color: var(--muted); }
+.tag {
+  display: inline-block; padding: .2rem .55rem; border: 1px solid var(--line);
+  border-radius: 100px; line-height: 1.4;
+}
+a.tag { color: inherit; text-decoration: none; }
+a.tag:hover { color: var(--fg); border-color: var(--accent); }
+footer { margin-top: 2rem; padding-top: 1.5rem; border-top: 1px solid var(--line); color: var(--muted); font-size: .85rem; }
+footer p { margin: 0 0 .7rem; max-width: 38rem; }
+footer p:last-child { margin-bottom: 0; }
+#gate { text-align: center; padding: 4rem 0; }
+#gate + * { display: none; }
+`;
+const SCRIPT = `
+document.querySelectorAll("[data-copy]").forEach(function (button) {
+  button.addEventListener("click", function () {
+    navigator.clipboard.writeText(button.dataset.copy).then(function () {
+      var previous = button.textContent;
+      button.textContent = "Copied";
+      setTimeout(function () { button.textContent = previous; }, 1500);
+    });
+  });
+});
+var gate = document.getElementById("gate");
+if (gate) {
+  gate.querySelector("button").addEventListener("click", function () {
+    gate.remove();
+    document.getElementById("list").style.display = "block";
+  });
+}
+`;
+/** The age gate shown ahead of an adult list; without script the list stays hidden. */
+function gate() {
+	return `<section id="gate">
+      <h2>Adults only</h2>
+      <p class="lede">This list contains explicit material. Confirm you are 18 or older.</p>
+      <button class="button primary" type="button">I am 18 or older</button>
+    </section>`;
+}
+/** One source's row: icon, name, description and what the app will record about it. */
+function card(pkg) {
+	const { manifest } = pkg;
+	const languages = manifest.languages.map((code) => code.toUpperCase()).join(", ");
+	const rating = manifest.contentRating === "adult" ? "18+" : "Mixed ratings";
+	return `<article class="source">
+        <img src="icons/${escapeHTML(pkg.slug)}.png" alt="" width="48" height="48">
+        <div>
+          <h3>${escapeHTML(manifest.name)}</h3>
+          <p>${escapeHTML(manifest.description)}</p>
+          <div class="meta">
+            <span class="tag">v${escapeHTML(manifest.version)}</span>
+            <span class="tag">${escapeHTML(languages)}</span>
+            <span class="tag">${rating}</span>
+            <a class="tag" href="sources/${escapeHTML(pkg.slug)}.json">source.json</a>
+          </div>
+        </div>
+      </article>`;
+}
+/** The add buttons: a deep link for a phone, the URL and a QR for a desktop browser. */
+function actions(url) {
+	return `<div class="add">
+      <div class="add-main">
+        <div class="actions">
+          <a class="button primary" href="${escapeHTML(`aletheia://add-list?url=${encodeURIComponent(url)}`)}">Open in Aletheia</a>
+          <button class="button" type="button" data-copy="${escapeHTML(url)}">Copy URL</button>
+        </div>
+        <p class="url">${escapeHTML(url)}</p>
+      </div>
+      <div class="qr">${qrSVG(url)}</div>
+    </div>`;
+}
+/** The notice every published list carries. */
+function notice() {
+	return `<footer>
+      <p>This list is not an official part of Aletheia, and it is not connected to, endorsed by,
+      or approved by any of the sites named above. Their names and logos belong to them.</p>
+      <p>No comics, images or accounts are stored or shared here. An entry only tells the app
+      where to go looking, and you can open any entry to see the sites it uses.</p>
+      <p>If you would like something taken off this list, get in touch and it will be removed.</p>
+    </footer>`;
+}
+/** The whole page for one list. */
+function page(list, url, members) {
+	const heading = escapeHTML(list.name);
+	const count = members.length === 1 ? "1 source" : `${members.length} sources`;
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${heading}</title>
+<style>${STYLE}</style>
+</head>
+<body>
+  <main>
+    <h1>${heading}</h1>
+    <p class="lede">Opens in Aletheia with this address filled in. You confirm before anything
+    is added, and the app keeps the list up to date afterwards.</p>
+    ${list.adult === true ? gate() : ""}
+    <div id="list"${list.adult === true ? " style=\"display:none\"" : ""}>
+      ${actions(url)}
+      <h2>${count}</h2>
+      ${members.map(card).join("\n      ")}
+    </div>
+    ${notice()}
+  </main>
+<script>${SCRIPT}<\/script>
+</body>
+</html>
+`;
+}
+/** Copies the icon and manifest each card links to, so the page stands alone once deployed. */
+async function assets(repo, out, members) {
+	await mkdir(join(out, "icons"), { recursive: true });
+	await mkdir(join(out, "sources"), { recursive: true });
+	for (const pkg of members) {
+		const icon = iconPath(repo, pkg.slug);
+		if (!existsSync(icon)) throw new CliError([`${pkg.folder}: not packed - run pack first`]);
+		await copyFile(icon, join(out, "icons", `${pkg.slug}.png`));
+		await copyFile(join(pkg.dir, "source.json"), join(out, "sources", `${pkg.slug}.json`));
+	}
+}
+/**
+* The `site` command: writes `dist/<target>/site/` for every list that declares a `url`.
+*
+* The page is generated from the same `lists/` and `source.json` data as the index it
+* advertises, so the two cannot disagree. It is static and self-contained: the QR is inlined
+* at build time and each source's icon and manifest are copied in beside it.
+*
+* A list with no `url` is skipped with a note, since the deep link and QR have nothing to
+* point at until that target's zone exists.
+*
+* @throws `CliError` when a list names a package that does not exist or is not packed.
+*/
+async function site(repo, packages) {
+	const bySlug = new Map(packages.map((pkg) => [pkg.slug, pkg]));
+	for (const list of await loadLists(repo)) {
+		const missing = list.sources.filter((slug) => !bySlug.has(slug));
+		if (missing.length > 0) throw new CliError(missing.map((slug) => `list "${list.name}": no package "${slug}"`));
+		if (list.url === void 0) {
+			info(`${list.target}: no url in the list, skipping the page`);
+			continue;
+		}
+		const members = list.sources.map((slug) => bySlug.get(slug));
+		const out = sitePath(repo, list.target);
+		await mkdir(out, { recursive: true });
+		await assets(repo, out, members);
+		await writeFile(join(out, "index.html"), page(list, list.url, members));
+		info(`${list.target}/site/index.html: ${members.length} source(s)`);
+	}
+}
+//#endregion
 //#region src/commands/serve.ts
 /** Content types for what `dist/` holds; anything else is served as octet-stream. */
 const TYPES = {
 	".json": "application/json",
 	".png": "image/png",
 	".althsource": "application/zip",
-	".js": "text/javascript"
+	".js": "text/javascript",
+	".html": "text/html; charset=utf-8"
 };
 /** Leading `../` segments left after normalisation, which would escape `dist/`. */
 const TRAVERSAL = /^(\.\.[/\\])+/;
@@ -807,6 +1073,7 @@ async function rebuild(repo) {
 		const packages = await loadPackages(repo);
 		await pack(repo, packages);
 		await indexes(repo, packages);
+		await site(repo, packages);
 	} catch (error) {
 		report(error);
 	}
@@ -819,8 +1086,9 @@ function lanAddress() {
 /**
 * The file under `dist/` a request names, or null when it names nothing servable.
 *
-* Null covers a missing file, a directory, a path that would escape `dist/`, and a URL
-* that does not decode.
+* A directory resolves to its `index.html` when it has one, the way Pages will serve the
+* generated site. Null covers a missing file, a directory without one, a path that would
+* escape `dist/`, and a URL that does not decode.
 */
 async function resolveFile(dist, url) {
 	let path;
@@ -829,8 +1097,11 @@ async function resolveFile(dist, url) {
 	} catch {
 		return null;
 	}
-	const file = join(dist, path);
-	return file.startsWith(dist) && existsSync(file) && (await stat(file)).isFile() ? file : null;
+	const target = join(dist, path);
+	if (!(target.startsWith(dist) && existsSync(target))) return null;
+	const file = (await stat(target)).isDirectory() ? join(target, "index.html") : target;
+	if (!(existsSync(file) && (await stat(file)).isFile())) return null;
+	return file;
 }
 /** A static server over `dist/` that sends `cache-control: no-store` so the app never caches a dev build. */
 function fileServer(dist) {
@@ -860,25 +1131,56 @@ function watchRepo(repo) {
 	return [watch(repo.packages, { recursive: true }, trigger), watch(repo.lists, { recursive: true }, trigger)];
 }
 /**
+* Binds the port and reports the one it got, since port 0 picks a free one.
+*
+* A busy port is the common way this fails and it arrives as an `error` event rather than a
+* rejection, so without this it surfaces as an unhandled event and a stack trace.
+*
+* @throws `CliError` naming the port when something already holds it.
+*/
+async function listen(server, port) {
+	try {
+		await new Promise((resolve, reject) => {
+			server.once("error", reject);
+			server.listen(port, "0.0.0.0", () => {
+				server.removeListener("error", reject);
+				resolve();
+			});
+		});
+	} catch (error) {
+		if (error.code === "EADDRINUSE") throw new CliError([`port ${port} is already in use - pass --port <n> to pick another`], { cause: error });
+		throw error;
+	}
+	const address = server.address();
+	return typeof address === "object" && address !== null ? address.port : port;
+}
+/**
 * The `serve` command: packs, indexes, serves `dist/` on the lan and rebuilds on change.
 *
 * Binds every interface and prints the lan URL of each list's `index.json`, which is what
 * the app's developer list points at. Port 0 binds a free port. Resolves once listening;
 * the returned `close` stops the watchers and the server.
 *
-* @throws `CliError` when there is no `lists/` directory, before any port is bound.
+* @throws `CliError` when there is no `lists/` directory, or when the port is taken.
 */
 async function serve(repo, port) {
 	const lists = await loadLists(repo);
 	await rebuild(repo);
 	const server = fileServer(repo.dist);
 	const watchers = watchRepo(repo);
-	await new Promise((resolve) => server.listen(port, "0.0.0.0", resolve));
-	const address = server.address();
-	const bound = typeof address === "object" && address !== null ? address.port : port;
+	let bound;
+	try {
+		bound = await listen(server, port);
+	} catch (error) {
+		for (const watcher of watchers) watcher.close();
+		throw error;
+	}
 	const url = `http://${lanAddress()}:${bound}/`;
 	info(`serving ${repo.dist} on ${url}`);
-	for (const list of lists) info(`  ${list.name}: ${url}${list.target}/index.json`);
+	for (const list of lists) {
+		info(`  ${list.name}: ${url}${list.target}/index.json`);
+		if (existsSync(sitePath(repo, list.target))) info(`  ${" ".repeat(list.name.length)}  ${url}${list.target}/site/`);
+	}
 	return {
 		url,
 		close: () => {
@@ -896,6 +1198,7 @@ const USAGE = `usage: aletheia <command> [options]
   check [--only <slug>]     typecheck, build, verify exports and run fixtures under JavaScriptCore
   pack  [--only <slug>]     build, rasterise the icon and zip to dist/packages/<slug>-v<version>.althsource
   index                     write dist/<target>/index.json for every list in lists/
+  site                      write dist/<target>/site/ - the page a reader adds the list from
   serve [--port <n>]        pack, index, serve dist/ on the lan and rebuild on change
   new <slug> [--name <n>]   scaffold packages/<slug> from the template
   live <slug> <series|-> [query]
@@ -949,6 +1252,9 @@ async function main(argv) {
 		case "index":
 			await indexes(repo, await loadPackages(repo));
 			return;
+		case "site":
+			await site(repo, await loadPackages(repo));
+			return;
 		case "serve":
 			await serve(repo, Number.parseInt(values.port ?? DEFAULT_PORT, 10));
 			return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aletheia-ios/tools",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "The aletheia CLI: build, check, pack, index and serve source packages",
   "license": "MIT",
   "repository": {
@@ -32,9 +32,10 @@
     "prepare": "lefthook install"
   },
   "dependencies": {
-    "@aletheia-ios/sdk": "^0.1.0",
+    "@aletheia-ios/sdk": "^0.4.0",
     "esbuild": "^0.28.2",
     "fflate": "^0.8.3",
+    "qrcode-generator": "^2.0.4",
     "sharp": "^0.35.4",
     "zod": "^4.5.4"
   },