@ryanatkn/gro 0.112.0

package/dist/docs/dev.md

@@ -0,0 +1,40 @@
+# dev
+
+Gro is designed to extend [SvelteKit](https://github.com/sveltejs/kit)
+with helpful tools. It supports:
+
+- frontends with SvelteKit and [Vite](https://github.com/vitejs/vite)
+- Node libraries
+- Node servers
+
+## usage
+
+```bash
+gro dev
+gro dev --no-watch # outputs dev artifacts and exits without watch mode
+```
+
+To configure a project, see [the config docs](config.md).
+
+## plugin
+
+`Plugin`s are objects that customize the behavior of `gro build` and `gro dev`.
+See [plugin.md](plugin.md) to learn more.
+
+## todo
+
+- [x] basics
+- [ ] add API using esbuild to optionally bundle specific pieces to speed up development
+- [ ] livereload CSS (and fix pop-in during dev)
+- [ ] HMR
+- [ ] probably support Rollup plugins in development, but how?
+- [ ] improve loading speed with `cache-control: immutable` and
+      [import maps](https://github.com/WICG/import-maps/)
+      (on my machine Firefox is much slower than Chrome
+      handling a module import waterfall, locally, and http2 didn't help)
+
+<p align="center">
+  <a href="https://github.com/ryanatkn/gro">
+    <img src="static/favicon.png" width="192" height="192">
+  </a>
+</p>

package/dist/docs/gen.md

@@ -0,0 +1,241 @@
+# gen
+
+> automated codegen by convention for
+> [Gro](https://github.com/ryanatkn/gro)
+
+## motivation
+
+The [`gro gen` task](/src/lib/gen.task.ts) helps us enhance our projects
+with convention-based code/data/file generation (codegen) techniques.
+
+Why? Codegen can produce cool results and unhalting pain.
+Used well, codegen can improve performance, flexibility, consistency, and development speed.
+As developers, automating our work is a natural thing to do,
+and whether or not it's a wise thing to do,
+`gro gen` can bring automation deeper into our code authoring workflows.
+
+By convention, `gro gen` looks through `src/`
+for any TypeScript files with `.gen.` in the file name,
+and it outputs a file stripped of `.gen.` to the same directory.
+The `*.gen.*` origin files export a `gen` function
+More flexibility is available when needed
+including multiple custom output files.
+
+`gen` is implemented as [a task](/src/lib/gen.task.ts)
+and [a plugin](/src/lib/gro_plugin_gen.ts),
+and runs only during development, not for production builds.
+
+Normally you'll want to commit generated files to git,
+but you can always gitignore a specific pattern like `*.ignore.*`
+and name the output files accordingly.
+
+Integrating codegen into our development process
+is a simple idea with vast potential.
+It lets us have a single source of truth for data
+without compromising any of our code's runtime characteristics.
+We can generate documentation, types,
+`index.ts` files exporting directories,
+data for a UI,
+validators, tests, fakes,
+and more by introspecting our data at buildtime,
+which speeds up development
+The goal is to leverage automation to increase the power we wield over our code
+with a straightforward developer experience.
+Ergonomics are key to unlocking codegen's full potential.
+
+**Be aware** — this is a sharp tool! It should be used sparingly, only when it's a clear win.
+It adds a layer of indirection between the code you write and run,
+and it's possible to tie yourself into knots with dependencies.
+Also, you could introduce security vulnerabilities
+if you fail to escape certain inputs,
+There's no support for sourcemaps yet, and I have no plans for them.
+(I would accept contributions, but I think it's a hard problem to do well,
+and I don't know what the payoffs would be)
+
+Inspirations include Lisp macros, the
+[Svelte](https://github.com/sveltejs/svelte) compiler,
+and [Zig](https://github.com/ziglang/zig)'s comptime.
+(but `gro gen` is far more primitive)
+
+## usage
+
+The `gro gen` task looks for any files with `.gen.`
+in the file name and tries to call an exported `gen`
+function to generate one or more output files,
+and then it writes the results to the filesystem.
+
+```bash
+gro gen # runs codegen for all *.gen.* files in src/
+gro gen --check # exits with error code 1 if anything is new or different; no-op to the fs
+```
+
+> in the following examples,
+> but it makes for a better DX
+
+### generate arbitrary TypeScript
+
+Given `src/script.gen.ts`:
+
+```ts
+import type {Gen} from '@ryanatkn/gro';
+
+export const gen: Gen = () => {
+	const message = 'generated';
+	return `console.log('${message} a ${typeof message}')`;
+};
+```
+
+Outputs `src/script.ts`:
+
+```ts
+console.log('generated a string');
+```
+
+### generate other filetypes
+
+Files with any extension can be generated without configuration.
+If the origin file name ends with the pattern `.gen.*.ts`,
+the default output file name is stripped of its trailing `.ts`.
+
+Given `src/markup.gen.html.ts`:
+
+```ts
+import type {Gen} from '@ryanatkn/gro';
+
+export const gen: Gen = () => {
+	const body = 'hi';
+	return `
+		<!DOCTYPE html>
+		<html>
+			<body>
+				${body}
+			</body>
+		</html>
+	`;
+};
+```
+
+Outputs `src/markup.html`:
+
+```html
+<!doctype html>
+<html>
+	<body>
+		hi
+	</body>
+</html>
+```
+
+### generate a custom file name or write to a different directory
+
+The `gen` function can return an object with custom configuration.
+
+Given `src/somewhere/originalName.gen.ts`:
+
+```ts
+import type {Gen} from '@ryanatkn/gro';
+
+export const gen: Gen = () => {
+	const message = 'output path can be relative and name can be anything';
+	return {
+		content: `console.log('${message}')`,
+		filename: '../elsewhere/otherName.ts',
+		format: optional_boolean_that_defaults_to_true,
+	};
+};
+```
+
+Outputs `src/elsewhere/otherName.ts`:
+
+```ts
+console.log('output path can be relative and name can be anything');
+```
+
+### generate multiple custom files
+
+The `gen` function can also return an array of files.
+
+Given `src/thing.gen.ts`:
+
+```ts
+import type {Gen} from '@ryanatkn/gro';
+
+export const gen: Gen = () => {
+	const fieldValue = 1;
+	return [
+		{
+			content: `
+				import {Thing} from './index';
+				export const isThing = (t: any): t is Thing => t?.field === ${fieldValue};
+			`,
+		},
+		{
+			content: `export interface Thing { field: ${typeof fieldValue} }`,
+			filename: 'types.ts',
+		},
+		{
+			content: `{"field": ${fieldValue}}`,
+			filename: 'data/thing.json',
+		},
+	];
+};
+```
+
+Outputs `src/thing.ts`:
+
+```ts
+import type {Thing} from './index.js';
+export const isThing = (t: any): t is Thing => t?.field === 1;
+```
+
+and `src/types.ts`:
+
+```ts
+export interface Thing {
+	field: number;
+}
+```
+
+and `src/data/thing.json`:
+
+```json
+{
+	"field": 1
+}
+```
+
+It's often helpful to check if any generated files are new or have changed.
+We don't want to forget to regenerate files before committing or publishing!
+The `check` CLI argument can be passed to perform this check
+instead of writing the generated files to disk.
+
+```bash
+gro gen --check # exits with error code 1 if anything is new or different; no-op to the fs
+```
+
+or in code:
+
+```ts
+import type {Task} from '@ryanatkn/gro';
+
+export const task: Task = {
+	run: async ({args, invoke_task}) => {
+		// this throws a `Task_Error` if anything is new or different
+		await invoke_task('gen', {...args, check: true});
+	},
+};
+```
+
+Gro uses this in [`check.task.ts`](/src/lib/check.task.ts)
+which is called during `gro publish`, and it's recommended in CI.
+(see [Gro's example `check.yml`](/.github/workflows/check.yml))
+
+## todo
+
+- [x] basic functionality
+- [x] format output with Prettier
+- [x] [watch mode and build integration](https://github.com/ryanatkn/gro/pull/283),
+      opt out with `watch: false` for expensive gen use cases
+- [ ] change the exported `gen` function to an object with a `summary` and other properties like `watch`
+- [ ] support generating non-text files
+- [ ] think about how to handle gen file dependency graphs (generated files as inputs to gen files)

package/dist/docs/gro_plugin_sveltekit_frontend.md

@@ -0,0 +1,97 @@
+# SvelteKit frontend plugin
+
+Gro's [SvelteKit frontend plugin](/src/lib/gro_plugin_sveltekit_app.ts)
+calls `vite dev` and `vite build` with some additional behaviors.
+
+```ts
+// gro.config.ts
+import type {Gro_ConfigCreator} from '@ryanatkn/gro';
+import {gro_plugin_sveltekit_app} from '@ryanatkn/gro/gro_plugin_sveltekit_app.js';
+
+const config: Gro_ConfigCreator = async (cfg) => {
+	cfg.plugins = async () => [
+		// this is included in the default config for SvelteKit projects:
+		gro_plugin_sveltekit_app({
+			// host_target?: Host_Target;
+			// well_known_package_json?: boolean | Map_Package_Json;
+			// well_known_src_json?: boolean | Map_Src_Json;
+			// filter_well_known_src?: (source: string, destination: string) => boolean | Promise<boolean>;
+		}),
+	];
+	return cfg;
+};
+
+export default config;
+
+// src/lib/gro_plugin_sveltekit_app.ts
+export type Host_Target = 'github_pages' | 'static' | 'node';
+
+export interface Map_Package_Json {
+	(package_json: Package_Json): Package_Json | null | Promise<Package_Json | null>;
+}
+```
+
+## `host_target`
+
+When `host_target` is the default value `'github_pages'`,
+a `.nojekyll` file is included in the build to tell GitHub Pages not to process it with Jekyll.
+
+## `well_known_package_json`
+
+If your root `package.json` has `"public": true`
+(telling Gro it's a [public package](./package_json.md#public-packages)),
+by default Gro copies `.well-known/package.json` to `static/` during `vite build`,
+so it's included in the SvelteKit build output.
+The motivation is to provide conventional package metadata to web users and tools.
+(more details below)
+
+> ⚠️ Outputting `.well-known/package.json` will surprise some users
+> and could result in information leaks that compromise privacy or security.
+> The feature is enabled only when your root `package.json` has `"public": true`.
+> Templates that default to public should prominently warn their users.
+
+By default the root `package.json` is copied without modifications,
+and you can provide your own `well_known_package_json` option to
+mutate the `package_json`, return new data, or return `null` to be a no-op.
+
+> Writing to `.well-known/package.json` is unstandardized behavior that
+> extends [Well-known URIs](https://wikipedia.org/wiki/Well-known_URIs) for Node packages
+> to provide conventional metadata for deployed websites.
+> [Mastodon](<https://en.wikipedia.org/wiki/Mastodon_(social_network)>) uses
+> [WebFinger](https://en.wikipedia.org/wiki/WebFinger) which uses `.well-known` for discovery.
+> One difference is that SvelteKit outputs static files relative to the configured `base` path,
+> so the `.well-known` directory may not be in the root `/`.
+> This is useful because it enables websites to provide metadata even when hosted in a namespaced
+> path like `username.github.io/projectname/.well-known`.
+
+Why publish this metadata to the web instead of relying on the git repo as the only source of truth?
+
+- we want to give all web users and tools access to discoverable package metadata
+- metadata is a much lighter dependency than an entire repo
+- some repos are deployed to multiple websites with metadata differences
+- some repos like monorepos have multiple `package.json` files
+- we don't want to force a dependency on git, the bespoke URLs of forge hosts like GitHub,
+  or any particular toolchains
+- the git repo is still the source of truth, but Gro adds a build step for project metadata,
+  giving devs full control over the published artifacts
+  instead of coupling metadata directly to a source repo's `package.json`
+
+## `well_known_src_json`
+
+If your root `package.json` has `"public": true`,
+by default Gro creates `.well-known/src.json` and `.well-known/src/`
+in `static/` during `vite build`,
+so they're included in the SvelteKit build output.
+More [about public packages](./package_json.md#public-packages).
+
+This can be customized with `well_known_src_json`.
+Setting it to `false` disables the feature, and `true` enables it.
+Setting it to a function maps the final `src.json` value - returning `null` disables it.
+
+The `.well-known/src.json` file contains more details about
+the `package.json`'s `exports`, like exported identifier names and types.
+It maps each export to a source file in `.well-known/src/`.
+
+The contents of your `src/` directory are copied to `.well-known/src/`
+using the same filter as `exports` in `package.json` by default,
+and this can be customized with `filter_well_known_src`.

package/dist/docs/package_json.md

@@ -0,0 +1,29 @@
+# `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)
+- `gro_plugin_sveltekit_app` outputs `.well-known/src/` by
+  copying over `src/` filtered by `filter_well_known_src` during `vite build` -
+  this is costly (usually more than doubling the final output size
+  of the code files in bytes, not counting images and such),
+  and it slows the build because it copies your entire source tree (sorry to hard drives),
+  but the UX is not affected
+
+> ⚠️ Setting `"public": true` in `package.json` exposes your source code at your deployed endpoint!
+> If that's the public web, that means your source code is public.

package/dist/docs/plugin.md

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

@@ -0,0 +1,144 @@
+# 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 # prints:
+gro changeset: call changeset with gro patterns
+
+[...args]   string[]                 []                           the commands to pass to changeset
+path        string                   './.changeset/config.json'   changeset config file path
+access      'restricted' | 'public'  undefined                    changeset 'access' config value, the default depends on package.json#private
+changelog   string                   '@changesets/changelog-git'  changeset "changelog" config value
+no-install  boolean                  false                        opt out of npm installing the changelog package
+
+# `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`.