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

Diff for: .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/`.

Diff for: .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

Diff for: .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

Diff for: .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

Diff for: 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

Diff for: 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));

Diff for: 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

Diff for: 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! 🥳

Diff for: docs/Initialization.md renamed to docs/InitializationFromTemplate.md

@@ -49,10 +49,9 @@ You can prevent the migration script from making some network-based changes usin
 - `--skip-contributors` _(`boolean`)_: Skips detecting existing contributors with [`all-contributors-for-repository`](https://github.com/JoshuaKGoldberg/all-contributors-for-repository)
 - `--skip-github-api` _(`boolean`)_: Skips calling to GitHub APIs
 - `--skip-install` _(`boolean`)_: Skips installing all the new template packages with `pnpm`
-- `--skip-initialize` _(`boolean`)_: Skips running the initialize script at the end of migration
 
 ```shell
-npx template-typescript-node-package --skip-github-api --skip-initialize --skip-install
+npx template-typescript-node-package --skip-github-api --skip-install
 ```
 
 > Tip: the `--skip-github-api` flag will cause all changes to be limited to your local repository.

Diff for: docs/InitializationFromTerminal.md

@@ -2,6 +2,7 @@
 	"$schema": "https://unpkg.com/knip@latest/schema.json",
 	"entry": [
 		"src/index.ts!",
+		"src/guide/index.ts",
 		"src/initialize/index.ts",
 		"src/migrate/index.ts",
 		"script/*e2e.js"

Diff for: docs/Migration.md

@@ -13,7 +13,7 @@
 	},
 	"type": "module",
 	"main": "./lib/index.js",
-	"bin": "./bin/migrate.js",
+	"bin": "./bin/index.js",
 	"files": [
 		"bin/",
 		"lib/",
@@ -23,9 +23,10 @@
 	],
 	"scripts": {
 		"build": "tsup",
+		"create:test": "node script/create-test-e2e.js",
 		"format": "prettier \"**/*\" --ignore-unknown",
 		"format:write": "pnpm format --write",
-		"initialize": "tsx src/initialize/index.ts",
+		"initialize": "tsx ./src/bin/index.js --mode initialize",
 		"initialize:test": "node script/initialize-test-e2e.js",
 		"lint": "eslint . .*js --max-warnings 0 --report-unused-disable-directives",
 		"lint:knip": "knip",
@@ -36,7 +37,8 @@
 		"migrate:test": "node script/migrate-test-e2e.js",
 		"prepare": "husky install",
 		"should-semantic-release": "should-semantic-release --verbose",
-		"test": "vitest"
+		"test": "vitest",
+		"tsc": "tsc"
 	},
 	"lint-staged": {
 		"*": "prettier --ignore-unknown --write"

Diff for: knip.jsonc

@@ -0,0 +1,41 @@
+import { $, execaCommand } from "execa";
+import { strict as assert } from "node:assert";
+
+const author = "Test Author";
+const description = "Test description.";
+const email = "[email protected]";
+const repository = "test-repository";
+const owner = "TestOwner";
+const title = "Test Title";
+
+await $`rm -rf ${repository}`;
+
+await $({
+	stdio: "inherit",
+})`c8 -o ./coverage-create -r html -r lcov node ./bin/index.js --mode create --author ${author} --email ${email} --description ${description} --owner ${owner} --title ${title} --repository ${repository} --skip-contributors --skip-github-api`;
+
+process.chdir(repository);
+
+const failures = [];
+
+for (const command of [
+	`pnpm i`,
+	`pnpm run build`,
+	`pnpm run format --list-different`,
+	`pnpm run lint`,
+	`pnpm run lint:md`,
+	`pnpm run lint:package`,
+	`pnpm run lint:packages`,
+	`pnpm run lint:spelling`,
+	`pnpm run lint:knip`,
+	`pnpm run test run`,
+	`pnpm run tsc`,
+]) {
+	const result = await execaCommand(command, { stdio: "inherit" });
+
+	if (result.exitCode) {
+		failures.push({ command, result });
+	}
+}
+
+assert.deepEqual(failures, []);

Diff for: package.json

@@ -11,7 +11,7 @@ const repository = "new-repository-test";
 // First we run initialize to modifies the local repo, so we can test the changes
 await $({
 	stdio: "inherit",
-})`node ./lib/initialize/index.js --description ${description} --owner ${owner} --title ${title} --repository ${repository} --skip-github-api --skip-restore`;
+})`node ./bin/index.js --description ${description} --mode initialize --owner ${owner} --title ${title} --repository ${repository} --skip-github-api --skip-restore`;
 
 const newPackageJson = JSON.parse(
 	(await fs.readFile("./package.json")).toString(),
@@ -52,4 +52,4 @@ await $`pnpm i`;
 await $`pnpm run build`;
 await $({
 	stdio: "inherit",
-})`c8 -o ./coverage-initialize -r html -r lcov node ./lib/initialize/index.js --description ${description} --owner ${owner} --title ${title} --repository ${repository} --skip-github-api --skip-removal --skip-restore`;
+})`c8 -o ./coverage-initialize -r html -r lcov node ./bin/index.js --description ${description} --mode initialize --owner ${owner} --title ${title} --repository ${repository} --skip-github-api --skip-removal --skip-restore`;

Diff for: script/create-test-e2e.js

@@ -9,7 +9,7 @@ const title = "Template TypeScript Node Package";
 
 await $({
 	stdio: "inherit",
-})`c8 -o ./coverage-migrate -r html -r lcov node ./bin/migrate.js  --description ${description} --owner ${owner} --title ${title} --repository ${repository} --skip-github-api --skip-contributors --skip-initialize --skip-install`;
+})`c8 -o ./coverage-migrate -r html -r lcov node ./bin/index.js --mode migrate --description ${description} --owner ${owner} --title ${title} --repository ${repository} --skip-github-api --skip-contributors --skip-install`;
 
 const { stdout: gitStatus } = await $`git status`;
 console.log(`Stdout from running \`git status\`:\n${gitStatus}`);
@@ -25,6 +25,7 @@ if (indexOfUnstagedFilesMessage === -1) {
 
 const filesExpectedToBeChanged = new Set([
 	".all-contributorsrc",
+	"bin/index.js",
 	"README.md",
 	"knip.jsonc",
 	"package.json",