@ryanatkn/gro 0.129.6 → 0.129.8

package/README.md

@@ -20,14 +20,14 @@ and [esbuild](https://github.com/evanw/esbuild)
 for making web frontends, servers, and libraries with TypeScript.
 It includes:
 
-- [task runner](/src/lib/docs/task.md) that uses the filesystem convention `*.task.ts`
-  - lots of [common builtin tasks](/src/lib/docs/tasks.md) that users can easily override and compose
+- [task runner](/src/docs/task.md) that uses the filesystem convention `*.task.ts`
+  - lots of [common builtin tasks](/src/docs/tasks.md) that users can easily override and compose
 - tools and patterns for
-  [developing](/src/lib/docs/dev.md),
-  [building](/src/lib/docs/build.md),
-  [testing](/src/lib/docs/test.md),
-  [deploying](/src/lib/docs/deploy.md),
-  and [publishing](/src/lib/docs/publish.md)
+  [developing](/src/docs/dev.md),
+  [building](/src/docs/build.md),
+  [testing](/src/docs/test.md),
+  [deploying](/src/docs/deploy.md),
+  and [publishing](/src/docs/publish.md)
   [SvelteKit](https://github.com/sveltejs/kit) apps, library packages, and Node servers
   - integrated [TypeScript](https://github.com/microsoft/typescript),
     [Svelte](https://github.com/sveltejs/svelte),
@@ -45,16 +45,16 @@ It includes:
       (these are best-effort shims, not perfect)
     - supports running TypeScript files directly without a task via `gro run a.ts`
       or `node --import @ryanatkn/gro/register.js a.ts`
-  - [configurable plugins](/src/lib/docs/plugin.md) to support SvelteKit,
+  - [configurable plugins](/src/docs/plugin.md) to support SvelteKit,
     [auto-restarting Node servers](/src/lib/gro_plugin_server.ts),
     and other external build processes
-    - see the [Gro config docs](/src/lib/docs/config.md) and
+    - see the [Gro config docs](/src/docs/config.md) and
       [the default config](https://github.com/ryanatkn/gro/blob/main/src/lib/gro.config.default.ts)
     - see [`fuz_template`](https://github.com/fuz-dev/fuz_template)
       for a simple starter project example, and
       [`@feltjs/felt`](https://github.com/feltjs/felt) for a more complex example with custom tasks
-- [testing](/src/lib/docs/test.md) with [`uvu`](https://github.com/lukeed/uvu)
-- codegen by convention with [`gen`](/src/lib/docs/gen.md)
+- [testing](/src/docs/test.md) with [`uvu`](https://github.com/lukeed/uvu)
+- codegen by convention with [`gen`](/src/docs/gen.md)
 - linting with [ESLint](https://github.com/eslint/eslint)
   (I also maintain [`@feltjs/eslint-config`](https://github.com/feltjs/eslint-config))
 - formatting with [Prettier](https://github.com/prettier/prettier)
@@ -62,17 +62,17 @@ It includes:
 ## docs
 
 - developing web frontends, servers, and libraries
-  - [config](/src/lib/docs/config.md)
-  - [dev](/src/lib/docs/dev.md)
-  - [build](/src/lib/docs/build.md) for production
-  - [deploy](/src/lib/docs/deploy.md) to a branch, like for GitHub pages
-  - [publish](/src/lib/docs/publish.md) to npm
-- [`Task`](/src/lib/docs/task.md) runner
-  - builtin [tasks](/src/lib/docs/tasks.md) list
-- [testing](/src/lib/docs/test.md) with [`uvu`](https://github.com/lukeed/uvu)
-- [`gen`](/src/lib/docs/gen.md) code generation
-- [`public` package](/src/lib/docs/package_json.md#public-packages) features (nonstandard)
-- full [docs index](/src/lib/docs#readme)
+  - [config](/src/docs/config.md)
+  - [dev](/src/docs/dev.md)
+  - [build](/src/docs/build.md) for production
+  - [deploy](/src/docs/deploy.md) to a branch, like for GitHub pages
+  - [publish](/src/docs/publish.md) to npm
+- [`Task`](/src/docs/task.md) runner
+  - builtin [tasks](/src/docs/tasks.md) list
+- [testing](/src/docs/test.md) with [`uvu`](https://github.com/lukeed/uvu)
+- [`gen`](/src/docs/gen.md) code generation
+- [`public` package](/src/docs/package_json.md#public-packages) features (nonstandard)
+- full [docs index](/src/docs#readme)
 
 ## install
 
@@ -161,8 +161,8 @@ await import('./foo.ts');
 ```
 
 Gro has a number of builtin tasks that you can run with the CLI.
-To learn more [see the task docs](/src/lib/docs/task.md)
-and [the generated task index](/src/lib/docs/tasks.md).
+To learn more [see the task docs](/src/docs/task.md)
+and [the generated task index](/src/docs/tasks.md).
 
 ```bash
 gro dev # start developing in watch mode
@@ -173,7 +173,7 @@ gro dev -- vite --port 3003 # forward args by separating sections with --
 gro build # build everything for production
 ```
 
-[Testing](/src/lib/docs/test.md) with [`uvu`](https://github.com/lukeed/uvu),
+[Testing](/src/docs/test.md) with [`uvu`](https://github.com/lukeed/uvu),
 including shims for [SvelteKit modules](https://kit.svelte.dev/docs/modules):
 
 ```bash
@@ -202,20 +202,20 @@ gro format # format all of the source files using Prettier
 gro format --check # check that all source files are formatted
 ```
 
-Codegen with [`gen`](/src/lib/docs/gen.md):
+Codegen with [`gen`](/src/docs/gen.md):
 
 ```bash
 gro gen # run codegen for all `*.gen.*` files
 gro gen --check # error if any generated files are new or different
 ```
 
-To deploy: (also see [`src/lib/docs/deploy.md`](/src/lib/docs/deploy.md))
+To deploy: (also see [`src/docs/deploy.md`](/src/docs/deploy.md))
 
 ```bash
 gro deploy # build and push to the `deploy` branch
 ```
 
-To publish: (also see [`src/lib/docs/publish.md`](/src/lib/docs/publish.md))
+To publish: (also see [`src/docs/publish.md`](/src/docs/publish.md))
 
 ```bash
 gro publish # flush changeset to changelog, bump version, publish to npm, and git push
@@ -230,8 +230,8 @@ gro upgrade excluded-dep-1 excluded-dep-2 # npm updates to the latest everything
 gro --version # print the Gro version
 ```
 
-For more see [the tasks index](/src/lib/docs/tasks.md),
-[the task feature docs](/src/lib/docs/task.md), and [the docs index](/src/lib/docs/README.md).
+For more see [the tasks index](/src/docs/tasks.md),
+[the task feature docs](/src/docs/task.md), and [the docs index](/src/docs/README.md).
 
 ## develop
 

package/dist/config.d.ts

@@ -4,11 +4,11 @@ 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
+ * @see https://github.com/ryanatkn/gro/blob/main/src/docs/config.md
  */
 export interface Gro_Config {
     /**
-     * @see https://github.com/ryanatkn/gro/blob/main/src/lib/docs/plugin.md
+     * @see https://github.com/ryanatkn/gro/blob/main/src/docs/plugin.md
      */
     plugins: Create_Config_Plugins;
     /**
@@ -31,7 +31,7 @@ export interface Gro_Config {
 /**
  * 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
+ * @see https://github.com/ryanatkn/gro/blob/main/src/docs/config.md
  */
 export interface Raw_Gro_Config {
     plugins?: Create_Config_Plugins;

package/dist/gen.test.js

@@ -241,7 +241,7 @@ test('validate_gen_module basic behavior', () => {
     assert.ok(!validate_gen_module({ task: { run: {} } }));
 });
 test('find_genfiles_result finds gen modules in a directory', () => {
-    const find_genfiles_result = find_genfiles(['docs'], [paths.lib], create_empty_config());
+    const find_genfiles_result = find_genfiles(['../docs'], [paths.lib], create_empty_config());
     assert.ok(find_genfiles_result.ok);
     assert.ok(find_genfiles_result.value.resolved_input_paths.length);
 });

package/dist/invoke.js

@@ -7,7 +7,7 @@ import { sveltekit_sync_if_obviously_needed } from './sveltekit_helpers.js';
 
 This module invokes the Gro CLI which in turn invokes tasks.
 Tasks are the CLI's primary concept.
-To learn more about them, see `src/lib/docs/task.md`.
+To learn more about them, see `src/docs/task.md`.
 
 When the CLI is invoked it passes the first CLI arg as `task_name` to `invoke_task`,
 and the rest of the args are forwarded to the task's `run` function.

package/dist/package.js

@@ -1,7 +1,7 @@
 // generated by src/lib/package.gen.ts
 export const package_json = {
     name: '@ryanatkn/gro',
-    version: '0.129.6',
+    version: '0.129.8',
     description: 'task runner and toolkit extending SvelteKit',
     motto: 'generate, run, optimize',
     glyph: '🌰',
@@ -266,7 +266,7 @@ export const package_json = {
 };
 export const src_json = {
     name: '@ryanatkn/gro',
-    version: '0.129.6',
+    version: '0.129.8',
     modules: {
         '.': {
             path: 'index.ts',

package/dist/src_json.d.ts

@@ -88,7 +88,7 @@ export declare const Src_Modules: z.ZodRecord<z.ZodString, z.ZodObject<{
 }, z.ZodTypeAny, "passthrough">>>;
 export type Src_Modules = z.infer<typeof Src_Modules>;
 /**
- * @see https://github.com/ryanatkn/gro/blob/main/src/lib/docs/gro_plugin_sveltekit_app.md#well-known-src
+ * @see https://github.com/ryanatkn/gro/blob/main/src/docs/gro_plugin_sveltekit_app.md#well-known-src
  */
 export declare const Src_Json: z.ZodIntersection<z.ZodRecord<z.ZodString, z.ZodUnknown>, z.ZodObject<{
     name: z.ZodString;

package/dist/src_json.js

@@ -22,7 +22,7 @@ export const Src_Module = z
     .passthrough();
 export const Src_Modules = z.record(Src_Module);
 /**
- * @see https://github.com/ryanatkn/gro/blob/main/src/lib/docs/gro_plugin_sveltekit_app.md#well-known-src
+ * @see https://github.com/ryanatkn/gro/blob/main/src/docs/gro_plugin_sveltekit_app.md#well-known-src
  */
 export const Src_Json = z.intersection(z.record(z.unknown()), // TODO is this what we want?
 z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryanatkn/gro",
-  "version": "0.129.6",
+  "version": "0.129.8",
   "description": "task runner and toolkit extending SvelteKit",
   "motto": "generate, run, optimize",
   "glyph": "🌰",

package/src/lib/config.ts

@@ -17,11 +17,11 @@ 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
+ * @see https://github.com/ryanatkn/gro/blob/main/src/docs/config.md
  */
 export interface Gro_Config {
 	/**
-	 * @see https://github.com/ryanatkn/gro/blob/main/src/lib/docs/plugin.md
+	 * @see https://github.com/ryanatkn/gro/blob/main/src/docs/plugin.md
 	 */
 	plugins: Create_Config_Plugins;
 	/**
@@ -45,7 +45,7 @@ export interface Gro_Config {
 /**
  * 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
+ * @see https://github.com/ryanatkn/gro/blob/main/src/docs/config.md
  */
 export interface Raw_Gro_Config {
 	plugins?: Create_Config_Plugins;

package/src/lib/gen.test.ts

@@ -298,7 +298,7 @@ test('validate_gen_module basic behavior', () => {
 });
 
 test('find_genfiles_result finds gen modules in a directory', () => {
-	const find_genfiles_result = find_genfiles(['docs'], [paths.lib], create_empty_config());
+	const find_genfiles_result = find_genfiles(['../docs'], [paths.lib], create_empty_config());
 	assert.ok(find_genfiles_result.ok);
 	assert.ok(find_genfiles_result.value.resolved_input_paths.length);
 });

package/src/lib/invoke.ts

@@ -9,7 +9,7 @@ import {sveltekit_sync_if_obviously_needed} from './sveltekit_helpers.js';
 
 This module invokes the Gro CLI which in turn invokes tasks.
 Tasks are the CLI's primary concept.
-To learn more about them, see `src/lib/docs/task.md`.
+To learn more about them, see `src/docs/task.md`.
 
 When the CLI is invoked it passes the first CLI arg as `task_name` to `invoke_task`,
 and the rest of the args are forwarded to the task's `run` function.

package/src/lib/package.ts

@@ -5,7 +5,7 @@ import type {Src_Json} from './src_json.js';
 
 export const package_json = {
 	name: '@ryanatkn/gro',
-	version: '0.129.6',
+	version: '0.129.8',
 	description: 'task runner and toolkit extending SvelteKit',
 	motto: 'generate, run, optimize',
 	glyph: '🌰',
@@ -272,7 +272,7 @@ export const package_json = {
 
 export const src_json = {
 	name: '@ryanatkn/gro',
-	version: '0.129.6',
+	version: '0.129.8',
 	modules: {
 		'.': {
 			path: 'index.ts',

package/src/lib/src_json.ts

@@ -35,7 +35,7 @@ export const Src_Modules = z.record(Src_Module);
 export type Src_Modules = z.infer<typeof Src_Modules>;
 
 /**
- * @see https://github.com/ryanatkn/gro/blob/main/src/lib/docs/gro_plugin_sveltekit_app.md#well-known-src
+ * @see https://github.com/ryanatkn/gro/blob/main/src/docs/gro_plugin_sveltekit_app.md#well-known-src
  */
 export const Src_Json = z.intersection(
 	z.record(z.unknown()), // TODO is this what we want?

package/dist/docs/README.gen.md.d.ts

@@ -1,6 +0,0 @@
-import { type Gen } from '../gen.js';
-/**
- * Renders a simple index of a possibly nested directory of files.
- */
-export declare const gen: Gen;
-//# sourceMappingURL=README.gen.md.d.ts.map

package/dist/docs/README.gen.md.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"README.gen.md.d.ts","sourceRoot":"","sources":["../../../../src/lib/docs/README.gen.md.ts"],"names":[],"mappings":"AAIA,OAAO,EAAC,KAAK,GAAG,EAAsB,MAAM,WAAW,CAAC;AAQxD;;GAEG;AACH,eAAO,MAAM,GAAG,EAAE,GA+CjB,CAAC"}

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

@@ -1,53 +0,0 @@
-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_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 = ({ 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 = [];
-    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/dist/docs/README.md

@@ -1,20 +0,0 @@
-# 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/dist/docs/build.md

@@ -1,41 +0,0 @@
-# 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.

package/dist/docs/config.md

@@ -1,213 +0,0 @@
-# config
-
-Gro supports SvelteKit apps, Node libraries, and Node servers with minimal abstraction
-with the help of an optional config file that lives at the root `gro.config.ts`.
-If a project does not define a config, Gro imports a default config from
-[`src/lib/gro.config.default.ts`](/src/lib/gro.config.default.ts),
-which looks at your project for the familiar patterns and tries to do the right thing.
-
-> The [default config](/src/lib/gro.config.default.ts)
-> detects three types of projects that can coexist in one repo:
-> SvelteKit frontends,
-> Node libraries with [`@sveltejs/package`](https://kit.svelte.dev/docs/packaging),
-> and Node servers.
-
-See [`src/lib/config.ts`](/src/lib/config.ts) for the config types and implementation.
-
-## examples
-
-[The default config](/src/lib/gro.config.default.ts)
-is used for projects that do not define `gro.config.ts`.
-It's also passed as the first argument to `Create_Gro_Config`.
-
-A simple config that does nothing:
-
-```ts
-// gro.config.ts
-import type {Create_Gro_Config} from '@ryanatkn/gro';
-
-const config: Create_Gro_Config = async (cfg) => {
-	// mutate `cfg` or return a new object
-	return cfg;
-};
-
-export default config;
-```
-
-The default export of a Gro config is `Gro_Config | Create_Gro_Config`:
-
-```ts
-export interface Create_Gro_Config {
-	(base_config: Gro_Config): Raw_Gro_Config | Promise<Raw_Gro_Config>;
-}
-
-// The strict variant that's used internally and exposed to users in tasks and elsewhere.
-export interface Gro_Config {
-	plugins: Create_Config_Plugins;
-	map_package_json: Map_Package_Json | null;
-	task_root_dirs: Path_Id[];
-	search_filters: Path_Filter[];
-}
-
-// The relaxed variant that users can provide. Superset of `Gro_Config`.
-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;
-}
-```
-
-To define a user config that overrides the default plugins:
-
-```ts
-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) => {
-	// `cfg`, which has type `Gro_Config` and 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(),
-	];
-
-	// example extending the default plugins:
-	const get_base_plugins = cfg.plugins;
-	cfg.plugins = async (ctx) => {
-		// replace a base plugin with `import {replace_plugin} from '@ryanatkn/gro';`:
-		const updated_plugins = replace_plugin(
-			await get_base_plugins(ctx),
-			gro_plugin_sveltekit_app({
-				// host_target?: Host_Target;
-				// well_known_package_json?: boolean | Map_Package_Json;
-			}),
-			// 'gro_plugin_sveltekit_app', // optional name if they don't match
-		);
-		return updated_plugins.concat(create_some_custom_plugin());
-	};
-
-	return cfg; // return type is `Raw_Gro_Config`, which is a relaxed superset of `Gro_Config`
-};
-
-export default config;
-```
-
-You can also export a config object and use `create_empty_config` to get the defaults:
-
-```ts
-import {create_empty_config} from '@ryanatkn/gro/config.js';
-
-const config = create_empty_config();
-
-// config.plugins = ...;
-// config.map_package_json = ...;
-// config.task_root_dirs = ...;
-// config.search_filters = ...;
-
-export default config;
-```
-
-See also [Gro's own internal config](/gro.config.ts).
-
-## `plugins`
-
-The `plugins` property is a function that returns an array of `Plugin` instances.
-Read more about plugins and the `Plugin` in
-[plugin.md](plugin.md), [dev.md](dev.md#plugin), and [build.md](build.md#plugin).
-
-```ts
-export interface Create_Config_Plugins<T_Plugin_Context extends Plugin_Context = Plugin_Context> {
-	(
-		ctx: T_Plugin_Context,
-	):
-		| (Plugin<T_Plugin_Context> | null | Array<Plugin<T_Plugin_Context> | null>)
-		| Promise<Plugin<T_Plugin_Context> | null | Array<Plugin<T_Plugin_Context> | null>>;
-}
-```
-
-## `map_package_json`
-
-The Gro config option `map_package_json` hooks into Gro's `package.json` automations.
-The `gro sync` task, which is called during the dev and build tasks among others,
-performs several steps to get a project's state ready,
-including `svelte-kit sync` and `package.json` automations.
-When the `map_package_json` config value is truthy,
-Gro outputs a mapped version of the root `package.json`.
-
-> The `gro check` task integrates with `map_package_json` to ensure everything is synced.
-
-The main purpose of `map_package_json` is to automate
-the `"exports"` property of your root `package.json`.
-The motivation is to streamline package publishing by supplementing
-[`@sveltejs/package`](https://kit.svelte.dev/docs/packaging).
-
-By default `package_json.exports` includes everything from `$lib/`
-except for some ignored files like tests and markdown,
-and you can provide your own `map_package_json` hook to
-mutate the `package_json`, return new data, or return `null` to be a no-op.
-
-Typical usage modifies `package_json.exports` during this step to define the public API.
-
-### using `map_package_json`
-
-```ts
-// gro.config.ts
-const config: Gro_Config = {
-	// ...other config
-
-	// disable mapping `package.json` with automated `exports`:
-	map_package_json: null,
-
-	// mutate anything and return the final config (can be async):
-	map_package_json: (package_json) => {
-		// example setting `exports`:
-		package_json.exports = {
-			'.': {
-				default: './dist/index.js',
-				types: './dist/index.d.ts',
-			},
-			'./example.js': {
-				default: './dist/example.js',
-				types: './dist/example.d.ts',
-			},
-			'./Example.svelte': {
-				svelte: './dist/Example.svelte',
-				types: './dist/Example.svelte.d.ts',
-			},
-		};
-		// example filtering `exports`:
-		package_json.exports = Object.fromEntries(
-			Object.entries(package_json.exports).filter(/* ... */),
-		);
-		return package_json; // returning `null` is a no-op
-	},
-};
-
-export interface Map_Package_Json {
-	(package_json: Package_Json): Package_Json | null | Promise<Package_Json | null>;
-}
-```
-
-## `task_root_dirs`
-
-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_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/deploy.md

@@ -1,32 +0,0 @@
-# deploy
-
-The [`gro deploy`](/src/lib/deploy.task.ts)
-task was originally designed to support static deployments to
-[GitHub pages](https://pages.github.com/),
-but what it actually does is just [build](./build.md) and push to a branch.
-
-Importantly, Gro **destructively force pushes** to the `--target` branch, `deploy` by default.
-This is because Gro treats your deployment
-branch as disposable, able to be deleted or squashed or whatever whenever.
-Internally, `gro deploy` uses [git worktree](https://git-scm.com/docs/git-worktree)
-for tidiness.
-
-```bash
-gro deploy # prepare build/ and commit it to the `deploy` branch, then push to go live
-gro deploy --source my-branch # deploy from `my-branch` instead of the default `main`
-
-# deploy to `custom-deploy-branch` instead of the default `deploy`
-# WARNING! this force pushes to the target branch!
-gro deploy --target custom-deploy-branch
-# the above actually fails because force pushing is destructive, so add `--force` to be extra clear:
-gro deploy --target custom-deploy-branch --force
-# TODO maybe it should be `--dangerous-target-branch` instead of `--target` and `--force`?
-
-gro deploy --dry # prepare build/ but don't commit or push
-gro deploy --clean # if something goes wrong, use this to reset git and gro state
-```
-
-Run `gro deploy --help` or see [`src/lib/deploy.task.ts`](/src/lib/deploy.task.ts) for the details.
-
-For needs more advanced than pushing to a remote branch,
-projects can implement a custom `src/lib/deploy.task.ts`.