Skip to content

Fix nushell completion path; adopt shared install helpers - #191

Merged
l1a merged 1 commit into
mainfrom
chore/standardise-install-helpers
Aug 13, 2026
Merged

Fix nushell completion path; adopt shared install helpers#191
l1a merged 1 commit into
mainfrom
chore/standardise-install-helpers

Conversation

@l1a

@l1a l1a commented Aug 12, 2026

Copy link
Copy Markdown
Owner

Description

The bug: scripts/install_completions.py wrote nushell completions to
$XDG_CONFIG_HOME/nushell/autoload. On Windows $nu.user-autoload-dirs is exactly
%APPDATA%\nushell\autoload — one entry — and nushell there never reads the XDG path, whatever
XDG_CONFIG_HOME says. So the helper wrote a real file to a directory nothing consults, printed
that path, and delivered nothing. Measured in rusticprofile (its 0.2.14), where the same defect
explained shell aliases missing for months while present in the dotfiles the whole time.

Two more in the same helper. It logged a generation failure to stderr, continued, and then ran
print("Installed completions for retch:") plus the full path list unconditionally — success
reported over work not done. And nothing checked whether zsh would ever load the file; it now asks
an interactive zsh, because a non-interactive one sources neither .zshrc nor anything it
includes and so returns the built-in fpath, getting the answer wrong just as confidently.

This repo's mechanism was right, and is now the standard

v0.6.16 moved these recipes to Python so they run natively on Windows without Git's usr\bin.
rusticprofile first proposed replacing them with plain-sh recipes because it held the
correctness fixes — which would have regressed that portability work in the name of consistency.
Each repo had solved half the problem. The shared standard keeps retch's mechanism and
rusticprofile's correctness.

scripts/install_completions.py, scripts/install_man.py and templates/justfile-common.just are
now vendored byte-identically across retch, rusticprofile and etr (TEMPLATE_VERSION = 2).
Project facts (BINS, MAN_PAGES) sit in a PROJECT header above the marked block, because etr
ships two binaries and a block with a hardcoded name cannot be copied.

just standard-check runs the helpers' --self-test; just check depends on it. Not a text
diff — three separate repos cannot diff each other's files, and a diff would pass happily on a repo
that never adopted the standard.

Also: install-tag VERSION

Installs a released tag with all three artefacts from that tag: binary via cargo install --git --tag, completions from the installed binary so they cannot disagree with its CLI, man page from
the tag via git show. It deliberately does not depend on install-man/install-completions, which
work from the checkout — reusing them would pair a tag's binary with the worktree's man page.
Prompted by a fleet host found running a current binary beside a man page eleven releases old.

Type of change

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • This change requires a documentation update

How Has This Been Tested?

  • just pr green: fmt, clippy --workspace and --features graphics, 69 + 114 + 15 tests,
    man regen at retch 0.6.20, audit advisory-only.
  • The self-tests were watched failing, and the first is literally this bug: reverting the
    nushell line reports windows nushell dir: expected …AppData\Roaming… got …/.config/….
    Dropping a shell and treating an empty XDG variable as a location also fail.
  • Exit codes checked without a pipe — an earlier check read $? from head and reported
    exit 0 on a failing self-test.
  • A generation failure now aborts with no Installed line (verified with a bad binary name).
  • Recipe inventory vs HEAD: exactly two additions (install-tag, standard-check), none
    removed. just --list parses.
  • The vendored helpers are byte-identical (sha256) to rusticprofile's copies.

Backup safety

n/a — tooling only; no repository or filesystem writes beyond the completion/man install paths.

Checklist:

  • Style, self-review, comments
  • Documentation updated — wiki pushed before this PR per AGENTS §4.8
    (Development-Setup.md, 7fc584f..03796ba)
  • just man re-run after the bump and committed
  • No new warnings
  • Tests added that prove the fix — the self-tests are the test, watched failing
  • Existing tests pass
  • No failure mode introduced can degrade silently — the helper raises rather than reporting
    success, and standard-check fails the build on a violation

install_completions.py wrote nushell completions to
$XDG_CONFIG_HOME/nushell/autoload. On Windows
$nu.user-autoload-dirs is exactly %APPDATA%\nushell\autoload and
nushell never reads the XDG path, so the helper wrote a real file
somewhere nothing consults, printed the path, and delivered nothing.

Two more defects in the same helper: it logged a generation failure
to stderr, continued, and then printed "Installed completions for
retch:" unconditionally -- success reported over work not done; and
nothing checked whether zsh would ever load the file (it reads only
directories on fpath, and site-functions is not on it by default).
It now checks, via an INTERACTIVE zsh, since a non-interactive one
reports the built-in default.

This repo's MECHANISM was right and is now the standard. v0.6.16
moved these recipes to Python so they run natively on Windows
without Git's usr\bin; rusticprofile first proposed replacing them
with sh recipes because it held the correctness fixes, which would
have regressed that work in the name of consistency. Each repo had
solved half the problem.

install_completions.py and install_man.py are now vendored
byte-identically across retch, rusticprofile and etr, with
templates/justfile-common.just as the Justfile block reference.
standard-check runs their self-tests -- not a text diff, since
separate repos cannot diff each other's files and a diff would pass
on a repo that never adopted the standard -- and check depends on it.

Also adds install-tag VERSION, which installs a released tag with
binary, completions (from the INSTALLED binary) and man page (from
the tag) so the three cannot disagree.

Assisted-By: Claude Opus 5
@l1a
l1a merged commit fbd7682 into main Aug 13, 2026
18 checks passed
@l1a
l1a deleted the chore/standardise-install-helpers branch August 13, 2026 00:11
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