@fuzdev/gro 0.192.0

package/src/lib/deploy.task.ts

@@ -0,0 +1,287 @@
+import {spawn} from '@fuzdev/fuz_util/process.js';
+import {print_error} from '@fuzdev/fuz_util/print.js';
+import {styleText as st} from 'node:util';
+import {z} from 'zod';
+import {cp, mkdir, readdir, rm} from 'node:fs/promises';
+import {join, resolve} from 'node:path';
+import {fs_exists, fs_empty_dir} from '@fuzdev/fuz_util/fs.js';
+import {
+	git_check_clean_workspace,
+	git_checkout,
+	git_local_branch_exists,
+	git_remote_branch_exists,
+	GitOrigin,
+	GitBranch,
+	git_delete_local_branch,
+	git_push_to_create,
+	git_reset_branch_to_first_commit,
+	git_pull,
+	git_fetch,
+	git_check_setting_pull_rebase,
+	git_clone_locally,
+	git_current_branch_name,
+} from '@fuzdev/fuz_util/git.js';
+
+import {TaskError, type Task} from './task.ts';
+import {print_path} from './paths.ts';
+import {GRO_DIRNAME, GIT_DIRNAME, SVELTEKIT_BUILD_DIRNAME} from './constants.ts';
+
+// 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
+
+// TODO customize
+const dir = process.cwd();
+const INITIAL_FILE_PATH = '.gitkeep';
+const DEPLOY_DIR = GRO_DIRNAME + '/deploy';
+const SOURCE_BRANCH = 'main';
+const TARGET_BRANCH = 'deploy';
+const DANGEROUS_BRANCHES = [SOURCE_BRANCH, 'master'];
+
+/** @nodocs */
+export const Args = z.strictObject({
+	source: GitBranch.describe('git source branch to build and deploy from').default(SOURCE_BRANCH),
+	target: GitBranch.describe('git target branch to deploy to').default(TARGET_BRANCH),
+	origin: GitOrigin.describe('git origin to deploy to').default('origin'),
+	deploy_dir: z.string().meta({description: 'the deploy output directory'}).default(DEPLOY_DIR),
+	build_dir: z
+		.string()
+		.meta({description: 'the SvelteKit build directory'})
+		.default(SVELTEKIT_BUILD_DIRNAME),
+	dry: z
+		.boolean()
+		.meta({
+			description: 'build and prepare to deploy without actually deploying',
+		})
+		.default(false),
+	force: z
+		.boolean()
+		.meta({description: 'caution!! destroys the target branch both locally and remotely'})
+		.default(false),
+	dangerous: z
+		.boolean()
+		.meta({description: 'caution!! enables destruction of branches like main and master'})
+		.default(false),
+	reset: z
+		.boolean()
+		.meta({
+			description: 'if true, resets the target branch back to the first commit before deploying',
+		})
+		.default(false),
+	build: z.boolean().meta({description: 'dual of no-build'}).default(true),
+	'no-build': z.boolean().meta({description: 'opt out of building'}).default(false),
+	sync: z.boolean().meta({description: 'dual of no-sync'}).default(true),
+	'no-sync': z.boolean().meta({description: 'opt out of gro sync in build'}).default(false),
+	gen: z.boolean().meta({description: 'dual of no-gen'}).default(true),
+	'no-gen': z.boolean().meta({description: 'opt out of gro gen in build'}).default(false),
+	install: z.boolean().meta({description: 'dual of no-install'}).default(true),
+	'no-install': z
+		.boolean()
+		.meta({description: 'opt out of installing packages before building'})
+		.default(false),
+	force_build: z
+		.boolean()
+		.meta({description: 'force a fresh build, ignoring the cache'})
+		.default(false),
+	pull: z.boolean().meta({description: 'dual of no-pull'}).default(true),
+	'no-pull': z.boolean().meta({description: 'opt out of git pull'}).default(false),
+});
+export type Args = z.infer<typeof Args>;
+
+/** @nodocs */
+export const task: Task<Args> = {
+	summary: 'deploy to a branch',
+	Args,
+	run: async ({args, log, invoke_task}): Promise<void> => {
+		const {
+			source,
+			target,
+			origin,
+			build_dir,
+			deploy_dir,
+			dry,
+			force,
+			dangerous,
+			reset,
+			build,
+			sync,
+			gen,
+			install,
+			force_build,
+			pull,
+		} = args;
+
+		// Checks
+		if (!force && target !== TARGET_BRANCH) {
+			throw new TaskError(
+				`Warning! You are deploying to a custom target branch '${target}',` +
+					` instead of the default '${TARGET_BRANCH}' branch.` +
+					` This is destructive to your '${target}' branch!` +
+					` If you understand and are OK with deleting your branch '${target}',` +
+					` both locally and remotely, pass --force to suppress this error.`,
+			);
+		}
+		if (!dangerous && DANGEROUS_BRANCHES.includes(target)) {
+			throw new TaskError(
+				`Warning! You are deploying to a custom target branch '${target}'` +
+					` and that appears very dangerous: it is destructive to your '${target}' branch!` +
+					` If you understand and are OK with deleting your branch '${target}',` +
+					` both locally and remotely, pass --dangerous to suppress this error.`,
+			);
+		}
+		const clean_error_message = await git_check_clean_workspace();
+		if (clean_error_message) {
+			throw new TaskError(
+				'Deploy failed because the git workspace has uncommitted changes: ' + clean_error_message,
+			);
+		}
+		if (!(await git_check_setting_pull_rebase())) {
+			throw new TaskError(
+				'Deploying currently requires `git config --global pull.rebase true`,' +
+					' but this restriction could be lifted with more work',
+			);
+		}
+
+		// Fetch the source branch in the cwd if it's not there
+		if (!(await git_local_branch_exists(source))) {
+			await git_fetch(origin, source);
+		}
+
+		// Prepare the source branch in the cwd
+		await git_checkout(source);
+		if (pull) {
+			await git_pull(origin, source);
+		}
+		if (await git_check_clean_workspace()) {
+			throw new TaskError(
+				'Deploy failed because the local source branch is out of sync with the remote one,' +
+					' finish rebasing manually or reset with `git rebase --abort`',
+			);
+		}
+
+		// Prepare the target branch remotely and locally
+		const resolved_deploy_dir = resolve(deploy_dir);
+		const target_spawn_options = {cwd: resolved_deploy_dir};
+		const remote_target_exists = await git_remote_branch_exists(origin, target);
+		if (remote_target_exists) {
+			// Remote target branch already exists, so sync up efficiently
+
+			// First, check if the deploy dir exists, and if so, attempt to sync it.
+			// If anything goes wrong, delete the directory and we'll initialize it
+			// using the same code path as if it didn't exist in the first place.
+			if (await fs_exists(resolved_deploy_dir)) {
+				if (target !== (await git_current_branch_name(target_spawn_options))) {
+					// We're in a bad state because the target branch has changed,
+					// so delete the directory and continue as if it wasn't there.
+					await rm(resolved_deploy_dir, {recursive: true});
+				} else {
+					await spawn('git', ['reset', '--hard'], target_spawn_options); // in case it's dirty
+					// 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});
+						}
+					}
+				}
+			}
+
+			// Second, initialize the deploy dir if needed.
+			// It may not exist, or it may have been deleted after failing to sync above.
+			if (!(await fs_exists(resolved_deploy_dir))) {
+				const local_deploy_branch_exists = await git_local_branch_exists(target);
+				await git_fetch(origin, ('+' + target + ':' + target) as GitBranch); // fetch+merge and allow non-fastforward updates with the +
+				await git_clone_locally(origin, target, dir, resolved_deploy_dir);
+				// Clean up if we created the target branch in the cwd
+				if (!local_deploy_branch_exists) {
+					await git_delete_local_branch(target);
+				}
+			}
+
+			// Local target branch is now synced with remote, but do we need to reset?
+			if (reset) {
+				await git_reset_branch_to_first_commit(origin, target, target_spawn_options);
+			}
+		} else {
+			// Remote target branch does not exist, so start from scratch
+
+			// Delete the deploy dir and recreate it
+			if (await fs_exists(resolved_deploy_dir)) {
+				await rm(resolved_deploy_dir, {recursive: true});
+				await mkdir(resolved_deploy_dir, {recursive: true});
+			}
+
+			// Delete the target branch locally in the cwd if it exists
+			if (await git_local_branch_exists(target)) {
+				await git_delete_local_branch(target);
+			}
+
+			// Create the target branch locally and remotely.
+			// This is more complex to avoid churning the cwd.
+			await git_clone_locally(origin, source, dir, resolved_deploy_dir);
+			await spawn('git', ['checkout', '--orphan', target], target_spawn_options);
+			// TODO there's definitely a better way to do this
+			await spawn('git', ['rm', '-rf', '.'], target_spawn_options);
+			await spawn('touch', [INITIAL_FILE_PATH], target_spawn_options);
+			await spawn('git', ['add', INITIAL_FILE_PATH], target_spawn_options);
+			await spawn('git', ['commit', '-m', 'init'], target_spawn_options);
+			await git_push_to_create(origin, target, target_spawn_options);
+			await git_delete_local_branch(source, target_spawn_options);
+		}
+
+		// Remove everything except .git from the deploy directory to avoid stale files
+		await fs_empty_dir(resolved_deploy_dir, (name) => name !== GIT_DIRNAME);
+
+		// Build
+		try {
+			if (build) {
+				await invoke_task('build', {sync, gen, install, force_build});
+			}
+		} catch (error) {
+			log.error(
+				st('red', 'build failed'),
+				'but',
+				st('green', 'no changes were made to git'),
+				print_error(error),
+			);
+			if (dry) {
+				log.info(st('red', 'dry deploy failed'));
+			}
+			throw new TaskError(`Deploy safely canceled due to build failure. See the error above.`);
+		}
+
+		// Verify build output exists
+		if (!(await fs_exists(build_dir))) {
+			throw new TaskError(`Directory to deploy does not exist after building: ${build_dir}`);
+		}
+
+		// Copy the build
+		const build_entries = await readdir(build_dir);
+		await Promise.all(
+			build_entries.map((path) =>
+				cp(join(build_dir, path), join(resolved_deploy_dir, path), {recursive: true}),
+			),
+		);
+
+		// At this point, `dist/` is ready to be committed and deployed!
+		if (dry) {
+			log.info(st('green', 'dry deploy complete:'), 'files at', print_path(resolved_deploy_dir));
+			return;
+		}
+
+		// Commit and push
+		try {
+			await spawn('git', ['add', '.', '-f'], target_spawn_options);
+			await spawn('git', ['commit', '-m', 'deployment'], target_spawn_options);
+			await spawn('git', ['push', origin, target, '-f'], target_spawn_options); // force push because we may be resetting the branch, see the checks above to make this safer
+		} catch (error) {
+			log.error(st('red', 'updating git failed:'), print_error(error));
+			throw new TaskError(`Deploy failed in a bad state: built but not pushed, see error above.`);
+		}
+
+		log.info(st('green', 'deployed')); // TODO log a different message if "Everything up-to-date"
+	},
+};

package/src/lib/dev.task.ts

@@ -0,0 +1,52 @@
+import {z} from 'zod';
+
+import type {Task} from './task.ts';
+import {Plugins, type PluginContext} from './plugin.ts';
+import {clean_fs} from './clean_fs.ts';
+
+/** @nodocs */
+export const Args = z.strictObject({
+	watch: z.boolean().meta({description: 'dual of no-watch'}).default(true),
+	'no-watch': z
+		.boolean()
+		.meta({
+			description: 'opt out of running a long-lived process to watch files and rebuild on changes',
+		})
+		.default(false),
+	sync: z.boolean().meta({description: 'dual of no-sync'}).default(true),
+	'no-sync': z.boolean().meta({description: 'opt out of gro sync'}).default(false),
+	install: z.boolean().meta({description: 'opt into installing packages'}).default(false),
+});
+export type Args = z.infer<typeof Args>;
+
+export type DevTaskContext = PluginContext<Args>;
+
+/** @nodocs */
+export const task: Task<Args> = {
+	summary: 'start SvelteKit and other dev plugins',
+	Args,
+	run: async (ctx) => {
+		const {args, invoke_task, log} = ctx;
+		const {watch, sync, install} = args;
+
+		await clean_fs({build_dev: true});
+
+		if (sync || install) {
+			if (!sync) log.warn('sync is false but install is true, so ignoring the sync option');
+			await invoke_task('sync', {install, gen: !watch});
+		}
+
+		const plugins = await Plugins.create({...ctx, dev: true, watch});
+		await plugins.setup();
+		if (!watch) {
+			await plugins.teardown();
+		} else {
+			// TODO maybe redesign for this API to be explicitly cancelable?
+			// Keep the task running indefinitely in watch mode.
+			// This prevents invoke_task from calling finish() and closing the filer.
+			await new Promise(() => {
+				// Never resolves - keeps filer and listeners alive.
+			});
+		}
+	},
+};

package/src/lib/disknode.ts

@@ -0,0 +1,26 @@
+import type {PathId} from '@fuzdev/fuz_util/path.js';
+
+// TODO extract more here from Filer
+
+export interface Disknode {
+	id: PathId;
+	// TODO figure out the best API that makes this lazy
+	/**
+	 * `null` contents means it doesn't exist.
+	 * We create the file in memory to track its dependents regardless of its existence on disk.
+	 */
+	contents: string | null;
+	/**
+	 * Is the source file outside of the `root_dir` or excluded by `watch_dir_options.filter`?
+	 */
+	external: boolean;
+	ctime: number | null;
+	mtime: number | null;
+	/**
+	 * SHA-256 hash of `contents`. `null` iff `contents` is `null`.
+	 * Used for content-based change detection and caching.
+	 */
+	content_hash: string | null;
+	dependents: Map<PathId, Disknode>;
+	dependencies: Map<PathId, Disknode>;
+}

package/src/lib/env.ts

@@ -0,0 +1,78 @@
+import dotenv from 'dotenv';
+import {resolve} from 'node:path';
+import {existsSync, readFileSync} from 'node:fs';
+
+export const load_env = (
+	dev: boolean,
+	visibility: 'public' | 'private',
+	public_prefix: string,
+	private_prefix: string,
+	env_dir?: string,
+	env_files = ['.env', '.env.' + (dev ? 'development' : 'production')],
+	ambient_env = process.env,
+): Record<string, string> => {
+	const envs: Array<Record<string, string | undefined>> = env_files
+		.map((path) => load(env_dir === undefined ? path : resolve(env_dir, path)))
+		.filter((v) => v !== undefined);
+	envs.push(ambient_env);
+	return merge_envs(envs, visibility, public_prefix, private_prefix);
+};
+
+/**
+ * Loads a single env value without merging it into `process.env`.
+ * By default searches process.env, then a local `.env` if one exists, then `../.env` if it exists.
+ * Empty strings are semantically the same as `undefined` for more ergonomic fallbacks.
+ */
+export const load_from_env = (key: string, paths = ['.env', '../.env']): string | undefined => {
+	let v = process.env[key];
+	if (v) return v;
+	for (const path of paths) {
+		const env = load(path);
+		v = env?.[key];
+		if (v) return v;
+	}
+	return undefined;
+};
+
+const load = (path: string): Record<string, string> | undefined => {
+	if (!existsSync(path)) return;
+	const loaded = readFileSync(path, 'utf8');
+	return dotenv.parse(loaded);
+};
+
+export const merge_envs = (
+	envs: Array<Record<string, string | undefined>>,
+	visibility: 'public' | 'private',
+	public_prefix: string,
+	private_prefix: string,
+): Record<string, string> => {
+	const env: Record<string, string> = {};
+
+	for (const e of envs) {
+		for (const key in e) {
+			if (
+				(visibility === 'private' && is_private_env(key, public_prefix, private_prefix)) ||
+				(visibility === 'public' && is_public_env(key, public_prefix, private_prefix))
+			) {
+				const value = e[key];
+				if (value !== undefined) env[key] = value;
+			}
+		}
+	}
+
+	return env;
+};
+
+export const is_private_env = (
+	key: string,
+	public_prefix: string,
+	private_prefix: string,
+): boolean =>
+	key.startsWith(private_prefix) && (public_prefix === '' || !key.startsWith(public_prefix));
+
+export const is_public_env = (
+	key: string,
+	public_prefix: string,
+	private_prefix: string,
+): boolean =>
+	key.startsWith(public_prefix) && (private_prefix === '' || !key.startsWith(private_prefix));

package/src/lib/esbuild_helpers.ts

@@ -0,0 +1,49 @@
+import {styleText as st} from 'node:util';
+import type {Logger} from '@fuzdev/fuz_util/log.js';
+import type * as esbuild from 'esbuild';
+
+import type {ParsedSvelteConfig} from './svelte_config.ts';
+
+export const print_build_result = (log: Logger, build_result: esbuild.BuildResult): void => {
+	for (const error of build_result.errors) {
+		log.error(st('red', 'esbuild error'), error);
+	}
+	for (const warning of build_result.warnings) {
+		log.warn(st('yellow', 'esbuild warning'), warning);
+	}
+};
+
+// This concatenates weirdly to avoid a SvelteKit warning,
+// because SvelteKit detects usage as a string and not the AST.
+const import_meta_env = 'import.' + 'meta.env.'; // eslint-disable-line no-useless-concat
+
+/**
+ * Creates an esbuild `define` shim for Vite's `import.meta\.env`.
+ * @see https://esbuild.github.io/api/#define
+ * @param dev
+ * @param base_url - best-effort shim from SvelteKit's `base` to Vite's `import.meta\.env.BASE_URL`
+ * @param ssr
+ * @param mode
+ * @returns
+ */
+export const to_define_import_meta_env = (
+	dev: boolean,
+	base_url: ParsedSvelteConfig['base_url'],
+	ssr = true,
+	mode = dev ? 'development' : 'production',
+): Record<string, string> => ({
+	// see `import_meta_env` for why this is defined weirdly instead of statically
+	[import_meta_env + 'DEV']: JSON.stringify(dev),
+	[import_meta_env + 'PROD']: JSON.stringify(!dev),
+	[import_meta_env + 'SSR']: JSON.stringify(ssr),
+	[import_meta_env + 'MODE']: JSON.stringify(mode),
+	// it appears SvelteKit's `''` translates to Vite's `'/'`, so this intentionally falls back for falsy values, not just undefined
+	[import_meta_env + 'BASE_URL']: JSON.stringify(base_url || '/'),
+});
+
+export const default_ts_transform_options: esbuild.TransformOptions = {
+	target: 'esnext', // TODO load local tsconfig
+	format: 'esm',
+	loader: 'ts',
+	charset: 'utf8',
+};

package/src/lib/esbuild_plugin_external_worker.ts

@@ -0,0 +1,94 @@
+import * as esbuild from 'esbuild';
+import type {Logger} from '@fuzdev/fuz_util/log.js';
+import {basename} from 'node:path';
+import type {CompileOptions, ModuleCompileOptions, PreprocessorGroup} from 'svelte/compiler';
+import type {PathId} from '@fuzdev/fuz_util/path.js';
+
+import {print_build_result, to_define_import_meta_env} from './esbuild_helpers.ts';
+import {resolve_specifier} from './resolve_specifier.ts';
+import {esbuild_plugin_sveltekit_shim_alias} from './esbuild_plugin_sveltekit_shim_alias.ts';
+import {esbuild_plugin_sveltekit_shim_env} from './esbuild_plugin_sveltekit_shim_env.ts';
+import {esbuild_plugin_sveltekit_shim_app} from './esbuild_plugin_sveltekit_shim_app.ts';
+import {esbuild_plugin_sveltekit_local_imports} from './esbuild_plugin_sveltekit_local_imports.ts';
+import {esbuild_plugin_svelte} from './esbuild_plugin_svelte.ts';
+import type {ParsedSvelteConfig} from './svelte_config.ts';
+
+export interface EsbuildPluginExternalWorkerOptions {
+	dev: boolean;
+	build_options: esbuild.BuildOptions;
+	dir?: string;
+	svelte_compile_options?: CompileOptions;
+	svelte_compile_module_options?: ModuleCompileOptions;
+	svelte_preprocessors?: PreprocessorGroup | Array<PreprocessorGroup>;
+	alias?: Record<string, string>;
+	base_url?: ParsedSvelteConfig['base_url'];
+	assets_url?: ParsedSvelteConfig['assets_url'];
+	public_prefix?: string;
+	private_prefix?: string;
+	env_dir?: string;
+	env_files?: Array<string>;
+	ambient_env?: Record<string, string>;
+	log?: Logger;
+}
+
+export const esbuild_plugin_external_worker = ({
+	dev,
+	build_options,
+	dir = process.cwd(),
+	svelte_compile_options,
+	svelte_compile_module_options,
+	svelte_preprocessors,
+	alias,
+	base_url,
+	assets_url,
+	public_prefix,
+	private_prefix,
+	env_dir,
+	env_files,
+	ambient_env,
+	log,
+}: EsbuildPluginExternalWorkerOptions): esbuild.Plugin => ({
+	name: 'external_worker',
+	setup: (build) => {
+		const builds: Map<string, Promise<esbuild.BuildResult>> = new Map();
+		const build_worker = async (path_id: PathId): Promise<esbuild.BuildResult> => {
+			if (builds.has(path_id)) return builds.get(path_id)!;
+			const building = esbuild.build({
+				entryPoints: [path_id],
+				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_svelte({
+						dev,
+						base_url,
+						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,
+			});
+			builds.set(path_id, building);
+			return building;
+		};
+
+		build.onResolve({filter: /\.worker(|\.js|\.ts)$/}, async ({path, resolveDir}) => {
+			const parsed = await resolve_specifier(path, resolveDir);
+			const {specifier, path_id, namespace} = parsed;
+			const build_result = await build_worker(path_id);
+			if (log) print_build_result(log, build_result);
+			return {path: './' + basename(specifier), external: true, namespace};
+		});
+	},
+});