feat: add back Usage example to create and initialize

.eslintrc.cjs

@@ -37,7 +37,7 @@ module.exports = {
 			files: ["**/*.ts"],
 			parser: "@typescript-eslint/parser",
 			rules: {
-				// These off-by-default rules work well for this repo and we like them on.
+				// These off-/differently-configured-by-default rules work well for this repo and we like them on.
 				"jsdoc/informative-docs": "error",
 				"logical-assignment-operators": [
 					"error",
@@ -53,6 +53,15 @@ module.exports = {
 				"jsdoc/require-returns": "off",
 			},
 		},
+		{
+			files: "**/*.md/*.ts",
+			rules: {
+				"n/no-missing-import": [
+					"error",
+					{ allowModules: ["create-typescript-app"] },
+				],
+			},
+		},
 		{
 			excludedFiles: ["**/*.md/*.ts"],
 			extends: [

script/create-test-e2e.js

@@ -4,7 +4,7 @@ import { strict as assert } from "node:assert";
 const author = "Test Author";
 const description = "Test description.";
 const email = "test@email.com";
-const repository = "test-repository";
+const repository = "create-typescript-app";
 const owner = "TestOwner";
 const title = "Test Title";
 

src/bin/index.ts

@@ -57,7 +57,7 @@ export async function bin(args: string[]) {
 	prompts.log.info(
 		[
 			chalk.italic(`Tip: to run again with the same input values, use:`),
-			chalk.blue(createRerunSuggestion(mode, options)),
+			chalk.blue(createRerunSuggestion(options)),
 		].join(" "),
 	);
 

src/create/createRerunSuggestion.test.ts

@@ -29,6 +29,7 @@ const options = {
 	excludeTests: undefined,
 	funding: undefined,
 	logo: undefined,
+	mode: "create",
 	owner: "TestOwner",
 	repository: "test-repository",
 	skipGitHubApi: true,
@@ -41,37 +42,39 @@ const options = {
 
 describe("createRerunSuggestion", () => {
 	it("includes key-value pairs with mixed truthy and falsy values", () => {
-		const actual = createRerunSuggestion("initialize", options);
+		const actual = createRerunSuggestion(options);
 
 		expect(actual).toMatchInlineSnapshot(
-			'"npx create-typescript-app --mode initialize --base everything --access public --author TestAuthor --create-repository true --description \\"Test description.\\" --email-github github@email.com --email-npm npm@email.com --exclude-compliance true --exclude-contributors true --exclude-lint-jsdoc true --exclude-lint-json true --exclude-lint-knip true --exclude-lint-package-json true --exclude-lint-perfectionist true --owner TestOwner --repository test-repository --skip-github-api true --skip-install true --skip-removal true --title \\"Test Title\\""',
+			'"npx create-typescript-app --mode create --base everything --access public --author TestAuthor --create-repository true --description \\"Test description.\\" --email-github github@email.com --email-npm npm@email.com --exclude-compliance true --exclude-contributors true --exclude-lint-jsdoc true --exclude-lint-json true --exclude-lint-knip true --exclude-lint-package-json true --exclude-lint-perfectionist true --mode create --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("initialize", {
+		const actual = createRerunSuggestion({
 			...options,
 			logo: {
 				alt: "Test alt.",
 				src: "test/src.png",
 			},
+			mode: "initialize",
 		});
 
 		expect(actual).toMatchInlineSnapshot(
-			'"npx create-typescript-app --mode initialize --base everything --access public --author TestAuthor --create-repository true --description \\"Test description.\\" --email-github github@email.com --email-npm npm@email.com --exclude-compliance true --exclude-contributors true --exclude-lint-jsdoc true --exclude-lint-json true --exclude-lint-knip true --exclude-lint-package-json true --exclude-lint-perfectionist true --logo test/src.png --logo-alt \\"Test alt.\\" --owner TestOwner --repository test-repository --skip-github-api true --skip-install true --skip-removal true --title \\"Test Title\\""',
+			'"npx create-typescript-app --mode initialize --base everything --access public --author TestAuthor --create-repository true --description \\"Test description.\\" --email-github github@email.com --email-npm npm@email.com --exclude-compliance true --exclude-contributors true --exclude-lint-jsdoc true --exclude-lint-json true --exclude-lint-knip true --exclude-lint-package-json true --exclude-lint-perfectionist true --logo test/src.png --logo-alt \\"Test alt.\\" --mode initialize --owner TestOwner --repository test-repository --skip-github-api true --skip-install true --skip-removal true --title \\"Test Title\\""',
 		);
 	});
 
 	it("includes exclusions when they exist", () => {
-		const actual = createRerunSuggestion("initialize", {
+		const actual = createRerunSuggestion({
 			...options,
 			excludeCompliance: true,
 			excludeLintMd: true,
 			excludeLintSpelling: true,
+			mode: "initialize",
 		});
 
 		expect(actual).toMatchInlineSnapshot(
-			'"npx create-typescript-app --mode initialize --base everything --access public --author TestAuthor --create-repository true --description \\"Test description.\\" --email-github github@email.com --email-npm npm@email.com --exclude-compliance true --exclude-contributors true --exclude-lint-jsdoc true --exclude-lint-json true --exclude-lint-knip true --exclude-lint-md true --exclude-lint-package-json true --exclude-lint-perfectionist true --exclude-lint-spelling true --owner TestOwner --repository test-repository --skip-github-api true --skip-install true --skip-removal true --title \\"Test Title\\""',
+			'"npx create-typescript-app --mode initialize --base everything --access public --author TestAuthor --create-repository true --description \\"Test description.\\" --email-github github@email.com --email-npm npm@email.com --exclude-compliance true --exclude-contributors true --exclude-lint-jsdoc true --exclude-lint-json true --exclude-lint-knip true --exclude-lint-md true --exclude-lint-package-json true --exclude-lint-perfectionist true --exclude-lint-spelling true --mode initialize --owner TestOwner --repository test-repository --skip-github-api true --skip-install true --skip-removal true --title \\"Test Title\\""',
 		);
 	});
 });

src/create/createRerunSuggestion.ts

@@ -1,4 +1,3 @@
-import { Mode } from "../bin/mode.js";
 import { allArgOptions } from "../shared/options/args.js";
 import { Options } from "../shared/types.js";
 
@@ -8,10 +7,7 @@ function getFirstMatchingArg(key: string) {
 	);
 }
 
-export function createRerunSuggestion(
-	mode: Mode,
-	options: Partial<Options>,
-): string {
+export function createRerunSuggestion(options: Partial<Options>): string {
 	const optionsNormalized = {
 		...options,
 		...(options.email
@@ -42,5 +38,5 @@ export function createRerunSuggestion(
 		})
 		.join(" ");
 
-	return `npx create-typescript-app --mode ${mode} ${args}`;
+	return `npx create-typescript-app --mode ${options.mode} ${args}`;
 }

src/create/createWithOptions.ts

@@ -16,7 +16,7 @@ export async function createWithOptions({ github, options }: GitHubAndOptions) {
 		[
 			"Writing structure",
 			async () => {
-				await writeStructure(options, "create");
+				await writeStructure(options);
 			},
 		],
 		[

src/create/index.ts

@@ -11,7 +11,7 @@ import { createRerunSuggestion } from "./createRerunSuggestion.js";
 import { createWithOptions } from "./createWithOptions.js";
 
 export async function create(args: string[]): Promise<ModeResult> {
-	const inputs = await readOptions(args);
+	const inputs = await readOptions(args, "create");
 	if (inputs.cancelled) {
 		return {
 			code: StatusCodes.Cancelled,
@@ -49,8 +49,9 @@ export async function create(args: string[]): Promise<ModeResult> {
 										"Consider creating a GitHub repository from the new directory:",
 									lines: [
 										`cd ${inputs.options.repository}`,
-										createRerunSuggestion("initialize", {
+										createRerunSuggestion({
 											...inputs.options,
+											mode: "initialize",
 											skipGitHubApi: false,
 											skipInstall: false,
 										}),

src/initialize/index.ts

@@ -7,7 +7,7 @@ import { runOrRestore } from "../shared/runOrRestore.js";
 import { initializeWithOptions } from "./initializeWithOptions.js";
 
 export const initialize: ModeRunner = async (args) => {
-	const inputs = await readOptions(args);
+	const inputs = await readOptions(args, "initialize");
 	if (inputs.cancelled) {
 		return {
 			code: StatusCodes.Cancelled,

src/initialize/initializeWithOptions.ts

@@ -19,7 +19,7 @@ export async function initializeWithOptions({
 		[
 			"Updating local files",
 			async () => {
-				await updateLocalFiles(options, "initialize");
+				await updateLocalFiles(options);
 			},
 		],
 		["Updating README.md", updateReadme],

src/migrate/index.ts

@@ -7,7 +7,7 @@ import { runOrRestore } from "../shared/runOrRestore.js";
 import { migrateWithOptions } from "./migrateWithOptions.js";
 
 export const migrate: ModeRunner = async (args) => {
-	const inputs = await readOptions(args);
+	const inputs = await readOptions(args, "migrate");
 	if (inputs.cancelled) {
 		return {
 			code: StatusCodes.Cancelled,

src/migrate/migrateWithOptions.ts

@@ -19,7 +19,7 @@ export async function migrateWithOptions({
 		[
 			"Writing structure",
 			async () => {
-				await writeStructure(options, "migrate");
+				await writeStructure(options);
 			},
 		],
 		[
@@ -31,7 +31,7 @@ export async function migrateWithOptions({
 		[
 			"Updating local files",
 			async () => {
-				await updateLocalFiles(options, "migrate");
+				await updateLocalFiles(options);
 			},
 		],
 		[

src/shared/options/args.ts

@@ -29,6 +29,7 @@ export const allArgOptions = {
 	funding: { type: "string" },
 	logo: { type: "string" },
 	"logo-alt": { type: "string" },
+	mode: { type: "string" },
 	owner: { type: "string" },
 	repository: { type: "string" },
 	"skip-github-api": { type: "boolean" },

src/shared/options/augmentOptionsWithExcludes.test.ts

@@ -34,6 +34,7 @@ const optionsBase = {
 	excludeTests: undefined,
 	funding: undefined,
 	logo: undefined,
+	mode: "create",
 	owner: "",
 	repository: "",
 	skipGitHubApi: false,

src/shared/options/optionsSchema.ts

@@ -41,6 +41,9 @@ export const optionsSchemaShape = {
 	funding: z.string().optional(),
 	logo: z.string().optional(),
 	logoAlt: z.string().optional(),
+	mode: z
+		.union([z.literal("create"), z.literal("initialize"), z.literal("migrate")])
+		.optional(),
 	owner: z.string().optional(),
 	repository: z.string().optional(),
 	skipGitHubApi: z.boolean().optional(),

src/shared/options/readOptions.test.ts

@@ -112,7 +112,7 @@ describe("readOptions", () => {
 			.object({ base: optionsSchemaShape.base })
 			.safeParse({ base: "b" });
 
-		const actual = await readOptions(["--base", "b"]);
+		const actual = await readOptions(["--base", "b"], "create");
 
 		expect(actual).toStrictEqual({
 			cancelled: true,
@@ -126,7 +126,7 @@ describe("readOptions", () => {
 		mockDetectEmailRedundancy.mockReturnValue(error);
 		mockGetPrefillOrPromptedOption.mockImplementation(() => undefined);
 
-		expect(await readOptions([])).toStrictEqual({
+		expect(await readOptions([], "create")).toStrictEqual({
 			cancelled: true,
 			error,
 			options: {
@@ -139,7 +139,7 @@ describe("readOptions", () => {
 		mockDetectEmailRedundancy.mockReturnValue(false);
 		mockGetPrefillOrPromptedOption.mockImplementation(() => undefined);
 
-		expect(await readOptions([])).toStrictEqual({
+		expect(await readOptions([], "create")).toStrictEqual({
 			cancelled: true,
 			options: {
 				...emptyOptions,
@@ -153,7 +153,7 @@ describe("readOptions", () => {
 			.mockImplementationOnce(() => "MockOwner")
 			.mockImplementation(() => undefined);
 
-		expect(await readOptions([])).toStrictEqual({
+		expect(await readOptions([], "create")).toStrictEqual({
 			cancelled: true,
 			options: {
 				...emptyOptions,
@@ -170,7 +170,7 @@ describe("readOptions", () => {
 			.mockImplementation(() => undefined);
 		mockEnsureRepositoryExists.mockResolvedValue({});
 
-		expect(await readOptions([])).toStrictEqual({
+		expect(await readOptions([], "create")).toStrictEqual({
 			cancelled: true,
 			options: {
 				...emptyOptions,
@@ -191,7 +191,7 @@ describe("readOptions", () => {
 			repository: mockOptions.repository,
 		});
 
-		expect(await readOptions([])).toStrictEqual({
+		expect(await readOptions([], "create")).toStrictEqual({
 			cancelled: true,
 			options: {
 				...emptyOptions,
@@ -213,7 +213,7 @@ describe("readOptions", () => {
 			repository: mockOptions.repository,
 		});
 
-		expect(await readOptions([])).toStrictEqual({
+		expect(await readOptions([], "create")).toStrictEqual({
 			cancelled: true,
 			options: {
 				...emptyOptions,
@@ -236,7 +236,7 @@ describe("readOptions", () => {
 			repository: mockOptions.repository,
 		});
 
-		expect(await readOptions(["--logo", "logo.svg"])).toStrictEqual({
+		expect(await readOptions(["--logo", "logo.svg"], "create")).toStrictEqual({
 			cancelled: true,
 			options: {
 				...emptyOptions,
@@ -260,7 +260,7 @@ describe("readOptions", () => {
 			repository: mockOptions.repository,
 		});
 
-		expect(await readOptions([])).toStrictEqual({
+		expect(await readOptions([], "create")).toStrictEqual({
 			cancelled: true,
 			options: {
 				...emptyOptions,
@@ -286,7 +286,7 @@ describe("readOptions", () => {
 		});
 		mockAugmentOptionsWithExcludes.mockResolvedValue(undefined);
 
-		expect(await readOptions([])).toStrictEqual({
+		expect(await readOptions([], "create")).toStrictEqual({
 			cancelled: true,
 			options: {
 				...emptyOptions,
@@ -305,7 +305,9 @@ describe("readOptions", () => {
 		});
 		mockGetPrefillOrPromptedOption.mockImplementation(() => "mock");
 
-		expect(await readOptions(["--base", mockOptions.base])).toStrictEqual({
+		expect(
+			await readOptions(["--base", mockOptions.base], "create"),
+		).toStrictEqual({
 			cancelled: false,
 			github: mockOptions.github,
 			options: {

src/shared/options/readOptions.ts

@@ -2,6 +2,7 @@ import { parseArgs } from "node:util";
 import { titleCase } from "title-case";
 import { z } from "zod";
 
+import { Mode } from "../../bin/mode.js";
 import { withSpinner } from "../cli/spinners.js";
 import { Options, OptionsLogo } from "../types.js";
 import { allArgOptions } from "./args.js";
@@ -30,7 +31,10 @@ export interface OptionsParseSuccess extends GitHubAndOptions {
 
 export type OptionsParseResult = OptionsParseCancelled | OptionsParseSuccess;
 
-export async function readOptions(args: string[]): Promise<OptionsParseResult> {
+export async function readOptions(
+	args: string[],
+	mode: Mode,
+): Promise<OptionsParseResult> {
 	const defaults = readOptionDefaults();
 	const { values } = parseArgs({
 		args,
@@ -193,6 +197,7 @@ export async function readOptions(args: string[]): Promise<OptionsParseResult> {
 		email: typeof email === "string" ? { github: email, npm: email } : email,
 		funding: options.funding ?? (await defaults.funding()),
 		logo,
+		mode,
 		owner: options.owner,
 		repository,
 		title: options.title,

src/shared/types.ts

@@ -1,3 +1,5 @@
+import { Mode } from "../bin/mode.js";
+
 export interface AllContributorContributor {
 	contributions: string[];
 	login: string;
@@ -59,6 +61,7 @@ export interface Options {
 	excludeTests?: boolean;
 	funding?: string;
 	logo: OptionsLogo | undefined;
+	mode: Mode;
 	owner: string;
 	repository: string;
 	skipGitHubApi?: boolean;

src/steps/finalizeDependencies.test.ts

@@ -41,6 +41,7 @@ const options = {
 	excludeTests: undefined,
 	funding: undefined,
 	logo: undefined,
+	mode: "create",
 	owner: "StubOwner",
 	repository: "stub-repository",
 	skipGitHubApi: false,