feat: add --offline mode (#879)

## PR Checklist

- [x] Addresses an existing open issue: fixes #878
- [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 `--offline` flag that skips running scripts. That includes a
timeout for `npm whoami`, as I've found that command to hang when I'm on
an airplane.

Also corrects a bit of the logic around adding the user as a
contributor, while I'm in the area. And fixes up unit tests around that.

docs/Options.md

@@ -105,10 +105,12 @@ npx create-typescript-app --exclude-lint-package-json --exclude-lint-packages --
 
 ### Skipping API Calls
 
+> Alternately, see [Offline Mode](#offline-mode) to skip API calls without disabling features
+
 You can prevent the migration script from making some network-based changes using any or all of the following CLI flags:
 
 - `--skip-all-contributors-api` _(`boolean`)_: Skips network calls that fetch all-contributors data from GitHub
-  - This flag does nothing if `--skip-all-contributors` was specified.
+  - This flag does nothing if `--exclude-all-contributors` was specified.
 - `--skip-github-api` _(`boolean`)_: Skips calling to GitHub APIs.
 - `--skip-install` _(`boolean`)_: Skips installing all the new template packages with `pnpm`.
 
@@ -133,3 +135,16 @@ For example, providing all local change skip flags:
 ```shell
 npx create-typescript-app --skip-removal --skip-restore --skip-uninstall
 ```
+
+## Offline Mode
+
+You can run `create-typescript-app` in an "offline" mode with `--offline`.
+Doing so will:
+
+- Enable `--exclude-all-contributors-api` and `--skip-github-api`
+- Skip network calls when setting up contributors
+- Run pnpm commands with pnpm's `--offline` mode
+
+```shell
+npx create-typescript-app --offline
+```

src/create/createWithOptions.ts

@@ -29,7 +29,7 @@ export async function createWithOptions({ github, options }: GitHubAndOptions) {
 
 	if (!options.excludeAllContributors && !options.skipAllContributorsApi) {
 		await withSpinner("Adding contributors to table", async () => {
-			await addToolAllContributors(options.owner);
+			await addToolAllContributors(options);
 		});
 	}
 

src/initialize/initializeWithOptions.ts

@@ -35,7 +35,7 @@ export async function initializeWithOptions({
 
 	if (!options.excludeAllContributors) {
 		await withSpinner("Updating existing contributor details", async () => {
-			await addOwnerAsAllContributor(options.owner);
+			await addOwnerAsAllContributor(options);
 		});
 	}
 
@@ -50,9 +50,8 @@ export async function initializeWithOptions({
 	}
 
 	if (!options.skipUninstall) {
-		await withSpinner(
-			"Uninstalling initialization-only packages",
-			uninstallPackages,
+		await withSpinner("Uninstalling initialization-only packages", async () =>
+			uninstallPackages(options.offline),
 		);
 	}
 

src/shared/getGitHubUserAsAllContributor.test.ts

@@ -0,0 +1,98 @@
+import chalk from "chalk";
+import { SpyInstance, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { getGitHubUserAsAllContributor } from "./getGitHubUserAsAllContributor.js";
+
+const mock$ = vi.fn();
+
+vi.mock("execa", () => ({
+	get $() {
+		return mock$;
+	},
+}));
+
+let mockConsoleWarn: SpyInstance;
+
+const owner = "TestOwner";
+
+describe("getGitHubUserAsAllContributor", () => {
+	beforeEach(() => {
+		mockConsoleWarn = vi
+			.spyOn(console, "warn")
+			.mockImplementation(() => undefined);
+	});
+
+	it("defaults to owner with a log when options.offline is true", async () => {
+		const actual = await getGitHubUserAsAllContributor({
+			offline: true,
+			owner,
+		});
+
+		expect(actual).toEqual(owner);
+		expect(mockConsoleWarn).toHaveBeenCalledWith(
+			chalk.gray(
+				`Skipping populating all-contributors contributions for TestOwner because in --offline mode.`,
+			),
+		);
+	});
+
+	it("uses the user from gh api user when it succeeds", async () => {
+		const login = "gh-api-user";
+
+		mock$.mockResolvedValueOnce({
+			stdout: JSON.stringify({ login }),
+		});
+
+		await getGitHubUserAsAllContributor({ owner });
+
+		expect(mockConsoleWarn).not.toHaveBeenCalled();
+		expect(mock$.mock.calls).toMatchInlineSnapshot(`
+			[
+			  [
+			    [
+			      "gh api user",
+			    ],
+			  ],
+			  [
+			    [
+			      "npx -y all-contributors-cli@6.25 add ",
+			      " ",
+			      "",
+			    ],
+			    "gh-api-user",
+			    "code,content,doc,ideas,infra,maintenance,projectManagement,tool",
+			  ],
+			]
+		`);
+	});
+
+	it("defaults the user to the owner when gh api user fails", async () => {
+		mock$.mockRejectedValueOnce({});
+
+		await getGitHubUserAsAllContributor({ owner });
+
+		expect(mockConsoleWarn).toHaveBeenCalledWith(
+			chalk.gray(
+				`Couldn't authenticate GitHub user, falling back to the provided owner name '${owner}'.`,
+			),
+		);
+		expect(mock$.mock.calls).toMatchInlineSnapshot(`
+			[
+			  [
+			    [
+			      "gh api user",
+			    ],
+			  ],
+			  [
+			    [
+			      "npx -y all-contributors-cli@6.25 add ",
+			      " ",
+			      "",
+			    ],
+			    "TestOwner",
+			    "code,content,doc,ideas,infra,maintenance,projectManagement,tool",
+			  ],
+			]
+		`);
+	});
+});

src/shared/getGitHubUserAsAllContributor.ts

@@ -1,21 +1,35 @@
 import chalk from "chalk";
 import { $ } from "execa";
 
+import { Options } from "./types.js";
+
 interface GhUserOutput {
 	login: string;
 }
 
-export async function getGitHubUserAsAllContributor(owner: string) {
+export async function getGitHubUserAsAllContributor(
+	options: Pick<Options, "offline" | "owner">,
+) {
+	if (options.offline) {
+		console.warn(
+			chalk.gray(
+				`Skipping populating all-contributors contributions for ${options.owner} because in --offline mode.`,
+			),
+		);
+		return options.owner;
+	}
+
 	let user: string;
+
 	try {
 		user = (JSON.parse((await $`gh api user`).stdout) as GhUserOutput).login;
 	} catch {
 		console.warn(
 			chalk.gray(
-				`Couldn't authenticate GitHub user, falling back to the provided owner name '${owner}'.`,
+				`Couldn't authenticate GitHub user, falling back to the provided owner name '${options.owner}'.`,
 			),
 		);
-		user = owner;
+		user = options.owner;
 	}
 
 	const contributions = [

src/shared/options/args.ts

@@ -30,6 +30,7 @@ export const allArgOptions = {
 	logo: { type: "string" },
 	"logo-alt": { type: "string" },
 	mode: { type: "string" },
+	offline: { type: "boolean" },
 	owner: { type: "string" },
 	repository: { type: "string" },
 	"skip-all-contributors-api": { type: "boolean" },

src/shared/options/augmentOptionsWithExcludes.test.ts

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

src/shared/options/optionsSchema.ts

@@ -44,6 +44,7 @@ export const optionsSchemaShape = {
 	mode: z
 		.union([z.literal("create"), z.literal("initialize"), z.literal("migrate")])
 		.optional(),
+	offline: z.boolean().optional(),
 	owner: z.string().optional(),
 	repository: z.string().optional(),
 	skipAllContributorsApi: z.boolean().optional(),

src/shared/options/readOptions.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it, vi } from "vitest";
 import z from "zod";
 
+import { Options } from "../types.js";
 import { optionsSchemaShape } from "./optionsSchema.js";
 import { readOptions } from "./readOptions.js";
 
@@ -30,6 +31,7 @@ const emptyOptions = {
 	excludeRenovate: undefined,
 	excludeTests: undefined,
 	funding: undefined,
+	offline: undefined,
 	owner: undefined,
 	repository: undefined,
 	skipAllContributorsApi: undefined,
@@ -59,7 +61,6 @@ vi.mock("./augmentOptionsWithExcludes.js", () => ({
 	get augmentOptionsWithExcludes() {
 		return mockAugmentOptionsWithExcludes;
 	},
-	// return { ...emptyOptions, ...mockOptions };
 }));
 
 const mockDetectEmailRedundancy = vi.fn();
@@ -317,4 +318,41 @@ describe("readOptions", () => {
 			},
 		});
 	});
+
+	it("skips API calls when --offline is true", async () => {
+		mockAugmentOptionsWithExcludes.mockImplementation((options: Options) => ({
+			...emptyOptions,
+			...mockOptions,
+			...options,
+		}));
+		mockGetPrefillOrPromptedOption.mockImplementation(() => "mock");
+		mockEnsureRepositoryExists.mockResolvedValue({
+			github: mockOptions.github,
+			repository: mockOptions.repository,
+		});
+
+		expect(
+			await readOptions(["--base", mockOptions.base, "--offline"], "create"),
+		).toStrictEqual({
+			cancelled: false,
+			github: mockOptions.github,
+			options: {
+				...emptyOptions,
+				...mockOptions,
+				access: "public",
+				description: "mock",
+				email: {
+					github: "mock",
+					npm: "mock",
+				},
+				logo: undefined,
+				mode: "create",
+				offline: true,
+				owner: "mock",
+				skipAllContributorsApi: true,
+				skipGitHubApi: true,
+				title: "mock",
+			},
+		});
+	});
 });

src/shared/options/readOptions.ts

@@ -75,10 +75,12 @@ export async function readOptions(
 		excludeRenovate: values["exclude-renovate"],
 		excludeTests: values["unit-tests"],
 		funding: values.funding,
+		offline: values.offline,
 		owner: values.owner,
 		repository: values.repository,
-		skipAllContributorsApi: values["skip-all-contributors-api"],
-		skipGitHubApi: values["skip-github-api"],
+		skipAllContributorsApi:
+			values["skip-all-contributors-api"] ?? values.offline,
+		skipGitHubApi: values["skip-github-api"] ?? values.offline,
 		skipInstall: values["skip-install"],
 		skipRemoval: values["skip-removal"],
 		skipRestore: values["skip-restore"],
@@ -132,7 +134,7 @@ export async function readOptions(
 	}
 
 	const { github, repository } = await ensureRepositoryExists(
-		values["skip-github-api"]
+		options.skipGitHubApi
 			? undefined
 			: await withSpinner("Checking GitHub authentication", getGitHub),
 		{

src/shared/types.ts

@@ -62,6 +62,7 @@ export interface Options {
 	funding?: string;
 	logo: OptionsLogo | undefined;
 	mode: Mode;
+	offline?: boolean;
 	owner: string;
 	repository: string;
 	skipAllContributorsApi?: boolean;