tabctl 0.1.0

package/cli/lib/help.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Help generation using option groups from options.ts as the source of truth.
+ * This eliminates duplication by referencing option groups instead of repeating
+ * options for every command.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildHelpData = buildHelpData;
+exports.printHelp = printHelp;
+const constants_1 = require("./constants");
+const options_1 = require("./options");
+const output_1 = require("./output");
+// ============================================================================
+// Help Data Generation
+// ============================================================================
+function formatOption(opt) {
+    if (opt.repeatable) {
+        return `${opt.flag} (repeatable)`;
+    }
+    return opt.flag;
+}
+/**
+ * Build structured help data from COMMANDS and OPTION_GROUPS.
+ */
+function buildHelpData(command) {
+    // Build option groups
+    const optionGroups = Object.entries(options_1.OPTION_GROUPS).map(([_key, group]) => ({
+        name: group.name,
+        description: group.description,
+        options: group.options.map(formatOption),
+    }));
+    optionGroups.push({
+        name: options_1.SCREENSHOT_OPTIONS.name,
+        description: options_1.SCREENSHOT_OPTIONS.description,
+        options: options_1.SCREENSHOT_OPTIONS.options.map(formatOption),
+    });
+    // Build commands list with their groups and specific options
+    const commands = Object.entries(options_1.COMMANDS)
+        .map(([name, meta]) => {
+        const cmd = {
+            name,
+            description: meta.description,
+        };
+        if (meta.groups && meta.groups.length > 0) {
+            cmd.groups = [...meta.groups];
+        }
+        if (meta.options && meta.options.length > 0) {
+            cmd.options = meta.options.map(formatOption);
+        }
+        return cmd;
+    });
+    const normalizedCommand = command ? normalizeHelpCommand(command) : undefined;
+    if (normalizedCommand && !options_1.COMMANDS[normalizedCommand]) {
+        (0, output_1.errorOut)(`Unknown command: ${normalizedCommand}`);
+    }
+    const filteredCommands = normalizedCommand
+        ? commands.filter((entry) => entry.name === normalizedCommand)
+        : commands;
+    const filteredGroups = normalizedCommand
+        ? optionGroups.filter((group) => {
+            const target = filteredCommands[0];
+            if (!target?.groups || target.groups.length === 0) {
+                return false;
+            }
+            const included = target.groups.some((groupKey) => {
+                const meta = options_1.OPTION_GROUPS[groupKey];
+                return meta?.name === group.name;
+            });
+            if (target.name === "screenshot" && group.name === options_1.SCREENSHOT_OPTIONS.name) {
+                return true;
+            }
+            return included;
+        })
+        : optionGroups;
+    // Global options
+    const globalOptions = ["--help", "--json", "--pretty"];
+    // Notes
+    const notes = [
+        "--before-group/--after-group only position tabs; use group-assign to move tabs into a group.",
+        "undo accepts a txid as a positional arg (or --txid) and supports --latest.",
+        "screenshot uses --out to write per-tab folders under the target directory.",
+        "Use selector attr href-url/src-url to resolve absolute http(s) links.",
+    ];
+    return {
+        version: constants_1.VERSION,
+        usage: "tabctl <command> [options]",
+        commands: filteredCommands,
+        optionGroups: filteredGroups,
+        globalOptions,
+        notes,
+    };
+}
+function normalizeHelpCommand(command) {
+    const trimmed = command.trim();
+    if (!trimmed) {
+        return undefined;
+    }
+    if (trimmed === "groups" || trimmed === "group") {
+        return "group-list";
+    }
+    return trimmed;
+}
+// ============================================================================
+// Text Output Formatting
+// ============================================================================
+/**
+ * Print help in human-readable text format.
+ */
+function printHelpText(data, command) {
+    const lines = [];
+    // Header
+    lines.push("tabctl - Edge tab management CLI");
+    lines.push(`Version: ${data.version}`);
+    lines.push("");
+    lines.push(`Usage: ${data.usage}`);
+    lines.push("");
+    if (!command) {
+        // Commands grouped by category
+        lines.push("Commands:");
+        const commandNames = data.commands.map((c) => c.name);
+        lines.push(`  ${commandNames.join(", ")}`);
+        lines.push("");
+    }
+    // Option Groups
+    if (!command) {
+        lines.push("Option Groups:");
+        lines.push("  (Commands reference these groups; see command details below)");
+        lines.push("");
+        for (const group of data.optionGroups) {
+            lines.push(`  [${group.name}] - ${group.description}`);
+            for (const opt of group.options) {
+                lines.push(`    ${opt}`);
+            }
+            lines.push("");
+        }
+    }
+    else {
+        for (const group of data.optionGroups) {
+            lines.push(`Options (${group.name}):`);
+            for (const opt of group.options) {
+                lines.push(`  ${opt}`);
+            }
+            lines.push("");
+        }
+    }
+    // Command Details
+    lines.push("Command Details:");
+    for (const cmd of data.commands) {
+        const parts = [`  ${cmd.name}`];
+        if (cmd.description) {
+            parts.push(`- ${cmd.description}`);
+        }
+        lines.push(parts.join(" "));
+        // Show which groups the command uses
+        if (!command && cmd.groups && cmd.groups.length > 0) {
+            const groupRefs = cmd.groups.map((g) => {
+                const group = options_1.OPTION_GROUPS[g];
+                return group ? `[${group.name}]` : `[${g}]`;
+            });
+            lines.push(`    Uses: ${groupRefs.join(", ")}`);
+        }
+        // Show command-specific options
+        if (cmd.options && cmd.options.length > 0) {
+            lines.push("    Options:");
+            for (const opt of cmd.options) {
+                lines.push(`      ${opt}`);
+            }
+        }
+    }
+    lines.push("");
+    // Global Options
+    if (!command) {
+        lines.push("Global Options:");
+        for (const opt of data.globalOptions) {
+            lines.push(`  ${opt}`);
+        }
+        lines.push("");
+    }
+    // Notes
+    if (!command) {
+        lines.push("Notes:");
+        for (const note of data.notes) {
+            lines.push(`  ${note}`);
+        }
+        lines.push("");
+    }
+    // Policy location
+    lines.push("Policy: $XDG_CONFIG_HOME/tabctl/policy.json (or ~/.config/tabctl/policy.json)");
+    lines.push("Policy is enforced when the file exists; missing file means no policy.");
+    process.stdout.write(lines.join("\n") + "\n");
+}
+// ============================================================================
+// Public API
+// ============================================================================
+/**
+ * Print help output in either JSON or text format.
+ */
+function printHelp(jsonOutput, command) {
+    const data = buildHelpData(command);
+    if (jsonOutput) {
+        (0, output_1.printJson)({ ok: true, data });
+        return;
+    }
+    printHelpText(data, command);
+}

package/cli/lib/options.js

@@ -0,0 +1,408 @@
+"use strict";
+/**
+ * Central source of truth for CLI options and command metadata.
+ * This eliminates duplication between argument parsing and help display.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMMANDS = exports.SCREENSHOT_OPTIONS = exports.OPTION_GROUPS = void 0;
+exports.getBooleanFlags = getBooleanFlags;
+exports.getAllowedFlags = getAllowedFlags;
+exports.getCommandAllowedFlags = getCommandAllowedFlags;
+exports.getCommandGroups = getCommandGroups;
+exports.getCommandOptions = getCommandOptions;
+exports.commandSupportsGroup = commandSupportsGroup;
+const GLOBAL_FLAGS = ["help", "json", "pretty"];
+// ============================================================================
+// Option Group Definitions
+// ============================================================================
+exports.OPTION_GROUPS = {
+    scope: {
+        name: "Scope Options",
+        description: "Filter which tabs/groups to operate on",
+        options: [
+            { flag: "--tab <id>", desc: "Target specific tab(s) by ID", repeatable: true },
+            { flag: "--group <name>", desc: "Target tabs in group by title" },
+            { flag: "--group-id <id>", desc: "Target group by ID (use -1 for ungrouped)" },
+            { flag: "--ungrouped", desc: "Alias for --group-id -1" },
+            { flag: "--window <id|active|last-focused>", desc: "Target tabs in specific window" },
+            { flag: "--all", desc: "Target all eligible tabs" },
+        ],
+    },
+    pagination: {
+        name: "Pagination Options",
+        description: "Control result paging (default limit: 100)",
+        options: [
+            { flag: "--limit <n>", desc: "Maximum items to return" },
+            { flag: "--offset <n>", desc: "Skip first n items" },
+            { flag: "--no-page", desc: "Disable pagination, return all results" },
+        ],
+    },
+};
+exports.SCREENSHOT_OPTIONS = {
+    name: "Screenshot Options",
+    description: "Control screenshot capture",
+    options: [
+        { flag: "--mode viewport|full", desc: "Capture mode" },
+        { flag: "--format png|jpeg", desc: "Image format" },
+        { flag: "--quality <n>", desc: "JPEG quality (0-100)" },
+        { flag: "--tile-max-dim <px>", desc: "Max tile dimension in pixels" },
+        { flag: "--max-bytes <n>", desc: "Max bytes per tile" },
+        { flag: "--wait-for load|dom|settle|none", desc: "Wait for page readiness before capture" },
+        { flag: "--wait-timeout-ms <ms>", desc: "Timeout for page readiness wait" },
+        { flag: "--out <dir>", desc: "Write files to directory" },
+        { flag: "--progress", desc: "Show progress during capture" },
+    ],
+};
+// ============================================================================
+// Command Metadata
+// ============================================================================
+exports.COMMANDS = {
+    help: {
+        description: "Show help information",
+    },
+    list: {
+        description: "List browser tabs",
+        groups: ["scope", "pagination"],
+        options: [
+            { flag: "--groups", desc: "Alias for group-list command" },
+        ],
+    },
+    analyze: {
+        description: "Analyze tabs for duplicates and stale content",
+        groups: ["scope"],
+        options: [
+            { flag: "--stale-days <n>", desc: "Days threshold for stale tabs" },
+            { flag: "--github", desc: "Enable GitHub PR/issue status checking" },
+            { flag: "--github-concurrency <n>", desc: "Max concurrent GitHub API requests" },
+            { flag: "--github-timeout-ms <ms>", desc: "Timeout for GitHub API requests" },
+            { flag: "--window-title", desc: "Include active window title in output" },
+            { flag: "--progress", desc: "Show progress during analysis" },
+        ],
+    },
+    dedupe: {
+        description: "Interactively deduplicate tabs",
+        groups: ["scope"],
+        options: [
+            { flag: "--stale-days <n>", desc: "Days threshold for stale tabs" },
+            { flag: "--github", desc: "Enable GitHub PR/issue status checking" },
+            { flag: "--github-concurrency <n>", desc: "Max concurrent GitHub API requests" },
+            { flag: "--github-timeout-ms <ms>", desc: "Timeout for GitHub API requests" },
+            { flag: "--include-stale", desc: "Include stale tabs in deduplication" },
+            { flag: "--window-title", desc: "Include active window title in output" },
+            { flag: "--progress", desc: "Show progress during analysis" },
+            { flag: "--confirm", desc: "Execute changes without prompting" },
+        ],
+    },
+    inspect: {
+        description: "Extract signals from tab content",
+        groups: ["scope", "pagination"],
+        options: [
+            { flag: "--signal-config <path>", desc: "Path to signal configuration file" },
+            { flag: "--signal <id>", desc: "Signal ID to extract", repeatable: true },
+            { flag: "--selector <name=css|json>", desc: "Custom selector definition (attr: href-url/src-url supported; text/textMode supported)", repeatable: true },
+            { flag: "--selector-attr <attr>", desc: "Default selector attr (text|href|src|href-url|src-url)" },
+            { flag: "--signal-concurrency <n>", desc: "Max concurrent signal extractions" },
+            { flag: "--signal-timeout-ms <ms>", desc: "Timeout for signal extraction" },
+            { flag: "--wait-for load|dom|settle|none", desc: "Wait for page readiness before inspection" },
+            { flag: "--wait-timeout-ms <ms>", desc: "Timeout for page readiness wait" },
+            { flag: "--progress", desc: "Show progress during inspection" },
+        ],
+    },
+    screenshot: {
+        description: "Capture screenshots from tabs",
+        groups: ["scope"],
+        options: exports.SCREENSHOT_OPTIONS.options,
+    },
+    focus: {
+        description: "Focus a specific tab",
+        options: [
+            { flag: "--tab <id>", desc: "Tab ID to focus" },
+        ],
+    },
+    refresh: {
+        description: "Refresh a specific tab",
+        options: [
+            { flag: "--tab <id>", desc: "Tab ID to refresh" },
+        ],
+    },
+    open: {
+        description: "Open new tabs with URLs",
+        options: [
+            { flag: "--url <url>", desc: "URL to open", repeatable: true },
+            { flag: "--group <name>", desc: "Add tabs to group by name" },
+            { flag: "--color <name>", desc: "Group color (if creating)" },
+            { flag: "--before-tab <id>", desc: "Position before this tab" },
+            { flag: "--after-tab <id>", desc: "Position after this tab" },
+            { flag: "--after-group <name>", desc: "Position after this group" },
+            { flag: "--window <id|active|last-focused|new>", desc: "Target window ID" },
+            { flag: "--new-window", desc: "Open in new window" },
+            { flag: "--window-group <name>", desc: "Find window containing group" },
+            { flag: "--window-tab <id>", desc: "Find window containing tab" },
+            { flag: "--window-url <substring>", desc: "Find window containing URL" },
+        ],
+    },
+    "group-list": {
+        description: "List tab groups",
+        groups: ["scope", "pagination"],
+    },
+    group: {
+        description: "Alias for group-list",
+        aliases: ["group-list"],
+        groups: ["scope", "pagination"],
+    },
+    "group-update": {
+        description: "Update tab group properties",
+        options: [
+            { flag: "--group <name>", desc: "Target group by title" },
+            { flag: "--group-id <id>", desc: "Target group by ID" },
+            { flag: "--window <id|active|last-focused>", desc: "Target window ID" },
+            { flag: "--title <name>", desc: "New group title" },
+            { flag: "--color <name>", desc: "New group color" },
+            { flag: "--collapsed", desc: "Collapse the group" },
+            { flag: "--expanded", desc: "Expand the group" },
+        ],
+    },
+    "group-ungroup": {
+        description: "Remove tabs from a group",
+        options: [
+            { flag: "--group <name>", desc: "Target group by title" },
+            { flag: "--group-id <id>", desc: "Target group by ID" },
+            { flag: "--window <id|active|last-focused>", desc: "Target window ID" },
+        ],
+    },
+    "group-assign": {
+        description: "Assign tabs to a group",
+        options: [
+            { flag: "--tab <id>", desc: "Tab ID(s) to assign", repeatable: true },
+            { flag: "--group <name>", desc: "Target group by title" },
+            { flag: "--group-id <id>", desc: "Target group by ID" },
+            { flag: "--window <id|active|last-focused>", desc: "Target window ID" },
+            { flag: "--create", desc: "Create group if not exists" },
+            { flag: "--color <name>", desc: "Group color (if creating)" },
+            { flag: "--collapsed", desc: "Collapse group after assign" },
+            { flag: "--expanded", desc: "Expand group after assign" },
+        ],
+    },
+    "move-tab": {
+        description: "Move a tab to a new position",
+        options: [
+            { flag: "--tab <id>", desc: "Tab ID to move" },
+            { flag: "--before-tab <id>", desc: "Position before this tab" },
+            { flag: "--after-tab <id>", desc: "Position after this tab" },
+            { flag: "--before-group <name>", desc: "Position before this group" },
+            { flag: "--after-group <name>", desc: "Position after this group" },
+            { flag: "--window <id|active|last-focused>", desc: "Target window ID" },
+            { flag: "--new-window", desc: "Move to new window" },
+        ],
+    },
+    "move-group": {
+        description: "Move a tab group to a new position",
+        options: [
+            { flag: "--group <name>", desc: "Target group by title" },
+            { flag: "--group-id <id>", desc: "Target group by ID" },
+            { flag: "--before-tab <id>", desc: "Position before this tab" },
+            { flag: "--after-tab <id>", desc: "Position after this tab" },
+            { flag: "--before-group <name>", desc: "Position before this group" },
+            { flag: "--after-group <name>", desc: "Position after this group" },
+            { flag: "--window <id|active|last-focused>", desc: "Target window ID" },
+            { flag: "--new-window", desc: "Move to new window" },
+        ],
+    },
+    "merge-window": {
+        description: "Merge tabs from one window to another",
+        options: [
+            { flag: "--from <id>", desc: "Source window ID" },
+            { flag: "--to <id>", desc: "Destination window ID" },
+            { flag: "--close-source", desc: "Close source window after merge" },
+            { flag: "--confirm", desc: "Execute without prompting" },
+        ],
+    },
+    setup: {
+        description: "Configure tabctl connection",
+        options: [
+            { flag: "--browser edge|chrome", desc: "Browser type" },
+            { flag: "--extension-id <id>", desc: "Extension ID to connect to" },
+            { flag: "--node <path>", desc: "Path to Node.js executable" },
+            { flag: "--name <name>", desc: "Profile name (default: browser type)" },
+            { flag: "--user-data-dir <path>", desc: "Chrome/Edge user data directory for custom profiles" },
+        ],
+    },
+    policy: {
+        description: "Manage browser policies",
+        options: [
+            { flag: "--init", desc: "Initialize policy configuration" },
+        ],
+    },
+    archive: {
+        description: "Archive tabs to storage",
+        groups: ["scope"],
+    },
+    close: {
+        description: "Close tabs",
+        options: [
+            { flag: "--apply <analysisId>", desc: "Apply analysis results" },
+            { flag: "--tab <id>", desc: "Tab ID(s) to close", repeatable: true },
+            { flag: "--group <name>", desc: "Close tabs in group by title" },
+            { flag: "--group-id <id>", desc: "Close tabs in group by ID" },
+            { flag: "--ungrouped", desc: "Close ungrouped tabs" },
+            { flag: "--window <id|active|last-focused>", desc: "Target window ID" },
+            { flag: "--confirm", desc: "Execute without prompting" },
+            { flag: "--dry-run", desc: "Show what would be closed" },
+        ],
+    },
+    report: {
+        description: "Generate tab reports",
+        groups: ["scope", "pagination"],
+        options: [
+            { flag: "--format json|md|csv", desc: "Output format" },
+            { flag: "--out <path>", desc: "Output file path" },
+        ],
+    },
+    undo: {
+        description: "Undo a previous operation",
+        options: [
+            { flag: "<txid>", desc: "Transaction ID (positional)" },
+            { flag: "--txid <id>", desc: "Transaction ID" },
+            { flag: "--latest", desc: "Undo most recent transaction" },
+        ],
+    },
+    history: {
+        description: "Show operation history",
+        options: [
+            { flag: "--limit <n>", desc: "Maximum entries to show" },
+        ],
+    },
+    skill: {
+        description: "Show AI agent skill documentation",
+        options: [
+            { flag: "--agent <name>", desc: "Target agent(s)", repeatable: true },
+            { flag: "--global", desc: "Show global skill info" },
+        ],
+    },
+    "profile-list": {
+        description: "List configured profiles",
+    },
+    profile: {
+        description: "Alias for profile-list",
+        aliases: ["profile-list"],
+    },
+    "profile-show": {
+        description: "Show active profile details",
+    },
+    "profile-switch": {
+        description: "Switch the default profile",
+        options: [
+            { flag: "<name>", desc: "Profile name (positional)" },
+        ],
+    },
+    "profile-remove": {
+        description: "Remove a profile",
+        options: [
+            { flag: "<name>", desc: "Profile name (positional)" },
+        ],
+    },
+    version: {
+        description: "Show version information",
+    },
+    ping: {
+        description: "Test connection to browser extension",
+    },
+};
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Get all allowed flags for argument parsing validation.
+ */
+function getBooleanFlags() {
+    const flags = new Set();
+    GLOBAL_FLAGS.forEach((flag) => flags.add(flag));
+    const addFromOptions = (options) => {
+        for (const opt of options) {
+            if (!/^--[a-z-]+$/.test(opt.flag.trim())) {
+                continue;
+            }
+            const match = opt.flag.match(/^--([a-z-]+)/);
+            if (match) {
+                flags.add(match[1]);
+            }
+        }
+    };
+    for (const group of Object.values(exports.OPTION_GROUPS)) {
+        addFromOptions(group.options);
+    }
+    for (const cmd of Object.values(exports.COMMANDS)) {
+        if (cmd.options) {
+            addFromOptions(cmd.options);
+        }
+    }
+    return flags;
+}
+function getAllowedFlags() {
+    const flags = new Set();
+    for (const flag of getBooleanFlags()) {
+        flags.add(flag);
+    }
+    // Add value flags from option groups
+    for (const group of Object.values(exports.OPTION_GROUPS)) {
+        for (const opt of group.options) {
+            const match = opt.flag.match(/^--([a-z-]+)/);
+            if (match)
+                flags.add(match[1]);
+        }
+    }
+    // Add value flags from command options
+    for (const cmd of Object.values(exports.COMMANDS)) {
+        for (const opt of cmd.options || []) {
+            const match = opt.flag.match(/^--([a-z-]+)/);
+            if (match)
+                flags.add(match[1]);
+        }
+    }
+    flags.add("profile");
+    return flags;
+}
+function getCommandAllowedFlags(command) {
+    const flags = new Set(GLOBAL_FLAGS);
+    flags.add("profile");
+    const meta = exports.COMMANDS[command];
+    const addOptions = (options) => {
+        if (!options) {
+            return;
+        }
+        for (const opt of options) {
+            const match = opt.flag.match(/^--([a-z-]+)/);
+            if (match) {
+                flags.add(match[1]);
+            }
+        }
+    };
+    if (meta?.groups) {
+        for (const groupKey of meta.groups) {
+            addOptions(exports.OPTION_GROUPS[groupKey]?.options);
+        }
+    }
+    addOptions(meta?.options);
+    return flags;
+}
+/**
+ * Get the option groups for a command.
+ */
+function getCommandGroups(command) {
+    const meta = exports.COMMANDS[command];
+    return meta?.groups ? [...meta.groups] : [];
+}
+/**
+ * Get command-specific options (not from groups).
+ */
+function getCommandOptions(command) {
+    const meta = exports.COMMANDS[command];
+    return meta?.options ? [...meta.options] : [];
+}
+/**
+ * Check if a command supports a specific option group.
+ */
+function commandSupportsGroup(command, group) {
+    const meta = exports.COMMANDS[command];
+    return meta?.groups?.includes(group) ?? false;
+}

package/cli/lib/output.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printJson = printJson;
+exports.errorOut = errorOut;
+exports.setupStdoutErrorHandling = setupStdoutErrorHandling;
+exports.emitVersionWarnings = emitVersionWarnings;
+const version_1 = require("../../shared/version");
+const profiles_1 = require("../../shared/profiles");
+function printJson(payload, pretty = true) {
+    try {
+        const active = (0, profiles_1.getActiveProfile)();
+        if (active) {
+            payload.profile = active.name;
+            payload.browser = active.profile.browser;
+        }
+    }
+    catch {
+        // Don't let profile errors break output
+    }
+    const output = pretty ? JSON.stringify(payload, null, 2) : JSON.stringify(payload);
+    process.stdout.write(`${output}\n`);
+}
+function errorOut(message) {
+    const hints = {
+        "Unknown option: --format": "Use --json for JSON output. --format is only for report.",
+    };
+    const hint = hints[message];
+    if (hint) {
+        printJson({ ok: false, error: { message, hint } });
+    }
+    else {
+        printJson({ ok: false, error: { message } });
+    }
+    process.exit(1);
+    throw new Error(message);
+}
+function setupStdoutErrorHandling() {
+    process.stdout.on("error", (error) => {
+        if (error.code === "EPIPE") {
+            process.exit(0);
+        }
+        throw error;
+    });
+}
+function emitVersionWarnings(response, fallbackAction) {
+    const hostVersion = typeof response.version === "string" ? response.version : null;
+    if (hostVersion && hostVersion !== version_1.VERSION) {
+        process.stderr.write(`[tabctl] version mismatch: cli ${version_1.VERSION}, host ${hostVersion}\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) {
+        process.stderr.write(`[tabctl] version mismatch: host ${hostVersion}, extension ${extensionVersion}\n`);
+    }
+    if (extensionComponent && extensionComponent !== "extension") {
+        process.stderr.write(`[tabctl] unexpected extension component: ${extensionComponent}\n`);
+    }
+    const action = response.action || fallbackAction;
+    const extensionExpected = !["history", "version"].includes(action);
+    if (extensionExpected && !extensionVersion) {
+        process.stderr.write("[tabctl] extension version unavailable; reload the extension to validate version match\n");
+    }
+}