fix: unofficial PyPI warning (#1982) and legacy extension command name auto-correction (#2017) by mbachorik · Pull Request #2027 · github/spec-kit

mbachorik · 2026-03-30T21:25:33Z

Summary

[Bug]: 0.4.2 removed "extension" command from specify #1982 — Adds a clear warning to `README.md` and `docs/installation.md` that the only official packages are published from `github/spec-kit`; any same-named PyPI packages are unaffiliated. Also adds `specify version` as a recommended post-install verification step.
[Bug]: PR #1776 alias validation breaks all community extensions — alias pattern not documented #2017 — Instead of hard-failing when a community extension uses a legacy command/alias name, auto-correct it to the required pattern and emit a compatibility warning. Names that cannot be safely corrected still raise `ValidationError`.
Bonus — Fixes a pre-existing flaky test (`TestPresetCatalog::test_search_with_cached_data`) that was making live network calls to the community catalog.

Changes

`docs/installation.md` / `README.md`

Warning block clarifying GitHub is the only official source
`specify version` verification step added after install instructions

`src/specify_cli/extensions.py`

`ExtensionManifest._validate()`: auto-corrects legacy 2-part primary command names (`{ext_id}.cmd` or `speckit.cmd` → `speckit.{ext_id}.cmd`), emitting compatibility warnings; names that cannot be safely corrected still raise `ValidationError`
Alias names follow the same correction path via `_try_correct_command_name()` — no separate alias helper
Hook `command` refs are rewritten when they point at a renamed command; alias-form refs (`{ext_id}.cmd`) are also canonicalized to `speckit.{ext_id}.cmd`; a warning is emitted whenever any rewrite occurs
Individual hook entries validated as dicts — non-mapping entries raise `ValidationError` instead of silently skipping (which would crash `HookExecutor.register_hooks()` later)
`_try_correct_command_name()`: static helper covering both `speckit.cmd` and `{ext_id}.cmd` legacy forms for primary commands and aliases

`src/specify_cli/init.py`

`extension_add`: prints compatibility warnings from `manifest.warnings` after successful install
`extension_remove` confirmation: correct singular/plural (`1 command` vs `N commands`)

`src/specify_cli/agents.py`

`CommandRegistrar.unregister_commands()`: removes empty skill parent directories after unlinking SKILL.md files, preventing orphaned `.claude/skills/speckit-*/` dirs

`tests/test_extensions.py`

`TestExtensionManifest`: new tests covering primary/alias auto-correction, hook ref rewriting and canonicalization, non-dict hook entry validation
`TestCommandRegistrar`: `test_unregister_skill_removes_parent_directory` covering orphaned dir cleanup
`TestExtensionRemoveCLI`: CLI tests covering singular/plural command count in removal confirmation

`tests/test_presets.py`

`test_search_with_cached_data`: patched to use `unittest.mock.patch` on `get_active_catalogs` to isolate test from live community catalog network calls

Test plan

Unit tests

160 extension tests pass (pytest tests/test_extensions.py)
Full suite passes

Live integration tests (real CLI, real filesystem, temp project dir)

All scenarios run against the workspace CLI with actual specify extension add/remove invocations:

Well-formed extension (foobar test extension):

✓ Extension installed successfully!
✓ .specify/extensions/foobar/ exists
✓ 11 command files created in .claude/commands/
✓ No compatibility warnings emitted

Legacy 2-part command name (foobar.hello → speckit.foobar.hello):

✓ Extension installed successfully!
⚠  Compatibility warning: Command name 'foobar.hello' does not follow the required
   pattern 'speckit.{extension}.{command}'. Registering as 'speckit.foobar.hello'.
   The extension author should update the manifest to use this name.
✓ Command file registered under canonical name

Hook with alias-form ref (foobar.hello → speckit.foobar.hello):

✓ Extension installed successfully!
⚠  Compatibility warning: Hook 'after_tasks' referenced command 'foobar.hello';
   updated to canonical form 'speckit.foobar.hello'. The extension author should
   update the manifest.

Non-dict hook entry (install must fail):

Validation Error: Hook 'after_tasks' must be a mapping, got str
✓ Extension not installed (install correctly aborted)

Remove — singular (1 command):

⚠  This will remove:
   • 1 command per agent

Remove — plural (2 commands):

⚠  This will remove:
   • 2 commands per agent

🤖 Generated with Claude Code

…ication (github#1982) Clarify that only packages from github/spec-kit are official, and add `specify version` as a post-install verification step to help users catch accidental installation of an unrelated package with the same name. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

This PR improves user safety and extension compatibility by warning against unofficial PyPI packages, adding a post-install verification step, and making legacy community extension command names auto-correct (with warnings) instead of hard-failing. It also stabilizes a previously flaky preset-catalog test by preventing unintended live community catalog lookups.

Changes:

Add prominent documentation warnings that Spec Kit’s official packages are only distributed from github/spec-kit, plus a recommended specify version verification step.
In extension manifest validation, auto-correct common legacy 2-part command names to the required 3-part speckit.{extension}.{command} form and surface compatibility warnings on install.
Make TestPresetCatalog::test_search_with_cached_data deterministic by restricting catalogs to default-only via a project-level preset-catalogs.yml.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`README.md`	Adds an “official source only” warning and a `specify version` verification step after install instructions.
`docs/installation.md`	Adds the same warning and a verification section recommending `specify version`.
`src/specify_cli/extensions.py`	Adds command-name regex constant, manifest `warnings`, and auto-correction logic for legacy command names.
`src/specify_cli/__init__.py`	Prints manifest compatibility warnings after successful `specify extension add`.
`tests/test_extensions.py`	Adds tests for both auto-correction paths and the no-warning valid path; updates an existing docstring.
`tests/test_presets.py`	Writes `.specify/preset-catalogs.yml` in a test to avoid community-catalog network flakiness.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/specify_cli/extensions.py

tests/test_presets.py

…iling (github#2017) Community extensions that predate the strict naming requirement use two common legacy formats ('speckit.command' and 'extension.command'). Instead of rejecting them outright, auto-correct to the required 'speckit.{extension}.{command}' pattern and emit a compatibility warning so authors know they need to update their manifest. Names that cannot be safely corrected (e.g. single-segment names) still raise ValidationError. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

… network calls test_search_with_cached_data asserted exactly 2 results but was getting 4 because _get_merged_packs() queries the full built-in catalog stack (default + community). The community catalog had no local cache and hit the network, returning real presets. Writing a project-level preset-catalogs.yml that pins the test to the default URL only makes the count assertions deterministic. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

The upstream github#1994 added alias validation in _collect_manifest_command_names, which also rejected legacy 2-part alias names (e.g. 'speckit.verify'). Extend the same auto-correction logic from _validate() to cover aliases, so both 'speckit.command' and 'extension.command' alias formats are corrected to 'speckit.{ext_id}.{command}' with a compatibility warning instead of hard-failing. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/specify_cli/extensions.py

tests/test_extensions.py

mnriem

Please address Copilot feedback. If not applicable, please explain why

- _try_correct_command_name: only correct 'X.Y' to 'speckit.ext_id.Y' when X matches ext_id, preventing misleading warnings followed by install failure due to namespace mismatch - _validate: add aliases type/string guards matching _collect_manifest _command_names defensive checks - _validate: track command renames and rewrite any hook.*.command references that pointed at a renamed command, emitting a warning - test: fix test_command_name_autocorrect_no_speckit_prefix to use ext_id matching the legacy namespace; add namespace-mismatch test - test: replace redundant preset-catalogs.yml isolation with monkeypatch.delenv("SPECKIT_PRESET_CATALOG_URL") so the env var cannot bypass catalog restriction in CI environments Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/specify_cli/extensions.py

tests/test_presets.py

mnriem

Please address Copilot feedback

mbachorik · 2026-04-01T11:27:49Z

@mnriem I've bundled this with the fix for 2/3dot alias notation. Will wait for feedback from the reporter (or we decide tonight and agree on fix). Will address all copilot feedback as usual .. (switching it to draft so it does not spam you)

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/specify_cli/extensions.py

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/specify_cli/extensions.py

tests/test_extensions.py

src/specify_cli/extensions.py

For SKILL.md-based agents (codex, kimi), each command lives in its own subdirectory (e.g. .agents/skills/speckit-ext-cmd/SKILL.md). The previous unregister_commands() only unlinked the file, leaving an empty parent dir. Now attempts rmdir() on the parent when it differs from the agent commands dir. OSError is silenced so non-empty dirs (e.g. user files) are safely left. Adds test_unregister_skill_removes_parent_directory to cover this. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

mbachorik · 2026-04-11T06:54:50Z

Fixed (#3067647278). Implemented the cleanup in unregister_commands():

After unlinking SKILL.md, attempts parent.rmdir() when the parent differs from the agent commands dir (i.e. it's a SKILL.md subdirectory, not a flat file). OSError is silenced so non-empty dirs are left untouched. Added test_unregister_skill_removes_parent_directory to cover this. 161 tests pass.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

mbachorik · 2026-04-11T09:33:58Z

All comments addressed.

mnriem · 2026-04-13T12:00:06Z

Are we still supporting the original aliasing? We need to give users time to migrate especially since it break extensions. I already reverted that part in an earlier PR, but I do not want to reintroduce the hard change now. We should reserve that for a later date.

mnriem

See comments above

Aliases are intentionally free-form to preserve community extension compatibility (e.g. 'speckit.verify' short aliases used by spec-kit-verify and other existing extensions). This aligns _validate() with the intent of upstream commit 4deb90f (fix: restore alias compatibility, github#2110/github#2125). Only type and None-normalization checks remain for aliases. Pattern enforcement continues for primary command names only. Updated tests to verify free-form aliases pass through unchanged with no warnings instead of being auto-corrected. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

mbachorik · 2026-04-14T16:35:01Z

Fixed. Removed alias pattern enforcement from _validate() entirely — aliases are now free-form, matching the intent of your upstream fix in #2125 (4deb90f). Only type and None-normalization checks remain; primary command names still enforce the 3-part speckit.{extension}.{command} pattern.

Verified end-to-end: a spec-kit-verify-style extension with a speckit.verify alias installs, registers (speckit-verify/SKILL.md), and unregisters cleanly with no warnings.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated 2 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

src/specify_cli/extensions.py

mnriem

Please address Copilot feedback. Thank you for staying with it!

Copilot

Pull request overview

This PR improves user guidance around unofficial PyPI packages and increases backward compatibility for community extensions by auto-correcting certain legacy command names, while also tightening/covering related behaviors with additional tests.

Changes:

Add documentation warnings that the official Spec Kit packages are sourced from github/spec-kit, plus a post-install specify version verification step.
Extend extension manifest validation to auto-correct legacy 2-part primary command names and rewrite hook command references, emitting compatibility warnings.
Improve uninstall cleanup (remove empty SKILL parent directories) and add/adjust tests, including isolating a previously flaky preset catalog test from network access.

Show a summary per file

File	Description
`docs/installation.md`	Adds prominent warning about unofficial PyPI packages and adds a verification step.
`README.md`	Adds the same warning + verification step to the main install instructions.
`src/specify_cli/extensions.py`	Adds `manifest.warnings`, legacy command auto-correction, and hook command ref rewriting.
`src/specify_cli/__init__.py`	Prints compatibility warnings after extension install and fixes remove confirmation pluralization.
`src/specify_cli/agents.py`	Removes empty SKILL parent directories after unregistering commands.
`tests/test_extensions.py`	Adds coverage for command auto-correction, hook rewriting, SKILL dir cleanup, and removal prompt wording.
`tests/test_presets.py`	Ensures cached-search test is deterministic and isolated from live network catalogs.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Files reviewed: 7/7 changed files
Comments generated: 1

src/specify_cli/extensions.py

mbachorik · 2026-04-14T19:59:44Z

@mnriem should ok now - there's no additional fix.

mnriem · 2026-04-14T20:05:20Z

@mbachorik Looks like it found one!

mbachorik · 2026-04-14T20:35:33Z

it's like a Russian roulette .. looking (before I crash for tonight)

If provides.commands contains a non-mapping entry (e.g. an int or string), 'name' not in cmd raises TypeError instead of a user-facing ValidationError. Added isinstance(cmd, dict) check at the top of the loop. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

mbachorik · 2026-04-14T20:39:59Z

Fixed comment #3082042943. Added isinstance(cmd, dict) at the top of the command loop — a non-mapping entry (e.g. an int or string) now raises ValidationError: Each command entry in 'provides.commands' must be a mapping instead of letting "name" not in cmd propagate a TypeError.

Copilot

Pull request overview

Copilot reviewed 7 out of 7 changed files in this pull request and generated no new comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

mbachorik · 2026-04-15T08:34:44Z

@mnriem no new comments from copilot (at least for me).

mbachorik requested a review from mnriem as a code owner March 30, 2026 21:25

Copilot AI review requested due to automatic review settings March 30, 2026 21:25

Copilot started reviewing on behalf of mbachorik March 30, 2026 21:26 View session

Copilot AI reviewed Mar 30, 2026

View reviewed changes

src/specify_cli/extensions.py Show resolved Hide resolved

tests/test_presets.py Outdated Show resolved Hide resolved

iamaeroplane and others added 2 commits March 30, 2026 23:31

mbachorik force-pushed the fix/pypi-warning-and-legacy-extension-names branch from 56c6b66 to 44d1996 Compare March 30, 2026 21:33

Copilot AI review requested due to automatic review settings March 30, 2026 21:47

Copilot started reviewing on behalf of mbachorik March 30, 2026 21:48 View session

Copilot AI reviewed Mar 30, 2026

View reviewed changes

src/specify_cli/extensions.py Outdated Show resolved Hide resolved

src/specify_cli/extensions.py Outdated Show resolved Hide resolved

tests/test_extensions.py Outdated Show resolved Hide resolved

mnriem requested changes Mar 31, 2026

View reviewed changes

mnriem requested a review from Copilot March 31, 2026 19:47

Copilot started reviewing on behalf of mnriem March 31, 2026 19:47 View session

Copilot AI reviewed Mar 31, 2026

View reviewed changes

src/specify_cli/extensions.py Outdated Show resolved Hide resolved

tests/test_presets.py Show resolved Hide resolved

mnriem self-requested a review March 31, 2026 19:55

mnriem requested changes Mar 31, 2026

View reviewed changes

mbachorik marked this pull request as draft April 1, 2026 11:27

mbachorik force-pushed the fix/pypi-warning-and-legacy-extension-names branch from 3fed7f7 to caee3e0 Compare April 4, 2026 07:34

Copilot AI review requested due to automatic review settings April 4, 2026 07:34

Copilot started reviewing on behalf of mbachorik April 4, 2026 07:35 View session

Copilot AI reviewed Apr 4, 2026

View reviewed changes

src/specify_cli/extensions.py Outdated Show resolved Hide resolved

src/specify_cli/extensions.py Outdated Show resolved Hide resolved

mbachorik requested a review from Copilot April 4, 2026 14:34

Copilot started reviewing on behalf of mbachorik April 4, 2026 14:35 View session

Copilot AI reviewed Apr 4, 2026

View reviewed changes

src/specify_cli/extensions.py Outdated Show resolved Hide resolved

tests/test_extensions.py Outdated Show resolved Hide resolved

src/specify_cli/extensions.py Show resolved Hide resolved

Copilot AI review requested due to automatic review settings April 4, 2026 15:29

Copilot started reviewing on behalf of mbachorik April 4, 2026 15:29 View session

mbachorik requested a review from Copilot April 11, 2026 08:02

Copilot started reviewing on behalf of mbachorik April 11, 2026 08:02 View session

Copilot AI reviewed Apr 11, 2026

View reviewed changes

mbachorik marked this pull request as ready for review April 11, 2026 09:33

mbachorik requested a review from mnriem April 11, 2026 09:34

mnriem requested changes Apr 13, 2026

View reviewed changes

mbachorik requested a review from Copilot April 14, 2026 16:38

Copilot started reviewing on behalf of mbachorik April 14, 2026 16:39 View session

Copilot AI reviewed Apr 14, 2026

View reviewed changes

src/specify_cli/extensions.py Show resolved Hide resolved

src/specify_cli/extensions.py Show resolved Hide resolved

mnriem self-requested a review April 14, 2026 17:38

mnriem requested changes Apr 14, 2026

View reviewed changes

mnriem requested a review from Copilot April 14, 2026 19:53

Copilot started reviewing on behalf of mnriem April 14, 2026 19:54 View session

Copilot AI reviewed Apr 14, 2026

View reviewed changes

src/specify_cli/extensions.py Show resolved Hide resolved

mbachorik requested a review from Copilot April 14, 2026 20:40

Copilot started reviewing on behalf of mbachorik April 14, 2026 20:41 View session

Copilot AI reviewed Apr 14, 2026

View reviewed changes

mbachorik requested a review from mnriem April 15, 2026 08:33

Conversation

mbachorik commented Mar 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

`docs/installation.md` / `README.md`

`src/specify_cli/extensions.py`

`src/specify_cli/init.py`

`src/specify_cli/agents.py`

`tests/test_extensions.py`

`tests/test_presets.py`

Test plan

Unit tests

Live integration tests (real CLI, real filesystem, temp project dir)

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

mbachorik commented Apr 1, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

mbachorik commented Apr 11, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

mbachorik commented Apr 11, 2026

Uh oh!

mnriem commented Apr 13, 2026

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

mbachorik commented Apr 14, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

mbachorik commented Mar 30, 2026 •

edited

Loading