tabctl 0.6.0-rc.2 → 0.6.0-rc.4

package/README.md

@@ -167,6 +167,11 @@ tabctl query '{ reportTabs(windowId: 123) { entries { tabId title url descriptio
 # Capture screenshots
 tabctl query 'query { captureScreenshots(tabIds: [456], mode: "viewport") { entries { tabId tiles { index width height } } } }'
 
+# Inspect persisted browser-state history for future restore tooling
+tabctl query 'query { latestBrowserState { snapshotId reason groups { logicalGroupId title browserGroupId tabUrls } } }'
+tabctl query 'query { browserStateHistory(limit: 10) { snapshotId recordedAt reason eventCount eventKinds } }'
+tabctl query 'query { browserStateGroupHistory(title: "Research", limit: 10) { snapshotId logicalGroupId title browserGroupId tabUrls } }'
+
 # Open tabs in a new grouped window
 tabctl query 'mutation { openTabs(urls: ["https://example.com"], group: "Research", newWindow: true) { windowId groupId tabs { tabId url } } }'
 
@@ -227,22 +232,26 @@ See [CLI.md](CLI.md#configuration) for full details.
 ## Runtime state
 - Socket: `<dataDir>/tabctl.sock` (default: `~/.local/state/tabctl/tabctl.sock`)
 - Undo log: `<dataDir>/undo.jsonl` (default: `~/.local/state/tabctl/undo.jsonl`)
+- Browser-state history DB: `<dataDir>/state.db` (default: `~/.local/state/tabctl/state.db`)
 - Profile registry: `<configDir>/profiles.json`
-- WSL TCP port file: `<dataDir>/tcp-port` (written by the Windows host)
+- Windows pipe endpoint file: `<dataDir>/pipe-endpoint`
 
 ## Windows + WSL transport
 
-On Windows, the host exposes a dual endpoint model:
+On Windows, the host exposes a named-pipe endpoint model:
 - Windows native clients use a named pipe endpoint (`\\.\pipe\tabctl-<hash>`).
-- WSL/Linux clients use `tcp://127.0.0.1:<port>`, with the host writing `<dataDir>/tcp-port`.
+- WSL/Linux clients use a Windows named-pipe bridge; the Windows host publishes `<dataDir>/pipe-endpoint`, and the WSL CLI relays through `powershell.exe`.
 
 WSL endpoint discovery (CLI):
-1. `TABCTL_SOCKET` (explicit endpoint); if this is a pipe endpoint in WSL, CLI still prefers discovered TCP.
-2. `TABCTL_TCP_PORT` (forces `127.0.0.1:<port>`).
-3. `tcp-port` file discovery from resolved data dir (and equivalent `/mnt/c/Users/*/.../tabctl/.../tcp-port` locations).
-4. Fallback: `tcp://127.0.0.1:38000`.
+1. `TABCTL_SOCKET` (explicit endpoint).
+2. `pipe-endpoint` file discovery from resolved data dir (and equivalent `/mnt/c/Users/*/.../tabctl/.../pipe-endpoint` locations).
+
+WSL named-pipe mode:
+- This is the default WSL transport now.
+- The CLI discovers the pipe endpoint from `<dataDir>/pipe-endpoint` (including the mirrored `/mnt/c/Users/*/...` candidate paths used for other WSL bridge files).
+- TCP is disabled for the WSL transport path.
 
-Relevant knobs: `TABCTL_SOCKET`, `TABCTL_TCP_PORT`, `TABCTL_PROFILE`, `TABCTL_DATA_DIR`, `TABCTL_STATE_DIR`, `TABCTL_CONFIG_DIR`.
+Relevant knobs: `TABCTL_SOCKET`, `TABCTL_PROFILE`, `TABCTL_DATA_DIR`, `TABCTL_STATE_DIR`, `TABCTL_CONFIG_DIR`.
 
 ## Troubleshooting (setup/ping on Windows + WSL)
 
@@ -252,9 +261,9 @@ Relevant knobs: `TABCTL_SOCKET`, `TABCTL_TCP_PORT`, `TABCTL_PROFILE`, `TABCTL_DA
 - Runtime command runs can auto-sync extension files when host/extension versions drift; rerun `tabctl query 'mutation { reloadExtension { reloading } }'` if the browser does not pick up changes immediately.
 - For local release-like testing while developing, force runtime sync behavior with `TABCTL_AUTO_SYNC_MODE=release-like`.
 - Disable runtime sync entirely with `TABCTL_AUTO_SYNC_MODE=off`.
-- `tabctl ping --json` is the canonical runtime version check (`versionsInSync`, `hostBaseVersion`, `baseVersion`).
-- Version metadata is intentionally health-only: regular GraphQL payloads do not include version fields unless you explicitly query health surfaces.
-- `tabctl ping` returns connect errors (`ENOENT`, `ECONNREFUSED`, timeout): ensure extension is loaded and active, rerun `tabctl setup`, and in WSL verify `TABCTL_TCP_PORT` or `<dataDir>/tcp-port` matches a listening localhost port.
+- `tabctl ping --json` is a host connectivity/health check; use it to confirm the native host is reachable and healthy.
+- Version metadata is intentionally health-only: regular GraphQL payloads do not include version fields unless you explicitly query health surfaces, which may expose fields such as `versionsInSync`, `hostBaseVersion`, and `baseVersion`.
+- `tabctl ping` returns connect errors (`ENOENT`, `ECONNREFUSED`, timeout): ensure extension is loaded and active, rerun `tabctl setup`, and in WSL verify the profile data dir contains a current `pipe-endpoint` file.
 - `tabctl doctor --fix --json` includes per-profile connectivity diagnostics in `data.profiles[].connectivity`; if ping remains unhealthy after local repairs, follow `manualSteps`.
 
 Local release-like sync test recipe:
@@ -265,7 +274,7 @@ tabctl setup --browser edge --extension-id <extension-id> --release-tag v0.5.2
 # 2) Run the current binary with forced release-like auto-sync
 TABCTL_AUTO_SYNC_MODE=release-like cargo run --manifest-path rust/Cargo.toml -p tabctl -- query '{ tabs { total } }'
 
-# 3) Verify host/extension base versions are back in sync
+# 3) Verify host connectivity/health after auto-sync
 tabctl ping --json
 ```
 
@@ -317,8 +326,7 @@ Policy is shared across all profiles.
 ## Security
 - The native host is locked to your extension ID.
 - All data stays local; no external API keys are used.
-- TCP connections (used for WSL ↔ Windows communication) are secured with a per-session auth token. The host generates a random token on startup; the CLI reads it automatically. See [CLI.md](CLI.md) for details.
-- TCP transport is available on all platforms via `TABCTL_HOST_TCP=1` (host) and `TABCTL_TRANSPORT=tcp` (CLI). All TCP connections are authenticated. See [CLI.md](CLI.md) for details.
+- WSL ↔ Windows communication uses a local named-pipe bridge via `powershell.exe`; no TCP fallback is used on that path.
 
 ## Development
 
@@ -336,8 +344,20 @@ npm test                          # unit tests
 Rust-only validation:
 ```bash
 npm run rust:verify
+npm run check:targets  # local cross-target cfg/type check
+```
+
+On macOS, `npm run check:targets` can use Zig for the C cross-compiler needed
+by `libsqlite3-sys`:
+
+```bash
+brew install zig
 ```
 
+The script auto-detects Zig outside CI and wires the Linux/Windows C compiler
+environment for the check. The pre-push hook does not run this optional check;
+run it manually when you want local cross-target coverage.
+
 Browser-backed integration harness (requires built dist artifacts and Chrome):
 ```bash
 npm run test:integration
@@ -363,8 +383,14 @@ Pre-release staging flow:
 - `bump:rc` promotes alpha to `x.y.z-rc.1` (or increments RC)
 - `bump:stable` drops the prerelease suffix for final stable publish
 
-Release publishing (`.github/workflows/publish.yml`) enforces:
+Release automation:
+- Run the **Prepare Release** workflow to choose or auto-detect the next version and open a release PR.
+- When that PR merges, **Tag Release** creates `v<version>` and dispatches **Release**.
+- The root `package.json` version and `optionalDependencies.tabctl-win32-x64` are kept in sync by `scripts/bump-version.js`.
+
+Release publishing (`.github/workflows/release.yml`) supports both tag pushes and explicit workflow dispatch, and enforces:
 - Git tag must match `package.json` version (`v<version>`)
+- `package.json.optionalDependencies["tabctl-win32-x64"]` must match `package.json` version
 - prerelease tags publish to `alpha`/`rc`; stable publishes to `latest`
 - `npm run build` and `npm test` must pass before publish
 - release assets include `tabctl-extension.zip` plus `tabctl-extension.zip.sha256`

package/dist/extension/background.js

@@ -474,7 +474,13 @@
     dirty: parsed.dirty
   };
   var KEEPALIVE_ALARM = "tabctl-keepalive";
+  var RECONNECT_ALARM = "tabctl-reconnect";
   var KEEPALIVE_INTERVAL_MINUTES = 1;
+  var BROWSER_STATE_SYNC_DEBOUNCE_MS = 750;
+  var RECONNECT_INITIAL_DELAY_MS = 250;
+  var RECONNECT_MAX_DELAY_MS = 3e4;
+  var RECONNECT_ALARM_MIN_DELAY_MS = 3e4;
+  var RECONNECT_STABLE_RESET_MS = 5e3;
   var screenshot = require_screenshot();
   var content = require_content();
   var { delay, executeWithTimeout } = content;
@@ -486,22 +492,87 @@
     return n;
   }
   var state = {
-    port: null
+    port: null,
+    reconnectTimer: null,
+    reconnectStableTimer: null,
+    reconnectAttempt: 0
+  };
+  var browserState = {
+    nextId: 1,
+    syncTimer: null,
+    pendingEvents: [],
+    incognitoWindowIds: /* @__PURE__ */ new Set(),
+    incognitoTabIds: /* @__PURE__ */ new Set(),
+    incognitoGroupIds: /* @__PURE__ */ new Set()
   };
   function log(...args) {
     console.log("[tabctl]", ...args);
   }
-  function sendResponse(id, ok, payload) {
-    if (!state.port) {
+  function reconnectDelayMs(attempt) {
+    return Math.min(RECONNECT_INITIAL_DELAY_MS * 2 ** attempt, RECONNECT_MAX_DELAY_MS);
+  }
+  function clearReconnectTimer() {
+    if (!state.reconnectTimer) {
+      return;
+    }
+    clearTimeout(state.reconnectTimer);
+    state.reconnectTimer = null;
+  }
+  function clearReconnectAlarm() {
+    chrome.alarms.clear(RECONNECT_ALARM);
+  }
+  function clearReconnectStableTimer() {
+    if (!state.reconnectStableTimer) {
       return;
     }
-    if (ok) {
-      const data = typeof payload === "object" && payload !== null ? payload : { payload };
-      state.port.postMessage({ id, ok: true, data });
+    clearTimeout(state.reconnectStableTimer);
+    state.reconnectStableTimer = null;
+  }
+  function scheduleReconnect(reason) {
+    if (state.port || state.reconnectTimer) {
+      return;
+    }
+    const attempt = state.reconnectAttempt;
+    const delayMs = reconnectDelayMs(attempt);
+    state.reconnectAttempt += 1;
+    log("Scheduling native host reconnect", { reason, delayMs, attempt });
+    chrome.alarms.create(RECONNECT_ALARM, {
+      delayInMinutes: Math.max(delayMs, RECONNECT_ALARM_MIN_DELAY_MS) / 6e4
+    });
+    state.reconnectTimer = setTimeout(() => {
+      state.reconnectTimer = null;
+      clearReconnectAlarm();
+      connectNative();
+    }, delayMs);
+  }
+  function resetReconnectBackoffAfterStablePort(port) {
+    clearReconnectStableTimer();
+    state.reconnectStableTimer = setTimeout(() => {
+      state.reconnectStableTimer = null;
+      if (state.port === port) {
+        state.reconnectAttempt = 0;
+      }
+    }, RECONNECT_STABLE_RESET_MS);
+  }
+  function ensureKeepaliveAlarm() {
+    chrome.alarms.create(KEEPALIVE_ALARM, { periodInMinutes: KEEPALIVE_INTERVAL_MINUTES });
+  }
+  function sendResponse(port, id, ok, payload) {
+    if (!port) {
+      log("dropping response because native port is unavailable", { id, ok });
       return;
     }
-    const error = payload instanceof Error ? { message: payload.message, stack: payload.stack } : payload;
-    state.port.postMessage({ id, ok: false, error });
+    try {
+      if (ok) {
+        const data = typeof payload === "object" && payload !== null ? payload : { payload };
+        port.postMessage({ id, ok: true, data });
+        return;
+      }
+      const error = payload instanceof Error ? { message: payload.message, stack: payload.stack } : payload;
+      port.postMessage({ id, ok: false, error });
+    } catch (error) {
+      log("failed to send native response", { id, ok, error });
+    }
   }
   function connectNative() {
     if (state.port) {
@@ -509,8 +580,13 @@
     }
     try {
       const port = chrome.runtime.connectNative(HOST_NAME);
+      clearReconnectTimer();
+      clearReconnectAlarm();
       state.port = port;
-      port.onMessage.addListener(handleNativeMessage);
+      resetReconnectBackoffAfterStablePort(port);
+      port.onMessage.addListener((message) => {
+        void handleNativeMessage(port, message);
+      });
       port.onDisconnect.addListener(() => {
         const lastError = chrome.runtime.lastError;
         if (lastError) {
@@ -518,27 +594,247 @@
         } else {
           log("Native host disconnected");
         }
-        state.port = null;
+        if (state.port === port) {
+          state.port = null;
+        }
+        clearReconnectStableTimer();
+        scheduleReconnect("disconnect");
       });
       log("Native host connected");
+      queueBrowserStateSync("startup");
     } catch (error) {
       log("Native host connection failed", error);
+      scheduleReconnect("connect-failed");
+    }
+  }
+  function nextBrowserStateId() {
+    const id = browserState.nextId;
+    browserState.nextId += 1;
+    return `browser-state-${Date.now()}-${id}`;
+  }
+  function normalizeEventPayload(kind, payload) {
+    const event = {
+      kind,
+      occurredAt: Date.now()
+    };
+    for (const [key, value] of Object.entries(payload)) {
+      if (value === void 0) {
+        continue;
+      }
+      event[key] = value;
+    }
+    if (event.incognito !== true && inferIncognitoEvent(payload)) {
+      event.incognito = true;
+    }
+    return event;
+  }
+  function inferIncognitoEvent(payload) {
+    const tabId = typeof payload.tabId === "number" ? payload.tabId : null;
+    if (tabId !== null && browserState.incognitoTabIds.has(tabId)) {
+      return true;
+    }
+    const groupId = typeof payload.groupId === "number" ? payload.groupId : null;
+    if (groupId !== null && browserState.incognitoGroupIds.has(groupId)) {
+      return true;
+    }
+    const windowId = typeof payload.windowId === "number" ? payload.windowId : null;
+    return windowId !== null && browserState.incognitoWindowIds.has(windowId);
+  }
+  function updateIncognitoState(snapshot) {
+    browserState.incognitoWindowIds.clear();
+    browserState.incognitoTabIds.clear();
+    browserState.incognitoGroupIds.clear();
+    for (const window2 of snapshot.windows || []) {
+      if (window2.incognito !== true || typeof window2.windowId !== "number") {
+        continue;
+      }
+      browserState.incognitoWindowIds.add(window2.windowId);
+      for (const tab of window2.tabs || []) {
+        if (typeof tab.tabId === "number") {
+          browserState.incognitoTabIds.add(tab.tabId);
+        }
+      }
+      for (const group of window2.groups || []) {
+        if (typeof group.groupId === "number") {
+          browserState.incognitoGroupIds.add(group.groupId);
+        }
+      }
     }
   }
+  async function postBrowserStateSync(reason) {
+    if (!state.port) {
+      return;
+    }
+    const eventCount = browserState.pendingEvents.length;
+    const events = browserState.pendingEvents.slice(0, eventCount);
+    try {
+      const snapshot = await getTabSnapshot();
+      updateIncognitoState(snapshot);
+      state.port.postMessage({
+        id: nextBrowserStateId(),
+        action: "browser-state-sync",
+        ok: true,
+        data: {
+          reason,
+          recordedAt: Date.now(),
+          events,
+          snapshot
+        }
+      });
+      browserState.pendingEvents.splice(0, eventCount);
+    } catch (error) {
+      log("Browser state sync failed", error);
+    }
+  }
+  function queueBrowserStateSync(reason) {
+    if (!state.port) {
+      connectNative();
+      return;
+    }
+    if (browserState.syncTimer) {
+      clearTimeout(browserState.syncTimer);
+    }
+    const delayMs = reason === "startup" ? 0 : BROWSER_STATE_SYNC_DEBOUNCE_MS;
+    browserState.syncTimer = setTimeout(() => {
+      browserState.syncTimer = null;
+      void postBrowserStateSync(reason);
+    }, delayMs);
+  }
+  function enqueueBrowserStateEvent(kind, payload, reason = "event") {
+    browserState.pendingEvents.push(normalizeEventPayload(kind, payload));
+    queueBrowserStateSync(reason);
+  }
+  function registerBrowserStateListeners() {
+    chrome.tabs?.onCreated?.addListener((tab) => {
+      enqueueBrowserStateEvent("tabs.onCreated", {
+        tabId: tab.id,
+        windowId: tab.windowId,
+        groupId: tab.groupId,
+        incognito: tab.incognito,
+        url: tab.url || tab.pendingUrl,
+        title: tab.title,
+        index: tab.index
+      });
+    });
+    chrome.tabs?.onUpdated?.addListener((tabId, changeInfo, tab) => {
+      const interesting = ["url", "title", "status", "pinned", "audible", "discarded", "favIconUrl"];
+      if (!interesting.some((key) => key in changeInfo)) {
+        return;
+      }
+      enqueueBrowserStateEvent("tabs.onUpdated", {
+        tabId,
+        windowId: tab.windowId,
+        groupId: tab.groupId,
+        incognito: tab.incognito,
+        changeInfo
+      });
+    });
+    chrome.tabs?.onMoved?.addListener((tabId, moveInfo) => {
+      enqueueBrowserStateEvent("tabs.onMoved", {
+        tabId,
+        windowId: moveInfo.windowId,
+        fromIndex: moveInfo.fromIndex,
+        toIndex: moveInfo.toIndex
+      });
+    });
+    chrome.tabs?.onAttached?.addListener((tabId, attachInfo) => {
+      enqueueBrowserStateEvent("tabs.onAttached", {
+        tabId,
+        windowId: attachInfo.newWindowId,
+        newPosition: attachInfo.newPosition
+      });
+    });
+    chrome.tabs?.onDetached?.addListener((tabId, detachInfo) => {
+      enqueueBrowserStateEvent("tabs.onDetached", {
+        tabId,
+        windowId: detachInfo.oldWindowId,
+        oldPosition: detachInfo.oldPosition
+      });
+    });
+    chrome.tabs?.onRemoved?.addListener((tabId, removeInfo) => {
+      enqueueBrowserStateEvent("tabs.onRemoved", {
+        tabId,
+        windowId: removeInfo.windowId,
+        isWindowClosing: removeInfo.isWindowClosing
+      });
+    });
+    chrome.tabs?.onActivated?.addListener((activeInfo) => {
+      enqueueBrowserStateEvent("tabs.onActivated", {
+        tabId: activeInfo.tabId,
+        windowId: activeInfo.windowId
+      });
+    });
+    chrome.tabGroups?.onCreated?.addListener((group) => {
+      enqueueBrowserStateEvent("tabGroups.onCreated", {
+        groupId: group.id,
+        windowId: group.windowId,
+        title: group.title,
+        color: group.color,
+        collapsed: group.collapsed
+      });
+    });
+    chrome.tabGroups?.onUpdated?.addListener((group) => {
+      enqueueBrowserStateEvent("tabGroups.onUpdated", {
+        groupId: group.id,
+        windowId: group.windowId,
+        title: group.title,
+        color: group.color,
+        collapsed: group.collapsed
+      });
+    });
+    chrome.tabGroups?.onMoved?.addListener((group) => {
+      enqueueBrowserStateEvent("tabGroups.onMoved", {
+        groupId: group.id,
+        windowId: group.windowId,
+        title: group.title,
+        color: group.color,
+        collapsed: group.collapsed
+      });
+    });
+    chrome.tabGroups?.onRemoved?.addListener((group) => {
+      enqueueBrowserStateEvent("tabGroups.onRemoved", {
+        groupId: group.id,
+        windowId: group.windowId,
+        title: group.title,
+        color: group.color,
+        collapsed: group.collapsed
+      });
+    });
+    chrome.windows?.onCreated?.addListener((window2) => {
+      enqueueBrowserStateEvent("windows.onCreated", {
+        windowId: window2.id,
+        incognito: window2.incognito,
+        focused: window2.focused,
+        state: window2.state
+      });
+    });
+    chrome.windows?.onRemoved?.addListener((windowId) => {
+      enqueueBrowserStateEvent("windows.onRemoved", { windowId });
+    });
+    chrome.windows?.onFocusChanged?.addListener((windowId) => {
+      enqueueBrowserStateEvent("windows.onFocusChanged", { windowId });
+    });
+  }
+  connectNative();
+  registerBrowserStateListeners();
+  ensureKeepaliveAlarm();
   chrome.runtime.onInstalled.addListener(() => {
     connectNative();
-    chrome.alarms.create(KEEPALIVE_ALARM, { periodInMinutes: KEEPALIVE_INTERVAL_MINUTES });
+    ensureKeepaliveAlarm();
   });
   chrome.runtime.onStartup.addListener(() => {
     connectNative();
-    chrome.alarms.create(KEEPALIVE_ALARM, { periodInMinutes: KEEPALIVE_INTERVAL_MINUTES });
+    ensureKeepaliveAlarm();
   });
   chrome.alarms.onAlarm.addListener((alarm) => {
     if (alarm.name === KEEPALIVE_ALARM) {
       connectNative();
+    } else if (alarm.name === RECONNECT_ALARM) {
+      clearReconnectTimer();
+      connectNative();
     }
   });
-  async function handleNativeMessage(message) {
+  async function handleNativeMessage(requestPort, message) {
     if (!message || typeof message !== "object") {
       return;
     }
@@ -548,9 +844,9 @@
     }
     try {
       const data = await handleAction(action, params || {}, id);
-      sendResponse(id, true, data);
+      sendResponse(requestPort, id, true, data);
     } catch (error) {
-      sendResponse(id, false, error);
+      sendResponse(requestPort, id, false, error);
     }
   }
   async function handleAction(action, params, requestId) {
@@ -570,6 +866,9 @@
           component: "extension"
         };
       case "reload":
+        chrome.alarms.create(RECONNECT_ALARM, {
+          delayInMinutes: RECONNECT_ALARM_MIN_DELAY_MS / 6e4
+        });
         setTimeout(() => chrome.runtime.reload(), 100);
         return { reloading: true };
       // --- Primitives: thin Chrome API wrappers (p: prefix) ---
@@ -656,7 +955,8 @@
           tabId: tab.id,
           windowId: win.id,
           index: tab.index,
-          url: tab.url,
+          incognito: win.incognito || false,
+          url: tab.url || tab.pendingUrl,
           title: tab.title,
           active: tab.active,
           pinned: tab.pinned,
@@ -680,6 +980,7 @@
       return {
         windowId: win.id,
         focused: win.focused,
+        incognito: win.incognito || false,
         state: win.state,
         tabs,
         groups: windowGroups

package/dist/extension/manifest.json

@@ -19,5 +19,5 @@
   "background": {
     "service_worker": "background.js"
   },
-  "version_name": "0.6.0-rc.2"
+  "version_name": "0.6.0-rc.4"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tabctl",
-  "version": "0.6.0-rc.2",
+  "version": "0.6.0-rc.4",
   "description": "CLI tool to manage and analyze browser tabs",
   "license": "MIT",
   "repository": {
@@ -52,7 +52,7 @@
     "typescript": "^5.4.5"
   },
   "optionalDependencies": {
-    "tabctl-win32-x64": "0.3.0"
+    "tabctl-win32-x64": "0.6.0-rc.4"
   },
   "dependencies": {
     "normalize-url": "^8.1.1"