@janga/norna 0.7.0

package/scripts/deploy-site.mjs

@@ -0,0 +1,389 @@
+import { execFile, spawn } from 'node:child_process';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import {
+	getFrontmatterSections,
+	getContentFiles,
+	readSiteFile,
+	supportedImageExtensions,
+	toPosixPath,
+} from './lib/site-content.mjs';
+import { projectConfig } from './lib/project-config.mjs';
+import {
+	engineRoot,
+	generatedImagesManifestLabel,
+	siteProjectRoot,
+	siteConfigLabel,
+	siteContentLabel,
+	siteImagesLabel,
+	sitePublicLabel,
+	siteRoutesLabel,
+	siteThemeLabel,
+} from './lib/site-paths.mjs';
+
+const execFileAsync = promisify(execFile);
+
+const root = siteProjectRoot;
+const branch = projectConfig.github.branch;
+const repo = projectConfig.github.repo;
+const pagesWorkflow = projectConfig.github.pagesWorkflow;
+const args = process.argv.slice(2);
+const mode = args[0] === 'commit' ? 'commit' : 'deploy';
+const modeArgs = mode === 'commit' ? args.slice(1) : args;
+const allowedExactPaths = new Set([
+	'astro.config.mjs',
+	generatedImagesManifestLabel,
+	'package-lock.json',
+	'package.json',
+	siteConfigLabel,
+	siteThemeLabel,
+	`${sitePublicLabel}/CNAME`,
+	`${sitePublicLabel}/favicon.ico`,
+	`${sitePublicLabel}/favicon.svg`,
+	`${sitePublicLabel}/robots.txt`,
+	`${sitePublicLabel}/sitemap.xml`,
+	'tsconfig.json',
+]);
+const failedConclusions = new Set(['action_required', 'cancelled', 'failure', 'startup_failure', 'timed_out']);
+
+const deployUsage = [
+	'Usage: norna deploy',
+	'',
+	`Publishes an already committed ${branch} branch: builds, verifies a clean worktree,`,
+	`pushes ${branch} when local ${branch} is ahead of origin/${branch}, and checks GitHub Pages.`,
+	`If local ${branch} already matches origin/${branch}, it skips push and checks Pages.`,
+	'',
+	'For the old build-and-commit convenience flow, use:',
+	'norna deploy:commit "Commit message"',
+].join('\n');
+const deployCommitUsage = [
+	'Usage: norna deploy:commit "Commit message"',
+	'',
+	`Builds, stages only allowed site changes, commits, pushes ${branch},`,
+	'and checks GitHub Pages.',
+].join('\n');
+
+const fail = (message) => {
+	console.error(message);
+	process.exit(1);
+};
+
+const runCapture = async (command, commandArgs, options = {}) => {
+	const { stdout } = await execFileAsync(command, commandArgs, {
+		cwd: root,
+		maxBuffer: 1024 * 1024 * 20,
+		...options,
+	});
+
+	return stdout;
+};
+
+const runInherit = (command, commandArgs) => new Promise((resolve, reject) => {
+	const child = spawn(command, commandArgs, {
+		cwd: root,
+		stdio: 'inherit',
+	});
+
+	child.once('error', reject);
+	child.once('exit', (code, signal) => {
+		if (code === 0) {
+			resolve();
+			return;
+		}
+
+		const commandText = [command, ...commandArgs].join(' ');
+		reject(new Error(signal
+			? `${commandText} exited with signal ${signal}.`
+			: `${commandText} exited with code ${code}.`));
+	});
+});
+
+const runBuild = async () => {
+	await runInherit(process.execPath, [path.join(engineRoot, 'scripts', 'build-site.mjs')]);
+};
+
+const printStatusShort = async () => {
+	const status = await runCapture('git', ['status', '--short']);
+	console.log('git status --short');
+	console.log(status.trim() || '(clean)');
+};
+
+const parseStatus = (statusBuffer) => {
+	const records = statusBuffer.toString('utf8').split('\0');
+	const entries = [];
+
+	for (let index = 0; index < records.length;) {
+		const record = records[index];
+		index += 1;
+
+		if (!record) continue;
+
+		const status = record.slice(0, 2);
+		const filePath = record.slice(3);
+		const entry = { status, path: filePath, fromPath: null };
+
+		if (status.includes('R') || status.includes('C')) {
+			entry.fromPath = records[index] || null;
+			index += 1;
+		}
+
+		entries.push(entry);
+	}
+
+	return entries;
+};
+
+const getStatusEntries = async () => parseStatus(await runCapture(
+	'git',
+	['status', '--porcelain=v1', '-z'],
+	{ encoding: 'buffer' },
+));
+
+const getExpectedImagePaths = async () => {
+	const contentFiles = await getContentFiles();
+	const imagePaths = new Set();
+
+	for (const contentFile of contentFiles) {
+		const { frontmatter } = await readSiteFile(contentFile.contentPath, contentFile.contentLabel);
+
+		for (const section of getFrontmatterSections(frontmatter)) {
+			for (const image of section.images) {
+				if (image.includes('/') || image.includes('\\')) continue;
+				if (!supportedImageExtensions.has(path.extname(image).toLowerCase())) continue;
+
+				imagePaths.add(toPosixPath(path.join(contentFile.imagesLabel, section.id, image)));
+			}
+		}
+	}
+
+	return imagePaths;
+};
+
+const isUntracked = (entry) => entry.status === '??';
+
+const isExpectedUntracked = (entry, expectedImagePaths) => (
+	isUntracked(entry)
+	&& (
+		expectedImagePaths.has(entry.path)
+		|| entry.path === generatedImagesManifestLabel
+		|| entry.path.startsWith(`${sitePublicLabel}/`)
+		|| entry.path.startsWith(`${siteRoutesLabel}/`)
+	)
+);
+
+const isAllowedPath = (entry, filePath, expectedImagePaths) => (
+	filePath === siteContentLabel
+	|| filePath === siteThemeLabel
+	|| (!isUntracked(entry) && filePath.startsWith(`${siteImagesLabel}/`))
+	|| filePath.startsWith(`${siteRoutesLabel}/`)
+	|| filePath.startsWith(`${sitePublicLabel}/`)
+	|| expectedImagePaths.has(filePath)
+	|| filePath.startsWith('src/')
+	|| allowedExactPaths.has(filePath)
+);
+
+const getEntryPaths = (entry) => [entry.path, entry.fromPath].filter(Boolean);
+
+const formatEntry = (entry) => `${entry.status} ${getEntryPaths(entry).join(' <- ')}`;
+
+const assertMainBranch = async () => {
+	const currentBranch = (await runCapture('git', ['branch', '--show-current'])).trim();
+
+	if (currentBranch !== branch) {
+		fail(`Refusing to deploy from branch "${currentBranch || '(detached HEAD)'}". Switch to ${branch} first.`);
+	}
+};
+
+const assertDeployableStatus = async (entries, expectedImagePaths) => {
+	if (entries.length === 0) {
+		fail('Refusing to deploy: no changes to commit after the gallery build.');
+	}
+
+	const unexpectedUntracked = entries.filter((entry) => (
+		isUntracked(entry) && !isExpectedUntracked(entry, expectedImagePaths)
+	));
+
+	if (unexpectedUntracked.length > 0) {
+		fail([
+			'Refusing to deploy: unexpected untracked files are present.',
+			`Only new referenced gallery images under ${siteImagesLabel}/<section-id>/ or ${siteRoutesLabel}/<route-folder>/images/<section-id>/ are staged automatically.`,
+			...unexpectedUntracked.map((entry) => `- ${formatEntry(entry)}`),
+		].join('\n'));
+	}
+
+	const unexpectedEntries = entries.filter((entry) => (
+		!getEntryPaths(entry).every((filePath) => isAllowedPath(entry, filePath, expectedImagePaths))
+	));
+
+	if (unexpectedEntries.length > 0) {
+		fail([
+			'Refusing to deploy: changes outside the deploy allowlist are present.',
+			'Commit them separately or update the deploy script deliberately.',
+			...unexpectedEntries.map((entry) => `- ${formatEntry(entry)}`),
+		].join('\n'));
+	}
+};
+
+const getStagePaths = (entries) => [...new Set(entries.flatMap(getEntryPaths))].sort();
+
+const assertCleanWorktree = async (message) => {
+	const entries = await getStatusEntries();
+
+	if (entries.length > 0) {
+		await printStatusShort();
+		fail(message);
+	}
+};
+
+const fetchRemoteMain = async () => {
+	await runInherit('git', ['fetch', 'origin']);
+};
+
+const getRemoteRelation = async () => {
+	const output = (await runCapture('git', [
+		'rev-list',
+		'--left-right',
+		'--count',
+		`origin/${branch}...HEAD`,
+	])).trim();
+	const [behind, ahead] = output.split(/\s+/).map(Number);
+
+	if (!Number.isInteger(behind) || !Number.isInteger(ahead)) {
+		fail(`Could not compare HEAD with origin/${branch}.`);
+	}
+
+	return { ahead, behind };
+};
+
+const plural = (count, word) => `${count} ${word}${count === 1 ? '' : 's'}`;
+
+const assertPushableBranch = async () => {
+	const relation = await getRemoteRelation();
+
+	if (relation.behind > 0 && relation.ahead > 0) {
+		fail([
+			`Refusing to deploy: local ${branch} and origin/${branch} have diverged.`,
+			`Local ${branch} is ${plural(relation.ahead, 'commit')} ahead and ${plural(relation.behind, 'commit')} behind origin/${branch}.`,
+			'Reconcile the branches before deploying.',
+		].join('\n'));
+	}
+
+	if (relation.behind > 0) {
+		fail([
+			`Refusing to deploy: local ${branch} is ${plural(relation.behind, 'commit')} behind origin/${branch}.`,
+			'Pull or rebase before deploying.',
+		].join('\n'));
+	}
+
+	return relation;
+};
+
+const getLatestPagesRun = async () => {
+	const output = await runCapture('gh', [
+		'run',
+		'list',
+		'--repo',
+		repo,
+		'--workflow',
+		pagesWorkflow,
+		'--branch',
+		branch,
+		'--limit',
+		'1',
+		'--json',
+		'databaseId,conclusion,status,url',
+	]);
+	const runs = JSON.parse(output || '[]');
+
+	return runs[0] ?? null;
+};
+
+const checkPagesWorkflow = async () => {
+	await runInherit('gh', ['run', 'list', '--repo', repo, '--branch', branch, '--limit', '3']);
+
+	const latestRun = await getLatestPagesRun();
+	if (!latestRun) {
+		console.warn(`No ${pagesWorkflow} runs found for ${branch}.`);
+		process.exit(0);
+	}
+
+	if (failedConclusions.has(latestRun.conclusion)) {
+		console.error(`${pagesWorkflow} run ${latestRun.databaseId} failed. Inspecting failed logs.`);
+		await runInherit('gh', ['run', 'view', String(latestRun.databaseId), '--repo', repo, '--log-failed']);
+		process.exit(1);
+	}
+
+	console.log(`${pagesWorkflow} latest run: ${latestRun.status}${latestRun.conclusion ? `/${latestRun.conclusion}` : ''}`);
+};
+
+const deployCommittedMain = async () => {
+	if (modeArgs.length > 0) {
+		fail([
+			'The deploy command no longer accepts a commit message.',
+			'Commit your changes first, then run norna deploy.',
+			'Use norna deploy:commit "Commit message" for the old build-and-commit convenience flow.',
+		].join('\n'));
+	}
+
+	await assertMainBranch();
+	await assertCleanWorktree('Refusing to deploy: commit or discard local changes before deploying.');
+	await fetchRemoteMain();
+	await assertPushableBranch();
+	await runBuild();
+	await printStatusShort();
+	await assertCleanWorktree('Refusing to deploy: the gallery build produced uncommitted changes. Commit them before deploying.');
+	await fetchRemoteMain();
+
+	const relation = await assertPushableBranch();
+
+	if (relation.ahead > 0) {
+		await runInherit('git', ['push', 'origin', branch]);
+	} else {
+		console.log(`Local ${branch} matches origin/${branch}; nothing to push.`);
+	}
+
+	await checkPagesWorkflow();
+};
+
+const deployWithCommit = async () => {
+	const commitMessage = modeArgs.join(' ').trim();
+
+	if (!commitMessage) {
+		fail(`Commit message is required.\n${deployCommitUsage}`);
+	}
+
+	await assertMainBranch();
+	await fetchRemoteMain();
+	await assertPushableBranch();
+	await runBuild();
+	await printStatusShort();
+
+	const entries = await getStatusEntries();
+	const expectedImagePaths = await getExpectedImagePaths();
+	await assertDeployableStatus(entries, expectedImagePaths);
+
+	const stagePaths = getStagePaths(entries);
+	await runInherit('git', ['add', '--', ...stagePaths]);
+	await runInherit('git', ['commit', '-m', commitMessage]);
+	await assertCleanWorktree('Refusing to push: uncommitted changes remain after commit.');
+	await fetchRemoteMain();
+	await assertPushableBranch();
+	await runInherit('git', ['push', 'origin', branch]);
+	await checkPagesWorkflow();
+};
+
+if (modeArgs.includes('--help') || modeArgs.includes('-h')) {
+	console.log(mode === 'commit' ? deployCommitUsage : deployUsage);
+	process.exit(0);
+}
+
+try {
+	if (mode === 'commit') {
+		await deployWithCommit();
+	} else {
+		await deployCommittedMain();
+	}
+} catch (error) {
+	console.error(error.message);
+	process.exit(1);
+}

package/scripts/dev-local.mjs

@@ -0,0 +1,313 @@
+import { execFile, spawn } from 'node:child_process';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import net from 'node:net';
+import { networkInterfaces } from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { getAstroArgs, runAstroInherit } from './lib/astro-command.mjs';
+import { astroCacheDir, engineRoot, siteProjectRoot } from './lib/site-paths.mjs';
+
+const execFileAsync = promisify(execFile);
+
+const port = 4321;
+const localHost = 'localhost';
+const localUrl = `http://${localHost}:${port}/`;
+const probeUrls = [localUrl, `http://127.0.0.1:${port}/`, `http://[::1]:${port}/`];
+const skipOpen = process.env.WALDE_NO_OPEN === '1';
+const statePath = path.join(astroCacheDir, 'dev-local.json');
+const logPath = path.join(astroCacheDir, 'dev.log');
+const command = process.argv[2] ?? 'start';
+
+const runAstro = async (args, options = {}) => execFileAsync(process.execPath, getAstroArgs(args), {
+	cwd: siteProjectRoot,
+	maxBuffer: 1024 * 1024 * 10,
+	...options,
+});
+
+const syncSitePublic = async () => execFileAsync(process.execPath, [path.join(engineRoot, 'scripts', 'sync-site-public.mjs')], {
+	cwd: siteProjectRoot,
+	maxBuffer: 1024 * 1024 * 10,
+});
+
+const getPortPids = async () => {
+	try {
+		const { stdout } = await execFileAsync('lsof', ['-nP', `-iTCP:${port}`, '-sTCP:LISTEN', '-t']);
+		return [...new Set(stdout.trim().split(/\s+/).map(Number).filter(Number.isInteger))];
+	} catch (error) {
+		if (error.code === 1 || error.code === 'ENOENT') {
+			return [];
+		}
+
+		throw error;
+	}
+};
+
+const readState = async () => {
+	try {
+		return JSON.parse(await readFile(statePath, 'utf8'));
+	} catch (error) {
+		if (error.code === 'ENOENT') {
+			return null;
+		}
+
+		throw error;
+	}
+};
+
+const getLanUrls = () => Object.values(networkInterfaces())
+	.flat()
+	.filter((network) => network?.family === 'IPv4' && !network.internal)
+	.map((network) => `http://${network.address}:${port}/`);
+
+const writeState = async (pid, host) => {
+	await mkdir(path.dirname(statePath), { recursive: true });
+	await writeFile(statePath, `${JSON.stringify({
+		pid,
+		port,
+		host,
+		mode: host === '0.0.0.0' ? 'lan' : 'local',
+		url: localUrl,
+		startedAt: new Date().toISOString(),
+	}, null, 2)}\n`);
+};
+
+const removeState = async () => {
+	await rm(statePath, { force: true });
+};
+
+const isPortFreeOnHost = (loopbackHost) => new Promise((resolve, reject) => {
+	const server = net.createServer();
+
+	server.once('error', (error) => {
+		if (error.code === 'EADDRINUSE') {
+			resolve(false);
+			return;
+		}
+
+		if (error.code === 'EADDRNOTAVAIL') {
+			resolve(true);
+			return;
+		}
+
+		reject(error);
+	});
+	server.once('listening', () => {
+		server.close(() => resolve(true));
+	});
+	server.listen({ port, host: loopbackHost, ipv6Only: loopbackHost === '::1' });
+});
+
+const isPortFree = async () => {
+	for (const loopbackHost of ['127.0.0.1', '::1']) {
+		if (!(await isPortFreeOnHost(loopbackHost))) {
+			return false;
+		}
+	}
+
+	return true;
+};
+
+const sleep = (milliseconds) => new Promise((resolve) => {
+	setTimeout(resolve, milliseconds);
+});
+
+const isServerReachable = async () => {
+	for (const probeUrl of probeUrls) {
+		try {
+			const response = await fetch(probeUrl, { signal: AbortSignal.timeout(1_000) });
+			await response.arrayBuffer();
+			return true;
+		} catch {
+			// Try the next loopback address.
+		}
+	}
+
+	return false;
+};
+
+const waitForServer = async () => {
+	const startedAt = Date.now();
+	const timeoutMs = 30_000;
+
+	while (Date.now() - startedAt < timeoutMs) {
+		if (await isServerReachable()) {
+			return;
+		}
+
+		await sleep(500);
+	}
+
+	throw new Error(`Timed out waiting for ${localUrl}`);
+};
+
+const waitForPidToStopListening = async (pid) => {
+	const startedAt = Date.now();
+	const timeoutMs = 5_000;
+
+	while (Date.now() - startedAt < timeoutMs) {
+		if (!(await getPortPids()).includes(pid)) {
+			return true;
+		}
+
+		await sleep(250);
+	}
+
+	return false;
+};
+
+const openBrowser = async () => {
+	if (skipOpen) {
+		console.log(`Browser open skipped. Open ${localUrl}`);
+		return;
+	}
+
+	if (process.platform === 'darwin') {
+		await execFileAsync('open', [localUrl]);
+		return;
+	}
+
+	if (process.platform === 'win32') {
+		await execFileAsync('cmd', ['/c', 'start', '', localUrl]);
+		return;
+	}
+
+	await execFileAsync('xdg-open', [localUrl]);
+};
+
+const stopServer = async ({ quiet = false } = {}) => {
+	const state = await readState();
+
+	await runAstro(['dev', 'stop']).catch(() => {});
+
+	if (!state?.pid) {
+		if (!quiet) {
+			console.log('No dev:local server is tracked.');
+		}
+		return;
+	}
+
+	const listeningPids = await getPortPids();
+
+	if (!listeningPids.includes(state.pid)) {
+		await removeState();
+		if (!quiet) {
+			console.log('No tracked dev:local server is running.');
+		}
+		return;
+	}
+
+	process.kill(state.pid, 'SIGTERM');
+
+	if (!(await waitForPidToStopListening(state.pid))) {
+		process.kill(state.pid, 'SIGKILL');
+		await waitForPidToStopListening(state.pid);
+	}
+
+	await removeState();
+
+	if (!quiet) {
+		console.log(`Stopped dev server on ${localUrl}.`);
+	}
+};
+
+const startServer = async ({ host = localHost, open = true } = {}) => {
+	await stopServer({ quiet: true });
+
+	const existingPids = await getPortPids();
+	if (existingPids.length > 0 || !(await isPortFree())) {
+		throw new Error(`Port ${port} is already in use. Stop the process using it, then rerun the dev command.`);
+	}
+
+	await syncSitePublic();
+	await runAstroInherit(['dev', '--background', '--host', host, '--port', String(port)]);
+	await waitForServer();
+
+	const startedPids = await getPortPids();
+	await writeState(startedPids[0] ?? null, host);
+	if (open) {
+		await openBrowser();
+	} else {
+		console.log(`Browser open skipped. Open ${localUrl}`);
+	}
+
+	console.log(`Astro dev server is running at ${localUrl}`);
+	if (host === '0.0.0.0') {
+		const lanUrls = getLanUrls();
+		console.log(lanUrls.length > 0
+			? `On this local network: ${lanUrls.join(', ')}`
+			: 'No local IPv4 address was found for LAN access.');
+	}
+	console.log('Manage it with norna dev:status, norna dev:logs, norna dev:restart, and norna dev:stop.');
+};
+
+const showStatus = async () => {
+	const state = await readState();
+	const listeningPids = await getPortPids();
+	const reachable = await isServerReachable();
+
+	if (state?.pid && listeningPids.includes(state.pid)) {
+		const reachability = reachable ? '' : ' The listener is active, but the URL probe did not respond.';
+		console.log(`dev:${state.mode ?? 'local'} is running at ${localUrl} (pid ${state.pid}).${reachability}`);
+		if (state.host === '0.0.0.0') {
+			const lanUrls = getLanUrls();
+			if (lanUrls.length > 0) console.log(`On this local network: ${lanUrls.join(', ')}`);
+		}
+		return;
+	}
+
+	if (reachable) {
+		const detail = state?.pid
+			? `the tracked pid ${state.pid} is not listening`
+			: 'no dev:local state file was found';
+		console.log(`A server is responding at ${localUrl}, but ${detail}.`);
+		return;
+	}
+
+	if (state) {
+		await removeState();
+	}
+
+	console.log(`No dev server is running at ${localUrl}.`);
+};
+
+const showLogs = async () => {
+	const shouldFollow = process.argv.includes('--follow');
+
+	if (shouldFollow) {
+		const tail = spawn('tail', ['-n', '80', '-f', logPath], { stdio: 'inherit' });
+		await new Promise((resolve, reject) => {
+			tail.once('exit', resolve);
+			tail.once('error', reject);
+		});
+		return;
+	}
+
+	try {
+		const lines = (await readFile(logPath, 'utf8')).trimEnd().split('\n');
+		console.log(lines.slice(-80).join('\n'));
+	} catch (error) {
+		if (error.code === 'ENOENT') {
+			console.log('No dev log found.');
+			return;
+		}
+
+		throw error;
+	}
+};
+
+if (command === 'start') {
+	await startServer({ open: !skipOpen });
+} else if (command === 'lan') {
+	await startServer({ host: '0.0.0.0', open: !skipOpen });
+} else if (command === 'status') {
+	await showStatus();
+} else if (command === 'logs') {
+	await showLogs();
+} else if (command === 'restart') {
+	const state = await readState();
+	await startServer({ host: state?.host === '0.0.0.0' ? '0.0.0.0' : localHost, open: false });
+} else if (command === 'stop') {
+	await stopServer();
+} else {
+	throw new Error(`Unknown dev-local command: ${command}`);
+}