@fuzdev/gro 0.192.0

package/src/lib/plugin.ts

@@ -0,0 +1,106 @@
+import type {TaskContext} from './task.ts';
+
+/**
+ * Gro `Plugin`s enable custom behavior during `gro dev` and `gro build`.
+ * In contrast, `Adapter`s use the results of `gro build` to produce final artifacts.
+ */
+export interface Plugin<TPluginContext extends PluginContext = PluginContext> {
+	name: string;
+	setup?: (ctx: TPluginContext) => void | Promise<void>;
+	adapt?: (ctx: TPluginContext) => void | Promise<void>;
+	teardown?: (ctx: TPluginContext) => void | Promise<void>;
+}
+
+export type PluginsCreateConfig<TPluginContext extends PluginContext = PluginContext> = (
+	ctx: TPluginContext,
+) => Array<Plugin<TPluginContext>> | Promise<Array<Plugin<TPluginContext>>>;
+
+export interface PluginContext<TArgs = object> extends TaskContext<TArgs> {
+	dev: boolean;
+	watch: boolean;
+}
+
+/** See `Plugins.create` for a usage example. */
+export class Plugins<TPluginContext extends PluginContext> {
+	readonly ctx: TPluginContext;
+	readonly instances: Array<Plugin<TPluginContext>>;
+
+	constructor(ctx: TPluginContext, instances: Array<Plugin>) {
+		this.ctx = ctx;
+		this.instances = instances;
+	}
+
+	static async create<TPluginContext extends PluginContext>(
+		ctx: TPluginContext,
+	): Promise<Plugins<TPluginContext>> {
+		const {timings} = ctx;
+		const timing_to_create = timings.start('plugins.create');
+		const instances: Array<Plugin> = await ctx.config.plugins(ctx);
+		const plugins = new Plugins(ctx, instances);
+		timing_to_create();
+		return plugins;
+	}
+
+	async setup(): Promise<void> {
+		const {ctx, instances} = this;
+		if (!instances.length) return;
+		const {timings, log} = ctx;
+		const timing_to_setup = timings.start('plugins.setup');
+		for (const plugin of instances) {
+			if (!plugin.setup) continue;
+			log.debug('setup plugin', plugin.name);
+			const timing = timings.start(`setup:${plugin.name}`);
+			await plugin.setup(ctx); // eslint-disable-line no-await-in-loop
+			timing();
+		}
+		timing_to_setup();
+	}
+
+	async adapt(): Promise<void> {
+		const {ctx, instances} = this;
+		const {timings} = ctx;
+		const timing_to_run_adapters = timings.start('plugins.adapt');
+		for (const plugin of instances) {
+			if (!plugin.adapt) continue;
+			const timing = timings.start(`adapt:${plugin.name}`);
+			await plugin.adapt(ctx); // eslint-disable-line no-await-in-loop
+			timing();
+		}
+		timing_to_run_adapters();
+	}
+
+	async teardown(): Promise<void> {
+		const {ctx, instances} = this;
+		if (!instances.length) return;
+		const {timings, log} = ctx;
+		const timing_to_teardown = timings.start('plugins.teardown');
+		for (const plugin of instances) {
+			if (!plugin.teardown) continue;
+			log.debug('teardown plugin', plugin.name);
+			const timing = timings.start(`teardown:${plugin.name}`);
+			await plugin.teardown(ctx); // eslint-disable-line no-await-in-loop
+			timing();
+		}
+		timing_to_teardown();
+	}
+}
+
+/**
+ * Replaces a plugin by name in `plugins` without mutating the param.
+ * Throws if the plugin name cannot be found.
+ * @param plugins - accepts the same types as the return value of `PluginsCreateConfig`
+ * @param new_plugin
+ * @param name - @default new_plugin.name
+ * @returns `plugins` with `new_plugin` at the index of the plugin with `name`
+ */
+export const plugin_replace = (
+	plugins: Array<Plugin>,
+	new_plugin: Plugin,
+	name = new_plugin.name,
+): Array<Plugin> => {
+	const index = plugins.findIndex((p) => p.name === name);
+	if (index === -1) throw Error('Failed to find plugin to replace: ' + name);
+	const replaced = plugins.slice();
+	replaced[index] = new_plugin;
+	return replaced;
+};

package/src/lib/publish.task.ts

@@ -0,0 +1,228 @@
+import {spawn} from '@fuzdev/fuz_util/process.js';
+import {z} from 'zod';
+import {styleText as st} from 'node:util';
+import {fs_exists} from '@fuzdev/fuz_util/fs.js';
+import {
+	GitBranch,
+	GitOrigin,
+	git_check_clean_workspace,
+	git_checkout,
+	git_fetch,
+	git_pull,
+} from '@fuzdev/fuz_util/git.js';
+
+import {TaskError, type Task} from './task.ts';
+import {package_json_load, package_json_parse_repo_url} from './package_json.ts';
+import {find_cli, spawn_cli} from './cli.ts';
+import {has_sveltekit_library} from './sveltekit_helpers.ts';
+import {update_changelog} from './changelog.ts';
+import {load_from_env} from './env.ts';
+import {CHANGESET_CLI} from './changeset_helpers.ts';
+
+/** @nodocs */
+export const Args = z.strictObject({
+	branch: GitBranch.describe('branch to publish from').default('main'),
+	origin: GitOrigin.describe('git origin to publish from').default('origin'),
+	changelog: z
+		.string()
+		.meta({description: 'file name and path of the changelog'})
+		.default('CHANGELOG.md'),
+	preserve_changelog: z
+		.boolean()
+		.meta({
+			description:
+				'opt out of linkifying and formatting the changelog from @changesets/changelog-git',
+		})
+		.default(false),
+	optional: z
+		.boolean()
+		.meta({description: 'exit gracefully if there are no changesets'})
+		.default(false),
+	dry: z
+		.boolean()
+		.meta({description: 'build and prepare to publish without actually publishing'})
+		.default(false),
+	check: z.boolean().meta({description: 'dual of no-check'}).default(true),
+	'no-check': z
+		.boolean()
+		.meta({description: 'opt out of checking before publishing'})
+		.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),
+	pull: z.boolean().meta({description: 'dual of no-pull'}).default(true),
+	'no-pull': z.boolean().meta({description: 'opt out of git pull'}).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: 'dual of no-install'}).default(true),
+	'no-install': z
+		.boolean()
+		.meta({description: 'opt out of installing packages before publishing'})
+		.default(false),
+	changeset_cli: z.string().meta({description: 'the changeset CLI to use'}).default(CHANGESET_CLI),
+});
+export type Args = z.infer<typeof Args>;
+
+/** @nodocs */
+export const task: Task<Args> = {
+	summary: 'bump version, publish to the configured registry, and git push',
+	Args,
+	run: async ({args, log, invoke_task, config}): Promise<void> => {
+		const {
+			branch,
+			origin,
+			changelog,
+			preserve_changelog,
+			dry,
+			check,
+			build,
+			pull,
+			sync,
+			install,
+			optional,
+			changeset_cli,
+		} = args;
+		if (dry) {
+			log.info(st('green', 'dry run!'));
+		}
+
+		const package_json = await package_json_load();
+
+		const has_sveltekit_library_result = await has_sveltekit_library(package_json);
+		if (!has_sveltekit_library_result.ok) {
+			throw new TaskError(
+				'Failed to find SvelteKit library: ' + has_sveltekit_library_result.message,
+			);
+		}
+
+		const changelog_exists = await fs_exists(changelog);
+
+		const found_changeset_cli = await find_cli(changeset_cli);
+		if (!found_changeset_cli) {
+			throw new TaskError(
+				'changeset command not found, install @changesets/cli locally or globally',
+			);
+		}
+
+		// Make sure we're on the right branch:
+		await git_fetch(origin, branch);
+		await git_checkout(branch);
+		if (pull) {
+			if (await git_check_clean_workspace()) {
+				throw new TaskError('The git workspace is not clean, pass --no-pull to bypass git pull');
+			}
+			await git_pull(origin, branch);
+		}
+
+		// Install packages to ensure deps are current.
+		// Handles cases like branch switches where package.json changed.
+		// Skip gen because it will run after version bump.
+		if (sync || install) {
+			if (!sync) log.warn('sync is false but install is true, so running sync for install only');
+			await invoke_task('sync', {install, gen: false});
+		}
+
+		// Check before proceeding, defaults to true.
+		if (check) {
+			await invoke_task('check', {workspace: true, sync: false});
+		}
+
+		let version!: string;
+		let optional_and_version_unchanged = false;
+
+		// Bump the version so the package.json is updated before building:
+		// TODO problem here is build may fail and put us in a bad state,
+		// but I don't see how we could do this to robustly
+		// have the new version in the build without building twice -
+		// maybe the code should catch the error and revert the version and delete the tag?
+		if (dry) {
+			log.info('dry run, skipping changeset version');
+		} else {
+			if (typeof package_json.version !== 'string') {
+				throw new TaskError('Failed to find package.json version');
+			}
+			const parsed_repo_url = package_json_parse_repo_url(package_json);
+			if (!parsed_repo_url) {
+				throw new TaskError(
+					'package.json `repository` must contain a repo url (and GitHub only for now, sorry),' +
+						' like `git+https://github.com/fuzdev/gro.git` or `https://github.com/fuzdev/gro`' +
+						' or an object with the `url` key',
+				);
+			}
+
+			// This is the first line that alters the repo.
+
+			const changeset_version_result = await spawn_cli(found_changeset_cli, ['version'], log);
+			if (!changeset_version_result?.ok) {
+				throw Error('changeset version failed: no commits were made: see the error above');
+			}
+
+			if (!preserve_changelog) {
+				const token = load_from_env('SECRET_GITHUB_API_TOKEN');
+				if (!token) {
+					log.warn(
+						'the env var SECRET_GITHUB_API_TOKEN was not found, so API calls with be unauthorized',
+					);
+				}
+				await update_changelog(parsed_repo_url.owner, parsed_repo_url.repo, changelog, token, log);
+			}
+
+			// Update package-lock.json to reflect the new version.
+			if (install) {
+				const install_result = await spawn(config.pm_cli, ['install']);
+				if (!install_result.ok) {
+					throw new TaskError(`Failed \`${config.pm_cli} install\` after version bump`);
+				}
+			}
+
+			// Regenerate files that depend on package.json version.
+			// The check above ensures gen is updated.
+			await invoke_task('gen');
+
+			const package_json_after_versioning = await package_json_load();
+			version = package_json_after_versioning.version!;
+			if (package_json.version === version) {
+				// The version didn't change.
+				// For now this is the best detection we have for a no-op `changeset version`.
+				if (optional) {
+					optional_and_version_unchanged = true;
+				} else {
+					// Doesn't build if the version didn't change and publishing isn't optional.
+					throw new TaskError(`\`${changeset_cli} version\` failed: are there any changes?`);
+				}
+			}
+		}
+
+		// Build after the version is bumped so the new version is in the build as needed.
+		// Skip sync and install because we already handled both above.
+		if (build) {
+			await invoke_task('build', {sync: false, install: false});
+		}
+
+		// Return early if there are no changes and publishing is optional, but after building,
+		// so if callers want to optimize away building
+		// they need to do so manually like in `gro release`.
+		// TODO this could be cleaned up if tasks had a return value to callers, it could specifiy that it didn't build
+		if (optional_and_version_unchanged) return;
+
+		if (dry) {
+			log.info('publishing branch ' + branch);
+			log.info(st('green', 'dry run complete!'));
+			return;
+		}
+
+		const changeset_publish_result = await spawn_cli(found_changeset_cli, ['publish'], log);
+		if (!changeset_publish_result?.ok) {
+			throw new TaskError(
+				`\`${changeset_cli} publish\` failed - continue manually or try again after running \`git reset --hard\``,
+			);
+		}
+
+		if (!changelog_exists && (await fs_exists(changelog))) {
+			await spawn('git', ['add', changelog]);
+		}
+		await spawn('git', ['commit', '-a', '-m', `publish v${version}`]);
+		await spawn('git', ['push', '--follow-tags']);
+
+		log.info(st('green', `published to branch ${st('cyan', branch)}!`));
+	},
+};

package/src/lib/register.ts

@@ -0,0 +1,3 @@
+import {register} from 'node:module';
+
+register('./loader.js', import.meta.url);

package/src/lib/reinstall.task.ts

@@ -0,0 +1,45 @@
+import {z} from 'zod';
+import {spawn} from '@fuzdev/fuz_util/process.js';
+import {rm} from 'node:fs/promises';
+
+import {TaskError, type Task} from './task.ts';
+import {LOCKFILE_FILENAME, NODE_MODULES_DIRNAME} from './constants.ts';
+
+/** @nodocs */
+export const Args = z.strictObject({});
+export type Args = z.infer<typeof Args>;
+
+/** @nodocs */
+export const task: Task<Args> = {
+	summary: `refreshes ${LOCKFILE_FILENAME} with the latest and cleanest deps`,
+	Args,
+	run: async ({log, config}): Promise<void> => {
+		log.info(`running the initial \`${config.pm_cli} install\``);
+		const initial_install_result = await spawn(config.pm_cli, ['install']);
+		if (!initial_install_result.ok) {
+			throw new TaskError(`Failed initial \`${config.pm_cli} install\``);
+		}
+
+		// Deleting both the lockfile and node_modules upgrades to the latest minor/patch versions.
+		await Promise.all([rm(LOCKFILE_FILENAME), rm(NODE_MODULES_DIRNAME, {recursive: true})]);
+		log.info(
+			`running \`${config.pm_cli} install\` after deleting ${LOCKFILE_FILENAME} and ${NODE_MODULES_DIRNAME}, this can take a while...`,
+		);
+		const second_install_result = await spawn(config.pm_cli, ['install']);
+		if (!second_install_result.ok) {
+			throw new TaskError(
+				`Failed \`${config.pm_cli} install\` after deleting ${LOCKFILE_FILENAME} and ${NODE_MODULES_DIRNAME}`,
+			);
+		}
+
+		// TODO @many this relies on npm behavior that changed in v11
+		// Deleting the lockfile and reinstalling cleans the lockfile of unnecessary dep noise,
+		// like esbuild's many packages for each platform.
+		await rm(LOCKFILE_FILENAME);
+		log.info(`running \`${config.pm_cli} install\` one last time to clean ${LOCKFILE_FILENAME}`);
+		const final_install_result = await spawn(config.pm_cli, ['install']);
+		if (!final_install_result.ok) {
+			throw new TaskError(`Failed \`${config.pm_cli} install\``);
+		}
+	},
+};

package/src/lib/release.task.ts

@@ -0,0 +1,26 @@
+import {z} from 'zod';
+
+import type {Task} from './task.ts';
+import {has_sveltekit_library, has_sveltekit_app} from './sveltekit_helpers.ts';
+import {package_json_load} from './package_json.ts';
+
+/** @nodocs */
+export const Args = z.strictObject({});
+export type Args = z.infer<typeof Args>;
+
+/** @nodocs */
+export const task: Task<Args> = {
+	summary: 'publish and deploy',
+	Args,
+	run: async ({invoke_task}) => {
+		const package_json = await package_json_load();
+
+		const publish = (await has_sveltekit_library(package_json)).ok;
+		if (publish) {
+			await invoke_task('publish', {optional: true});
+		}
+		if ((await has_sveltekit_app()).ok) {
+			await invoke_task('deploy', {build: !publish});
+		}
+	},
+};

package/src/lib/resolve.task.ts

@@ -0,0 +1,43 @@
+import {z} from 'zod';
+import {styleText as st} from 'node:util';
+
+import {TASK_FILE_SUFFIXES, type Task} from './task.ts';
+import {resolve_input_paths, to_input_paths} from './input_path.ts';
+
+/** @nodocs */
+export const Args = z.strictObject({
+	_: z.array(z.string()).meta({description: 'the input paths to resolve'}).default(['']),
+	verbose: z.boolean().meta({description: 'log diagnostics'}).default(false),
+});
+export type Args = z.infer<typeof Args>;
+
+/** @nodocs */
+export const task: Task<Args> = {
+	summary: 'diagnostic that logs resolved filesystem info for the given input paths',
+	Args,
+	run: async ({args, config, log}): Promise<void> => {
+		const {_, verbose} = args;
+
+		if (verbose) log.info('raw input paths:', _);
+
+		const input_paths = to_input_paths(_);
+		if (verbose) log.info('input paths:', input_paths);
+
+		const {task_root_dirs} = config;
+		if (verbose) log.info('task root paths:', task_root_dirs);
+
+		const {resolved_input_paths, possible_paths_by_input_path, unmapped_input_paths} =
+			await resolve_input_paths(input_paths, task_root_dirs, TASK_FILE_SUFFIXES);
+		if (verbose) log.info('resolved_input_paths:', resolved_input_paths);
+		if (verbose) log.info('possible_paths_by_input_path:', possible_paths_by_input_path);
+		if (verbose) log.info('unmapped_input_paths:', unmapped_input_paths);
+
+		for (const p of resolved_input_paths) {
+			log.info('resolved:', st('green', p.id));
+		}
+
+		if (!resolved_input_paths.length) {
+			log.warn(st('yellow', 'no input paths were resolved'));
+		}
+	},
+};

package/src/lib/resolve_specifier.ts

@@ -0,0 +1,81 @@
+import {extname, isAbsolute, join, relative} from 'node:path';
+import {fs_exists} from '@fuzdev/fuz_util/fs.js';
+import type {PathId} from '@fuzdev/fuz_util/path.js';
+
+import {replace_extension} from './paths.ts';
+
+// TODO ideally this module doesnt exist, but import.meta.resolve doesn't work in loaders last I tried
+
+export interface ResolvedSpecifier {
+	/**
+	 * The resolved filesystem path for the specifier.
+	 */
+	path_id: PathId;
+	/**
+	 * Same as `path_id` but includes `?raw` and other querystrings. (currently none)
+	 */
+	path_id_with_querystring: string;
+	specifier: string;
+	mapped_specifier: string;
+	namespace: undefined | 'sveltekit_local_imports_ts' | 'sveltekit_local_imports_js';
+	raw: boolean;
+}
+
+/**
+ * Maps an import `specifier` relative to `dir`,
+ * and infer the correct extension following Vite conventions.
+ * If no `.js` file is found for the specifier on the filesystem, it assumes `.ts`.
+ */
+export const resolve_specifier = async (
+	specifier: string,
+	dir: string,
+): Promise<ResolvedSpecifier> => {
+	const raw = specifier.endsWith('?raw'); // TODO more robust detection? other values?
+	const final_specifier = raw ? specifier.substring(0, specifier.length - 4) : specifier;
+	const absolute_path = isAbsolute(final_specifier) ? final_specifier : join(dir, final_specifier);
+
+	let mapped_path;
+	let path_id;
+	let namespace: ResolvedSpecifier['namespace'];
+
+	const ext = extname(absolute_path);
+	const is_js = ext === '.js';
+	const is_ts = ext === '.ts';
+
+	if (!is_js && !is_ts && (await fs_exists(absolute_path))) {
+		// unrecognized extension and the file exists
+		mapped_path = absolute_path;
+		path_id = absolute_path;
+	} else if (is_ts) {
+		// explicitly ts
+		mapped_path = replace_extension(absolute_path, '.js');
+		path_id = absolute_path;
+		namespace = 'sveltekit_local_imports_ts';
+	} else {
+		// extensionless, or js that points to ts, or just js
+		const js_id = is_js ? absolute_path : absolute_path + '.js';
+		const ts_id = is_js ? replace_extension(absolute_path, '.ts') : absolute_path + '.ts';
+		const [ts_exists, js_exists] = await Promise.all([fs_exists(ts_id), fs_exists(js_id)]);
+		if (!ts_exists && js_exists) {
+			mapped_path = js_id;
+			path_id = js_id;
+			namespace = 'sveltekit_local_imports_js';
+		} else {
+			mapped_path = js_id;
+			path_id = ts_id;
+			namespace = 'sveltekit_local_imports_ts';
+		}
+	}
+
+	let mapped_specifier = relative(dir, mapped_path);
+	if (mapped_specifier[0] !== '.') mapped_specifier = './' + mapped_specifier;
+
+	return {
+		path_id,
+		path_id_with_querystring: raw ? path_id + '?raw' : path_id,
+		raw,
+		specifier,
+		mapped_specifier,
+		namespace,
+	};
+};

package/src/lib/run.task.ts

@@ -0,0 +1,65 @@
+import {args_serialize} from '@fuzdev/fuz_util/args.js';
+import {fs_exists} from '@fuzdev/fuz_util/fs.js';
+import {spawn_result_to_message} from '@fuzdev/fuz_util/process.js';
+import {styleText as st} from 'node:util';
+import {z} from 'zod';
+
+import {to_implicit_forwarded_args} from './args.ts';
+import {resolve_gro_module_path, spawn_with_loader} from './gro_helpers.ts';
+import {TaskError, type Task} from './task.ts';
+
+/**
+ * Runs a TypeScript file with Gro's loader, forwarding all args to the script.
+ * Useful for scripts that need SvelteKit shims ($lib, $env, etc).
+ *
+ * @module
+ */
+
+/** @nodocs */
+export const Args = z
+	.object({
+		_: z.array(z.string()).meta({description: 'the file path to run'}).default([]),
+	})
+	.catchall(
+		z.union([
+			z.string(),
+			z.number(),
+			z.boolean(),
+			z.array(z.union([z.string(), z.number(), z.boolean()])),
+		]),
+	);
+export type Args = z.infer<typeof Args>;
+
+/** @nodocs */
+export const task: Task<Args> = {
+	summary: 'execute a file with the loader, like `node` but works for TypeScript',
+	Args,
+	run: async ({args, log}) => {
+		const {_, ...forwarded_args} = args;
+		const [path, ...positional_argv] = _;
+
+		if (!path) {
+			log.info(st('green', '\n\nUsage: ') + st('cyan', 'gro run path/to/file.ts [...args]\n'));
+			return;
+		}
+
+		if (!(await fs_exists(path))) {
+			throw new TaskError('Cannot find file to run at path: ' + path);
+		}
+
+		// Get args after `--` without requiring a command name.
+		// This allows `gro run script.ts -- --help` to pass --help to the script.
+		const implicit_args = to_implicit_forwarded_args();
+
+		// Reconstruct argv: positional args + explicit named args + implicit args after --
+		const named_argv = args_serialize({...forwarded_args, ...implicit_args});
+		const full_argv = [...positional_argv, ...named_argv];
+
+		const loader_path = resolve_gro_module_path('loader.js');
+
+		const spawned = await spawn_with_loader(loader_path, path, full_argv);
+		if (!spawned.ok) {
+			throw new TaskError(`\`gro run ${path}\` failed: ${spawn_result_to_message(spawned)}`);
+		}
+	},
+};