feat(javascript-web): keep a lockfile-less site with a root index.html 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, reached only after the existing lockfile check declines, that
claims the project when index.html sits in the ROOT and no server framework is
in dependencies. Root-only matters: the existing hasIndexHtml helper globs six
levels deep, which is fine alongside a lockfile and far too loose deciding
alone, and would pull in a Node library with a docs/index.html. dependencies
and not devDependencies, since a static site may keep a server around to
preview itself locally.

Sites whose index.html lives under public/ or dist/ are left to javascript_node:
without a lockfile that shape is indistinguishable from a server's asset
directory. A site with no package.json at all also stays unclaimed, since
PostHog/posthog.com#18390 routes those users to the JS snippet from the docs.
Both limits are pinned as tests.

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,20 @@ 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 in
+      // `dependencies`. A site under `public/` or `dist/` is left alone —
+      // that shape is indistinguishable from a server's asset directory.
+      const declaresServer = SERVER_PACKAGES.some(
+        (pkg) => packageJson?.dependencies?.[pkg] !== undefined,
+      );
+      if (hasRootIndexHtml(options) && !declaresServer) {
+        return true;
+      }
+
       // Otherwise → Node/Backend (handled by javascriptNode fallback)
       return false;
     },

src/frameworks/javascript-web/utils.ts

@@ -32,6 +32,34 @@ export const FRAMEWORK_PACKAGES = [
   '@sveltejs/kit',
 ] as const;
 
+/**
+ * Packages that mean the project serves requests rather than shipping a browser
+ * bundle. Checked against `dependencies` only — a static site may well keep a
+ * server in `devDependencies` to preview itself locally, and that shouldn't
+ * read as a backend.
+ */
+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,107 @@ 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 server kept in devDependencies to preview a site is not read as a backend', async () => {
+    const opts = project({
+      'package.json': JSON.stringify({
+        name: 'portfolio',
+        devDependencies: { express: '^4' },
+      }),
+      'index.html': '<!doctype html><html></html>',
+    });
+    await expect(detectFramework(opts.installDir)).resolves.toBe(
+      Integration.javascript_web,
+    );
+  });
+
+  // Known limit: indistinguishable from a server's asset directory without a
+  // lockfile, so it is left to javascript_node rather than guessed at.
+  test('a site whose index.html lives under public/ is not claimed without a lockfile', async () => {
+    const opts = project({
+      'package.json': JSON.stringify({ name: 'site' }),
+      '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")',