Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

`completion install zsh` writes `~/.zshrc` when `$ZDOTDIR` is set, so zsh never loads the completions

Aperta Adatta ai principianti
  • Qualcosa non va?
#2,138 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 2 giorni

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
2/5
Tempo stimato
1-3 ore
Idoneità per principianti
75/100
Tipo di issue
Bug
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Stack tecnologico
typescript, zsh
Ambito
cli

Direzione di ricerca

Leggi src/core/completions/installers/zsh-installer.ts, in particolare getZshrcPath() e i percorsi di installazione, disinstallazione e istruzioni manuali che lo usano. Controlla i test dell’installer e riproduci il caso con un HOME e un ZDOTDIR temporanei; il lavoro è completato quando installazione e disinstallazione hanno come destinazione ${ZDOTDIR:-$HOME}/.zshrc e riportano quel percorso, mantenendo il fallback esistente quando ZDOTDIR non è impostato.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

What you were trying to do

I was setting up tab completion for OpenSpec in zsh. My zsh config lives in ~/.config/zsh: ~/.zshenv exports ZDOTDIR="$HOME/.config/zsh".

This is a common XDG-style layout. It is also the default in Home Manager when xdg.enable is on and home.stateVersion is 26.05 or later: programs.zsh.dotDir defaults to ~/.config/zsh and is exported as ZDOTDIR. So new Home Manager setups with XDG enabled are affected too.

What happened
$ openspec completion install zsh
✓ Completion script installed and .zshrc configured successfully

Restart your shell or run: exec zsh

The installer created a new ~/.zshrc containing the # OPENSPEC:START … # OPENSPEC:END block. My real config, $ZDOTDIR/.zshrc, was not touched. zsh only reads ~/.zshrc when ZDOTDIR is unset (zsh manual: Startup/Shutdown Files). So the block is never loaded, _openspec never gets on fpath, and completion silently doesn't work even though the install reported success.

openspec completion uninstall zsh has the same problem: it only looks in ~/.zshrc.

What you expected instead

The block goes into the file zsh actually reads, ${ZDOTDIR:-$HOME}/.zshrc. Uninstall removes it from the same file, and the messages name that file.

Minimal steps to reproduce

These steps use a throwaway HOME, so they don't touch your real config:

TMPHOME=$(mktemp -d)
mkdir -p "$TMPHOME/.config/zsh"
echo '# my zshrc' > "$TMPHOME/.config/zsh/.zshrc"

HOME="$TMPHOME" ZDOTDIR="$TMPHOME/.config/zsh" openspec completion install zsh

ls -A "$TMPHOME"                  # a new .zshrc appears in HOME
cat "$TMPHOME/.config/zsh/.zshrc" # still just "# my zshrc", no OPENSPEC block
HOME="$TMPHOME" ZDOTDIR="$TMPHOME/.config/zsh" zsh -i -c 'whence -v _openspec'
# _openspec not found

With the fix described below, the last command prints _openspec is an autoload shell function from …/.zsh/completions/_openspec.

OpenSpec version

1.14.3 (also reproduces on main at c04f30e5)

Coding agent and model

None. This is plain CLI usage.

OS and Node version

macOS 26 (Darwin 25.5.0, arm64), zsh 5.9, Node 24.21.0

Where it comes from, and an offer to fix it

getZshrcPath() in src/core/completions/installers/zsh-installer.ts builds the path from $HOME only. Install, uninstall and the manual instructions all go through it.

I have a small fix with regression tests:

  • It resolves the path from $ZDOTDIR and falls back to $HOME. Output is identical when ZDOTDIR is unset.
  • The new tests fail on main and pass with the change. The full suite, tsc and lint are green.

I'd be glad to open a PR if you'd like me to.

A few things I checked or wasn't sure about:

  • IDE terminals. VS Code's zsh shell integration points ZDOTDIR at its own directory during startup, then restores the user's value (USER_ZDOTDIR) before the prompt. So a command typed in the terminal sees the right ZDOTDIR.
  • Read-only .zshrc. Under Home Manager, $ZDOTDIR/.zshrc is usually a read-only symlink into the Nix store. With the fix, the installer's existing write check catches that: it leaves the file alone and prints the manual instructions for the correct path. Today it reports "configured successfully" and drops a stray ~/.zshrc instead.
  • Script location. I kept the completion script itself in ~/.zsh/completions to keep the change small. People who set ZDOTDIR often prefer nothing new in $HOME, so I can move it under $ZDOTDIR if you prefer.
  • The spec. The cli-completion spec names ~/.zshrc literally. If you'd rather update the spec wording too, I'm happy to follow the feature flow.
  • Tests. The installer tests would also need to clear ZDOTDIR the way they already clear ZSH. Otherwise, on a machine with ZDOTDIR set, the suite would edit the developer's real .zshrc once the fix lands.

I found this while reading the installer code with Claude Code (Claude Opus 5.5), which also ran the reproduction above on my machine. I reviewed the report and the fix.

Lingua principale
TypeScript
Stelle
72.3k
Fork
4.9k
Merge medio
2g 10h
PR unite (30g)
72

Preparare l'ambiente

Apri in Codespaces

Avvia il container di sviluppo del progetto nel browser, con il tuo account GitHub.

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di Fission-AI/OpenSpec

Tutte le issue di Fission-AI/OpenSpec

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.