AgendaPro/RUNBOOK.md

AgendaPro: local setup and failure recovery

Recommended install

Use the checked-in lockfile and a project-local npm cache:

npm run setup
npm run dev

On PowerShell machines where npm.ps1 is blocked by execution policy, use npm.cmd:

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:

netstat -ano | findstr :3000
netstat -ano | findstr :5173

Change ports without editing source:

PORT=3001 VITE_PORT=5174 API_URL=http://127.0.0.1:3001 npm run dev

PowerShell equivalent:

$env:PORT='3001'; $env:VITE_PORT='5174'; $env:API_URL='http://127.0.0.1:3001'; npm.cmd run dev