@ryanatkn/gro 0.169.1 → 0.171.0

package/src/lib/build_cache.ts

@@ -0,0 +1,362 @@
+import {
+	existsSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	rmSync,
+	statSync,
+	writeFileSync,
+} from 'node:fs';
+import {join} from 'node:path';
+import type {Logger} from '@ryanatkn/belt/log.js';
+import {styleText as st} from 'node:util';
+import {git_current_commit_hash} from '@ryanatkn/belt/git.js';
+import {z} from 'zod';
+
+import {to_hash} from './hash.ts';
+import type {Gro_Config} 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 Build_Output_Entry = 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 Build_Output_Entry = z.infer<typeof Build_Output_Entry>;
+
+/**
+ * Metadata stored in .gro/ directory to track build cache validity.
+ * Schema validates structure at load time to catch corrupted cache files.
+ */
+export const Build_Cache_Metadata = 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(Build_Output_Entry)
+		.meta({description: 'build output files with hashes and filesystem stats'}),
+});
+export type Build_Cache_Metadata = z.infer<typeof Build_Cache_Metadata>;
+
+/**
+ * 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: Gro_Config,
+	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 = (): Build_Cache_Metadata | null => {
+	const metadata_path = join(paths.build, BUILD_CACHE_METADATA_FILENAME);
+
+	if (!existsSync(metadata_path)) {
+		return null;
+	}
+
+	try {
+		const contents = readFileSync(metadata_path, 'utf-8');
+		const parsed = JSON.parse(contents);
+
+		// Validate structure with Zod
+		const metadata = Build_Cache_Metadata.parse(parsed);
+
+		// Validate version
+		if (metadata.version !== BUILD_CACHE_VERSION) {
+			// Clean up stale cache with old schema version
+			try {
+				rmSync(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 {
+			rmSync(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 = (metadata: Build_Cache_Metadata, log?: Logger): void => {
+	try {
+		// Ensure .gro directory exists
+		mkdirSync(paths.build, {recursive: true});
+
+		const metadata_path = join(paths.build, BUILD_CACHE_METADATA_FILENAME);
+		writeFileSync(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: Build_Cache_Metadata): Promise<boolean> => {
+	// Verify all tracked output files exist and have matching size
+	for (const output of metadata.outputs) {
+		if (!existsSync(output.path)) {
+			return false;
+		}
+
+		// Fast negative check: size mismatch = definitely invalid
+		// This avoids expensive file reads and hashing for files that have clearly changed
+		const stats = statSync(output.path);
+		if (stats.size !== output.size) {
+			return false;
+		}
+	}
+
+	// Size matches for all files - now verify content with cryptographic hashing
+	// Hash all files in parallel for performance
+	const hash_promises = metadata.outputs.map(async (output) => {
+		try {
+			const contents = readFileSync(output.path);
+			const actual_hash = await to_hash(contents);
+			return actual_hash === output.hash;
+		} catch {
+			// File deleted/inaccessible between checks = cache invalid
+			return false;
+		}
+	});
+
+	const results = await Promise.all(hash_promises);
+	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: Gro_Config,
+	log: Logger,
+	git_commit?: string | null,
+): Promise<boolean> => {
+	// Load existing metadata
+	const metadata = 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<Build_Output_Entry>> => {
+	// Collect all files to hash first
+	interface File_Entry {
+		full_path: string;
+		cache_key: string;
+	}
+
+	const files_to_hash: Array<File_Entry> = [];
+
+	// Recursively collect files
+	const collect_files = (dir: string, relative_base: string, dir_prefix: string): void => {
+		const entries = readdirSync(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()) {
+				collect_files(full_path, relative_path, dir_prefix);
+			} else if (entry.isFile()) {
+				files_to_hash.push({full_path, cache_key});
+			}
+			// Symlinks are intentionally ignored - we only hash regular files
+		}
+	};
+
+	// Collect files from all build directories
+	for (const build_dir of build_dirs) {
+		if (!existsSync(build_dir)) {
+			continue; // Skip non-existent directories
+		}
+		collect_files(build_dir, '', build_dir);
+	}
+
+	// Hash all files in parallel and collect stats
+	const hash_promises = files_to_hash.map(
+		async ({full_path, cache_key}): Promise<Build_Output_Entry> => {
+			const stats = statSync(full_path);
+			const contents = readFileSync(full_path);
+			const hash = await to_hash(contents);
+
+			return {
+				path: cache_key,
+				hash,
+				size: stats.size,
+				mtime: stats.mtimeMs,
+				ctime: stats.ctimeMs,
+				mode: stats.mode,
+			};
+		},
+	);
+
+	return await Promise.all(hash_promises);
+};
+
+/**
+ * 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 = (): Array<string> => {
+	const build_dirs: Array<string> = [];
+
+	// Check for SvelteKit app output (build/)
+	if (existsSync(SVELTEKIT_BUILD_DIRNAME)) {
+		build_dirs.push(SVELTEKIT_BUILD_DIRNAME);
+	}
+
+	// Check for SvelteKit library output (dist/)
+	if (existsSync(SVELTEKIT_DIST_DIRNAME)) {
+		build_dirs.push(SVELTEKIT_DIST_DIRNAME);
+	}
+
+	// Check for server and other plugin outputs (dist_*)
+	const root_entries = readdirSync('.');
+	const dist_dirs = root_entries.filter((p) => {
+		if (!p.startsWith(GRO_DIST_PREFIX)) return false;
+		try {
+			return statSync(p).isDirectory();
+		} catch {
+			// File was deleted/moved during iteration - skip it
+			return false;
+		}
+	});
+	build_dirs.push(...dist_dirs);
+
+	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: Gro_Config,
+	log: Logger,
+	git_commit?: string | null,
+	build_dirs?: Array<string>,
+): Promise<Build_Cache_Metadata> => {
+	const cache_key = await compute_build_cache_key(config, log, git_commit);
+	const dirs = build_dirs ?? 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

@@ -51,7 +51,7 @@ const map_changelog = async (
 	for (const line of parsed) {
 		const matches = LINE_WITH_SHA_MATCHER.exec(line);
 		if (matches) {
-			const commit_sha = matches[1];
+			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) {

package/src/lib/changeset.task.ts

@@ -174,7 +174,7 @@ const create_changeset_adder = (
 		if (filenames_added.length !== 1) {
 			throw Error('expected to find exactly one new changeset file');
 		}
-		const path = join(dir, filenames_added[0]);
+		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]);

package/src/lib/commit.task.ts

@@ -26,7 +26,7 @@ export const task: Task<Args> = {
 
 		const branch = await git_current_branch_name();
 
-		await spawn('git', ['commit', '-a', '-m', message]);
+		await spawn('git', ['commit', '-a', '-m', message!]);
 		await git_push(origin, branch, undefined, true);
 	},
 };

package/src/lib/deploy.task.ts

@@ -27,7 +27,7 @@ import {print_path} from './paths.ts';
 import {GRO_DIRNAME, GIT_DIRNAME, SVELTEKIT_BUILD_DIRNAME} from './constants.ts';
 import {empty_dir} from './fs.ts';
 
-// docs at ./docs/deploy.md
+// docs at ../docs/deploy.md
 
 // terminal command for testing:
 // npm run bootstrap && rm -rf .gro && clear && gro deploy --source no-git-workspace --no-build --dry
@@ -159,11 +159,14 @@ export const task: Task<Args> = {
 					await rm(resolved_deploy_dir, {recursive: true});
 				} else {
 					await spawn('git', ['reset', '--hard'], target_spawn_options); // in case it's dirty
-					await git_pull(origin, target, target_spawn_options);
-					if (await git_check_clean_workspace(target_spawn_options)) {
-						// We're in a bad state because the local branch lost continuity with the remote,
-						// so delete the directory and continue as if it wasn't there.
-						await rm(resolved_deploy_dir, {recursive: true});
+					// Skip pulling target branch when resetting (optimization - we reset after anyway)
+					if (!reset) {
+						await git_pull(origin, target, target_spawn_options);
+						if (await git_check_clean_workspace(target_spawn_options)) {
+							// We're in a bad state because the local branch lost continuity with the remote,
+							// so delete the directory and continue as if it wasn't there.
+							await rm(resolved_deploy_dir, {recursive: true});
+						}
 					}
 				}
 			}
@@ -219,10 +222,6 @@ export const task: Task<Args> = {
 			if (build) {
 				await invoke_task('build');
 			}
-			if (!existsSync(build_dir)) {
-				log.error(st('red', 'directory to deploy does not exist after building:'), build_dir);
-				return;
-			}
 		} catch (err) {
 			log.error(
 				st('red', 'build failed'),
@@ -236,6 +235,11 @@ export const task: Task<Args> = {
 			throw new Task_Error(`Deploy safely canceled due to build failure. See the error above.`);
 		}
 
+		// Verify build output exists
+		if (!existsSync(build_dir)) {
+			throw new Task_Error(`Directory to deploy does not exist after building: ${build_dir}`);
+		}
+
 		// Copy the build
 		await Promise.all(
 			readdirSync(build_dir).map((path) =>

package/src/lib/esbuild_plugin_svelte.ts

@@ -109,7 +109,7 @@ const convert_svelte_message_to_esbuild = (
 ): esbuild.PartialMessage => {
 	let location: esbuild.PartialMessage['location'] = null;
 	if (start && end) {
-		const lineText = source.split(/\r\n|\r|\n/g)[start.line - 1];
+		const lineText = source.split(/\r\n|\r|\n/g)[start.line - 1] ?? '';
 		const lineEnd = start.line === end.line ? end.column : lineText.length;
 		location = {
 			file: path,

package/src/lib/gen.ts

@@ -53,6 +53,7 @@ export type Gen = Gen_Function | Gen_Config;
 
 export type Gen_Function = (ctx: Gen_Context) => Raw_Gen_Result | Promise<Raw_Gen_Result>;
 
+// TODO add a Gen_Config_Raw variant and change `normalize_gen_config` to `gen_cook_config`
 export interface Gen_Config {
 	generate: Gen_Function;
 	dependencies?: Gen_Dependencies;
@@ -180,7 +181,7 @@ export const to_output_file_name = (filename: string): string => {
 	for (let i = 0; i < length; i++) {
 		if (i === gen_pattern_index) continue; // skip the `.gen.` pattern
 		if (i === length - 1 && parts[i] === '') continue; // allow empty extension
-		final_parts.push(parts[i]);
+		final_parts.push(parts[i]!);
 	}
 	return final_parts.join('.');
 };

package/src/lib/gro_config.ts

@@ -2,6 +2,7 @@ import {join, resolve} from 'node:path';
 import {existsSync} from 'node:fs';
 import {identity} from '@ryanatkn/belt/function.js';
 import type {Path_Filter, Path_Id} from '@ryanatkn/belt/path.js';
+import {json_stringify_deterministic} from '@ryanatkn/belt/json.js';
 
 import {GRO_DIST_DIR, IS_THIS_GRO, paths} from './paths.ts';
 import {
@@ -17,6 +18,14 @@ import create_default_config from './gro.config.default.ts';
 import type {Create_Config_Plugins} from './plugin.ts';
 import type {Map_Package_Json} from './package_json.ts';
 import type {Parsed_Svelte_Config} from './svelte_config.ts';
+import {to_hash} from './hash.ts';
+
+/**
+ * SHA-256 hash of empty string, used for configs without build_cache_config.
+ * This ensures consistent cache behavior when no custom config is provided.
+ */
+export const EMPTY_BUILD_CACHE_CONFIG_HASH =
+	'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
 
 /**
  * The config that users can extend via `gro.config.ts`.
@@ -54,6 +63,13 @@ export interface Gro_Config extends Raw_Gro_Config {
 	pm_cli: string;
 	/** @default SVELTE_CONFIG_FILENAME */
 	svelte_config_filename?: string;
+	/**
+	 * SHA-256 hash of the user's `build_cache_config` from `gro.config.ts`.
+	 * This is computed during config normalization and the raw value is immediately deleted.
+	 * If no `build_cache_config` was provided, this is the hash of an empty string.
+	 * @see Raw_Gro_Config.build_cache_config
+	 */
+	build_cache_config_hash: string;
 }
 
 /**
@@ -68,6 +84,24 @@ export interface Raw_Gro_Config {
 	search_filters?: Path_Filter | Array<Path_Filter> | null;
 	js_cli?: string;
 	pm_cli?: string;
+	/**
+	 * Optional object defining custom build inputs for cache invalidation.
+	 * This value is hashed during config normalization and used to detect
+	 * when builds need to be regenerated due to non-source changes.
+	 *
+	 * Use cases:
+	 * - Environment variables baked into build: `{api_url: process.env.PUBLIC_API_URL}`
+	 * - External data files: `{data: fs.readFileSync('data.json', 'utf-8')}`
+	 * - Build feature flags: `{enable_analytics: true}`
+	 *
+	 * Can be a static object or an async function that returns an object.
+	 *
+	 * IMPORTANT: It's safe to include secrets here because they are hashed and `delete`d
+	 * during config normalization. The raw value is never logged or persisted.
+	 */
+	build_cache_config?:
+		| Record<string, unknown>
+		| (() => Record<string, unknown> | Promise<Record<string, unknown>>);
 }
 
 export type Create_Gro_Config = (
@@ -87,6 +121,7 @@ export const create_empty_gro_config = (): Gro_Config => ({
 	search_filters: [(id) => !SEARCH_EXCLUDER_DEFAULT.test(id)],
 	js_cli: JS_CLI_DEFAULT,
 	pm_cli: PM_CLI_DEFAULT,
+	build_cache_config_hash: EMPTY_BUILD_CACHE_CONFIG_HASH,
 });
 
 /**
@@ -112,8 +147,9 @@ export const EXPORTS_EXCLUDER_DEFAULT = /(\.md|\.(test|ignore)\.|\/(test|fixture
 /**
  * Transforms a `Raw_Gro_Config` to the more strict `Gro_Config`.
  * This allows users to provide a more relaxed config.
+ * Hashes the `build_cache_config` and deletes the raw value for security.
  */
-export const cook_gro_config = (raw_config: Raw_Gro_Config): Gro_Config => {
+export const cook_gro_config = async (raw_config: Raw_Gro_Config): Promise<Gro_Config> => {
 	const empty_config = create_empty_gro_config();
 
 	// All of the raw config properties are optional,
@@ -125,8 +161,28 @@ export const cook_gro_config = (raw_config: Raw_Gro_Config): Gro_Config => {
 		search_filters = empty_config.search_filters,
 		js_cli = empty_config.js_cli,
 		pm_cli = empty_config.pm_cli,
+		build_cache_config,
 	} = raw_config;
 
+	// Hash build_cache_config and delete the raw value
+	// IMPORTANT: Raw value may contain secrets - hash it and delete immediately
+	let build_cache_config_hash: string;
+	if (!build_cache_config) {
+		build_cache_config_hash = EMPTY_BUILD_CACHE_CONFIG_HASH;
+	} else {
+		// Resolve if it's a function
+		const resolved =
+			typeof build_cache_config === 'function' ? await build_cache_config() : build_cache_config;
+
+		// Hash the JSON representation with deterministic key ordering
+		build_cache_config_hash = await to_hash(
+			new TextEncoder().encode(json_stringify_deterministic(resolved)),
+		);
+	}
+
+	// Delete the raw value to ensure it doesn't persist in memory
+	delete (raw_config as any).build_cache_config;
+
 	return {
 		plugins,
 		map_package_json,
@@ -138,6 +194,7 @@ export const cook_gro_config = (raw_config: Raw_Gro_Config): Gro_Config => {
 				: [],
 		js_cli,
 		pm_cli,
+		build_cache_config_hash,
 	};
 };
 
@@ -146,7 +203,9 @@ export interface Gro_Config_Module {
 }
 
 export const load_gro_config = async (dir = paths.root): Promise<Gro_Config> => {
-	const default_config = cook_gro_config(await create_default_config(create_empty_gro_config()));
+	const default_config = await cook_gro_config(
+		await create_default_config(create_empty_gro_config()),
+	);
 
 	const config_path = join(dir, GRO_CONFIG_FILENAME);
 	if (!existsSync(config_path)) {
@@ -159,7 +218,7 @@ export const load_gro_config = async (dir = paths.root): Promise<Gro_Config> =>
 
 	validate_gro_config_module(config_module, config_path);
 
-	return cook_gro_config(
+	return await cook_gro_config(
 		typeof config_module.default === 'function'
 			? await config_module.default(default_config)
 			: config_module.default,

package/src/lib/hash.ts

@@ -1,12 +1,10 @@
-import {webcrypto} from 'node:crypto';
-
-const {subtle} = webcrypto;
+const {subtle} = globalThis.crypto;
 
 /**
  * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto
  */
 export const to_hash = async (
-	data: Buffer,
+	data: BufferSource,
 	algorithm: 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512' = 'SHA-256',
 ): Promise<string> => {
 	const digested = await subtle.digest(algorithm, data);

package/src/lib/invoke_task.ts

@@ -96,7 +96,10 @@ export const invoke_task = async (
 	}
 	const loaded_tasks = loaded.value;
 
-	if (resolved_input_files.length > 1 || resolved_input_files[0].resolved_input_path.is_directory) {
+	if (
+		resolved_input_files.length > 1 ||
+		resolved_input_files[0]!.resolved_input_path.is_directory
+	) {
 		// The input path matches a directory. Log the tasks but don't run them.
 		log_tasks(log, loaded_tasks);
 		await finish();
@@ -105,7 +108,7 @@ export const invoke_task = async (
 
 	// The input path matches a file that's presumable a task, so load and run it.
 	if (loaded_tasks.modules.length !== 1) throw Error('expected one loaded task'); // run only one task at a time
-	const task = loaded_tasks.modules[0];
+	const task = loaded_tasks.modules[0]!;
 	log.info(
 		`→ ${st('cyan', task.name)} ${(task.mod.task.summary && st('gray', task.mod.task.summary)) ?? ''}`,
 	);