bitvid/ONBOARDING_REPORT.md

Developer Onboarding Audit

Date: 2026-02-12 Environment: Linux (x64) | Node.js v22

Steps Executed

1. npm ci: Successful.
2. npm run build:css: Successful.
3. npm run format: Successful.
4. npm run build: Successful (required for full lint coverage).
5. npm run lint: Successful.
   • lint:assets skipped initially when dist/ was missing, then passed after npm run build.
   • lint:sw-compat skipped due to missing git history (expected in shallow clones).
6. npm run test:unit: Successful (13 tests passed).

Findings

• Reliability: The onboarding steps are robust. Dependencies installed correctly, and build/test scripts executed without error.
• Documentation:
  • README.md correctly lists npm ci, npm start (which builds), and npm run test:unit. It was missing npm run lint in the "Verify setup" checklist.
  • CONTRIBUTING.md correctly lists npm run format and npm run lint. It did not explicitly mention that npm run build is a prerequisite for lint:assets (though the lint script handles the missing build gracefully).
• Dev Container: The .devcontainer/devcontainer.json uses mcr.microsoft.com/devcontainers/javascript-node:22 which aligns with the project's requirement. However, postCreateCommand uses npx playwright install without --with-deps, which might fail if system dependencies are missing in the base image.
• Node Version: package.json correctly enforces "engines": { "node": ">=22" }.

Recommendations Implemented

1. Documentation Updates:
   • Added npm run lint to README.md verification steps.
   • Clarified build prerequisites for linting in CONTRIBUTING.md.
2. Dev Container Robustness:
   • Updated .devcontainer/devcontainer.json to use npx playwright install --with-deps.