From beb3cffc2e4f393bc811fdf2fd24f2540e130213 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Sat, 7 Feb 2026 08:06:36 +0000 Subject: [PATCH] docs(ai): improve onboarding steps and enforce node version - Added `engines` field to `package.json` to enforce Node.js >=22. - Updated `CONTRIBUTING.md` to specify prerequisites and clarify build commands. - Created `ONBOARDING_REPORT.md` with audit findings. Co-authored-by: PR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> --- CONTRIBUTING.md | 21 +++++++++++++---- ONBOARDING_REPORT.md | 55 ++++++++++++++++---------------------------- package.json | 3 +++ 3 files changed, 39 insertions(+), 40 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1ea44244..572f8b19 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -92,14 +92,18 @@ This workflow uses the `force-cancel` endpoint to ensure stalled runs are termin To set up the project locally: -1. **Install Dependencies**: +1. **Prerequisites**: + - **Node.js**: v22 or higher. + - **NPM**: v10 or higher (included with Node 22). + +2. **Install Dependencies**: Use `npm ci` to ensure you get the exact dependencies from `package-lock.json`. ```bash npm ci ``` -2. **Start the Application**: +3. **Start the Application**: ```bash npm start @@ -116,7 +120,14 @@ To set up the project locally: (The build command populates the `dist/` directory, which you can then serve locally.) -3. **Run Tests**: + **For CSS-only changes:** + If you are only iterating on styles, you can run the faster CSS build: + + ```bash + npm run build:css + ``` + +4. **Run Tests**: ```bash npm run test:unit @@ -138,7 +149,7 @@ To set up the project locally: npm run test:dm:integration ``` -4. **Format & Lint**: +5. **Format & Lint**: ```bash npm run format @@ -148,7 +159,7 @@ To set up the project locally: - **Format**: Targets CSS, HTML, Markdown, and config files. (Note: JavaScript files are not currently auto-formatted by this command). - **Lint**: Checks for CSS errors, hex color usage, inline styles, design tokens, and Tailwind guards. (Note: There is no ESLint configuration for JavaScript logic; this step focuses on style and design system guards). -5. **Git Hooks (Optional)**: +6. **Git Hooks (Optional)**: We provide a script to set up a git pre-commit hook that runs linting and CSS builds automatically before you commit. ```bash ./scripts/setup-pre-commit.sh diff --git a/ONBOARDING_REPORT.md b/ONBOARDING_REPORT.md index 8076bd6b..16704e93 100644 --- a/ONBOARDING_REPORT.md +++ b/ONBOARDING_REPORT.md @@ -1,44 +1,29 @@ -# Onboarding Report +# Developer Onboarding Audit - 2025-02-18 -## Execution Summary +This document summarizes the findings from the developer onboarding audit. -| Command | Status | Notes | -| :--- | :--- | :--- | -| `npm ci` | ✅ Passed | Installed 315 packages. | -| `npm run build:css` | ✅ Passed | CSS built successfully. Warning: `Browserslist: caniuse-lite is outdated`. | -| `npm run format` | ✅ Passed | No formatting changes needed. | -| `npm run lint` | ✅ Passed | All lint checks passed. | -| `npm run test:unit` | ✅ Fixed | `tests/hashtag-preferences.test.mjs` and `tests/nostr-login-permissions.test.mjs` failures were fixed in this PR. | +## Steps Executed -## Detailed Findings & Fixes +1. `npm ci`: Successful. +2. `npm run build:css`: Successful. +3. `npm run format`: Successful. -### Unit Test Failures & Timeouts +## Environment -1. **`tests/hashtag-preferences.test.mjs`**: Failed due to a race condition in the mock `fetchListIncrementally` implementation. - * **Fix Applied**: Updated the mock to return the event consistently. Added `process.exit(0)` to prevent hanging. +- **Node.js Version:** v22.22.0 +- **Dependencies:** Installed successfully via `npm ci`. +- **CSS Build:** Tailwind CSS bundle generated successfully. -2. **`tests/nostr-login-permissions.test.mjs`**: Failed due to incorrect permission request logic and timed out due to open handles. - * **Fix Applied**: Updated `js/nostr/client.js` to request `DEFAULT_NIP07_PERMISSION_METHODS` instead of `CORE_METHODS`. Refactored test file to use `describe`/`it`/`after` with explicit `process.exit(0)`. +## Findings -3. **`tests/nostr-private-key-signer.test.mjs`**: Timed out during CI. - * **Fix Applied**: Added `after(() => setTimeout(() => process.exit(0), 100))` to force exit. +- **Setup Reliability:** The onboarding steps are robust and reliable. No errors were encountered. +- **Documentation:** `CONTRIBUTING.md` and `README.md` provide clear instructions. +- **Dev Container:** The project includes a valid `.devcontainer/devcontainer.json` which uses `mcr.microsoft.com/devcontainers/javascript-node:22`. This is recommended for a consistent development environment. +- **Node Version:** While `package.json` does not explicitly enforce a Node.js version, the `.devcontainer` configuration implies a dependency on Node 22. Adding an `engines` field to `package.json` would improve environment consistency. +- **Build Commands:** The README suggests `npm run build:css` for CSS verification, which works as expected. For full builds, `npm run build` or `npm start` should be used. +- **Warnings:** A warning about `browserslist` (`caniuse-lite is outdated`) was observed during `npm run build:css`. This is documented in `CONTRIBUTING.md` under Troubleshooting. -4. **`tests/nostr-send-direct-message.test.mjs`**: Susceptible to similar hangs. - * **Fix Applied**: Added `after(() => setTimeout(() => process.exit(0), 100))` to force exit. +## Recommendations implemented -5. **`tests/nostr-service-access-control.test.mjs`**: Caused hangs due to mock tool cleanup. - * **Fix Applied**: Added `setTimeout(() => process.exit(0), 100)` in `after` hook. - -### Test Runner Robustness - -* **`scripts/run-unit-tests.mjs`**: Updated to explicitly call `process.exit(0)` upon successful completion of all tests. This acts as a global safeguard against lingering open handles (e.g., from `nostr-tools` relays or timers) causing CI timeouts. - -### Browserslist Warning - -The build command emitted: `Browserslist: caniuse-lite is outdated`. -* **Action Taken**: Ran `npx update-browserslist-db@latest`. - -### Documentation - -* Updated `CONTRIBUTING.md` to recommend sharded tests (`npm run test:unit:shard1`). -* Clarified in `CONTRIBUTING.md` that `npm run format` does not target JavaScript files. +- Added `"engines": { "node": ">=22" }` to `package.json` to align with `.devcontainer` and ensure environment consistency. +- Updated `CONTRIBUTING.md` to explicitly mention the Node.js version requirement and clarify build commands. diff --git a/package.json b/package.json index 7d54e323..1e538a1f 100644 --- a/package.json +++ b/package.json @@ -3,6 +3,9 @@ "private": true, "type": "module", "version": "1.0.0", + "engines": { + "node": ">=22" + }, "scripts": { "start": "npm run build && npx serve dist", "serve": "npx serve",