react-hooks-global-states-debug 16.0.4 → 16.0.5

package/cli.mjs

@@ -0,0 +1,706 @@
+#!/usr/bin/env node
+
+// src/agent/protocol.ts
+var AGENT_DEFAULT_PORT = 7787;
+var AGENT_CLOSE_SUPERSEDED = 4001;
+var ALL_STORES = "*";
+
+// src/cli/args.ts
+var DEFAULT_TIMEOUT_SECONDS = 10;
+var HELP = `rgsh: see what happens inside your stores from a terminal, and drive them
+
+WHAT IT DOES
+  Connects to the React Global State Hooks DevTools panel and streams one block per store action:
+  the store, the action and its input, the state changes it caused, the result or error, and the
+  duration. Other commands read a store, run an action, or change its state.
+
+BEFORE YOU START
+  1. The app must import the debug package (import 'react-hooks-global-states/debug').
+  2. Chrome has the DevTools extension, with DevTools open on the app tab and the
+     react-global-state-hooks panel opened once. rgsh cannot start without it.
+  3. Same port on both sides: rgsh listens on 7787 by default; change it with --port and in the
+     panel under gear > Terminal connection.
+
+DISCOVER
+  rgsh --list                       every store: name or creation location, state preview, actions
+  rgsh                              pick stores with the arrow keys (a list when there is no terminal)
+  rgsh state <store> [path]         current state and metadata. path: todos[0].done, user.name
+                                    A store is a name, or the creation location of an unnamed store
+                                    (ShoppingCart.tsx:23), as printed by --list.
+
+WATCH
+  rgsh --store todos                one store
+  rgsh --store todos,auth           several (comma separated, or repeat --store)
+  rgsh --store "*"                  every store: DevTools does more work and the stream is much larger
+
+CHANGE
+  rgsh action <store> <name> [args...]     run an action:  rgsh action todos add "Write the docs"
+  rgsh patch  <store> <json>               objects merge into the state, anything else replaces it
+                                           rgsh patch todos '{"filter":"done"}'   rgsh patch counter 5
+  rgsh set    <store> <json>               replace the whole state (like the State tab editor)
+  Each command prints the resulting block (state changes, result or error) and exits.
+
+VALUES
+  Arguments and states are JSON: 5, true, null, {"a":1}, ["x"], "text". A plain word is text.
+  A value that starts with { [ or " must be valid JSON. Never code: nothing is evaluated.
+  Numbers and booleans that should be text need quotes: '"5"'.
+
+OPTIONS
+  --store, -s <names>    stores to watch
+  --list, -l             list stores and exit
+  --port <number>        port to listen on (default ${AGENT_DEFAULT_PORT}); must match the panel
+  --timeout <seconds>    how long action/patch/set wait for the result (default ${DEFAULT_TIMEOUT_SECONDS})
+  --help, -h
+
+READING THE OUTPUT
+  12:03:41.221 [todos] add("Write the docs")      time, store, action(input)
+    state:                                        state (1/2), (2/2)... when the action set state several times
+      todos[2]: undefined \u2192 {"id":3}              path: before \u2192 after; undefined = did not exist / removed
+    result: {"ok":true}                           omitted when the action returned nothing
+    error: Error: boom                            instead of result when the action threw
+    duration: 6ms
+  [name #2] means several live instances share that store. "setState" is a direct state change.
+  "store created" / "store removed": the store appeared or disappeared (mount, unmount, reload).
+  Events print when an action finishes, so a slow async action appears after it settles.
+
+EXIT CODES
+  0 done   1 failed (unknown store or action, not allowed, action threw)   2 no --store given, no terminal
+  3 sent, but the page reported nothing within --timeout
+
+GOOD TO KNOW
+  - Unnamed stores are identified by where they were created; name your stores in minified builds.
+  - Metadata shown by "state" is what the page announced when the store was created. Changes made
+    later with setMetadata are not reported by the debug package.
+  - Values that cannot be serialized (functions, DOM nodes) appear as {"__non_serializable__": ...}
+    and are kept as they are when you patch or set.
+  - Large values are cut with an explicit marker such as \u2026(+120 chars) or \u2026(+8 items).
+  - Only one store at a time for action, set, patch and state. A store with several live
+    instances is refused.
+  - Ctrl+C stops watching; DevTools goes back to normal and the terminal work stops.`;
+var UsageError = class extends Error {
+};
+var parseValue = (text) => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    if (/^\s*[{["]/.test(text)) throw new UsageError(`Not valid JSON: ${text}`);
+    return text;
+  }
+};
+var parseCommand = (positionals) => {
+  const [name, store, ...rest] = positionals;
+  if (name === void 0) return null;
+  if (name === "action") {
+    const [action, ...args] = rest;
+    if (!store || !action) throw new UsageError("Usage: rgsh action <store> <action> [args...]");
+    return { kind: "action", store, action, args: args.map(parseValue) };
+  }
+  if (name === "set" || name === "patch") {
+    if (!store || rest.length !== 1) throw new UsageError(`Usage: rgsh ${name} <store> <json>`);
+    const value = parseValue(rest[0]);
+    return name === "set" ? { kind: "set", store, state: value } : { kind: "patch", store, patch: value };
+  }
+  if (name === "state") {
+    if (!store || rest.length > 1) throw new UsageError("Usage: rgsh state <store> [path]");
+    return { kind: "state", store, path: rest[0] ?? "" };
+  }
+  throw new UsageError(`Unknown command "${name}"`);
+};
+var parseArgs = (argv) => {
+  const options = {
+    targets: [],
+    command: null,
+    timeoutSeconds: DEFAULT_TIMEOUT_SECONDS,
+    list: false,
+    help: false,
+    port: AGENT_DEFAULT_PORT
+  };
+  const positionals = [];
+  const takeValue = (flag, inline, index) => {
+    if (inline !== void 0) return [inline, index];
+    const value = argv[index + 1];
+    if (value === void 0 || value.startsWith("-") && value !== ALL_STORES) {
+      throw new UsageError(`${flag} needs a value`);
+    }
+    return [value, index + 1];
+  };
+  for (let index = 0; index < argv.length; index++) {
+    const [flag, inline] = argv[index].split(/=(.*)/s, 2);
+    if (flag === "--help" || flag === "-h") options.help = true;
+    else if (flag === "--list" || flag === "-l") options.list = true;
+    else if (flag === "--store" || flag === "-s") {
+      const [value, next] = takeValue(flag, inline, index);
+      index = next;
+      options.targets.push(...value.split(",").map((target) => target.trim()).filter(Boolean));
+    } else if (flag === "--timeout") {
+      const [value, next] = takeValue(flag, inline, index);
+      index = next;
+      options.timeoutSeconds = Number(value);
+      if (!(options.timeoutSeconds > 0)) throw new UsageError(`--timeout must be a positive number, got "${value}"`);
+    } else if (flag === "--port") {
+      const [value, next] = takeValue(flag, inline, index);
+      index = next;
+      options.port = Number(value);
+      if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65535) {
+        throw new UsageError(`--port must be a number between 1 and 65535, got "${value}"`);
+      }
+    } else if (argv[index].startsWith("-") && argv[index] !== ALL_STORES && !/^-\d/.test(argv[index])) {
+      throw new UsageError(`Unknown option "${argv[index]}"`);
+    } else {
+      positionals.push(argv[index]);
+    }
+  }
+  options.command = parseCommand(positionals);
+  if (options.command && options.targets.length) {
+    throw new UsageError("--store does not combine with state/action/set/patch: name the store after the command");
+  }
+  return options;
+};
+
+// src/cli/format.ts
+var INLINE_MAX = 100;
+var pad = (value, size = 2) => String(value).padStart(size, "0");
+var formatTime = (at) => {
+  const date = new Date(at);
+  return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}`;
+};
+var formatStoreRef = ({ label, instance }) => `[${label}${instance ? ` #${instance}` : ""}]`;
+var formatValue = (value, indent) => {
+  if (value === void 0) return "undefined";
+  const inline = JSON.stringify(value);
+  if (inline.length <= INLINE_MAX) return inline;
+  return JSON.stringify(value, null, 2).replace(/\n/g, `
+${indent}`);
+};
+var formatChange = (change, indent) => {
+  const { path, before, after } = change;
+  if (!("before" in change) && !("after" in change)) return path;
+  return `${path || "(state)"}: ${formatValue(before, indent)} \u2192 ${formatValue(after, indent)}`;
+};
+var formatSteps = (event) => {
+  const { steps, stateCalls } = event;
+  if (!stateCalls) return [];
+  if (!steps.length) return ["  state: no change"];
+  return steps.flatMap((changes, index) => {
+    const title = steps.length > 1 ? `  state (${index + 1}/${steps.length}):` : "  state:";
+    return [title, ...changes.map((change) => `    ${formatChange(change, "    ")}`)];
+  });
+};
+var formatAction = (event) => {
+  const { store, action, input, result, durationMs } = event;
+  const call = action === "setState" ? "setState" : `${action}(${(input ?? []).map((arg) => JSON.stringify(arg)).join(", ")})`;
+  const lines = [`${formatTime(event.at)} ${formatStoreRef(store)} ${call}`, ...formatSteps(event)];
+  if (result && "error" in result) lines.push(`  error: ${result.error}`);
+  else if (result && result.value !== void 0) lines.push(`  result: ${formatValue(result.value, "  ")}`);
+  if (durationMs !== void 0) lines.push(`  duration: ${durationMs}ms`);
+  return lines;
+};
+var formatEvent = (event) => {
+  if (event.kind === "action") return formatAction(event).join("\n");
+  const what = event.kind === "store-created" ? "store created" : "store removed";
+  return `${formatTime(event.at)} ${formatStoreRef(event.store)} ${what}`;
+};
+var storeTitle = (store) => {
+  if (store.name) return store.instances > 1 ? `${store.name} (${store.instances} instances)` : store.name;
+  return `unnamed \u2014 ${store.location ?? "unknown location"}`;
+};
+var storeLabel = (store) => store.name ?? `unnamed ${store.location ?? ""}`.trim();
+var oneLine = (text, max = 120) => {
+  const flat = text.replace(/\s*\n\s*/g, " ");
+  return flat.length > max ? `${flat.slice(0, max)}\u2026` : flat;
+};
+var formatStoreList = (stores) => {
+  if (!stores.length) return "No stores known by DevTools yet. Load the app with the debug package imported.";
+  return stores.map(
+    (store) => [
+      storeTitle(store),
+      ...store.name && store.location ? [`  at ${store.location}`] : [],
+      `  state: ${oneLine(store.preview)}`,
+      ...store.actions.length ? [`  actions: ${store.actions.join(", ")}`] : []
+    ].join("\n")
+  ).join("\n\n");
+};
+var formatState = (reply) => {
+  const pretty = (value) => value === void 0 ? "undefined" : JSON.stringify(value, null, 2);
+  return [
+    `${formatStoreRef(reply.store)} state${reply.path ? ` at ${reply.path}` : ""}:`,
+    pretty(reply.state),
+    "",
+    "metadata (as announced when the store was created; later setMetadata calls are not reported):",
+    pretty(reply.metadata)
+  ].join("\n");
+};
+
+// src/cli/resolve.ts
+var MAX_CANDIDATES = 8;
+var editDistance = (a, b) => {
+  let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i++) {
+    const current = [i];
+    for (let j = 1; j <= b.length; j++) {
+      current[j] = Math.min(previous[j] + 1, current[j - 1] + 1, previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    previous = current;
+  }
+  return previous[b.length];
+};
+var findCandidates = (target, stores) => {
+  const needle = target.toLowerCase();
+  const labels = stores.map(storeLabel);
+  const close = labels.filter((label) => {
+    const candidate = label.toLowerCase();
+    return candidate.includes(needle) || needle.includes(candidate) || editDistance(candidate, needle) <= 2;
+  });
+  return (close.length ? close : labels).slice(0, MAX_CANDIDATES);
+};
+var resolveTargets = (targets, stores) => {
+  const selectors = /* @__PURE__ */ new Set();
+  const unknown = [];
+  for (const target of targets) {
+    const byName = stores.filter((store) => store.name === target);
+    const matches = byName.length ? byName : stores.filter((store) => store.location?.endsWith(target));
+    if (!matches.length) {
+      unknown.push({ target, candidates: findCandidates(target, stores) });
+      continue;
+    }
+    for (const store of matches) selectors.add(store.selector);
+  }
+  return { selectors: [...selectors], unknown };
+};
+
+// src/cli/server.ts
+var REQUEST_TIMEOUT_MS = 1e4;
+var PanelSession = class {
+  constructor(socket, hello) {
+    this.socket = socket;
+    this.hello = hello;
+    this.replyWaiters = /* @__PURE__ */ new Set();
+    this.eventListeners = [];
+    this.closeListeners = [];
+    socket.on("message", (data) => this.receive(data.toString()));
+    socket.on("close", () => {
+      for (const listener of this.closeListeners) listener();
+    });
+  }
+  receive(text) {
+    let message;
+    try {
+      message = JSON.parse(text);
+    } catch {
+      return;
+    }
+    if (message.type === "EVENT") {
+      for (const listener of this.eventListeners) listener(message.event);
+      return;
+    }
+    for (const waiter of [...this.replyWaiters]) waiter(message);
+  }
+  onEvent(listener) {
+    this.eventListeners.push(listener);
+  }
+  onClose(listener) {
+    this.closeListeners.push(listener);
+  }
+  send(message) {
+    this.socket.send(JSON.stringify(message));
+  }
+  /** Sends a request and resolves with the first reply of one of the expected types. */
+  request(message, expected) {
+    return new Promise((resolve, reject) => {
+      const finish = () => {
+        clearTimeout(timer);
+        this.replyWaiters.delete(waiter);
+        this.closeListeners = this.closeListeners.filter((listener) => listener !== onClose);
+      };
+      const waiter = (reply) => {
+        if (!expected.includes(reply.type)) return;
+        finish();
+        resolve(reply);
+      };
+      const onClose = () => {
+        finish();
+        reject(new Error("DevTools panel disconnected"));
+      };
+      const timer = setTimeout(() => {
+        finish();
+        reject(new Error(`DevTools did not answer ${message.type} in ${REQUEST_TIMEOUT_MS / 1e3}s`));
+      }, REQUEST_TIMEOUT_MS);
+      this.replyWaiters.add(waiter);
+      this.closeListeners.push(onClose);
+      this.send(message);
+    });
+  }
+};
+var isAllowedOrigin = (origin) => origin === void 0 || origin.startsWith("chrome-extension://");
+var MissingWsError = class extends Error {
+  constructor() {
+    super(
+      [
+        "rgsh needs the 'ws' package to talk to the DevTools extension, and it is not installed in this project.",
+        "Install it as a dev dependency:",
+        "  yarn add -D ws",
+        "  npm install -D ws",
+        "  pnpm add -D ws"
+      ].join("\n")
+    );
+    this.name = "MissingWsError";
+  }
+};
+var loadWebSocketServer = async () => {
+  try {
+    const ws = await import("ws");
+    return ws.WebSocketServer ?? ws.default.Server;
+  } catch (error) {
+    if (error.code === "ERR_MODULE_NOT_FOUND") throw new MissingWsError();
+    throw error;
+  }
+};
+var startServer = async (port) => {
+  const WebSocketServer = await loadWebSocketServer();
+  return new Promise((resolve, reject) => {
+    const panelListeners = [];
+    let current = null;
+    const wss = new WebSocketServer({
+      host: "127.0.0.1",
+      port,
+      verifyClient: ({ origin }) => isAllowedOrigin(origin)
+    });
+    wss.once("error", reject);
+    wss.on("connection", (socket) => {
+      socket.once("message", (data) => {
+        let hello;
+        try {
+          hello = JSON.parse(data.toString());
+        } catch {
+          return socket.close();
+        }
+        if (hello.type !== "HELLO") return socket.close();
+        current?.close(AGENT_CLOSE_SUPERSEDED, "a newer DevTools panel connected");
+        current = socket;
+        socket.on("close", () => {
+          if (current === socket) current = null;
+        });
+        const panel = new PanelSession(socket, hello);
+        for (const listener of panelListeners) listener(panel);
+      });
+    });
+    wss.once("listening", () => {
+      wss.off("error", reject);
+      wss.on("error", () => void 0);
+      resolve({
+        port: wss.address().port,
+        onPanel: (listener) => panelListeners.push(listener),
+        close: () => new Promise((done) => {
+          for (const client of wss.clients) client.close();
+          wss.close(() => done());
+        })
+      });
+    });
+  });
+};
+
+// src/cli/run.ts
+var EXIT = { ok: 0, failed: 1, needsTarget: 2, noOutcome: 3 };
+var ALL_WARNING = 'warning: --store "*" listens to every store. DevTools does extra processing for every state change and this stream gets much larger. Naming the stores you need (--store todos,auth) is more efficient.';
+var RESUBSCRIBE_ATTEMPTS = 5;
+var RESUBSCRIBE_DELAY_MS = 1e3;
+var wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var describePanel = ({ tabId, page }) => [tabId !== null ? `tab ${tabId}` : null, page].filter(Boolean).join(" ");
+var run = async (options, io, signal) => {
+  let server;
+  try {
+    server = await startServer(options.port);
+  } catch (error) {
+    const { code } = error;
+    io.err(
+      error instanceof MissingWsError ? error.message : code === "EADDRINUSE" ? `Port ${options.port} is already in use. Is another rgsh running? Stop it or pass --port.` : `Could not start the listener on port ${options.port}: ${error.message}`
+    );
+    return EXIT.failed;
+  }
+  return new Promise((resolve) => {
+    let current = null;
+    let subscribed = null;
+    let finished = false;
+    let commandStarted = false;
+    const finish = async (code) => {
+      if (finished) return;
+      finished = true;
+      await server.close();
+      resolve(code);
+    };
+    signal.addEventListener("abort", () => void finish(EXIT.ok), { once: true });
+    const subscribe = async (panel, selectors) => {
+      const reply = await panel.request({ type: "SUBSCRIBE", selectors }, ["SUBSCRIBED", "REJECTED"]);
+      if (reply.type === "REJECTED") return reply;
+      subscribed = selectors;
+      const names = reply.matched.length ? reply.matched.map(formatStoreRef).join(" ") : "(no store yet)";
+      io.err(`Listening to ${reply.all ? "all stores" : names}. Press Ctrl+C to stop.`);
+      return null;
+    };
+    const runCommand = async (panel, command) => {
+      const { stores } = await panel.request({ type: "GET_STORES" }, ["AVAILABLE_STORES"]);
+      const resolved = resolveTargets([command.store], stores);
+      if (resolved.unknown.length) {
+        const [{ target, candidates }] = resolved.unknown;
+        io.err(`Store "${target}" was not found. Available: ${candidates.join(", ") || "(none)"}`);
+        return finish(EXIT.failed);
+      }
+      const [selector] = resolved.selectors;
+      if (resolved.selectors.length !== 1) {
+        io.err(`"${command.store}" matches ${resolved.selectors.length} stores. Name exactly one.`);
+        return finish(EXIT.failed);
+      }
+      if (command.kind === "state") {
+        const reply2 = await panel.request({ type: "GET_STATE", selector, path: command.path }, ["STATE", "REQUEST_REJECTED"]);
+        if (reply2.type === "REQUEST_REJECTED") {
+          io.err(reply2.reason);
+          return finish(EXIT.failed);
+        }
+        if (!reply2.found) {
+          io.err(`Nothing at "${reply2.path}" in ${formatStoreRef(reply2.store)}.`);
+          return finish(EXIT.failed);
+        }
+        io.out(`${formatState(reply2)}
+`);
+        return finish(EXIT.ok);
+      }
+      const watch = await panel.request({ type: "SUBSCRIBE", selectors: [selector] }, ["SUBSCRIBED", "REJECTED"]);
+      if (watch.type === "REJECTED") {
+        io.err(`${watch.reason}: ${watch.unknown.join(", ")}`);
+        return finish(EXIT.failed);
+      }
+      const isWatched = ({ label, instance }) => watch.matched.some((store) => store.label === label && store.instance === instance);
+      const expectedAction = command.kind === "action" ? command.action : "setState";
+      const seen = [];
+      const outcome = new Promise((done) => {
+        const timer = setTimeout(() => done(null), options.timeoutSeconds * 1e3);
+        panel.onEvent((event2) => {
+          seen.push(event2);
+          if (event2.kind !== "action" || event2.action !== expectedAction || !isWatched(event2.store)) return;
+          clearTimeout(timer);
+          done(event2);
+        });
+      });
+      const request = (() => {
+        if (command.kind === "set") return { type: "SET_STATE", selector, state: command.state };
+        if (command.kind === "patch") return { type: "PATCH_STATE", selector, patch: command.patch };
+        return { type: "RUN_ACTION", selector, action: command.action, args: command.args };
+      })();
+      const reply = await panel.request(request, ["DISPATCHED", "REQUEST_REJECTED"]);
+      if (reply.type === "REQUEST_REJECTED") {
+        io.err(reply.reason);
+        return finish(EXIT.failed);
+      }
+      const event = await outcome;
+      for (const other of seen) if (other !== event) io.out(`${formatEvent(other)}
+
+`);
+      if (!event) {
+        io.err(
+          `Sent, but the page reported nothing within ${options.timeoutSeconds}s. The action may still be running, or the store is not live on the page.`
+        );
+        return finish(EXIT.noOutcome);
+      }
+      io.out(`${formatEvent(event)}
+`);
+      return finish(event.kind === "action" && event.result && "error" in event.result ? EXIT.failed : EXIT.ok);
+    };
+    const start = async (panel) => {
+      const { stores } = await panel.request({ type: "GET_STORES" }, ["AVAILABLE_STORES"]);
+      if (options.list) {
+        io.out(`${formatStoreList(stores)}
+`);
+        return finish(EXIT.ok);
+      }
+      let selectors;
+      if (options.targets.length) {
+        if (options.targets.includes(ALL_STORES)) {
+          io.err(ALL_WARNING);
+          selectors = ALL_STORES;
+        } else {
+          const resolved = resolveTargets(options.targets, stores);
+          if (resolved.unknown.length) {
+            for (const { target, candidates } of resolved.unknown) {
+              io.err(`Store "${target}" was not found. Available: ${candidates.join(", ") || "(none)"}`);
+            }
+            return finish(EXIT.failed);
+          }
+          selectors = resolved.selectors;
+        }
+      } else if (io.interactive && stores.length) {
+        const picked = await io.pick(stores);
+        if (!picked) return finish(EXIT.ok);
+        if ("all" in picked) {
+          io.err(ALL_WARNING);
+          selectors = ALL_STORES;
+        } else {
+          selectors = picked.selectors;
+        }
+      } else {
+        io.out(`${formatStoreList(stores)}
+`);
+        io.err('\nPass --store <names> (or --store "*") to stream one or more of these stores.');
+        return finish(EXIT.needsTarget);
+      }
+      const rejected = await subscribe(panel, selectors);
+      if (rejected) {
+        io.err(`${rejected.reason}: ${rejected.unknown.join(", ")}`);
+        return finish(EXIT.failed);
+      }
+    };
+    const restore = async (panel, selectors) => {
+      for (let attempt = 1; attempt <= RESUBSCRIBE_ATTEMPTS; attempt++) {
+        if (current !== panel) return;
+        if (!await subscribe(panel, selectors)) return;
+        await wait(RESUBSCRIBE_DELAY_MS);
+      }
+      io.err("Could not restore the subscription: the stores are not known by DevTools any more.");
+      return finish(EXIT.failed);
+    };
+    server.onPanel((panel) => {
+      const isFirst = subscribed === null;
+      current = panel;
+      io.err(`Connected to the DevTools panel${describePanel(panel.hello) ? ` (${describePanel(panel.hello)})` : ""}.`);
+      if (!options.command) panel.onEvent((event) => io.out(`${formatEvent(event)}
+
+`));
+      panel.onClose(() => {
+        if (current !== panel || finished) return;
+        current = null;
+        io.err("DevTools panel disconnected. Waiting for it to reconnect...");
+      });
+      if (options.command) {
+        if (commandStarted) return;
+        commandStarted = true;
+      }
+      const flow = options.command ? runCommand(panel, options.command) : isFirst ? start(panel) : restore(panel, subscribed);
+      flow.catch((error) => {
+        io.err(error.message);
+        return finish(EXIT.failed);
+      });
+    });
+    io.err(
+      `Waiting for the DevTools panel on port ${options.port}. Open DevTools on the app tab and select the react-global-state-hooks panel.`
+    );
+  });
+};
+
+// src/cli/select.ts
+var ALL_ROW = "All stores";
+var renderSelector = (stores, { cursor, marked }, rows) => {
+  const rowTitles = [
+    ...stores.map((store2, index) => `${marked.has(index) ? "\u25C9" : " "} ${storeTitle(store2)}`),
+    `  ${ALL_ROW}`
+  ];
+  const chrome = 4;
+  const visible = rows ? Math.max(3, Math.min(rowTitles.length, Math.floor((rows - chrome) / 2))) : rowTitles.length;
+  const start = Math.min(Math.max(0, cursor - Math.floor(visible / 2)), rowTitles.length - visible);
+  const lines = ["Select a store (\u2191/\u2193 move, space mark several, enter confirm, q quit):", ""];
+  for (let index = start; index < start + visible; index++) {
+    lines.push(`${index === cursor ? "\u276F" : " "} ${rowTitles[index]}`);
+  }
+  lines.push("");
+  const store = stores[cursor];
+  if (!store) {
+    lines.push("Listen to every store. This is slower and noisier than picking specific stores.");
+    return lines;
+  }
+  const preview = [store.name ?? "unnamed"];
+  if (store.location) preview.push(store.location);
+  preview.push("", "State:", ...store.preview.split("\n"));
+  if (store.actions.length) preview.push("", "Actions:", ...store.actions);
+  const room = rows ? Math.max(0, rows - chrome - visible) : preview.length;
+  if (preview.length > room) return [...lines, ...preview.slice(0, Math.max(0, room - 1)), "\u2026"];
+  return [...lines, ...preview];
+};
+var KEYS = {
+  up: "\x1B[A",
+  down: "\x1B[B",
+  ctrlC: "",
+  enter: "\r",
+  space: " "
+};
+var pickStores = (stores) => new Promise((resolve) => {
+  const { stdin, stdout } = process;
+  const rowCount = stores.length + 1;
+  const view = { cursor: 0, marked: /* @__PURE__ */ new Set() };
+  const draw = () => {
+    const lines = renderSelector(stores, view, stdout.rows);
+    stdout.write(`\x1B[H${lines.map((line) => `\x1B[2K${line}`).join("\n")}\x1B[J`);
+  };
+  const finish = (selection) => {
+    stdin.off("data", onData);
+    stdin.setRawMode(false);
+    stdin.pause();
+    stdout.write("\x1B[?25h\x1B[?1049l");
+    resolve(selection);
+  };
+  const onData = (chunk) => {
+    const key = chunk.toString();
+    if (key === KEYS.ctrlC || key === "q" || key === "\x1B") return finish(null);
+    if (key === KEYS.up || key === "k") view.cursor = (view.cursor + rowCount - 1) % rowCount;
+    else if (key === KEYS.down || key === "j") view.cursor = (view.cursor + 1) % rowCount;
+    else if (key === KEYS.space && view.cursor < stores.length) {
+      if (!view.marked.delete(view.cursor)) view.marked.add(view.cursor);
+    } else if (key === KEYS.enter) {
+      if (view.cursor === stores.length) return finish({ all: true });
+      const picked = view.marked.size ? [...view.marked] : [view.cursor];
+      return finish({ selectors: picked.map((index) => stores[index].selector) });
+    }
+    draw();
+  };
+  stdout.write("\x1B[?1049h\x1B[?25l");
+  stdin.setRawMode(true);
+  stdin.resume();
+  stdin.on("data", onData);
+  draw();
+});
+
+// src/cli/main.ts
+var main = async () => {
+  let options;
+  try {
+    options = parseArgs(process.argv.slice(2));
+  } catch (error) {
+    if (!(error instanceof UsageError)) throw error;
+    process.stderr.write(`
+
+
+${error.message}
+
+${HELP}
+`);
+    return EXIT.failed;
+  }
+  if (options.help) {
+    process.stdout.write(`
+
+
+${HELP}
+`);
+    return EXIT.ok;
+  }
+  const controller = new AbortController();
+  process.once("SIGINT", () => controller.abort());
+  process.once("SIGTERM", () => controller.abort());
+  process.stdout.on("error", () => controller.abort());
+  return run(
+    options,
+    {
+      out: (text) => void process.stdout.write(text),
+      err: (text) => void process.stderr.write(`${text}
+`),
+      interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+      pick: pickStores
+    },
+    controller.signal
+  );
+};
+main().then(
+  (code) => process.exit(code),
+  (error) => {
+    process.stderr.write(`${error instanceof Error ? error.stack : String(error)}
+`);
+    process.exit(EXIT.failed);
+  }
+);