@ryanatkn/gro 0.129.4 → 0.129.6

package/src/lib/config.ts

@@ -0,0 +1,161 @@
+import {join, resolve} from 'node:path';
+import {existsSync} from 'node:fs';
+
+import {GRO_DIST_DIR, IS_THIS_GRO, paths} from './paths.js';
+import {
+	GRO_CONFIG_PATH,
+	NODE_MODULES_DIRNAME,
+	SERVER_DIST_PATH,
+	SVELTEKIT_BUILD_DIRNAME,
+	SVELTEKIT_DIST_DIRNAME,
+} from './path_constants.js';
+import create_default_config from './gro.config.default.js';
+import type {Create_Config_Plugins} from './plugin.js';
+import type {Map_Package_Json} from './package_json.js';
+import type {Path_Filter, Path_Id} from './path.js';
+
+/**
+ * The config that users can extend via `gro.config.ts`.
+ * This is exposed to users in places like tasks and genfiles.
+ * @see https://github.com/ryanatkn/gro/blob/main/src/lib/docs/config.md
+ */
+export interface Gro_Config {
+	/**
+	 * @see https://github.com/ryanatkn/gro/blob/main/src/lib/docs/plugin.md
+	 */
+	plugins: Create_Config_Plugins;
+	/**
+	 * Maps the project's `package.json` before writing it to the filesystem.
+	 * The `package_json` argument may be mutated, but the return value is what's used by the caller.
+	 * Returning `null` is a no-op for the caller.
+	 */
+	map_package_json: Map_Package_Json | null;
+	/**
+	 * The root directories to search for tasks given implicit relative input paths.
+	 * Defaults to `./src/lib`, then the cwd, then the Gro package dist.
+	 */
+	task_root_dirs: Path_Id[];
+	/**
+	 * When searching the filsystem for tasks and genfiles,
+	 * directories and files are included if they pass all of these filters.
+	 */
+	search_filters: Path_Filter[];
+}
+
+/**
+ * The relaxed variant of `Gro_Config` that users can provide via `gro.config.ts`.
+ * Superset of `Gro_Config`.
+ * @see https://github.com/ryanatkn/gro/blob/main/src/lib/docs/config.md
+ */
+export interface Raw_Gro_Config {
+	plugins?: Create_Config_Plugins;
+	map_package_json?: Map_Package_Json | null;
+	task_root_dirs?: string[];
+	search_filters?: Path_Filter | Path_Filter[] | null;
+}
+
+export type Create_Gro_Config = (
+	base_config: Gro_Config,
+) => Raw_Gro_Config | Promise<Raw_Gro_Config>;
+
+export const create_empty_config = (): Gro_Config => ({
+	plugins: () => [],
+	map_package_json: default_map_package_json,
+	task_root_dirs: [
+		// TODO maybe disable if no SvelteKit `lib` directory? or other detection to improve defaults
+		paths.lib,
+		IS_THIS_GRO ? null : paths.root,
+		IS_THIS_GRO ? null : GRO_DIST_DIR,
+	].filter((v) => v !== null),
+	search_filters: [(id) => !DEFAULT_SEARCH_EXCLUDER.test(id)],
+});
+
+/**
+ * The regexp used by default to exclude directories and files
+ * when searching the filesystem for tasks and genfiles.
+ * Customize via `search_filters` in the `Gro_Config`.
+ * See the test cases for the exact behavior.
+ */
+export const DEFAULT_SEARCH_EXCLUDER = new RegExp(
+	`(${
+		'(^|/)\\.[^/]+' + // exclude all `.`-prefixed directories
+		// TODO probably change to `pkg.name` instead of this catch-all (also `gro` below)
+		`|(^|/)${NODE_MODULES_DIRNAME}(?!/(@[^/]+/)?gro/${SVELTEKIT_DIST_DIRNAME})` + // exclude `node_modules` unless it's to the Gro directory
+		`|(^|/)${SVELTEKIT_BUILD_DIRNAME}` + // exclude the SvelteKit build directory
+		`|(^|/)(?<!(^|/)gro/)${SVELTEKIT_DIST_DIRNAME}` + // exclude the SvelteKit dist directory unless it's in the Gro directory
+		`|(^|/)${SERVER_DIST_PATH}` // exclude the Gro server plugin dist directory
+	})($|/)`,
+	'u',
+);
+
+const default_map_package_json: Map_Package_Json = (package_json) => {
+	if (package_json.exports) {
+		package_json.exports = Object.fromEntries(
+			Object.entries(package_json.exports).filter(([k]) => !DEFAULT_EXPORTS_EXCLUDER.test(k)),
+		);
+	}
+	return package_json;
+};
+
+export const DEFAULT_EXPORTS_EXCLUDER = /(\.md|\.(test|ignore)\.|\/(test|fixtures|ignore)\/)/u;
+
+/**
+ * Transforms a `Raw_Gro_Config` to the more strict `Gro_Config`.
+ * This allows users to provide a more relaxed config.
+ */
+export const normalize_config = (raw_config: Raw_Gro_Config): Gro_Config => {
+	const empty_config = create_empty_config();
+	// All of the raw config properties are optional,
+	// so fall back to the empty values when `undefined`.
+	const {
+		plugins = empty_config.plugins,
+		map_package_json = empty_config.map_package_json,
+		task_root_dirs = empty_config.task_root_dirs,
+		search_filters = empty_config.search_filters,
+	} = raw_config;
+	return {
+		plugins,
+		map_package_json,
+		task_root_dirs: task_root_dirs.map((p) => resolve(p)),
+		search_filters: Array.isArray(search_filters)
+			? search_filters
+			: search_filters
+				? [search_filters]
+				: [],
+	};
+};
+
+export interface Gro_Config_Module {
+	readonly default: Raw_Gro_Config | Create_Gro_Config;
+}
+
+export const load_config = async (dir = paths.root): Promise<Gro_Config> => {
+	const default_config = normalize_config(await create_default_config(create_empty_config()));
+	const config_path = join(dir, GRO_CONFIG_PATH);
+	if (!existsSync(config_path)) {
+		// No user config file found, so return the default.
+		return default_config;
+	}
+	// Import the user's `gro.config.ts`.
+	const config_module = await import(config_path);
+	validate_config_module(config_module, config_path);
+	return normalize_config(
+		typeof config_module.default === 'function'
+			? await config_module.default(default_config)
+			: config_module.default,
+	);
+};
+
+export const validate_config_module: (
+	config_module: any,
+	config_path: string,
+) => asserts config_module is Gro_Config_Module = (config_module, config_path) => {
+	const config = config_module.default;
+	if (!config) {
+		throw Error(`Invalid Gro config module at ${config_path}: expected a default export`);
+	} else if (!(typeof config === 'function' || typeof config === 'object')) {
+		throw Error(
+			`Invalid Gro config module at ${config_path}: the default export must be a function or object`,
+		);
+	}
+};

package/src/lib/deploy.task.ts

@@ -0,0 +1,243 @@
+import {spawn} from '@ryanatkn/belt/process.js';
+import {print_error} from '@ryanatkn/belt/print.js';
+import {green, red} from '@ryanatkn/belt/styletext.js';
+import {z} from 'zod';
+import {cp, mkdir, rm} from 'node:fs/promises';
+import {join, resolve} from 'node:path';
+import {existsSync, readdirSync} from 'node:fs';
+
+import {Task_Error, type Task} from './task.js';
+import {print_path} from './paths.js';
+import {GRO_DIRNAME, GIT_DIRNAME, SVELTEKIT_BUILD_DIRNAME} from './path_constants.js';
+import {empty_dir} from './fs.js';
+import {
+	git_check_clean_workspace,
+	git_checkout,
+	git_local_branch_exists,
+	git_remote_branch_exists,
+	Git_Origin,
+	Git_Branch,
+	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 './git.js';
+
+// 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'];
+
+export const Args = z
+	.object({
+		source: Git_Branch.describe('git source branch to build and deploy from').default(
+			SOURCE_BRANCH,
+		),
+		target: Git_Branch.describe('git target branch to deploy to').default(TARGET_BRANCH),
+		origin: Git_Origin.describe('git origin to deploy to').default('origin'),
+		deploy_dir: z.string({description: 'the deploy output directory'}).default(DEPLOY_DIR),
+		build_dir: z
+			.string({description: 'the SvelteKit build directory'})
+			.default(SVELTEKIT_BUILD_DIRNAME),
+		dry: z
+			.boolean({
+				description: 'build and prepare to deploy without actually deploying',
+			})
+			.default(false),
+		force: z
+			.boolean({description: 'caution!! destroys the target branch both locally and remotely'})
+			.default(false),
+		dangerous: z
+			.boolean({description: 'caution!! enables destruction of branches like main and master'})
+			.default(false),
+		reset: z
+			.boolean({
+				description: 'if true, resets the target branch back to the first commit before deploying',
+			})
+			.default(false),
+		build: z.boolean({description: 'dual of no-build'}).default(true),
+		'no-build': z.boolean({description: 'opt out of building'}).default(false),
+	})
+	.strict();
+export type Args = z.infer<typeof Args>;
+
+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} =
+			args;
+
+		// Checks
+		if (!force && target !== TARGET_BRANCH) {
+			throw new Task_Error(
+				`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 Task_Error(
+				`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 Task_Error(
+				'Deploy failed because the git workspace has uncommitted changes: ' + clean_error_message,
+			);
+		}
+		if (!(await git_check_setting_pull_rebase())) {
+			throw new Task_Error(
+				'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);
+		await git_pull(origin, source);
+		if (await git_check_clean_workspace()) {
+			throw new Task_Error(
+				'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 (existsSync(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
+					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 (!existsSync(resolved_deploy_dir)) {
+				const local_deploy_branch_exists = await git_local_branch_exists(target);
+				await git_fetch(origin, ('+' + target + ':' + target) as Git_Branch); // 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 (existsSync(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 empty_dir(resolved_deploy_dir, (path) => path !== GIT_DIRNAME);
+
+		// Build
+		try {
+			if (build) {
+				await invoke_task('build');
+			}
+			if (!existsSync(build_dir)) {
+				log.error(red('directory to deploy does not exist after building:'), build_dir);
+				return;
+			}
+		} catch (err) {
+			log.error(red('build failed'), 'but', green('no changes were made to git'), print_error(err));
+			if (dry) {
+				log.info(red('dry deploy failed'));
+			}
+			throw new Task_Error(`Deploy safely canceled due to build failure. See the error above.`);
+		}
+
+		// Copy the build
+		await Promise.all(
+			readdirSync(build_dir).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(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 (err) {
+			log.error(red('updating git failed:'), print_error(err));
+			throw new Task_Error(`Deploy failed in a bad state: built but not pushed, see error above.`);
+		}
+
+		log.info(green('deployed')); // TODO log a different message if "Everything up-to-date"
+	},
+};

package/src/lib/dev.task.ts

@@ -0,0 +1,43 @@
+import {z} from 'zod';
+
+import type {Task} from './task.js';
+import {Plugins, type Plugin_Context} from './plugin.js';
+import {clean_fs} from './clean_fs.js';
+
+export const Args = z
+	.object({
+		watch: z.boolean({description: 'dual of no-watch'}).default(true),
+		'no-watch': z
+			.boolean({
+				description:
+					'opt out of running a long-lived process to watch files and rebuild on changes',
+			})
+			.default(false),
+		sync: z.boolean({description: 'dual of no-sync'}).default(true),
+		'no-sync': z.boolean({description: 'opt out of gro sync'}).default(false),
+	})
+	.strict();
+export type Args = z.infer<typeof Args>;
+
+export type DevTask_Context = Plugin_Context<Args>;
+
+export const task: Task<Args> = {
+	summary: 'start SvelteKit and other dev plugins',
+	Args,
+	run: async (ctx) => {
+		const {args, invoke_task} = ctx;
+		const {watch, sync} = args;
+
+		await clean_fs({build_dev: true});
+
+		if (sync) {
+			await invoke_task('sync');
+		}
+
+		const plugins = await Plugins.create({...ctx, dev: true, watch});
+		await plugins.setup();
+		if (!watch) {
+			await plugins.teardown();
+		}
+	},
+};

package/src/lib/docs/README.gen.md.ts

@@ -0,0 +1,63 @@
+import {dirname, relative, basename} from 'node:path';
+import {parse_path_parts, parse_path_segments} from '@ryanatkn/belt/path.js';
+import {strip_start} from '@ryanatkn/belt/string.js';
+
+import {type Gen, to_output_file_name} from '../gen.js';
+import {paths, base_path_to_path_id} from '../paths.js';
+import {search_fs} from '../search_fs.js';
+
+// TODO look at `tasks.gen.md.ts` to refactor and generalize
+// TODO show nested structure, not a flat list
+// TODO work with file types beyond markdown
+
+/**
+ * Renders a simple index of a possibly nested directory of files.
+ */
+export const gen: Gen = ({origin_id}) => {
+	// TODO need to get this from project config or something
+	const root_path = parse_path_segments(paths.root).at(-1);
+
+	const origin_dir = dirname(origin_id);
+	const origin_base = basename(origin_id);
+
+	const base_dir = paths.source;
+	const relative_path = strip_start(origin_id, base_dir);
+	const relative_dir = dirname(relative_path);
+
+	// TODO should this be passed in the context, like `defaultOutputFileName`?
+	const output_file_name = to_output_file_name(origin_base);
+
+	// TODO this is GitHub-specific
+	const root_link = `[${root_path}](/../..)`;
+	const doc_files = search_fs(origin_dir);
+	const doc_paths: string[] = [];
+	for (const {path} of doc_files) {
+		if (path === output_file_name || !path.endsWith('.md')) {
+			continue;
+		}
+		doc_paths.push(path);
+	}
+
+	// TODO do we want to use absolute paths instead of relative paths,
+	// because GitHub works with them and it simplifies the code?
+	const is_index_file = output_file_name === 'README.md';
+	const path_parts = parse_path_parts(relative_dir).map((relative_path_part) => {
+		const segment = parse_path_segments(relative_path_part).at(-1);
+		return is_index_file && relative_path_part === relative_dir
+			? segment
+			: `[${segment}](${relative(origin_dir, base_path_to_path_id(relative_path_part)) || './'})`;
+	});
+	const breadcrumbs =
+		'> <sub>' + [root_link, ...path_parts, output_file_name].join(' / ') + '</sub>';
+
+	// TODO render the footer with the origin_id
+	return `# docs
+
+${breadcrumbs}
+
+${doc_paths.reduce((docList, doc) => docList + `- [${basename(doc, '.md')}](${doc})\n`, '')}
+${breadcrumbs}
+
+> <sub>generated by [${origin_base}](${origin_base})</sub>
+`;
+};

package/src/lib/docs/README.md

@@ -0,0 +1,20 @@
+# docs
+
+> <sub>[gro](/../..) / [lib](..) / docs / README.md</sub>
+
+- [build](build.md)
+- [config](config.md)
+- [deploy](deploy.md)
+- [dev](dev.md)
+- [gen](gen.md)
+- [gro_plugin_sveltekit_app](gro_plugin_sveltekit_app.md)
+- [package_json](package_json.md)
+- [plugin](plugin.md)
+- [publish](publish.md)
+- [task](task.md)
+- [tasks](tasks.md)
+- [test](test.md)
+
+> <sub>[gro](/../..) / [lib](..) / docs / README.md</sub>
+
+> <sub>generated by [README.gen.md.ts](README.gen.md.ts)</sub>

package/src/lib/docs/build.md

@@ -0,0 +1,41 @@
+# build
+
+> these docs are for production builds, for development see [dev.md](dev.md)
+
+## usage
+
+The `gro build` task produces outputs for production:
+
+```bash
+gro build
+```
+
+This runs the configured Gro plugins, `setup -> adapt -> teardown`, in production mode.
+
+If your project has a SvelteKit frontend,
+[the default plugin](../gro_plugin_sveltekit_app.ts) calls `vite build`,
+forwarding any [`-- vite [...]` args](https://vitejs.dev/config/):
+
+```bash
+gro build -- vite --config my-config.js
+```
+
+## plugins
+
+`Plugin`s are objects that customize the behavior of `gro build` and `gro dev`.
+They try to defer to underlying tools as much as possible, and exist to glue everything together.
+For example, the library plugin internally uses
+[`svelte-package`](https://kit.svelte.dev/docs/packaging).
+See [plugin.md](plugin.md) to learn more.
+
+## deploying and publishing
+
+Now that we can produce builds, how do we share them with the world?
+
+The [`gro deploy`](deploy.md) task outputs builds to a branch,
+like for static publishing to GitHub pages.
+
+The [`gro publish`](publish.md) task publishes packages to npm.
+
+Both of these tasks call `gro build` internally,
+and you can always run it manually if you're curious.