webmcp_everywhere 0.1.0

package/webmcp_everywhere.mjs

@@ -0,0 +1,1166 @@
+#!/usr/bin/env node
+
+// tools/npm_command_entry.ts
+import Fs7 from "node:fs";
+import Path6 from "node:path";
+
+// tools/installation_status.ts
+import Fs6 from "node:fs";
+import Path5 from "node:path";
+
+// src/native_messaging_host/host_state_files.ts
+import Crypto from "node:crypto";
+import Fs from "node:fs";
+import Os from "node:os";
+import Path from "node:path";
+var HostStateFiles = class _HostStateFiles {
+  static {
+    /** Where the endpoint details, the token, and the log are kept, for an agent to read. */
+    this.STATE_DIR = process.env.WEBMCP_EVERYWHERE_STATE_DIR ?? Path.join(Os.homedir(), ".webmcp_everywhere");
+  }
+  /**
+   * Names the one file the bearer token is kept in.
+   *
+   * @returns The path of `token` inside the state directory.
+   */
+  static _tokenPath() {
+    return Path.join(_HostStateFiles.STATE_DIR, "token");
+  }
+  /**
+   * Reads the stored token, creating one on first run.
+   *
+   * The token persists so an agent configured once keeps working across restarts. This file is the only
+   * place it is kept, and every reader is sent here for it.
+   *
+   * @returns The token.
+   */
+  static _readOrCreateToken() {
+    Fs.mkdirSync(_HostStateFiles.STATE_DIR, {
+      recursive: true,
+      mode: 448
+    });
+    const tokenPath = _HostStateFiles._tokenPath();
+    if (Fs.existsSync(tokenPath) === true) {
+      return Fs.readFileSync(tokenPath, "utf8").trim();
+    }
+    const token = Crypto.randomBytes(32).toString("hex");
+    Fs.writeFileSync(tokenPath, token, {
+      mode: 384
+    });
+    return token;
+  }
+  /**
+   * Names the file that tells an agent where to go.
+   *
+   * @returns The path of `endpoint.json` inside the state directory.
+   */
+  static _endpointPath() {
+    return Path.join(_HostStateFiles.STATE_DIR, "endpoint.json");
+  }
+  /**
+   * Records where the host is listening, so an agent can be pointed at it.
+   *
+   * Only a host that holds the port writes this file, and it records which process holds it, so the file
+   * can be removed by the host that wrote it and by no other.
+   *
+   * The bearer token is not written here. It never changes, and putting a correct token on the line
+   * beside an address that can go stale made the whole file read as authoritative: readers followed it
+   * to a port nothing was listening on. The token has one home, `~/.webmcp_everywhere/token`, and this
+   * file carries only what is true of the host writing it right now.
+   *
+   * @param port - The bound port.
+   * @returns Nothing.
+   */
+  static _writeEndpoint(port) {
+    const record = {
+      url: `http://127.0.0.1:${port}/mcp`,
+      processId: process.pid,
+      startedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    Fs.writeFileSync(_HostStateFiles._endpointPath(), JSON.stringify(record, null, "	") + "\n", {
+      mode: 384
+    });
+  }
+  /**
+   * Removes `endpoint.json`, but only when it is this host's own.
+   *
+   * A host that stopped used to leave the file behind, so it went on naming a port nothing was listening
+   * on and every agent following the README was pointed at nothing. Checking the process identifier
+   * first means a host that has already given the port up to a newer one never removes the newer one's
+   * file.
+   *
+   * @returns Nothing.
+   */
+  static _removeEndpointIfOurs() {
+    try {
+      const record = JSON.parse(
+        Fs.readFileSync(_HostStateFiles._endpointPath(), "utf8")
+      );
+      if (record.processId !== process.pid) {
+        return;
+      }
+      Fs.unlinkSync(_HostStateFiles._endpointPath());
+    } catch {
+    }
+  }
+};
+
+// tools/packaged_release_installation.ts
+import Fs5 from "node:fs";
+import Path4 from "node:path";
+
+// tools/generate_extension_key.ts
+import Crypto2 from "node:crypto";
+import Fs2 from "node:fs";
+import Path2 from "node:path";
+var __filename = import.meta.filename;
+var __dirname = import.meta.dirname;
+var GenerateExtensionKey = class _GenerateExtensionKey {
+  /**
+   * Derives Chrome's extension identifier from a public key.
+   *
+   * Chrome takes the SHA-256 of the DER-encoded public key, keeps the first sixteen bytes, and maps
+   * each of the thirty-two nibbles onto the letters `a` to `p`.
+   *
+   * @param publicKeyDer - The DER-encoded SubjectPublicKeyInfo.
+   * @returns The thirty-two character extension identifier.
+   */
+  static identifierFromPublicKey(publicKeyDer) {
+    const digest = Crypto2.createHash("sha256").update(publicKeyDer).digest();
+    let identifier = "";
+    for (const byte of digest.subarray(0, 16)) {
+      identifier += String.fromCharCode(97 + (byte >> 4));
+      identifier += String.fromCharCode(97 + (byte & 15));
+    }
+    return identifier;
+  }
+  /**
+   * Generates a key pair, writes the public half into the manifest, and reports the identifier.
+   *
+   * @returns What was generated and where the private half went.
+   */
+  static run() {
+    const manifestPath = Path2.join(__dirname, "..", "src", "chrome_extension", "manifest.json");
+    const manifest = JSON.parse(Fs2.readFileSync(manifestPath, "utf8"));
+    if (manifest.key !== void 0) {
+      const identifier = _GenerateExtensionKey.identifierFromPublicKey(
+        Buffer.from(manifest.key, "base64")
+      );
+      return {
+        identifier,
+        privateKeyPath: "unchanged, the manifest already carries a key"
+      };
+    }
+    const { publicKey, privateKey } = Crypto2.generateKeyPairSync("rsa", {
+      modulusLength: 2048
+    });
+    const publicKeyDer = publicKey.export({
+      type: "spki",
+      format: "der"
+    });
+    manifest.key = publicKeyDer.toString("base64");
+    Fs2.writeFileSync(manifestPath, JSON.stringify(manifest, null, "	") + "\n");
+    const privateKeyPath = Path2.join(__dirname, "..", "extension_private_key.pem");
+    Fs2.writeFileSync(
+      privateKeyPath,
+      privateKey.export({
+        type: "pkcs8",
+        format: "pem"
+      })
+    );
+    return {
+      identifier: _GenerateExtensionKey.identifierFromPublicKey(publicKeyDer),
+      privateKeyPath
+    };
+  }
+  /**
+   * Reads the extension identifier the manifest currently pins.
+   *
+   * @returns The extension identifier.
+   * @throws When the manifest carries no key.
+   */
+  static currentIdentifier(manifestPath) {
+    const readFrom = manifestPath ?? Path2.join(__dirname, "..", "src", "chrome_extension", "manifest.json");
+    const manifest = JSON.parse(Fs2.readFileSync(readFrom, "utf8"));
+    if (manifest.key === void 0) {
+      throw new Error('the manifest has no key; run "node tools/generate_extension_key_entry.ts" first');
+    }
+    return _GenerateExtensionKey.identifierFromPublicKey(Buffer.from(manifest.key, "base64"));
+  }
+};
+
+// tools/install_native_host.ts
+import Fs3 from "node:fs";
+import Os2 from "node:os";
+import Path3 from "node:path";
+var __filename2 = import.meta.filename;
+var __dirname2 = import.meta.dirname;
+var InstallNativeHost = class _InstallNativeHost {
+  static {
+    /** The host name the extension asks for, which must match the manifest file name. */
+    this.HOST_NAME = "com.webmcp_everywhere.host";
+  }
+  /**
+   * Works out what an installation would write, without writing any of it.
+   *
+   * This exists so that the installation can say what it is about to do to the user's machine before it
+   * does it. Writing a file into a browser the user installed is not something to announce afterwards.
+   *
+   * @param options - Where the installation would write.
+   * @returns The files the installation would write.
+   */
+  static plan(options = {}) {
+    const identifier = GenerateExtensionKey.currentIdentifier(options.extensionManifestPath);
+    const launcher = _InstallNativeHost._resolveLauncher(options.launcherPath);
+    return {
+      identifier,
+      launcher,
+      manifests: _InstallNativeHost.manifestPaths(options)
+    };
+  }
+  /**
+   * Names every manifest file the installation writes, without reading anything else.
+   *
+   * The installation, the uninstallation and the command that copies a release somewhere stable all
+   * need this same list, and a file name spelled in three places is spelled wrong in one of them
+   * eventually. It reads no launcher and no extension manifest, so it also answers before an
+   * installation exists, which is what lets a command name the files it is about to write.
+   *
+   * @param options - Which directories to cover.
+   * @returns The manifest files, in the order they are written.
+   */
+  static manifestPaths(options = {}) {
+    return _InstallNativeHost.manifestDirectories(options).map((directory) => {
+      return Path3.join(directory, `${_InstallNativeHost.HOST_NAME}.json`);
+    });
+  }
+  /**
+   * Writes the launcher and the manifest.
+   *
+   * @param options - Where to install.
+   * @returns What was written.
+   */
+  static run(options = {}) {
+    const planned = _InstallNativeHost.plan(options);
+    const manifest = _InstallNativeHost._renderManifest(
+      planned.launcher,
+      planned.identifier,
+      options.templateDir
+    );
+    for (const manifestPath of planned.manifests) {
+      Fs3.mkdirSync(Path3.dirname(manifestPath), {
+        recursive: true
+      });
+      Fs3.writeFileSync(manifestPath, manifest);
+    }
+    return planned;
+  }
+  /**
+   * Lists every directory Chrome might read host manifests from.
+   *
+   * The everyday Chrome reads them from its own support directory. A Chrome started with a custom
+   * `--user-data-dir`, which is what `LaunchChrome` and the verification runners use, reads them from
+   * inside that directory instead and never looks at the everyday one, which is why a throwaway profile
+   * can be covered without touching the browser the user installed.
+   *
+   * This is public because the uninstallation has to remove a manifest from exactly the directories the
+   * installation writes one into, and two lists that have to agree are one list.
+   *
+   * @param options - Which directories to cover.
+   * @returns The directories that hold a manifest, the everyday Chrome first when it is covered.
+   */
+  static manifestDirectories(options = {}) {
+    const directories = [];
+    if (options.isEverydayChromeCovered !== false) {
+      directories.push(_InstallNativeHost.everydayChromeDirectory());
+    }
+    for (const userDataDir of options.userDataDirs ?? []) {
+      directories.push(Path3.join(userDataDir, "NativeMessagingHosts"));
+    }
+    return directories;
+  }
+  /**
+   * Names the directory the everyday Chrome, the one the user installed, reads host manifests from.
+   *
+   * @param homeDir - The home folder to read it out of, for a runner installing into a throwaway one.
+   * @returns The absolute path of that directory on this platform.
+   */
+  static everydayChromeDirectory(homeDir = Os2.homedir()) {
+    if (process.platform === "darwin") {
+      return Path3.join(homeDir, "Library", "Application Support", "Google", "Chrome", "NativeMessagingHosts");
+    }
+    return Path3.join(homeDir, ".config", "google-chrome", "NativeMessagingHosts");
+  }
+  ///////////////////////////////////////////////////////////////////////////////
+  ///////////////////////////////////////////////////////////////////////////////
+  //	Helpers
+  ///////////////////////////////////////////////////////////////////////////////
+  ///////////////////////////////////////////////////////////////////////////////
+  /**
+   * Fills the host manifest template in with this installation's values.
+   *
+   * The manifest lives in `data/native_messaging_template/com.webmcp_everywhere.host.json` rather than in
+   * this file, so that the shape Chrome reads can be looked at and edited as the JSON document it is. It
+   * is read every time instead of being cached, because an installation runs once and then exits. Every
+   * placeholder has to be replaced, so an unreplaced one is an error rather than something written out
+   * to Chrome, which would refuse the manifest with no useful message.
+   *
+   * @param launcher - The absolute path to the executable file Chrome starts.
+   * @param identifier - The extension identifier the manifest allows to connect.
+   * @param templateDir - The folder holding the template, or nothing for this working copy's.
+   * @returns The manifest text to write, ending in a newline.
+   */
+  static _renderManifest(launcher, identifier, templateDir) {
+    const folder = templateDir ?? Path3.join(__dirname2, "..", "data", "native_messaging_template");
+    const templatePath = Path3.join(folder, `${_InstallNativeHost.HOST_NAME}.json`);
+    if (Fs3.existsSync(templatePath) === false) {
+      throw new Error(`host manifest template is missing: ${templatePath}`);
+    }
+    const template = Fs3.readFileSync(templatePath, "utf8");
+    const values = {
+      hostName: _InstallNativeHost.HOST_NAME,
+      launcherPath: launcher,
+      extensionIdentifier: identifier
+    };
+    let rendered = template;
+    for (const [placeholder, value] of Object.entries(values)) {
+      rendered = rendered.split(`{{${placeholder}}}`).join(value);
+    }
+    const leftover = rendered.match(/\{\{[^}]*\}\}/);
+    if (leftover !== null) {
+      throw new Error(`host manifest template has an unknown placeholder: ${leftover[0]}`);
+    }
+    JSON.parse(rendered);
+    return rendered.endsWith("\n") === true ? rendered : rendered + "\n";
+  }
+  /**
+   * Locates the executable Chrome actually launches.
+   *
+   * Chrome runs the path in the manifest directly, so it has to be an executable file rather than a
+   * script it would have to know how to interpret. `bin/webmcp_native_host.sh` is that file, it is
+   * kept in the repository, and it works out the rest of the paths on its own, so this only has to
+   * check that it is there and that it is executable.
+   *
+   * @param named - A launcher to use instead of this working copy's, such as a packaged release's.
+   * @returns The absolute path to the launcher.
+   * @throws When the launcher is not there.
+   */
+  static _resolveLauncher(named) {
+    const repoRoot = Path3.join(__dirname2, "..");
+    const launcher = named === void 0 ? Path3.join(repoRoot, "bin", "webmcp_native_host.sh") : Path3.resolve(named);
+    if (Fs3.existsSync(launcher) === false) {
+      throw new Error(`launcher is missing: ${launcher}`);
+    }
+    Fs3.chmodSync(launcher, 493);
+    return launcher;
+  }
+};
+
+// tools/release_layout.ts
+var ReleaseLayout = class {
+  static {
+    /** The bundled native messaging host, one file with its dependencies inlined. */
+    this.HOST_BUNDLE = "webmcp_native_host.mjs";
+  }
+  static {
+    /** The launcher Chrome starts, which finds a Node.js and runs the bundle beside it. */
+    this.LAUNCHER = "webmcp_native_host.sh";
+  }
+  static {
+    /** The installer that registers that launcher with Chrome. */
+    this.INSTALLER = "install_the_native_messaging_host.mjs";
+  }
+  static {
+    /** The command an `npx webmcp_everywhere` run starts, which the `bin` field of the manifest names. */
+    this.COMMAND = "webmcp_everywhere.mjs";
+  }
+  static {
+    /** The manifest npm publishes the folder with. */
+    this.PACKAGE_MANIFEST = "package.json";
+  }
+  static {
+    /** The folder a person loads at `chrome://extensions`. */
+    this.EXTENSION_DIR = "chrome_extension";
+  }
+  static {
+    /** The folder holding the host manifest template the installer fills in. */
+    this.TEMPLATE_DIR = "native_messaging_template";
+  }
+  static {
+    /** The extension manifest inside the extension folder, which pins the extension identifier. */
+    this.EXTENSION_MANIFEST = "manifest.json";
+  }
+};
+
+// tools/uninstall_native_host.ts
+import Fs4 from "node:fs";
+var UninstallNativeHost = class _UninstallNativeHost {
+  /**
+   * Removes the manifest from every directory the installation writes it into.
+   *
+   * @param options - Where to uninstall from.
+   * @returns Every manifest file looked at, and whether each one was there.
+   */
+  static run(options = {}) {
+    const manifests = [];
+    for (const manifestPath of InstallNativeHost.manifestPaths(options)) {
+      const launcher = _UninstallNativeHost._readLauncher(manifestPath);
+      let isRemoved = false;
+      if (Fs4.existsSync(manifestPath) === true) {
+        Fs4.rmSync(manifestPath);
+        isRemoved = true;
+      }
+      manifests.push({
+        path: manifestPath,
+        isRemoved,
+        launcher
+      });
+    }
+    return {
+      manifests,
+      stateDir: HostStateFiles.STATE_DIR
+    };
+  }
+  ///////////////////////////////////////////////////////////////////////////////
+  ///////////////////////////////////////////////////////////////////////////////
+  //	Helpers
+  ///////////////////////////////////////////////////////////////////////////////
+  ///////////////////////////////////////////////////////////////////////////////
+  /**
+   * Reads the executable a manifest names, before that manifest is removed.
+   *
+   * A manifest another program wrote, or one this project wrote and then half overwrote, is still a
+   * file to remove, so an unreadable one is reported as an unknown launcher rather than refused.
+   *
+   * @param manifestPath - The manifest file to read.
+   * @returns The path in the manifest's `path` field, or null when there is none to read.
+   */
+  static _readLauncher(manifestPath) {
+    if (Fs4.existsSync(manifestPath) === false) {
+      return null;
+    }
+    try {
+      const parsed = JSON.parse(Fs4.readFileSync(manifestPath, "utf8"));
+      if (typeof parsed.path === "string") {
+        return parsed.path;
+      }
+      return null;
+    } catch {
+      return null;
+    }
+  }
+};
+
+// tools/packaged_release_installation.ts
+var PackagedReleaseInstallation = class _PackagedReleaseInstallation {
+  static {
+    /** The folder inside the state directory that the release is copied into. */
+    this.FOLDER_NAME = "installation";
+  }
+  /**
+   * Names the folder an installation goes into.
+   *
+   * @param options - Where the installation reads from and writes to.
+   * @returns The target folder, which is the state directory's `installation` unless one was named.
+   */
+  static targetDir(options) {
+    return options.targetDir ?? Path4.join(HostStateFiles.STATE_DIR, _PackagedReleaseInstallation.FOLDER_NAME);
+  }
+  /**
+   * Works out everything an installation would write, without writing any of it.
+   *
+   * This is what lets the command name every path it is about to touch before it touches one. A copy
+   * into the user's home folder and a file written into the browser they installed are both things to
+   * announce beforehand, not afterwards.
+   *
+   * @param options - Where the installation reads from and writes to.
+   * @returns The folders and files the installation would write.
+   */
+  static plan(options) {
+    const targetDir = _PackagedReleaseInstallation.targetDir(options);
+    const isAlreadyInPlace = Path4.resolve(options.sourceDir) === Path4.resolve(targetDir);
+    const nativeHost = {
+      identifier: GenerateExtensionKey.currentIdentifier(
+        Path4.join(options.sourceDir, ReleaseLayout.EXTENSION_DIR, ReleaseLayout.EXTENSION_MANIFEST)
+      ),
+      launcher: Path4.join(targetDir, ReleaseLayout.LAUNCHER),
+      manifests: InstallNativeHost.manifestPaths({
+        isEverydayChromeCovered: options.isEverydayChromeCovered,
+        userDataDirs: options.userDataDirs
+      })
+    };
+    return {
+      sourceDir: options.sourceDir,
+      targetDir,
+      isTargetDirReplaced: Fs5.existsSync(targetDir) === true && isAlreadyInPlace === false,
+      isAlreadyInPlace,
+      extensionDir: Path4.join(targetDir, ReleaseLayout.EXTENSION_DIR),
+      stateDir: HostStateFiles.STATE_DIR,
+      nativeHost
+    };
+  }
+  /**
+   * Copies the release into the target folder, then registers its launcher with Chrome.
+   *
+   * Running it a second time replaces the folder rather than adding a second one beside it, because a
+   * user updating to a newer version is the ordinary case and two installations would leave Chrome
+   * pointing at whichever was registered last with no way to tell which.
+   *
+   * @param options - Where the installation reads from and writes to.
+   * @returns What was written, in the same shape `plan` returns.
+   */
+  static install(options) {
+    const planned = _PackagedReleaseInstallation.plan(options);
+    if (planned.isAlreadyInPlace === false) {
+      Fs5.rmSync(planned.targetDir, {
+        recursive: true,
+        force: true
+      });
+      Fs5.mkdirSync(Path4.dirname(planned.targetDir), {
+        recursive: true,
+        mode: 448
+      });
+      Fs5.cpSync(planned.sourceDir, planned.targetDir, {
+        recursive: true
+      });
+    }
+    _PackagedReleaseInstallation._makeRunnable(Path4.join(planned.targetDir, ReleaseLayout.LAUNCHER));
+    _PackagedReleaseInstallation._makeRunnable(Path4.join(planned.targetDir, ReleaseLayout.COMMAND));
+    InstallNativeHost.run({
+      launcherPath: Path4.join(planned.targetDir, ReleaseLayout.LAUNCHER),
+      templateDir: Path4.join(planned.targetDir, ReleaseLayout.TEMPLATE_DIR),
+      extensionManifestPath: Path4.join(
+        planned.targetDir,
+        ReleaseLayout.EXTENSION_DIR,
+        ReleaseLayout.EXTENSION_MANIFEST
+      ),
+      isEverydayChromeCovered: options.isEverydayChromeCovered,
+      userDataDirs: options.userDataDirs
+    });
+    return planned;
+  }
+  /**
+   * Takes the registration and the installation folder back out, and leaves everything else.
+   *
+   * The token and the loaded adapters are not removed. They are the user's, they took a decision each
+   * to create, and a command that installed a browser extension has no business deleting them.
+   *
+   * @param options - Where the installation was written, and which Chrome it covered.
+   * @returns Every manifest looked at, whether the folder was removed, and the state directory left alone.
+   */
+  static remove(options) {
+    const targetDir = _PackagedReleaseInstallation.targetDir(options);
+    const uninstalled = UninstallNativeHost.run({
+      isEverydayChromeCovered: options.isEverydayChromeCovered,
+      userDataDirs: options.userDataDirs
+    });
+    const isTargetDirRemoved = Fs5.existsSync(targetDir);
+    if (isTargetDirRemoved === true) {
+      Fs5.rmSync(targetDir, {
+        recursive: true,
+        force: true
+      });
+    }
+    return {
+      targetDir,
+      isTargetDirRemoved,
+      manifests: uninstalled.manifests,
+      stateDir: uninstalled.stateDir
+    };
+  }
+  ///////////////////////////////////////////////////////////////////////////////
+  ///////////////////////////////////////////////////////////////////////////////
+  //	Helpers
+  ///////////////////////////////////////////////////////////////////////////////
+  ///////////////////////////////////////////////////////////////////////////////
+  /**
+   * Makes one copied file executable again.
+   *
+   * A copy does not always carry the executable bit through, and neither does every way a package
+   * reaches a machine. Chrome starting the launcher and a person running the command are both silent
+   * failures when it is missing, so it is set rather than assumed.
+   *
+   * @param path - The file to make executable.
+   * @returns Nothing.
+   */
+  static _makeRunnable(path) {
+    if (Fs5.existsSync(path) === false) {
+      return;
+    }
+    Fs5.chmodSync(path, 493);
+  }
+};
+
+// src/adapter_format/tool_naming.ts
+var ToolNaming = class _ToolNaming {
+  static {
+    /** Separates the site slug from the unqualified tool name. Two underscores, so single ones are free. */
+    this.SEPARATOR = "__";
+  }
+  static {
+    /**
+     * The site slug the browser's own tools are qualified with, which belongs to no adapter.
+     *
+     * `list_pages`, `open_page` and `close_page` are answered by the bridge rather than by any page, so
+     * anything counting adapters has to tell them apart from an adapter's tools. The qualified names
+     * themselves are spelled out in `native_bridge.ts` and in `webmcp_native_host.ts`, which is where they
+     * are offered from.
+     */
+    this.BROWSER_SLUG = "webmcp_everywhere";
+  }
+  static {
+    /** Names WebMCP accepts. Anything outside this set is rejected before registration is attempted. */
+    this.VALID_NAME = /^[a-z0-9_]+$/;
+  }
+  /**
+   * Joins a site slug and an unqualified tool name into the name actually registered with WebMCP.
+   *
+   * @param siteSlug - The adapter's site slug, for example `demo_playwright_dev`.
+   * @param toolName - The unqualified tool name, for example `list_todos`.
+   * @returns The qualified name, for example `demo_playwright_dev__list_todos`.
+   */
+  static qualify(siteSlug, toolName) {
+    return `${siteSlug}${_ToolNaming.SEPARATOR}${toolName}`;
+  }
+  /**
+   * Splits a qualified name back into its site slug and unqualified tool name.
+   *
+   * @param qualifiedName - A name such as `demo_playwright_dev__list_todos`.
+   * @returns The two parts, or `null` when the name is not qualified.
+   */
+  static unqualify(qualifiedName) {
+    const index = qualifiedName.indexOf(_ToolNaming.SEPARATOR);
+    if (index === -1) {
+      return null;
+    }
+    return {
+      siteSlug: qualifiedName.slice(0, index),
+      toolName: qualifiedName.slice(index + _ToolNaming.SEPARATOR.length)
+    };
+  }
+  /**
+   * Reports whether a qualified name belongs to the given adapter.
+   *
+   * @param qualifiedName - The name to test.
+   * @param siteSlug - The adapter's site slug.
+   * @returns `true` when the name was registered by that adapter.
+   */
+  static belongsTo(qualifiedName, siteSlug) {
+    return qualifiedName.startsWith(siteSlug + _ToolNaming.SEPARATOR);
+  }
+};
+
+// tools/installation_status.ts
+var InstallationStatus = class _InstallationStatus {
+  static {
+    /** How long to wait for the host to answer, in milliseconds, when the caller names nothing. */
+    this.TIMEOUT = 2e3;
+  }
+  /**
+   * Walks the delivery path as far as it goes, and says where it stopped.
+   *
+   * @param options - Where to look, and how long to wait.
+   * @returns What was found at every step.
+   */
+  static async read(options = {}) {
+    const stateDir = options.stateDir ?? HostStateFiles.STATE_DIR;
+    const installationDir = Path5.join(stateDir, PackagedReleaseInstallation.FOLDER_NAME);
+    const extensionDir = Path5.join(installationDir, ReleaseLayout.EXTENSION_DIR);
+    const timeout = options.timeoutMilliseconds ?? _InstallationStatus.TIMEOUT;
+    const partial = {
+      installationDir,
+      extensionDir,
+      stateDir,
+      endpoint: null,
+      isExtensionConnected: false,
+      toolNames: [],
+      adapters: [],
+      browserToolCount: 0
+    };
+    const endpoint = _InstallationStatus._readEndpoint(stateDir);
+    if (endpoint === null) {
+      if (Fs6.existsSync(installationDir) === false) {
+        return {
+          ...partial,
+          isReady: false,
+          stage: "nothing_installed",
+          summary: `Nothing is installed at ${installationDir}`,
+          remedy: ["Install it: npx webmcp_everywhere"]
+        };
+      }
+      return {
+        ...partial,
+        isReady: false,
+        stage: "no_host_listening",
+        summary: "No browser is holding the port, so the extension is not loaded or Chrome is not running.",
+        remedy: _InstallationStatus._loadTheExtension(extensionDir)
+      };
+    }
+    const health = await _InstallationStatus._askHealth(endpoint.url, timeout);
+    if (health === null) {
+      return {
+        ...partial,
+        endpoint,
+        isReady: false,
+        stage: "nothing_answers_the_recorded_address",
+        summary: `${endpoint.url} was recorded by process ${endpoint.processId}, and nothing answers there.`,
+        remedy: ["Quit Chrome and start it again, which starts a new host."]
+      };
+    }
+    if (health.processId !== endpoint.processId) {
+      return {
+        ...partial,
+        endpoint,
+        isReady: false,
+        stage: "another_program_holds_the_port",
+        summary: `Process ${health.processId} is answering on ${endpoint.url}, not the host that recorded it.`,
+        remedy: [
+          "The port serves one browser at a time. Close the other browser holding it,",
+          "then quit Chrome and start it again."
+        ]
+      };
+    }
+    if (health.extensionConnected === false) {
+      return {
+        ...partial,
+        endpoint,
+        isReady: false,
+        stage: "extension_not_connected",
+        summary: `A host is listening on ${endpoint.url}, and no extension is connected to it.`,
+        remedy: _InstallationStatus._loadTheExtension(extensionDir)
+      };
+    }
+    const tokenPath = Path5.join(stateDir, "token");
+    if (Fs6.existsSync(tokenPath) === false) {
+      return {
+        ...partial,
+        endpoint,
+        isExtensionConnected: true,
+        isReady: false,
+        stage: "no_token",
+        summary: `There is no bearer token at ${tokenPath}, so nothing may ask the host anything.`,
+        remedy: ["Quit Chrome and start it again, which writes one."]
+      };
+    }
+    const token = Fs6.readFileSync(tokenPath, "utf8").trim();
+    const answer = await _InstallationStatus._askTools(endpoint.url, token, timeout);
+    if (answer.isTokenRefused === true) {
+      return {
+        ...partial,
+        endpoint,
+        isExtensionConnected: true,
+        isReady: false,
+        stage: "token_refused",
+        summary: `The host refused the token in ${tokenPath}`,
+        remedy: ["Quit Chrome and start it again, then read the token again."]
+      };
+    }
+    const adapters = _InstallationStatus._groupByAdapter(answer.toolNames);
+    const browserToolCount = answer.toolNames.filter((name) => {
+      return ToolNaming.belongsTo(name, ToolNaming.BROWSER_SLUG) === true;
+    }).length;
+    const siteToolCount = answer.toolNames.length - browserToolCount;
+    if (answer.toolNames.length === 0) {
+      return {
+        ...partial,
+        endpoint,
+        isExtensionConnected: true,
+        isReady: false,
+        stage: "no_tools_offered",
+        summary: "The extension is connected and the host offered no tools at all, not even its own.",
+        remedy: ["Quit Chrome and start it again."]
+      };
+    }
+    const answered = {
+      ...partial,
+      endpoint,
+      isExtensionConnected: true,
+      toolNames: answer.toolNames,
+      adapters,
+      browserToolCount,
+      isReady: true
+    };
+    if (adapters.length === 0) {
+      return {
+        ...answered,
+        stage: "no_site_adapter_running",
+        summary: `The extension is loaded and connected, and ${browserToolCount} browser tools are reaching your agent. No open tab has a site adapter running in it.`,
+        remedy: [
+          "Open a site one of your adapters covers, then ask again. Your agent can open one itself",
+          "with the webmcp_everywhere__open_page tool.",
+          "The extension popup lists every adapter and says why a withheld one is withheld."
+        ]
+      };
+    }
+    return {
+      ...answered,
+      stage: "tools_offered",
+      summary: `${siteToolCount} tools from ${adapters.length} ${adapters.length === 1 ? "adapter" : "adapters"} are reaching your agent, and ${browserToolCount} browser tools beside them.`,
+      remedy: []
+    };
+  }
+  ///////////////////////////////////////////////////////////////////////////////
+  ///////////////////////////////////////////////////////////////////////////////
+  //	Helpers
+  ///////////////////////////////////////////////////////////////////////////////
+  ///////////////////////////////////////////////////////////////////////////////
+  /**
+   * Reads where a host said it is listening.
+   *
+   * The file is there only while a host really holds the port, and it is removed by the host that
+   * wrote it, so a missing file means no browser is running rather than an address gone stale.
+   *
+   * @param stateDir - The state directory to read it from.
+   * @returns The record, or null when there is no readable one.
+   */
+  static _readEndpoint(stateDir) {
+    const endpointPath = Path5.join(stateDir, "endpoint.json");
+    if (Fs6.existsSync(endpointPath) === false) {
+      return null;
+    }
+    try {
+      return JSON.parse(Fs6.readFileSync(endpointPath, "utf8"));
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Asks whatever is on that address what it is and whether an extension is connected to it.
+   *
+   * @param url - The Model Context Protocol address the endpoint file names.
+   * @param timeoutMilliseconds - How long to wait for an answer.
+   * @returns What answered, or null when nothing did.
+   */
+  static async _askHealth(url, timeoutMilliseconds) {
+    try {
+      const response = await fetch(new URL("/health", url), {
+        signal: AbortSignal.timeout(timeoutMilliseconds)
+      });
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Asks the host for its tool list, exactly the way an agent does.
+   *
+   * @param url - The Model Context Protocol address.
+   * @param token - The bearer token to present.
+   * @param timeoutMilliseconds - How long to wait for an answer.
+   * @returns The names offered, and whether the token was refused.
+   */
+  static async _askTools(url, token, timeoutMilliseconds) {
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          accept: "application/json, text/event-stream",
+          authorization: `Bearer ${token}`
+        },
+        body: JSON.stringify({
+          jsonrpc: "2.0",
+          id: 1,
+          method: "tools/list",
+          params: {}
+        }),
+        signal: AbortSignal.timeout(timeoutMilliseconds)
+      });
+      if (response.status === 401 || response.status === 403) {
+        return {
+          toolNames: [],
+          isTokenRefused: true
+        };
+      }
+      const body = await response.json();
+      const toolNames = (body.result?.tools ?? []).map((tool) => tool.name ?? "").filter((name) => name.length > 0);
+      return {
+        toolNames,
+        isTokenRefused: false
+      };
+    } catch {
+      return {
+        toolNames: [],
+        isTokenRefused: false
+      };
+    }
+  }
+  /**
+   * Sorts tool names into the adapters that registered them, and the tabs they name.
+   *
+   * A name carries its adapter in front of the first double underscore, and carries a tab suffix only
+   * when two tabs offer the same tool — see `docs/tool_naming_and_tab_identity.md`.
+   *
+   * The browser's own tools are left out. They are answered by the bridge rather than by any page, they
+   * are always there, and counting them as an adapter would report a page open when none is.
+   *
+   * @param toolNames - The names the host offered.
+   * @returns One entry per site adapter, by site slug, in alphabetical order.
+   */
+  static _groupByAdapter(toolNames) {
+    const bySlug = /* @__PURE__ */ new Map();
+    for (const name of toolNames) {
+      if (ToolNaming.belongsTo(name, ToolNaming.BROWSER_SLUG) === true) {
+        continue;
+      }
+      const parts = ToolNaming.unqualify(name);
+      const siteSlug = parts === null ? name : parts.siteSlug;
+      const adapter = bySlug.get(siteSlug) ?? {
+        siteSlug,
+        toolCount: 0,
+        tabIds: []
+      };
+      adapter.toolCount = adapter.toolCount + 1;
+      const tab = /__tab(\d+)$/.exec(name);
+      if (tab !== null) {
+        const tabId = Number.parseInt(tab[1], 10);
+        if (adapter.tabIds.includes(tabId) === false) {
+          adapter.tabIds.push(tabId);
+        }
+      }
+      bySlug.set(siteSlug, adapter);
+    }
+    const adapters = [...bySlug.values()];
+    for (const adapter of adapters) {
+      adapter.tabIds.sort((left, right) => left - right);
+    }
+    adapters.sort((left, right) => left.siteSlug.localeCompare(right.siteSlug));
+    return adapters;
+  }
+  /**
+   * The two steps only a person can take, named with the folder to pick.
+   *
+   * @param extensionDir - The folder to load at `chrome://extensions`.
+   * @returns The lines to print.
+   */
+  static _loadTheExtension(extensionDir) {
+    return [
+      "Chrome loads an unpacked extension by hand:",
+      "  1. Open chrome://extensions and turn on Developer mode.",
+      "  2. Choose Load unpacked, and select this folder:",
+      `     ${extensionDir}`
+    ];
+  }
+};
+
+// tools/npm_command_entry.ts
+var __filename3 = import.meta.filename;
+var __dirname3 = import.meta.dirname;
+var NpmCommandEntry = class _NpmCommandEntry {
+  static {
+    /** The path segments that name a folder npm fills for one run and empties whenever it decides to. */
+    this.CACHE_SEGMENTS = ["_npx", "_cacache"];
+  }
+  static {
+    /** The issue holding the plan this command is a milestone of. */
+    this.PLAN_URL = "https://github.com/jeromeetienne/webmcp_everywhere/issues/12";
+  }
+  static {
+    /** Where an agent is pointed once the extension is loaded and Chrome has started the host. */
+    this.ENDPOINT_URL = "http://127.0.0.1:8765/mcp";
+  }
+  /**
+   * Runs the subcommand the arguments name.
+   *
+   * @param argv - The arguments after the command name, which is `process.argv.slice(2)`.
+   * @returns Nothing.
+   */
+  static async run(argv) {
+    const subcommand = argv[0] ?? "install";
+    if (subcommand === "install") {
+      _NpmCommandEntry._install();
+      await _NpmCommandEntry._reportStatus(true);
+      return;
+    }
+    if (subcommand === "status") {
+      const report = await _NpmCommandEntry._reportStatus(false);
+      process.exitCode = report.isReady === true ? 0 : 1;
+      return;
+    }
+    if (subcommand === "uninstall") {
+      _NpmCommandEntry._uninstall();
+      return;
+    }
+    if (subcommand === "--version" || subcommand === "version") {
+      console.log(_NpmCommandEntry._extensionVersion());
+      return;
+    }
+    if (subcommand === "--help" || subcommand === "help") {
+      _NpmCommandEntry._usage(console.log);
+      return;
+    }
+    console.error(`webmcp_everywhere: no subcommand called ${subcommand}`);
+    _NpmCommandEntry._usage(console.error);
+    process.exitCode = 1;
+  }
+  ///////////////////////////////////////////////////////////////////////////////
+  ///////////////////////////////////////////////////////////////////////////////
+  //	Helpers
+  ///////////////////////////////////////////////////////////////////////////////
+  ///////////////////////////////////////////////////////////////////////////////
+  /**
+   * Names every path the installation is about to write, then writes them.
+   *
+   * The announcement comes first for the same reason the installer inside a release announces: from
+   * the moment the host manifest exists, Chrome starts a program outside the browser sandbox with the
+   * user's full rights, and that is not a thing to be opted into silently.
+   *
+   * @returns Nothing.
+   */
+  static _install() {
+    const planned = PackagedReleaseInstallation.plan({
+      sourceDir: __dirname3
+    });
+    console.log(`WebMCP Everywhere ${_NpmCommandEntry._extensionVersion()}`);
+    console.log("");
+    if (planned.isAlreadyInPlace === true) {
+      console.log(`This is already installed at ${planned.targetDir}, so only the registration runs again.`);
+    } else {
+      const verb = planned.isTargetDirReplaced === true ? "replaces the folder" : "writes the folder";
+      console.log(`This ${verb} ${planned.targetDir}`);
+      console.log(`with a copy of ${planned.sourceDir}`);
+      if (_NpmCommandEntry._isFolderNpmMayEmpty(planned.sourceDir) === true) {
+        console.log("");
+        console.log("The copy is made because npm empties the folder above whenever it decides to, and");
+        console.log("Chrome keeps an absolute path for both an unpacked extension and a native messaging");
+        console.log("host. Registering the folder npm owns would break the day npm cleared it.");
+      }
+    }
+    console.log("");
+    console.log("It is also about to write:");
+    for (const manifestPath of planned.nativeHost.manifests) {
+      console.log(`  ${manifestPath}`);
+    }
+    console.log("");
+    console.log(`Each of those tells Chrome to start: ${Path6.join(planned.targetDir, ReleaseLayout.LAUNCHER)}`);
+    console.log(`and to let only the extension ${planned.nativeHost.identifier} talk to it.`);
+    console.log("");
+    console.log("Chrome will start that program outside the browser sandbox, with your rights.");
+    console.log("To undo all of it: npx webmcp_everywhere uninstall");
+    console.log("");
+    const installed = PackagedReleaseInstallation.install({
+      sourceDir: __dirname3
+    });
+    console.log(`installed ${installed.targetDir}`);
+    for (const manifestPath of installed.nativeHost.manifests) {
+      console.log(`wrote     ${manifestPath}`);
+    }
+  }
+  /**
+   * Asks the running system whether the extension is loaded and reaching an agent, and says so.
+   *
+   * @param isAfterInstall - Whether this follows an installation, which changes what is left to say.
+   * @returns What the check found, so a caller can act on it.
+   */
+  static async _reportStatus(isAfterInstall) {
+    const report = await InstallationStatus.read();
+    console.log("");
+    console.log(report.summary);
+    if (report.remedy.length > 0) {
+      console.log("");
+      for (const line of report.remedy) {
+        console.log(line);
+      }
+    }
+    if (report.adapters.length > 0) {
+      console.log("");
+      const widest = Math.max(...report.adapters.map((adapter) => adapter.siteSlug.length));
+      for (const adapter of report.adapters) {
+        const tabs = adapter.tabIds.length === 0 ? "" : `   in ${adapter.tabIds.length === 1 ? "tab" : "tabs"} ${adapter.tabIds.join(", ")}`;
+        const count = `${adapter.toolCount}`.padStart(2);
+        console.log(`  ${adapter.siteSlug.padEnd(widest)}  ${count} tools${tabs}`);
+      }
+    }
+    const tokenPath = Path6.join(report.stateDir, "token");
+    if (report.isReady === true && report.endpoint !== null) {
+      console.log("");
+      console.log(`Point your agent at ${report.endpoint.url}, with the bearer token from`);
+      console.log(`  ${tokenPath}`);
+    } else if (isAfterInstall === true) {
+      console.log("");
+      console.log(`Once it is loaded, point your agent at ${_NpmCommandEntry.ENDPOINT_URL}, with the`);
+      console.log(`bearer token from ${tokenPath}`);
+    }
+    return report;
+  }
+  /**
+   * Removes the registration and the installation folder, and says what it left behind.
+   *
+   * @returns Nothing.
+   */
+  static _uninstall() {
+    const removed = PackagedReleaseInstallation.remove({
+      sourceDir: __dirname3
+    });
+    for (const manifest of removed.manifests) {
+      if (manifest.isRemoved === true) {
+        console.log(`removed ${manifest.path}`);
+        if (manifest.launcher !== null) {
+          console.log(`  it told Chrome to start: ${manifest.launcher}`);
+        }
+      } else {
+        console.log(`nothing to remove at ${manifest.path}`);
+      }
+    }
+    if (removed.isTargetDirRemoved === true) {
+      console.log(`removed ${removed.targetDir}`);
+    } else {
+      console.log(`nothing to remove at ${removed.targetDir}`);
+    }
+    console.log("");
+    console.log("Chrome will no longer start the native messaging host for this extension.");
+    console.log("The extension itself is removed at chrome://extensions, which this does not touch.");
+    console.log(`Your bearer token and your loaded adapters are left alone in ${removed.stateDir}`);
+    console.log(`To remove those as well: rm -rf ${removed.stateDir}`);
+  }
+  /**
+   * Prints what the command accepts.
+   *
+   * @param write - Where the lines go, so that an unknown subcommand can print this to standard error.
+   * @returns Nothing.
+   */
+  static _usage(write) {
+    write("");
+    write("  npx webmcp_everywhere              install it, then say whether it is working");
+    write("  npx webmcp_everywhere status       say whether it is working, and exit 1 when it is not");
+    write("  npx webmcp_everywhere uninstall    take the installation and the registration back out");
+    write("  npx webmcp_everywhere --version    print the version of the extension it carries");
+    write("");
+    write(`The plan this command follows is ${_NpmCommandEntry.PLAN_URL}`);
+  }
+  /**
+   * Answers whether npm empties the folder a path names.
+   *
+   * @param folder - The folder to test.
+   * @returns True when a segment of the path names one of npm's own caches.
+   */
+  static _isFolderNpmMayEmpty(folder) {
+    const segments = folder.split(Path6.sep);
+    return _NpmCommandEntry.CACHE_SEGMENTS.some((segment) => segments.includes(segment));
+  }
+  /**
+   * Reads the version out of the extension manifest this package carries.
+   *
+   * The packaged release holds a manifest of its own that npm publishes it with, and the version there
+   * and the version here are the same number; `tools/package_release.ts` refuses to package them apart.
+   * This one is read because it is the version of the thing a person loads into Chrome.
+   *
+   * @returns The version string, or `unknown` when the manifest is missing or unreadable.
+   */
+  static _extensionVersion() {
+    const manifestPath = Path6.join(__dirname3, ReleaseLayout.EXTENSION_DIR, ReleaseLayout.EXTENSION_MANIFEST);
+    if (Fs7.existsSync(manifestPath) === false) {
+      return "unknown";
+    }
+    try {
+      const manifest = JSON.parse(Fs7.readFileSync(manifestPath, "utf8"));
+      return manifest.version ?? "unknown";
+    } catch {
+      return "unknown";
+    }
+  }
+};
+await NpmCommandEntry.run(process.argv.slice(2));
+export {
+  NpmCommandEntry
+};