tabctl 0.6.0-alpha.1 → 0.6.0-alpha.11

package/README.md

@@ -8,12 +8,12 @@ A command-line instrument for browser tab orchestration — list, search, group,
 
 ```bash
 mise use -g github:ekroon/tabctl   # install the tabctl binary
-tabctl setup --browser edge         # or: --browser chrome
+tabctl setup --browser edge --extension-id <id>   # or: --browser chrome --extension-id <id>
 # Load the extension: edge://extensions → Developer mode → Load unpacked → paste: ~/.local/state/tabctl/extension/
 tabctl ping
 ```
 
-If it pings back, the wire is live. You're connected.
+Setup writes the wrapper script, native messaging manifest, and registers the profile in one step. Works on macOS, Linux, and Windows. If it pings back, the wire is live. You're connected.
 
 ### Alternative: build from source
 
@@ -84,9 +84,22 @@ npm install
 npm run build
 ```
 
+Local development shortcuts are available via `Makefile`:
+
+```bash
+make dev-up BROWSER=edge PROFILE=edge
+make dev-run PROFILE=edge CMD="list --all --json"
+make dev-run-release-like PROFILE=edge CMD="list --all --json"
+```
+
+If `npm` is not on PATH in your shell, override it per command:
+```bash
+make dev-build NPM=~/.local/share/mise/shims/npm
+```
+
 ### 2. Set up your browser
 
-Run setup — it syncs the extension, tells you where to load it, and auto-derives the extension ID:
+Run setup to write the manifest, wrapper script, and profile registration:
 
 <!-- test: "setup explicit --extension-id overrides auto-derived ID" -->
 ```bash
@@ -94,33 +107,32 @@ tabctl setup --browser chrome
 ```
 
 This will:
-1. Copy the extension to a stable location (`~/.local/state/tabctl/extension/`)
-2. Print the path (and copy it to your clipboard)
-3. Ask you to load it as an unpacked extension in `chrome://extensions`
-4. Auto-derive the extension ID from the installed path
-5. Download the version-pinned release extension asset (`tabctl-extension.zip` + `.sha256`) into the tabctl data directory for offline/manual recovery
-
-Optional setup release overrides:
-- Flags: `--release-repo`, `--release-tag` (or `--release-version`), `--release-asset`, `--skip-extension-download`
-- Env vars: `TABCTL_RELEASE_REPO`, `TABCTL_RELEASE_TAG`, `TABCTL_RELEASE_ASSET`, `TABCTL_SETUP_FETCH_EXTENSION=0`
-- Precedence: flags override env vars, then built-in defaults; if download fails, setup continues and includes warning details in setup output.
+1. Write the native messaging manifest and wrapper script
+2. Register the browser profile in `profiles.json`
+3. Download the version-pinned release extension asset (`tabctl-extension.zip` + `.sha256`) into the tabctl data directory
+4. Sync the managed unpacked extension directory to the tabctl version (`~/.local/state/tabctl/extension/`)
+5. Derive the extension ID from the managed extension path (or use explicit `--extension-id`)
+6. Print the path for loading as an unpacked extension in `chrome://extensions`
+
+For local dev builds (no GitHub download), point setup at an unpacked directory:
+```bash
+tabctl setup --browser chrome --extension-dir dist/extension
+```
 
 > **Edge?** Use `--browser edge` and load from `edge://extensions` instead.
 >
-> **Windows:** setup verifies connectivity after writing setup artifacts and checks the runtime extension ID reported by the browser. Connectivity failures and runtime extension ID mismatches exit non-zero and print manual recovery steps (including expected vs runtime IDs).
-
-If you need to override the auto-derived ID (e.g. for a custom extension path):
+> **Cross-platform:** setup works on macOS, Linux, and Windows. On Windows, setup verifies connectivity after writing setup artifacts and checks the runtime extension ID reported by the browser. Connectivity failures and runtime extension ID mismatches exit non-zero and print manual recovery steps (including expected vs runtime IDs).
 
-<!-- test: "setup writes native host manifest for chrome" -->
-```bash
-tabctl setup --browser chrome --extension-id <your-extension-id>
-```
+Optional setup release overrides:
+- Flags: `--extension-dir`, `--release-repo`, `--release-tag` (or `--release-version`), `--release-asset`, `--skip-extension-download`
+- Env vars: `TABCTL_SETUP_EXTENSION_DIR`, `TABCTL_RELEASE_REPO`, `TABCTL_RELEASE_TAG`, `TABCTL_RELEASE_ASSET`, `TABCTL_SETUP_FETCH_EXTENSION=0`
+- Precedence: flags override env vars, then built-in defaults; if download fails, setup continues and includes warning details in setup output.
 
 ### 3. Verify and explore
 
 <!-- test: "ping sends ping action", "list sends list action" -->
 ```bash
-tabctl ping       # check the connection
+tabctl ping       # check connection + runtime version sync
 tabctl list       # see your open tabs
 ```
 
@@ -249,7 +261,25 @@ Relevant knobs: `TABCTL_SOCKET`, `TABCTL_TCP_PORT`, `TABCTL_PROFILE`, `TABCTL_DA
 - `tabctl setup` fails with `Windows setup verification failed`: check `data.verification.reason` in JSON output (`ping-timeout`, `socket-not-found`, `socket-refused`, `ping-not-ok`, `extension-id-mismatch`), then follow printed manual steps.
 - Runtime ID mismatch (`extension-id-mismatch`): compare expected vs runtime IDs from setup output, then rerun setup with the runtime ID shown by `edge://extensions` / `chrome://extensions`:
   - `tabctl setup --browser <edge|chrome> --extension-id <runtime-id>`
+- Runtime command runs can auto-sync extension files when host/extension versions drift; rerun `tabctl reload` 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 command payloads (`open`, `list`, etc.) do not include version fields.
 - `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 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:
+```bash
+# 1) Install an older extension release into managed extension path
+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 -- list --all
+
+# 3) Verify host/extension base versions are back in sync
+tabctl ping --json
+```
 
 ## Multi-Browser Setup
 
@@ -260,10 +290,10 @@ tabctl supports multiple browser profiles. Each profile connects to a different
 <!-- test: "setup writes native host manifest", "setup writes native host manifest for chrome", "setup --name creates custom-named profile", "profile-list with multiple profiles shows all", "profile-switch success updates default", "--profile flag overrides active profile" -->
 ```bash
 # Setup for Edge
-tabctl setup --browser edge
+tabctl setup --browser edge --extension-id <edge-extension-id>
 
 # Setup for Chrome (with custom name)
-tabctl setup --browser chrome --name chrome-work
+tabctl setup --browser chrome --name chrome-work --extension-id <chrome-extension-id>
 
 # List profiles
 tabctl profile-list
@@ -299,6 +329,8 @@ 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.
 
 ## Development
 
@@ -318,7 +350,7 @@ Rust-only validation:
 npm run rust:verify
 ```
 
-Integration script (currently Rust-suite parity in CI/local):
+Browser-backed integration harness (requires built dist artifacts and Chrome):
 ```bash
 npm run test:integration
 ```
@@ -377,5 +409,5 @@ Notes:
 - Selector `attr` supports `href-url`/`src-url` to return absolute http(s) URLs.
 - `screenshot --out` writes per-tab folders into the target directory.
 - `tabctl undo` accepts a positional txid, `--txid`, or `--latest`.
-- `tabctl history --json` returns a JSON array in `data`.
+- `tabctl history --json` returns a top-level JSON array.
 - `--format` is only supported by `report` (use `--json` elsewhere).