@fuzdev/gro 0.192.0

package/src/lib/input_path.ts

@@ -0,0 +1,254 @@
+import {dirname, isAbsolute, join, resolve} from 'node:path';
+import {stat} from 'node:fs/promises';
+import {fs_exists, fs_search} from '@fuzdev/fuz_util/fs.js';
+import {strip_start} from '@fuzdev/fuz_util/string.js';
+import {z} from 'zod';
+import type {Flavored} from '@fuzdev/fuz_util/types.js';
+import type {PathInfo, PathId, ResolvedPath} from '@fuzdev/fuz_util/path.js';
+
+import {GRO_PACKAGE_DIR, GRO_DIST_DIR} from './paths.ts';
+import {TASK_FILE_SUFFIX_JS} from './task.ts';
+
+// TODO Flavored doesn't work when used in schemas, use Zod brand instead? problem is ergonomics
+export const InputPath = z.string();
+export type InputPath = Flavored<z.infer<typeof InputPath>, 'InputPath'>;
+
+export const RawInputPath = z.string();
+export type RawInputPath = Flavored<z.infer<typeof RawInputPath>, 'RawInputPath'>;
+
+/**
+ * Raw input paths are paths that users provide to Gro to reference files for tasks and gen.
+ *
+ * A raw input path can be to a file or directory in the following forms:
+ *
+ * - an absolute path, preserved
+ * - an explicit relative path, e.g. `./src/foo`, resolved to `root_path` which defaults to the cwd
+ * - an implicit relative path, e.g. `src/foo`, preserved
+ * - an implicit relative path prefixed with `gro/`, transformed to absolute in the Gro directory
+ *
+ * Thus, input paths are either absolute or implicitly relative.
+ */
+export const to_input_path = (
+	raw_input_path: RawInputPath,
+	root_path = process.cwd(), // TODO @many isn't passed in anywhere, maybe hoist to `invoke_task` and others
+): InputPath => {
+	if (raw_input_path.startsWith(GRO_PACKAGE_DIR)) {
+		return GRO_DIST_DIR + strip_start(raw_input_path, GRO_PACKAGE_DIR);
+	} else if (raw_input_path[0] === '.') {
+		return resolve(root_path, raw_input_path);
+	}
+	return raw_input_path as InputPath;
+};
+
+export const to_input_paths = (
+	raw_input_paths: Array<RawInputPath>,
+	root_path?: string, // TODO @many isn't passed in anywhere, maybe hoist to `invoke_task` and others
+): Array<InputPath> => raw_input_paths.map((p) => to_input_path(p, root_path));
+
+export interface PossiblePath {
+	id: PathId;
+	input_path: InputPath;
+	root_dir: PathId;
+}
+
+/**
+ * Gets a list of possible source ids for each input path with `extensions`,
+ * duplicating each under `root_dirs`, without checking the filesystem.
+ */
+export const get_possible_paths = async (
+	input_path: InputPath,
+	root_dirs: Array<PathId>,
+	extensions: Array<string>,
+): Promise<Array<PossiblePath>> => {
+	const possible_paths: Set<PossiblePath> = new Set();
+
+	const add_possible_paths = (path: string, root_dir: PathId) => {
+		// Specifically for paths to the Gro package dist, optimize by only looking for `.task.js`.
+		if (path.startsWith(GRO_DIST_DIR)) {
+			possible_paths.add({
+				id: (path.endsWith('/') || path.endsWith(TASK_FILE_SUFFIX_JS)
+					? path
+					: path + TASK_FILE_SUFFIX_JS) as PathId,
+				input_path,
+				root_dir,
+			});
+		} else {
+			possible_paths.add({id: path as PathId, input_path, root_dir});
+			if (!path.endsWith('/') && !extensions.some((e) => path.endsWith(e))) {
+				for (const extension of extensions) {
+					possible_paths.add({id: path + extension, input_path, root_dir});
+				}
+			}
+		}
+	};
+
+	if (isAbsolute(input_path)) {
+		const exists = await fs_exists(input_path);
+		const is_directory = exists && (await stat(input_path)).isDirectory();
+		add_possible_paths(input_path, is_directory ? input_path : dirname(input_path));
+	} else {
+		for (const root_dir of root_dirs) {
+			add_possible_paths(join(root_dir, input_path), root_dir);
+		}
+	}
+	return Array.from(possible_paths);
+};
+
+export interface ResolvedInputPath {
+	input_path: InputPath;
+	id: PathId;
+	is_directory: boolean;
+	root_dir: PathId;
+}
+
+export interface ResolvedInputFile {
+	id: PathId;
+	input_path: InputPath;
+	resolved_input_path: ResolvedInputPath;
+}
+
+export interface ResolvedInputPaths {
+	resolved_input_paths: Array<ResolvedInputPath>;
+	possible_paths_by_input_path: Map<InputPath, Array<PossiblePath>>;
+	unmapped_input_paths: Array<InputPath>;
+}
+
+/**
+ * Gets the path data for each input path, checking the filesystem for the possibilities
+ * and stopping at the first existing file or falling back to the first existing directory.
+ * If none is found for an input path, it's added to `unmapped_input_paths`.
+ */
+export const resolve_input_paths = async (
+	input_paths: Array<InputPath>,
+	root_dirs: Array<PathId>,
+	extensions: Array<string>,
+): Promise<ResolvedInputPaths> => {
+	const resolved_input_paths: Array<ResolvedInputPath> = [];
+	const possible_paths_by_input_path: Map<InputPath, Array<PossiblePath>> = new Map();
+	const unmapped_input_paths: Array<InputPath> = [];
+	for (const input_path of input_paths) {
+		let found_file: [PathInfo, PossiblePath] | null = null;
+		let found_dirs: Array<[PathInfo, PossiblePath]> | null = null;
+		// eslint-disable-next-line no-await-in-loop
+		const possible_paths = await get_possible_paths(input_path, root_dirs, extensions);
+		possible_paths_by_input_path.set(input_path, possible_paths);
+
+		// Find the first existing file path or fallback to the first directory path.
+		for (const possible_path of possible_paths) {
+			// eslint-disable-next-line no-await-in-loop
+			if (!(await fs_exists(possible_path.id))) continue;
+			// eslint-disable-next-line no-await-in-loop
+			const stats = await stat(possible_path.id);
+			if (stats.isDirectory()) {
+				found_dirs ??= [];
+				found_dirs.push([{id: possible_path.id, is_directory: stats.isDirectory()}, possible_path]);
+			} else {
+				found_file = [{id: possible_path.id, is_directory: stats.isDirectory()}, possible_path];
+				break;
+			}
+		}
+		if (found_file) {
+			resolved_input_paths.push({
+				input_path,
+				id: found_file[0].id,
+				is_directory: found_file[0].is_directory,
+				root_dir: found_file[1].root_dir,
+			});
+		} else if (found_dirs) {
+			for (const found_dir of found_dirs) {
+				resolved_input_paths.push({
+					input_path,
+					id: found_dir[0].id,
+					is_directory: found_dir[0].is_directory,
+					root_dir: found_dir[1].root_dir,
+				});
+			}
+		} else {
+			unmapped_input_paths.push(input_path);
+		}
+	}
+	return {
+		resolved_input_paths,
+		possible_paths_by_input_path,
+		unmapped_input_paths,
+	};
+};
+
+export interface ResolvedInputFiles {
+	resolved_input_files: Array<ResolvedInputFile>;
+	resolved_input_files_by_root_dir: Map<PathId, Array<ResolvedInputFile>>;
+	input_directories_with_no_files: Array<InputPath>;
+}
+
+/**
+ * Finds all of the matching files for the given input paths.
+ * De-dupes source ids.
+ */
+export const resolve_input_files = async (
+	resolved_input_paths: Array<ResolvedInputPath>,
+	search: (dir: string) => Promise<Array<ResolvedPath>> = fs_search,
+): Promise<ResolvedInputFiles> => {
+	const resolved_input_files: Array<ResolvedInputFile> = [];
+	// Add all input paths initially, and remove each when resolved to a file.
+	const existing_path_ids: Set<PathId> = new Set();
+
+	let remaining = resolved_input_paths.slice();
+	const handle_found = (input_path: InputPath, id: PathId) => {
+		remaining = remaining.filter(
+			(r) => !(r.id === id || r.input_path === input_path || r.input_path === id), // `r.input_path === id` may be unnecessary
+		);
+	};
+
+	// TODO parallelize but would need to de-dupe and retain order
+	for (const resolved_input_path of resolved_input_paths) {
+		const {input_path, id, is_directory} = resolved_input_path;
+		if (is_directory) {
+			// Handle input paths that resolve to directories.
+			// eslint-disable-next-line no-await-in-loop
+			const files = await search(id);
+			if (!files.length) continue;
+			const path_ids: Array<PathId> = [];
+			for (const {path, is_directory} of files) {
+				if (is_directory) continue;
+				const path_id = join(id, path);
+				if (!existing_path_ids.has(path_id)) {
+					existing_path_ids.add(path_id);
+					path_ids.push(path_id);
+				}
+				handle_found(input_path, path_id);
+			}
+			if (!path_ids.length) continue;
+			const resolved_input_files_for_input_path: Array<ResolvedInputFile> = [];
+			for (const path_id of path_ids) {
+				const resolved_input_file: ResolvedInputFile = {
+					id: path_id,
+					input_path,
+					resolved_input_path,
+				};
+				resolved_input_files.push(resolved_input_file);
+				resolved_input_files_for_input_path.push(resolved_input_file);
+			}
+		} else {
+			if (!existing_path_ids.has(id)) {
+				// Handle input paths that resolve to files.
+				existing_path_ids.add(id);
+				const resolved_input_file: ResolvedInputFile = {id, input_path, resolved_input_path};
+				resolved_input_files.push(resolved_input_file);
+			}
+			handle_found(input_path, id);
+		}
+	}
+	return {
+		resolved_input_files,
+		resolved_input_files_by_root_dir: resolved_input_files.reduce((map, resolved_input_file) => {
+			const {root_dir} = resolved_input_file.resolved_input_path;
+			if (map.has(root_dir)) {
+				map.get(root_dir)!.push(resolved_input_file);
+			} else {
+				map.set(root_dir, [resolved_input_file]);
+			}
+			return map;
+		}, new Map<PathId, Array<ResolvedInputFile>>()),
+		input_directories_with_no_files: remaining.map((r) => r.input_path),
+	};
+};

package/src/lib/invoke.ts

@@ -0,0 +1,34 @@
+import {attach_process_error_handler} from '@fuzdev/fuz_util/process.js';
+import {configure_print_colors} from '@fuzdev/fuz_util/print.js';
+
+import {invoke_task} from './invoke_task.ts';
+import {to_task_args} from './args.ts';
+import {load_gro_config} from './gro_config.ts';
+import {sveltekit_sync_if_obviously_needed} from './sveltekit_helpers.ts';
+
+/*
+
+This module invokes the Gro CLI which in turn invokes tasks.
+Tasks are the CLI's primary concept.
+To learn more about them, see `src/docs/task.md`.
+
+When the CLI is invoked it passes the first CLI arg as `task_name` to `invoke_task`,
+and the rest of the args are forwarded to the task's `run` function.
+
+*/
+
+// handle uncaught errors
+attach_process_error_handler({
+	to_error_label: (err) => (err.constructor.name === 'TaskError' ? 'TaskError' : null),
+	map_error_text: (err) => (err.constructor.name === 'SilentError' ? '' : null),
+});
+
+if (!process.env.NO_COLOR) {
+	const {styleText} = await import('node:util');
+	configure_print_colors(styleText);
+}
+
+await sveltekit_sync_if_obviously_needed();
+
+const {task_name, args} = to_task_args();
+await invoke_task(task_name, args, await load_gro_config());

package/src/lib/invoke_task.ts

@@ -0,0 +1,139 @@
+import type {Args} from '@fuzdev/fuz_util/args.js';
+import {Logger} from '@fuzdev/fuz_util/log.js';
+import {print_ms, print_timings} from '@fuzdev/fuz_util/print.js';
+import {create_stopwatch, Timings} from '@fuzdev/fuz_util/timings.js';
+import {styleText as st} from 'node:util';
+
+import {to_forwarded_args} from './args.ts';
+import {run_task} from './run_task.ts';
+import {to_input_path, RawInputPath} from './input_path.ts';
+import {find_tasks, load_tasks, SilentError} from './task.ts';
+import {package_json_load_for_gro} from './package_json.ts';
+import {log_tasks, log_error_reasons} from './task_logging.ts';
+import type {GroConfig} from './gro_config.ts';
+import {Filer} from './filer.ts';
+
+/**
+ * Invokes Gro tasks by name using the filesystem as the source.
+ *
+ * When a task is invoked,
+ * Gro first searches for tasks in the current working directory.
+ * and falls back to searching Gro's directory, if the two are different.
+ * See `src/lib/input_path.ts` for info about what "task_name" can refer to.
+ * If it matches a directory, all of the tasks within it are logged,
+ * both in the current working directory and Gro.
+ *
+ * This code is particularly hairy because
+ * we're accepting a wide range of user input
+ * and trying to do the right thing.
+ * Precise error messages are especially difficult and
+ * there are some subtle differences in the complex logical branches.
+ * The comments describe each condition.
+ *
+ * @param task_name - The name of the task to invoke.
+ * @param args - The CLI args to pass to the task.
+ * @param config - The Gro configuration.
+ * @param initial_timings - The timings to use for the top-level task, `null` for composed tasks.
+ */
+export const invoke_task = async (
+	task_name: RawInputPath,
+	args: Args | undefined,
+	config: GroConfig,
+	initial_filer?: Filer,
+	initial_timings?: Timings | null,
+	parent_log?: Logger,
+): Promise<void> => {
+	// Create child logger if parent exists, otherwise root logger
+	const log_label = task_name || 'gro';
+	const log = parent_log ? parent_log.child(log_label) : new Logger(log_label);
+	log.info('invoking', task_name ? st('cyan', task_name) : 'gro');
+
+	// track if we created the filer
+	const owns_filer = !initial_filer;
+	const filer = initial_filer ?? new Filer({log: log.child('filer'), ...config.filer_options});
+
+	const owns_timings = !initial_timings;
+	const timings = initial_timings ?? new Timings();
+
+	const total_timing = create_stopwatch();
+	const finish = async () => {
+		// cleanup filer only if we created it and it was initialized
+		if (owns_filer && filer.inited) {
+			await filer.close();
+		}
+
+		if (owns_timings) return; // kinda weird, print timings only for the top-level task
+		print_timings(timings, log);
+		log.info(`🕒 ${print_ms(total_timing())}`);
+	};
+
+	// Check if the caller just wants to see the version.
+	if (!task_name && (args?.version || args?.v)) {
+		const gro_package_json = await package_json_load_for_gro();
+		log.info(`${st('gray', 'v')}${st('cyan', gro_package_json.version)}`);
+		await finish();
+		return;
+	}
+
+	// Resolve the input path for the provided task name.
+	const input_path = to_input_path(task_name);
+
+	const {task_root_dirs} = config;
+
+	// Find the task or directory specified by the `input_path`.
+	// Fall back to searching the Gro directory as well.
+	const found = await find_tasks([input_path], task_root_dirs, config);
+	if (!found.ok) {
+		log_error_reasons(log, found.reasons);
+		throw new SilentError();
+	}
+
+	// Found a match either in the current working directory or Gro's directory.
+	const found_tasks = found.value;
+	const {resolved_input_files} = found_tasks;
+
+	// Load the task module.
+	const loaded = await load_tasks(found_tasks);
+	if (!loaded.ok) {
+		log_error_reasons(log, loaded.reasons);
+		throw new SilentError();
+	}
+	const loaded_tasks = loaded.value;
+
+	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();
+		return;
+	}
+
+	// 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]!;
+	log.info(
+		`→ ${st('cyan', task.name)} ${(task.mod.task.summary && st('gray', task.mod.task.summary)) ?? ''}`,
+	);
+
+	const timing_to_run_task = timings.start('run task ' + task_name);
+	const result = await run_task(
+		task,
+		{...args, ...to_forwarded_args(`gro ${task.name}`)},
+		invoke_task,
+		config,
+		filer,
+		log,
+		timings,
+	);
+	timing_to_run_task();
+	if (!result.ok) {
+		log.info(`${st('red', '🞩')} ${st('cyan', task.name)}`);
+		log_error_reasons(log, [result.reason]);
+		throw result.error;
+	}
+	log.info(`✓ ${st('cyan', task.name)}`);
+
+	await finish();
+};

package/src/lib/lint.task.ts

@@ -0,0 +1,39 @@
+import {args_serialize} from '@fuzdev/fuz_util/args.js';
+import {print_spawn_result} from '@fuzdev/fuz_util/process.js';
+import {z} from 'zod';
+
+import {to_forwarded_args} from './args.ts';
+import {find_cli, spawn_cli} from './cli.ts';
+import {TaskError, type Task} from './task.ts';
+
+const ESLINT_CLI = 'eslint';
+
+/** @nodocs */
+export const Args = z.strictObject({
+	_: z.array(z.string()).meta({description: 'paths to serve'}).default([]),
+	eslint_cli: z.string().meta({description: 'the ESLint CLI to use'}).default(ESLINT_CLI),
+});
+export type Args = z.infer<typeof Args>;
+
+/** @nodocs */
+export const task: Task<Args> = {
+	summary: 'run eslint',
+	Args,
+	run: async ({log, args}): Promise<void> => {
+		const {_, eslint_cli} = args;
+
+		const found_eslint_cli = await find_cli(eslint_cli);
+		if (!found_eslint_cli) {
+			// TODO maybe make this an option?
+			log.info('ESLint is not installed; skipping linting');
+			return;
+		}
+
+		const forwarded_args = {_, 'max-warnings': 0, ...to_forwarded_args(eslint_cli)};
+		const serialized_args = args_serialize(forwarded_args);
+		const eslintResult = await spawn_cli(found_eslint_cli, serialized_args, log);
+		if (!eslintResult?.ok) {
+			throw new TaskError(`ESLint found some problems. ${print_spawn_result(eslintResult!)}`);
+		}
+	},
+};

package/src/lib/loader.ts

@@ -0,0 +1,229 @@
+import {compile, compileModule, preprocess} from 'svelte/compiler';
+import {fileURLToPath, pathToFileURL} from 'node:url';
+import {dirname, join} from 'node:path';
+import type {LoadHook, ResolveHook} from 'node:module';
+import {readFileSync} from 'node:fs';
+import ts_blank_space from 'ts-blank-space';
+
+import {render_env_shim_module} from './sveltekit_shim_env.ts';
+import {
+	render_sveltekit_shim_app_environment,
+	render_sveltekit_shim_app_paths,
+	SVELTEKIT_SHIM_APP_ENVIRONMENT_MATCHER,
+	SVELTEKIT_SHIM_APP_PATHS_MATCHER,
+	sveltekit_shim_app_specifiers,
+} from './sveltekit_shim_app.ts';
+import {default_svelte_config} from './svelte_config.ts';
+import {paths} from './paths.ts';
+import {TS_MATCHER, SVELTE_MATCHER, SVELTE_RUNES_MATCHER} from './constants.ts';
+import {resolve_specifier} from './resolve_specifier.ts';
+import {map_sveltekit_aliases} from './sveltekit_helpers.ts';
+
+// TODO get out of the loader business, starting with https://nodejs.org/api/typescript.html#type-stripping
+
+/*
+
+Usage via `$lib/register.ts`:
+
+```bash
+node --import @fuzdev/gro/register.js foo.ts
+```
+
+Usage via `$lib/run.task.ts`:
+
+```bash
+gro run foo.ts
+```
+
+Direct usage without register (see also `$lib/gro.ts`):
+
+```bash
+node --import 'data:text/javascript,import {register} from "node:module"; import {pathToFileURL} from "node:url"; register("@fuzdev/gro/loader.js", pathToFileURL("./"));' --experimental-import-meta-resolve --experimental-strip-types' foo.ts
+```
+
+TODO how to improve that gnarly import line? was originally designed for the now-deprecated `--loader`
+
+*/
+
+// TODO sourcemaps for the svelte preprocessors
+// TODO `import.meta.resolve` wasn't available in loaders when this was first implemented, but might be now
+
+// dev is always true in the loader
+const dev = true;
+
+const dir = paths.root;
+
+const {
+	alias,
+	base_url,
+	assets_url,
+	env_dir,
+	private_prefix,
+	public_prefix,
+	svelte_compile_options,
+	svelte_compile_module_options,
+	svelte_preprocessors,
+} = default_svelte_config;
+
+const aliases = Object.entries(alias);
+
+const RAW_MATCHER = /(%3Fraw|\.css|\.svg)$/; // TODO others? configurable?
+
+/** @nodocs */
+export const load: LoadHook = async (url, context, nextLoad) => {
+	// console.log(`url`, url);
+	if (SVELTEKIT_SHIM_APP_PATHS_MATCHER.test(url)) {
+		// SvelteKit `$app/paths` shim
+		return {
+			format: 'module',
+			shortCircuit: true,
+			source: render_sveltekit_shim_app_paths(base_url, assets_url),
+		};
+	} else if (SVELTEKIT_SHIM_APP_ENVIRONMENT_MATCHER.test(url)) {
+		// SvelteKit `$app/environment` shim
+		return {
+			format: 'module',
+			shortCircuit: true,
+			source: render_sveltekit_shim_app_environment(dev),
+		};
+	} else if (SVELTE_RUNES_MATCHER.test(url)) {
+		// Svelte runes in js/ts, `.svelte.ts`
+		const filename = fileURLToPath(url);
+		const loaded = await nextLoad(url, {...context, format: 'module-typescript'});
+		const raw_source = loaded.source?.toString(); // eslint-disable-line @typescript-eslint/no-base-to-string
+		if (raw_source == null) throw Error(`Failed to load ${url}`);
+		// TODO should be nice if we could use Node's builtin amaro transform, but I couldn't find a way after digging into the source, AFAICT it's internal and not exposed
+		const source = ts_blank_space(raw_source); // TODO was using oxc-transform and probably should, but this doesn't require sourcemaps, and it's still alpha as of May 2025
+		const transformed = compileModule(source, {
+			...svelte_compile_module_options,
+			dev,
+			filename,
+		});
+		return {format: 'module', shortCircuit: true, source: transformed.js.code};
+	} else if (TS_MATCHER.test(url)) {
+		// ts but not `.svelte.ts`
+		return nextLoad(url, {...context, format: 'module-typescript'});
+	} else if (SVELTE_MATCHER.test(url)) {
+		// Svelte, `.svelte`
+		const loaded = await nextLoad(url, {...context, format: 'module'});
+		const raw_source = loaded.source!.toString(); // eslint-disable-line @typescript-eslint/no-base-to-string
+		const filename = fileURLToPath(url);
+		const preprocessed = svelte_preprocessors // TODO @many use sourcemaps (and diagnostics?)
+			? await preprocess(raw_source, svelte_preprocessors, {filename})
+			: null;
+		const source = preprocessed?.code ?? raw_source;
+		const transformed = compile(source, {...svelte_compile_options, dev, filename});
+		return {format: 'module', shortCircuit: true, source: transformed.js.code};
+	} else if (context.importAttributes.type === 'json') {
+		// json - any file extension
+		// TODO probably follow esbuild and also export every top-level property for objects from the module for good treeshaking - https://esbuild.github.io/content-types/#json (type generation?)
+		// TODO why is removing the importAttributes needed? can't pass no context either -
+		//   error: `Module "file:///home/user/dev/repo/foo.json" is not of type "json"`
+		const loaded = await nextLoad(url, {...context, importAttributes: undefined});
+		const raw_source = loaded.source?.toString(); // eslint-disable-line @typescript-eslint/no-base-to-string
+		if (raw_source == null) throw Error(`Failed to load ${url}`);
+		const source = `export default ` + raw_source;
+		return {format: 'module', shortCircuit: true, source};
+	} else if (RAW_MATCHER.test(url)) {
+		// raw text imports like `?raw`, `.css`, `.svg`
+		const filename = fileURLToPath(url.endsWith('%3Fraw') ? url.substring(0, url.length - 6) : url);
+		const raw_source = readFileSync(filename, 'utf8');
+		const source =
+			'export default `' + raw_source.replaceAll('\\', '\\\\').replaceAll('`', '\\`') + '`;';
+		return {format: 'module', shortCircuit: true, source};
+	} else {
+		// SvelteKit `$env`
+		// TODO use `format` from the resolve hook to speed this up and make it simpler
+		if (context.format === 'sveltekit-env') {
+			let mode: 'static' | 'dynamic';
+			let visibility: 'public' | 'private';
+			switch (context.importAttributes.virtual) {
+				case '$env/static/public': {
+					mode = 'static';
+					visibility = 'public';
+					break;
+				}
+				case '$env/static/private': {
+					mode = 'static';
+					visibility = 'private';
+					break;
+				}
+				case '$env/dynamic/public': {
+					mode = 'dynamic';
+					visibility = 'public';
+					break;
+				}
+				case '$env/dynamic/private': {
+					mode = 'dynamic';
+					visibility = 'private';
+					break;
+				}
+				default: {
+					throw Error(`Unknown $env import: ${context.importAttributes.virtual}`);
+				}
+			}
+			const source = render_env_shim_module(
+				dev,
+				mode,
+				visibility,
+				public_prefix,
+				private_prefix,
+				env_dir,
+			);
+			return {format: 'module', shortCircuit: true, source};
+		}
+	}
+
+	// fallback to default behavior
+	return nextLoad(url, context);
+};
+
+/** @nodocs */
+export const resolve: ResolveHook = async (specifier, context, nextResolve) => {
+	let s = specifier;
+
+	// Support SvelteKit `$env` imports
+	if (
+		s === '$env/static/public' ||
+		s === '$env/static/private' ||
+		s === '$env/dynamic/public' ||
+		s === '$env/dynamic/private'
+	) {
+		// The returned `url` is validated before `load` is called,
+		// so we need a slightly roundabout strategy to pass through the specifier for virtual files.
+		return {
+			url: pathToFileURL(join(dir, 'src/lib', s)).href,
+			format: 'sveltekit-env',
+			importAttributes: {virtual: s}, // TODO idk I'm just making this up
+			shortCircuit: true,
+		};
+	}
+
+	// Support SvelteKit `$app` imports, including from node_modules
+	const shimmed = sveltekit_shim_app_specifiers.get(s);
+	if (shimmed !== undefined) {
+		return nextResolve(shimmed, context);
+	}
+
+	// Apply SvelteKit aliases (handles self-referencing packages like @fuzdev/fuz_util -> src/lib)
+	s = map_sveltekit_aliases(s, aliases);
+
+	// Bare specifiers (not starting with . or /) use Node's default resolution
+	if (s[0] !== '.' && s[0] !== '/') {
+		return nextResolve(s, context);
+	}
+
+	// Resolve paths using Vite conventions
+	const parent_url = context.parentURL;
+	if (!parent_url) {
+		return nextResolve(s, context);
+	}
+
+	const resolved = await resolve_specifier(s, dirname(fileURLToPath(parent_url)));
+
+	return {
+		url: pathToFileURL(resolved.path_id_with_querystring).href,
+		format: 'module',
+		shortCircuit: true,
+	};
+};