Skip to content

refactor(paths): replace eager constants with lazy getters (N4)#27

Merged
NagyVikt merged 1 commit into
mainfrom
agent/n4-paths-deprecation
May 17, 2026
Merged

refactor(paths): replace eager constants with lazy getters (N4)#27
NagyVikt merged 1 commit into
mainfrom
agent/n4-paths-deprecation

Conversation

@NagyVikt
Copy link
Copy Markdown
Collaborator

Summary

Implements Theme N4 — Drop eager paths.ts constants from
docs/future/17-ROADMAP.md.

The bare exports codexDir, accountsDir, authPath, currentNamePath,
registryPath, and sessionMapPath in src/lib/config/paths.ts were
evaluated at module import time, so env-var overrides set after the first
import had no effect. Rationale lives in
docs/future/01-ARCHITECTURE.md §10.2.

All internal call sites already use the resolveX() functions; the bare
constants are now marked @deprecated and scheduled for removal in v0.2.0
so any external library consumers get a one-release migration window.

Exit criteria

  • No file imports the bare constants (codexDir, accountsDir, etc.).
  • The constants are marked @deprecated with a one-release removal note (v0.2.0).
  • A test under src/tests/paths.test.ts proves env-var changes apply after module load.

Files changed

  • src/lib/config/paths.ts — JSDoc @deprecated on six bare constants; resolvers unchanged.
  • src/tests/paths.test.ts — new; 6 tests covering all five resolvers plus a regression guard.

Zero call-site conversions were required: grep confirms every importer of config/paths already pulls in resolveX() functions, not the bare names.

Verification

$ npm run build
$ npm test
# tests 91
# pass 91
# fail 0

$ grep -rn 'from .*/config/paths' src/ \
    | grep -v 'resolveCodex\|resolveAccounts\|resolveAuth\|resolveCurrentName\|resolveRegistry\|resolveSessionMap\|resolveSnapshot\|paths.ts\|paths.test'
# (only false-positive: multi-line import in account-service.ts — every symbol imported is a resolver)

Behavior change

None for end users. Pure refactor + new test. The deprecated constants still resolve to the same paths they always did.

Coordination

Sibling PRs from N1 (durability) and N3 (errors taxonomy) running in
parallel; expect a rebase if they land first. This PR deliberately did
not touch command file bodies (only resolver-import sites would
change anyway, and there were none), so the conflict surface with N3 is
empty.

Test plan

  • npm run build clean
  • npm test — 91/91 pass on Node 22 / Linux
  • CI matrix (Ubuntu/macOS/Windows × Node 18/20/22)

Theme N4 — Drop eager paths.ts constants.

The bare exports `codexDir`, `accountsDir`, `authPath`, `currentNamePath`,
`registryPath`, and `sessionMapPath` were evaluated at module import time, so
env-var overrides (`CODEX_AUTH_CODEX_DIR`, `CODEX_AUTH_JSON_PATH`, etc.) set
after the first `import` had no effect. That broke tests that set the env
after `require()`, and broke systemd `--user` daemons that inherited a
different `HOME` than the user-facing CLI.

All internal call sites already use the `resolveX()` functions; no
conversions were needed in this PR. The bare constants are now marked
`@deprecated` and scheduled for removal in v0.2.0 so any external library
consumers get a one-release migration window.

A new `src/tests/paths.test.ts` proves the resolvers track env-var changes
applied after module load, and includes a regression guard asserting the
deprecated bare constants do NOT track env-var changes (so we know the
defect is gone when v0.2.0 removes them).

Exit criteria (docs/future/17-ROADMAP.md Theme N4):
- No file imports the bare constants.
- Constants marked @deprecated with one-release removal note.
- Test under src/tests/paths.test.ts proves env-var changes apply after
  module load.
@NagyVikt NagyVikt merged commit 12c577f into main May 17, 2026
12 checks passed
NagyVikt added a commit that referenced this pull request May 18, 2026
Bumps package.json + package-lock.json from 0.1.24 to 0.1.25 and
extends releases/v0.1.25.md to cover every theme that landed since
v0.1.24:

- N1 durability (#29): atomic writes, registry lock, fsync-before-rename
- N2 account-service split (#30): 1675 LOC -> 164 LOC orchestrator + 12 modules
- N3 error taxonomy + --json (#28): AuthmuxError base, stable codes, JSON envelope
- N4 lazy path resolvers (#27): bare constants deprecated for v0.2.0
- P0 wave (#26): secure perms, [y/N] update prompt, kiro ENOENT, CI matrix,
  registry proxy-source round-trip, 18k-line improvement docs

Notes follow the canonical 7-section shape from
docs/future/17-ROADMAP.md (Added, Changed, Fixed, Deprecated, Removed,
Security, Migration), with the prior Durability section folded into a
"Theme deep-dives" appendix so the canonical shape is intact.

No code changes. No npm publish.

Verification:
- npm run build: clean
- npm test: 129/129 pass
- node -e "require('./package.json').version" -> 0.1.25
- node -e "require('./package-lock.json').version" -> 0.1.25

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant