@hover-dev/cli 0.3.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Hyperyond Studio
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,61 @@
+# @hover-dev/cli
+
+One-command setup for [Hover](https://github.com/Hyperyond/Hover) — detects your bundler, installs the right integration package, and wires it into your config file.
+
+## Usage
+
+No installation required. `npx` runs the latest published version on demand:
+
+```bash
+npx @hover-dev/cli add
+```
+
+That's it. The CLI:
+
+1. **Reads your `package.json`** to figure out your bundler (Vite, Astro, Nuxt, or Webpack).
+2. **Reads your lockfile** to pick the right package manager (pnpm, yarn, bun, or npm).
+3. **Installs** the matching Hover package as a dev dependency.
+4. **Updates** your config file (`vite.config.ts` / `astro.config.mjs` / `nuxt.config.ts` / `webpack.config.js`) to load the plugin.
+
+Then run your dev server and click the floating ✨ in the bottom-right corner.
+
+## Force a specific bundler
+
+If detection picks the wrong one (e.g. your project has multiple bundlers, or you're starting from a fresh repo), use a flag:
+
+```bash
+npx @hover-dev/cli add --vite        # vite-plugin-hover
+npx @hover-dev/cli add --astro       # @hover-dev/astro
+npx @hover-dev/cli add --nuxt        # @hover-dev/nuxt
+npx @hover-dev/cli add --webpack     # webpack-plugin-hover
+```
+
+## Preview without modifying anything
+
+```bash
+npx @hover-dev/cli add --dry-run
+```
+
+Prints what would be installed + which config file would be modified, then exits without changing anything.
+
+## What if my config file is unusual?
+
+The CLI uses [magicast](https://github.com/unjs/magicast) to safely mutate `defineConfig({ ... })` and bare-object configs. If your config has an unusual shape (re-exported config, conditional logic, etc.), the CLI will:
+
+1. Still install the right Hover package.
+2. Skip the config mutation and print the exact lines you need to paste in.
+
+This is also what happens if you have no config file at all — many projects rely on bundler defaults until they need to customise.
+
+## Use as a project dep (optional)
+
+`npx` is the default and recommended way. If you want to lock the CLI version per-project (e.g. to make a setup command for new teammates), install it as a dev dep:
+
+```bash
+pnpm add -D @hover-dev/cli
+pnpm hover add
+```
+
+## License
+
+Apache-2.0 — same as the rest of Hover.

package/dist/detect.d.ts

@@ -0,0 +1,41 @@
+import { type Framework } from './frameworks.js';
+export interface PackageJson {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+    [key: string]: unknown;
+}
+/**
+ * Locate and parse the user's package.json. Returns the parsed contents +
+ * the absolute directory it lives in (so callers know the project root
+ * for spawning the package manager + resolving config-file paths).
+ *
+ * Walks up from `startDir` looking for `package.json` — this lets the user
+ * run `npx @hover-dev/cli add` from a subdirectory and still target the
+ * project root. Stops at the filesystem root.
+ */
+export declare function readUserPackageJson(startDir?: string): {
+    pkg: PackageJson;
+    rootDir: string;
+} | null;
+/**
+ * Detect which framework the user's package.json signals. Returns the
+ * highest-priority framework whose `detectDeps` overlap with the user's
+ * combined dep tree. Returns null if none match (likely a fresh project
+ * or non-JS repo).
+ */
+export declare function detectFramework(pkg: PackageJson): Framework | null;
+/**
+ * Detect which package manager the user is on by sniffing the lockfile.
+ * Falls back to npm if nothing matches (every Node install has npm), but
+ * prints a warning so the user knows we're guessing.
+ *
+ * Priority is lockfile-first because lockfile commitment is the strongest
+ * signal — `packageManager` field in package.json is a softer hint that
+ * users often forget to update.
+ */
+export type PackageManager = 'pnpm' | 'yarn' | 'bun' | 'npm';
+export declare function detectPackageManager(rootDir: string): {
+    pm: PackageManager;
+    reason: string;
+};
+//# sourceMappingURL=detect.d.ts.map

package/dist/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../src/detect.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAE7D,MAAM,WAAW,WAAW;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,GAAE,MAAsB,GAAG;IAAE,GAAG,EAAE,WAAW,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAgBlH;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CAQlE;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,GAAG,KAAK,CAAC;AAE7D,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG;IAAE,EAAE,EAAE,cAAc,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAoB5F"}

package/dist/detect.js

@@ -0,0 +1,68 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { FRAMEWORKS } from './frameworks.js';
+/**
+ * Locate and parse the user's package.json. Returns the parsed contents +
+ * the absolute directory it lives in (so callers know the project root
+ * for spawning the package manager + resolving config-file paths).
+ *
+ * Walks up from `startDir` looking for `package.json` — this lets the user
+ * run `npx @hover-dev/cli add` from a subdirectory and still target the
+ * project root. Stops at the filesystem root.
+ */
+export function readUserPackageJson(startDir = process.cwd()) {
+    let dir = resolve(startDir);
+    while (true) {
+        const candidate = join(dir, 'package.json');
+        if (existsSync(candidate)) {
+            try {
+                const pkg = JSON.parse(readFileSync(candidate, 'utf-8'));
+                return { pkg, rootDir: dir };
+            }
+            catch {
+                return null;
+            }
+        }
+        const parent = resolve(dir, '..');
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/**
+ * Detect which framework the user's package.json signals. Returns the
+ * highest-priority framework whose `detectDeps` overlap with the user's
+ * combined dep tree. Returns null if none match (likely a fresh project
+ * or non-JS repo).
+ */
+export function detectFramework(pkg) {
+    const allDeps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+    for (const framework of FRAMEWORKS) {
+        for (const dep of framework.detectDeps) {
+            if (dep in allDeps)
+                return framework;
+        }
+    }
+    return null;
+}
+export function detectPackageManager(rootDir) {
+    const lockfileMap = [
+        { file: 'pnpm-lock.yaml', pm: 'pnpm' },
+        { file: 'yarn.lock', pm: 'yarn' },
+        { file: 'bun.lockb', pm: 'bun' },
+        { file: 'bun.lock', pm: 'bun' },
+        { file: 'package-lock.json', pm: 'npm' },
+    ];
+    for (const { file, pm } of lockfileMap) {
+        if (existsSync(join(rootDir, file))) {
+            return { pm, reason: `lockfile ${file}` };
+        }
+    }
+    // Soft hint: explicit `packageManager` field.
+    const pkgRaw = readFileSync(join(rootDir, 'package.json'), 'utf-8');
+    const pkgManagerMatch = /"packageManager"\s*:\s*"(pnpm|yarn|bun|npm)/.exec(pkgRaw);
+    if (pkgManagerMatch) {
+        return { pm: pkgManagerMatch[1], reason: 'packageManager field' };
+    }
+    return { pm: 'npm', reason: 'no lockfile found; defaulting to npm' };
+}

package/dist/frameworks.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Registry of frameworks `@hover-dev/cli` knows how to wire Hover into.
+ *
+ * To add a new framework (e.g. SvelteKit, SolidStart, Qwik, Next-with-Turbopack):
+ * write a new entry here and a matching mutator in `mutate.ts`. Nothing else
+ * in the CLI changes — `detect.ts`, `install.ts`, and the top-level
+ * dispatcher all consume this list generically.
+ *
+ * `detectDeps` is matched against the user's `package.json` `dependencies` +
+ * `devDependencies` keys (and a couple of indirect signals). The order in
+ * the array is the priority order — a Nuxt project legitimately has `vite`
+ * in its dep tree, so Nuxt must check before Vite. `--<framework>` flags
+ * override detection entirely.
+ *
+ * `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 interface Framework {
+    /** Short id used as the --<id> CLI flag and the `Detected: <id>` output. */
+    id: FrameworkId;
+    /** Human-readable name printed in logs. */
+    label: string;
+    /** Hover package the user gets installed for this framework. */
+    hoverPackage: string;
+    /** package.json dependency keys whose presence signals this framework.
+     *  Checked in priority order across the registry. */
+    detectDeps: string[];
+    /** Possible filenames for the framework's config file. First match wins. */
+    configCandidates: string[];
+}
+/**
+ * Detection priority is high → low. A monorepo or framework whose dep tree
+ * legitimately contains a lower-priority framework (Nuxt has `vite`, Astro
+ * has `vite`) must come first so the right shim wins.
+ *
+ * The `Webpack` entry below intentionally checks the user-facing webpack
+ * tooling (webpack-cli / next) rather than a transitive `webpack` dep —
+ * every Vite project has `webpack` somewhere in its tree because of
+ * dev-server internals.
+ */
+export declare const FRAMEWORKS: Framework[];
+export declare function findFrameworkById(id: FrameworkId): Framework | undefined;
+//# sourceMappingURL=frameworks.d.ts.map

package/dist/frameworks.d.ts.map

@@ -0,0 +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"}

package/dist/frameworks.js

@@ -0,0 +1,47 @@
+/**
+ * Detection priority is high → low. A monorepo or framework whose dep tree
+ * legitimately contains a lower-priority framework (Nuxt has `vite`, Astro
+ * has `vite`) must come first so the right shim wins.
+ *
+ * The `Webpack` entry below intentionally checks the user-facing webpack
+ * tooling (webpack-cli / next) rather than a transitive `webpack` dep —
+ * every Vite project has `webpack` somewhere in its tree because of
+ * dev-server internals.
+ */
+export const FRAMEWORKS = [
+    {
+        id: 'astro',
+        label: 'Astro',
+        hoverPackage: '@hover-dev/astro',
+        detectDeps: ['astro'],
+        configCandidates: ['astro.config.mjs', 'astro.config.ts', 'astro.config.js'],
+    },
+    {
+        id: 'nuxt',
+        label: 'Nuxt',
+        hoverPackage: '@hover-dev/nuxt',
+        detectDeps: ['nuxt'],
+        configCandidates: ['nuxt.config.ts', 'nuxt.config.js', 'nuxt.config.mjs'],
+    },
+    {
+        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
+        // transitive dep is too noisy to detect on.
+        detectDeps: ['webpack-cli', 'next'],
+        configCandidates: ['webpack.config.js', 'webpack.config.mjs', 'webpack.config.ts'],
+    },
+    {
+        id: 'vite',
+        label: 'Vite',
+        hoverPackage: 'vite-plugin-hover',
+        // Catch-all for Vite-based projects that aren't Astro / Nuxt / Svelte.
+        detectDeps: ['vite'],
+        configCandidates: ['vite.config.ts', 'vite.config.js', 'vite.config.mjs'],
+    },
+];
+export function findFrameworkById(id) {
+    return FRAMEWORKS.find(f => f.id === id);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { detectFramework, detectPackageManager, readUserPackageJson } from './detect.js';
+import { findFrameworkById, FRAMEWORKS } from './frameworks.js';
+import { installPackage } from './install.js';
+import { mutateConfig } from './mutate.js';
+import { bold, cyan, dim, err, info, ok, spark, warn } from './log.js';
+function parseArgs(argv) {
+    const out = {
+        command: null,
+        framework: null,
+        dryRun: false,
+        help: false,
+        version: false,
+    };
+    for (const arg of argv) {
+        if (arg === '--help' || arg === '-h')
+            out.help = true;
+        else if (arg === '--version' || arg === '-v')
+            out.version = true;
+        else if (arg === '--dry-run')
+            out.dryRun = true;
+        else if (arg.startsWith('--')) {
+            const candidate = arg.slice(2);
+            if (FRAMEWORKS.some(f => f.id === candidate)) {
+                out.framework = candidate;
+            }
+            else {
+                err(`Unknown flag: ${arg}`);
+                process.exit(2);
+            }
+        }
+        else if (!out.command) {
+            out.command = arg;
+        }
+        else {
+            err(`Unexpected positional argument: ${arg}`);
+            process.exit(2);
+        }
+    }
+    return out;
+}
+function printUsage() {
+    console.log(`${bold('@hover-dev/cli')} — wire Hover into your dev workflow
+
+Usage:
+  npx @hover-dev/cli add              ${dim('# auto-detect bundler, install, wire')}
+  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 --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.
+  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.
+
+For more: https://github.com/Hyperyond/Hover
+`);
+}
+async function runAdd(args) {
+    const found = readUserPackageJson();
+    if (!found) {
+        err(`No package.json found in the current directory or any parent.`);
+        err(`Run this command from your project root, or run \`npm init\` first.`);
+        return 1;
+    }
+    const { pkg, rootDir } = found;
+    // Step 1: pick framework — explicit flag wins over detection.
+    const framework = args.framework
+        ? findFrameworkById(args.framework)
+        : detectFramework(pkg);
+    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.`);
+        return 1;
+    }
+    if (args.framework) {
+        info(`Using ${bold(framework.label)} (forced via --${framework.id}).`);
+    }
+    else {
+        info(`Detected ${bold(framework.label)} project.`);
+    }
+    // Step 2: pick package manager.
+    const { pm, reason } = detectPackageManager(rootDir);
+    info(`Using package manager: ${bold(pm)} ${dim(`(${reason})`)}.`);
+    if (args.dryRun) {
+        warn(`Dry-run — not installing or modifying files.`);
+        info(`Would install: ${cyan(framework.hoverPackage)} (dev dependency, via ${pm}).`);
+        info(`Would mutate: ${cyan(framework.configCandidates[0])} (or whichever candidate exists).`);
+        return 0;
+    }
+    // Step 3: install the right Hover package as a dev dependency.
+    info(`Installing ${cyan(framework.hoverPackage)} ...`);
+    const installCode = await installPackage(pm, framework.hoverPackage, rootDir);
+    if (installCode !== 0) {
+        err(`Package manager exited with code ${installCode}. Aborting.`);
+        return installCode;
+    }
+    ok(`Installed ${framework.hoverPackage}.`);
+    // Step 4: wire the plugin into the config file.
+    info(`Wiring into ${cyan(framework.configCandidates[0])} ...`);
+    const result = await mutateConfig(rootDir, framework);
+    switch (result.kind) {
+        case 'ok':
+            if (result.alreadyWired) {
+                ok(`${result.configPath} already wired — left as-is.`);
+            }
+            else {
+                ok(`Updated ${result.configPath}.`);
+            }
+            break;
+        case 'manual':
+            warn(`Couldn't update your config automatically: ${result.reason}.`);
+            console.log(result.instructions);
+            break;
+        case 'error':
+            warn(`Skipped config update — magicast couldn't safely mutate the file.`);
+            warn(`Reason: ${result.reason}`);
+            console.log(result.instructions);
+            break;
+    }
+    spark(`Done. Run your dev server and click the floating ✨.`);
+    return 0;
+}
+async function main() {
+    const args = parseArgs(process.argv.slice(2));
+    if (args.help) {
+        printUsage();
+        return;
+    }
+    if (args.version) {
+        // Read version from our own package.json at runtime so we don't bake a
+        // string into source that drifts from package.json. Walk up from
+        // src/ or dist/ until we find the package's own package.json.
+        const here = dirname(fileURLToPath(import.meta.url));
+        let dir = here;
+        while (dir !== '/' && !existsSync(join(dir, 'package.json')))
+            dir = dirname(dir);
+        const own = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf-8'));
+        console.log(own.version);
+        return;
+    }
+    if (args.command === 'add') {
+        const code = await runAdd(args);
+        process.exit(code);
+    }
+    if (!args.command) {
+        printUsage();
+        process.exit(0);
+    }
+    err(`Unknown command: ${args.command}`);
+    printUsage();
+    process.exit(2);
+}
+main().catch(e => {
+    err(e instanceof Error ? e.stack ?? e.message : String(e));
+    process.exit(1);
+});

package/dist/install.d.ts

@@ -0,0 +1,12 @@
+import type { PackageManager } from './detect.js';
+/**
+ * Spawn the user's package manager with the install command. Inherits stdio
+ * so the user sees the PM's native progress output (it's better than
+ * anything we could synthesise). Resolves with the exit code; the caller
+ * decides whether to bail.
+ *
+ * `cwd` should be the user's project root (where package.json lives) —
+ * `detect.readUserPackageJson` returns it as `rootDir`.
+ */
+export declare function installPackage(pm: PackageManager, pkg: string, cwd: string): Promise<number>;
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAqBlD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,cAAc,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO5F"}

package/dist/install.js

@@ -0,0 +1,36 @@
+import { spawn } from 'node:child_process';
+/**
+ * Map (package manager, install kind) → argv. Each PM has its own dialect:
+ *   - `pnpm add -D`, `yarn add -D`, `bun add -d`, `npm install --save-dev`.
+ * We pin to dev-dependency installs because every Hover integration is a
+ * dev-only tool (no production runtime code).
+ */
+function buildInstallArgv(pm, pkg) {
+    switch (pm) {
+        case 'pnpm':
+            return ['add', '-D', pkg];
+        case 'yarn':
+            return ['add', '-D', pkg];
+        case 'bun':
+            return ['add', '-d', pkg];
+        case 'npm':
+            return ['install', '--save-dev', pkg];
+    }
+}
+/**
+ * Spawn the user's package manager with the install command. Inherits stdio
+ * so the user sees the PM's native progress output (it's better than
+ * anything we could synthesise). Resolves with the exit code; the caller
+ * decides whether to bail.
+ *
+ * `cwd` should be the user's project root (where package.json lives) —
+ * `detect.readUserPackageJson` returns it as `rootDir`.
+ */
+export function installPackage(pm, pkg, cwd) {
+    return new Promise((resolveExit, rejectExit) => {
+        const argv = buildInstallArgv(pm, pkg);
+        const child = spawn(pm, argv, { cwd, stdio: 'inherit' });
+        child.on('error', rejectExit);
+        child.on('exit', code => resolveExit(code ?? -1));
+    });
+}

package/dist/log.d.ts

@@ -0,0 +1,13 @@
+export declare const dim: (s: string) => string;
+export declare const bold: (s: string) => string;
+export declare const green: (s: string) => string;
+export declare const yellow: (s: string) => string;
+export declare const red: (s: string) => string;
+export declare const blue: (s: string) => string;
+export declare const cyan: (s: string) => string;
+export declare const info: (msg: string) => void;
+export declare const ok: (msg: string) => void;
+export declare const warn: (msg: string) => void;
+export declare const err: (msg: string) => void;
+export declare const spark: (msg: string) => void;
+//# sourceMappingURL=log.d.ts.map

package/dist/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../src/log.ts"],"names":[],"mappings":"AAOA,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,KAAG,MAAsB,CAAC;AACvD,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,KAAG,MAAsB,CAAC;AACxD,eAAO,MAAM,KAAK,GAAI,GAAG,MAAM,KAAG,MAAuB,CAAC;AAC1D,eAAO,MAAM,MAAM,GAAI,GAAG,MAAM,KAAG,MAAuB,CAAC;AAC3D,eAAO,MAAM,GAAG,GAAI,GAAG,MAAM,KAAG,MAAuB,CAAC;AACxD,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,KAAG,MAAuB,CAAC;AACzD,eAAO,MAAM,IAAI,GAAI,GAAG,MAAM,KAAG,MAAuB,CAAC;AAWzD,eAAO,MAAM,IAAI,GAAI,KAAK,MAAM,KAAG,IAAyC,CAAC;AAC7E,eAAO,MAAM,EAAE,GAAI,KAAK,MAAM,KAAG,IAAuC,CAAC;AACzE,eAAO,MAAM,IAAI,GAAI,KAAK,MAAM,KAAG,IAAyC,CAAC;AAC7E,eAAO,MAAM,GAAG,GAAI,KAAK,MAAM,KAAG,IAA0C,CAAC;AAC7E,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,KAAG,IAA0C,CAAC"}

package/dist/log.js

@@ -0,0 +1,26 @@
+// Minimal ANSI color + symbol helpers. We avoid pulling in chalk / picocolors
+// to keep the CLI dependency surface tight (faster npx cold-start). Falls
+// back to plain text if the output stream isn't a TTY (e.g. CI piping into
+// a log file) so we don't dump escape codes into logs.
+const isTTY = process.stdout.isTTY === true;
+const wrap = (code, s) => (isTTY ? `\x1b[${code}m${s}\x1b[0m` : s);
+export const dim = (s) => wrap('2', s);
+export const bold = (s) => wrap('1', s);
+export const green = (s) => wrap('32', s);
+export const yellow = (s) => wrap('33', s);
+export const red = (s) => wrap('31', s);
+export const blue = (s) => wrap('34', s);
+export const cyan = (s) => wrap('36', s);
+// Status symbols mirror what tools like Vite / Astro / shadcn use.
+const SYM = {
+    info: blue('ℹ'),
+    ok: green('✓'),
+    warn: yellow('⚠'),
+    err: red('✗'),
+    spark: cyan('✨'),
+};
+export const info = (msg) => console.log(`${SYM.info} ${msg}`);
+export const ok = (msg) => console.log(`${SYM.ok} ${msg}`);
+export const warn = (msg) => console.log(`${SYM.warn} ${msg}`);
+export const err = (msg) => console.error(`${SYM.err} ${msg}`);
+export const spark = (msg) => console.log(`${SYM.spark} ${msg}`);

package/dist/mutate.d.ts

@@ -0,0 +1,36 @@
+import type { Framework, FrameworkId } from './frameworks.js';
+/**
+ * Result of attempting to wire Hover into the user's config file.
+ *
+ * - `ok` — config was modified (or was already wired; idempotent).
+ * - `manual` — we couldn't safely mutate (no config file, unusual shape).
+ *   `instructions` contains the lines the user should paste themselves.
+ * - `error` — magicast threw; we bailed without touching the file.
+ */
+export type MutateResult = {
+    kind: 'ok';
+    configPath: string;
+    alreadyWired: boolean;
+} | {
+    kind: 'manual';
+    reason: string;
+    instructions: string;
+} | {
+    kind: 'error';
+    reason: string;
+    instructions: string;
+};
+/**
+ * Wire Hover into the user's config file. Picks the first existing
+ * `configCandidates` entry, dispatches to a per-framework mutator. Each
+ * mutator is responsible for being idempotent (re-running the CLI on an
+ * already-wired project should not duplicate the import or array entry).
+ */
+export declare function mutateConfig(rootDir: string, framework: Framework): Promise<MutateResult>;
+/**
+ * Plain-text fallback instructions for `kind: 'manual'` / `kind: 'error'`.
+ * Mirrors what the AST mutator would have produced, so a user with an
+ * unusual config file can hand-edit and get the same result.
+ */
+export declare function manualInstructions(id: FrameworkId): string;
+//# sourceMappingURL=mutate.d.ts.map

package/dist/mutate.d.ts.map

@@ -0,0 +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"}

package/dist/mutate.js

@@ -0,0 +1,184 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { builders, loadFile, writeFile } from 'magicast';
+/**
+ * Wire Hover into the user's config file. Picks the first existing
+ * `configCandidates` entry, dispatches to a per-framework mutator. Each
+ * mutator is responsible for being idempotent (re-running the CLI on an
+ * already-wired project should not duplicate the import or array entry).
+ */
+export async function mutateConfig(rootDir, framework) {
+    const configPath = framework.configCandidates
+        .map(name => join(rootDir, name))
+        .find(p => existsSync(p));
+    if (!configPath) {
+        return {
+            kind: 'manual',
+            reason: `no ${framework.configCandidates[0]} found`,
+            instructions: manualInstructions(framework.id),
+        };
+    }
+    try {
+        switch (framework.id) {
+            case 'vite':
+                return await mutateVite(configPath);
+            case 'astro':
+                return await mutateAstro(configPath);
+            case 'nuxt':
+                return await mutateNuxt(configPath);
+            case 'webpack':
+                return await mutateWebpack(configPath);
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            kind: 'error',
+            reason: msg,
+            instructions: manualInstructions(framework.id),
+        };
+    }
+}
+// ─── Vite: hover() in plugins array ─────────────────────────────────────
+async function mutateVite(configPath) {
+    const mod = await loadFile(configPath);
+    // Idempotency: bail if `hover` is already imported from vite-plugin-hover.
+    // (We could be more clever and re-push if missing-from-array but present
+    // in imports, but that's a corner case — overwriting an intentional removal
+    // would be more harmful.)
+    if (alreadyImported(mod, 'vite-plugin-hover')) {
+        return { kind: 'ok', configPath, alreadyWired: true };
+    }
+    mod.imports.$add({ from: 'vite-plugin-hover', imported: 'hover' });
+    const config = unwrapDefineConfig(mod.exports.default);
+    ensureArray(config, 'plugins');
+    config.plugins.push(builders.functionCall('hover'));
+    await writeFile(mod, configPath);
+    return { kind: 'ok', configPath, alreadyWired: false };
+}
+// ─── Astro: hover() in integrations array ───────────────────────────────
+async function mutateAstro(configPath) {
+    const mod = await loadFile(configPath);
+    if (alreadyImported(mod, '@hover-dev/astro')) {
+        return { kind: 'ok', configPath, alreadyWired: true };
+    }
+    mod.imports.$add({ from: '@hover-dev/astro', imported: 'hover' });
+    const config = unwrapDefineConfig(mod.exports.default);
+    ensureArray(config, 'integrations');
+    config.integrations.push(builders.functionCall('hover'));
+    await writeFile(mod, configPath);
+    return { kind: 'ok', configPath, alreadyWired: false };
+}
+// ─── Nuxt: '@hover-dev/nuxt' string in modules array ────────────────────
+async function mutateNuxt(configPath) {
+    const mod = await loadFile(configPath);
+    const config = unwrapDefineConfig(mod.exports.default);
+    ensureArray(config, 'modules');
+    // Idempotency: Nuxt modules are referenced by string, so check the array.
+    // magicast arrays are iterable proxies, not real Arrays, so don't trust
+    // `Array.isArray` — iterate instead.
+    for (const m of config.modules) {
+        if (m === '@hover-dev/nuxt') {
+            return { kind: 'ok', configPath, alreadyWired: true };
+        }
+    }
+    config.modules.push('@hover-dev/nuxt');
+    await writeFile(mod, configPath);
+    return { kind: 'ok', configPath, alreadyWired: false };
+}
+// ─── Webpack: new HoverPlugin() in plugins array ────────────────────────
+async function mutateWebpack(configPath) {
+    const mod = await loadFile(configPath);
+    if (alreadyImported(mod, 'webpack-plugin-hover')) {
+        return { kind: 'ok', configPath, alreadyWired: true };
+    }
+    mod.imports.$add({ from: 'webpack-plugin-hover', imported: 'HoverPlugin' });
+    const config = unwrapDefineConfig(mod.exports.default);
+    ensureArray(config, 'plugins');
+    config.plugins.push(builders.newExpression('HoverPlugin'));
+    await writeFile(mod, configPath);
+    return { kind: 'ok', configPath, alreadyWired: false };
+}
+// ─── Helpers ────────────────────────────────────────────────────────────
+/**
+ * Check whether a module already has a named/default import from `source`.
+ * magicast's `imports` proxy is keyed by binding name; each entry exposes
+ * its source as `.from`. Defensive: returns false on any unexpected shape.
+ */
+function alreadyImported(mod, source) {
+    try {
+        for (const item of mod.imports.$items) {
+            if (item.from === source)
+                return true;
+        }
+    }
+    catch {
+        /* fall through */
+    }
+    return false;
+}
+/**
+ * `export default defineConfig({ ... })` is the convention across Vite /
+ * Astro / Nuxt. Unwrap to the inner object so callers can mutate
+ * `plugins` / `integrations` / `modules` directly. Bare object exports
+ * (`export default { ... }`) are returned unchanged.
+ */
+function unwrapDefineConfig(exp) {
+    if (exp?.$type === 'function-call' && Array.isArray(exp.$args) && exp.$args[0]) {
+        return exp.$args[0];
+    }
+    return exp;
+}
+/**
+ * Ensure a key on the magicast-proxied config object holds an array. The
+ * obvious-looking `cfg[key] ??= []` does NOT work reliably against the
+ * proxy — the proxy returns "something" for missing keys (not undefined),
+ * so the nullish-assignment short-circuits, and subsequent pushes go into
+ * a detached array that never makes it back to the AST. Explicit `if not
+ * present then assign a real []` does work, because the proxy turns the
+ * assignment into an actual AST node.
+ */
+function ensureArray(config, key) {
+    if (config[key] === undefined || config[key] === null) {
+        config[key] = [];
+    }
+}
+/**
+ * Plain-text fallback instructions for `kind: 'manual'` / `kind: 'error'`.
+ * Mirrors what the AST mutator would have produced, so a user with an
+ * unusual config file can hand-edit and get the same result.
+ */
+export function manualInstructions(id) {
+    switch (id) {
+        case 'vite':
+            return [
+                `Add to your vite config:`,
+                ``,
+                `  import { hover } from 'vite-plugin-hover';`,
+                `  // ...`,
+                `  plugins: [react(), hover()],`,
+            ].join('\n');
+        case 'astro':
+            return [
+                `Add to your astro config:`,
+                ``,
+                `  import { hover } from '@hover-dev/astro';`,
+                `  // ...`,
+                `  integrations: [hover()],`,
+            ].join('\n');
+        case 'nuxt':
+            return [
+                `Add to your nuxt config:`,
+                ``,
+                `  modules: ['@hover-dev/nuxt'],`,
+            ].join('\n');
+        case 'webpack':
+            return [
+                `Add to your webpack config:`,
+                ``,
+                `  const { HoverPlugin } = require('webpack-plugin-hover');`,
+                `  // ...`,
+                `  plugins: [..., new HoverPlugin()],`,
+            ].join('\n');
+    }
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@hover-dev/cli",
+  "version": "0.3.0",
+  "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",
+  "homepage": "https://github.com/Hyperyond/Hover#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hyperyond/Hover.git",
+    "directory": "packages/cli"
+  },
+  "bugs": "https://github.com/Hyperyond/Hover/issues",
+  "keywords": [
+    "hover",
+    "cli",
+    "scaffold",
+    "vite",
+    "astro",
+    "nuxt",
+    "webpack",
+    "playwright",
+    "claude"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "magicast": "^0.5.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\""
+  },
+  "types": "dist/index.d.ts",
+  "bin": {
+    "hover": "dist/index.js"
+  }
+}