feat: automate repository creation for --mode create (#690)

## PR Checklist

- [x] Addresses an existing open issue: fixes #688
- [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

Streamlines the heck out of the `--mode create` (`npx
template-typescript-node-package`) experience:

* Instead of telling you to run some initialize commands, it offers to
run them for you
* Similarly, after creating a new repository, the creation script will
offer to update the repo using GitHub's APIs for you
* Adds a `--create-repository` flag to automatically do those things

Author: JoshuaKGoldberg

Diff for: docs/InitializationFromTemplate.md

@@ -21,7 +21,7 @@ pnpm run initialize
 ```
 
 The initialization script will interactively prompt for values to be used in creating the new repository.
-Each may provided as a string CLI flag as well:
+Each may provided as a 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`)

Diff for: docs/InitializationFromTerminal.md

@@ -13,32 +13,30 @@ Pass `--mode create` to tell it to create a new repository in a child directory:
 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`:
+Then, go through the following two steps to set up required repository tooling on GitHub:
 
-```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
-```
+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! 🥳
 
 ## 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:
+Each may provided as a CLI flag as well:
 
+- `--create-repository`: Whether to automatically create a repository on github.com with the given repository name under the owner
 - `--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:
+For example, pre-populating all values and creating a new repository:
 
 ```shell
-npx template-typescript-node-package --mode create --repository "testing-repository" --title "Testing Title" --owner "TestingOwner" --description "Test Description"
+npx template-typescript-node-package --create-repository --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:

Diff for: src/bin/index.ts

@@ -13,9 +13,9 @@ export async function bin(args: string[]) {
 
 	prompts.intro(
 		[
-			chalk.greenBright`Welcome to the`,
-			chalk.bgGreenBright.black`template-typescript-node-package`,
-			chalk.greenBright(`package! 🎉`),
+			chalk.greenBright(`Welcome to`),
+			chalk.bgGreenBright.black(`template-typescript-node-package`),
+			chalk.greenBright(`! 🎉`),
 		].join(" "),
 	);
 

Diff for: src/create/createWithValues.ts

@@ -1,7 +1,14 @@
+import * as prompts from "@clack/prompts";
+import { $ } from "execa";
+
 import { runOrSkip } from "../shared/cli/runOrSkip.js";
 import { withSpinner } from "../shared/cli/spinners.js";
+import { doesRepositoryExist } from "../shared/doesRepositoryExist.js";
 import { HelpersAndValues } from "../shared/inputs.js";
 import { finalizeDependencies } from "../steps/finalizeDependencies.js";
+import { initializeBranchProtectionSettings } from "../steps/initializeBranchProtectionSettings.js";
+import { initializeRepositorySettings } from "../steps/initializeRepositorySettings.js";
+import { initializeRepositoryLabels } from "../steps/labels/initializeRepositoryLabels.js";
 import { runCommands } from "../steps/runCommands.js";
 import { writeReadme } from "../steps/writeReadme.js";
 import { writeStructure } from "../steps/writing/writeStructure.js";
@@ -30,4 +37,28 @@ export async function createWithValues(input: HelpersAndValues) {
 		"pnpm format --write",
 		"pnpm lint --fix",
 	]);
+
+	const sendToGitHub =
+		input.octokit &&
+		(await doesRepositoryExist(input.octokit, input.values)) &&
+		(input.values.createRepository ??
+			(await prompts.confirm({
+				message:
+					"Would you like to push the template's tooling up to the repository on GitHub?",
+			})) === true);
+
+	await runOrSkip("Initializing API metadata", !sendToGitHub, async () => {
+		await $`git remote add origin https://github.com/${input.values.owner}/${input.values.repository}`;
+		await $`git add -A`;
+		await $`git commit --message ${"chore: initialized repo ✨"}`;
+		await $`git push -u origin main --force`;
+
+		/* eslint-disable @typescript-eslint/no-non-null-assertion */
+		await initializeBranchProtectionSettings(input.octokit!, input.values);
+		await initializeRepositoryLabels();
+		await initializeRepositorySettings(input.octokit!, input.values);
+		/* eslint-enable @typescript-eslint/no-non-null-assertion */
+	});
+
+	return { sentToGitHub: sendToGitHub };
 }

Diff for: src/create/index.ts

@@ -34,29 +34,38 @@ export async function create(args: string[]) {
 
 	return await runOrRestore({
 		run: async () => {
-			await createWithValues({
+			const { sentToGitHub } = await createWithValues({
 				...inputs,
 				values: await augmentValuesWithNpmInfo(inputs.values),
 			});
 
-			outro([
-				{
-					label:
-						"Consider creating a GitHub repository from the new directory:",
-					lines: [
-						`cd ${inputs.values.repository}`,
-						`gh repo create ${inputs.values.repository} --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`,
-					],
-				},
-				{
-					label:
-						"If you do, be sure to populate its ACCESS_TOKEN and NPM_TOKEN secrets.",
-				},
-			]);
+			outro(
+				sentToGitHub
+					? [
+							{
+								label:
+									"Now, all you have to do is populate the repository's ACCESS_TOKEN and NPM_TOKEN secrets.",
+							},
+					  ]
+					: [
+							{
+								label:
+									"Consider creating a GitHub repository from the new directory:",
+								lines: [
+									`cd ${inputs.values.repository}`,
+									`gh repo create ${inputs.values.repository} --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`,
+								],
+							},
+							{
+								label:
+									"If you do, be sure to populate its ACCESS_TOKEN and NPM_TOKEN secrets.",
+							},
+					  ],
+			);
 		},
 		skipRestore: inputs.values.skipRestore ?? true,
 	});

Diff for: src/initialize/initializeWithValues.ts

@@ -36,9 +36,9 @@ export async function initializeWithValues(input: HelpersAndValues) {
 
 	await runOrSkip("Initializing API metadata", !input.octokit, async () => {
 		/* eslint-disable @typescript-eslint/no-non-null-assertion */
+		await initializeBranchProtectionSettings(input.octokit!, input.values);
 		await initializeRepositoryLabels();
 		await initializeRepositorySettings(input.octokit!, input.values);
-		await initializeBranchProtectionSettings(input.octokit!, input.values);
 		/* eslint-enable @typescript-eslint/no-non-null-assertion */
 	});
 

Diff for: src/shared/args.ts

@@ -1,5 +1,6 @@
 export const allArgOptions = {
 	author: { type: "string" },
+	"create-repository": { type: "boolean" },
 	description: { type: "string" },
 	email: { type: "string" },
 	funding: { type: "string" },

Diff for: src/shared/augmentValuesWithNpmInfo.ts

@@ -14,6 +14,7 @@ export async function augmentValuesWithNpmInfo<Values extends InputValues>(
 		author: await getPrefillOrPromptedValue(
 			values.author,
 			"What author (username) will be used for the npm owner?",
+			values.owner.toLowerCase(),
 		),
 		email: await getPrefillOrPromptedValue(
 			values.email,

Diff for: src/shared/doesRepositoryExist.test.ts

@@ -0,0 +1,47 @@
+import { Octokit } from "octokit";
+import { SpyInstance, describe, expect, it, vi } from "vitest";
+
+import { doesRepositoryExist } from "./doesRepositoryExist.js";
+
+const createMockOctokit = (
+	repos: Partial<Record<keyof Octokit["rest"]["repos"], SpyInstance>>,
+) =>
+	({
+		rest: {
+			repos,
+		},
+	}) as unknown as Octokit;
+
+const owner = "StubOwner";
+const repository = "stub-repository";
+
+describe("doesRepositoryExist", () => {
+	it("returns true when the octokit GET resolves", async () => {
+		const octokit = createMockOctokit({ get: vi.fn().mockResolvedValue({}) });
+
+		const actual = await doesRepositoryExist(octokit, { owner, repository });
+
+		expect(actual).toEqual(true);
+	});
+
+	it("returns false when the octokit GET rejects with a 404", async () => {
+		const octokit = createMockOctokit({
+			get: vi.fn().mockRejectedValue({ status: 404 }),
+		});
+
+		const actual = await doesRepositoryExist(octokit, { owner, repository });
+
+		expect(actual).toEqual(false);
+	});
+
+	it("throws the error when awaiting the octokit GET throws a non-404 error", async () => {
+		const error = new Error("Oh no!");
+		const octokit = createMockOctokit({
+			get: vi.fn().mockRejectedValue(error),
+		});
+
+		await expect(
+			async () => await doesRepositoryExist(octokit, { owner, repository }),
+		).rejects.toEqual(error);
+	});
+});

Diff for: src/shared/doesRepositoryExist.ts

@@ -0,0 +1,27 @@
+import { Octokit, RequestError } from "octokit";
+
+export interface DoesRepositoryExistOptions {
+	owner: string;
+	repository: string;
+}
+
+export async function doesRepositoryExist(
+	octokit: Octokit,
+	options: DoesRepositoryExistOptions,
+) {
+	// Because the Octokit SDK throws on 404s (😡),
+	// we try/catch to check whether the repo exists.
+	try {
+		await octokit.rest.repos.get({
+			owner: options.owner,
+			repo: options.repository,
+		});
+		return true;
+	} catch (error) {
+		if ((error as RequestError).status !== 404) {
+			throw error;
+		}
+
+		return false;
+	}
+}