Fix local:install preflight: env-var requirements should not block install #45

New issue

Closed

opened 2026-08-18 21:28:41 +00:00 by david · 1 comment

david commented

2026-08-18 21:28:41 +00:00

Owner

Problem

npm run local:install (scripts/local-install.mjs) hard-fails in preflight when an extension requirement is missing. Env-var requirements should not be hard requirements: env vars are usually stored in per-machine .env files (gitignored, absent from a fresh clone), so install must not block on them.

Current preflight hard-fails on these env-var requirements:

DATABASE_URL (postgres extension) — checks process.env AND the checkout's .env
FORGEJO_TOKEN (forgejo extension) — checks process.env only

Non-env requirements (rg binary, fj auth list, pi CLI + git structural checks) are intentionally not part of this change.

Agreed decisions

Remove the DATABASE_URL check entirely. It is a per-repo requirement: the postgres extension loads .env from process.cwd() (the user's project) at runtime, so checking the package checkout's .env at install time is the wrong place. Drop the check (and the now-unused readDotEnv call in preflight).
FORGEJO_TOKEN becomes warn-and-continue. It is a global credential, so a missing token is non-fatal. Keep the check env-only (no .env reading — a global token does not live in a repo's .env). When missing: print the existing full remediation text on stderr, prefixed [local:install] Warning: …, then continue (no process.exit).
Non-env requirements stay hard-fail: pi CLI, git-checkout/main/clean-tree checks, rg binary, fj auth list.

Acceptance criteria

scripts/local-install.mjs: DATABASE_URL check removed; FORGEJO_TOKEN check emits a warning (full remediation text, [local:install] Warning: … prefix, stderr) and does not abort; rg/fj/pi/git checks still hard-fail.
scripts/local-install.test.mjs: replace preflight aborts when FORGEJO_TOKEN is missing with a warns-but-does-not-abort test; drop withDb (DATABASE_URL no longer checked); keep withToken for the warning test.
README.md: keep Postgres credentials + FORGEJO_TOKEN as runtime prerequisites; preflight step list drops DATABASE_URL and marks FORGEJO_TOKEN warn-only; fail-fast table updated (DATABASE_URL row removed, FORGEJO_TOKEN row becomes a warning note).
docs/IMPLEMENTATION_PLAN.md: Step 0 preflight bullets + §5.1 negative tests updated to match.
npm test passes; npm run local:install exits 0 with no env vars set (only the FORGEJO_TOKEN warning printed).

Notes

Repo workflow: branch bug/issue-<N>/<slug>, commits issue-<N>: <summary>, PR Closes #<N>.

## Problem `npm run local:install` (`scripts/local-install.mjs`) hard-fails in preflight when an extension requirement is missing. Env-var requirements should not be hard requirements: env vars are usually stored in per-machine `.env` files (gitignored, absent from a fresh clone), so install must not block on them. Current preflight hard-fails on these env-var requirements: - `DATABASE_URL` (postgres extension) — checks `process.env` AND the checkout's `.env` - `FORGEJO_TOKEN` (forgejo extension) — checks `process.env` only Non-env requirements (`rg` binary, `fj auth list`, pi CLI + git structural checks) are intentionally **not** part of this change. ## Agreed decisions - **Remove the `DATABASE_URL` check entirely.** It is a per-repo requirement: the postgres extension loads `.env` from `process.cwd()` (the user's project) at runtime, so checking the package checkout's `.env` at install time is the wrong place. Drop the check (and the now-unused `readDotEnv` call in `preflight`). - **`FORGEJO_TOKEN` becomes warn-and-continue.** It is a global credential, so a missing token is non-fatal. Keep the check env-only (no `.env` reading — a global token does not live in a repo's `.env`). When missing: print the existing full remediation text on stderr, prefixed `[local:install] Warning: …`, then continue (no `process.exit`). - **Non-env requirements stay hard-fail:** `pi` CLI, git-checkout/`main`/clean-tree checks, `rg` binary, `fj auth list`. ## Acceptance criteria - [ ] `scripts/local-install.mjs`: `DATABASE_URL` check removed; `FORGEJO_TOKEN` check emits a warning (full remediation text, `[local:install] Warning: …` prefix, stderr) and does not abort; `rg`/`fj`/pi/git checks still hard-fail. - [ ] `scripts/local-install.test.mjs`: replace `preflight aborts when FORGEJO_TOKEN is missing` with a warns-but-does-not-abort test; drop `withDb` (DATABASE_URL no longer checked); keep `withToken` for the warning test. - [ ] `README.md`: keep Postgres credentials + `FORGEJO_TOKEN` as runtime prerequisites; preflight step list drops `DATABASE_URL` and marks `FORGEJO_TOKEN` warn-only; fail-fast table updated (`DATABASE_URL` row removed, `FORGEJO_TOKEN` row becomes a warning note). - [ ] `docs/IMPLEMENTATION_PLAN.md`: Step 0 preflight bullets + §5.1 negative tests updated to match. - [ ] `npm test` passes; `npm run local:install` exits 0 with no env vars set (only the FORGEJO_TOKEN warning printed). ## Notes Repo workflow: branch `bug/issue-<N>/<slug>`, commits `issue-<N>: <summary>`, PR `Closes #<N>`.

david added the

bug

label

2026-08-18 21:28:47 +00:00

david referenced this issue

2026-08-18 21:36:43 +00:00

45: Fix local:install preflight: env-var requirements should not block install #46

david closed this issue

2026-08-18 21:36:45 +00:00

david commented

2026-08-18 21:36:45 +00:00

Author