feat(javascript-web): keep browser projects without a lockfile off the Node SDK

javascript_web requires a committed lockfile and javascript_node matches any
package.json, so a browser-only project whose lockfile is not committed falls
through to the Node integration and the run installs the server SDK.

Add one branch that runs only after the existing lockfile check declines: claim
the project when index.html sits in the ROOT and no server framework is declared.
Root-only matters — the existing hasIndexHtml helper globs six levels deep, which
is fine alongside a lockfile and far too loose when deciding alone; it would pull
in a Node library with a docs/index.html.

A site with no package.json at all stays unclaimed on purpose — PostHog/posthog.com#18390
routes those users to the JS snippet from the docs, which is the better answer.

Refs #870

Author: Ref34t

src/frameworks/javascript-web/javascript-web-wizard-agent.ts

@@ -8,9 +8,11 @@ import { hasDeclaredDependency } from '@utils/package-json';
 import { tryGetPackageJson } from '@utils/setup-utils';
 import {
   FRAMEWORK_PACKAGES,
+  SERVER_PACKAGES,
   detectJsPackageManager,
   detectBundler,
   hasIndexHtml,
+  hasRootIndexHtml,
   type JavaScriptContext,
 } from './utils';
 import { detectNodePackageManagers } from '@lib/detection/package-manager';
@@ -38,6 +40,10 @@ export const JAVASCRIPT_WEB_AGENT_CONFIG: FrameworkConfig<JavaScriptContext> = {
     detectPackageManager: detectNodePackageManagers,
     detect: async (options) => {
       const packageJson = await tryGetPackageJson(options);
+
+      // A site with no package.json at all is deliberately left unclaimed: the
+      // snippet is the whole integration and there is nothing for the wizard to
+      // do. PostHog/posthog.com#18390 routes those users to it from the docs.
       if (!packageJson) {
         return false;
       }
@@ -73,6 +79,18 @@ export const JAVASCRIPT_WEB_AGENT_CONFIG: FrameworkConfig<JavaScriptContext> = {
         return true;
       }
 
+      // No lockfile. `javascriptNode` matches any package.json, so falling
+      // through here hands a browser-only project the server SDK. Claim it
+      // instead, but only on evidence strong enough to stand without the
+      // lockfile: an index.html in the ROOT (the site's entry point, not a
+      // `docs/` page or a generated report), and no server framework declared.
+      if (
+        hasRootIndexHtml(options) &&
+        !SERVER_PACKAGES.some((pkg) => hasDeclaredDependency(pkg, packageJson))
+      ) {
+        return true;
+      }
+
       // Otherwise → Node/Backend (handled by javascriptNode fallback)
       return false;
     },
@@ -100,9 +118,9 @@ export const JAVASCRIPT_WEB_AGENT_CONFIG: FrameworkConfig<JavaScriptContext> = {
 
   prompts: {
     projectTypeDetection:
-      'This is a JavaScript/TypeScript project. Look for package.json and lockfiles (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb) to confirm.',
+      'This is a browser-side JavaScript/TypeScript project. Look for package.json and lockfiles (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb) to confirm.',
     packageInstallation:
-      'Look for lockfiles to determine the package manager (npm, yarn, pnpm, bun). Do not manually edit package.json.',
+      'Look for lockfiles to determine the package manager (npm, yarn, pnpm, bun). A project without a committed lockfile is still a browser project — install posthog-js with the package manager the project appears to use. Do not manually edit package.json.',
     getAdditionalContextLines: (context) => {
       const lines = [
         `Package manager: ${context.packageManagerName ?? 'unknown'}`,

src/frameworks/javascript-web/utils.ts

@@ -32,6 +32,33 @@ export const FRAMEWORK_PACKAGES = [
   '@sveltejs/kit',
 ] as const;
 
+/**
+ * Packages that mean the project serves requests rather than shipping a browser
+ * bundle. An index.html sitting next to one of these is a server's static asset
+ * directory, not a static site, so `javascript_node` should keep the match.
+ */
+export const SERVER_PACKAGES = [
+  'express',
+  'fastify',
+  'koa',
+  '@nestjs/core',
+  '@hapi/hapi',
+  'hapi',
+  'restify',
+  'h3',
+] as const;
+
+/**
+ * An index.html in the project root — the entry point of a site, as opposed to
+ * a `docs/` page or a generated report deeper in the tree. Used only where a
+ * match has to stand on its own without a lockfile to corroborate it.
+ */
+export function hasRootIndexHtml(
+  options: Pick<WizardRunOptions, 'installDir'>,
+): boolean {
+  return fs.existsSync(path.join(options.installDir, 'index.html'));
+}
+
 /**
  * Detect the JS package manager for the project by checking lockfiles.
  * Reuses the existing package manager detection infrastructure.

src/lib/detection/__tests__/framework.test.ts

@@ -115,6 +115,82 @@ describe('detectFramework (end-to-end over real project dirs)', () => {
     );
   });
 
+  test('a browser project with no committed lockfile is not handed to javascript_node', async () => {
+    const opts = project({
+      'package.json': JSON.stringify({
+        name: 'portfolio',
+        scripts: { build: 'tailwindcss -o dist/style.css' },
+      }),
+      'index.html': '<!doctype html><html></html>',
+    });
+    await expect(detectFramework(opts.installDir)).resolves.toBe(
+      Integration.javascript_web,
+    );
+  });
+
+  test('an Express server with a root index.html stays on javascript_node', async () => {
+    const opts = project({
+      'package.json': JSON.stringify({ dependencies: { express: '^4' } }),
+      'index.html': '<!doctype html><html></html>',
+    });
+    await expect(detectFramework(opts.installDir)).resolves.toBe(
+      Integration.javascriptNode,
+    );
+  });
+
+  test('a Node library with a docs/index.html stays on javascript_node', async () => {
+    const opts = project({
+      'package.json': JSON.stringify({ name: 'lib' }),
+      'src/index.js': 'module.exports = {}',
+      'docs/index.html': '<!doctype html><html></html>',
+    });
+    await expect(detectFramework(opts.installDir)).resolves.toBe(
+      Integration.javascriptNode,
+    );
+  });
+
+  test('a server framework we do not list is still safe if index.html is not at the root', async () => {
+    const opts = project({
+      'package.json': JSON.stringify({ dependencies: { hono: '^4' } }),
+      'public/index.html': '<!doctype html><html></html>',
+    });
+    await expect(detectFramework(opts.installDir)).resolves.toBe(
+      Integration.javascriptNode,
+    );
+  });
+
+  test('a lockfile project keeps matching on a nested index.html (unchanged)', async () => {
+    const opts = project({
+      'package.json': JSON.stringify({ name: 'site' }),
+      'package-lock.json': '{}',
+      'public/index.html': '<!doctype html><html></html>',
+    });
+    await expect(detectFramework(opts.installDir)).resolves.toBe(
+      Integration.javascript_web,
+    );
+  });
+
+  test('a Node project with no frontend signal stays on javascript_node', async () => {
+    const opts = project({
+      'package.json': JSON.stringify({ dependencies: { lodash: '^4' } }),
+      'index.js': 'module.exports = {}',
+    });
+    await expect(detectFramework(opts.installDir)).resolves.toBe(
+      Integration.javascriptNode,
+    );
+  });
+
+  // A site with no package.json is left unclaimed on purpose — the snippet is
+  // the whole integration. PostHog/posthog.com#18390 routes those users to it.
+  test('a hand-written static site is deliberately claimed by nobody', async () => {
+    const opts = project({
+      'index.html': '<!doctype html><html><head></head><body>hi</body></html>',
+      'about.html': '<!doctype html><html></html>',
+      'css/style.css': 'body { color: black }',
+    });
+    await expect(detectFramework(opts.installDir)).resolves.toBeUndefined();
+  });
+
   test('a Kotlin Multiplatform project resolves to kmp', async () => {
     const opts = project({
       'settings.gradle.kts': 'include(":shared")',