@hearthlog/tooling 0.0.0-stage → 0.1.1

package/src/deploy/deploy-runner.ts

@@ -0,0 +1,240 @@
+/**
+ * Shared deployment primitives for the CI-native pipelines.
+ *
+ * This replaces the former compensating-transaction machinery: it only runs
+ * commands, invokes Wrangler, loads the deploy units, and builds one tenant
+ * bundle. Rollback is delegated to Cloudflare's native per-Worker version
+ * history (`wrangler deployments` / `wrangler rollback`).
+ *
+ * Wrangler authentication:
+ *   - CI (`CI`/`GITHUB_ACTIONS`) uses CLOUDFLARE_API_TOKEN for deploys and
+ *     secret pushes, exactly like the old single-Worker `deploy.yml`.
+ *   - Local runs keep using the Wrangler OAuth session unless
+ *     `STOR_WRANGLER_API_TOKEN=1` is set, because the local Access-only API
+ *     token cannot push Worker secrets.
+ */
+
+import { spawn } from "node:child_process";
+import { rm } from "node:fs/promises";
+import { devNull } from "node:os";
+import { join } from "node:path";
+
+import { REPOSITORY_ROOT } from "../tenants/tenant-config.js";
+import { resolveFrontendWranglerTarget, siteBuildDirectory } from "../tenants/wrangler-config.js";
+
+
+export interface DeployUnit {
+	/** Journal key: "backend" or the site id. */
+	key: string;
+	label: string;
+	config: string;
+	/** --env value; null means the config is standalone (no --env). */
+	envKey: string | null;
+	kind: "backend" | "frontend";
+}
+
+export interface RunCommandOptions {
+	captureStdout?: boolean;
+	env?: NodeJS.ProcessEnv;
+	/** Written to the child's stdin and closed; used by `wrangler secret bulk`. */
+	input?: string;
+}
+
+export interface CommandResult {
+	code: number;
+	stdout: string;
+	stderr: string;
+}
+
+function quote(value: string): string {
+	return /^[A-Za-z0-9_./:@%=-]+$/.test(value) ? value : JSON.stringify(value);
+}
+
+export function formatCommand(command: string, args: string[]): string {
+	return [command, ...args].map(quote).join(" ");
+}
+
+/** Run a command, inheriting stdio unless stdout capture is requested. */
+export async function runCommand(
+	command: string,
+	args: string[],
+	options: RunCommandOptions = {},
+): Promise<string> {
+	const rendered = formatCommand(command, args);
+	console.log(`\n$ ${rendered}`);
+
+	return await new Promise<string>((resolvePromise, rejectPromise) => {
+		const child = spawn(command, args, {
+			cwd: REPOSITORY_ROOT,
+			env: options.env ?? process.env,
+			stdio: [
+				options.input === undefined ? "inherit" : "pipe",
+				options.captureStdout ? "pipe" : "inherit",
+				"inherit",
+			],
+		});
+		let stdout = "";
+		if (options.captureStdout && child.stdout) child.stdout.setEncoding("utf8");
+		child.stdout?.on("data", (chunk: string) => {
+			stdout += chunk;
+		});
+		if (options.input !== undefined) child.stdin?.end(options.input);
+		child.once("error", rejectPromise);
+		child.once("exit", (code, signal) => {
+			if (code === 0) {
+				resolvePromise(stdout);
+				return;
+			}
+			const reason = signal
+				? `signal ${signal}`
+				: `exit code ${code ?? "unknown"}`;
+			rejectPromise(new Error(`Command failed with ${reason}: ${rendered}`));
+		});
+	});
+}
+
+/**
+ * Run a command without rejecting on a non-zero exit, capturing both streams.
+ * Used for idempotent provisioning calls that must distinguish "already
+ * exists" from a real failure.
+ */
+export async function runCommandResult(
+	command: string,
+	args: string[],
+	options: RunCommandOptions = {},
+): Promise<CommandResult> {
+	const rendered = formatCommand(command, args);
+	console.log(`\n$ ${rendered}`);
+
+	return await new Promise<CommandResult>((resolvePromise, rejectPromise) => {
+		const child = spawn(command, args, {
+			cwd: REPOSITORY_ROOT,
+			env: options.env ?? process.env,
+			stdio: [
+				options.input === undefined ? "inherit" : "pipe",
+				"pipe",
+				"pipe",
+			],
+		});
+		let stdout = "";
+		let stderr = "";
+		child.stdout?.setEncoding("utf8");
+		child.stderr?.setEncoding("utf8");
+		child.stdout?.on("data", (chunk: string) => {
+			stdout += chunk;
+		});
+		child.stderr?.on("data", (chunk: string) => {
+			stderr += chunk;
+		});
+		if (options.input !== undefined) child.stdin?.end(options.input);
+		child.once("error", rejectPromise);
+		child.once("exit", (code, signal) => {
+			if (signal) {
+				rejectPromise(
+					new Error(`Command failed with signal ${signal}: ${rendered}`),
+				);
+				return;
+			}
+			resolvePromise({ code: code ?? -1, stdout, stderr });
+		});
+	});
+}
+
+export function isCi(): boolean {
+	return Boolean(
+		process.env.CI || process.env.GITHUB_ACTIONS || process.env.STOR_CI,
+	);
+}
+
+/** Environment for Wrangler invocations. See the module header. */
+export function wranglerEnvironment(
+	overrides: NodeJS.ProcessEnv = {},
+): NodeJS.ProcessEnv {
+	const environment: NodeJS.ProcessEnv = { ...process.env, ...overrides };
+	if (!isCi() && process.env.STOR_WRANGLER_API_TOKEN !== "1") {
+		delete environment.CLOUDFLARE_API_TOKEN;
+		delete environment.CLOUDFLARE_API_KEY;
+		delete environment.CLOUDFLARE_API_EMAIL;
+	}
+	return environment;
+}
+
+/**
+ * The project's own wrangler binary. Calling it directly (not through
+ * `pnpm exec`) keeps `--env-file` away from pnpm's standalone executable,
+ * which would read the flag as its own Node option and fail.
+ */
+export const WRANGLER_BIN = join(REPOSITORY_ROOT, "node_modules", ".bin", "wrangler");
+
+export function wranglerArgs(
+	config: string,
+	envKey: string | null,
+	args: string[],
+): string[] {
+	const tail = envKey === null ? [] : ["--env", envKey];
+	return [
+		...args,
+		"--config",
+		config,
+		...tail,
+		"--env-file",
+		devNull,
+	];
+}
+
+export async function runWrangler(
+	config: string,
+	envKey: string | null,
+	args: string[],
+	options: RunCommandOptions = {},
+): Promise<string> {
+	return await runCommand(WRANGLER_BIN, wranglerArgs(config, envKey, args), {
+		...options,
+		env: wranglerEnvironment(options.env),
+	});
+}
+
+/** The wrangler target for one site, resolving generated tenant configs. */
+export async function frontendUnit(siteId: string): Promise<DeployUnit> {
+	const target = resolveFrontendWranglerTarget(siteId);
+	return {
+		key: siteId,
+		label: `frontend ${siteId}`,
+		config: target.config,
+		envKey: target.envKey,
+		kind: "frontend",
+	};
+}
+
+/**
+ * Build one tenant into its Wrangler `assets.directory`.
+ *
+ * `pnpm build` writes the site's catalog, tenant module, and app shell to
+ * `.generated/` first, so the Worker bundles that site's modules; call
+ * `restoreGenerated()` when the site's Wrangler commands are done. `kit.outDir` is left at the default
+ * `.svelte-kit`. The old parallel transaction deploy also pointed SvelteKit's
+ * outDir at an isolated directory; that made SvelteKit and `vite-plugin-pwa`
+ * race over `output/client/service-worker.js` on a clean CI checkout, so it is
+ * gone. One tenant builds per CI job / local invocation, so sharing the
+ * default `.svelte-kit` is safe.
+ */
+export async function buildTenant(siteId: string): Promise<void> {
+	const output = join(REPOSITORY_ROOT, siteBuildDirectory(siteId));
+	await rm(output, { recursive: true, force: true });
+	await runCommand("pnpm", ["build"], {
+		env: {
+			...process.env,
+			VITE_STOR_TENANT: siteId,
+		},
+	});
+}
+
+/**
+ * Build the default site's generated files again. A tenant build leaves `.generated/` with that site's
+ * (smaller) catalog, and the tools that read every site's configuration need the default site's, which
+ * covers them all.
+ */
+export async function restoreGenerated(): Promise<void> {
+	const { VITE_STOR_TENANT: _site, ...environment } = process.env;
+	await runCommand("pnpm", ["build:generated", "--quiet"], { env: environment });
+}

package/src/deploy/deploy-tenant.ts

@@ -0,0 +1,170 @@
+#!/usr/bin/env npx tsx
+/**
+ * Build and deploy one tenant's frontend Worker.
+ *
+ * This is the CI-native replacement for the per-tenant leg of the old
+ * compensating transaction. It validates the bundle with a Wrangler dry-run,
+ * then deploys. Roll back with Cloudflare's native per-Worker versions:
+ *
+ *   pnpm exec wrangler deployments list --config .generated/sites/<site>/wrangler.jsonc
+ *   pnpm exec wrangler rollback <deployment-id> --config .generated/sites/<site>/wrangler.jsonc
+ *
+ * Usage:
+ *   pnpm deploy:tenant -- --site st
+ *   pnpm deploy:tenant -- --site st --dry-run
+ *   pnpm deploy:tenant -- --site st --skip-build
+ *
+ * A site on its own stack (tenants/<id>/deployment.json) also deploys its own
+ * public Gallery and calendar feed Workers after the frontend, because the
+ * feed Worker binds to the frontend's renderer.
+ */
+
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { relative } from "node:path";
+
+import { buildTenant, frontendUnit, restoreGenerated, runWrangler } from "./deploy-runner.js";
+import { buildGalleryPublic } from "../public-workers/build-gallery-public.js";
+import { generateHostConfigs, hostWorkerConfigPath, hostWorkerDirectory } from "../tenants/host-configs.js";
+import {
+	loadTenantConfig,
+	REPOSITORY_ROOT,
+	siteById,
+	type ResolvedSite,
+} from "../tenants/tenant-config.js";
+import { generateTenantWranglerConfigs } from "../tenants/wrangler-config.js";
+
+interface Options {
+	site: string;
+	dryRun: boolean;
+	skipBuild: boolean;
+	help: boolean;
+}
+
+function usage(): string {
+	return `Build and deploy one tenant frontend Worker.
+
+Usage:
+  pnpm deploy:tenant -- --site <id> [options]
+
+Options:
+  --site <id>                 Site id from tenants.json (required)
+  --dry-run                   Build and bundle without uploading
+  --skip-build                Deploy the existing build/<site> output
+  -h, --help                  Show this help`;
+}
+
+export function parseOptions(argv: string[]): Options {
+	const options: Options = {
+		site: "",
+		dryRun: false,
+		skipBuild: false,
+		help: false,
+	};
+	for (let index = 0; index < argv.length; index += 1) {
+		const argument = argv[index];
+		switch (argument) {
+			case "--":
+				break;
+			case "--site": {
+				const site = argv[index + 1]?.trim();
+				if (!site) throw new Error("--site requires a site id");
+				options.site = site;
+				index += 1;
+				break;
+			}
+			case "--dry-run":
+				options.dryRun = true;
+				break;
+			case "--skip-build":
+				options.skipBuild = true;
+				break;
+			case "--help":
+			case "-h":
+				options.help = true;
+				break;
+			default:
+				throw new Error(`Unknown option: ${argument}`);
+		}
+	}
+	return options;
+}
+
+export async function deploySite(options: Options): Promise<void> {
+	if (!options.site) throw new Error("--site requires a site id");
+	const { sites } = await loadTenantConfig();
+	const site = siteById(sites, options.site);
+
+	// Generated tenant wrangler configs are derived from tenants.json.
+	await generateTenantWranglerConfigs(site.id);
+
+	// The build leaves the site's own catalog in `.generated/`, which its Worker bundles; the commands
+	// that read every site's configuration run after it is restored.
+	const unit = await frontendUnit(site.id);
+	try {
+		if (!options.skipBuild) {
+			await buildTenant(site.id);
+		}
+		console.log(`\nValidating ${unit.label}...`);
+		await runWrangler(unit.config, unit.envKey, ["deploy", "--dry-run"]);
+		if (!options.dryRun) {
+			console.log(`\nDeploying ${unit.label}...`);
+			await runWrangler(unit.config, unit.envKey, ["deploy"]);
+			console.log(`Deployed ${site.id}.`);
+		}
+	} finally {
+		if (!options.skipBuild) await restoreGenerated();
+	}
+
+	if (options.dryRun) {
+		await deployOwnPublicWorkers(site, true, options.skipBuild);
+		console.log(`\nDry run complete for ${site.id}. Nothing was uploaded.`);
+		return;
+	}
+	await deployOwnPublicWorkers(site, false, options.skipBuild);
+}
+
+/** The public Workers of a site on its own stack; shared sites use the shared ones. */
+async function deployOwnPublicWorkers(site: ResolvedSite, dryRun: boolean, skipBuild: boolean): Promise<void> {
+	if (!site.deployment) return;
+	const args = ["deploy", ...(dryRun ? ["--dry-run"] : [])];
+	if (site.features.includes("gallery")) {
+		if (skipBuild) {
+			// A release built elsewhere carries its Worker bundle; only the configs are written here.
+			await generateHostConfigs(site.id);
+			if (!existsSync(join(hostWorkerDirectory(site.id, "gallery-public"), "dist", "worker", "index.js"))) {
+				throw new Error(`--skip-build needs the built public Gallery Worker: run hearthlog gallery-public:build --site ${site.id} first`);
+			}
+		} else {
+			await buildGalleryPublic(site.id);
+		}
+		const config = relative(REPOSITORY_ROOT, hostWorkerConfigPath(site.id, "gallery-public"));
+		console.log(`\n${dryRun ? "Validating" : "Deploying"} the ${site.id} public Gallery Worker...`);
+		await runWrangler(config, null, args);
+	}
+	// Calendar is on for every site, so every site on its own stack has a feed Worker.
+	await generateHostConfigs(site.id);
+	const calendarConfig = relative(REPOSITORY_ROOT, hostWorkerConfigPath(site.id, "calendar-public"));
+	console.log(`\n${dryRun ? "Validating" : "Deploying"} the ${site.id} calendar feed Worker...`);
+	await runWrangler(calendarConfig, null, args);
+}
+
+export async function main(argv = process.argv.slice(2)): Promise<void> {
+	const options = parseOptions(argv);
+	if (options.help) {
+		console.log(usage());
+		return;
+	}
+	process.chdir(REPOSITORY_ROOT);
+	await deploySite(options);
+}
+
+const invokedPath = process.argv[1] ? resolve(process.argv[1]) : "";
+if (invokedPath === fileURLToPath(import.meta.url)) {
+	main().catch((error: unknown) => {
+		console.error(`\n${error instanceof Error ? error.message : String(error)}`);
+		process.exitCode = 1;
+	});
+}

package/src/deploy/deployment-security.ts

@@ -0,0 +1,141 @@
+import { defaultConcurrency, mapWithConcurrency } from './async-utils.js';
+import {
+	ACCESS_TOKEN_REQUIREMENT,
+	CloudflareAccessClient,
+	planAccessApps,
+	type ExistingAccessApp,
+	type ExistingAccessPolicy,
+} from './cloudflare-access.js';
+import { loadTenantConfig, type ResolvedSite } from '../tenants/tenant-config.js';
+
+export interface DeploymentAccessSite {
+	id: string;
+	title: string;
+	hostname: string;
+	authorizedEmails: readonly string[];
+}
+
+export interface DeploymentAccessIssue {
+	siteId: string;
+	hostname: string;
+	kind: 'missing-app' | 'missing-policy';
+	detail: string;
+}
+
+function deploymentSites(sites: readonly ResolvedSite[]): DeploymentAccessSite[] {
+	return sites.map((site) => ({
+		id: site.id,
+		title: site.title,
+		hostname: site.hostname,
+		authorizedEmails: site.authorizedEmails,
+	}));
+}
+
+/**
+ * Turn the existing Access planner's actions into deployment-blocking issues.
+ * A deployment is safe only when every target has an exact host-wide Access
+ * application and every configured email is covered by an Allow policy.
+ */
+export function planDeploymentAccess(
+	sites: readonly DeploymentAccessSite[],
+	existingApps: readonly ExistingAccessApp[],
+	policiesByAppId: ReadonlyMap<string, readonly ExistingAccessPolicy[]>,
+): DeploymentAccessIssue[] {
+	const actions = planAccessApps(sites, existingApps, policiesByAppId);
+	const issues: DeploymentAccessIssue[] = [];
+
+	for (const site of sites) {
+		const siteActions = actions.filter((action) => action.siteId === site.id);
+		const missingApp = siteActions.find((action) => action.kind === 'create-app');
+		if (missingApp?.kind === 'create-app') {
+			issues.push({
+				siteId: site.id,
+				hostname: site.hostname,
+				kind: 'missing-app',
+				detail: `no exact host-wide Access application protects ${site.hostname}`,
+			});
+			continue;
+		}
+
+		const policyDrift = siteActions.find(
+			(action) =>
+				action.kind === 'reconcile-policy' && action.missingEmails.length > 0,
+		);
+		if (policyDrift?.kind === 'reconcile-policy') {
+			issues.push({
+				siteId: site.id,
+				hostname: site.hostname,
+				kind: 'missing-policy',
+				detail: `Access Allow policy is missing ${policyDrift.missingEmails.join(', ')}`,
+			});
+			continue;
+		}
+
+		if (!siteActions.some((action) => action.kind === 'adopt-app')) {
+			issues.push({
+				siteId: site.id,
+				hostname: site.hostname,
+				kind: 'missing-app',
+				detail: `could not resolve an Access application for ${site.hostname}`,
+			});
+		}
+	}
+
+	return issues;
+}
+
+/**
+ * Verify the Access perimeter before a real Worker deployment. This is
+ * intentionally read-only: creation and policy reconciliation stay in the
+ * explicit tenant provisioning phase used by release:all.
+ */
+export async function assertDeploymentAccess(
+	options: {
+		concurrency?: number;
+		token?: string;
+		accountId?: string | null;
+	} = {},
+): Promise<void> {
+	const token = options.token?.trim() ?? process.env.CLOUDFLARE_API_TOKEN?.trim() ?? '';
+	if (!token) {
+		throw new Error(
+			`Refusing the deployment: Cloudflare Access protection ` +
+				`cannot be verified because CLOUDFLARE_API_TOKEN is missing. ` +
+				`The token needs the ${ACCESS_TOKEN_REQUIREMENT}.`,
+		);
+	}
+
+	const { sites } = await loadTenantConfig();
+	const targets = deploymentSites(sites);
+	if (targets.length === 0) {
+		throw new Error(`Refusing the deployment: no frontend sites are configured`);
+	}
+
+	const client = new CloudflareAccessClient(
+		token,
+		options.accountId === undefined
+			? process.env.CLOUDFLARE_ACCOUNT_ID?.trim() || null
+			: options.accountId,
+	);
+	const existingApps = await client.listApps();
+	const initialActions = planAccessApps(targets, existingApps, new Map());
+	const matchedApps = initialActions
+		.filter((action) => action.kind === 'adopt-app')
+		.map((action) => action.appId);
+	const policiesByAppId = new Map<string, ExistingAccessPolicy[]>();
+	const policyResults = await mapWithConcurrency(
+		[...new Set(matchedApps)],
+		options.concurrency ?? defaultConcurrency(),
+		async (appId) => [appId, await client.listPolicies(appId)] as const,
+	);
+	for (const [appId, policies] of policyResults) policiesByAppId.set(appId, policies);
+
+	const issues = planDeploymentAccess(targets, existingApps, policiesByAppId);
+	if (issues.length > 0) {
+		throw new Error([
+			`Refusing the deployment: Cloudflare Access is incomplete.`,
+			...issues.map((issue) => `- ${issue.siteId} (${issue.hostname}): ${issue.detail}`),
+			'Run `pnpm ensure:tenant -- --set-secret` to reconcile it before deploying.',
+		].join('\n'));
+	}
+}