OUI_XFAB documentation

Dependency Handbook

Authority and maintenance

This handbook owns the purpose, maintenance owner, declared range, resolved version, compatibility constraints, and audit policy/status for every direct package in package.json.

• package.json is authoritative for direct dependency ranges and supported runtime engines.
• package-lock.json is authoritative for exact direct versions and the complete resolved transitive graph.
• This handbook documents direct packages only. Manually duplicating the transitive graph here is prohibited because it would drift from the lockfile.
• npm run validate:dependencies checks that every direct dependency appears exactly once and that its declared and resolved versions match the package files.

Update the relevant row whenever package.json or package-lock.json changes. The owner column identifies the repository area responsible for compatibility review.

Runtime baseline

• Node.js: >=24.15.0 <25, required by the jsdom 30 test runtime while preserving Node 24 LTS.
• npm: version 11 is the validated package-manager generation; the declared minimum remains >=8.0.0.
• Install reproducibly with npm ci.
• Install the access service's separate production graph with npm ci --prefix services/oui-access-service.
• Keep @types/node on the Node 24 line while Node 24 LTS is the deployment runtime.

Runtime dependencies

Development dependencies

Transitive dependency inspection

The independently deployed services/oui-access-service package deliberately owns mssql ^12.7.0 (resolved 12.7.0) for parameterized SQL Server access. Its package-lock.json is authoritative for that service graph. mssql supports Node >=18.19.0, including the repository's required Node 24 line. The browser application does not import this dependency.

Do not copy the transitive package list into documentation. Inspect the authoritative lockfile graph with:

npm ls --all
npm explain <package>
npm outdated
npm audit
npm audit --omit=dev

Use npm ci to prove that a lockfile change installs reproducibly before committing it.

Upgrade cohorts and compatibility constraints

• Phase 1 has a dedicated compatible dependency checkpoint and provides this machine-validated handbook.
• Phase 2 installed jsdom 30.0.0 and Pinia 4.0.2 as separate, independently verified cohorts.
• Vuetify 4.1.x is the sole UI component library and reuses @mdi/font 7.4.47.
• Eleventy and Wrangler are development-only documentation tooling; they do not enter the browser application bundle. Documentation deploys use the dedicated oui-xfab-docs Cloudflare Pages project.
• PrimeVue, PrimeIcons, and PrimeUIX Themes were removed after the UI migration; they are no longer direct or resolved dependencies of the browser application.
• Keep every interaction surface coherent: component, test, and style ownership move together.
• Node 26 and TypeScript 7 are deferred. TypeScript 6 uses the canonical typescript package so the future TypeScript 7 upgrade remains a direct major-version change.
• Do not use forced overrides or breaking downgrades to make audit output disappear.

Audit status

There are currently no accepted audit exceptions. Both npm audit --omit=dev and the full npm audit must report zero vulnerabilities. Do not use npm audit fix --force; apply compatible lockfile updates deliberately and verify them with npm ci and the repository gates.

Update workflow

1. Change one dependency cohort at a time.
2. Regenerate package-lock.json with the validated Node 24/npm 11 toolchain.
3. Update the affected handbook rows and compatibility notes.
4. Run npm run validate:dependencies.
5. Run focused tests for the affected owner, followed by lint, strict type-check, coverage, production build, and browser verification required by AGENTS.md.
6. Run npm audit --omit=dev and npm audit; never force-fix a breaking downgrade.
7. Commit each verified cohort independently so it can be reverted without disturbing later work.