@ryanatkn/gro 0.119.0 → 0.120.0

package/README.md

@@ -76,7 +76,7 @@ It includes:
 
 ## install
 
-> depends on node >=20.10
+> depends on node >=22.3
 
 Typical usage installs [@ryanatkn/gro](https://www.npmjs.com/package/@ryanatkn/gro)
 as a dev dependency:
@@ -107,7 +107,7 @@ gro # prints available tasks - defers to any local gro installation
 Run a task: gro [name]
 View help:  gro [name] --help
 
-18 tasks in gro:
+19 tasks in gro:
 
 build      build the project
 changeset  call changeset with gro patterns
@@ -122,6 +122,7 @@ lint       run eslint
 publish    bump version, publish to npm, and git push
 reinstall  refreshes package-lock.json with the latest and cleanest deps
 release    publish and deploy
+resolve    run `gro gen`, update `package.json`, and optionally `npm i` to sync up
 run        execute a file with the loader, like `node` but works for TypeScript
 sync       run `gro gen`, update `package.json`, and optionally `npm i` to sync up
 test       run tests with uvu

package/dist/changelog.d.ts

@@ -1,3 +1,4 @@
+import type { Fetch_Value_Cache } from '@ryanatkn/belt/fetch.js';
 /**
  * Updates a changelog produced by `@changesets/changelog-git` with better links and formatting.
  * It's similar to `@changesets/changelog-github` but doesn't require a token for light usage.

package/dist/changeset.task.js

@@ -3,9 +3,8 @@ import { spawn } from '@ryanatkn/belt/process.js';
 import { red, blue } from 'kleur/colors';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { readdir } from 'node:fs/promises';
+import { existsSync, readdirSync } from 'node:fs';
 import { Task_Error } from './task.js';
-import { exists } from './fs.js';
 import { load_package_json } from './package_json.js';
 import { find_cli, spawn_cli } from './cli.js';
 import { Git_Origin, git_check_fully_staged_workspace, git_push_to_create } from './git.js';
@@ -67,7 +66,7 @@ export const task = {
             throw new Task_Error('Failed to find SvelteKit library: ' + has_sveltekit_library_result.message);
         }
         const path = join(dir, 'config.json');
-        const inited = await exists(path);
+        const inited = existsSync(path);
         if (!inited) {
             await spawn_cli('changeset', ['init']);
             const access = access_arg ?? package_json.private ? RESTRICTED_ACCESS : PUBLIC_ACCESS;
@@ -109,9 +108,9 @@ export const task = {
  * @see https://github.com/changesets/changesets/pull/1121
  */
 const create_changeset_adder = async (repo_name, dir, message, bump) => {
-    const filenames_before = await readdir(dir);
+    const filenames_before = readdirSync(dir);
     return async () => {
-        const filenames_after = await readdir(dir);
+        const filenames_after = readdirSync(dir);
         const filenames_added = filenames_after.filter((p) => !filenames_before.includes(p));
         if (!filenames_added.length) {
             throw Error('expected to find a new changeset file');

package/dist/clean_fs.d.ts

@@ -1,5 +1,4 @@
-/// <reference types="node" />
-import type { RmOptions } from 'node:fs';
+import { type RmOptions } from 'node:fs';
 export declare const clean_fs: ({ build, build_dev, build_dist, sveltekit, nodemodules, }: {
     build?: boolean;
     build_dev?: boolean;

package/dist/clean_fs.js

@@ -1,4 +1,5 @@
-import { rm, readdir } from 'node:fs/promises';
+import { rm } from 'node:fs/promises';
+import { readdirSync } from 'node:fs';
 import { paths } from './paths.js';
 import { NODE_MODULES_DIRNAME, GRO_DIST_PREFIX, SVELTEKIT_DEV_DIRNAME, SVELTEKIT_BUILD_DIRNAME, SVELTEKIT_VITE_CACHE_PATH, SVELTEKIT_DIST_DIRNAME, } from './path_constants.js';
 export const clean_fs = async ({ build = false, build_dev = false, build_dist = false, sveltekit = false, nodemodules = false, }, rm_options = { force: true, recursive: true }) => {
@@ -10,7 +11,7 @@ export const clean_fs = async ({ build = false, build_dev = false, build_dist =
         promises.push(rm(paths.build_dev, rm_options));
     }
     if (build || build_dist) {
-        const paths = (await readdir('.')).filter((p) => p.startsWith(GRO_DIST_PREFIX));
+        const paths = readdirSync('.').filter((p) => p.startsWith(GRO_DIST_PREFIX));
         for (const path of paths) {
             promises.push(rm(path, rm_options));
         }

package/dist/cli.d.ts

@@ -1,10 +1,9 @@
-/// <reference types="node" />
 import type { SpawnOptions } from 'node:child_process';
 import { type Spawn_Result } from '@ryanatkn/belt/process.js';
 /**
  * Looks for the CLI `name`, first local to the cwd and then globally.
  */
-export declare const find_cli: (name: string) => Promise<'local' | 'global' | null>;
+export declare const find_cli: (name: string) => Promise<"local" | "global" | null>;
 /**
  * Calls the CLI `name` if available, first local to the cwd and then globally.
  */

package/dist/cli.js

@@ -1,12 +1,12 @@
 import { spawn, spawn_out } from '@ryanatkn/belt/process.js';
 import { join } from 'node:path';
-import { exists } from './fs.js';
+import { existsSync } from 'node:fs';
 import { NODE_MODULES_DIRNAME } from './path_constants.js';
 /**
  * Looks for the CLI `name`, first local to the cwd and then globally.
  */
 export const find_cli = async (name) => {
-    if (await exists(join(NODE_MODULES_DIRNAME, `.bin/${name}`))) {
+    if (existsSync(join(NODE_MODULES_DIRNAME, `.bin/${name}`))) {
         return 'local';
     }
     const { stdout } = await spawn_out('which', [name]);

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import type { Create_Config_Plugins } from './plugin.js';
 import type { Map_Package_Json } from './package_json.js';
+import type { Path_Filter } from './path.js';
 export interface Gro_Config {
     plugins: Create_Config_Plugins;
     /**
@@ -12,12 +13,24 @@ export interface Gro_Config {
      * 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_paths: string[];
+    task_root_dirs: string[];
+    /**
+     * When searching the filsystem for tasks and genfiles,
+     * directories and files are included if they pass all of these filters.
+     */
+    search_filters: Path_Filter | Path_Filter[] | null;
 }
 export interface Create_Gro_Config {
     (base_config: Gro_Config): Gro_Config | Promise<Gro_Config>;
 }
 export declare const create_empty_config: () => Gro_Config;
+/**
+ * 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 declare const DEFAULT_SEARCH_EXCLUDER: RegExp;
 export declare const DEFAULT_EXPORTS_EXCLUDER: RegExp;
 export interface Gro_Config_Module {
     readonly default: Gro_Config | Create_Gro_Config;

package/dist/config.js

@@ -1,14 +1,26 @@
 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 } from './path_constants.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 { exists } from './fs.js';
 export const create_empty_config = () => ({
     plugins: () => [],
     // TODO maybe disable if no SvelteKit `lib` directory? or other detection to improve defaults
     map_package_json: default_map_package_json,
-    task_root_paths: [paths.lib, paths.root, IS_THIS_GRO ? null : GRO_DIST_DIR].filter(Boolean),
+    task_root_dirs: [
+        paths.lib,
+        IS_THIS_GRO ? null : paths.root,
+        IS_THIS_GRO ? null : GRO_DIST_DIR,
+    ].filter(Boolean),
+    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(`((^|/)\\.[^/]+|/?${NODE_MODULES_DIRNAME}|(^|/)${SVELTEKIT_BUILD_DIRNAME}|(?<!(^|/)gro/)${SVELTEKIT_DIST_DIRNAME}|(^|/)${SERVER_DIST_PATH})($|/)`, 'u');
 const default_map_package_json = async (package_json) => {
     if (package_json.exports) {
         package_json.exports = Object.fromEntries(Object.entries(package_json.exports).filter(([k]) => !DEFAULT_EXPORTS_EXCLUDER.test(k)));
@@ -20,7 +32,7 @@ export const load_config = async (dir = paths.root) => {
     const default_config = await create_default_config(create_empty_config());
     const config_path = join(dir, GRO_CONFIG_PATH);
     let config;
-    if (await exists(config_path)) {
+    if (existsSync(config_path)) {
         const config_module = await import(config_path);
         validate_config_module(config_module, config_path);
         config =
@@ -37,7 +49,7 @@ export const load_config = async (dir = paths.root) => {
 // Mutates `config` with cleaned up values.
 const normalize_config = (config) => {
     // TODO any validation?
-    config.task_root_paths = config.task_root_paths.map((p) => resolve(p));
+    config.task_root_dirs = config.task_root_dirs.map((p) => resolve(p));
 };
 export const validate_config_module = (config_module, config_path) => {
     const config = config_module.default;

package/dist/config.test.js

@@ -1,8 +1,57 @@
 import { test } from 'uvu';
 import * as assert from 'uvu/assert';
-import { load_config } from './config.js';
+import { DEFAULT_SEARCH_EXCLUDER, load_config } from './config.js';
 test('load_config', async () => {
     const config = await load_config();
     assert.ok(config);
 });
+test('DEFAULT_SEARCH_EXCLUDER', () => {
+    const assert_excludes = (dirname) => {
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`a/${dirname}/c`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`a/${dirname}/c/d.js`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`a/${dirname}/`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`a/${dirname}`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`/a/${dirname}/c`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`/a/${dirname}/c/d.js`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`/a/${dirname}/`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`/a/${dirname}`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`/${dirname}/a`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`/${dirname}/a/b.js`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`/${dirname}/`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`/${dirname}`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`./${dirname}/a`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`./${dirname}/a/b.js`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`./${dirname}/`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`./${dirname}`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`${dirname}/a`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`${dirname}/a/b.js`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`${dirname}/`), 'should exclude: ' + dirname);
+        assert.ok(DEFAULT_SEARCH_EXCLUDER.test(`${dirname}`), 'should exclude: ' + dirname);
+    };
+    assert_excludes('node_modules');
+    assert_excludes('dist');
+    assert_excludes('build');
+    assert_excludes('.git');
+    assert_excludes('.gro');
+    assert_excludes('.svelte-kit');
+    assert.ok(!DEFAULT_SEARCH_EXCLUDER.test('nodemodules'));
+    assert.ok(!DEFAULT_SEARCH_EXCLUDER.test('a/b/c'));
+    assert.ok(!DEFAULT_SEARCH_EXCLUDER.test('/a/b/c'));
+    assert.ok(!DEFAULT_SEARCH_EXCLUDER.test('/a/b/c.js'));
+    assert.ok(!DEFAULT_SEARCH_EXCLUDER.test('/a/b/c.d.js'));
+    assert.ok(!DEFAULT_SEARCH_EXCLUDER.test('./a/b/c'));
+    assert.ok(!DEFAULT_SEARCH_EXCLUDER.test('./a/b/c.d.js'));
+    // Special exception for `gro/dist/`:
+    assert.ok(DEFAULT_SEARCH_EXCLUDER.test('/home/not_gro/dist/a.task.js'));
+    assert.ok(DEFAULT_SEARCH_EXCLUDER.test('/home/grodist/a.task.js'));
+    assert.ok(DEFAULT_SEARCH_EXCLUDER.test('not_gro/dist/a.task.js'));
+    assert.ok(DEFAULT_SEARCH_EXCLUDER.test('not_dist/a.task.js'));
+    assert.ok(DEFAULT_SEARCH_EXCLUDER.test('grodist/a.task.js'));
+    assert.ok(!DEFAULT_SEARCH_EXCLUDER.test('/home/gro/dist/a.task.js'));
+    assert.ok(!DEFAULT_SEARCH_EXCLUDER.test('gro/dist/a.task.js'));
+    assert.ok(!DEFAULT_SEARCH_EXCLUDER.test('./gro/dist/a.task.js'));
+    // But not `gro/build/` and others because they're not usecases:
+    assert.ok(DEFAULT_SEARCH_EXCLUDER.test('/home/gro/build/a.task.js'));
+    assert.ok(DEFAULT_SEARCH_EXCLUDER.test('/home/gro/node_modules/a.task.js'));
+});
 test.run();

package/dist/deploy.task.js

@@ -2,12 +2,13 @@ import { spawn } from '@ryanatkn/belt/process.js';
 import { print_error } from '@ryanatkn/belt/print.js';
 import { green, red } from 'kleur/colors';
 import { z } from 'zod';
-import { cp, mkdir, readdir, rm } from 'node:fs/promises';
+import { cp, mkdir, rm } from 'node:fs/promises';
 import { join, resolve } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
 import { Task_Error } from './task.js';
 import { print_path } from './paths.js';
 import { GRO_DIRNAME, GIT_DIRNAME, SVELTEKIT_BUILD_DIRNAME } from './path_constants.js';
-import { empty_dir, exists } from './fs.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:
@@ -96,7 +97,7 @@ export const task = {
             // 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 exists(resolved_deploy_dir)) {
+            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.
@@ -114,7 +115,7 @@ export const task = {
             }
             // Second, initialize the deploy dir if needed.
             // It may not exist, or it may have been deleted after failing to sync above.
-            if (!(await exists(resolved_deploy_dir))) {
+            if (!existsSync(resolved_deploy_dir)) {
                 const local_deploy_branch_exists = await git_local_branch_exists(target);
                 await git_fetch(origin, ('+' + target + ':' + target)); // fetch+merge and allow non-fastforward updates with the +
                 await git_clone_locally(origin, target, dir, resolved_deploy_dir);
@@ -131,7 +132,7 @@ export const task = {
         else {
             // Remote target branch does not exist, so start from scratch
             // Delete the deploy dir and recreate it
-            if (await exists(resolved_deploy_dir)) {
+            if (existsSync(resolved_deploy_dir)) {
                 await rm(resolved_deploy_dir, { recursive: true });
                 await mkdir(resolved_deploy_dir, { recursive: true });
             }
@@ -160,7 +161,7 @@ export const task = {
             if (build) {
                 await invoke_task('build');
             }
-            if (!(await exists(build_dir))) {
+            if (!existsSync(build_dir)) {
                 log.error(red('directory to deploy does not exist after building:'), build_dir);
                 return;
             }
@@ -173,7 +174,7 @@ export const task = {
             throw new Task_Error(`Deploy safely canceled due to build failure. See the error above.`);
         }
         // Copy the build
-        await Promise.all((await readdir(build_dir)).map((path) => cp(join(build_dir, path), join(resolved_deploy_dir, path), { recursive: true })));
+        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));

package/dist/docs/README.gen.md.js

@@ -2,7 +2,7 @@ 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 { to_output_file_name } from '../gen.js';
-import { paths, base_path_to_source_id } from '../paths.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
@@ -24,7 +24,7 @@ export const gen = async ({ origin_id }) => {
     const root_link = `[${root_path}](/../..)`;
     const doc_files = await search_fs(origin_dir);
     const doc_paths = [];
-    for (const path of doc_files.keys()) {
+    for (const { path } of doc_files) {
         if (path === output_file_name || !path.endsWith('.md')) {
             continue;
         }
@@ -37,7 +37,7 @@ export const gen = async ({ origin_id }) => {
         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_source_id(relative_path_part)) || './'})`;
+            : `[${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

package/dist/docs/config.md

@@ -44,7 +44,8 @@ export interface Create_Gro_Config {
 export interface Gro_Config {
 	plugins: Create_Config_Plugins;
 	map_package_json: Map_Package_Json | null;
-	task_root_paths: string[];
+	task_root_dirs: string[];
+	search_filters: Path_Filter | Path_Filter[] | null;
 }
 ```
 
@@ -55,7 +56,11 @@ import type {Create_Gro_Config} from '@ryanatkn/gro';
 import {gro_plugin_sveltekit_app} from '@ryanatkn/gro/gro_plugin_sveltekit_app.js';
 
 const config: Create_Gro_Config = async (cfg) => {
-	// example setting your own plugins:
+	// `cfg`, which is equal to `create_empty_config()`,
+	// can be mutated or you can return your own.
+	// A return value is required to avoid potential errors and reduce ambiguity.
+
+	// example setting your own plugins):
 	cfg.plugins = async () => [
 		gro_plugin_sveltekit_app(),
 		(await import('./src/custom_plugin.js')).plugin(),
@@ -90,7 +95,8 @@ const config = create_empty_config();
 
 // config.plugins = ...;
 // config.map_package_json = ...;
-// config.task_root_paths = ...;
+// config.task_root_dirs = ...;
+// config.search_filters = ...;
 
 export default config;
 ```
@@ -176,12 +182,22 @@ export interface Map_Package_Json {
 }
 ```
 
-## `task_root_paths`
+## `task_root_dirs`
 
-The Gro config option `task_root_paths` allows customizing Gro's task resolution.
+The Gro config option `task_root_dirs` allows customizing Gro's task resolution.
 When calling `gro [input_path]`, absolute and explicitly relative paths starting with `.`
 are resolved according to normal filesystem rules,
 but non-explicit input paths, like `foo`, are resolved by searching
-through `task_root_paths` in order until a matching file or directory is found on the filesystem.
+through `task_root_dirs` in order until a matching file or directory is found on the filesystem.
 
 The default task paths are `./src/lib`, then `.`, and then Gro's dist directory.
+
+## `search_filters`
+
+The Gro config option `search_filters` allows customizing
+how Gro searches for tasks and genfiles on the filesystem.
+Directories and files are included if they pass all of these filters.
+
+By default, it uses the `DEFAULT_SEARCH_EXCLUDER` to exclude
+dot-prefixed directories, node_modules,
+and the build and dist directories for SvelteKit and Gro.

package/dist/docs/gen.md

@@ -109,10 +109,11 @@ The `Gen` function receives one argument, the `Gen_Context` object:
 ```ts
 export interface Gen_Context {
 	config: Gro_Config;
+	sveltekit_config: Parsed_Sveltekit_Config;
 	/**
 	 * Same as `import.meta.url` but in path form.
 	 */
-	origin_id: string;
+	origin_id: Path_Id;
 	log: Logger;
 }
 // export const gen: Gen = ({config, origin_id, log}) => {

package/dist/docs/task.md

@@ -28,7 +28,7 @@ and defers composition to the user in regular TypeScript modules.
 - Gro automatically discovers all `*.task.ts|js` files
   in its configurable directory, so creating a new task
   is as simple as [creating a new file](#define-a-task), no config needed
-  (defaults to `src/lib`, see the config option [`task_root_paths`](./config.md#task_root_paths))
+  (defaults to `src/lib`, see the config option [`task_root_dirs`](./config.md#task_root_dirs))
 - to view [the available tasks](https://github.com/ryanatkn/gro/blob/main/src/lib/docs/tasks.md)
   run `gro` with no arguments
 - task definitions are just objects with an async `run` function and some optional properties,
@@ -59,10 +59,10 @@ As a developer, it's nice to be able to reuse TypeScript modules in every contex
 $ gro
 ```
 
-The [config](./config.md) option [task_root_paths](./config.md#task_root_paths)
+The [config](./config.md) option [task_root_dirs](./config.md#task_root_dirs)
 tells Gro where to search for tasks.
 
-> Currently, only the first directory specified in `task_root_paths` that's found on the filesystem
+> Currently, only the first directory specified in `task_root_dirs` that's found on the filesystem
 > will be used to automatically discover tasks, like when running `gro` without args.
 > Please open an issue if you would like to see Gro be able to discover
 > tasks in more than one directory - it will take some reworking of internals
@@ -162,6 +162,7 @@ import type {Task_Context} from '@ryanatkn/gro';
 export interface Task_Context<T_Args = object> {
 	args: T_Args;
 	config: Gro_Config;
+	sveltekit_config: Parsed_Sveltekit_Config;
 	log: Logger;
 	timings: Timings;
 	invoke_task: (task_name: string, args?: Args, config?: Gro_Config) => Promise<void>;

package/dist/docs/tasks.gen.md.js

@@ -2,25 +2,32 @@ 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 { to_output_file_name } from '../gen.js';
-import { paths, base_path_to_source_id } from '../paths.js';
-import { load_task_modules } from '../task_module.js';
+import { paths, base_path_to_path_id } from '../paths.js';
 import { log_error_reasons } from '../task_logging.js';
+import { find_tasks, load_tasks, Task_Error } from '../task.js';
 // This is the first simple implementation of Gro's automated docs.
 // It combines Gro's gen and task systems
-// to generate a markdown file describing all of the project's tasks.
+// to generate a markdown file with a summary of all of Gro's tasks.
 // Other projects that use Gro should be able to import this module
 // or other otherwise get frictionless access to this specific use case,
 // and they should be able to extend or customize it to any degree.
 // TODO display more info about each task, including a summary and params
 // TODO needs some cleanup and better APIs - paths are confusing and verbose!
 // TODO add backlinks to every document that links to this one
-export const gen = async ({ config, origin_id, log }) => {
-    const result = await load_task_modules([paths.lib], config.task_root_paths);
-    if (!result.ok) {
-        log_error_reasons(log, result.reasons);
-        throw new Error(result.type);
+export const gen = async ({ origin_id, log, config }) => {
+    const found = await find_tasks(['.'], [paths.lib], config);
+    if (!found.ok) {
+        log_error_reasons(log, found.reasons);
+        throw new Task_Error(`Failed to generate task docs: ${found.type}`);
     }
-    const tasks = result.modules;
+    const found_tasks = found.value;
+    const loaded = await load_tasks(found_tasks);
+    if (!loaded.ok) {
+        log_error_reasons(log, loaded.reasons);
+        throw new Task_Error(`Failed to generate task docs: ${loaded.type}`);
+    }
+    const loaded_tasks = loaded.value;
+    const tasks = loaded_tasks.modules;
     const root_path = parse_path_segments(paths.root).at(-1);
     const origin_dir = dirname(origin_id);
     const origin_base = basename(origin_id);
@@ -33,7 +40,7 @@ export const gen = async ({ config, origin_id, log }) => {
     const root_link = `[${root_path}](/../..)`;
     // TODO do we want to use absolute paths instead of relative paths,
     // because GitHub works with them and it simplifies the code?
-    const path_parts = parse_path_parts(relative_dir).map((relative_path_part) => `[${parse_path_segments(relative_path_part).at(-1)}](${relative(origin_dir, base_path_to_source_id(relative_path_part)) || './'})`);
+    const path_parts = parse_path_parts(relative_dir).map((relative_path_part) => `[${parse_path_segments(relative_path_part).at(-1)}](${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 `# tasks

package/dist/docs/tasks.md

@@ -19,6 +19,7 @@ What is a `Task`? See [`task.md`](./task.md).
 - [publish](../publish.task.ts) - bump version, publish to npm, and git push
 - [reinstall](../reinstall.task.ts) - refreshes package-lock.json with the latest and cleanest deps
 - [release](../release.task.ts) - publish and deploy
+- [resolve](../resolve.task.ts) - diagnostic that logs the info resolved from the filesystem for the given input paths
 - [run](../run.task.ts) - execute a file with the loader, like `node` but works for TypeScript
 - [sync](../sync.task.ts) - run `gro gen`, update `package.json`, and optionally `npm i` to sync up
 - [test](../test.task.ts) - run tests with uvu

package/dist/env.d.ts

@@ -1,6 +1,5 @@
-/// <reference types="node" />
-export declare const load_env: (dev: boolean, visibility: 'public' | 'private', public_prefix: string, private_prefix: string, env_dir?: string, env_files?: string[], ambient_env?: NodeJS.ProcessEnv) => Promise<Record<string, string>>;
-export declare const merge_envs: (envs: Array<Record<string, string | undefined>>, visibility: 'public' | 'private', public_prefix: string, private_prefix: string) => Record<string, string>;
+export declare const load_env: (dev: boolean, visibility: "public" | "private", public_prefix: string, private_prefix: string, env_dir?: string, env_files?: string[], ambient_env?: NodeJS.ProcessEnv) => Promise<Record<string, string>>;
+export declare const merge_envs: (envs: Array<Record<string, string | undefined>>, visibility: "public" | "private", public_prefix: string, private_prefix: string) => Record<string, string>;
 export declare const is_private_env: (key: string, public_prefix: string, private_prefix: string) => boolean;
 export declare const is_public_env: (key: string, public_prefix: string, private_prefix: string) => boolean;
 /**

package/dist/env.js

@@ -1,7 +1,7 @@
 import dotenv from 'dotenv';
 import { readFile } from 'node:fs/promises';
 import { resolve } from 'node:path';
-import { exists } from './fs.js';
+import { existsSync } from 'node:fs';
 export const load_env = async (dev, visibility, public_prefix, private_prefix, env_dir, env_files = ['.env', '.env.' + (dev ? 'development' : 'production')], ambient_env = process.env) => {
     const envs = await Promise.all(env_files
         .map(async (path) => (await load(env_dir === undefined ? path : resolve(env_dir, path))))
@@ -10,7 +10,7 @@ export const load_env = async (dev, visibility, public_prefix, private_prefix, e
     return merge_envs(envs, visibility, public_prefix, private_prefix);
 };
 const load = async (path) => {
-    if (!(await exists(path)))
+    if (!existsSync(path))
         return undefined;
     const loaded = await readFile(path, 'utf8');
     return dotenv.parse(loaded);

package/dist/esbuild_helpers.d.ts

@@ -1,3 +1,4 @@
+import type { Logger } from '@ryanatkn/belt/log.js';
 import type * as esbuild from 'esbuild';
 import type { Parsed_Sveltekit_Config } from './sveltekit_config.js';
 export declare const print_build_result: (log: Logger, build_result: esbuild.BuildResult) => void;
@@ -10,5 +11,5 @@ export declare const print_build_result: (log: Logger, build_result: esbuild.Bui
  * @param mode
  * @returns
  */
-export declare const to_define_import_meta_env: (dev: boolean, base_url: Parsed_Sveltekit_Config['base_url'], ssr?: boolean, mode?: string) => Record<string, string>;
+export declare const to_define_import_meta_env: (dev: boolean, base_url: Parsed_Sveltekit_Config["base_url"], ssr?: boolean, mode?: string) => Record<string, string>;
 export declare const ts_transform_options: esbuild.TransformOptions;

package/dist/esbuild_plugin_external_worker.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="svelte" />
 import * as esbuild from 'esbuild';
 import type { Logger } from '@ryanatkn/belt/log.js';
 import type { CompileOptions, PreprocessorGroup, ModuleCompileOptions } from 'svelte/compiler';

package/dist/esbuild_plugin_external_worker.js

@@ -11,11 +11,11 @@ export const esbuild_plugin_external_worker = ({ dev, build_options, dir = proce
     name: 'external_worker',
     setup: (build) => {
         const builds = new Map();
-        const build_worker = async (source_id) => {
-            if (builds.has(source_id))
-                return builds.get(source_id);
+        const build_worker = async (path_id) => {
+            if (builds.has(path_id))
+                return builds.get(path_id);
             const building = esbuild.build({
-                entryPoints: [source_id],
+                entryPoints: [path_id],
                 plugins: [
                     esbuild_plugin_sveltekit_shim_app({ dev, base_url, assets_url }),
                     esbuild_plugin_sveltekit_shim_env({
@@ -38,13 +38,13 @@ export const esbuild_plugin_external_worker = ({ dev, build_options, dir = proce
                 define: to_define_import_meta_env(dev, base_url),
                 ...build_options,
             });
-            builds.set(source_id, building);
+            builds.set(path_id, building);
             return building;
         };
         build.onResolve({ filter: /\.worker(|\.js|\.ts)$/u }, async ({ path, resolveDir }) => {
             const parsed = await resolve_specifier(path, resolveDir);
-            const { specifier, source_id, namespace } = parsed;
-            const build_result = await build_worker(source_id);
+            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 };

package/dist/esbuild_plugin_svelte.d.ts

@@ -1,4 +1,3 @@
-/// <reference types="svelte" />
 import type * as esbuild from 'esbuild';
 import { type CompileOptions, type ModuleCompileOptions, type PreprocessorGroup } from 'svelte/compiler';
 export interface Options {

package/dist/esbuild_plugin_sveltekit_local_imports.js

@@ -13,8 +13,8 @@ export const esbuild_plugin_sveltekit_local_imports = () => ({
             const { path, importer } = args;
             if (!importer)
                 return { path };
-            const { source_id, namespace } = await resolve_specifier(path, dirname(importer));
-            return { path: source_id, namespace }; // `namespace` may be `undefined`, but esbuild needs the absolute path for json etc
+            const { path_id, namespace } = await resolve_specifier(path, dirname(importer));
+            return { path: path_id, namespace }; // `namespace` may be `undefined`, but esbuild needs the absolute path for json etc
         });
         build.onLoad({ filter: /.*/u, namespace: 'sveltekit_local_imports_ts' }, async ({ path }) => ({
             contents: await readFile(path),

package/dist/format_directory.d.ts

@@ -1,4 +1,5 @@
 import type { Spawn_Result } from '@ryanatkn/belt/process.js';
+import type { Logger } from '@ryanatkn/belt/log.js';
 /**
  * Formats a directory on the filesystem.
  * If the source directory is given, it also formats all of the root directory files.

package/dist/fs.d.ts

@@ -1,6 +1,4 @@
-/// <reference types="node" />
-import type { RmOptions } from 'node:fs';
-export declare const exists: (path: string) => Promise<boolean>;
+import { type RmOptions } from 'node:fs';
 /**
  * Empties a directory with an optional `filter`.
  */