fix: cache template tarballs by resolved HEAD sha

Resolving HEAD to a commit sha lets begit key its cache on it and skip
the download entirely on later scaffolds — a warm run is roughly twice
as fast. The lookup goes through api.github.com (60 requests/hour
unauthenticated), so it degrades instead of failing: a throw, a missing
sha, or a lookup slower than 2s all fall back to fetching HEAD from the
archive endpoint uncached.

The live-download tests get a 60s budget. Their earlier intermittent
failures were vitest's 5s default expiring on a cold-cache ~3MB tarball,
not a defect in the code under test.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Tommypop2

packages/create-solid/CHANGELOG.md

@@ -8,7 +8,7 @@
 
   - Template downloads are no longer pinned to a baked-in solidjs/templates commit. Scaffolds come from live HEAD of the default branch, matching the `templates.json` manifest, so upstream template changes and dependency repins reach users without a CLI release.
   - Removed the `SOLID_CLI_TEMPLATES_REF` environment override that shipped in 0.9.0, along with the pin it existed to escape.
-  - Scaffolding still avoids api.github.com, which is rate limited to 60 requests/hour for unauthenticated users: templates are fetched straight from the archive endpoint rather than resolving HEAD to a commit sha first.
+  - HEAD is resolved to a commit sha before downloading so the tarball can be cached under it and reused by later scaffolds. That lookup goes through api.github.com, which is rate limited to 60 requests/hour for unauthenticated users, so any failure — rate limited, offline, slow — falls back to fetching HEAD from the archive endpoint directly, uncached.
   - Solid 2.0 is labelled "Solid 2.0 (RC)" in the project picker now that Solid 2.0 core is a release candidate. It stays listed first but not preselected.
 
 ## 0.9.0

packages/create/CHANGELOG.md

@@ -8,7 +8,7 @@
 
   - Template downloads are no longer pinned to a baked-in solidjs/templates commit. Scaffolds come from live HEAD of the default branch, matching the `templates.json` manifest, so upstream template changes and dependency repins reach users without a CLI release.
   - Removed the `SOLID_CLI_TEMPLATES_REF` environment override that shipped in 0.9.0, along with the pin it existed to escape.
-  - Scaffolding still avoids api.github.com, which is rate limited to 60 requests/hour for unauthenticated users: templates are fetched straight from the archive endpoint rather than resolving HEAD to a commit sha first.
+  - HEAD is resolved to a commit sha before downloading so the tarball can be cached under it and reused by later scaffolds. That lookup goes through api.github.com, which is rate limited to 60 requests/hour for unauthenticated users, so any failure — rate limited, offline, slow — falls back to fetching HEAD from the archive endpoint directly, uncached.
   - Solid 2.0 is labelled "Solid 2.0 (RC)" in the project picker now that Solid 2.0 core is a release candidate. It stays listed first but not preselected.
 
 ## 0.9.0

packages/create/src/utils/download.ts

@@ -2,25 +2,53 @@ import { downloadRepo, GithubFetcher } from "@begit/core";
 
 export const TEMPLATES_REPO = { owner: "solidjs", name: "templates" } as const;
 
+/** A slow commit lookup must not hold up a scaffold — it is only there to enable caching */
+const LATEST_COMMIT_TIMEOUT_MS = 2000;
+
+/**
+ * Resolves HEAD of the templates repo to a commit sha, so begit can key its
+ * tarball cache on it and reuse the download across scaffolds.
+ *
+ * This goes through api.github.com, which is rate limited to 60 requests/hour
+ * for unauthenticated users (the archive endpoint the tarball itself comes from
+ * is not). Every failure — rate limited, offline, timeout, unexpected payload —
+ * resolves to `undefined`, and the caller falls back to fetching HEAD directly.
+ */
+export const latestTemplatesCommit = async (): Promise<string | undefined> => {
+	const lookup = (async () => {
+		try {
+			return await GithubFetcher.fetchLatestCommit(TEMPLATES_REPO);
+		} catch {
+			return undefined;
+		}
+	})();
+	let timer: ReturnType<typeof setTimeout>;
+	const timeout = new Promise<undefined>((resolve) => {
+		timer = setTimeout(() => resolve(undefined), LATEST_COMMIT_TIMEOUT_MS);
+	});
+	return Promise.race([lookup, timeout]).finally(() => clearTimeout(timer));
+};
+
 /**
  * Downloads `subdir` of the solidjs/templates repo into `destination`.
  *
  * No ref is pinned: scaffolds always come from live HEAD of the default branch,
  * matching the `templates.json` manifest, so template updates reach users
- * without a CLI release.
- *
- * `fetch_latest_commit` is off because resolving HEAD to a sha goes through
- * api.github.com, which is rate limited to 60 requests/hour for unauthenticated
- * users — the archive download itself is not. Without a sha there is nothing to
- * key a cache on, so caching is off too and every scaffold fetches a fresh
- * tarball, which is what tracking HEAD means.
+ * without a CLI release. HEAD is resolved to a sha first so begit can cache the
+ * tarball under it and skip the download next time; when that lookup fails we
+ * fetch HEAD directly instead, uncached — slower, but never a broken scaffold.
  */
-export const downloadTemplate = (subdir: string, destination: string) =>
-	downloadRepo(
+export const downloadTemplate = async (subdir: string, destination: string) => {
+	const hash = await latestTemplatesCommit();
+	return downloadRepo(
 		{
-			repo: { ...TEMPLATES_REPO, subdir },
+			repo: { ...TEMPLATES_REPO, subdir, hash },
 			dest: destination,
-			opts: { cache: false, fetch_latest_commit: false },
+			// HEAD is already resolved (or deliberately left unresolved) above, so begit
+			// must not call the API itself. Without a sha there is nothing to key a cache
+			// entry on, so the tarball is discarded rather than left behind unkeyed.
+			opts: { cache: !!hash, fetch_latest_commit: false },
 		},
 		GithubFetcher,
 	);
+};

packages/create/tests/download.test.ts

@@ -0,0 +1,38 @@
+import { afterEach, expect, it, vi } from "vitest";
+import { GithubFetcher } from "@begit/core";
+import { latestTemplatesCommit } from "../src/utils/download";
+
+afterEach(() => {
+	vi.restoreAllMocks();
+	vi.useRealTimers();
+});
+
+it("resolves HEAD to a sha so begit can cache the tarball under it", async () => {
+	vi.spyOn(GithubFetcher, "fetchLatestCommit").mockResolvedValue("c3032d9");
+
+	expect(await latestTemplatesCommit()).toBe("c3032d9");
+});
+
+it("falls back to no sha when the commit lookup throws", async () => {
+	// Offline, DNS failure, or a non-JSON response from the API
+	vi.spyOn(GithubFetcher, "fetchLatestCommit").mockRejectedValue(new Error("fetch failed"));
+
+	expect(await latestTemplatesCommit()).toBeUndefined();
+});
+
+it("falls back to no sha when the API answers without one", async () => {
+	// What a rate-limited response looks like by the time begit is done with it
+	vi.spyOn(GithubFetcher, "fetchLatestCommit").mockResolvedValue(undefined);
+
+	expect(await latestTemplatesCommit()).toBeUndefined();
+});
+
+it("falls back to no sha rather than letting a hanging lookup block the scaffold", async () => {
+	vi.useFakeTimers();
+	vi.spyOn(GithubFetcher, "fetchLatestCommit").mockReturnValue(new Promise(() => {}));
+
+	const resolved = latestTemplatesCommit();
+	await vi.advanceTimersByTimeAsync(2000);
+
+	expect(await resolved).toBeUndefined();
+});

packages/create/tests/template.test.ts

@@ -46,20 +46,32 @@ const expectScaffold = (destination: string) => {
 	expect(readdirSync(join(destination, "src")).length).toBeGreaterThan(0);
 };
 
-it("downloads and extracts the vanilla template", async () => {
-	const destination = scratch("vanilla");
-	const { path, template } = await liveTarget("vanilla");
+// A cold begit cache means pulling the whole templates tarball (~3MB), which does not
+// reliably fit in vitest's 5s default on a slow or contended connection
+const DOWNLOAD_TIMEOUT_MS = 60_000;
 
-	await createVanilla({ template, destination, path }, false);
+it(
+	"downloads and extracts the vanilla template",
+	async () => {
+		const destination = scratch("vanilla");
+		const { path, template } = await liveTarget("vanilla");
 
-	expectScaffold(destination);
-});
+		await createVanilla({ template, destination, path }, false);
 
-it("downloads and extracts the solid-v2 template", async () => {
-	const destination = scratch("solid-v2");
-	const { path, template } = await liveTarget("solid");
+		expectScaffold(destination);
+	},
+	DOWNLOAD_TIMEOUT_MS,
+);
 
-	await createSolidV2({ template, destination, path }, false);
+it(
+	"downloads and extracts the solid-v2 template",
+	async () => {
+		const destination = scratch("solid-v2");
+		const { path, template } = await liveTarget("solid");
 
-	expectScaffold(destination);
-});
+		await createSolidV2({ template, destination, path }, false);
+
+		expectScaffold(destination);
+	},
+	DOWNLOAD_TIMEOUT_MS,
+);