tabctl 0.5.3 → 0.6.0-alpha.10

package/README.md

@@ -7,13 +7,21 @@ A command-line instrument for browser tab orchestration — list, search, group,
 ## Install
 
 ```bash
-npm install -g tabctl
-tabctl setup --browser chrome
-# Load the extension: chrome://extensions → Developer mode → Load unpacked → paste: ~/.local/state/tabctl/extension/
+mise use -g github:ekroon/tabctl   # install the tabctl binary
+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
+
+```bash
+cargo install --path rust/crates/tabctl
+```
+
+> **Legacy:** `npm install -g tabctl` still works for the Node.js-based distribution but is no longer the primary install method. No Node.js or Go is required at runtime — the single `tabctl` binary handles everything.
 
 ## Agent Skill
 
@@ -54,28 +62,44 @@ When tabctl is installed as a skill, your agent sees what you see. Just talk to
 
 ---
 
-`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.
+`tabctl` is a single Rust binary that serves as both the CLI and the native messaging host. The CLI sends commands over a Unix socket (or named pipe on Windows) to the host, which proxies them to the browser extension via native messaging. The `tabctl host` subcommand is the native messaging entry point — invoked automatically by the browser, not manually.
 
 This repo contains:
-- Chrome/Edge extension (tab/group inspection + actions)
-- Native messaging host (Node)
-- CLI (`tabctl`) for on-demand workflows
+- Chrome/Edge extension (`src/extension/`, the only TypeScript component)
+- Rust workspace (`rust/crates/*`) — single `tabctl` binary for CLI + host + shared runtime
+- Node packaging/build scripts for distribution (legacy)
 
 ## Quick Start
 
 ### 1. Build and install
 
+```bash
+cargo install --path rust/crates/tabctl   # puts tabctl on your PATH
+```
+
+For development with the full build pipeline (extension + Rust):
+
 ```bash
 npm install
 npm run build
-npm link          # puts tabctl on your PATH
 ```
 
-If you haven't run `npm link`, you can always use `node ./cli/tabctl.js` instead of `tabctl`.
+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
@@ -83,25 +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
+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.
+>
+> **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).
 
-If you need to override the auto-derived ID (e.g. for a custom extension path):
-
-<!-- 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
 ```
 
@@ -209,6 +240,46 @@ See [CLI.md](CLI.md#configuration) for full details.
 - Socket: `<dataDir>/tabctl.sock` (default: `~/.local/state/tabctl/tabctl.sock`)
 - Undo log: `<dataDir>/undo.jsonl` (default: `~/.local/state/tabctl/undo.jsonl`)
 - Profile registry: `<configDir>/profiles.json`
+- WSL TCP port file: `<dataDir>/tcp-port` (written by the Windows host)
+
+## Windows + WSL transport
+
+On Windows, the host exposes a dual 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 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`.
+
+Relevant knobs: `TABCTL_SOCKET`, `TABCTL_TCP_PORT`, `TABCTL_PROFILE`, `TABCTL_DATA_DIR`, `TABCTL_STATE_DIR`, `TABCTL_CONFIG_DIR`.
+
+## Troubleshooting (setup/ping on Windows + WSL)
+
+- `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
 
@@ -219,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
@@ -258,24 +329,34 @@ 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
 
-### TypeScript workflow
-Source lives in `src/` and compiles to `build/`, then syncs to the runtime locations:
-- `src/extension/background.ts` -> `extension/background.js`
-- `src/host/host.ts` -> `host/host.js`
-- `src/cli/tabctl.ts` -> `cli/tabctl.js`
-- `src/tests/unit/*.ts` -> `tests/unit/*.js`
+### Build workflow
+The single `tabctl` binary is built from the Rust workspace (`rust/`). TypeScript is limited to the browser extension boundary (`src/extension/`). No Node.js or Go is required at runtime.
 
-Build and test:
+Build and verify:
 
 ```bash
-npm install
-npm run build
-npm test
+cargo build --release -p tabctl   # build the binary
+npm install && npm run build      # full pipeline (extension + Rust)
+npm test                          # unit tests
 ```
 
+Rust-only validation:
+```bash
+npm run rust:verify
+```
+
+Browser-backed integration harness (requires built dist artifacts and Chrome):
+```bash
+npm run test:integration
+```
+
+WSL CI validates the WSL->Windows invocation bridge (`test.yml` `wsl` job) with phases: `prerequisites`, `diagnostics`, `build_and_unit`, `setup_validation`, `windows_invocation`, `integration`. Runtime/build execution is delegated to Windows commands (`cmd.exe`/`powershell.exe`), so WSL-local Rust compilation is not required.
+
 ### Versioning
 The base version lives in `package.json` and is embedded into the CLI, host, and extension at build time.
 
@@ -284,6 +365,25 @@ Commands:
 npm run bump:patch
 npm run bump:minor
 npm run bump:major
+npm run bump:alpha
+npm run bump:rc
+npm run bump:stable
+```
+
+Pre-release staging flow:
+- `bump:alpha` creates/increments `x.y.z-alpha.N`
+- `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:
+- Git tag must match `package.json` version (`v<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`
+
+Fetch the extension asset from a release with:
+```bash
+tabctl extension-fetch --version 0.5.3
 ```
 
 Local builds default to a dev version when a `.git` directory is present, appending the short SHA.
@@ -309,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).