@aletheia-ios/tools 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aletheia
+
+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

@@ -0,0 +1,80 @@
+# @aletheia-ios/tools
+
+The `aletheia` command. Turns a repository of source packages into `.althsource` files and the
+`index.json` a source list publishes. Runs on a Mac or in CI, never on a phone - the on-device
+half is [`@aletheia-ios/sdk`](https://github.com/aletheia-ios/sdk).
+
+```sh
+pnpm add -D @aletheia-ios/tools
+```
+
+```
+usage: aletheia <command> [options]
+
+  build [--only <slug>]     bundle each package's src/index.ts to dist/build/<slug>/main.js
+  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/
+  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]
+                            run a package against the live site in node and print what it returns
+```
+
+## A repository
+
+```
+my-sources/
+  packages/
+    mangadex/        source.json  filters.json  icon.svg  src/index.ts  fixtures/smoke.json
+    ...
+  lists/
+    main.json        { "name": "My Sources", "target": "main", "sources": ["mangadex"] }
+  dist/              generated
+```
+
+`aletheia` finds the nearest `packages/` above the working directory. Every package folder
+name is its slug and must match `source.json`.
+
+## What each command guarantees
+
+**build** - one esbuild IIFE per package, ES2022, no Node or DOM assumptions, ending with the
+source object on `globalThis.__source`. Fails if the bundle pulled in zod, which means a source
+imported `@aletheia-ios/sdk/schemas`.
+
+**check** - `tsc` per package when TypeScript is installed in the repository, then build, then
+the bundle is evaluated in the `jsc` shell inside `JavaScriptCore.framework` - the engine the
+phone runs, not Node. Verifies the four required exports, reports which optional ones exist,
+and if `fixtures/smoke.json` is present runs search, details, chapters and content against
+canned responses. A Web API the bundle assumed and the phone lacks fails here, not on a device.
+
+**pack** - rasterises whichever of `icon.svg`, `icon.png`, `icon.jpg` is checked in (prefer
+svg > png > jpg) to a 512x512 `icon.png`, then zips the five files with fixed timestamps. The
+same content always produces the same bytes; the app treats one package published by two lists
+as one package because of this.
+
+**index** - for every `lists/*.json`, reads the packed files and writes
+`dist/<target>/index.json` (validated against the sdk's `Index` schema, relative URLs, sha256,
+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.
+
+**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.
+
+**new** - copies the template: an offline source with `hosts: []` that passes `check` as-is,
+so the first thing you see from a new package is green.
+
+**live** - builds one package and runs it in Node with a real network behind `__host.fetch`,
+honouring the manifest's `hosts` allowlist. For comparing a port against what the app shows
+today. Never part of `check`.
+
+## Fixtures
+
+`fixtures/smoke.json` is an array of `{ "match": "<substring of a URL>", "body": <json> }`.
+`check` answers each `__host.fetch` with the first fixture whose `match` appears in the URL,
+and calls `search("smoke")`, `details("series")`, `chapters("series")`,
+`content("series", "chapter")` in that order. Capture real responses from the site and trim
+them; the point is that the mapping code runs over real shapes without a network.
+
+MIT.

package/dist/cli.js

@@ -0,0 +1,979 @@
+#!/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 { basename, dirname, extname, join, normalize, relative, resolve } from "node:path";
+import { build } from "esbuild";
+import { createReadStream, existsSync, mkdtempSync, 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";
+import sharp from "sharp";
+import { networkInterfaces, tmpdir } from "node:os";
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import vm from "node:vm";
+import { zipSync } from "fflate";
+import { createServer } from "node:http";
+//#region src/lib/log.ts
+/** Bytes per kilobyte as the size lines report it. */
+const KB = 1024;
+/**
+* A failure the cli reports as plain lines and exits 1 on.
+*
+* Anything else that escapes is a bug in the cli and is printed with its stack. Commands
+* collect every problem they can find into one `CliError` so a broken repository is fixed
+* in one round trip rather than one file at a time.
+*/
+var CliError = class extends Error {
+	/** One problem per line, already prefixed with the file or package it belongs to. */
+	lines;
+	constructor(lines, options) {
+		super(lines.join("\n"), options);
+		this.name = "CliError";
+		this.lines = lines;
+	}
+};
+/** Prints a progress line to stdout. */
+function info(message) {
+	console.log(message);
+}
+/** Prints a non-fatal problem to stderr with a `warning:` prefix. */
+function warn(message) {
+	console.warn(`warning: ${message}`);
+}
+/**
+* Prints an error to stderr: a `CliError` as its lines, anything else as-is with its stack.
+*
+* Shared by the process entry and by `serve`, which keeps running after a failed rebuild.
+*/
+function report(error) {
+	if (error instanceof CliError) for (const line of error.lines) console.error(line);
+	else console.error(error);
+}
+/** Formats a byte count as `12.3 kB`. */
+function kb(bytes) {
+	return `${(bytes / KB).toFixed(1)} kB`;
+}
+//#endregion
+//#region src/context.ts
+/**
+* Finds this cli's own package root by walking up to the folder holding `template/`.
+*
+* `dist/cli.js` and `src/commands/*.ts` sit at different depths, so a fixed relative path
+* would resolve correctly from only one of them.
+*/
+function ownRoot() {
+	let dir = dirname(fileURLToPath(import.meta.url));
+	while (!existsSync(join(dir, "template"))) {
+		const parent = dirname(dir);
+		if (parent === dir) throw new Error("template/ not found next to the aletheia cli");
+		dir = parent;
+	}
+	return dir;
+}
+/** The folder this cli is installed in, holding `template/` and its own `node_modules/`. */
+const OWN_ROOT = ownRoot();
+/**
+* Locates the repository from a working directory: the nearest ancestor holding `packages/`.
+*
+* @throws `CliError` when no ancestor has one.
+*/
+function findRepo(cwd = process.cwd()) {
+	let dir = resolve(cwd);
+	for (;;) {
+		if (existsSync(join(dir, "packages"))) return {
+			root: dir,
+			packages: join(dir, "packages"),
+			lists: join(dir, "lists"),
+			dist: join(dir, "dist")
+		};
+		const parent = dirname(dir);
+		if (parent === dir) throw new CliError([`no packages/ directory found above ${cwd}`]);
+		dir = parent;
+	}
+}
+/**
+* Reads and parses a json file.
+*
+* @throws `CliError` naming the file when it is missing or malformed, with the original error
+*   as the cause.
+*/
+async function readJSON(path) {
+	try {
+		return JSON.parse(await readFile(path, "utf8"));
+	} catch (error) {
+		throw new CliError([`${path}: ${error instanceof Error ? error.message : String(error)}`], { cause: error });
+	}
+}
+/** Turns a failed parse into `file path: message` lines; empty for a successful one. */
+function issues(file, result) {
+	if (result.success) return [];
+	return result.error.issues.map((issue) => `${file} ${issue.path.join(".") || "(root)"}: ${issue.message}`);
+}
+/**
+* Loads one package by folder name, validating `source.json`, `filters.json` and, when
+* present, `auth.json` against the sdk schemas.
+*
+* Every problem across the three files is collected before anything is thrown, and the
+* manifest's slug has to match the folder name because the folder is what lists refer to.
+*
+* @throws `CliError` listing every problem found.
+*/
+async function loadPackage(repo, slug) {
+	const dir = join(repo.packages, slug);
+	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`);
+	const filtersResult = Filters.safeParse(await readJSON(join(dir, "filters.json")));
+	problems.push(...issues(`${slug}/filters.json`, filtersResult));
+	let auth = null;
+	if (existsSync(join(dir, "auth.json"))) {
+		const authResult = AuthSpec.safeParse(await readJSON(join(dir, "auth.json")));
+		problems.push(...issues(`${slug}/auth.json`, authResult));
+		if (authResult.success) auth = authResult.data;
+	}
+	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,
+		dir,
+		manifest: manifestResult.data,
+		filters: filtersResult.data,
+		auth
+	};
+}
+/**
+* Loads every package folder under `packages/`, sorted by name, skipping dotfolders.
+*
+* With `only` (the `--only` flags) the set is narrowed first, and a name that is not a
+* folder is an error rather than silently nothing. Problems from every package are
+* collected before anything is thrown.
+*
+* @throws `CliError` listing unknown `only` names, or every problem across the packages.
+*/
+async function loadPackages(repo, only) {
+	const names = (await readdir(repo.packages, { withFileTypes: true })).filter((entry) => entry.isDirectory() && !entry.name.startsWith(".")).map((entry) => entry.name).filter((name) => only === void 0 || only.includes(name)).sort();
+	if (only !== void 0) {
+		const missing = only.filter((name) => !names.includes(name));
+		if (missing.length > 0) throw new CliError(missing.map((name) => `no package "${name}"`));
+	}
+	const problems = [];
+	const packages = [];
+	for (const name of names) try {
+		packages.push(await loadPackage(repo, name));
+	} catch (error) {
+		if (error instanceof CliError) problems.push(...error.lines);
+		else throw error;
+	}
+	if (problems.length > 0) throw new CliError(problems);
+	return packages;
+}
+/** Where `build` writes a package's bundle: `dist/build/<slug>/main.js`. */
+function bundlePath(repo, slug) {
+	return join(repo.dist, "build", slug, "main.js");
+}
+/** Where `pack` writes a package's archive: `dist/packages/<slug>-v<version>.althsource`. */
+function packagePath(repo, pkg) {
+	return join(repo.dist, "packages", `${pkg.slug}-v${pkg.manifest.version}.althsource`);
+}
+/** Where `pack` writes a package's rasterised icon: `dist/icons/<slug>.png`. */
+function iconPath(repo, slug) {
+	return join(repo.dist, "icons", `${slug}.png`);
+}
+//#endregion
+//#region src/commands/build.ts
+/**
+* A fallback resolution root for the bundler.
+*
+* The sdk installed next to this cli resolves from here, so a repository that has not
+* installed `@aletheia-ios/sdk` itself still builds.
+*/
+const OWN_NODE_MODULES = join(OWN_ROOT, "node_modules");
+/** Matches a zod file in esbuild's input list, under a flat or pnpm layout. */
+const ZOD_INPUT = /node_modules\/(\.pnpm\/)?zod[/@]/;
+/**
+* Bundles one package's `src/index.ts` to `dist/build/<slug>/main.js`.
+*
+* The output is a single ES2022 iife for a neutral platform, with no node or dom
+* assumptions, ending by leaving the default export on `globalThis.__source` where the
+* host reads it after evaluation.
+*
+* @throws `CliError` when the bundle pulled in zod, which means the source imported
+*   `@aletheia-ios/sdk/schemas` and would ship a validator to every phone.
+*/
+async function buildOne(repo, pkg) {
+	const outfile = bundlePath(repo, pkg.slug);
+	await mkdir(dirname(outfile), { recursive: true });
+	const result = await build({
+		entryPoints: [join(pkg.dir, "src", "index.ts")],
+		bundle: true,
+		format: "iife",
+		globalName: "__bundle",
+		footer: { js: "globalThis.__source = __bundle.default;" },
+		platform: "neutral",
+		target: "es2022",
+		outfile,
+		tsconfig: join(pkg.dir, "tsconfig.json"),
+		nodePaths: [OWN_NODE_MODULES],
+		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`]);
+	return {
+		pkg,
+		path: outfile,
+		bytes: Object.values(result.metafile.outputs)[0]?.bytes ?? 0
+	};
+}
+/** The `build` command: bundles each package in turn and prints its size. */
+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)}`);
+		built.push(one);
+	}
+	return built;
+}
+//#endregion
+//#region src/lib/icon.ts
+/** The file names a package may use for its icon, in order of preference. */
+const CANDIDATES = [
+	"icon.svg",
+	"icon.png",
+	"icon.jpg"
+];
+/** The smallest raster the cli will upscale; anything less looks blurred on a phone. */
+const MIN_RASTER = 256;
+/** The density an svg is rendered at so its edges stay sharp after the resize. */
+const SVG_DENSITY = 300;
+/**
+* Returns the path of the package's icon.
+*
+* Exactly one of `icon.svg`, `icon.png`, `icon.jpg` must be present: svg is preferred
+* because it rasterises to any size, but a package keeps whichever it has and never two.
+*
+* @throws `CliError` when the folder has no icon or more than one.
+*/
+function findIcon(dir, slug) {
+	const present = CANDIDATES.filter((name) => existsSync(join(dir, name)));
+	if (present.length !== 1) throw new CliError([present.length === 0 ? `${slug}: no icon - add icon.svg, icon.png or icon.jpg` : `${slug}: more than one icon (${present.join(", ")}) - keep exactly one`]);
+	return join(dir, present[0]);
+}
+/**
+* Renders an icon file to a square png of `ICON_SIZE`, letterboxed on transparency.
+*
+* The app decodes png only, so an svg is rasterised here and never on the device. A raster
+* smaller than `MIN_RASTER` on its long side is refused rather than upscaled.
+*
+* @throws `CliError` when a raster icon is too small.
+*/
+async function rasterise(source, slug) {
+	const image = sharp(source, { density: SVG_DENSITY });
+	const metadata = await image.metadata();
+	if (metadata.format !== "svg" && Math.max(metadata.width ?? 0, metadata.height ?? 0) < MIN_RASTER) throw new CliError([`${slug}: icon is ${metadata.width}x${metadata.height}, need at least ${MIN_RASTER}px on the long side`]);
+	return image.resize(512, 512, {
+		fit: "contain",
+		background: {
+			r: 0,
+			g: 0,
+			b: 0,
+			alpha: 0
+		}
+	}).png().toBuffer();
+}
+//#endregion
+//#region src/lib/jsc.ts
+/**
+* The shell inside `JavaScriptCore.framework` on macOS.
+*
+* It is the same engine the phone runs, which is the point: node has `fetch`, `atob` and
+* `TextEncoder`, and JavaScriptCore does not. A bundle that assumes one of them fails here
+* instead of on a device.
+*/
+const JSC = "/System/Library/Frameworks/JavaScriptCore.framework/Versions/Current/Helpers/jsc";
+/** Whether the jsc shell exists on this machine; false anywhere but macOS. */
+function hasJSC() {
+	return existsSync(JSC);
+}
+/**
+* The stand-in host the bundle sees: a `__host.fetch` answered from fixtures, no html
+* bridge, and a `console` that goes to jsc's `print`.
+*/
+const HARNESS = `
+  var __calls = [];
+  var __host = {
+    fetch: function (request) {
+      __calls.push(request.url);
+      var fixture = __fixtures.find(function (f) { return request.url.indexOf(f.match) !== -1; });
+      if (!fixture) return Promise.reject(new Error("no fixture for " + request.url));
+      return Promise.resolve({ status: 200, headers: {}, url: request.url, text: JSON.stringify(fixture.body) });
+    },
+    html: {},
+  };
+  var console = { log: print, warn: print, error: print };
+`;
+/** Prints the `typeof` of every contract method on the exported source. */
+const EXPORTS = `
+  print("RESULT " + JSON.stringify({
+    search: typeof __source.search, details: typeof __source.details,
+    chapters: typeof __source.chapters, content: typeof __source.content,
+    comments: typeof __source.comments, replies: typeof __source.replies,
+    chaptersChanged: typeof __source.chaptersChanged, isChallenge: typeof __source.isChallenge,
+    pingURL: typeof __source.pingURL,
+  }));
+`;
+/**
+* Calls search, details, chapters and content in turn and prints what came back.
+*
+* `drainMicrotasks` is jsc's way of running the promise chain to completion; there is no
+* event loop in the shell. JavaScriptCore's `Error.stack` omits the message, so it is
+* printed first along with a `SourceError` code when there is one.
+*/
+const SMOKE = `
+  var __ctx = { settings: {} };
+  var __out = {};
+  __source.search({ text: "smoke", filters: [], sort: null, cursor: null, route: null }, __ctx)
+    .then(function (s) { __out.search = s; return __source.details("series", __ctx); })
+    .then(function (d) { __out.details = d; return __source.chapters("series", __ctx); })
+    .then(function (c) { __out.chapters = c; return __source.content("series", "chapter", __ctx); })
+    .then(function (p) { __out.content = p; print("RESULT " + JSON.stringify(__out)); })
+    .catch(function (e) {
+      if (!(e && e.message)) return print("ERROR " + e);
+      print("ERROR " + (e.code ? e.code + ": " : "") + e.message + "\\n" + e.stack);
+    });
+  drainMicrotasks();
+`;
+/**
+* Writes harness + fixtures + bundle + script to a temp file and runs it under jsc.
+*
+* The script reports through a single `RESULT ` or `ERROR ` line on stdout; a non-zero exit
+* (an uncaught throw while the bundle loads) counts as a failure too.
+*/
+function run(bundle, fixtures, script) {
+	const file = join(mkdtempSync(join(tmpdir(), "aletheia-jsc-")), "run.js");
+	writeFileSync(file, `${HARNESS}\nvar __fixtures = ${JSON.stringify(fixtures)};\n${bundle}\n${script}`);
+	const child = spawnSync(JSC, [file], { encoding: "utf8" });
+	const output = `${child.stdout}${child.stderr}`;
+	const line = child.stdout.split("\n").find((candidate) => candidate.startsWith("RESULT ") || candidate.startsWith("ERROR "));
+	if (child.status !== 0 || !line || line.startsWith("ERROR ")) return {
+		ok: false,
+		result: null,
+		output
+	};
+	return {
+		ok: true,
+		result: JSON.parse(line.slice(7)),
+		output
+	};
+}
+/** Evaluates the bundle under jsc and reports which contract methods it exports. */
+function exportsOf(bundle) {
+	return run(bundle, [], EXPORTS);
+}
+/**
+* Evaluates the bundle under jsc and runs the four required calls against fixtures.
+*
+* The calls use the placeholder slugs `series` and `chapter` and the query text `smoke`;
+* fixtures answer whatever URLs the source builds from them.
+*/
+function smoke(bundle, fixtures) {
+	return run(bundle, fixtures, SMOKE);
+}
+//#endregion
+//#region src/commands/check.ts
+/** The methods every source must export. */
+const REQUIRED = [
+	"search",
+	"details",
+	"chapters",
+	"content"
+];
+/** The methods whose presence the app reads as a capability. */
+const OPTIONAL = [
+	"comments",
+	"replies",
+	"chaptersChanged",
+	"isChallenge",
+	"pingURL"
+];
+/**
+* Runs the repository's own `tsc` against the package's tsconfig.
+*
+* Skipped with a warning when TypeScript is not installed in the repository; the bundler
+* strips types without checking them, so this is the only place a type error surfaces.
+* Returns tsc's output lines, empty when it passed.
+*/
+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`);
+		return [];
+	}
+	const child = spawnSync(tsc, [
+		"-p",
+		join(pkg.dir, "tsconfig.json"),
+		"--noEmit"
+	], { encoding: "utf8" });
+	if (child.status === 0) return [];
+	return child.stdout.trim().split("\n");
+}
+/** The icon problems for a package as lines, empty when it has exactly one icon. */
+function icon(pkg) {
+	try {
+		findIcon(pkg.dir, pkg.slug);
+		return [];
+	} catch (error) {
+		if (error instanceof CliError) return error.lines;
+		throw error;
+	}
+}
+/**
+* Evaluates a built bundle under JavaScriptCore and returns its problems as lines.
+*
+* Verifies the required exports, prints the capabilities the app will derive, and when
+* `fixtures/smoke.json` exists runs the four calls against it. Without fixtures the
+* exports alone are verified and a warning says so.
+*/
+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}`];
+	const missing = REQUIRED.filter((name) => exported.result?.[name] !== "function");
+	if (missing.length > 0) return missing.map((name) => `${pkg.slug}: 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 fixturesPath = join(pkg.dir, "fixtures", "smoke.json");
+	if (!existsSync(fixturesPath)) {
+		warn(`${pkg.slug}: 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}`];
+	const out = result.result;
+	info(`${label} - "${out.details.title}", ${out.search.items.length} results, ${out.chapters.length} chapters, ${out.content.length} pages`);
+	return [];
+}
+/**
+* The `check` command: typecheck, build, then verify each bundle under JavaScriptCore.
+*
+* Type errors stop the run before anything is built. After that every package is checked
+* and every problem reported together. The JavaScriptCore step needs the jsc shell that
+* ships with macOS and is skipped with a warning elsewhere.
+*
+* @throws `CliError` listing every problem found.
+*/
+async function check(repo, packages) {
+	const problems = [];
+	for (const pkg of packages) problems.push(...typecheck(repo, pkg));
+	if (problems.length > 0) throw new CliError(problems);
+	const built = await build$1(repo, packages);
+	const jsc = hasJSC();
+	if (!jsc) warn("jsc shell not found (macOS only) - skipping the JavaScriptCore run");
+	for (const { pkg, path } of built) {
+		problems.push(...icon(pkg));
+		if (jsc) problems.push(...await evaluate$1(pkg, path));
+	}
+	if (problems.length > 0) throw new CliError(problems);
+}
+//#endregion
+//#region src/commands/indexes.ts
+/**
+* Validates one `lists/<name>.json`: the list's display name, the `dist/<target>` folder
+* it publishes to, and the package slugs it includes.
+*/
+const List = z.strictObject({
+	name: z.string().min(1),
+	target: z.string().regex(/^[a-z0-9-]+$/),
+	sources: z.array(z.string().min(1)).min(1)
+});
+/**
+* Loads every `lists/*.json`, sorted by file name.
+*
+* @throws `CliError` when there is no `lists/` directory, or listing every invalid field
+*   across the lists.
+*/
+async function loadLists(repo) {
+	if (!existsSync(repo.lists)) throw new CliError([`no lists/ directory in ${repo.root}`]);
+	const names = (await readdir(repo.lists)).filter((name) => name.endsWith(".json")).sort();
+	const lists = [];
+	const problems = [];
+	for (const name of names) {
+		const result = List.safeParse(JSON.parse(await readFile(join(repo.lists, name), "utf8")));
+		if (result.success) lists.push(result.data);
+		else problems.push(...result.error.issues.map((issue) => `lists/${name} ${issue.path.join(".") || "(root)"}: ${issue.message}`));
+	}
+	if (problems.length > 0) throw new CliError(problems);
+	return lists;
+}
+/**
+* The package folder's last commit date as ISO 8601.
+*
+* Taken from git so an unchanged package keeps its date across rebuilds and the app does
+* not see a fresh update every deploy. Falls back to now outside a git checkout.
+*/
+function updatedDate(pkg) {
+	const child = spawnSync("git", [
+		"log",
+		"-1",
+		"--format=%cI",
+		"--",
+		pkg.dir
+	], {
+		cwd: pkg.dir,
+		encoding: "utf8"
+	});
+	const iso = child.status === 0 ? child.stdout.trim() : "";
+	return iso === "" ? (/* @__PURE__ */ new Date()).toISOString() : new Date(iso).toISOString();
+}
+/**
+* Builds a package's entry for a list: manifest fields, the packed file's size and
+* sha256, and download and icon URLs relative to `dist/<target>/`.
+*
+* @throws `CliError` when the package has not been packed.
+*/
+async function entry(repo, pkg, target) {
+	const path = packagePath(repo, pkg);
+	if (!existsSync(path)) throw new CliError([`${pkg.slug}: not packed - run pack first`]);
+	const bytes = await readFile(path);
+	const base = join(repo.dist, target);
+	return {
+		slug: pkg.slug,
+		name: pkg.manifest.name,
+		version: pkg.manifest.version,
+		minAppVersion: pkg.manifest.minAppVersion,
+		contractVersion: pkg.manifest.contractVersion,
+		contentRating: pkg.manifest.contentRating,
+		languages: pkg.manifest.languages,
+		size: (await stat(path)).size,
+		sha256: createHash("sha256").update(bytes).digest("hex"),
+		updatedDate: updatedDate(pkg),
+		downloadURL: relative(base, path),
+		iconURL: relative(base, iconPath(repo, pkg.slug))
+	};
+}
+/**
+* The `index` command: writes `dist/<target>/index.json` for every list.
+*
+* The index is validated against the sdk's `Index` schema before it is written, so a
+* deploy never publishes what the app would reject. Next to it, `manifest.json` names the
+* package and icon files that target's deploy has to upload besides its own directory.
+*
+* @throws `CliError` when a list names a package that does not exist or is not packed.
+*/
+async function indexes(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}"`));
+		const members = list.sources.map((slug) => bySlug.get(slug));
+		const entries = [];
+		for (const pkg of members) entries.push(await entry(repo, pkg, list.target));
+		const index = Index.parse({
+			name: list.name,
+			updatedDate: (/* @__PURE__ */ new Date()).toISOString(),
+			sources: entries
+		});
+		const dir = join(repo.dist, list.target);
+		await mkdir(dir, { recursive: true });
+		await writeFile(join(dir, "index.json"), `${JSON.stringify(index, null, 2)}\n`);
+		const manifest = {
+			packages: members.map((pkg) => basename(packagePath(repo, pkg))),
+			icons: members.map((pkg) => basename(iconPath(repo, pkg.slug)))
+		};
+		await writeFile(join(dir, "manifest.json"), `${JSON.stringify(manifest, null, 2)}\n`);
+		info(`${list.target}/index.json: ${entries.length} source(s)`);
+	}
+}
+//#endregion
+//#region src/commands/live.ts
+/** How many search results are listed before the walk moves on. */
+const PREVIEW = 5;
+/**
+* Evaluates the bundle in a node vm with a real network behind `__host.fetch`.
+*
+* The manifest's `hosts` allowlist is enforced the way the app enforces it, so a source
+* that reaches somewhere it did not declare fails here too. There is no html bridge.
+*/
+function evaluate(bundle, hosts) {
+	const context = vm.createContext({
+		console,
+		__host: {
+			async fetch(request) {
+				const { host } = new URL(request.url);
+				if (!hosts.includes(host)) throw new Error(`host not allowed by source.json: ${host}`);
+				const response = await fetch(request.url, {
+					method: request.method ?? "GET",
+					headers: {
+						"user-agent": "aletheia-tools live",
+						...request.headers ?? {}
+					},
+					...request.body === void 0 ? {} : { body: request.body }
+				});
+				return {
+					status: response.status,
+					headers: Object.fromEntries(response.headers),
+					url: response.url,
+					text: await response.text()
+				};
+			},
+			html: {}
+		}
+	});
+	vm.runInContext(bundle, context);
+	return context.__source;
+}
+/**
+* The `live` command: builds one package and walks it against the live site in node.
+*
+* Searches for `text`, opens `series` (or the first result when it is `-`), lists its
+* chapters, revalidates when the source can, and fetches the first chapter's pages,
+* printing a summary of each step. This is how a port is compared with what the app shows
+* today; it is never part of `check`.
+*
+* @throws `CliError` when the search returns nothing to open.
+*/
+async function live(repo, pkg, series, text) {
+	const { path } = await buildOne(repo, pkg);
+	const source = evaluate(await readFile(path, "utf8"), pkg.manifest.hosts);
+	const ctx = { settings: {} };
+	const started = Date.now();
+	const search = await source.search({
+		text,
+		filters: [],
+		sort: null,
+		cursor: null,
+		route: null
+	}, ctx);
+	info(`search "${text}": ${search.items.length} results, next=${search.next}`);
+	for (const item of search.items.slice(0, PREVIEW)) info(`  ${item.slug}  ${item.title}`);
+	const slug = series === "-" ? search.items[0]?.slug : series;
+	if (slug === void 0) throw new CliError(["nothing to open - no results"]);
+	const details = await source.details(slug, ctx);
+	info(`details: ${details.title} [${details.classification}, ${details.publication}]`);
+	info(`  ${details.covers.length} covers, ${details.tags.length} tags, authors ${details.authors.join(", ")}`);
+	const chapters = await source.chapters(slug, ctx);
+	info(`chapters: ${chapters.length}`);
+	const [first] = chapters;
+	if (first !== void 0) {
+		info(`  first: #${first.number} "${first.title}" ${first.language} by ${first.scanlator}`);
+		if (source.chaptersChanged) {
+			const revalidation = await source.chaptersChanged(slug, chapters.length, ctx);
+			info(`revalidate with stored=${chapters.length}: ${revalidation.kind}`);
+		}
+		const pages = await source.content(slug, first.slug, ctx);
+		info(`content: ${pages.length} pages, first ${pages[0]?.url ?? "-"}`);
+	}
+	info(`done in ${Date.now() - started} ms`);
+}
+//#endregion
+//#region src/commands/new.ts
+/** The package skeleton shipped with the cli: an offline source that passes `check` as-is. */
+const TEMPLATE = join(OWN_ROOT, "template");
+/** File extensions that get placeholder substitution; everything else is copied verbatim. */
+const TEXT = /* @__PURE__ */ new Set([
+	".json",
+	".ts",
+	".md"
+]);
+/** A valid package slug: lowercase letters, digits and hyphens. */
+const SLUG = /^[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 })) {
+		const path = join(dir, entry.name);
+		if (entry.isDirectory()) {
+			await substitute(path, values);
+			continue;
+		}
+		if (!TEXT.has(path.slice(path.lastIndexOf(".")))) continue;
+		let text = await readFile(path, "utf8");
+		for (const [placeholder, value] of values) text = text.replaceAll(placeholder, value);
+		await writeFile(path, text);
+	}
+}
+/**
+* The `new` command: copies the template to `packages/<slug>` and fills in the slug and
+* display name.
+*
+* The result is an offline source with `hosts: []` that passes `check` unchanged, so the
+* first thing seen from a new package is green.
+*
+* @throws `CliError` when the slug is not lowercase-letters-digits-hyphens or the folder
+*   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`]);
+	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`);
+}
+//#endregion
+//#region src/lib/zip.ts
+/**
+* The modification time stamped on every entry.
+*
+* A fixed mtime is what makes two builds of the same content byte-identical, which the app
+* relies on to treat one package published by two lists as one package.
+*/
+const EPOCH = /* @__PURE__ */ new Date("2000-01-01T00:00:00Z");
+/**
+* Zips files into bytes that depend only on their names and contents.
+*
+* Entries are written in sorted name order with the fixed mtime and maximum deflate, so
+* the same input always produces the same archive and the same sha256.
+*/
+function deterministicZip(files) {
+	const entries = {};
+	for (const name of Object.keys(files).sort()) entries[name] = [files[name], {
+		mtime: EPOCH,
+		level: 9
+	}];
+	return zipSync(entries);
+}
+//#endregion
+//#region src/commands/pack.ts
+/** How many hex characters of the sha256 the progress line shows. */
+const SHORT_HASH = 12;
+/**
+* The `pack` command: builds each package, rasterises its icon, and zips the package files
+* to `dist/packages/<slug>-v<version>.althsource`.
+*
+* The archive holds `source.json`, `filters.json`, `icon.png`, `main.js` and, when the
+* package has one, `auth.json`. The zip is deterministic, so the same content always gives
+* the same bytes and sha256. The icon is also written on its own to `dist/icons/` for the
+* index to link.
+*/
+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 files = {
+			"source.json": await readFile(join(pkg.dir, "source.json")),
+			"filters.json": await readFile(join(pkg.dir, "filters.json")),
+			"icon.png": icon,
+			"main.js": await readFile(path)
+		};
+		if (existsSync(join(pkg.dir, "auth.json"))) files["auth.json"] = await readFile(join(pkg.dir, "auth.json"));
+		const zip = deterministicZip(files);
+		const out = packagePath(repo, pkg);
+		const iconOut = iconPath(repo, pkg.slug);
+		await mkdir(dirname(out), { recursive: true });
+		await mkdir(dirname(iconOut), { recursive: true });
+		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)}`);
+		packed.push({
+			pkg,
+			path: out,
+			icon: iconOut,
+			bytes: zip.byteLength,
+			sha256
+		});
+	}
+	return packed;
+}
+//#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"
+};
+/** Leading `../` segments left after normalisation, which would escape `dist/`. */
+const TRAVERSAL = /^(\.\.[/\\])+/;
+/** How long after the last change to wait before rebuilding, so an editor's save burst is one build. */
+const DEBOUNCE_MS = 300;
+const OK = 200;
+const NOT_FOUND = 404;
+/**
+* Packs and indexes the whole repository, reporting failures instead of throwing.
+*
+* A broken package while serving is a message on stderr, not a dead server; the previous
+* build stays served until the next successful one.
+*/
+async function rebuild(repo) {
+	try {
+		const packages = await loadPackages(repo);
+		await pack(repo, packages);
+		await indexes(repo, packages);
+	} catch (error) {
+		report(error);
+	}
+}
+/** The first non-internal IPv4 address, which is what a phone on the same wifi can reach. */
+function lanAddress() {
+	for (const list of Object.values(networkInterfaces())) for (const iface of list ?? []) if (iface.family === "IPv4" && !iface.internal) return iface.address;
+	return "127.0.0.1";
+}
+/**
+* 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.
+*/
+async function resolveFile(dist, url) {
+	let path;
+	try {
+		path = normalize(decodeURIComponent(url)).replace(TRAVERSAL, "");
+	} catch {
+		return null;
+	}
+	const file = join(dist, path);
+	return file.startsWith(dist) && existsSync(file) && (await stat(file)).isFile() ? file : null;
+}
+/** A static server over `dist/` that sends `cache-control: no-store` so the app never caches a dev build. */
+function fileServer(dist) {
+	return createServer(async (request, response) => {
+		const file = await resolveFile(dist, request.url ?? "/");
+		if (file === null) {
+			response.writeHead(NOT_FOUND).end();
+			return;
+		}
+		response.writeHead(OK, {
+			"content-type": TYPES[extname(file)] ?? "application/octet-stream",
+			"cache-control": "no-store"
+		});
+		createReadStream(file).pipe(response);
+	});
+}
+/** Watches `packages/` and `lists/` and rebuilds once per burst of changes. */
+function watchRepo(repo) {
+	let timer = null;
+	const trigger = () => {
+		if (timer) clearTimeout(timer);
+		timer = setTimeout(() => {
+			info("change detected, rebuilding");
+			rebuild(repo).catch(report);
+		}, DEBOUNCE_MS);
+	};
+	return [watch(repo.packages, { recursive: true }, trigger), watch(repo.lists, { recursive: true }, trigger)];
+}
+/**
+* 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.
+*/
+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;
+	const url = `http://${lanAddress()}:${bound}/`;
+	info(`serving ${repo.dist} on ${url}`);
+	for (const list of lists) info(`  ${list.name}: ${url}${list.target}/index.json`);
+	return {
+		url,
+		close: () => {
+			for (const watcher of watchers) watcher.close();
+			return new Promise((resolve, reject) => server.close((error) => error ? reject(error) : resolve()));
+		}
+	};
+}
+//#endregion
+//#region src/cli.ts
+/** What `aletheia`, `aletheia --help` and an unknown command print. */
+const USAGE = `usage: aletheia <command> [options]
+
+  build [--only <slug>]     bundle each package's src/index.ts to dist/build/<slug>/main.js
+  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/
+  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]
+                            run a package against the live site in node and print what it returns
+
+Run from anywhere inside a repository that has a packages/ directory.`;
+/** The port `serve` binds when `--port` is not given. */
+const DEFAULT_PORT = "8787";
+/**
+* Parses the arguments and dispatches to one command.
+*
+* Every command runs from the repository found above the working directory, and all but
+* `serve` and `new` load the packages first so a broken manifest fails before any work.
+*
+* @throws `CliError` for an unknown command or a missing positional, plus whatever the
+*   command throws.
+*/
+async function main(argv) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		options: {
+			only: {
+				type: "string",
+				multiple: true
+			},
+			port: { type: "string" },
+			name: { type: "string" },
+			help: {
+				type: "boolean",
+				short: "h"
+			}
+		}
+	});
+	const [command, ...rest] = positionals;
+	if (values.help || command === void 0) {
+		info(USAGE);
+		return;
+	}
+	const repo = findRepo();
+	switch (command) {
+		case "build":
+			await build$1(repo, await loadPackages(repo, values.only));
+			return;
+		case "check":
+			await check(repo, await loadPackages(repo, values.only));
+			return;
+		case "pack":
+			await pack(repo, await loadPackages(repo, values.only));
+			return;
+		case "index":
+			await indexes(repo, await loadPackages(repo));
+			return;
+		case "serve":
+			await serve(repo, Number.parseInt(values.port ?? DEFAULT_PORT, 10));
+			return;
+		case "new": {
+			const [slug] = rest;
+			if (slug === void 0) throw new CliError(["usage: aletheia new <slug> [--name <name>]"]);
+			await create(repo, slug, values.name ?? slug);
+			return;
+		}
+		case "live": {
+			const [slug, series, text] = rest;
+			if (slug === void 0 || series === void 0) throw new CliError(["usage: aletheia live <slug> <series|-> [query]"]);
+			await live(repo, await loadPackage(repo, slug), series, text ?? "");
+			return;
+		}
+		default: throw new CliError([
+			`unknown command "${command}"`,
+			"",
+			USAGE
+		]);
+	}
+}
+main(process.argv.slice(2)).catch((error) => {
+	report(error);
+	process.exit(1);
+});
+//#endregion
+export {};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@aletheia-ios/tools",
+  "version": "0.1.0",
+  "description": "The aletheia CLI: build, check, pack, index and serve source packages",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aletheia-ios/tools.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "packageManager": "pnpm@10.16.1",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "aletheia": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "scripts": {
+    "build": "tsdown && chmod +x dist/cli.js",
+    "typecheck": "tsc",
+    "lint": "biome check .",
+    "format": "biome format --write .",
+    "test": "vitest run --coverage",
+    "check": "pnpm typecheck && pnpm lint && pnpm build && pnpm test && publint",
+    "prepare": "lefthook install"
+  },
+  "dependencies": {
+    "@aletheia-ios/sdk": "^0.1.0",
+    "esbuild": "^0.28.2",
+    "fflate": "^0.8.3",
+    "sharp": "^0.35.4",
+    "zod": "^4.5.4"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.12",
+    "@types/node": "^24.13.3",
+    "@vitest/coverage-v8": "5.0.0",
+    "lefthook": "^2.1.12",
+    "publint": "^0.3.24",
+    "tsdown": "^0.23.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  }
+}

package/template/filters.json

@@ -0,0 +1,9 @@
+[
+  {
+    "kind": "multiSelect",
+    "id": "genre",
+    "name": "Genres",
+    "canExclude": false,
+    "options": [{ "id": "action", "name": "Action" }, { "id": "romance", "name": "Romance" }]
+  }
+]

package/template/fixtures/catalogue.json

@@ -0,0 +1,18 @@
+{
+  "series": [
+    {
+      "slug": "series",
+      "title": "Example Series",
+      "synopsis": "A series that exists only to prove the package loads.",
+      "tags": ["Action"],
+      "authors": ["Example Author"],
+      "chapters": [
+        {
+          "slug": "chapter",
+          "title": "Chapter 1",
+          "pages": ["https://example.com/pages/1.png", "https://example.com/pages/2.png"]
+        }
+      ]
+    }
+  ]
+}

package/template/fixtures/smoke.json

@@ -0,0 +1 @@
+[]

package/template/icon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64"><rect width="64" height="64" rx="14" fill="#2f3542"/><circle cx="32" cy="32" r="14" fill="none" stroke="#ffffff" stroke-width="4"/></svg>

package/template/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@aletheia-source/__SLUG__",
+  "private": true,
+  "type": "module",
+  "devDependencies": {
+    "@aletheia-ios/sdk": "^0.1.0",
+    "typescript": "^7.0.2"
+  }
+}

package/template/source.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "../../node_modules/@aletheia-ios/sdk/dist/json-schema/source.json",
+  "slug": "__SLUG__",
+  "name": "__NAME__",
+  "description": "",
+  "version": "0.1.0",
+  "minAppVersion": "1.4.0",
+  "contractVersion": "1.0",
+  "languages": ["en"],
+  "baseURL": "https://example.com",
+  "referer": "https://example.com",
+  "hosts": [],
+  "contentRating": "mixed",
+  "sort": {
+    "default": "recent",
+    "options": [{ "id": "recent", "name": "Recently Added" }]
+  },
+  "presets": [
+    {
+      "id": "latest",
+      "name": "Latest Updates",
+      "subtitle": "Freshly released",
+      "order": 0,
+      "sort": "recent"
+    }
+  ]
+}

package/template/src/index.ts

@@ -0,0 +1,60 @@
+import type { Source } from "@aletheia-ios/sdk/types";
+import { SourceError } from "@aletheia-ios/sdk/utils";
+import catalogue from "../fixtures/catalogue.json" with { type: "json" };
+
+/**
+ * An offline source: everything it returns is baked in at build time, and `hosts` is `[]`
+ * so the app refuses any network call.
+ *
+ * Replace this file with a real one; the mangadex package in aletheia-ios/sample shows the
+ * shape of a source that talks to a site.
+ */
+const source: Source = {
+  async search(query) {
+    const text = (query.text ?? "").toLowerCase();
+    const items = catalogue.series
+      .filter((series) => text === "" || series.title.toLowerCase().includes(text))
+      .map((series) => ({ slug: series.slug, title: series.title, cover: null, adult: false }));
+    return { items, next: null };
+  },
+
+  async details(seriesSlug) {
+    const series = catalogue.series.find((candidate) => candidate.slug === seriesSlug);
+    if (series === undefined) throw new SourceError("notFound", seriesSlug);
+    return {
+      slug: series.slug,
+      title: series.title,
+      altTitles: [],
+      synopsis: series.synopsis,
+      url: `https://example.com/series/${series.slug}`,
+      classification: "Safe",
+      publication: "Ongoing",
+      covers: [],
+      tags: series.tags,
+      authors: series.authors,
+    };
+  },
+
+  async chapters(seriesSlug) {
+    const series = catalogue.series.find((candidate) => candidate.slug === seriesSlug);
+    if (series === undefined) throw new SourceError("notFound", seriesSlug);
+    return series.chapters.map((chapter, index) => ({
+      slug: chapter.slug,
+      title: chapter.title,
+      number: index + 1,
+      language: "en" as const,
+      scanlator: "__NAME__",
+      url: `https://example.com/series/${series.slug}/${chapter.slug}`,
+      publishedDate: null,
+    }));
+  },
+
+  async content(seriesSlug, chapterSlug) {
+    const series = catalogue.series.find((candidate) => candidate.slug === seriesSlug);
+    const chapter = series?.chapters.find((candidate) => candidate.slug === chapterSlug);
+    if (chapter === undefined) throw new SourceError("notFound", chapterSlug);
+    return chapter.pages.map((url, index) => ({ index, url }));
+  },
+};
+
+export default source;

package/template/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "es2022",
+    "lib": ["es2022"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": ["src", "*.json"]
+}