Hacktoberfest 2026: los issues que los mantenedores marcaron para octubre, abiertos y aptos para principiantes. Explorar issues de Hacktoberfest

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

Cerrado Apto para principiantes
  • ¿Algo no está bien?
#2,138 0 comentarios 1 reacción 0 asignados Ver en GitHub

Los mantenedores suelen responder en 2 días

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
2/5
Tiempo estimado
1-3 horas
Aptitud para principiantes
75/100
Tipo de issue
Error
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
typescript, zsh
Área
cli

Línea de trabajo

Lee src/core/completions/installers/zsh-installer.ts, especialmente getZshrcPath() y las rutas de instalación, desinstalación e instrucciones manuales que lo usan. Revisa las pruebas del instalador y reproduce el caso con un HOME y un ZDOTDIR temporales; se considera terminado cuando la instalación y la desinstalación tienen como destino ${ZDOTDIR:-$HOME}/.zshrc e indican esa ruta, manteniendo el fallback existente cuando ZDOTDIR no está definido.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.

Lenguaje dominante
TypeScript
Estrellas
73k
Forks
5k
Merge medio
3 d 20 h
PR fusionados (30 d)
69

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de Fission-AI/OpenSpec

Todos los issues de Fission-AI/OpenSpec

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.