tabctl 0.5.0 → 0.5.3

package/README.md

@@ -1,16 +1,66 @@
 # tabctl
 
-`tabctl` is a command-line tool that gives you terminal control over your browser tabs. List, search, group, move, close, deduplicate, inspect, and report on tabs without leaving your terminal — across Chrome and Edge.
+Every open tab is a thread you forgot to pull. Tabctl finds them all.
 
-It works through a lightweight local stack: the CLI talks to a native messaging host, which proxies requests to a browser extension. A policy file can protect pinned tabs or specific groups from automated actions, and every mutation is undoable.
+A command-line instrument for browser tab orchestration — list, search, group, archive, close, undo — wired into Edge or Chrome through a native messaging bridge. Built for humans who hoard tabs and the AI agents who clean up after them.
+
+## Install
+
+```bash
+npm install -g tabctl
+tabctl setup --browser chrome
+# Load the extension: chrome://extensions → Developer mode → Load unpacked → paste: ~/.local/state/tabctl/extension/
+tabctl ping
+```
+
+If it pings back, the wire is live. You're connected.
+
+## Agent Skill
+
+Give your coding agent eyes into the browser. One command and it learns the protocol.
+
+```bash
+tabctl skill
+# or: npx skills add https://github.com/ekroon/tabctl --skill tabctl -a opencode -a github-copilot -a claude-code
+```
+
+## Safety
+
+Nothing leaves your machine. No cloud. No telemetry. Just a socket between your terminal and your browser, quiet as rain on neon.
+
+Every mutation is undoable — `tabctl undo` rewinds closes, archives, and group changes like they never happened. A configurable policy layer shields pinned tabs and protected domains from accidental destruction. You pull the trigger; tabctl keeps the safety on until you mean it.
+
+## What You Can Say
+
+When tabctl is installed as a skill, your agent sees what you see. Just talk to it.
+
+> *"Which of my tabs can I close?"*
+> The agent scans for duplicates, stale pages, and tabs you haven't touched in days — then offers to clean house.
+
+> *"Are any of my open tabs relevant to my note on Project Helios?"*
+> When connected to Obsidian, your agent cross-references every open tab against your notes and surfaces the ones that matter.
+
+> *"I just finished researching service mesh architectures. Organize what I found."*
+> Groups your tabs by theme, extracts key URLs, and drops a summary into your notes — before you forget what you were looking at.
+
+> *"Where's that AWS pricing page I had open somewhere?"*
+> The agent searches your open tabs and groups by title and URL — and brings it back into focus.
+
+> *"Pull every error message from my open Sentry tabs into a markdown table."*
+> The agent reads each tab, extracts what you need, and formats it — no copy-paste, no context switching.
+
+> *"Group everything by project. You know which ones."*
+> Your agent infers context from URLs, titles, and your workspace — then sorts ninety tabs into five groups with names that actually make sense.
+
+---
+
+`tabctl` works through a lightweight local stack: the CLI talks to a native messaging host, which proxies requests to a browser extension. The host only runs while the browser is open and the extension is connected.
 
 This repo contains:
 - Chrome/Edge extension (tab/group inspection + actions)
 - Native messaging host (Node)
 - CLI (`tabctl`) for on-demand workflows
 
-The host only runs while the browser is open and the extension is connected.
-
 ## Quick Start
 
 ### 1. Build and install

package/dist/cli/lib/commands/setup.js

@@ -78,7 +78,7 @@ function resolveNodePath(options) {
 function resolveHostPath(dataDir) {
     // Sync host bundle to stable path so wrapper survives npm upgrades
     try {
-        const result = (0, extension_sync_1.syncHost)(dataDir);
+        const result = (0, extension_sync_1.syncHost)(dataDir, { force: true });
         return result.hostPath;
     }
     catch (err) {
@@ -181,7 +181,7 @@ function runSetup(options, prettyOutput) {
     const hostPath = resolveHostPath(config.baseDataDir);
     let extensionSync;
     try {
-        extensionSync = (0, extension_sync_1.syncExtension)(config.baseDataDir);
+        extensionSync = (0, extension_sync_1.syncExtension)(config.baseDataDir, { force: true });
     }
     catch {
         extensionSync = null;
@@ -275,9 +275,20 @@ function runSetup(options, prettyOutput) {
             "",
         ].join("\n"));
     }
+    const extensionsUrl = browser === "edge" ? "edge://extensions" : "chrome://extensions";
+    const browserName = browser === "edge" ? "Edge" : "Chrome";
+    const extensionDir = extensionSync?.extensionDir || null;
+    const loadSteps = extensionDir
+        ? [
+            `Load the extension: ${extensionsUrl} → Developer mode → Load unpacked`,
+            `  Path: ${extensionDir}`,
+            process.platform === "darwin" ? "  Tip: press Cmd+Shift+G in the file dialog to paste the path" : null,
+        ].filter(Boolean).join("\n")
+        : `Load the extension: ${extensionsUrl} → Developer mode → Load unpacked`;
     process.stderr.write([
+        loadSteps,
         `Verify connection: tabctl --profile ${profileName} ping`,
-        `If ping fails, ensure the ${browser === "edge" ? "Edge" : "Chrome"} extension is active.`,
+        `If ping fails, ensure the ${browserName} extension is active.`,
         "",
     ].join("\n"));
 }

package/dist/cli/lib/output.js

@@ -65,34 +65,42 @@ function setupStdoutErrorHandling() {
 }
 function emitVersionWarnings(response, fallbackAction) {
     const hostVersion = typeof response.version === "string" ? response.version : null;
-    // CLI ↔ host version mismatch: auto-upgrade (sync files + trigger reload)
-    if (hostVersion && hostVersion !== version_1.VERSION) {
-        try {
-            const config = (0, config_1.resolveConfig)();
-            const hostResult = (0, extension_sync_1.syncHost)(config.baseDataDir);
-            const extResult = (0, extension_sync_1.syncExtension)(config.baseDataDir);
-            const anySynced = hostResult.synced || extResult.synced;
-            // Send reload if we synced new files OR if the running host is stale
-            if (anySynced) {
-                process.stderr.write(`[tabctl] upgraded: ${hostVersion} → ${version_1.BASE_VERSION}. Reloading extension...\n`);
-            }
-            else {
-                process.stderr.write(`[tabctl] host is stale (${hostVersion}), reloading extension...\n`);
-            }
-            (0, client_1.sendFireAndForget)({ id: (0, client_2.createRequestId)(), action: "reload", params: {} });
-            // Check and fix wrapper Node path for the active profile
+    const data = response.data;
+    const hostBaseVersion = data && typeof data.hostBaseVersion === "string" ? data.hostBaseVersion : null;
+    const isDevCli = version_1.DEV_BUILD;
+    // CLI ↔ host BASE_VERSION mismatch: auto-upgrade (sync files + trigger reload).
+    // Dev builds never sync — they use whatever host is already installed.
+    const effectiveHostBase = hostBaseVersion ?? hostVersion;
+    if (effectiveHostBase && effectiveHostBase !== version_1.BASE_VERSION && !isDevCli) {
+        // Downgrade: host is newer than CLI — warn but don't sync/reload
+        if ((0, extension_sync_1.compareBaseVersions)(version_1.BASE_VERSION, effectiveHostBase) < 0) {
+            process.stderr.write(`[tabctl] cli (${version_1.BASE_VERSION}) is older than host (${effectiveHostBase}). Consider upgrading: npm install -g tabctl\n`);
+        }
+        else {
             try {
-                repairActiveWrapper(config.baseDataDir);
+                const config = (0, config_1.resolveConfig)();
+                const hostResult = (0, extension_sync_1.syncHost)(config.baseDataDir);
+                const extResult = (0, extension_sync_1.syncExtension)(config.baseDataDir);
+                const anySynced = hostResult.synced || extResult.synced;
+                if (anySynced) {
+                    process.stderr.write(`[tabctl] upgraded: ${effectiveHostBase} → ${version_1.BASE_VERSION}. Reloading extension...\n`);
+                }
+                else {
+                    process.stderr.write(`[tabctl] host is stale (${effectiveHostBase}), reloading extension...\n`);
+                }
+                (0, client_1.sendFireAndForget)({ id: (0, client_2.createRequestId)(), action: "reload", params: {} });
+                try {
+                    repairActiveWrapper(config.baseDataDir);
+                }
+                catch {
+                    // Wrapper repair is best-effort
+                }
             }
             catch {
-                // Wrapper repair is best-effort
+                process.stderr.write(`[tabctl] version mismatch: cli ${version_1.BASE_VERSION}, host ${effectiveHostBase}. Run: tabctl setup\n`);
             }
         }
-        catch {
-            process.stderr.write(`[tabctl] version mismatch: cli ${version_1.VERSION}, host ${hostVersion}. Run: tabctl setup\n`);
-        }
     }
-    const data = response.data;
     const extensionVersion = data && typeof data.extensionVersion === "string" ? data.extensionVersion : null;
     const extensionComponent = data && typeof data.extensionComponent === "string" ? data.extensionComponent : null;
     if (extensionVersion && hostVersion && extensionVersion !== hostVersion) {

package/dist/extension/manifest.json

@@ -1,7 +1,7 @@
 {
   "manifest_version": 3,
   "name": "Tab Control",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "description": "Archive and manage browser tabs with CLI support",
   "permissions": [
     "tabs",
@@ -19,5 +19,5 @@
   "background": {
     "service_worker": "background.js"
   },
-  "version_name": "0.5.0"
+  "version_name": "0.5.3"
 }

package/dist/host/host.bundle.js

@@ -128,11 +128,12 @@ var require_version = __commonJS({
   "dist/shared/version.js"(exports2) {
     "use strict";
     Object.defineProperty(exports2, "__esModule", { value: true });
-    exports2.DIRTY = exports2.GIT_SHA = exports2.VERSION = exports2.BASE_VERSION = void 0;
-    exports2.BASE_VERSION = "0.5.0";
-    exports2.VERSION = "0.5.0";
-    exports2.GIT_SHA = null;
+    exports2.DEV_BUILD = exports2.DIRTY = exports2.GIT_SHA = exports2.VERSION = exports2.BASE_VERSION = void 0;
+    exports2.BASE_VERSION = "0.5.3";
+    exports2.VERSION = "0.5.3";
+    exports2.GIT_SHA = "7d279446";
     exports2.DIRTY = false;
+    exports2.DEV_BUILD = false;
   }
 });
 

package/dist/shared/extension-sync.js

@@ -11,6 +11,8 @@ exports.resolveInstalledExtensionDir = resolveInstalledExtensionDir;
 exports.resolveInstalledHostPath = resolveInstalledHostPath;
 exports.readExtensionVersion = readExtensionVersion;
 exports.readHostVersion = readHostVersion;
+exports.compareBaseVersions = compareBaseVersions;
+exports.isDevBuild = isDevBuild;
 exports.syncExtension = syncExtension;
 exports.syncHost = syncHost;
 exports.checkExtensionSync = checkExtensionSync;
@@ -18,6 +20,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_crypto_1 = __importDefault(require("node:crypto"));
 const config_1 = require("./config");
+const version_1 = require("./version");
 exports.EXTENSION_DIR_NAME = "extension";
 exports.HOST_BUNDLE_NAME = "host.bundle.js";
 /**
@@ -72,11 +75,44 @@ function readHostVersion(hostPath) {
         return null;
     }
 }
-function syncExtension(dataDir) {
+/**
+ * Compare two semver versions by their base (major.minor.patch) components.
+ * Strips any prerelease/build metadata before comparing.
+ * Returns -1 if a < b, 0 if equal, 1 if a > b.
+ */
+function compareBaseVersions(a, b) {
+    const strip = (v) => v.replace(/[-+].*$/, "");
+    const pa = strip(a).split(".").map(Number);
+    const pb = strip(b).split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const va = pa[i] ?? 0;
+        const vb = pb[i] ?? 0;
+        if (va < vb)
+            return -1;
+        if (va > vb)
+            return 1;
+    }
+    return 0;
+}
+/** Returns true when the current CLI is a dev build. */
+function isDevBuild() {
+    return version_1.DEV_BUILD;
+}
+function syncExtension(dataDir, options) {
     const bundledDir = resolveBundledExtensionDir();
     const installedDir = resolveInstalledExtensionDir(dataDir);
     const bundledVersion = readExtensionVersion(bundledDir);
     const installedVersion = readExtensionVersion(installedDir);
+    if (!options?.force) {
+        // Dev builds never overwrite installed files
+        if (isDevBuild()) {
+            return { synced: false, bundledVersion, installedVersion, extensionDir: installedDir };
+        }
+        // Downgrade protection: don't replace a newer installed version
+        if (bundledVersion && installedVersion && compareBaseVersions(bundledVersion, installedVersion) < 0) {
+            return { synced: false, bundledVersion, installedVersion, extensionDir: installedDir };
+        }
+    }
     const needsCopy = !node_fs_1.default.existsSync(installedDir) || bundledVersion !== installedVersion;
     if (needsCopy) {
         node_fs_1.default.mkdirSync(installedDir, { recursive: true });
@@ -89,11 +125,21 @@ function syncExtension(dataDir) {
         extensionDir: installedDir,
     };
 }
-function syncHost(dataDir) {
+function syncHost(dataDir, options) {
     const bundledPath = resolveBundledHostPath();
     const installedPath = resolveInstalledHostPath(dataDir);
     const bundledVersion = readHostVersion(bundledPath);
     const installedVersion = readHostVersion(installedPath);
+    if (!options?.force) {
+        // Dev builds never overwrite installed files
+        if (isDevBuild()) {
+            return { synced: false, bundledVersion, installedVersion, hostPath: installedPath };
+        }
+        // Downgrade protection: don't replace a newer installed version
+        if (bundledVersion && installedVersion && compareBaseVersions(bundledVersion, installedVersion) < 0) {
+            return { synced: false, bundledVersion, installedVersion, hostPath: installedPath };
+        }
+    }
     const needsCopy = !node_fs_1.default.existsSync(installedPath) || bundledVersion !== installedVersion;
     if (needsCopy) {
         node_fs_1.default.mkdirSync(node_path_1.default.dirname(installedPath), { recursive: true });

package/dist/shared/version.js

@@ -1,7 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DIRTY = exports.GIT_SHA = exports.VERSION = exports.BASE_VERSION = void 0;
-exports.BASE_VERSION = "0.5.0";
-exports.VERSION = "0.5.0";
-exports.GIT_SHA = null;
+exports.DEV_BUILD = exports.DIRTY = exports.GIT_SHA = exports.VERSION = exports.BASE_VERSION = void 0;
+exports.BASE_VERSION = "0.5.3";
+exports.VERSION = "0.5.3";
+exports.GIT_SHA = "7d279446";
 exports.DIRTY = false;
+exports.DEV_BUILD = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tabctl",
-  "version": "0.5.0",
+  "version": "0.5.3",
   "description": "CLI tool to manage and analyze browser tabs",
   "license": "MIT",
   "repository": {