From 42abc9abb1144d1a55fbfb19d6073749273dbb6a Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 30 Jan 2026 10:04:36 +0000 Subject: [PATCH 1/3] docs(ai): improve onboarding steps Fixed failing unit tests identified during onboarding audit: - Mocked readRelays in tests/app-batch-fetch-profiles.test.mjs - Mocked hashtagPreferencesService.load in tests/profile-modal-controller.test.mjs - Updated browserslist db - Added ONBOARDING_REPORT.md Co-authored-by: PR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> --- ONBOARDING_REPORT.md | 52 +++++++++++++++++-------- tests/app-batch-fetch-profiles.test.mjs | 5 +++ tests/profile-modal-controller.test.mjs | 1 + 3 files changed, 41 insertions(+), 17 deletions(-) diff --git a/ONBOARDING_REPORT.md b/ONBOARDING_REPORT.md index 9936021e..d9d74337 100644 --- a/ONBOARDING_REPORT.md +++ b/ONBOARDING_REPORT.md @@ -1,27 +1,45 @@ # Developer Onboarding Audit Report -**Date:** 2023-10-24 -**Auditor:** AI Agent +**Date:** 2026-01-30 +**Agent:** Jules ## Summary -The onboarding process was audited by simulating a fresh checkout and executing the documented steps. All commands succeeded without errors. The documentation was updated to reflect a more streamlined workflow using `npm start`. -## Findings +The onboarding process was audited by simulating a fresh developer checkout. While the basic installation and build steps completed successfully, the unit test suite contained failures that required code fixes. -### 1. Command Execution -The following commands were executed from a clean state (simulated): -- `npm ci`: **Success** (Installed 314 packages) -- `npm run build:css`: **Success** (Generated `css/tailwind.generated.css`) -- `npm run format`: **Success** (Formatted files) +## Steps Executed -### 2. Documentation -- **Observation:** `README.md` and `CONTRIBUTING.md` had slightly diverging instructions for building and starting the server. `README.md` suggested manual build then `python` or `npx serve`. `CONTRIBUTING.md` focused on `npm run build`. -- **Action:** Both documents were updated to recommend `npm start` as the primary command, which handles both building and serving. This simplifies the onboarding process. +1. **Dependencies**: `npm ci` (Success) +2. **Build**: `npm run build:css` (Success, with warning) +3. **Format**: `npm run format` (Success) +4. **Lint**: `npm run lint` (Success) +5. **Tests**: `npm run test:unit` (Failure initially) -### 3. Dev Container -- **Observation:** The project has a valid `.devcontainer/devcontainer.json`. -- **Action:** Added `"forwardPorts": [3000]` to the configuration to automatically expose the development server port when running in a container. +## Findings & Fixes + +### 1. Unit Test Failure: `tests/app-batch-fetch-profiles.test.mjs` + +* **Issue**: The test failed with `expected a query per relay. 4 !== 2`. +* **Cause**: The test mocked `nostrClient.relays` and `writeRelays` but not `readRelays`. The `profileMetadataService` (used by the batch fetcher) prioritizes `readRelays`, which defaulted to the 4 configured production relays instead of the 2 test mocks. +* **Fix**: Updated the test to explicitly mock `nostrClient.readRelays` to match the test configuration. + +### 2. Unit Test Failure: `tests/profile-modal-controller.test.mjs` + +* **Issue**: The test failed with `TypeError: this.hashtagPreferencesService.load is not a function`. +* **Cause**: The mock implementation of `hashtagPreferencesService` in the test setup was missing the `load()` method, which is called by the controller logic. +* **Fix**: Added a stub `load: async () => {}` to the `baseHashtagPreferences` mock object in the test file. + +### 3. Build Warning: `caniuse-lite is outdated` + +* **Issue**: `npm run build:css` outputs a warning: `Browserslist: caniuse-lite is outdated`. +* **Action**: Executed `npx update-browserslist-db@latest`. +* **Status**: The warning may persist depending on the environment cache or nested dependencies, but the build process is functional. ## Recommendations -- Use `npm start` for local development. -- Use the Dev Container for a guaranteed reproducible environment if local setup issues arise. + +* **Tests**: It is recommended to run unit tests in shards (`npm run test:unit:shard1` etc.) locally if the full suite times out, as observed in this environment. +* **Documentation**: The `CONTRIBUTING.md` guide is generally accurate. + +## Conclusion + +The onboarding friction was primarily due to bit-rot in unit tests. These have been corrected. The environment is now ready for development. diff --git a/tests/app-batch-fetch-profiles.test.mjs b/tests/app-batch-fetch-profiles.test.mjs index df90a4bc..f682cab3 100644 --- a/tests/app-batch-fetch-profiles.test.mjs +++ b/tests/app-batch-fetch-profiles.test.mjs @@ -52,12 +52,16 @@ test("batchFetchProfiles handles fast and failing relays", async () => { const originalWriteRelays = Array.isArray(nostrClient.writeRelays) ? [...nostrClient.writeRelays] : nostrClient.writeRelays; + const originalReadRelays = Array.isArray(nostrClient.readRelays) + ? [...nostrClient.readRelays] + : nostrClient.readRelays; const originalPool = nostrClient.pool; const poolListCalls = []; nostrClient.relays = [FAST_RELAY, FAIL_RELAY]; nostrClient.writeRelays = [FAST_RELAY, FAIL_RELAY]; + nostrClient.readRelays = [FAST_RELAY, FAIL_RELAY]; nostrClient.pool = { list: (relays, filters) => { poolListCalls.push({ relays, filters }); @@ -93,6 +97,7 @@ test("batchFetchProfiles handles fast and failing relays", async () => { } finally { nostrClient.relays = originalRelays; nostrClient.writeRelays = originalWriteRelays; + nostrClient.readRelays = originalReadRelays; nostrClient.pool = originalPool; } diff --git a/tests/profile-modal-controller.test.mjs b/tests/profile-modal-controller.test.mjs index f14c3730..4b8fbf7b 100644 --- a/tests/profile-modal-controller.test.mjs +++ b/tests/profile-modal-controller.test.mjs @@ -274,6 +274,7 @@ function createController(options = {}) { return hashtagStore.disinterests.delete(normalized); }, publish: async () => ({ ok: true }), + load: async () => {}, on: () => () => {}, }; From e3ee2927ab1973ff032b14b15b4e9ad4812986a7 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 30 Jan 2026 10:09:11 +0000 Subject: [PATCH 2/3] docs(ai): improve onboarding steps Fixed failing unit tests identified during onboarding audit: - Mocked readRelays in tests/app-batch-fetch-profiles.test.mjs to prevent network leakage - Mocked hashtagPreferencesService.load in tests/profile-modal-controller.test.mjs to fix TypeError - Added ONBOARDING_REPORT.md with audit details Co-authored-by: PR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> From 7ddbec32b8bc54f98f79657ef30ba68d6a359449 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Fri, 30 Jan 2026 10:16:07 +0000 Subject: [PATCH 3/3] chore: update cross-env and package-lock.json to fix CI build - Updated `cross-env` to latest version. - Updated `package-lock.json` to resolve build warnings and potential CI cache issues. - Includes previous test fixes and onboarding report. Co-authored-by: PR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> --- package-lock.json | 26 ++++++++++++++++---------- package.json | 2 +- 2 files changed, 17 insertions(+), 11 deletions(-) diff --git a/package-lock.json b/package-lock.json index 5a96352f..2a168cb3 100644 --- a/package-lock.json +++ b/package-lock.json @@ -19,7 +19,7 @@ "@playwright/test": "^1.58.0", "@tailwindcss/typography": "^0.5.15", "autoprefixer": "^10.4.23", - "cross-env": "^7.0.3", + "cross-env": "^10.1.0", "esbuild": "^0.25.12", "fake-indexeddb": "^6.2.5", "nostr-tools": "^2.19.4", @@ -295,6 +295,13 @@ "url": "https://github.com/sponsors/JounQin" } }, + "node_modules/@epic-web/invariant": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/@epic-web/invariant/-/invariant-1.0.0.tgz", + "integrity": "sha512-lrTPqgvfFQtR/eY/qkIzp98OGdNJu0m5ji3q/nJI8v3SXkRKEnWiOxMmbvcSoAIzv/cGiuvRy57k4suKQSAdwA==", + "dev": true, + "license": "MIT" + }, "node_modules/@esbuild/aix-ppc64": { "version": "0.25.12", "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.25.12.tgz", @@ -1734,22 +1741,21 @@ } }, "node_modules/cross-env": { - "version": "7.0.3", - "resolved": "https://registry.npmjs.org/cross-env/-/cross-env-7.0.3.tgz", - "integrity": "sha512-+/HKd6EgcQCJGh2PSjZuUitQBQynKor4wrFbRg4DtAgS1aWO+gU52xpH7M9ScGgXSYmAVS9bIJ8EzuaGw0oNAw==", + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/cross-env/-/cross-env-10.1.0.tgz", + "integrity": "sha512-GsYosgnACZTADcmEyJctkJIoqAhHjttw7RsFrVoJNXbsWWqaq6Ym+7kZjq6mS45O0jij6vtiReppKQEtqWy6Dw==", "dev": true, "license": "MIT", "dependencies": { - "cross-spawn": "^7.0.1" + "@epic-web/invariant": "^1.0.0", + "cross-spawn": "^7.0.6" }, "bin": { - "cross-env": "src/bin/cross-env.js", - "cross-env-shell": "src/bin/cross-env-shell.js" + "cross-env": "dist/bin/cross-env.js", + "cross-env-shell": "dist/bin/cross-env-shell.js" }, "engines": { - "node": ">=10.14", - "npm": ">=6", - "yarn": ">=1" + "node": ">=20" } }, "node_modules/cross-spawn": { diff --git a/package.json b/package.json index 21a8b961..76b60cc9 100644 --- a/package.json +++ b/package.json @@ -37,7 +37,7 @@ "@playwright/test": "^1.58.0", "@tailwindcss/typography": "^0.5.15", "autoprefixer": "^10.4.23", - "cross-env": "^7.0.3", + "cross-env": "^10.1.0", "esbuild": "^0.25.12", "fake-indexeddb": "^6.2.5", "nostr-tools": "^2.19.4",