fix: add troubleshooting tips for npm template not found error (#1055)

### Linked issue

resolves #828 

### Description

The behavior when specifying an invalid template name (e.g.,
vite-plus-app) with the vp create command has been improved.

With this update, the CLI now checks the npm registry before executing
the package manager. If the template is not found (HTTP 404 error), it
will display an error message and terminate the process immediately.

---------

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

Author: naokihaba

packages/cli/src/create/templates/remote.ts

@@ -2,6 +2,7 @@ import * as prompts from '@voidzero-dev/vite-plus-prompts';
 import colors from 'picocolors';
 
 import type { WorkspaceInfo } from '../../types/index.js';
+import { checkNpmPackageExists } from '../../utils/package.js';
 import {
   type ExecutionResult,
   formatDlxCommand,
@@ -40,6 +41,18 @@ export async function executeRemoteTemplate(
   } else {
     // TODO: prompt for project name if not provided for degit
     // Template not found - use package manager runner (npx/pnpm dlx/etc.)
+    if (!isGitHubTemplate) {
+      // templateInfo.command is the npm package name (e.g. "create-vite", "@tanstack/create-start")
+      const packageExists = await checkNpmPackageExists(templateInfo.command);
+      if (!packageExists) {
+        if (!silent) {
+          prompts.log.error(
+            `Template "${templateInfo.command}" not found on npm. Run ${yellow('vp create --list')} to see available templates.`,
+          );
+        }
+        return { exitCode: 1 };
+      }
+    }
     result = await runRemoteTemplateCommand(
       workspaceInfo,
       workspaceInfo.rootDir,

packages/cli/src/utils/__tests__/package.spec.ts

@@ -0,0 +1,57 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { checkNpmPackageExists } from '../package.js';
+
+describe('checkNpmPackageExists', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('returns true when package exists (200)', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue({ status: 200, ok: true } as Response);
+    expect(await checkNpmPackageExists('create-vite')).toBe(true);
+  });
+
+  it('returns false when package does not exist (404)', async () => {
+    vi.spyOn(globalThis, 'fetch').mockResolvedValue({ status: 404, ok: false } as Response);
+    expect(await checkNpmPackageExists('create-vite-plus-app')).toBe(false);
+  });
+
+  it('returns true on network error', async () => {
+    vi.spyOn(globalThis, 'fetch').mockRejectedValue(new TypeError('fetch failed'));
+    expect(await checkNpmPackageExists('create-vite')).toBe(true);
+  });
+
+  it('strips version from unscoped package name', async () => {
+    const mockFetch = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue({ status: 200, ok: true } as Response);
+    await checkNpmPackageExists('create-vite@latest');
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://registry.npmjs.org/create-vite',
+      expect.objectContaining({ method: 'HEAD' }),
+    );
+  });
+
+  it('strips version from scoped package name', async () => {
+    const mockFetch = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue({ status: 200, ok: true } as Response);
+    await checkNpmPackageExists('@tanstack/create-start@latest');
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://registry.npmjs.org/@tanstack/create-start',
+      expect.objectContaining({ method: 'HEAD' }),
+    );
+  });
+
+  it('does not strip scope from scoped package without version', async () => {
+    const mockFetch = vi
+      .spyOn(globalThis, 'fetch')
+      .mockResolvedValue({ status: 200, ok: true } as Response);
+    await checkNpmPackageExists('@tanstack/create-start');
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://registry.npmjs.org/@tanstack/create-start',
+      expect.objectContaining({ method: 'HEAD' }),
+    );
+  });
+});

packages/cli/src/utils/package.ts

@@ -63,3 +63,22 @@ export function hasVitePlusDependency(
 ) {
   return Boolean(pkg?.dependencies?.[VITE_PLUS_NAME] || pkg?.devDependencies?.[VITE_PLUS_NAME]);
 }
+
+/**
+ * Check if an npm package exists in the public registry.
+ * Returns true if the package exists or if the check could not be performed (network error, timeout).
+ * Returns false only if the registry definitively responds with 404.
+ */
+export async function checkNpmPackageExists(packageName: string): Promise<boolean> {
+  const atIndex = packageName.indexOf('@', 2);
+  const name = atIndex === -1 ? packageName : packageName.slice(0, atIndex);
+  try {
+    const response = await fetch(`https://registry.npmjs.org/${name}`, {
+      method: 'HEAD',
+      signal: AbortSignal.timeout(3000),
+    });
+    return response.status !== 404;
+  } catch {
+    return true; // Network error or timeout - let the package manager handle it
+  }
+}