Windows/Git Bash: python3 App Execution Alias stub defeats feature.json parser fallback in common.sh (sh variant)

[dulguun0225]

Summary

On a stock Windows machine (Git for Windows only — no jq, no real Python on PATH), every bash-variant script that reads .specify/feature.json fails with ERROR: Feature directory not found ... immediately after a successful specify init --script sh. The cause is that the JSON parser fallback chain in common.sh selects python3 based on existence (command -v), but on Windows python3 resolves to the Microsoft Store App Execution Alias stub, which exists on PATH yet fails at runtime. The chain then swallows the runtime failure and returns an empty value, and the grep/sed last-resort parser is unreachable because the chain is if/elif/else on availability, not on parse success.

Environment

• Spec Kit v0.12.3 (installed via uv tool/uvx from the git tag)
• Windows 11, Git for Windows (bash 5.2.37, MSYS), run under Git Bash
• No jq installed (Git for Windows does not ship one)
• No real Python on PATH; C:\Users\<user>\AppData\Local\Microsoft\WindowsApps\python3.exe stub present (Windows default)

Reproduction

# on the machine described above, in Git Bash
uvx --from "git+https://github.com/github/spec-kit.git@v0.12.3" \
  specify init target --integration generic \
  --integration-options "--commands-dir .agent/commands" \
  --script sh --ignore-agent-tools
cd target && git init -b main . && git add -A && git commit -m scaffold
bash .specify/scripts/bash/create-new-feature.sh --json --short-name demo "demo feature"
# ^ succeeds, persists .specify/feature.json = {"feature_directory":"specs/001-demo"}
bash .specify/scripts/bash/setup-plan.sh --json
# ERROR: Feature directory not found. Set SPECIFY_FEATURE_DIRECTORY or ensure
#        .specify/feature.json contains feature_directory.

feature.json exists and contains the key — it just can't be read:

$ command -v python3
/c/Users/<user>/AppData/Local/Microsoft/WindowsApps/python3
$ python3 -c "print(42)"; echo exit=$?
Python was not found; run without arguments to install from the Microsoft Store, ...
exit=49

Root cause

scripts/bash/common.sh, read_feature_json_feature_directory() (v0.12.3, ~lines 95–120):

if command -v jq >/dev/null 2>&1; then
    ... jq ...
elif command -v python3 >/dev/null 2>&1; then   # <- stub passes this test
    if ! _fd=$(python3 -c "..." 2>/dev/null); then  # <- fails at runtime (exit 49)
        _fd=''                                       # <- failure swallowed
    fi
else
    ... grep/sed fallback ...                        # <- unreachable
fi

create-new-feature.sh masks the problem on its own persist path (it falls back to printf for writing), so the failure only appears one script later, which makes it look like state corruption rather than a parser issue.

Notably, CI runners (GitHub Actions windows-latest etc.) never see this: they ship both jq and a real python3. It only bites real end-user Windows machines — which are exactly the machines the sh-variant + Git Bash path is meant to serve.

Suggested fix

Any of these would do (first is smallest):

1. Runtime-probe instead of existence-probe: python3 -c 'print(0)' >/dev/null 2>&1 before committing to the python3 branch (the stub also fails this, exit 49).
2. Fall through the chain on parse failure rather than returning empty (jq → python3 → grep/sed as successive attempts, not exclusive branches).
3. Prefer python over python3 on MSYS/Windows, or check both.

The same existence-vs-runtime pattern may exist in other scripts that shell out to python3; worth a quick grep.

Workaround (for anyone else hitting this)

Install jq, disable the python3 App Execution Alias, or expose a real interpreter as python3 (e.g. one managed by uv python install).

[github-actions]

Bug assessment — windows-python3-stub-parser: Valid · severity medium

---

Bug Assessment: Windows python3 stub defeats feature.json parser fallback

• Slug: windows-python3-stub-parser
• Created: 2026-07-02T13:13:29Z
• Source: issue Windows/Git Bash: python3 App Execution Alias stub defeats feature.json parser fallback in common.sh (sh variant) #3304
• Verdict: valid
• Severity: medium

Report (summarized)

Reported by @dulguun0225. On Windows 11 with Git Bash (no jq; no real Python — only the Microsoft Store App Execution Alias stub on PATH), running bash .specify/scripts/bash/setup-plan.sh --json after a successful create-new-feature.sh call fails with:

ERROR: Feature directory not found. Set SPECIFY_FEATURE_DIRECTORY or ensure
       .specify/feature.json contains feature_directory.

The file exists and contains the correct feature_directory key. The reporter correctly identified that command -v python3 returns success for the Windows Store stub, which then fails at runtime (exit 49), and the else (grep/sed) fallback branch is never reached.

Symptom

read_feature_json_feature_directory() in scripts/bash/common.sh returns an empty string on Windows/Git Bash when no jq is available and python3 resolves to the Windows Store stub, because the parser-selection chain is structured as if/elif/else on tool existence rather than on parse success. get_feature_paths() then emits the "Feature directory not found" error even though .specify/feature.json is present and valid.

Reproduction

1. Windows 11 + Git Bash (MSYS), no jq installed, python3 is only the Windows Store stub.
2. Run uvx specify init target --integration generic --script sh --ignore-agent-tools
3. cd target && git init -b main . && git add -A && git commit -m scaffold
4. bash .specify/scripts/bash/create-new-feature.sh --json --short-name demo "demo feature" — succeeds; writes .specify/feature.json = {"feature_directory":"specs/001-demo"}
5. bash .specify/scripts/bash/setup-plan.sh --json — fails with "Feature directory not found".
6. Verify: command -v python3 returns the stub path; python3 -c "print(42)" exits 49 without executing.

Suspected Code Paths

• scripts/bash/common.sh:101–116 — read_feature_json_feature_directory(): the if/elif/else chain at lines 101, 105, 110. The elif command -v python3 >/dev/null 2>&1 (line 105) succeeds for the stub, entering the python3 branch. The inner if ! _fd=$(python3 -c "..." 2>/dev/null) at line 107 does detect the failure (exit 49, with stderr suppressed), setting _fd=''. But the else grep/sed branch at lines 110–116 is unreachable once the elif fires.
• scripts/bash/common.sh:185–194 — get_feature_paths(): calls read_feature_json_feature_directory() at line 187; if that returns empty (line 188), line 193 emits the "Feature directory not found" error and returns 1.
• scripts/bash/setup-plan.sh:31 — calls get_feature_paths via common.sh; line 31 || { echo "ERROR..."; exit 1; } propagates the failure.

Secondary occurrences of command -v python3 in common.sh (lines 251, 355, 447, 467) use patterns that already handle python3 runtime failure gracefully (else separator="." or unordered fallback scan), so they are not blocking in this scenario.

Root Cause Hypothesis

The read_feature_json_feature_directory() function (lines 95–120 of common.sh) selects the JSON parser tool once via an existence probe (command -v) and enters the chosen branch exclusively. When the Windows Store python3 stub exists on PATH, command -v python3 succeeds, the elif branch is entered, and the stub's runtime failure only produces an empty _fd — it does not fall through to the grep/sed parser. The grep/sed branch is architecturally unreachable whenever command -v python3 returns 0, regardless of whether python3 can actually execute code.

Confidence: high. The code path is directly readable in common.sh lines 101–116 and matches the reporter's detailed analysis exactly.

Proposed Remediation

Preferred — runtime probe instead of existence probe (smallest change):

Replace the command -v python3 existence check with a runtime capability probe before entering the python3 branch:

# Before: existence check (passes for the Windows Store stub)
elif command -v python3 >/dev/null 2>&1; then

# After: runtime capability check (the stub exits 49; a real interpreter exits 0)
elif python3 -c '' >/dev/null 2>&1; then

python3 -c '' (execute an empty string) is a minimal no-op that succeeds for any real Python interpreter and fails with exit 49 for the Windows Store stub. This is a two-word change, preserves all existing behavior on non-Windows platforms, and requires no refactoring of the chain.

Alternative — fall-through on empty result:

Convert the if/elif/else to successive attempts, falling through to the next parser whenever the current one returns an empty value. This is more robust in general (e.g., handles broken jq installs), but is a larger change and could mask unexpected failures silently.

Files likely to change:

• scripts/bash/common.sh (line 105: replace the elif command -v python3 condition)
• Tests for read_feature_json_feature_directory() (see below)

Tests to add or update:

• A unit/integration test that stubs python3 as a non-executable (or an alias that exits non-zero) and asserts that read_feature_json_feature_directory() still returns the correct value from a valid feature.json via the grep/sed fallback.
• A test for the full setup-plan.sh call with no jq and no real python3, verifying it completes without error when feature.json is present and well-formed.

Risks & Considerations

• Blast radius is narrow: only affects users on Windows/Git Bash with no jq and only the Store stub on PATH. CI (windows-latest) ships both jq and real Python, so the CI green status is misleading for this specific platform configuration.
• No breaking change: python3 -c '' is supported since Python 2.6+; any real interpreter will pass it.
• Diagnostic gap: The error message "Feature directory not found" is attributed to a missing or unreadable feature.json, not a parser failure. A more actionable error when all parsers return empty would help future diagnosis.
• Other command -v python3 calls: Lines 251, 355, 447, and 467 in common.sh all use command -v python3 but each has an inner fallback that handles runtime failure independently. They should be audited for the same probe upgrade for consistency, but they are not currently blocking.

Open Questions

• [NEEDS CLARIFICATION: Does the project have an automated test matrix that runs against a Git Bash environment without jq? If not, the fix should be accompanied by a CI job or documented manual test step covering this configuration.]

---

Posted on behalf of @mnriem by GitHub Copilot (model: claude-sonnet-4.6, autonomous)

Generated by 🐛 Assess Bug from Labeled Issue for issue #3304 · 166.6 AIC · ⌖ 22.5 AIC · ⊞ 31.8K · ◷