@fuzdev/gro 0.192.0

package/src/lib/build_cache.ts

@@ -0,0 +1,378 @@
+import {mkdir, readdir, readFile, rm, stat, writeFile} from 'node:fs/promises';
+import {join} from 'node:path';
+import {styleText as st} from 'node:util';
+import {z} from 'zod';
+import type {Logger} from '@fuzdev/fuz_util/log.js';
+import {git_current_commit_hash} from '@fuzdev/fuz_util/git.js';
+import {fs_exists} from '@fuzdev/fuz_util/fs.js';
+import {map_concurrent} from '@fuzdev/fuz_util/async.js';
+import {hash_secure} from '@fuzdev/fuz_util/hash.js';
+
+import type {GroConfig} from './gro_config.ts';
+import {paths} from './paths.ts';
+import {SVELTEKIT_BUILD_DIRNAME, SVELTEKIT_DIST_DIRNAME, GRO_DIST_PREFIX} from './constants.ts';
+
+export const BUILD_CACHE_METADATA_FILENAME = 'build.json';
+export const BUILD_CACHE_VERSION = '1';
+
+/**
+ * Metadata about a single build output file.
+ * Includes cryptographic hash for validation plus filesystem stats for debugging and optimization.
+ */
+export const BuildOutputEntry = z.strictObject({
+	path: z
+		.string()
+		.meta({description: "relative path from project root (e.g., 'build/index.html')."}),
+	hash: z.string().meta({description: 'SHA-256 hash of file contents'}),
+	size: z.number().meta({description: 'file size in bytes'}),
+	mtime: z.number().meta({description: 'modification time in milliseconds since epoch'}),
+	ctime: z.number().meta({
+		description: 'POSIX change time in milliseconds since epoch',
+	}),
+	mode: z.number().meta({description: 'unix file permission mode (e.g., 33188 = 0644)'}),
+});
+export type BuildOutputEntry = z.infer<typeof BuildOutputEntry>;
+
+/**
+ * Metadata stored in .gro/ directory to track build cache validity.
+ * Schema validates structure at load time to catch corrupted cache files.
+ */
+export const BuildCacheMetadata = z.strictObject({
+	version: z.string().meta({description: 'schema version for future compatibility'}),
+	git_commit: z.string().nullable().meta({description: 'git commit hash at time of build'}),
+	build_cache_config_hash: z
+		.string()
+		.meta({description: "hash of user's custom build_cache_config from gro.config.ts."}),
+	timestamp: z.string().meta({description: 'timestamp when build completed'}),
+	outputs: z
+		.array(BuildOutputEntry)
+		.meta({description: 'build output files with hashes and filesystem stats'}),
+});
+export type BuildCacheMetadata = z.infer<typeof BuildCacheMetadata>;
+
+/**
+ * Computes the cache key components for a build.
+ * This determines whether a cached build can be reused.
+ *
+ * @param config Gro config (build_cache_config_hash is already computed during config load)
+ * @param log Logger
+ * @param git_commit Optional pre-computed git commit hash (optimization to avoid re-reading)
+ */
+export const compute_build_cache_key = async (
+	config: GroConfig,
+	log: Logger,
+	git_commit?: string | null,
+): Promise<{
+	git_commit: string | null;
+	build_cache_config_hash: string;
+}> => {
+	// 1. Git commit hash - primary cache key
+	const commit = git_commit !== undefined ? git_commit : await git_current_commit_hash();
+	if (!commit) {
+		log.warn('Not in a git repository - build cache will use null git commit');
+	}
+
+	// 2. Build cache config hash - already computed during config normalization
+	return {
+		git_commit: commit,
+		build_cache_config_hash: config.build_cache_config_hash,
+	};
+};
+
+/**
+ * Loads build cache metadata from .gro/ directory.
+ * Invalid or corrupted cache files are automatically deleted.
+ */
+export const load_build_cache_metadata = async (): Promise<BuildCacheMetadata | null> => {
+	const metadata_path = join(paths.build, BUILD_CACHE_METADATA_FILENAME);
+
+	if (!(await fs_exists(metadata_path))) {
+		return null;
+	}
+
+	try {
+		const contents = await readFile(metadata_path, 'utf-8');
+		const parsed = JSON.parse(contents);
+
+		// Validate structure with Zod
+		const metadata = BuildCacheMetadata.parse(parsed);
+
+		// Validate version
+		if (metadata.version !== BUILD_CACHE_VERSION) {
+			// Clean up stale cache with old schema version
+			try {
+				await rm(metadata_path, {force: true});
+			} catch {
+				// Ignore cleanup errors
+			}
+			return null;
+		}
+
+		return metadata;
+	} catch {
+		// Clean up corrupted/invalid cache file
+		// (catches JSON.parse, Zod validation, and version errors)
+		try {
+			await rm(metadata_path, {force: true});
+		} catch {
+			// Ignore cleanup errors
+		}
+		return null;
+	}
+};
+
+/**
+ * Saves build cache metadata to .gro/ directory.
+ * Errors are logged but don't fail the build (cache is optional).
+ */
+export const save_build_cache_metadata = async (
+	metadata: BuildCacheMetadata,
+	log?: Logger,
+): Promise<void> => {
+	try {
+		// Ensure .gro directory exists
+		await mkdir(paths.build, {recursive: true});
+
+		const metadata_path = join(paths.build, BUILD_CACHE_METADATA_FILENAME);
+		await writeFile(metadata_path, JSON.stringify(metadata, null, '\t'), 'utf-8');
+	} catch (error) {
+		// Cache writes are optional - log warning but don't fail the build
+		log?.warn(
+			st('yellow', 'Failed to save build cache'),
+			st('dim', `(${error instanceof Error ? error.message : String(error)})`),
+		);
+	}
+};
+
+/**
+ * Validates that a cached build is still valid by checking stats and hashing outputs.
+ * Uses size as a fast negative check before expensive hashing.
+ * This is comprehensive validation to catch manual tampering or corruption.
+ */
+export const validate_build_cache = async (metadata: BuildCacheMetadata): Promise<boolean> => {
+	// Verify all tracked output files exist and have matching size
+	// Sequential checks with early return for performance
+	for (const output of metadata.outputs) {
+		// eslint-disable-next-line no-await-in-loop
+		if (!(await fs_exists(output.path))) {
+			return false;
+		}
+
+		// Fast negative check: size mismatch = definitely invalid
+		// This avoids expensive file reads and hashing for files that have clearly changed
+		// eslint-disable-next-line no-await-in-loop
+		const stats = await stat(output.path);
+		if (stats.size !== output.size) {
+			return false;
+		}
+	}
+
+	// Size matches for all files - now verify content with cryptographic hashing
+	// Hash files with controlled concurrency (could be 10k+ files)
+	const results = await map_concurrent(
+		metadata.outputs,
+		async (output) => {
+			try {
+				const contents = await readFile(output.path);
+				const actual_hash = await hash_secure(contents);
+				return actual_hash === output.hash;
+			} catch {
+				// File deleted/inaccessible between checks = cache invalid
+				return false;
+			}
+		},
+		20,
+	);
+	return results.every((valid) => valid);
+};
+
+/**
+ * Main function to check if the build cache is valid.
+ * Returns true if the cached build can be used, false if a fresh build is needed.
+ *
+ * @param config Gro config
+ * @param log Logger
+ * @param git_commit Optional pre-computed git commit hash (optimization)
+ */
+export const is_build_cache_valid = async (
+	config: GroConfig,
+	log: Logger,
+	git_commit?: string | null,
+): Promise<boolean> => {
+	// Load existing metadata
+	const metadata = await load_build_cache_metadata();
+	if (!metadata) {
+		log.debug('No build cache metadata found');
+		return false;
+	}
+
+	// Compute current cache key
+	const current = await compute_build_cache_key(config, log, git_commit);
+
+	// Check if cache keys have changed
+	if (metadata.git_commit !== current.git_commit) {
+		log.debug('Build cache invalid: git commit changed');
+		return false;
+	}
+
+	if (metadata.build_cache_config_hash !== current.build_cache_config_hash) {
+		log.debug('Build cache invalid: build_cache_config changed');
+		return false;
+	}
+
+	// Comprehensive validation: verify output files
+	const outputs_valid = await validate_build_cache(metadata);
+	if (!outputs_valid) {
+		log.debug('Build cache invalid: output files missing or corrupted');
+		return false;
+	}
+
+	log.info(st('green', 'Build cache valid'), st('dim', `(from ${metadata.timestamp})`));
+	return true;
+};
+
+/**
+ * Collects information about all files in build output directories.
+ * Returns an array of entries with path, hash, size, mtime, ctime, and mode.
+ *
+ * Files are hashed in parallel for performance. For very large builds (10k+ files),
+ * this may take several seconds but ensures complete cache validation.
+ *
+ * @param build_dirs Array of output directories to scan (e.g., ['build', 'dist', 'dist_server'])
+ */
+export const collect_build_outputs = async (
+	build_dirs: Array<string>,
+): Promise<Array<BuildOutputEntry>> => {
+	// Collect all files to hash first
+	interface FileEntry {
+		full_path: string;
+		cache_key: string;
+	}
+
+	const files_hash_secure: Array<FileEntry> = [];
+
+	// Recursively collect files
+	const collect_files = async (
+		dir: string,
+		relative_base: string,
+		dir_prefix: string,
+	): Promise<void> => {
+		const entries = await readdir(dir, {withFileTypes: true});
+
+		for (const entry of entries) {
+			// Skip metadata file itself
+			if (entry.name === BUILD_CACHE_METADATA_FILENAME) {
+				continue;
+			}
+
+			const full_path = join(dir, entry.name);
+			const relative_path = relative_base ? join(relative_base, entry.name) : entry.name;
+			const cache_key = join(dir_prefix, relative_path);
+
+			if (entry.isDirectory()) {
+				// eslint-disable-next-line no-await-in-loop
+				await collect_files(full_path, relative_path, dir_prefix);
+			} else if (entry.isFile()) {
+				files_hash_secure.push({full_path, cache_key});
+			}
+			// Symlinks are intentionally ignored - we only hash regular files
+		}
+	};
+
+	// Collect files from all build directories sequentially
+	for (const build_dir of build_dirs) {
+		// eslint-disable-next-line no-await-in-loop
+		if (!(await fs_exists(build_dir))) {
+			continue; // Skip non-existent directories
+		}
+		// eslint-disable-next-line no-await-in-loop
+		await collect_files(build_dir, '', build_dir);
+	}
+
+	// Hash files with controlled concurrency and collect stats (could be 10k+ files)
+	return map_concurrent(
+		files_hash_secure,
+		async ({full_path, cache_key}): Promise<BuildOutputEntry> => {
+			const stats = await stat(full_path);
+			const contents = await readFile(full_path);
+			const hash = await hash_secure(contents);
+
+			return {
+				path: cache_key,
+				hash,
+				size: stats.size,
+				mtime: stats.mtimeMs,
+				ctime: stats.ctimeMs,
+				mode: stats.mode,
+			};
+		},
+		20,
+	);
+};
+
+/**
+ * Discovers all build output directories in the current working directory.
+ * Returns an array of directory names that exist: build/, dist/, dist_*
+ */
+export const discover_build_output_dirs = async (): Promise<Array<string>> => {
+	const build_dirs: Array<string> = [];
+
+	// Check for SvelteKit app output (build/) and library output (dist/) in parallel
+	const [build_exists, dist_exists] = await Promise.all([
+		fs_exists(SVELTEKIT_BUILD_DIRNAME),
+		fs_exists(SVELTEKIT_DIST_DIRNAME),
+	]);
+
+	if (build_exists) {
+		build_dirs.push(SVELTEKIT_BUILD_DIRNAME);
+	}
+	if (dist_exists) {
+		build_dirs.push(SVELTEKIT_DIST_DIRNAME);
+	}
+
+	// Check for server and other plugin outputs (dist_*)
+	const root_entries = await readdir('.');
+	const dist_dir_checks = await Promise.all(
+		root_entries
+			.filter((p) => p.startsWith(GRO_DIST_PREFIX))
+			.map(async (p) => {
+				try {
+					const s = await stat(p);
+					return s.isDirectory() ? p : null;
+				} catch {
+					// File was deleted/moved during iteration - skip it
+					return null;
+				}
+			}),
+	);
+	build_dirs.push(...dist_dir_checks.filter((p): p is string => p !== null));
+
+	return build_dirs;
+};
+
+/**
+ * Creates build cache metadata after a successful build.
+ * Automatically discovers all build output directories (build/, dist/, dist_*).
+ *
+ * @param config Gro config
+ * @param log Logger
+ * @param git_commit Optional pre-computed git commit hash (optimization)
+ * @param build_dirs Optional pre-discovered build directories (optimization to avoid redundant filesystem scans)
+ */
+export const create_build_cache_metadata = async (
+	config: GroConfig,
+	log: Logger,
+	git_commit?: string | null,
+	build_dirs?: Array<string>,
+): Promise<BuildCacheMetadata> => {
+	const cache_key = await compute_build_cache_key(config, log, git_commit);
+	const dirs = build_dirs ?? (await discover_build_output_dirs());
+	const outputs = await collect_build_outputs(dirs);
+
+	return {
+		version: BUILD_CACHE_VERSION,
+		...cache_key,
+		timestamp: new Date().toISOString(),
+		outputs,
+	};
+};

package/src/lib/changelog.ts

@@ -0,0 +1,69 @@
+import {readFile, writeFile} from 'node:fs/promises';
+import {z} from 'zod';
+import type {Logger} from '@fuzdev/fuz_util/log.js';
+import type {FetchValueCache} from '@fuzdev/fuz_util/fetch.js';
+
+import {github_fetch_commit_prs} from './github.ts';
+
+/**
+ * Updates a changelog produced by `@changesets/changelog-git` with better links and formatting.
+ * It's similar to `@changesets/changelog-github` but doesn't require a token for light usage.
+ * This may be better implemented as a standalone dependency
+ * as an alternative to `@changesets/changelog-git`.
+ * @returns boolean indicating if the changelog changed
+ */
+export const update_changelog = async (
+	owner: string,
+	repo: string,
+	path = 'CHANGELOG.md',
+	token?: string,
+	log?: Logger,
+	cache: FetchValueCache = new Map(), // include a default cache to efficiently handle multiple changesets per commit
+): Promise<boolean> => {
+	const contents = await readFile(path, 'utf8');
+	const parsed = parse_changelog(contents);
+	const mapped = await map_changelog(parsed, owner, repo, token, log, cache);
+	const updated = serialize_changelog(mapped);
+	if (contents === updated) {
+		return false;
+	}
+	await writeFile(path, updated, 'utf8');
+	return true;
+};
+
+// keeping this really simple for now, no need to parse further for our current usecases
+const ParsedChangelog = z.array(z.string());
+type ParsedChangelog = z.infer<typeof ParsedChangelog>;
+const parse_changelog = (contents: string): ParsedChangelog => contents.split('\n');
+const serialize_changelog = (parsed: ParsedChangelog): string => parsed.join('\n');
+
+const LINE_WITH_SHA_MATCHER = /^- ([a-z0-9]{7,8}): /;
+
+const map_changelog = async (
+	parsed: ParsedChangelog,
+	owner: string,
+	repo: string,
+	token?: string,
+	log?: Logger,
+	cache?: FetchValueCache,
+): Promise<ParsedChangelog> => {
+	const mapped: ParsedChangelog = [];
+	for (const line of parsed) {
+		const matches = LINE_WITH_SHA_MATCHER.exec(line);
+		if (matches) {
+			const commit_sha = matches[1]!;
+			const l = '- ' + line.substring(commit_sha.length + 4);
+			const prs = await github_fetch_commit_prs(owner, repo, commit_sha, token, log, cache); // eslint-disable-line no-await-in-loop
+			if (prs?.length) {
+				mapped.push(`${l} (${prs.map((p) => `[#${p.number}](${p.html_url})`).join(', ')})`);
+			} else {
+				mapped.push(
+					`${l} ([${commit_sha}](https://github.com/${owner}/${repo}/commit/${commit_sha}))`,
+				);
+			}
+		} else {
+			mapped.push(line);
+		}
+	}
+	return mapped;
+};

package/src/lib/changeset.task.ts

@@ -0,0 +1,228 @@
+import {z} from 'zod';
+import {spawn} from '@fuzdev/fuz_util/process.js';
+import {styleText as st} from 'node:util';
+import type {WrittenConfig} from '@changesets/types';
+import {readdir, readFile, writeFile} from 'node:fs/promises';
+import {join} from 'node:path';
+import {fs_exists} from '@fuzdev/fuz_util/fs.js';
+import {
+	GitOrigin,
+	git_check_fully_staged_workspace,
+	git_push_to_create,
+} from '@fuzdev/fuz_util/git.js';
+
+import {TaskError, type Task} from './task.ts';
+import {find_cli, spawn_cli} from './cli.ts';
+import {has_sveltekit_library} from './sveltekit_helpers.ts';
+import {
+	CHANGESET_CLI,
+	CHANGESET_DIR,
+	ChangesetAccess,
+	ChangesetBump,
+	CHANGESET_PUBLIC_ACCESS,
+	CHANGESET_RESTRICTED_ACCESS,
+} from './changeset_helpers.ts';
+import {package_json_load} from './package_json.ts';
+
+/** @nodocs */
+export const Args = z.strictObject({
+	/**
+	 * The optional rest args get joined with a space to form the `message`.
+	 */
+	_: z
+		.array(z.string())
+		.meta({description: 'the message for the changeset and commit'})
+		.max(1)
+		.default([]),
+	minor: z.boolean().meta({description: 'bump the minor version'}).default(false),
+	major: z.boolean().meta({description: 'bump the major version'}).default(false),
+	dir: z.string().meta({description: 'changeset dir'}).default(CHANGESET_DIR),
+	access: ChangesetAccess.describe(
+		"changeset 'access' config value, the default depends on package.json#private",
+	).optional(),
+	changelog: z
+		.string()
+		.meta({description: 'changelog dep package name, used as changeset\'s "changelog" config'})
+		.default('@changesets/changelog-git'),
+	dep: z.boolean().meta({description: 'dual of no-dep'}).default(true),
+	'no-dep': z
+		.boolean()
+		.meta({description: 'opt out of installing the changelog package'})
+		.default(false),
+	origin: GitOrigin.describe('git origin to deploy to').default('origin'),
+	changeset_cli: z.string().meta({description: 'the changeset CLI to use'}).default(CHANGESET_CLI),
+});
+export type Args = z.infer<typeof Args>;
+
+/**
+ * Calls the `changeset` CLI with some simple automations.
+ * This API is designed for convenient manual usage, not clarity or normality.
+ *
+ * Usage:
+ * - gro changeset some commit message
+ * - gro changeset some commit message --minor
+ * - gro changeset "some commit message" --minor
+ *
+ * @nodocs
+ */
+export const task: Task<Args> = {
+	summary: 'call changeset with gro patterns',
+	Args,
+	run: async (ctx): Promise<void> => {
+		const {
+			invoke_task,
+			args: {
+				_: [message],
+				minor,
+				major,
+				dir,
+				access: access_arg,
+				changelog,
+				dep,
+				origin,
+				changeset_cli,
+			},
+			log,
+			svelte_config,
+			config,
+		} = ctx;
+
+		if (!message && (minor || major)) throw new TaskError('cannot bump version without a message');
+		if (minor && major) throw new TaskError('cannot bump both minor and major');
+
+		const bump: ChangesetBump = minor ? 'minor' : major ? 'major' : 'patch';
+
+		const found_changeset_cli = await find_cli(changeset_cli);
+		if (!found_changeset_cli) {
+			throw new TaskError(
+				'changeset command not found: install @changesets/cli locally or globally',
+			);
+		}
+
+		const package_json = await package_json_load();
+
+		const has_sveltekit_library_result = await has_sveltekit_library(package_json, svelte_config);
+		if (!has_sveltekit_library_result.ok) {
+			throw new TaskError(
+				'Failed to find SvelteKit library: ' + has_sveltekit_library_result.message,
+			);
+		}
+
+		const path = join(dir, 'config.json');
+
+		const inited = await fs_exists(path);
+
+		if (!inited) {
+			await spawn_cli(found_changeset_cli, ['init'], log);
+
+			const access =
+				(access_arg ?? package_json.private)
+					? CHANGESET_RESTRICTED_ACCESS
+					: CHANGESET_PUBLIC_ACCESS;
+
+			const access_color = access === CHANGESET_RESTRICTED_ACCESS ? 'blue' : 'red';
+			log.info('initing changeset with ' + st(access_color, access) + ' access');
+			if (access !== CHANGESET_RESTRICTED_ACCESS) {
+				await update_changeset_config(path, (config) => {
+					const updated = {...config};
+					updated.access = access;
+					updated.changelog = changelog;
+					return updated;
+				});
+			}
+
+			await spawn('git', ['add', dir]);
+
+			if (dep) {
+				await spawn(config.pm_cli, ['install', '-D', changelog]);
+			}
+		}
+
+		// TODO small problem here where generated files don't get committed
+		await invoke_task('sync', {install: inited || !dep}); // after installing above, and in all cases
+
+		if (message) {
+			// TODO see the helper below, simplify this to CLI flags when support is added to Changesets
+			const changeset_adder = await create_changeset_adder(package_json.name, dir, message, bump);
+			await spawn_cli(found_changeset_cli, ['add', '--empty'], log);
+			await changeset_adder();
+			if (!(await git_check_fully_staged_workspace())) {
+				await spawn('git', ['commit', '-m', message]);
+				await git_push_to_create(origin);
+			}
+		} else {
+			await spawn_cli(found_changeset_cli, [], log);
+			await spawn('git', ['add', dir]);
+		}
+	},
+};
+
+/**
+ * TODO ideally this wouldn't exist and we'd use CLI flags, but they doesn't exist yet
+ * @see https://github.com/changesets/changesets/pull/1121
+ */
+const create_changeset_adder = async (
+	repo_name: string,
+	dir: string,
+	message: string,
+	bump: ChangesetBump,
+): Promise<() => Promise<void>> => {
+	const filenames_before = await readdir(dir);
+	return async () => {
+		const filenames_after = await readdir(dir);
+		const filenames_added = filenames_after.filter((p) => !filenames_before.includes(p));
+		if (!filenames_added.length) {
+			throw Error('expected to find a new changeset file');
+		}
+		if (filenames_added.length !== 1) {
+			throw Error('expected to find exactly one new changeset file');
+		}
+		const path = join(dir, filenames_added[0]!);
+		const contents = create_new_changeset(repo_name, message, bump);
+		await writeFile(path, contents, 'utf8');
+		await spawn('git', ['add', path]);
+	};
+};
+
+const create_new_changeset = (
+	repo_name: string,
+	message: string,
+	bump: ChangesetBump,
+): string => `---
+"${repo_name}": ${bump}
+---
+
+${message}
+`;
+
+type ChangesetCallback = (config: WrittenConfig) => WrittenConfig | Promise<WrittenConfig>;
+
+type UpdateWrittenConfig = (path: string, cb: ChangesetCallback) => Promise<boolean>;
+
+// TODO refactor all of this with zod and package_json helpers - util file helper? JSON parse pluggable
+
+const update_changeset_config: UpdateWrittenConfig = async (path, cb) => {
+	const config_contents = await load_changeset_config_contents(path);
+	const config = parse_changeset_config(config_contents);
+
+	const updated = await cb(config);
+
+	const serialized = serialize_changeset_config(updated);
+
+	if (serialized === config_contents) {
+		return false;
+	}
+
+	await write_changeset_config(path, serialized);
+	return true;
+};
+
+const load_changeset_config_contents = (path: string): Promise<string> => readFile(path, 'utf8');
+
+const write_changeset_config = (path: string, serialized: string): Promise<void> =>
+	writeFile(path, serialized);
+
+const serialize_changeset_config = (config: WrittenConfig): string =>
+	JSON.stringify(config, null, '\t') + '\n';
+
+const parse_changeset_config = (contents: string): WrittenConfig => JSON.parse(contents);

package/src/lib/changeset_helpers.ts

@@ -0,0 +1,14 @@
+import {z} from 'zod';
+
+export const CHANGESET_RESTRICTED_ACCESS = 'restricted';
+export const CHANGESET_PUBLIC_ACCESS = 'public';
+
+export const ChangesetAccess = z.enum([CHANGESET_RESTRICTED_ACCESS, CHANGESET_PUBLIC_ACCESS]);
+export type ChangesetAccess = z.infer<typeof ChangesetAccess>;
+
+export const CHANGESET_CLI = 'changeset';
+
+export const CHANGESET_DIR = '.changeset';
+
+export const ChangesetBump = z.enum(['patch', 'minor', 'major']);
+export type ChangesetBump = z.infer<typeof ChangesetBump>;