tabctl 0.1.0

package/README.md

@@ -0,0 +1,261 @@
+# 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.
+
+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.
+
+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
+
+```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`.
+
+### 2. Set up your browser
+
+Run the interactive setup — it syncs the extension, tells you where to load it, and prompts for the extension ID:
+
+<!-- test: "setup interactive mode reads extension-id from stdin" -->
+```bash
+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. Prompt you to paste the extension ID
+
+> **Edge?** Use `--browser edge` and load from `edge://extensions` instead.
+
+If you already know your extension ID, skip the interactive flow:
+
+<!-- test: "setup writes native host manifest for chrome" -->
+```bash
+tabctl setup --browser chrome --extension-id <your-extension-id>
+```
+
+### 3. Verify and explore
+
+<!-- test: "ping sends ping action", "list sends list action" -->
+```bash
+tabctl ping       # check the connection
+tabctl list       # see your open tabs
+```
+
+> **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 github options", "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 analyze` | Find stale or duplicate tabs |
+| `tabctl inspect --tab <id>` | Extract page metadata or CSS selectors |
+| `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 |
+
+See [CLI.md](CLI.md) for the full command reference, options, and examples.
+
+## Screenshot output
+When `--out` is omitted, screenshots are written to `./.tabctl/screenshots/<timestamp>` and the JSON response includes `writtenTo`.
+
+## Agent workflow (context -> selector)
+Use screenshots only when you need visual context, then extract selectors with `inspect`.
+
+1) Capture context (full page tiles):
+<!-- test: "screenshot passes capture options" -->
+```bash
+tabctl screenshot --tab <id> --mode full
+```
+
+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"}'
+```
+
+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
+```
+
+## Agent skills
+
+Install the tabctl skill for agents (OpenCode, Claude Code, Codex, etc.) via the bundled command (uses the Skills CLI under the hood):
+
+<!-- test: "skill install creates project skill link" -->
+```bash
+tabctl skill
+```
+
+This writes a project-local skill to `.opencode/skills/tabctl/SKILL.md`. You can also install globally:
+
+<!-- test: "skill install supports global scope" -->
+```bash
+tabctl skill --global
+```
+
+To install into a specific agent toolchain with `skills`:
+
+```bash
+npx skills add https://github.com/ekroon/tabctl --skill tabctl -a opencode
+```
+
+## Policy (protect tabs)
+By default the CLI loads a policy file from:
+`<configDir>/policy.json` (default: `~/.config/tabctl/policy.json`)
+
+Set `TABCTL_CONFIG_DIR` to override the config directory.
+
+This is a **protection-only** policy that marks tabs as ineligible for agent actions.
+Example:
+
+```json
+{
+  "protect": {
+    "pinned": true,
+    "groupTitles": ["🔒"]
+  }
+}
+```
+
+Create a default policy file:
+
+<!-- test: "policy init creates default file" -->
+```bash
+tabctl policy --init
+```
+
+`tabctl setup` does not install a default policy.
+See `config/policy.example.json` for a starter template.
+
+## Configuration
+Config directory: `TABCTL_CONFIG_DIR` → `$XDG_CONFIG_HOME/tabctl` → `~/.config/tabctl`
+
+An optional `config.json` in the config directory can set `dataDir` to override where state files (socket, undo log) are stored. When `TABCTL_CONFIG_DIR` is set but no `dataDir` is configured, data defaults to `<configDir>/data/`; otherwise it uses `$XDG_STATE_HOME/tabctl` (or `~/.local/state/tabctl`).
+
+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`)
+- Profile registry: `<configDir>/profiles.json`
+
+## Multi-Browser Setup
+
+> **Advanced topic** — you only need this if you run tabctl with more than one browser (e.g. Edge *and* Chrome).
+
+tabctl supports multiple browser profiles. Each profile connects to a different **browser** (Chrome, Edge).
+
+<!-- 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 --extension-id <edge-id>
+
+# Setup for Chrome (with custom name)
+tabctl setup --browser chrome --extension-id <chrome-id> --name chrome-work
+
+# List profiles
+tabctl profile-list
+
+# Switch default
+tabctl profile-switch edge
+
+# One-off command with different profile
+tabctl list --profile chrome-work
+```
+
+### Custom Chrome Profile Directories
+
+If you launch Chrome with `--user-data-dir`, Chrome looks for native messaging manifests inside that directory. Use `--user-data-dir` in setup to write the manifest to the right place:
+
+<!-- test: "setup --user-data-dir writes manifest to custom path" -->
+```bash
+tabctl setup --browser chrome --user-data-dir /path/to/chrome-profile
+```
+
+This writes the manifest to `<user-data-dir>/NativeMessagingHosts/` instead of the system-wide location.
+
+### How It Works
+
+Each profile gets its own:
+- Native host manifest and wrapper script
+- Unix socket for CLI-host communication
+- Undo history log
+- Data directory
+
+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.
+
+## 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 and test:
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+### Versioning
+The base version lives in `package.json` and is embedded into the CLI, host, and extension at build time.
+
+Commands:
+```bash
+npm run bump:patch
+npm run bump:minor
+npm run bump:major
+```
+
+Local builds default to a dev version when a `.git` directory is present, appending the short SHA.
+```bash
+npm run build
+```
+
+This produces versions like `0.1.0-dev.abc12345` (and appends `.dirty` when the repo has uncommitted changes).
+
+For release builds without SHA, set:
+```bash
+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.
+- 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`, `github-state`, `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`.
+- `tabctl history --json` returns a JSON array in `data`.
+- `--format` is only supported by `report` (use `--json` elsewhere).

package/cli/lib/args.js

@@ -0,0 +1,141 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeGroupColor = normalizeGroupColor;
+exports.normalizeSignals = normalizeSignals;
+exports.validateSignals = validateSignals;
+exports.parseArgs = parseArgs;
+const constants_1 = require("./constants");
+const options_1 = require("./options");
+const output_1 = require("./output");
+function normalizeGroupColor(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim().toLowerCase();
+    if (!trimmed) {
+        return undefined;
+    }
+    if (!constants_1.GROUP_COLORS.has(trimmed)) {
+        (0, output_1.errorOut)(`Invalid color: ${value}. Use one of: ${Array.from(constants_1.GROUP_COLORS).join(", ")}`);
+    }
+    return trimmed;
+}
+function normalizeSignals(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.map((signal) => String(signal).trim()).filter(Boolean);
+}
+function validateSignals(signals) {
+    for (const signal of signals) {
+        if (!constants_1.SUPPORTED_SIGNAL_SET.has(signal)) {
+            (0, output_1.errorOut)(`Unknown signal: ${signal}. Use one of: ${constants_1.SUPPORTED_SIGNALS.join(", ")}`);
+        }
+    }
+}
+function normalizeCommand(value) {
+    if (!value) {
+        return value;
+    }
+    if (value === "groups" || value === "group") {
+        return "group-list";
+    }
+    const meta = options_1.COMMANDS[value];
+    if (!meta?.aliases || meta.aliases.length === 0) {
+        return value;
+    }
+    return meta.aliases[0] ?? value;
+}
+function parseArgs(argv) {
+    const args = [...argv];
+    let command;
+    const options = { _: [] };
+    const warnings = [];
+    const pendingFlags = [];
+    const allowedFlags = (0, options_1.getAllowedFlags)();
+    const booleanFlags = (0, options_1.getBooleanFlags)();
+    while (args.length > 0) {
+        const arg = args.shift();
+        if (!arg.startsWith("--")) {
+            if (!command) {
+                command = normalizeCommand(arg);
+                if (command) {
+                    const commandAllowedFlags = (0, options_1.getCommandAllowedFlags)(command);
+                    for (const pending of pendingFlags) {
+                        if (!commandAllowedFlags.has(pending)) {
+                            warnings.push(`--${pending} is not supported by ${command}`);
+                        }
+                    }
+                }
+                continue;
+            }
+            options._.push(arg);
+            continue;
+        }
+        const key = arg.slice(2);
+        if (!allowedFlags.has(key)) {
+            if (key === "format") {
+                (0, output_1.errorOut)("Unknown option: --format");
+            }
+            (0, output_1.errorOut)(`Unknown option: --${key}`);
+        }
+        if (command) {
+            const commandAllowedFlags = (0, options_1.getCommandAllowedFlags)(command);
+            if (!commandAllowedFlags.has(key)) {
+                warnings.push(`--${key} is not supported by ${command}`);
+            }
+        }
+        else {
+            pendingFlags.push(key);
+        }
+        // Boolean flags (no value needed)
+        if (booleanFlags.has(key)) {
+            options[key] = true;
+            continue;
+        }
+        // Value required
+        const value = args.shift();
+        if (value == null) {
+            (0, output_1.errorOut)(`Missing value for --${key}`);
+        }
+        // Repeatable flags (accumulate into arrays)
+        if (key === "signal") {
+            if (!options.signal) {
+                options.signal = [];
+            }
+            options.signal.push(value);
+            continue;
+        }
+        if (key === "tab") {
+            if (!options.tab) {
+                options.tab = [];
+            }
+            options.tab.push(value);
+            continue;
+        }
+        if (key === "agent") {
+            if (!options.agent) {
+                options.agent = [];
+            }
+            options.agent.push(value);
+            continue;
+        }
+        if (key === "url") {
+            if (!options.url) {
+                options.url = [];
+            }
+            options.url.push(value);
+            continue;
+        }
+        if (key === "selector") {
+            if (!options.selector) {
+                options.selector = [];
+            }
+            options.selector.push(value);
+            continue;
+        }
+        // Single value flags
+        options[key] = value;
+    }
+    return { command, options, warnings };
+}

package/cli/lib/client.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRequestId = createRequestId;
+exports.sendRequest = sendRequest;
+exports.fetchSnapshot = fetchSnapshot;
+const net_1 = __importDefault(require("net"));
+const constants_1 = require("./constants");
+function createRequestId() {
+    return `req-${Date.now()}-${Math.random().toString(16).slice(2, 10)}`;
+}
+function sendRequest(payload, onProgress) {
+    return new Promise((resolve, reject) => {
+        const { socketPath } = (0, constants_1.resolveConfig)();
+        const client = net_1.default.createConnection(socketPath);
+        let buffer = "";
+        client.on("connect", () => {
+            client.write(`${JSON.stringify(payload)}\n`);
+        });
+        client.on("data", (data) => {
+            buffer += data;
+            let index;
+            while ((index = buffer.indexOf("\n")) >= 0) {
+                const line = buffer.slice(0, index).trim();
+                buffer = buffer.slice(index + 1);
+                if (!line) {
+                    continue;
+                }
+                let response;
+                try {
+                    response = JSON.parse(line);
+                }
+                catch (error) {
+                    client.end();
+                    client.destroy();
+                    reject(error);
+                    return;
+                }
+                if (response.progress && onProgress) {
+                    onProgress(response);
+                    continue;
+                }
+                client.end();
+                client.destroy();
+                resolve(response);
+                return;
+            }
+        });
+        client.on("error", (error) => {
+            reject(error);
+        });
+    });
+}
+async function fetchSnapshot() {
+    const response = await sendRequest({ id: createRequestId(), action: "list", params: {} });
+    if (!response.ok) {
+        return null;
+    }
+    return response.data;
+}

package/cli/lib/commands/index.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Command module index.
+ * Re-exports all command handlers and parameter builders.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUndoParams = exports.buildHistoryParams = exports.buildScreenshotParams = exports.buildReportParams = exports.buildCloseParams = exports.buildArchiveParams = exports.buildMergeWindowParams = exports.buildMoveGroupParams = exports.buildMoveTabParams = exports.buildGroupAssignParams = exports.buildGroupUngroupParams = exports.buildGroupUpdateParams = exports.buildOpenParams = exports.buildRefreshParams = exports.buildFocusParams = exports.buildInspectParams = exports.buildAnalyzeParams = exports.runProfileRemove = exports.runProfileSwitch = exports.runProfileShow = exports.runProfileList = exports.runGroupList = exports.runList = exports.runPing = exports.runUndo = exports.runHistory = exports.runPolicy = exports.runVersion = exports.runSkillInstall = exports.runSetup = void 0;
+// Meta commands (version, ping, setup, skill, policy, history, undo)
+var meta_1 = require("./meta");
+Object.defineProperty(exports, "runSetup", { enumerable: true, get: function () { return meta_1.runSetup; } });
+Object.defineProperty(exports, "runSkillInstall", { enumerable: true, get: function () { return meta_1.runSkillInstall; } });
+Object.defineProperty(exports, "runVersion", { enumerable: true, get: function () { return meta_1.runVersion; } });
+Object.defineProperty(exports, "runPolicy", { enumerable: true, get: function () { return meta_1.runPolicy; } });
+Object.defineProperty(exports, "runHistory", { enumerable: true, get: function () { return meta_1.runHistory; } });
+Object.defineProperty(exports, "runUndo", { enumerable: true, get: function () { return meta_1.runUndo; } });
+Object.defineProperty(exports, "runPing", { enumerable: true, get: function () { return meta_1.runPing; } });
+// List commands (list, group-list)
+var list_1 = require("./list");
+Object.defineProperty(exports, "runList", { enumerable: true, get: function () { return list_1.runList; } });
+Object.defineProperty(exports, "runGroupList", { enumerable: true, get: function () { return list_1.runGroupList; } });
+// Profile commands (profile-list, profile-show, profile-switch, profile-remove)
+var profile_1 = require("./profile");
+Object.defineProperty(exports, "runProfileList", { enumerable: true, get: function () { return profile_1.runProfileList; } });
+Object.defineProperty(exports, "runProfileShow", { enumerable: true, get: function () { return profile_1.runProfileShow; } });
+Object.defineProperty(exports, "runProfileSwitch", { enumerable: true, get: function () { return profile_1.runProfileSwitch; } });
+Object.defineProperty(exports, "runProfileRemove", { enumerable: true, get: function () { return profile_1.runProfileRemove; } });
+// Parameter builders for all commands
+var params_1 = require("./params");
+Object.defineProperty(exports, "buildAnalyzeParams", { enumerable: true, get: function () { return params_1.buildAnalyzeParams; } });
+Object.defineProperty(exports, "buildInspectParams", { enumerable: true, get: function () { return params_1.buildInspectParams; } });
+Object.defineProperty(exports, "buildFocusParams", { enumerable: true, get: function () { return params_1.buildFocusParams; } });
+Object.defineProperty(exports, "buildRefreshParams", { enumerable: true, get: function () { return params_1.buildRefreshParams; } });
+Object.defineProperty(exports, "buildOpenParams", { enumerable: true, get: function () { return params_1.buildOpenParams; } });
+Object.defineProperty(exports, "buildGroupUpdateParams", { enumerable: true, get: function () { return params_1.buildGroupUpdateParams; } });
+Object.defineProperty(exports, "buildGroupUngroupParams", { enumerable: true, get: function () { return params_1.buildGroupUngroupParams; } });
+Object.defineProperty(exports, "buildGroupAssignParams", { enumerable: true, get: function () { return params_1.buildGroupAssignParams; } });
+Object.defineProperty(exports, "buildMoveTabParams", { enumerable: true, get: function () { return params_1.buildMoveTabParams; } });
+Object.defineProperty(exports, "buildMoveGroupParams", { enumerable: true, get: function () { return params_1.buildMoveGroupParams; } });
+Object.defineProperty(exports, "buildMergeWindowParams", { enumerable: true, get: function () { return params_1.buildMergeWindowParams; } });
+Object.defineProperty(exports, "buildArchiveParams", { enumerable: true, get: function () { return params_1.buildArchiveParams; } });
+Object.defineProperty(exports, "buildCloseParams", { enumerable: true, get: function () { return params_1.buildCloseParams; } });
+Object.defineProperty(exports, "buildReportParams", { enumerable: true, get: function () { return params_1.buildReportParams; } });
+Object.defineProperty(exports, "buildScreenshotParams", { enumerable: true, get: function () { return params_1.buildScreenshotParams; } });
+Object.defineProperty(exports, "buildHistoryParams", { enumerable: true, get: function () { return params_1.buildHistoryParams; } });
+Object.defineProperty(exports, "buildUndoParams", { enumerable: true, get: function () { return params_1.buildUndoParams; } });

package/cli/lib/commands/list.js

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * List command handlers: list, group-list
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runList = runList;
+exports.runGroupList = runGroupList;
+const constants_1 = require("../constants");
+const output_1 = require("../output");
+const client_1 = require("../client");
+const scope_1 = require("../scope");
+const pagination_1 = require("../pagination");
+const snapshot_1 = require("../snapshot");
+// ============================================================================
+// List Command
+// ============================================================================
+async function runList(options, policyContext, policySummary, prettyOutput) {
+    // Validate scope flags early (before connecting) so invalid values
+    // are rejected without needing a socket connection.
+    const scope = (0, scope_1.resolveScopeFlags)(options);
+    const response = await (0, client_1.sendRequest)({
+        id: (0, client_1.createRequestId)(),
+        action: "list",
+        params: {},
+        client: {
+            component: "cli",
+            version: constants_1.VERSION,
+            baseVersion: constants_1.BASE_VERSION,
+            gitSha: constants_1.GIT_SHA,
+            dirty: constants_1.DIRTY,
+        },
+    });
+    if (!response.ok) {
+        (0, output_1.printJson)(response, prettyOutput);
+        process.exit(1);
+    }
+    const data = response.data;
+    if (data && Array.isArray(data.windows)) {
+        const filtered = (0, snapshot_1.filterSnapshotByPolicy)(data, policyContext.policy);
+        if (typeof scope.windowId === "string") {
+            const resolvedWindowId = (0, scope_1.resolveWindowIdFromSnapshot)(filtered, scope.windowId);
+            scope.windowId = resolvedWindowId ?? null;
+        }
+        const allScope = options.all === true || !scope.hasScope;
+        const listParams = allScope
+            ? { all: true }
+            : {
+                tabIds: scope.tabIds.length ? scope.tabIds : undefined,
+                groupTitle: scope.groupTitle || undefined,
+                groupId: scope.groupId != null ? scope.groupId : undefined,
+                windowId: scope.windowId != null ? scope.windowId : undefined,
+            };
+        if (typeof listParams.windowId === "string") {
+            const resolvedWindowId = (0, scope_1.resolveWindowIdFromSnapshot)(filtered, listParams.windowId);
+            listParams.windowId = resolvedWindowId ?? undefined;
+        }
+        const selection = (0, scope_1.selectTabsFromSnapshot)(filtered, listParams);
+        if (selection.error) {
+            (0, output_1.printJson)({ ok: false, error: selection.error }, prettyOutput);
+            process.exit(1);
+        }
+        const selectedTabs = selection.tabs || [];
+        const tabIdSet = new Set(selectedTabs.map((tab) => tab.tabId).filter((id) => typeof id === "number"));
+        const ordered = listParams.all
+            ? (0, snapshot_1.orderTabs)(filtered, null)
+            : tabIdSet.size > 0
+                ? (0, snapshot_1.orderTabs)(filtered, tabIdSet)
+                : [];
+        const scopeArgs = (0, scope_1.buildScopeArgs)(options, allScope);
+        const pagination = (0, pagination_1.resolvePagination)(options, ordered.length, "list", scopeArgs);
+        const start = pagination.offset;
+        const end = pagination.offset + pagination.limit;
+        const pagedTabs = ordered.slice(start, end);
+        const pagedSnapshot = (0, snapshot_1.buildPagedSnapshot)(filtered, pagedTabs);
+        data.windows = pagedSnapshot.windows;
+        if (pagination.page) {
+            data.page = pagination.page;
+        }
+        data.policy = policySummary;
+    }
+    else if (response.ok) {
+        response.policy = policySummary;
+    }
+    (0, output_1.emitVersionWarnings)(response, "list");
+    (0, output_1.printJson)(response, prettyOutput);
+}
+// ============================================================================
+// Group-List Command
+// ============================================================================
+async function runGroupList(options, policyContext, policySummary, prettyOutput) {
+    const params = {
+        windowId: options.all ? undefined : options.window,
+    };
+    const response = await (0, client_1.sendRequest)({
+        id: (0, client_1.createRequestId)(),
+        action: "group-list",
+        params,
+        client: {
+            component: "cli",
+            version: constants_1.VERSION,
+            baseVersion: constants_1.BASE_VERSION,
+            gitSha: constants_1.GIT_SHA,
+            dirty: constants_1.DIRTY,
+        },
+    });
+    if (!response.ok) {
+        (0, output_1.printJson)(response, prettyOutput);
+        process.exit(1);
+    }
+    const data = response.data;
+    // Fallback to snapshot if groups missing
+    if (data && (!Array.isArray(data.groups) || data.groups === null)) {
+        const scope = (0, scope_1.resolveScopeFlags)(options);
+        const snapshot = await (0, client_1.fetchSnapshot)();
+        if (snapshot) {
+            const filteredSnapshot = (0, snapshot_1.filterSnapshotByPolicy)(snapshot, policyContext.policy);
+            if (typeof scope.windowId === "string") {
+                const resolvedWindowId = (0, scope_1.resolveWindowIdFromSnapshot)(filteredSnapshot, scope.windowId);
+                scope.windowId = resolvedWindowId ?? null;
+            }
+            const scopeWindow = typeof scope.windowId === "number" && Number.isFinite(scope.windowId) ? scope.windowId : null;
+            const groups = (0, snapshot_1.buildGroupsFromSnapshot)(filteredSnapshot, scopeWindow);
+            data.groups = (0, scope_1.filterGroupsByScope)(groups, scope, filteredSnapshot, snapshot_1.buildTabIndex);
+        }
+        else {
+            data.groups = [];
+        }
+    }
+    // Apply scope filtering and pagination
+    if (data && Array.isArray(data.groups)) {
+        let groups = data.groups;
+        const scope = (0, scope_1.resolveScopeFlags)(options);
+        const allScope = options.all === true || !scope.hasScope;
+        let snapshot = null;
+        if (!allScope && scope.tabIds.length > 0) {
+            snapshot = await (0, client_1.fetchSnapshot)();
+            if (!snapshot) {
+                (0, output_1.errorOut)("Failed to load tabs for group-list filtering");
+            }
+        }
+        if (!allScope) {
+            groups = (0, scope_1.filterGroupsByScope)(groups, scope, snapshot, snapshot_1.buildTabIndex);
+        }
+        const scopeArgs = (0, scope_1.buildScopeArgs)(options, allScope);
+        const pagination = (0, pagination_1.resolvePagination)(options, groups.length, "group-list", scopeArgs);
+        const start = pagination.offset;
+        const end = pagination.offset + pagination.limit;
+        data.groups = groups.slice(start, end);
+        if (pagination.page) {
+            data.page = pagination.page;
+        }
+        data.policy = policySummary;
+    }
+    else if (response.ok) {
+        response.policy = policySummary;
+    }
+    (0, output_1.emitVersionWarnings)(response, "group-list");
+    (0, output_1.printJson)(response, prettyOutput);
+}