fix(create): read org manifest from the tarball when the registry strips createConfig (#2063)

Fixes #2062 (thanks @fengmk2 for the invitation to contribute the fix).

## Problem

`vp create @org:name` resolves the org template catalog by fetching the
registry packument and reading `versions[x].createConfig`. Some
registries — GitHub Packages among them — store only the package.json
fields the npm CLI requires, so custom fields like `createConfig` are
**absent from packument version metadata** even though the published
tarball preserves the full package.json byte-for-byte. (Per the [npm
registry
spec](https://github.com/npm/registry/blob/main/docs/responses/package-metadata.md),
full version objects *should* carry all publisher fields — npmjs.org
does — but alternative registries demonstrably don't; the same behavior
was hit by Renovate's npm-hosted presets in
[renovate#8266](renovatebot/renovate#8266),
where GitHub Support confirmed "only the fields required by the NPM CLI
are stored".)

Result: `No \`createConfig.templates\` manifest in @org/create —
\`@org:name\` requires one.` for any org package hosted on such a
registry, no matter how it was published.

## Fix

When the resolved packument version metadata lacks `createConfig`
**entirely** (as opposed to present-but-empty) and advertises
`dist.tarball`, download the tarball and read `createConfig` from its
`package.json` — the one artifact every registry preserves verbatim. New
`readPackageJsonFromTarball` helper in `org-tarball.ts` reuses the
existing `downloadTarball` (streaming + 50 MB cap + auth via
`fetchNpmResource`), `verifyIntegrity`, `parseTarGzip`, and
`normalizeEntryName` (so only the root `package/package.json` matches).

Behavior is unchanged everywhere else:
- packument carries the field → fast path, no extra request (asserted by
a test)
- 404s, `requestedVersion` resolution → unchanged
- `createConfig` present but `templates: []` → still "no manifest",
**no** fallback fetch
- malformed manifests (packument *or* tarball) → still
`OrgManifestSchemaError`

Known trade-off: in the fallback path the tarball can be downloaded
twice (once for the manifest read, once later by
`ensureOrgPackageExtracted` for bundled entries — which has its own
on-disk cache). Kept the diff minimal; happy to thread the bytes into
the extraction cache in this PR or a follow-up if you prefer.

## Validation

- Unit: 3 new tests in `org-manifest.spec.ts` (fallback success with a
real in-test `nanotar.createTarGzip` fixture and matching sha512
integrity; both-sources-missing → null; fast-path fetch-count
assertion); full spec 39/39, package unit suite green, `tsgo` clean, `vp
fmt --check` clean.
- End-to-end: replayed a **real GitHub Packages packument + tarball
pair** (captured from a live scoped package that exhibits the stripping)
through a local registry stub: the release CLI reproduces the failure;
this branch scaffolds successfully, with the tarball's original `sha512`
integrity verified.
- Snap tests: no diffs from this change (`create-generator-monorepo`
timed out in my local environment — its path doesn't involve the
org-manifest code; expecting CI to confirm).

Two adjacent issues from #2062 are intentionally **not** addressed here
to keep the diff focused: the unauthenticated-first fetch not retrying
on 404 (some registries 404 unauthenticated metadata), and the error
message conflating not-found / auth-gated / field-stripped. Happy to
follow up on either.

---------

Co-authored-by: MK (fengmk2) <fengmk2@gmail.com>

Author: hiro-daikin

packages/cli/src/create/__tests__/org-manifest.spec.ts

@@ -1,3 +1,6 @@
+import { createHash } from 'node:crypto';
+
+import { createTarGzip } from 'nanotar';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import {
@@ -138,6 +141,8 @@ describe('filterManifestForContext', () => {
   });
 });
 
+const TARBALL_URL = 'https://registry.npmjs.org/@your-org/create/-/create-1.0.0.tgz';
+
 function packument(
   vpTemplates: unknown,
   extra: Record<string, unknown> = {},
@@ -150,7 +155,7 @@ function packument(
       '1.0.0': {
         version: '1.0.0',
         dist: {
-          tarball: 'https://registry.npmjs.org/@your-org/create/-/create-1.0.0.tgz',
+          tarball: TARBALL_URL,
           integrity: 'sha512-fake',
         },
         createConfig: vpTemplates !== undefined ? { templates: vpTemplates } : undefined,
@@ -171,6 +176,37 @@ function mockFetchJson(body: unknown, status = 200): ReturnType<typeof vi.spyOn>
   } as unknown as Response);
 }
 
+/** Resolve the requested URL from any of `fetch`'s accepted input shapes. */
+function requestUrl(input: string | URL | Request): string {
+  return typeof input === 'string' ? input : input instanceof URL ? input.href : input.url;
+}
+
+/** A real npm-pack-shaped tarball containing only a package.json. */
+async function tarballWith(packageJson: unknown): Promise<Uint8Array> {
+  return await createTarGzip([
+    {
+      name: 'package/package.json',
+      data: new TextEncoder().encode(JSON.stringify(packageJson)),
+    },
+  ]);
+}
+
+/**
+ * Mock fetch to serve the packument for the registry URL and a real tarball
+ * `Response` (with a streamable body) for the `.tgz` URL.
+ */
+function mockFetchPackumentAndTarball(
+  packumentBody: unknown,
+  tarBytes: Uint8Array,
+): ReturnType<typeof vi.spyOn> {
+  return vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+    if (requestUrl(input).endsWith('.tgz')) {
+      return new Response(tarBytes.slice().buffer, { status: 200 });
+    }
+    return new Response(JSON.stringify(packumentBody), { status: 200 });
+  });
+}
+
 describe('readOrgManifest', () => {
   afterEach(() => {
     vi.restoreAllMocks();
@@ -181,8 +217,64 @@ describe('readOrgManifest', () => {
     expect(await readOrgManifest('@your-org')).toBeNull();
   });
 
-  it('returns null when the package has no createConfig.templates field', async () => {
-    mockFetchJson(packument(undefined));
+  it('returns null when neither the packument nor the tarball has createConfig.templates', async () => {
+    // No `createConfig` in the packument triggers the tarball fallback; the
+    // tarball's package.json lacks the field too, so the result is still null.
+    const tarBytes = await tarballWith({ name: '@your-org/create', version: '1.0.0' });
+    const spy = mockFetchPackumentAndTarball(
+      packument(undefined, { dist: { tarball: TARBALL_URL } }),
+      tarBytes,
+    );
+    expect(await readOrgManifest('@your-org')).toBeNull();
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+
+  it('falls back to the tarball package.json when the registry strips createConfig from the packument', async () => {
+    // GitHub Packages (and potentially other registries) omit custom fields
+    // from packument version metadata while the published tarball keeps the
+    // full package.json.
+    const tarBytes = await tarballWith({
+      name: '@your-org/create',
+      version: '1.0.0',
+      createConfig: {
+        templates: [{ name: 'web', description: 'Web app', template: './templates/web' }],
+      },
+    });
+    const integrity = `sha512-${createHash('sha512').update(tarBytes).digest('base64')}`;
+    const spy = mockFetchPackumentAndTarball(
+      packument(undefined, { dist: { tarball: TARBALL_URL, integrity } }),
+      tarBytes,
+    );
+    const manifest = await readOrgManifest('@your-org');
+    expect(manifest).not.toBeNull();
+    expect(manifest?.templates).toEqual([
+      { name: 'web', description: 'Web app', template: './templates/web' },
+    ]);
+    expect(manifest?.tarballUrl).toBe(TARBALL_URL);
+    expect(spy).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not download the tarball when the packument carries the manifest', async () => {
+    const spy = mockFetchJson(
+      packument([{ name: 'web', description: 'Web app', template: './templates/web' }]),
+    );
+    expect(await readOrgManifest('@your-org')).not.toBeNull();
+    expect(spy).toHaveBeenCalledTimes(1);
+  });
+
+  it('treats a tarball probe failure as "no manifest" so passthrough still works', async () => {
+    // A normal @scope/create package (no manifest anywhere) whose tarball
+    // cannot be probed — e.g. a download error — must not turn into a hard
+    // failure; `null` lets the caller fall through to the passthrough path.
+    vi.spyOn(globalThis, 'fetch').mockImplementation(async (input) => {
+      if (requestUrl(input).endsWith('.tgz')) {
+        throw new Error('network unreachable');
+      }
+      return new Response(
+        JSON.stringify(packument(undefined, { dist: { tarball: TARBALL_URL } })),
+        { status: 200 },
+      );
+    });
     expect(await readOrgManifest('@your-org')).toBeNull();
   });
 

packages/cli/src/create/org-manifest.ts

@@ -1,6 +1,7 @@
 import path from 'node:path';
 
 import { fetchNpmResource, getNpmRegistry } from '../utils/npm-config.ts';
+import { readPackageJsonFromTarball } from './org-tarball.ts';
 
 /**
  * A single template entry shared by org manifests (`createConfig.templates`)
@@ -291,6 +292,11 @@ async function fetchPackument(
  * - the package does not exist on the registry (404), or
  * - the package exists but has no `createConfig.templates` field
  *
+ * When the packument version metadata lacks `createConfig` entirely, the
+ * published tarball's package.json is consulted before giving up — some
+ * registries (GitHub Packages among them) strip custom fields from version
+ * metadata while preserving the tarball byte-for-byte.
+ *
  * Throws when:
  * - the `createConfig.templates` field is present but malformed (`OrgManifestSchemaError`), or
  * - the registry request fails for any non-404 reason
@@ -331,7 +337,22 @@ export async function readOrgManifest(
   if (!meta) {
     return null;
   }
-  const templates = validateManifest(meta, packageName);
+  let templates = validateManifest(meta, packageName);
+  if (!templates && meta.createConfig === undefined && meta.dist?.tarball) {
+    // `createConfig` absent (not merely empty) means the registry either
+    // stripped it from the version metadata or the package has no manifest;
+    // probe the published tarball to tell the two apart (see
+    // `readPackageJsonFromTarball`). The probe is best-effort: any
+    // download/integrity/parse failure degrades to "no manifest" so a normal
+    // `@scope/create` package still reaches the passthrough path. A manifest
+    // that IS present but malformed still throws, because `validateManifest`
+    // runs outside the catch.
+    const packageJson = await readPackageJsonFromTarball(
+      meta.dist.tarball,
+      meta.dist.integrity,
+    ).catch(() => null);
+    templates = validateManifest(packageJson, packageName);
+  }
   if (!templates) {
     return null;
   }

packages/cli/src/create/org-tarball.ts

@@ -116,6 +116,38 @@ async function downloadTarball(url: string): Promise<Uint8Array> {
   return bytes;
 }
 
+/**
+ * Download a package tarball and parse its `package/package.json`.
+ *
+ * Some registries (GitHub Packages among them) strip fields they don't
+ * recognize — including `createConfig` — from packument *version metadata*
+ * while preserving the published tarball byte-for-byte. This gives
+ * `readOrgManifest` a fallback source of truth for those registries.
+ *
+ * Returns `null` when the archive contains no `package/package.json`.
+ * Throws on download/integrity failures or unparsable JSON.
+ */
+export async function readPackageJsonFromTarball(
+  tarballUrl: string,
+  integrity?: string,
+): Promise<unknown> {
+  const bytes = await downloadTarball(tarballUrl);
+  verifyIntegrity(bytes, integrity);
+  const entries = await parseTarGzip(bytes);
+  for (const entry of entries) {
+    if (normalizeEntryName(entry.name) !== 'package.json' || !entry.data) {
+      continue;
+    }
+    const text = new TextDecoder().decode(entry.data);
+    try {
+      return JSON.parse(text) as unknown;
+    } catch {
+      throw new Error(`invalid package.json in tarball: ${tarballUrl}`);
+    }
+  }
+  return null;
+}
+
 const STAGING_SUFFIX_PREFIX = '.tmp-';
 
 /**