diff --git a/AGENTS.md b/AGENTS.md index 5519c43..ae0a89e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,7 +90,7 @@ Do not manually edit generated output or installed dependencies: - Node.js must use the `lts/jod` NVM alias, as declared in `.nvmrc`. - Documented commands target Bash on Linux, macOS, or Windows WSL. Use Bash explicitly for agent commands; fish's `nvm.fish` is unavailable in Bash. -- Before every npm command, explicitly load Bash NVM and select Node in the same shell session: `export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"; . "$NVM_DIR/nvm.sh" && nvm use lts/jod && npm run build`. Do not rely on `.bashrc` loading in noninteractive shells or fall back to system Node. +- Initialize Bash NVM once at the start of each shell session: `export NVM_DIR="${NVM_DIR:-$HOME/.nvm}"; . "$NVM_DIR/nvm.sh" && nvm use` from the project root. `nvm use` reads `lts/jod` from `.nvmrc`. Reuse that initialized shell for subsequent npm commands. If a tool starts a fresh shell for each execution, initialize each new shell or use a persistent shell; environment changes do not carry between independent shells. Stop if initialization fails. Do not rely on `.bashrc` loading in noninteractive shells or fall back to system Node. - If `${NVM_DIR:-$HOME/.nvm}/nvm.sh` is missing, ask the user for permission before installing Bash NVM. Follow `docs/development.md#shell-and-nvm-setup` after approval. Keep existing fish NVM separate. - Install exact dependencies: `npm ci` - Start the Ionic development server: `npm start` diff --git a/README.md b/README.md index ecce562..eaac6bd 100644 --- a/README.md +++ b/README.md @@ -38,49 +38,48 @@ For desktop development, also install: These commands target **Bash** (Linux, macOS, or Windows WSL). From fish, start `bash` first. Follow the [shell and NVM setup](docs/development.md#shell-and-nvm-setup) before continuing. If Bash NVM is missing, agents must ask permission before -installing it. `.nvmrc` declares `lts/jod`: +installing it. `.nvmrc` declares `lts/jod`. + +Initialize NVM once at the start of each Bash session, from the project root: ```bash export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm install lts/jod -nvm use lts/jod && npm ci +. "$NVM_DIR/nvm.sh" && nvm use ``` -Each npm command block loads Bash NVM explicitly and selects the required Node -version, including in fresh noninteractive shells. +On first setup, run `nvm install` after loading NVM if the required Node version +is not installed. Stop if setup fails; do not use the system Node as a fallback. +The commands below reuse this session. Repeat the setup when opening a new shell. + +Install the project dependencies: + +```bash +npm ci +``` If Ionic CLI is not already installed: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm install --global @ionic/cli +npm install --global @ionic/cli ``` ## Web development ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm start +npm start ``` Build the Angular application: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm run build +npm run build ``` Run linting and tests: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm run lint -nvm use lts/jod && npm test +npm run lint +npm test ``` `npm test` starts Karma in its configured mode and may remain open in watch mode. @@ -96,18 +95,14 @@ For VS Code, the recommended extension is `esbenp.prettier-vscode`. Use **Format The Tauri CLI is available through: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm run tauri -- +npm run tauri -- ``` For example: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm run tauri -- dev -nvm use lts/jod && npm run tauri -- build +npm run tauri -- dev +npm run tauri -- build ``` > Tauri development intentionally uses `http://localhost:8103`. The current `npm start` script does not explicitly select that port, so verify that Ionic is listening on `8103` when using `tauri dev`. diff --git a/docs/development.md b/docs/development.md index c2d3b06..91e8290 100644 --- a/docs/development.md +++ b/docs/development.md @@ -27,18 +27,21 @@ NVM. After approval, follow the official Use the default `~/.nvm` location, or set `NVM_DIR` to your existing Bash NVM installation. Keep an existing fish installation separate. -After NVM is installed, install the required Node release from the project root: +Initialize NVM once at the start of each Bash session, from the project root: ```bash export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm install lts/jod +. "$NVM_DIR/nvm.sh" && nvm use ``` -Every npm command block below explicitly loads NVM and selects `lts/jod`. -This also works in noninteractive Bash sessions that do not load `.bashrc`. -Run each block from the project root. Stop if loading NVM or selecting Node fails; -do not fall back to the system Node version. +`nvm use` reads the required `lts/jod` version from `.nvmrc`. On first setup, +run `nvm install` after loading NVM if that version is not installed. +Stop if loading NVM or selecting Node fails; do not fall back to system Node. + +Run the commands below in that initialized shell. Repeat setup for each new +shell, including noninteractive shells that do not load `.bashrc`. Agents should +reuse an initialized shell for subsequent npm commands; separate command +executions do not necessarily share environment changes. Angular 22 requires TypeScript 6.0 and Node.js 22.22.3 or newer on the Node.js 22 line. If your installed `lts/jod` is older, run `nvm install lts/jod` @@ -47,17 +50,13 @@ after loading Bash NVM. Install exact project dependencies with: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm ci +npm ci ``` If needed, install Ionic CLI globally: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm install --global @ionic/cli +npm install --global @ionic/cli ``` The committed `.nvmrc` uses the named `lts/jod` alias. Do not replace it with another Node release or add `.tool-versions` unless the team intentionally changes version-management tools. @@ -71,17 +70,13 @@ Install Rust stable and the Tauri 2 prerequisites for your operating system. `sr Start the Ionic development server: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm start +npm start ``` Build the Angular application: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm run build +npm run build ``` The production web output is generated under `www/`. Do not edit that directory manually. @@ -140,10 +135,8 @@ which proposes incompatible downgrades of Angular and the test tooling. Run Tauri commands through the npm script: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm run tauri dev -nvm use lts/jod && npm run tauri build +npm run tauri dev +npm run tauri build ``` Tauri development intentionally expects the frontend at `http://localhost:8103`. `devUrl` tells Tauri where to connect, and `beforeDevCommand` runs `npm run ng -- serve --host=0.0.0.0 --port=8103` to serve the frontend on the matching port without opening a browser. This uses the project's Angular CLI and does not require a global Ionic CLI installation. Keep these settings aligned when changing Tauri or serve configuration. @@ -158,12 +151,10 @@ load these values from `.env` files. Keep private keys and passwords outside the repository. ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" export TAURI_SIGNING_PRIVATE_KEY="$HOME/.tauri/myapp.key" # For a key without a password: export TAURI_SIGNING_PRIVATE_KEY_PASSWORD="" -nvm use lts/jod && npm run tauri build +npm run tauri build ``` For a password-protected key, replace the empty-password export with a hidden diff --git a/docs/testing.md b/docs/testing.md index 275d229..33f1e81 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -12,22 +12,19 @@ as the app rather than installing an older nested copy. These examples target Bash and run from the project root. Complete the [shell and NVM setup](development.md#shell-and-nvm-setup) first. Agents must ask -permission before installing missing Bash NVM. Each npm block loads NVM explicitly. +permission before installing missing Bash NVM. Initialize NVM once per Bash +session as described there, then run the commands below in that same shell. Run the interactive test suite: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm test +npm test ``` Run the configured non-watching CI test mode: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm test -- --configuration=ci +npm test -- --configuration=ci ``` The test environment requires an available Chrome installation. Test coverage output, when enabled by the test runner, is written under `coverage/app/`. @@ -35,9 +32,7 @@ The test environment requires an available Chrome installation. Test coverage ou Run the suite once in headless Chrome with a coverage report: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm test -- --watch=false --browsers=ChromeHeadless --code-coverage +npm test -- --watch=false --browsers=ChromeHeadless --code-coverage ``` If Chrome is not auto-detected, set `CHROME_BIN` to its executable path @@ -53,17 +48,13 @@ spies and signals to isolate assignments, confirmation, and role swaps. Lint TypeScript and Angular templates: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm run lint +npm run lint ``` Build the production Angular application: ```bash -export NVM_DIR="${NVM_DIR:-$HOME/.nvm}" -. "$NVM_DIR/nvm.sh" -nvm use lts/jod && npm run build +npm run build ``` Check Rust changes from the Tauri directory: