@softspark/ai-toolkit 4.24.0 → 4.24.1

package/CHANGELOG.md

@@ -7,6 +7,33 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.24.1 — a dead link reported itself as installed (2026-08-19)
+
+### Fixed
+
+- **`plugin install` treated a dangling symlink as an installed asset.** The guard
+  was `if path.exists() or path.is_symlink()`, and a link whose target is gone
+  satisfies the second half — so the installer printed `OK agent` / `OK skill`,
+  changed nothing, and left the user with a dead link and a green log. This is the
+  exact state a toolkit upgrade produces: `npm install -g @softspark/ai-toolkit`
+  replaces `app/` wholesale, so every `~/.claude` link into the old package points
+  at nothing, and re-running install could not repair it.
+
+  A dangling link is now dropped before the guard runs and relinked to the
+  resolved source, printing `Dangling agent link removed: <name>`. **Live links and
+  real files are untouched** — those are user content, and the merge-friendly
+  install model keeps them.
+
+  Surfaced while migrating a pack from `app/plugins/` to the v4.24.0 user root:
+  the upgrade broke both links and `plugin install` insisted everything was fine.
+
+### Added
+
+- **Two tests.** One builds the post-upgrade state (links pointing into a path
+  that no longer exists) and asserts install removes and relinks both; the other
+  pins the negative — a real file on the agent name and a live skill link survive
+  a reinstall untouched.
+
 ## v4.24.0 — external packs stop dying on upgrade (2026-08-18)
 
 ### Added

package/README.md

@@ -6,18 +6,17 @@
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-109-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1522%20passing-success)](tests/)
-
-## What's New in v4.24.0
-
-**v4.24.0** — a plugin pack maintained in its own repository had nowhere safe to
-live: the only directory the toolkit scanned was `app/plugins/`, inside the npm
-package, so every `npm install -g` upgrade deleted it. Packs now also load from
-`~/.softspark/ai-toolkit/plugins/`, which the user owns and upgrades never touch.
-The entry can be a symlink to an npm-installed package, so updating an external
-pack is one `npm install -g` with nothing to re-link. Core packs still win a name
-collision. Ships with v4.23.1's fix for pack-shipped agents, which the same
-external-pack workflow depends on.
+[![Tests](https://img.shields.io/badge/tests-1524%20passing-success)](tests/)
+
+## What's New in v4.24.1
+
+**v4.24.1** — `plugin install` accepted a dead symlink as proof of installation.
+The guard asked `exists() or is_symlink()`, and a link with no target still
+answers yes to the second half, so the installer logged `OK` and repaired
+nothing — precisely the state a toolkit upgrade leaves, since replacing `app/`
+breaks every link into it. Dangling links are now dropped and relinked; real
+files and live links stay untouched. Pairs with v4.24.0's user-level pack root,
+which is what stops the breakage happening in the first place.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 

package/app/.claude-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.24.0",
+  "version": "4.24.1",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.24.0",
+  "version": "4.24.1",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.24.0",
+  "version": "4.24.1",
   "description": "AI coding toolkit: 109 skills, 44 agents, 12 developer-tool integrations, recoverable native tool-output filtering, Claude Chat/Cowork export, safety constitution, SARIF audit, and signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/plugin.py

@@ -603,10 +603,30 @@ def _ensure_claude_settings() -> Path:
     return settings_path
 
 
+def _clear_dangling_link(path: Path, label: str) -> bool:
+    """Drop a symlink whose target no longer exists, so install can relink it.
+
+    A toolkit upgrade replaces app/ wholesale, which leaves every ~/.claude link
+    into the old package pointing at nothing. The install guard treated such a
+    link as installed (`exists() or is_symlink()`), reported OK and repaired
+    nothing — the user was left with a dead link and a green log. Only dangling
+    links are removed: a live link or a real file is user content and stays.
+    """
+    if path.is_symlink() and not path.exists():
+        try:
+            path.unlink()
+        except OSError:
+            return False
+        print(f"    Dangling {label} link removed: {path.name}")
+        return True
+    return False
+
+
 def _install_claude_skills(pack: dict, pack_dir: Path, installed_items: list[str]) -> None:
     for skill in pack.get("includes", {}).get("skills", []):
         skill_dir = CLAUDE_DIR / "skills" / skill
         source_dir = _resolve_skill_source(pack_dir, skill)
+        _clear_dangling_link(skill_dir, "skill")
         if skill_dir.exists() or skill_dir.is_symlink():
             print(f"    OK skill: {skill}")
         elif source_dir:
@@ -622,6 +642,7 @@ def _install_claude_agents(pack: dict, pack_dir: Path, installed_items: list[str
     for agent in pack.get("includes", {}).get("agents", []):
         agent_file = CLAUDE_DIR / "agents" / f"{agent}.md"
         source_file = _resolve_agent_source(pack_dir, agent)
+        _clear_dangling_link(agent_file, "agent")
         if agent_file.exists() or agent_file.is_symlink():
             print(f"    OK agent: {agent}")
         elif source_file is not None: