From e913d0b67f4e8a70cc56cb6e37dead01f6a7d01e Mon Sep 17 00:00:00 2001 From: nvaldez Date: Thu, 19 Nov 2026 11:22:35 +0100 Subject: [PATCH] feat v0.2.0: phronesis --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 --- README.md | 1 + SPEC.md | 24 +++++++++---- pyproject.toml | 2 +- src/phronesis/cli.py | 51 +++++++++++++++++++++++++-- test/test_cli.py | 83 ++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 151 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index afd5a8b..8d43741 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,7 @@ phronesis filter the list phronesis show one skill and an install hint phronesis --install [--harness ] install globally (~/.vibe/skills) phronesis --project [--harness ] install in the project only (.vibe/skills) +phronesis --uninstall remove it again (project scope: add --project) phronesis --update update every installed skill ``` diff --git a/SPEC.md b/SPEC.md index 71f74fa..58ee003 100644 --- a/SPEC.md +++ b/SPEC.md @@ -97,6 +97,7 @@ phronesis/ | `phronesis ` | The one-row table for that skill plus an install hint | 0 | | `phronesis --install [--harness ]` | Install globally (section 6) | 0, or 2 on error | | `phronesis --project [--harness ]` | Install in the project only (section 6) | 0, or 2 on error | +| `phronesis --uninstall [--project] [--harness ]` | 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 ` | 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: `. 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 --uninstall` removes the harness + target directory `harness.global_dir()//`, 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 (, ) -> `. + 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 diff --git a/pyproject.toml b/pyproject.toml index 75f110f..bdcbf66 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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" diff --git a/src/phronesis/cli.py b/src/phronesis/cli.py index c32d987..d474773 100644 --- a/src/phronesis/cli.py +++ b/src/phronesis/cli.py @@ -24,13 +24,15 @@ from phronesis import version from phronesis.formatting import format_list USAGE = ("phronesis [-h] [-l | --list] [--version] [--update] " - "[--harness ] [] [--install | --project] [-f]") + "[--harness ] [] [--install | --uninstall] " + "[--project] [-f]") PARSER_DESCRIPTION = "One CLI, a chest of skills (SPEC.md)." PARSER_EPILOG = ("Forms: phronesis lists every skill; phronesis filters " "the list; phronesis shows one skill; phronesis " - "--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 globally for the harness") + parser.add_argument("--uninstall", action="store_true", + help="remove from the harness (global, or the project with --project)") parser.add_argument("--project", action="store_true", - help="install 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="", @@ -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 --uninstall [--project] " + "[--harness ]") + 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 --install | --project [-f] " diff --git a/test/test_cli.py b/test/test_cli.py index 0326abf..0f59e4c 100644 --- a/test/test_cli.py +++ b/test/test_cli.py @@ -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()