[Bug]: preset-provided scripts are never resolved — `type: script` and `$CORE_SCRIPT` have no effect
- 主要言語
- Python
- スター
- 137k
- フォーク
- 12.3k
- 平均マージ
- 2日 12時間
- マージ済み PR(30日)
- 159
説明
### Bug Description
The preset reference documents scripts as a first-class layer of the resolution stack:
> "Presets can provide command files, template files (like `plan-template.md`), and script files.
Templates and scripts are looked up from the stack when Spec Kit needs them.
Scripts support **replace** and **wrap**; script wrappers use `$CORE_SCRIPT` as the placeholder."
and lists the project-local override location as `.specify/templates/overrides/scripts/`.
None of this takes effect. A preset may declare `type: script`, and `specify preset add` accepts and
installs it without complaint, but **nothing ever asks the resolver for a script**, so the file that
actually runs is always the core one.
Three independent places in the shipped code show why:
1. **No caller requests the script type.** The only production call into preset composition
determines the type as
`template_type = "command" if is_command else "template"`
(`specify_cli/presets/_commands.py:495`). The value `"script"` is never passed, so
`PresetResolver.resolve()` / `collect_all_layers()` are never invoked for scripts — even though
both handle `template_type == "script"` (`specify_cli/presets/__init__.py:5524`, `5531`, `5613`,
and the `$CORE_SCRIPT` substitution at `:6168`).
2. **The Bash runtime resolves only `.md`.** `resolve_template()` in
`core_pack/scripts/bash/common.sh:509` looks for `"$base/overrides/${template_name}.md"`, and
every subsequent tier appends `.md` as well. There is no `.sh` branch and no
`overrides/scripts/` lookup anywhere in the file.
3. **The Python twin mirrors that.** `core_pack/scripts/python/common.py:308` documents its order as
"mirrors resolve_template in scripts/bash/common.sh" and resolves
`overrides/f"{template_name}.md"` only.
So the composition engine for scripts exists and is reachable by unit test, but is not wired to
anything that runs.
This looks like the script half of #2132 / #2133 never landed on the runtime side, while #3143
documented it as shipped. I could not find an existing report: no open issue or PR with "script" in
the title covers it (#1964 is adjacent but is about extensions and has been open since March 2026),
and #4443 / #4445 concern PyYAML availability, not resolution.
runs the command.
**Suggestion.** Either wire a caller for `template_type="script"` and add `.sh` resolution to
`common.sh` and its Python twin, or — if scripts are not meant to be resolvable yet — adjust
`docs/reference/presets.md` and have `preset.yml` validation reject `type: script` so the
declaration fails loudly instead of silently.
### Steps to Reproduce
```bash
# 1. Scaffold a project
mkdir demo && cd demo && git init
specify init . --integration claude --script sh --force
# 2. Record the core script's hash
sha256sum .specify/scripts/bash/setup-plan.sh
# 3a. Try the documented project-local override
mkdir -p .specify/templates/overrides/scripts
printf '#!/usr/bin/env bash\necho "OVERRIDE RAN"\n' \
> .specify/templates/overrides/scripts/setup-plan.sh
chmod +x .specify/templates/overrides/scripts/setup-plan.sh
# 3b. Or try a preset that provides the script
mkdir -p /tmp/p/scripts
cat > /tmp/p/preset.yml <<'YAML'
schema_version: "1.0"
preset:
id: "gate"
name: "Gate"
version: "1.0.0"
description: "Wraps setup-plan."
requires:
speckit_version: ">=1.0.0"
provides:
templates:
- type: "script"
name: "setup-plan"
file: "scripts/setup-plan.sh"
strategy: "wrap"
YAML
printf '#!/usr/bin/env bash\necho "BEFORE"\n$CORE_SCRIPT "$@"\n' > /tmp/p/scripts/setup-plan.sh
specify preset add --dev /tmp/p
# 4. Re-scaffold and compare
specify init . --integration claude --script sh --force
sha256sum .specify/scripts/bash/setup-plan.sh
```
### Expected Behavior
`.specify/scripts/bash/setup-plan.sh` is composed from the stack, so the wrapper runs first and
delegates to the core script through `$CORE_SCRIPT` — matching the documented behaviour that
"templates and scripts are looked up from the stack when Spec Kit needs them".
### Actual Behavior
The hash in step 4 is **identical** to step 2 and still matches
`.specify/integrations/speckit.manifest.json`. The override file and the preset-provided script are
never read. `specify preset add` reports success and `specify preset list` shows the preset as
enabled, so there is no signal that the declared script is inert.
Tried additionally, all without effect: `strategy: replace` as well as `wrap`,
`specify integration upgrade`, `specify init --here --force`. Same result on `1.0.1`.
### Specify CLI Version
1.0.6
### AI Agent
Claude Code
### Operating System
macOS 26.6.2
### Python Version
Python 3.11.15
### Error Logs
```shell
# There is no error output — that is part of the problem.
# A preset declaring a script installs cleanly and is reported as active:
$ specify preset add --dev /tmp/p
Installing preset from /tmp/p...
✓ Preset 'Gate' v1.0.0 installed (priority 10)
$ specify preset list
Installed Presets (in resolution order — highest precedence first)
Gate (gate) v1.0.0 — enabled — priority 10
Wraps setup-plan.
Templates: 1
# …while the script it provides is never resolved or executed.
```
### Additional Context
**Why this matters.** The documented mechanism is the natural way to add a step in front of a core
script: the preset wraps `setup-plan.sh`, the core script stays untouched underneath, and Spec Kit
maintains the relationship. Any preset that needs to run a check, a fetch, or a validation before
the command body reads its inputs wants exactly this.
**Current workaround, for anyone hitting the same wall.** Override the *command* instead of the
script. A preset providing `speckit.plan` with `strategy: "wrap"` and a five-line body:
```markdown
---
scripts:
sh: scripts/bash/setup-plan-wrapper.sh --json
---
{CORE_TEMPLATE}
```
points the materialised command at a project-owned script, which ends with
`exec "$ROOT/.specify/scripts/bash/setup-plan.sh" "$@"`. This works and survives upgrades, because
`{CORE_TEMPLATE}` keeps pulling the command body from core.
It has two costs that the documented mechanism would remove:
- **two artefacts instead of one.** The script cannot travel inside the preset, so it lives beside
it as a separate committed file, and it needs a distinct filename because it cannot replace
`setup-plan.sh`.
- **nothing validates the link.** A preset whose frontmatter names a script that does not exist
installs without any warning and is listed as healthy; the dead path only surfaces when a user
runs the command.
**Suggestion.** Either wire a caller for `template_type="script"` and add `.sh` resolution to
`common.sh` and its Python twin, or — if scripts are not meant to be resolvable yet — adjust
`docs/reference/presets.md` and have `preset.yml` validation reject `type: script` so the
declaration fails loudly instead of silently.
コントリビューションガイド
調査の方向性
Start with the listed scaffold and re-scaffold reproduction, then trace the caller at specify_cli/presets/_commands.py:495 into the script handling in specify_cli/presets/__init__.py. Compare the .md-only resolution paths in core_pack/scripts/bash/common.sh:509 and core_pack/scripts/python/common.py:308 with the existing script composition logic and its unit coverage. Done means the documented script behavior works end to end, or unsupported script declarations are rejected and the documentation is corrected.
索引モデルが issue の本文から書いたものです。
評価
- 技術スタック
- bash, python
- 領域
- cli, tooling
- issue の種類
- バグ
- 難易度
- 4/5
- 見積もり時間
- 3〜5日
- 活発さ
- 活発
- 明瞭さ
- おおむね明確
- 初心者へのやさしさ
- 58/100