Add mrd-viz extension and backend (initial review pass)

.devcontainer/mrd-viz/devcontainer.json

@@ -0,0 +1,42 @@
+{
+  // Lightweight, extension-specific dev container for MRD Viz (Scenario B).
+  // The other config, ".devcontainer/devcontainer.json" ("mrd"), is the full
+  // repo toolchain (conda + MATLAB + C++) and is a poor fit for just viewing
+  // .mrd files, so this pins Python 3.12 (matching the backend) and stays minimal.
+  "name": "MRD Viz extension",
+  "image": "mcr.microsoft.com/devcontainers/python:3.12-bookworm",
+  "features": {
+    "ghcr.io/devcontainers/features/azure-cli:1": {}
+  },
+  // postCreate installs Node.js (from nodejs.org), plus the `just` and `azcopy`
+  // CLIs. Node is installed here rather than via the devcontainer `node` feature
+  // because that feature pulls pnpm from the public npm registry at build time,
+  // which is blocked on some corporate networks. Project provisioning (backend +
+  // the MRD Viz extension) is a one-time `just container-setup` you run afterwards.
+  "postCreateCommand": "bash .devcontainer/mrd-viz/postCreate.sh",
+  // Ordered package-index candidates (Microsoft-internal mirror first, public
+  // registry as fallback). `.devcontainer/mrd-viz/select-pkg-index.sh` picks the
+  // first reachable one and exports PIP_INDEX_URL / npm_config_registry, so the
+  // internal feed lives here — not in a hidden dotfile — and external contributors
+  // fall back to the public registry automatically. Override either list, or set
+  // PIP_INDEX_URL / npm_config_registry directly, to force a specific feed.
+  "remoteEnv": {
+    "MRD_PIP_INDEX_URLS": "https://packagefeedproxy.microsoft.io/pypi/simple/ https://pypi.org/simple/",
+    "MRD_NPM_REGISTRIES": "https://packagefeedproxy.microsoft.io/npm/ https://registry.npmjs.org/"
+  },
+  "customizations": {
+    "vscode": {
+      "settings": {
+        // `just container-setup` creates this venv; pointing the extension at it
+        // explicitly (via the developer override) avoids the installed-VSIX discovery
+        // gap and the python/python3 PATH ambiguity. backendPath is machine-scoped, so
+        // this applies as a container remote setting and never leaks back to the host.
+        "mrdViz.backendPath": "/home/vscode/.venvs/mrd-viz/bin/python",
+        "python.defaultInterpreterPath": "/home/vscode/.venvs/mrd-viz/bin/python"
+      },
+      "extensions": [
+        "ms-python.python"
+      ]
+    }
+  }
+}

.devcontainer/mrd-viz/postCreate.sh

@@ -0,0 +1,104 @@
+#!/usr/bin/env bash
+# postCreate for the MRD Viz dev container.
+# Installs the generic CLI tools the workflow needs, then best-effort provisions
+# the backend virtualenv so the container is turnkey for a first run. Building and
+# installing the extension VSIX stays a one-time `just mrd-viz-container-setup`
+# step (it needs the npm registry, which is what fails on restricted networks).
+set -euo pipefail
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+
+# Resolve the container architecture so the Node and azcopy downloads match it.
+arch="$(uname -m)"
+case "$arch" in
+	x86_64)        node_arch="x64";   azcopy_url="https://aka.ms/downloadazcopy-v10-linux";       azcopy_glob="azcopy_linux_amd64_*" ;;
+	aarch64|arm64) node_arch="arm64"; azcopy_url="https://aka.ms/downloadazcopy-v10-linux-arm64"; azcopy_glob="azcopy_linux_arm64_*" ;;
+	*) echo ">> Unsupported architecture: $arch" >&2; exit 1 ;;
+esac
+
+# Node.js (from nodejs.org, which is reachable even where the public npm registry
+# is blocked). Installed here instead of the devcontainer `node` feature, which
+# pulls pnpm from the public npm registry at build time. Node bundles npm.
+if ! command -v node >/dev/null 2>&1; then
+	echo ">> Installing Node.js"
+	node_version="v24.18.0"
+	curl -fsSL "https://nodejs.org/dist/${node_version}/node-${node_version}-linux-${node_arch}.tar.xz" -o /tmp/node.tar.xz
+	sudo tar -xJf /tmp/node.tar.xz -C /usr/local --strip-components=1
+	rm -f /tmp/node.tar.xz
+fi
+
+# just: task runner used by `just container-setup`.
+if ! command -v just >/dev/null 2>&1; then
+	echo ">> Installing just"
+	curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh -o /tmp/just-install.sh
+	sudo bash /tmp/just-install.sh --to /usr/local/bin
+	rm -f /tmp/just-install.sh
+fi
+
+# azcopy: used to pull .mrd data from Azure storage.
+if ! command -v azcopy >/dev/null 2>&1; then
+	echo ">> Installing azcopy"
+	curl -sSL "$azcopy_url" -o /tmp/azcopy.tar.gz
+	tar -xzf /tmp/azcopy.tar.gz -C /tmp
+	sudo cp /tmp/${azcopy_glob}/azcopy /usr/local/bin/azcopy
+	sudo chmod +x /usr/local/bin/azcopy
+	rm -rf /tmp/azcopy.tar.gz /tmp/${azcopy_glob}
+fi
+
+# Backend provisioning (best-effort, non-fatal). The dev container points
+# mrdViz.backendPath at this venv, so create it and install the mrd_viz backend
+# now for a turnkey first run. This only needs PyPI (mrd-python/numpy/pillow),
+# which is typically reachable even where the npm registry is blocked; the guard
+# keeps a failure from aborting container creation and falls back to the manual
+# step in the banner below.
+venv="$HOME/.venvs/mrd-viz"
+backend_dir="$repo_root/mrd-viz/backend"
+backend_ready=0
+if [ -x "$venv/bin/python" ] && "$venv/bin/python" -m mrd_viz.cli --version >/dev/null 2>&1; then
+	backend_ready=1
+elif [ -d "$backend_dir" ]; then
+	# Point pip at the first reachable index (internal mirror, else public PyPI).
+	# shellcheck source=./select-pkg-index.sh
+	source "$repo_root/.devcontainer/mrd-viz/select-pkg-index.sh"
+	echo ">> Provisioning MRD Viz backend virtualenv: $venv"
+	if python3 -m venv "$venv" \
+		&& "$venv/bin/python" -m pip install --upgrade pip \
+		&& "$venv/bin/python" -m pip install -e "$backend_dir"; then
+		backend_ready=1
+	else
+		echo ">> WARNING: automatic backend setup failed (often a blocked/restricted network)." >&2
+		rm -rf "$venv"
+	fi
+fi
+
+if [ "$backend_ready" -eq 1 ]; then
+	cat <<'EOF'
+
+============================================================
+ MRD Viz dev container is ready. Backend is installed and
+ mrdViz.backendPath points at ~/.venvs/mrd-viz, so opening a
+ .mrd file should work out of the box.
+
+ If the MRD Viz extension itself is not installed yet, run:
+     just mrd-viz-container-setup
+ (builds + installs the extension VSIX; needs npm registry
+  access - see mrd-viz/docs/DEVCONTAINER.md for restricted
+  networks).
+============================================================
+EOF
+else
+	cat <<'EOF'
+
+============================================================
+ MRD Viz dev container is ready, but automatic backend setup
+ did not complete (often a blocked/restricted network).
+
+ Finish setup by running:
+     just mrd-viz-container-setup
+
+ That creates the backend virtualenv, installs mrd_viz, and
+ builds + installs the MRD Viz extension in this window.
+ See mrd-viz/docs/DEVCONTAINER.md for restricted-network tips.
+============================================================
+EOF
+fi

.devcontainer/mrd-viz/select-pkg-index.sh

@@ -0,0 +1,59 @@
+# shellcheck shell=bash
+# Pick the first reachable package index/registry from an ordered, space-separated
+# candidate list and export the variables pip and npm read natively
+# (PIP_INDEX_URL, npm_config_registry). Source this before running pip/npm.
+#
+# Candidate ladder (same idea as the backend resolver): the Microsoft-internal
+# mirror is tried first, the public registry second. Microsoft-internal devs on a
+# restricted network get the mirror; external devs fall back to the public
+# registry automatically. The lists come from devcontainer.json (remoteEnv):
+#   MRD_PIP_INDEX_URLS   e.g. "https://internal/pypi/simple/ https://pypi.org/simple/"
+#   MRD_NPM_REGISTRIES   e.g. "https://internal/npm/ https://registry.npmjs.org/"
+# When unset (running outside the dev container), they default to public only.
+#
+# Override the final choice by exporting PIP_INDEX_URL / npm_config_registry
+# yourself before sourcing; an explicit value is always respected.
+
+: "${MRD_PIP_INDEX_URLS:=https://pypi.org/simple/}"
+: "${MRD_NPM_REGISTRIES:=https://registry.npmjs.org/}"
+
+# Echo the first URL in $1 (space-separated) whose host completes an HTTPS request
+# within a short timeout. Any HTTP response (even 404) counts as reachable; only a
+# TLS handshake / connection failure — the restricted-network symptom — is a miss.
+_mrd_first_reachable() {
+	local url
+	for url in $1; do
+		if curl -sS --max-time 6 -o /dev/null -I "$url" >/dev/null 2>&1; then
+			printf '%s' "$url"
+			return 0
+		fi
+	done
+	return 1
+}
+
+# pip
+if [ -n "${PIP_INDEX_URL:-}" ]; then
+	echo ">> Using PyPI index (from PIP_INDEX_URL): $PIP_INDEX_URL"
+elif _pip_url="$(_mrd_first_reachable "$MRD_PIP_INDEX_URLS")"; then
+	export PIP_INDEX_URL="$_pip_url"
+	echo ">> Using PyPI index: $PIP_INDEX_URL"
+else
+	echo ">> WARNING: no reachable PyPI index among: $MRD_PIP_INDEX_URLS" >&2
+	echo ">> If you are on a restricted/corporate network, run this and retry:" >&2
+	echo ">>     export PIP_INDEX_URL=\"${MRD_PIP_INDEX_URLS%% *}\"" >&2
+fi
+
+# npm
+if [ -n "${npm_config_registry:-}" ]; then
+	echo ">> Using npm registry (from npm_config_registry): $npm_config_registry"
+elif _npm_url="$(_mrd_first_reachable "$MRD_NPM_REGISTRIES")"; then
+	export npm_config_registry="$_npm_url"
+	echo ">> Using npm registry: $npm_config_registry"
+else
+	echo ">> WARNING: no reachable npm registry among: $MRD_NPM_REGISTRIES" >&2
+	echo ">> If you are on a restricted/corporate network, run this and retry:" >&2
+	echo ">>     export npm_config_registry=\"${MRD_NPM_REGISTRIES%% *}\"" >&2
+fi
+
+unset -f _mrd_first_reachable
+unset _pip_url _npm_url

.gitattributes

@@ -0,0 +1,4 @@
+# Shell scripts and justfiles run inside Linux dev containers; keep them LF
+# so bash/just don't choke on CR characters even when edited on Windows.
+*.sh text eol=lf
+justfile text eol=lf

.github/workflows/mrd_viz.yml

@@ -0,0 +1,42 @@
+name: MRD Viz
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - "mrd-viz/**"
+      - ".github/workflows/mrd_viz.yml"
+  push:
+    branches: [main]
+    paths:
+      - "mrd-viz/**"
+      - ".github/workflows/mrd_viz.yml"
+  workflow_dispatch:
+
+jobs:
+  ci:
+    name: Backend and Extension Checks
+    runs-on: ubuntu-24.04
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Set up Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: mrd-viz/extension/mrd-viz/package-lock.json
+
+      - name: Set up just
+        uses: extractions/setup-just@v4
+
+      - name: Run MRD Viz CI
+        working-directory: mrd-viz
+        run: just ci