@ryanatkn/gro 0.112.0

package/dist/config.js

@@ -0,0 +1,42 @@
+import { join } from 'node:path';
+import { CONFIG_PATH, paths } from './paths.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,
+});
+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)));
+    }
+    return package_json;
+};
+export const DEFAULT_EXPORTS_EXCLUDER = /(\.md|\.(test|ignore)\.|\/(test|fixtures|ignore)\/)/u;
+export const load_config = async (dir = paths.root) => {
+    const default_config = await create_default_config(create_empty_config());
+    const config_path = join(dir, CONFIG_PATH);
+    let config;
+    if (await exists(config_path)) {
+        const config_module = await import(config_path);
+        validate_config_module(config_module, config_path);
+        config =
+            typeof config_module.default === 'function'
+                ? await config_module.default(default_config)
+                : config_module.default;
+    }
+    else {
+        config = default_config;
+    }
+    return config;
+};
+export const validate_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/dist/config.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/config.test.js

@@ -0,0 +1,8 @@
+import { test } from 'uvu';
+import * as assert from 'uvu/assert';
+import { load_config } from './config.js';
+test('load_config', async () => {
+    const config = await load_config();
+    assert.ok(config);
+});
+test.run();

package/dist/deploy.task.d.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { type Task } from './task.js';
+export declare const Args: z.ZodObject<{
+    source: z.ZodDefault<z.ZodString>;
+    target: z.ZodDefault<z.ZodString>;
+    origin: z.ZodDefault<z.ZodString>;
+    deploy_dir: z.ZodDefault<z.ZodString>;
+    build_dir: z.ZodDefault<z.ZodString>;
+    dry: z.ZodDefault<z.ZodBoolean>;
+    force: z.ZodDefault<z.ZodBoolean>;
+    dangerous: z.ZodDefault<z.ZodBoolean>;
+    reset: z.ZodDefault<z.ZodBoolean>;
+    install: z.ZodDefault<z.ZodBoolean>;
+    'no-install': z.ZodDefault<z.ZodBoolean>;
+    build: z.ZodDefault<z.ZodBoolean>;
+    'no-build': z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    build: boolean;
+    target: string;
+    install: boolean;
+    origin: string;
+    reset: boolean;
+    'no-install': boolean;
+    source: string;
+    deploy_dir: string;
+    build_dir: string;
+    dry: boolean;
+    force: boolean;
+    dangerous: boolean;
+    'no-build': boolean;
+}, {
+    source?: string | undefined;
+    target?: string | undefined;
+    origin?: string | undefined;
+    deploy_dir?: string | undefined;
+    build_dir?: string | undefined;
+    dry?: boolean | undefined;
+    force?: boolean | undefined;
+    dangerous?: boolean | undefined;
+    reset?: boolean | undefined;
+    install?: boolean | undefined;
+    'no-install'?: boolean | undefined;
+    build?: boolean | undefined;
+    'no-build'?: boolean | undefined;
+}>;
+export type Args = z.infer<typeof Args>;
+export declare const task: Task<Args>;

package/dist/deploy.task.js

@@ -0,0 +1,198 @@
+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 { join, resolve } from 'node:path';
+import { Task_Error } from './task.js';
+import { GIT_DIRNAME, GRO_DIRNAME, print_path, SVELTEKIT_BUILD_DIRNAME } from './paths.js';
+import { empty_dir, exists } 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
+// TODO use `to_forwarded_args` and the `gro deploy -- gro build --no-install` pattern to remove the `install`/`no-install` args (also needs testing, maybe a custom override for `gro ` prefixes)
+// terminal command for testing:
+// npm run build && rm -rf .gro && clear && gro deploy --source no-git-workspace --no-build --dry
+// TODO customize
+const cwd = process.cwd();
+const INITIAL_FILE_PATH = '.gitkeep';
+const INITIAL_FILE_CONTENTS = '';
+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),
+    install: z.boolean({ description: 'dual of no-install' }).default(true),
+    'no-install': z
+        .boolean({ description: 'opt out of npm installing before building' })
+        .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 const task = {
+    summary: 'deploy to a branch',
+    Args,
+    run: async ({ args, log, invoke_task }) => {
+        const { source, target, origin, build_dir, deploy_dir, dry, force, dangerous, reset, install, 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 (await exists(resolved_deploy_dir)) {
+                if (target !== (await git_current_branch_name(target_spawn_options))) {
+                    // We're in a bad state because the target branch has changed,
+                    // so delete the directory and continue as if it wasn't there.
+                    await rm(resolved_deploy_dir, { recursive: true });
+                }
+                else {
+                    await spawn('git', ['reset', '--hard'], target_spawn_options); // in case it's dirty
+                    await git_pull(origin, target, target_spawn_options);
+                    if (await git_check_clean_workspace(target_spawn_options)) {
+                        // We're in a bad state because the local branch lost continuity with the remote,
+                        // so delete the directory and continue as if it wasn't there.
+                        await rm(resolved_deploy_dir, { recursive: true });
+                    }
+                }
+            }
+            // Second, initialize the deploy dir if needed.
+            // It may not exist, or it may have been deleted after failing to sync above.
+            if (!(await exists(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, cwd, resolved_deploy_dir);
+                // Clean up if we created the target branch in the cwd
+                if (!local_deploy_branch_exists) {
+                    await git_delete_local_branch(target);
+                }
+            }
+            // Local target branch is now synced with remote, but do we need to reset?
+            if (reset) {
+                await git_reset_branch_to_first_commit(origin, target, target_spawn_options);
+            }
+        }
+        else {
+            // Remote target branch does not exist, so start from scratch
+            // Delete the deploy dir and recreate it
+            if (await exists(resolved_deploy_dir)) {
+                await rm(resolved_deploy_dir, { recursive: true });
+                await mkdir(resolved_deploy_dir, { recursive: true });
+            }
+            // Delete the target branch locally in the cwd if it exists
+            if (await git_local_branch_exists(target)) {
+                await git_delete_local_branch(target);
+            }
+            // Create the target branch locally and remotely.
+            // This is more complex to avoid churning the cwd.
+            await git_clone_locally(origin, source, cwd, resolved_deploy_dir);
+            await spawn(`git checkout --orphan ${target} && ` +
+                // TODO there's definitely a better way to do this
+                `git rm -rf . && ` +
+                `echo "${INITIAL_FILE_CONTENTS}" >> ${INITIAL_FILE_PATH} && ` +
+                `git add ${INITIAL_FILE_PATH} && ` +
+                `git commit -m "init"`, [], 
+            // Use `shell: true` because the above is unwieldy with standard command construction
+            { ...target_spawn_options, shell: true });
+            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', { install });
+            }
+            if (!(await exists(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((await readdir(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/dist/dev.task.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import type { Task } from './task.js';
+import { type Plugin_Context } from './plugin.js';
+export declare const Args: z.ZodObject<{
+    watch: z.ZodDefault<z.ZodBoolean>;
+    'no-watch': z.ZodDefault<z.ZodBoolean>;
+    sync: z.ZodDefault<z.ZodBoolean>;
+    'no-sync': z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    watch: boolean;
+    sync: boolean;
+    'no-watch': boolean;
+    'no-sync': boolean;
+}, {
+    watch?: boolean | undefined;
+    'no-watch'?: boolean | undefined;
+    sync?: boolean | undefined;
+    'no-sync'?: boolean | undefined;
+}>;
+export type Args = z.infer<typeof Args>;
+export type DevTask_Context = Plugin_Context<Args>;
+export declare const task: Task<Args>;

package/dist/dev.task.js

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+import { Plugins } 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 const task = {
+    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/dist/docs/README.gen.md.d.ts

@@ -0,0 +1,5 @@
+import { type Gen } from '../gen.js';
+/**
+ * Renders a simple index of a possibly nested directory of files.
+ */
+export declare const gen: Gen;

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

@@ -0,0 +1,53 @@
+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 { 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 = async ({ 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 docFiles = await search_fs(origin_dir);
+    const docPaths = [];
+    for (const path of docFiles.keys()) {
+        if (path === output_file_name || !path.endsWith('.md')) {
+            continue;
+        }
+        docPaths.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_source_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}
+
+${docPaths.reduce((docList, doc) => docList + `- [${basename(doc, '.md')}](${doc})\n`, '')}
+${breadcrumbs}
+
+> <sub>generated by [${origin_base}](${origin_base})</sub>
+`;
+};

package/dist/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_frontend](gro_plugin_sveltekit_frontend.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

@@ -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.

package/dist/docs/config.md

@@ -0,0 +1,162 @@
+# 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): Gro_Config | Promise<Gro_Config>;
+}
+
+export interface Gro_Config {
+	plugins: Create_Config_Plugins;
+	map_package_json: Map_Package_Json | 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) => {
+	// 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;
+};
+
+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>;
+}
+```

package/dist/docs/deploy.md

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