Onboarding: nasa/openmct

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/nasa/openmct shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

Verdict

GO — Healthy across the board

• Last commit today
• 10 active contributors
• Distributed ownership (top contributor 22% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

Verify before trusting

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live nasa/openmct repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/nasa/openmct.

What it runs against: a local clone of nasa/openmct — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in nasa/openmct | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>nasa/openmct</code></summary>

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of nasa/openmct. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/nasa/openmct.git
#   cd openmct
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of nasa/openmct and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "nasa/openmct(\\.git)?\\b" \\
  && ok "origin remote is nasa/openmct" \\
  || miss "origin remote is not nasa/openmct (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "e2e/index.js" \\
  && ok "e2e/index.js" \\
  || miss "missing critical file: e2e/index.js"
test -f "e2e/baseFixtures.js" \\
  && ok "e2e/baseFixtures.js" \\
  || miss "missing critical file: e2e/baseFixtures.js"
test -f "e2e/appActions.js" \\
  && ok "e2e/appActions.js" \\
  || miss "missing critical file: e2e/appActions.js"
test -f ".webpack/webpack.common.mjs" \\
  && ok ".webpack/webpack.common.mjs" \\
  || miss "missing critical file: .webpack/webpack.common.mjs"
test -f ".github/workflows/e2e-full.yml" \\
  && ok ".github/workflows/e2e-full.yml" \\
  || miss "missing critical file: .github/workflows/e2e-full.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/nasa/openmct"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

</details>

TL;DR

Open MCT is a web-based mission control framework built in Vue and JavaScript that enables real-time visualization and analysis of telemetry data from spacecraft and remote systems. It's an extensible, open-source platform used by NASA for spacecraft mission operations, rover planning, and any telemetry-driven system monitoring. Core capability: a plugin-based dashboard system that renders real-time data streams into interactive displays, plots, and operator interfaces. Traditional monorepo structure: main application bundle built with Webpack 5 (.webpack/ contains common/dev/prod/coverage configs), Vue components comprise 1.7M lines, JavaScript core is 3.8M lines, SCSS styling at 507K lines. Plugin system allows extensibility without forking core. E2E test framework in ./e2e/ uses Playwright with Percy integration for visual regression.

Who it's for

NASA mission operators, spacecraft flight controllers, and systems engineers who need to monitor live telemetry and plan operations; also engineers building custom mission control applications who want a proven framework instead of building from scratch.

Maturity & risk

Highly mature and production-ready. The project has 3.8M lines of JavaScript across 60+ key files, comprehensive GitHub Actions CI/CD (CodeQL, e2e-full, e2e-perf workflows), Percy.io visual regression testing, and is actively developed at NASA's Ames Research Center. Current version 4.1.0-next indicates active development with frequent releases.

Low to moderate risk. Code is well-structured with linting (.eslintrc.cjs), spell-checking (.cspell.json), and strict testing protocols (e2e/, codecov.yml). Main risk: monolithic Vue/Webpack architecture may require deep knowledge to modify core plugins. Dependency surface is large (~1.7M lines of Vue code), but Dependabot automation (.github/dependabot.yml) manages updates. No obvious single-maintainer bottleneck given NASA Ames backing.

Active areas of work

Active development on version 4.1.0-next. CI/CD is continuously running (e2e-full, e2e-perf, pr-platform workflows). Visual regression testing via Percy.io is integrated. npm prerelease workflow suggests regular incremental releases. Dependabot configuration indicates proactive dependency updates.

Get running

git clone https://github.com/nasa/openmct.git
cd openmct
nvm install  # optional, ensures correct Node version
npm install
npm start
# Open MCT runs at http://localhost:8080/

Daily commands:

npm start
# Starts dev server on http://localhost:8080/ with hot reload
npm test  # runs e2e tests via Playwright (in e2e/)
npm run test:visual  # runs Percy visual regression tests

Map of the codebase

• e2e/index.js — Primary entry point for the e2e test framework; all contributors must understand the fixture and helper export structure.
• e2e/baseFixtures.js — Defines core Playwright fixtures (page, context, browser) and initialization patterns that all e2e tests depend on.
• e2e/appActions.js — Centralizes common application interactions and navigation patterns used across all e2e test suites.
• .webpack/webpack.common.mjs — Shared webpack configuration for build tooling; changes here affect all development and production builds.
• .github/workflows/e2e-full.yml — Defines the primary CI/CD pipeline for running comprehensive e2e tests; critical for understanding test execution flow.
• e2e/playwright-ci.config.js — Playwright configuration for CI environments; essential for understanding test execution settings and browser coverage.
• TESTING.md — Official testing documentation covering test structure, conventions, and best practices for all contributors.

How to make changes

Add a new e2e test for a feature

1. Create a new test file in the appropriate subdirectory under e2e/tests (or root e2e directory based on feature type) (TESTING.md)
2. Import fixtures and helpers from e2e/index.js and e2e/appActions.js (e2e/index.js)
3. Use baseFixtures to access page, context, and initialized application state (e2e/baseFixtures.js)
4. Implement test cases using Playwright test() with fixture destructuring (e2e/appActions.js)

Add a new test initialization helper for a plugin or feature

1. Create a new file in e2e/helper/ following the naming pattern addInit*.js (e2e/helper/addInitExampleUser.js)
2. Export a function that receives the browser fixture and programmatically initializes the feature (e2e/helper/addInitFaultManagementPlugin.js)
3. Export the helper from e2e/index.js to make it available to all tests (e2e/index.js)
4. Use the helper in test files by importing from the e2e package and calling in test setup (e2e/appActions.js)

Add a new Playwright configuration for a specific test environment

1. Create a new playwright-*.config.js file in the e2e directory (e.g., playwright-custom.config.js) (e2e/playwright-ci.config.js)
2. Use use: { ...devices['Chromium'] } or other device presets to define browser/device targeting (e2e/playwright-mobile.config.js)
3. Configure webServer pointing to the application (usually localhost:8080 for development) (e2e/playwright-performance-prod.config.js)
4. Add corresponding npm script to e2e/package.json (e.g., test:custom: npx playwright test -c playwright-custom.config.js) (e2e/package.json)

Enhance webpack build configuration for a new asset type or feature

1. Evaluate if the change applies to all environments (common), specific to dev, or production-specific (.webpack/webpack.common.mjs)
2. Add or modify loader rules in the appropriate config file (e.g., for new file types add to module.rules) (.webpack/webpack.common.mjs)
3. If environment-specific, override or extend in webpack.dev.mjs, webpack.prod.mjs, or webpack.coverage.mjs (.webpack/webpack.prod.mjs)
4. Test the build with npm run build and verify output bundle contains expected assets (package.json)

Why these technologies

• Playwright — Cross-browser automation framework chosen for reliable, maintainable e2e testing across desktop and mobile devices with excellent CI/CD integration.
• Webpack — Module bundler providing code splitting, asset optimization, and development server capabilities essential for the mission control web application.
• Percy.io — Visual regression testing platform ensures UI consistency across releases and prevents accidental visual regressions.
• GitHub Actions — Native CI/CD solution for automated testing, security scanning (CodeQL), and release workflows integrated with the repository.
• ESLint + Prettier — Code quality and formatting consistency tools enforce team standards and reduce cognitive load during code review.

Trade-offs already made

• Separate e2e package with its own package.json and dependencies
  • Why:
  • Consequence: undefined

Traps & gotchas

1. Node version must match .nvmrc (version 18+ likely); nvm install is not optional for some systems. 2. npm start requires no conflicting port 8080 process. 3. Tests in e2e/ require a running MCT instance; CI handles this via workflow setup. 4. Vue 3 composition API is the pattern; older Options API examples in docs may be outdated. 5. Plugin system requires understanding of the registration/dependency model—see examples in src/plugins/. 6. SCSS is globally scoped; naming conflicts possible if adding styles without BEM conventions.

Architecture

Concepts to learn

• Plugin Architecture / Dependency Injection — MCT's entire extensibility model relies on runtime plugin registration; understanding this is required to add domain-specific features without forking
• Vue 3 Composition API — MCT uses Composition API for reactive state management in components; this is the primary pattern for UI changes
• Webpack Module Federation — Webpack config hints at possible micro-frontend patterns; understanding module resolution is critical for plugin bundling
• Time-Series Telemetry Decimation — Mission control systems must handle high-frequency data streams (100Hz+); MCT likely uses decimation/downsampling strategies visible in plotting code
• Playwright Visual Regression (Percy.io) — Percy integration in CI/CD means UI changes trigger snapshot comparisons; critical to understand before modifying styles or layouts
• Real-Time Data Binding & Reactivity — MCT's core value is live telemetry updates; Vue reactivity under the hood but MCT likely wraps this with telemetry-specific adapters (see dataSources/)
• SCSS + BEM (Block Element Modifier) Naming — 507K SCSS lines require strict naming to avoid cascade conflicts; MCT likely follows BEM for scoped component styles

Related repos

• grafana/grafana — Similar real-time telemetry visualization platform; Grafana is alternative for dashboarding but MCT is NASA-optimized for mission control workflows
• apache/superset — Open-source data visualization framework; overlaps in dashboard/charting but MCT is higher-frequency telemetry focused
• nasa/openmct-plugins — Official NASA-maintained plugins extending MCT (hypothetical sibling repo); check GitHub org for extension examples
• plotly/plotly.js — Real-time plotting library often integrated with MCT for time-series telemetry charting

PR ideas

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add E2E test coverage for visual regression in CI/CD pipeline

The repo uses Percy.io for visual regression testing (shown in README badge and .percy.ci.yml/.percy.nightly.yml configs), but there's no documented workflow showing how to run visual tests locally or integrate them into PR validation. The e2e/README.md exists but likely doesn't cover the Percy integration workflow. This would help contributors understand the visual testing process and ensure visual regressions are caught before merging.

• [ ] Review e2e/README.md and identify missing Percy setup instructions
• [ ] Document how to run visual tests locally using 'npm run test:visual' from e2e/package.json
• [ ] Add examples of expected Percy integration in e2e/README.md with references to .percy.ci.yml and .percy.nightly.yml
• [ ] Document how contributors should handle visual test failures in PRs

Create E2E test helper for accessibility (a11y) validation

The repo includes @axe-core/playwright in e2e/package.json devDependencies, indicating accessibility testing capability, but there's no visible helper module in e2e/helper/ for accessibility assertions. Adding a standardized a11y helper (similar to addInitExampleFaultProvider.js pattern) would enable contributors to easily add accessibility tests to new features and ensure WCAG compliance across the mission control framework.

• [ ] Create e2e/helper/addInitA11yValidator.js that wraps @axe-core/playwright for consistent accessibility scanning
• [ ] Add utility functions for common a11y checks (keyboard navigation, ARIA labels, color contrast)
• [ ] Document usage in e2e/README.md with example test cases
• [ ] Add a sample a11y test in e2e/ that demonstrates the helper in action

Document E2E environment setup and troubleshooting guide

The e2e/ directory has complex dependencies (.nvmrc specifies Node version, .percy.ci.yml and .percy.nightly.yml exist, multiple helper files reference various initialization strategies), but the e2e/README.md likely lacks detailed setup instructions, environment variable configuration, and troubleshooting for common issues. New contributors often struggle with E2E setup; a comprehensive guide would reduce onboarding friction.

• [ ] Update e2e/README.md with prerequisites section (Node version from .nvmrc, Playwright system dependencies)
• [ ] Document required environment variables (Percy tokens, test URLs, optional dependencies like fsevents)
• [ ] Add troubleshooting section for common failures (Playwright browser installation, Percy authentication, database connectivity if using e2e-couchdb.yml)
• [ ] Link to relevant GitHub workflow files (e2e-full.yml, e2e-perf.yml) to show CI usage patterns

Good first issues

• Add missing unit test coverage for utility functions in src/utils/; current codecov badge suggests gaps under 90% threshold. Pick an untested utility file and write Jest specs.
• Documentation is split between API.md, docs/src/guide/, and comments; add JSDoc comments to exported plugin APIs in src/plugins/ to improve IDE autocomplete and reduce confusion for new developers.
• SCSS has 507K lines but no Stylelint config in root; add .stylelintrc to enforce BEM naming and prevent cascade bugs. Start with linting existing SCSS in src/styles/.

Top contributors

• @akhenry — 22 commits
• @shefalijoshi — 21 commits
• @jvigliotta — 13 commits
• @dependabot[bot] — 11 commits
• @davetsay — 10 commits

Recent commits

• 9a855cf — add optional dependency to build on linux (#8306) (davetsay)
• e5120e9 — Update dependencies and enable additional npm options (#8298) (akhenry)
• 4935d5e — Feature/historical conditions (#8148) (jvigliotta)
• 09ad12b — Modified test to wait for expected telemetry conditions (#8292) (akhenry)
• bfbd001 — Test for out of order data plotting (#8285) (shefalijoshi)
• e7e53fe — Condition set staleness (#8289) (akhenry)
• 4d28dfd — Better tick width calculation, step size and styles adjustment (#8273) (shefalijoshi)
• 46ab69f — Fix plot rendering when real-time data is not in chronological order (#8274) (shefalijoshi)
• e0899f1 — Adds new default sort option for fault management view (#8275) (shefalijoshi)
• 98a5b22 — Derived Telemetry Prototype (#7815) (scottbell)

Security observations

The Open MCT e2e testing framework has a generally solid security posture with evidence of security practices (SECURITY.md, CodeQL integration, dependency reviews). However, several dependencies require updates to address potential vulnerabilities. The main concerns are: (1) Outdated Playwright and optional dependencies that may contain known vulnerabilities, (2) Lack of evidence for explicit security header configuration in the web framework, and (3) E2E test credential management practices. The codebase benefits from NASA's security review process and automated vulnerability scanning via CodeQL, but dependency management should be more aggressive in applying security patches. No evidence of hardcoded secrets, injection vulnerabilities, or severe misconfigurations was found in the provided file structure.

• Medium · Outdated Playwright Dependency — e2e/package.json - @playwright/test: 1.57.0. The e2e test suite uses @playwright/test version 1.57.0, which may contain known vulnerabilities. Playwright has regular security updates, and using an older version could expose the test infrastructure to known exploits. Fix: Update to the latest stable version of @playwright/test. Run 'npm audit' and 'npm update' to identify and patch vulnerable dependencies.
• Medium · Optional Dependency with Known Vulnerabilities — e2e/package.json - fsevents: 2.3.2. The 'fsevents' package (2.3.2) is included as an optionalDependency. While optional dependencies don't block installation, outdated versions may contain security vulnerabilities. fsevents 2.3.2 is several versions behind current releases. Fix: Update fsevents to the latest version (currently 2.4.x or higher). Consider evaluating whether this optional dependency is necessary for the project.
• Low · Percy CLI and Playwright Integration Risk — e2e/package.json - @percy/cli: 1.27.4, @percy/playwright: 1.0.4. @percy/cli (1.27.4) and @percy/playwright (1.0.4) are pinned to specific versions. While visual regression testing is important, outdated versions of these dependencies could contain vulnerabilities or compatibility issues. Fix: Regularly update Percy dependencies to their latest versions. Add dependency monitoring to CI/CD pipeline to detect security updates.
• Low · Missing Package Lock Verification — e2e/package-lock.json. The presence of package-lock.json suggests npm dependency pinning, which is good for reproducibility. However, without evidence of lock file verification in CI/CD, there's a risk of supply chain attacks through dependency manipulation. Fix: Ensure CI/CD pipeline verifies package-lock.json integrity. Consider implementing npm audit in the build pipeline and using 'npm ci' instead of 'npm install'.
• Low · Lack of Explicit Security Headers Configuration — .webpack/ configuration directory. The webpack configuration files present in .webpack/ directory don't show explicit security header configuration in the visible file structure. This is important for a web-based mission control framework. Fix: Ensure webpack output and/or express/server configuration includes security headers (Content-Security-Policy, X-Frame-Options, X-Content-Type-Options, etc.). Review the main webpack config for security configurations.
• Low · E2E Test Credentials Management — e2e/helper/ directory - user and authentication related helpers. The e2e test suite includes helpers for various test scenarios (e.g., addInitExampleUser.js, addInitRestrictedNotebook.js). Test credentials and example data must be properly managed to avoid exposure of sensitive patterns. Fix: Ensure all test credentials and example data are properly isolated from production. Use environment variables for test credentials. Never commit real credentials or sensitive test data to the repository.

LLM-derived; treat as a starting point, not a security audit.

Where to read next

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

---

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.