@kud/foxhop-cli 1.0.0

package/README.md

@@ -0,0 +1,33 @@
+# @kud/foxhop-cli
+
+The CLI and native-messaging host for [foxhop](https://github.com/kud/foxhop) — focus a
+specific Firefox tab from anywhere on macOS.
+
+> Requires the foxhop Firefox extension. See the
+> [project README](https://github.com/kud/foxhop#readme) for the full setup.
+
+## Install
+
+```sh
+npm install -g @kud/foxhop-cli
+foxhop install        # register the native messaging host with Firefox
+foxhop init           # seed ~/.config/foxhop/tabs.json
+```
+
+## Usage
+
+```sh
+foxhop focus chatgpt                       # focus a saved target, foregrounding Firefox
+foxhop focus --match figma.com --url https://figma.com
+foxhop list                                # saved targets (--json for machine output)
+foxhop tabs                                # currently open Firefox tabs (--json)
+foxhop add gmail --match mail.google.com --url https://mail.google.com --title Gmail
+foxhop remove gmail
+foxhop sync                                # generate per-tab Raycast hotkey scripts
+```
+
+Targets live in `~/.config/foxhop/tabs.json` (the source of truth). Each has `name`,
+`match`, optional `url`, `strategy` (hostname·prefix·exact·search) and `pick`
+(recent·first·pinned). Set `FOXHOP_BROWSER` if you don't run Firefox Nightly.
+
+MIT © Erwann Mest

package/dist/cli.js

@@ -0,0 +1,474 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { defineCommand, runMain } from "citty";
+import { spawn } from "child_process";
+
+// src/config.ts
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+var xdgConfigHome = process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
+var CONFIG_DIR = join(xdgConfigHome, "foxhop");
+var CONFIG_PATH = join(CONFIG_DIR, "tabs.json");
+var SCHEMA_PATH = join(CONFIG_DIR, "tabs.schema.json");
+var readConfig = () => {
+  if (!existsSync(CONFIG_PATH)) return { targets: [] };
+  try {
+    const parsed = JSON.parse(readFileSync(CONFIG_PATH, "utf8"));
+    return { targets: Array.isArray(parsed?.targets) ? parsed.targets : [] };
+  } catch {
+    return { targets: [] };
+  }
+};
+var findTarget = (config, name) => config.targets.find((target) => target.name === name);
+var SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "foxhop targets",
+  type: "object",
+  properties: {
+    targets: {
+      type: "array",
+      items: {
+        type: "object",
+        required: ["name", "match"],
+        additionalProperties: false,
+        properties: {
+          name: {
+            type: "string",
+            description: "Identifier used by `foxhop focus <name>`"
+          },
+          title: { type: "string", description: "Human-friendly label" },
+          match: {
+            type: "string",
+            description: "Substring matched against tab URLs/titles"
+          },
+          url: { type: "string", description: "Opened when no tab matches" },
+          strategy: {
+            enum: ["hostname", "prefix", "exact", "search"],
+            default: "hostname"
+          },
+          pick: {
+            enum: ["recent", "first", "pinned"],
+            default: "recent",
+            description: "Which tab to focus when several match"
+          }
+        }
+      }
+    }
+  }
+};
+var EXAMPLE = {
+  targets: [
+    {
+      name: "chatgpt",
+      title: "ChatGPT",
+      match: "chatgpt.com",
+      url: "https://chatgpt.com"
+    },
+    {
+      name: "todoist",
+      title: "Todoist",
+      match: "todoist.com",
+      url: "https://app.todoist.com"
+    }
+  ]
+};
+var writeSchema = () => {
+  mkdirSync(CONFIG_DIR, { recursive: true });
+  writeFileSync(SCHEMA_PATH, JSON.stringify(SCHEMA, null, 2) + "\n");
+};
+var writeConfig = (config) => {
+  writeSchema();
+  writeFileSync(
+    CONFIG_PATH,
+    JSON.stringify(
+      { $schema: "./tabs.schema.json", targets: config.targets },
+      null,
+      2
+    ) + "\n"
+  );
+};
+var writeExampleConfig = () => {
+  writeSchema();
+  if (!existsSync(CONFIG_PATH)) writeConfig(EXAMPLE);
+  return CONFIG_PATH;
+};
+var upsertTarget = (target) => {
+  const { targets } = readConfig();
+  const next = {
+    targets: [
+      ...targets.filter((existing) => existing.name !== target.name),
+      target
+    ]
+  };
+  writeConfig(next);
+  return next;
+};
+var removeTarget = (name) => {
+  const { targets } = readConfig();
+  const filtered = targets.filter((target) => target.name !== name);
+  const removed = filtered.length !== targets.length;
+  if (removed) writeConfig({ targets: filtered });
+  return { targets: filtered, removed };
+};
+
+// src/client.ts
+import net from "net";
+
+// src/constants.ts
+import { homedir as homedir2 } from "os";
+import { join as join2 } from "path";
+var HOST_NAME = "io.kud.foxhop";
+var EXTENSION_ID = "foxhop@kud.io";
+var SOCKET_PATH = join2(homedir2(), ".foxhop.sock");
+var MANIFEST_DIR = join2(
+  homedir2(),
+  "Library",
+  "Application Support",
+  "Mozilla",
+  "NativeMessagingHosts"
+);
+var MANIFEST_PATH = join2(MANIFEST_DIR, `${HOST_NAME}.json`);
+
+// src/client.ts
+var sendToHost = (request, timeoutMs = 5e3) => new Promise((resolve, reject) => {
+  const socket = net.createConnection(SOCKET_PATH);
+  let response = "";
+  const timer = setTimeout(() => {
+    socket.destroy();
+    reject(new Error("timeout"));
+  }, timeoutMs);
+  socket.setEncoding("utf8");
+  socket.on("connect", () => socket.write(JSON.stringify(request) + "\n"));
+  socket.on("data", (chunk) => response += chunk);
+  socket.on("end", () => {
+    clearTimeout(timer);
+    try {
+      resolve(JSON.parse(response));
+    } catch {
+      resolve(null);
+    }
+  });
+  socket.on("error", (error) => {
+    clearTimeout(timer);
+    reject(error);
+  });
+});
+
+// src/install.ts
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync2, chmodSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join as join3 } from "path";
+var install = () => {
+  const distDir = dirname(fileURLToPath(import.meta.url));
+  const hostEntry = join3(distDir, "host-cli.js");
+  chmodSync(hostEntry, 493);
+  mkdirSync2(MANIFEST_DIR, { recursive: true });
+  const manifest = {
+    name: HOST_NAME,
+    description: "foxhop native messaging host",
+    path: hostEntry,
+    type: "stdio",
+    allowed_extensions: [EXTENSION_ID]
+  };
+  writeFileSync2(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + "\n");
+  process.stdout.write(
+    `foxhop: installed native host manifest
+  manifest \u2192 ${MANIFEST_PATH}
+  host     \u2192 ${hostEntry}
+`
+  );
+};
+
+// src/sync.ts
+import {
+  mkdirSync as mkdirSync3,
+  writeFileSync as writeFileSync3,
+  chmodSync as chmodSync2,
+  existsSync as existsSync2,
+  readdirSync,
+  readFileSync as readFileSync2,
+  rmSync
+} from "fs";
+import { join as join4 } from "path";
+var MARKER = "@foxhop.generated";
+var defaultScriptsDir = () => join4(CONFIG_DIR, "scripts");
+var stableNode = (node) => {
+  const index = node.indexOf("/installs/node/");
+  if (index === -1) return node;
+  const shim = node.slice(0, index) + "/shims/node";
+  return existsSync2(shim) ? shim : node;
+};
+var scriptBody = (node, cli, target) => {
+  const title = target.title ?? target.name;
+  return `#!/bin/bash
+
+# @raycast.schemaVersion 1
+# @raycast.title Focus ${title}
+# @raycast.mode silent
+# @raycast.packageName foxhop
+# @raycast.icon \u{1F98A}
+
+# Documentation:
+# @raycast.description Focus the ${title} tab in Firefox (opens it if not already open).
+# @raycast.author kud
+# ${MARKER}
+
+exec "${stableNode(node)}" "${cli}" focus ${target.name}
+`;
+};
+var isGenerated = (path) => {
+  try {
+    return readFileSync2(path, "utf8").includes(MARKER);
+  } catch {
+    return false;
+  }
+};
+var sync = (node, cli, dir = defaultScriptsDir()) => {
+  const { targets } = readConfig();
+  mkdirSync3(dir, { recursive: true });
+  const wanted = new Set(targets.map((target) => `focus-${target.name}.sh`));
+  const removed = (existsSync2(dir) ? readdirSync(dir) : []).filter((file) => file.startsWith("focus-") && file.endsWith(".sh")).filter((file) => !wanted.has(file) && isGenerated(join4(dir, file)));
+  for (const file of removed) rmSync(join4(dir, file));
+  for (const target of targets) {
+    const file = join4(dir, `focus-${target.name}.sh`);
+    writeFileSync3(file, scriptBody(node, cli, target));
+    chmodSync2(file, 493);
+  }
+  return { dir, written: targets.length, removed: removed.length };
+};
+
+// src/cli.ts
+import { fileURLToPath as fileURLToPath2 } from "url";
+var browserApp = () => process.env.FOXHOP_BROWSER ?? "Firefox Nightly";
+var foreground = () => spawn("open", ["-a", browserApp()], {
+  stdio: "ignore",
+  detached: true
+}).unref();
+var openUrl = (url) => spawn("open", [url], { stdio: "ignore", detached: true }).unref();
+var focus = defineCommand({
+  meta: {
+    name: "focus",
+    description: "Focus a Firefox tab by saved target name, or an ad-hoc match"
+  },
+  args: {
+    name: {
+      type: "positional",
+      required: false,
+      description: "Saved target name (see `foxhop list`)"
+    },
+    match: {
+      type: "string",
+      description: "Ad-hoc substring to match against tab URLs"
+    },
+    url: { type: "string", description: "URL to open when no tab matches" },
+    strategy: {
+      type: "string",
+      description: "hostname | prefix | exact | search"
+    },
+    pick: {
+      type: "string",
+      description: "recent | first | pinned (which tab when several match)"
+    }
+  },
+  run: async ({ args }) => {
+    const request = args.match ? {
+      op: "focus",
+      match: args.match,
+      url: args.url,
+      strategy: args.strategy ?? "hostname",
+      pick: args.pick ?? "recent"
+    } : resolveNamed(String(args.name ?? ""));
+    if (!request) {
+      console.error(
+        `foxhop: no target named "${args.name}". Edit ${CONFIG_PATH}, or run \`foxhop list\` / \`foxhop init\`.`
+      );
+      process.exit(1);
+    }
+    try {
+      const ack = await sendToHost(request);
+      if (ack?.ok && ack.action !== "not-found") foreground();
+      else
+        console.error(
+          `foxhop: ${ack?.error ?? "no matching tab and no url to open"}`
+        );
+    } catch {
+      if ("url" in request && request.url) {
+        openUrl(request.url);
+      } else {
+        console.error(
+          "foxhop: cannot reach the host \u2014 is Firefox running with the foxhop extension?"
+        );
+        process.exit(1);
+      }
+    }
+  }
+});
+var resolveNamed = (name) => {
+  const target = findTarget(readConfig(), name);
+  if (!target) return null;
+  return {
+    op: "focus",
+    match: target.match,
+    url: target.url,
+    strategy: target.strategy ?? "hostname",
+    pick: target.pick ?? "recent"
+  };
+};
+var list = defineCommand({
+  meta: { name: "list", description: "List saved focus targets" },
+  args: { json: { type: "boolean", description: "Output JSON" } },
+  run: ({ args }) => {
+    const { targets } = readConfig();
+    if (args.json) {
+      process.stdout.write(JSON.stringify(targets, null, 2) + "\n");
+      return;
+    }
+    if (!targets.length) {
+      console.log(
+        `No targets yet. Run \`foxhop init\` for an example, or edit ${CONFIG_PATH}.`
+      );
+      return;
+    }
+    for (const target of targets) {
+      console.log(`${target.name.padEnd(16)} ${target.match}`);
+    }
+  }
+});
+var tabs = defineCommand({
+  meta: { name: "tabs", description: "List currently open Firefox tabs" },
+  args: { json: { type: "boolean", description: "Output JSON" } },
+  run: async ({ args }) => {
+    const ack = await sendToHost({ op: "list" }).catch(() => null);
+    const openTabs = ack?.tabs ?? [];
+    if (args.json) {
+      process.stdout.write(JSON.stringify(openTabs, null, 2) + "\n");
+      return;
+    }
+    if (!openTabs.length) {
+      console.error(
+        "foxhop: no tabs (is Firefox running with the foxhop extension?)"
+      );
+      process.exit(1);
+    }
+    for (const tab of openTabs) {
+      console.log(`${tab.title}
+  ${tab.url}`);
+    }
+  }
+});
+var init = defineCommand({
+  meta: {
+    name: "init",
+    description: "Write an example config to ~/.config/foxhop/tabs.json"
+  },
+  run: () => {
+    const path = writeExampleConfig();
+    console.log(`foxhop: wrote example config and schema next to ${path}`);
+  }
+});
+var installCommand = defineCommand({
+  meta: {
+    name: "install",
+    description: "Register the native messaging host manifest with Firefox"
+  },
+  run: () => install()
+});
+var syncCommand = defineCommand({
+  meta: {
+    name: "sync",
+    description: "Generate a Raycast script command per saved target (for per-tab hotkeys)"
+  },
+  args: {
+    dir: {
+      type: "string",
+      description: `Output directory (default: ${defaultScriptsDir()})`
+    }
+  },
+  run: ({ args }) => {
+    const result = sync(
+      process.execPath,
+      fileURLToPath2(import.meta.url),
+      args.dir
+    );
+    console.log(
+      `foxhop: wrote ${result.written} script(s)` + (result.removed ? `, removed ${result.removed} stale` : "") + ` in ${result.dir}`
+    );
+    console.log(
+      "Add that folder in Raycast \u2192 Extensions \u2192 Script Commands \u2192 Add Directories, then assign hotkeys."
+    );
+  }
+});
+var add = defineCommand({
+  meta: { name: "add", description: "Add or update a target in tabs.json" },
+  args: {
+    name: {
+      type: "positional",
+      required: true,
+      description: "Target id (used by `foxhop focus <name>`)"
+    },
+    match: {
+      type: "string",
+      required: true,
+      description: "Substring matched against tab URLs"
+    },
+    url: { type: "string", description: "URL opened when no tab matches" },
+    title: { type: "string", description: "Human-friendly label" },
+    strategy: {
+      type: "string",
+      description: "hostname | prefix | exact | search"
+    },
+    pick: {
+      type: "string",
+      description: "recent | first | pinned (which tab when several match)"
+    }
+  },
+  run: ({ args }) => {
+    upsertTarget({
+      name: String(args.name),
+      match: String(args.match),
+      url: args.url,
+      title: args.title,
+      strategy: args.strategy,
+      pick: args.pick
+    });
+    console.log(`foxhop: saved "${args.name}"`);
+  }
+});
+var remove = defineCommand({
+  meta: { name: "remove", description: "Remove a target from tabs.json" },
+  args: {
+    name: {
+      type: "positional",
+      required: true,
+      description: "Target id to remove"
+    }
+  },
+  run: ({ args }) => {
+    const { removed } = removeTarget(String(args.name));
+    if (!removed) {
+      console.error(`foxhop: no target named "${args.name}"`);
+      process.exit(1);
+    }
+    console.log(`foxhop: removed "${args.name}"`);
+  }
+});
+runMain(
+  defineCommand({
+    meta: {
+      name: "foxhop",
+      description: "Focus specific Firefox tabs from anywhere on macOS"
+    },
+    subCommands: {
+      focus,
+      list,
+      tabs,
+      add,
+      remove,
+      init,
+      sync: syncCommand,
+      install: installCommand
+    }
+  })
+);

package/dist/host-cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+
+// src/host.ts
+import net from "net";
+import { existsSync, unlinkSync } from "fs";
+
+// src/framing.ts
+import { endianness } from "os";
+var littleEndian = endianness() === "LE";
+var encodeMessage = (message) => {
+  const json = Buffer.from(JSON.stringify(message), "utf8");
+  const header = Buffer.allocUnsafe(4);
+  if (littleEndian) header.writeUInt32LE(json.length, 0);
+  else header.writeUInt32BE(json.length, 0);
+  return Buffer.concat([header, json]);
+};
+var createMessageReader = (onMessage) => {
+  let buffer = Buffer.alloc(0);
+  return (chunk) => {
+    buffer = Buffer.concat([buffer, chunk]);
+    while (buffer.length >= 4) {
+      const length = littleEndian ? buffer.readUInt32LE(0) : buffer.readUInt32BE(0);
+      if (buffer.length < 4 + length) break;
+      const json = buffer.subarray(4, 4 + length).toString("utf8");
+      buffer = buffer.subarray(4 + length);
+      onMessage(JSON.parse(json));
+    }
+  };
+};
+
+// src/constants.ts
+import { homedir } from "os";
+import { join } from "path";
+var HOST_NAME = "io.kud.foxhop";
+var EXTENSION_ID = "foxhop@kud.io";
+var SOCKET_PATH = join(homedir(), ".foxhop.sock");
+var MANIFEST_DIR = join(
+  homedir(),
+  "Library",
+  "Application Support",
+  "Mozilla",
+  "NativeMessagingHosts"
+);
+var MANIFEST_PATH = join(MANIFEST_DIR, `${HOST_NAME}.json`);
+var REQUEST_TIMEOUT_MS = 3e3;
+
+// src/host.ts
+var runHost = () => {
+  const pending = /* @__PURE__ */ new Map();
+  let sequence = 0;
+  const sendToExtension = (message) => process.stdout.write(encodeMessage(message));
+  process.stdin.on(
+    "data",
+    createMessageReader((ack) => {
+      const resolve = pending.get(ack.reqId);
+      if (!resolve) return;
+      pending.delete(ack.reqId);
+      resolve(ack);
+    })
+  );
+  process.stdin.on("end", () => process.exit(0));
+  if (existsSync(SOCKET_PATH)) {
+    try {
+      unlinkSync(SOCKET_PATH);
+    } catch {
+    }
+  }
+  const server = net.createServer((socket) => {
+    socket.setEncoding("utf8");
+    let raw = "";
+    socket.on("data", (chunk) => {
+      raw += chunk;
+      const newline = raw.indexOf("\n");
+      if (newline === -1) return;
+      let request;
+      try {
+        request = JSON.parse(raw.slice(0, newline));
+      } catch {
+        socket.end(JSON.stringify({ ok: false, error: "bad-request" }));
+        return;
+      }
+      const reqId = ++sequence;
+      const timeout = setTimeout(() => {
+        if (!pending.has(reqId)) return;
+        pending.delete(reqId);
+        socket.end(JSON.stringify({ ok: false, error: "timeout" }));
+      }, REQUEST_TIMEOUT_MS);
+      pending.set(reqId, (ack) => {
+        clearTimeout(timeout);
+        socket.end(JSON.stringify(ack));
+      });
+      sendToExtension({ reqId, ...request });
+    });
+  });
+  server.on("error", (error) => {
+    process.stderr.write(`foxhop-host: socket error: ${error.message}
+`);
+  });
+  server.listen(SOCKET_PATH);
+};
+
+// src/install.ts
+import { mkdirSync, writeFileSync, chmodSync } from "fs";
+import { fileURLToPath } from "url";
+import { dirname, join as join2 } from "path";
+var install = () => {
+  const distDir = dirname(fileURLToPath(import.meta.url));
+  const hostEntry = join2(distDir, "host-cli.js");
+  chmodSync(hostEntry, 493);
+  mkdirSync(MANIFEST_DIR, { recursive: true });
+  const manifest = {
+    name: HOST_NAME,
+    description: "foxhop native messaging host",
+    path: hostEntry,
+    type: "stdio",
+    allowed_extensions: [EXTENSION_ID]
+  };
+  writeFileSync(MANIFEST_PATH, JSON.stringify(manifest, null, 2) + "\n");
+  process.stdout.write(
+    `foxhop: installed native host manifest
+  manifest \u2192 ${MANIFEST_PATH}
+  host     \u2192 ${hostEntry}
+`
+  );
+};
+
+// src/host-cli.ts
+var command = process.argv[2];
+if (command === "install") install();
+else runHost();

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@kud/foxhop-cli",
+  "version": "1.0.0",
+  "description": "foxhop CLI and native messaging host — focus specific Firefox tabs from macOS",
+  "type": "module",
+  "license": "MIT",
+  "author": "Erwann Mest <m@kud.io>",
+  "homepage": "https://github.com/kud/foxhop#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kud/foxhop.git",
+    "directory": "cli"
+  },
+  "bugs": {
+    "url": "https://github.com/kud/foxhop/issues"
+  },
+  "keywords": [
+    "firefox",
+    "macos",
+    "raycast",
+    "cli",
+    "tabs",
+    "native-messaging",
+    "focus"
+  ],
+  "bin": {
+    "foxhop": "./dist/cli.js",
+    "foxhop-host": "./dist/host-cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "citty": "0.2.2"
+  },
+  "devDependencies": {
+    "@types/node": "26.0.0",
+    "tsup": "8.5.1",
+    "tsx": "4.22.4",
+    "typescript": "6.0.3",
+    "vitest": "4.1.9"
+  }
+}