overengineeringstudio / overengineeringstudio/effect-utils
pnpm install friction: frozen lockfiles, stale lockfiles, and task ordering
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 82
- Forks
- 2
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 121
Description
Context
- We discussed making pnpm installs always use --frozen-lockfile locally to align with CI and R5 determinism.
- This would tighten the install/update separation but can increase dev friction when package.json changes (esp via .genie.ts) or when lockfiles are missing/stale.
- There is also a race risk when tasks run genie:run and pnpm:install in parallel; frozen installs can fail if package.json is updated during install.
Scenarios to consider
- Fresh clone + dev runs
dt pnpm:installwith missing/stale lockfiles- Should fail fast with actionable guidance: run
dt pnpm:update(anddt nix:hash:<pkg>if needed).
- Should fail fast with actionable guidance: run
- Developer edits .genie.ts (package.json regenerated), then runs
dt pnpm:install- With frozen default, should fail unless
dt genie:run+dt pnpm:updatewas run. - Consider enforcing
genie:runbeforepnpm:installwhen frozen is set.
- With frozen default, should fail unless
- CI vs local parity (R5)
- CI uses
--frozen-lockfiletoday. Local sometimes doesn’t, which can mask stale lockfiles. - Target: same inputs → same outcome, regardless of cache state.
- CI uses
- Task graph ordering/race
genie:runandpnpm:installcan run in parallel via setup tasks.- With frozen installs, a race can yield intermittent failures or installs against old deps.
- Consider explicit ordering or grouping.
- Missing lockfile (per‑package
pnpm-lock.yaml)- Currently warns and proceeds (non‑deterministic). Decide if we should hard‑fail instead.
Tradeoffs
- Pros of frozen‑by‑default
- Strong determinism and CI parity
- Early detection of stale lockfiles
- Fewer “works locally but fails in CI” situations
- Cons of frozen‑by‑default
- More friction for routine dependency updates
- Requires clearer workflow/education and better error messages
- Needs tighter task ordering to avoid parallel race with genie generation
Options / Ideas
- Add an env toggle:
PNPM_FROZEN=1/0(orPNPM_INSTALL_MODE=frozen|loose)- Default could be: frozen on CI, configurable locally
- If frozen is default:
- Ensure
pnpm:installdepends ongenie:runwhen package.json is generated - Improve stale lockfile error messaging and point to
dt pnpm:update - Consider failing fast when lockfile missing instead of warning
- Ensure
- Document workflow
- Short section in README or context/workarounds: “edit .genie.ts → dt genie:run → dt pnpm:update → dt nix:hash”
Acceptance ideas
- Fresh clone +
dt pnpm:installbehaves deterministically and provides clear instructions on failure. - CI/local parity (R5): no cache‑dependent pass/fail differences.
- No race when setup tasks run in parallel.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the .genie.ts-generated package.json flow and the dt pnpm:install, dt pnpm:update, dt genie:run, and dt nix:hash tasks. Reproduce the fresh-clone, stale-lockfile, generated-package, and parallel-setup scenarios described in the issue. Done means the chosen frozen-install policy, task ordering, missing-lockfile behavior, and failure guidance are defined and validated against the listed acceptance ideas.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- build-system, ci-cd, developer-experience
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100