feat: reworked setup flow and renamed to "initialization" and "migration" (#668)

<!-- 👋 Hi, thanks for sending a PR to template-typescript-node-package!
💖.
Please fill out all fields below and make sure each item is true and [x]
checked.
Otherwise we may not be able to review your PR. -->

## PR Checklist

- [x] Addresses an existing open issue: fixes #613
- [x] That issue was marked as [`status: accepting
prs`](https://github.com/JoshuaKGoldberg/template-typescript-node-package/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22)
- [x] Steps in
[CONTRIBUTING.md](https://github.com/JoshuaKGoldberg/template-typescript-node-package/blob/main/.github/CONTRIBUTING.md)
were taken

## Overview

* Renames the existing scripts and refers to them under the umbrella
term of "setup":
  * "Hydration": is now called "migration"
  * "Setup": is now called "initialization"
* Splits their usage docs into `./docs/*.md` files, with more
explanations of what they do

Author: JoshuaKGoldberg

.github/DEVELOPMENT.md

@@ -13,7 +13,7 @@ pnpm install
 
 ## Building
 
-Run [[**tsup**](https://tsup.egoist.dev) locally to build source files from `src/` into output files in `lib/`:
+Run [**tsup**](https://tsup.egoist.dev) locally to build source files from `src/` into output files in `lib/`:
 
 ```shell
 pnpm build
@@ -87,47 +87,81 @@ Add `--watch` to keep the type checker running in a watch mode that updates the
 pnpm tsc --watch
 ```
 
-## The Hydration Script
+## Setup Scripts
 
-This template's "hydration" script is located in `src/hydrate/`.
-It needs to be [built](#building) before it can be run.
+As described in the `README.md` file and `docs/`, this template repository comes with two scripts that can set up an existing or new repository.
 
-Be warned that running the hydration script in a repository -including this one- will modify that repository.
-To test out the script, you may want to create a new test repository to run on:
+> **Warning**
+> Both setup scripts override many files in the directory they're run in.
+> Make sure to save any changes you want to preserve before running them.
+
+### The Initialization Script
+
+This template's "initialization" script is located in `src/initialize/`.
+You can run it locally with `pnpm run initialize`.
+It uses [`tsx`](https://github.com/esbuild-kit/tsx) so you don't need to build files before running.
 
 ```shell
-cd ..
-mkdir temp
-cd temp
-echo node_modules > .gitignore
-git init
-npm init --yes
+pnpm run initialize
 ```
 
-Then, in that directory, you can directly call the hydration script:
+> 💡 Consider running `git add -A` to stage all local changes before running.
+
+#### Testing the Initialization Script
+
+You can run the end-to-end test for initializing locally on the command-line.
+Note that files need to be built with `pnpm run build` beforehand.
 
 ```shell
-node ../template-typescript-node-package/lib/hydrate/index.js -- description "Hooray, trying things out locally."
+pnpm run initialize:test
 ```
 
-Along with the hydration script itself, end-to-end tests are removed on package setup.
+That end-to-end test executes `script/initialize-test-e2e.js`, which:
 
-## The Setup Script
+1. Runs the initialization script using `--skip-github-api` and other skip flags
+2. Checks that the local repository's files were changed correctly (e.g. removed initialization-only files)
+3. Runs `pnpm run lint:knip` to make sure no excess dependencies or files were left over
+4. Resets everything
+5. Runs initialization a second time, capturing test coverage
 
-This template's "setup" script is located in `script/`.
+The `pnpm run initialize:test` script is run in CI to ensure that templating changes are in sync with the template's actual files.
+See `.github/workflows/test-initialize.yml`.
 
-### Testing the Setup Script
+### The Migration Script
 
-This template source includes an "end-to-end" test for `script/setup.js`.
-You can run it locally on the command-line:
+This template's "migration" script is located in `src/migrate/`.
+Note that files need to be built with `pnpm run build` beforehand.
+
+To test out the script locally, run it from a different repository's directory:
+
+```shell
+cd ../other-repo
+node ../template-typescript-node-package/bin/migrate.js
+```
+
+The migration script will work on any directory.
+You can try it out in a blank directory with scripts like:
+
+```shell
+cd ..
+mkdir temp
+cd temp
+node ../template-typescript-node-package/bin/migrate.js
+```
+
+#### Testing the Migration Script
+
+You can run the end-to-end test for migrating locally on the command-line:
 
 ```shell
-pnpm run setup:test
+pnpm run initiamigratelize:test
 ```
 
-That end-to-end test executes `script/setup-test-e2e.js`, which:
+That end-to-end test executes `script/migrate-test-e2e.js`, which:
 
-1. Runs the setup script using `--skip-api`
-2. Checks that the local repository's files were changed correctly (e.g. removed setup-only files)
+1. Runs the migration script using `--skip-github-api` and other skip flags
+2. Checks that only a small list of allowed files were changed
+3. Checks that the local repository's files were changed correctly (e.g. removed initialization-only files)
 
-Along with the setup script itself, end-to-end tests are removed on package setup.
+The `pnpm run migrate:test` script is run in CI to ensure that templating changes are in sync with the template's actual files.
+See `.github/workflows/test-migrate.yml`.

.github/workflows/setup.yml .github/workflows/test-initialize.yml

@@ -1,23 +1,23 @@
 jobs:
-  setup:
+  initialize:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
       - uses: ./.github/actions/prepare
       - run: pnpm run build
-      - run: pnpm run setup:test
+      - run: pnpm run initialize:test
       - name: Codecov
         uses: codecov/codecov-action@v3
         with:
-          files: coverage-setup/lcov.info
-          flags: setup
+          files: coverage-initialize/lcov.info
+          flags: initialize
       - if: always()
         name: Archive code coverage results
         uses: actions/upload-artifact@v3
         with:
-          path: coverage-setup
+          path: coverage-initialize
 
-name: Test Setup Script
+name: Test Initialization Script
 
 on:
   pull_request: ~

.github/workflows/hydrate.yml .github/workflows/test-migrate.yml

@@ -1,23 +1,23 @@
 jobs:
-  hydrate:
+  migrate:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
       - uses: ./.github/actions/prepare
       - run: pnpm run build
-      - run: pnpm run hydrate:test
+      - run: pnpm run migrate:test
       - name: Codecov
         uses: codecov/codecov-action@v3
         with:
-          files: coverage-hydrate/lcov.info
-          flags: hydrate
+          files: coverage-migrate/lcov.info
+          flags: migrate
       - if: always()
         name: Archive code coverage results
         uses: actions/upload-artifact@v3
         with:
-          path: coverage-hydrate
+          path: coverage-migrate
 
-name: Test Hydrate Script
+name: Test Migration Script
 
 on:
   pull_request: ~

README.md

@@ -26,9 +26,23 @@
     <img alt="TypeScript: Strict 💪" src="https://img.shields.io/badge/typescript-strict_💪-21bb42.svg" />
 </p>
 
+## Getting Started
+
+First make sure you have the following installed:
+
+- [GitHub CLI](https://cli.github.com) _(you'll need to be logged in)_
+- [Node.js](https://nodejs.org)
+- [pnpm](https://pnpm.io)
+
+This repository comes with two scripts to set up an existing or new repository with tooling.
+Use the corresponding docs page to get started:
+
+- [Initializing from the template](./docs/Initialization.md): creating a new repository with the [_Use this template_](https://github.com/JoshuaKGoldberg/template-typescript-node-package/generate) button on GitHub
+- [Migrating an existing repository](./docs/Migration.md): adding this template's tooling on top of an existing repository
+
 ## Explainer
 
-This template is available for anybody who wants to set up a basic Node application using TypeScript.
+This template is available for anybody who wants to set up a Node application using TypeScript.
 It sets up the following tooling for you:
 
 - [**All Contributors**](https://allcontributors.org): Tracks various kinds of contributions and displays them in a nicely formatted table in the README.md.
@@ -44,112 +58,6 @@ It sets up the following tooling for you:
 - [**TypeScript**](https://typescriptlang.org): A typed superset of JavaScript, configured with strict compiler options.
 - [**Vitest**](https://vitest.dev): Fast unit tests, configured with coverage tracking and [console-fail-test](https://github.com/JoshuaKGoldberg/console-fail-test).
 
-## Setup
-
-This package comes with a bootstrap/initialization setup script that fills out your repository's details, installs necessary packages, then removes itself and uninstalls setup dependencies.
-
-First make sure you have the following installed:
-
-- [GitHub CLI](https://cli.github.com) _(you'll need to be logged in)_
-- [Node.js](https://nodejs.org)
-- [pnpm](https://pnpm.io)
-
-To use this template:
-
-1. Click the [_Use this template_](https://github.com/JoshuaKGoldberg/template-typescript-node-package/generate) button to create a new repository with the same Git history
-2. Open that repository, such as by [cloning it locally](https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository) or [developing in a codespace](https://docs.github.com/en/codespaces/developing-in-codespaces/developing-in-a-codespace)
-3. Create two tokens in [repository secrets](https://docs.github.com/en/actions/security-guides/encrypted-secrets):
-   - `ACCESS_TOKEN`: A [GitHub PAT](https://github.com/settings/tokens/new) with _repo_ and _workflow_ permissions
-   - `NPM_TOKEN`: An [npm access token](https://docs.npmjs.com/creating-and-viewing-access-tokens/) with _Automation_ permissions
-4. `pnpm install`
-5. `pnpm run setup` to run the setup script
-6. Install the [Codecov GitHub App](https://github.com/marketplace/codecov) and [Renovate GitHub App](https://github.com/marketplace/renovate)
-
-> The setup script removes the `## Explainer`, `## Setup`, and `## Repository Hydration` sections from this README.md.
-
-### Setup Options
-
-The setup script requires four options to fill out repository details.
-It will interactively prompt for any that are not provided as a string CLI flag:
-
-1. `repository`: The kebab-case name of the repository (e.g. `template-typescript-node-package`)
-2. `title`: Title Case title for the repository to be used in documentation (e.g. `Template TypeScript Node Package`)
-3. `owner`: GitHub organization or user the repository is underneath (e.g. `JoshuaKGoldberg`)
-4. `description`: Sentence case description of the repository (e.g. `A quickstart-friendly TypeScript package with lots of great repository tooling. ✨`)
-
-Additionally, a `--skip-api` boolean CLI flag may be specified to prevent the setup script from calling to GitHub APIs for repository hydration.
-The script normally posts to GitHub APIs to set information such as repository description and branch protections on github.com.
-Specifying `--skip-api` prevents those API calls, effectively limiting setup changes to local files in Git.
-Doing so can be useful to preview what running setup does.
-
-For example, pre-populating all values and skipping API calls:
-
-```shell
-pnpm run setup --repository "testing-repository" --title "Testing Title" --owner "TestingOwner" --description "Test Description" --skip-api
-```
-
-> Tip: after running `pnpm run setup` with `--skip-api`, you can always `git add -A; git reset --hard HEAD` to completely reset all changes.
-
-## Repository Hydration
-
-> **Warning**
-> Hydration will override many files in your repository.
-> You'll want to review each of the changes and make sure nothing important is removed.
-
-Alternately, if you have an existing repository that you'd like to give the files from this repository, you can run `template-typescript-node-package` in a repository to "hydrate" it.
-
-```shell
-npx template-typescript-node-package
-```
-
-Repository settings will be auto-filled from the repository's files if possible, but can be provided manually as well:
-
-- `author` _(`string`)_: e.g. `"Josh Goldberg"`
-- `description` _(`string`)_: e.g. `"A quickstart-friendly TypeScript template with comprehensive formatting, linting, releases, testing, and other great tooling built-in. ✨"`
-- `email` _(`string`)_: e.g. `"[email protected]"`
-- `funding` _(`string`, optional)_: e.g. `"JoshuaKGoldberg"`
-- `owner` _(`string`)_: e.g. `"JoshuaKGoldberg"`
-- `repository` _(`string`)_: e.g. `"template-typescript-node-package"`
-- `title` _(`string`)_: e.g. `"Template TypeScript Node Package"`
-
-For example, providing a `funding` value different from the `author`:
-
-```shell
-npx template-typescript-node-package --funding MyOrganization
-```
-
-The hydration script by default will include all the features in this template.
-You can disable some of them on the command-line:
-
-- `releases` _(`boolean`)_: Whether to include automated package publishing
-- `unitTests` _(`boolean`)_: Whether to include unit tests with code coverage tracking
-
-```shell
-npx template-typescript-node-package --releases false --unitTests false
-```
-
-You can prevent the hydration script from making network-based changes using either or both of the following CLI flags:
-
-- `--skip-contributors` _(`boolean`)_: Skips detecting existing contributors with [`all-contributors-for-repository`](https://github.com/JoshuaKGoldberg/all-contributors-for-repository)
-- `--skip-install` _(`boolean`)_: Skips installing all the new template packages with `pnpm`
-- `--skip-setup` _(`boolean`)_: Skips running the setup script at the end of hydration
-
-```shell
-npx template-typescript-node-package --skip-install --skip-setup
-```
-
-## Usage
-
-```shell
-npm i template-typescript-node-package
-```
-
-```ts
-import { greet } from "template-typescript-node-package";
-
-greet("Hello, world!");
-```
-
 ## Development
 
 See [`.github/CONTRIBUTING.md`](./.github/CONTRIBUTING.md), then [`.github/DEVELOPMENT.md`](./.github/DEVELOPMENT.md).

bin/hydrate.js

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { migrate } from "../lib/migrate/index.js";
+
+process.exitCode = await migrate(process.argv.slice(2));

bin/migrate.js

@@ -0,0 +1,22 @@
+# FAQs
+
+## Can I use <insert tool here&gt with this template?
+
+Yes!
+After you set up a repository, you can substitute in any tools you'd like.
+
+If you think the tool would be broadly useful to most consumers of this template, feel free to [file a feature request](https://github.com/JoshuaKGoldberg/template-typescript-node-package/issues/new?assignees=&labels=type%3A+feature&projects=&template=03-feature.yml&title=%F0%9F%9A%80+Feature%3A+%3Cshort+description+of+the+feature%3E) to add it in.
+
+## Is there a way to pull in template updates to previously created repositories?
+
+Not yet.
+You can always copy & paste them in manually.
+
+See [🚀 Feature: Add a script to sync the tooling updates from forked template repo #498](https://github.com/JoshuaKGoldberg/template-typescript-node-package/issues/498): it will likely eventually be possible.
+
+## Why does this package include so many tools?
+
+This repository is meant to serve as a starter that includes all the general tooling a modern TypeScript/Node repository could possibly need.
+Each of the included tools exists for a good reason and provides real value.
+
+If you don't want to use any particular tool, you can always remove it manually.