[issues/510] Add manual QA environments (Ubuntu Docker, Cursor) and BATS tests for QA scripts

.gitignore

@@ -32,18 +32,23 @@ packages/*/icon_large.png
 # Claude config
 .claude/settings.local.json
 
+# Docker image build stamp (local timestamp for rebuild detection)
+packages/rangelink-vscode-extension/.docker-image-stamp
+
 # Temp files created by integration test suites (cleaned up on normal exit; guard for CI kills)
 packages/rangelink-vscode-extension/__rl-test-*.ts
 packages/rangelink-vscode-extension/__rl-test-*.txt
 packages/rangelink-vscode-extension/.vscode/
 
 # Generated QA output (not committed)
 packages/rangelink-vscode-extension/qa/output/
+packages/rangelink-vscode-extension/qa/fixtures/workspace/cursor-qa-guide.txt
 
 # Folders where Claude Code is told to create and manage working documents
 .breadcrumbs/
 .claude-questions/
 .commit-msgs/
 .scratchpads/
+
 # Claude skill working directories
 .claude-work/

package.json

@@ -33,7 +33,9 @@
     "test:bats": "bats tests/shell/",
     "test:release": "pnpm --filter rangelink-vscode-extension test:release",
     "test:release:automated": "pnpm --filter rangelink-vscode-extension test:release:automated",
+    "test:release:cursor": "pnpm --filter rangelink-vscode-extension test:release:cursor",
     "test:release:grep": "pnpm --filter rangelink-vscode-extension test:release:grep",
+    "test:release:ubuntu": "pnpm --filter rangelink-vscode-extension test:release:ubuntu",
     "test:release:with-extensions": "pnpm --filter rangelink-vscode-extension test:release:with-extensions",
     "validate:qa-coverage:vscode-extension": "pnpm --filter rangelink-vscode-extension validate:qa-coverage",
     "verify:qa-scripts:vscode-extension": "pnpm --filter rangelink-vscode-extension verify:qa-scripts",

packages/rangelink-vscode-extension/.vscodeignore

@@ -18,10 +18,30 @@ tsconfig.json
 out/**
 .vscode/**
 .vscode-test/**
+.vscode-test.*.mjs
 node_modules/**
 coverage/**
 jest.config.*
 scripts/**
+**/jest.config.*
+esbuild.config.js
+
+# Documentation (only README ships)
+DEVELOPMENT.md
+TESTING.md
+PUBLISHING.md
+**/*.md
+
+# QA and test fixtures (large, not needed at runtime)
+qa/**
+test-fixtures/**
+
+# Docker
+docker/**
+.docker-image-stamp
+
+# Temp files from integration tests
+__rl-test-*
 
 # Repository files
 .git*
@@ -30,7 +50,13 @@ scripts/**
 
 # Keep these (automatic):
 # - package.json
-# - README.md
+# - README.md (let through despite **/*.md above)
 # - LICENSE
 # - icon.png
 # - dist/extension.js (bundled main entry)
+!readme.md
+!README.md
+!changelog.md
+!CHANGELOG.md
+!LICENSE*
+!icon*.png

packages/rangelink-vscode-extension/TESTING.md

@@ -15,6 +15,8 @@
 | Integration (CI-safe)    | `pnpm test:release:automated`                                 | CI / headless environments         | ✅                   |
 | Integration (extensions) | `pnpm test:release:with-extensions`                           | Tests needing real AI extensions   | ✅                   |
 | Integration (filter)     | `pnpm test:release:grep "<pattern>"`                          | Run specific TCs by ID or suite    | —                    |
+| Ubuntu manual QA         | `pnpm test:release:ubuntu`                                    | Manual QA of Ctrl+R keybindings    | —                    |
+| Cursor manual QA         | `pnpm test:release:cursor`                                    | Manual QA of Cursor IDE TCs        | —                    |
 | Prepare QA test plan     | `pnpm generate:qa-test-plan:vscode-extension`                 | Start of release cycle             | —                    |
 | Generate QA issue        | `pnpm generate:qa-issue:vscode-extension`                     | At the start of each release cycle | —                    |
 | Local QA checklist       | `pnpm generate:qa-issue:vscode-extension -- --local`          | Offline QA / before manual pass    | —                    |
@@ -233,6 +235,39 @@ Steps run in this order:
 
 ---
 
+## Manual QA Environments
+
+Some TCs are marked `automated: false` with a `non_automatable_reason` because they require a specific platform or IDE that cannot be tested in the standard extension host. The scripts below launch dedicated environments for these TCs.
+
+### Ubuntu (Ctrl+R keybindings)
+
+`platform-specific` TCs require a Linux environment where `Ctrl` (not `Cmd`) is the primary modifier key. The provided Docker container runs Ubuntu 24.04 with XFCE desktop, VS Code, and the extension's repo mounted at `/workspace`.
+
+**Prerequisites:** Docker Desktop (or Docker Engine) installed and running.
+
+```bash
+# Builds image on first run (or after Dockerfile changes: docker build -t rangelink-qa-ubuntu -f docker/Dockerfile.ubuntu .)
+pnpm test:release:ubuntu
+```
+
+The container opens a noVNC web desktop at http://localhost:6080/vnc.html. Open a terminal inside the desktop, run the extension tests, or manually verify `Ctrl+R` keybinding variants against the fixture workspace at `/workspace/packages/rangelink-vscode-extension/qa/fixtures/workspace`.
+
+The Dockerfile is at `docker/Dockerfile.ubuntu`. VS Code is installed from the Microsoft apt repo.
+
+### Cursor (IDE-specific tests)
+
+`ide-specific` TCs require Cursor IDE. These can only be verified manually — Cursor has no headless extension host mode for third-party extensions.
+
+```bash
+pnpm test:release:cursor
+```
+
+Builds the extension, installs it in Cursor, prints the Cursor-specific TCs to verify, then launches Cursor. Any workspace works — the fixture is just a convenience with a few file types ready.
+
+The `cursor` CLI must be on your PATH. If it's not, install it from Cursor's command palette: `Cmd+Shift+P` → "Install 'cursor' command".
+
+---
+
 ## QA Test Plan
 
 The QA test plan is a version-scoped YAML file that tracks both automated and manual test cases for a given release cycle.

packages/rangelink-vscode-extension/docker/Dockerfile.ubuntu

@@ -0,0 +1,48 @@
+FROM ubuntu:24.04
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV DISPLAY=:1
+
+# XFCE desktop + VNC + noVNC + VS Code prerequisites
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    xfce4 xfce4-terminal dbus-x11 \
+    tigervnc-standalone-server tigervnc-tools \
+    novnc websockify \
+    wget curl ca-certificates gnupg git \
+    libnss3 libatk-bridge2.0-0 libdrm2 libgbm1 libasound2t64 \
+    libx11-xcb1 libxcb-dri3-0 libxcomposite1 libxcursor1 libxdamage1 \
+    libxi6 libxtst6 libxrandr2 libxss1 \
+    && rm -rf /var/lib/apt/lists/*
+
+# VS Code from Microsoft apt repo
+RUN wget -qO- https://packages.microsoft.com/keys/microsoft.asc | gpg --dearmor -o /usr/share/keyrings/microsoft-archive-keyring.gpg \
+    && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/microsoft-archive-keyring.gpg] https://packages.microsoft.com/repos/code stable main" > /etc/apt/sources.list.d/vscode.list \
+    && apt-get update && apt-get install -y --no-install-recommends code \
+    && rm -rf /var/lib/apt/lists/*
+
+# Node.js 22
+RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
+    && apt-get install -y nodejs \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN corepack enable && corepack prepare pnpm@latest --activate
+
+# Wrapper: VS Code refuses to run as root without --no-sandbox + --user-data-dir.
+# argv.json isn't read early enough to satisfy the root-user guard.
+RUN mv /usr/bin/code /usr/bin/code-real && \
+    echo '#!/bin/sh' > /usr/bin/code && \
+    echo 'exec /usr/bin/code-real --no-sandbox --user-data-dir /root/.vscode-data "$@"' >> /usr/bin/code && \
+    chmod +x /usr/bin/code && \
+    mkdir -p /root/Desktop /root/.vnc && \
+    echo '#!/bin/sh' > /root/.vnc/xstartup && \
+    echo 'startxfce4' >> /root/.vnc/xstartup && \
+    chmod +x /root/.vnc/xstartup
+
+COPY docker/entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+WORKDIR /workspace
+
+EXPOSE 6080
+
+ENTRYPOINT ["/entrypoint.sh"]

packages/rangelink-vscode-extension/docker/entrypoint.sh

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+export CI=true
+
+# Generate Ubuntu TC checklist on the desktop
+echo "==> Extracting Ubuntu TCs from QA YAML..."
+
+TC_FILE="/root/Desktop/qa-ubuntu-tests.txt"
+
+node /workspace/packages/rangelink-vscode-extension/scripts/resolve-qa-labels.js --json 2>/dev/null | node -e "
+  const d = JSON.parse(require('fs').readFileSync(0, 'utf8'));
+  const tcs = d.ubuntu_tcs;
+  const lines = [];
+  lines.push('Ubuntu QA — TCs to verify');
+  lines.push('=============================');
+  lines.push('');
+  lines.push('Copy-paste the commands below into this VS Code terminal.');
+  lines.push('');
+  if (!tcs.length) {
+    lines.push('No Ubuntu-specific TCs found.');
+  } else {
+    for (const tc of tcs) {
+      const status = tc.automated === false ? 'manual' : tc.automated;
+      const reason = tc.nonAutomatableReason ? ' (' + tc.nonAutomatableReason + ')' : '';
+      lines.push('[' + status + reason + '] ' + tc.id);
+      lines.push('  ' + tc.scenario);
+      if (tc.automated !== false) {
+        lines.push('  $ pnpm test:release:grep ' + tc.id);
+      }
+      lines.push('');
+    }
+  }
+  lines.push('');
+  lines.push('Fixture workspace: /workspace/packages/rangelink-vscode-extension/qa/fixtures/workspace');
+  require('fs').writeFileSync('$TC_FILE', lines.join('\n'));
+"
+
+echo "==> Wrote $TC_FILE"
+
+# First run: populate the container-native node_modules volume (Linux binaries for esbuild etc.)
+if [[ ! -d /workspace/node_modules/.pnpm ]]; then
+  echo "==> Installing dependencies (first run, cached on subsequent runs)..."
+  cd /workspace
+  pnpm install 2>&1
+  echo "==> Dependencies ready"
+fi
+
+# Build and package the extension (Linux-native esbuild from the Docker volume).
+# vsce triggers vscode:prepublish which runs tests — skip that by calling vsce directly.
+echo "==> Building extension..."
+cd /workspace
+pnpm --filter rangelink-vscode-extension compile 2>&1
+cd /workspace/packages/rangelink-vscode-extension
+../../scripts/sync-assets.sh 2>&1
+npx vsce package --no-dependencies 2>&1
+VSIX=$(ls /workspace/packages/rangelink-vscode-extension/rangelink-vscode-extension-*.vsix 2>/dev/null | head -1)
+if [[ -z "$VSIX" ]]; then
+  echo "ERROR: .vsix not found after build — extension will not be installed" >&2
+  exit 1
+fi
+
+# Start VNC server on :1 — no auth for local Docker use
+tigervncserver :1 -geometry 1680x1050 -depth 24 -localhost yes -SecurityTypes None
+
+# Install the extension into VS Code (needs X running)
+sleep 2
+if [[ -n "$VSIX" ]]; then
+  echo "==> Installing extension: $VSIX"
+  if ! DISPLAY=:1 code --install-extension "$VSIX" 2>&1; then
+    echo "ERROR: Failed to install extension: $VSIX" >&2
+    exit 1
+  fi
+fi
+
+# Launch VS Code with fixture workspace
+DISPLAY=:1 code "/workspace/packages/rangelink-vscode-extension/qa/fixtures/workspace" &
+
+# Bridge VNC (5901) to WebSocket (6080)
+websockify --web /usr/share/novnc 0.0.0.0:6080 localhost:5901 &
+
+echo ""
+echo "============================================="
+echo "  Ubuntu QA Desktop ready"
+echo "  Open: http://localhost:6080/vnc.html"
+echo "============================================="
+echo ""
+
+wait

packages/rangelink-vscode-extension/package.json

@@ -52,8 +52,10 @@
     "test:fast": "jest --coverage --testPathIgnorePatterns '<rootDir>/src/__integration-tests__/' '\\.integration\\.test\\.ts$'",
     "test:release": "./scripts/run-integration-tests.sh",
     "test:release:automated": "./scripts/run-integration-tests.sh --automated --exclude-label requires-extensions --exclude-label cursor",
+    "test:release:cursor": "./scripts/qa-cursor.sh",
     "test:release:grep": "./scripts/run-integration-tests.sh --grep",
     "test:release:prepare": "pnpm compile && rm -rf out/__integration-tests__ && tsc -p tsconfig.integration.json && node scripts/setup-integration-test-settings.js",
+    "test:release:ubuntu": "./scripts/qa-ubuntu-docker.sh run",
     "test:release:with-extensions": "./scripts/run-integration-tests.sh --with-extensions",
     "test:watch": "jest --watch",
     "validate:qa-coverage": "./scripts/validate-qa-coverage.sh",