happyskills 1.10.0 → 1.10.1

package/CHANGELOG.md

@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.10.1] - 2026-06-09
+
+### Fixed
+
+- Fix `uninstall` leaving deep transitive dependencies stranded. Orphan pruning ran a single pass, so removing a skill (or kit / constellation core) pruned its direct dependencies but left behind any *grandchild* dependency whose only parent was one of those now-pruned dependencies — it accumulated as unused cruft in `.agents/skills/` and the lock file. Pruning now cascades to a fixed point, removing the full chain of newly-orphaned dependencies. The data-loss guard is preserved: a dependency that any surviving skill still declares (e.g. a shared satellite like `happyskills-design`) is never pruned, and directly-installed (`__root__`) skills are never swept up.
+
 ## [1.10.0] - 2026-06-06
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "happyskills",
-	"version": "1.10.0",
+	"version": "1.10.1",
 	"description": "Package manager for AI agent skills",
 	"license": "SEE LICENSE IN LICENSE",
 	"author": "Nicolas Dao <nic@cloudlesslabs.com> (https://cloudlesslabs.com)",

package/src/engine/uninstaller.js

@@ -36,6 +36,37 @@ const find_orphans = (skills, removed_skill) => {
 	return orphans
 }
 
+// Cascading orphan detection. `find_orphans` is single-pass by design (its unit
+// contract): it only reports the DIRECT orphans of `removed_skill`. But pruning a
+// direct orphan A can in turn strand A's own private sub-dependency B — a grandchild
+// that nothing else needs once A is gone. A single pass leaves B behind because A is
+// still in the map (so A both counts as a live requester of B and, via its
+// `dependencies`, as a "surviving declarer" of B).
+//
+// This wrapper closes that gap WITHOUT weakening the data-loss guard. It runs
+// `find_orphans` to a fixed point over a shrinking working copy: each round, the
+// orphans found are physically removed from the map, so the next round sees them as
+// gone — both as requesters (`skills[r]` is now false) and as declarers
+// (`declared_by_survivor` no longer finds them). A skill that ANY surviving skill
+// still declares is never pruned, exactly as before — only skills whose entire
+// requirement chain has been removed cascade out. Terminates because every round
+// deletes at least one entry from a finite map.
+const find_orphans_cascading = (skills, removed_skill) => {
+	const working = { ...skills }
+	delete working[removed_skill]
+
+	const all_orphans = []
+	let round = find_orphans(working, removed_skill)
+	while (round.length > 0) {
+		for (const name of round) {
+			all_orphans.push(name)
+			delete working[name]
+		}
+		round = find_orphans(working, removed_skill)
+	}
+	return all_orphans
+}
+
 const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', async () => {
 	const { global: is_global = false, project_root, agents: agents_flag } = options
 
@@ -64,7 +95,7 @@ const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', asyn
 		}
 	}
 
-	const orphans = find_orphans(all_skills, skill)
+	const orphans = find_orphans_cascading(all_skills, skill)
 	const to_remove = [skill, ...orphans]
 
 	for (const name of to_remove) {
@@ -97,4 +128,4 @@ const uninstall = (skill, options = {}) => catch_errors('Uninstall failed', asyn
 	return { removed: to_remove, orphans_pruned: orphans }
 })
 
-module.exports = { uninstall, find_orphans }
+module.exports = { uninstall, find_orphans, find_orphans_cascading }

package/src/engine/uninstaller.test.js

@@ -1,6 +1,6 @@
 const { describe, it } = require('node:test')
 const assert = require('node:assert')
-const { find_orphans } = require('./uninstaller')
+const { find_orphans, find_orphans_cascading } = require('./uninstaller')
 
 describe('find_orphans', () => {
 	it('returns empty when all skills have requesters in the skills map', () => {
@@ -134,3 +134,122 @@ describe('find_orphans', () => {
 		assert.ok(result.includes('happyskillsai/happyskills-design'))
 	})
 })
+
+describe('find_orphans_cascading', () => {
+	it('cascades: prunes a grandchild stranded once its only parent is orphaned', () => {
+		// Kit K -> A -> B. B is A's private sub-dependency (not listed directly by the
+		// kit). Uninstalling K must prune A (direct orphan) AND B (cascaded orphan).
+		// This is the exact case single-pass find_orphans leaves stranded.
+		const skills = {
+			'acme/_kit-x': { requested_by: ['__root__'], dependencies: { 'acme/a': '^1.0.0' } },
+			'acme/a':      { requested_by: ['acme/_kit-x'], dependencies: { 'acme/b': '^1.0.0' } },
+			'acme/b':      { requested_by: ['acme/_kit-x'], dependencies: {} }
+		}
+		const result = find_orphans_cascading(skills, 'acme/_kit-x')
+		assert.ok(result.includes('acme/a'), 'direct orphan A should be pruned')
+		assert.ok(result.includes('acme/b'), 'cascaded orphan B should be pruned')
+	})
+
+	it('still protects a shared dependency a surviving skill declares (no over-pruning under cascade)', () => {
+		// The data-loss guard must survive the cascade: design is declared by the
+		// surviving happyskills, so uninstalling create-release-skill must NOT prune it
+		// even though we now iterate to a fixed point.
+		const skills = {
+			'happyskillsai/happyskills': {
+				requested_by: ['__root__'],
+				dependencies: { 'happyskillsai/happyskills-design': '^0.1.0' }
+			},
+			'nicolasdao/create-release-skill': {
+				requested_by: ['__root__'],
+				dependencies: { 'happyskillsai/happyskills-design': '^0.9.0' }
+			},
+			'happyskillsai/happyskills-design': {
+				requested_by: ['nicolasdao/create-release-skill']
+			}
+		}
+		const result = find_orphans_cascading(skills, 'nicolasdao/create-release-skill')
+		assert.ok(!result.includes('happyskillsai/happyskills-design'))
+	})
+
+	it('never prunes a user-installed (__root__) skill, even mid-cascade', () => {
+		// K -> A, but A is ALSO directly installed by the user. Removing K orphans
+		// nothing the user still wants: A is __root__-anchored and stays.
+		const skills = {
+			'acme/_kit-x': { requested_by: ['__root__'], dependencies: { 'acme/a': '^1.0.0' } },
+			'acme/a':      { requested_by: ['__root__', 'acme/_kit-x'], dependencies: {} }
+		}
+		const result = find_orphans_cascading(skills, 'acme/_kit-x')
+		assert.deepStrictEqual(result, [])
+	})
+
+	it('halts the cascade at a still-shared mid-chain dependency', () => {
+		// K -> A -> B, but B is ALSO required by an unrelated surviving skill S.
+		// Removing K prunes A, but B must stay because S still needs it.
+		const skills = {
+			'acme/_kit-x': { requested_by: ['__root__'], dependencies: { 'acme/a': '^1.0.0' } },
+			'acme/a':      { requested_by: ['acme/_kit-x'], dependencies: { 'acme/b': '^1.0.0' } },
+			'acme/s':      { requested_by: ['__root__'], dependencies: { 'acme/b': '^1.0.0' } },
+			'acme/b':      { requested_by: ['acme/_kit-x', 'acme/s'], dependencies: {} }
+		}
+		const result = find_orphans_cascading(skills, 'acme/_kit-x')
+		assert.ok(result.includes('acme/a'), 'A is orphaned')
+		assert.ok(!result.includes('acme/b'), 'B is still needed by surviving acme/s')
+	})
+
+	it('constellation: uninstalling the core prunes bundled satellites, keeps shared + opt-in ones', () => {
+		// Models the real happyskills constellation: the core declares 5 bundled
+		// satellites as dependencies. happyskills-design is ALSO declared by a surviving
+		// skill (create-release-skill). collab + stats are OPT-IN — installed directly
+		// (__root__), never dependencies of the core.
+		const skills = {
+			'happyskillsai/happyskills': {
+				requested_by: ['__root__'],
+				dependencies: {
+					'happyskillsai/happyskills-design': '^0.1.0',
+					'happyskillsai/happyskills-publish': '^0.1.0',
+					'happyskillsai/happyskills-sync': '^0.1.0',
+					'happyskillsai/happyskills-search': '^0.1.0',
+					'happyskillsai/happyskills-help': '^0.1.0'
+				}
+			},
+			'nicolasdao/create-release-skill': {
+				requested_by: ['__root__'],
+				dependencies: { 'happyskillsai/happyskills-design': '^0.9.0' }
+			},
+			'happyskillsai/happyskills-design':  { requested_by: ['happyskillsai/happyskills', 'nicolasdao/create-release-skill'], dependencies: {} },
+			'happyskillsai/happyskills-publish': { requested_by: ['happyskillsai/happyskills'], dependencies: {} },
+			'happyskillsai/happyskills-sync':    { requested_by: ['happyskillsai/happyskills'], dependencies: {} },
+			'happyskillsai/happyskills-search':  { requested_by: ['happyskillsai/happyskills'], dependencies: {} },
+			'happyskillsai/happyskills-help':    { requested_by: ['happyskillsai/happyskills'], dependencies: {} },
+			'happyskillsai/happyskills-collab':  { requested_by: ['__root__'], dependencies: {} },
+			'happyskillsai/happyskills-stats':   { requested_by: ['__root__'], dependencies: {} }
+		}
+		const result = find_orphans_cascading(skills, 'happyskillsai/happyskills').sort()
+		assert.deepStrictEqual(result, [
+			'happyskillsai/happyskills-help',
+			'happyskillsai/happyskills-publish',
+			'happyskillsai/happyskills-search',
+			'happyskillsai/happyskills-sync'
+		])
+		// design is shared (create-release-skill still declares it) → kept
+		assert.ok(!result.includes('happyskillsai/happyskills-design'))
+		// collab + stats are opt-in (__root__) → never swept up by a core uninstall
+		assert.ok(!result.includes('happyskillsai/happyskills-collab'))
+		assert.ok(!result.includes('happyskillsai/happyskills-stats'))
+	})
+
+	it('matches find_orphans for a flat kit (no nested sub-dependencies)', () => {
+		// The common curated-kit case: K directly lists A, B, C and none depend on each
+		// other. Single-pass and cascading must agree — cascade changes nothing here.
+		const skills = {
+			'acme/_kit-x': { requested_by: ['__root__'], dependencies: { 'acme/a': '^1', 'acme/b': '^1', 'acme/c': '^1' } },
+			'acme/a':      { requested_by: ['acme/_kit-x'], dependencies: {} },
+			'acme/b':      { requested_by: ['acme/_kit-x'], dependencies: {} },
+			'acme/c':      { requested_by: ['acme/_kit-x'], dependencies: {} }
+		}
+		const single = find_orphans(skills, 'acme/_kit-x').sort()
+		const cascaded = find_orphans_cascading(skills, 'acme/_kit-x').sort()
+		assert.deepStrictEqual(cascaded, ['acme/a', 'acme/b', 'acme/c'])
+		assert.deepStrictEqual(cascaded, single)
+	})
+})