@ryanatkn/gro 0.129.6 → 0.129.8

package/src/lib/docs/package_json.md

@@ -1,33 +0,0 @@
-# `package.json`
-
-Gro extends [`package.json`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json)
-with additional functionality.
-
-## `public` packages
-
-Setting `"public": true` in `package.json` opts into
-behavior designed for public open source projects:
-
-- [`gro_plugin_sveltekit_app`](./gro_plugin_sveltekit_app.md)
-  copies `package.json` from your project root to your
-  SvelteKit static directory at `.well-known/package.json` during `vite build`,
-  mapping it with the optional
-  [`well_known_package_json` option](./gro_plugin_sveltekit_app.md#well_known_package_json).
-- `gro_plugin_sveltekit_app` outputs `.well-known/src.json`
-  using the `exports` property of `package.json` during `vite build`,
-  containing additional information about the source modules,
-  mapping it with the optional
-  [`well_known_src_json` option](./gro_plugin_sveltekit_app.md#well_known_src_json).
-- If you define a truthy value for the
-  [`well_known_src_files` option](./gro_plugin_sveltekit_app.md#well_known_src_files),
-  `gro_plugin_sveltekit_app` outputs `.well-known/src/` by
-  copying over `src/` during `vite build`, filtered by `well_known_src_files` if it's a function.
-  This is costly (usually more than doubling the final output size
-  of the code files in bytes, not counting images and such),
-  it slows the build because it copies your entire source tree (sorry to hard drives),
-  and it exposes your source code the same as the built files.
-
-> ⚠️ Setting `"public": true` in `package.json` exposes your `package.json`
-> and `src.json` metadata with your other built files by default!
-> Further opting in with `well_known_src_files` exposes your actual source files.
-> If your built files are public, that means these additional files are also public.

package/src/lib/docs/plugin.md

@@ -1,50 +0,0 @@
-# plugin
-
-During the [`gro dev`](dev.md) and [`gro build`](build.md) tasks,
-Gro uses `Plugin`s to support custom usecases outside of the normal build pipeline.
-
-In this early implementation of plugins in Gro,
-plugins run serially, in the order they are returned from `plugins` in the `gro.config.ts`.
-Each step of Gro's build processes - `gro dev` for development and `gro build` for production -
-runs a method of each plugin, batched together as `setup -> adapt -> teardown`,
-with some behavioral inconsistencies:
-
-- `adapt` only runs during production aka `gro build`
-- `teardown` does not run for `gro dev` in the default `watch` mode,
-  but it does run with `gro dev --no-watch`
-- there should probably be a finalization step that runs `teardown` on uncaught exceptions
-
-The API needs to be improved for more advanced usecases,
-currently it offers little flexibility -
-we'll follow the Vite/SvelteKit APIs probably. (`pre` etc)
-Maybe let you map the array of each method batch. (is that possible with those?)
-
-Gro's builtin plugins:
-
-- [`@ryanatkn/gro_plugin_server`](../gro_plugin_server.ts)
-- [`@ryanatkn/gro_plugin_sveltekit_library`](../gro_plugin_sveltekit_library.ts)
-- [`@ryanatkn/gro_plugin_sveltekit_app`](../gro_plugin_sveltekit_app.ts)
-- [`@ryanatkn/gro_plugin_gen`](../gro_plugin_gen.ts)
-  (currently disabled, will be replaced with an esbuild plugin)
-
-Also see [`config.plugin` in the config docs](config.md#plugin)
-and usage in [the default config](../gro.config.default.ts).
-The default config detects which plugins are included by inspecting the current project.
-
-The implementation is at [`src/lib/plugin.ts`](../plugin.ts) with more details.
-
-```ts
-export interface Plugin<T_Plugin_Context extends Plugin_Context = Plugin_Context> {
-	name: string;
-	setup?: (ctx: T_Plugin_Context) => void | Promise<void>;
-	adapt?: (ctx: T_Plugin_Context) => void | Promise<void>;
-	teardown?: (ctx: T_Plugin_Context) => void | Promise<void>;
-}
-
-export interface Plugin_Context<T_Args = object> extends Task_Context<T_Args> {
-	dev: boolean;
-	watch: boolean;
-}
-```
-
-The `adapt` step only runs for production during `gro build`, taking after SvelteKit adapters.

package/src/lib/docs/publish.md

@@ -1,137 +0,0 @@
-# publish
-
-Here's how to publish a new version of a repo with Gro, including for Gro itself.
-
-## svelte-package
-
-Gro uses SvelteKit's [`@sveltejs/package`](https://kit.svelte.dev/docs/packaging)
-with the task `gro publish` to publish packages to npm.
-Gro's default config enables [`@ryanatkn/gro/gro_plugin_sveltekit_library.js`](../gro_plugin_sveltekit_library.ts)
-if it detects `@sveltejs/package` installed as a dependency in the package.json.
-
-```bash
-# enable `gro publish` to publish to npm:
-npm i -D @sveltejs/package # enables `@ryanatkn/gro/gro_plugin_sveltekit_library.js`
-gro sync # updates package.json "exports"
-git commit -am "..."
-# `gro publish` calls `svelte-package`
-```
-
-## login to npm
-
-```bash
-npm whoami # check if you're logged in
-
-# not logged in?
-npm login # and follow the instructions
-```
-
-> more about [`npm login`](https://docs.npmjs.com/v6/commands/npm-adduser)
-
-## using changesets
-
-The [`gro publish` task](https://github.com/ryanatkn/gro/blob/main/src/lib/publish.task.ts)
-integrates with [Changesets](https://github.com/changesets/changesets)
-to publish packages to [npm](https://npmjs.com/). Internally the task calls both
-[`changeset version`](https://github.com/changesets/changesets/blob/main/packages/README.md#version)
-and
-[`changeset publish`](https://github.com/changesets/changesets/blob/main/packages/README.md#publish).
-
-Gro does not include Changesets as a dependency.
-Install it globally or local to your repo
-(I prefer global, it's not a light dependency):
-
-```bash
-npm i -g @changesets/cli # install globally
-npm i -D @changesets/cli # or install local to your repo
-```
-
-To [init Changesets](https://github.com/changesets/changesets/blob/main/packages/README.md#init)
-in a repo or [add](https://github.com/changesets/changesets/blob/main/packages/README.md#add)
-a changeset to an already-inited repo, use `gro changeset`:
-
-```bash
-gro changeset # inits or adds a changeset
-gro changeset --help # view the args docs
-
-# `gro changeset` is equivalent to:
-changeset init # if needed -- prefix with `npx ` if installed only locally
-changeset
-git add .changeset/$FILE
-# TODO include a `git commit` flag or default behavior, maybe `gro changeset "message"`
-```
-
-After initing, optionally configure and install a custom changelog package
-in the `"changelog"` property of the newly created `.changeset/config.json`:
-
-```diff
-# .changeset/config.json
-- "changelog": "@changesets/changelog",
-+ "changelog": "@changesets/changelog-git",
-```
-
-```bash
-npm i -D @changesets/changelog-git  # a minimal package that requires no GitHub auth
-```
-
-Gro inits `"access"` based on the package.json `"private": true` value.
-To manually configure the `access` property:
-
-```diff
-# .changeset/config.json
-- "access": "public",
-+ "access": "restricted",
-```
-
-See [the Changesets docs](https://github.com/changesets/changesets) for more.
-
-## GitHub API setup
-
-Gro currently expects repos to be on GitHub to generate changelogs with Changesets.
-(sorry, maybe in the future we'll support other forges)
-
-Gro modifies the barebones changelog generated by `@changesets/changelog-git`,
-doing things like linkifying commit hashes or linking to PRs if they exist.
-The difference between Gro's version and `@changesets/changelog-github` is that Gro
-doesn't require a token for authorization for public repos,
-and Gro makes some different choices for usability.
-
-Gro calls the GitHub API using the environment variable `GITHUB_TOKEN_SECRET` for authorization,
-which is a [GitHub token](https://github.com/settings/tokens)
-(with "public access" for public repos, no options selected)
-in either `process.env`, a project-local `.env`, or the parent directory at `../.env`
-(currently optional to read public repos, but it's recommended regardless,
-and you'll need to select options to support private repos).
-
-You'll get a warning if the token is unavailable, but for light usage you won't hit rate limts.
-
-## `gro publish`
-
-The publish task builds the project, bumps the version, publishes to npm,
-commits the changes, and then pushes the commit and tag.
-
-Ensure `"dist"` is in the `"files"` property of `package.json`:
-
-```json
-"files": [
-  "dist"
-],
-```
-
-Then publish:
-
-```bash
-gro publish
-gro publish --help # view the options
-gro publish -- svelte-package -w # forward options
-```
-
-See [the SvelteKit packaging docs](https://kit.svelte.dev/docs/packaging) for more.
-
-If `changeset publish` fails during `gro publish`,
-the task exits without pushing anything to the remote origin.
-It does however create the version commit and tag.
-A common failure is not being logged into npm. (see the instructions above)
-If the builds are correct but `changeset publish` failed,
-and you don't want to undo the version commit and tag,
-you can continue manually with `changeset publish` or `npm publish`.

package/src/lib/docs/task.md

@@ -1,391 +0,0 @@
-# task
-
-> task runner for
-> [Gro](https://github.com/ryanatkn/gro)
-
-## contents
-
-- [what](#what)
-- [usage](#usage)
-- [why?](#why)
-
-## what
-
-A Gro `Task` is just an object with a `run` function and some optional metadata.
-Gro prefers conventions and code over configuration,
-and its task runner leverages the filesystem as the API
-and defers composition to the user in regular TypeScript modules.
-
-> Tasks are a special Gro construct.
-> If you want to simply execute regular TypeScript files,
-> use the `gro run` task, which works like the normal `node` CLI
-> but uses the Gro loader to support `.ts`.
-
-- tasks are defined by naming files with the `.task.ts` and `.task.js` suffixes
-- tasks can be run from the CLI via a name (`gro foo`),
-  which uses Gro's task resolution (see more below),
-  or via paths that are absolute (`gro /path/to/foo`) or explicitly relative (`gro ./foo`)
-- 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_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,
-  so composing tasks is explicit in your code, just like any other module
-  (but there's also the helper `invoke_task`, see more below)
-- the task object's `run` function has access to CLI args
-- tasks optionally use [zod](https://github.com/colinhacks/zod) schemas
-  for `args` types, runtime parsing with helpful validation errors,
-  and generated help docs (`gro foo --help`), with DRY co-located definitions
-- it's easy to call into or override any of Gro's builtin tasks,
-  like [`gro test`](/src/lib/test.task.ts) and [`gro gen`](/src/lib/gen.task.ts) -
-  your own versions with the same name take precedence, and you can invoke the base
-  tasks using the `gro/` prefix, e.g. `gro gro/test`
-  (tasks are also copy-paste friendly! just update the imports)
-- it's fast because it imports only the modules imported by your invoked tasks, not every task's
-
-The task runner's purpose is to provide an ergonomic interface
-between the CLI, build tools, and app code.
-As a developer, it's nice to be able to reuse TypeScript modules in every context.
-
-## usage
-
-### show all available tasks
-
-```bash
-# This looks through `src/lib` in both the current working directory and Gro's source
-# for all files matching `*.task.ts|js` and logs them out with their args docs.
-$ gro
-```
-
-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_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
-> but it seems like the right design.
-
-### show tasks in a directory
-
-```bash
-# Logs all `*.task.ts|js` files in `src/lib/some/dir` and `gro/src/lib/some/dir`.
-# If no tasks are found, it displays an error.
-$ gro some/dir
-```
-
-> To learn more about the Gro CLI path conventions,
-> see [the `input_paths` comments](../input_path.ts)
-
-### run a task
-
-```bash
-# This runs `src/lib/some/file.task.ts`,
-# or if it doesn't exist, `gro/src/lib/some/file.task.ts`.
-# If neither exists, it displays an error.
-$ gro some/file arg1 arg2 --arg3 example
-
-# This runs `gro/src/lib/some/file.task.ts` directly
-# without checking the current working directory,
-# and displays an error if it doesn't exist.
-$ gro gro/some/file
-```
-
-### define a task
-
-```ts
-// src/lib/some/file.task.ts
-import type {Task} from '@ryanatkn/gro';
-
-export const task: Task = {
-	run: async ({log, args}) => {
-		log.info('CLI args', args); // => {_: ['arg1', 'arg2'], arg3: 'example'}
-		await whatever();
-	},
-};
-```
-
-The minimum:
-
-```ts
-// src/lib/some/minimal.task.ts
-export const task = {
-	run: () => console.log('a minimal example'),
-};
-```
-
-Minimum with [`Args`](#task-args):
-
-```ts
-// src/lib/some/withargs.task.ts
-import type {Task} from '@ryanatkn/gro';
-import {z} from 'zod';
-
-export const Args = z
-	.object({
-		arg: z.number({description: 'example number arg'}).default(2),
-	})
-	.strict();
-export type Args = z.infer<typeof Args>;
-
-export const task: Task = {
-	Args,
-	run: async ({args}) => {
-		args.arg; // `number` that defaults to `2`
-	},
-};
-```
-
-### type `Task`
-
-```ts
-import type {Task} from '@ryanatkn/gro';
-
-export interface Task<
-	T_Args = Args, // same as `z.infer<typeof Args>`
-	T_Args_Schema extends z.ZodType = z.ZodType,
-	T_Return = unknown,
-> {
-	run: (ctx: Task_Context<T_Args>) => Promise<T_Return>;
-	summary?: string;
-	Args?: T_Args_Schema;
-}
-```
-
-### type `Task_Context`
-
-```ts
-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>;
-}
-```
-
-### run a task inside another task with `invoke_task`
-
-Because Gro tasks are just functions,
-you can directly import them from within other tasks and run them.
-However, we recommend using the `invoke_task` helper
-for its ergonomics and automatic logging and diagnostics.
-
-The `invoke_task` helper uses Gro's task resolution rules
-to allow user code to override builtin tasks.
-For example, Gro's `check.task.ts` calls `invoke_task('test')`
-so that it calls your `src/lib/test.task.ts` if it exists
-and falls back to `gro/src/lib/test.task.ts` if not.
-
-It's less important to use `invoke_task` over explicit imports in user code
-because you don't need to rely on the task override rules to get desired behavior,
-but the logging and diagnostics it provides are nice to have.
-
-```bash
-gro some/file
-```
-
-```ts
-// src/lib/some/file.task.ts
-import type {Task} from '@ryanatkn/gro';
-
-export const task: Task = {
-	run: async ({args, invoke_task}) => {
-		// runs `src/lib/some/file.task.ts`, automatically forwarding `args`
-		await invoke_task('some/file');
-		// as documented above, the following is similar but lacks nice features:
-		// await (await import('./some/file.task.js')).run(ctx);
-
-		// runs `src/lib/other/file.task.ts` and falls back to `gro/src/other/file.task.ts`,
-		// forwarding both custom args and a different event emitter (warning: spaghetti)
-		await invoke_task(
-			'other/file',
-			{...args, optionally: 'extended'},
-			optionalEventEmitterForSubtree,
-			optionalDevFlagForSubtree,
-			optionalFsForSubtree,
-		);
-
-		// runs `gro/src/lib/other/file.task.ts` directly, bypassing any local version
-		await invoke_task('gro/other/file');
-	},
-};
-```
-
-### hook into one of [Gro's builtin tasks](../docs/tasks.md)
-
-```bash
-# This normally loads Gro's version of the test task at `gro/src/lib/test.task.ts`,
-# but projects can define `src/lib/test.task.ts` to extend or replace it.
-$ gro test
-```
-
-```ts
-// src/lib/test.task.ts
-import type {Task} from '@ryanatkn/gro';
-
-export const task: Task = {
-	run: async ({args, invoke_task}) => {
-		await doSomethingFirst();
-		// As discussed in the `invoke_task` section above,
-		// it's possible to `import {task as groBuiltinTestTask} from '@ryanatkn/gro/test.task.js'`
-		// and then call `groBuiltinTestTask.run` directly,
-		// but that loses some important benefits.
-		// Still, the task is available to import if you want it for any reason!
-		await invoke_task('gro/test', {...args, optionally: 'extended'}, newEventEmitterForSubtree);
-		await emailEveryoneWithTestResults();
-	},
-};
-```
-
-Note that when hooking into [Gro's builtin tasks](../docs/tasks.md),
-like `test.task.ts` above, you don't have to call its version.
-You can copy/paste an existing task and customize it,
-rewrite a task from scratch, compose them together, or whatever is needed for each project.
-
-### task `Args`
-
-The **`Args` property** of each `Task` (not the task context **`args` param** described above!)
-is an optional [zod](https://github.com/colinhacks/zod) schema.
-Using zod has some benefits:
-
-- automatically print helpful text on the CLI with `gro` and `gro taskname --help`
-- automated args parsing/validation using the schema with initialized defaults
-- type safety using args in tasks
-- concise source of truth
-
-```ts
-// src/lib/dosomething.task.ts
-import type {Task} from '@ryanatkn/gro';
-import type {z} from 'zod';
-
-export const Args = z
-	.object({
-		_: z.array(z.string(), {description: 'rest args'}).default([]),
-		yepyep: z.string({description: 'helpful info'}).default('ya'),
-		okcool: z.number({description: 'that prints to the CLI'}).default(1234),
-		maybee: z.boolean({description: 'and optional args work too'}),
-	})
-	.strict();
-export type Args = z.infer<typeof Args>;
-
-export const task: Task<Args> = {
-	Args,
-	run: async ({args}) => {
-		args._; // string[]
-		args.yepyep; // string
-		args.okcool; // number
-		args.maybee; // boolean | undefined
-	},
-};
-```
-
-Running `gro dosomething --help` prints the schema information in a friendly format.
-
-### task args forwarding
-
-Some builtin Gro tasks call external commands like
-[`svelte-kit`](https://github.com/sveltejs/kit),
-[`vite`](https://github.com/vitejs/vite),
-[`uvu`](https://github.com/lukeed/uvu),
-[`tsc`](https://github.com/microsoft/typescript),
-and [`prettier`](https://github.com/prettier/prettier).
-Gro supports generic agnostic args forwarding to these tasks via the `--` pattern:
-for example, to forward args to `svelte-kit` and `uvu`, no matter which task invokes them,
-use `gro taskname --taskname-arg -- uvu --arg1 neat --arg2 22 -- svelte-kit --arg3`.
-
-Any number of sections separated by `--` may be defined, and the first arg
-that appears after each `--` is assumed to be the CLI command.
-If `gro taskname` or its invoked tasks don't call `uvu` or `svelte-kit`,
-the `--` args will be ignored.
-
-There's one special case for task args forwarding: running Gro tasks.
-If `gro` is the command following a `--`, e.g. the second `gro` of
-`gro taskname -- gro taskname2 --a --b`,
-then `--a` and `--b` will be forwarded to `taskname2`.
-Forwarded args to Gro tasks override direct args, including args to `invoke_task`,
-so `gro taskname --a 1 -- gro taskname --a 2` will invoke `taskname` with `{a: 2}`.
-
-The `invoke_task` helper in the task context forwards the CLI args for the specified task.
-CLI args take precedence over args passed directly to `invoke_task`.
-This may not always be the desired behavior, but it gives the user more control,
-because you can't change args in code you don't control.
-
-### throwing errors
-
-If a task encounters an error, normally it should throw rather than exiting the process.
-This defers control to the caller, like your own parent tasks.
-
-Often, errors that tasks encounter do not need a stack trace,
-and we don't want the added noise to be logged.
-To suppress logging the stack trace for an error,
-throw a `Task_Error`.
-
-```ts
-import {Task, Task_Error} from '@ryanatkn/gro';
-
-export const task: Task = {
-	run: async () => {
-		if (someErrorCondition) {
-			throw new Task_Error('We hit a known error - ignore the stack trace!');
-		}
-	},
-};
-```
-
-## why?
-
-Gro usage on the command line (`gro <task_name_or_directory> [...flags]`)
-looks a lot like using `node`.
-What makes Gro different?
-
-- The `*.task.ts` file name convention signals to Gro that your application
-  contains task modules that conform to some interface.
-  This allows them to be discoverable by convention,
-  so running `gro` displays them all without any config, and it puts generic handles on them,
-  enabling various verbs (e.g. `run`) and
-  structured metadata (e.g. `summary` and args schemas for docs and validation).
-- Tasks aren't just a script on the filesystem, they can be composed and inspected in code.
-  Task modules do not have any side effects when imported,
-  while Node scripts just execute when imported -
-  their primary purpose is to cause side effects, and they're limited to the filesystem API.
-  This is useful in many cases - for example `gro taskname --help`
-  inspects the args schema and other metadata to print help to the console,
-  and `gro` prints the `summary` property of each task it discovers.
-  There's lots more to explore here, like task composition
-  and improved DX with new capabilities.
-- Tasks support CLI args that are validated and typesafe
-  via colocated Zod schemas with minimal boilerplate.
-- Tasks are forwarded CLI args when called via `invoke_task` in other tasks,
-  so running `gro foo -- gro bar --a b` passes `{a: 'b'}` automatically to the `bar` task.
-- Module resolution differs and leverages discoverability:
-  - When a task name is given to Gro,
-    it first searches `src/lib/` in the current working directory and
-    falls back to searching the Gro directory.
-    This allows your code and CLI commands to compose Gro's builtin tasks
-    or override them without changing how you invoke them.
-    Gro reserves no special behavior for its own commands -
-    `gro test`, `gro gen`, and all the rest are just tasks that all follow the same rules.
-    (see its task at [`src/lib/test.task.ts`](/src/lib/test.task.ts)).
-  - When a directory is given to Gro,
-    it prints all of the tasks found inside it,
-    both relative to the current working directory and Gro's directory.
-    So when you run `gro` by itself,
-    it prints all tasks available both in your project and Gro.
-  - The trailing `.task.ts` in the file path provided to `gro` is optional,
-    so for example, `gro foo/bar` is the same as `gro foo/bar.task.ts`, a nice convenience.
-
-## :turtle:<sub>:turtle:</sub><sub><sub>:turtle:</sub></sub>
-
-Gro's task runner has many inspirations:
-
-- [mgutz/task](https://github.com/mgutz/task)
-- [Gulp](https://github.com/gulpjs/gulp)
-- [@mgutz](https://github.com/mgutz)' [Projmate](https://github.com/projmate/projmate-core)
-- [Grunt](https://github.com/gruntjs/grunt)
-- [npm scripts](https://docs.npmjs.com/v8/using-npm/scripts)