@hearthlog/tooling 0.0.0-stage → 0.1.1

package/src/compose/module-scaffold.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env npx tsx
+/**
+ * Creating and exporting modules (plan, phases 7.4 and 7.6).
+ *
+ *   pnpm module:new    -- <name> [--feature <id>]   a working module from the template, in modules/<name>/
+ *   pnpm module:export -- <name> --out <directory>  that module as a repository of its own
+ *
+ * A module made here composes without a single edit to the core: it needs only
+ * its directory, and a tenant that lists its feature. The export is the layout
+ * of a module repository: the module at the root with its own license and README, a `files` list that leaves out
+ * the tests, provenance publishing, the platform as peers and dev dependencies, `pnpm test` (which is `hearthlog
+ * check-module`: a site that enables the module builds, then its unit tests run), and the CI and tag-driven release workflows.
+ */
+
+import { cpSync, copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { MODULE_API_VERSION } from "@hearthlog/contracts";
+
+import { REPOSITORY_ROOT } from "../tenants/tenant-config.js";
+
+const TEMPLATE = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "templates", "module");
+const NAME = /^[a-z][a-z0-9-]{1,30}$/;
+
+export interface ScaffoldOptions {
+    name: string;
+    /** The feature id a tenant lists; the module's name by default. Persisted in tenants, so never renamed. */
+    feature?: string;
+    publisher?: string;
+}
+
+function title(name: string): string {
+    return name.charAt(0).toUpperCase() + name.slice(1).replace(/-/g, " ");
+}
+
+/** The files of a minimal, working module: one feature, one page, no data. */
+export function moduleTemplate(options: ScaffoldOptions): Record<string, string> {
+    const { name } = options;
+    if (!NAME.test(name)) throw new Error(`"${name}" must be lowercase letters, digits and hyphens`);
+    const feature = options.feature ?? name;
+    if (!NAME.test(feature)) throw new Error(`The feature id "${feature}" must be lowercase letters, digits and hyphens`);
+    const publisher = options.publisher ?? "org.example";
+    const label = title(name);
+    return {
+        "package.json": `${JSON.stringify({
+            name: `@hearthlog/module-${name}`,
+            version: "0.1.0",
+            license: "AGPL-3.0-only",
+            private: true,
+            type: "module",
+            exports: {
+                "./hearthlog.module.json": "./hearthlog.module.json",
+                "./pages/*.js": "./src/pages/*.ts",
+                "./pages/*.svelte": "./src/pages/*.svelte",
+            },
+            dependencies: { "@hearthlog/sdk": "workspace:*" },
+        }, null, 2)}\n`,
+        "hearthlog.module.json": `${JSON.stringify({
+            manifestVersion: 1,
+            id: `${publisher}.${name}`,
+            package: `@hearthlog/module-${name}`,
+            version: "0.1.0",
+            compatibility: { moduleApi: MODULE_API_VERSION },
+            features: [{
+                id: feature,
+                path: `/${feature}`,
+                label,
+                subtitle: `${label} for your workspace`,
+                keywords: `${name} ${feature}`,
+                navGroup: "Tools",
+                icon: "puzzle-outline",
+            }],
+            routes: [{ path: `/${feature}`, page: "./src/pages/home.svelte", load: "./src/pages/home.ts" }],
+        }, null, 2)}\n`,
+        "src/pages/home.ts": `import { deferLocalPage } from "@hearthlog/sdk/runtime";
+
+export const load = ({ url }: { url: URL }) => deferLocalPage(url, {}, async () => ({}));
+`,
+        "src/pages/home.svelte": `<script lang="ts">
+    import { PageHeader } from "@hearthlog/sdk/ui";
+    import { tenant } from "@hearthlog/sdk/runtime";
+</script>
+
+<svelte:head><title>${label} | {tenant.title}</title></svelte:head>
+<div class="stor-page w-full p-2.5 sm:p-3">
+    <PageHeader title="${label}" />
+    <section class="stor-panel p-[var(--stor-panel-padding)]">
+        <p class="text-sm text-[var(--stor-muted-text)]">${label} is installed.</p>
+    </section>
+</div>
+`,
+        "README.md": `# ${label}
+
+A module for the stor platform. It reaches the app only through \`@hearthlog/sdk\`; see
+\`docs/modules.md\` in the platform repository for what a module may declare (pages, entities,
+repositories, gateway code, startup code, attention badges) and \`pnpm check:modules\` for the
+boundary it enforces.
+`,
+    };
+}
+
+export function scaffoldModule(modulesDirectory: string, options: ScaffoldOptions): string {
+    const directory = join(modulesDirectory, options.name);
+    if (existsSync(directory)) throw new Error(`${relative(REPOSITORY_ROOT, directory)} already exists`);
+    for (const [file, content] of Object.entries(moduleTemplate(options))) {
+        const path = join(directory, file);
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, content);
+    }
+    return directory;
+}
+
+/**
+ * A module as a repository of its own: its files at the root, `workspace:`
+ * references turned into ranges, a license, and a README that says what is
+ * still missing (CI and publishing, which wait for the platform packages).
+ */
+export function exportModule(modulesDirectory: string, name: string, out: string, platformRange = ">=0.1.0 <0.2.0"): string[] {
+    const source = join(modulesDirectory, name);
+    if (!existsSync(join(source, "hearthlog.module.json"))) throw new Error(`modules/${name} is not a module`);
+    if (existsSync(out) && readdirSync(out).length > 0) throw new Error(`${out} is not empty`);
+    cpSync(source, out, { recursive: true, filter: (path) => !/(^|\/)(node_modules|\.git|dist)(\/|$)/.test(path) });
+    const packagePath = join(out, "package.json");
+    const manifest = JSON.parse(readFileSync(packagePath, "utf8")) as {
+        name?: string; private?: boolean; dependencies?: Record<string, string>; peerDependencies?: Record<string, string>; license?: string;
+    };
+    const platform = Object.keys(manifest.dependencies ?? {}).filter((dependency) => dependency.startsWith("@hearthlog/"));
+    // A platform package the sources import must be declared, or the repository cannot resolve it.
+    const imported = new Set<string>();
+    for (const file of listFiles(join(out, "src")).filter((candidate) => /\.(ts|svelte)$/.test(candidate))) {
+        for (const match of readFileSync(file, "utf8").matchAll(/from ["'](@hearthlog\/[a-z-]+)[/"']/g)) imported.add(match[1]!);
+    }
+    const undeclared = [...imported].filter((dependency) => !platform.includes(dependency) && dependency !== manifest.name && !dependency.startsWith("@hearthlog/module-"));
+    if (undeclared.length > 0) throw new Error(`modules/${name} imports ${undeclared.join(", ")} without declaring it in its package.json`);
+    manifest.peerDependencies = { ...(manifest.peerDependencies ?? {}), ...Object.fromEntries(platform.map((dependency) => [dependency, platformRange])) };
+    for (const dependency of platform) delete manifest.dependencies![dependency];
+    if (manifest.dependencies && Object.keys(manifest.dependencies).length === 0) delete manifest.dependencies;
+    delete manifest.private;
+    manifest.license = "AGPL-3.0-only";
+    const root = JSON.parse(readFileSync(join(REPOSITORY_ROOT, "package.json"), "utf8")) as { devDependencies?: Record<string, string>; packageManager?: string };
+    const publishable = {
+        ...manifest,
+        repository: { type: "git", url: `git+https://github.com/hearthlog/hearthlog-module-${name}.git` },
+        publishConfig: { access: "public", provenance: true },
+        files: ["src", ...(existsSync(join(out, "public")) ? ["public"] : []), "hearthlog.module.json", "!**/*.test.ts"],
+        packageManager: root.packageManager,
+        scripts: { test: "hearthlog check-module" },
+        // The platform the module is developed and tested against; the peer range says which releases it accepts.
+        devDependencies: {
+            ...Object.fromEntries([...platform, "@hearthlog/tooling"].sort().map((dependency) => [dependency, platformRange])),
+            vitest: root.devDependencies?.vitest ?? "^4.1.11",
+        },
+    };
+    writeFileSync(packagePath, `${JSON.stringify(publishable, null, 2)}\n`);
+    mkdirSync(join(out, ".github", "workflows"), { recursive: true });
+    copyFileSync(join(TEMPLATE, "gitignore.tmpl"), join(out, ".gitignore"));
+    copyFileSync(join(TEMPLATE, "gitleaks.toml.tmpl"), join(out, ".gitleaks.toml"));
+    // vitest's esbuild needs its install script; pnpm 10 asks for it by name.
+    writeFileSync(join(out, "pnpm-workspace.yaml"), "onlyBuiltDependencies:\n  - esbuild\n");
+    copyFileSync(join(TEMPLATE, "ci.yml.tmpl"), join(out, ".github", "workflows", "ci.yml"));
+    copyFileSync(join(TEMPLATE, "release.yml.tmpl"), join(out, ".github", "workflows", "release.yml"));
+    cpSync(join(REPOSITORY_ROOT, "LICENSE"), join(out, "LICENSE"));
+    const readme = join(out, "README.md");
+    const existing = existsSync(readme) ? readFileSync(readme, "utf8").trimEnd() : `# ${title(name)}`;
+    writeFileSync(readme, `${existing}\n\n## Status\n\nIt installs against \`@hearthlog/sdk\` ${platformRange}.\n\n\`\`\`bash\npnpm install\npnpm test   # generates a site that enables this module, installs it, builds it, then runs the unit tests\n\`\`\`\n\nRelease: set \`version\` in \`package.json\`, commit, and push the tag \`v<version>\`; the release workflow publishes with provenance after approval.\n`);
+    return listFiles(out).map((file) => relative(out, file)).sort();
+}
+
+function listFiles(directory: string): string[] {
+    return readdirSync(directory).flatMap((entry) => {
+        const path = join(directory, entry);
+        return statSync(path).isDirectory() ? listFiles(path) : [path];
+    });
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    const args = process.argv.slice(2).filter((argument) => argument !== "--");
+    const [command, name] = args;
+    const value = (flag: string) => {
+        const index = args.indexOf(flag);
+        return index === -1 ? undefined : args[index + 1];
+    };
+    const modules = join(REPOSITORY_ROOT, "modules");
+    if (command === "new" && name) {
+        const directory = scaffoldModule(modules, { name, feature: value("--feature") });
+        console.log(`Created ${relative(REPOSITORY_ROOT, directory)}. Next:\n  1. pnpm install\n  2. pnpm generate:modules && pnpm generate:entities\n  3. add "${value("--feature") ?? name}" to a site's features in tenants.json, then pnpm compose`);
+    } else if (command === "export" && name && value("--out")) {
+        const files = exportModule(modules, name, resolve(value("--out")!));
+        console.log(`Exported ${files.length} file(s) of modules/${name} to ${resolve(value("--out")!)}`);
+    } else {
+        console.error("Usage: pnpm module:new -- <name> [--feature <id>]\n       pnpm module:export -- <name> --out <directory>");
+        process.exit(1);
+    }
+}

package/src/deploy/artifact-compare.ts

@@ -0,0 +1,93 @@
+/**
+ * What a built site ships, reduced to what must not change when the same site is built somewhere else (another
+ * checkout, another lockfile): its routes, the names of its chunks without their content hashes, its offline precache
+ * list, the gateway table, the Ledger event contracts, and the generated Worker configuration. File hashes are not part
+ * of the comparison (a different install changes them); how many files agree byte for byte is reported only.
+ *
+ * `hearthlog artifact compare --site <id> --against <host root>` builds the comparison of the host in the current
+ * directory with another built host (the handover gate of a site that moves into a repository of its own), and
+ * `scripts/tarball-equivalence.ts` uses the same functions to compare a workspace build with one made from tarballs.
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, relative } from "node:path";
+
+import { siteBuildDirectory } from "../tenants/wrangler-config.js";
+
+export interface Fingerprint {
+    routes: string[];
+    chunks: string[];
+    precache: string[];
+    contents: string[];
+    gateway: string;
+    contracts: string;
+    wrangler: string;
+}
+
+function walk(directory: string): string[] {
+    if (!existsSync(directory)) return [];
+    return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+        const path = join(directory, entry.name);
+        return entry.isDirectory() ? walk(path) : [path];
+    });
+}
+
+/** `name-AbC123xy.js` and `AbC123xy.js` become `name-#.js` and `#.js`: Vite and Kit name chunks by content hash. */
+export function unhash(path: string): string {
+    return path.replace(/(^|[-./])[A-Za-z0-9_-]{8}(?=\.[a-z0-9]+$)/, "$1#");
+}
+
+/** The fingerprint of the site built in `root` (its `build` directory, Kit's output directory, and `.generated`). */
+export async function fingerprint(root: string, siteId: string, kitDirectory: string = join(root, ".svelte-kit")): Promise<Fingerprint> {
+    const shell = dirname(createRequire(join(root, "package.json")).resolve("@hearthlog/shell/package.json"));
+    const offline = await import(join(shell, "src/service-worker/offline-bundle.ts"));
+    const buildDirectory = join(root, siteBuildDirectory(siteId));
+    const generated = join(root, ".generated");
+    if (!existsSync(join(buildDirectory, "service-worker.js"))) throw new Error(`${root} has no build of ${siteId}: run its build first`);
+    const precache: string[] = offline
+        .precacheEntries([...offline.parseServiceWorkerManifestPaths(readFileSync(join(buildDirectory, "service-worker.js"), "utf8")), ...offline.PRECACHE_EXTRA_PATHS].map((path: string) => ({ path, revision: null })))
+        .map((entry: { url: string }) => unhash(entry.url));
+    const manifest = readFileSync(join(kitDirectory, "output/server/manifest.js"), "utf8");
+    const routes = [...manifest.matchAll(/id:\s*"([^"]*)"/g)].map((match) => match[1]!).sort();
+    const paths = walk(join(buildDirectory, "_app"));
+    return {
+        routes,
+        chunks: paths.map((path) => unhash(relative(buildDirectory, path))).sort(),
+        precache: precache.sort(),
+        contents: paths.map((path) => createHash("sha256").update(readFileSync(path)).digest("hex")),
+        gateway: readFileSync(join(generated, "sites", siteId, "server-modules.ts"), "utf8"),
+        contracts: readFileSync(join(generated, "src/event-schemas.generated.ts"), "utf8"),
+        wrangler: readFileSync(join(generated, "sites", siteId, "wrangler.jsonc"), "utf8"),
+    };
+}
+
+/** What differs between two fingerprints; empty when the site is the same. `names` says which side each is in the messages. */
+export function compareFingerprints(label: string, left: Fingerprint, right: Fingerprint, names: [string, string] = ["left", "right"]): { problems: string[]; identical: number } {
+    const problems: string[] = [];
+    const list = (name: string, a: string[], b: string[]) => {
+        // A multiset difference: after hashes are stripped many chunks share a name, so counts matter.
+        const only = (x: string[], y: string[]) => {
+            const remaining = [...y];
+            return x.filter((item) => {
+                const index = remaining.indexOf(item);
+                if (index < 0) return true;
+                remaining.splice(index, 1);
+                return false;
+            });
+        };
+        const missing = only(a, b);
+        const extra = only(b, a);
+        if (missing.length + extra.length > 0) {
+            problems.push(`${label}: ${name} differ (${missing.length} only in the ${names[0]} build, ${extra.length} only in the ${names[1]} build)\n    - ${missing.slice(0, 8).join("\n    - ")}\n    + ${extra.slice(0, 8).join("\n    + ")}`);
+        }
+    };
+    list("routes", left.routes, right.routes);
+    list("chunk names", left.chunks, right.chunks);
+    list("precache entries", left.precache, right.precache);
+    if (left.gateway !== right.gateway) problems.push(`${label}: the gateway table differs`);
+    if (left.contracts !== right.contracts) problems.push(`${label}: the Ledger contracts differ`);
+    if (left.wrangler !== right.wrangler) problems.push(`${label}: the generated Worker config differs`);
+    return { problems, identical: left.contents.filter((hash) => right.contents.includes(hash)).length };
+}

package/src/deploy/artifact.ts

@@ -0,0 +1,127 @@
+#!/usr/bin/env npx tsx
+/**
+ * `hearthlog artifact manifest|verify --site <id>`: the seal between a tenant's build job and its deploy job.
+ *
+ * The build job has no secrets. It builds the site (`build/<id>`, the generated files, the Gallery Worker) and seals
+ * them in `artifact-manifest.json`: the hash of every file, the hash of the lockfile, and one hash over all of it. The
+ * deploy job, which does hold secrets, restores the files, installs the same lockfile, and runs `verify` first, so
+ * what it deploys is what the build job made and nothing it had to build itself.
+ *
+ * `compare --site <id> --against <root>` is the handover gate of a site that moves into a repository of its own: its
+ * structure (routes, chunk names, precache list, gateway table, Ledger contracts, Worker config) must equal that of the
+ * same site built in the other checkout (see artifact-compare.ts).
+ */
+
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { compareFingerprints, fingerprint } from "./artifact-compare.js";
+import { GENERATED_DIRECTORY } from "../compose/compose-modules.js";
+import { REPOSITORY_ROOT } from "../tenants/tenant-config.js";
+import { siteBuildDirectory } from "../tenants/wrangler-config.js";
+
+export const MANIFEST_FILE = "artifact-manifest.json";
+
+export interface ArtifactManifest {
+    schemaVersion: 1;
+    site: string;
+    /** Hash of the lockfile the build installed. */
+    lockfile: string;
+    /** Hash of every file, by path relative to the host root. */
+    files: Record<string, string>;
+    /** One hash over the lockfile and all the file hashes. */
+    sha256: string;
+}
+
+const sha256 = (data: Buffer | string) => createHash("sha256").update(data).digest("hex");
+
+function filesUnder(directory: string): string[] {
+    if (!existsSync(directory)) return [];
+    return readdirSync(directory, { withFileTypes: true })
+        .filter((entry) => entry.name !== "node_modules" && entry.name !== ".DS_Store")
+        .sort((a, b) => a.name.localeCompare(b.name))
+        .flatMap((entry) => (entry.isDirectory() ? filesUnder(join(directory, entry.name)) : [join(directory, entry.name)]));
+}
+
+function digest(lockfile: string, files: Record<string, string>): string {
+    return sha256([lockfile, ...Object.entries(files).sort(([a], [b]) => a.localeCompare(b)).map(([path, hash]) => `${path}\0${hash}`)].join("\n"));
+}
+
+/** The paths a deploy needs: the site's build output and every generated file. */
+export function artifactPaths(siteId: string, root: string = REPOSITORY_ROOT): string[] {
+    return [join(root, siteBuildDirectory(siteId)), join(root, relative(REPOSITORY_ROOT, GENERATED_DIRECTORY))];
+}
+
+export function buildManifest(siteId: string, root: string = REPOSITORY_ROOT, paths: string[] = artifactPaths(siteId, root)): ArtifactManifest {
+    const lockfile = sha256(readFileSync(join(root, "pnpm-lock.yaml")));
+    const files: Record<string, string> = {};
+    for (const file of paths.flatMap(filesUnder)) files[relative(root, file).split(sep).join("/")] = sha256(readFileSync(file));
+    return { schemaVersion: 1, site: siteId, lockfile, files, sha256: digest(lockfile, files) };
+}
+
+/** Why the files on disk are not the ones the manifest sealed; empty when they are. */
+export function manifestProblems(manifest: ArtifactManifest, root: string = REPOSITORY_ROOT, paths: string[] = artifactPaths(manifest.site, root)): string[] {
+    const problems: string[] = [];
+    const current = buildManifest(manifest.site, root, paths);
+    if (manifest.schemaVersion !== 1) problems.push(`the manifest has schema version ${String(manifest.schemaVersion)}, not 1`);
+    if (current.lockfile !== manifest.lockfile) problems.push("pnpm-lock.yaml is not the lockfile the build installed");
+    for (const path of Object.keys(manifest.files)) {
+        if (!(path in current.files)) problems.push(`${path} is missing`);
+        else if (current.files[path] !== manifest.files[path]) problems.push(`${path} changed since the build`);
+    }
+    for (const path of Object.keys(current.files)) if (!(path in manifest.files)) problems.push(`${path} was not part of the build`);
+    if (digest(manifest.lockfile, manifest.files) !== manifest.sha256) problems.push("the manifest's own hash does not match its entries");
+    return problems;
+}
+
+async function main(argv: string[]): Promise<void> {
+    const [command, ...rest] = argv;
+    const siteIndex = rest.indexOf("--site");
+    const siteId = siteIndex === -1 ? undefined : rest[siteIndex + 1];
+    if ((command !== "manifest" && command !== "verify" && command !== "compare") || !siteId) {
+        console.error("Usage: hearthlog artifact manifest --site <id>\n       hearthlog artifact verify   --site <id>\n       hearthlog artifact compare  --site <id> --against <built host root>");
+        process.exit(1);
+    }
+    if (command === "compare") {
+        const againstIndex = rest.indexOf("--against");
+        const other = againstIndex === -1 ? undefined : rest[againstIndex + 1];
+        if (!other) throw new Error("Usage: hearthlog artifact compare --site <id> --against <built host root>");
+        const here = await fingerprint(REPOSITORY_ROOT, siteId);
+        const there = await fingerprint(resolve(other), siteId);
+        const { problems, identical } = compareFingerprints(siteId, there, here, ["other", "this"]);
+        console.log(`${siteId}: ${here.routes.length} routes, ${here.chunks.length} chunks, ${here.precache.length} precache entries; ${identical} of ${there.contents.length} files under _app are byte-identical (informational)`);
+        if (problems.length > 0) {
+            console.error(`This build does not match the other one:\n${problems.join("\n")}`);
+            process.exit(1);
+        }
+        console.log(`The build of ${siteId} here ships what the build in ${resolve(other)} ships.`);
+        return;
+    }
+    const path = join(REPOSITORY_ROOT, MANIFEST_FILE);
+    if (command === "manifest") {
+        const manifest = buildManifest(siteId);
+        if (Object.keys(manifest.files).length === 0) throw new Error(`There is nothing to seal for ${siteId}: build it first`);
+        writeFileSync(path, `${JSON.stringify(manifest, null, 2)}\n`);
+        console.log(`Sealed ${Object.keys(manifest.files).length} files of ${siteId}: ${manifest.sha256}`);
+        return;
+    }
+    const manifest = JSON.parse(readFileSync(path, "utf8")) as ArtifactManifest;
+    if (manifest.site !== siteId) throw new Error(`The manifest is for ${manifest.site}, not ${siteId}`);
+    const problems = manifestProblems(manifest);
+    if (problems.length > 0) {
+        console.error(`The artifact does not match its manifest:\n${problems.slice(0, 20).map((problem) => `  - ${problem}`).join("\n")}`);
+        process.exit(1);
+    }
+    console.log(`The artifact of ${siteId} matches its manifest: ${manifest.sha256}`);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    try {
+        await main(process.argv.slice(2));
+    } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}

package/src/deploy/async-utils.ts

@@ -0,0 +1,71 @@
+import { availableParallelism } from "node:os";
+
+/**
+ * Resolve a bounded worker-pool size. The default leaves one CPU available for
+ * the orchestrator and caps parallel Cloudflare/build work at four workers.
+ */
+export function defaultConcurrency(): number {
+    return Math.min(4, Math.max(1, availableParallelism() - 1));
+}
+
+export function parseConcurrency(
+    value: string | undefined,
+    fallback = defaultConcurrency(),
+): number {
+    if (value === undefined || value.trim() === "") return fallback;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 32) {
+        throw new Error("Concurrency must be an integer between 1 and 32");
+    }
+    return parsed;
+}
+
+/** Run independent work with a fixed-size pool while preserving result order. */
+export async function mapWithConcurrency<T, R>(
+    items: readonly T[],
+    concurrency: number,
+    task: (item: T, index: number) => Promise<R>,
+): Promise<R[]> {
+    if (items.length === 0) return [];
+    if (!Number.isInteger(concurrency) || concurrency < 1) {
+        throw new Error("Concurrency must be a positive integer");
+    }
+
+    const results = new Array<R>(items.length);
+    let nextIndex = 0;
+
+    async function worker(): Promise<void> {
+        while (true) {
+            const index = nextIndex++;
+            if (index >= items.length) return;
+            results[index] = await task(items[index], index);
+        }
+    }
+
+    const workerResults = await Promise.allSettled(
+        Array.from(
+            { length: Math.min(concurrency, items.length) },
+            () => worker(),
+        ),
+    );
+    const failure = workerResults.find(
+        (result): result is PromiseRejectedResult => result.status === "rejected",
+    );
+    if (failure) throw failure.reason;
+    return results;
+}
+
+export async function settleWithConcurrency<T>(
+    items: readonly T[],
+    concurrency: number,
+    task: (item: T, index: number) => Promise<void>,
+): Promise<PromiseSettledResult<void>[]> {
+    return await mapWithConcurrency(items, concurrency, async (item, index) => {
+        try {
+            await task(item, index);
+            return { status: "fulfilled", value: undefined } as const;
+        } catch (reason) {
+            return { status: "rejected", reason } as const;
+        }
+    });
+}

package/src/deploy/backup-tenants.ts

@@ -0,0 +1,139 @@
+#!/usr/bin/env npx tsx
+/**
+ * Tenant Backup
+ *
+ * Exports every site's Ledger application using the canonical
+ * ledger-logical-export format (see packages/ledger/scripts/logical-backup.ts). Sites
+ * must have a stored credential from `pnpm provision:tenants`.
+ *
+ * Environment:
+ *   LEDGER_BASE_URL      e.g. http://127.0.0.1:8787 (local) or the deployed
+ *                        Ledger worker URL
+ *   LEDGER_ADMIN_TOKEN   administrator token, used to list all applications
+ *                        so apps outside tenants.json are reported
+ *   LEDGER_OUTPUT_ROOT   optional directory for the exports (default: .wrangler/backups)
+ *
+ * Usage: pnpm ledger:export:tenants [-- --output-suffix my-run]
+ */
+
+import { spawn } from "node:child_process";
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+
+import {
+    loadTenantConfig,
+    REPOSITORY_ROOT,
+} from "../tenants/tenant-config.js";
+import {
+    legacyTenantCredentialPath,
+    tenantCredentialPath,
+} from "./ledger-credential.js";
+import { ledgerScript } from "./ledger-scripts.js";
+
+const baseUrl = (process.env.LEDGER_BASE_URL ?? "").replace(/\/$/, "");
+const adminToken = process.env.LEDGER_ADMIN_TOKEN ?? "";
+if (!baseUrl || !adminToken) {
+    console.error(
+        "LEDGER_BASE_URL and LEDGER_ADMIN_TOKEN are required " +
+            "(see ledger/.dev.vars.example for local values).",
+    );
+    process.exit(1);
+}
+
+const args = process.argv.slice(2);
+const suffixIndex = args.indexOf("--output-suffix");
+const suffix = suffixIndex !== -1 ? `-${args[suffixIndex + 1]}` : "";
+const stamp = new Date().toISOString().replace(/\D/g, "").slice(0, 14);
+const outputRoot =
+    process.env.LEDGER_OUTPUT_ROOT ?? join(REPOSITORY_ROOT, ".wrangler", "backups");
+
+const { sites } = await loadTenantConfig();
+const siteByAppName = new Map(sites.map((site) => [site.ledgerAppName, site]));
+
+const response = await fetch(`${baseUrl}/admin/v1/apps`, {
+    headers: { Authorization: `Bearer ${adminToken}` },
+});
+if (!response.ok) {
+    console.error(`Listing applications failed with ${response.status}`);
+    process.exit(1);
+}
+const { apps } = (await response.json()) as { apps: Array<{ id: string; name: string; revokedAt: string | null }> };
+
+const activeApps = apps.filter((app) => app.revokedAt === null);
+const failures: string[] = [];
+const skipped: string[] = [];
+
+await mkdir(outputRoot, { recursive: true, mode: 0o700 });
+
+for (const app of activeApps) {
+    const site = siteByAppName.get(app.name);
+    if (!site) {
+        skipped.push(app.name);
+        console.warn(`No tenants.json site for app "${app.name}" (${app.id}); skipped.`);
+        continue;
+    }
+
+    let token: string;
+    try {
+        const credentialFile = tenantCredentialPath(site.id);
+        const fallbackCredentialFile = legacyTenantCredentialPath(site.id);
+        const credential = JSON.parse(
+            await import("node:fs/promises").then((fs) =>
+                fs.readFile(
+                    credentialFile,
+                    "utf8",
+                ).catch(() => fs.readFile(fallbackCredentialFile, "utf8")),
+            ),
+        ) as {
+            appId: string;
+            token: string;
+        };
+        if (credential.appId !== app.id) {
+            skipped.push(app.name);
+            console.warn(
+                `Stored credential for ${site.id} points at ${credential.appId}, ` +
+                    `not ${app.id}; run pnpm provision:tenants first.`,
+            );
+            continue;
+        }
+        token = credential.token;
+    } catch {
+        skipped.push(app.name);
+        console.warn(
+            `No stored credential for site ${site.id}; run pnpm provision:tenants first.`,
+        );
+        continue;
+    }
+
+    const output = join(outputRoot, `${app.name}${suffix}-${stamp}`);
+    console.log(`\nExporting app "${app.name}" (site ${site.id}) into ${output}...`);
+    const exitCode = await new Promise<number | null>((resolvePromise) => {
+        const backup = ledgerScript("logical-backup", ["export", "--output", output]);
+        const child = spawn(
+            backup.command,
+            backup.args,
+            {
+                cwd: REPOSITORY_ROOT,
+                stdio: "inherit",
+                env: {
+                    ...process.env,
+                    LEDGER_BASE_URL: baseUrl,
+                    LEDGER_AUTH_TOKEN: token,
+                },
+            },
+        );
+        child.once("error", () => resolvePromise(1));
+        child.once("exit", (code) => resolvePromise(code));
+    });
+    if (exitCode !== 0) failures.push(app.name);
+}
+
+console.log(
+    `\nBackup finished: ${activeApps.length - skipped.length - failures.length} exported, ` +
+        `${skipped.length} skipped, ${failures.length} failed.`,
+);
+if (skipped.length > 0) console.log(`Skipped apps: ${skipped.join(", ")}`);
+if (failures.length > 0) {
+    console.error(`Failed apps: ${failures.join(", ")}`);
+    process.exitCode = 1;
+}