feat v0.2.0: phronesis <skill> --uninstall - remove installed skills

- --uninstall [--project] removes the harness target skill directory
  and drops the matching state entry; --install/--uninstall exclusive
- safety guard (SPEC 6.6): the directory must hold a parseable SKILL.md
  whose front-matter name equals the directory, else refused, exit 2;
  unbundled (retired) skill names can still be removed by name
- SPEC section 6 items 6.6-6.7, section 3 table/3.2, item 8.4 rewritten;
  README command block; 8 new tests (76 total, all checks green)

Generated by Mistral Vibe.
Co-Authored-By: Mistral Vibe <vibe@mistral.ai>
This commit is contained in:
nvaldez
2026-11-19 11:22:35 +01:00
parent 0e4fe45bc1
commit e913d0b67f
5 changed files with 151 additions and 10 deletions
+1
View File
@@ -23,6 +23,7 @@ phronesis <category> filter the list
phronesis <skill> show one skill and an install hint
phronesis <skill> --install [--harness <name>] install globally (~/.vibe/skills)
phronesis <skill> --project [--harness <name>] install in the project only (.vibe/skills)
phronesis <skill> --uninstall remove it again (project scope: add --project)
phronesis --update update every installed skill
```
+18 -6
View File
@@ -97,6 +97,7 @@ phronesis/
| `phronesis <skill>` | The one-row table for that skill plus an install hint | 0 |
| `phronesis <skill> --install [--harness <name>]` | Install globally (section 6) | 0, or 2 on error |
| `phronesis <skill> --project [--harness <name>]` | Install in the project only (section 6) | 0, or 2 on error |
| `phronesis <skill> --uninstall [--project] [--harness <name>]` | Remove the skill and its state entry (SPEC items 6.6 to 6.7) | 0, or 2 on error |
| `phronesis --update` | Update every installed skill (section 7) | 0, or 2 on error |
| `phronesis --version` | `phronesis <version>` | 0 |
| `phronesis -h`, `phronesis --help` | Usage (SPEC item 3.8) | 0 |
@@ -106,9 +107,10 @@ phronesis/
a category only when it matches a category in use; otherwise it is
treated as a skill name. Names and category labels must not collide
(SPEC item 4.6).
- **3.2** `--install` and `--project` are mutually exclusive; using
both exits 2. Each needs a skill word; with neither option the call
lists.
- **3.2** `--install` and `--project` are mutually exclusive, and so are
`--install` and `--uninstall`; each needs a skill word; with neither
install nor uninstall option the call lists. `--project` scopes
`--uninstall` to the project (SPEC item 6.7).
- **3.3** Listing format (bare, `--list`, filtered, one skill):
- **3.3.1** First line `Phronesis Version: <version>`. When at least
one skill is listed, a blank line and the table follow.
@@ -213,6 +215,16 @@ python-tdd 1.2.0 development
`installed python-tdd 1.2.0 (vibe, global) -> /home/me/.vibe/skills/python-tdd/SKILL.md`.
- **6.5** A skill that is not bundled exits 2 with close matches
(SPEC item 3.5).
- **6.6** `phronesis <skill> --uninstall` removes the harness
target directory `harness.global_dir()/<name>/`, or the project one
with `--project`. A safety guard runs first: the directory must hold
a `SKILL.md` whose front matter parses and whose `name` equals the
directory; anything else is refused with exit 2 and nothing is
deleted. The skill does not need to still be bundled (SPEC item 8.3).
- **6.7** After a successful removal the matching state entry
`(name, harness, scope)` is dropped (SPEC item 8.3), and one line is
printed: `removed <name> <version> (<harness>, <scope>) -> <path>`.
A missing state entry does not fail the removal.
## 7. Update
@@ -258,9 +270,9 @@ python-tdd 1.2.0 development
- **8.3** An entry is unique by `(name, harness, scope)`: reinstalling
updates the entry instead of appending a new one. The `path` is the
absolute `SKILL.md` path; `scope` is `global` or `project`.
- **8.4** Uninstalling is not part of the CLI; removing the harness
directory and the state entry is the workaround until section 6
grows a `--remove`.
- **8.4** `--uninstall` drops the matching entry (SPEC item 6.7);
a state entry whose files were removed by hand is reinstalled by
`--update` (SPEC item 7.3).
## 9. Quality gates
+1 -1
View File
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
[project]
name = "phronesis"
version = "0.1.1"
version = "0.2.0"
description = "A chest of skills: list them, install them into an agent harness (vibe, ...)"
readme = "README.md"
requires-python = ">=3.11"
+48 -3
View File
@@ -24,13 +24,15 @@ from phronesis import version
from phronesis.formatting import format_list
USAGE = ("phronesis [-h] [-l | --list] [--version] [--update] "
"[--harness <name>] [<category|skill>] [--install | --project] [-f]")
"[--harness <name>] [<category|skill>] [--install | --uninstall] "
"[--project] [-f]")
PARSER_DESCRIPTION = "One CLI, a chest of skills (SPEC.md)."
PARSER_EPILOG = ("Forms: phronesis lists every skill; phronesis <category> filters "
"the list; phronesis <skill> shows one skill; phronesis <skill> "
"--install | --project installs it; phronesis --update refreshes "
"--install installs it and --uninstall removes it, --project "
"scopes either to the project; phronesis --update refreshes "
"every installed skill.")
@@ -57,8 +59,10 @@ def build_parser() -> PhronesisParser:
help="update every skill recorded in the state file")
parser.add_argument("--install", action="store_true",
help="install <skill> globally for the harness")
parser.add_argument("--uninstall", action="store_true",
help="remove <skill> from the harness (global, or the project with --project)")
parser.add_argument("--project", action="store_true",
help="install <skill> in the project only")
help="scope --install or --uninstall to the project only")
parser.add_argument("-f", "--force", action="store_true",
help="install or update without the confirmation prompt")
harness_action = parser.add_argument("--harness", metavar="<name>",
@@ -132,6 +136,38 @@ def install_skill(skill: registry.Skill, harness: harnesses.Harness, scope: str,
return 0
def uninstall_skill(name: str, harness: harnesses.Harness, scope: str) -> int:
"""Remove one installed skill, with a skill-directory safety guard (SPEC item 6.6)."""
if scope == "global":
target_dir = harness.global_dir()
else:
target_dir = harness.project_dir(pathlib.Path.cwd())
target = target_dir / name
skill_md = target / "SKILL.md"
if not skill_md.is_file():
raise UsageError(f"{name!r} is not installed for {harness.name} "
f"in {scope} scope; nothing to remove")
try:
data = registry.parse_frontmatter(skill_md.read_text(encoding="utf-8"),
origin=str(skill_md))
except registry.RegistryError as error:
raise UsageError(f"refusing to remove {target}: {error}") from error
if str(data["name"]) != name:
raise UsageError(f"refusing to remove {target}: its SKILL.md name "
f"{data['name']!r} does not match the directory")
shutil.rmtree(target)
path = state.state_path()
entries = state.load(path)
kept = [entry for entry in entries
if (entry.get("name"), entry.get("harness"), entry.get("scope"))
!= (name, harness.name, scope)]
if len(kept) != len(entries):
state.save(kept, path)
print(f"removed {name} {data['version']} ({harness.name}, {scope}) "
f"-> {skill_md}")
return 0
def update_all() -> int:
"""Update every installed skill from the state file (SPEC section 7)."""
path = state.state_path()
@@ -167,6 +203,15 @@ def dispatch(parsed: argparse.Namespace) -> int:
return update_all()
if parsed.install and parsed.project:
raise UsageError("pick one of --install or --project, not both")
if parsed.install and parsed.uninstall:
raise UsageError("pick one of --install or --uninstall, not both")
if parsed.uninstall:
if len(parsed.words) != 1:
raise UsageError("usage: phronesis <skill> --uninstall [--project] "
"[--harness <name>]")
scope = "project" if parsed.project else "global"
harness = harnesses.lookup(parsed.harness)
return uninstall_skill(parsed.words[0], harness, scope)
if parsed.install or parsed.project:
if len(parsed.words) != 1:
raise UsageError("usage: phronesis <skill> --install | --project [-f] "
+83
View File
@@ -1,10 +1,12 @@
"""CLI tests: list, filter, install, prompt, force, and update (SPEC sections 3, 6, 7)."""
import json
import shutil
import pytest
from phronesis import cli
from phronesis import harnesses
from phronesis import registry
from phronesis import state
@@ -213,3 +215,84 @@ def test_installed_json_is_plain_json(config, capsys):
assert set(data) == {"skills"}
assert set(data["skills"][0]) == {"name", "version", "harness", "scope",
"path", "installed"}
# --- uninstall (SPEC items 6.6, 6.7, 8.4)
def test_uninstall_removes_skill_and_state(config, capsys):
run(capsys, "python-tdd", "--install")
target = config.parent / "home" / ".vibe" / "skills" / "python-tdd"
code, out, _ = run(capsys, "python-tdd", "--uninstall")
assert code == 0
assert "removed python-tdd 1.2.0 (vibe, global)" in out
assert not target.exists()
assert state.load(state.state_path()) == []
def test_uninstall_project_scoped(config, capsys, tmp_path, monkeypatch):
work = tmp_path / "work"
work.mkdir()
monkeypatch.chdir(work)
run(capsys, "python-tdd", "--project")
code, _, _ = run(capsys, "python-tdd", "--uninstall", "--project")
assert code == 0
assert not (work / ".vibe" / "skills" / "python-tdd").exists()
assert state.load(state.state_path()) == []
def test_uninstall_needs_the_skill_installed(config, capsys):
code, _, err = run(capsys, "python-tdd", "--uninstall")
assert code == 2
assert "not installed" in err
def test_uninstall_refuses_a_non_skill_directory(config, capsys):
target = config.parent / "home" / ".vibe" / "skills" / "not-a-skill"
target.mkdir(parents=True)
(target / "SKILL.md").write_text("random notes, no front matter",
encoding="utf-8")
code, _, err = run(capsys, "not-a-skill", "--uninstall")
assert code == 2
assert "refusing to remove" in err
assert (target / "SKILL.md").is_file()
def test_uninstall_refuses_a_name_mismatch(config, capsys):
skill_md_run = run(capsys, "python-tdd", "--install")
target_dir = config.parent / "home" / ".vibe" / "skills" / "python-tdd"
other = target_dir.parent / "other-name"
other.mkdir()
shutil.copytree(target_dir, other, dirs_exist_ok=True)
code, _, err = run(capsys, "other-name", "--uninstall")
assert code == 2
assert "does not match the directory" in err
assert (other / "SKILL.md").is_file()
def test_uninstall_works_without_a_state_entry(config, capsys):
target = config.parent / "home" / ".vibe" / "skills" / "python-tdd"
target.mkdir(parents=True)
body = registry.SKILLS["python-tdd"].skill_md.read_text(encoding="utf-8")
(target / "SKILL.md").write_text(body, encoding="utf-8")
code, out, _ = run(capsys, "python-tdd", "--uninstall")
assert code == 0
assert "removed" in out
assert not target.exists()
def test_install_and_uninstall_are_exclusive(config, capsys):
code, _, err = run(capsys, "python-tdd", "--install", "--uninstall")
assert code == 2
assert "pick one of --install or --uninstall" in err
def test_uninstall_of_unbundled_name_is_allowed(config, capsys):
target = config.parent / "home" / ".vibe" / "skills" / "retired-skill"
target.mkdir(parents=True)
(target / "SKILL.md").write_text(
"---\nname: retired-skill\nversion: 0.9.0\ndescription: gone\n"
"category: misc\n---\n", encoding="utf-8")
code, out, _ = run(capsys, "retired-skill", "--uninstall")
assert code == 0
assert not target.exists()