Repository navigation
Description
Problem
The shared prerequisite checker reports a Microsoft Store install of a tool as missing on Windows.
Since powershell-format moved to the node checker, a Windows CLI session with the Store build of
pwsh 7.6.6 prints at every SessionStart:
powershell-format: pwsh was not found on PATH. Hooks that need pwsh skip until it is installed.
pwsh works. The Store build resolves through an App Execution Alias,
%LOCALAPPDATA%\Microsoft\WindowsApps\pwsh.exe, which is on the user PATH. That alias is a reparse
point (IO_REPARSE_TAG_APPEXECLINK): fs.lstatSync reports isSymbolicLink() === true with
size 85, and fs.statSync throws EACCES.
On current main, isExecutable() in lib/prerequisites.mjs:244-252 calls
statSync(file).isFile() inside a try/catch, so the EACCES makes it return false. which()
(lib/prerequisites.mjs:255-266) then skips the alias and returns null, and detectEntry() for a
cli/runtime entry (lib/prerequisites.mjs:313-319) reports missing. The probe mode turns that
into the SessionStart notice. findLocalBin() (:268-280) and the system-lib branch (:330-333)
share the same helper and the same blind spot.
Impact is a false alarm, not lost formatting: the formatter hook itself resolves pwsh with
command -v pwsh (plugins/powershell-format/hooks/powershell-format.sh:124), which finds the
alias, so formatting still runs. The cost is a wrong notice every session that teaches users to
ignore prerequisite notices.
The bash probe this replaced (hooks/probe-prerequisite.sh:18 in powershell-format 0.9.11, removed
by #5980) used command -v, which does resolve the alias. That is why the notice started only after
the update.
This is not pwsh-specific. Any prerequisite installed from the Store or exposed only through a
WindowsApps alias (winget-installed tools, Store Python) gets the same false missing.
Evidence
Verified this pass:
lib/prerequisites.mjsread at origin/main:isExecutable()at:244-252,which()at
:255-266. The item cited:246-254; the code is unchanged, the lines shifted by two.- On a Windows machine with Store pwsh, against the installed powershell-format 0.9.14 copy of the
lib (byte-identical function to main):- The installed copy's
isExecutable()andwhich()bodies diff identical to origin/main's. node --input-type=module -e "import {which} from 'file:///<plugin-root>/lib/prerequisites.mjs'; console.log(which('pwsh'))"
printsnull.command -v pwshprints/c/Users/<user>/AppData/Local/Microsoft/WindowsApps/pwsh.
- The installed copy's
- powershell-format 0.9.11's
hooks/probe-prerequisite.sh:18iscommand -v "$1" >/dev/null 2>&1 && return 0. - powershell-format on main declares pwsh as
kind: cli,need: required,
for: hook:powershell-format.sh,detect.any: ["pwsh"], no version floor
(plugins/powershell-format/prerequisites.json), and wires the probe through
plugins/powershell-format/hooks/hooks.json:51. lib/prerequisites.mjsis registered inscripts/shared-copies.txtwith 60 generated copies
(list below).- No existing issue covers this. Searched open and closed issues for WindowsApps, App Execution
Alias, and prerequisites/pwsh not found. Related but distinct: fix(disk-hygiene): setup check detects Windows Store python3 alias stub fail-open (F3) #1110 (disk-hygiene, Store python3
alias stub fail-open).
From the item, not re-run here (no extra live probes were allowed): the lstatSync /
statSync shape of the alias (isSymbolicLink() === true, size 85, EACCES).
Inferred, not verified: that fs.readlinkSync on an APPEXECLINK returns the alias target path
(libuv reads that reparse tag in its readlink). The implementer must confirm this on a real alias
before relying on it.
Proposed approach
The fix has a trap: WindowsApps also holds "install me" stubs. On stock Windows,
WindowsApps\python.exe and python3.exe exist when Python is NOT installed; running them opens
the Store or exits without doing anything (#1110). Today the stat failure hides those stubs, which
is accidentally correct. Counting every WindowsApps alias as found would flip these entries to a
false present, because they declare Python with no version floor that would catch the stub:
runtime, no version: code-metrics, code-tidying, evals, harness-config, planningcli, no version: machine-health, pixel-art, repo-fleet-hygiene, retro-audio, review
Stub rejection protects every Python entry, not only those. A python.org install ships python.exe
and py.exe but no python3.exe (installer layout, not re-verified here). Most entries list
python3 first in detect.any, and which() takes the first name that resolves. On such a host
the only python3 on PATH is the WindowsApps stub, so accepting stubs would pick it ahead of the
real python: python-pkg entries would flip to a false missing (the import probe runs the
stub), and entries with a version block would degrade to unverified.
So the recommended change to lib/prerequisites.mjs:
- In
isExecutable(), on win32 only, whenstatSyncthrows,lstatSyncthe candidate. If it is
a symlink/reparse point, accept it only when it is a real app alias, not an installer stub. - Distinguish the two by the alias target's executable name, not its package. Resolve the target
withreadlinkSync(confirm first that it reads APPEXECLINK) and treat the Python redirector
stub target as not found; everything else counts as found andwhich()returns the alias path.
Do not reject by package: the Python stubs and winget's own alias are both owned by App
Installer (Microsoft.DesktopAppInstaller_*), so a package rule would also hide winget. Confirm
the exact stub target file name on a real host with Python not installed. - If
readlinkSynccannot read the tag, fall back to the narrower rule: accept a WindowsApps
reparse point only when the name is not one of the known stub names (python,python3), and
keep reporting those as missing. Say which rule shipped in the PR.
Alternatives considered:
- Shell out to
where.exeorcommand -vwhen the scan fails (the item's second suggestion).
Rejected as the primary fix: it spawns a process per lookup in a SessionStart hook, adds a
dependency on which shell is present, andwhere.exealso lists the Python stubs, so it does not
solve the stub problem. - Accept any WindowsApps reparse point (the item's first suggestion as written). Rejected for the
Python-stub regression above. - Add version floors to every Python entry so stubs land in
unverified. Out of scope here; it
touches 10 manifests and still reports a stub as something other than missing.
Files to change: lib/prerequisites.mjs, lib/prerequisites.test.mjs, then regenerate the copies
with scripts/sync-shared-copies.sh and bump every carrying plugin.
Acceptance criteria
- On win32,
which("pwsh")returns the WindowsApps alias path when pwsh is installed from the
Store, andprerequisites.mjs probefor powershell-format emits no notice. - On win32, a Store "install me" stub (for example
python3.exewith Python not installed) is
still reported asmissing, notpresent. - On win32, with a stub
python3alias and a realpythonboth on PATH, resolving
["python3", "python"]returns the realpython. - A WindowsApps alias whose target is not the Python redirector (for example winget's) is
reported as found. - Behavior on Linux and macOS is unchanged (the new branch is gated on
platform === "win32"). -
lib/prerequisites.test.mjshas a case for the alias rule. The real reparse point cannot be
created in a test, so the stat calls the rule depends on are injectable (or the rule lives in
a small pure function taking the lstat result and link target) and the test feeds a
Store-alias shape and a stub shape. -
scripts/sync-shared-copies.sh --checkpasses and--check-bump origin/mainreports every
carrying plugin bumped. - Each carrying plugin's CHANGELOG has the entry; powershell-format's names the false pwsh
notice as the user-visible fix.
Constraints and gotchas
- The SessionStart notice is a hook false positive, so the repo's hook-precision rule applies: the
fix lands with a stay-quiet test that fails before the fix
(docs/conventions/hook-precision/README.md#the-discipline). The Store-alias test case in the
acceptance criteria is that test; confirm it fails against the unpatchedisExecutable(). - Never edit a copy under
plugins/*/lib/prerequisites.mjs. Each is generated from the canonical
lib/prerequisites.mjswith a header; edit the canonical and runscripts/sync-shared-copies.sh
(ADR 0019).--checkfails CI if a copy drifts. - Changing the canonical requires a version bump in every carrying plugin;
scripts/sync-shared-copies.sh --check-bump <base>enforces it. A plugin whose only change is the
sync takes the CHANGELOG line the script prints: "Sharedprerequisites.mjssynced (); no
change to this plugin's ...". - The 60 carrying plugins (from
scripts/shared-copies.txt): actionlint, ai-briefing, ai-slop,
animation, architecture, attribution, autonomy, bash-format, biome-format, code-metrics,
code-tidying, context-budget, context-guard, context7, desktop-notification, disk-hygiene,
docs-hygiene, docs-naming, dometrain, eol-normalizer, evals, explainer-video, firecrawl, gaming,
go-format, guardrails, harness-config, harness-ops, instruction-placement, kindle-dedrm,
knowledge, machine-health, markdown-format, mcp-tools, miro, multi-agent, pixel-art, planning,
playbooks, playwright, plugin-quality, powershell-format, rate-limit-guard, repo-fleet-hygiene,
repo-hygiene, retro-audio, review, ruff-format, session-flow, skill-quality, songwriting,
source-control, speech, testing, toolchain, typos-format, visualization, wizard, work-items, x. - Spawning the found path still works for a real alias:
CreateProcesslaunches App Execution
Aliases, so theversion,system-libandpython-pkgprobes thatrun()the found binary are
unaffected oncewhich()returns it. - The checker runs in a SessionStart hook and must exit 0 on a valid manifest; keep the new branch
inside the existing try/catch so an unexpectedlstat/readlinkerror degrades to "not found",
never to a thrown error. - fix(disk-hygiene): setup check detects Windows Store python3 alias stub fail-open (F3) #1110 already established that the Store Python stub is a fail-open vector for disk-hygiene; do
not regress that by making the shared checker call the stub present.
Context
Source: local handoff item 20261003-152816-prerequisites-mjs-store-app-alias-false-missing.md
(retired into this issue), raised from a Windows CLI session on Claude Code 2.1.288.
Related: #5919 (introduced lib/prerequisites.mjs), #5980 (converted plugins to it and removed the
bash probe-prerequisite.sh), #5468 (the earlier bash probes), #1110 (Store python3 stub).
Activity
fix(prerequisites): let an entry reject Store App Execution Aliases