@ryanatkn/gro 0.129.4 → 0.129.6

package/src/lib/gro_plugin_server.ts

@@ -0,0 +1,288 @@
+import {spawn_restartable_process, type Restartable_Process} from '@ryanatkn/belt/process.js';
+import * as esbuild from 'esbuild';
+import type {Config as SvelteKitConfig} from '@sveltejs/kit';
+import {join, resolve} from 'node:path';
+import {identity} from '@ryanatkn/belt/function.js';
+import {strip_before, strip_end} from '@ryanatkn/belt/string.js';
+import type {Result} from '@ryanatkn/belt/result.js';
+import {existsSync} from 'node:fs';
+
+import type {Plugin} from './plugin.js';
+import {base_path_to_path_id, LIB_DIRNAME, paths} from './paths.js';
+import type {Path_Id} from './path.js';
+import {GRO_DEV_DIRNAME, SERVER_DIST_PATH} from './path_constants.js';
+import {watch_dir, type Watch_Node_Fs} from './watch_dir.js';
+import {init_sveltekit_config} from './sveltekit_config.js';
+import {esbuild_plugin_sveltekit_shim_app} from './esbuild_plugin_sveltekit_shim_app.js';
+import {esbuild_plugin_sveltekit_shim_env} from './esbuild_plugin_sveltekit_shim_env.js';
+import {print_build_result, to_define_import_meta_env} from './esbuild_helpers.js';
+import {esbuild_plugin_sveltekit_shim_alias} from './esbuild_plugin_sveltekit_shim_alias.js';
+import {esbuild_plugin_external_worker} from './esbuild_plugin_external_worker.js';
+import {esbuild_plugin_sveltekit_local_imports} from './esbuild_plugin_sveltekit_local_imports.js';
+import {esbuild_plugin_svelte} from './esbuild_plugin_svelte.js';
+import {throttle} from './throttle.js';
+import {sveltekit_config_global} from './sveltekit_config_global.js';
+
+// TODO sourcemap as a hoisted option? disable for production by default - or like `outpaths`, passed a `dev` param
+
+export const SERVER_SOURCE_ID = base_path_to_path_id(LIB_DIRNAME + '/server/server.ts');
+
+export const has_server = (path = SERVER_SOURCE_ID): Result<object, {message: string}> => {
+	if (!existsSync(path)) {
+		return {ok: false, message: `no server file found at ${path}`};
+	}
+	return {ok: true};
+};
+
+export interface Options {
+	/**
+	 * same as esbuild's `entryPoints`
+	 */
+	entry_points?: string[];
+	/**
+	 * @default cwd
+	 */
+	dir?: string;
+	/**
+	 * Returns the `Outpaths` given a `dev` param.
+	 * Decoupling this from plugin creation allows it to be created generically,
+	 * so the build and dev tasks can be the source of truth for `dev`.
+	 */
+	outpaths?: Create_Outpaths;
+	/**
+	 * @default SvelteKit's `.env`, `.env.development`, and `.env.production`
+	 */
+	env_files?: string[];
+	/**
+	 * @default process.env
+	 */
+	ambient_env?: Record<string, string>;
+	/**
+	 * @default loaded from `${cwd}/${SVELTEKIT_CONFIG_FILENAME}`
+	 */
+	sveltekit_config?: SvelteKitConfig;
+	/**
+	 * @default 'esnext'
+	 */
+	target?: string;
+	/**
+	 * Optionally map the esbuild options.
+	 * @default identity
+	 */
+	esbuild_build_options?: (base_options: esbuild.BuildOptions) => esbuild.BuildOptions;
+	/**
+	 * Milliseconds to throttle rebuilds.
+	 * Should be longer than it takes to build to avoid backpressure.
+	 * @default 1000
+	 */
+	rebuild_throttle_delay?: number; // TODO could detect the backpressure problem and at least warn, shouldn't be a big deal
+	/**
+	 * The CLI command to run the server, like `'node'` or `'bun'` or `'deno'`.
+	 * Receives the path to the server js file as its argument.
+	 * @default 'node'
+	 */
+	cli_command?: string;
+	/**
+	 * Whether to run the server or not after building.
+	 * @default dev
+	 */
+	run?: boolean;
+}
+
+export interface Outpaths {
+	/**
+	 * @default '.gro/dev' or 'dist_server'
+	 */
+	outdir: string;
+	/**
+	 * @default 'src/lib'
+	 */
+	outbase: string;
+	/**
+	 * @default 'server.js'
+	 */
+	outname: string;
+}
+
+export type Create_Outpaths = (dev: boolean) => Outpaths;
+
+export const gro_plugin_server = ({
+	entry_points = [SERVER_SOURCE_ID],
+	dir = process.cwd(),
+	outpaths = (dev) => ({
+		outdir: join(dir, dev ? GRO_DEV_DIRNAME : SERVER_DIST_PATH),
+		outbase: paths.lib,
+		outname: 'server/server.js',
+	}),
+	env_files,
+	ambient_env,
+	sveltekit_config,
+	target = 'esnext',
+	esbuild_build_options = identity,
+	rebuild_throttle_delay = 1000,
+	cli_command = 'node',
+	run, // `dev` default is not available in this scope
+}: Options = {}): Plugin => {
+	let build_ctx: esbuild.BuildContext | null = null;
+	let watcher: Watch_Node_Fs | null = null;
+	let server_process: Restartable_Process | null = null;
+	let deps: Set<Path_Id> | null = null;
+
+	return {
+		name: 'gro_plugin_server',
+		setup: async ({dev, watch, timings, log}) => {
+			const parsed_sveltekit_config =
+				!sveltekit_config && strip_end(dir, '/') === process.cwd()
+					? sveltekit_config_global
+					: await init_sveltekit_config(sveltekit_config ?? dir);
+			const {
+				alias,
+				base_url,
+				assets_url,
+				env_dir,
+				private_prefix,
+				public_prefix,
+				svelte_compile_options,
+				svelte_compile_module_options,
+				svelte_preprocessors,
+			} = parsed_sveltekit_config;
+
+			// TODO hacky
+			if (svelte_compile_options.generate === undefined) {
+				svelte_compile_options.generate = 'server';
+			}
+			if (svelte_compile_module_options.generate === undefined) {
+				svelte_compile_module_options.generate = 'server';
+			}
+
+			const {outbase, outdir, outname} = outpaths(dev);
+
+			const server_outpath = join(outdir, outname);
+
+			const timing_to_esbuild_create_context = timings.start('create build context');
+
+			const build_options = esbuild_build_options({
+				outdir,
+				outbase,
+				format: 'esm',
+				platform: 'node',
+				packages: 'external',
+				bundle: true,
+				target,
+				metafile: watch,
+			});
+
+			build_ctx = await esbuild.context({
+				entryPoints: entry_points.map((path) => resolve(dir, path)),
+				plugins: [
+					esbuild_plugin_sveltekit_shim_app({dev, base_url, assets_url}),
+					esbuild_plugin_sveltekit_shim_env({
+						dev,
+						public_prefix,
+						private_prefix,
+						env_dir,
+						env_files,
+						ambient_env,
+					}),
+					esbuild_plugin_sveltekit_shim_alias({dir, alias}),
+					esbuild_plugin_external_worker({
+						dev,
+						build_options,
+						dir,
+						svelte_compile_options,
+						svelte_compile_module_options,
+						svelte_preprocessors,
+						alias,
+						base_url,
+						public_prefix,
+						private_prefix,
+						env_dir,
+						env_files,
+						ambient_env,
+						log,
+					}),
+					esbuild_plugin_svelte({
+						dir,
+						svelte_compile_options,
+						svelte_compile_module_options,
+						svelte_preprocessors,
+					}),
+					esbuild_plugin_sveltekit_local_imports(),
+				],
+				define: to_define_import_meta_env(dev, base_url),
+				...build_options,
+			});
+
+			timing_to_esbuild_create_context();
+
+			const rebuild = throttle(async () => {
+				let build_result;
+				try {
+					build_result = await build_ctx!.rebuild();
+				} catch (err) {
+					log.error('[gro_plugin_server] build failed', err);
+					return;
+				}
+				const {metafile} = build_result;
+				if (!metafile) return;
+				print_build_result(log, build_result);
+				deps = parse_deps(metafile.inputs, dir);
+				server_process?.restart();
+			}, rebuild_throttle_delay);
+
+			await rebuild();
+
+			// uses chokidar instead of esbuild's watcher for efficiency
+			if (watch) {
+				let watcher_ready = false;
+				// TODO maybe reuse this watcher globally via an option,
+				// because it watches all of `$lib`, and that means it excludes `$routes`
+				// while also including a lot of client files we don't care about,
+				// but we can't discern which of `$lib` to watch ahead of time
+				watcher = watch_dir({
+					dir: paths.lib,
+					on_change: (change) => {
+						if (!watcher_ready || !deps?.has(change.path)) return;
+						void rebuild();
+					},
+				});
+				await watcher.init();
+				watcher_ready = true;
+			}
+
+			if (!existsSync(server_outpath)) {
+				throw Error(`Node server failed to start due to missing file: ${server_outpath}`);
+			}
+
+			if (run ?? dev) {
+				server_process = spawn_restartable_process(cli_command, [server_outpath]);
+			}
+		},
+		teardown: async () => {
+			if (server_process) {
+				const s = server_process; // avoid possible issue where a build is in progress, don't want to issue a restart, could be fixed upstream in `spawn_restartable_process`
+				server_process = null;
+				await s.kill();
+			}
+			if (watcher) {
+				await watcher.close();
+			}
+			if (build_ctx) {
+				await build_ctx.dispose();
+			}
+		},
+	};
+};
+
+/**
+ * The esbuild metafile contains the paths in `entryPoints` relative to the `dir`
+ * even though we're resolving them to absolute paths before passing them to esbuild,
+ * so we resolve them here relative to the `dir`.
+ */
+const parse_deps = (metafile_inputs: Record<string, unknown>, dir: string): Set<string> => {
+	const deps: Set<string> = new Set();
+	for (const key in metafile_inputs) {
+		deps.add(resolve(dir, strip_before(key, ':')));
+	}
+	return deps;
+};

package/src/lib/gro_plugin_sveltekit_app.ts

@@ -0,0 +1,257 @@
+import type {Spawned_Process} from '@ryanatkn/belt/process.js';
+import {cpSync, mkdirSync, rmSync, writeFileSync, existsSync} from 'node:fs';
+import {dirname, join} from 'node:path';
+
+import type {Plugin} from './plugin.js';
+import {serialize_args, to_forwarded_args} from './args.js';
+import {serialize_package_json, type Map_Package_Json, load_package_json} from './package_json.js';
+import {Task_Error} from './task.js';
+import {find_cli, spawn_cli, spawn_cli_process} from './cli.js';
+import {type Map_Src_Json, serialize_src_json, create_src_json} from './src_json.js';
+import {DEFAULT_EXPORTS_EXCLUDER} from './config.js';
+import {sveltekit_config_global} from './sveltekit_config_global.js';
+import {SOURCE_DIRNAME} from './path_constants.js';
+import {VITE_CLI} from './sveltekit_helpers.js';
+
+export interface Options {
+	/**
+	 * Used for finalizing a SvelteKit build like adding a `.nojekyll` file for GitHub Pages.
+	 * @default 'github_pages'
+	 */
+	host_target?: Host_Target;
+
+	/**
+	 * If truthy, adds `/.well-known/package.json` to the static output.
+	 * If a function, maps the value.
+	 */
+	well_known_package_json?: boolean | Map_Package_Json;
+
+	/**
+	 * If truthy, adds `/.well-known/src.json` and `/.well-known/src/` to the static output.
+	 * If a function, maps the value.
+	 */
+	well_known_src_json?: boolean | Map_Src_Json;
+
+	/**
+	 * If truthy, copies `src/` to `/.well-known/src/` to the static output.
+	 * Pass a function to customize which files get copied.
+	 */
+	well_known_src_files?: boolean | Copy_File_Filter;
+	/**
+	 * The Vite CLI to use.
+	 */
+	vite_cli?: string;
+}
+
+export type Host_Target = 'github_pages' | 'static' | 'node';
+
+export type Copy_File_Filter = (file_path: string) => boolean;
+
+export const gro_plugin_sveltekit_app = ({
+	host_target = 'github_pages',
+	well_known_package_json,
+	well_known_src_json,
+	well_known_src_files,
+	vite_cli = VITE_CLI,
+}: Options = {}): Plugin => {
+	let sveltekit_process: Spawned_Process | undefined = undefined;
+	return {
+		name: 'gro_plugin_sveltekit_app',
+		setup: async ({dev, watch, log}) => {
+			const found_vite_cli = find_cli(vite_cli);
+			if (!found_vite_cli)
+				throw new Error(`Failed to find Vite CLI \`${vite_cli}\`, do you need to run \`npm i\`?`);
+			if (dev) {
+				// `vite dev` in development mode
+				if (watch) {
+					const serialized_args = ['dev', ...serialize_args(to_forwarded_args(vite_cli))];
+					sveltekit_process = spawn_cli_process(found_vite_cli, serialized_args, log);
+				} else {
+					log.debug(
+						`the SvelteKit app plugin is loaded but will not output anything` +
+							' because `dev` is true and `watch` is false',
+					);
+				}
+			} else {
+				// `vite build` in production mode
+
+				// `.well-known/package.json`
+				const package_json = load_package_json(); // TODO put in plugin context? same with sveltekit config?
+				if (well_known_package_json === undefined) {
+					well_known_package_json = package_json.public; // eslint-disable-line no-param-reassign
+				}
+				const mapped_package_json = !well_known_package_json
+					? null
+					: well_known_package_json === true
+						? package_json
+						: await well_known_package_json(package_json);
+				const serialized_package_json =
+					mapped_package_json && serialize_package_json(mapped_package_json);
+
+				// `.well-known/src.json` and `.well-known/src/`
+				const final_package_json = mapped_package_json ?? package_json;
+				const src_json = create_src_json(final_package_json);
+				if (well_known_src_json === undefined) {
+					well_known_src_json = final_package_json.public; // eslint-disable-line no-param-reassign
+				}
+				const mapped_src_json = !well_known_src_json
+					? null
+					: well_known_src_json === true
+						? src_json
+						: await well_known_src_json(src_json);
+				const serialized_src_json = mapped_src_json && serialize_src_json(mapped_src_json);
+
+				// TODO this strategy means the files aren't available during development --
+				// maybe a Vite middleware is best? what if this plugin added its plugin to your `vite.config.ts`?
+
+				// copy files to `static` before building, in such a way
+				// that's non-destructive to existing files and dirs and easy to clean up
+				const {assets_path} = sveltekit_config_global;
+				const cleanups: Cleanup[] = [
+					serialized_package_json
+						? create_temporarily(
+								join(assets_path, '.well-known/package.json'),
+								serialized_package_json,
+							)
+						: null,
+					serialized_src_json
+						? create_temporarily(join(assets_path, '.well-known/src.json'), serialized_src_json)
+						: null,
+					serialized_src_json && well_known_src_files
+						? copy_temporarily(
+								SOURCE_DIRNAME,
+								assets_path,
+								'.well-known',
+								well_known_src_files === true
+									? (file_path) => !DEFAULT_EXPORTS_EXCLUDER.test(file_path)
+									: well_known_src_files,
+							)
+						: null,
+					/**
+					 * GitHub pages processes everything with Jekyll by default,
+					 * breaking things like files and dirs prefixed with an underscore.
+					 * This adds a `.nojekyll` file to the root of the output
+					 * to tell GitHub Pages to treat the outputs as plain static files.
+					 */
+					host_target === 'github_pages'
+						? create_temporarily(join(assets_path, '.nojekyll'), '')
+						: null,
+				].filter((v) => v != null);
+				const cleanup = () => {
+					for (const c of cleanups) c();
+				};
+				try {
+					const serialized_args = ['build', ...serialize_args(to_forwarded_args(vite_cli))];
+					const spawned = await spawn_cli(found_vite_cli, serialized_args, log);
+					if (!spawned?.ok) {
+						throw new Task_Error(`${vite_cli} build failed with exit code ${spawned?.code}`);
+					}
+				} catch (err) {
+					cleanup();
+					throw err;
+				}
+				cleanup();
+			}
+		},
+		teardown: async () => {
+			if (sveltekit_process) {
+				sveltekit_process.child.kill();
+				await sveltekit_process.closed;
+			}
+		},
+	};
+};
+
+type Cleanup = () => void;
+
+// TODO probably extract these, and create a common helper or merge them
+
+const copy_temporarily = (
+	source_path: string,
+	dest_dir: string,
+	dest_base_dir = '',
+	filter?: Copy_File_Filter,
+): Cleanup => {
+	const path = join(dest_dir, dest_base_dir, source_path);
+	const dir = dirname(path);
+
+	const dir_already_exists = existsSync(dir);
+	let root_created_dir: string | undefined;
+	if (!dir_already_exists) {
+		root_created_dir = to_root_dir_that_doesnt_exist(dir);
+		if (!root_created_dir) throw Error();
+		mkdirSync(dir, {recursive: true});
+	}
+
+	const path_already_exists = existsSync(path);
+	if (!path_already_exists) {
+		cpSync(source_path, path, {recursive: true, filter});
+	}
+
+	return () => {
+		if (!dir_already_exists) {
+			if (!root_created_dir) throw Error();
+			if (existsSync(root_created_dir)) {
+				rmSync(root_created_dir, {recursive: true});
+			}
+		} else if (!path_already_exists) {
+			if (existsSync(path)) {
+				rmSync(path, {recursive: true});
+			}
+		}
+	};
+};
+
+/**
+ * Creates a file at `path` with `contents` if it doesn't already exist,
+ * and returns a function that deletes the file and any created directories.
+ * @param path
+ * @param contents
+ * @returns cleanup function that deletes the file and any created dirs
+ */
+const create_temporarily = (path: string, contents: string): Cleanup => {
+	const dir = dirname(path);
+
+	const dir_already_exists = existsSync(dir);
+	let root_created_dir: string | undefined;
+	if (!dir_already_exists) {
+		root_created_dir = to_root_dir_that_doesnt_exist(dir);
+		if (!root_created_dir) throw Error();
+		mkdirSync(dir, {recursive: true});
+	}
+
+	const path_already_exists = existsSync(path);
+	if (!path_already_exists) {
+		writeFileSync(path, contents, 'utf8');
+	}
+
+	return () => {
+		if (!dir_already_exists) {
+			if (!root_created_dir) throw Error();
+			if (existsSync(root_created_dir)) {
+				rmSync(root_created_dir, {recursive: true});
+			}
+		} else if (!path_already_exists) {
+			if (existsSync(path)) {
+				rmSync(path);
+			}
+		}
+	};
+};
+
+/**
+ * Niche and probably needs refactoring,
+ * for `/a/b/DOESNT_EXIST/NOR_THIS/ETC` returns `/a/b/DOESNT_EXIST`
+ * where `/a/b` does exist on the filesystem and `DOESNT_EXIST` is not one of its subdirectories.
+ */
+const to_root_dir_that_doesnt_exist = (dir: string): string | undefined => {
+	let prev: string | undefined;
+	let d = dir;
+	do {
+		if (existsSync(d)) {
+			return prev;
+		}
+		prev = d;
+	} while ((d = dirname(d)));
+	throw Error('no dirs exist for ' + dir);
+};

package/src/lib/gro_plugin_sveltekit_library.ts

@@ -0,0 +1,74 @@
+import {print_spawn_result, spawn} from '@ryanatkn/belt/process.js';
+
+import type {Plugin} from './plugin.js';
+import {Task_Error} from './task.js';
+import {load_package_json} from './package_json.js';
+import {serialize_args, to_forwarded_args} from './args.js';
+import {find_cli, spawn_cli} from './cli.js';
+import {
+	SVELTE_PACKAGE_CLI,
+	has_sveltekit_library,
+	type Svelte_Package_Options,
+} from './sveltekit_helpers.js';
+
+export interface Options {
+	/**
+	 * The options passed to the SvelteKit packaging CLI.
+	 * @see https://kit.svelte.dev/docs/packaging#options
+	 */
+	svelte_package_options?: Svelte_Package_Options;
+	/**
+	 * The SvelteKit packaging CLI to use. Defaults to `svelte-package`.
+	 * @see https://kit.svelte.dev/docs/packaging
+	 */
+	svelte_package_cli?: string;
+}
+
+export const gro_plugin_sveltekit_library = ({
+	svelte_package_options,
+	svelte_package_cli = SVELTE_PACKAGE_CLI,
+}: Options = {}): Plugin => {
+	return {
+		name: 'gro_plugin_sveltekit_library',
+		setup: async ({log}) => {
+			const has_sveltekit_library_result = has_sveltekit_library();
+			if (!has_sveltekit_library_result.ok) {
+				throw new Task_Error(
+					'Failed to find SvelteKit library: ' + has_sveltekit_library_result.message,
+				);
+			}
+			const found_svelte_package_cli = find_cli(svelte_package_cli);
+			if (found_svelte_package_cli?.kind !== 'local') {
+				throw new Task_Error(
+					`Failed to find SvelteKit packaging CLI \`${svelte_package_cli}\`, do you need to run \`npm i\`?`,
+				);
+			}
+			const serialized_args = serialize_args({
+				...svelte_package_options,
+				...to_forwarded_args(svelte_package_cli),
+			});
+			await spawn_cli(found_svelte_package_cli, serialized_args, log);
+		},
+		adapt: async ({log, timings}) => {
+			const package_json = load_package_json();
+
+			// `npm link`
+			if (package_json.bin) {
+				const timing_to_npm_link = timings.start('npm link');
+				await Promise.all(
+					Object.values(package_json.bin).map(async (bin_path) => {
+						const chmod_result = await spawn('chmod', ['+x', bin_path]);
+						if (!chmod_result.ok)
+							log.error(`chmod on bin path ${bin_path} failed with code ${chmod_result.code}`);
+					}),
+				);
+				log.info(`linking`);
+				const link_result = await spawn('npm', ['link', '-f']); // TODO don't use `-f` unless necessary or at all?
+				if (!link_result.ok) {
+					throw new Task_Error(`Failed to link. ${print_spawn_result(link_result)}`);
+				}
+				timing_to_npm_link();
+			}
+		},
+	};
+};

package/src/lib/hash.test.ts

@@ -0,0 +1,33 @@
+import {suite} from 'uvu';
+import * as assert from 'uvu/assert';
+import {webcrypto} from 'node:crypto';
+
+import {to_hash} from './hash.js';
+
+/* test__to_hash */
+const test__to_hash = suite('to_hash');
+
+test__to_hash('turns a buffer into a string', async () => {
+	assert.type(await to_hash(Buffer.from('hey')), 'string');
+});
+
+test__to_hash('returns the same value given the same input', async () => {
+	assert.is(await to_hash(Buffer.from('hey')), await to_hash(Buffer.from('hey')));
+});
+
+test__to_hash('checks against an implementation copied from MDN', async () => {
+	const data = Buffer.from('some_test_string');
+	assert.is(await to_hash_from_mdn_example(data), await to_hash(data));
+});
+
+test__to_hash.run();
+/* test__to_hash */
+
+/**
+ * Copied from https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto/digest
+ * and compared against our implementation for extra assurances, because cryptography.
+ */
+const to_hash_from_mdn_example = async (data: Buffer): Promise<string> =>
+	Array.from(new Uint8Array(await webcrypto.subtle.digest('SHA-256', data)))
+		.map((h) => h.toString(16).padStart(2, '0'))
+		.join('');

package/src/lib/hash.ts

@@ -0,0 +1,19 @@
+import {webcrypto} from 'node:crypto';
+
+const {subtle} = webcrypto;
+
+/**
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto
+ */
+export const to_hash = async (
+	data: Buffer,
+	algorithm: 'SHA-1' | 'SHA-256' | 'SHA-384' | 'SHA-512' = 'SHA-256',
+): Promise<string> => {
+	const digested = await subtle.digest(algorithm, data);
+	const bytes = Array.from(new Uint8Array(digested));
+	let hex = '';
+	for (const h of bytes) {
+		hex += h.toString(16).padStart(2, '0');
+	}
+	return hex;
+};

package/src/lib/index.ts

@@ -0,0 +1,4 @@
+export type {Gro_Config, Create_Gro_Config, Raw_Gro_Config} from './config.js';
+export {type Plugin, replace_plugin} from './plugin.js';
+export type {Gen, Gen_Context} from './gen.js';
+export {type Task, type Task_Context, Task_Error} from './task.js';