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

mnriem

Please address Copilot feedback

mbachorik · 2026-04-10T13:21:55Z

Fixed the cmd_count wording in the removal prompt (comment #3039884810).

Changed "across AI agents" → "per agent" — this accurately describes what max gives (the per-agent command count). Using sum was considered but avoided: users think in logical commands, not agent×file counts, so summing would overstate removal scope and be confusing.

'across AI agents' implied a total count, but cmd_count uses max() across agents (per-agent count). Using sum() would double-count since users think in logical commands, not per-agent files. 'per agent' accurately describes what the number represents. 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 1 comment.

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

src/specify_cli/extensions.py

mbachorik · 2026-04-10T13:50:45Z

Fixed the PR description discrepancy (comment #3064573350).

The seen_skill_names dict claim has been removed. Here's why a separate map in _validate() is not needed:

After _validate() runs, all command/alias names are in canonical speckit.{extension}.{command} form (enforced by EXTENSION_COMMAND_NAME_PATTERN + auto-correction).
_collect_manifest_command_names() (called at install time) already rejects duplicate canonical names with a ValidationError (line 646-648).
For a fixed ext_id, the SKILL output name transform (speckit.ext.cmd → speckit-ext-cmd) is injective — canonical uniqueness implies SKILL output name uniqueness.

So collision protection already exists; the PR description was overstating what _validate() does.

Upstream added hook-only extension support to ExtensionManifest._validate(): type checks for provides.commands and hooks, allows extensions with only hooks (no commands), and validates individual hook entries have a 'command' field. Merged with our rename_map / command auto-correction logic. Test conflicts: upstream renamed test_no_commands → test_no_commands_no_hooks and softened the alias autocorrect assertion. Kept our detailed assertions (they test the actual behavior this PR introduces) and applied the rename. Updated hook error message match to upstream's new wording. 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/__init__.py

src/specify_cli/extensions.py

The comment said 'covers all agents' implying a total, but cmd_count uses max() across agents (per-agent count). Updated comment to explain the max() choice and why sum() would double-count. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

mbachorik · 2026-04-11T04:09:40Z

Fixed both comments:

Code comment (#3065047470): Updated the inline comment at __init__.py to say max() gives a per-agent count and explain why sum() was not used (would double-count logical commands across agents).
PR description (#3065047530): Removed the seen_skill_names / collision detection bullet — it described behavior that isn't in this PR. Duplicate canonical names are caught by _collect_manifest_command_names() at install time, not in _validate(). Also removed the stale 'collision detection' mention from the test plan section.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

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

src/specify_cli/__init__.py

Adds TestExtensionRemoveCLI with two CliRunner tests: - singular: 1 registered command → '1 command per agent' - plural: 2 registered commands → '2 commands per agent' These prevent regressions on the cmd_count pluralization logic and the 'per agent' wording introduced in this PR. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

mbachorik · 2026-04-11T05:28:28Z

Fixed (#3067574962). Added TestExtensionRemoveCLI with two CliRunner tests:

test_remove_confirmation_singular_command: installs an extension, sets 1 registered command in the registry, invokes specify extension remove and asserts '1 command' (no trailing 's') appears in the prompt.
test_remove_confirmation_plural_commands: same but 2 commands → asserts '2 commands'.

160 extension tests pass.

Copilot

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

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

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.

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 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 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

mnriem requested changes Apr 6, 2026

View reviewed changes

mbachorik requested a review from Copilot April 10, 2026 13:27

Copilot started reviewing on behalf of mbachorik April 10, 2026 13:27 View session

Copilot AI reviewed Apr 10, 2026

View reviewed changes

src/specify_cli/extensions.py Show resolved Hide resolved

mbachorik marked this pull request as draft April 10, 2026 13:36

mbachorik requested a review from Copilot April 10, 2026 14:49

Copilot started reviewing on behalf of mbachorik April 10, 2026 14:49 View session

Copilot AI reviewed Apr 10, 2026

View reviewed changes

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

src/specify_cli/extensions.py Show resolved Hide resolved

mbachorik requested a review from Copilot April 11, 2026 04:10

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

Copilot AI reviewed Apr 11, 2026

View reviewed changes

src/specify_cli/__init__.py Show resolved Hide resolved

mbachorik requested a review from Copilot April 11, 2026 05:29

Copilot started reviewing on behalf of mbachorik April 11, 2026 05:29 View session

Copilot AI reviewed Apr 11, 2026

View reviewed changes

src/specify_cli/extensions.py Show resolved Hide resolved

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

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!

mnriem left a comment

Choose a reason for hiding this comment

Uh oh!

mbachorik commented Apr 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

mbachorik commented Apr 10, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

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 Mar 30, 2026 •

edited

Loading