@ryanatkn/gro 0.129.5 → 0.129.7

package/dist/docs/dev.md

@@ -1,40 +0,0 @@
-# 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/logo.svg" alt="a pixelated green oak acorn with a glint of sun" width="192" height="192">
-  </a>
-</p>

package/dist/docs/gen.md

@@ -1,269 +0,0 @@
-# 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)
-
-> ⚠️ Generated files should never be edited directly,
-> because the next time `gro gen` or `gro sync` runs,
-> any uncommitted changes will be lost!
-> I considered making `gen` only write to files that have no uncommitted changes,
-> but that would impede many workflows,
-> and I don't want to nudge users towards a habit of always adding an override flag.
-> I can see one possible improvement that lets the user
-> opt into making gen write only to unchanged files for those workflows that don't mind it,
-> so if you would like to see that or something similar,
-> please open an issue or [share your thoughts on Discord](https://discord.gg/YU5tyeK72X).
-
-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');
-```
-
-### gen context
-
-The `Gen` function receives one argument, the `Gen_Context` object:
-
-```ts
-export interface Gen_Context {
-	config: Gro_Config;
-	sveltekit_config: Parsed_Sveltekit_Config;
-	/**
-	 * Same as `import.meta.url` but in path form.
-	 */
-	origin_id: Path_Id;
-	log: Logger;
-}
-// export const gen: Gen = ({config, origin_id, log}) => {
-```
-
-### 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_app.md

@@ -1,113 +0,0 @@
-# SvelteKit app plugin
-
-Gro's [SvelteKit app 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;
-			// well_known_src_files?: boolean | Copy_File_Filter;
-		}),
-	];
-	return cfg;
-};
-
-export default config;
-
-// src/lib/gro_plugin_sveltekit_app.ts
-export type Host_Target = 'github_pages' | 'static' | 'node';
-
-export interface Copy_File_Filter {
-	(file_path: string): boolean | Promise<boolean>;
-}
-
-// src/lib/package_json.ts
-export interface Map_Package_Json {
-	(package_json: Package_Json): Package_Json | null | Promise<Package_Json | null>;
-}
-
-// src/lib/src_json.ts
-export interface Map_Src_Json {
-	(src_json: Src_Json): Src_Json | null | Promise<Src_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/`.
-
-## `well_known_src_files`
-
-The contents of your `src/` directory can be included in the output
-if you want your app's source code to be available the same as the built files.
-This is disabled by default.
-If `well_known_src_files` is truthy,
-the plugin copies `src/` to `static/.well-known/src/` during `vite build`.
-Passing `true` uses the same filter as `exports` in `package.json` by default,
-and it also accepts a custom filter function.

package/dist/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/dist/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/dist/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`.