overengineeringstudio / overengineeringstudio/effect-utils

pnpm install friction: frozen lockfiles, stale lockfiles, and task ordering

Open
#130 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area:nix area:nix-hash type:chore
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

  1. Fresh clone + dev runs dt pnpm:install with missing/stale lockfiles
    • Should fail fast with actionable guidance: run dt pnpm:update (and dt nix:hash:<pkg> if needed).
  2. Developer edits .genie.ts (package.json regenerated), then runs dt pnpm:install
    • With frozen default, should fail unless dt genie:run + dt pnpm:update was run.
    • Consider enforcing genie:run before pnpm:install when frozen is set.
  3. CI vs local parity (R5)
    • CI uses --frozen-lockfile today. Local sometimes doesn’t, which can mask stale lockfiles.
    • Target: same inputs → same outcome, regardless of cache state.
  4. Task graph ordering/race
    • genie:run and pnpm:install can 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.
  5. 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 (or PNPM_INSTALL_MODE=frozen|loose)
    • Default could be: frozen on CI, configurable locally
  • If frozen is default:
    • Ensure pnpm:install depends on genie:run when package.json is generated
    • Improve stale lockfile error messaging and point to dt pnpm:update
    • Consider failing fast when lockfile missing instead of warning
  • 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:install behaves 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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.