@hover-dev/cli 0.3.0 → 0.3.2

package/dist/frameworks.d.ts

@@ -15,7 +15,7 @@
  * `configCandidates` is the list of filenames the mutator will look for,
  * in priority order. The first one that exists in cwd wins.
  */
-export type FrameworkId = 'astro' | 'nuxt' | 'webpack' | 'vite';
+export type FrameworkId = 'astro' | 'nuxt' | 'next' | 'webpack' | 'vite';
 export interface Framework {
     /** Short id used as the --<id> CLI flag and the `Detected: <id>` output. */
     id: FrameworkId;

package/dist/frameworks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frameworks.d.ts","sourceRoot":"","sources":["../src/frameworks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAEhE,MAAM,WAAW,SAAS;IACxB,4EAA4E;IAC5E,EAAE,EAAE,WAAW,CAAC;IAChB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB;yDACqD;IACrD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,EAiCjC,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAExE"}
+{"version":3,"file":"frameworks.d.ts","sourceRoot":"","sources":["../src/frameworks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,CAAC;AAEzE,MAAM,WAAW,SAAS;IACxB,4EAA4E;IAC5E,EAAE,EAAE,WAAW,CAAC;IAChB,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,YAAY,EAAE,MAAM,CAAC;IACrB;yDACqD;IACrD,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,4EAA4E;IAC5E,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,EAAE,SAAS,EAiDjC,CAAC;AAEF,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,WAAW,GAAG,SAAS,GAAG,SAAS,CAExE"}

package/dist/frameworks.js

@@ -23,14 +23,30 @@ export const FRAMEWORKS = [
         detectDeps: ['nuxt'],
         configCandidates: ['nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs'],
     },
+    {
+        id: 'next',
+        label: 'Next.js',
+        hoverPackage: '@hover-dev/next',
+        // Must check before `webpack` — Next 16+ defaults to Turbopack, and a
+        // Next project's `next` dep should land on `@hover-dev/next`, not the
+        // webpack plugin (which only covers `next dev --webpack`).
+        detectDeps: ['next'],
+        // `.mjs` and `.js` first because Next loads them via native `import()`
+        // and our `mutateNext` can magicast them in place. `.ts` is checked
+        // last and triggers a `manual` result that tells the user to rename to
+        // `.mjs` first — Next loads `.ts` configs through a CJS require step
+        // that can't resolve `@hover-dev/next`'s ESM-only `exports` map.
+        configCandidates: ['next.config.mjs', 'next.config.js', 'next.config.ts'],
+    },
     {
         id: 'webpack',
         label: 'Webpack',
         hoverPackage: 'webpack-plugin-hover',
-        // `webpack-cli` is the user-facing wrapper; `next` ships its own webpack
-        // (and our plugin works under `next dev --webpack`). Pure `webpack` as a
+        // `webpack-cli` is the user-facing wrapper for vanilla webpack-dev-server,
+        // Rspack / Rsbuild, CRA, Vue CLI. We no longer detect on `next` here —
+        // Next projects route to `@hover-dev/next` above. Pure `webpack` as a
         // transitive dep is too noisy to detect on.
-        detectDeps: ['webpack-cli', 'next'],
+        detectDeps: ['webpack-cli'],
         configCandidates: ['webpack.config.js', 'webpack.config.mjs', 'webpack.config.ts'],
     },
     {

package/dist/index.js

@@ -50,13 +50,14 @@ Usage:
   npx @hover-dev/cli add --vite       ${dim('# force a specific bundler')}
   npx @hover-dev/cli add --astro
   npx @hover-dev/cli add --nuxt
+  npx @hover-dev/cli add --next
   npx @hover-dev/cli add --webpack
   npx @hover-dev/cli add --dry-run    ${dim('# show what would happen, change nothing')}
   npx @hover-dev/cli --help
   npx @hover-dev/cli --version
 
 What it does:
-  1. Detects your bundler (Vite / Astro / Nuxt / Webpack) from package.json.
+  1. Detects your bundler (Vite / Astro / Nuxt / Next / Webpack) from package.json.
   2. Detects your package manager (pnpm / yarn / bun / npm) from your lockfile.
   3. Installs the matching Hover integration as a dev dependency.
   4. Adds the plugin/integration to your config file.
@@ -79,7 +80,7 @@ async function runAdd(args) {
     if (!framework) {
         err(`Couldn't detect a supported bundler in package.json.`);
         info(`Supported: ${FRAMEWORKS.map(f => f.id).join(', ')}.`);
-        info(`Force one with --vite / --astro / --nuxt / --webpack.`);
+        info(`Force one with --vite / --astro / --nuxt / --next / --webpack.`);
         return 1;
     }
     if (args.framework) {
@@ -127,6 +128,27 @@ async function runAdd(args) {
             console.log(result.instructions);
             break;
     }
+    // Next.js needs one extra manual step the CLI cannot safely do: render
+    // `<HoverScript />` in `app/layout.tsx`. Modifying JSX in user code with
+    // ASTs invites whitespace drift and Server Component shape surprises;
+    // the instruction is short, so we print it and let the human paste it.
+    if (framework.id === 'next' && result.kind === 'ok' && !result.alreadyWired) {
+        info(`One last step — add ${cyan('<HoverScript />')} to your ${cyan('app/layout.tsx')}:`);
+        console.log(`
+  import { HoverScript } from '@hover-dev/next';
+
+  export default function RootLayout({ children }) {
+    return (
+      <html>
+        <body>
+          {children}
+          <HoverScript />
+        </body>
+      </html>
+    );
+  }
+`);
+    }
     spark(`Done. Run your dev server and click the floating ✨.`);
     return 0;
 }

package/dist/mutate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mutate.d.ts","sourceRoot":"","sources":["../src/mutate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CA+B/F;AAoHD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAiC1D"}
+{"version":3,"file":"mutate.d.ts","sourceRoot":"","sources":["../src/mutate.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,IAAI,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,OAAO,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACxD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5D;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAiC/F;AAuRD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,WAAW,GAAG,MAAM,CAmD1D"}

package/dist/mutate.js

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { builders, loadFile, writeFile } from 'magicast';
 /**
@@ -26,6 +26,8 @@ export async function mutateConfig(rootDir, framework) {
                 return await mutateAstro(configPath);
             case 'nuxt':
                 return await mutateNuxt(configPath);
+            case 'next':
+                return await mutateNext(configPath, rootDir);
             case 'webpack':
                 return await mutateWebpack(configPath);
         }
@@ -86,6 +88,160 @@ async function mutateNuxt(configPath) {
     await writeFile(mod, configPath);
     return { kind: 'ok', configPath, alreadyWired: false };
 }
+// ─── Next.js: withHover() wrap + instrumentation.ts merge ──────────────
+/**
+ * Next is the only framework where wiring touches two files:
+ *
+ * 1. `next.config.{ts,mjs,js}` — wrap the user's exported config in
+ *    `withHover(...)`. Idempotent: detect an existing import from
+ *    `@hover-dev/next` and bail.
+ * 2. `instrumentation.ts` — Next's blessed hook for dev-only server-side
+ *    init. We MUST NOT boot the Hover service in `next.config.ts` because
+ *    that file is also loaded by `next build`, which would leak an orphan
+ *    service into CI. The instrumentation hook only fires for
+ *    `next dev` / `next start`.
+ *
+ * The user's `app/layout.tsx` still needs a `<HoverScript />` import after
+ * `{children}` — we can't safely AST-mutate JSX in user code (RSC,
+ * Server Component conventions, formatting), so the CLI prints a manual
+ * one-liner for that step instead of touching the file.
+ */
+async function mutateNext(configPath, rootDir) {
+    // Next 16 loads `.ts` configs through a CJS `transpile-config` step that
+    // does `require()` on the compiled output. That path does NOT honour
+    // the `"import"` condition in ESM-only `exports`, so it cannot load
+    // `@hover-dev/next` (which is ESM). The user has to rename to `.mjs`
+    // (or `.js` with `"type": "module"` in package.json) — `.mjs` goes
+    // through Node's native `import()` which resolves ESM correctly.
+    // Spike + verification in CLAUDE.md "Edge runtime isolation" section.
+    if (configPath.endsWith('.ts')) {
+        return {
+            kind: 'manual',
+            reason: 'next.config.ts cannot load @hover-dev/next (Next loads .ts configs via CJS require, which does not honour ESM exports)',
+            instructions: tsConfigManualInstructions(configPath),
+        };
+    }
+    const mod = await loadFile(configPath);
+    // Step 1: wrap next.config export in withHover(...) — idempotent.
+    let configAlreadyWired = false;
+    if (alreadyImported(mod, '@hover-dev/next')) {
+        configAlreadyWired = true;
+    }
+    else {
+        mod.imports.$add({ from: '@hover-dev/next', imported: 'withHover' });
+        // Wrap whatever the user has as `export default`. Works for plain object,
+        // for `defineConfig({...})` (no-op upstream — Next never had that
+        // helper), and for already-wrapped configs (which we skip via the
+        // `alreadyImported` check above).
+        const previous = mod.exports.default;
+        mod.exports.default = builders.functionCall('withHover', previous);
+        await writeFile(mod, configPath);
+    }
+    // Step 2: instrumentation.ts — create or merge.
+    const instrumentationPath = findOrPickInstrumentationPath(rootDir);
+    const instrumentationAlreadyWired = ensureInstrumentationRegistersHover(instrumentationPath);
+    const alreadyWired = configAlreadyWired && instrumentationAlreadyWired;
+    return { kind: 'ok', configPath, alreadyWired };
+}
+/**
+ * Tailored manual-instructions message for the "you have a next.config.ts"
+ * case. Tells the user exactly what to rename and what to paste, with the
+ * same shape as if the CLI had mutated successfully — so a `mv && paste`
+ * leaves them in the same end state as the auto-magicast path.
+ */
+function tsConfigManualInstructions(configPath) {
+    const tsName = configPath.split('/').pop() ?? 'next.config.ts';
+    const mjsName = tsName.replace(/\.ts$/, '.mjs');
+    return [
+        `Next 16 can't load @hover-dev/next from a ${tsName}.`,
+        `(Next loads .ts configs via a CJS \`require()\` step that can't resolve`,
+        `the ESM-only \`exports\` map @hover-dev/next ships.) Rename to ${mjsName}`,
+        `and paste this:`,
+        ``,
+        `  // ${mjsName}`,
+        `  import { withHover } from '@hover-dev/next';`,
+        ``,
+        `  /** @type {import('next').NextConfig} */`,
+        `  const nextConfig = {`,
+        `    // your existing config`,
+        `  };`,
+        ``,
+        `  export default withHover(nextConfig);`,
+        ``,
+        `Then continue with steps 2 and 3 below.`,
+        ``,
+        manualInstructions('next'),
+    ].join('\n');
+}
+/**
+ * Locate the user's existing instrumentation file, or pick a default path
+ * to create one at. Next looks for `instrumentation.{ts,js}` at the project
+ * root or under `src/`. We prefer `src/` if it exists (consistent with the
+ * Next default scaffold), otherwise drop one at the project root.
+ */
+function findOrPickInstrumentationPath(rootDir) {
+    const candidates = [
+        join(rootDir, 'instrumentation.ts'),
+        join(rootDir, 'instrumentation.js'),
+        join(rootDir, 'src', 'instrumentation.ts'),
+        join(rootDir, 'src', 'instrumentation.js'),
+    ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    const useSrc = existsSync(join(rootDir, 'src'));
+    return useSrc ? join(rootDir, 'src', 'instrumentation.ts') : join(rootDir, 'instrumentation.ts');
+}
+/**
+ * Ensure the instrumentation file calls `register` from
+ * `@hover-dev/next/instrumentation`. Returns true if the file already
+ * had it wired (so the caller can report "already wired" honestly).
+ *
+ * We do this as a plain text edit (not magicast) because instrumentation
+ * files are usually tiny and the user might have written them in one of
+ * many idiomatic shapes (named function, arrow, async). String-level
+ * editing keeps formatting stable; magicast's stringifier would reformat.
+ */
+function ensureInstrumentationRegistersHover(filePath) {
+    const HOVER_IMPORT = "import { register as registerHover } from '@hover-dev/next/instrumentation';";
+    const HOVER_CALL = 'await registerHover();';
+    if (!existsSync(filePath)) {
+        // Greenfield — write a full instrumentation file.
+        const fresh = [
+            HOVER_IMPORT,
+            '',
+            'export async function register() {',
+            `  ${HOVER_CALL}`,
+            '}',
+            '',
+        ].join('\n');
+        writeFileSync(filePath, fresh, 'utf-8');
+        return false;
+    }
+    const existing = readFileSync(filePath, 'utf-8');
+    if (existing.includes('@hover-dev/next/instrumentation')) {
+        return true;
+    }
+    // The file exists but doesn't reference us. We want to (a) add our
+    // import at the top, (b) inject `await registerHover();` into the
+    // user's existing `register` function if we can find it, or
+    // (c) bail to a comment if we can't.
+    let next = `${HOVER_IMPORT}\n${existing}`;
+    const registerMatch = /(export\s+async\s+function\s+register\s*\([^)]*\)\s*\{)/.exec(next);
+    if (registerMatch) {
+        next = next.replace(registerMatch[0], `${registerMatch[0]}\n  ${HOVER_CALL}`);
+    }
+    else {
+        // Couldn't find a function signature to splice into — append a new
+        // register export. If the user already has one in a non-standard
+        // shape Next will warn at startup, which is fine — better than us
+        // silently doing nothing.
+        next = `${next}\n\nexport async function register() {\n  ${HOVER_CALL}\n}\n`;
+    }
+    writeFileSync(filePath, next, 'utf-8');
+    return false;
+}
 // ─── Webpack: new HoverPlugin() in plugins array ────────────────────────
 async function mutateWebpack(configPath) {
     const mod = await loadFile(configPath);
@@ -172,6 +328,24 @@ export function manualInstructions(id) {
                 ``,
                 `  modules: ['@hover-dev/nuxt'],`,
             ].join('\n');
+        case 'next':
+            return [
+                `Three steps for Next.js:`,
+                ``,
+                `1. Wrap your next.config:`,
+                `   import { withHover } from '@hover-dev/next';`,
+                `   export default withHover({ /* your config */ });`,
+                ``,
+                `2. Create instrumentation.ts at your project root:`,
+                `   import { register as registerHover } from '@hover-dev/next/instrumentation';`,
+                `   export async function register() {`,
+                `     await registerHover();`,
+                `   }`,
+                ``,
+                `3. Render <HoverScript /> in your app/layout.tsx, after {children}:`,
+                `   import { HoverScript } from '@hover-dev/next';`,
+                `   // ... inside <body>: {children}<HoverScript />`,
+            ].join('\n');
         case 'webpack':
             return [
                 `Add to your webpack config:`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hover-dev/cli",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "CLI for Hover. Detects your bundler, installs the right Hover integration package, and wires it into your config — one command.",
   "license": "Apache-2.0",
   "author": "Hyperyond",