50 lines
2.2 KiB
Markdown
50 lines
2.2 KiB
Markdown
# AgendaPro: local setup and failure recovery
|
|
|
|
## Recommended install
|
|
|
|
Use the checked-in lockfile and a project-local npm cache:
|
|
|
|
```text
|
|
npm run setup
|
|
npm run dev
|
|
```
|
|
|
|
On PowerShell machines where `npm.ps1` is blocked by execution policy, use `npm.cmd`:
|
|
|
|
```text
|
|
npm.cmd run setup
|
|
npm.cmd run dev
|
|
```
|
|
|
|
The setup script uses `npm ci`; it does not mutate dependency versions. The local cache is ignored by Git and avoids failures caused by an unwritable global npm cache.
|
|
|
|
## What was audited
|
|
|
|
- `SEC_E_NO_CREDENTIALS` during clone: Git was using the Windows Schannel TLS backend and the host could not acquire TLS credentials. This is a machine-level Git/TLS issue, not an application error. Retry the clone with `git -c http.sslBackend=openssl clone <url>`.
|
|
- `npm.ps1` execution-policy error: PowerShell blocked the npm wrapper. `npm.cmd` is the same npm installation without the blocked PowerShell wrapper.
|
|
- npm `EPERM` in `AppData\Local\npm-cache`: the global cache was not writable. `.npmrc` and `scripts/setup.mjs` route the cache to `.cache/npm` inside the project.
|
|
- `tsx` `uv_os_get_passwd`/`os.userInfo()` error: the host returned an OS error while tsx selected its temporary directory. `scripts/run-tsx.mjs` keeps the native call when it works and supplies a safe username fallback when it fails.
|
|
- Vite/esbuild config loading: the original config used `__dirname` in an ESM project. `vite.config.ts` now resolves `src` from `import.meta.url`, binds the dev server deterministically to `127.0.0.1`, supports `VITE_PORT`, and fails clearly when the port is already occupied.
|
|
- Git `dubious ownership`: some managed workspaces are created by a different Windows identity. If needed, authorize only this checkout with `git config --global --add safe.directory <absolute-project-path>`.
|
|
|
|
## Preflight and recovery
|
|
|
|
The project validates Node.js >= 22.5 and `node:sqlite` before development, build, and production start. If a port is busy, inspect it with:
|
|
|
|
```text
|
|
netstat -ano | findstr :3000
|
|
netstat -ano | findstr :5173
|
|
```
|
|
|
|
Change ports without editing source:
|
|
|
|
```text
|
|
PORT=3001 VITE_PORT=5174 API_URL=http://127.0.0.1:3001 npm run dev
|
|
```
|
|
|
|
PowerShell equivalent:
|
|
|
|
```text
|
|
$env:PORT='3001'; $env:VITE_PORT='5174'; $env:API_URL='http://127.0.0.1:3001'; npm.cmd run dev
|
|
```
|