feat: add create flow and unify bin with --mode (#681)

<!-- 👋 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 #670 
- [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

Changes the bin script to be the main launching point for the app. It
can take in or prompt for a `--mode` set to either `"create"`,
`"initialize"`, or `"migrate"`.

This comes with a few cleanups:

* Simplified `runOrRestore` so that it just runs or logs - leaving
parsing logic to the functions that call it
* Removed a lot of the terminal logs so that the remaining output is
cleaner
* Cleaned up input parsing to have fewer different code paths / types

Tracking my todo items:

- [x] Add a new `create` flow alongside `initialize` and `migrate`
- [x] Manually test a bunch
- [x] Refactor their code to streamline the flow of logic
- [x] Fix unit tests
- [x] Fix existing end-to-end tests
- [x] Overhaul documentation
- [x] Add a new end-to-end test
- [x] Manually test some more

Author: JoshuaKGoldberg

.github/DEVELOPMENT.md

@@ -41,12 +41,12 @@ pnpm format:write
 This package includes several forms of linting to enforce consistent code quality and styling.
 Each should be shown in VS Code, and can be run manually on the command-line:
 
+- `pnpm lint` ([ESLint](https://eslint.org) with [typescript-eslint](https://typescript-eslint.io)): Lints JavaScript and TypeScript source files
 - `pnpm lint:knip` ([knip](https://github.com/webpro/knip)): Detects unused files, dependencies, and code exports
 - `pnpm lint:md` ([Markdownlint](https://github.com/DavidAnson/markdownlint)): Checks Markdown source files
 - `pnpm lint:package` ([npm-package-json-lint](https://npmpackagejsonlint.org/)): Lints the `package.json` file
 - `pnpm lint:packages` ([pnpm dedupe --check](https://pnpm.io/cli/dedupe)): Checks for unnecessarily duplicated packages in the `pnpm-lock.yml` file
 - `pnpm lint:spelling` ([cspell](https://cspell.org)): Spell checks across all source files
-- `pnpm lint` ([ESLint](https://eslint.org) with [typescript-eslint](https://typescript-eslint.io)): Lints JavaScript and TypeScript source files
 
 ## Testing
 
@@ -89,12 +89,32 @@ pnpm tsc --watch
 
 ## Setup Scripts
 
-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.
+As described in the `README.md` file and `docs/`, this template repository comes with three scripts that can set up an existing or new repository.
 
 > **Warning**
-> Both setup scripts override many files in the directory they're run in.
+> Each setup script overrides many files in the directory they're run in.
 > Make sure to save any changes you want to preserve before running them.
 
+### The Creation Script
+
+This template's "creation" script is located in `src/create/`.
+You can run it locally with `node bin/index.js --mode create`.
+Note that files need to be built with `pnpm run build` beforehand.
+
+#### Testing the Creation Script
+
+You can run the end-to-end test for creation locally on the command-line.
+Note that the files need to be built with `pnpm run build` beforehand.
+
+```shell
+pnpm run create:test
+```
+
+That end-to-end test executes `script/create-test-e2e.js`, which:
+
+1. Runs the creation script to create a new `test-repository` child directory and repository
+2. Asserts that commands such as `build` and `lint` each pass
+
 ### The Initialization Script
 
 This template's "initialization" script is located in `src/initialize/`.

.github/workflows/test-create.yml

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

.github/workflows/test-initialize.yml

@@ -6,7 +6,8 @@ jobs:
       - uses: ./.github/actions/prepare
       - run: pnpm run build
       - run: pnpm run initialize:test
-      - name: Codecov
+      - if: always()
+        name: Codecov
         uses: codecov/codecov-action@v3
         with:
           files: coverage-initialize/lcov.info

.github/workflows/test-migrate.yml

@@ -6,7 +6,8 @@ jobs:
       - uses: ./.github/actions/prepare
       - run: pnpm run build
       - run: pnpm run migrate:test
-      - name: Codecov
+      - if: always()
+        name: Codecov
         uses: codecov/codecov-action@v3
         with:
           files: coverage-migrate/lcov.info

README.md

@@ -26,6 +26,12 @@
     <img alt="TypeScript: Strict 💪" src="https://img.shields.io/badge/typescript-strict_💪-21bb42.svg" />
 </p>
 
+Note that this template is early stage, opinionated, and not endorsed by the TypeScript team.
+It sets up a _lot_ of tooling out of the box.
+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.
+
 ## Getting Started
 
 First make sure you have the following installed:
@@ -37,7 +43,8 @@ First make sure you have the following installed:
 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
+- [Initializing from the template](./docs/InitializationFromTemplate.md): creating a new repository with the [_Use this template_](https://github.com/JoshuaKGoldberg/template-typescript-node-package/generate) button on GitHub _(recommended)_
+- [Initializing from the terminal](./docs/InitializationFromTerminal.md): creating a new repository locally on the command-line
 - [Migrating an existing repository](./docs/Migration.md): adding this template's tooling on top of an existing repository
 
 ## Explainer

bin/index.js

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

bin/migrate.js

@@ -1,5 +1,5 @@
 codecov:
   notify:
-    after_n_builds: 3
+    after_n_builds: 4
 comment:
-  after_n_builds: 3
+  after_n_builds: 4

codecov.yml

@@ -0,0 +1,51 @@
+# Initializing from the Terminal
+
+As a local alternative to [initialization from the template](./InitializationFromTemplate.md), you can run `npx template-typescript-node-package` in your terminal:
+
+```shell
+npx template-typescript-node-package
+```
+
+The prompt by default will ask you which mode you'd like to run in.
+Pass `--mode create` to tell it to create a new repository in a child directory:
+
+```shell
+npx template-typescript-node-package --mode create
+```
+
+Upon completion, the prompt will suggest commands to get started working in the repository and create a corresponding GitHub repository.
+Those commands will roughly run the [The Initialization Script](./InitializationFromTemplate.md#the-initialization-script), but with `npm template-typescript-node-package --mode initialize` instead of `pnpm run initialize`:
+
+```shell
+cd repository-name
+gh repo create repository-name --public --source=. --remote=origin
+npx template-typescript-node-package --mode initialize
+git add -A
+git commit -m "chore: initial commit ✨"
+git push -u origin main
+```
+
+## The Creation Script
+
+The creation script will interactively prompt for values to be used in creating the new repository.
+Each may provided as a string CLI flag as well:
+
+- `--description`: Sentence case description of the repository (e.g. `A quickstart-friendly TypeScript package with lots of great repository tooling. ✨`)
+- `--owner`: GitHub organization or user the repository is underneath (e.g. `JoshuaKGoldberg`)
+- `--repository`: The kebab-case name of the repository (e.g. `template-typescript-node-package`)
+- `--title`: Title Case title for the repository to be used in documentation (e.g. `Template TypeScript Node Package`)
+
+For example, pre-populating all values:
+
+```shell
+npx template-typescript-node-package --mode create --repository "testing-repository" --title "Testing Title" --owner "TestingOwner" --description "Test Description"
+```
+
+Then, go through the following two steps to set up required repository tooling on GitHub:
+
+1. 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
+2. Install the [Codecov GitHub App](https://github.com/marketplace/codecov) and [Renovate GitHub App](https://github.com/marketplace/renovate)
+
+At this point, your new repository should be ready for development! 🥳