@twango/twiki 0.0.0-stage → 0.1.0-rc.0

package/site/tooling/lib/asset-hash-cache.ts

@@ -0,0 +1,116 @@
+import { lstatSync, readFileSync, realpathSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { wranglerAssetHash } from './deployment-manifest';
+import { sha256 } from './deployment-config';
+import { writeChanged } from './output';
+
+export const assetHashAlgorithmVersion = 'wrangler-4.100-blake3-base64-extension-v1';
+export interface AssetHashes {
+	hash: string;
+	sha256: string;
+	size: number;
+}
+type Record = AssetHashes & { stamp: string; extension: string };
+const inventories = new Map<string, Map<string, Record>>();
+const digest = /^[a-f0-9]{64}$/;
+const assetDigest = /^[a-f0-9]{32}$/;
+function inventory(site: string) {
+	const root = path.resolve(site);
+	let value = inventories.get(root);
+	if (!value) {
+		value = new Map();
+		try {
+			const saved = JSON.parse(
+				readFileSync(path.join(root, 'build/generated/cache/deployment-hashes.json'), 'utf8')
+			);
+			if (
+				saved.schema === 1 &&
+				saved.algorithm === assetHashAlgorithmVersion &&
+				Array.isArray(saved.entries)
+			) {
+				for (const [file, record] of saved.entries) {
+					if (
+						typeof file === 'string' &&
+						file.startsWith(root + path.sep) &&
+						valid(record) &&
+						typeof record.stamp === 'string' &&
+						typeof record.extension === 'string'
+					)
+						value.set(file, record);
+				}
+			}
+		} catch {}
+		inventories.set(root, value);
+	}
+	return value;
+}
+function valid(value: AssetHashes) {
+	return (
+		value &&
+		digest.test(value.sha256) &&
+		assetDigest.test(value.hash) &&
+		Number.isSafeInteger(value.size) &&
+		value.size >= 0
+	);
+}
+function fileStamp(site: string, file: string) {
+	const absolute = path.resolve(file);
+	if (!absolute.startsWith(path.resolve(site) + path.sep) || realpathSync(absolute) !== absolute)
+		throw new Error('Asset hashing requires an owned regular file');
+	const stat = lstatSync(absolute, { bigint: true });
+	if (!stat.isFile()) throw new Error('Asset hashing requires a regular file');
+	return JSON.stringify(
+		[stat.dev, stat.ino, stat.mode, stat.size, stat.mtimeNs, stat.ctimeNs].map(String)
+	);
+}
+/** Local acceleration only. This file/stamp inventory must never be transported. */
+export function cachedAssetHashes(site: string, file: string): AssetHashes | undefined {
+	try {
+		const absolute = path.resolve(file);
+		const record = inventory(site).get(absolute);
+		// Some Linux filesystems coalesce timestamp updates within a kernel tick,
+		// even when stat exposes nanoseconds. Never reuse recently written files.
+		const stat = lstatSync(absolute, { bigint: true });
+		const newest = stat.mtimeNs > stat.ctimeNs ? stat.mtimeNs : stat.ctimeNs;
+		if (BigInt(Date.now()) * 1_000_000n - newest < 1_000_000_000n) return;
+		if (
+			record &&
+			record.extension === path.extname(absolute) &&
+			record.stamp === fileStamp(site, absolute)
+		)
+			return { hash: record.hash, sha256: record.sha256, size: record.size };
+	} catch {}
+}
+/** Caller has verified these hashes against an authenticated product's actual bytes. */
+export function rememberVerifiedAsset(site: string, file: string, hashes: AssetHashes) {
+	if (!valid(hashes)) throw new Error('Invalid verified asset hashes');
+	const absolute = path.resolve(file);
+	if (lstatSync(absolute).size !== hashes.size) throw new Error('Verified asset size changed');
+	inventory(site).set(absolute, {
+		...hashes,
+		stamp: fileStamp(site, absolute),
+		extension: path.extname(absolute)
+	});
+}
+export function captureAssetHashes(site: string, file: string): AssetHashes {
+	const cached = cachedAssetHashes(site, file);
+	if (cached) return cached;
+	const before = fileStamp(site, file);
+	const bytes = readFileSync(file);
+	const value = { hash: wranglerAssetHash(bytes, file), sha256: sha256(bytes), size: bytes.length };
+	if (before !== fileStamp(site, file)) throw new Error('Asset changed while hashing');
+	rememberVerifiedAsset(site, file, value);
+	return value;
+}
+export function flushAssetHashCache(site: string) {
+	const file = path.join(path.resolve(site), 'build/generated/cache/deployment-hashes.json');
+	mkdirSync(path.dirname(file), { recursive: true });
+	writeChanged(
+		file,
+		JSON.stringify({
+			schema: 1,
+			algorithm: assetHashAlgorithmVersion,
+			entries: [...inventory(site)]
+		})
+	);
+}

package/site/tooling/lib/autotag.ts

@@ -0,0 +1,99 @@
+/**
+ * Directory-derived AutoTag, ported verbatim from the wisconsin Quartz fork's
+ * `quartz/plugins/transformers/autotag.ts`, minus the Quartz plugin wrapper.
+ *
+ * Config matches quartz.config.ts: enabled, excludePaths ["assets", "des-inv"],
+ * customMapping {}.
+ */
+import { slugTag } from './slug';
+
+export interface AutoTagOptions {
+	excludePaths?: string[];
+	customMapping?: Record<string, string>;
+}
+
+export const QUARTZ_AUTOTAG_OPTIONS: AutoTagOptions = {
+	excludePaths: ['assets', 'des-inv'],
+	customMapping: {}
+};
+
+interface TagStrategy {
+	tag: string;
+	scope: 'global' | 'immediate'; // global applies to all descendants, immediate only to direct children
+}
+
+function extractCourseCode(directory: string): string {
+	return directory.includes('-') ? directory.substring(directory.lastIndexOf('-') + 1) : directory;
+}
+
+function extractTerm(directory: string): string | null {
+	return directory.includes('-') ? directory.substring(0, directory.indexOf('-')) : null;
+}
+
+function extractSubject(courseCode: string): string | null {
+	const match = courseCode.match(/^[a-z]+/i);
+	return match ? match[0] : null;
+}
+
+function generateTagStrategies(
+	directory: string,
+	customMapping?: Record<string, string>
+): TagStrategy[] {
+	const strategies: TagStrategy[] = [];
+	const courseCode = customMapping?.[directory] || extractCourseCode(directory);
+
+	// Course code tag is global - applies to all nested content
+	strategies.push({ tag: slugTag(courseCode), scope: 'global' });
+
+	// Term tag only applies to immediate children
+	const term = extractTerm(directory);
+	if (term) {
+		strategies.push({ tag: slugTag(term), scope: 'immediate' });
+	}
+
+	// Subject tag only applies to immediate children
+	const subject = extractSubject(courseCode);
+	if (subject && subject !== courseCode) {
+		strategies.push({ tag: slugTag(subject), scope: 'immediate' });
+	}
+
+	return strategies;
+}
+
+/**
+ * Returns the auto tags for a page given its path relative to content/
+ * (e.g. "sp26-cs537/p1/README.md"). The caller appends them to the page's
+ * existing tags, deduped, in order — same as the fork.
+ */
+export function autoTagsFor(
+	relativePath: string,
+	opts: AutoTagOptions = QUARTZ_AUTOTAG_OPTIONS
+): string[] {
+	const pathSegments = relativePath.split('/');
+	if (pathSegments.length < 2) return [];
+
+	const firstDir = pathSegments[0];
+	if (opts.excludePaths?.includes(firstDir)) return [];
+
+	// Check if this is an immediate child (only 2 segments) or nested deeper
+	const isImmediateChild = pathSegments.length === 2;
+
+	// Generate tag strategies for this directory
+	const strategies = generateTagStrategies(firstDir, opts.customMapping);
+
+	// Filter strategies based on scope
+	return strategies
+		.filter((s) => s.scope === 'global' || (s.scope === 'immediate' && isImmediateChild))
+		.map((s) => s.tag);
+}
+
+/** fork behavior: append new tags after existing ones, skipping duplicates */
+export function applyAutoTags(
+	existingTags: string[],
+	relativePath: string,
+	opts?: AutoTagOptions
+): string[] {
+	const applicableTags = autoTagsFor(relativePath, opts);
+	const newTags = applicableTags.filter((tag) => !existingTags.includes(tag));
+	return [...existingTags, ...newTags];
+}

package/site/tooling/lib/build-assembly.ts

@@ -0,0 +1,148 @@
+import {
+	existsSync,
+	lstatSync,
+	mkdirSync,
+	mkdtempSync,
+	readFileSync,
+	readdirSync,
+	realpathSync,
+	renameSync,
+	rmSync,
+	writeFileSync
+} from 'node:fs';
+import path from 'node:path';
+import { publicAssetManifest } from './public-assets';
+
+function directory(file: string) {
+	if (!lstatSync(file).isDirectory()) throw new Error(`Expected build directory: ${file}`);
+}
+
+function contained(root: string, file: string) {
+	const relative = path.relative(root, path.resolve(root, file));
+	if (relative.startsWith('..' + path.sep) || relative === '..' || path.isAbsolute(relative))
+		throw new Error(`Build artifact escapes its snapshot: ${file}`);
+	return path.resolve(root, file);
+}
+
+function rejectSymlinks(root: string) {
+	for (const entry of readdirSync(root, { recursive: true, withFileTypes: true }))
+		if (entry.isSymbolicLink())
+			throw new Error(
+				`Public artifact cannot be a symlink: ${path.join(entry.parentPath, entry.name)}`
+			);
+}
+
+/** Assemble completed isolated editions; only successful promotion changes canonical output. */
+export function assembleBuilds(canonicalSite: string, publicSite: string, fullSite: string) {
+	const sites = [canonicalSite, publicSite, fullSite].map((site) => realpathSync(site));
+	if (new Set(sites).size !== sites.length)
+		throw new Error('Build editions must have separate roots');
+	const publicOutput = path.join(publicSite, 'build/.svelte-kit/cloudflare');
+	const fullOutput = path.join(fullSite, 'build/.svelte-kit/cloudflare');
+	const publicGenerated = path.join(publicSite, 'build/generated');
+	const fullGenerated = path.join(fullSite, 'build/generated');
+	const trees = ['build/.svelte-kit', 'build/generated', 'src/lib/generated', 'static'];
+	for (const tree of trees) directory(path.join(fullSite, tree));
+	directory(publicOutput);
+	directory(fullOutput);
+	rejectSymlinks(publicOutput);
+	const pages: Record<string, string> = JSON.parse(
+		readFileSync(path.join(publicGenerated, 'public-routes.json'), 'utf8')
+	);
+	const content: { htmlAssets: string[] } = JSON.parse(
+		readFileSync(path.join(publicGenerated, 'content-manifest.json'), 'utf8')
+	);
+	const entries: { course: string; file: string }[] = JSON.parse(
+		readFileSync(path.join(publicSite, 'src/lib/generated/file-entries.json'), 'utf8')
+	);
+	for (const asset of content.htmlAssets) {
+		pages[`/${asset}`] = `${asset}.html`;
+		pages[`/${asset}.html`] = `${asset}.html`;
+	}
+	for (const file of Object.values(pages)) {
+		const target = contained(publicOutput, file);
+		if (!lstatSync(target).isFile()) throw new Error(`Public page is missing: ${file}`);
+	}
+	const publicAssets = publicAssetManifest(publicOutput, pages, entries);
+	for (const target of new Set(Object.values(publicAssets))) {
+		const relative = decodeURIComponent(target.slice('/_published'.length));
+		const file = contained(publicOutput, relative.replace(/^\//, '') || 'index.html');
+		if (
+			![file, `${file}.html`].some(
+				(candidate) => existsSync(candidate) && lstatSync(candidate).isFile()
+			)
+		)
+			throw new Error(`Public asset target is missing: ${target}`);
+	}
+
+	const published = path.join(fullOutput, '_published');
+	const transaction = mkdtempSync(path.join(canonicalSite, 'build/.assembly-'));
+	const promoted: {
+		source: string;
+		target: string;
+		backup: string;
+		replaced: boolean;
+		installed: boolean;
+	}[] = [];
+	let movedPublic = false;
+	try {
+		rmSync(published, { recursive: true, force: true });
+		renameSync(publicOutput, published);
+		movedPublic = true;
+		for (const name of ['public-routes.json', 'public-assets', 'public-files', 'public-static']) {
+			const source = path.join(publicGenerated, name);
+			if (!existsSync(source)) continue;
+			const target = path.join(fullGenerated, name);
+			rmSync(target, { recursive: true, force: true });
+			renameSync(source, target);
+		}
+		writeFileSync(path.join(fullGenerated, 'public-assets.json'), JSON.stringify(publicAssets));
+		// These local reuse records contain scratch paths and output inode stamps.
+		rmSync(path.join(fullGenerated, 'cache/course-files'), { recursive: true, force: true });
+		rmSync(path.join(fullGenerated, 'dev-state.json'), { force: true });
+		for (const [index, tree] of trees.entries()) {
+			const operation = {
+				source: path.join(fullSite, tree),
+				target: path.join(canonicalSite, tree),
+				backup: path.join(transaction, String(index)),
+				replaced: false,
+				installed: false
+			};
+			promoted.push(operation);
+			mkdirSync(path.dirname(operation.target), { recursive: true });
+			if (existsSync(operation.target)) {
+				renameSync(operation.target, operation.backup);
+				operation.replaced = true;
+			}
+			renameSync(operation.source, operation.target);
+			operation.installed = true;
+		}
+	} catch (error) {
+		const failures: unknown[] = [];
+		for (const operation of promoted.reverse()) {
+			try {
+				if (operation.installed) renameSync(operation.target, operation.source);
+				if (operation.replaced) renameSync(operation.backup, operation.target);
+			} catch (rollbackError) {
+				failures.push(rollbackError);
+			}
+		}
+		if (movedPublic && existsSync(published)) {
+			try {
+				renameSync(published, publicOutput);
+			} catch (rollbackError) {
+				failures.push(rollbackError);
+			}
+		}
+		if (failures.length)
+			throw new AggregateError(
+				[error, ...failures],
+				`Assembly rollback failed; backups retained at ${transaction}`
+			);
+		rmSync(transaction, { recursive: true, force: true });
+		throw error;
+	}
+	// Canonical .wrangler and build/.wrangler are outside the promoted trees.
+	rmSync(transaction, { recursive: true, force: true });
+	return { publicPages: Object.keys(pages).length, fileRoutes: entries.length, publicAssets };
+}