tabctl 0.6.0-alpha.9 → 0.6.0-rc.10

package/README.md

@@ -1,8 +1,8 @@
 # tabctl
 
-Every open tab is a thread you forgot to pull. Tabctl finds them all.
+Every open tab is a thread you forgot to pull. Tabctl helps you query and change them safely.
 
-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.
+A command-line instrument for browser tab orchestration, now centered on a GraphQL API exposed through `tabctl query` and `tabctl schema`, plus `ping` and `history` convenience commands. Built for humans who hoard tabs and the AI agents who clean up after them.
 
 ## Install
 
@@ -25,18 +25,17 @@ cargo install --path rust/crates/tabctl
 
 ## Agent Skill
 
-Give your coding agent eyes into the browser. One command and it learns the protocol.
+Give your coding agent eyes into the browser. Install the tabctl skill via the Skills CLI:
 
 ```bash
-tabctl skill
-# or: npx skills add https://github.com/ekroon/tabctl --skill tabctl -a opencode -a github-copilot -a claude-code
+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.
+Every mutation is undoable — `undoAction` 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
 
@@ -130,75 +129,80 @@ Optional setup release overrides:
 
 ### 3. Verify and explore
 
-<!-- test: "ping sends ping action", "list sends list action" -->
 ```bash
-tabctl ping       # check connection + runtime version sync
-tabctl list       # see your open tabs
+tabctl ping
+tabctl query '{ tabs { total items { tabId title url } } }'
+tabctl schema
 ```
 
 > **Multiple browsers?** See [Multi-Browser Setup](#multi-browser-setup) for running tabctl with both Chrome and Edge.
 
 ## Commands
 
-<!-- test: "list sends list action", "analyze passes tab ids and progress option", "inspect passes signal options", "close without confirm fails", "report format md returns markdown content", "undo sends undo action with txid" -->
 | Command | Description |
 |---------|-------------|
-| `tabctl list` | List open tabs and groups |
-| `tabctl open --url <url> --group <name>` | Open tabs into a group (reuses existing, skips duplicates) |
-| `tabctl analyze` | Find stale or duplicate tabs |
-| `tabctl inspect --tab <id>` | Extract page metadata or CSS selectors |
-| `tabctl group-gather` | Merge duplicate groups with the same name |
-| `tabctl close --tab <id>` | Close tabs with full undo support |
-| `tabctl report` | Generate reports in JSON, Markdown, or CSV |
-| `tabctl undo` | Revert the last action |
+| `tabctl query '<GRAPHQL>'` | Query and mutate browser state through GraphQL |
+| `tabctl schema` | Print the GraphQL schema |
+| `tabctl ping` | Check host/browser connectivity and runtime version sync |
+| `tabctl history` | Show recent undo history entries |
+| `tabctl setup`, `doctor`, `policy`, `profile-*` | Local/admin profile management |
 
-See [CLI.md](CLI.md) for the full command reference, options, and examples.
+Read-only browser features include:
+- `inspectTabs` for page metadata and selector-based reads
+- `readTabs` for page HTML → Markdown conversion with Kreuzberg preprocessing and per-tab diagnostics
+- `reportTabs`, `captureScreenshots`, and browser-state history queries for summaries and context
 
-## Screenshot output
-When `--out` is omitted, screenshots are written to `./.tabctl/screenshots/<timestamp>` and the JSON response includes `writtenTo`.
+See [CLI.md](CLI.md) for the full command reference, options, and examples.
 
-## Agent workflow (context -> selector)
-Use screenshots only when you need visual context, then extract selectors with `inspect`.
+## GraphQL examples
 
-1) Capture context (full page tiles):
-<!-- test: "screenshot passes capture options" -->
 ```bash
-tabctl screenshot --tab <id> --mode full
-```
+# Query tabs and groups
+tabctl query '{ windows { windowId groups { groupId title } tabs { tabId title url groupTitle } } }'
 
-2) Identify the element visually, then extract its selector:
-<!-- test: "inspect passes signal options" -->
-```bash
-tabctl inspect --tab <id> --signal selector --selector '{"name":"target","selector":".your-selector"}'
-```
+# Analyze stale and duplicate tabs
+tabctl query '{ analyze(windowId: 123, staleDays: 30) { totalTabs duplicateTabs staleTabs } }'
 
-3) If you need an absolute URL, set `--selector-attr href-url` or set `attr` to `href-url`/`src-url`:
-<!-- test: "inspect passes selector attr" -->
-```bash
-tabctl inspect --tab <id> --signal selector --selector '{"name":"link","selector":"a[href]","attr":"href-url"}'
-tabctl inspect --tab <id> --signal selector --selector "link=a[href]" --selector-attr href-url
-```
+# Inspect page metadata
+tabctl query 'query { inspectTabs(tabIds: [456], signals: ["page-meta"]) { entries { tabId signals { name valueJson } } } }'
 
-## Agent skills
+# Inspect selectors with typed attrs and filters
+tabctl query 'query { inspectTabs(windowId: 123, selectors: [{ name: "prices", selector: ".price", attr: "text", all: true }, { name: "buy_now_visible", selector: "button.buy-now", attr: "visible" }, { name: "buy_now_style", selector: "button.buy-now", attr: "styles", styleProps: ["color", "background-color"] }, { name: "review_count", selector: ".review", attr: "count" }, { name: "email_value", selector: "input[type=email]", attr: "value" }]) { entries { tabId url signals { name valueJson } } } }'
 
-Install the tabctl skill for agents (OpenCode, Claude Code, Codex, etc.) via the bundled command (uses the Skills CLI under the hood):
+# Read tab content as Markdown (Kreuzberg preprocessing by default)
+tabctl query 'query { readTabs(windowId: 123, extract: true, maxChars: 30000) { entries { tabId title url markdown chars truncated extracted cached status emptyReason diagnostics { source sourceHtmlChars sourceTextChars documentReadyState truncatedHtml cachedAt cacheAgeMs } error } } }'
 
-<!-- test: "skill install creates project skill link" -->
-```bash
-tabctl skill
+# Generate reports
+tabctl query '{ reportTabs(windowId: 123) { entries { tabId title url description } } }'
+
+# 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 } } }'
+
+# Close tabs with undo support
+tabctl query 'mutation { closeTabs(tabIds: [456], confirm: true) { txid closedTabs } }'
+tabctl query 'mutation { undoAction(latest: true) { txid summary } }'
 ```
 
-This writes a project-local skill to `.opencode/skills/tabctl/SKILL.md`. You can also install globally:
+## Agent skills
+
+Install the tabctl skill for agents (OpenCode, Claude Code, Codex, etc.) via the Skills CLI:
 
-<!-- test: "skill install supports global scope" -->
 ```bash
-tabctl skill --global
+npx skills add https://github.com/ekroon/tabctl --skill tabctl -a opencode
 ```
 
-To install into a specific agent toolchain with `skills`:
+Install globally:
 
 ```bash
-npx skills add https://github.com/ekroon/tabctl --skill tabctl -a opencode
+npx skills add https://github.com/ekroon/tabctl --skill tabctl --global -a opencode
 ```
 
 ## Policy (protect tabs)
@@ -239,34 +243,38 @@ 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)
 
 - `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.
+- 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 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 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:
@@ -275,9 +283,9 @@ Local release-like sync test recipe:
 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
+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
 ```
 
@@ -302,7 +310,7 @@ tabctl profile-list
 tabctl profile-switch edge
 
 # One-off command with different profile
-tabctl list --profile chrome-work
+tabctl --profile chrome-work query '{ tabs { total } }'
 ```
 
 ### Custom Chrome Profile Directories
@@ -329,8 +337,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
 
@@ -348,8 +355,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
@@ -375,8 +394,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`
@@ -399,15 +424,11 @@ TABCTL_VERSION_MODE=release npm run build
 ```
 
 Notes:
-- `close --apply` uses the most recent analysis by `analysisId`.
-- `close` without `--apply` requires `--confirm` to prevent accidental closure.
+- Browser reads and mutations now go through GraphQL via `tabctl query`.
 - Reports include short descriptions from page metadata and a fallback snippet.
-- `list` and `group-list` paginate by default (limit 100); use `--limit`, `--offset`, or `--no-page`.
-- Use `--group-id -1` or `--ungrouped` to target ungrouped tabs.
-- `--selector` implies `--signal selector`.
-- Unknown inspect signals are rejected (valid: `page-meta`, `selector`).
-- 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`.
+- `inspectTabs` supports `page-meta` plus selector reads with `all`, `text`, `textMode`, `styleProps`, and attrs such as `html`, `value`, `count`, `box`, `styles`, `visible`, `enabled`, and `checked`.
+- `readTabs` converts main-frame page HTML to Markdown with Kreuzberg `html-to-markdown`; per-tab `status`, `emptyReason`, `diagnostics`, and `error` distinguish empty pages, unsupported URLs, injection failures, conversion failures, timeouts, and cached fallbacks (`status: CACHED`, `cached: true`, `diagnostics.source: "cache"`).
+- Cached fallbacks use a bounded profile-local open-tab HTML cache refreshed after successful reads, active tab switches, and quiescent active pages; diagnostics include cache age and match mode when cached content is used.
+- `captureScreenshots` returns tile metadata and image data from GraphQL.
+- `undoAction` accepts either an explicit `txid` or `latest: true`.
 - `tabctl history --json` returns a top-level JSON array.
-- `--format` is only supported by `report` (use `--json` elsewhere).