feat: add --guide options (#983)

## PR Checklist

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

## Overview

Adds `--guide` with the accompanying `--guide-title`, similar to the
existing `--logo` and `--logo-alt` options. It will be inferred from an
existing `.github/DEVELOPMENT.md` when present.

Author: JoshuaKGoldberg

Diff for: .github/DEVELOPMENT.md

@@ -1,5 +1,8 @@
 # Development
 
+> If you'd like a more guided walkthrough, see [Contributing to a create-typescript-app Repository](https://www.joshuakgoldberg.com/blog/contributing-to-a-create-typescript-app-repository).
+> It'll walk you through the common activities you'll need to contribute.
+
 After [forking the repo from GitHub](https://help.github.com/articles/fork-a-repo) and [installing pnpm](https://pnpm.io/installation):
 
 ```shell

Diff for: docs/FAQs.md

@@ -1,5 +1,11 @@
 # FAQs
 
+## Do you have a guide to working with a `create-typescript-app` repository?
+
+Yes!
+See [Contributing to a create-typescript-app Repository](https://www.joshuakgoldberg.com/blog/contributing-to-a-create-typescript-app-repository).
+It'll walk you through the common activities you'll need to contribute to a repository scaffolded with `create-typescript-app`.
+
 ## Can I use _(insert tool here)_ with this template?
 
 Yes!
@@ -61,13 +67,13 @@ You can always copy & paste them in manually, and/or re-run `npx create-typescri
 
 See [🚀 Feature: Add a script to sync the tooling updates from forked template repo #498](https://github.com/JoshuaKGoldberg/create-typescript-app/issues/498): it will likely eventually be possible.
 
-### What about `eslint-config-prettier`?
+## What about `eslint-config-prettier`?
 
 [`eslint-config-prettier`](https://github.com/prettier/eslint-config-prettier) is an ESLint plugin that serves only to turn off all rules that are unnecessary or might conflict with formatters such as Prettier.
 None of the ESLint configs enabled by this repository's tooling leave any rules enabled that would need to be disabled.
 Using `eslint-config-prettier` would be redundant.
 
-### What determines which "base" a tool goes into?
+## What determines which "base" a tool goes into?
 
 The four bases correspond to what have seemed to be the most common user needs of template consumers:
 
@@ -80,7 +86,7 @@ The four bases correspond to what have seemed to be the most common user needs o
 
 Note that users can always customize exactly with portions are kept in with `--base` **`prompt`**.
 
-### Which tools can't I remove?
+## Which tools can't I remove?
 
 The following pieces of this template's tooling don't have options to be removed:
 
@@ -99,7 +105,7 @@ 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.
 
-### What tooling does this package use that isn't part of created repositories?
+## What tooling does this package use that isn't part of created repositories?
 
 Glad you asked!
 These are the projects used across many parts of `create-typescript-app`:

Diff for: docs/Options.md

@@ -57,10 +57,12 @@ The setup scripts also allow for optional overrides of the following inputs whos
 - `--email` _(`string`)_: Email address to be listed as the point of contact in docs and packages (e.g. `[email protected]`)
   - Optionally, `--email-github` _(`string`)_ and/or `--email-npm` _(`string`)_ may be provided to use different emails in `.md` files and `package.json`, respectively
 - `--funding` _(`string`)_: GitHub organization or username to mention in `funding.yml` (by default, `owner`)
+- `--guide` _(`string`)_: Link to a contribution guide to place at the top of the development docs
+  - `--guide-title` _(`string`)_: If `--guide` is provided or detected from an existing DEVELOPMENT.md, the text title to place in the guide link
 - `--keywords` _(`string[]`)_: Any number of keywords to include in `package.json` (by default, none)
   - This can be specified any number of times, like `--keywords apple --keywords "banana cherry"`
 - `--logo` _(`string`)_: Local image file in the repository to display near the top of the README.md as a logo
-  - `--logo-alt` _(`string`)_: If `--logo` is provided or detected from an existing README.md, alt text that describes the image will be prompted for if not provided
+  - `--logo-alt` _(`string`)_: If `--logo` is provided or detected from an existing README.md, alt text that describes the image (will be prompted for if not provided)
 - `--preserve-generated-from` _(`boolean`)_: Whether to keep the GitHub repository _generated from_ notice (by default, `false`)
 
 For example, customizing the ownership and users associated with a new repository:

Diff for: src/create/createRerunSuggestion.test.ts

@@ -50,6 +50,21 @@ describe("createRerunSuggestion", () => {
 		);
 	});
 
+	it("includes stringified guide when it exists", () => {
+		const actual = createRerunSuggestion({
+			...options,
+			guide: {
+				href: "https://example.com",
+				title: "Test Title",
+			},
+			mode: "initialize",
+		});
+
+		expect(actual).toMatchInlineSnapshot(
+			'"npx create-typescript-app --mode initialize --base everything --access public --author TestAuthor --description \\"Test description.\\" --directory . --email-github [email protected] --email-npm [email protected] --exclude-all-contributors true --exclude-compliance true --exclude-lint-jsdoc true --exclude-lint-json true --exclude-lint-knip true --exclude-lint-package-json true --exclude-lint-perfectionist true --guide https://example.com --guide-title \\"Test Title\\" --keywords \\"abc def ghi jkl mno pqr\\" --mode initialize --owner TestOwner --repository test-repository --skip-github-api true --skip-install true --skip-removal true --title \\"Test Title\\""',
+		);
+	});
+
 	it("includes stringified logo when it exists", () => {
 		const actual = createRerunSuggestion({
 			...options,

Diff for: src/create/createRerunSuggestion.ts

@@ -10,13 +10,17 @@ function getFirstMatchingArg(key: string) {
 export function createRerunSuggestion(options: Partial<Options>): string {
 	const optionsNormalized = {
 		...options,
-		...(options.email
+		email: undefined,
+		...(options.email && {
+			emailGitHub: options.email.github,
+			emailNpm: options.email.npm,
+		}),
+		...(options.guide
 			? {
-					email: undefined,
-					emailGitHub: options.email.github,
-					emailNpm: options.email.npm,
+					guide: options.guide.href,
+					guideTitle: options.guide.title,
 			  }
-			: { email: undefined }),
+			: { guide: undefined }),
 		...(options.logo
 			? {
 					logo: options.logo.src,

Diff for: src/shared/options/args.ts

@@ -29,6 +29,8 @@ export const allArgOptions = {
 	"exclude-renovate": { type: "boolean" },
 	"exclude-tests": { type: "boolean" },
 	funding: { type: "string" },
+	guide: { type: "string" },
+	"guide-title": { type: "string" },
 	keywords: { multiple: true, type: "string" },
 	logo: { type: "string" },
 	"logo-alt": { type: "string" },

Diff for: src/shared/options/createOptionDefaults/index.ts

@@ -10,6 +10,7 @@ import { tryCatchAsync } from "../../tryCatchAsync.js";
 import { tryCatchLazyValueAsync } from "../../tryCatchLazyValueAsync.js";
 import { PromptedOptions } from "../../types.js";
 import { parsePackageAuthor } from "./parsePackageAuthor.js";
+import { readDefaultsFromDevelopment } from "./readDefaultsFromDevelopment.js";
 import { readDefaultsFromReadme } from "./readDefaultsFromReadme.js";
 
 export function createOptionDefaults(promptedOptions?: PromptedOptions) {
@@ -57,6 +58,7 @@ export function createOptionDefaults(promptedOptions?: PromptedOptions) {
 			promptedOptions?.repository ??
 			(await gitDefaults())?.name ??
 			(await packageData()).name,
+		...readDefaultsFromDevelopment(),
 		...readDefaultsFromReadme(),
 	};
 }

Diff for: src/shared/options/createOptionDefaults/readDefaultsFromDevelopment.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { readDefaultsFromDevelopment } from "./readDefaultsFromDevelopment.js";
+
+const mockReadFileSafe = vi.fn();
+
+vi.mock("../../readFileSafe.js", () => ({
+	get readFileSafe() {
+		return mockReadFileSafe;
+	},
+}));
+
+describe("readDefaultsFromDevelopment", () => {
+	describe("guide", () => {
+		it("defaults to undefined when .github/DEVELOPMENT.md cannot be found", async () => {
+			mockReadFileSafe.mockResolvedValue("");
+
+			const guide = await readDefaultsFromDevelopment().guide();
+
+			expect(guide).toBeUndefined();
+		});
+
+		it("reads guide when it exists", async () => {
+			mockReadFileSafe.mockResolvedValue(`# Development
+
+> If you'd like a more guided walkthrough, see [Contributing to a create-typescript-app Repository](https://www.joshuakgoldberg.com/blog/contributing-to-a-create-typescript-app-repository).
+> It'll walk you through the common activities you'll need to contribute.
+`);
+
+			const guide = await readDefaultsFromDevelopment().guide();
+
+			expect(guide).toBe(
+				"https://www.joshuakgoldberg.com/blog/contributing-to-a-create-typescript-app-repository",
+			);
+		});
+	});
+
+	describe("guideTitle", () => {
+		it("defaults to undefined when .github/DEVELOPMENT.md cannot be found", async () => {
+			mockReadFileSafe.mockResolvedValue("");
+
+			const guideTitle = await readDefaultsFromDevelopment().guideTitle();
+
+			expect(guideTitle).toBeUndefined();
+		});
+
+		it("reads guideTitle when it exists", async () => {
+			mockReadFileSafe.mockResolvedValue(`# Development
+
+> If you'd like a more guided walkthrough, see [Contributing to a create-typescript-app Repository](https://www.joshuakgoldberg.com/blog/contributing-to-a-create-typescript-app-repository).
+> It'll walk you through the common activities you'll need to contribute.
+`);
+
+			const guideTitle = await readDefaultsFromDevelopment().guideTitle();
+
+			expect(guideTitle).toBe(
+				"Contributing to a create-typescript-app Repository",
+			);
+		});
+	});
+});

Diff for: src/shared/options/createOptionDefaults/readDefaultsFromDevelopment.ts

@@ -0,0 +1,20 @@
+import lazyValue from "lazy-value";
+
+import { readFileSafe } from "../../readFileSafe.js";
+
+export function readDefaultsFromDevelopment() {
+	const development = lazyValue(
+		async () => await readFileSafe(".github/DEVELOPMENT.md", ""),
+	);
+
+	const guideTag = lazyValue(async () =>
+		(await development()).match(
+			/> .*guided walkthrough, see \[((?!\[).+)\]\((.+)\)/i,
+		),
+	);
+
+	return {
+		guide: async () => (await guideTag())?.[2],
+		guideTitle: async () => (await guideTag())?.[1],
+	};
+}

Diff for: src/shared/options/optionsSchema.ts

@@ -39,6 +39,8 @@ export const optionsSchemaShape = {
 	excludeRenovate: z.boolean().optional(),
 	excludeTests: z.boolean().optional(),
 	funding: z.string().optional(),
+	guide: z.string().url().optional(),
+	guideTitle: z.string().optional(),
 	keywords: z.array(z.string()).optional(),
 	logo: z.string().optional(),
 	logoAlt: z.string().optional(),

Diff for: src/shared/options/readOptions.test.ts

@@ -31,6 +31,8 @@ const emptyOptions = {
 	excludeRenovate: undefined,
 	excludeTests: undefined,
 	funding: undefined,
+	guide: undefined,
+	logo: undefined,
 	offline: undefined,
 	owner: undefined,
 	preserveGeneratedFrom: false,
@@ -227,6 +229,62 @@ describe("readOptions", () => {
 		});
 	});
 
+	it("returns a cancellation when the guide title prompt is cancelled", async () => {
+		mockDetectEmailRedundancy.mockReturnValue(false);
+		mockGetPrefillOrPromptedOption
+			.mockImplementationOnce(() => "MockOwner")
+			.mockImplementationOnce(() => "MockRepository")
+			.mockImplementationOnce(() => "Mock description.")
+			.mockImplementationOnce(() => "Mock Title")
+			.mockImplementation(() => undefined);
+		mockEnsureRepositoryExists.mockResolvedValue({
+			github: mockOptions.github,
+			repository: mockOptions.repository,
+		});
+
+		expect(
+			await readOptions(["--guide", "https://example.com"], "create"),
+		).toStrictEqual({
+			cancelled: true,
+			options: {
+				...emptyOptions,
+				description: "Mock description.",
+				guide: "https://example.com",
+				owner: "MockOwner",
+				repository: "MockRepository",
+				title: "Mock Title",
+			},
+		});
+	});
+
+	it("returns a cancellation when the guide alt prompt is cancelled", async () => {
+		mockDetectEmailRedundancy.mockReturnValue(false);
+		mockGetPrefillOrPromptedOption
+			.mockImplementationOnce(() => "MockOwner")
+			.mockImplementationOnce(() => "MockRepository")
+			.mockImplementationOnce(() => "Mock description.")
+			.mockImplementationOnce(() => "Mock Title")
+			.mockImplementation(() => undefined);
+		mockEnsureRepositoryExists.mockResolvedValue({
+			github: mockOptions.github,
+			repository: mockOptions.repository,
+		});
+
+		expect(
+			await readOptions(["--guide", "https://example.com"], "create"),
+		).toStrictEqual({
+			cancelled: true,
+			options: {
+				...emptyOptions,
+				description: "Mock description.",
+				guide: "https://example.com",
+				owner: "MockOwner",
+				repository: "MockRepository",
+				title: "Mock Title",
+			},
+		});
+	});
+
 	it("returns a cancellation when the logo alt prompt is cancelled", async () => {
 		mockDetectEmailRedundancy.mockReturnValue(false);
 		mockGetPrefillOrPromptedOption
@@ -244,6 +302,7 @@ describe("readOptions", () => {
 			options: {
 				...emptyOptions,
 				description: "Mock description.",
+				logo: "logo.svg",
 				owner: "MockOwner",
 				repository: "MockRepository",
 			},
@@ -307,6 +366,10 @@ describe("readOptions", () => {
 			...mockOptions,
 		});
 		mockGetPrefillOrPromptedOption.mockImplementation(() => "mock");
+		mockEnsureRepositoryExists.mockResolvedValue({
+			github: mockOptions.github,
+			repository: mockOptions.repository,
+		});
 
 		expect(
 			await readOptions(["--base", mockOptions.base], "create"),
@@ -320,6 +383,39 @@ describe("readOptions", () => {
 		});
 	});
 
+	it("returns success options when --base is valid with all optional options", async () => {
+		mockAugmentOptionsWithExcludes.mockResolvedValue({
+			...emptyOptions,
+			...mockOptions,
+		});
+		mockGetPrefillOrPromptedOption.mockImplementation(() => "mock");
+		mockEnsureRepositoryExists.mockResolvedValue({
+			github: mockOptions.github,
+			repository: mockOptions.repository,
+		});
+
+		expect(
+			await readOptions(
+				[
+					"--base",
+					mockOptions.base,
+					"--guide",
+					"https://example.com",
+					"--logo",
+					"logo.svg",
+				],
+				"create",
+			),
+		).toStrictEqual({
+			cancelled: false,
+			github: mockOptions.github,
+			options: {
+				...emptyOptions,
+				...mockOptions,
+			},
+		});
+	});
+
 	it("returns cancelled options when augmentOptionsWithExcludes returns undefined", async () => {
 		mockAugmentOptionsWithExcludes.mockResolvedValue(undefined);
 		mockGetPrefillOrPromptedOption.mockImplementation(() => "mock");
@@ -417,6 +513,7 @@ describe("readOptions", () => {
 					github: "mock",
 					npm: "mock",
 				},
+				guide: undefined,
 				logo: undefined,
 				mode: "create",
 				offline: true,